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

[Thomas Keller]

Julio M. Merino Vidal schrieb:
>> 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.
> 
> Sounds fine.  But why is heads special and is not, e.g. "ls heads"?

Well, I have no idea, but I certainly would vote for putting heads under
ls (if we want to keep this kind of sub-commands anyways, see below).

>> 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?
> 
> Maybe.  I'm now more worried in the infrastructure needed to properly
> print out the information rather than these minor nits :-)  They can
> easily be fixed later on, even on the main branch without any hassle at
> all.

Its always the small things which people tend to argue heavily about,
especially if the beloved, known UI changes in any way... =)

>> 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.
> 
> Yeah, and here is where my previous concerns raise again.  Where does
> one draw the line between command groups and subcommands?  Because the
> current interface is inconsistent [...]

IMHO having multi-word commands would be more consistent and I'd happily
implement that, but I guess nobody would use it actually =). I
absolutely dislike command names with dashes or even underscores in it,
they are long and naturally hard to type.

But what about the following: Let us put all commands into appropriate
groups, but allow shorthands, in the way

  mtn commit

is actually resolved to

  mtn workspace commit

just because there is no other command group which also has a "commit"
command. Now if we would introduce a "commit" command in some other
group, there could be the output

mtn: "commit" resolves to multiple commands, which one did you mean?
mtn:
mtn:   workspace commit   Commit workspace to database
mtn:   foo commit         Commit foo to somewhere

This would also resolve the "mtn heads" <> "mtn list heads" issue.
Logically (for the help output) the heads command would be listed under
list (ls), but mtn heads would also work (as before) because there is no
other command with the same name (yet).

>> 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?
> 
> In this case the syntax could show:
> 
> mtn checkout --revision foo bar
> mtn checkout --branch foo bar

Hrm... good idea... now the question is how one could define such mutual
exclusive options with the CMD macro? By allowing a list of strings
instead of a single string as third parameter?

> being the two mutually exclusively.  I've seen such an output multiple
> times.  (See man netstat for an example.)
> 
> And now that you mention options.  This is something I've always found
> weird in every program I've seen: why oh why is --version an option
> instead of a subcommand?  It is changing the whole behavior of the
> program, much like the 'help' command does.  So it should really be 'mtn
> version'.

100% ACK... go for it!

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