Some quick preliminary hints. This section will be expanded.
mbx -h: help message, command summary
mbx -v: progress indicators (verbose)
mbx -vv: debugging information (doubly-verbose)
Provide complete debugging output with bug reports
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. Some insight into failures can be found in this directory (which we leave behind for the system to clean-up later). Early in the -vv doubly-verbose output, this directory is reported after the string temporary directory:.
$ ~/mathbook/script/mbx -vv -c sageplot -f svg -d images ~/mathbook/examples/sample-article/sample-article.xml
This will extract every image described in sample-article by a <sageplot> element and produce output as SVG files (if possible), which will be deposited in the images subdirectory of the current working directory.
- 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 8.3 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. Sometimes exploring this directory is helpful when debugging problems.