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

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

On Sat, Mar 12 2022, Bagas Sanjaya wrote:

> 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?