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
[\\]?&lt;!--(?P<index>\d+)--&gt;=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 <!--<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 https://github.com/asciidoctor/asciidoctor/issues/577 for progress on that issue.