I'm currently stuck between two possible solutions for a "copy-paste friendly" code callout syntax for XML-based languages.
As you're probably aware, code callouts in AsciiDoc use the form <n>, where n is the 1-based index of the callout.
For example, you might have:
[source,ruby]
----
puts "Hello, Asciidoctor community!" <1>
----
<1> Prints a welcome message to the console
The problem with this syntax is that it causes a syntax error if you copy-paste the code. These are the types of problems we want to fix in Asciidoctor.
Already in 0.1.3 (and improved in the upcoming 0.1.4), Asciidoctor allows you to tuck the callout away inside a line comment:
[source,ruby]
----
puts "Hello, Asciidoctor community!" # <1>
----
<1> Prints a welcome message to the console
Now the code is "copy-paste friendly" in raw form. This works for both # and // line comments (the space after the comment delimiter(s) is optional).
That covers most languages with the exception of ones in the XML family. I'm currently stuck between the following two proposals:
Option A:: <!--<1>-->
Option B:: <!--1-->
Although Option A is truer to the AsciiDoc syntax, I'm leaning towards Option B since it's:
a. more concise
b. closer to the <1> form (if you consider it's just padding the number with extra chars)
You may wonder, why not support both? When we don't settle on a syntax, we introduce complexity. We've heard many times that there are too many ways to do things in AsciiDoc, so we don't want to keep creating multiple paths.
The other reason is that it requires an extra regex match group to catch both and that slows down the processor (and I'm militant about Asciidoctor's speed ;))
The main thing I'm asking is whether Option B is acceptable to you. If there is strong opposition, then we'll go with Option A. Ask yourself, what looks better in raw form?
-Dan
Locked
