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

Receitas · Capítulo 5 · Estrutura do livro

Um livro técnico com referências entre capítulos

Um manual solar de três capítulos cujo texto escreve @fig:sun, @tbl:loads e @sec:array-size; buildBundle imprime cada número e página de um capítulo a outro.

Nesta página
  • Amostra em inglês: ainda sem edição em português
  • Refile 178 × 233 mm
  • 1 coluna
  • IBM Plex Serif 9,6/13,8
  • IBM Plex Mono
  • IBM Plex Sans Condensed
  • 9 páginas
  • Nível
  • Postext 1.57.1
  • Diagramado em 134 ms
  • 246 linhas de código

Em poucas palavras

Um manual curto para dimensionar os painéis solares e as baterias de uma cabana. Quando o capítulo 3 remete a uma tabela do capítulo 1, ou o capítulo 1 a uma seção do 2, saem impressos o número e a página certos, e eles são links.

O que você vai compor

Um manual técnico curto, Power for a Cabin, composto em IBM Plex numa página de 178 × 233 mm: uma capa com as trajetórias do sol desenhadas em código, um sumário e três capítulos sob uma faixa azul-noite. O livro dimensiona um pequeno sistema solar, de modo que cada capítulo se apoia nos outros. O capítulo 3 cita a tabela de consumo do capítulo 1 e o gráfico de horas de sol do capítulo 2; o capítulo 1 manda o leitor adiante, para a seção 2.3, e informa a página. Quem escreve põe @tbl:loads e @sec:array-size, do jeito que o pandoc-crossref lê, em quatro arquivos Markdown separados. buildBundle os diagrama como um só livro, de modo que cada referência imprime o número que o destino recebeu no próprio capítulo, a página em que ele caiu e um link para ele.

Esta receita responde a

  • Como remeto a uma figura, uma tabela ou uma seção de outro capítulo, no estilo do pandoc-crossref, com os números sempre corretos?
  • 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 44–61no código completo
// buildBundle lays the chapters out in order. Each chapter whose text names a target it
// does not hold (`@sec:array-size` in chapter 1, `@tbl:loads` in chapter 3) is laid out
// with the outline of the whole book, so the reference prints "section 2.3" and its page,
// and links to it. Headings carry their ids in the Markdown, `## Sizing the array
// {#sec:array-size}`; figures and tables are resources whose ids are what follows the @.
const book = () => buildBundle({ chapters, config: config(), resources });
const crossRefs = {
  chapter: t({ en: 'chapter {n}', es: 'capítulo {n}' }), // @sec:array → "chapter 2"
  section: t({ en: 'section {n}', es: 'apartado {n}' }), // @sec:losses → "section 2.2"
  page: t({ en: 'p. {n}', es: 'pág. {n}' }), // :ref{id="sec:losses" style=page} → "p. 7"
};
// Figures and tables count per chapter ({h1}.{n}) and carry on from one document to the
// next. A reference prints the type's shortLabel: @fig:sun → "Fig. 2.1", @Tbl:loads (capital
// T, at the start of a sentence) → "Table 1.1", [-@tbl:loads] → the bare "1.1".
const resourceTypes = defaultResourceTypes(LANG).map((type) => ({ ...type,
  shortLabel: type.id === 'table' ? t({ en: 'table', es: 'tabla' })
    : t({ en: 'fig.', es: 'figura' }),
  ...(type.id === 'table' && { captionStyle: { position: 'above' } }) }));

Ingredientes

Tipografia
IBM Plex Serif, IBM Plex Sans Condensed, IBM Plex Mono (SIL OFL 1.1)
Materiais
Nenhum: todas as imagens são desenhadas em código

Preparo

#1 · Dar nome a cada destino uma vez, para o livro inteiro

O código é a resposta curta acima. Os títulos levam um identificador do Pandoc com o prefixo, ## Sizing the array {#sec:array-size}. Figuras e tabelas são recursos declarados no script, e os ids delas se escrevem do mesmo jeito, fig:sun e tbl:loads, de modo que o texto diz @fig:sun esteja a figura dois parágrafos antes ou dois capítulos antes. Um id precisa ser único no livro todo, não só no capítulo.

#2 · Diagramar os capítulos como um só livro

script.js · linhas 44–61no código completo
// buildBundle lays the chapters out in order. Each chapter whose text names a target it
// does not hold (`@sec:array-size` in chapter 1, `@tbl:loads` in chapter 3) is laid out
// with the outline of the whole book, so the reference prints "section 2.3" and its page,
// and links to it. Headings carry their ids in the Markdown, `## Sizing the array
// {#sec:array-size}`; figures and tables are resources whose ids are what follows the @.
const book = () => buildBundle({ chapters, config: config(), resources });
const crossRefs = {
  chapter: t({ en: 'chapter {n}', es: 'capítulo {n}' }), // @sec:array → "chapter 2"
  section: t({ en: 'section {n}', es: 'apartado {n}' }), // @sec:losses → "section 2.2"
  page: t({ en: 'p. {n}', es: 'pág. {n}' }), // :ref{id="sec:losses" style=page} → "p. 7"
};
// Figures and tables count per chapter ({h1}.{n}) and carry on from one document to the
// next. A reference prints the type's shortLabel: @fig:sun → "Fig. 2.1", @Tbl:loads (capital
// T, at the start of a sentence) → "Table 1.1", [-@tbl:loads] → the bare "1.1".
const resourceTypes = defaultResourceTypes(LANG).map((type) => ({ ...type,
  shortLabel: type.id === 'table' ? t({ en: 'table', es: 'tabla' })
    : t({ en: 'fig.', es: 'figura' }),
  ...(type.id === 'table' && { captionStyle: { position: 'above' } }) }));

buildBundle leva os contadores de figuras e tabelas de um capítulo para o seguinte, por isso a primeira tabela do capítulo 3 é a 3.1 e @tbl:loads no capítulo 3 continua imprimindo table 1.1. Um capítulo cujo texto menciona um título que ele não contém é diagramado com a estrutura do livro inteiro, e diagramado de novo (três rodadas no máximo) até as páginas dessa estrutura pararem de mudar. É assim que o capítulo 1 consegue imprimir section 2.1 … p. 6 antes de o capítulo 2 existir no papel.

#3 · Escolher as palavras que uma referência imprime

crossRefs define chapter, section e p. (em espanhol, capítulo, apartado e pág.). Uma referência a figura ou tabela imprime o shortLabel do tipo, aqui em minúscula como o pandoc-crossref as compõe, fig. 2.1 e table 1.1. Uma maiúscula no prefixo, @Tbl:loads ou @Sec:array, põe o rótulo em maiúscula no início da frase, e [-@tbl:losses] imprime só o número, para tables 2.1 and 3.1.

#4 · Remeter adiante a seções, para trás a figuras

Uma figura ou tabela é numerada, e posicionada como flutuante, onde é citada pela primeira vez. @fig:soc no capítulo 1 a transformaria na figura 1.2 e a colocaria no capítulo 1. Por isso o capítulo 1 remete adiante a @sec:autonomy, e as figuras e tabelas são citadas primeiro no próprio capítulo; os capítulos seguintes remetem a elas à vontade. A página vai junto com a seção, :ref{id="sec:sun-hours" style=page}: uma referência a um recurso imprime o rótulo e o número, nunca a página.

#5 · As aberturas e a capa saem da mesma faixa

script.js · linhas 65–85no código completo
const BAND = 52; // mm from the trim's top
const opener = { enabled: true, minHeight: mm(54), slot: { elements: [
  { kind: 'box', id: 'band', style: { backgroundColor: col('night') },
    placement: { ...at('bleed', 'top-left'), size: { width: 'fill', height: mm(BAND + 3) } } },
  { kind: 'text', id: 'kicker', content: t({ en: 'Chapter', es: 'Capítulo' }), ...caps(8.5),
    color: col('sun'), placement: at('container', 'top-left', 0, 2) },
  { kind: 'text', id: 'title', content: '{titleText}', fontFamily: COND, fontWeight: 600,
    fontSize: pt(30), lineHeight: 1.05, color: col('paper'), align: 'left', overflow: 'wrap',
    placement: { ...at('#kicker', 'below', 0, 3), size: { width: mm(MEASURE - 26) } } },
  { kind: 'text', id: 'number', content: '{chapterNumber}', fontFamily: COND, fontWeight: 600,
    fontSize: pt(84), lineHeight: 1, color: col('sun'), align: 'right',
    placement: { ...at('container', 'top-right', 0, -6), size: { width: mm(40) } } },
  { kind: 'text', id: 'lead', content: '{attr.lead}', fontFamily: SERIF, italic: true,
    fontSize: pt(11), lineHeight: 1.38, color: col('ink'), align: 'left', overflow: 'wrap',
    placement: { ...at('container', 'top-left', 0, BAND - MARGIN.top + 8),
      size: { width: mm(MEASURE - 10) } } },
] } };
// The contents page wears the same band, with the book's subtitle as its kicker.
const contentsOpener = { ...opener, minHeight: mm(BAND - MARGIN.top + 4), slot: { elements:
  opener.slot.elements.filter((e) => ['band', 'kicker', 'title'].includes(e.id))
    .map((e) => (e.id === 'kicker' ? { ...e, content: '{subtitle}' } : e)) } };

A faixa desce 55 mm a partir do topo do refile em todos os capítulos e no sumário, que reaproveitam os mesmos elementos; o número do capítulo é {chapterNumber}, e o texto de entrada, um atributo do título.

script.js · linhas 89–109no código completo
const COVER_BAND = 168; // mm
const cover = { enabled: true, slot: { elements: [
  { kind: 'box', id: 'band', style: { backgroundColor: col('night') },
    placement: { ...at('bleed', 'top-left'), size: { width: 'fill', height: mm(COVER_BAND) } } },
  { kind: 'image', id: 'art', resourceId: 'cover',
    placement: { ...at('bleed', 'top-left'), size: { width: 'fill' } } },
  // Stacked upwards from the subtitle, so a title of one line or two keeps its distance.
  { kind: 'text', id: 'subtitle', content: '{subtitle}', fontFamily: SERIF, italic: true,
    fontSize: pt(14), color: col('tint'), align: 'left',
    placement: at('page', 'top-left', MARGIN.inner, COVER_BAND - 22) },
  { kind: 'text', id: 'title', content: '{titleText}', fontFamily: COND, fontWeight: 600,
    fontSize: pt(52), lineHeight: 1, color: col('paper'), align: 'left', overflow: 'wrap',
    placement: { ...at('#subtitle', 'above', 0, -4), size: { width: mm(140) } } },
  { kind: 'text', id: 'kicker', content: '{attr.kicker}', ...caps(8.5), color: col('sun'),
    placement: at('#title', 'above', 0, -4) },
  { kind: 'text', id: 'author', content: '{author}', fontFamily: COND, fontWeight: 600,
    fontSize: pt(13), color: col('ink'), align: 'left',
    placement: at('page', 'top-left', MARGIN.inner, COVER_BAND + 14) },
  { kind: 'text', id: 'edition', content: '{attr.edition}', ...caps(7.5), color: col('muted'),
    placement: at('#author', 'below', 0, 2.5) },
] } };

A receita completa

Sandbox
// ═══ Postext Cookbook · Nº 094 · A technical book whose references cross chapters ═══
// https://postext.dev/en/cookbook/technical-book-crossref-chapters
// Code: MIT · Text: original (CC BY 4.0) · Charts: generated in code (CC BY 4.0)
// Fonts: IBM Plex Serif, Sans Condensed and Mono (SIL OFL 1.1) · Needs postext ≥ 1.28.0
// A small handbook in four Markdown documents. The text writes @fig:sun, @tbl:loads and
// @sec:array-size the way pandoc-crossref reads them, and buildBundle resolves each one to
// the right number, title or page wherever in the book its target lies.
import {
  buildBundle, prepareFonts, withLoadedFonts, renderPageToCanvas, registerResourceImage,
  defaultResourceTypes, parseTSV, setAlignment, inlineSvgFonts,
} 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 = 'technical-book-crossref-chapters';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: a night-blue band, one burnt-orange accent, an amber for the charts
const palette = {
  ink: '#1c1f24', // text: a cool near-black
  night: '#1f3247', // openers, the cover, table heads
  accent: '#a8471a', // numbers, kickers, references (5.6:1 on paper)
  sun: '#e9a33a', // the charts and the cover only, never text on paper
  tint: '#f5ede3', // daylight in the charts
  rule: '#cfc7bc', // hairlines
  muted: '#5e636a', // running heads, colophon, chart labels
  paper: '#ffffff',
};
// Each colour names its palette entry and carries its hex.
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 = 'IBM Plex Serif', COND = 'IBM Plex Sans Condensed', MONO = 'IBM Plex Mono';
const TRIM = { w: 178, h: 233 }; // mm: a technical-book trim
const MARGIN = { top: 22, bottom: 22, inner: 20, outer: 32 }; // a 126 mm measure
const LEAD = 13.8; // pt: the body leading
const MEASURE = TRIM.w - MARGIN.inner - MARGIN.outer;
const at = (to, edge, x = 0, y = 0) => ({ anchor: { to, edge }, offset: { x: mm(x), y: mm(y) } });
const caps = (size, extra = {}) => ({ fontFamily: MONO, fontSize: pt(size), fontWeight: 600,
  letterSpacing: pt(size * 0.14), textTransform: 'uppercase', align: 'left', ...extra });

// #region answer: one set of identifiers for the whole book, resolved across chapters
// buildBundle lays the chapters out in order. Each chapter whose text names a target it
// does not hold (`@sec:array-size` in chapter 1, `@tbl:loads` in chapter 3) is laid out
// with the outline of the whole book, so the reference prints "section 2.3" and its page,
// and links to it. Headings carry their ids in the Markdown, `## Sizing the array
// {#sec:array-size}`; figures and tables are resources whose ids are what follows the @.

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

#Imprimir “Figure 2.1” no texto

Um livro que escreve as referências por extenso usa o nome completo do tipo em vez do rótulo curto.

-  shortLabel: type.id === 'table' ? t({ en: 'table', es: 'tabla' })
-    : t({ en: 'fig.', es: 'figura' }),
+  shortLabel: type.id === 'table' ? t({ en: 'Table', es: 'Tabla' })
+    : t({ en: 'Figure', es: 'Figura' }),

#Numerar as seções com o sinal de parágrafo

-  section: t({ en: 'section {n}', es: 'apartado {n}' }), // @sec:losses → "section 2.2"
+  section: '§ {n}',

Erros comuns

Erro comum

Uma figura é numerada e posicionada onde é citada pela primeira vez

A primeira referência :ref ou @fig: a uma figura ou tabela dá a ela o seu número e o seu lugar, então uma referência em um capítulo anterior a leva para lá. Remeta adiante à seção que a contém, e à própria figura só depois que ela estiver posicionada. Referências cruzadas →

  • Uma referência a um id que nenhum capítulo define imprime ?. Confira os ids depois de renomear um título num capítulo: as referências a ele estão nos outros.
  • Diagramar os capítulos um por um com buildDocument perde os contadores e a estrutura do livro: cada capítulo numera as figuras a partir de 1 de novo, e uma referência a outro capítulo imprime ?. Use buildBundle, ou encadeie continuation e passe o outline você mesmo.
  • As equações não têm numeração própria no Postext, por isso @eq: só encontra uma âncora que você tenha definido e imprime o texto dela; este livro escreve as duas fórmulas sem número.
  • Um título de seção que abre uma página, ou que fica sob uma tabela no alto da página como o 3.3 na página 9, perde por padrão todo o espaço acima dele, e o ajuste à grade põe então sob o título a fração de linha que falta: o texto fica mais longe dele do que nos títulos no meio da página. headings.columnHeadSpace: 'remainder' deixa essa fração de linha acima do título (títulos). Convém a um livro em uma coluna, onde nenhuma coluna vizinha mostra que o título começa um pouco mais abaixo.

Créditos

Texto
Texto original, CC BY 4.0
Fontes
IBM Plex Serif (SIL OFL 1.1) · IBM Plex Sans Condensed (SIL OFL 1.1) · IBM Plex Mono (SIL OFL 1.1)
SandboxPDF