Saltar al contingut principal
Recepta número 76

Receptari · Capítol 2 · Text i tipografia

Una cartilla amb pinyin: la lectura sobre cada caràcter

Ruby caràcter a caràcter en una cartilla de Hong Kong: {人之初|rén zhī chū} centra una síl·laba de pinyin sobre cada caràcter, en Andika, en 28 pt d'interlínia.

En aquesta pàgina
Sortida
Canvas
Nivell
Intermedi
Postext
Provada amb Postext 1.65.0
Requereix ≥ 1.25.0
Llicència
Actualitzada el 10 d’oct. del 2026
Codi MIT · Text CC BY 4.0

pp. 36–37 · 1–2 de 4

  • Mostra en castellà: encara no hi ha edició en català
  • Format 184 × 260 mm
  • 1 columna
  • LXGW WenKai TC 26/54
  • Andika
  • Noto Sans TC
  • 4 pàgines
  • Nivell
  • Postext 1.57.1
  • Compost en 74 ms
  • 180 línies de codi

En poques paraules

Pàgines d'una cartilla infantil de Hong Kong. Ensenya a escriure la pronúncia en lletres llatines damunt de cada caràcter xinès, amb quadrícules per practicar l'escriptura.

Què compondràs

Dues dobles pàgines de 《蒙學誦讀》, una cartilla inventada de Hong Kong, on els infants llegeixen en veu alta el Clàssic dels tres caràcters en mandarí (putonghua). Cada pàgina és una lliçó de quatre parelles de versos en kai de 一号 (26 pt), i cada caràcter va sota la seva síl·laba de pinyin. Les síl·labes van en Andika perquè dibuixa la a i la g d'un sol pis que imprimeixen els llibres escolars xinesos. Una banda verd pàl·lid porta l'etiqueta vermella de la lliçó, una petita aquarel·la i el títol en 初号 (42 pt) amb la seva pròpia lectura. Sota el text, sis quadrícules d'escriptura (田字格) guarden els caràcters per copiar, i una nota explica a la família què diuen els versos. La seva parella en castellà és la cartilla de síl·labes en xips, on cada síl·laba és un xip de color en lloc d'una lectura sobre un caràcter.

Una cartilla s'aparta expressament de les normes del llibre xinès. Un infant llegeix pocs caràcters i grans, així que la línia en porta dotze de 26 pt on un llibre en posa entre 25 i 40 de 10,5 pt, i l'interlineat passa una mica del doble del cos perquè hi càpiguen les lectures. Cada parella de versos va centrada a la seva pròpia línia, sense justificar ni sagnar. El text va en kai, la lletra que segueix el pinzell, perquè ensenya els traços que l'infant aprèn a escriure; un llibre el compondria en song.

Aquesta recepta respon a

  • Com poso pinyin damunt dels caràcters xinesos?

La resposta curta

script.js · línies 36–56al codi complet
// {人之初|rén zhī chū} gives each character its own syllable (mono ruby): three readings for
// three characters, split on the spaces. The reading sits in the line gap, centred on its
// character; a syllable wider than the character widens that character's box by what the
// reading needs, less the quarter of the reading's size it may lend a neighbour.
const cjk = {
  // The type area in characters: 12 per line, 11 lines of 54 pt. The margins grow to centre it.
  grid: { enabled: true, charsPerLine: CHARS, linesPerPage: 11 },
  ruby: {
    fontFamily: PINYIN, // one-storey a and g, as a Chinese primer prints them
    // 9.9 pt over the text, 16 pt over the title: the widest syllables (xiāng, zhuān) still fit
    // over one character, so every couplet is 8 em long and keeps to the grid.
    fontSize: em(0.38),
    color: col('pinyin'),
  },
};
// The line pitch never changes for a reading: the gap between lines (54 − 26 = 28 pt) must
// hold it, or the build warns rubyExceedsLeading.
const text = {
  fontFamily: KAI, fontSize: pt(TEXT), lineHeight: pt(LINE),
  textAlign: 'center', firstLineIndent: pt(0), // one couplet to a line, centred
};

Ingredients

Tipografia
LXGW WenKai TC, Noto Sans TC, Andika (SIL OFL 1.1)
Recursos
  • brush-800.jpg
  • jade-800.jpg
  • shuttle-800.jpg
  • sprout-800.jpg
  • The writing squares, drawn in code in the page’s palette (Postext Cookbook, CC BY 4.0)
  • Lesson 1’s vignette: a seedling, a watercolour (Generated With Diffusion Models, original)
  • Lesson 2’s vignette: the shuttle of a loom, a watercolour (Generated With Diffusion Models, original)
  • Lesson 3’s vignette: a brush and its first stroke, a watercolour (Generated With Diffusion Models, original)
  • Lesson 4’s vignette: a jade disc on a red cord, a watercolour (Generated With Diffusion Models, original)

Elaboració

#1 · Una síl·laba sobre cada caràcter

El codi és la resposta curta de més amunt. {人之初|rén zhī chū} dona tres lectures a tres caràcters, separades pels espais: cada síl·laba se centra sobre el seu caràcter, i la línia es pot tallar entre ells. La lectura no ocupa espai propi. Va al buit entre línies, aquí 54 − 26 = 28 pt, i un buit més estret que la lectura s'avisa com a rubyExceedsLeading. Una síl·laba més ampla que el seu caràcter sí que ocupa espai: eixampla la caixa d'aquest caràcter, i en una línia centrada els caràcters que la segueixen surten de la retícula. Les lectures porten el cos amb què les síl·labes més amples de la mostra, xiāng i zhuān, encara caben sobre un caràcter, 0,38 em (9,9 pt): cada parella de versos fa vuit caràcters i cada caràcter conserva la seva casella. Amb 0,45 em, 性相近,習相遠 s'estiraria fins a vuit caràcters i mig i obriria buits al voltant de 相.

#2 · El títol conserva la seva lectura

script.js · línies 60–77al codi complet
const BAND = 68; // mm from the top edge
// Heading designs ignore parity: a place for the drawing on each side, 14 mm from the outer
// edge, named {left="…"} on a verso and {right="…"} on a recto. A missing attribute draws nothing.
const picture = (side, x) => ({ kind: 'image', id: `picture-${side}`,
  resourceId: `{attr.${side}}`, decorative: true, reserve: false,
  placement: { anchor: { to: 'page', edge: `top-${side}` }, offset: { x: mm(x), y: mm(14) },
    size: { width: mm(42), height: mm(42) } } });
const opener = { enabled: true, slot: { elements: [
  { kind: 'box', id: 'band', reserve: false, style: { backgroundColor: col('tint') },
    placement: { anchor: { to: 'page', edge: 'top-left' },
      size: { width: mm(184), height: mm(BAND) } } },
  picture('left', 14), picture('right', -14),
  { kind: 'text', id: 'lesson', content: '{titleText}', fontFamily: HEI, fontSize: pt(11),
    fontWeight: 700, letterSpacing: pt(2), color: col('paper'), align: 'center', overflow: 'wrap',
    placement: { anchor: { to: 'container', edge: 'top' } },
    box: { backgroundColor: col('red'), borderRadius: mm(3.5),
      padding: { top: mm(1.2), right: mm(3.6), bottom: mm(1.2), left: mm(3.6) } } },
] } };

El text d'un disseny no imprimeix lectures, així que el títol no pot sortir del disseny de l'obertura. El títol de primer nivell, 第一課, dibuixa la banda, la vinyeta i l'etiqueta vermella; el de la lliçó és el títol de segon nivell que va a sota, sense disseny propi, en 初号, i el compositor de text el compon amb el seu pinyin. reserve: false deixa la banda i la vinyeta fora de l'alçada del títol, i span: 'page' les pinta sota el text.

Un disseny de títol no té en compte parity, així que la vinyeta té un element a cada costat de la pàgina: {attr.left} a 14 mm de la vora esquerra i {attr.right} a 14 mm de la dreta. Les lliçons de pàgina parella escriuen # 第一課 {left="sprout"}, i les de senar, {right="shuttle"}, de manera que cada vinyeta queda al costat exterior de la doble pàgina; l'element al qual falta l'atribut no dibuixa res.

#3 · Sis quadrícules amb un sol atribut

script.js · línies 81–101al codi complet
// Design text prints no readings, so the squares hold the characters alone. A Han character
// is one em wide, so tracking of (pitch − em) sets one in the middle of each square.
const [SQ, GAP, WRITE] = [15, 3.4, 30]; // mm, mm, pt
const ROW = 6 * SQ + 5 * GAP; // mm
const X0 = (MEASURE - ROW) / 2; // the row is centred on the measure
const EM = WRITE * 25.4 / 72; // mm: one character at 30 pt, 10.6 mm wide
const squares = { enabled: true, slot: { elements: [
  { kind: 'text', id: 'label', content: '{titleText}', fontFamily: HEI, fontSize: pt(10),
    fontWeight: 700, letterSpacing: pt(1.5), color: col('red'), align: 'left', overflow: 'wrap',
    placement: { anchor: { to: 'container', edge: 'top-left' }, offset: { x: mm(X0) } } },
  ...Array.from({ length: 6 }, (_, k) => ({ kind: 'image', id: `square${k}`, resourceId: 'tian',
    decorative: true, placement: { anchor: { to: 'container', edge: 'top-left' },
      offset: { x: mm(X0 + k * (SQ + GAP)), y: mm(7) },
      size: { width: mm(SQ), height: mm(SQ) } } })),
  { kind: 'text', id: 'chars', content: '{attr.write}', fontFamily: KAI, fontSize: pt(WRITE),
    lineHeight: 1, letterSpacing: mm(SQ + GAP - EM), color: col('ink'), align: 'left',
    verticalAlign: 'middle', overflow: 'clip',
    placement: { anchor: { to: 'container', edge: 'top-left' },
      offset: { x: mm(X0 + (SQ - EM) / 2), y: mm(7) },
      size: { width: mm(ROW + GAP), height: mm(SQ) } } },
] } };

### 我會寫 {write="人之本不相以"} passa al disseny els sis caràcters en un atribut. En LXGW WenKai TC cada caràcter xinès fa un quadratí, així que un espaiat igual al pas de les quadrícules menys un quadratí (18,4 − 10,6 mm) porta cada caràcter a la seva quadrícula, i un sol element de text omple la fila. La quadrícula és un SVG dibuixat en codi: un marc vermell i una creu de traços.

#4 · Cada font carrega els seus propis caràcters

script.js · línies 282–289al codi complet
// Fontsource cuts a Chinese face into about a hundred files by character range
// (gotcha: cjk-fonts-slices). The Kai sets the whole sample; the Hei only the headings'
// labels and the footer's series line, so it fetches a few files.
const labels = (markdown.match(/^#{1,3} [^{\n]*/gm) ?? []).join('') + '蒙學誦讀 第一冊';
await loadFonts(FONTS, markdown); // the latin files, and Andika's latin-ext for ǎ ǐ ǒ ǔ
await Promise.all([loadCjkFonts({ [KAI]: FONTS[KAI] }, markdown),
  loadCjkFonts({ [HEI]: FONTS[HEI] }, labels),
  loadSvg('tian.svg', tian), ...VIGNETTES.map((fileId) => loadImage(fileId, asset(fileId)))]);

Fontsource talla cada font xinesa en un centenar de fitxers per intervals de caràcters. La kai compon tota la mostra i carrega els fitxers que contenen els seus caràcters. La hei només compon les etiquetes, els rètols i el peu, així que rep aquest text i baixa uns pocs fitxers. Andika arriba amb loadFonts, que afegeix el fitxer latin-ext quan el text té lletres més enllà de Latin-1, com ǎ i ǐ.

#5 · L'etiqueta de llengua porta la puntuació de Hong Kong

script.js · línies 121–123al codi complet
  // Punctuation at full width, where LXGW WenKai TC centres it as Hong Kong and Taiwan print
  // it, and the basic line-breaking rules. Written out, never LANG (gotcha: cjk-locale-tag).
  locale: 'zh-HK',

zh-HK fixa les regles de Hong Kong: puntuació d'amplada completa i el joc bàsic de regles de tall, que aquí cap parella de versos no necessita. LXGW WenKai TC dibuixa la coma i el punt al centre de la casella, com els imprimeixen Hong Kong i Taiwan, i per això aquesta cartilla és de Hong Kong. Una cartilla continental també va en kai, en caràcters simplificats i amb la coma i el punt a baix a l'esquerra de la casella. Però Fontsource no té una kai de text per al xinès simplificat, i la tradicional enganxaria aquests signes al caràcter següent, així que en aquest Receptari una pàgina continental pren Noto Serif SC, la song de la pàgina de novel·la continental.

La recepta completa

Sandbox
// ═══ Postext Cookbook · Nº 076 · A pinyin primer: readings over every character ═══
// https://postext.dev/en/cookbook/pinyin-primer
// Code: MIT · Text: 三字經 (PD); pinyin, notes: CC BY 4.0 · Vignettes: diffusion models
// Fonts: LXGW WenKai TC, Noto Sans TC, Andika (SIL OFL 1.1) · Needs postext ≥ 1.25.0
import {
  buildDocument, withLoadedFonts, renderPageToCanvas, registerResourceImage,
} from 'https://esm.sh/postext';

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

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: a primer's colours, every one linked by id
const palette = {
  ink: '#29241f', // the characters: a warm near-black
  pinyin: '#355a4d', // the readings, a shade off the ink so the two layers part
  red: '#bf3a2b', // lesson badges and the writing squares
  jade: '#2f7a5e', // the folio discs
  tint: '#edf4ea', // the band behind each lesson's title
  cream: '#faf3e4', // the note for families
  muted: '#6d665e', // series line, colophon
  paper: '#ffffff',
};
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
// The engine's defaults link to 'main-color': point it at the red.
const colorPalette = Object.entries({ ...palette, 'main-color': palette.red })
  .map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
// #endregion
const [KAI, HEI, PINYIN] = ['LXGW WenKai TC', 'Noto Sans TC', 'Andika'];
const TEXT = 26; // pt: 一号, the size of a first reader's text
const LINE = 54; // pt: 2.1 × the size, so a reading fits between two lines
const CHARS = 12; // characters per line: the measure is 12 × 26 pt = 110 mm
const MEASURE = CHARS * TEXT * 25.4 / 72; // mm

// #region answer: one reading per character, in Andika, in a line gap wide enough to hold it
// {人之初|rén zhī chū} gives each character its own syllable (mono ruby): three readings for
// three characters, split on the spaces. The reading sits in the line gap, centred on its
// character; a syllable wider than the character widens that character's box by what the
// reading needs, less the quarter of the reading's size it may lend a neighbour.
const cjk = {
  // The type area in characters: 12 per line, 11 lines of 54 pt. The margins grow to centre it.
  grid: { enabled: true, charsPerLine: CHARS, linesPerPage: 11 },
  ruby: {
    fontFamily: PINYIN, // one-storey a and g, as a Chinese primer prints them
    // 9.9 pt over the text, 16 pt over the title: the widest syllables (xiāng, zhuān) still fit
    // over one character, so every couplet is 8 em long and keeps to the grid.
    fontSize: em(0.38),
    color: col('pinyin'),

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

#Mostra la retícula mentre compons

show: true dibuixa al canvas les dotze caselles de cada línia; el PDF les omet tret que renderToPdf rebi characterGrid: true.

-  grid: { enabled: true, charsPerLine: CHARS, linesPerPage: 11 },
+  grid: { enabled: true, charsPerLine: CHARS, linesPerPage: 11, show: true },

#Posa el zhuyin al costat dels caràcters

Les lectures en bopomofo es col·loquen en una columna a la dreta de cada caràcter; la cartilla de zhuyin les compon en una pàgina vertical.

Errors freqüents

Error freqüent

Les lectures s'imprimeixen al text, no en dissenys, peus ni cel·les

Les lectures ruby es dibuixen en paràgrafs, títols, elements de llista, cites i requadres. Un element de text d'un disseny (una obertura, una capçalera, una etiqueta), un peu, una nota a peu de pàgina i una cel·la de taula imprimeixen els caràcters base sense les seves lectures. Un títol que necessita el seu pinyin és un títol sense disseny propi: dibuixa el que l'envolta (una banda, el número de la lliçó) amb el disseny del títol anterior, els elements del qual amb reserve: false es pinten sota el text d'una obertura span: 'page'. Ruby: lectures en pinyin i zhuyin →

Error freqüent

Compon la puntuació de cada regió amb una font d'aquella regió

Les amplades de la puntuació mouen el blanc de cada signe al costat on el posa la regió del document, no al costat on el dibuixa la font: amb zh-Hans, una coma Kaiming conserva la meitat esquerra de la seva caixa, on una font simplificada dibuixa el signe, i cedeix la dreta. Una font tradicional centra ,。 a la caixa, de manera que la meitat que se'n va s'emporta part del signe i la coma s'enganxa al caràcter següent. LXGW WenKai TC, l'única Kai de text de Fontsource, ho fa en text simplificat. Compon el text, les notes i les cites continentals en Noto Serif SC o Noto Sans SC, deixa les fonts TC per a zh-Hant i fes servir una lletra de pinzell simplificada (Ma Shan Zheng) només en línies d'exhibició, on el text de disseny no aplica amplades de puntuació. A més, dibuixa formes heretades que no imprimeix ni l'estàndard continental ni el de Taiwan, 為 amb el 爫 de 爲 i 令 (a 冷, 領) amb el peu de 卩: revisa els caràcters que compon a cada pàgina. Amplada de la puntuació xinesa →

Error freqüent

Les fonts xineses es carreguen per fragments, amb el bloc cjk

Fontsource serveix una família xinesa, japonesa o coreana en un centenar de fitxers per pes, cadascun amb un interval de caràcters. loadFonts només baixa el fitxer latin, així que a la pantalla els caràcters xinesos surten d'una font del sistema i es mesuren malament, i fontsourceProvider lliura al PDF aquest fitxer latin, que els imprimeix com a caixes buides. Afegeix el bloc cjk del kit, crida loadCjkFonts(FONTS, markdown) després de loadFonts (una vegada per veu, amb el text que compon, si el llibre fa servir diverses fonts xineses) i passa a renderToPdf fontProvider: cjkPdfProvider: tots dos agafen els fitxers que contenen els caràcters del text. Fonts xineses, japoneses i coreanes →

Error freqüent

Etiqueta el document zh-Hans o zh-Hant, no amb LANG

Les edicions d'una recepta són en i es, però una mostra xinesa és xinesa en totes dues: `locale: LANG` l'etiquetaria com a anglès o castellà, separaria les seves paraules llatines, anomenaria Figure o Figura les seves figures i donaria al PDF una llengua equivocada. Des de postext 1.30 l'etiqueta és a més la llengua en què es compon el text (en què es mesura, es pinta i s'incrusta), de manera que sota una etiqueta anglesa o castellana una font xinesa compon amb altres formes les xifres i la puntuació que comparteix amb el text llatí, i les línies es parteixen per un altre lloc. Escriu tu l'etiqueta: 'zh-Hans' (convencions de la Xina continental: tall GB, puntuació Kaiming) o 'zh-Hant' (Taiwan: puntuació d'amplada completa centrada); 'zh-HK' per a Hong Kong. Un 'zh' tot sol es llegeix com a xinès simplificat continental. Una mostra japonesa porta 'ja' (gotcha ja-locale-tag). Tall de línies en xinès →

Avís de maquetació · rubyExceedsLeading

Lectures enganxades a la línia veïna

Per què. Un paràgraf amb lectures ruby damunt o sota del text té una interlínia més estreta que les lectures: ocupen l'interlineat i toquen la línia veïna.

Solució. Compon el paràgraf amb més interlineat (com a mínim el cos més `cjk.ruby.fontSize`), o redueix les lectures. Documentació →

  • Aquesta recepta no ofereix PDF. El fontsourceProvider del kit incrusta només el fitxer latin d'una font, i les lletres amb to ā ǎ ǐ ǒ ǔ són a latin-ext, així que el PDF les perdria i postext-pdf avisaria de cadascuna amb missingGlyph. Si el necessites, compon les lectures amb una font xinesa: cjkPdfProvider en tria els fitxers caràcter a caràcter.

  • Comprova cada caràcter de les quadrícules amb les formes normalitzades de la regió. LXGW WenKai TC dibuixa 為 amb la part de dalt de 爲 (爫), una forma antiga que passa al text corrent, com a 老何為 i 為人子, però no en una quadrícula que copia un infant de Hong Kong. Per això la lliçó tercera practica 幼.

Crèdits

Text
Imatges
  • The writing squares, drawn in code in the page’s palette · Postext Cookbook · CC BY 4.0
  • Lesson 1’s vignette: a seedling, a watercolour · Generated With Diffusion Models · original
  • Lesson 2’s vignette: the shuttle of a loom, a watercolour · Generated With Diffusion Models · original
  • Lesson 3’s vignette: a brush and its first stroke, a watercolour · Generated With Diffusion Models · original
  • Lesson 4’s vignette: a jade disc on a red cord, a watercolour · Generated With Diffusion Models · original
Fonts
LXGW WenKai TC (SIL OFL 1.1) · Noto Sans TC (SIL OFL 1.1) · Andika (SIL OFL 1.1)
Sandbox