Saltar al contingut principal
Recepta número 92

Receptari · Capítol 5 · Estructura del llibre

Un manual amb remissions que apunten a pàgines

Un manual de bicicleta amb remissions que diuen «consulta l'apartat 3.2, a la pàgina 3», endavant i enrere, amb números i pàgines de la maqueta.

En aquesta pàgina
Sortida
Canvas · PDF
Nivell
Intermedi
Postext
Provada amb Postext 1.65.0
Requereix ≥ 1.28.0 · postext-pdf ≥ 1.28.0
Llicència
Actualitzada el 11 d’oct. del 2026
Codi MIT · Text CC BY 4.0
  • Mostra en castellà: encara no hi ha edició en català
  • Format 148 × 210 mm
  • 1 columna
  • Archivo 9,3/13
  • Archivo Narrow
  • 4 pàgines
  • Nivell
  • Postext 1.57.1
  • Compost en 64 ms
  • 131 línies de codi

En poques paraules

Un manual breu per a una bicicleta de cicloturisme. Quan el text t'envia a un altre apartat, en dona el número i la pàgina on és, i tots dos són enllaços.

Què compondràs

El manual de l'usuari d'una bicicleta de cicloturisme fictícia, l'Ardena T3: quatre pàgines A5 en Archivo, amb el nom del model en una banda blau marí sobre la primera. Un manual no es llegeix en ordre, així que cada instrucció que depèn d'una altra diu on és: consulta l'apartat 3.2, a la pàgina 3. Qui l'escriu dona un identificador a un títol, un paràgraf o una frase d'un pas i escriu :ref allà on el text hi remet; Postext imprimeix el número, el títol o la pàgina i el converteix en enllaç. L'índex de la portada s'escriu igual, així que moure un apartat, o traduir el manual i deixar que es recompongui, no deixa mai un número vell.

Aquesta recepta respon a

  • Com remeto a una secció i a la pàgina on és, i mantinc totes dues correctes quan el llibre canvia?

La resposta curta

script.js · línies 28–38al codi complet
// In the Markdown, `## Brakes {#sec-brakes}` names a heading, `:anchor{#warn-pressure}`
// a point in a paragraph and `[close the lever]{#step-close-lever}` a phrase in a step.
// `:ref{id="sec-pad-wear"}` prints "section 3.2", `style=page` "page 3", `style=title`
// the heading's words and `style=pageNumber` the bare 3. The page numbers come from the
// previous layout pass: the engine lays the manual out again until they hold.
const crossRefs = {
  section: t({ en: 'section {n}', es: 'apartado {n}' }), // H2 and H3: "section 3.2"
  page: t({ en: 'page {n}', es: 'página {n}' }), // spelt out: a manual is read by anyone
};
// Every reference is a link in the PDF and on screen; this makes it look like one.
const references = { referenceColor: col('orange'), referenceBold: true };

Ingredients

Tipografia
Archivo, Archivo Narrow (SIL OFL 1.1)
Recursos
Cap: totes les imatges es dibuixen en codi

Elaboració

#1 · Anomena allò a què remet el text

El codi és la resposta curta de més amunt. Els títols porten un identificador a la manera de Pandoc, ### Desgaste de las pastillas {#sec-pad-wear}; l'avís sobre la pressió comença amb :anchor{#warn-pressure}, una marca invisible; l'últim pas per muntar la roda és [cierra la palanca de modo que apunte hacia atrás]{#step-close-lever}, que conserva les seves paraules i els posa nom; i el requadre s'obre amb :::callout{#box-wet type="note" title="Con lluvia"}. Una remissió al pas imprimeix les seves paraules; una al requadre, el seu títol.

#2 · Una destinació, quatre maneres d'anomenar-la

:ref{id="sec-pad-wear"} imprimeix apartat 3.2 amb la paraula de crossRefs.section; style=page imprimeix pàgina 3 amb la de crossRefs.page; style=title imprimeix Desgast de les pastilles; style=pageNumber, només el 3. L'índex de la portada combina el número sol, el títol i la pàgina sola, així que es llegeix com un índex de debò. En anglès les mateixes remissions imprimeixen section 3.2 i page 3, perquè les plantilles segueixen la llengua de l'edició.

#3 · Les pàgines s'ajusten soles

El número de pàgina només es coneix quan el manual ja està compost. El motor el compon, llegeix la pàgina on ha caigut cada destinació i el torna a compondre fins que cap remissió no canvia, el mateix bucle que omple un índex. Un text que creix en traduir-lo, o un apartat que passa al davant, canvia les pàgines, i les remissions les segueixen endavant i enrere.

#4 · Els números surten del comptador de nivell 2

script.js · línies 42–47al codi complet
const H2 = { level: 2, numberingTemplate: '{2}', numberSeparator: '   ', fontFamily: DISPLAY,
  fontWeight: 700, fontSize: pt(15), lineHeight: pt(LEAD * 1.5), color: col('navy'),
  marginTop: pt(LEAD), marginBottom: pt(LEAD / 3) };
const H3 = { level: 3, numberingTemplate: '{2}.{3}', numberSeparator: '  ', fontFamily: DISPLAY,
  fontWeight: 700, fontSize: pt(10.5), lineHeight: pt(LEAD), color: col('ink'),
  marginTop: pt(LEAD / 2), marginBottom: pt(LEAD / 4) };

El manual té un sol títol de nivell 1, el nom del model a la portada, així que els seus apartats es numeren des del nivell 2: {2} dona de l'1 al 5 i {2}.{3} dona 1.1, 1.2.

#5 · La portada és l'obertura d'aquest títol

script.js · línies 51–73al codi complet
const BAND = 104; // mm from the trim's top
const label = { fontFamily: DISPLAY, fontWeight: 700, textTransform: 'uppercase',
  letterSpacing: pt(1.6), align: 'left' };
const cover = {
  enabled: true,
  minHeight: mm(BAND - PAGE.top + 8), // the contents start 8 mm under the band
  slot: { elements: [
    { kind: 'box', id: 'band', style: { backgroundColor: col('navy') },
      placement: { ...at('page', 'top-left'), size: { width: 'fill', height: mm(BAND) } } },
    { kind: 'box', id: 'stripe', style: { backgroundColor: col('orange') },
      placement: { ...at('page', 'top-left', 0, BAND), size: { width: 'fill', height: mm(2.5) } } },
    { kind: 'text', id: 'kicker', content: '{attr.kicker}', ...label, fontSize: pt(9),
      color: col('tint'), placement: at('container', 'top-left', 0, 6) },
    { kind: 'text', id: 'title', content: '{titleText}', fontFamily: DISPLAY, fontWeight: 700,
      fontSize: pt(58), lineHeight: 1, color: col('paper'), align: 'left',
      placement: at('container', 'top-left', -1, 30) },
    { kind: 'text', id: 'subtitle', content: '{attr.subtitle}', fontFamily: TEXT,
      fontSize: pt(11), color: col('paper'), align: 'left',
      placement: at('container', 'top-left', 0, 55) },
    { kind: 'text', id: 'edition', content: '{attr.edition}', ...label, fontSize: pt(7.5),
      color: col('tint'), placement: at('container', 'top-left', 0, 74) },
  ] },
};

La banda fa 104 mm, mitja pàgina, i la tanca una franja taronja. L'avantítol, el subtítol i la línia de l'edició són atributs del títol, així que l'edició espanyola els canvia en el seu propi text.

script.js · línies 13–20al codi complet
const palette = {
  ink: '#1b1f24', navy: '#1d2c3c', orange: '#b8471b', tint: '#f7e7de', rule: '#d5cfc8',
  muted: '#5c636b', paper: '#ffffff',
};
// Each colour carries its hex and the palette entry it follows.
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = Object.entries({ ...palette, 'main-color': palette.orange })
  .map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));

La recepta completa

Sandbox
// ═══ Postext Cookbook · Nº 092 · A manual whose references point to pages ══════════
// https://postext.dev/en/cookbook/manual-see-page-references
// Code: MIT · Text: original (CC BY 4.0) · Pictures: none
// Fonts: Archivo, Archivo Narrow (SIL OFL 1.1) · Needs postext ≥ 1.28.0
import { buildDocumentWithFonts, renderPageToCanvas } from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';

const LANG = 'es'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'manual-see-page-references';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: a navy cover band and one signal orange for numbers and references
const palette = {
  ink: '#1b1f24', navy: '#1d2c3c', orange: '#b8471b', tint: '#f7e7de', rule: '#d5cfc8',
  muted: '#5c636b', paper: '#ffffff',
};
// Each colour carries its hex and the palette entry it follows.
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = Object.entries({ ...palette, 'main-color': palette.orange })
  .map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
// #endregion
const TEXT = 'Archivo', DISPLAY = 'Archivo Narrow';
const PAGE = { w: 148, h: 210, top: 20, bottom: 20, inner: 18, outer: 15 }; // mm: A5, mirrored
const LEAD = 13; // pt
const at = (to, edge, x = 0, y = 0) => ({ anchor: { to, edge }, offset: { x: mm(x), y: mm(y) } });

// #region answer: the words a reference prints, and references that are links
// In the Markdown, `## Brakes {#sec-brakes}` names a heading, `:anchor{#warn-pressure}`
// a point in a paragraph and `[close the lever]{#step-close-lever}` a phrase in a step.
// `:ref{id="sec-pad-wear"}` prints "section 3.2", `style=page` "page 3", `style=title`
// the heading's words and `style=pageNumber` the bare 3. The page numbers come from the
// previous layout pass: the engine lays the manual out again until they hold.
const crossRefs = {
  section: t({ en: 'section {n}', es: 'apartado {n}' }), // H2 and H3: "section 3.2"
  page: t({ en: 'page {n}', es: 'página {n}' }), // spelt out: a manual is read by anyone
};
// Every reference is a link in the PDF and on screen; this makes it look like one.
const references = { referenceColor: col('orange'), referenceBold: true };
// #endregion

// #region numbers: sections 1–5 and 1.1, 1.2… under the one level-1 heading
const H2 = { level: 2, numberingTemplate: '{2}', numberSeparator: '   ', fontFamily: DISPLAY,
  fontWeight: 700, fontSize: pt(15), lineHeight: pt(LEAD * 1.5), color: col('navy'),
  marginTop: pt(LEAD), marginBottom: pt(LEAD / 3) };
const H3 = { level: 3, numberingTemplate: '{2}.{3}', numberSeparator: '  ', fontFamily: DISPLAY,
  fontWeight: 700, fontSize: pt(10.5), lineHeight: pt(LEAD), color: col('ink'),
  marginTop: pt(LEAD / 2), marginBottom: pt(LEAD / 4) };
// #endregion

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

#Abreuja «pàg.» a les remissions

Una obra de consulta amb moltes remissions a pàgina guanya espai amb l'abreviatura.

-  page: t({ en: 'page {n}', es: 'página {n}' }), // spelt out: a manual is read by anyone
+  page: t({ en: 'p. {n}', es: 'pág. {n}' }),

#Deixa les remissions en negre

Quan la pàgina és plena de remissions, deixa-les en el color del text i en negreta; continuen sent enllaços al PDF i a la pantalla.

-const references = { referenceColor: col('orange'), referenceBold: true };
+const references = { referenceColor: col('ink'), referenceBold: true };

Errors freqüents

  • Una remissió a un :anchor sense estil imprimeix la pàgina, perquè una àncora invisible no té paraules pròpies. Fes servir [palabras]{#id} quan la remissió hagi de citar el text.
  • Un identificador ha de ser únic al llibre. Les remissions arriben al primer {#sec-brakes}, i el tauler Revisió del Sandbox avisa del segon com a duplicateAnchor.

Crèdits

Text
Text original, CC BY 4.0
Fonts
Archivo (SIL OFL 1.1) · Archivo Narrow (SIL OFL 1.1)
SandboxPDF