[Monotone-devel] Help on subcommands (help-rewrite branch)

[Julio M. Merino Vidal]

Hi,

I think that the n.v.m.help-rewrite branch is in pretty good shape  
now.  Basically, it has the following changes over n.v.m:

- The CMD* macros now take a parameter to the parent command (not a
  string mentioning the group they are in).  This allows the
  construction of a tree of commands rather than a plain list.
- The CMD* macros also take an 'abstract' parameter to specify a
  brief description for each command.  This is shown in command
  summaries.
- CMD_WITH_SUBCMDS is gone.  Commands that take subcommands are now
  defined with the more generic CMD_GROUP.
- Automation commands are defined with CMD_AUTOMATE and are added to
  the same tree of commands.
- Command name completion works at any level of the command name, but
  names cannot be skipped.  E.g., 'drop' is always 'drop', not 'attr
  drop'.

- I seized the opportunity to add a new 'version' command.  More details
  about why are given in fdafb86c8adf1d3281e0c78504ce30e2211f162d.
- I also added the args_vector and arg_type types, as mentioned in a
  previous mail, to homogenize the representation of command-line
  arguments.  Not related to the branch's purpose, but made things a
  lot easier and consistent.

With all the above internal changes, 'mtn help' is now able to lookup  
help for commands at any level.  For example, all of the commands  
below will show information for "attr set":

    $ mtn help attr set
    $ mtn help a set
    $ mtn help at s

Whereas these will show a list of all subcommands of attr:

    $ mtn help attr
    $ mtn help at

Similarly, 'mtn help' shows a list of available command groups and  
using 'mtn help <group>' shows a list of all commands available  
inside it:

    $ mtn help informative

There are still some things to do, such as completing the help  
messages for all the automate commands[*] and improving some  
sentences.  But big changes should not happen any more.

Could you please review the code and tell me if it is appropriate for  
mainline?  If so, I would like to merge it after 0.35 has been  
released (and after the above pending things have been addressed).

There are other changes I'd like to try that involve removing the  
special-casing of top-level commands (see the comment at the  
beginning of commands.cc).  But these may result in some command-line  
incompatibilities, and I'd rather not do these on a first attempt.   
I.e., I'd first like to get the refactoring merged into mainline  
without losing compatibility and, later on, propose these new ideas.

Thank you,

* I think that the comments describing the behavior of each automate
  command can be migrated to the online help system, making them more
  easily accessible.  See the comment before the definition of
  CMD_AUTOMATE.

--
Julio M. Merino Vidal <address@hidden>