Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
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 |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Administrator
|
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.
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). 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 |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
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
|
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
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. |
Free forum by Nabble | Edit this page |