Section 5.10 Keeping Your Source Up-to-Date
Once in a while it becomes necessary to adjust how the PreTeXt vocabulary is arranged, which involves adding or removing elements or attributes, or changing their behavior. When elements or attributes are removed, or their relationships with other elements change, we say that certain items or behaviors are deprecated. Fortunately, we can often automate the changes.
When there is a deprecation, a warning is added so that any conversion will report the presence of the old use in the console. Sometimes we can preserve the old behavior, so there is no rush to make changes to your source. Sometimes a change needs to be more urgent. And frequently old behaviors do not get updates or bug-fixes. Our warnings provide advice and information about what you need to do. There are also announcements on public discussion groups, clearly marked as deprecations. Also, the schema will change as part of any deprecation, so the old elements or old use will be reported.
The rest of this section describes a tool you can use to automate the process of adjusting your source when there are deprecations. Generally, there is an XSLT 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
difftool to inspect the actual changes made. You can record your eventual changes using revision-control. (See Git for Authors.)
Do not enable
xincludeprocessing 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 18.104.22.168 for background.
The output files will be labeled as having
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.xmlis 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/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
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
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.