Debugging Image Generation

Section 47.5 Debugging Image Generation

A principal use of the pretext/pretext script is to isolate source code from <latex-image> sections, package them up as proper *.tex files, run LaTeX to make cropped PDF versions, and then convert these to other formats such as SVG or PNG.

Much of this activity happens in a temporary directory, and it is similar for Asymptote images and other options of the script. If you use the -vv switch described above, then these temporary directories will be noted in the debugging output requested, and a complete list will be the last line of output. In this case, and if the script encounters an error prior to successful execution, then these directories will be left in place. Looking to see what files end up there, and what those files contain, is often useful in determining the step where the script fails, and maybe even why.

With no chatter requested, or just progress indications (-v) these temporary directories will be cleaned out as the last part of successful execution.

Another option is to ask for the actual source files (*.tex, *.asy, etc.) as the output of a run. This is accomplished with the -f source option when invoking pretext/pretext. If the right packages or macros are not being employed in these files, this is an easy way to get at the source files for inspection and analysis, and is a good first check on problematic execution.

It is possible to design an image whose dimensions exceed the page size of typical LaTeX output. An example is an image you might use only for some HTML output, such as a slideshow. In this case, construction and conversion to an output format like SVG may fail. There is a string parameter, latex.geometry, that allows you to provide options to the LaTeX geometry package

ctan.org/pkg/geometry

which influence page size. At a minimum, you need to override the page size, plus it might be best to override the “printable” area as well. (See Section 47.8 for more on string parameters, which will be obsolete in the future.) Here is a sample addition to a call to the pretext script. Note that you cannot put the -x switch last, so it must precede some other option.

-x latex.geometry "paperwidth=21in,paperheight=21in,total={20in,20in}"

Since the image will ultimately be cropped, there is little harm in making the overall page grossly oversized. However, if the LaTeX code you are using employs lengths like \linewidth or \textwidth (which we will claim is not a good practice), then your image might be very sensitive to how you set the page geometry. Note that restricting the scope (Section 47.10) might be useful if this accomodation is only needed for one image.

Prev Top Next