[Monotone-devel] More descriptive help summary

[Julio M. Merino Vidal]

Hello,

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.

Many other programs that support "subcommands" usually print a short  
summary of each one when asking for help.  This eases the  
identification of that specific command you need at a given moment.

What do think of doing something similar for monotone?  I've some  
local changes to implement this and the preliminary result can be  
seen at the end of this mail.  I still have to polish the abstracts  
and the category titles for it to be ready, though.

I might later do some other cleanups such as improving the  
descriptions of several commands and making them automatically adapt  
to the current terminal width (as other parts of the program do).

Cheers,

PS: The preliminary output.  Any line wrapping is my mailer's fault!

blaine:~/Projects/monotone> ./mtn
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:

Commands for automated execution
  automate               automation interface

Commands for database manipulation
  db                     Manipulates database state

Commands for program debugging
  asciik                 Prints an ASCII representation of the  
revisions' graph
  fdiff                  Differences 2 files and outputs the result
  fload                  Loads a file's contents into the database
  fmerge                 Merges 3 files and outputs the result
  get_roster             Dumps the roster associated with a given  
identifier
  identify               Calculates the identity of a file or stdin
  rcs_import             Parses versions in RCS files

Commands for information retrieval
  annotate               Prints an annotated copy of a file
  cat                    Prints a file from the database
  complete               Completes a partial identifier
  diff                   Shows current differences
  help                   Displays help about commands and options
  list                   Shows database objects
  log                    Prints history in reverse order
  ls                     Shows database objects
  show_conflicts         Shows what conflicts would need to be resolved
  status                 Shows workspace's status information

Commands for keys and certificates manipulation
  cert                   Creates a certificate for a revision
  dropkey                Drops a public and/or private key
  genkey                 Generates an RSA key-pair
  passphrase             Changes the passphrase of a private RSA key
  ssh_agent_add          Adds a private key to ssh-agent
  ssh_agent_export       Export a private key for use with ssh-agent
  trusted                Tests whether a hypothetical certificate  
would be trusted

Commands for network access
  clone                  Checks out a revision from remote a  
database into a directory
  pull                   Pulls branches from a netsync server
  push                   Pushes branches to a netsync server
  serve                  Serves the database to connecting clients
  sync                   Synchronizes branches with a netsync server

Commands for packet reading/writing
  privkey                Prints a private key packet
  pubkey                 Prints a public key packet
  read                   Reads packets from files

Commands for RCS interaction
  cvs_import             Imports all versions in a CVS repository

Commands for information reviewing
  approve                Approves a particular revision
  comment                Comments on a particular revision
  disapprove             Disapproves a particular revision
  tag                    Puts a symbolic tag certificate on a revision
  testresult             Notes the results of running a test on a  
revision

Commands for tree manipulation
  checkout               Checks out a revision from the database  
into a directory
  co                     Checks out a revision from the database  
into a directory
  explicit_merge         Merges two explicitly given revisions
  heads                  Shows unmerged head revisions of a branch
  import                 Imports the contents of a directory into a  
branch
  merge                  Merges unmerged heads of a branch
  merge_into_dir         Merges one branch into a subdirectory in  
another branch
  merge_into_workspace   Merges a revision into the current  
workspace's base revision
  migrate_workspace      Migrates a workspace directory's metadata  
to the latest format
  propagate              Merges from one branch to another  
asymmetrically
  refresh_inodeprints    Refreshes the inodeprint cache
  setup                  Sets up a new workspace directory

Commands for variables manipulation
  set                    Sets a database variable
  unset                  Unsets a database variable

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

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