Re: [PATCH v3 21/36] doc txt & -h consistency: add missing options and labels

Instead of going over the patches in the rest of the series, I think we'd probably need to step back a bit and give ourselves a general guideline.

This list is a draft of things I have learned from reading the series, many of them from this step 21/36 alone, but some are from earlier steps. I think the ones with '*' in front of them are not controversial, but others are merely my suggestions at this point:

 * Use of spaces in optional [] and choose-from-one, both for
   freestanding token and for a value (i.e. what immediately follows
   an equal sign '='), are as specified in [PATCH 1/36].

 * For a command "git cmd", the documentation in the SYNOPSIS
   section and the usage string from "git cmd -h" ought to match.
   Let's call them simply a "usage string".

 * The usage string for a command that has majorly different
   operating modes can and should enumerate the different forms
   separately (cf. how "git diff -h" lists different modes).

 * The usage string for a command with a large number of options can
   and should use "[<options>]" placeholder in the SYNOPSIS and
   "usage:" lines, i.e. "git cmd [<options>]", and let the
   DESCRIPTION section (in documentation) and the option listing (in
   the output from usage_with_options() function).

 + The usage string for a command with a small number of options can
   enumerate individual options as long as the result (for each
   operating modes) can fit on a single line.

 + When a usage string shows options individually (instead of using
   [<options>] placeholder and leaving the listing to the latter
   half of usage_with_options()):

   - if an option has both long and short forms, only long form can
     and should be shown if the resulting line would become overly
     long with both listed as choices.

     do   : "git cmd [--quiet] [--verbose] [--dry-run] <pathspec>"
     don't: "git cmd [--quiet | -q] [--verbose | -v] [--dry-run | -n] <pathspec>"

   - when showing a Boolean option, show only the form that
     countermands the default, unless the command can take a
     different default depending on the context.  When use of other
     options or configuration can change the default value, show the
     option as "--[no-]option".

     do   : "git pack-refs [--all] [--no-prune]"
     don't: "git pack-refs [--[no-]all] [--[no-]prune]"

   - when showing an option that can be given multiple times that
     causes cumulative effect (as opposed to the "last one wins"),
     signal that by saying "--option..." to signal that it is
     meaningful to have one or more of them.