Skip to main content

Section 5.6 Customizations

There are some aspects of your output that are entirely divorced from the actual content, and are presumably all about how that content is presented. Two good examples are the size of the font used in /PDF/print output, and the granularity of web pages in HTML output (by this we mean, is each web page a whole chapter, a whole section, a whole subsection?). Producing output with varying values of these parameters does absolutely nothing to change your content in any way, and so should not be a part of your writing, nor a concern while you concentrating on your writing.
Therefore, many aspects of how your writing is presented is accomplished by your publisher. Note that this is very different from your role as the author of your project. When your project is mature then you can consult with your publisher about how to best present your project to your audience. An entire part of this guide is devoted to this process (Part IV), but if you are curious, the first part of Chapter 26 can serve as an introduction.
So when you want to adjust something, there are two places to look, and one question sorts them out: would the change alter the actual words or content of your document, or only how that content appears? Configuration that affects the words themselves lives in the <docinfo> element of your source (Section 4.25), since it travels with your writing and your document is not the same document without it. Configuration that affects presentation and production lives in a publication file (Chapter 45), where a publisher—even if that publisher is you, wearing a different hat—can change it without touching your meaning.
Some common wants, sorted:
  • Calling every <activity> a “Laboratory”: the <rename> element, in <docinfo>—it changes words your readers see.
  • A macro used throughout your mathematics: the <macros> element, in <docinfo>—your mathematics does not survive without it.
  • How the text of a cross-reference reads (“Theorem 5.2” versus “5.2”): the <xrefs> element, in docinfo/defaults—that text sits inside sentences you wrote around it.
  • The paper size or font size of the PDF: the publication file—same words, different sheet.
  • Whether each web page is a chapter or a section: the publication file.
  • Whether solutions to exercises are visible or withheld: the publication file—the publisher selects among whole components you provided.
  • How deep the numbering of divisions runs: the publication file—numbers are generated apparatus, not authored words.
This division has a corollary for your workflow. Because <docinfo> items determine words on the page, your prose grows around them and they become woven into your writing: change the document-wide style of cross-reference text late, and every sentence written around an <xref> deserves a re-read. So settle <docinfo> early. Publisher switches are the reverse: they never require revisiting what you wrote, and most can be safely ignored until authoring is complete, then changed with little effort. (A few publication file entries are part of the build machinery you use while authoring—the destination directory for generated files, the address of a WeBWorK server—so those get set early, but even they remain cheap to change.)
PrevTopNext