RFC: show the revision specifier on help

[John Arbash Meinel]

Matthieu Moy wrote:
> Goffredo Baroncelli <kreijack at alice.it> writes:
> 
>> Hi all,
>>
>> with the enclosed patch, the "bzr help -l" command shows info about the 
>> revision specifier.
> 
> Indeed, I'd prefer having some "help topics" than putting this at the
> end of "help -l". Probably the revisionspec are not the only thing
> which are not a command, and would deserve some doc in "bzr help".
> 
> So, I'd rather see stg like
> 
> $ bzr help revisionspec
> [...]
> 
> with a pointer to it in "bzr help".
> 
> Help topics could also be groups of commands, like
> 
> $ bzr help basic-commands
> $ bzr help branching
> $ ...

I agree 100%.

At one point I had started working on such a thing, but it got delayed
because we were trying to get a release out the door, and I didn't get
back to it.

Here is the layout that I would like to see:

1) A new registry of help topics in either bzrlib.help, or possibly a
new file 'bzrlib.help_topics'. This can be as simple as a dictionary
mapping the topic name to a function returning the help text. A function
is better than raw text, because it can use some introspection. Like for
'bzr help revisionspec' should use introspection to get the list of
registered specs, and print out their help text. That way plugins can
register new help topics, and new information to be included in the
final help of other topics.

2) A new target 'bzr help topics', which would list the topics. The help
text should indicate that this is for help on general topics that might
apply to multiple commands, etc.

I can't work on it today, as I already have 3 or 4 patches outstanding
that need to be cleaned up and submitted. And the sooner I get those
done, the less I'm running around.

Otherwise I'll try to get to it later this week. But if you can get to
it first, I would be more than happy to wait. :)

John
=:->


-------------- 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/20060905/20b9d794/attachment.pgp