Saltar al contingut principal
Recepta número 55

Receptari · Capítol 10 · Sortida i integració

Una galerada amb cada error marcat en vermell

Una galerada revisada dues vegades, amb els errors que detecta el motor i els que troba el pen marcats en vermell a la pàgina i lligats al seu Markdown.

En aquesta pàgina
Nivell
Avançat
Postext
Provada amb Postext 1.65.0
Requereix ≥ 1.34.0
Llicència
Actualitzada el 16 d’oct. del 2026
Codi MIT · Text CC BY 4.0
  • Mostra en castellà: encara no hi ha edició en català
  • Format 190 × 253 mm
  • Columna i mitja, espai entre columnes de 6 mm
  • Charis SIL 10/14
  • Chivo
  • Fragment Mono
  • 2 pàgines
  • Nivell
  • Postext 1.57.1
  • Compost en 10 ms
  • 250 línies de codi

En poques paraules

Una notícia d'un setmanari local, revisada dues vegades a la recerca d'errors. Mostra com marcar cada error en vermell sobre la pàgina i enllaçar-lo amb la línia del text que l'ha causat.

Què compondràs

El número 41 de La Marea, un setmanari comunal, obre amb la tornada de la barcassa nocturna del Quilén, i el pen revisa la notícia dues vegades. Les primeres proves són el text tal com va arribar a la taula, la notícia corregida amb set errors reposats, entre els quals un segell escrit com una directiva que no existeix i un requadre que no es tanca mai. Aquests set errors deixen deu marques. Com a la targeta, cada error se subratlla en vermell a la línia on s'ha compost (una línia fluixa s'ombreja sencera), i el seu número al marge és el de la seva entrada a la llista al costat de les pàgines. En prémer una línia o una entrada se selecciona el seu Markdown. Les pàgines de sota són les segones proves. En aquestes les revisions no troben res, i el segell SEGUNDAS PRUEBAS queda fixat a la cantonada superior dreta.

Aquesta recepta respon a

  • Com esbrino què falla en el meu document (avisos, desbordaments, composició que no convergeix)?
  • Com relaciono un clic a la pàgina pintada amb el Markdown d'origen, per construir un editor?
  • Per què una línia surt en bandera o massa estirada (URL, compostos llargs, paraules llargues en cel·les)?

La resposta curta

script.js · línies 170–203al codi complet
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);
}

Ingredients

També fa servir
Columna i mitja
Tipografia
Charis SIL, Chivo, Fragment Mono (SIL OFL 1.1)
Recursos
  • 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)

Elaboració

#1 · Llegeix el que retorna el motor i comprova tu la resta

El codi és la resposta curta de més amunt. parseMarkdownWithIssues() retorna una incidència per cada $, $$ o ::: que queda obert, i doc.warnings recull un calloutOverflow per cada requadre que cap tall no ha pogut partir. doc.converged i doc.iterationCount diuen si la composició s'ha assentat, i aquesta notícia s'assenta en una iteració, amb errors o sense. El motor anota a més els ids i les directives desconeguts a doc.contentWarnings, i findLooseLines retorna les línies fluixes: són les revisions que mostra el tauler Revisió del Sandbox (a Taulers laterals). proof() fa aquestes lectures pel seu compte, perquè tots els errors quedin en una sola llista amb la mateixa forma: un tipus, un tram del Markdown i un detall. Compara els ids de :ref i ::resource amb els resources de la composició, i els noms dels contenidors amb KNOWN_CONTAINERS i KNOWN_DIRECTIVES. Per a aquesta notícia marca a més els blocs de llista amb un any com a startNumber i qualsevol fórmula, perquè la notícia no en porta cap, i a les línies ja compostes busca espais que passen de maxWordSpacing, línies en bandera i guionets afegits dins d'una adreça.

#2 · Torna a introduir els errors a la versió corregida

script.js · línies 157–166al codi complet
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);

El pen desa un sol fitxer Markdown, la notícia corregida, i en treu les primeres proves desfent set correccions; així les dues versions no es poden desfasar i cada marca té una causa coneguda. La versió corregida es compon al final, i és la que mostren les pàgines de sota. \$ escapa el signe de dòlar d'un preu perquè no obri una fórmula. Un unidor de paraules (U+2060) davant de cada any de la cronologia de la pàgina 2 impedeix que una entrada com 1971. Entra en servicio… obri una llista numerada des d'aquest any; les primeres proves només treuen el de 1971. Amb l'esquema https://, l'adreça web es compon com a tal: no la parteix mai per síl·labes, només per les seves juntures, després d'una barra o abans d'un punt. Sense l'esquema és una paraula més, i les primeres proves la parteixen com puertoaliso.exam-ple. La setena entrada treu la línia de tancament de la cronologia, i el pas 3 explica què en fa la composició.

#3 · Marca cada error on s'ha compost

script.js · línies 207–245al codi complet
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);
  });
}

Cada línia del VDT porta sourceStart i sourceEnd, de manera que el rang d'origen d'un error porta a la línia que l'ha imprès. La línia d'obertura o de tancament d'un contenidor no imprimeix res, i la seva marca va a la primera línia que comença en els REACH (80) caràcters següents. Un calloutOverflow rep una barra al peu de la columna que indica. Un sol descuit pot deixar diverses marques. Els dòlars sense escapar converteixen $1.200 a pie, $ en una fórmula, que no imprimeix res perquè aquest pen no carrega el motor matemàtic, i el tercer dòlar obre una fórmula que no es tanca; a l'edició anglesa, a més, el paràgraf de les tarifes queda amb una línia amb espais d'1,9 vegades l'amplada normal. Les dues línies de tancament que li falten al requadre de dades el deixen obert, amb el seu grup :::columns, fins al final de la notícia, i el que segueix es compon a dins, a la segona columna del grup. Un grup de columnes es talla entre les seves columnes igual que el requadre que el conté, així que, si només faltessin aquestes dues línies, no desbordaria res. El desbordament ve de la línia de tancament que falta a la cronologia. El seu requadre, obert dins del de dades, es queda amb els cinc últims paràgrafs i el colofó, i un requadre ficat dins d'un altre no es talla mai. Es compon a la pàgina 3 i passa 64 mm del peu de la columna; el que queda per sota d'aquest peu no s'imprimeix, i les primeres proves tenen tres pàgines en lloc de dues. L'avís porta el rang d'origen del requadre de dades, que és el que la composició ha col·locat, de manera que l'entrada 7 selecciona el requadre exterior, des de la seva tanca fins al final de la notícia. proof() marca una línia com a fluixa quan el seu espai entre paraules, lineWordSpacing(line), supera maxWordSpacing (1,6 aquí). Una línia amb espais que passarien de 3× no té cap proporció amb què comparar, perquè el motor la compon en bandera, i per això proof() comprova també ragged.

#4 · Selecciona el Markdown d'una línia

script.js · línies 249–267al codi complet
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);
  };
}

Un clic arriba en píxels CSS. onPageClick() el passa a píxels de pàgina, busca la línia amb el bbox on cau i selecciona al textarea el rang d'origen d'aquesta línia; una entrada de la llista selecciona de la mateixa manera el rang del seu error. selectSource() enfoca el textarea sense moure la pàgina i fixa el seu scrollTop amb l'alçada del text anterior a la selecció. El bbox d'una línia justificada conserva l'amplada natural de la línia, no l'amplada a què es pinta, així que linesOf() l'allarga fins a la vora dreta del bloc. Sense això, l'ombrejat es quedaria abans del marge i un clic a prop de la vora dreta no seleccionaria res.

#5 · Deixa que el requadre es parteixi i fixa el segell

script.js · línies 54–68al codi complet
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 permet que el requadre de dades comenci al peu de la pàgina 1 i continuï a la pàgina 2 sota el seu filet vermell, sense títol. El requadre no té fons ni filet al peu, i a la pàgina 2 només el blanc el separa de la notícia; per això marginBottom mesura una línia sencera (14 pt), i amb 4 pt l'horari quedaria a 1,5 mm del paràgraf següent. El segell és placement: 'fixed', fora del flux i fixat a 8 mm de la vora superior, i width: 'auto' l'ajusta al seu títol, amb 42 mm d'amplada en lloc dels 110 mm de la columna principal.

La recepta completa

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 = 'es'; // @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),

L'script.js compost funciona tal com és: enganxa'l com a script de mòdul en qualsevol pàgina o obre la recepta a CodePen. Carpeta de la recepta a GitHub ↗ (s'obre en una pestanya nova)

Variants

#Mantén sencer el requadre

Amb el keepTogether per defecte, el requadre passa sencer a la pàgina 2; la pàgina 1 acaba 33 mm abans i la notícia ocupa una tercera pàgina.

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

#Atura una composició que encara té errors

En un script de compilació o en un test, passa proof() per la versió final i llança un error si troba alguna cosa.

 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.');

Errors freqüents

Error freqüent

Un $ sol obre matemàtiques: escriu \$

El signe de dòlar obre matemàtiques en línia, de manera que un preu com $40 comença una fórmula. Escriu \$40. Escapaments i caràcters literals →

Error freqüent

«1998. » o «- » al començament d'un paràgraf obren una llista

Un paràgraf que comença per un número, un punt i un espai, o per un guionet i un espai, es converteix en un element de llista. Posa un unidor de paraules (U+2060) davant del número i escriu els diàlegs amb guió llarg. Escapaments i caràcters literals →

Avís del Markdown · unclosedMath

Delimitador matemàtic sense tancar

Per què. Un $ obre una fórmula en línia que no es tanca mai; sol ser el d'un preu.

Solució. Escriu \$ per a un dòlar literal, o tanca la fórmula a la mateixa línia. Documentació →

Avís del Markdown · unclosedContainer

Contenidor sense tancar

Per què. Un contenidor ::: no es tanca mai, de manera que arriba fins al final del document.

Solució. Afegeix una línia només amb ::: on acaba el contenidor. Documentació →

Avís de maquetació · calloutOverflow

El requadre desborda la seva columna

Per què. Un requadre que cap tall no pot partir (perquè conté una figura, una taula o un requadre niat més alts que la columna, o un splitMinLines massa alt) s'ha col·locat desbordat; el motor ho anota a doc.warnings i el Sandbox ho mostra. Un requadre amb span: 'side' més alt que una columna lateral buida també es col·loca desbordat.

Solució. Escurça el requadre, deixa que es parteixi amb keepTogether: false, abaixa splitMinLines o dona-li un altre span. Documentació →

Comprovació del Sandbox · unknownResourceId

Recurs desconegut

Per què. Un :ref o un ::resource fa servir un id que no té cap recurs; la referència imprimeix «?» i no es col·loca res.

Solució. Corregeix l'id (només amb cometes dobles) o afegeix el recurs. Documentació →

Avís de maquetació · unknownDirective

Directiva desconeguda

Per què. Una línia :::nom no és cap de les directives ni dels contenidors de Postext, de manera que s'imprimeix com a text.

Solució. Compara el nom amb els admesos (pagebreak, columnbreak, numbering, space, toc, callout, paragraphs, part, columns, paper). Documentació →

Comprovació del Sandbox · looseLine

Línia fluixa

Per què. Una línia justificada estira els espais per sobre del llindar, gairebé sempre per una paraula llarga, un URL o una mesura estreta.

Solució. Activa la partició de mots en la llengua correcta, eixampla la mesura, reformula o compon aquest passatge en bandera. Documentació →

  • Ajusta el text perquè el requadre ompli la pàgina 1 fins a la seva última línia. Un requadre que tanca una pàgina baixa fins al peu quan s'equilibren les columnes (headings.balancing.closingBox, 'first' per defecte): si treus l'última frase del primer paràgraf, el filet del requadre queda a 6,4 mm del paràgraf de les tarifes en lloc de quedar a 2,4 mm.

Crèdits

Text
Text original, CC BY 4.0
Imatges
  • 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