En poques paraules
Un manual d'instruccions de set pàgines, en alemany, per a un bullidor elèctric. Mostra com crear requadres de seguretat amb el triangle d'advertiment, en vermell o ambre segons el nivell de perill.
Què compondràs
Un manual de set pàgines per al Verra W1, un bullidor inventat, en alemany i en A5. A la pàgina de seguretat, els dos nivells de perill van en requadres: a l'esquerra baixa una franja del color d'avís amb el triangle d'advertiment, i un marc fi del mateix color tanca el requadre, vermell a WARNUNG i ambre a VORSICHT. HINWEIS, que avisa de danys a l'aparell, canvia franja i triangle per un fons verd blavós de cantonades arrodonides. Abans dels requadres, un paràgraf presenta les tres paraules d'advertiment en xips plens. A la pàgina 3, un dibuix amb línies de referència numerades va sobre la seva llegenda, i a la 4 les tecles són xips perfilats al costat de números de pas grans. La taula d'avaries ocupa les pàgines 6 i 7. Els peus diuen Abbildung i Tabelle, i la taula partida, Fortsetzung.
Aquesta recepta respon a
- Com faig requadres de nota, consell o advertiment amb icona, franja de color i cantonades arrodonides?
- Com faig xips en línia: tecles, etiquetes, bancs de paraules per a exercicis?
- Com personalitzo les llistes: pics per nivell, numeració (a)/(i), caselles de tasques i un espaiat que respecti la retícula?
- Com afegeixo una figura amb peu numerat i la cito en el text («vegeu la fig. 3.2»)?
- Com faig una taula amb files de capçalera, cel·les combinades, amplades de columna i alineació per cel·la?
- Com parteixo una taula llarga entre pàgines amb la capçalera repetida i un avís de «continua»?
- Com aconsegueixo les etiquetes «Figura» i «Taula» en la llengua del meu document?
La 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
];
Ingredients
- Funcions
- Icones i distintius de cantonadaRequadresTipus de recurs propisAdreces dels enllaços en paperChips en líniaCites que col·loquen les figuresFigures just aquíCol·locació de figuresTaules a partir de dadesEstil de taulesTaules que passen de pàginaTítols numeratsLlistes numeradesPartició de mots i llengua del documentFigura i Taula en la teva llenguaObertures dissenyadesEstils de títolCobertes, portades i colofonsCapçaleres i folisTextos, filets i caixes als dissenys de pàgina
- També fa servir
- Notes a peu de pàginaAtributs de títolSalts de pàgina i de columnaCapçaleres segons el tipus de pàginaEstils de paràgrafFigures i taules com a recursosEstils de taula amb nomCapítols sense número
- Tipografia
- Red Hat Text, Red Hat Display, Red Hat Mono (SIL OFL 1.1)
- Recursos
- Cap: totes les imatges es dibuixen en codi
Elaboració
#1 · Una franja que porta el triangle
El codi és el de la resposta curta, més amunt. stripe pinta la franja per la vora esquerra. Quan un requadre porta franja lateral, la icona se centra sobre la franja en lloc d'ocupar una columna pròpia (estils de requadre), i align: 'top' alinea la vora superior de la icona amb la del títol. El border del mateix color converteix la franja en el costat gruixut d'un marc; sense ell, el text del requadre quedaria solt a la pàgina, al costat d'una barra de color. PAD_Y està calculat perquè el títol, la seva separació i els farciments superior i inferior sumin dues línies de la retícula de 12,8 pt. El cos manté l'interlineat de la retícula, així que cada requadre mesura un nombre enter de línies (10 el de WARNUNG, 8 el de VORSICHT), i marginTop: pt(LEAD) deixa exactament una línia entre els dos requadres de la pàgina 2. A VORSICHT, l'ambre es queda a la franja i el marc, i el títol i els pics van en el color del text: l'ambre sobre blanc dona un contrast de 2,0:1, i la lletra petita necessita 4,5:1. HINWEIS parteix de la mateixa base (...notice(…)) i desactiva la franja i el marc, de manera que la seva icona d'informació ocupa una columna pròpia i borderRadius arrodoneix un fons llis.
#2 · Noms alemanys per a figures i taules
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' };
Amb locale: 'de', la partició de mots és l'alemanya i els tipus integrats porten noms alemanys: sense res més, els peus dirien Abbildung 2.1 i Tabelle 5.1, i sota la primera part de la taula partida es llegiria Wird fortgesetzt. L'estil de taula escriu sencers aquest avís i el sufix del peu, i defaultResourceTypes('de') es passa per dos canvis. El primer és counted: {n} amb resetOn: 'never' numera correlativament tot el manual (Abbildung 1, Tabelle 1 a 3) en lloc de tornar a començar a cada secció. Només el tipus de taula fixa captionStyle.position: 'above', així que les taules porten el peu damunt de la capçalera i el dibuix el manté a sota.
#3 · Tecles, paraules d'advertiment i números de peça com a xips
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 envolta amb un filet el nom d'una tecla, en Red Hat Mono i sense farciment, tal com el porta imprès el botó. Els xips de les paraules d'advertiment van plens del color del seu requadre, i l'ambre porta la paraula en el color del text, igual que el títol de VORSICHT. nr dona als números de peça un radi més gran que la meitat de la seva alçada, així que surten rodons, com els cercles numerats del dibuix. La mida dels xips es dona en em del text que els envolta: una tecla mesura 8,6 pt al text corregut i 7,5 pt en una cel·la de taula (estils de xip).
#4 · Números de pas sobre la línia 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 –
Els passos són una llista numerada amb les xifres en Red Hat Display 800 a 15 pt, en verd blavós i sense separador. El número d'una llista se centra a la seva primera línia en comptes de recolzar-se a la línia de base, així que una xifra de 15 pt al costat de text de 9,3 pt queda prop d'1 pt per sota de la línia. numberVerticalOffset: pt(-1), un valor mesurat a la captura, puja el seu peu fins a la línia de base. itemSpacing separa els passos 5 pt per deixar lloc a les xifres grans. Els pics niats sota un pas comencen a 6,5 mm, a l'alçada del text del pas; són guions verd blavós, i els del tercer nivell, grisos (llistes numerades).
#5 · Números de secció en una pestanya 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 secció és un títol de primer nivell dins de la columna, dibuixat amb una zona de disseny. La pestanya imprimeix {number} (l'omple numberingTemplate: '{1}') en blanc sobre un quadrat verd blavós, i el títol comença 3 mm a la seva dreta. Número i títol comparteixen cos i interlineat, així que el mateix farciment superior els assenta a la mateixa línia de base. La pestanya és un quadrat de 22 pt, 3,6 pt menys que dues línies de la retícula de 12,8 pt, de manera que pestanya i títol caben en dues línies de retícula. La coberta també és un títol de primer nivell, amb un estil d'encapçalament sense número, així que Sicherheitshinweise és la secció 1.
#6 · Una taula d'avaries amb cel·les combinades que es parteix
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 taula és un TSV en un fitxer de contingut propi. A les dades d'avaries, una línia amb la primera cel·la buida pertany a l'avaria anterior; mergeCells uneix aquestes primeres cel·les en una sola cel·la alta i marca com a ocultes les que cobreix. parseTSV no fixa cap fila de capçalera, així que la declara headerRowCount: 1, i aquesta és la fila que es repeteix a la pàgina 7. La taula és més alta que una pàgina, així que es parteix i continua a la següent. position: 'top' la converteix en un flotant al capdamunt de la pàgina 6; col·locada 'here' es partiria igual des de postext 1.25, però el text que la segueix començaria més avall a la pàgina 7 i les últimes línies passarien a una vuitena pàgina. El tall cau entre dues files i no travessa mai una cel·la combinada, així que cada avaria queda a la mateixa pàgina que les seves causes (taules més altes que la pàgina). Es cita a la pàgina 5 i encapçala la 6, la primera pàgina després de la cita que pot ocupar un flotant top. fold col·loca les dues meitats d'una llista l'una al costat de l'altra, a la llegenda i a les dades tècniques, i la llegenda centra els seus xips de número amb align: 'center'.
#7 · Una adreça web i un codi per a qui llegeix en paper
La secció d'eliminació remet al cercador de punts de recollida de la Stiftung EAR, el registre alemany d'aparells vells, amb un enllaç Markdown corrent. En pantalla i al PDF continua sent un enllaç; en paper no es pot seguir, així que links: { print: 'notes', show: 'both' } afegeix una crida després del text de l'enllaç i compon l'adreça al peu de la pàgina al costat d'un codi QR. urlDisplay: 'short' treu https:// i la barra final de l'adreça impresa, i qr: { size: mm(12), side: 'start' } posa un codi de 12 mm davant de la línia de la nota. Les notes d'enllaç són notes al peu, així que footnotes en fixa el cos, el color i el filet. La nota ocupa tres línies de la pàgina 7; per això es van escurçar el paràgraf d'eliminació, un remei de la taula i el colofó, i el manual es manté en set pàgines (enllaços en paper).
La recepta 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 = 'es'; // @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
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
#Numera figures i taules per secció
Amb el número de secció a la plantilla i un reinici a cada secció, el dibuix passa a ser Abbildung 2.1 i la taula d'avaries, Tabelle 5.1.
-const counted = { numberingTemplate: '{n}', resetOn: 'never', counterFormat: 'decimal' }; // 1, 2…
+const counted = { numberingTemplate: '{h1}.{n}', resetOn: 'h1', counterFormat: 'decimal' };Errors freqüents
Error freqüent
Un flotant 'top' va a la pàgina següent a la seva cita tret que pugui encapçalar la pàgina que el cita
Per defecte un flotant no va mai per sobre de la seva pròpia referència, així que un flotant 'top' a tota l'amplada citat a la pàgina N obre la pàgina N+1. Amb placement.citingPage: true al recurs o al defaultPlacement del seu tipus (o layout.floatsAtCitingPage per a tot el llibre, des de postext 1.25) encapçala en canvi la pàgina N, i el text de damunt de la referència baixa sota seu, quan hi cap dins de layout.maxTopFraction i la línia que el cita continua en aquesta pàgina. No encapçala mai la primera pàgina d'un capítol ni una pàgina després d'un salt forçat: allà continua obrint la pàgina següent, i 'auto' o 'bottom' poden ocupar el peu de la pàgina que el cita. Col·locació de figures →
Error freqüent
El número d'una llista es centra a la primera línia, no es recolza en la línia de base
El número d'una llista numerada es pinta amb la línia de base «middle» del canvas, 0,3 em del text per sobre de la primera línia de base de l'element, així que un número en una altra font o amb un numberFontSize més gran creix cap amunt i cap avall des d'allà en lloc de recolzar-se en la línia: una font de retolació queda alta i un número de pas gran penja sobre la primera línia. Col·loca'l amb orderedLists.numberVerticalOffset i revisa el resultat a mida real. Els números de l'índex es recolzen en la línia de base des de postext 1.5; els de les llistes continuen centrats. Llistes numerades →
- L'equilibratge de columnes baixa un requadre que tanca una pàgina fins a l'última línia de la retícula, així que l'espai que sobra a la pàgina s'obre damunt seu (equilibri de columnes). El text de la pàgina 2 està ajustat per omplir la columna sense que sobri cap línia. Si treus un pic de VORSICHT, el requadre continua acabant al peu i la separació entre els dos requadres passa de 4,5 a 13,6 mm; amb
headings: { balancing: { enabled: false } }el requadre es queda una línia per sota de WARNUNG i la pàgina acaba dues línies abans del peu.
Crèdits
- Recepta
- Ignacio Ferro
- Text
- Text original, CC BY 4.0
- Fonts
- Red Hat Text (SIL OFL 1.1) · Red Hat Display (SIL OFL 1.1) · Red Hat Mono (SIL OFL 1.1)
- Codi
- MIT, com Postext
Editar aquest text ↗ (s'obre en una pestanya nova)Carpeta de la recepta a GitHub ↗ (s'obre en una pestanya nova)


