Re: [Monotone-devel] More descriptive help summary

[Julio M. Merino Vidal]

On 09/04/2007, at 13:11, Richard Levitte - VMS Whacker wrote:

> In message <address@hidden> on Mon,  
> 9 Apr 2007 09:45:51 +0200, "Julio M. Merino Vidal"  
> <address@hidden> said:
>
> jmmv84> Or "remove" subcommands and make them regular commands
> jmmv84> (e.g. "db-init" instead of "db init").
>
> I disagree with that idea fdor aesthetic reasons.  That, or mtn should
> be split in small programs, such as mtn-db-init.  I'm sure we don't
> want that.

It is just that the current interface seems "inconsistent".  Either  
some categories ought to be removed, or some of the subcommands  
erased.  I.e., what's the difference between the "database" category  
and the "db" command?  Or between "automation" and "automate"?  It  
seems that re-categorizing such commands is easier, and won't cause  
any incompatibilities.

> jmmv84> An alternative could be to show no commands at all on the
> jmmv84> default help, but only the categories with a little blurb of
> jmmv84> what they are about.  Such as:
> jmmv84>
> jmmv84> [...options summary here...]
> jmmv84>
> jmmv84> Command categories:
> jmmv84>
> jmmv84>      automation  Commands for scripted execution
> jmmv84>      db          Commands to manage the database
> jmmv84>      ...
> jmmv84>
> jmmv84> Type "mtn help <category>" to show information on all commands
> jmmv84> available in that category.
>
> I *like* that thought.  I'd hate for the help immediately requiring a
> pager, which often results in users going:

I've implemented this and left a preliminary patch here (which is  
quite large for an attachment):

    http://www.NetBSD.org/~jmmv/mtn-help.diff

I don't dare to commit this without agreement nor approval first ;-)   
So... comments?

What the above does is the following:

1) Changes the default 'mtn help' to print the list of available groups
   and their purpose in a compact way.
2) Changes 'mtn help' to take either a group name or a command name.
3) 'mtn help <group_name>' shows all available commands within the given
   group, alongside their purpose.
4) 'mtn help <command_name>' shows the detailed information for the
   given command, just as before.

I haven't touched the descriptions nor the options (yet).

Cheers,

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