Another markup-escaping question

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

Another markup-escaping question

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

Re: Another markup-escaping question

mojavelinux
Administrator
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



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

Re: Another markup-escaping question

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

Re: Another markup-escaping question

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


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}
----
--

or

--
[subs=+replacements]
----
&#45;&#45;
----

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



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

Re: Another markup-escaping question

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

Re: Another markup-escaping question

mojavelinux
Administrator
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



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