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

From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Mar 22, 2022, 12:52 UTC
Message-ID: <220322.86r16up2n9.gmgdl@evledraar.gmail.com>
In-Reply-To: <20220312113136.26716-1-bagasdotme@gmail.com>

On Sat, Mar 12 2022, Bagas Sanjaya wrote:

Show 24 quoted lines

> Simplify SYNOPSIS section to only mention [<options>...] placeholder.
> Redundant options list can now be avoided for aesthetic and clarity.
>
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>
>  Shaoxuan Yuan suggested me to do the simplication, as in [1].
>
>  [1]:
> https://lore.kernel.org/git/CAJyCBORGGbn6d5UYMdRnfrbn9OONcgMMxaCyJ4qUoQY3+s8-uQ@mail.gmail.com/
>
>  Documentation/git-repack.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt
> index ee30edc178..39dac64833 100644
> --- a/Documentation/git-repack.txt
> +++ b/Documentation/git-repack.txt
> @@ -9,7 +9,7 @@ git-repack - Pack unpacked objects in a repository
>  SYNOPSIS
>  --------
>  [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>...]

I've been correcting some of the "git <cmd> -h" output recently, i.e. to update some of these, and disagree that we should just have this be <options>.

The point of this section is to give you a view at a glance of the available options without paging through OPTIONS.

This change proposes to basically do away with the section entirely. Since most commands take options we might as well remove all of the SYNOPSIS sections if we followed this pattern.

Now, I don't think we should do that, but I don't see if you do why you'd be targeting git-repack in particular. If you think it improves asthetics & clarity isn't that something that you'd think would also go for the rest of Documentation/git-*.txt, or just git-repack.txt for some (unstated) reason?