LaTeX File

Section 30.17 LaTeX File

The LaTeX file created by PreTeXt will contain the majority of your content in a form that you could use it in a new standalone LaTeX document, in accordance with Principle 1.1.1:9. However some constructions which are not natural in LaTeX, such as a <sidebyside>, may be cumbersome to reuse. We continue to improve and refine these situations, though.

Our philosophy is to create and use many new LaTeX environments, allowing styling and fine-tuning to occur in the preamble. This makes the body look more like simple LaTeX and allows for much greater flexiblity in styling, along with greater reliability for successful LaTeX compilation.

The existence, variety, and quality of LaTeX packages changes continuously. We can, and will, swap out some packages for replacements, as needed or desirable. This is to your advantage, as you are absolved of the need to evaluate competing packages, and to insure that they do not clash with each other. So resist the temptation to modify the LaTeX output significantly prior to compilation, as it will inevitably lead to frustration. The LaTeX file is a means to an end—it allows us to create a PDF with excellent typography, and especially for the demands of technical discplines, such as STEM and music. It is meant to ephemeral, not archival.

If some other variety of LaTeX (or TeX) file is desired, a new conversion could be created. Many of the more complicated aspects of any conversion are purposely isolated in the pretext-common.xsl file so that they can be easily re-purposed and there is consistency across output formats.

Best Practice 30.17.1. Only Edit LaTeX Files Rarely.

We want to stress that the LaTeX file created by various conversions is meant to be an intermediate format. In other words, it is ephemeral. We try to make it clean and organized, but it is not the LaTeX a human would write. You might be able to recycle a paragraph or two in other documents you create without PreTeXt. But it is not meant to be stable or archival, and no long-term use is supported in any way. In other words, it is not a supported output format, beyond compiling to a PDF without errors.

Because of that, you may find it necessary to manually adjust a file to control widows or orphans, or maybe the placement of a graphics file, or similar adjustments. Some of the most the common adjustments used by PreTeXt authors are inserting \newpage, \noindent, or \par to avoid awkward transitions, or to remove an occasional \leavevmode; consult a good LaTeX reference before making such changes, as effects later in the output may be unpredictable.

We view this as the final step before making a new edition, which might be a PDF that you submit to a print-on-demand service (Chapter 43). So hand-editing might be an annual exercise, at the most frequent. One way to keep track of larger number of edits over long periods of time is to write a script (in an appropriate language), which looks for unique strings before or after trouble spots and replaces the nearby content. Another minimally invasive option is to keep a separate git branch of the LaTeX file which makes the desired changes, which can then be applied on those rare occasions it is necessary (ideally, with little rebasing needed).