rev-parse --parseopt: option argument name hints

Built-in commands can specify names for option arguments when usage text
is generated for a command.  sh based commands should be able to do the
same.

Option argument name hint is any text that comes after [*=?!] after the
argument name up to the first whitespace.

Signed-off-by: Ilya Bobyr <ilya.bobyr@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
t1502: protect runs of SPs used in the indentation

The expected output from the argument help use runs of SPs to align
the description of each option; a careless use of --whitespace=fix
can turn leading parts of them into appropriate number of HTs.
Prevent such a breakage by prefixing all the expected lines with
leading vertical bars in the original and stripping them with a
small sed script.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
parse-options: multi-word argh should use dash to separate words

"When you need to use space, use dash" is a strange way to say that
you must not use a space.  By convention, most of the command line
descriptions use dashed-multi-words, and technically, you do not
even need or want to use spaces in these places---you should be
spelling your multi-word-parameters with words separated with
dashes.  Rephrase the documentation to avoid this strangeness.

Fix a few existing multi-word argument help strings, i.e.

 - GPG key-ids given to -S/--gpg-sign are "key-id";
 - Refs used for storing notes are "notes-ref"; and
 - Expiry timestamps given to --expire are "expiry-date".

Signed-off-by: Junio C Hamano <gitster@pobox.com>
update-index: teach --cacheinfo a new syntax mode,sha1,path

The "--cacheinfo" option is very unusual in that it takes three
option parameters.  An option with an optional parameter is bad
enough.  An option with multiple parameters is simply insane.

Introduce a new syntax that takes these three things concatenated
together with a comma, which makes the command line syntax more
uniform across subcommands, while retaining the traditional syntax
for backward compatiblity.

If we were designing the "update-index" subcommand from scratch
today, it may probably have made sense to make this option (and
possibly others) a command mode option that does not take any option
parameter (hence no need for arg-help).  But we do not live in such
an ideal world, and as far as I can tell, the command still supports
(and must support) mixed command modes in a single invocation, e.g.

    $ git update-index path1 --add path2 \
        --cacheinfo 100644 $(git hash-object --stdin -w <path3) path3 \
	path4

must make sure path1 is already in the index and update all of these
four paths.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
parse-options: make sure argh string does not have SP or _

We encourage an argument hint that consists of multiple words to be
spelled as a single-token separated with dashes.  In order to help
catching violations added by new users of parse-options, make sure
argh does not contain SP or _ when the code validates the option
definitions.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
Merge branch 'ib/rev-parse-parseopt-argh' into jch

* ib/rev-parse-parseopt-argh:
  parse-options: make sure argh string does not have SP or _
  update-index: teach --cacheinfo a new syntax mode,sha1,path
  parse-options: multi-word argh should use dash to separate words
  t1502: protect runs of SPs used in the indentation
  rev-parse --parseopt: option argument name hints