Section 6.5 Validation
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?)
jingfor the first step, RELAX-NG validation. This is an open source companion to the
trangconverter 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
sort -k 2then the output will group similar messages together.
Previously, we used
xsltprocas 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
xmllintprogram, 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
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.