Section 7.4 Strategy
Much like the build advice at the end of Section 5.11, the
pretext/pretext script collects necessary bits into a system-created temporary directory, does its work, and copies out the desired results. So in the example of the previous section, each chunk of TikZ code is isolated, your LaTeX macros are copied from
<docinfo>, and a syntactically correct LaTeX file is produced (one per image). Then
pretext calls your system's LaTeX executable on each of these files to produce a one-page PDF. This is then cropped and converted to an SVG version, which at the end is copied to the location specified in the
Some insight into failures can be found in the temporary directory where all this processing happened. (We leave the directory, and its contents, behind for the system to clean-up next time the system is rebooted). Early in the
-vv doubly-verbose output, this directory is reported after the string
If you have modularized your source across more than one XML file, then be sure to provide your “top-level” or “master” file as the final argument to the script, just like you would for an invocation of
xsltproc. It is important to understand that your source is one huge “source tree” and your file-by-file modularization is never respected or recognized in any way. In particular, use of the
xincludemechanism is handled by the script, and you should not apply the script to each of your source files individually. If image production (or some other task) takes a long time, see Section 7.10 for a way to have the script restrict its action to only a portion of your project.
Do not place the script, or configuration files, anywhere else (except as recommended for your personal copy of the configuration file). The locations are critically important for locating other files, such as the stylesheets used to isolate parts of your project for processing.
Much of the work of this script happens in the temporary directory described above. We leave a lot of intermediate work behind in this directory. Often, exploring this directory is helpful when debugging problems, or a failure to finish successfully. For an example, see Section 7.5.