Callouts in html listings

Previous Topic Next Topic
classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view

Callouts in html listings


I have a question regarding callouts in html listing. I used following syntax for defining callouts in html source.

             <input type="button" value="Show me" id="myButton"/> <!--<1>-->       

It was ok, I guess, before 0.1.4 rc1 version. But asciidoctor is  complains about this:

asciidoctor: WARNING: ch1_advancedjs.asciidoc: line 1737: no callouts refer to list item 1

Construct like

<input type="button" value="Show me" id="myButton"/> <!--1-->       

fixes situation but causes warnings with asciidoc.
I still want to keep sources of our book compatible with asciidoc because I'm not sure what O'Reilly's book toolchain is using.


Reply | Threaded
Open this post in threaded view

Re: Callouts in html listings


Fear not. It's possible to get AsciiDoc on the same page with Asciidoctor.

What's great about AsciiDoc is that you can teach it new tricks via the asciidoc.conf file. As part of this feature, I've added the configuration to compat/asciidoc.conf [1] that educates AsciiDoc how to handle the XML-friendly callouts.

Just add the following lines to your asciidoc.conf file (adjacent to book.asciidoc and site.asciidoc):

# additional callout match for XML

If you already have a [macros] section, then you only need to include the line with the regex.

O'Reilly should be able to add this line to the asciidoc.conf that they use. This is a much better syntax than <!--<1>-->, so I strongly recommend that they support it. I'd be happy to have a chat with them about it if necessary.

I've given a lot of thought about how to support both <!--1--> and <!--<1>-->, but it's really difficult without making the regular expression for callouts even more complex...or overly greedy. As it stands now, it's already the most complex regular expression in Asciidoctor. I really want avoid it putting a drag on parsing any more than it already is, esp if it's looking for a syntax that we want to get away from.

Btw, there is another way to solve the compatibility if all else fails. It's possible to use an Asciidoctor preprocessor extension to scan the lines and change any <!--<1>--> reference to <!--1-->.

Keep me updated as to what they say. There is a compatibility interface in the works that lets you turn on and off stuff like this, so if it becomes a big issue, we could add it to that interface. See for progress on that issue.