Much like the build advice at the end of Section 46.10, 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:.
• If you have modularized your source across more than one XML file, then be sure to provide your top-level 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 47.10 for a way to have the script restrict its action to only a portion of your project.