Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Using double-colon in asciidoctor inside quotes #1066

Open
gibiansky opened this issue Aug 15, 2014 · 7 comments
Open

Using double-colon in asciidoctor inside quotes #1066

gibiansky opened this issue Aug 15, 2014 · 7 comments
Assignees
Milestone

Comments

@gibiansky
Copy link

@gibiansky gibiansky commented Aug 15, 2014

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
Copy link
Author

@gibiansky gibiansky commented Aug 15, 2014

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
Copy link
Member

@mojavelinux mojavelinux commented Sep 11, 2014

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.

@mojavelinux mojavelinux added this to the support milestone Sep 11, 2014
@mojavelinux mojavelinux self-assigned this Sep 11, 2014
@jxxcarlson
Copy link

@jxxcarlson jxxcarlson commented Sep 11, 2014

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
Copy link
Member

@mojavelinux mojavelinux commented Sep 11, 2014

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
Copy link
Member

@mojavelinux mojavelinux commented Sep 11, 2014

...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
Copy link
Author

@gibiansky gibiansky commented Sep 11, 2014

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

@mojavelinux
Copy link
Member

@mojavelinux mojavelinux commented Sep 11, 2014

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
3 participants