Skip to main content
Recipe number 55

Cookbook · Chapter 10 · Output & integration

A galley proof with every fault marked in red

A newspaper galley proofed twice, with every fault the engine reports or the pen finds itself marked in red on the page and linked to its Markdown.

  • Trim 190 × 253 mm
  • Column and a half, 6 mm gutter
  • Charis SIL 10/14
  • Chivo
  • Fragment Mono
  • 2 pages
  • Level
  • Postext 1.57.1
  • Laid out in 8 ms
  • 250 lines of code

In short

A news story from a local weekly, checked twice for mistakes. It shows how to mark every fault in red on the page and link it back to the line of text that caused it.

What you'll build

Issue 41 of The Tideline, a county weekly, leads with the return of the night ferry across the Sawyer, and the pen proofs the story twice. The first pass is the copy as filed, the corrected story with seven slips put back, among them a stamp typed as a directive that does not exist and a fact box that never closes. Those seven slips leave eleven marks. As on the card, each fault is underlined in red on the line where it was set (a loose line is washed instead), and its number in the margin matches its entry in the list beside the pages. Clicking a line or an entry selects its Markdown. The pages below are the second pass. The checks find nothing in it, and a PROOF · 2ND PASS stamp is pinned in the top right corner.

This recipe answers

  • How do I find out what is wrong with my document (warnings, overflow, non-converging layout)?
  • How do I map a click on the rendered page back to the Markdown source, to build an editor?
  • Why is one line set ragged or over-stretched (URLs, long compounds, long words in cells)?

The short answer

script.js · lines 170–203in full code
const MM = DPI / 25.4; // page px per mm
function proof(md, doc) {
  const faults = [];
  const add = (kind, from, to, detail, at) => faults.push({ kind, from, to, detail, at });
  const { blocks, issues } = parseMarkdownWithIssues(md); // a $, $$ or ::: left open
  for (const i of issues) add(i.kind, i.sourceStart, i.sourceEnd);
  for (const w of doc.warnings ?? []) { // calloutOverflow: a box no cut could split
    add(w.kind, w.sourceStart, w.sourceEnd, Math.round(w.overflowPx / MM), w);
  }
  if (!doc.converged) add('unsettled', 0, 1, doc.iterationCount); // the layout never settled
  // The pen's own readings of the source and the lines, in the same list and shape.
  const ids = new Set(resources.map((r) => r.id)); // an unknown id prints '?'
  for (const m of md.matchAll(/:ref\{id="([^"]*)"|^::resource\{id="([^"]*)"/gm)) {
    if (!ids.has(m[1] ?? m[2])) add('unknownResourceId', m.index, m.index + m[0].length);
  }
  for (const m of md.matchAll(/^:::?([a-z][\w-]*)/gim)) { // an unknown fence prints as text
    const known = KNOWN_CONTAINERS.has(m[1]) || KNOWN_DIRECTIVES.has(m[1]) || m[1] === 'resource';
    if (!known) add('unknownDirective', m.index, m.index + m[0].length);
  }
  for (const b of blocks) { // formulas count as faults only because this story has none
    if (b.startNumber > 999) add('yearList', b.sourceStart, b.sourceEnd); // 1971. opens a list
    for (const s of b.spans ?? []) if (s.math) add('formula', s.math.sourceStart, s.math.sourceEnd);
  }
  // The lines as set: spaces past maxWordSpacing, a line set ragged, a hyphen in an address.
  const max = doc.config.bodyText.maxWordSpacing;
  for (const l of doc.pages.flatMap((p) => p.columns.flatMap((c) => c.blocks))
    .flatMap((b) => b.lines ?? [])) {
    const ratio = Math.round(lineWordSpacing(l) * 100) / 100; // as the report prints it
    if (ratio > max) add('looseLine', l.sourceStart, l.sourceEnd, ratio);
    if (l.ragged) add('raggedLine', l.sourceStart, l.sourceEnd); // past 3×: no ratio left
    if (l.hyphenated && /[./]\S+-$/.test(l.text)) add('addressHyphen', l.sourceStart, l.sourceEnd);
  }
  return faults.sort((a, b) => a.from - b.from);
}

The checks: what the parser and the layout report, and what they leave to you

Ingredients

Type
Charis SIL, Chivo, Fragment Mono (SIL OFL 1.1)
Assets
  • crossing-1590.jpg
  • The night crossing at the head of page 1 (Generated With Diffusion Models, original)
  • The route map, drawn in code in the page's palette (Ignacio Ferro, CC BY 4.0)

Method

#1 · Read what the engine reports, then check the rest

The code is the short answer above. parseMarkdownWithIssues() returns an issue for each $, $$ or ::: left open, and doc.warnings holds a calloutOverflow for each box that no cut could split. doc.converged and doc.iterationCount say whether the layout settled, and this story settles after one iteration with or without its faults. The engine also records unknown ids and directives in doc.contentWarnings, and findLooseLines returns the loose lines: the checks the Sandbox's Checks panel shows (Sidebar panels). proof() makes those readings itself, so that every fault lands in one list with one shape: a kind, a source range and a detail. It compares :ref and ::resource ids with the resources of the build, and fence names with KNOWN_CONTAINERS and KNOWN_DIRECTIVES. For this story it also flags a list block whose startNumber is a year and any formula, since the story has none, and it reads the set lines for spaces stretched past maxWordSpacing, lines set ragged and hyphens added inside an address.

#2 · Put the faults back into the corrected copy

script.js · lines 157–166in full code
const FIRST_PASS = [ // [corrected, faulty], replaced wherever it occurs
  [':::callout{type="stamp"}\n:::', t({ en: ':::stamp', es: ':::sello' })], // no such directive
  [':ref{id="route"}', ':ref{id="route-map"}'], // an id no resource has
  ['\\$', '$'], // bare dollars (gotcha: dollar-math)
  [' https://', ' '], // a web address without its scheme
  [':::\n:::\n', ''], // the fact box's two closing fences
  ['\u20601971.', '1971.'], // the word joiner before 1971 (gotcha: digit-period-list)
  [t({ en: 'October 2.\n:::', es: 'octubre.\n:::' }), t({ en: 'October 2.', es: 'octubre.' })],
]; // last: the timeline's closing fence, so its box stays open inside the open fact box
const firstPass = (md) => FIRST_PASS.reduce((out, [fix, fault]) => out.replaceAll(fix, fault), md);

The pen keeps one Markdown file, the corrected story, and makes the first pass from it by undoing seven fixes, so the two versions cannot drift apart and each mark has a known cause. The corrected copy is built last, and the pages below show that build. \$ escapes the dollar sign of a price, so no formula opens. A word joiner (U+2060) before each year in the timeline on page 2 stops an entry such as 1971. The Tern… from opening a list numbered from its year; the first pass takes out only the one before 1971. With the scheme https://, a web address is set as an address, never hyphenated and broken only at its joints, as on page 1 before .example. Without it the address is an ordinary word, and the first pass hyphenates it as night-ferry. The seventh entry takes out the closing fence of the timeline box, and step 3 shows what the layout makes of it.

#3 · Mark each fault where it was set

script.js · lines 207–245in full code
const linesOf = (page) => [...page.columns.flatMap((c) => c.blocks), ...(page.floats ?? [])]
  .flatMap((b) => (b.lines ?? []).map((l) => ({ ...l.bbox, from: l.sourceStart, to: l.sourceEnd,
    width: l.justifiedSpaceRatio // a bbox is the natural width; a justified line fills the block
      ? b.bbox.x + b.bbox.width - l.bbox.x : l.bbox.width })));
const REACH = 80; // characters after a fence where its first line may start
function spotOf(page, f) { // where a fault shows on this page: its first line, in page px
  if (f.at) { // a box that ran off its column: a bar under the column's foot
    const c = page.columns[f.at.columnIndex]?.bbox;
    return f.at.pageIndex === page.index ? { ...c, y: c.y + c.height, height: 1.6 * MM } : null;
  }
  const lines = linesOf(page); // a fence sets no line of its own: then the first line after it
  return lines.find((r) => r.from < f.to && r.to > f.from)
    ?? lines.find((r) => r.from >= f.from && r.from - f.to < REACH);
}
function paintMarks(canvas, page, faults, scale) {
  const ctx = canvas.getContext('2d');
  ctx.setTransform(scale, 0, 0, scale, 0, 0); // page px from here on
  Object.assign(ctx, { font: `${3 * MM}px "${MONO}"`, textAlign: 'center' });
  const taken = []; // the numbers set so far: two on one line sit side by side
  faults.forEach((f, n) => {
    const r = spotOf(page, f);
    if (!r) return;
    const wash = f.kind === 'looseLine'; // a loose line is washed, any other fault underlined
    Object.assign(ctx, { fillStyle: palette.proof, globalAlpha: wash ? 0.2 : 1 });
    ctx.fillRect(r.x, wash ? r.y : r.y + r.height, r.width, wash ? r.height : 0.45 * MM);
    const [left, y] = [r.x + r.width / 2 < page.width / 2, r.y + r.height / 2]; // nearest margin
    const shift = taken.filter((ty) => Math.abs(ty - y) < 4.5 * MM).length * 5.2 * MM;
    const [x, edge] = [left ? 6.5 * MM + shift : page.width - 6.5 * MM - shift,
      left ? r.x : r.x + r.width]; // the number, and a leader from it to the text
    taken.push(y);
    ctx.globalAlpha = 1;
    ctx.fillRect(Math.min(x, edge), y - 0.12 * MM, Math.abs(x - edge), 0.24 * MM);
    ctx.beginPath();
    ctx.arc(x, y, 2.4 * MM, 0, 2 * Math.PI);
    ctx.fill();
    ctx.fillStyle = palette.paper;
    ctx.fillText(String(n + 1), x, y + 1.05 * MM);
  });
}

Every line of the VDT carries sourceStart and sourceEnd, so a fault's source range leads to the line that printed it. A container fence prints no line of its own, and its mark goes on the first line that starts within REACH (80) characters after it. A calloutOverflow gets a bar under the foot of the column it names. One slip can leave several marks. The bare dollars turn $2.50 on foot, $ into a formula, which prints nothing because this pen never loads the maths engine, and the third dollar opens a formula that never closes. Without that phrase, one line of the fares paragraph comes out with spaces 1.9 times their normal width. The fact box's two missing fences leave it and its :::columns group open to the end of the story, and what follows is set inside them, in the group's second column. A columns group is cut between its columns like the box around it, so with those two fences alone nothing overflows. The timeline's fence is the one that does it. Its box, left open inside the fact box, takes in the last five paragraphs and the colophon, and a box inside another box is never cut. It is set on page 3 and runs 69 mm past the foot of the column; what lies below that foot is not printed, and the first pass has three pages instead of two. The warning carries the source range of the fact box, the box the layout placed, so entry 8 selects the outer box, from its fence to the end of the story. proof() calls a line loose when its word spacing, lineWordSpacing(line), is above maxWordSpacing (1.6 here). A line whose spaces would pass 3× has no ratio to compare, because the breaker sets it ragged instead, so proof() checks ragged as well.

#4 · Select the Markdown behind a line

script.js · lines 249–267in full code
function selectSource(from, to) {
  const all = source.value; // measure the wrapped height of the text before the selection
  source.value = all.slice(0, from);
  const top = source.scrollHeight;
  source.value = all;
  source.focus({ preventScroll: true });
  source.setSelectionRange(from, to); // the offsets the parser and the layout give
  source.scrollTop = top > source.clientHeight ? top - source.clientHeight / 3 : 0;
}
function onPageClick(canvas, page) {
  canvas.onclick = ({ clientX, clientY }) => {
    const box = canvas.getBoundingClientRect(); // CSS px to page px
    const [x, y] = [(clientX - box.left) * (page.width / box.width),
      (clientY - box.top) * (page.height / box.height)];
    const hit = linesOf(page).find((r) => x >= r.x && x <= r.x + r.width && y >= r.y
      && y <= r.y + r.height);
    if (hit?.from !== undefined) selectSource(hit.from, hit.to);
  };
}

A click arrives in CSS pixels. onPageClick() scales it to page pixels, finds the line whose bbox contains it and selects that line's source range in the textarea; an entry in the list selects its fault's range the same way. selectSource() focuses the textarea without scrolling the page and sets its scrollTop from the height of the text before the selection. A justified line's bbox keeps the line's natural width, not the width it is painted at, so linesOf() extends it to the right edge of its block. Otherwise the wash would stop short of the margin, and a click near the right edge would select nothing.

#5 · Let the fact box split, pin the stamp

script.js · lines 54–68in full code
const boxes = [
  // keepTogether: false: cut between two blocks at the page foot; a line of white closes it.
  { id: 'facts', keepTogether: false, backgroundEnabled: false, marginBottom: pt(LEAD),
    stripe: { enabled: true, side: 'top', width: pt(2.5), color: col('proof') },
    padding: { ...NONE, top: mm(2.6) }, titleStyle: { ...caps(8), color: col('proof') },
    body: { fontSize: pt(9), lineHeight: pt(LEAD), textAlign: 'left', firstLineIndent: pt(0) },
    lists: { bulletChar: '•', color: col('proof') } },
  // 'fixed': pinned to the page its fence falls on, out of the flow; 'auto': as wide as its title.
  { id: 'stamp', placement: 'fixed', width: 'auto', backgroundEnabled: false,
    title: t({ en: 'Proof · 2nd pass', es: 'Segundas pruebas' }),
    fixed: { anchor: { to: 'page', edge: 'top-right' }, offset: { x: mm(-OUTER), y: mm(8) } },
    border: { enabled: true, color: col('proof'), width: pt(1.2) }, borderRadius: mm(1),
    padding: { top: mm(1.4), right: mm(2.4), bottom: mm(1.2), left: mm(2.4) },
    titleStyle: { ...caps(9), color: col('proof'), gap: mm(0) } },
];

keepTogether: false lets the fact box start at the foot of page 1 and go on overleaf under its red rule, without its title. The box has no background and no rule at its foot, so on page 2 only white space separates the timetable from the story, and marginBottom is a full line of leading, 14 pt; with 4 pt the timetable would end 1.5 mm above the next paragraph. The stamp is placement: 'fixed', out of the flow and pinned 8 mm below the top edge, and width: 'auto' shrinks it to its title, 42 mm wide instead of the main column's 110 mm.

The whole recipe

Sandbox
// ═══ Postext Cookbook · Nº 055 · A galley proof with every fault marked in red ══════
// https://postext.dev/en/cookbook/proof-sheet-diagnostics
// Code: MIT · Text: original (CC BY 4.0) · Map: code (CC BY 4.0) · Photo: diffusion models
// Fonts: Charis SIL, Chivo, Fragment Mono (SIL OFL 1.1) · Needs postext ≥ 1.34.0
import { buildDocumentWithFonts, prepareFonts, renderPageToCanvas, registerResourceImage,
  parseMarkdownWithIssues, KNOWN_DIRECTIVES, KNOWN_CONTAINERS, lineWordSpacing,
} from 'https://esm.sh/postext';

const LANG = 'en'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'proof-sheet-diagnostics';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// col() links a colour to its palette entry; the hex is the value the entry holds.
const palette = { // proof: the one accent and the marks; rule: the map's banks; muted: furniture
  ink: '#1d1d1b', proof: '#d7263d', paper: '#f6f3ea', rule: '#bdb8aa', muted: '#76726a' };
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = [...Object.entries(palette), ['main-color', palette.proof]] // every default
  .map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } })); // on main-color: red
const [TEXT, DISPLAY, MONO] = ['Charis SIL', 'Chivo', 'Fragment Mono'];
const [TRIM_W, TRIM_H, TOP, BOTTOM, INNER, OUTER] = [190, 253, 22, 20, 17, 14]; // mm, mirrored
const MEASURE = TRIM_W - INNER - OUTER; // mm: 159, the text block the opener spans
const [LEAD, ART_H, DPI] = [14, 50, 150]; // pt: leading; mm: the photograph; page px/inch
const NONE = { top: mm(0), right: mm(0), bottom: mm(0), left: mm(0) };
const caps = (size) => ({ fontFamily: MONO, fontSize: pt(size), letterSpacing: pt(size * 0.12),
  textTransform: 'uppercase', fontWeight: 400 });

const below = (id, gap, width = MEASURE) => ({ anchor: { to: id, edge: id === 'container'
  ? 'top-left' : 'below' }, offset: { x: mm(0), y: mm(gap) }, size: { width: mm(width) } });
const text = (id, content, family, size, color, placement, extra) => ({ kind: 'text', id,
  content, fontFamily: family, fontSize: pt(size), color: col(color), align: 'left',
  overflow: 'wrap', placement, ...extra });
const opener = { enabled: true, slot: { elements: [ // the drawing, then the words under it
  { kind: 'image', id: 'art', resourceId: 'crossing', placement: { ...below('container', 0),
    size: { width: mm(MEASURE), height: mm(ART_H) } } },
  // The words start 6 mm under the drawing, and the opener reserves down to the byline.
  text('kicker', '{attr.kicker}', MONO, 8, 'proof', below('container', ART_H + 6), caps(8)),
  text('title', '{titleText}', DISPLAY, 50, 'ink', below('#kicker', 1.4),
    { fontWeight: 900, lineHeight: 0.96 }), // a multiple of the size
  text('standfirst', '{attr.standfirst}', TEXT, 11.5, 'ink', below('#title', 4, 136),
    { italic: true, lineHeight: 1.3 }),
  text('byline', '{attr.byline}', MONO, 7.5, 'muted', below('#standfirst', 3), caps(7.5))] } };
const head = (id, content, parity, edge, x, y = 12) => text(id, content, MONO, 7.5, 'muted',
  { anchor: { to: 'page', edge }, offset: { x: mm(x), y: mm(y) } }, { ...caps(7.5), parity,
    pages: 'body', align: edge.split('-')[1] ?? 'center' }); // y: mm from the trim
const RUNNING = t({ en: ['The Tideline · issue 41', 'News · the night ferry'],
  es: ['La Marea · número 41', 'Noticias · la barcaza nocturna'] });
const header = { elements: [
  head('verso', `{pageNumber}   ${RUNNING[0]}`, 'even', 'top-left', OUTER),

The composed script.js runs as it is: paste it into any page’s module script, or open the recipe on CodePen. Recipe folder on GitHub ↗ (opens in a new tab)

Variations

#Keep the fact box whole

With the default keepTogether, the box moves to page 2 in one piece; page 1 ends 33 mm short and the story runs onto a third page.

-  { id: 'facts', keepTogether: false, backgroundEnabled: false, marginBottom: pt(LEAD),
+  { id: 'facts', backgroundEnabled: false, marginBottom: pt(LEAD),

#Stop a build that still has faults

In a build script or a test, run proof() on the final copy and throw if it finds anything.

 const doc = await build(markdown); // last: the corrected galley, the pages below
+if (proof(markdown, doc).length) throw new Error('The second pass still has faults.');

Pitfalls

Pitfall

A bare $ opens maths: write \$

A dollar sign opens inline maths, so a price such as $40 starts a formula. Write \$40. Escapes and literal characters →

Pitfall

'1998. ' or '- ' at a paragraph start opens a list

A paragraph that starts with a number, a period and a space, or with a hyphen and a space, becomes a list item. Put a word joiner (U+2060) before the number, and write dialogue with an em dash. Escapes and literal characters →

Markdown warning · unclosedMath

Unclosed math delimiter

Why. A $ opens inline maths that is never closed, usually because it belongs to a price.

Fix. Write \$ for a literal dollar, or close the formula on the same line. Docs →

Markdown warning · unclosedContainer

Unclosed container

Why. A ::: fence is never closed, so the container runs to the end of the document.

Fix. Add a line holding a bare ::: where the container ends. Docs →

Layout warning · calloutOverflow

Callout overflows its column

Why. A box that no cut can split (a figure, a table or a box nested inside it taller than the column, or too high splitMinLines) was placed overflowing; the engine records it in doc.warnings and the Sandbox lists it. A span: 'side' box taller than an empty side column is placed overflowing too.

Fix. Shorten the box, let it split with keepTogether: false, lower splitMinLines, or give it another span. Docs →

Sandbox check · unknownResourceId

Unknown resource

Why. A :ref or ::resource names an id no resource has; the reference prints "?" and nothing is placed.

Fix. Correct the id (double quotes only) or add the resource. Docs →

Layout warning · unknownDirective

Unknown directive

Why. A :::name line is not one of Postext's directives or containers, so it prints as text.

Fix. Check the spelling against the supported names (pagebreak, columnbreak, numbering, space, toc, callout, paragraphs, part, columns, paper). Docs →

Sandbox check · looseLine

Loose line

Why. A justified line stretches its spaces beyond the threshold, usually because of a long word, a URL or a narrow measure.

Fix. Turn on hyphenation in the right language, widen the measure, rephrase, or set the passage ragged. Docs →

  • Fit the copy so the fact box fills page 1 to its last line. A box that closes a page moves down to its foot when the columns are balanced (headings.balancing.closingBox, 'first' by default): cut the last sentence of the first paragraph and the box's rule sits 6.4 mm under the fares paragraph instead of 2.4 mm.

Credits

Text
Original prose, CC BY 4.0
Images
  • The night crossing at the head of page 1 · Generated With Diffusion Models · original
  • The route map, drawn in code in the page's palette · Ignacio Ferro · CC BY 4.0
Fonts
Charis SIL (SIL OFL 1.1) · Chivo (SIL OFL 1.1) · Fragment Mono (SIL OFL 1.1)
Sandbox