Em poucas palavras
Um manual de instruções de sete páginas, em alemão, para uma chaleira elétrica. Mostra como fazer boxes de aviso de segurança com o triângulo de alerta, em vermelho ou âmbar conforme o nível de perigo.
O que você vai compor
Um manual de instruções de sete páginas para a Verra W1, uma chaleira elétrica inventada, em alemão e em A5. A página de segurança põe os dois níveis de perigo em boxes: uma faixa na cor de alerta desce pelo lado esquerdo e leva o triângulo de advertência, e uma moldura fina da mesma cor fecha o box, vermelha em WARNUNG e âmbar em VORSICHT. HINWEIS, o nível para danos ao aparelho, troca a faixa e o triângulo por um fundo verde-azulado de cantos arredondados. O parágrafo acima dos boxes traz as três palavras de advertência em chips preenchidos. A página 3 tem um desenho das peças com linhas de chamada numeradas sobre a legenda, e na página 4 os nomes das teclas são chips contornados ao lado de números de passo grandes. A tabela de solução de problemas ocupa as páginas 6 e 7. As legendas dizem Abbildung e Tabelle, e a tabela dividida leva Fortsetzung nas duas páginas.
Esta receita responde a
- Como faço boxes de nota, dica ou aviso com ícone, faixa de cor e cantos arredondados?
- Como faço chips em linha: teclas, etiquetas, bancos de palavras para exercícios?
- Como personalizo listas: marcadores por nível, numeração (a)/(i), caixas de seleção de tarefas e um espaçamento que fique na grade?
- Como acrescento uma figura com legenda numerada e a cito no texto (“ver fig. 3.2”)?
- Como faço uma tabela com linhas de cabeçalho, células mescladas, larguras de coluna e alinhamento por célula?
- Como divido uma tabela longa entre páginas com o cabeçalho repetido e um aviso de “continua”?
- Como faço os rótulos “Figura” e “Tabela” saírem no idioma do meu documento?
A resposta curta
const BAND = 8.5; // mm: a stripe on the side is the icon's column; the icon is centred on it
const [TITLE, TITLE_GAP] = [8.6, 2.4]; // pt; a box title's line is 1.2 times its size
const PAD_Y = (2 * LEAD - 1.2 * TITLE - TITLE_GAP) / 2; // pt: title and padding fill two lines
const notice = (id, hue, ink, icon) => ({ id, backgroundEnabled: false,
stripe: { enabled: true, side: 'left', width: mm(BAND), color: col(hue) },
border: { enabled: true, color: col(hue), width: pt(0.75) }, // closes the band into a frame
icon: { kind: 'resource', resourceId: icon, size: mm(5.6), align: 'top' },
padding: { top: pt(PAD_Y), right: mm(3.2), bottom: pt(PAD_Y), left: mm(3.2) },
titleStyle: { fontFamily: DISPLAY, fontWeight: 800, fontSize: pt(TITLE), color: col(ink),
textTransform: 'uppercase', letterSpacing: pt(1.3), gap: pt(TITLE_GAP) },
body: { fontSize: pt(8.8), lineHeight: pt(LEAD) }, // on the grid: a box is whole lines tall
lists: { color: col(ink), gap: mm(2) }, marginTop: pt(LEAD), marginBottom: pt(0) });
const calloutStyles = [
notice('warnung', 'warning', 'warning', 'triangle-white'), // white triangle, red '!'
notice('vorsicht', 'caution', 'ink', 'triangle-ink'), // amber type would fail contrast
{ ...notice('hinweis', 'brand', 'brand'), stripe: { enabled: false }, border: { enabled: false },
backgroundEnabled: true, background: col('tint'), borderRadius: mm(2), // property damage:
icon: { kind: 'resource', resourceId: 'info', size: mm(4.6) } }, // no band, an icon column
];
Ingredientes
- Funcionalidades
- Ícones e selos de canto nos boxesBoxesTipos de recurso personalizadosEndereços dos links no papelChips no textoCitações que posicionam as figurasFiguras exatamente aquiPosicionamento de figurasTabelas a partir de dadosEstilo de tabelaTabelas que passam de páginaTítulos numeradosListas numeradasHifenização e idioma do documentoFigura e Tabela no seu idiomaAberturas desenhadasEstilos de títuloCapas, folhas de rosto e colofõesCabeços e fóliosTextos, fios e caixas nos designs de página
- Também usa
- Notas de rodapéAtributos de títuloQuebras de página e de colunaCabeços por tipo de páginaEstilos de parágrafoFiguras e tabelas como recursosEstilos de tabela com nomeCapítulos sem número
- Tipografia
- Red Hat Text, Red Hat Display, Red Hat Mono (SIL OFL 1.1)
- Materiais
- Nenhum: todas as imagens são desenhadas em código
Preparo
#1 · Uma faixa que leva o triângulo
O código é a resposta curta logo acima. stripe pinta a faixa pela borda esquerda. Quando um box tem faixa lateral, o ícone fica centralizado sobre a faixa em vez de ocupar uma coluna própria (estilos de boxe), e align: 'top' alinha a borda superior do ícone com a do título. A border da mesma cor fecha a faixa numa moldura; sem ela, o texto do box ficaria solto na página, ao lado de uma barra colorida. PAD_Y é calculado para que o título, o espaço abaixo dele e os enchimentos superior e inferior somem duas linhas da grade de 12,8 pt. O corpo mantém a entrelinha da grade, e assim cada box tem um número inteiro de linhas de altura (10 em WARNUNG, 8 em VORSICHT), e marginTop: pt(LEAD) deixa exatamente uma linha entre os dois boxes da página 2. VORSICHT mantém o âmbar na faixa e na moldura e põe o título e os marcadores na cor do texto: âmbar sobre branco dá um contraste de 2,0:1, e texto pequeno precisa de 4,5:1. HINWEIS parte da mesma base (...notice(…)) e desativa a faixa e a moldura, por isso seu ícone de informação ganha uma coluna própria e borderRadius arredonda um fundo liso.
#2 · Nomes em alemão para figuras e tabelas
const counted = { numberingTemplate: '{n}', resetOn: 'never', counterFormat: 'decimal' }; // 1, 2…
// The built-in types in German, Abbildung and Tabelle; a table is captioned over its head.
const resourceTypes = defaultResourceTypes('de').map((type) => ({ ...type, ...counted,
...(type.id === 'table' && { captionStyle: { position: 'above' } }) }));
const tableStyle = { rules: 'horizontal', borderColor: col('rule'), borderWidth: pt(0.5),
headerBackground: col('ink'), headerColor: col('paper'), headerFontFamily: MONO,
headerFontSize: pt(7.6), bodyFontSize: pt(8.2), cellPadding: mm(1.3),
// The engine's own German strings are '(Forts.)' and 'Wird fortgesetzt': these spell them out.
continuedSuffix: '(Fortsetzung)', continuesMarker: 'Fortsetzung auf der nächsten Seite' };
locale: 'de' dá ao manual a hifenização alemã e nomes alemães aos tipos padrão: sem mais nada, as legendas diriam Abbildung 2.1 e Tabelle 5.1, e sob a primeira parte da tabela dividida se leria Wird fortgesetzt. O estilo de tabela escreve por extenso essa nota e o sufixo da legenda, e defaultResourceTypes('de') é passado por duas mudanças. A primeira é counted: {n} com resetOn: 'never' numera o manual inteiro em sequência (Abbildung 1, Tabelle 1 a 3) em vez de recomeçar em cada seção. Só o tipo tabela define captionStyle.position: 'above', de modo que as tabelas levam a legenda acima do cabeçalho e o desenho mantém a sua embaixo.
#3 · Teclas, palavras de advertência e números de peça como chips
const filled = (id, fill, ink) => ({ id, fontFamily: DISPLAY, bold: true, fontSize: em(0.82),
background: col(fill), color: col(ink), borderWidth: pt(0), paddingX: em(0.45) }); // no outline
const chipStyles = [
{ id: 'taste', fontFamily: MONO, bold: true, fontSize: em(0.92), backgroundEnabled: false,
borderColor: col('ink'), borderWidth: pt(0.6), borderRadius: pt(2.2), paddingX: em(0.4) },
filled('warnung', 'warning', 'paper'), filled('vorsicht', 'caution', 'ink'),
filled('hinweis', 'brand', 'paper'), { ...filled('nr', 'brand', 'paper'), fontSize: em(0.95),
borderRadius: em(1) }, // a part number, round like the drawing's
];
taste contorna o nome de uma tecla na fonte monoespaçada, sem preenchimento, do jeito que o rótulo vem impresso no botão. Os chips das palavras de advertência são preenchidos com as cores dos boxes, e o chip âmbar põe a palavra na cor do texto, como o título de VORSICHT. nr dá aos números de peça um raio maior que metade da altura, e eles saem como discos, iguais aos círculos numerados do desenho. O tamanho dos chips é dado em em do texto ao redor: uma tecla tem 8,6 pt no texto corrido e 7,5 pt numa célula de tabela (estilos de chip).
#4 · Números de passo na linha de base
const orderedLists = { separator: '', fontFamily: DISPLAY, fontWeight: 800, color: col('brand'),
numberFontSize: pt(15), gap: mm(3), itemSpacing: pt(5), marginTop: pt(LEAD / 2),
marginBottom: pt(0), numberVerticalOffset: pt(-1) }; // gotcha: list-number-centred
const unorderedLists = { color: col('brand'), gap: mm(2), marginTop: pt(0), marginBottom: pt(0),
levels: [{ level: 2, bulletChar: '–', indent: mm(6.5) }, // at a step's text: number + 3 mm gap
{ level: 3, bulletChar: '–', color: col('muted') }] }; // teal •, teal –, grey –
Os passos são uma lista numerada com os algarismos em Red Hat Display 800 de 15 pt, em verde-azulado, sem separador. O número de uma lista fica centralizado na primeira linha em vez de se apoiar na linha de base, e um algarismo de 15 pt ao lado de texto de 9,3 pt fica cerca de 1 pt abaixo da linha. numberVerticalOffset: pt(-1), um valor medido na captura, ergue o pé do algarismo até a linha de base. itemSpacing separa os passos em 5 pt para dar espaço aos algarismos grandes. Os marcadores aninhados sob um passo começam a 6,5 mm, na altura do texto do passo; são travessões verde-azulados, e os do terceiro nível são cinza (listas numeradas).
#5 · Números de seção numa aba invertida
const H1 = 14, TAB = 2 * LEAD - 3.6, PAD = (TAB - H1 * 1.2) / 2; // pt: a square 2 lines less 3.6
const face = { fontFamily: DISPLAY, fontWeight: 800, fontSize: pt(H1), lineHeight: 1.2 }; // both
const section = { level: 1, numberingTemplate: '{1}', // {number}: 1, 2, 3 …
breakBefore: { enabled: false }, marginTop: pt(LEAD), marginBottom: pt(LEAD / 2), // run on
advancedDesign: { enabled: true, slot: { elements: [
{ kind: 'text', id: 'tab', content: '{number}', ...face, color: col('paper'), align: 'center',
box: { backgroundColor: col('brand'), padding: pad(PAD) },
placement: pin('container', 'top-left', 0, 0, { width: pt(TAB) }) },
{ kind: 'text', id: 'title', content: '{titleText}', ...face, color: col('ink'),
overflow: 'wrap', box: { padding: { top: pt(PAD) } }, placement: pin('#tab', 'right-of', 3) },
] } } };
Cada seção é um título de nível 1 dentro da coluna, desenhado a partir de um espaço de design. A aba imprime {number} (preenchido por numberingTemplate: '{1}') em branco sobre um quadrado verde-azulado, e o título começa 3 mm à direita dela. Número e título têm o mesmo corpo e a mesma entrelinha, e por isso o mesmo enchimento superior os assenta na mesma linha de base. A aba é um quadrado de 22 pt, 3,6 pt a menos que duas linhas da grade de 12,8 pt, e o título não passa de duas linhas da grade. A capa também é um título de nível 1, com um estilo de título sem número, de modo que Sicherheitshinweise é a seção 1.
#6 · Uma tabela de solução de problemas com células mescladas que se divide
function faultTable(tsv) { // the first line is the head row; the widths are weights
let m = { ...parseTSV(tsv, { headerRows: 1 }), columnWidths: [30, 34, 36] };
for (let r = 2, top = 1; r < m.rows.length; r++) { // a rowspan per fault: no cut runs through it
if (m.rows[r][0].content) top = r; // mergeCells hides what it covers: merged-cells-hiddenby
else m = mergeCells(m, { start: { row: top, col: 0 }, end: { row: r, col: 0 } });
}
return m;
}
const fold = (rows, columnWidths) => ({ columnWidths, rows: rows.slice(0, rows.length / 2) // 2 up
.map((row, k) => [...row, ...rows[k + rows.length / 2]]) });
const legend = fold(parseTSV(parts).rows.map(([chip, name]) => [{ ...chip, align: 'center' },
name]), [7, 43, 7, 43]); // each part's number chip centred in its narrow column
const HERE = { placement: { position: 'here' } }; // at the resource's ::resource line
const table = (id, caption, model, styleId = 'bare', where = HERE) => ({ id, typeId: 'table',
kind: 'table', caption, table: { model, styleId }, createdAt: 0, updatedAt: 0, ...where });
const tables = [table('legende', 'Teile des Verra W1', legend),
table('daten', 'Kenndaten des VW-170', fold(parseTSV(data).rows, [20, 30, 20, 30])),
table('stoerungen', 'Störungen und ihre Behebung', faultTable(faults), null, // the house style,
{ placement: { position: 'top' } })]; // a float: it heads the page after its citation
Cada tabela é um TSV num arquivo de conteúdo próprio. Nos dados de solução de problemas, uma linha cuja primeira célula está vazia pertence ao defeito de cima, e mergeCells junta essas primeiras células numa única célula alta e marca como ocultas as que ela cobre. parseTSV não define linha de cabeçalho, por isso headerRowCount: 1 a declara, e é essa linha que se repete na página 7. A tabela é mais alta que uma página, por isso é dividida e continua na seguinte. position: 'top' a transforma num flutuante no alto da página 6; posicionada 'here' ela se dividiria do mesmo jeito desde o postext 1.25, mas o texto depois dela começaria mais abaixo na página 7 e as últimas linhas passariam para uma oitava página. O corte cai entre linhas e nunca atravessa uma célula mesclada, e cada defeito fica na mesma página que suas causas (tabelas mais altas que a página). Ela é citada na página 5 e abre a página 6, a primeira depois da citação que uma flutuante no topo pode ocupar. fold põe as duas metades de uma lista lado a lado, na legenda e nos dados técnicos, e a legenda centraliza os chips de número com align: 'center'.
#7 · Um endereço web e um código para quem lê no papel
A seção de descarte manda o leitor ao buscador de pontos de coleta da Stiftung EAR, o registro alemão de aparelhos usados, com um link Markdown comum. Na tela e no PDF ele continua sendo um link; no papel não dá para segui-lo, então links: { print: 'notes', show: 'both' } acrescenta uma chamada depois do texto do link e compõe o endereço no pé da página ao lado de um código QR. urlDisplay: 'short' tira https:// e a barra final do endereço impresso, e qr: { size: mm(12), side: 'start' } põe um código de 12 mm antes da linha da nota. As notas de link são notas de rodapé, então footnotes define o corpo, a cor e o fio delas. A nota ocupa três linhas da página 7; por isso o parágrafo de descarte, uma solução da tabela e o colofão foram encurtados, e o manual continua com sete páginas (links na edição impressa).
A receita completa
// ═══ Postext Cookbook · Nº 050 · Product manual with safety notices ════════════════
// https://postext.dev/en/cookbook/product-manual-warnings
// Code: MIT · Text: original, in German (CC BY 4.0) · Drawings: generated in code (CC BY 4.0)
// Fonts: Red Hat Text, Red Hat Display, Red Hat Mono (SIL OFL 1.1) · Needs postext ≥ 1.65.0
import {
buildDocumentWithFonts, prepareFonts, renderPageToCanvas, registerResourceImage, parseTSV,
mergeCells, defaultResourceTypes, inlineSvgFonts } from 'https://esm.sh/postext';
const LANG = 'en'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'product-manual-warnings';
// ─── 1 · Design ─────────────────────────────────────────────────────────────
const palette = { ink: '#1a1f24', paper: '#ffffff', // a blue-black on white
brand: '#10727b', tint: '#e4f0f1', // the house teal (5.7:1 on white) and its pale tint
warning: '#d62e1f', caution: '#f2a900', // the signal colours of WARNUNG and VORSICHT
rule: '#cfd5da', muted: '#5b6570' }; // hairlines; running heads and notes
// 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.brand }) // the defaults
.map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
const [TEXT, DISPLAY, MONO] = ['Red Hat Text', 'Red Hat Display', 'Red Hat Mono'];
const PAGE = { w: 148, h: 210, top: 19, bottom: 19.4, inner: 17, outer: 13 }; // mm: A5, mirrored
const LEAD = 12.8; // pt: the body's leading and baseline grid, 38 lines to the page
const pin = (to, edge, x = 0, y = 0, size) => ({ anchor: { to, edge },
offset: { x: mm(x), y: mm(y) }, ...(size && { size }) });
const pad = (y, x = 0) => ({ top: pt(y), bottom: pt(y), left: pt(x), right: pt(x) }); // pt
// #region answer: signal-word boxes: a band in the hazard's colour carries its triangle
const BAND = 8.5; // mm: a stripe on the side is the icon's column; the icon is centred on it
const [TITLE, TITLE_GAP] = [8.6, 2.4]; // pt; a box title's line is 1.2 times its size
const PAD_Y = (2 * LEAD - 1.2 * TITLE - TITLE_GAP) / 2; // pt: title and padding fill two lines
const notice = (id, hue, ink, icon) => ({ id, backgroundEnabled: false,
stripe: { enabled: true, side: 'left', width: mm(BAND), color: col(hue) },
border: { enabled: true, color: col(hue), width: pt(0.75) }, // closes the band into a frame
icon: { kind: 'resource', resourceId: icon, size: mm(5.6), align: 'top' },
padding: { top: pt(PAD_Y), right: mm(3.2), bottom: pt(PAD_Y), left: mm(3.2) },
titleStyle: { fontFamily: DISPLAY, fontWeight: 800, fontSize: pt(TITLE), color: col(ink),
textTransform: 'uppercase', letterSpacing: pt(1.3), gap: pt(TITLE_GAP) },
body: { fontSize: pt(8.8), lineHeight: pt(LEAD) }, // on the grid: a box is whole lines tall
lists: { color: col(ink), gap: mm(2) }, marginTop: pt(LEAD), marginBottom: pt(0) });
const calloutStyles = [
notice('warnung', 'warning', 'warning', 'triangle-white'), // white triangle, red '!'
notice('vorsicht', 'caution', 'ink', 'triangle-ink'), // amber type would fail contrast
{ ...notice('hinweis', 'brand', 'brand'), stripe: { enabled: false }, border: { enabled: false },
backgroundEnabled: true, background: col('tint'), borderRadius: mm(2), // property damage:
icon: { kind: 'resource', resourceId: 'info', size: mm(4.6) } }, // no band, an icon column
];
// #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
#Numere figuras e tabelas por seção
Com o número da seção no modelo e um reinício em cada seção, o desenho vira Abbildung 2.1 e a tabela de solução de problemas, Tabelle 5.1.
-const counted = { numberingTemplate: '{n}', resetOn: 'never', counterFormat: 'decimal' }; // 1, 2…
+const counted = { numberingTemplate: '{h1}.{n}', resetOn: 'h1', counterFormat: 'decimal' };Erros comuns
Erro comum
Um flutuante 'top' vai para a página seguinte à sua citação, a menos que possa encabeçar a página que o cita
Por padrão um flutuante nunca fica acima da própria referência, então um flutuante 'top' na largura da página citado na página N abre a página N+1. Com placement.citingPage: true no recurso ou no defaultPlacement do seu tipo (ou layout.floatsAtCitingPage para o livro todo, desde o postext 1.25) ele encabeça a página N, e o texto acima da referência desce para baixo dele, quando cabe dentro de layout.maxTopFraction e a linha que o cita continua nessa página. Nunca encabeça a primeira página de um capítulo nem uma página depois de uma quebra forçada: ali continua abrindo a página seguinte, e 'auto' ou 'bottom' podem ocupar o pé da página que o cita. Posicionamento de figuras →
Erro comum
O número de uma lista é centralizado na primeira linha, não apoiado na linha de base
O número de uma lista numerada é pintado com a linha de base 'middle' do canvas, 0,3 em do texto acima da primeira linha de base do item, então um número em outra fonte ou com numberFontSize maior cresce para cima e para baixo a partir daí, em vez de se apoiar na linha: uma fonte de display fica alta, e um número grande de passo fica pendurado sobre a primeira linha. Posicione-o com orderedLists.numberVerticalOffset e confira o resultado em tamanho real. Os números do sumário se apoiam na linha de base desde o postext 1.5; os das listas continuam centralizados. Listas numeradas →
- O equilíbrio de colunas empurra um box que fecha uma página até a última linha da grade, e todo o espaço que sobra na página se abre acima do box (equilíbrio de colunas). O texto da página 2 foi ajustado para encher a coluna sem sobra. Apague um marcador de VORSICHT e o box continua terminando no pé, mas o espaço entre os dois boxes passa de 4,5 para 13,6 mm; com
headings: { balancing: { enabled: false } }, o box fica uma linha abaixo de WARNUNG e a página termina duas linhas antes do pé.
Créditos
- Receita
- Ignacio Ferro
- Texto
- Texto original, CC BY 4.0
- Fontes
- Red Hat Text (SIL OFL 1.1) · Red Hat Display (SIL OFL 1.1) · Red Hat 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)


