{"thread":{"id":"60969","subject":"[PATCH 0/3] Doc placeholders","startedAt":"2024-02-20T22:32:57Z","lastAt":"2024-02-24T18:28:55Z","messageCount":15,"participants":["Jean-Noël Avila via GitGitGadget","Eric Sunshine","Junio C Hamano","Jean-Noël Avila","Jean-Noël AVILA"],"isPatch":true,"patchVersion":1,"patchTotal":3},"messages":[{"id":"489033","messageId":"pull.1670.git.1708468374.gitgitgadget@gmail.com","threadId":"60969","inReplyTo":null,"subject":"[PATCH 0/3] Doc placeholders","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-02-20T22:32:51Z","receivedAt":"2024-02-20T22:32:57Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Here a few commits of some typos/mistakes found while translating the\nmanpages.\n\nJean-Noël Avila (3):\n doc: git-rev-parse: enforce command-line description syntax\n doc: git-clone fix missing placeholder end carret\n doc: add some missing sentence dots.\n\n Documentation/config/diff.txt | 4 ++--\n Documentation/git-clone.txt | 2 +-\n Documentation/git-fast-export.txt | 2 +-\n Documentation/git-rev-parse.txt | 24 ++++++++++++------------\n 4 files changed, 16 insertions(+), 16 deletions(-)\n\n\nbase-commit: 5fdd5b989cbe5096d44e89861a92b2dd47c279d9\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1670%2Fjnavila%2Fdoc_placeholders-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1670/jnavila/doc_placeholders-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1670\n-- \ngitgitgadget\n"},{"id":"489034","messageId":"17b0284c379e62a756e1bba008f4671f6afc0ad9.1708468374.git.gitgitgadget@gmail.com","threadId":"60969","inReplyTo":"pull.1670.git.1708468374.gitgitgadget@gmail.com","subject":"[PATCH 1/3] doc: git-rev-parse: enforce command-line description syntax","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-02-20T22:32:52Z","receivedAt":"2024-02-20T22:32:58Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n\ngit-rev-parse(1) manpage is completely off with respect to the\ncommand-line description syntax with badly formatted placeholders and\nmalformed alternatives.\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/git-rev-parse.txt | 24 ++++++++++++------------\n 1 file changed, 12 insertions(+), 12 deletions(-)\n\ndiff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt\nindex 546faf90177..5d83dd36da1 100644\n--- a/Documentation/git-rev-parse.txt\n+++ b/Documentation/git-rev-parse.txt\n@@ -9,7 +9,7 @@ git-rev-parse - Pick out and massage parameters\n SYNOPSIS\n --------\n [verse]\n-'git rev-parse' [] ...\n+'git rev-parse' [] ...\n \n DESCRIPTION\n -----------\n@@ -130,7 +130,7 @@ for another option.\n \t'git diff-{asterisk}'). In contrast to the `--sq-quote` option,\n \tthe command input is still interpreted as usual.\n \n---short[=length]::\n+--short[=]::\n \tSame as `--verify` but shortens the object name to a unique\n \tprefix with at least `length` characters. The minimum length\n \tis 4, the default is the effective value of the `core.abbrev`\n@@ -165,9 +165,9 @@ Options for Objects\n --all::\n \tShow all refs found in `refs/`.\n \n---branches[=pattern]::\n---tags[=pattern]::\n---remotes[=pattern]::\n+--branches[=]::\n+--tags[=]::\n+--remotes[=]::\n \tShow all branches, tags, or remote-tracking branches,\n \trespectively (i.e., refs found in `refs/heads`,\n \t`refs/tags`, or `refs/remotes`, respectively).\n@@ -176,7 +176,7 @@ If a `pattern` is given, only refs matching the given shell glob are\n shown. If the pattern does not contain a globbing character (`?`,\n `*`, or `[`), it is turned into a prefix match by appending `/*`.\n \n---glob=pattern::\n+--glob=::\n \tShow all refs matching the shell glob pattern `pattern`. If\n \tthe pattern does not start with `refs/`, this is automatically\n \tprepended. If the pattern does not contain a globbing\n@@ -197,7 +197,7 @@ respectively, and they must begin with `refs/` when applied to `--glob`\n or `--all`. If a trailing '/{asterisk}' is intended, it must be given\n explicitly.\n \n---exclude-hidden=[fetch|receive|uploadpack]::\n+--exclude-hidden=(fetch|receive|uploadpack)::\n \tDo not include refs that would be hidden by `git-fetch`,\n \t`git-receive-pack` or `git-upload-pack` by consulting the appropriate\n \t`fetch.hideRefs`, `receive.hideRefs` or `uploadpack.hideRefs`\n@@ -314,17 +314,17 @@ The following options are unaffected by `--path-format`:\n Other Options\n ~~~~~~~~~~~~~\n \n---since=datestring::\n---after=datestring::\n+--since=::\n+--after=::\n \tParse the date string, and output the corresponding\n \t--max-age= parameter for 'git rev-list'.\n \n---until=datestring::\n---before=datestring::\n+--until=::\n+--before=::\n \tParse the date string, and output the corresponding\n \t--min-age= parameter for 'git rev-list'.\n \n-...::\n+...::\n \tFlags and parameters to be parsed.\n \n \n-- \ngitgitgadget\n\n"},{"id":"489035","messageId":"7d85bfe6c5511d3918dd84365249797abe6fa04b.1708468374.git.gitgitgadget@gmail.com","threadId":"60969","inReplyTo":"pull.1670.git.1708468374.gitgitgadget@gmail.com","subject":"[PATCH 2/3] doc: git-clone fix missing placeholder end carret","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-02-20T22:32:53Z","receivedAt":"2024-02-20T22:32:59Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/git-clone.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\nindex 6e43eb9c205..0c07720c6f4 100644\n--- a/Documentation/git-clone.txt\n+++ b/Documentation/git-clone.txt\n@@ -311,7 +311,7 @@ or `--mirror` is given)\n \tThe result is Git repository can be separated from working\n \ttree.\n \n---ref-format=::\n \n Specify the given ref storage format for the repository. The valid values are:\n +\n-- \ngitgitgadget\n\n"},{"id":"489036","messageId":"1faa934a152d2eedc8949c1e17aff787614770e2.1708468374.git.gitgitgadget@gmail.com","threadId":"60969","inReplyTo":"pull.1670.git.1708468374.gitgitgadget@gmail.com","subject":"[PATCH 3/3] doc: add some missing sentence dots.","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-02-20T22:32:54Z","receivedAt":"2024-02-20T22:33:00Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= \n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/config/diff.txt | 4 ++--\n Documentation/git-fast-export.txt | 2 +-\n 2 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt\nindex bd5ae0c3378..6c7e09a1ef5 100644\n--- a/Documentation/config/diff.txt\n+++ b/Documentation/config/diff.txt\n@@ -223,5 +223,5 @@ diff.colorMoved::\n \n diff.colorMovedWS::\n \tWhen moved lines are colored using e.g. the `diff.colorMoved` setting,\n-\tthis option controls the `` how spaces are treated\n-\tfor details of valid modes see '--color-moved-ws' in linkgit:git-diff[1].\n+\tthis option controls the `` how spaces are treated.\n+\tFor details of valid modes see '--color-moved-ws' in linkgit:git-diff[1].\ndiff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt\nindex 4643ddbe68f..752e4b9b01d 100644\n--- a/Documentation/git-fast-export.txt\n+++ b/Documentation/git-fast-export.txt\n@@ -48,7 +48,7 @@ When asking to 'abort' (which is the default), this program will die\n when encountering such a tag. With 'drop' it will omit such tags from\n the output. With 'rewrite', if the tagged object is a commit, it will\n rewrite the tag to tag an ancestor commit (via parent rewriting; see\n-linkgit:git-rev-list[1])\n+linkgit:git-rev-list[1]).\n \n -M::\n -C::\n-- \ngitgitgadget\n"},{"id":"489037","messageId":"CAPig+cSFK_sVZn5p3Bw12HOEF4Z99niPGMHp1Dp2w2EUjjZ4zw@mail.gmail.com","threadId":"60969","inReplyTo":"7d85bfe6c5511d3918dd84365249797abe6fa04b.1708468374.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 2/3] doc: git-clone fix missing placeholder end carret","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2024-02-20T22:39:48Z","receivedAt":"2024-02-20T22:40:00Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Tue, Feb 20, 2024 at 5:33 PM Jean-Noël Avila via GitGitGadget\n wrote:\n> doc: git-clone fix missing placeholder end carret\n\nI believe you meant: s/carret/caret/\n\nIn English, I think this symbol is typically called an \"angle bracket\".\n\nEither way, probably not worth a reroll since it's just a commit-message nit.\n\n> Signed-off-by: Jean-Noël Avila \n>\n> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\n> @@ -311,7 +311,7 @@ or `--mirror` is given)\n> ---ref-format= +--ref-format=::\n"},{"id":"489038","messageId":"xmqqzfvulph4.fsf@gitster.g","threadId":"60969","inReplyTo":"1faa934a152d2eedc8949c1e17aff787614770e2.1708468374.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 3/3] doc: add some missing sentence dots.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-02-20T22:50:47Z","receivedAt":"2024-02-20T22:50:50Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Jean-Noël Avila via GitGitGadget\" writes:\n\n> Subject: Re: [PATCH 3/3] doc: add some missing sentence dots.\n\n\"sentence dots.\" -> \"full stop at the end of sentence\" or something?\n\n> diff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt\n> index bd5ae0c3378..6c7e09a1ef5 100644\n> --- a/Documentation/config/diff.txt\n> +++ b/Documentation/config/diff.txt\n> @@ -223,5 +223,5 @@ diff.colorMoved::\n> \n> diff.colorMovedWS::\n> \tWhen moved lines are colored using e.g. the `diff.colorMoved` setting,\n> -\tthis option controls the `` how spaces are treated\n> -\tfor details of valid modes see '--color-moved-ws' in linkgit:git-diff[1].\n> +\tthis option controls the `` how spaces are treated.\n> +\tFor details of valid modes see '--color-moved-ws' in linkgit:git-diff[1].\n\nVery good. Thanks for spotting this one.\n\n> diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt\n> index 4643ddbe68f..752e4b9b01d 100644\n> --- a/Documentation/git-fast-export.txt\n> +++ b/Documentation/git-fast-export.txt\n> @@ -48,7 +48,7 @@ When asking to 'abort' (which is the default), this program will die\n> when encountering such a tag. With 'drop' it will omit such tags from\n> the output. With 'rewrite', if the tagged object is a commit, it will\n> rewrite the tag to tag an ancestor commit (via parent rewriting; see\n> -linkgit:git-rev-list[1])\n> +linkgit:git-rev-list[1]).\n\nDitto.\n"},{"id":"489039","messageId":"xmqqsf1mlp6f.fsf@gitster.g","threadId":"60969","inReplyTo":"17b0284c379e62a756e1bba008f4671f6afc0ad9.1708468374.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 1/3] doc: git-rev-parse: enforce command-line description syntax","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-02-20T22:57:12Z","receivedAt":"2024-02-20T22:57:15Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Jean-Noël Avila via GitGitGadget\" writes:\n\n> [verse]\n> -'git rev-parse' [] ...\n> +'git rev-parse' [] ...\n\nGood. The \"or more\" is signalled by the ellipsis, not \"args\" being\nplural.\n\n> ---short[=length]::\n> +--short[=]::\n> \tSame as `--verify` but shortens the object name to a unique\n> \tprefix with at least `length` characters. The minimum length\n\nThis same comment applies throughout this patch, but in other places\nwhen we use in the option argument description, don't\nwe use the same in text as well? I am wondering if\nthe `length` (typeset in fixed-width) should become . What\ndo other recent[*] documentation pages commonly do?\n\n\tSide note: I say \"recent\" because rev-parse doc is one of\n\tthe oldest ones that did not get typesetting attention they\n\tdeserve, compared to more recent ones that got nitpicked\n\twhile they were written and updated.\n\n> ---branches[=pattern]::\n> ---tags[=pattern]::\n> ---remotes[=pattern]::\n> +--branches[=]::\n> +--tags[=]::\n> +--remotes[=]::\n> \tShow all branches, tags, or remote-tracking branches,\n> \trespectively (i.e., refs found in `refs/heads`,\n> \t`refs/tags`, or `refs/remotes`, respectively).\n\nDitto. We see `pattern` that may want to become in the\ndescription (after the post context of this hunk).\n\n> ---glob=pattern::\n> +--glob=::\n> \tShow all refs matching the shell glob pattern `pattern`. If\n> \tthe pattern does not start with `refs/`, this is automatically\n> \tprepended. If the pattern does not contain a globbing\n\nDitto.\n\n> ---exclude-hidden=[fetch|receive|uploadpack]::\n> +--exclude-hidden=(fetch|receive|uploadpack)::\n> \tDo not include refs that would be hidden by `git-fetch`,\n> \t`git-receive-pack` or `git-upload-pack` by consulting the appropriate\n> \t`fetch.hideRefs`, `receive.hideRefs` or `uploadpack.hideRefs`\n\nGood.\n\n> ---since=datestring::\n> ---after=datestring::\n> +--since=::\n> +--after=::\n> \tParse the date string, and output the corresponding\n> \t--max-age= parameter for 'git rev-list'.\n\nGood, modulo possibly \"date string\" -> \"\".\n\n> ---until=datestring::\n> ---before=datestring::\n> +--until=::\n> +--before=::\n> \tParse the date string, and output the corresponding\n> \t--min-age= parameter for 'git rev-list'.\n\nDitto.\n\n> -...::\n> +...::\n> \tFlags and parameters to be parsed.\n\nGood.\n"},{"id":"489041","messageId":"xmqqh6i2loz0.fsf@gitster.g","threadId":"60969","inReplyTo":"CAPig+cSFK_sVZn5p3Bw12HOEF4Z99niPGMHp1Dp2w2EUjjZ4zw@mail.gmail.com","subject":"Re: [PATCH 2/3] doc: git-clone fix missing placeholder end carret","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-02-20T23:01:39Z","receivedAt":"2024-02-20T23:01:44Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Eric Sunshine writes:\n\n> On Tue, Feb 20, 2024 at 5:33 PM Jean-Noël Avila via GitGitGadget\n> wrote:\n>> doc: git-clone fix missing placeholder end carret\n>\n> I believe you meant: s/carret/caret/\n>\n> In English, I think this symbol is typically called an \"angle bracket\".\n\nYes, caret is \"^\".\n\n>> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\n>> @@ -311,7 +311,7 @@ or `--mirror` is given)\n>> ---ref-format=> +--ref-format=::\n\nA closing angle bracket is what is missing there. Thanks for\nreading carefully.\n"},{"id":"489053","messageId":"67dca173-3048-430b-88a1-d3b5d853f84b@free.fr","threadId":"60969","inReplyTo":"xmqqsf1mlp6f.fsf@gitster.g","subject":"Re: [PATCH 1/3] doc: git-rev-parse: enforce command-line description syntax","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2024-02-21T07:41:48Z","receivedAt":"2024-02-21T07:41:59Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Le 20/02/2024 à 23:57, Junio C Hamano a écrit :\n> \"Jean-Noël Avila via GitGitGadget\" writes:\n> \n>> [verse]\n>> -'git rev-parse' [] ...\n>> +'git rev-parse' [] ...\n> \n> Good. The \"or more\" is signalled by the ellipsis, not \"args\" being\n> plural.\n> \n>> ---short[=length]::\n>> +--short[=]::\n>> \tSame as `--verify` but shortens the object name to a unique\n>> \tprefix with at least `length` characters. The minimum length\n> \n> This same comment applies throughout this patch, but in other places\n> when we use in the option argument description, don't\n> we use the same in text as well? I am wondering if\n> the `length` (typeset in fixed-width) should become . What\n> do other recent[*] documentation pages commonly do?\n\nThis is another part of the inconsistences in documentation that I'd \nlike to tackle (hopefully, not in another life).\n\nUsing angle brackets for placeholders everywhere they appear is a visual \nlink to the preceding syntax description, but may feel a bit heavy on \nsome cases. Anyway, I'm all for applying the rule everywhere, for the \nsake of consistency.\n\nBackticks and single quotes are used indistinctively (by the way, \nasciidoctor does not process single quotes as markup) and are not used \neverywhere they should. Using backticks is also a good hint for \ntranslators to mean \"verbatim, do not translate\". Obviously, the \nplaceholders ask for translation, so the backtick rule should not apply \nto them, even if another formating would be welcome : __ \nfor instance?\n\n> \n> \tSide note: I say \"recent\" because rev-parse doc is one of\n> \tthe oldest ones that did not get typesetting attention they\n> \tdeserve, compared to more recent ones that got nitpicked\n> \twhile they were written and updated.\n> \n>> ---branches[=pattern]::\n>> ---tags[=pattern]::\n>> ---remotes[=pattern]::\n>> +--branches[=]::\n>> +--tags[=]::\n>> +--remotes[=]::\n>> \tShow all branches, tags, or remote-tracking branches,\n>> \trespectively (i.e., refs found in `refs/heads`,\n>> \t`refs/tags`, or `refs/remotes`, respectively).\n> \n> Ditto. We see `pattern` that may want to become in the\n> description (after the post context of this hunk).\n> \n>> ---glob=pattern::\n>> +--glob=::\n>> \tShow all refs matching the shell glob pattern `pattern`. If\n>> \tthe pattern does not start with `refs/`, this is automatically\n>> \tprepended. If the pattern does not contain a globbing\n> \n> Ditto.\n> \n>> ---exclude-hidden=[fetch|receive|uploadpack]::\n>> +--exclude-hidden=(fetch|receive|uploadpack)::\n>> \tDo not include refs that would be hidden by `git-fetch`,\n>> \t`git-receive-pack` or `git-upload-pack` by consulting the appropriate\n>> \t`fetch.hideRefs`, `receive.hideRefs` or `uploadpack.hideRefs`\n> \n> Good.\n> \n>> ---since=datestring::\n>> ---after=datestring::\n>> +--since=::\n>> +--after=::\n>> \tParse the date string, and output the corresponding\n>> \t--max-age= parameter for 'git rev-list'.\n> \n> Good, modulo possibly \"date string\" -> \"\".\n> \n>> ---until=datestring::\n>> ---before=datestring::\n>> +--until=::\n>> +--before=::\n>> \tParse the date string, and output the corresponding\n>> \t--min-age= parameter for 'git rev-list'.\n> \n> Ditto.\n> \n>> -...::\n>> +...::\n>> \tFlags and parameters to be parsed.\n> \n> Good.\n\n"},{"id":"489091","messageId":"xmqqfrxlpvv1.fsf@gitster.g","threadId":"60969","inReplyTo":"67dca173-3048-430b-88a1-d3b5d853f84b@free.fr","subject":"Re: [PATCH 1/3] doc: git-rev-parse: enforce command-line description syntax","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-02-21T17:31:30Z","receivedAt":"2024-02-21T17:31:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jean-Noël Avila writes:\n\n>>> ---short[=length]::\n>>> +--short[=]::\n>>> \tSame as `--verify` but shortens the object name to a unique\n>>> \tprefix with at least `length` characters. The minimum length\n>> This same comment applies throughout this patch, but in other places\n>> when we use in the option argument description, don't\n>> we use the same in text as well? I am wondering if\n>> the `length` (typeset in fixed-width) should become . What\n>> do other recent[*] documentation pages commonly do?\n>\n> This is another part of the inconsistences in documentation that I'd\n> like to tackle (hopefully, not in another life).\n>\n> Using angle brackets for placeholders everywhere they appear is a\n> visual link to the preceding syntax description, but may feel a bit\n> heavy on some cases. Anyway, I'm all for applying the rule everywhere,\n> for the sake of consistency.\n\nI agree that if is not an appropriate way to spell\nthem in the explanation text, we would want to change them\nconsistently everywhere, and until then, using the angle-bracketted\n that is common would be better. The text will be\nmodified again when we decide to switch from to\nsomething else, so updating them now may be a wasted effort, but (1)\nwe may decide that is good enough after all, or (2) it\nmay make it easier to mechanically identify words whose mark-up\nshould be converted if we consistently use now, even\nif we know it won't be the final mark-up.\n\nSo I am inclined to say that we should first do `length` -> \nin the body text in the short term. But I also think we should\n*not* do so as part of this patch, whose focus is how the option\nenumeration header should mark up the option arguments.\n\n> Backticks and single quotes are used indistinctively (by the way,\n> asciidoctor does not process single quotes as markup) and are not used\n> everywhere they should. Using backticks is also a good hint for\n> translators to mean \"verbatim, do not translate\". Obviously, the\n> placeholders ask for translation, so the backtick rule should not\n> apply to them, even if another formating would be welcome :\n> __ for instance?\n\nYes. The way AsciiDoc renders (at least HTML) an unadorned \nis not so great.\n\nIn \"git-add.html\" manual page, we see these examples. The first one\n(unadorned) does not make the placeholder word stand out enough; the\nsecond one that does `` makes it stand out better, but as you\nsaid, the `verbatim` mark-up is semantically wrong.\n\nhttps://git.github.io/htmldocs/git-add.html#:~:text=For%20more%20details%20about%20the%20%3Cpathspec%3E%20syntax\n\nhttps://git.github.io/htmldocs/git-add.html#:~:text=Pathspec%20is%20passed%20in%20%3Cfile%3E%20instead%20of%20commandline%20args.%20If%20%3Cfile%3E%20is%20exactly%20%2D%20then%20standard%20input%20is%20used.%20Pathspec\n\nThe last part of the Documentation/CodingGuidelines document talks\nabout how to mark up placeholders but it does not go beyond saying\nthat they are written as .\nWhatever mark-up rule we decide to use, we should document it there.\n\nThanks.\n\n\n"},{"id":"489109","messageId":"5764785.DvuYhMxLoT@cayenne","threadId":"60969","inReplyTo":"xmqqfrxlpvv1.fsf@gitster.g","subject":"Re: [PATCH 1/3] doc: git-rev-parse: enforce command-line description syntax","fromName":"Jean-Noël AVILA","fromEmail":"jn.avila@free.fr","sentAt":"2024-02-21T21:52:06Z","receivedAt":"2024-02-21T21:52:16Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"On Wednesday, 21 February 2024 18:31:30 CET Junio C Hamano wrote:\n> Jean-Noël Avila writes:\n> \n> >>> ---short[=length]::\n> >>> +--short[=]::\n> >>> \tSame as `--verify` but shortens the object name to a unique\n> >>> \tprefix with at least `length` characters. The minimum length\n> >> This same comment applies throughout this patch, but in other places\n> >> when we use in the option argument description, don't\n> >> we use the same in text as well? I am wondering if\n> >> the `length` (typeset in fixed-width) should become . What\n> >> do other recent[*] documentation pages commonly do?\n> >\n> > This is another part of the inconsistences in documentation that I'd\n> > like to tackle (hopefully, not in another life).\n> >\n> > Using angle brackets for placeholders everywhere they appear is a\n> > visual link to the preceding syntax description, but may feel a bit\n> > heavy on some cases. Anyway, I'm all for applying the rule everywhere,\n> > for the sake of consistency.\n> \n> I agree that if is not an appropriate way to spell\n> them in the explanation text, we would want to change them\n> consistently everywhere, and until then, using the angle-bracketted\n> that is common would be better. The text will be\n> modified again when we decide to switch from to\n> something else, so updating them now may be a wasted effort, but (1)\n> we may decide that is good enough after all, or (2) it\n> may make it easier to mechanically identify words whose mark-up\n> should be converted if we consistently use now, even\n> if we know it won't be the final mark-up.\n> \n> So I am inclined to say that we should first do `length` -> \n> in the body text in the short term. But I also think we should\n> *not* do so as part of this patch, whose focus is how the option\n> enumeration header should mark up the option arguments.\n> \n> > Backticks and single quotes are used indistinctively (by the way,\n> > asciidoctor does not process single quotes as markup) and are not used\n> > everywhere they should. Using backticks is also a good hint for\n> > translators to mean \"verbatim, do not translate\". Obviously, the\n> > placeholders ask for translation, so the backtick rule should not\n> > apply to them, even if another formating would be welcome :\n> > __ for instance?\n> \n> Yes. The way AsciiDoc renders (at least HTML) an unadorned \n> is not so great.\n> \n> In \"git-add.html\" manual page, we see these examples. The first one\n> (unadorned) does not make the placeholder word stand out enough; the\n> second one that does `` makes it stand out better, but as you\n> said, the `verbatim` mark-up is semantically wrong.\n> \n> https://git.github.io/htmldocs/git-add.html#:~:text=For%20more%20details%20about%20the%20%3Cpathspec%3E%20syntax\n> \n> https://git.github.io/htmldocs/git-add.html#:~:text=Pathspec%20is%20passed%20in%20%3Cfile%3E%20instead%20of%20commandline%20args.%20If%20%3Cfile%3E%20is%20exactly%20%2D%20then%20standard%20input%20is%20used.%20Pathspec\n> \n> The last part of the Documentation/CodingGuidelines document talks\n> about how to mark up placeholders but it does not go beyond saying\n> that they are written as .\n> Whatever mark-up rule we decide to use, we should document it there.\n> \n> Thanks.\n> \n> \n> \n> \n\nHi,\n\nI just saw that you pushed this series to 'next'. That's embarrassing because I missed other spots in the file were the formating was not correct. I was also preparing the changes of placeholders in paragraphs as suggested.\n\nShould I prepare another PR?\n\nThanks\n\n\n\n"},{"id":"489112","messageId":"xmqqbk89molz.fsf@gitster.g","threadId":"60969","inReplyTo":"xmqqfrxlpvv1.fsf@gitster.g","subject":"Re: [PATCH 1/3] doc: git-rev-parse: enforce command-line description syntax","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-02-21T22:36:24Z","receivedAt":"2024-02-21T22:36:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n>> Backticks and single quotes are used indistinctively (by the way,\n>> asciidoctor does not process single quotes as markup) ...\n\nHmph, it sounds like a bug of asciidoctor we'd need to work around?\n\nIn any case, I practiced your \"__\" rule on git-add.txt\nand here is how my local HTML rendition of the updated line in the\nfirst hunk in the attached patch looks like with \"AsciiDoc 10.2.0\".\n\n https://pasteboard.co/6koO0h0KJAjW.png\n\nThe actual HTML for the above part looks like this:\n\n

For more details about the\n <pathspec> syntax, see the pathspec entry\n in gitglossary(7).

\n\nIn the first hunk, the updated \"__\" is enclosed inside an\n.. pair, which is made into \"font-style: italic\" via css,\nwhile 'pathspec' that remains is already inside ...\n\nBy the way, I am getting some typesetting effect from the pair of\nsingle quotes with AsciiDoctor. Here is the rendition of the same\npart:\n\n https://pasteboard.co/LbDi95G8BNGv.png\n\nThe element in the generated HTML claims it\nis \"Asciidoctor 2.0.20\". The actual HTML for that piece looks like\nthis:\n\n

For more details about the <pathspec> syntax,\n see the pathspec entry\n in gitglossary(7).

\n\nSo, perhaps we do not have to do a lot of 'word' -> _word_\nreplacements, hopefully?\n\n----- >8 --------- >8 --------- >8 --------- >8 ----\n\nSubject: [PATCH] doc: apply the new placeholder rules to git-add documentation\n\nSigned-off-by: Junio C Hamano \n\ndiff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\nindex ed44c1cb31..b73071ba47 100644\n--- a/Documentation/git-add.txt\n+++ b/Documentation/git-add.txt\n@@ -63,7 +63,7 @@ OPTIONS\n \tto ignore removed files; use `--no-all` option if you want\n \tto add modified or new files but ignore removed ones.\n +\n-For more details about the syntax, see the 'pathspec' entry\n+For more details about the __ syntax, see the 'pathspec' entry\n in linkgit:gitglossary[7].\n \n -n::\n@@ -119,10 +119,10 @@ apply to the index. See EDITING PATCHES below.\n -u::\n --update::\n \tUpdate the index just where it already has an entry matching\n-\t. This removes as well as modifies index entries to\n+\t__. This removes as well as modifies index entries to\n \tmatch the working tree, but adds no new files.\n +\n-If no is given when `-u` option is used, all\n+If no __ is given when `-u` option is used, all\n tracked files in the entire working tree are updated (old versions\n of Git used to limit the update to the current directory and its\n subdirectories).\n@@ -131,11 +131,11 @@ subdirectories).\n --all::\n --no-ignore-removal::\n \tUpdate the index not only where the working tree has a file\n-\tmatching but also where the index already has an\n+\tmatching __ but also where the index already has an\n \tentry. This adds, modifies, and removes index entries to\n \tmatch the working tree.\n +\n-If no is given when `-A` option is used, all\n+If no __ is given when `-A` option is used, all\n files in the entire working tree are updated (old versions\n of Git used to limit the update to the current directory and its\n subdirectories).\n@@ -145,11 +145,11 @@ subdirectories).\n \tUpdate the index by adding new files that are unknown to the\n \tindex and files modified in the working tree, but ignore\n \tfiles that have been removed from the working tree. This\n-\toption is a no-op when no is used.\n+\toption is a no-op when no __ is used.\n +\n This option is primarily to help users who are used to older\n-versions of Git, whose \"git add ...\" was a synonym\n-for \"git add --no-all ...\", i.e. ignored removed files.\n+versions of Git, whose \"git add __...\" was a synonym\n+for \"git add --no-all __...\", i.e. ignored removed files.\n \n -N::\n --intent-to-add::\n@@ -198,8 +198,8 @@ for \"git add --no-all ...\", i.e. ignored removed files.\n \tunchanged.\n \n --pathspec-from-file=::\n-\tPathspec is passed in `` instead of commandline args. If\n-\t`` is exactly `-` then standard input is used. Pathspec\n+\tPathspec is passed in __ instead of commandline args. If\n+\t__ is exactly `-` then standard input is used. Pathspec\n \telements are separated by LF or CR/LF. Pathspec elements can be\n \tquoted as explained for the configuration variable `core.quotePath`\n \t(see linkgit:git-config[1]). See also `--pathspec-file-nul` and\n"},{"id":"489127","messageId":"2926790.e9J7NaK4W3@cayenne","threadId":"60969","inReplyTo":"xmqqbk89molz.fsf@gitster.g","subject":"Re: [PATCH 1/3] doc: git-rev-parse: enforce command-line description syntax","fromName":"Jean-Noël AVILA","fromEmail":"jn.avila@free.fr","sentAt":"2024-02-22T09:07:53Z","receivedAt":"2024-02-22T09:16:16Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"On Wednesday, 21 February 2024 23:36:24 CET Junio C Hamano wrote:\n> Junio C Hamano writes:\n> \n> >> Backticks and single quotes are used indistinctively (by the way,\n> >> asciidoctor does not process single quotes as markup) ...\n> \n> Hmph, it sounds like a bug of asciidoctor we'd need to work around?\n> \n> In any case, I practiced your \"__\" rule on git-add.txt\n> and here is how my local HTML rendition of the updated line in the\n> first hunk in the attached patch looks like with \"AsciiDoc 10.2.0\".\n> \n> https://pasteboard.co/6koO0h0KJAjW.png\n> \n> The actual HTML for the above part looks like this:\n> \n>

For more details about the\n> <pathspec> syntax, see the pathspec entry\n> in gitglossary(7).

\n> \n> In the first hunk, the updated \"__\" is enclosed inside an\n> .. pair, which is made into \"font-style: italic\" via css,\n> while 'pathspec' that remains is already inside ...\n> \n> By the way, I am getting some typesetting effect from the pair of\n> single quotes with AsciiDoctor. Here is the rendition of the same\n> part:\n> \n> https://pasteboard.co/LbDi95G8BNGv.png\n> \n> The element in the generated HTML claims it\n> is \"Asciidoctor 2.0.20\". The actual HTML for that piece looks like\n> this:\n> \n>

For more details about the <pathspec> syntax,\n> see the pathspec entry\n> in gitglossary(7).

\n> \n> So, perhaps we do not have to do a lot of 'word' -> _word_\n> replacements, hopefully?\n> \n\nAsciidoctor tries to \"normify\" the asciidoc format (https://asciidoc-wg.eclipse.org/projects/) and pushes for deprecating the 'word' markup which \nis a asciidoc.py legacy.\n\nSee https://docs.asciidoctor.org/asciidoctor/latest/migrate/asciidoc-py/\n#updated-and-deprecated-asciidoc-syntax\n\nIn the transition period (which is lasting), they introduce a compatibility \nmode with the compat-mode flag in order to support legacy content.\n\nFor all I know, asciidoc.py has entered a maintenance stage where it will not \nsupport the evolutions of the standard. Should the Git documentation migrate \nto asciidoctor and drop the compat mode is an open question. At least, we \nshould try to stick as much as possible to the common markup _ for emphasis. \nThis would have the added benefit of differentiating single quotes from \nbackticks, because single quotes would completely disappear in the end, except \nwhen a real single quote is needed.\n\n For the migration to \"standard\" asciidoc, I would also recommend using \"=\" \nprefix for titles instead of underlines which require changing two lines when \nmodifying a title and are a pain for translators in languages with variable \nwidth characters.\n\n\n> ----- >8 --------- >8 --------- >8 --------- >8 ----\n> \n> Subject: [PATCH] doc: apply the new placeholder rules to git-add \ndocumentation\n> \n> Signed-off-by: Junio C Hamano \n> \n> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\n> index ed44c1cb31..b73071ba47 100644\n> --- a/Documentation/git-add.txt\n> +++ b/Documentation/git-add.txt\n> @@ -63,7 +63,7 @@ OPTIONS\n> \tto ignore removed files; use `--no-all` option if you want\n> \tto add modified or new files but ignore removed ones.\n> +\n> -For more details about the syntax, see the 'pathspec' entry\n> +For more details about the __ syntax, see the 'pathspec' entry\n> in linkgit:gitglossary[7].\n> \n> -n::\n> @@ -119,10 +119,10 @@ apply to the index. See EDITING PATCHES below.\n> -u::\n> --update::\n> \tUpdate the index just where it already has an entry matching\n> -\t. This removes as well as modifies index entries to\n> +\t__. This removes as well as modifies index entries to\n> \tmatch the working tree, but adds no new files.\n> +\n> -If no is given when `-u` option is used, all\n> +If no __ is given when `-u` option is used, all\n> tracked files in the entire working tree are updated (old versions\n> of Git used to limit the update to the current directory and its\n> subdirectories).\n> @@ -131,11 +131,11 @@ subdirectories).\n> --all::\n> --no-ignore-removal::\n> \tUpdate the index not only where the working tree has a file\n> -\tmatching but also where the index already has an\n> +\tmatching __ but also where the index already has an\n> \tentry. This adds, modifies, and removes index entries to\n> \tmatch the working tree.\n> +\n> -If no is given when `-A` option is used, all\n> +If no __ is given when `-A` option is used, all\n> files in the entire working tree are updated (old versions\n> of Git used to limit the update to the current directory and its\n> subdirectories).\n> @@ -145,11 +145,11 @@ subdirectories).\n> \tUpdate the index by adding new files that are unknown to the\n> \tindex and files modified in the working tree, but ignore\n> \tfiles that have been removed from the working tree. This\n> -\toption is a no-op when no is used.\n> +\toption is a no-op when no __ is used.\n> +\n> This option is primarily to help users who are used to older\n> -versions of Git, whose \"git add ...\" was a synonym\n> -for \"git add --no-all ...\", i.e. ignored removed files.\n> +versions of Git, whose \"git add __...\" was a synonym\n> +for \"git add --no-all __...\", i.e. ignored removed files.\n> \n> -N::\n> --intent-to-add::\n> @@ -198,8 +198,8 @@ for \"git add --no-all ...\", i.e. ignored \nremoved files.\n> \tunchanged.\n> \n> --pathspec-from-file=::\n> -\tPathspec is passed in `` instead of commandline args. If\n> -\t`` is exactly `-` then standard input is used. Pathspec\n> +\tPathspec is passed in __ instead of commandline args. If\n> +\t__ is exactly `-` then standard input is used. Pathspec\n> \telements are separated by LF or CR/LF. Pathspec elements can be\n> \tquoted as explained for the configuration variable `core.quotePath`\n> \t(see linkgit:git-config[1]). See also `--pathspec-file-nul` and\n> \n> \n\nThis looks good to me. \n\n\n\n"},{"id":"489166","messageId":"xmqqr0h4h2sz.fsf@gitster.g","threadId":"60969","inReplyTo":"2926790.e9J7NaK4W3@cayenne","subject":"Re: [PATCH 1/3] doc: git-rev-parse: enforce command-line description syntax","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-02-22T16:38:36Z","receivedAt":"2024-02-22T16:38:39Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jean-Noël AVILA writes:\n\n>> So, perhaps we do not have to do a lot of 'word' -> _word_\n>> replacements, hopefully?\n\n> ... At least, we \n> should try to stick as much as possible to the common markup _ for emphasis.\n\nOK, that clears up my confusion. Thanks.\n\nWe do not want to rely on an external party indefinitely maintaining\nwhat they consider backward compatibility wart, so the mark-up migration\nwould need to happen before it becomes too late.\n\n> This would have the added benefit of differentiating single quotes from \n> backticks, because single quotes would completely disappear in the end, except \n> when a real single quote is needed.\n\nGiven enough time, yes. Or we can actively disable AsciiDoctor's\ncompatibility mode and/or tweak asciidoc.conf to do the equivalent\nfor AsciiDoc, to start early. Until then, we cannot really use \"a\nreal single quote\", right?\n\n> For the migration to \"standard\" asciidoc, I would also recommend using \"=\" \n> prefix for titles instead of underlines which require changing two lines when \n> modifying a title and are a pain for translators in languages with variable \n> width characters.\n\nI personally strongly prefer the underline format because I care\nabout readability of sources, but that is just me. Is that also\ngetting deprecated?\n\nThanks.\n"},{"id":"489279","messageId":"6079595.lOV4Wx5bFT@cayenne","threadId":"60969","inReplyTo":"xmqqr0h4h2sz.fsf@gitster.g","subject":"Re: [PATCH 1/3] doc: git-rev-parse: enforce command-line description syntax","fromName":"Jean-Noël AVILA","fromEmail":"jn.avila@free.fr","sentAt":"2024-02-24T18:28:45Z","receivedAt":"2024-02-24T18:28:55Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"On Thursday, 22 February 2024 17:38:36 CET Junio C Hamano wrote:\n> Jean-Noël AVILA writes:\n> \n> >> So, perhaps we do not have to do a lot of 'word' -> _word_\n> >> replacements, hopefully?\n> \n> > ... At least, we \n> > should try to stick as much as possible to the common markup _ for \nemphasis.\n> \n> OK, that clears up my confusion. Thanks.\n> \n> We do not want to rely on an external party indefinitely maintaining\n> what they consider backward compatibility wart, so the mark-up migration\n> would need to happen before it becomes too late.\n> \n> > This would have the added benefit of differentiating single quotes from \n> > backticks, because single quotes would completely disappear in the end, \nexcept \n> > when a real single quote is needed.\n> \n> Given enough time, yes. Or we can actively disable AsciiDoctor's\n> compatibility mode and/or tweak asciidoc.conf to do the equivalent\n> for AsciiDoc, to start early. Until then, we cannot really use \"a\n> real single quote\", right?\n\nThe logic for managing single quotes as markup is that there should be a word \nboundary at the quote ' for opening and ' for \nclosing, whereas for \"real single quote\" there's no space. This rule is \n\"natural\" when writing in English and writers don't pay attention.\n\n> \n> > For the migration to \"standard\" asciidoc, I would also recommend using \"=\" \n> > prefix for titles instead of underlines which require changing two lines \nwhen \n> > modifying a title and are a pain for translators in languages with \nvariable \n> > width characters.\n> \n> I personally strongly prefer the underline format because I care\n> about readability of sources, but that is just me. Is that also\n> getting deprecated?\n> \n\nThe underline format is bound to be deprecated. Right now, Asciidoctor detects \nthis formatting to infer a switch to compat-mode. That's why markup-quote \nworks as expected with Asciidoctor in current documents.\n\n> Thanks.\n> \n> \n\n\n\n\n"}]}