Documentation/git-reflog: remove unneeded \ from \{
PATCH 1/1 Documentation/git-reflog: remove unneeded \ from \{
From: Glen Choo <[email protected]>
There are some inconsistencies with how different asciidoc environments handle different combinations of "\{<>}", e.g. these results were observed with asciidoc on two different environments:
| Input | Output (env A) | Output (env B) | same/different |
|-----------+----------------+------------------+----------------|
| \{<foo>\} | {<foo>} | \{<foo>}^M | different |
| {<foo>} | {<foo>} | {<foo>} | same |
| \{<foo>} | {<foo>} | \{<foo>}^M | different |
| \{foo\} | {foo} | {foo} | same |
| \{\} | {} | \{}^M | different |
| \{} | {} | {} | same |
| {\} | {} | {} | same |The only instance of this biting us is "@\{<specifier>\}" in Documentation/git-reflog.txt; all other combinations of "\{<>}" (e.g. in Documentation/revisions.txt) seem to render consistently.
Fix this inconsistent rendering by removing the unnecessary "\" in Documentation/git-reflog.txt.
---
Documentation/git-reflog: remove unneeded \ from {
I noticed this inconsistency as I was trying to build Git docs with Google's internal build system. This string seems particularly problematic e.g. you can see unnecessary "\" on
https://git-scm.com/docs/git-reflog#_description.
I'm not proficient in asciidoc at all, but I suspect that this isn't tied to the asciidoc version; I initially observed these differences in environments with different versions of asciidoc (9.0.0 and 10.2.0) but I can't reproduce this at all on my Mac using different versions of asciidoc and asciidoctor from Homebrew. Perhaps the issue is in some underlying library?
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1304%2Fchooglen%2Fdocumentation%2Fbackslash-brace-asciidoc-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1304/chooglen/documentation/backslash-brace-asciidoc-v1
Pull-Request: https://github.com/git/git/pull/1304
Documentation/git-reflog.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-reflog.txt +1 -1
@@ -22,7 +22,7 @@ depending on the subcommand: [--rewrite] [--updateref] [--stale-fix] [--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...] 'git reflog delete' [--rewrite] [--updateref] - [--dry-run | -n] [--verbose] <ref>@\{<specifier>\}... + [--dry-run | -n] [--verbose] <ref>@{<specifier>}... 'git reflog exists' <ref> Reference logs, or "reflogs", record when the tips of branches and
base-commit: 23b219f8e3f2adfb0441e135f0a880e6124f766c
Signature · 1 line
gitgitgadget
Quoted 12 lines · Glen Choo via GitGitGadget
Fix this inconsistent rendering by removing the unnecessary "\" in
Documentation/git-reflog.txt.Signed-off-by Glen Choo <[email protected]>---
Documentation/git-reflog: remove unneeded \ from {I noticed this inconsistency as I was trying to build Git docs with Google's internal build system. This string seems particularly problematic e.g. you can see unnecessary "\" on
https://git-scm.com/docs/git-reflog#_description.
Quoted 6 lines
I'm not proficient in asciidoc at all, but I suspect that this isn't tied to the asciidoc version; I initially observed these differences in environments with different versions of asciidoc (9.0.0 and 10.2.0) but I can't reproduce this at all on my Mac using different versions of asciidoc and asciidoctor from Homebrew. Perhaps the issue is in some underlying library?
Thanks. ref@\{specifier\} came from 552cecc2 (Teach "git reflog" a subcommand to delete single entries, 2007-10-17) but that is so distant past that the world must have changed too much that past experiences would not help all that much X-<. There are too many moving parts, older and more recent asciidoc, plus asciidoctor.
Those who care about gitman.texi may also want to check the end result, as the toolchain there involves docbook, yet another moving part.
Will queue. Thanks.
Quoted 22 lines
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1304%2Fchooglen%2Fdocumentation%2Fbackslash-brace-asciidoc-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1304/chooglen/documentation/backslash-brace-asciidoc-v1
Pull-Request: https://github.com/git/git/pull/1304Documentation/git-reflog.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/git-reflog.txt +1
-1@@ -22,7 +22,7 @@ depending on the subcommand: [--rewrite] [--updateref] [--stale-fix] [--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...] 'git reflog delete' [--rewrite] [--updateref] - [--dry-run | -n] [--verbose] <ref>@\{<specifier>\}... + [--dry-run | -n] [--verbose] <ref>@{<specifier>}... 'git reflog exists' <ref> Reference logs, or "reflogs", record when the tips of branches andbase-commit:
23b219f8e3f2adfb0441e135f0a880e6124f766c
Hi Junio & Glen,
Quoted 21 lines · Junio C Hamano
Quoted 12 lines · Glen Choo via GitGitGadget
Fix this inconsistent rendering by removing the unnecessary "\" in
Documentation/git-reflog.txt.Signed-off-by Glen Choo <[email protected]>---
Documentation/git-reflog: remove unneeded \ from {I noticed this inconsistency as I was trying to build Git docs with Google's internal build system. This string seems particularly problematic e.g. you can see unnecessary "\" on
https://git-scm.com/docs/git-reflog#_description.Quoted 6 lines
I'm not proficient in asciidoc at all, but I suspect that this isn't tied to the asciidoc version; I initially observed these differences in environments with different versions of asciidoc (9.0.0 and 10.2.0) but I can't reproduce this at all on my Mac using different versions of asciidoc and asciidoctor from Homebrew. Perhaps the issue is in some underlying library?
Quoted 4 lines
Thanks. ref@\{specifier\} came from
552cecc2(Teach "git reflog" a subcommand to delete single entries, 2007-10-17) but that is so distant past that the world must have changed too much that past experiences would not help all that much X-<.
Oh wow, what a blast from the past. I indeed do not recall the specifics why I used that backslash, maybe it was needed back then. Or at least it did not hurt back then.
Here's my ACK in any case,
Dscho
Quoted 32 lines
There are too many moving parts, older and more recent asciidoc, plus asciidoctor.
Those who care about gitman.texi may also want to check the end result, as the toolchain there involves docbook, yet another moving part.
Will queue. Thanks.
Quoted 22 lines
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1304%2Fchooglen%2Fdocumentation%2Fbackslash-brace-asciidoc-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1304/chooglen/documentation/backslash-brace-asciidoc-v1
Pull-Request: https://github.com/git/git/pull/1304Documentation/git-reflog.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/git-reflog.txt +1
-1@@ -22,7 +22,7 @@ depending on the subcommand: [--rewrite] [--updateref] [--stale-fix] [--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...] 'git reflog delete' [--rewrite] [--updateref] - [--dry-run | -n] [--verbose] <ref>@\{<specifier>\}... + [--dry-run | -n] [--verbose] <ref>@{<specifier>}... 'git reflog exists' <ref> Reference logs, or "reflogs", record when the tips of branches andbase-commit:
23b219f8e3f2adfb0441e135f0a880e6124f766c
Quoted 17 lines · Glen Choo via GitGitGadget
From: Glen Choo <[email protected]>
There are some inconsistencies with how different asciidoc environments handle different combinations of "\{<>}", e.g. these results were observed with asciidoc on two different environments:
| Input | Output (env A) | Output (env B) | same/different | |-----------+----------------+------------------+----------------| | \{<foo>\} | {<foo>} | \{<foo>}^M | different | | {<foo>} | {<foo>} | {<foo>} | same | | \{<foo>} | {<foo>} | \{<foo>}^M | different | | \{foo\} | {foo} | {foo} | same | | \{\} | {} | \{}^M | different | | \{} | {} | {} | same | | {\} | {} | {} | same |
Quoted 3 lines
The only instance of this biting us is "@\{<specifier>\}" in
Documentation/git-reflog.txt; all other combinations of "\{<>}" (e.g. inDocumentation/revisions.txt) seem to render consistently.
So, I did some investigation. {} are used for attributes, if you do {manversion} that will be replaced by the manversion attribute (which we are setting), but if you do {foobar} (an attribute that doesn't exist) different implementations will do different things, what you should do is \{foobar} as that's how the documentation says you should escape attributes [1].
In 552cecc214 (Teach "git reflog" a subcommand to delete single entries, 2007-10-17) it was {specifier} which could have been an attribute and thus should be quoted, but in 49cbad0edd (doc: express grammar placeholders between angle brackets, 2021-11-06) it was changed to {<specifier>} and that apparently cannot be an attribute, so it should not be quoted.
We shouldn't be using verses for this kind of stuff though, since we want the whole thing displayed as-is, it's better to use literal blocks [2], but that's a bigger change.
For now it should be:
@{<specifier>}
So the patch is correct. ACK.
Cheers.
[1] https://docs.asciidoctor.org/asciidoc/latest/attributes/reference-attributes/
[2] https://docs.asciidoctor.org/asciidoc/latest/verbatim/literal-blocks/
Signature · 1 line
Felipe Contreras
Quoted 30 lines · Felipe Contreras
Quoted 17 lines · Glen Choo via GitGitGadget
From: Glen Choo <[email protected]>
There are some inconsistencies with how different asciidoc environments handle different combinations of "\{<>}", e.g. these results were observed with asciidoc on two different environments:
| Input | Output (env A) | Output (env B) | same/different | |-----------+----------------+------------------+----------------| | \{<foo>\} | {<foo>} | \{<foo>}^M | different | | {<foo>} | {<foo>} | {<foo>} | same | | \{<foo>} | {<foo>} | \{<foo>}^M | different | | \{foo\} | {foo} | {foo} | same | | \{\} | {} | \{}^M | different | | \{} | {} | {} | same | | {\} | {} | {} | same |Quoted 3 lines
The only instance of this biting us is "@\{<specifier>\}" in
Documentation/git-reflog.txt; all other combinations of "\{<>}" (e.g. inDocumentation/revisions.txt) seem to render consistently.So, I did some investigation. {} are used for attributes, if you do {manversion} that will be replaced by the manversion attribute (which we are setting), but if you do {foobar} (an attribute that doesn't exist) different implementations will do different things, what you should do is \{foobar} as that's how the documentation says you should escape attributes [1].
Quoted 6 lines
In
552cecc214(Teach "git reflog" a subcommand to delete single entries, 2007-10-17) it was {specifier} which could have been an attribute and thus should be quoted, but in49cbad0edd(doc: express grammar placeholders between angle brackets, 2021-11-06) it was changed to {<specifier>} and that apparently cannot be an attribute, so it should not be quoted.
Aha! Thanks! I'm glad that there's a satisfying explanation for all of this :)
Quoted 18 lines
We shouldn't be using verses for this kind of stuff though, since we want the whole thing displayed as-is, it's better to use literal blocks [2], but that's a bigger change.
For now it should be:
@{<specifier>}
So the patch is correct. ACK.
Cheers.
[1] https://docs.asciidoctor.org/asciidoc/latest/attributes/reference-attributes/
[2] https://docs.asciidoctor.org/asciidoc/latest/verbatim/literal-blocks/Signature · 1 line
Felipe Contreras