Saltar al contenido principal
Receta número 41

Recetario · Capítulo 10 · Salida e integración

Ida y vuelta de un .postext en dos idiomas

Un folleto DL a doble cara guardado en un archivo .postext y compuesto de nuevo a partir de sus bytes, con las fuentes, los dibujos y las etiquetas que lleva.

En esta página
  • Formato 99 × 210 mm
  • 1 columna
  • DM Sans 9,4/13,4
  • DM Serif Display
  • Instrument Sans
  • 2 páginas
  • Nivel
  • Postext 1.57.1
  • Compuesto en 64 ms
  • 178 líneas de código

En pocas palabras

Un folleto de dos caras de un antiguo molino de marea, en inglés y en español. Enseña a guardar un documento con sus fuentes e imágenes en un solo archivo y a sacar de él las mismas páginas.

Lo que vas a componer

Las dos caras de un folleto DL de visita, de 99 × 210 mm, para un molino de mareas en una ría inventada. La portada es un solo dibujo: una rueda de molino en la línea del agua, con la mitad superior sobre la arena y la inferior pálida bajo el azul del agua, el título en DM Serif Display cursiva de 50 pt y una pestaña azul con el código de la edición, ES o EN. El dorso empieza con el molino en sección y sigue con el texto en DM Sans justificada, el horario en una tabla con la cabecera en azul, pies en Instrument Sans, un colofón y una franja azul con la fundación que lo edita. Cada edición se escribe en un archivo .postext, y cada página que ves se compone a partir de los bytes de ese archivo, con las fuentes y los dibujos que lleva dentro.

Esta receta responde a

  • ¿Cómo abro un archivo .postext y lo pinto con sus propias fuentes, imágenes y configuración?
  • ¿Cómo creo un paquete .postext desde el código para pasar un documento al Sandbox o a otro programa?
  • ¿Cómo publico el mismo libro en dos idiomas desde un solo proyecto?
  • ¿Cómo consigo las etiquetas «Figura» y «Tabla» en el idioma de mi documento?

La respuesta corta

script.js · líneas 294–310en el código completo
// The writer: text, design, resources and every file they name, zipped. createBundle looks
// up each fileId (a drawing's svg.fileId, a face's variant fileId) in `files`.
const { bytes, warnings } = await createBundle({
  name: t({ en: 'The Tide Mill of Arenal', es: 'El molino de mareas de Arenal' }),
  locale: LANG, // one language per file; `localized` would add the other edition to it
  markdown, config: config(), resources,
  files: { ...drawings, ...faceFiles },
  thumbnail: { data: drawings['cover.svg'], mime: 'image/svg+xml' }, // the book's picture
});
if (warnings.length) console.warn(warnings); // what was left out, and why

// The reader has nothing but the bytes. Each fileId is now the file's path inside the zip:
// mill.svg is resources/mill.svg, and the faces sit under fonts/.
const bundle = await openBundle(bytes);
await loadBundleFonts(bundle); // one FontFace per face from the file, in place of loadFonts()
await registerBundleImages(bundle); // the drawings, for the canvas
const docs = buildBundle(bundle); // one VDTDocument per chapter: a leaflet has one

Ingredientes

Tipografía
DM Sans, DM Serif Display, Instrument Sans (SIL OFL 1.1)
Recursos
Ninguno: todas las imágenes se dibujan en código

Elaboración

#1 · Escribe la edición y vuelve a leer solo los bytes

script.js · líneas 294–310en el código completo
// The writer: text, design, resources and every file they name, zipped. createBundle looks
// up each fileId (a drawing's svg.fileId, a face's variant fileId) in `files`.
const { bytes, warnings } = await createBundle({
  name: t({ en: 'The Tide Mill of Arenal', es: 'El molino de mareas de Arenal' }),
  locale: LANG, // one language per file; `localized` would add the other edition to it
  markdown, config: config(), resources,
  files: { ...drawings, ...faceFiles },
  thumbnail: { data: drawings['cover.svg'], mime: 'image/svg+xml' }, // the book's picture
});
if (warnings.length) console.warn(warnings); // what was left out, and why

// The reader has nothing but the bytes. Each fileId is now the file's path inside the zip:
// mill.svg is resources/mill.svg, and the faces sit under fonts/.
const bundle = await openBundle(bytes);
await loadBundleFonts(bundle); // one FontFace per face from the file, in place of loadFonts()
await registerBundleImages(bundle); // the drawings, for the canvas
const docs = buildBundle(bundle); // one VDTDocument per chapter: a leaflet has one

createBundle comprime en un zip el capítulo, la configuración, los recursos y todos los archivos que citan, y openBundle no recibe más que esos bytes. Las fuentes salen de loadBundleFonts, los dibujos de registerBundleImages y el diseño de bundle.config. Una fuente que no esté en files sale con la fuente de reserva del navegador, y un dibujo que falte se descarta con un aviso y su remisión se imprime como (?). Dentro del zip, cada fileId pasa a ser una ruta (mill.svg es ahora resources/mill.svg), y los recursos y el customFonts que devuelve openBundle ya usan los nombres nuevos (abrir un paquete).

#2 · Mete las fuentes en el archivo

script.js · líneas 277–289en el código completo
const customFonts = Object.entries(FONTS).map(([name, specs]) => ({ name,
  variants: specs.map((spec) => ({ weight: parseInt(spec, 10), format: 'woff2',
    style: spec.endsWith('i') ? 'italic' : 'normal', fileId: `${fontsourceId(name)}-${spec}` })),
}));
// The bytes: Fontsource's static woff2 files, latin subset, which covers the Spanish text too.
const faceFiles = Object.fromEntries(await Promise.all(customFonts.flatMap(({ name, variants }) =>
  variants.map(async ({ weight, style, fileId }) => {
    const id = fontsourceId(name);
    const res = await fetch(`https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/files/`
      + `${id}-latin-${weight}-${style}.woff2`);
    if (!res.ok) throw new Error(`Fontsource has no ${name} ${weight} ${style}`);
    return [fileId, new Uint8Array(await res.arrayBuffer())];
  }))));

Un paquete lleva una fuente cuando customFonts la declara y files guarda sus bytes con el fileId de la variante; createBundle guarda la DM Sans 400 como fonts/dm-sans-400-normal.woff2. El pen descarga de Fontsource los siete woff2, pero no registra ninguno: loadBundleFonts añade a document.fonts las copias del paquete antes de que buildBundle mida una sola línea, y el PDF saca sus fuentes de esos mismos siete archivos.

#3 · Nombra cada archivo por su fileId

script.js · líneas 234–267en el código completo
const svg = (id, w, h, altText, extra) => ({ id, typeId: 'figure', kind: 'svg', createdAt: 0,
  updatedAt: 0, altText, svg: { fileId: `${id}.svg`, width: w * 10, height: h * 10 }, ...extra });
const row = (...cells) => cells.map((content) => ({ content }));
const head = (...cells) => cells.map((content) => ({ content, isHeader: true }));
const resources = [
  svg('cover', PAGE.w, PAGE.h, t({ en: 'A mill wheel on the waterline, its lower half pale '
    + 'under the estuary', es: 'Una rueda de molino en la línea del agua, con la mitad '
    + 'inferior pálida bajo la ría' })),
  svg('mill', SECTION.w, SECTION.h, t({
    en: 'The mill in section: the pond at high level on the left, the mill house on the dam '
      + 'with its millstones, the horizontal wheel in the vaulted pit, and the estuary on the '
      + 'right below a dashed high-water line',
    es: 'El molino en sección: el estanque a nivel alto a la izquierda, la casa del molino sobre '
      + 'la presa con sus muelas, el rodezno en el cárcavo abovedado y la ría a la derecha, bajo '
      + 'una línea discontinua de pleamar' }), {
    placement: { position: 'here' },
    caption: t({ en: 'Two hours after high water: the pond turns the wheel, and the estuary '
      + 'has fallen below the dashed line.',
    es: 'Dos horas tras la pleamar: el estanque mueve el rodezno y la ría ha quedado por debajo '
      + 'de la línea discontinua.' }) }),
  { id: 'hours', typeId: 'table', kind: 'table', createdAt: 0, updatedAt: 0,
    placement: { position: 'here' },
    caption: t({ en: 'Opening hours. Last entry 45 minutes before closing.',
      es: 'Horario. Última entrada 45 minutos antes del cierre.' }),
    table: { model: { headerRowCount: 1, columnWidths: [1.55, 0.9, 1.55], rows: t({
      en: [head('Season', 'Days', 'Hours'),
        row('April–June', 'Tue–Sun', '10:00–14:00, 16:00–19:00'),
        row('July–August', 'Mon–Sun', '10:00–20:00'),
        row('September–March', 'Fri–Sun', '10:30–14:30')],
      es: [head('Temporada', 'Días', 'Horario'),
        row('Abril–junio', 'Mar.–dom.', '10:00–14:00 y 16:00–19:00'),
        row('Julio–agosto', 'Lun.–dom.', '10:00–20:00'),
        row('Septiembre–marzo', 'Vie.–dom.', '10:30–14:30')] }) } } },
];

Los dos dibujos son SVG que genera el propio pen y que se entregan en files con el svg.fileId de su recurso; la tabla son datos, así que viaja en preset.json con su pie. La sección y la tabla se colocan con position: 'here': la sección en la cabeza del dorso y el horario bajo el párrafo que lo cita. El folleto fija layout.inlineResourceGap: 'above', que deja el aire de un recurso en línea solo por encima, y así el dorso cabe en una cara: el título que sigue a la sección trae su propio espacio, y una línea :::space{lines=0.5} tras la tabla deja 3,7 mm bajo el pie.

#4 · Mantén las etiquetas en el idioma del archivo

script.js · líneas 55–59en el código completo
  // Hyphenation patterns and the PDF's /Lang.
  locale: t({ en: 'en-us', es: 'es' }),
  // '{n}' numbers the figures 1, 2, 3: a leaflet has no chapters to number them by. Without
  // resourceTypes the reader builds Figure 1.1 or Figura 1.1, in the language of the file.
  resourceTypes: defaultResourceTypes(LANG).map((type) => ({ ...type, numberingTemplate: '{n}' })),

Quien abre un archivo crea los tipos integrados en el idioma que ese archivo sirve: sin resourceTypes en la configuración, el folleto en español imprime Figura 1.1 y Tabla 1.1 lo abra quien lo abra, también el Sandbox desde /en/sandbox. El folleto escribe los tipos solo por sus números: '{n}' quita el número de capítulo, que un folleto de dos páginas no necesita (tipos de recurso). La misma función config() fija locale, que elige los patrones de separación silábica del español (compuer-tas en el dorso) y el idioma que declara el PDF.

#5 · Entrega los mismos bytes

script.js · líneas 316–324en el código completo
const file = `tide-mill-${LANG}.postext`;
document.getElementById('pt-actions').append(Object.assign(document.createElement('a'), {
  href: URL.createObjectURL(new Blob([bytes], { type: 'application/zip' })), download: file,
  textContent: `Download ${file} · ${Math.round(bytes.length / 1024)} KB` }));
// The PDF embeds the faces the bundle carries, and draws the figures from its files.
offerPdf(() => renderToPdf(docs, {
  fontProvider: bundleFontProvider(bundle, { decodeWoff2: decompressWoff2 }),
  resourceBytes: bundleResourceBytes(bundle),
}), `${RECIPE}-${LANG}.pdf`);

El enlace ofrece los mismos bytes desde los que se compusieron las páginas: 132 KB con las fuentes. Al importarlo en el Sandbox (Libros → Nuevo → Abrir un archivo .postext…), el archivo se convierte en un libro en español o en inglés que lleva como imagen la rueda de thumbnail. El PDF toma sus fuentes de bundleFontProvider, que devuelve la del paquete más próxima en peso, con el mismo estilo si lo hay, y sus dibujos de bundleResourceBytes, así que no se descarga dos veces ninguna fuente ni imagen (componer y renderizar un paquete).

#6 · Dibuja la portada con un solo título

script.js · líneas 28–50en el código completo
const at = (x, y, width, edge = 'top-left') => ({ anchor: { to: 'page', edge },
  offset: { x: mm(x), y: mm(y) }, size: { width: mm(width) } });
const text = (id, content, family, size, placement, look) => ({ kind: 'text', id, content,
  fontFamily: family, fontSize: pt(size), color: col('estuary'), placement, ...look });
const caps = { fontFamily: LABEL, fontWeight: 700, textTransform: 'uppercase',
  letterSpacing: pt(1.15) };
const [MEASURE, EDGE] = [PAGE.w - 2 * PAGE.side, 17]; // mm; EDGE: trim to kicker and facts
const cover = { id: 'cover', advancedDesign: { enabled: true, slot: { elements: [
  { kind: 'image', id: 'art', resourceId: 'cover', placement: { anchor: { to: 'page',
    edge: 'top-left' }, size: { width: mm(PAGE.w), height: mm(PAGE.h) } } },
  text('kicker', '{attr.kicker}', LABEL, 7.5, at(PAGE.side, EDGE, MEASURE), caps),
  // The language tab: the edition's code on a blue flap hanging from the top edge.
  text('edition', '{attr.edition}', LABEL, 8, { anchor: { to: 'page', edge: 'top-right' },
    offset: { x: mm(-PAGE.side) } }, { ...caps, color: col('foam'), box: {
    backgroundColor: col('estuary'), padding: { top: mm(8), right: mm(2.4), bottom: mm(2.2),
      left: mm(2.4) } } }),
  text('title', '{titleText}', DISPLAY, 50, at(PAGE.side - 0.8, 25, MEASURE + 2),
    { italic: true, lineHeight: 0.96 }), // 48 pt from line to line
  text('lead', '{attr.lead}', TEXT, 11, at(PAGE.side + 2, WATER + 50, MEASURE - 4),
    { color: col('foam'), italic: true, lineHeight: 1.4 }),
  text('facts', '{attr.facts}', LABEL, 7.5, at(PAGE.side, -EDGE, MEASURE, 'bottom-left'),
    { ...caps, color: col('sand') }),
] } } };

La portada es el diseño del encabezado de cubierta: el dibujo anclado a la página a tamaño completo, el texto del título con {titleText}, el antetítulo, la entradilla y la línea de datos, que salen de sus atributos, y un texto con caja para la pestaña del idioma. El nivel 1 de los títulos lleva span: 'page', así que el dibujo llega al borde inferior del papel. Si se queda en la columna, el diseño se corta al pie de la caja de texto: el dibujo acabaría 13 mm antes del borde inferior.

La receta completa

Sandbox
// ═══ Postext Cookbook · Nº 041 · .postext round trip in two languages ════════════
// https://postext.dev/en/cookbook/bundle-round-trip
// Code: MIT · Text: original (CC BY 4.0) · Drawings: generated in code (CC BY 4.0)
// Fonts: DM Sans, DM Serif Display, Instrument Sans (SIL OFL 1.1) · Needs postext ≥ 1.25.0
import { createBundle, openBundle, loadBundleFonts, registerBundleImages, buildBundle,
  bundleFontProvider, bundleResourceBytes, defaultResourceTypes, renderPageToCanvas }
  from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';

const LANG = 'es'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'bundle-round-trip';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
const palette = { ink: '#172130', muted: '#56606c', // text; the colophon
  estuary: '#25476a', mud: '#8a6f4d', // the one accent; the wheel's wood in the drawings
  sand: '#e9dcc4', foam: '#eef2f3', rule: '#c4ced6', paper: '#ffffff' };
// Each colour carries its hex and the palette entry it follows.
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
// The engine's defaults link to 'main-color': point it at the estuary blue.
const colorPalette = Object.entries({ ...palette, 'main-color': palette.estuary })
  .map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
const [TEXT, DISPLAY, LABEL] = ['DM Sans', 'DM Serif Display', 'Instrument Sans'];
const PAGE = { w: 99, h: 210, top: 12, bottom: 13, side: 10 }; // mm: a DL leaflet, both sides
const [BODY, LEAD] = [9.4, 13.4]; // pt
const WATER = 98; // mm from the top of the cover: where the sand ends and the estuary begins

// #region cover: the front of the leaflet, a heading drawn over one picture
const at = (x, y, width, edge = 'top-left') => ({ anchor: { to: 'page', edge },
  offset: { x: mm(x), y: mm(y) }, size: { width: mm(width) } });
const text = (id, content, family, size, placement, look) => ({ kind: 'text', id, content,
  fontFamily: family, fontSize: pt(size), color: col('estuary'), placement, ...look });
const caps = { fontFamily: LABEL, fontWeight: 700, textTransform: 'uppercase',
  letterSpacing: pt(1.15) };
const [MEASURE, EDGE] = [PAGE.w - 2 * PAGE.side, 17]; // mm; EDGE: trim to kicker and facts
const cover = { id: 'cover', advancedDesign: { enabled: true, slot: { elements: [
  { kind: 'image', id: 'art', resourceId: 'cover', placement: { anchor: { to: 'page',
    edge: 'top-left' }, size: { width: mm(PAGE.w), height: mm(PAGE.h) } } },
  text('kicker', '{attr.kicker}', LABEL, 7.5, at(PAGE.side, EDGE, MEASURE), caps),
  // The language tab: the edition's code on a blue flap hanging from the top edge.
  text('edition', '{attr.edition}', LABEL, 8, { anchor: { to: 'page', edge: 'top-right' },
    offset: { x: mm(-PAGE.side) } }, { ...caps, color: col('foam'), box: {
    backgroundColor: col('estuary'), padding: { top: mm(8), right: mm(2.4), bottom: mm(2.2),
      left: mm(2.4) } } }),
  text('title', '{titleText}', DISPLAY, 50, at(PAGE.side - 0.8, 25, MEASURE + 2),
    { italic: true, lineHeight: 0.96 }), // 48 pt from line to line
  text('lead', '{attr.lead}', TEXT, 11, at(PAGE.side + 2, WATER + 50, MEASURE - 4),
    { color: col('foam'), italic: true, lineHeight: 1.4 }),
  text('facts', '{attr.facts}', LABEL, 7.5, at(PAGE.side, -EDGE, MEASURE, 'bottom-left'),

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

#Lee un paquete bilingüe

La guía de Postext lleva en un solo archivo sus capítulos, su configuración y sus pies en inglés y en español; { locale } elige la edición, que se abre como doce capítulos en 48 páginas en cualquiera de los dos idiomas, mientras el enlace sigue ofreciendo el archivo del folleto y el botón del PDF compone la guía.

-const bundle = await openBundle(bytes);
+const guide = await fetch('https://postext.dev/bundles/postext-guide.postext');
+const bundle = await openBundle(await guide.arrayBuffer(), { locale: LANG });

#Numera las figuras por capítulo

Sin los tipos, quien abre el archivo los crea en su idioma con la numeración por defecto, y las figuras cuentan desde el título de cubierta: Figura 1.1 y Tabla 1.1 en esta edición, Figure 1.1 y Table 1.1 en la inglesa.

-  resourceTypes: defaultResourceTypes(LANG).map((type) => ({ ...type, numberingTemplate: '{n}' })),

Errores frecuentes

  • Aquí cada edición es un archivo propio. Para llevar los dos idiomas en uno, pasa a createBundle un mapa localized (Paquetes bilingües); openBundle(bytes, { locale }) lee entonces cualquiera de las dos ediciones.

Créditos

Texto
Texto original, CC BY 4.0
Fuentes
DM Sans (SIL OFL 1.1) · DM Serif Display (SIL OFL 1.1) · Instrument Sans (SIL OFL 1.1)
SandboxPDF