Section 5.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
xsltproc 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?)
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. 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 F. 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 2 then the output will group similar messages together.
If you use
xsltproc as your XSLT processor, 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
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 Schematron rules is unique to PreTeXt and will report exceptions that are too difficult to express with RELAX-NG. So validation is two complementary steps. See Appendix F for the exact syntax for using this stylesheet.