Re: [Monotone-devel] More descriptive help summary

[William Uther]

On 09/04/2007, at 5:13 AM, Julio M. Merino Vidal wrote:

> I find that the current summary of commands printed by "mtn help"  
> is too terse and therefore not as useful as it would be.  It is  
> nice to see all available commands grouped by category but this is  
> of few use if you don't understand what their compact name means or  
> even less if you are new to monotone.

I understand where you are coming from, and I can see a use for the  
type of longer help you suggested.  But I'm not sure I like the  
length of sample help output you provided.  I think it is good to try  
and keep the help down to 1 (or 2) screenfuls.  More than that and I  
stop using the help command for a quick refresher.

I'm going to brainstorm a few possible solutions:

- re-organise the commands so there are fewer of them?

- Don't show help at all for rare commands

- extend the "mtn help <command>" syntax to "mtn help <command group>"

- include help on using help at the bottom of the main help command.

- While we're at it, it would be great if you could use help on  
subcommands: "mtn help db init"

I guess I'd use the heuristic that you want to remove information  
from the initial help screen that isn't commonly used, but make sure  
you have instructions on how to get it if you need it.

Some suggested output (without code, making it all hot air really):

% mtn help
Usage: mtn [OPTION...] command [ARG...]

Common global arguments:

  --db [ -d ] <arg>     set name of database
  --help [ -h ]         display help message
  --key [ -k ] <arg>    set key for signatures
  --quiet               suppress verbose, informational and progress  
messages
  --ssh-sign <arg>      sign with ssh-agent, 'yes' to sign with ssh  
if key
                        found, 'no' to force monotone to sign,  
'check' to sign
                        with both and compare
  --version             print version number, then exit

command groups:

automation, database, debug, informative, key, cert, network, packet,  
rcs, review,
tree, vars, workspace

common commands:

  annotate               Prints an annotated copy of a file
  diff                   Shows current differences
  list                   Shows database objects
  log                    Prints history in reverse order
  status                 Shows workspace's status information
  serve                  Serves the database to connecting clients
  sync                   Synchronizes branches with a netsync server
  checkout               Checks out a revision from the database  
into a directory
  merge                  Merges unmerged heads of a branch
  add                    Adds files to the workspace
  commit                 Commits workspace changes to the database
  rename                 Renames entries in the workspace
  drop                   Drops files from the workspace
  update                 Updates the workspace

Use "mtn help <command group>" for more information on commands in  
that group, or
use "mtn help <command>" for more information on a particular command.



Then if they use "mtn help <command group>" you might get something  
like this:

% mtn help workspace
Usage: mtn [OPTION...] command [ARG...]

  --confdir <arg>       set location of configuration directory
  --db [ -d ] <arg>     set name of database
  --debug               print debug log to stderr while running
  --dump <arg>          file to dump debugging log to, on failure
  --full-version        print detailed version number, then exit
  --help [ -h ]         display help message
  --key [ -k ] <arg>    set key for signatures
  --keydir <arg>        set location of key store
  --log <arg>           file to write the log to
  --norc                do not load ~/.monotone/monotonerc or _MTN/ 
monotonerc lua files
  --nostd               do not load standard lua hooks
  --quiet               suppress verbose, informational and progress  
messages
  --rcfile <arg>        load extra rc file
  --reallyquiet         suppress warning, verbose, informational and  
progress messages
  --root <arg>          limit search for workspace to specified root
  --ssh-sign <arg>      sign with ssh-agent, 'yes' to sign with ssh  
if key
                        found, 'no' to force monotone to sign,  
'check' to sign
                        with both and compare
  --ticker <arg>        set ticker style (count|dot|none)
  --version             print version number, then exit
  --xargs [ -@ ] <arg>  insert command line arguments taken from the  
given file

Commands for workspace manipulation:

  add                    Adds files to the workspace
  attr                   Manages file attributes
  commit, ci             Commits workspace changes to the database
  drop, rm               Drops files from the workspace
  mkdir                  Creates directories and adds them to the  
workspace
  pivot_root             Renames the root directory
  pluck                  Applies changes made at arbitrary places in  
history
  rename, mv             Renames entries in the workspace
  revert                 Reverts files and/or directories
  update                 Updates the workspace

Use "mtn help <command>" for more information on a particular command.


Finally, the output for "mtn help <command>" would be the same as  
currently.

Does that meet your requirements of helpfulness?

Cheers,

Will         :-}