Skip to main content

Section 9.3 Strategy

Much like the build advice at the end of Section 4.8, the mbx 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 mbx calls your 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 later). 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 9.5 for a way to have the script restrict its action to only a portion of your project.
  • Certain arguments that are filenames require a full (not relative) path to locate the right objects. In the example above, you can see the source file requires this (where the shell in use here will expand the ~ to the user's home directory). The -d flag does not require a full path, and so can be specified relative to the current working directory.
  • Do not place the script, or configuration files, anywhere else (except as recommended for your personal copy of the configuration file). The locations are 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.