The PreTeXt Guide

This section describes a tool you can use to automate the process of adjusting your source when there are deprecations. Generally, there is an XSL stylesheet which will convert your XML source to another XML source file, fixing many of the deprecations automatically. However, it is the nature of XML processing that your source file will undergo some cosmetic changes. For example, the order of attributes is never relevant, so an XML-to-XML conversion is free to re-order the attributes of an element, perhaps different from how you like to author them.

You perform this conversion using xsl/utilities/fix-deprecations.xsl on an XML source file in the usual way. By default, output appears on the console, so you will want to specify an output file, for example with the -o flag of xsltproc. You will discover a safety measure that requires you to also use a parameter, which you can pass in to xsltproc with the -stringparam command-line argument.

One choice of the parameter will result in just “copying” your source file and making all the cosmetic source format changes (we refer to this here as normalization ). This might be a useful thing to do first, all by itself, either as a first step, or an exploratory experiment. The other value of the parameter will actually make changes, and report some information about progress.

To process a directory with multiple source files, I would proceed as follows. First make three temporary directories, /tmp/original,/tmp/normal,/tmp/clean, and copy my source files into /tmp/original. Then, using a BASH shell, and inputting the command all on one long line.

rob@lava:/tmp/original$ for f in *.xml; do xsltproc -o ../normal/$f -stringparam fix normalize
$ /home/rob/mathbook/xsl/utilities/fix-deprecations.xsl $f; done

This will loop over every XML file in the current working directory, /tmp/original, running the normalization conversion on each file, with the output files using the same filename, but now being placed in the /tmp/normal directory. If you change to the /tmp directory, then you can compare the results. I like to use the diff utility provided by git.

rob@lava:/tmp$ git diff original normal

Or, try this for a view that might be more informative.

rob@lava:/tmp$ git diff --word-diff original normal

You may only do the above once, on your first use of this conversion stylesheet. You will see how your style of authoring XML will undergo some minor changes. We can repeat the above to actual make the changes necessary due to PreTeXt deprecations. Make /tmp/normal the working directory.

rob@lava:/tmp/normal$ for f in *.xml; do xsltproc -o ../clean/$f -stringparam fix all
$ /home/rob/mathbook/xsl/utilities/fix-deprecations.xsl $f; done

And as above, you can now compare the normal and clean directories to see actual changes. If you are satisfied with the changes, you can copy the files in the clean directory back onto your source files. If you are using revision-control (you are, aren’t you?) then you can make a commit that holds these changes. (See Git for Authors⁵.) Or maybe even make two commits, one from the normalization step, and a second with the substantive changes.