Using double-colon in asciidoctor inside quotes

[gibiansky]

What is the right way to use double colons :: in Asciidoctor?

For example, consider the following document.

----
print a + b <1>
----
<1> Hello this is `1 :: 2`
a test `a :: b`

The line a test a :: bis not included in the output, because the double-colons are parsed as bold, or something along those lines. Using+ ... +`` does not change anything.

What's the right thing to do here?

[gibiansky]

Ah, I see I can just write a {two-colons} b. Is there an easier way? Again, I use :: all the time, so this is a real pain to use {two-colons} instead.

For the time being... horrible, hacky extensions save the day:

require 'asciidoctor'
require 'asciidoctor/extensions'

include ::Asciidoctor

class FixDoubleColon < Extensions::Preprocessor
  def process document, reader
      Reader.new reader.readlines.map { |line|
          (line.include? "`") ? line.gsub("::", "{two-colons}") : line
      }
  end
end

Extensions.register :fixdoublecolon do |document|
    document.preprocessor FixDoubleColon
end

[mojavelinux]

Unfortunately, this is a really tricky one. The double colon is being matched as a description list, which takes higher precedence than inline parsing. The pattern for matching a description list is:

[>= 0 spaces][>= 1 chars][>= 0 spaces][2-4 colons or 2 semi-colons][space or end-of-line]

Your example matches that pattern perfectly, but it's not what you are expecting. At the moment, the only way to prevent this match is to use an attribute. You can always shorten what you have to type by aliasing the double colon to a shorter name

:2c: ::

test `a {2c} b`

This might be the sharpest edge in the AsciiDoc syntax.

[jxxcarlson]

Won't your recursive descent parser cure all these ills?

On Sep 10, 2014, at 10:39 PM, Dan Allen notifications@github.com wrote:

Unfortunately, this is a really tricky one. The double colon is being matched as a description list, which takes higher precedence than inline parsing. The pattern for matching a description list is:

[0 or more spaces][1 or more chars][0 or more spaces][2-4 colons or 2 semi-colons][space or end-of-line]

Your example matches that pattern perfectly, but it's not what you are expecting. At the moment, the only way to prevent this match is to use an attribute. You can always shorten what you have to type by aliasing the double colon to a shorter name

:2c: ::

test a {2c} b
This might be the sharpest edge in the AsciiDoc syntax.

—
Reply to this email directly or view it on GitHub.

[mojavelinux]

In this case, unfortunately not. We are already in a recursive decent in this part of the processor. The problem is that by all definitions of the grammar, using the double colon like is is a perfectly valid description list term.

I think the solution here is to require that description list terms appear on their own line. This removes the ambiguity in the content. Thus, we would disallow:

term:: description

and instead require it to be:

term::
description

I find myself always typing it using the second form anyway. We'd have to survey existing AsciiDoc content to see how widespread the first usage is, but I don't sense it being a hard sell if it means we can eliminate this nasty corner case.

[mojavelinux]

...another option is to disallow the space after the term when using the single-line form. Hence, this would be legal:

term:: description

But this would not:

term :: description

We have to give the parser a chance to understand what's going on.

[gibiansky]

Can you just disallow "`" as part of the left term? That would also prevent it from being parsed as a descriptor, no?

[mojavelinux]

The problem with doing that it's very "whack a mole" kind of solution. There are actually a lot of possible things that should be escaped. We also have to check a lot of places for the start of the list and this would slow things down considerably.

It's much better to settle on a deterministic syntax.