Skip to main content
\( \newcommand{\lt}{<} \newcommand{\gt}{>} \newcommand{\amp}{&} \)

SectionC.1Jing 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 need it. A PreTeXt developer might find it useful, and it is a by-product the jing install described below, and is also packaged for Debian and Ubuntu Linux (which is how we use it).

jing is our recommendation for validation by authors, and works very well. It is also packaged for Debian and Ubuntu Linux. Reports of other similarly easy installations for other operating systems are especially welcome. We have only used the installation from source described below, so in particular have not tested xinclude support in the packaged versions.

Installation notes for jing and trang follow.

Clone

Clone the git repository at github.com/relaxng/jing-trang. You will end up with a new jing-trang directory, which we reference below in a relative fashion.

readme.md

Follow the instructions in the top-level readme.md, observing the following notes keyed to the four steps. These helpful notes come courtesy of Jahrme Risner, Mitch Keller, Bruce Yoshiwara, Ken Levasseur, and Jessica Sklar.

1. JDK

It is necesssary to have a 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. JDK is the Java Development Kit.

2. JAVA_HOME

You will need to have this environment variable set correctly. You can see if echo ${JAVA_HOME} on Linux to see if it produces anything sensible and/or consistent with Step 1. Ken Levasseur notes that on OSX 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, here and in Step 4.

3. Root Directory

This should not cause any particular difficulties.

4. ANT

You may need to install this 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 4.2) 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.

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.

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.