Posted by mojavelinux on
URL: https://discuss.asciidoctor.org/code-callout-syntax-for-XML-based-languages-tp499p500.html

As a bonus of supporting Option B (not that I'm lobbying for it or anything ;)), is that I would then allow the longer form anywhere if you want to be consistent.

For instance, you could write the comment in the Ruby code as:

[source,ruby]
----
puts "Hello, Asciidoctor community!"   # < !--1-->
----
<1> Prints a welcome message to the console

or even:

[source,ruby]
----
puts "Hello, Asciidoctor community!"   # <--1-->
----
<1> Prints a welcome message to the console

(I'd make the ! an optional character).

The longer form has the benefit of drawing more attention to the callouts, if that's something that you like. While yes, this does mean there are multiple ways to do it, it's for good reason. XML comments suck and we have to live with them :)

-Dan