Appendix G. Diagnostics

The asciidoc(1) --verbose command-line option prints additional information to stderr: files processed, filters processed, warnings, system attribute evaluation.

A special attribute named trace enables the output of element-by-element diagnostic messages detailing output markup generation to stderr. The trace attribute can be set on the command-line or from within the document using Attribute Entries (the latter allows tracing to be confined to specific portions of the document).

Trace names. 

<blockname> block close
<blockname> block open
dropped line (a line containing an undefined attribute reference).
floating title
list close
list entry close
list entry open
list item close
list item open
list label close
list label open
list open
macro block (a block macro)
name (man page NAME section)
preamble close
preamble open
push blockname
pop blockname
section close
section open: level <level>
subs (all inline substitutions)


Command-line examples:

  1. Trace the entire document.

    $ asciidoc -a trace mydoc.txt
  2. Trace messages whose names start with quotes or macros:

    $ asciidoc -a 'trace=quotes|macros'  mydoc.txt
  3. Print the first line of each trace message:

    $ asciidoc -a trace mydoc.txt 2>&1 | grep ^TRACE:

Attribute Entry examples:

  1. Begin printing all trace messages:

  2. Print only matched trace messages:

    :trace: quotes|macros
  3. Turn trace messages off: