Skip to main content

The PreTeXt Guide

Subsection 5.6.1 External and Generated Files

Early in your writing project, you will decide you want to add images, embedded YouTube videos, interactive demonstrations, or other enhancements that are more than just words on the page. Some of these objects will be created outside of your PreTeXt project, such as a photograph. But some images are described within your PreTeXt project, such as a diagram authored using the TikZ package, and PreTeXt will help generate different versions of the diagram in different file formats for use in output formats that are not . For an embedded YouTube video we provide tools that will automatically get you a thumbnail preview image from a YouTube server, which will then appear in your non-interactive PDF version. We describe the photograph as external, since it comes from “somewhere else,” independent of anything you authored in your source. In contrast, an SVG image of your TikZ diagram for HTML output, and a preview image of a YouTube video for use in a print version, are described as generated since they are dependent on what you have put in your source, and PreTeXt automates almost all of their creation for you.
As these files are added to your project, you want to organize them in a specific (but flexible) way. First, make a directory (folder) for your external files. You can use any name you like, including external. Within reason you can place it wherever you want. Natural choices are as a peer of a source directory that holds your PreTeXt files, or as a subdirectory of your project’s top-level directory that may hold all your PreTeXt files. You can also organize this directory with subdirectories of your own choice, if that helps you stay organized.
Similarly, you need a separate directory for your generated files. As above, it can be named anything, including generated, and you can place it almost anywhere (close by). But now, it must have a precise directory structure, described below in List, according to what sort of generation produced the files.
After you have read this section, see the discussion of generated and external files in Subsection 27.2.4 for some good examples of why this flexibility is useful.