Posted by mojavelinux on URL: https://discuss.asciidoctor.org/Difficulty-in-consistently-escaping-markup-tp5318p5327.html
At this point I concluded that I have no actual understanding of how the \-escaping
rules work
I want to start by admitting that the backslash escaping in Asciidoctor (and mostly true of AsciiDoc Python as well) is designed primarily for internal and sparse use. Backslashes get strategically placed during conversion so as to veto certain substitutions, but there are a lot of rules as to when they do and do not apply.
While that sounds sort of lazy, it's one of the key reasons Asciidoctor is so fast. It goes out of its way to avoid unnecessary work...but that does introduce some limitations you might not expect when coming from a general purpose programming language.
Despite all that, there are reliable ways to write unconstrained formatting marks literally.
or how to consistently write the term '__kernel' in a way that will render
properly, and not affect following syntax.
Double underscore is one of several unconstrained formatting marks. Unconstrained formatting marks are meant to match anywhere, context-free. While that's useful to compel formatting, they're the trickiest combination of characters to type literally.
There are two solutions I like to propose:
* Use an attribute reference to insert the unconstrained formatting marks verbatim
* Wrap the text that includes these marks in an inline passthrough
I find the first solution to be the clearest. Here's how you might do it:
:__: __
{__}kernel
or
:__kernel: __kernel
{__kernel}
This works since attribute references are expanded after the quotes substitution (i.e., text formatting) is applied.
The other solution is to use an inline passthrough, which has both a constrained and unconstrained form. The constrained form will work fine for your use case:
+__kernel+
It's the closest thing to a backslash. Everything between the passthrough is escaped from interpolation (attribute references, text formatting, etc). However, the text still receives the proper output escaping for HTML (e.g., < becomes <).
The more brute-force approach to escaping interpolation is to use the pass:c[] macro, which is the equivalent of the plus formatting marks.
pass:c[__kernel]
(The c applies the output escaping for HTML, though isn't always required).
So there you have it. That's the proper way in AsciiDoc to escape unconstrained formatting (at the moment).