Pular para o conteúdo principal
Receita número 92

Receitas · Capítulo 5 · Estrutura do livro

Um manual cujas remissões apontam para páginas

Um manual de bicicleta cujas remissões dizem “veja a seção 3.2 na página 3”, para a frente e para trás, com todo número e página tirados da diagramação.

Nesta página
Saída
Canvas · PDF
Postext
Testada com o Postext 1.65.0
Requer ≥ 1.28.0 · postext-pdf ≥ 1.28.0
Licença
Atualizada em 11 de out. de 2026
Código MIT · Texto CC BY 4.0
  • Amostra em inglês: ainda sem edição em português
  • Refile 148 × 210 mm
  • 1 coluna
  • Archivo 9,3/13
  • Archivo Narrow
  • 4 páginas
  • Nível
  • Postext 1.57.1
  • Diagramado em 64 ms
  • 131 linhas de código

Em poucas palavras

Um manual curto de uma bicicleta de cicloturismo. Quando o texto manda você para outra seção, ele dá o número dessa seção e a página em que ela está, e os dois são links.

O que você vai compor

O manual do proprietário de uma bicicleta de cicloturismo fictícia, a Ardena T3: quatro páginas A5 compostas em Archivo, com o nome do modelo numa faixa azul-marinho sobre a primeira página. Um manual não é lido em ordem, de modo que toda instrução que depende de outra diz onde ela está: veja a seção 3.2 na página 3. Quem escreve dá um identificador a um título, a um parágrafo ou a uma frase de um passo e escreve :ref onde o texto remete a ele; o Postext imprime o número, o título ou a página e o transforma em link. O sumário da capa é escrito do mesmo jeito, de modo que mover uma seção, ou traduzir o manual e deixá-lo se recompor, nunca deixa um número desatualizado.

Esta receita responde a

  • Como remeto a uma seção e à página em que ela está, e mantenho as duas corretas quando o livro muda?

A resposta curta

script.js · linhas 28–38no código completo
// 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 };

Ingredientes

Tipografia
Archivo, Archivo Narrow (SIL OFL 1.1)
Materiais
Nenhum: todas as imagens são desenhadas em código

Preparo

#1 · Dar nome àquilo a que o texto remete

O código é a resposta curta acima. Os títulos recebem um identificador à maneira do Pandoc, ### Checking pad wear {#sec-pad-wear}; o aviso sobre a pressão dos pneus começa com :anchor{#warn-pressure}, uma marca invisível; o último passo da montagem da roda é [close the lever so that it points backwards]{#step-close-lever}, que mantém as palavras e lhes dá um nome; e o boxe abre com :::callout{#box-wet type="note" title="Wet weather"}. Uma remissão ao passo imprime as palavras do passo; uma remissão ao boxe, o título dele.

#2 · Um destino, quatro maneiras de nomeá-lo

:ref{id="sec-pad-wear"} imprime section 3.2 com a palavra de crossRefs.section; style=page imprime page 3 com a palavra de crossRefs.page; style=title imprime Checking pad wear; style=pageNumber imprime só o 3. O sumário da capa combina o número sozinho, o título e a página sozinha, e assim se lê como um sumário. Em espanhol, as mesmas remissões imprimem apartado 3.2 e página 3, porque os modelos seguem o idioma da edição.

#3 · As páginas se acertam sozinhas

O número de uma página só é conhecido depois que o manual é diagramado. O motor o diagrama, lê a página em que caiu cada destino e diagrama de novo até que nenhuma remissão mude, o mesmo ciclo que preenche um sumário. Um texto que cresce na tradução, ou uma seção levada para o começo, muda as páginas, e as remissões as acompanham, para a frente e para trás.

#4 · Os números saem do contador de nível 2

script.js · linhas 42–47no código completo
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) };

O manual tem um único título de nível 1, o nome do modelo na capa, por isso as seções são numeradas a partir do nível 2: {2} dá de 1 a 5 e {2}.{3} dá 1.1, 1.2.

#5 · A capa é a abertura desse título

script.js · linhas 51–73no código completo
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) },
  ] },
};

A faixa tem 104 mm de altura, meia página, e um fio laranja a fecha. O chapéu, o subtítulo e a linha da edição são atributos do título, por isso a edição espanhola os troca no próprio texto.

script.js · linhas 13–20no código completo
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' } }));

A receita 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 = 'en'; // @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

O script.js montado funciona como está: cole-o como script de módulo em qualquer página ou abra a receita no CodePen. Pasta da receita no GitHub ↗ (abre em uma nova aba)

Variações

#Escrever “p.” nas remissões

Uma obra de consulta com muitas remissões de página ganha espaço com a 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}' }),

#Deixar as remissões em preto

Quando a maior parte da página são remissões, mantenha-as na cor do texto e em negrito; elas continuam sendo links no PDF e na tela.

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

Erros comuns

  • Uma remissão a um :anchor sem estilo imprime a página, porque uma âncora invisível não tem palavras próprias. Use [words]{#id} quando a remissão tiver de citar o texto.
  • Um identificador tem de ser único no livro. As remissões chegam ao primeiro {#sec-brakes}, e o painel Verificações do Sandbox lista um segundo como duplicateAnchor.

Créditos

Texto
Texto original, CC BY 4.0
Fontes
Archivo (SIL OFL 1.1) · Archivo Narrow (SIL OFL 1.1)
SandboxPDF