[Rubygems-developers] New command-line help approach

[Gavin Sinclair]

On Friday, May 7, 2004, 6:39:45 AM, Ryan wrote:

> I agree with Michael.  His examples are also a lot like the Perforce
> command-line program, called p4, which I think is quite well designed.  The
> first parameter is always a command:

>    p4 edit <some_file>           # edit a file
>    p4 describe -s <some_change>  # describe a change in a short format
>    p4 help                       # show general p4 help
>    p4 help commands              # show generic help on the commands
>    p4 help edit                  # show specific help on the edit command

> Each command has its own options which come between the command name and the
> normal command parameters (like in describe above.)  Running the 'p4' command
> by itself shows the same output as 'p4 help'.

> This would be pretty easy to implement, just using a case for the command part,
> then maybe seperate optparse objects for each command's options/parameters.

That's an interesting thought.  But what about common options?  Is
there a way to mix OptionParser objects?

In defense of the current system, there is a distinction between
commands and options: only commands have short forms.  Thus:

  gem -i rake --gen-rdoc --install-stub --run-tests

There are exceptions:

  * minor commands (verify and alien) don't have short forms

  * major options (local/remote/both) have short forms, but these
    are distinguishable by their case: -R for --remote but -i for
    --install

The proposals have some appeal, but I don't think there's a real need
for change here.  Aesthetically, I'm happy with my example above, even
though I do like option/command distinctions.  The smarter help
facility is a good idea (although I have never really mastered CVS's
help system).

Fortunately, however, 'gem' is a small enough system that it doesn't
*need* hierachical help in the way some commands do.  True, the gem
reference is a bit long, but I think the average user can get going
with the software having read nothing but --help-examples.

Also fortunately, I think we're reaching the limits of gem's
functionality.  If the system doesn't get much more complex, then the
assumptions that have lead to its current design will continue to
hold.

# There are probably more things we can do, interface-wise, but I'm
# starting to think that we could end up with a command 'gemx' (gem
# extra) to handle non-core functions.

Cheers,
Gavin