Re: [PATCH] Documentation/git-reflog: remove unneeded \ from \{

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: Aug 10, 2022, 13:06 UTC
Message-ID: <CAMP44s2z1FC-3T0X39aT5WTq2aFGph_-iVz-yJtTN6VpG-qdzA@mail.gmail.com>
In-Reply-To: <pull.1304.git.git.1659387885711.gitgitgadget@gmail.com>

On Mon, Aug 1, 2022 at 4:04 PM Glen Choo via GitGitGadget <gitgitgadget@gmail.com> wrote:

Show 20 quoted lines

>
> From: Glen Choo <chooglen@google.com>
>
> 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>\} | {&lt;foo&gt;}  | \{&lt;foo&gt;}^M | different      |
>   | {<foo>}   | {&lt;foo&gt;}  | {&lt;foo&gt;}    | same           |
>   | \{<foo>}  | {&lt;foo&gt;}  | \{&lt;foo&gt;}^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.

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/

-- 
Felipe Contreras