SectionF.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 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. 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 (next).

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 necesssary 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.

2. You will need to have the JAVA_HOME environment variable set correctly. You can try echo ${JAVA_HOME} in a console 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, 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 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 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.