Section 52.1 The Seven Severities
The severities, from least to most consequential, are the following. A severity is a statement about a message; only the last,
fatal, is also an action.
- debug
-
Fine-grained trace, for pinpointing a problem. Silent unless the reader asks for maximum verbosity. (“xsltproc command: …”)
- info
-
Coarse progress, so the reader sees the conversion advancing. (“converting source to HTML”)
- fallback
-
Input was bad or absent, but a sensible default was substituted, so the output is still complete. (“no
@width, assuming100%”) - warning
-
Something the author should address. (“a deprecated element was used”)
- error
-
There is no good default, so a localized piece of the output is broken or missing, but processing continues. (“cross-reference target does not exist”)
- bug
-
An internal PreTeXt defect—not the author’s fault. Please report it. The renderer degrades and continues. (“an
<otherwise>meant to be unreachable”) - fatal
-
Processing halts and no output is expected. (“the source is not valid PreTeXt”)
The distinction between the last two is the crux, and worth stating twice. Bug is a severity: it records that PreTeXt itself is at fault, and then execution continues by degrading gracefully. Fatal is a severity and an action: it records the message and then stops the build.
Reach for
fatal only as an absolute last resort. An author waiting on a build—perhaps minutes before a class—is far better served by degraded output they can still use than by a halt with nothing to show. Unless PreTeXt genuinely cannot produce anything sensible, prefer error (or bug) and carry on. Halting is for source, or conditions, so broken that continuing would be meaningless.
