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

[Felipe Contreras <felipe.contreras@xxxxxxxxx>]

On Mon, Aug 1, 2022 at 4:04 PM Glen Choo via GitGitGadget
<gitgitgadget@xxxxxxxxx> wrote:
>
> From: Glen Choo <chooglen@xxxxxxxxxx>
>
> 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