Vai al contenuto principale
Ricetta numero 186

Ricettario · Capitolo 2 · Caratteri e testo

Citazioni e statistiche lontane dai margini della riga

Un articolo a due colonne composto due volte: la prima bozza segnala ogni richiamo o segno al margine della riga, la seconda penalizza quelle interruzioni.

p. 211 · 1 di 6

  • Esempio in inglese: non c’è ancora un’edizione italiana
  • Formato 170 × 240 mm
  • 2 colonne, Intercolonna di 6 mm
  • STIX Two Text 9,5/12,8
  • IBM Plex Sans
  • IBM Plex Sans Condensed
  • 6 pagine
  • Livello
  • Postext 1.79.0
  • Impaginato in 153 ms
  • 180 righe di codice

In breve

In una colonna giustificata stretta un richiamo come [2, 3] può aprire da solo una riga, e p < 0,05 può spezzarsi dopo il segno. L’articolo è composto due volte: una mostra dove succede, l’altra spezza le righe perché non succeda quasi più.

Che cosa comporrai

Tre pagine di una rivista di pediatria di 170 × 240 mm, su due colonne giustificate di 66 mm in STIX Two Text: uno studio originale sull’ecografia polmonare nella polmonite del bambino, con una bibliografia numerata in stile Vancouver. Una colonna così stretta lascia poche scelte all’algoritmo che divide le righe, e in tre punti il testo inglese si spezza male. Un richiamo, [2, 3], apre da solo una riga, lontano dalla parola a cui si riferisce, e due volte il rapporto di verosimiglianza LR− = 0.09 si spezza dopo il segno di uguale. La prima bozza è composta con citationBreaks e operatorBreaks a 'warn'. Non cambia nessuna interruzione, marca ciascuna con una banda ambra pallido e le elenca su un cartellino dopo la bibliografia. La seconda è composta con 'avoid', e delle tre ne resta una. L’edizione spagnola compone lo stesso studio con la virgola decimale.

Questa ricetta risponde a

  • Come evito che un numero di citazione o una statistica come p < 0,05 vengano spezzati a fine riga?
  • Come compongo i numeri delle citazioni come apici e rendo i DOI link attivi, come fanno le riviste mediche?

La risposta breve

script.js · righe 27–42nel codice completo
const bodyText = {
  fontFamily: SERIF, fontSize: pt(9.5), lineHeight: pt(LEAD), color: col('ink'),
  boldColor: col('ink'), italicColor: col('ink'), referenceColor: col('ink'),
  referenceBold: false, textAlign: 'justify', firstLineIndent: mm(3.5),
  indentAfterHeading: false, hyphenation: { enabled: true },
  optimalLineBreaking: true, // the rules price breaks in the Knuth–Plass breaker
  avoidWidows: true, avoidOrphans: true, avoidRunts: true,
  // A line that opens on a citation, "[8, 9]" (citationBreak), or ends or opens on a sign
  // set between spaces, "p <" / "0.05" (operatorBreak). 'warn' reports each one and changes
  // nothing; 'avoid' adds the penalty to the demerits of those breaks and reports the ones
  // it keeps. The first proof sets 'warn' (see proofs).
  citationBreaks: 'avoid', operatorBreaks: 'avoid',
  // 10000 by default, what a line spaced to the limit costs. A 66 mm column offers few other
  // breaks; at 30000 the breaker takes looser lines, never past maxWordSpacing.
  citationBreakPenalty: 30000, operatorBreakPenalty: 30000,
};

Ingredienti

Tipo
STIX Two Text, IBM Plex Sans, IBM Plex Sans Condensed (SIL OFL 1.1)
Risorse
Nessuna: ogni immagine è disegnata nel codice

Preparazione

#1 · Un prezzo per due tipi di interruzione

Il codice è la risposta breve qui sopra. C’è un’interruzione di citazione quando una riga comincia con un richiamo numerato, o con la seconda metà di un richiamo, come 5] dopo [4,. C’è un’interruzione di operatore quando una riga finisce o comincia con un segno tra due spazi: =, <, ±, ×, il meno. 'warn' segnala entrambe e lascia le righe come sono. 'avoid' aggiunge una penalità ai demeriti di quelle interruzioni, e l’algoritmo di Knuth–Plass cerca un altro modo di spezzare il paragrafo. Serve optimalLineBreaking: la divisione riga per riga non ha demeriti a cui aggiungere qualcosa.

La penalità predefinita, 10000, è il costo di una riga allargata fino al limite dello spazio tra le parole, quindi l’algoritmo non apre mai una riga oltre quel limite per tenere un richiamo accanto alla sua parola. In questa colonna 10000 lasciava due interruzioni in ogni edizione. Con 30000 l’algoritmo accetta righe più larghe, sempre entro maxWordSpacing, e in ogni edizione ne resta una. Un valore più alto non cambiava più nulla: l’ultima interruzione non ha alternative entro il limite.

#2 · Marcare le interruzioni nel testo

script.js · righe 254–279nel codice completo
// The word before the citation and the citation, or the sign and the number on its other
// side, wrapped in :mark[…]: a band under ordinary text, so the breaks stay where they were.
const wordEnd = (s, i) => i + s.slice(i).search(/[\s;)]|[,.](?!\d)|$/); // 0.09, not 0
function sides(source, w, a, b) { // a warning names line a, before the break, by its source
  if (w.kind === 'citationBreak') { // "colleagues [@simel1991]"
    const cite = source.lastIndexOf('[@', b.sourceStart + 2);
    return [source.lastIndexOf(' ', cite - 2) + 1, source.indexOf(']', cite) + 1];
  }
  if (w.edge === 'end') { // "LR− = 0.09": the sign ends line a, the number opens line b
    const from = source.lastIndexOf(` ${w.text} `, a.sourceEnd) + 1;
    return [from, wordEnd(source, from + w.text.length + 1)];
  }
  const sign = source.indexOf(` ${w.text} `, b.sourceStart - 1); // the sign opens line b
  return [source.lastIndexOf(' ', sign - 1) + 1, sign + 1 + w.text.length];
}
function markBreaks(source, doc, found) {
  const pairs = doc.blocks.flatMap((b) => b.lines.map((line, i) => [line, b.lines[i + 1]]));
  const spans = new Map();
  for (const w of found) {
    const [a, b] = pairs.find(([line]) => line.sourceStart === w.sourceStart) ?? [];
    const [from, to] = b ? sides(source, w, a, b) : [];
    if (from > a?.sourceStart && to > from && to <= b.sourceEnd) spans.set(from, to);
  }
  return [...spans].sort(([x], [y]) => y - x).reduce((md, [from, to]) => `${md.slice(0, from)}`
    + `:mark[${md.slice(from, to)}]{style="edge"}${md.slice(to)}`, source);
}

Ogni avviso riporta il suo tipo, il richiamo o il segno, il testo delle due righe, la posizione della prima nel sorgente e la pagina. Lo script trova quelle due righe nel documento composto e avvolge l’interruzione in :mark[…]: la parola prima del richiamo e il richiamo, oppure il segno e il numero dall’altra parte. Una marcatura dipinge una banda sotto il testo e lascia le interruzioni dov’erano. La banda non arriva al numero generato dallo stile delle citazioni, quindi sulla pagina è marcata solo la parola che lo precede.

Prima bozza, pagina 211: LR− = 0.09 spezzato nell’abstract, e first a fine riga con [2, 3] all’inizio della riga seguente.

#3 · Due bozze e un cartellino di quesiti

script.js · righe 283–303nel codice completo
const KIND = { citationBreak: t({ en: 'citation', es: 'cita' }),
  operatorBreak: t({ en: 'sign', es: 'signo' }) };
const edge = (s, end) => (end ? s.trim().split(/\s+/).slice(-2) : s.trim().split(/\s+/)
  .slice(0, 2)).join('\u00a0').replace(/[.,;]$/, ''); // no-break spaces: no breaks of its own
const query = (doc, w) => `${t({ en: 'p.', es: 'pág.' })}\u00a0${doc.pages[w.pageIndex]
  .pageLabel}, ${KIND[w.kind]}: …${edge(w.lines[0], true)}\u00a0/ ${edge(w.lines[1])}…`;
const slip = (mode, doc, found) => ['', `:::callout{type="slip" title="${mode === 'warn'
  ? t({ en: 'First proof: queries', es: 'Primeras pruebas: consultas' })
  : t({ en: 'Second proof: queries', es: 'Segundas pruebas: consultas' })}"}`,
`citationBreaks / operatorBreaks: '${mode}' · ${found.length} ${found.length === 1
  ? t({ en: 'break', es: 'corte' }) : t({ en: 'breaks', es: 'cortes' })}.`,
...found.flatMap((w) => ['', query(doc, w)]), ':::', ''].join('\n');
const build = (md, mode) => buildDocumentWithFonts({ markdown: md }, { ...config,
  bodyText: { ...bodyText, citationBreaks: mode, operatorBreaks: mode } }, kitFonts(FONTS));
async function proof(mode) {
  const plain = await build(markdown, mode); // pass 1: where the breaks are
  const found = (plain.contentWarnings ?? []).filter((w) => /^(citation|operator)Break$/
    .test(w.kind));
  return build(markBreaks(markdown, plain, found) + slip(mode, plain, found), mode); // pass 2
}
const docs = { warn: await proof('warn'), avoid: await proof('avoid') };

Ogni bozza è composta due volte. La prima composizione trova le interruzioni; la seconda compone l’articolo con le marcature e un cartellino dopo la bibliografia, che cade quindi sull’ultima pagina. È così che un compositore restituisce le bozze con i suoi quesiti. Le righe del cartellino uniscono le parole con spazi indivisibili, così non aggiungono interruzioni proprie. capture.doc pubblica le due composizioni marcate, [1, 3].

Seconda bozza, pagina 213: il cartellino elenca un’interruzione rimasta nell’articolo.

L’interruzione che resta in inglese è first sopra [2, 3], a pagina 211. In spagnolo la prima bozza ne trova quattro, tra cui CP+ sopra = 19,19 e [4, sopra 5], dove si spezza il richiamo stesso, e la seconda ne tiene una, anteriores [4, sopra 5].

#4 · Richiami numerati tra parentesi quadre

script.js · righe 46–50nel codice completo
registerCitationEngine(createCiteprocEngine({ styles: STYLES, locales: LOCALES }));
const citations = { style: 'elsevier-vancouver', locale: t({ en: 'en-GB', es: 'es-ES' }),
  marker: 'brackets', collapseRanges: true, // [8, 9] and [4–6], set after a word space
  bibliography: { fontSize: em(0.8), lineHeight: pt(9.6), entrySpacing: pt(1),
    labelWidth: mm(6), labelAlign: 'right', doi: 'hide' } };

Il processore delle citazioni compone ogni [@key] come un numero tra parentesi quadre dopo uno spazio e raggruppa le serie come [4–6]. Lo spazio prima della parentesi e quello dopo una virgola al suo interno sono entrambi punti in cui una riga può spezzarsi: per questo una colonna stretta con molte citazioni ha bisogno della regola.

#5 · La testata e il blocco dell’articolo

script.js · righe 54–78nel codice completo
const text = (id, content, family, size, extra) => ({ kind: 'text', id, content, align: 'left',
  fontFamily: family, fontSize: pt(size), color: col('ink'), overflow: 'wrap', ...extra });
const at = (to, edge, x, y, width) => ({ anchor: { to, edge }, offset: { x: mm(x), y: mm(y) },
  ...(width && { size: { width: mm(width), height: 'auto' } }) });
const caps = { fontFamily: COND, fontWeight: 600, letterSpacing: pt(1.2),
  textTransform: 'uppercase' };
const JOURNAL = t({ en: 'Ribera Paediatric Journal', es: 'Revista Pediátrica de la Ribera' });
const white = { ...caps, color: col('paper') };
const titleBlock = { enabled: true, minHeight: mm(58), slot: { elements: [
  { kind: 'box', id: 'band', style: { backgroundColor: col('accent') }, placement: {
    anchor: { to: 'page', edge: 'top-left' }, size: { width: 'fill', height: mm(13) } } },
  text('journal', JOURNAL, COND, 9, { ...white, placement: at('page', 'top-left', INNER, 5) }),
  text('issue', '{attr.issue}', COND, 9, { ...white, align: 'right',
    placement: at('page', 'top-right', -OUTER, 5, 60) }),
  text('kind', '{attr.kind}', COND, 8.5, { ...caps, color: col('accent'),
    placement: at('container', 'top-left', 0, 0, MEASURE) }),
  text('title', '{titleText}', SANS, 16, { fontWeight: 600, lineHeight: 1.18,
    placement: at('#kind', 'below', 0, 2.5, MEASURE - 6) }),
  text('authors', '{attr.authors}', SERIF, 10, { inlineMarks: true, // ^1^ → ¹
    placement: at('#title', 'below', 0, 3.5, MEASURE) }),
  text('affiliations', '{attr.affiliations}', SANS, 7.2, { inlineMarks: true, lineHeight: 1.35,
    color: col('muted'), placement: at('#authors', 'below', 0, 1.6, MEASURE) }),
  text('note', '{attr.note}', SANS, 7.2, { color: col('muted'),
    placement: at('#affiliations', 'below', 0, 2.4, MEASURE) }),
] } };

Lo stile del titolo disegna la fascia della rivista, il tipo di articolo, il titolo, gli autori con i numeri di affiliazione e una nota, tutto a partire da attributi dell’H1. Le due edizioni condividono lo stile, e il testo resta nel Markdown.

La ricetta completa

Sandbox
// ═══ Postext Cookbook · Nº 186 · Citations and statistics off the line edges ═══════════
// https://postext.dev/en/cookbook/clinical-paper-line-edges
// Code: MIT · Text: original (CC BY 4.0) · Pictures: none
// Fonts: STIX Two Text, IBM Plex Sans and Sans Condensed (SIL OFL 1.1) · Needs postext ≥ 1.79.0
import {
  buildDocumentWithFonts, renderPageToCanvas, registerCitationEngine,
} from 'https://esm.sh/postext';
import { createCiteprocEngine, STYLES, LOCALES } from 'https://esm.sh/postext-citeproc';

const LANG = 'en'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'clinical-paper-line-edges';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: an indigo journal, a pale amber band for the proof marks
const palette = { ink: '#1b1e26', accent: '#2c4a7c', tint: '#e9eef6', mark: '#f7dfa9',
  muted: '#596173', paper: '#ffffff' };
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = Object.entries({ ...palette, 'main-color': palette.accent })
  .map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
// #endregion
const [SERIF, SANS, COND] = ['STIX Two Text', 'IBM Plex Sans', 'IBM Plex Sans Condensed'];
const [TRIM_W, TRIM_H, TOP, BOTTOM, INNER, OUTER, GUTTER] = [170, 240, 20, 22, 17, 15, 6];
const MEASURE = TRIM_W - INNER - OUTER; // 138 mm: two columns of 66 mm, about 45 characters
const LEAD = 12.8; // pt, for 9.5 pt type

// #region answer: no line opens on a citation, no line ends or opens on a lone sign
const bodyText = {
  fontFamily: SERIF, fontSize: pt(9.5), lineHeight: pt(LEAD), color: col('ink'),
  boldColor: col('ink'), italicColor: col('ink'), referenceColor: col('ink'),
  referenceBold: false, textAlign: 'justify', firstLineIndent: mm(3.5),
  indentAfterHeading: false, hyphenation: { enabled: true },
  optimalLineBreaking: true, // the rules price breaks in the Knuth–Plass breaker
  avoidWidows: true, avoidOrphans: true, avoidRunts: true,
  // A line that opens on a citation, "[8, 9]" (citationBreak), or ends or opens on a sign
  // set between spaces, "p <" / "0.05" (operatorBreak). 'warn' reports each one and changes
  // nothing; 'avoid' adds the penalty to the demerits of those breaks and reports the ones
  // it keeps. The first proof sets 'warn' (see proofs).
  citationBreaks: 'avoid', operatorBreaks: 'avoid',
  // 10000 by default, what a line spaced to the limit costs. A 66 mm column offers few other
  // breaks; at 30000 the breaker takes looser lines, never past maxWordSpacing.
  citationBreakPenalty: 30000, operatorBreakPenalty: 30000,
};
// #endregion

// #region citations: numbered references in brackets, the list in the Vancouver order
registerCitationEngine(createCiteprocEngine({ styles: STYLES, locales: LOCALES }));
const citations = { style: 'elsevier-vancouver', locale: t({ en: 'en-GB', es: 'es-ES' }),
  marker: 'brackets', collapseRanges: true, // [8, 9] and [4–6], set after a word space

Lo script.js composto funziona così com’è: incollalo nello script modulo di qualsiasi pagina, oppure apri la ricetta su CodePen. Cartella della ricetta su GitHub ↗ (si apre in una nuova scheda)

Varianti

#Segnala le interruzioni senza cambiare nulla

Una rivista che controlla le bozze a mano può lasciare la regola a 'warn': la Sandbox elenca ogni interruzione tra i suoi avvisi, e le righe restano come le ha spezzate l’algoritmo.

-  citationBreaks: 'avoid', operatorBreaks: 'avoid',
+  citationBreaks: 'warn', operatorBreaks: 'warn',

#Tieni la penalità predefinita

Con 10000 la spaziatura resta un po’ più stretta e in ogni edizione restano due interruzioni invece di una.

-  citationBreakPenalty: 30000, operatorBreakPenalty: 30000,

Errori frequenti

Avviso di impaginazione · citationBreak

Citazione a inizio riga

Perché. Una riga di un paragrafo comincia con una citazione numerata posta dopo una parola, o con un pezzo di essa: «autori» alla fine di una riga e «[12]» all’inizio della successiva, o «[14,» sopra «16]». Un numero tra parentesi dopo un numero non è una citazione («2016 (3)»), né una parola tra parentesi. Il testo da destra a sinistra e il cinese, il giapponese o il coreano restano come sono. Con bodyText.citationBreaks su 'warn' si segnalano tutte queste interruzioni; su 'avoid', quelle che la divisione in righe ha tenuto perché nessuna composizione entro la spaziatura tra le parole le evitava per meno di bodyText.citationBreakPenalty. Il motore annota ciascuna in doc.contentWarnings con la citazione, le due righe e la loro pagina.

Soluzione. Imposta bodyText.citationBreaks su 'avoid': la divisione in righe dà un prezzo a un’interruzione prima di una citazione o al suo interno e ricompone il paragrafo dove la spaziatura tra le parole lo permette; lo spazio continua ad allargarsi con gli altri. Un’interruzione che resta costa più di bodyText.citationBreakPenalty da evitare, spesso perché la citazione è larga per la giustezza: alza la penalità per scambiarla con righe più larghe, o scrivi uno spazio unificatore (U+00A0) tra la parola e la citazione per legare quella coppia qualunque sia la regola. Nel port di un libro esistente lascia 'warn': il port riproduce le divisioni dell’originale. Documentazione →

Avviso di impaginazione · operatorBreak

Segno a bordo riga

Perché. Una riga di un paragrafo finisce o comincia con un segno isolato tra spazi, uno di = < > ≤ ≥ ± × ≈ ≠ ÷ − + · →: «LR+ =» alla fine di una riga con «18,29» nella successiva, o «± 0,03» all’inizio di una riga. Un trattino tra parole non è un segno. Il testo da destra a sinistra e il cinese, il giapponese o il coreano restano come sono. Con bodyText.operatorBreaks su 'warn' si segnalano tutte queste interruzioni, una per interruzione (una riga che comincia e finisce con un segno ne dà due); su 'avoid', quelle che la divisione in righe ha tenuto perché nessuna composizione entro la spaziatura tra le parole le evitava per meno di bodyText.operatorBreakPenalty. Il motore annota ciascuna in doc.contentWarnings con il segno, il bordo (fine o inizio), le due righe e la loro pagina.

Soluzione. Imposta bodyText.operatorBreaks su 'avoid': la divisione in righe dà un prezzo a un’interruzione agli spazi ai due lati del segno e ricompone il paragrafo dove la spaziatura tra le parole lo permette. Un’interruzione che resta costa più di bodyText.operatorBreakPenalty da evitare, spesso in una colonna stretta dove il segno e i suoi due termini sono larghi: alza la penalità per scambiarla con righe più larghe, o scrivi spazi unificatori (U+00A0, o U+202F per uno sottile) attorno al segno per legarlo qualunque sia la regola. Nel port di un libro esistente lascia 'warn': il port riproduce le divisioni dell’originale. Documentazione →

  • Le interruzioni si cercano nelle righe già spezzate. Un cambio di formato, di corpo o di testo le sposta: leggi gli avvisi di ogni composizione e non copiare le posizioni da una precedente.
  • Per tenere un richiamo preciso accanto alla sua parola in qualunque colonna, scrivi uno spazio indivisibile prima di esso nel Markdown. Al resto dell’articolo pensa la regola.

Crediti

Testo
Testo originale, CC BY 4.0
Font
STIX Two Text (SIL OFL 1.1) · IBM Plex Sans (SIL OFL 1.1) · IBM Plex Sans Condensed (SIL OFL 1.1)
Sandbox