Catch a Missing or Undefined Attribute
By default, the original AsciiDoc processor drops the entire line if it contains a reference to a missing attribute (e.g.,
This "feature" was added for use in templates written for the original processor, which also used the AsciiDoc syntax.
This behavior is not needed in Asciidoctor since templates are written in a dedicated template language (e.g., ERB, Haml, Slim, etc.). More critically, the behavior is frustrating for the author, editor or reader. To them, it’s not immediately apparent when a line goes missing. Discovering its absence often requires a full (and tedious) read-through of the document or section.
Asciidoctor has two attributes to alleviate this inconvenience:
The attribute attribute-missing controls how missing references are handled. By default, missing references are left intact so it’s clear to the author when one hasn’t been satisfied since, likely, the intent is for it to be replaced.
This attribute has four possible values:
leave the reference in place (default setting)
drop the reference, but not the line
drop the line on which the reference occurs (compliant behavior)
print a warning about the missing attribute
Consider the following line of AsciiDoc:
Here’s how the line is handled in each case, assuming the
name attribute is not defined:
WARNING: skipping reference to missing attribute: XYZ
The attribute attribute-undefined controls how expressions that undefine an attribute are handled. By default, the line is dropped since the expression is a statement, not content.
This attribute has two possible values:
substitute the expression with an empty string after processing it
drop the line that contains this expression (default setting and compliant behavior)
skip doesn’t make sense here since the statement is not intended to produce content.
Consider the following declaration:
Depending on whether attribute-undefined is
drop-line, either the statement or the line that contains it will be discarded.
It’s reasonable to stick with the compliant behavior, drop-line, in this case.
|We recommend putting any statement that undefines an attribute on a line by itself.|