Skip to main content

Section 5.9 Images Described in Source

We believe it is important to preserve a record of how diagrams and other graphics are produced. This can be easy when a graphics language is employed to describe the graphical elements, rather than creating a bit-mapped image with some other interface. So we have <asymptote>, <latex-image>, and <sageplot> for elements holding code to produce diagrams or images.

The upside to this is that small edits to the code can easily accomplish minor changes or corrections necessary for the images. The macros provided by an author can be used in the text and in a diagram, leading to greater consistency between the two. Finally, starting from source, we can do the best possible job of producing image formats that are compatible with the document output formats and which scale smoothly in PDFs and in web browsers.

The downside is that processing these images requires various “helper” programs, such as asy, pdflatex, and sage. This requires installing the helper program and perhaps setting the path to it on your system. This is done inside the project.ptx manifest as children as the <executables> element.

Whenever you need to process images described in your source, run pretext build with the -d flag. This will build the correct image output file for your specified target format. If you would like to build additional image formats, you can add -df all to the command. You can also use -a in conjunction with -d to only build these assets and not convert your entire source (useful for really large projects).