Difficulty in consistently escaping __ markup

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Difficulty in consistently escaping __ markup

oddhack
I want to write a sentence with multiple instances of an identifier whose name
starts with __ (two underscores). Test case:

__kernel foo __kernel foo __kernel
    -> (when entered as written, all examples using Asciidoctor.js browser plugin,
         pseudo-HTML markup to indicate italics):
kernel foo kernel foo __kernel

Not what I want, but that makes sense given the __ operator. So I should escape it:

\__kernel foo __kernel foo __kernel
    ->
__kernel foo __kernel foo __kernel

That's what I actually want. But I should escape all instances of the term for consistency, right?

\__kernel foo \__kernel foo \__kernel
    ->
__kernel foo \__kernel foo \__kernel

Oops. How about following http://asciidoctor.org/docs/asciidoc-writers-guide/ "Preventing substitution"
and using double backslash?

\\__kernel foo __kernel foo __kernel
    ->
\__kernel foo __kernel foo __kernel

Still oops. How about being consistent with \\?

\\__kernel__ foo \\__kernel foo \\__kernel
    ->
__kernel__ foo \__kernel foo \\__kernel

At this point I concluded that I have no actual understanding of how the \-escaping
rules work, or how to consistently write the term '__kernel' in a way that will render
properly, and not affect following syntax. Insights appreciated.

Thanks,
Jon

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Difficulty in consistently escaping __ markup

mojavelinux
Administrator

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 &lt;).

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

I added a section to the user manual that covers these techniques. See http://asciidoctor.org/docs/user-manual/#escaping-unconstrained-quotes.

-Dan

p.s. Implementing proper backslashing rules may become feasible once we solve https://github.com/asciidoctor/asciidoctor/issues/61 (by now a rather infamous issue).

--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Difficulty in consistently escaping __ markup

oddhack
I may not be following the first suggestion. When I try it on the following test case:

:__: __
:__kernel: __kernel

Non-attrib: __kernel blah __kernel

Underscore attrib: {__}kernel blah {__}kernel

Full Attrib: {__kernel} blah {__kernel}

What I see rendered is:

Non-attrib: kernel blah kernel

Underscore attrib: {}kernel blah {}kernel

Full Attrib: {kernel} blah {kernel}

The +__kernel+ passthrough does (in this example, anyway) seem to do the right thing,
though. Thanks!

Jon

mojavelinux wrote
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.
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Difficulty in consistently escaping __ markup

mojavelinux
Administrator

On Sat, Mar 4, 2017 at 2:01 AM, oddhack [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I may not be following the first suggestion.

Uh oh, it looks like I tricked myself. The unconstrained is so unconstrained that it even matches inside of attribute references. So the problem is the attribute name. You need to pick one that does not contain the unconstrained pattern.

:dbl_: __

or

:du: __

Then it will work. I'll update the docs.

-Dan


--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Loading...