Re: [PATCH] Documentation: simplify synopsis of git-repack(1)

From: Bagas Sanjaya <bagasdotme@gmail.com>
Date: Mar 22, 2022, 07:11 UTC
Message-ID: <93d4b801-491c-694e-704c-fbe68f90b660@gmail.com>
In-Reply-To: <xmqqsfrlvfs8.fsf@gitster.g>

On 14/03/22 02.00, Junio C Hamano wrote:

Show 8 quoted lines

> Bagas Sanjaya <bagasdotme@gmail.com> 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.

Show 10 quoted lines

> 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@mail.gmail.com/

-- 
An old man doll... just what I always wanted! - Clara