Backslashes are sometimes interpreted literally

[bk2204]

AsciiDoc generally wants backlashes before braces if those braces do not refer to attributes. However, Asciidoctor interprets these as literal backslashes, which makes rendering documentation consistently between the two implementations difficult.

An example of this is https://github.com/git/git/blob/master/Documentation/revisions.txt. Perhaps Asciidoctor could behave more like AsciiDoc in this regard.

[mojavelinux]

This change would have a major impact on performance. AsciiDoc Python matches anything between curly braces as an attribute, then decides later whether to throw it back. Asciidoctor avoids a lot of matches by being strict about the contents between the curly braces.

What we could do is, if in compat-mode, we could do an initial search for the inverse of the normal attribute search plus backslashes (e.g., \{<date>\}) and strip out the backslashes. That way, we can cover both scenarios.

There might be some edge cases remaining, but I'm pretty sure we can find a compatible syntax for those...or cross the bridge when we get there.

[mojavelinux]

Actually, there is a workaround today. If the contents between the curly braces is not a valid attribute name or expression, the backslashes are not necessary. For instance, the following renders literally: {<date>}. That's probably the best short-term fix...at least for many of the instances.

[mojavelinux]

Btw, when experimenting with the changes, the attribute-missing is an extremely useful setting in Asciidoctor.

-a attribute-missing=warn

That way, you know when an attribute needs to be escaped.

[mojavelinux]

The downside of the workaround is that you have to think about whether to escape or not escape the attribute reference. However, in most cases the rules are simple:

• cannot contain a space
• cannot contain special characters like angled brackets
• cannot begin with a hyphen

You can think of the inverse logic, but usually it's easier to look for the presence of an exception and remove the backslashes if you see one present.