Re: [Monotone-devel] Re: More descriptive help summary

[Thomas Keller]

Julio M. Merino Vidal schrieb:
> I've pushed some changes into the net.venge.monotone.help-rewrite
> branch.  It holds a proof of concept of these changes to the help
> command.  There is still work to do though, so do not consider this final.
> 
> Comments welcome!

I've build your recent rev (ab1af5b230e686b0b24d5557bcb0780fbea0f77c)
and here are my ramblings:

a) I'd really like to see aliases for commands grouped to the particular
command, so instead

Commands to manipulate the tree:
  checkout    Checks out a revision from the database into a directory
  co          Checks out a revision from the database into a directory

something like

Commands to manipulate the tree:
  checkout (co)  Checks out a revision from the database into a directory

(one or more aliases would go into into braces, separated by comma) or

Commands to manipulate the tree:
  checkout|co    Checks out a revision from the database into a directory

(the alias(es) are separated by a pipe from the main command, which
takes less space


b) From my personal view I'd improve the naming of the command groups so
they do not all have to start with "Commands (that|for|to)", which is
IMHO not needed:

  automation    Aid for scripted execution
  database      Manipulate the database
  debug         Aid in program debugging
  informative   Retrieve information
  key and cert  Manage keys and certificates
  network       Access the network
  packet i/o    Read and write packets
  rcs           Interact with RCS and CVS
  review        Review revisions
  tree          Manipulate the tree
  vars          Manage persistent variables
  workspace     Deal with the workspace

Note that I'm not a native English speaker, so some of these could mean
foobar, but you should get the idea.

c) If we're at it, I think we should re-group some items... f.e. the
"heads" command doesn't actually manipulate the tree, so it shouldn't be
grouped in there, but rather into the "information" group. And what
about merge_into_workspace? Yes, this is a merge command, but on the
other side it doesn't affect the tree in the database, as it writes out
a merge revision into the workspace, so maybe it would be better grouped
in there?

d) Furthermore, as William already proposed, I'd really like to see
proper help machinery for subcommands as well. We're having now a couple
of commands which take sub commands (db, ls, automate), and while some
might say "ls is crappy and should be replaced anyways", there is still
db and automate which needs our attention.

e) And finally, this is something that also affects the options setup
and maybe the general understanding of arguments and options, and maybe
its just my understanding of options that is still incomplete.
However, I always think of an option as of something completly optional,
i.e. the command will output / do something reasonable even without
giving this implicit option.
Now some commands (checkout, clone, etc.) have two or more possible
options (in this case --revision and --branch), which are not completly
optional, but more of a "either this or that or both" deal. I wonder how
one can make this particular circumstance more explicit to the novice user?

Thomas.

-- 
ICQ: 85945241 | SIP: 1-747-027-0392 | http://www.thomaskeller.biz
> Guitone, a frontend for monotone: http://guitone.thomaskeller.biz
> Music lyrics and more: http://musicmademe.com