An important syntax change coming in 1.5.0

On Mon, Jul 14, 2014 at 9:25 PM, mojavelinux [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Issue #718 (https://github.com/asciidoctor/asciidoctor/issues/718) proposes swapping the backtick and plus characters in the AsciiDoc syntax to give consistent meaning to the plus character and better align with Markdown. This syntax change is likely the most significant in the 1.5.0 development cycle, so it's important to be aware of it and provide feedback--if you have any--prior to the release (happening later this week or next).

Before I introduce what has changed by pull request #718 (https://github.com/asciidoctor/asciidoctor/pull/1006), I want to highlight the fact that you can forgo the changes to the syntax by setting the new compat-mode attribute to legacy either in the document header:

:compat-mode: legacy

or by passing the attribute to the API:

-a compat-mode=legacy

As this issue points out, the meaning of + in the AsciiDoc syntax is currently inconsistent. I believe we can make the AsciiDoc syntax easier to understand and remember if we consistently implement + as a passthrough (literal) mark.

Where the quad plus (++++) and triple plus (+++) pass content without any processing, double plus (++) and single plus (+) pass content "as you see it" (which means escaping special characters). Double plus (++) is an unconstrained match (can be used anywhere inline, just like double dollar ($)), while single plus (+) is a constrained match (can be used at word boundaries). For example:

* +{conf}+ becomes {conf}
* dev++{conf}++ becomes dev{conf}

TIP: You may recognize that ++ is now equivalent to $ (and perhaps easier to read).

Notice that I did not mention anything about formatting the text as monospace. I think we need to separate how the content is marked for parsing from how it's marked for formatting. This gives us much more flexibility in how we markup the text, because we can combine passthrough semantics with formatting marks in whatever way necessary.

The backtick characters around text only mean that the text should be formatted as monospace. The backtick characters do not add passthrough semantics. In most cases, the passthrough semantics aren't necessary, so using the backticks for monospaced formatting is all that's necessary.

* `literal` becomes literal (in monospace)
* `{backend}` becomes html5 (in monospace)
* a``|``b becomes a|b (where | is monospace)

The question that remains is, how do you prevent substitutions in text formatted as monospaced? (i.e., monospaced literal) Answer: You either escape the substitution or combine the formatting and the passthrough.

* `\{backend}` becomes {backend} (in monospace)
* `+{backend}+` becomes {backend} (in monospace)

By not mixing monospace formatting with passthrough (literal) semantics, we are deviating slightly from the behavior of backticks in Markdown. However, that's because AsciiDoc has additional features, such as attribute references, that we want to be able to leverage when formatting text as monospace (just as we would anywhere). As it turns out, the lack of ability for substitutions when creating monospaced text in Markdown is quite limiting (and frustrating).

Let's give this separation of inline passthroughs (using single and double plus) and monospace formatting (using single and double backticks) a try and see how it goes. If we need to remove or reduce the number of subsitution applied when formatting text as monospace, we can entertain the idea once we've given this configuration a trial.

-Dan

--

Dan Allen | http://google.com/profiles/dan.j.allen

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/An-important-syntax-change-coming-in-1-5-0-tp1911.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML