COMaT Managing Your Project

Chapter 5 Managing Your Project

Section 5.1 File and directory structure

Here we describe the file and directory structure of a project. PreTeXt allows a fair amount of flexibility in how you structure the project, but we believe the following are best practices.

source folder: Contains all your .ptx files that hold the content of your document. A new book starts with just a single file, but later we will see how to modularize the source to make organizing it easier.
publication folder: Contains your publication.ptx file or files, which define the publication-specific information about your document, as we saw in Chapter 6
assets folder: Put any images or other static files that you will include in your document here. This does not include images that you describe inside your source (like <latex-image>). You can have subfolders as you like, and if you refer to these files in your source, you do not use “assets” as part of the file name (PreTeXt knows where to look, since this is specified in the publication.ptx file.)
generated-assets folder: This is a folder that PreTeXt automatically creates and fills with assets that it generates from your source. You shouldn’t edit anything in this folder. It is not tracked by git by default.
output folder: Another folder created by PreTeXt. It will contain the results of pretext build. In general, you should not touch anything in this folder. Not tracked by git by default.
project.ptx file: This is the project manifest file, which you use to manage the different builds of your project. We will describe how to use this in more detail below.

There are a few other files that you might see in a project, such as requirements.txt and .gitignore. Don’t worry about these for now.

When your project grows, you will likely want to separate your main.ptx source file (inside the source folder) into multiple .ptx files. For example, you might want a single file per chapter, and even a separate file for each section. You can do this by using the <xi:include> tag. For example, if you have a file source/chapter1.ptx that contains the first chapter of your book, you can include it in your main.ptx file like this:

<xi:include href="./chapter1.ptx" />

In the top level tag of the file in which you use <xi:include> (in this case, main.ptx), you must add the following attribute:

xmlns:xi="http://www.w3.org/2001/XInclude"

Then in the chapter1.ptx file, you would start with the standard <?xml version="1.0" encoding="UTF-8"?> followed by the top-level tag <chapter>. There can only be one top level tag in this file. A second chapter would need to be its own file and <xi:include> it separately.

More information can be found in the Modular Source Files

pretextbook.org/doc/guide/html/processing-modular.html

section of the guide.

Section 5.2 Project.ptx

View Source

You will likely want to build your source file into multiple output formats. How do you tell PreTeXt what outputs you want? You keep track of this, and some other information, in your project.ptx file.

The project.ptx file is a project manifest file. It is used to manage the different builds of your project. It is a .ptx file, but it is not part of the content of your document. It is used to tell PreTeXt how to build your document.

For now, take a look at the project.ptx file in this project. You will see that there are multiple targets each with a name, and a specified <format>, <source>, <publication> (file), and <output-dir> (directory). The <source> and <publication> are probably the same for all targets, but they don’t have to be.

For a complete description of this file and its use, see https://pretextbook.org/doc/guide/html/processing-CLI.html#cli-project-manifest.

Chapter 5 Managing Your Project

Section 5.1 File and directory structure

Section 5.2 Project.ptx

Section 5.3 Versions

Section 5.4 Building subsets

Section 5.5 Codespaces, GitHub, and GitHub Pages