git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* [PATCH] Documentation: simplify synopsis of git-repack(1)
@ 2022-03-12 11:31 Bagas Sanjaya
  2022-03-13 19:00 ` Junio C Hamano
  2022-03-22 12:52 ` Ævar Arnfjörð Bjarmason
  0 siblings, 2 replies; 5+ messages in thread
From: Bagas Sanjaya @ 2022-03-12 11:31 UTC (permalink / raw)
  To: git; +Cc: Shaoxuan Yuan, Taylor Blau, Derrick Stolee, 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


^ permalink raw reply related	[flat|nested] 5+ messages in thread

* Re: [PATCH] Documentation: simplify synopsis of git-repack(1)
  2022-03-12 11:31 [PATCH] Documentation: simplify synopsis of git-repack(1) Bagas Sanjaya
@ 2022-03-13 19:00 ` Junio C Hamano
  2022-03-22  7:11   ` Bagas Sanjaya
  2022-03-22 12:52 ` Ævar Arnfjörð Bjarmason
  1 sibling, 1 reply; 5+ messages in thread
From: Junio C Hamano @ 2022-03-13 19:00 UTC (permalink / raw)
  To: Bagas Sanjaya; +Cc: git, Shaoxuan Yuan, Taylor Blau, Derrick Stolee

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.

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: [PATCH] Documentation: simplify synopsis of git-repack(1)
  2022-03-13 19:00 ` Junio C Hamano
@ 2022-03-22  7:11   ` Bagas Sanjaya
  2022-03-22  9:16     ` Shaoxuan Yuan
  0 siblings, 1 reply; 5+ messages in thread
From: Bagas Sanjaya @ 2022-03-22  7:11 UTC (permalink / raw)
  To: Junio C Hamano; +Cc: git, Shaoxuan Yuan, Taylor Blau, Derrick Stolee

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

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: [PATCH] Documentation: simplify synopsis of git-repack(1)
  2022-03-22  7:11   ` Bagas Sanjaya
@ 2022-03-22  9:16     ` Shaoxuan Yuan
  0 siblings, 0 replies; 5+ messages in thread
From: Shaoxuan Yuan @ 2022-03-22  9:16 UTC (permalink / raw)
  To: Bagas Sanjaya; +Cc: Junio C Hamano, git, Taylor Blau, Derrick Stolee

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

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: [PATCH] Documentation: simplify synopsis of git-repack(1)
  2022-03-12 11:31 [PATCH] Documentation: simplify synopsis of git-repack(1) Bagas Sanjaya
  2022-03-13 19:00 ` Junio C Hamano
@ 2022-03-22 12:52 ` Ævar Arnfjörð Bjarmason
  1 sibling, 0 replies; 5+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-03-22 12:52 UTC (permalink / raw)
  To: Bagas Sanjaya; +Cc: git, Shaoxuan Yuan, Taylor Blau, Derrick Stolee


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?

^ permalink raw reply	[flat|nested] 5+ messages in thread

end of thread, other threads:[~2022-03-22 12:56 UTC | newest]

Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-03-12 11:31 [PATCH] Documentation: simplify synopsis of git-repack(1) Bagas Sanjaya
2022-03-13 19:00 ` Junio C Hamano
2022-03-22  7:11   ` Bagas Sanjaya
2022-03-22  9:16     ` Shaoxuan Yuan
2022-03-22 12:52 ` Ævar Arnfjörð Bjarmason

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).