You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
92 lines
4.5 KiB
92 lines
4.5 KiB
4 years ago
|
////
|
||
|
|
Included in:
|
||
|
|
|
||
|
|
- user-manual: Catch a missing or undefined attribute
|
||
|
|
////
|
||
|
|
|
||
|
|
As a result of a misconfigured document or inadvertent substitution, an attribute reference may point to a non-existent attribute (e.g., `+{does-not-exist}+`).
|
||
|
|
It could be that the attribute reference itself undefines the attribute (e.g., `+{set:attribute-no-more!}+`).
|
||
|
|
You'll want to think about how you want the processor to handle these situations and configure it accordingly.
|
||
|
|
|
||
|
|
AsciiDoc Python simply drops any line that contains a reference to a missing attribute.
|
||
|
|
This "`feature`" was designed with AsciiDoc Python's own template language in mind, which is also based on the AsciiDoc syntax.
|
||
|
|
However, this behavior was never really intended for use in regular AsciiDoc documents.
|
||
|
|
The behavior is frustrating for the author, editor, or reader because it's not immediately obvious when a line goes missing.
|
||
|
|
Discovering the absence of certain line often requires a painstaking read-through of the document or section, if it's even noticed at all.
|
||
|
|
|
||
|
|
Asciidoctor offers two attributes to alleviate this inconvenience: `attribute-missing` and `attribute-undefined`.
|
||
|
|
|
||
|
|
===== Missing attribute
|
||
|
|
|
||
|
|
The `attribute-missing` attribute controls how missing (i.e., unresolved) references are handled.
|
||
|
|
By default, missing references are left intact so the integrity of the document is preserved (`skip`).
|
||
|
|
However, that mode doesn't help the author track down these references.
|
||
|
|
|
||
|
|
To help with that task, Asciidoctor can be configured to warn when a missing reference is encountered (`warn`).
|
||
|
|
Asciidoctor can also emulate the behavior of AsciiDoc Python (`drop-line`), or offer something in between (`drop`).
|
||
|
|
|
||
|
|
Here are the four possible values of the `attribute-missing` attribute:
|
||
|
|
|
||
|
|
`skip`:: leaves the reference intact without issuing a warning (default setting)
|
||
|
|
`drop`:: drops the reference, but not the whole line
|
||
|
|
`drop-line`:: drops the whole line on which the reference occurs (matches behavior of AsciiDoc Python)
|
||
|
|
`warn`:: leaves the reference intact, but also prints a warning about the missing attribute (recommended)
|
||
|
|
|
||
|
|
Consider the following line of AsciiDoc:
|
||
|
|
|
||
|
|
[source]
|
||
|
|
----
|
||
|
|
Hello, {name}!
|
||
|
|
----
|
||
|
|
|
||
|
|
Here's how the line is handled in each case, assuming the `name` attribute is not defined:
|
||
|
|
|
||
|
|
[horizontal]
|
||
|
|
`skip`:: Hello, \{name}!
|
||
|
|
`drop`:: Hello, !
|
||
|
|
`drop-line`:: {empty}
|
||
|
|
`warn`::
|
||
|
|
+
|
||
|
|
----
|
||
|
|
asciidoctor: WARNING: skipping reference to missing attribute: name
|
||
|
|
----
|
||
|
|
|
||
|
|
If you want the processor to fail when the document contains a missing attribute, set the `attribute-missing` attribute to `warn` and pass the `--failure-level=WARN` option to the processor.
|
||
|
|
|
||
|
|
$ asciidoctor -a attribute-missing=warn --failure-level=WARN doc.adoc
|
||
|
|
|
||
|
|
When using the API, you can consult the logger for the max severity of all messages reported or look for specific messages in the stack.
|
||
|
|
|
||
|
|
There are several exceptions when the `attribute-missing` attribute is not strictly honored.
|
||
|
|
One of those cases is the include directive.
|
||
|
|
If a missing attribute is found in the target of an include directive, the processor will issue a warning about the missing attribute and drop the include directive.
|
||
|
|
This behavior was chosen because showing the unresolved include directive to the reader is messy.
|
||
|
|
|
||
|
|
Another case is the block image macro.
|
||
|
|
If a missing attribute is found in the target of an include directive, the processor will issue a warning about the missing attribute, but leave the image macro unresolved so as to show it as alt text.
|
||
|
|
|
||
|
|
A missing attribute reference can safely be used in an ifeval clause without any side effects (i.e., `drop`) since often the purpose of that statement is to determine whether an attribute resolves to a value.
|
||
|
|
|
||
|
|
===== Undefined attribute
|
||
|
|
|
||
|
|
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:
|
||
|
|
|
||
|
|
`drop`:: substitute the expression with an empty string after processing it
|
||
|
|
`drop-line`:: drop the line that contains this expression (default setting; matches behavior of AsciiDoc Python)
|
||
|
|
|
||
|
|
The option `skip` doesn't make sense here since the statement is not intended to produce content.
|
||
|
|
|
||
|
|
Consider the following declaration:
|
||
|
|
|
||
|
|
```
|
||
|
|
{set:name!}
|
||
|
|
```
|
||
|
|
|
||
|
|
Depending on whether attribute-undefined is `drop` or `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.
|
||
|
|
|
||
|
|
TIP: We recommend putting any statement that undefines an attribute on a line by itself.
|