Subsection 5.6.3 Backward-Compatibility and Migration
Directory management was added in the middle of 2021. For projects existing at that time, it is an “opt-in” feature. In other words, existing projects can still be built by moving additional files in the same ways as always, so long as you do not have a
<directories> element in your publication file.However, it is absolutely necessary to opt-in to directory management (via the publication file) if you want to build EPUB or Kindle formats. You will also then be able to build PDF and HTML output with a single invocation of the
pretext/pretext script, without any extra effort to place additional files in the right places.New projects should definitely adopt directory management as their project develops. New features and tools will assume this. We now describe how existing projects can migrate.
Previously there was not a firm distinction between external and generated files, though they were specified differently in PreTeXt source. Many authors placed both types of files into a single directory, and since the default for locating generated files was a directory called
images, this was often the single directory employed. Thus, external files would be specified with a @source attribute such as<image source="images/bobcat.jpg"/>
A solution, if a bit clunky, is to make a new directory named
ext and copy images and its contents to become a subdirectory of ext. Then place a relative path to ext in the @external attribute in your publication file. This means you will not have to edit your PreTeXt source at all. At some later time, you could remove all references to images in your source and move the files themselves directly into ext.For generated files it will be a bit more involved. You need a new directory, such as
gen, and you need to add it to your publication file with the right relative path. Then you will need to create as many of the relevant directories from List 5.6.2.2 as necessary, as subdirectories of gen. Populate these subdirectories with the relevant files, which may have been located in images before you started migrating. There was a string parameter, directory.images, that could be used to specify an alternative directory to the default, images. That parameter is now announced as deprecated, but will still be effective until your project opts-in.As another short-term option for Mac or Linux users, it is possible to take previously existing resource directories and make symbolic links from a previous image directory, such as
my_images, to the names provided here. In that case, assuming the directory structure provided here, a command like ln -s my_images external (issued in the directory containing my_images) would create the correct symbolic link.
