{"thread":{"id":"57546","subject":"[PATCH] Documentation: simplify synopsis of git-repack(1)","startedAt":"2022-03-12T11:32:05Z","lastAt":"2022-03-22T12:56:03Z","messageCount":5,"participants":["Bagas Sanjaya","Junio C Hamano","Shaoxuan Yuan","Ævar Arnfjörð Bjarmason"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"451218","messageId":"20220312113136.26716-1-bagasdotme@gmail.com","threadId":"57546","inReplyTo":null,"subject":"[PATCH] Documentation: simplify synopsis of git-repack(1)","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2022-03-12T11:31:37Z","receivedAt":"2022-03-12T11:32:05Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"Simplify SYNOPSIS section to only mention [<options>...] placeholder.\nRedundant options list can now be avoided for aesthetic and clarity.\n\nSigned-off-by: Bagas Sanjaya <bagasdotme@gmail.com>\n---\n\n Shaoxuan Yuan suggested me to do the simplication, as in [1].\n\n [1]:\nhttps://lore.kernel.org/git/CAJyCBORGGbn6d5UYMdRnfrbn9OONcgMMxaCyJ4qUoQY3+s8-uQ@mail.gmail.com/\n\n Documentation/git-repack.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt\nindex ee30edc178..39dac64833 100644\n--- a/Documentation/git-repack.txt\n+++ b/Documentation/git-repack.txt\n@@ -9,7 +9,7 @@ git-repack - Pack unpacked objects in a repository\n SYNOPSIS\n --------\n [verse]\n-'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [-b] [-m] [--window=<n>] [--depth=<n>] [--threads=<n>] [--keep-pack=<pack-name>] [--write-midx]\n+'git repack' [<options>...]\n \n DESCRIPTION\n -----------\n\nbase-commit: 1a4874565fa3b6668042216189551b98b4dc0b1b\n-- \nAn old man doll... just what I always wanted! - Clara\n\n"},{"id":"451257","messageId":"xmqqsfrlvfs8.fsf@gitster.g","threadId":"57546","inReplyTo":"20220312113136.26716-1-bagasdotme@gmail.com","subject":"Re: [PATCH] Documentation: simplify synopsis of git-repack(1)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-03-13T19:00:39Z","receivedAt":"2022-03-13T19:00:54Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Bagas Sanjaya <bagasdotme@gmail.com> writes:\n\n> Simplify SYNOPSIS section to only mention [<options>...] placeholder.\n> Redundant options list can now be avoided for aesthetic and clarity.\n\nThe \"git cmd --help\" output is meant to be readable and useful, so\nclarity is good, but I do not know much about aesthetics.\n\nMore importantly, the above does not answer a lot more important\nquestion.  Is it just loss of duplicated information that this\ncommit brings in?  Isn't the motivation that \"not all options are\nlisted in SYNOPSIS section, and/or some options listed there are not\ndescribed in the body text and are not supported\"?  And instead of\ntrying to keep them in sync, the author chose to simplify SYNOPSIS\nand have readers look options up in the body text, no?  These two\nwould make a good pair of \"what problem do we solve?\" and \"how we\nchoose to solve it?\".\n\n>  [verse]\n> -'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [-b] [-m] [--window=<n>] [--depth=<n>] [--threads=<n>] [--keep-pack=<pack-name>] [--write-midx]\n> +'git repack' [<options>...]\n\nUnlike commands with multiple \"operation modes\", \"repack\" does one\nthing and only one thing, so a single-liner \"git repack <options>\"\nmay work well.\n"},{"id":"451830","messageId":"93d4b801-491c-694e-704c-fbe68f90b660@gmail.com","threadId":"57546","inReplyTo":"xmqqsfrlvfs8.fsf@gitster.g","subject":"Re: [PATCH] Documentation: simplify synopsis of git-repack(1)","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2022-03-22T07:11:53Z","receivedAt":"2022-03-22T07:12:01Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On 14/03/22 02.00, Junio C Hamano wrote:\n> Bagas Sanjaya <bagasdotme@gmail.com> writes:\n> \n>> Simplify SYNOPSIS section to only mention [<options>...] placeholder.\n>> Redundant options list can now be avoided for aesthetic and clarity.\n> \n> The \"git cmd --help\" output is meant to be readable and useful, so\n> clarity is good, but I do not know much about aesthetics.\n> \n\nSorry for the long delay. I wish I could just say \"for the clarity\"\nhere.\n\n> More importantly, the above does not answer a lot more important\n> question.  Is it just loss of duplicated information that this\n> commit brings in?  Isn't the motivation that \"not all options are\n> listed in SYNOPSIS section, and/or some options listed there are not\n> described in the body text and are not supported\"?  And instead of\n> trying to keep them in sync, the author chose to simplify SYNOPSIS\n> and have readers look options up in the body text, no?  These two\n> would make a good pair of \"what problem do we solve?\" and \"how we\n> choose to solve it?\".\n> \n\nIndeed not all options are listed in SYNOPSIS, and in my previous attempt\nat [1], I followed suggestion from Shaoxuan.\n\n>>   [verse]\n>> -'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [-b] [-m] [--window=<n>] [--depth=<n>] [--threads=<n>] [--keep-pack=<pack-name>] [--write-midx]\n>> +'git repack' [<options>...]\n> \n\n> Unlike commands with multiple \"operation modes\", \"repack\" does one\n> thing and only one thing, so a single-liner \"git repack <options>\"\n> may work well.\n\nOK.\n\n[1]: https://lore.kernel.org/git/CAJyCBORGGbn6d5UYMdRnfrbn9OONcgMMxaCyJ4qUoQY3+s8-uQ@mail.gmail.com/\n-- \nAn old man doll... just what I always wanted! - Clara\n"},{"id":"451835","messageId":"CAJyCBORBK+j4nnG-MWYksRcXJPPPpAhiqVagqUS=t1itCTWoWg@mail.gmail.com","threadId":"57546","inReplyTo":"93d4b801-491c-694e-704c-fbe68f90b660@gmail.com","subject":"Re: [PATCH] Documentation: simplify synopsis of git-repack(1)","fromName":"Shaoxuan Yuan","fromEmail":"shaoxuan.yuan02@gmail.com","sentAt":"2022-03-22T09:16:44Z","receivedAt":"2022-03-22T09:17:05Z","isPatch":true,"sender":{"key":"shaoxuan.yuan02@gmail.com","avatar":"https://avatars.githubusercontent.com/u/46557895?v=4"},"body":"On Tue, Mar 22, 2022 at 3:11 PM Bagas Sanjaya <bagasdotme@gmail.com> wrote:\n>\n> On 14/03/22 02.00, Junio C Hamano wrote:\n> > Bagas Sanjaya <bagasdotme@gmail.com> writes:\n> >\n> >> Simplify SYNOPSIS section to only mention [<options>...] placeholder.\n> >> Redundant options list can now be avoided for aesthetic and clarity.\n> >\n> > The \"git cmd --help\" output is meant to be readable and useful, so\n> > clarity is good, but I do not know much about aesthetics.\n> >\n>\n> Sorry for the long delay. I wish I could just say \"for the clarity\"\n> here.\n\nYes, that's what I meant to say. Certainly \"aesthetics\" is not as appropriate\nto be under evaluation here.\n\n-- \nThanks & Regards,\nShaoxuan\n"},{"id":"451843","messageId":"220322.86r16up2n9.gmgdl@evledraar.gmail.com","threadId":"57546","inReplyTo":"20220312113136.26716-1-bagasdotme@gmail.com","subject":"Re: [PATCH] Documentation: simplify synopsis of git-repack(1)","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-03-22T12:52:43Z","receivedAt":"2022-03-22T12:56:03Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Sat, Mar 12 2022, Bagas Sanjaya wrote:\n\n> Simplify SYNOPSIS section to only mention [<options>...] placeholder.\n> Redundant options list can now be avoided for aesthetic and clarity.\n>\n> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>\n> ---\n>\n>  Shaoxuan Yuan suggested me to do the simplication, as in [1].\n>\n>  [1]:\n> https://lore.kernel.org/git/CAJyCBORGGbn6d5UYMdRnfrbn9OONcgMMxaCyJ4qUoQY3+s8-uQ@mail.gmail.com/\n>\n>  Documentation/git-repack.txt | 2 +-\n>  1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt\n> index ee30edc178..39dac64833 100644\n> --- a/Documentation/git-repack.txt\n> +++ b/Documentation/git-repack.txt\n> @@ -9,7 +9,7 @@ git-repack - Pack unpacked objects in a repository\n>  SYNOPSIS\n>  --------\n>  [verse]\n> -'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [-b] [-m] [--window=<n>] [--depth=<n>] [--threads=<n>] [--keep-pack=<pack-name>] [--write-midx]\n> +'git repack' [<options>...]\n\nI've been correcting some of the \"git <cmd> -h\" output recently, i.e. to\nupdate some of these, and disagree that we should just have this be\n<options>.\n\nThe point of this section is to give you a view at a glance of the\navailable options without paging through OPTIONS.\n\nThis change proposes to basically do away with the section\nentirely. Since most commands take options we might as well remove all\nof the SYNOPSIS sections if we followed this pattern.\n\nNow, I don't think we should do that, but I don't see if you do why\nyou'd be targeting git-repack in particular. If you think it improves\nasthetics & clarity isn't that something that you'd think would also go\nfor the rest of Documentation/git-*.txt, or just git-repack.txt for some\n(unstated) reason?\n"}]}