{"thread":{"id":"58250","subject":"[PATCH] Documentation/git-reflog: remove unneeded \\ from \\{","startedAt":"2022-08-01T21:04:52Z","lastAt":"2022-08-10T16:55:45Z","messageCount":5,"participants":["Glen Choo via GitGitGadget","Junio C Hamano","Johannes Schindelin","Felipe Contreras","Glen Choo"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"460375","messageId":"pull.1304.git.git.1659387885711.gitgitgadget@gmail.com","threadId":"58250","inReplyTo":null,"subject":"[PATCH] Documentation/git-reflog: remove unneeded \\ from \\{","fromName":"Glen Choo via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-08-01T21:04:45Z","receivedAt":"2022-08-01T21:04:52Z","isPatch":true,"sender":{"key":"glencbz@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58092771?v=4"},"body":"From: Glen Choo \n\nThere are some inconsistencies with how different asciidoc environments\nhandle different combinations of \"\\{<>}\", e.g. these results were\nobserved with asciidoc on two different environments:\n\n | Input | Output (env A) | Output (env B) | same/different |\n |-----------+----------------+------------------+----------------|\n | \\{\\} | {<foo>} | \\{<foo>}^M | different |\n | {} | {<foo>} | {<foo>} | same |\n | \\{} | {<foo>} | \\{<foo>}^M | different |\n | \\{foo\\} | {foo} | {foo} | same |\n | \\{\\} | {} | \\{}^M | different |\n | \\{} | {} | {} | same |\n | {\\} | {} | {} | same |\n\nThe only instance of this biting us is \"@\\{\\}\" in\nDocumentation/git-reflog.txt; all other combinations of \"\\{<>}\" (e.g. in\nDocumentation/revisions.txt) seem to render consistently.\n\nFix this inconsistent rendering by removing the unnecessary \"\\\" in\nDocumentation/git-reflog.txt.\n\nSigned-off-by: Glen Choo \n---\n Documentation/git-reflog: remove unneeded \\ from {\n \n I noticed this inconsistency as I was trying to build Git docs with\n Google's internal build system. This string seems particularly\n problematic e.g. you can see unnecessary \"\\\" on\n https://git-scm.com/docs/git-reflog#_description.\n \n I'm not proficient in asciidoc at all, but I suspect that this isn't\n tied to the asciidoc version; I initially observed these differences in\n environments with different versions of asciidoc (9.0.0 and 10.2.0) but\n I can't reproduce this at all on my Mac using different versions of\n asciidoc and asciidoctor from Homebrew. Perhaps the issue is in some\n underlying library?\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1304%2Fchooglen%2Fdocumentation%2Fbackslash-brace-asciidoc-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1304/chooglen/documentation/backslash-brace-asciidoc-v1\nPull-Request: https://github.com/git/git/pull/1304\n\n Documentation/git-reflog.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt\nindex 5ced7ad4f8b..db9d46edfa9 100644\n--- a/Documentation/git-reflog.txt\n+++ b/Documentation/git-reflog.txt\n@@ -22,7 +22,7 @@ depending on the subcommand:\n \t[--rewrite] [--updateref] [--stale-fix]\n \t[--dry-run | -n] [--verbose] [--all [--single-worktree] | ...]\n 'git reflog delete' [--rewrite] [--updateref]\n-\t[--dry-run | -n] [--verbose] @\\{\\}...\n+\t[--dry-run | -n] [--verbose] @{}...\n 'git reflog exists' \n \n Reference logs, or \"reflogs\", record when the tips of branches and\n\nbase-commit: 23b219f8e3f2adfb0441e135f0a880e6124f766c\n-- \ngitgitgadget\n"},{"id":"460386","messageId":"xmqqles7odhy.fsf@gitster.g","threadId":"58250","inReplyTo":"pull.1304.git.git.1659387885711.gitgitgadget@gmail.com","subject":"Re: [PATCH] Documentation/git-reflog: remove unneeded \\ from \\{","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-08-01T21:33:29Z","receivedAt":"2022-08-01T21:33:37Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Glen Choo via GitGitGadget\" writes:\n\n> Fix this inconsistent rendering by removing the unnecessary \"\\\" in\n> Documentation/git-reflog.txt.\n>\n> Signed-off-by: Glen Choo \n> ---\n> Documentation/git-reflog: remove unneeded \\ from {\n> \n> I noticed this inconsistency as I was trying to build Git docs with\n> Google's internal build system. This string seems particularly\n> problematic e.g. you can see unnecessary \"\\\" on\n> https://git-scm.com/docs/git-reflog#_description.\n> \n> I'm not proficient in asciidoc at all, but I suspect that this isn't\n> tied to the asciidoc version; I initially observed these differences in\n> environments with different versions of asciidoc (9.0.0 and 10.2.0) but\n> I can't reproduce this at all on my Mac using different versions of\n> asciidoc and asciidoctor from Homebrew. Perhaps the issue is in some\n> underlying library?\n\nThanks. ref@\\{specifier\\} came from 552cecc2 (Teach \"git reflog\" a\nsubcommand to delete single entries, 2007-10-17) but that is so\ndistant past that the world must have changed too much that past\nexperiences would not help all that much X-<. There are too many\nmoving parts, older and more recent asciidoc, plus asciidoctor.\n\nThose who care about gitman.texi may also want to check the end\nresult, as the toolchain there involves docbook, yet another moving\npart.\n\nWill queue. Thanks.\n\n> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1304%2Fchooglen%2Fdocumentation%2Fbackslash-brace-asciidoc-v1\n> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1304/chooglen/documentation/backslash-brace-asciidoc-v1\n> Pull-Request: https://github.com/git/git/pull/1304\n>\n> Documentation/git-reflog.txt | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt\n> index 5ced7ad4f8b..db9d46edfa9 100644\n> --- a/Documentation/git-reflog.txt\n> +++ b/Documentation/git-reflog.txt\n> @@ -22,7 +22,7 @@ depending on the subcommand:\n> \t[--rewrite] [--updateref] [--stale-fix]\n> \t[--dry-run | -n] [--verbose] [--all [--single-worktree] | ...]\n> 'git reflog delete' [--rewrite] [--updateref]\n> -\t[--dry-run | -n] [--verbose] @\\{\\}...\n> +\t[--dry-run | -n] [--verbose] @{}...\n> 'git reflog exists' \n> \n> Reference logs, or \"reflogs\", record when the tips of branches and\n>\n> base-commit: 23b219f8e3f2adfb0441e135f0a880e6124f766c\n"},{"id":"460970","messageId":"r6orqqn6-7s7q-6023-97s3-3672soos4397@tzk.qr","threadId":"58250","inReplyTo":"xmqqles7odhy.fsf@gitster.g","subject":"Re: [PATCH] Documentation/git-reflog: remove unneeded \\ from \\{","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2022-08-10T09:23:16Z","receivedAt":"2022-08-10T09:23:49Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi Junio & Glen,\n\nOn Mon, 1 Aug 2022, Junio C Hamano wrote:\n\n> \"Glen Choo via GitGitGadget\" writes:\n>\n> > Fix this inconsistent rendering by removing the unnecessary \"\\\" in\n> > Documentation/git-reflog.txt.\n> >\n> > Signed-off-by: Glen Choo \n> > ---\n> > Documentation/git-reflog: remove unneeded \\ from {\n> >\n> > I noticed this inconsistency as I was trying to build Git docs with\n> > Google's internal build system. This string seems particularly\n> > problematic e.g. you can see unnecessary \"\\\" on\n> > https://git-scm.com/docs/git-reflog#_description.\n> >\n> > I'm not proficient in asciidoc at all, but I suspect that this isn't\n> > tied to the asciidoc version; I initially observed these differences in\n> > environments with different versions of asciidoc (9.0.0 and 10.2.0) but\n> > I can't reproduce this at all on my Mac using different versions of\n> > asciidoc and asciidoctor from Homebrew. Perhaps the issue is in some\n> > underlying library?\n>\n> Thanks. ref@\\{specifier\\} came from 552cecc2 (Teach \"git reflog\" a\n> subcommand to delete single entries, 2007-10-17) but that is so\n> distant past that the world must have changed too much that past\n> experiences would not help all that much X-<.\n\nOh wow, what a blast from the past. I indeed do not recall the specifics\nwhy I used that backslash, maybe it was needed back then. Or at least it\ndid not hurt back then.\n\nHere's my ACK in any case,\nDscho\n\n> There are too many moving parts, older and more recent asciidoc, plus\n> asciidoctor.\n>\n> Those who care about gitman.texi may also want to check the end\n> result, as the toolchain there involves docbook, yet another moving\n> part.\n>\n> Will queue. Thanks.\n>\n> > Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1304%2Fchooglen%2Fdocumentation%2Fbackslash-brace-asciidoc-v1\n> > Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1304/chooglen/documentation/backslash-brace-asciidoc-v1\n> > Pull-Request: https://github.com/git/git/pull/1304\n> >\n> > Documentation/git-reflog.txt | 2 +-\n> > 1 file changed, 1 insertion(+), 1 deletion(-)\n> >\n> > diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt\n> > index 5ced7ad4f8b..db9d46edfa9 100644\n> > --- a/Documentation/git-reflog.txt\n> > +++ b/Documentation/git-reflog.txt\n> > @@ -22,7 +22,7 @@ depending on the subcommand:\n> > \t[--rewrite] [--updateref] [--stale-fix]\n> > \t[--dry-run | -n] [--verbose] [--all [--single-worktree] | ...]\n> > 'git reflog delete' [--rewrite] [--updateref]\n> > -\t[--dry-run | -n] [--verbose] @\\{\\}...\n> > +\t[--dry-run | -n] [--verbose] @{}...\n> > 'git reflog exists' \n> >\n> > Reference logs, or \"reflogs\", record when the tips of branches and\n> >\n> > base-commit: 23b219f8e3f2adfb0441e135f0a880e6124f766c\n>\n"},{"id":"460980","messageId":"CAMP44s2z1FC-3T0X39aT5WTq2aFGph_-iVz-yJtTN6VpG-qdzA@mail.gmail.com","threadId":"58250","inReplyTo":"pull.1304.git.git.1659387885711.gitgitgadget@gmail.com","subject":"Re: [PATCH] Documentation/git-reflog: remove unneeded \\ from \\{","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2022-08-10T13:06:30Z","receivedAt":"2022-08-10T13:06:46Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Mon, Aug 1, 2022 at 4:04 PM Glen Choo via GitGitGadget\n wrote:\n>\n> From: Glen Choo \n>\n> There are some inconsistencies with how different asciidoc environments\n> handle different combinations of \"\\{<>}\", e.g. these results were\n> observed with asciidoc on two different environments:\n>\n> | Input | Output (env A) | Output (env B) | same/different |\n> |-----------+----------------+------------------+----------------|\n> | \\{\\} | {<foo>} | \\{<foo>}^M | different |\n> | {} | {<foo>} | {<foo>} | same |\n> | \\{} | {<foo>} | \\{<foo>}^M | different |\n> | \\{foo\\} | {foo} | {foo} | same |\n> | \\{\\} | {} | \\{}^M | different |\n> | \\{} | {} | {} | same |\n> | {\\} | {} | {} | same |\n>\n> The only instance of this biting us is \"@\\{\\}\" in\n> Documentation/git-reflog.txt; all other combinations of \"\\{<>}\" (e.g. in\n> Documentation/revisions.txt) seem to render consistently.\n\nSo, I did some investigation. {} are used for attributes, if you do\n{manversion} that will be replaced by the manversion attribute (which\nwe are setting), but if you do {foobar} (an attribute that doesn't\nexist) different implementations will do different things, what you\nshould do is \\{foobar} as that's how the documentation says you should\nescape attributes [1].\n\nIn 552cecc214 (Teach \"git reflog\" a subcommand to delete single\nentries, 2007-10-17) it was {specifier} which could have been an\nattribute and thus should be quoted, but in 49cbad0edd (doc: express\ngrammar placeholders between angle brackets, 2021-11-06) it was\nchanged to {} and that apparently cannot be an attribute,\nso it should not be quoted.\n\nWe shouldn't be using verses for this kind of stuff though, since we\nwant the whole thing displayed as-is, it's better to use literal\nblocks [2], but that's a bigger change.\n\nFor now it should be:\n\n @{}\n\nSo the patch is correct. ACK.\n\nCheers.\n\n[1] https://docs.asciidoctor.org/asciidoc/latest/attributes/reference-attributes/\n[2] https://docs.asciidoctor.org/asciidoc/latest/verbatim/literal-blocks/\n\n-- \nFelipe Contreras\n"},{"id":"461005","messageId":"kl6l5yj0qbqt.fsf@chooglen-macbookpro.roam.corp.google.com","threadId":"58250","inReplyTo":"CAMP44s2z1FC-3T0X39aT5WTq2aFGph_-iVz-yJtTN6VpG-qdzA@mail.gmail.com","subject":"Re: [PATCH] Documentation/git-reflog: remove unneeded \\ from \\{","fromName":"Glen Choo","fromEmail":"chooglen@google.com","sentAt":"2022-08-10T16:55:38Z","receivedAt":"2022-08-10T16:55:45Z","isPatch":true,"sender":{"key":"glencbz@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58092771?v=4"},"body":"Felipe Contreras writes:\n\n> On Mon, Aug 1, 2022 at 4:04 PM Glen Choo via GitGitGadget\n> wrote:\n>>\n>> From: Glen Choo \n>>\n>> There are some inconsistencies with how different asciidoc environments\n>> handle different combinations of \"\\{<>}\", e.g. these results were\n>> observed with asciidoc on two different environments:\n>>\n>> | Input | Output (env A) | Output (env B) | same/different |\n>> |-----------+----------------+------------------+----------------|\n>> | \\{\\} | {<foo>} | \\{<foo>}^M | different |\n>> | {} | {<foo>} | {<foo>} | same |\n>> | \\{} | {<foo>} | \\{<foo>}^M | different |\n>> | \\{foo\\} | {foo} | {foo} | same |\n>> | \\{\\} | {} | \\{}^M | different |\n>> | \\{} | {} | {} | same |\n>> | {\\} | {} | {} | same |\n>>\n>> The only instance of this biting us is \"@\\{\\}\" in\n>> Documentation/git-reflog.txt; all other combinations of \"\\{<>}\" (e.g. in\n>> Documentation/revisions.txt) seem to render consistently.\n>\n> So, I did some investigation. {} are used for attributes, if you do\n> {manversion} that will be replaced by the manversion attribute (which\n> we are setting), but if you do {foobar} (an attribute that doesn't\n> exist) different implementations will do different things, what you\n> should do is \\{foobar} as that's how the documentation says you should\n> escape attributes [1].\n>\n> In 552cecc214 (Teach \"git reflog\" a subcommand to delete single\n> entries, 2007-10-17) it was {specifier} which could have been an\n> attribute and thus should be quoted, but in 49cbad0edd (doc: express\n> grammar placeholders between angle brackets, 2021-11-06) it was\n> changed to {} and that apparently cannot be an attribute,\n> so it should not be quoted.\n\nAha! Thanks! I'm glad that there's a satisfying explanation for all of\nthis :)\n\n>\n> We shouldn't be using verses for this kind of stuff though, since we\n> want the whole thing displayed as-is, it's better to use literal\n> blocks [2], but that's a bigger change.\n>\n> For now it should be:\n>\n> @{}\n>\n> So the patch is correct. ACK.\n>\n> Cheers.\n>\n> [1] https://docs.asciidoctor.org/asciidoc/latest/attributes/reference-attributes/\n> [2] https://docs.asciidoctor.org/asciidoc/latest/verbatim/literal-blocks/\n>\n> -- \n> Felipe Contreras\n"}]}