The PreTeXt Guide

The schema is born within a PreTeXt document, schema/pretext.xml, where surrounding text provides documentation and guidance on implementation. The literate programming support in PreTeXt (start at Section 3.31) is used to produce a file, schema/pretext.rnc, which is a RELAX-NG specification in compact syntax. HTML and PDF versions are available on the PreTeXt website as documentation. We provide some guidance below on reading the compact syntax.

The compact syntax is a faithful representation of the more verbose XML syntax. And vice-versa, so it is possible to translate back-and-forth between the two syntaxes. In practice, we convert the compact version to the XML version, producing a file schema/pretext.rng. Some tools require this latter (100% equivalent) version. We perform this conversion with trang, an open source program written by James Clark, one of the authors of RELAX-NG. (trang stands for “TRAnslator for relax NG”.) The compact syntax is often indicated as RNC and the XML syntax is often indicated as RNG.

XSD (XML Schema Definition), from the World Wide Web Consortium (W3C), is an alternative to the RELAX-NG syntax. It cannot express as many situations as the RELAX-NG syntax, but we have created the PreTeXt schema in a way that trang can convert to an XSD specification without introducing any more-permissive “approximations.” But the XSD version seems to have a few small inaccuracies, and in particular should not be used for validation. That said, schema/pretext.xsd may be useful for tools (e.g. editors) that require it.

The files pretext.xml, pretext.rnc, pretext.rng, and pretext.xsd are all provided in the schema directory under revision control, and are updated by the schema/build.sh script when changes are made to pretext.xml. So as an author, you do not need to install or run trang and should just link to the (continually updated) copies in your mathbook directory.

We once provided a document type definition (DTD) as a description of the PreTeXt vocabulary. Mitch Keller

¹

rellek.net/home/

wrote an excellent initial version of this chapter to help others understand similar principles in the context of the DTD. However, the DTD was not sufficiently flexible to handle elements that behave differently in different locations, such as an <introduction> to a <chapter> versus an <introduction> to an <exercisegroup>. As further evidence, trang will knowingly refuse to convert the PreTeXt schema to a DTD since the DTD syntax is not sufficiently expressive to describe PreTeXt.

If you are interested in conversions, more tools can be found at relaxng.org and we have information on installation in Appendix E. We would be pleased to learn more about authors’ experiences with other converters.