Saltar al contenido principal
Receta número 50

Recetario · Capítulo 6 · Recuadros y notas

Manual de producto con avisos de seguridad

Manual de un hervidor en alemán: los recuadros WARNUNG y VORSICHT llevan el triángulo en una franja del color de aviso, y los pies dicen Abbildung y Tabelle.

pp. 2–3 de 7

  • Formato 148 × 210 mm
  • 1 columna
  • Red Hat Text 9,3/12,8
  • Red Hat Display
  • Red Hat Mono
  • 7 páginas
  • Nivel
  • Postext 1.65.0
  • Compuesto en 150 ms
  • 184 líneas de código

En pocas palabras

Un manual de instrucciones de siete páginas, en alemán, para un hervidor eléctrico. Enseña a crear recuadros de seguridad con el triángulo de advertencia, en rojo o ámbar según el nivel de peligro.

Lo que vas a componer

Un manual de siete páginas para el Verra W1, un hervidor inventado, en alemán y en A5. En la página de seguridad, los dos niveles de peligro van en recuadros: a la izquierda baja una franja del color de aviso con el triángulo de advertencia, y un borde fino del mismo color cierra el recuadro, rojo en WARNUNG y ámbar en VORSICHT. HINWEIS, que avisa de daños en el aparato, cambia franja y triángulo por un fondo verde azulado de esquinas redondeadas. Antes de los recuadros, un párrafo presenta las tres palabras de advertencia en chips rellenos. En la página 3, un dibujo con líneas de referencia numeradas va sobre su leyenda, y en la 4 las teclas son chips perfilados junto a números de paso grandes. La tabla de averías ocupa las páginas 6 y 7. Los pies dicen Abbildung y Tabelle, y la tabla partida, Fortsetzung.

Esta receta responde a

  • ¿Cómo hago recuadros de nota, consejo o advertencia con icono, franja de color y esquinas redondeadas?
  • ¿Cómo hago chips en línea: teclas, etiquetas, bancos de palabras para ejercicios?
  • ¿Cómo personalizo las listas: viñetas por nivel, numeración (a)/(i), casillas de tareas y un espaciado que respete la rejilla?
  • ¿Cómo añado una figura con pie numerado y la cito en el texto («véase la fig. 3.2»)?
  • ¿Cómo hago una tabla con filas de cabecera, celdas combinadas, anchos de columna y alineación por celda?
  • ¿Cómo parto una tabla larga entre páginas con la cabecera repetida y un aviso de «continúa»?
  • ¿Cómo consigo las etiquetas «Figura» y «Tabla» en el idioma de mi documento?

La respuesta corta

script.js · líneas 29–47en el código completo
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

Tipografía
Red Hat Text, Red Hat Display, Red Hat Mono (SIL OFL 1.1)
Recursos
Ninguno: todas las imágenes se dibujan en código

Elaboración

#1 · Una franja que lleva el triángulo

El código es el de la respuesta corta, más arriba. stripe pinta la franja por el borde izquierdo. Cuando un recuadro lleva franja lateral, el icono se centra sobre ella en lugar de ocupar una columna propia (estilos de recuadro), y align: 'top' alinea el borde superior del icono con el del título. El border del mismo color convierte la franja en el lado grueso de un borde; sin él, el texto del recuadro quedaría suelto en la página, al lado de una barra de color. PAD_Y está calculado para que el título, su separación y los rellenos superior e inferior sumen dos líneas de la rejilla de 12,8 pt. El texto base mantiene el interlineado de la rejilla, así que cada recuadro mide un número entero de líneas (10 el de WARNUNG, 8 el de VORSICHT), y marginTop: pt(LEAD) deja exactamente una línea entre los dos recuadros de la página 2. En VORSICHT, el ámbar se queda en la franja y el marco, y el título y las viñetas van en el color del texto: el ámbar sobre blanco da un contraste de 2,0:1, y la letra pequeña necesita 4,5:1. HINWEIS parte de la misma base (...notice(…)) y desactiva la franja y el marco, de modo que su icono de información ocupa una columna propia y borderRadius redondea un fondo liso.

#2 · Nombres alemanes para figuras y tablas

script.js · líneas 51–59en el código completo
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' };

Con locale: 'de', la separación silábica es la alemana y los tipos integrados llevan nombres alemanes: sin nada más, los pies dirían Abbildung 2.1 y Tabelle 5.1, y bajo la primera parte de la tabla partida se leería Wird fortgesetzt. El estilo de tabla escribe enteros ese aviso y el sufijo del pie, y defaultResourceTypes('de') se pasa por dos cambios. El primero es counted: {n} con resetOn: 'never' numera de corrido todo el manual (Abbildung 1, Tabelle 1 a 3) en lugar de volver a empezar en cada sección. Solo el tipo de tabla fija captionStyle.position: 'above', así que las tablas llevan el pie encima de la cabecera y el dibujo lo mantiene debajo.

#3 · Teclas, palabras de advertencia y números de pieza como chips

script.js · líneas 63–71en el código completo
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 rodea con un filete el nombre de una tecla, en Red Hat Mono y sin relleno, como lo lleva impreso el botón. Los chips de las palabras de advertencia van rellenos del color de su recuadro, y el ámbar lleva la palabra en el color del texto, igual que el título de VORSICHT. nr da a los números de pieza un radio mayor que la mitad de su altura, así que salen redondos, como los círculos numerados del dibujo. El tamaño de los chips se da en em del texto que los rodea: una tecla mide 8,6 pt en el texto corrido y 7,5 pt en una celda de tabla (estilos de chip).

#4 · Números de paso sobre la línea base

script.js · líneas 75–80en el código completo
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 –

Los pasos son una lista numerada con las cifras en Red Hat Display 800 a 15 pt, en verde azulado y sin separador. El número de una lista se centra en su primera línea en vez de apoyarse en la línea base, así que una cifra de 15 pt junto a texto de 9,3 pt queda cerca de 1 pt por debajo de la línea. numberVerticalOffset: pt(-1), un valor medido en la captura, sube su pie hasta la línea base. itemSpacing separa los pasos 5 pt para dejar sitio a las cifras grandes. Las viñetas anidadas bajo un paso empiezan a 6,5 mm, a la altura del texto del paso; son guiones verde azulado, y los del tercer nivel, grises (listas ordenadas).

#5 · Números de sección en una pestaña invertida

script.js · líneas 84–94en el código completo
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ón es un encabezado de primer nivel dentro de la columna, dibujado con una zona de diseño. La pestaña imprime {number} (lo rellena numberingTemplate: '{1}') en blanco sobre un cuadrado verde azulado, y el título empieza 3 mm a su derecha. Número y título comparten cuerpo e interlineado, así que el mismo relleno superior los asienta en la misma línea base. La pestaña es un cuadrado de 22 pt, 3,6 pt menos que dos líneas de la rejilla de 12,8 pt, de modo que pestaña y título caben en dos líneas de rejilla. La cubierta también es un encabezado de primer nivel, con un estilo de encabezado sin número, así que Sicherheitshinweise es la sección 1.

#6 · Una tabla de averías con celdas combinadas que se parte

script.js · líneas 297–315en el código completo
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 tabla es un TSV en un archivo de contenido propio. En los datos de averías, una línea con la primera celda vacía pertenece a la avería anterior; mergeCells une esas primeras celdas en una sola celda alta y marca como ocultas las que cubre. parseTSV no fija ninguna fila de cabecera, así que la declara headerRowCount: 1, y esa es la fila que se repite en la página 7. La tabla es más alta que una página, así que se parte y sigue en la siguiente. position: 'top' la convierte en un flotante en la cabeza de la página 6; colocada 'here' se partiría igual desde postext 1.25, pero el texto que la sigue empezaría más abajo en la página 7 y las últimas líneas pasarían a una octava página. El corte cae entre dos filas y nunca atraviesa una celda combinada, así que cada avería queda en la misma página que sus causas (tablas más altas que la página). Se cita en la página 5 y encabeza la 6, la primera página tras la cita que puede ocupar un flotante top. fold coloca las dos mitades de una lista una al lado de la otra, en la leyenda y en los datos técnicos, y la leyenda centra sus chips de número con align: 'center'.

#7 · Una dirección web y un código para quien lee en papel

La sección de eliminación remite al buscador de puntos de recogida de la Stiftung EAR, el registro alemán de aparatos usados, con un enlace Markdown corriente. En pantalla y en el PDF sigue siendo un enlace; en papel no se puede seguir, así que links: { print: 'notes', show: 'both' } añade una llamada tras el texto del enlace y compone la dirección al pie de la página junto a un código QR. urlDisplay: 'short' quita https:// y la barra final de la dirección impresa, y qr: { size: mm(12), side: 'start' } pone un código de 12 mm delante de la línea de la nota. Las notas de enlace son notas al pie, así que footnotes fija su cuerpo, su color y su filete. La nota ocupa tres líneas de la página 7, por eso se acortaron el párrafo de eliminación, un remedio de la tabla y el colofón, y el manual sigue en siete páginas (enlaces en papel).

La receta 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

El script.js compuesto funciona tal cual: pégalo como script de módulo en cualquier página o abre la receta en CodePen. Carpeta de la receta en GitHub ↗ (se abre en una nueva pestaña)

Variantes

#Numera figuras y tablas por sección

Con el número de sección en la plantilla y un reinicio en cada sección, el dibujo pasa a ser Abbildung 2.1 y la tabla de averías, Tabelle 5.1.

-const counted = { numberingTemplate: '{n}', resetOn: 'never', counterFormat: 'decimal' }; // 1, 2…
+const counted = { numberingTemplate: '{h1}.{n}', resetOn: 'h1', counterFormat: 'decimal' };

Errores frecuentes

Error frecuente

Un flotante 'top' va a la página siguiente a su cita salvo que pueda encabezar la página que lo cita

Por defecto un flotante nunca va por encima de su propia referencia, así que un flotante 'top' a todo el ancho citado en la página N abre la página N+1. Con placement.citingPage: true en el recurso o en el defaultPlacement de su tipo (o layout.floatsAtCitingPage para todo el libro, desde postext 1.25) encabeza en cambio la página N, y el texto de encima de la referencia baja bajo él, cuando cabe dentro de layout.maxTopFraction y la línea que lo cita sigue en esa página. Nunca encabeza la primera página de un capítulo ni una página tras un salto forzado: allí sigue abriendo la página siguiente, y 'auto' o 'bottom' pueden ocupar el pie de la página que lo cita. Colocación de figuras →

Error frecuente

Las celdas combinadas necesitan hiddenBy: usa mergeCells

Las celdas se colocan según su posición en la fila, así que una celda combinada necesita celdas de relleno marcadas con hiddenBy donde se extiende; omitirlas, como en HTML, desplaza todas las columnas siguientes. Combina celdas con mergeCells. Desde postext 1.5 una tabla con una rejilla irregular se anota en doc.contentWarnings como raggedTableGrid, y parseTSV(texto, { headerRows }) marca las filas de cabecera. Tablas a partir de datos →

Error frecuente

El número de una lista se centra en su primera línea, no se apoya en la línea base

El número de una lista numerada se pinta con la línea base «middle» del canvas, 0,3 em del texto por encima de la primera línea base del elemento, así que un número en otra fuente o con un numberFontSize mayor crece hacia arriba y hacia abajo desde ahí en vez de apoyarse en la línea: una fuente de rótulo queda alta y un número grande de paso cuelga sobre la primera línea. Colócalo con orderedLists.numberVerticalOffset y revisa el resultado a tamaño real. Los números del índice se apoyan en la línea base desde postext 1.5; los de las listas siguen centrados. Listas numeradas →

  • El equilibrado de columnas baja un recuadro que cierra una página hasta la última línea de la rejilla, así que el espacio que sobra en la página se abre encima de él (equilibrado de columnas). El texto de la página 2 está ajustado para llenar la columna sin que sobre ninguna línea. Si borras una viñeta de VORSICHT, el recuadro sigue acabando al pie y la separación entre los dos recuadros pasa de 4,5 a 13,6 mm; con headings: { balancing: { enabled: false } } el recuadro se queda una línea por debajo de WARNUNG y la página termina dos líneas antes del pie.

Créditos

Texto
Texto original, CC BY 4.0
Fuentes
Red Hat Text (SIL OFL 1.1) · Red Hat Display (SIL OFL 1.1) · Red Hat Mono (SIL OFL 1.1)
Sandbox