The PreTeXt Guide

We cannot stress enough the importance of validating your source early and frequently. Error conditions and messages can be built into processing (we have some anyway), but they are much better accomodated by tools built for just this purpose. If your processing with the PreTeXt-CLI suddenly fails, or if chunks of your content fail to materialize, it is highly likely that a validation check will tell you where the problem lies. If you integrate regular checks into your workflow, then sudden problems can be traced to recent changes. (Perhaps paired with using git bisect, in the extreme. You are using revision control, aren’t you?)

We use jing for the first step, RELAX-NG validation. This is an open source companion to the trang converter described above. As a Java program, it should be cross-platform. It is also packaged for Debian and Ubuntu Linux, and is installed in CoCalc (see Section 5.14). It provides messages keyed to the line number and character number of your source, and the messages are very clear and informative. See notes on installation in Appendix E. We would be pleased to learn more about authors’ experiences with other validators.

You might get a lot of error messages the first time you use jing. If so, it might be that many of them are the same situation. If you pipe the output of jing through sort -k 2 then the output will group similar messages together.

Previously, we used xsltproc as the XSLT processor. We no longer recommend this option for authors, who should be using the PreTeXt-CLI. However, if you still use xsltproc, then you likely automatically also have the xmllint program, which will perform validation with RELAX-NG schema. Our experience is that it bails out at the first warning, or at least does not process the remainder of the current subtree, and that the error messages are often very misleading. We will not support questions about validation based on output from xmllint.

The second step is easier, since it is an XSL transform. In other words, it is just another stylesheet, which you run against your source, with a processor like xsltproc. This stylesheet encoding additional restrictions is unique to PreTeXt and will report exceptions that are too difficult to express with RELAX-NG. So validation is two complementary steps. See Section 6.2 for the exact syntax for using this stylesheet.