| Message ID | 20220312113136.26716-1-bagasdotme@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Documentation: simplify synopsis of git-repack(1) | expand |
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.
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/
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.
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?
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 -----------
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(-) base-commit: 1a4874565fa3b6668042216189551b98b4dc0b1b