Saltar al contingut principal
Recepta número 50

Receptari · Capítol 6 · Requadres i notes

Manual de producte amb avisos de seguretat

Manual d'un bullidor en alemany: els requadres WARNUNG i VORSICHT porten el triangle en una franja del color d'avís, i els peus diuen Abbildung i Tabelle.

  • Mostra en castellà: encara no hi ha edició en català
  • Format 148 × 210 mm
  • 1 columna
  • Red Hat Text 9,3/12,8
  • Red Hat Display
  • Red Hat Mono
  • 7 pàgines
  • Nivell
  • Postext 1.65.0
  • Compost en 150 ms
  • 184 línies de codi

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

script.js · línies 29–47al codi complet
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

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

script.js · línies 51–59al codi complet
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

script.js · línies 63–71al codi complet
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

script.js · línies 75–80al codi complet
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

script.js · línies 84–94al codi complet
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

script.js · línies 297–315al codi complet
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

Sandbox
// ═══ 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

Les cel·les combinades necessiten hiddenBy: fes servir mergeCells

Les cel·les es col·loquen segons la seva posició a la fila, així que una cel·la combinada necessita cel·les de farciment marcades amb hiddenBy on s'estén; ometre-les, com en HTML, desplaça totes les columnes següents. Combina cel·les amb mergeCells. Des de postext 1.5 una taula amb una graella irregular s'anota a doc.contentWarnings com a raggedTableGrid, i parseTSV(text, { headerRows }) marca les files de capçalera. Taules a partir de dades →

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

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)
Sandbox