[MERGE] concise help for commands by default

[Ben Finney]

Martin Pool <mbp at sourcefrog.net> writes:

> 2009/2/17 Ben Finney <bignose+hates-spam at benfinney.id.au>:
> > -1 for '--help' giving different behaviour from'-h'.
> 
> That was what I meant; -h would no longer be an abbreviation of
> --help but rather of --short-help. Cos it's short.

That would make it differ from the vast majority of tools that provide
‘-h’ and ‘--help’ as short/long options for getting at help. And that
difference, I think, would be inexcusable for an interface that people
are trying to use to figure out the rest of the interface :-)

I'm firmly of the position that ‘-h’ and ‘--help’ should be exactly
synonymous; indeed, should be thought of as alternate spellings of the
same option. That's a convention unbroken by just about any of the
thousands of programs I've encountered which provide both names.


I wouldn't be against the following behaviour:

  --short-help        Displays short help.

  --long-help         Displays long help.

  -h, --help          Same as ‘--short-help’.

This way, the unity of the option known by the names ‘-h’ and ‘--help’
remains, and only its behaviour changes.

I also think that it's important to actually have two new options (and
not just a single new option) for the distinct types of help that are
being provided. While learning about the interface, if I, as a Bazaar
newcomer, arbitrarily see one of ‘--short-help’ or ‘--long-help’, my
mental model will immediately infer the existence of the corresponding
other option; so it would be better if the interface conforms with
that mental model.

-- 
 \     “I hope that after I die, people will say of me: ‘That guy sure |
  `\                            owed me a lot of money’.” —Jack Handey |
_o__)                                                                  |
Ben Finney