[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Monotone-devel] More descriptive help summary

From: Julio M. Merino Vidal
Subject: Re: [Monotone-devel] More descriptive help summary
Date: Mon, 9 Apr 2007 09:45:51 +0200

On 09/04/2007, at 2:10, William Uther wrote:

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"

Or "remove" subcommands and make them regular commands (e.g. "db- init" instead of "db init"). At the moment some categories such as db or automation contain just a single command within them, which does a lot of things on its own and hides information one more level deep down.

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.

I like it.

An alternative could be to show no commands at all on the default help, but only the categories with a little blurb of what they are about. Such as:

[...options summary here...]

Command categories:

    automation  Commands for scripted execution
    db          Commands to manage the database

Type "mtn help <category>" to show information on all commands available in that category.

Dunno how useful that could be, though. I think I like more your idea ;-)


Julio M. Merino Vidal <address@hidden>

reply via email to

[Prev in Thread] Current Thread [Next in Thread]