Asciidoctor :: Discussion

Another markup-escaping question

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

6 messages Options

oddhack

Jun 18, 2017; 11:07pm

Another markup-escaping question

51 posts

I'm writing some source blocks containing asciidoc content, as part of our style guide. I'd like to get
something like this:

[NOTE]
.Guideline
====
To introduce the description, start an open block:

[source,asciidoc]
----
[open,refpage='command']
--
Command description
----
====

With the intent to result in output like (leading spaces added just for reading purposes):

Guideline
To introduce the description, start an open block:

[open,refpage='command']
--
Command description

But I can't figure out how to escape the '--' markup to make its way through to the source highlighter, without the escape marks also making their way through. I've played a bit with different block delimiters, uselessly. Any thoughts on how to do this?

mojavelinux

Jun 19, 2017; 4:22am

Re: Another markup-escaping question

Administrator

2681 posts

The only line of content that needs to be escaped inside a delimited block is a line that matches the start delimiter exactly. When that situation occurs, you can simply vary the length of the enclosing delimiter lines to prevent the match.

Having said that, I don't see any reason why your example wouldn't work. A line that consists of two hyphens inside of a listing block does not have any special meaning.

Are you observing unexpected output? If so, using which tool and version?

-Dan

On Sun, Jun 18, 2017 at 5:07 PM, oddhack [via Asciidoctor :: Discussion] <[hidden email]> wrote:

I'm writing some source blocks containing asciidoc content, as part of our style guide. I'd like to get
something like this:

[NOTE]
.Guideline
====
To introduce the description, start an open block:

[source,asciidoc]
----
[open,refpage='command']
--
Command description
----
====

With the intent to result in output like

To introduce the description, start an open block:

[open,refpage='command']
--
Command description

But I can't figure out how to escape the '--' markup to make its way through to the source highlighter, without the escape marks also making their way through. I've played a bit with different block delimiters, uselessly. Any thoughts on how to do this?

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Another-markup-escaping-question-tp5665.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

... [show rest of quote]

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

oddhack

Jun 19, 2017; 8:36am

Re: Another markup-escaping question

51 posts

Ah, I see the problem now - missed one level of block quoting, so the real scenario was more like

[open]
--
[source,asciidoc]
----
[open]
--
Lorem ipsum.

include::lorem.ipsum[]
----
--

I can work around this by using three dashes on the outer (actual) open block to avoid misinterpretation of the two dashes on the inner (code highlighter-rendered) two dashes, but is there truly no way to escape the inner two dashes so they don't cause this problem to begin with?

mojavelinux

Jun 19, 2017; 9:02am

Re: Another markup-escaping question

Administrator

2681 posts

Open block is the one exception to this rule. That's why we have this issue:

https://github.com/asciidoctor/asciidoctor/issues/1121

The choice to use two hyphens for an open block in AsciiDoc (Python) was a mistake. It broke the model of AsciiDoc in more than one way. That's why I plan on addressing it. It's probably going to be part of the 1.5.7 release.

You can escape the hyphens in the listing block using either an attribute reference or a character reference.

For example:

:open-block-delimiter: --

[subs=attributes+]

----

{open-block-delimiter}

----

[subs=+replacements]

----

I prefer the first solution.

Cheers,

-Dan

On Mon, Jun 19, 2017 at 2:36 AM, oddhack [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Ah, I see the problem now - missed one level of block quoting, so the real scenario was more like

[open]
--
[source,asciidoc]
----
[open]
--
Lorem ipsum.

include::lorem.ipsum[]
----
--

I can work around this by using three dashes on the outer (actual) open block to avoid misinterpretation of the two dashes on the inner (code highlighter-rendered) two dashes, but is there truly no way to escape the inner two dashes so they don't cause this problem to begin with?

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Another-markup-escaping-question-tp5665p5670.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

... [show rest of quote]

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

mojavelinux

Jun 19, 2017; 9:03am

Re: Another markup-escaping question

Administrator

2681 posts

In reply to this post by oddhack

On Mon, Jun 19, 2017 at 3:02 AM, Dan Allen <[hidden email]> wrote:

:open-block-delimiter: --
--
[subs=attributes+]
----
{open-block-delimiter}
----
--

You could also use:

[subs=attributes+]

----

{blank}--

----

--

-Dan

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

mojavelinux

Jun 19, 2017; 9:07am

Re: Another markup-escaping question

Administrator

2681 posts

In reply to this post by oddhack

One more trick. You can add indentation, then strip it away during conversion. That's even cleaner:

[indent=0]

----

Lorem ipsum.

----

On Mon, Jun 19, 2017 at 3:03 AM, Dan Allen <[hidden email]> wrote:

On Mon, Jun 19, 2017 at 3:02 AM, Dan Allen <[hidden email]> wrote:
:open-block-delimiter: --
--
[subs=attributes+]
----
{open-block-delimiter}
----
--

You could also use:

--
[subs=attributes+]
----
{blank}--
----
--

-Dan

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

... [show rest of quote]

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