Login  Register

code callout syntax for XML-based languages

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
5 messages Options Options
Embed post
Permalink
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

code callout syntax for XML-based languages

mojavelinux
Administrator
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
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: code callout syntax for XML-based languages

mojavelinux
Administrator
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
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: code callout syntax for XML-based languages

mojavelinux
Administrator
One more thing to mention. This doesn't break the *default* code callout syntax. That still stands. So you can happily do:

[source,xml]
----
<section> <1>
----
<1> A semantic HTML 5 tag for identifying a section of the page

Of course, that sort of highlights the problem :)

-Dan
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: code callout syntax for XML-based languages

LightGuardjp
Option A, IMO, just looks weird.


On Thu, Aug 22, 2013 at 1:19 AM, mojavelinux [via Asciidoctor :: Discussion] <[hidden email]> wrote:
One more thing to mention. This doesn't break the *default* code callout syntax. That still stands. So you can happily do:

[source,xml]
----
<section> <1>
----
<1> A semantic HTML 5 tag for identifying a section of the page

Of course, that sort of highlights the problem :)

-Dan


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/code-callout-syntax-for-XML-based-languages-tp499p501.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: code callout syntax for XML-based languages

mojavelinux
Administrator
Yep, agreed.

I worked out how to add support into AsciiDoc for the XML-based callout syntax, so I think I'm going to move forward with it.

Here's the latest pull request:

https://github.com/asciidoctor/asciidoctor/pull/583

Here's the diff to the Enterprise Web Book that applies this new syntax:

https://github.com/mojavelinux/EnterpriseWebBook/compare/xml-callouts-syntax

-Dan