A couple of weeks ago, I updated Monotone to 0.34 and noticed a small style problem in the help output: the line wrapping was not working properly, so some words got cut on the terminal's boundary. After resolving this minor issue, I realized that I didn't know what most of the commands shown in the main help screen did. Virtually all other command-line utilities that have integrated help show some form of an abstract description for each command which allows the novice to quickly see what they are about. So why wouldn't Monotone?
I started extending the internal commands interface to accept a little abstract for each command and command group, to be later shown in the help output. This was rather easy, and I posted some preliminary changes in to the mailing list. But you know what happens when proposing trivial changes...
People complained that the new output was too long to be useful, which I agreed on and fixed by only showing commands in a given group at a time. But... there was also an interesting request: allow the documentation of subcommands (e.g. list keys) in a consistent way with how primary commands (e.g. checkout) are defined. There is even a bug (#18281) about this issue.
And... that has kept me busy for way longer than I expected. I've ended up rewriting the way commands are defined internally by constructing a tree of commands instead of a plain list. This allows the generic command lookup algorithm to locate commands at any level in the tree, thus being able to standarize the way to define help and options on them.
I've also been messing with Cogito recently and found some of its user interface features to be very convenient. These include automatic paging of long output and colored diffs straight on the console. Something to borrow from them if I ever have the time for it, I guess ;-)
What did you think about this article?(Experimental)