Keeping Your Source Up-to-Date

Section 46.9 Keeping Your Source Up-to-Date

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.

So you have two choices:

Process your source with any of the provided conversions and edit by hand until the warnings all disappear.
Run the deprecation-fixing conversion and accept the changes in XML formatting. (Read on for more specifics about these changes.)

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.

Here are some notes:

Be sure to experiment on copies of your source in a scratch directory. Send your output to another directory. When finished, use a diff tool to inspect the actual changes made. You can record your eventual changes using revision-control. (See Git for Authors
¹
pretextbook.org/gfa/html/
.)
Do not enable xinclude processing or else your several files will all be merged into one as output and any modularity of your source will be lost.
Every single bit of indentation and whitespace in your source will be preserved, except perhaps for some blank lines near the top of your source files, and limited exceptions noted below.
Attributes will likely be re-ordered, with normalized spacing between them.
Empty elements will have any spaces removed from the end of the tag.
Elements with no content may be written with a single empty tag.
CDATA sections will be converted to text acceptable to the XML parser. In other words, the CDATA wrapper will be removed and dangerous characters (&, <, >) will be replaced by equivalent entities (such as &). If you have many matrices expressed in LaTeX and wrapped in a CDATA, this might be a big change. See Subsubsection 4.1.4.2 for background.
The output files will be labeled as having UTF-8 encoding.
It could be necessary to run this conversion more than once if deprecations build on one another. In other words, we do not update specific conversions, but rely on regular use to keep source up-to-date.
It should be safe to run this conversion repeatedly, even after new deprecations are added. In fact, it is encouraged.
The PreTeXt source file examples/sample-errors-and-warnings.xml is intentionally full of lots of bad stuff. You can experiment with it, should you want to see interesting things happen. We have already performed the normalization step, so you can concentrate on substantive changes.

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

pretextbook.org/gfa/html/

.) Or maybe even make two commits, one from the normalization step, and a second with the substantive changes.

Prev Top Next