The PreTeXt Guide

A schema, in our case a RELAX-NG schema, is a formal specification of an XML vocabulary (the allowed tags and attributes), and how they relate to each other. So, for example, the restrictions that say you cannot nest a <book> inside of a <chapter>, nor can you nest a <subsection> in a <chapter> without an intervening <section>, are expressed and enforced by the schema. One of the beauties of the schema is that it is written using a very specific syntax and then there are tools that use a schema as input. In particular, a PreTeXt source file that conforms to the PreTeXt schema is said to be valid. You should strive to always, always, always have valid source files, and therefore you want to regularly verify that this is the case.

You can find the PreTeXt schema in the schema folder of the GitHub repository⁷. The version we author and maintain is pretext.xml, which is used to create pretext.rnc, which uses the compact syntax of the RELAX-NG specification. By providing the schema and your source to a program called a validator you can check if your source is valid, and if not, why. See Chapter 6 for the details on doing this.

The PreTeXt-CLI also has some basic validating capability: after running pretext build, open the .error_schema.log file in the main folder of your project to see validation errors.

If you author source that is valid PreTeXt, then a conversion of your source to another format should succeed. And maybe in the future, somebody will create a new conversion to a new output format, and your source should still produce faithful output, with no extra effort from you. Think of the schema as a contract between authors of source files and developers of converters. This is different than performing a conversion and getting good-looking output–that can just be a happy accident and your source may not succeed with some other conversion.

We cannot stress enough the importance of setting up and performing regular validation and preventing many consistent errors of the same type. You will learn what elements are allowed where, and which are not, from the messages produced by validation errors. And when a conversion fails, or produces spectacularly incorrect output, validating your source should be your first reaction. Always.

The other beauty of a schema is that you can supply it to a text editor (Section 1.2) and then you will get context-sensitive help that greatly assists you in using only the tags and attributes that are allowed in a given location of your source. XML Copy Editor⁸ is the one editor like this we have tried, but we do not have extensive experience.

We have devoted an entire chapter (Chapter 6) to amplifying this introduction and providing more details, such as where to find details on installing a validator.