Troubleshoot Unconstrained Formatting Pairs

An unconstrained formatting pair is often used to format just one or a few characters in a word.

When should I use unconstrained formatting?

Consider the following questions:

Is there a letter, number, or underscore directly outside the opening or closing formatting marks?
Is there a colon, semicolon, or closing curly bracket directly before the opening formatting mark?
Is there a space directly inside of a formatting mark?

If you answered “yes” to any of these questions, you need to use an unconstrained pair.

To help you determine whether a particular syntax pattern requires an unconstrained pair versus a constrained pair, consider the following scenarios:

Constrained or Unconstrained?
AsciiDoc	Result	Formatting Pair	Reason
`Sara__h__`	Sarah	Unconstrained	The letter `a` is directly adjacent to the opening mark.
`Bold`	Bold	Unconstrained	The `o` is directly adjacent to the closing mark.
`–2016`	–2016	Unconstrained	The `;` is directly adjacent to the opening mark.
` bold `	bold	Unconstrained	There are spaces directly inside the formatting marks.
`2016–`	2016–	Constrained	The adjacent `&` is not a letter, number, underscore, colon, or semicolon.
`9-to-5`	9-to-5	Constrained	The adjacent hyphen is not a letter, number, underscore, colon, or semicolon.

Unconstrained pair edge cases

There are cases when it might seem logical to use a constrained pair, but an unconstrained pair is required. Substitutions may be applied by the parser before getting to the formatting marks, in which case the characters adjacent to those marks may not be what you see in the original source.

One such example is enclosing a monospace phrase inside curved quotation marks, such as “end points”.

You might start with the following syntax:

"`end points`"

That only gives you “end points”. The backticks contribute to making the curved quotation marks, but the word isn’t rendered in monospace.

Adding another pair of backticks isn’t enough either.

"``end points``"

The parser ignores the inner pair of backticks and interprets them as literal characters, rendering the phrase as “`end points`”.

You have to use an unconstrained pair of monospace formatting marks to render the phrase in monospace and a constrained pair of backticks to render the quotation marks as curved. That’s three pairs of backticks in total.

Example 1. A monospace phrase inside curved quotation marks

"```end points```"

If, instead, you wanted to surround the monospace phrase with typewriter quotation marks, such as "end points", then you need to interrupt the curved quotation marks by applying a role to the monospace phrase or escaping the typewriter quote. For example:

Example 2. A monospace phrase inside typewriter quotation marks

"[.code]``end points``" or \"``end points``"

Another example is a possessive, monospace phrase that ends in an “s”. In this case, you must switch the monospace phrase to unconstrained formatting.

The ``class```' static methods make it easy to operate
on files and directories.

Rendered possessive, monospace phrase

The class’ static methods make it easy to operate on files and directories.

Alternately, you could encode the curved apostrophe directly in the AsciiDoc source to get the same result.

The `class`’ static methods make it easy to operate on files and directories.

This situation is expected to improve in the future when the AsciiDoc language switches to using a parsing expression grammar for inline formatting instead of the current regular expression-based strategy. For details, follow Asciidoctor issue #61.

Escape unconstrained formatting marks

Since unconstrained formatting marks are meant to match anywhere in the text, context free, that means you may catch them formatting text that you don’t want styled sometimes. Admittedly, these symbols are a bit tricky to type literally when the content calls for it. But being able to do so is just a matter of knowing the tricks, which this section will cover.

Let’s assume you are typing the following two lines:

The __kernel qualifier can be used with the __attribute__ keyword...

#`CB###2`# and #`CB###3`#

In the first sentence, you aren’t looking for any text formatting, but you’re certainly going to get it. The processor will interpret the double underscore in front of __kernel as an unconstrained formatting mark. In the second sentence, you might expect CB###2 and CB###3 to be highlighted and displayed using a monospace font. However, what you get is a scrambled mess. The mix of constrained and unconstrained formatting marks in the line is ambiguous.

There are two reliable solutions for escaping unconstrained formatting marks:

use an attribute reference to insert the unconstrained formatting mark verbatim, or
wrap the text you don’t want formatted in an inline passthrough.

The attribute reference is preferred because it’s the easiest to read:

:scores: __
:hash3: ###

The {scores}kernel qualifier can be used with the {scores}attribute{scores} keyword...

#`CB{hash3}2`# and #`CB{hash3}3`#

This works because attribute expansion is performed after text formatting (i.e., quotes substitution) in the normal substitution order.

Here’s how you’d write these lines using the inline single plus macro to escape the unconstrained formatting marks instead:

The +__kernel+ qualifier can be used with the +__attribute__+ keyword...

#`+CB###2+`# and #`+CB###3+`#

Notice the addition of the plus symbols. Everything between the plus symbols is escaped from interpolation (attribute references, text formatting, etc.). However, the text still receives proper output escaping for HTML special characters (e.g., < becomes <).

The enclosure `+TEXT+` (text enclosed in pluses surrounded by backticks) is a special formatting combination in AsciiDoc. It means to format TEXT as monospace, but don’t interpolate formatting marks or attribute references in TEXT. It’s roughly equivalent to Markdown’s backticks. Since AsciiDoc offers more advanced formatting, the double enclosure is necessary.