Subsection 5.6.2 Managing Directories
The name, and location of the external and generated directories (both of them, always) are then specified in a publication file (see Subsection 44.7.1 for the precise specification). The values of these attributes are relative pathnames to the directories, relative to the location of the main PreTeXt file for your project. Let us take a look at an example.
Suppose you are M. Jones, the author of the AOTA project, and so you might have the following directory and file structure. There is some sort of overall path from the root of your entire filesystem to your project, so on Linux this path could be
/home/mjones/books/
and on other operating systems it will be slightly different, but those differences are not relevant here. Inside of
books there would be an aota directory for the AOTA project, structured as follows. We are most interested in the ext and gen directories.aota
source
aota.ptx
alligators.ptx
dogs.ptx
publication
print.ptx
online.ptx
epub.ptx
ext
photos
slow-alligator.jpeg
fast-whippet.png
movies
alligator-chases-whippet.mp4
data
deer-weights.csv
gen
latex-image
marsupial-life-cycle.svg
youtube
sloth.jpg
In your publication files you would then have the entry, as a sub-element of the
source element,<directories external="../ext" generated="../gen"/>
Notice that we have deliberately named our directories
ext and gen as part of this illustration, so that they are not identical to the attribute names on the <directories> element. The two attribute values are relative to the location of the main PreTeXt file, in this case aota.ptx. The two periods, .., mean to go up a level, here to the aota directory, then the slash indicates a step down to either gen or ext. Note that latex-image and youtube within gen must be specified exactly that way. Now every PreTeXt production tool can deduce where your files are.How do you specify in your PreTeXt source which file to use where? Suppose you want your two (external) photographs to be used in a
<sidebyside> element. You would author<sidebyside widths="50% 30%">
<image source="photos/slow-alligator.jpeg"/>
<image source="photos/fast-whippet.jpeg"/>
<sidebyside/>
Notice that the values of your
@source attributes do not include ext or ../ext. This gives you the freedom to move your ext directory or rename it, and then you only change the publication file and not your source. The decision to have the subdirectories photos and movies are not easily changed, since they will be in your source, but they may have value for the organization of your project.The chase video is of your own creation, you have included it as part of your project’s files, and will be hosting it on your web server, where the rest of your HTML version is made available for viewing. You might author
<figure xml:id="fig-chase">
<caption>Alligator chases whippet</caption>
<video source="movies/alligator-chases-whippet.mp4"/>
<figure/>
The situation with the generated files is presently a bit more complicated, but will eventually be transparent to an author. The marsupial life cycle diagram has been authored in your source using the language from the LaTeX TikZ package, which is delimited as a
<latex-image> element. When building a PDF from LaTeX output this is a no-brainer—PreTeXt just puts your TikZ code into the LaTeX file. But how about HTML output? The pretext/pretext script will manufacture a standalone version of this image and then convert it to an SVG, and this version will work very well in the online version of your project. What do you author?<figure xml:id="fig-life-cycle">
<caption>Marsupial Life Cycle</caption>
<latex-image xml:id="marsupial-life-cycle">
-- some TiKZ code here --
</latex-image>
<figure/>
With the right options to the
pretext/pretext script, the file marsupial-life-cycle.svg will be generated. Presently, you must explicitly tell the script to place the output in the directory/home/mjones/books/gen/latex-image
but we plan to make this the default behavior. Or you could generate the file anywhere, and move it to the
latex-image subdirectory of gen. Notice how much of the process of creating a companion SVG image (which excels in a web browser) is automated, and how the @xml:id attribute and the directories in the publication file are used to keep everything coordinated. The latex-image directory is not negotiable, it is the home for every image authored using a PreTeXt <latex-image> element (see List 5.6.2.2).The slow sloth video was created by somebody else and posted to YouTube as a super slo-mo 240fps video. You authored it within a
<figure> simply by using the ID of the video on YouTube.<figure xml:id="fig-sloth">
<caption>Slow Sloth</caption>
<video xml:id="sloth" youtube="DJWEqYcxUl8"/>
<figure/>
With the right options to the
pretext/pretext script, the file sloth.jpg will be generated by requesting a thumbnail preview from YouTube’s servers. Note how this content is generated from your source (precisely, the YouTube ID) through an automated process. Presently, you must explicitly tell the script to place the output in the directory/home/mjones/books/gen/youtube
but we plan to make this the default behavior. The
youtube directory is not negotiable, it is the home for every server-generated preview image for an embedded YouTube video (see List 5.6.2.2). (Note that any <video> may have an author-provided image as its preview, and then this would be considered an external file.)As you can tell from the above, different output formats have different expectations for additional files and when producing an output, there may be different expectations for where exactly where to find files. A good example is the EPUB format, which despite being basically an HTML format, is still very rigorous about names, formats, and locations for image files. With the above procedures you provide just enough information for PreTeXt to handle the remainder of the complexity for you, without you becoming an expert with the EPUB standard. So the
pretext/pretext script can automatically produce PDF, HTML, EPUB, Kindle, and braille, each in a single step.We have skirted one finer point of all this. How does an author know if a file is external or generated and what are the supported subdirectories of the generated directory? A PreTeXt
@source attribute will almost always point to a file that belongs in the external directory. An exception is the @preview attribute which is used to specify static images to use in outputs like PDF or print to represent more dynamic objects employed in more-capable electronic formats (videos, audio, interactives). (Please alert us to other exceptions!) The list below describes the subdirectories of the generated directory. The files that belong in these directories are all generated by the pretex/pretext script using aspects of your authored source.asymptote- Images described by Asymptote code in an
<asymptote>element. latex-image- Images described by LaTeX code in a
<latex-image>element. preview- Static images of dynamic content, created with automatic screenshots via a headless web server.
problems- MyOpenMath problems in static PreTeXt forms. Possibly broken.
sageplot- Images described by Sage code in a
<sageplot>element. youtube- Static images for YouTube videos, automatically downloaded from YouTube servers.
Just one more obscure situation to address, requiring a peek under the hood. Occasionally there are external files used in ways that PreTeXt cannot “see” them and provide the management necessary. One example is a file of data points used to generate a plot using the
<latex-image> element. Suppose we have a file/home/mjones/books/ext/data/deer-weights.csv
as shown in Example 5.6.2.1. We will use this inside of a
<latex-image> element employing PGF code with a table {}; construction. As part of building the LaTeX output, this file will be copied to a temporary directory asexternal/data/deer-weights.csv
Note that your
ext has been converted to external as files are copied—that is not a typo. PreTeXt is not going to examine all your code and try to guess where you have requested a file. So you need to author\addplot table {external/data/deer-weights.csv};
using the filename created after the copy. Then the LaTeX compilation will locate the file successfully. The
external directory after the file copy is not negotiable, that is what is always used.
