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

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

[Bagas Sanjaya]

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>...]
 
 DESCRIPTION
 -----------

base-commit: 1a4874565fa3b6668042216189551b98b4dc0b1b
-- 
An old man doll... just what I always wanted! - Clara

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

[Junio C Hamano]

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.

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

>  [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.

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

[Bagas Sanjaya]

On 14/03/22 02.00, Junio C Hamano wrote:
> 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.

> 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

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

[Shaoxuan Yuan]

On Tue, Mar 22, 2022 at 3:11 PM Bagas Sanjaya <bagasdotme@gmail.com> wrote:
>
> On 14/03/22 02.00, Junio C Hamano wrote:
> > 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.

Yes, that's what I meant to say. Certainly "aesthetics" is not as appropriate
to be under evaluation here.

-- 
Thanks & Regards,
Shaoxuan

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

[Ævar Arnfjörð Bjarmason]

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?