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

[Julio M. Merino Vidal]

On 12/04/2007, at 0:28, Thomas Keller wrote:

> 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

Yep, good catch.  This has been addressed.  Will push the changes in  
a while.

> 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:

I somewhat agree.  As you, I don't like that all sentences start with  
the same words.  But if they are reworded to not mention "Commands  
for..." or whatever, I feel they don't give the idea of being groups  
of commands.  But then there is the title before them that explicitly  
says that they are groups...

> c) If we're at it, I think we should re-group some items...

Indeed.

> 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"?

> 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.

> 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:

1. database is a command group that contains just one command, db,  
and in turn that command holds a lot of somewhat-related subcommands  
to manage the database.  One may ask: why aren't all these  
subcommands directly in the top-level command group 'database'?

2. workspace (to pick one) is a category with multiple somewhat- 
related commands, each one being independent.

For consistency, either it should be "mtn db_init" or "mtn workspace  
commit".  But I guess there is no chance in doing the former (and I  
don't like the latter).

> 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

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'.

Cheers,

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