Skip to main content

The PreTeXt Guide

Robert A. Beezer, David Farmer, Alex Jordan, Mitchel T. Keller

Section E.1 Jing and Trang

These tools come from James Clark, an author of the RELAX-NG syntax. trang is a converter between different formats for schemas. An author should not ever need it. Though a PreTeXt developer might find it useful, and it is a by-product of the jing-trang install described below.
jing is our recommendation for RELAX-NG validation by authors, and works very well.
jing and trang are packaged (separately) for Debian/Ubuntu Linux, see Subsection E.1.1. Reports of other similarly easy installations for other operating systems, to be included here, are especially welcome. We have employed the Debian/Ubuntu versions and also versions built from source, see Subsection E.1.2.

Subsection E.1.1 jing on Ubuntu and CoCalc

CoCalc
 1 
cocalc.com/
runs Ubuntu when you create a terminal window. The necessary Ubuntu Linux (Debian) package is also named jing and is installed as part of the CoCalc setup. So on Ubuntu, you need to install this package, and on CoCalc you will need to copy over the schema/pretext.rng version of the schema. If you have a CoCalc subscription, it would be even better if you made a clone of the PreTeXt repository, so it would be trivial to update and always have the latest version of the schema in your CoCalc account.
Now it is straightforward to execute jing:
jing /path/to/pretext.rng aota.xml
Presumably something similar to the above will work for any Linux distribution that has packages for jing.
Note that if you have modularized your source files (see Section 5.3), you only need to provide the top-level file as an argument to jing. In particular, the subsidiary files are certain to fail validation since they do not have a <pretext> root element.

Subsection E.1.2 Install jing from Source

If you cannot install this tool easily as part of your system, you can still follow the notes below to build from source. Many authors have done this successfully. Installation notes for jing and trang follow.
Clone
Clone the git repository at github.com/relaxng/jing-trang with the command
git clone https://github.com/relaxng/jing-trang
which assumes you have a command-line version of git installed. You will end up with a new jing-trang directory, which you will certainly want outside of your PreTeXt files and outside of your project files.
readme.md
Follow the instructions in the readme.md found at the top level of the jing-trang distribution, observing the following notes keyed to the four steps. These helpful notes come courtesy of the experiences of Jahrme Risner, Mitch Keller, Bruce Yoshiwara, Ken Levasseur, and Jessica Sklar on a variety of operating systems.
  1. It is necessary to have a developer’s version of java on your machine. Try which java to see if one is already available. Any output here might help in the next step. References here to the JDK is the Java Development Kit. There are specific directions for MacOS (Section J.1) and Windows (Section L.6).
  2. You will need to have the JAVA_HOME environment variable set correctly. You can try echo ${JAVA_HOME} in a Linux console to see if it produces anything sensible and/or consistent with Step 1. Ken Levasseur notes that on MacOS you can go
    echo $(/usr/libexec/java_home)
    and the output is what you set to the JAVA_HOME variable.
    On Windows you may need to set Environmental Variables in the Windows System Properties GUI, both here and in Step 4.
  3. Setting your working directory to the root directory of the jing-trang distribution should not cause any particular difficulties.
  4. You may need to install the ANT tool, almost certainly on Windows. Again, on Windows you may need to set an ANT_HOME environment variable. On Linux, this may be all set for you already as a system tool.
    The README suggests changing slashes on Windows. But you may already be using a shell that gives Unix-like behavior. So try both directions, if necessary. Also, the README suggests running ./ant test (or .\ant test). Doing this on Windows may yield a BUILD FAILED message, but jing may still work.
Results
Change into the build subdirectory. You may have more files here, but the two you really want are jing.jar and trang.jar. So if you have these, you are in good shape.
If you have modularized your source files (Section 5.3) then you need one more library. Look in the top-level lib directory (a peer of build) for xercesImpl.jar. You have two and a half choices now.
  • Copy lib/xercesImpl.jar into build.
  • Or make a “symbolic link” to the third JAR archive. Be sure you are in build and go
    ln -s ../lib/xercesImpl.jar
    which will just make your operating system think this third archive is in the build directory.
  • A third option would be to adjust/augment some classpath information below and send us a report of success. We have not tested this approach.
Now you are ready to use jing to validate a PreTeXt document. Note that the commands below require the XML version of the schema, which is the non-compact version. Also, these are the commands if you build jing-trang from source. If you install a system-supplied version, then consult the man pages, or similar, for syntax which is likely much easier and direct.
For a document contained in a single file, run (with suitable working directory and path prefixes).
java -jar jing-trang/build/jing.jar pretext.rng my-book.xml
For a document modularized across several files using the xinclude mechanism, issue as one single command line (again, with suitable working directory and path prefixes). This presumes you have moved or symlinked the lib/xercesImpl.jar file into the build directory. Do not leave any spaces around the equals-sign, we have split that line there for readability, so the -D option should not have any spaces in its argument.
java -classpath jing-trang/build
-Dorg.apache.xerces.xni.parser.XMLParserConfiguration=
    org.apache.xerces.parsers.XIncludeParserConfiguration
-jar jing-trang/build/jing.jar pretext.rng my-book.xml
It may go without saying that scripting this task will make you more likely to do it as often as is necessary and you will save yourself much time, and a little frustration, in the process.
Jahrme Risner provides the following setup he uses to make it very convenient to regularly validate his sources. This is a “shell script”, which a Linux user might add to their ~/.bashrc file. Note that we have again split the line with the -D option at the equals-sign, without a line-continuation character. Do not do that in your version.
ptx-check() {
  java\
    -classpath ~/GitHub/jing-trang/build\
    -Dorg.apache.xerces.xni.parser.XMLParserConfiguration=
        org.apache.xerces.parsers.XIncludeParserConfiguration\
    -jar ~/GitHub/jing-trang/build/jing.jar\
    ~/GitHub/mathbook/Schema/pretext.rng "$1"
}
Then he can simply go
~ $ ptx-check my-book.xml
at anytime. Note that you might have to provide or adjust some of the paths above for your situation. And there are other ways to script tasks like this.
PrevTopNext