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

[Glen Choo <chooglen@xxxxxxxxxx>]

Felipe Contreras <felipe.contreras@xxxxxxxxx> writes:

> 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.

Aha! Thanks! I'm glad that there's a satisfying explanation for all of
this :)

>
> 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