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
// 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
- Funcionalidades
- Referências cruzadasLegendas numeradasLivros compostos capítulo a capítuloTítulos numeradosSumárioAberturas desenhadasAtributos de títuloEstilos de títuloCapítulos sem númeroCabeços e fóliosCapas, folhas de rosto e colofõesImagens nos designs de páginaMargens espelhadasPaleta de cores semânticaEstilos de parágrafoExportação para PDF
- Também usa
- Citações em um estilo de citaçãoCitações que posicionam as figurasFigura e Tabela no seu idiomaCabeços por tipo de páginaFontes incorporadas ao PDFTipos de recurso personalizadosFiguras e tabelas como recursosCabeços por seçãoTabelas a partir de dados
- 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
// 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
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.
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
// ═══ 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
buildDocumentperde 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 ?. UsebuildBundle, ou encadeiecontinuatione passe ooutlinevocê 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
- Receita
- Ignacio Ferro
- 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)
- Código
- MIT, como o Postext
Editar este texto ↗ (abre em uma nova aba)Pasta da receita no GitHub ↗ (abre em uma nova aba)


