Skip to main content

Section 49.2 Choosing a Home for Configuration

Every new configurable feature must decide where its switch lives: in the <docinfo> element of an author’s source, or in a publication file. This is not a matter of taste, and mistakes are expensive to unwind (a deprecation, a period of honoring both, and churn in every project). Decide by these three principles, applied in order.
  1. The dividing line. <docinfo> affects what actual letters and content appear on a page; the publication file affects how that content appears. Remove something from <docinfo> and the document no longer means the same thing, or no longer builds. Change something in the publication file and the same document is presented differently.
  2. The publisher’s limits. A publication file entry may select among, or suppress, whole units the author provided (which of hint, answer, solution display; a solutions manual), and may control generated apparatus (numbers, running heads). It may never alter, nor render incorrect, words the author wrote—nor words that must agree grammatically with them. If a publisher flipping the switch could manufacture incorrect prose, the switch belongs in <docinfo>.
  3. Defaults follow their attribute. A document-wide default for an attribute that authors write on elements lives where the attribute lives: with the source, in <docinfo>.
The extremes are easy. A macro is <docinfo> at its purest: the mathematics neither builds nor means anything without it. Page geometry is the publication file at its purest: identical letters on a different sheet.
The instructive cases sit near the line.
  • The document-wide style of cross-reference text looks presentational, but is <docinfo>. Authors write prose around the generated text (the word “see” followed by an <xref/>), so a publisher-side change can produce “Section Section 5.4” in a sentence the author proofread. Principle 2 forbids exactly this.
  • Exercise-component visibility changes which letters appear on the page, yet is the publication file: the publisher selects among whole units the author supplied, altering none of them.
  • The depth of division numbering changes visible glyphs, yet is the publication file: numbers are generated apparatus.
  • A document-wide default image width is <docinfo> by principle 3: it is a default for the authored @width attribute, a convenience for a per-image authoring decision.
  • Managed directories illustrate that one concept can straddle the line: the files an author curates (external images, data) are source material—swap the directory and it is a different book—while the destination for generated build products is publisher convenience. The homes now match: @external and @data are declared on docinfo/directories, @generated in the publication file. Judge each piece by its nature, not by keeping a family together.
When a proposed feature resists these tests, that is usually a sign it bundles an authoring concern with a presentation concern, and should be split.
PrevTopNext