[MERGE] show the revision specifier on help

[John Arbash Meinel]

Goffredo Baroncelli wrote:

...

> I followed your suggestion in the enclosed patch. I defined four topics:
> 1) global_help:  the help which is displayied when bazaar is runned without 
> arguments
> 2) commands: list of commands ( bzr help -l )
> 3) topics: list of topics ( bzr help --list-topics )
> 4) revisionspec: revision specifier list
> 
> The patch creates a new file ( help_topics.py ) which defines the following 
> functions:
> - add_topic(name, obj, comment): add a new topic
> - write_topic(name, outfile=sys.stdout): write topic 
> - is_topic(name): return if exist a topic named "name"
> - get_topics_list( ): return the topic list
> 
> In the same file are defined the global_help topic, the "topics" topic, and 
> the "revisionspec" topic.
> 
> Comments are welcome
> Goffredo

I think the basic flow is okay. I think '--list-topics' is redundant to
'bzr help topics', so I don't think it is really necessary.

Instead, I would rather see the "global" help have a: final line:

bzr help topics		list all help topics (concepts outside the scope of a
single command).

I haven't figured out exactly how to reduce that so it fits nicely on 1
line with < 80 characters. But I think that is the best way to make it
discoverable.


...

> $ ./bzr help --list-topics
> commands
>         List of commands
> global_help
>         Basic commands
> topics
>         Topics list
> revisionspec
>         Revisions specifier
>

The topics are going to be short, single word keys. So it might be nicer
to put everything on one line:

commands  List of all commands
global_help Basic commands
...

I would also change 'global_help' to be either 'basic_help' or 'basic'.



> $ ./bzr help revisionspec
> 
> Revision prefix specifier:
> --------------------------
>   revno:
>     This takes the a number  and return the related revision.
>     Optionally can be specified a branch
>     examples:
>       revno:1                   -> return the first revision
>       revno:3:/path/to/branch   -> return the 3rd revision of
>                                    the branch '/path/to/branch'

This looks quite good.

There were some PEP8 problems with your patch, and I had a few other
comments to be made. So I went ahead and updated your patch with the
changes I would like to see. It should be attached.

I also cleaned up some of the help text for the various revision specs.

I think this looks pretty good. Though once I get Registry merged into
bzr, I'd like to switch all of the add_topic, etc functions into using a
Registry object instead.

John
=:->
-------------- next part --------------
A non-text attachment was scrubbed...
Name: help_topics.diff
Type: text/x-patch
Size: 13867 bytes
Desc: not available
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20060909/5ece4855/attachment.bin 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 254 bytes
Desc: OpenPGP digital signature
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20060909/5ece4855/attachment.pgp