Saltar al contenido principal
Receta número 55

Recetario · Capítulo 10 · Salida e integración

Una galerada con cada fallo marcado en rojo

Una galerada revisada dos veces, con los fallos que detecta el motor y los que encuentra el propio pen marcados en rojo en la página y ligados a su Markdown.

En esta página
  • Formato 190 × 253 mm
  • Columna y media, medianil de 6 mm
  • Charis SIL 10/14
  • Chivo
  • Fragment Mono
  • 2 páginas
  • Nivel
  • Postext 1.57.1
  • Compuesto en 10 ms
  • 250 líneas de código

En pocas palabras

Una noticia de un semanario local, revisada dos veces en busca de errores. Enseña a marcar cada fallo en rojo sobre la página y a enlazarlo con la línea del texto que lo causó.

Lo que vas a componer

El número 41 de La Marea, un semanario comunal, abre con la vuelta de la barcaza nocturna del Quilén, y el pen revisa la noticia dos veces. Las primeras pruebas son el texto tal como llegó a la mesa, la noticia corregida con siete fallos repuestos, entre ellos un sello escrito como una directiva que no existe y un recuadro que nunca se cierra. Esos siete fallos dejan diez marcas. Como en la tarjeta, cada fallo se subraya en rojo en la línea donde se compuso (una línea floja se sombrea entera), y su número en el margen es el de su entrada en la lista junto a las páginas. Al pulsar una línea o una entrada se selecciona su Markdown. Las páginas de abajo son las segundas pruebas. En ellas las comprobaciones no encuentran nada, y el sello SEGUNDAS PRUEBAS queda fijado en la esquina superior derecha.

Esta receta responde a

  • ¿Cómo averiguo qué falla en mi documento (avisos, desbordamientos, composición que no converge)?
  • ¿Cómo relaciono un clic en la página pintada con el Markdown de origen, para construir un editor?
  • ¿Por qué una línea sale en bandera o demasiado estirada (URL, compuestos largos, palabras largas en celdas)?

La respuesta corta

script.js · líneas 170–203en el código completo
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);
}

Ingredientes

También usa
Columna y media
Tipografía
Charis SIL, Chivo, Fragment Mono (SIL OFL 1.1)
Recursos
  • crossing-1590.jpg
  • La travesía nocturna en la cabeza de la página 1 (Generated With Diffusion Models, original)
  • El plano de la ruta, dibujado con código con la paleta de la página (Ignacio Ferro, CC BY 4.0)

Elaboración

#1 · Lee lo que devuelve el motor y comprueba tú el resto

El código es la respuesta corta de arriba. parseMarkdownWithIssues() devuelve una incidencia por cada $, $$ o ::: que queda abierto, y doc.warnings recoge un calloutOverflow por cada recuadro que ningún corte pudo partir. doc.converged y doc.iterationCount dicen si la composición se asentó, y esta noticia se asienta en una iteración, con fallos o sin ellos. El motor anota además los ids y las directivas desconocidos en doc.contentWarnings, y findLooseLines devuelve las líneas flojas: son las comprobaciones que muestra el panel Revisión del Sandbox (en Paneles laterales). proof() hace esas lecturas por su cuenta, para que todos los fallos queden en una sola lista con la misma forma: un tipo, un tramo del Markdown y un detalle. Compara los ids de :ref y ::resource con los resources de la composición, y los nombres de contenedor con KNOWN_CONTAINERS y KNOWN_DIRECTIVES. Para esta noticia marca además los bloques de lista cuyo startNumber es un año y cualquier fórmula, porque la noticia no lleva ninguna, y en las líneas ya compuestas busca espacios que pasan de maxWordSpacing, líneas en bandera y guiones añadidos dentro de una dirección.

#2 · Reintroduce los fallos en la versión corregida

script.js · líneas 157–166en el código completo
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 guarda un solo archivo Markdown, la noticia corregida, y saca de él las primeras pruebas deshaciendo siete correcciones; así las dos versiones no pueden desfasarse y cada marca tiene una causa conocida. La versión corregida se compone al final, y es la que muestran las páginas de abajo. \$ escapa el signo de dólar de un precio para que no abra una fórmula. Un unidor de palabras (U+2060) delante de cada año de la cronología de la página 2 impide que una entrada como 1971. Entra en servicio… abra una lista numerada desde ese año; las primeras pruebas solo quitan el de 1971. Con el esquema https://, la dirección web se compone como tal: nunca la parte por sílabas, solo por sus juntas, tras una barra o antes de un punto. Sin el esquema es una palabra más, y las primeras pruebas la parten como puertoaliso.exam-ple. La séptima entrada quita la línea que cierra la cronología, y el paso 3 cuenta lo que la composición hace con ella.

#3 · Marca cada fallo donde se compuso

script.js · líneas 207–245en el código completo
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ínea del VDT lleva sourceStart y sourceEnd, de modo que el rango de origen de un fallo lleva a la línea que lo imprimió. Los delimitadores de un contenedor no imprimen ninguna línea, y su marca va a la primera línea que empieza en los REACH (80) caracteres siguientes. Un calloutOverflow recibe una barra al pie de la columna que indica. Un solo descuido puede dejar varias marcas. Los dólares sin escapar convierten $1.200 a pie, $ en una fórmula, que no imprime nada porque este pen no carga el motor matemático, y el tercer dólar abre una fórmula que no se cierra; en la edición inglesa, además, el párrafo de las tarifas queda con una línea cuyos espacios miden 1,9 veces su ancho normal. Las dos líneas de cierre que le faltan al recuadro de datos lo dejan abierto, con su grupo :::columns, hasta el final de la noticia, y lo que sigue se compone dentro de ellos, en la segunda columna del grupo. Un grupo de columnas se corta entre sus columnas igual que el recuadro que lo contiene, así que con esas dos líneas de cierre no desborda nada. El desbordamiento viene de la línea de cierre que le falta a la cronología. Su recuadro, abierto dentro del de datos, se queda con los cinco últimos párrafos y el colofón, y un recuadro metido en otro no se corta nunca. Se compone en la página 3 y pasa 64 mm del pie de la columna; lo que queda por debajo de ese pie no se imprime, y las primeras pruebas tienen tres páginas en lugar de dos. El aviso lleva el rango de origen del recuadro de datos, que es el que la composición colocó, de modo que la entrada 7 selecciona el recuadro exterior, desde su línea de apertura hasta el final de la noticia. proof() da una línea por floja cuando su espacio entre palabras, lineWordSpacing(line), supera maxWordSpacing (1,6 aquí). Una línea cuyos espacios pasarían de 3× no tiene proporción que comparar, porque el motor la compone en bandera, y por eso proof() comprueba también ragged.

#4 · Selecciona el Markdown de una línea

script.js · líneas 249–267en el código completo
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 llega en píxeles CSS. onPageClick() lo pasa a píxeles de página, busca la línea en cuyo bbox cae y selecciona en el textarea el rango de origen de esa línea; una entrada de la lista selecciona del mismo modo el rango de su fallo. selectSource() enfoca el textarea sin mover la página y fija su scrollTop con la altura del texto anterior a la selección. El bbox de una línea justificada conserva el ancho natural de la línea, no el ancho al que se pinta, así que linesOf() lo alarga hasta el borde derecho del bloque. Sin eso, el sombreado se quedaría antes del margen y un clic cerca del borde derecho no seleccionaría nada.

#5 · Deja que el recuadro se parta y fija el sello

script.js · líneas 54–68en el código completo
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 permite que el recuadro de datos empiece al pie de la página 1 y siga en la página 2 bajo su filete rojo, sin título. El recuadro no tiene fondo ni filete al pie, y en la página 2 solo el blanco lo separa de la noticia; por eso marginBottom mide una línea entera (14 pt), y con 4 pt el horario quedaría a 1,5 mm del párrafo siguiente. El sello es placement: 'fixed', fuera del flujo y fijado a 8 mm del borde superior, y width: 'auto' lo ajusta a su título, con 42 mm de ancho en lugar de los 110 mm de la columna principal.

La receta 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),

El script.js compuesto funciona tal cual: pégalo como script de módulo en cualquier página o abre la receta en CodePen. Carpeta de la receta en GitHub ↗ (se abre en una nueva pestaña)

Variantes

#Mantén entero el recuadro

Con el keepTogether por defecto, el recuadro pasa entero a la página 2; la página 1 termina 33 mm antes y la noticia ocupa una tercera página.

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

#Detén una composición que aún tiene fallos

En un script de compilación o en un test, pasa proof() por la versión final y lanza un error si encuentra algo.

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

Errores frecuentes

Error frecuente

Un $ suelto abre matemáticas: escribe \$

El signo de dólar abre matemáticas en línea, así que un precio como $40 empieza una fórmula. Escribe \$40. Escapes y caracteres literales →

Error frecuente

«1998. » o «- » al principio de un párrafo abren una lista

Un párrafo que empieza por un número, un punto y un espacio, o por un guion y un espacio, se convierte en un elemento de lista. Pon un unidor de palabras (U+2060) antes del número y escribe los diálogos con raya. Escapes y caracteres literales →

Aviso del Markdown · unclosedMath

Delimitador matemático sin cerrar

Por qué. Un $ abre una fórmula en línea que nunca se cierra; suele ser el de un precio.

Solución. Escribe \$ para un dólar literal, o cierra la fórmula en la misma línea. Documentación →

Aviso del Markdown · unclosedContainer

Contenedor sin cerrar

Por qué. Un bloque ::: nunca se cierra, así que el contenedor llega hasta el final del documento.

Solución. Añade una línea con solo ::: donde termina el contenedor. Documentación →

Aviso de maquetación · calloutOverflow

El recuadro desborda su columna

Por qué. Un recuadro que ningún corte puede partir (una figura, una tabla o un recuadro anidado en él más alto que la columna, o un splitMinLines demasiado alto) se colocó desbordada; el motor lo anota en doc.warnings y el Sandbox lo muestra. Un recuadro con span: 'side' más alto que una columna lateral vacía también se coloca desbordado.

Solución. Acorta el recuadro, deja que se parta con keepTogether: false, baja splitMinLines o dale otro span. Documentación →

Comprobación del Sandbox · unknownResourceId

Recurso desconocido

Por qué. Un :ref o un ::resource usa un id que no corresponde a ningún recurso; la referencia imprime «?» y no se coloca nada.

Solución. Corrige el id (solo con comillas dobles) o añade el recurso. Documentación →

Aviso de maquetación · unknownDirective

Directiva desconocida

Por qué. Una línea :::nombre no es ninguna de las directivas ni de los contenedores de Postext, así que se imprime como texto.

Solución. Compara el nombre con los admitidos (pagebreak, columnbreak, numbering, space, toc, callout, paragraphs, part, columns, paper). Documentación →

Comprobación del Sandbox · looseLine

Línea floja

Por qué. Una línea justificada estira sus espacios por encima del umbral, casi siempre por una palabra larga, una URL o una medida estrecha.

Solución. Activa la separación silábica en el idioma correcto, ensancha la medida, reformula o compón ese pasaje en bandera. Documentación →

  • Ajusta el texto para que el recuadro llene la página 1 hasta su última línea. Un recuadro que cierra una página baja hasta el pie cuando se equilibran las columnas (headings.balancing.closingBox, 'first' por defecto): si quitas la última frase del primer párrafo, el filete del recuadro queda a 6,4 mm del párrafo de las tarifas en lugar de a 2,4 mm.

Créditos

Texto
Texto original, CC BY 4.0
Imágenes
  • La travesía nocturna en la cabeza de la página 1 · Generated With Diffusion Models · original
  • El plano de la ruta, dibujado con código con la paleta de la página · Ignacio Ferro · CC BY 4.0
Fuentes
Charis SIL (SIL OFL 1.1) · Chivo (SIL OFL 1.1) · Fragment Mono (SIL OFL 1.1)
Sandbox