On 14/03/22 02.00, Junio C Hamano wrote:
Bagas Sanjaya <bagasdotme@xxxxxxxxx> writes:
Simplify SYNOPSIS section to only mention [<options>...] placeholder.
Redundant options list can now be avoided for aesthetic and clarity.
The "git cmd --help" output is meant to be readable and useful, so
clarity is good, but I do not know much about aesthetics.
Sorry for the long delay. I wish I could just say "for the clarity"
here.
More importantly, the above does not answer a lot more important
question. Is it just loss of duplicated information that this
commit brings in? Isn't the motivation that "not all options are
listed in SYNOPSIS section, and/or some options listed there are not
described in the body text and are not supported"? And instead of
trying to keep them in sync, the author chose to simplify SYNOPSIS
and have readers look options up in the body text, no? These two
would make a good pair of "what problem do we solve?" and "how we
choose to solve it?".
Indeed not all options are listed in SYNOPSIS, and in my previous attempt
at [1], I followed suggestion from Shaoxuan.
[verse]
-'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [-b] [-m] [--window=<n>] [--depth=<n>] [--threads=<n>] [--keep-pack=<pack-name>] [--write-midx]
+'git repack' [<options>...]
Unlike commands with multiple "operation modes", "repack" does one
thing and only one thing, so a single-liner "git repack <options>"
may work well.
OK.
[1]: https://lore.kernel.org/git/CAJyCBORGGbn6d5UYMdRnfrbn9OONcgMMxaCyJ4qUoQY3+s8-uQ@xxxxxxxxxxxxxx/
--
An old man doll... just what I always wanted! - Clara
