[RFC] disambiguating help topics.
John Arbash Meinel
john at arbash-meinel.com
Thu Apr 19 17:32:34 BST 2007
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.
More information about the bazaar