Saltar al contingut principal
Recepta número 1

Receptari · Capítol 12 · Llibres de text

Llibre de text amb columna al marge

Columna i mitja amb la columna exterior només per a flotants: s'hi apilen figures i glosses amb span 'side', i captionSide hi porta la resta de peus.

En aquesta pàgina

pp. 88–89 · 2–3 de 4

  • Mostra en castellà: encara no hi ha edició en català
  • Format 210 × 275 mm
  • Columna i mitja, espai entre columnes de 7 mm
  • Merriweather 9,3/13,5
  • Merriweather Sans
  • 4 pàgines
  • Nivell
  • Postext 1.57.1
  • Compost en 69 ms
  • 240 línies de codi

En poques paraules

Un capítol d'un llibre de física amb una columna ampla de text i una altra d'estreta al costat de la vora exterior. L'estreta porta diagrames i notes breus al costat del text que acompanyen.

Què compondràs

El capítol 4 de Palanca y lente, un manual de física en pàgina de 210 × 275 mm. El text ocupa una columna ampla i no entra mai al marge exterior, una columna lateral de 53 mm. El número del capítol, un 4 verd, va en aquesta columna lateral a l'altura del títol, i els objectius, a sota. Els diagrames s'apilen des del capdamunt de la columna lateral, i els termes clau van en glosses verd clar al costat del passatge que els defineix. Les figures que es queden a la columna de text, sobre fons fosc o clar, porten el peu al marge, a l'altura de la seva base. Només el panell del prisma creua les dues columnes. Els marges són simètrics, així que la columna lateral queda sempre al costat exterior de la pàgina, a la dreta a les senars i a l'esquerra a les parelles.

Aquesta recepta respon a

  • Com compono en columna i mitja, amb una columna de text ampla i una de lateral estreta?
  • Com poso notes al marge o glosses al costat del paràgraf que expliquen?
  • Com afegeixo una figura amb peu numerat i la cito en el text («vegeu la fig. 3.2»)?
  • Com decideixo on va una figura: al capdamunt de la pàgina, a l'amplada de les dues columnes, just aquí o al marge?
  • Com poso el peu al costat d'una figura, o damunt d'una taula sobre una barra de color?
  • Com numero els títols (1, 1.1, 1.1.1) i dono a cada nivell un estil diferent?

La resposta curta

script.js · línies 41–56al codi complet
const layout = {
  layoutType: 'oneAndHalf', // a wide main column and a narrow side column
  sideColumnPercent: 30, // of the 176 mm content width: a 52.8 mm channel
  sideColumnRole: 'floats', // no body text: side figures, side captions and side boxes only
  sideColumnSide: 'outer', // right on a recto, left on a verso (the margins are mirrored)
  gutterWidth: mm(7), // the text column keeps the rest: 176 − 52.8 − 7 = 116 mm
};
// A figure placed with span 'side' stacks in the channel from the head of the page that cites it,
// under the numeral on a chapter's first page.
const side = { span: 'side' };
// A figure left in the text column (the default span) sets its caption in the channel beside
// it; page-wide floats ignore captionSide and keep theirs underneath.
const resourceTypes = defaultResourceTypes(LANG).map((type) => (type.id !== 'figure' ? type
  : { ...type, defaultPlacement: { captionSide: true } })); // the built-in types, in LANG
// A box fenced :::callout{type="term" span="side"} leaves the flow and lands in the channel at the
// height the text has reached: fence each gloss before the paragraph it should stand beside.

Ingredients

Tipografia
Merriweather, Merriweather Sans (SIL OFL 1.1)
Recursos
Cap: totes les imatges es dibuixen en codi

Elaboració

#1 · Reserva el marge per als flotants

El codi d'aquest pas és la resposta curta de més amunt. En una disposició en columna i mitja, sideColumnPercent: 30 dona a la columna lateral el 30 % dels 176 mm d'amplada de la caixa (52,8 mm), i la columna de text es queda amb el que sobra després de l'espai entre columnes de 7 mm (116 mm, uns 75 caràcters de Merriweather de 9,3 pt). sideColumnRole: 'floats' tanca la columna lateral al text, i sideColumnSide: 'outer' la posa al costat exterior, que amb marges simètrics canvia d'una pàgina a l'altra. Les figures hi van amb span: 'side'. Un requadre amb span="side" a la línia d'obertura surt del flux i entra a la columna lateral a l'altura per on va el text, així que cada glossa comença al costat del bloc que segueix la seva tanca.

#2 · Deixa que la cita col·loqui cada figura

script.js · línies 502–517al codi complet
const drawings = new Map(); // fileId → SVG markup, registered before the build
const figure = (id, { width, height, markup }, placement) => {
  drawings.set(`${id}.svg`, markup);
  return { id, typeId: 'figure', kind: 'svg', createdAt: 0, updatedAt: 0, caption: t(captions[id]),
    altText: t(captions[id]), // read aloud in HTML and tagged PDF; the canvas does not use it
    svg: { fileId: `${id}.svg`, width, height }, ...(placement && { placement }) };
};
const resources = [ // no placement: a main-column float, its caption in the channel
  figure('burning-glass', burningGlass()),
  figure('refraction', refraction(), side),
  figure('critical-angle', criticalAngle(), side),
  figure('fibre', fibre()),
  figure('prism', prism(), { span: 'page', position: 'top' }), // across text column and channel
  figure('principal-rays', principalRays()),
  figure('diverging', diverging(), side),
];

El primer :ref a una figura la numera i la situa on indica la seva col·locació. Una figura amb span: 'side' s'apila des del capdamunt de la columna lateral de la pàgina que la cita, encara que la cita quedi més avall, i passa a la pàgina següent si no li basta la resta de la columna lateral. Les figures 4.2 i 4.3, citades totes dues a la pàgina 88, baixen per la columna lateral d'aquella pàgina amb la glossa de l'angle límit entre elles. El prisma és un flotant top a tota l'amplada citat a la pàgina 88, i un flotant no queda mai per sobre de la seva cita, així que obre la 89 sobre les dues columnes. Les figures 4.1, 4.4 i 4.6 es queden a la columna de text i prenen captionSide del defaultPlacement del tipus figura. Ocupen l'espai inferior de la columna, així que cada peu queda a l'altura de la base de la seva figura; a l'espai superior s'alinearia amb la vora de dalt.

#3 · Obre el capítol al marge

script.js · línies 79–112al codi complet
// Every element counts toward the opener's depth, the page-anchored numeral too (gotcha:
// opener-reserves-anchored). minHeight fixes that depth at nine lines of the grid, room for a
// one-line title, the rule and a four-line standfirst (41.2 mm), so the text starts on the same
// line in every such chapter, however short its standfirst and even with a smaller numeral. Kicker
// and numeral (40.6 mm) reach the ninth line too; a deeper opener grows past it, line by line.
const [KICKER, NUMERAL] = [8, 104]; // pt
const opener = {
  enabled: true,
  minHeight: pt(LEAD * 9), // 42.9 mm: the text starts on the eleventh line, after marginBottom
  slot: {
    elements: [
      { kind: 'text', id: 'title', content: '{titleText}', fontFamily: SANS, fontWeight: 800,
        fontSize: pt(32), lineHeight: 1.05, color: col('ink'), align: 'left', overflow: 'wrap',
        placement: { anchor: { to: 'container', edge: 'top-left' }, size: { width: 'fill' } } },
      { kind: 'rule', id: 'rule', direction: 'horizontal', thickness: pt(1), color: col('accent'),
        placement: { anchor: { to: '#title', edge: 'below' }, offset: { y: mm(4) },
          size: { width: 'fill' } } },
      { kind: 'text', id: 'lead', content: '{attr.lead}', fontFamily: SERIF, italic: true,
        fontSize: pt(10.5), lineHeight: 1.45, color: col('ink'), align: 'left', overflow: 'wrap',
        placement: { anchor: { to: '#rule', edge: 'below' }, offset: { y: mm(3.5) },
          size: { width: 'fill' } } },
      // The kicker hangs from the page's top-right corner, not from the heading: the channel lies
      // outside the heading's column, and on the right only on a recto (so chapters open on one).
      // The numeral hangs from the kicker.
      { kind: 'text', id: 'kicker', content: t({ en: 'Chapter', es: 'Capítulo' }), ...label,
        fontSize: pt(KICKER), align: 'left', placement: { anchor: { to: 'page', edge: 'top-right' },
          offset: { x: mm(-OUTER), y: mm(TOP) }, size: { width: mm(CHANNEL) } } },
      { kind: 'text', id: 'numeral', content: '{chapterNumber}', fontFamily: SANS, fontWeight: 800,
        fontSize: pt(NUMERAL), lineHeight: 1, color: col('accent'), align: 'left',
        placement: { anchor: { to: '#kicker', edge: 'below' }, offset: { y: mm(0.5) },
          size: { width: mm(CHANNEL) } } },
    ],
  },
};

El títol de primer nivell es queda a la columna de text, on una ranura de disseny n'apila el text, el filet i l'entradeta; l'avanttítol penja de la cantonada superior dreta de la pàgina i el número, de l'avanttítol, tots dos amb l'amplada de la columna lateral. minHeight fixa l'alçada de l'obertura en nou línies de la retícula (42,9 mm), que donen cabuda a un títol d'una línia, el filet i una entradeta de quatre, així que amb una entradeta més curta el text no puja. L'avanttítol i el número de 104 pt acaben 40,6 mm per sota del marge superior, dins d'aquestes nou línies, així que tampoc no fan baixar el text. La columna lateral només és a la dreta a les pàgines senars, i per això el títol de primer nivell salta a pàgina senar. El requadre d'objectius va després del primer paràgraf, i cap figura del marge no es cita abans que ell, així que queda sota el número (ho explica «Errors freqüents»).

#4 · Porta els folis al costat del canal

script.js · línies 116–138al codi complet
const [HEAD_Y, FOOT_Y, HEAD_GAP] = [12.5, -12, 9]; // mm from the top and bottom trim; folio to head
// A text on the physical page: edge picks the corner, x and y are its offsets in mm.
const head = ({ edge, x, y = HEAD_Y, ...text }) => ({
  kind: 'text', pages: 'body', ...label, color: col('muted'), ...text,
  placement: { anchor: { to: 'page', edge }, offset: { x: mm(x), y: mm(y) } },
});
const folio = { content: '{pageNumber}', fontSize: pt(8.5), letterSpacing: pt(0),
  color: col('accent') };
const verso = { parity: 'even', edge: 'top-left' }; // x counts in from the left edge
const recto = { parity: 'odd', edge: 'top-right' }; // x counts back from the right edge
const header = { elements: [
  head({ id: 'verso-folio', ...verso, ...folio, x: OUTER }),
  head({ id: 'verso-title', ...verso, content: '{title}', x: OUTER + HEAD_GAP }),
  head({ id: 'recto-title', ...recto, x: -(OUTER + HEAD_GAP),
    content: t({ en: 'Chapter {chapterNumber} · {chapterTitle}',
      es: 'Capítulo {chapterNumber} · {chapterTitle}' }) }),
  head({ id: 'recto-folio', ...recto, ...folio, x: -OUTER }),
] };
// A chapter's first page, always a recto, carries a drop folio at the foot of the channel instead.
const footer = { elements: [
  head({ id: 'drop-folio', ...recto, ...folio, pages: 'opener', edge: 'bottom-right', x: -OUTER,
    y: FOOT_Y }),
] };

Cada element s'ancora a la pàgina física i es filtra per parity, així que el foli i la capçalera queden a la mateixa vora que la columna lateral a totes dues bandes de la doble pàgina. pages: 'body' els aparta de l'obertura, que porta en canvi un foli al peu de la columna lateral.

#5 · Comença el llibre al capítol 4

script.js · línies 529–534al codi complet
const continuation = { pageNumbering: { startAt: 87 }, // odd, like page 1: a recto
  headings: { h1: 3, h2: 0, h3: 0, h4: 0, h5: 0, h6: 0 } }; // the next # is chapter 4
const doc = await buildDocumentWithFonts({ markdown, resources, continuation }, config(),
  kitFonts(FONTS));
showPages(doc, { title: t({ en: 'Textbook with a margin column',
  es: 'Libro de texto con columna al margen' }) });

Aquestes pàgines són el capítol 4 d'un llibre més llarg. La continuació deixa el comptador de capítols en 3, així que {chapterNumber} imprimeix 4 i el numberingTemplate: '{1}.{2}' del segon nivell numera els apartats del 4.1 al 4.3; les figures van de la 4.1 a la 4.7. ## Preguntas {style="plain"} fa servir una entrada de headingStyles amb numbered: false, així que aquest títol no porta número. Els folis comencen al 87 perquè la primera pàgina cau a la dreta, i a la dreta van els folis senars.

#6 · Anomena els colors una sola vegada

script.js · línies 16–32al codi complet
const palette = {
  ink: '#1a222d', // text, and the dark panels of figures 4.1, 4.4 and 4.5
  accent: '#17774f', // the only accent colour: numerals, folios, section headings, labels
  ray: '#f2a516', // light rays in every diagram
  glass: '#cfe6dd', // glass in the diagrams
  tint: '#edf5f1', // the key-term glosses and the light plate of a construction diagram
  muted: '#5b6863', // running heads, the normals in the diagrams, the colophon
  paper: '#ffffff',
};
// A colour carries its id and its hex. The diagrams read `palette` as well, so retint the
// chapter by editing it: the text, the designs and the drawings change together.
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = [
  ...Object.entries(palette).map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } })),
  // The engine's defaults link to 'main-color': point it at the accent, so nothing prints blue.
  { id: 'main-color', name: 'accent (defaults)', value: { hex: palette.accent, model: 'hex' } },
];

Cada color de la configuració enllaça amb una entrada de la paleta i porta a més el seu hex, que col() copia del mateix objecte. Per canviar els colors del capítol, edita palette: els diagrames llegeixen el mateix objecte, així que el vidre, els raigs, els panells foscos i el fons clar canvien alhora que números, avanttítols i glosses. main-color apunta al color d'accent, així que els colors per defecte dels estils de text que la configuració no fixa surten en verd i no en el blau del motor.

La recepta completa

Sandbox
// ═══ Postext Cookbook · Nº 001 · Textbook with a margin column ═══════════════════
// https://postext.dev/en/cookbook/textbook-margin-column
// Code: MIT · Text: original (CC BY 4.0) · Diagrams: generated in code (CC BY 4.0)
// Fonts: Merriweather, Merriweather Sans (SIL OFL 1.1) · Needs postext ≥ 1.25.0
// A chapter of a physics textbook in the column-and-a-half layout: the body text keeps to
// the main column, and the outer margin is a channel for diagrams, captions and glosses.
import {
  buildDocumentWithFonts, renderPageToCanvas, registerResourceImage, defaultResourceTypes,
} from 'https://esm.sh/postext';

const LANG = 'es'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'textbook-margin-column';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: semantic colours, each linked by id and written out in hex
const palette = {
  ink: '#1a222d', // text, and the dark panels of figures 4.1, 4.4 and 4.5
  accent: '#17774f', // the only accent colour: numerals, folios, section headings, labels
  ray: '#f2a516', // light rays in every diagram
  glass: '#cfe6dd', // glass in the diagrams
  tint: '#edf5f1', // the key-term glosses and the light plate of a construction diagram
  muted: '#5b6863', // running heads, the normals in the diagrams, the colophon
  paper: '#ffffff',
};
// A colour carries its id and its hex. The diagrams read `palette` as well, so retint the
// chapter by editing it: the text, the designs and the drawings change together.
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = [
  ...Object.entries(palette).map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } })),
  // The engine's defaults link to 'main-color': point it at the accent, so nothing prints blue.
  { id: 'main-color', name: 'accent (defaults)', value: { hex: palette.accent, model: 'hex' } },
];
// #endregion
// The page in mm, named once: the channel, the opener and the running heads derive from it.
const [TRIM_W, TRIM_H] = [210, 275];
const [TOP, BOTTOM, INNER, OUTER] = [24, 22, 20, 14]; // inner and outer swap on a verso
const LEAD = 13.5; // body leading in pt
const [SERIF, SANS] = ['Merriweather', 'Merriweather Sans'];

// #region answer: a float-only channel on the outer edge, and what goes into it
const layout = {
  layoutType: 'oneAndHalf', // a wide main column and a narrow side column
  sideColumnPercent: 30, // of the 176 mm content width: a 52.8 mm channel
  sideColumnRole: 'floats', // no body text: side figures, side captions and side boxes only
  sideColumnSide: 'outer', // right on a recto, left on a verso (the margins are mirrored)
  gutterWidth: mm(7), // the text column keeps the rest: 176 − 52.8 − 7 = 116 mm
};
// A figure placed with span 'side' stacks in the channel from the head of the page that cites it,

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

#Deixa els peus sota les figures

Amb els valors per defecte del tipus figura, els peus de les figures 4.1, 4.4 i 4.6 ocupen línies de la columna de text, i la columna lateral queda només per a diagrames i glosses.

-const resourceTypes = defaultResourceTypes(LANG).map((type) => (type.id !== 'figure' ? type
-  : { ...type, defaultPlacement: { captionSide: true } })); // the built-in types, in LANG
+const resourceTypes = defaultResourceTypes(LANG); // what the engine uses when none are set

#Posa el canal a la dreta a totes les pàgines

Per a un document que es llegeix pàgina a pàgina en pantalla, desactiva els marges simètrics i passa a la vora dreta el foli i la capçalera de les parelles; així els capítols poden obrir-se a qualsevol pàgina.

-  sideColumnSide: 'outer', // right on a recto, left on a verso (the margins are mirrored)
+  sideColumnSide: 'right', // what 'outer' means anyway once the margins stop mirroring
-    bottom: mm(BOTTOM), left: mm(INNER), right: mm(OUTER), mirror: true } }, // left: recto's inner
+    bottom: mm(BOTTOM), left: mm(INNER), right: mm(OUTER), mirror: false } },
-      { level: 1, breakBefore: { enabled: true, parity: 'odd' }, marginBottom: pt(LEAD),
+      { level: 1, breakBefore: { enabled: true, parity: 'any' }, marginBottom: pt(LEAD),
-const verso = { parity: 'even', edge: 'top-left' }; // x counts in from the left edge
+const verso = { parity: 'even', edge: 'top-right' };
-  head({ id: 'verso-folio', ...verso, ...folio, x: OUTER }),
-  head({ id: 'verso-title', ...verso, content: '{title}', x: OUTER + HEAD_GAP }),
+  head({ id: 'verso-folio', ...verso, ...folio, x: -OUTER }),
+  head({ id: 'verso-title', ...verso, content: '{title}', x: -(OUTER + HEAD_GAP) }),
-  head({ id: 'drop-folio', ...recto, ...folio, pages: 'opener', edge: 'bottom-right', x: -OUTER,
+  head({ id: 'drop-folio', ...folio, pages: 'opener', edge: 'bottom-right', x: -OUTER,

#Obre el capítol sota una banda de color

Obertura de capítol sobre banda a sang porta una banda de color a sang per dalt de la pàgina i hi posa a sobre el títol i un número de capítol de 168 pt.

Errors freqüents

Error freqüent

Els requadres laterals no floten: esperen lloc

Un requadre amb span: 'side' no flota: es col·loca al costat del bloc al qual segueix i, si el canal del marge és ple, espera la pàgina següent. Posa cada glossa just després del paràgraf que explica. Si el capítol s'acaba amb requadres encara en espera, cadascun ocupa la columna lateral d'una pàgina posterior al text, en l'ordre de les seves tanques, i la composició ho avisa (afterText); fins a postext 1.24 només s'obria una d'aquestes pàgines i els requadres restants es perdien sense avís. Notes al marge →

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

Una obertura reserva alçada fins al seu element ancorat més baix

Una obertura de disseny avançat reserva l'alçada del seu element més baix, i també hi compten els ancorats a la pàgina o a la sang que queden per sota del títol, així que un ornament al peu de la pàgina empeny el text a la següent. Dona a aquest element reserve: false (des de postext 1.5): es pinta on està ancorat i no reserva res. Els elements que segueixen la mateixa banda (ancorats al seu peu, o d'alçada 'fill') no en fixen mai l'alçada. Obertures dissenyades →

Error freqüent

Sense <marker> ni filtres als SVG, o passen a mapa de bits

Una figura SVG només continua sent vectorial al PDF sense <marker>, filtres ni màscares; si no, passa a mapa de bits, i els filtres molt imbricats la poden deixar en blanc a Chrome. Dibuixa les puntes de fletxa com a traçats. Figures i taules com a recursos →

  • Figures i glosses s'apilen a la columna lateral en l'ordre en què el text hi arriba, mai l'una al costat de l'altra. La glossa de l'angle límit va després del paràgraf de la llei de Snell i abans del que cita la figura 4.3, així que a la pàgina 88 s'apila entre les figures 4.2 i 4.3, al costat del paràgraf que presenta el terme. Amb la línia d'obertura després d'aquesta cita, cauria sota la figura 4.3.
  • A la primera pàgina d'un capítol, les figures laterals s'apilen sota l'avanttítol i el número. Una figura citada al primer paràgraf ocupa aquest lloc i fa baixar el requadre d'objectius per la columna lateral, així que aquest capítol cita la seva primera figura del marge després del requadre.

Crèdits

Text
Text original, CC BY 4.0
Fonts
Merriweather (SIL OFL 1.1) · Merriweather Sans (SIL OFL 1.1)
Sandbox