Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
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 |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
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 |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
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 |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
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: ... [show rest of quote] |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
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 |
Free forum by Nabble | Edit this page |