[RFC] disambiguating help topics.

[John Arbash Meinel]

Martin Pool wrote:
> On 4/19/07, Robert Collins <robertc at robertcollins.net> wrote:
>> Currently 'bzr help' can have several things that qualify.
>>
>> For example, if I add a command (perhaps from a plugin) called 'topics',
>> I can't get at the help for it.
>>
>> I think we should do two things to address this. We should make sure
>> that everything that help can report on has a namespace of some sort
>> within which is must be unique. E.g. directly registered things cannot
>> be shadowed - they are fine. commands can be shadowed - they should be
>> also have help available at 'commands/command-name' (or perhaps 'command
>> command-name'). Help on plugins, which I am adding should be available
>> at 'help PLUGINNAME' but also 'help plugins/PLUGINNAME' (or 'help
>> plugins PLUGINNAME' perhaps). I personally prefer the / separator but am
>> happy with separate words too if someone has a stronger preference than
>> mine :).
>>
>> Secondly, whever a requested help topic is ambiguous, 'bzr help THING'
>> should automatically add 'see also:' entries for the alternatives. Using
>> my example above:
>>
>> $ bzr help topics
>> ...
>> ...
>> See also: commands/topics
> 
> Sounds good.  Slashes would be ok with me.
> 

Slashes or colons. "bzr help plugin:vimdiff" versus "bzr help
plugin/vimdiff" or "bzr help plugin vimdiff".

I personally like ":" as a namespace separator.

But +1 to disambiguation. And I really like the auto see also idea as it
makes it much more discoverable.

John
=:->