Asciidoctor :: Discussion

Callouts in html listings

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

2 messages Options

gamussa

Callouts in html listings

Hi,

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

[source,html]
----
 <body>
        <p>
             <input type="button" value="Show me" id="myButton"/> <!--<1>-->       
        </p>
</body>
----

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

[source,html]
----
<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.

Thoughts?

Cheers,
Vik

mojavelinux

Re: Callouts in html listings

Administrator

Vik,

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):

[macros]
# additional callout match for XML
[\\]?=callout

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 , 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  and , 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  reference to .

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 https://github.com/asciidoctor/asciidoctor/issues/577 for progress on that issue.

-Dan

[1] https://github.com/asciidoctor/asciidoctor/blob/master/compat/asciidoc.conf

--

Dan Allen | http://google.com/profiles/dan.j.allen