Skip to main content

Section 44.4 Strategy

Much like the build advice at the end of Section 43.9, 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 macros are copied from <docinfo>, and a syntactically correct file is produced (one per image). Then pretext calls your system's 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 -d argument.

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 temporary directory:.

Some notes:

  • 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 xinclude mechanism 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 44.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 44.5.