build Section

The build section of the configuration file describes how the document is to be built, including options for LaTeX compilation. Four main attributes can be set in this section:

seed

This is just an integer to seed the random number generator. This is useful for ensuring reproducibility when generating documents with randomized content.

copies

This is an integer specifying the number of copies of the document to be generated. This is useful for creating multiple versions of a document with different randomized content. If not specified, this defaults to 1.

serials, serial-digits, serial-range, serial-file, serial-hex, and serial-hex-digits

When copies is greater than 1 (or not specified so that it defaults to 1), pygacity uses serial numbers to differentiate multiple copies of a document when generating randomized content. The following attributes control the generation of serial numbers:

  • serials: A list of integers specifying the serial numbers to be used. If this attribute is provided, it overrides the other three serial-related attributes.

  • serial-range: A list of two integers specifying the inclusive range of serial numbers to be used. For example, [1, 10] would generate serial numbers from 1 to 10.

  • serial-digits: An integer specifying the number of decimal digits in randomly generated serial numbers (default: 8). The serial is drawn uniformly from the range [10^(n-1), 10^n - 1] where n is serial-digits.

  • serial-file: A string specifying the path to a text file containing a list of serial numbers, one per line. If this attribute is provided, it overrides the other serial-generation attributes.

  • serial-hex: A boolean (default: false). When true, the serial number is displayed and used in output filenames as a lowercase hexadecimal string rather than as a decimal integer. The underlying integer is unchanged, so reproducibility of randomized content is fully preserved — only the visual representation differs.

  • serial-hex-digits: An integer specifying the minimum number of hex digits in the serial string when serial-hex is true (default: 8). The value is zero-padded on the left to this width, ensuring all serials have a consistent length. For example, with the default of 8, a serial of 28114514 would appear as 01ad3e52.

If none of these attributes are specified, or if copies is set to 1, no serial numbers will be used.

solutions

This is a boolean value (true or false) indicating whether a companion document that includes full solutions (if you wrote them!). It is true by default.

job-name

This is a string specifying the job name to be used in the LaTeX compilation process. This determines the names of auxiliary files generated during compilation.

paths

Specific names of subdirectories to be used for various build artifacts can be set in this subsection. The following paths can be specified:

  • build-dir: Directory where intermediate build files are stored; defaults to build/.

  • cache-dir: Directory where cached files are stored; defaults to .cache under the build directory.

If any of these attributes are not specified, or the paths subsection is not provided, default values will be used.