Debugging typography

When spacing looks wrong, the first step is to make the invisible boxes visible. glu renders every element into nested boxes (the CSS box model above, lines as horizontal boxes below), and the --trace flag draws them into the PDF. The full reference of the flag and its frontmatter and Lua equivalents is in Using glu; this page shows what to look for.

boxmodel: margins, borders, padding, content

glu --trace boxmodel document.md

The overlay uses the browser developer tools palette: content areas are blue, padding green, borders yellow, margins orange, each drawn as a translucent layer. Two reading aids:

• Where the margins of neighbouring elements collapse, their translucent layers overlap and the strip appears darker; a doubled strip is normal, it shows the two margins sharing one gap.
• Nested containers (a list inside a blockquote) stack their layers, so indentation steps show as deepening blue.

hboxes: line geometry

glu --trace hboxes document.md

Every line box is tinted turquoise above the baseline and pink below it, with the baseline drawn as a rule. This is the tool for leading questions: under the default half-leading model the tinted boxes touch (the leading lives inside them), under -bag-leading-model: trailing they shrink to the natural line size and white gaps open between them.

hyperlinks and dests: interaction areas

glu --trace hyperlinks,dests document.md

hyperlinks frames every clickable area, dests marks every PDF destination (the target of internal links and bookmarks) with a small circle and its name. Useful when a link is present but its active area sits beside the visible text.

Reading the log

The log file (document.log, next to the PDF) carries warnings that correspond directly to visible defects:

WARN Font has no glyph for character, shown as .notdef char=쎾 codepoint=U+C3BE font=CrimsonPro-Regular
WARN Unknown trace switch value=boxes known="boxmodel, dests, hboxes, hyperlinks"

A blank where a character should be means the font stack does not cover it (see Choosing fonts); the warning names the exact codepoint and font. glu doctor checks the environment when a document renders differently on another machine.

Method: isolate, then compare

Typography problems are best debugged like code: reduce the document to the smallest fragment that still shows the effect, then render it twice with exactly one property flipped.

glu --trace hboxes -o a.pdf sample.html
glu --trace hboxes -o b.pdf --css flip.css sample.html

where flip.css contains the one candidate change (a different -bag-leading-model, a different line-height, a size-adjust). The traced pair usually answers the question at a glance; the screenshots in this chapter were produced exactly this way.