Recommended syntax for an AsciiDoc spec

This page catalogs syntax recommendations (including deprecation) in anticipation of an AsciiDoc spec.

Setext (two-line) section titles

Setext (two-line) section titles should be deprecated. We often hear authors complain about them because:

• They require excessive typing

• They are required to match the length of the title, making them:

  • a pain to maintain

  • incompatible with languages that have double-width characters

  • display inconsistently when render in a non-monospaced font

• They require writer’s to remember the mapping from symbols to levels

Emphasized text

The single-quote form to mark emphasized text should be deprecated (in favor of the underscore form)

Reasoning:

• Using single quotes for italic is not what people expect (and could format text meant to be in single quotes)

• The single quote form doesn’t have an unconstrained equivalent, so you have to switch to the underscores anyway

• The underscore form is consistent w/ Markdown

Clarify substitution levels

Not exactly syntax, but it is a specification issue…​

Problem:

The specification in AsciiDoc User Guide (ADUG) (version 8.6.8, 17 July 2012) gives two different versions of the default order of substitutions (ADUG 8.5 and 9 vs. ADUG 32). Based on the following test, ADUG 32 seems to match the reference asciidoc implementation, and also AsciiDoctor’s. But…​ maybe not.

Code

 :test: (R
 :testy: )
 {test}{testy}

Result

®

It is not clear that the order of processing in ADUG 32 is optimal either, putting aside backward compatibility as a criterion (see Line drops). It is, however, established behavior, which counts.

Proposal:

Adopt ADUG 32 order of substitutions as the default standard, but make sure that the substitutions carried out are carefully detailed. What, exactly, comprises the classes of quote, macro, etc.?

Note	If backward compatibility were disregarded, attribute substitution might deserve to go to the front of the substitution level-order, to avoid the line-drop problem.

Reasoning:

Backward compatibility with apparent current behavior.

Line drops

Problem:

What are the circumstances under which a line is dropped due to an undefined attribute? What should happen to the text around it? The following test case behaves surprisingly in both AsciiDoctor and asciidoc. This may be viewed as reflecting a problem with the specification.

Code

TEST

Does this {undefined} `drop a line
or does it drop two?`

TEST

Result

TEST

Does this {undefined} drop a line or does it drop two?

TEST

The reference asciidoc implementation does other unexpected things when it drops a line, behavior shared by AsciiDoctor in part:

Code

*This should be bold text.
If not, something {undefined} has happened.*
But this should be plain text.

Result

This should be bold text. If not, something {undefined} has happened. But this should be plain text.

The explanation probably traces back to order of substitution. In the second case, substitution puts in a tag that ends up unmatched when the line containing it is dropped. In the first case — not investigated — perhaps a break tag has replaced a search target.

Proposal:

• considered: "yeah, that’s the specified behavior, 'cause it all makes sense when you think about it enough."

Ewww.

• considered: Just declare the above test cases to be bad input, and move on.

Yuck.

• considered: Fix up all the possible pathological outcomes and keep the specification as is.

Life is too short.

• proposed: Modify "drop the line" when an attribute is undefined to "drop the line up to the tag boundaries".

Reasoning:

• It’s easy to test for tag boundaries.

• Declaring input as invalid is an unpleasant solution.

• Declaring tag breakage as specified behavior is no way to live.

• Minimal effect on existing documents (or: if you were writing documents that rely on the above behaviors up until now, you are a bad person and probably deserve punishment).