Text Formatting and Punctuation

A formatting mark is a symbolic character, such as *, _, or ~, that indicates the inline style you want the AsciiDoc converter to apply to the text. Formatting marks come in pairs.

A formatting pair consists of an identical opening mark and closing mark that encloses the text you want to style. The formatted text (i.e., the text enclosed by a formatting pair) can span multiple, contiguous lines.

The opening mark specifies where you want the style to start. The closing mark specifies where you want the style to end.

Formatting pairs can be nested, but they cannot be overlapped. If the pairs are overlapped, the behavior is unspecified and the AsciiDoc processor may produce malformed output.

A formatting pair is defined as either constrained or unconstrained, depending on where it’s allowed to be applied. An unconstrained pair can be applied anywhere, whereas the application of a constrained pair is more limited.

When a space-like character directly precedes the text to format, and a space-like character or punctuation mark (,, ;, ", ., ?, or !) directly follows the text, and the text does not start or end with a space-like character, a constrained formatting pair can be used. A constrained pair uses a single opening mark and a single closing mark to enclose the text to be styled (e.g., *strong*).

For example, you use this form to format a word that stands alone,

to format a sequence of words,

or to format a word adjacent to punctuation, like an exclamation mark.

As you can see, the constrained pair offers a more succinct markup at the tradeoff of having more limited (constrained) use. However, it should suffice in most cases, so the abbreviated markup is a benefit. You can think of a constrained pair as being a weaker markup than an unconstrained pair.

An unconstrained formatting pair can be used anywhere in the text. When the conditions are not met for a constrained formatting pair, the situation calls for an unconstrained formatting pair. An unconstrained pair consists of a double opening mark and a double closing mark that encloses the text to be styled (e.g., Sara**h**).

For example, you’d use an unconstrained pair to format one or more letters in a word.

The unconstrained pair provides a more brute force approach to formatting at the tradeoff of being more verbose. You’ll typically switch to an unconstrained pair when a constrained pair doesn’t do the trick. See When should I use an unconstrained pair? for more examples of when to use an unconstrained pair.