threads / patch / 57546

patchDocumentation: simplify synopsis of git-repack(1)

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

## tl;dr

5 messages between Mar 12, 2022 and Mar 22, 2022. Diffs are folded; open one to read it.

replies: 4people: 4as markdown or json

Bagas Sanjaya· Mar 12, 2022, 11:31 UTC · lore

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(-)
Show changes to Documentation/git-repack.txt +1 −1
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
Junio C Hamano· Mar 13, 2022, 19:00 UTC · re: Bagas Sanjaya · lore

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

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.

Bagas Sanjaya· Mar 22, 2022, 07:11 UTC · re: Junio C Hamano · lore

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

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
Shaoxuan Yuan· Mar 22, 2022, 09:16 UTC · re: Bagas Sanjaya · lore

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

On Tue, Mar 22, 2022 at 3:11 PM Bagas Sanjaya <bagasdotme@gmail.com> wrote:
Show 13 quoted lines
>
> 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
Ævar Arnfjörð Bjarmason· Mar 22, 2022, 12:52 UTC · re: Bagas Sanjaya · lore

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

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?

← back to recent threads