Section 5.5 Warnings and Errors

Your first response to any trouble—a failed conversion, or output that looks spectacularly wrong—should be to validate your source, always (see Section 5.4 and the fuller Chapter 6). Many puzzling conversion warnings are only downstream symptoms of a structural mistake that validation names directly and early. And do not be alarmed if a document that produces fine output still reports validation errors, or the reverse: the two checks are independent, a point the Author FAQ (Chapter 9) takes up, along with several warnings that are safe to ignore.

When a conversion does warn, it tells you where. Alongside a description of the problem, PreTeXt prints the structural path to the element—an ancestor chain such as pretext/book/chapter/section/theorem/statement/p/xref, with a trailing @name for an attribute—and the nearest enclosing <title> and author-supplied @xml:id. Any one of these is a search target: copy a title or an @xml:id and use your editor’s “find in all files”, or grep from a terminal, to land on the exact spot in your source, whichever file holds it. Because the whole project is processed as a single tree, a conversion message cannot name the file for you, but the search will.

The validation report locates a problem even more precisely. It names the offending source file outright, and gives a counted path such as /pretext/article/section[2]/p[3]/em[2]/p[1]—in the second <section>, its third <p>, that paragraph’s second <em>, the first <p> inside—along with a line number in the assembled version of your source and an excerpt of the offending content. A count tallies elements of the same name, so p[3] is the third paragraph of its section even when other elements stand between, and an element that is the only one of its name at its location shows no count. This is one more reason validation is the first response, not the last resort.

If a message is too vague to act on, narrow it by removing content until it goes away. With modular source (Section 5.3) this is quick: comment out the <xi:include> for a chapter or section, rebuild, and see whether the problem leaves with it; an individual element can be commented out with <!-- --> just the same. When a whole chapter is suspect, bisect it by hand—comment out half of its sections, rebuild, and repeat on whichever half still fails. A few rounds corner almost any offending construction, even one a message describes poorly.