Skip to main content

Chapter 5 Conversion to PDF and Print

The stylesheet mathbook-latex.xsl can produce two very similar outputs. Each is a file in syntax, which can be converted to a PDF with a executable (“engine”). However, there are two purposes for such a PDF. The first is a document which is meant to be read on a screen. We call this an electronic PDF. The second is meant to be printed as a physical book, so it would be the file you provide to a copy shop, campus bookstore, or print-on-demand service (see Chapter 13). We call this a print PDF.

As an illustration of the difference, an electronic PDF will contain cross-references that are active, and colored to be obvious to the reader. For the print PDF the same cross-reference will be black and inactive.

The latex.print switch controls the selection of the two output modes of this single stylesheet. The default is no for the electronic version, and yes will change to the print version. In this chapter, we describe both of these two, slightly dissimilar, conversions together.

Text Justification and Alignment

The text.alignment switch will control how text is aligned (such as in paragraphs). The value justify is the default, and raggedright will cause alignment on the left, with an uneven right edge, employing less hypenation.

One-Sided or Two-Sided

An electronic PDF will default to page layout appropriate for a document printed single-sided, which makes the most sense for a document that may not be printed, or which might be printed on a personal printer.

A print PDF will default to page layout appropriate for a document printed two-sided, which makes the most sense for a document that may be sent to a print-on-demand service or printed on a printer that will print on both sides of a sheet of paper.

These defaults may be overridden with the latex.sided switch with values one and two.

One-sided layout will default to symmetric left/right margins, and page headers with the page numbers always placed in the upper-right corner as part of default page headers. There will be no blank pages between chapters of a book.

Two-sided layout will have asymmetric margins with the ratio of inner (adjacent to spine) to outer at 2:3. You need some extra space at the spine to compensate for the binding, but when a book is open, the two pages are separated by two inner margins, so these do not need to be as wide as the outer margin to give some distance between the pages. And readers will want more space to write in the outer margins, perhaps providing simple proofs of important results. (This ratio may be changed with the hmarginratio key of the geometry package.) Page headings will have page numbers on the outside of the page, with odd numbers on the right-side page. Chapters will possibly have a blank page between them, so they begin on a right/odd page. Behavior is similar in the front matter and back matter.

Page Shape

The latex.geometry switch can be used to supply a single string composed of any options to the \geometry{} command of the geometry package, and these will override any defaults supplied by PreTeXt. Resist the temptation to pack in as much text on the page as you can. PreTeXt varies the width of the text in reaction to the font size and is already very close to the maximum number of characters per line for comfortable reading by humans.

An electronic PDF may be printed on physical paper, but perhaps you want to make a version that works well on a portable device that naturally supports a portrait orientation, such as an Android tablet, an iPad, a Kindle (device or application), smart phone, Sony Digital Paper, or a ReMarkable tablet. Aspect ratios vary across these devices, but once you settle on a target ratio, we have had good luck with the following algorithm and parameters:

  1. Specify 10 point text
  2. Text width of about 4.5 inches
  3. Add quarter-inch left/right margins to compute text width
  4. Use aspect ratio to compute an overall height (about 6.5 inches)
  5. Subtract quarter-inch top and bottom margins to obtain text height

Then you can provide the geometry package the overall size as the papersize and the text width and text height as the total size of the body, resulting in equal (tight) margins all around, and good use of limited screen real estate. These parameters create a PDF that is very legible on a larger smart phone, and for fine detail, rotating the device to landscape works well. Really.

Nested Lists

can fail if lists are nested too deeply. Maximums may be up to four nested ordered lists, and up to six overall (mixing in unordered lists). If you hit these limits, ask yourself if your situation is really that complicated, or ask us to consider a feature request adding a technical fix.

Multi-Column List Order

Lists with several columns are rendered in column-major order, as of 2018-02-28. In other words, the first list items (<li>) in your source will populate the first column.

Watermarks

You can add a watermark to your PDF which will render as large, light grey text, at an angle across teh page. Use latex.watermark to set the text (avoid obscure characters or symbols, and do not use any XML markup). Use latex.watermark.scale to adjust for long or short text. The -only “\\” will survive in the text to create multiple lines of text. Submit a feature request if this is not flexible enough to meet a special need.

Cover Images

The docinfo/covers element may be used to specify the filenames (with relative paths) of a front-cover image and a back-cover image via the @front and @back attributes. The image must be a single-page PDF, and it will be scaled to fit an entire page. So it is your responsibility to supply an image which has the correct aspect ratio and sufficient resolution. These are only supported for the conversion.

This is meant to help you create a professional electronic PDF. A print-on-demand service (Chapter 13) will likely want a standalone image (possibly with the front and back, plus a spine, all rolled into one wrap image). So build your real cover images (Chapter 12), and then modify them for this use.

Fill-Ins

The <fillin> element can be rendered as a line near the baseline of the current line of text, or as a complete rectangle (“box”). Set latex.fillin.style to the values underline or box.

Experimentation

Two hooks are provided to allow for arbitrary additions to the preamble. It should go without saying that this is for experimenting with new features and is no way supported, including, but not limited to, interactions with current packages in use, or those added in the future.

Arbitrary text () used as the values of latex.preamble.early and latex.preamble.late will be added to the very beginning, or very end (respectively), of the generated preamble.

Styling

Note that some of these switches are about style. There are many more ways to influence the style of the output, see Chapter 11.

Switch Reference

The following switches can be provided on the command-line, or perhaps more conveniently in a simple XSL file. See Section 3.1 for more detail.

Switch Default Values
latex.print no yes, no
latex.sides Varies one, two
latex.font.size 10pt 8pt to 20pt (8 steps)
latex.geometry Any options to \geometry{}
text.alignment justify raggedright, justify
latex.watermark Simple text, no markup
latex.watermark.scale 2.0 Positive rational number
latex.fillin.style underline underline, box
latex.preamble.early Arbitrary
latex.preamble.late Arbitrary
Table 5.0.1 Options for Conversion
File

The file created by PreTeXt will contain the majority of your content in a form that you could use it in a new standalone document, in accordance with Principle B.0.1:9. However some constructions which are not natural in , 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 environments, allowing styling and fine-tuning to occur in the preamble. This makes the body look more like simple and allows for much greater flexiblity in styling, along with greater reliability for successful compilation.

The existence, variety, and quality of 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 output significantly prior to compilation, as it will inevitably lead to frustration. The 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 (or ) file is desired, a new conversion could be created. Many of the more complicated aspects of any conversion are purposely isolated in the mathbook-common.xsl file so that they can be easily re-purposed and there is consistency across output formats.