Saltar al contingut principal
Recepta número 123

Receptari · Capítol 2 · Text i tipografia

Un manual tècnic japonès: kana, kanji i llatí

Un capítol A5 d'un llibre japonès de programació: talls i puntuació segons JLReq, un quart de quadratí davant el llatí, codi, 図3-1 i notes per pàgina.

En aquesta pàgina
  • Mostra en castellà: encara no hi ha edició en català
  • Format 148 × 210 mm
  • 1 columna
  • Noto Serif JP 9/16
  • BIZ UDGothic
  • Noto Sans JP
  • 5 pàgines
  • Nivell
  • Postext 1.65.0
  • Compost en 150 ms
  • 202 línies de codi

En poques paraules

Un capítol d'un llibre japonès de programació, ple de paraules angleses, codi i xifres. Postext compon la puntuació i els talls de línia amb les regles japoneses i afegeix un espai fi allà on el japonès toca el llatí.

Què compondràs

Cinc pàgines del capítol 3 d'un llibre japonès de programació inventat, 実践 日本語テキスト処理 (Processament pràctic de text japonès), sobre la normalització Unicode. Es compon com els llibres japonesos d'informàtica: A5, una columna de 36 caràcters per 29 línies de Noto Serif JP de 9 pt, títols en Noto Sans JP i codi en BIZ UDGothic. És el cas difícil de la composició japonesa, perquè gairebé cada frase porta una paraula llatina, un punt de codi, una xifra o un nom de funció. Els talls de línia segueixen el 禁則処理 (kinsoku shori) més estricte de JLReq, la puntuació conserva l'espaiat d'amplada completa i un quart de quadratí separa el japonès del llatí sense que ningú hi teclegi cap espai. Una figura, una taula, un llistat i les notes porten etiquetes japoneses: 図3-1, 表3-1 i números volats comptats per pàgina. Llistats de codi i tecles és el mateix tipus de pàgina en anglès.

Aquesta recepta respon a

  • Com espaio la puntuació japonesa: 、。「」 estrets on es troben, un espai després de ?! i el claudàtor que obre un paràgraf?
  • Per què el kana petit, ー i els tancaments no poden començar una línia en japonès, i com trio com d'estricta és la regla?
  • Per què el meu text japonès surt amb regles xineses: etiquetes 图, kana petit a l'inici de línia, kanji amb formes xineses?

La resposta curta

script.js · línies 34–56al codi complet
// locale 'ja' turns on JLReq composition: kinsoku at its strictest, full-width marks squeezed
// where two meet (」、 takes one em, not two), a closing mark keeps its half em at a line
// end, 、。 may hang past it, and a paragraph opening with 「 sets the bracket in the indent.
// The values below are the ones 'auto' picks for 'ja'; they are spelled out to be seen.
const cjk = {
  lineBreak: 'ja-very-strict', // no line starts with ー, small kana, 々, 」、。?・ or :
  punctuationWidth: 'fullwidth', // 、。「」 keep their em inside the line (JLReq §3.1.2)
  hangingPunctuation: 'allow', // 、。 hang only when the line would otherwise break before them
  paragraphStartBracket: 'half', // 「 at a paragraph start sits in the indent's second half
  latinSpacing: em(0.25), // 四分アキ between kana or kanji and Latin letters or digits
  grid: { enabled: true, charsPerLine: CHARS, linesPerPage: LINES }, // whole ems, whole lines
};
// The Latin is the Japanese face's own proportional Latin, at the text's size: never
// full-width A or a second face for the words in parentheses.
const bodyText = {
  fontFamily: MINCHO, fontSize: pt(BODY), lineHeight: pt(PITCH), color: col('ink'),
  boldColor: col('ink'), italicColor: col('ink'), referenceColor: col('ink'),
  textAlign: 'justify', firstLineIndent: em(1), indentAfterHeading: true, // 1 字下げ
  referenceBold: false, // 図3-1 and 表3-1 in the text weight: the face loads no bold
  hyphenation: { enabled: false }, avoidRunts: true, // no one-character last line
  // The grid cuts a list where the page ends: the four forms stay in one piece.
  shortListSplit: 'avoid', shortListMaxItems: 4,
};

Ingredients

Tipografia
Noto Serif JP, Noto Sans JP, BIZ UDGothic (SIL OFL 1.1)
Recursos
  • Figure 3-1, the bytes of が, drawn in code in the page’s palette (Postext Cookbook, CC BY 4.0)

Elaboració

#1 · Les regles japoneses arriben amb l'etiqueta

El codi és la resposta curta de més amunt. locale: 'ja' activa les regles de JLReq, els Requirements for Japanese Text Layout del W3C, i els valors escrits sota cjk són els que 'auto' tria per al japonès (Tipografia de l'Àsia oriental). Amb ja-very-strict, cap línia no comença per ー, un kana petit, 々 o un signe de tancament, i cap no acaba en un signe d'obertura. La puntuació (約物, yakumono) conserva el seu quadratí dins la línia, i dos signes que es troben, com 」、, en comparteixen un. A la pàgina 41, la línia que acaba en 実際に変換し、 treu el 、 més enllà del marge dret: és la ぶら下げ (burasage), i el motor només la fa servir quan, sense ella, hauria de passar el signe a la línia següent. latinSpacing posa un quart de quadratí (四分アキ, shibun aki) entre Unicode i では, i entre U+304C i を, tot i que el Markdown no hi porta cap espai. Només es posa al costat d'una lletra o d'una xifra: normalize() i is_normalized() acaben en parèntesi, de manera que el Markdown porta un espai entre ells i 関数.

Pàgina 41: un quart de quadratí a banda i banda d'Unicode i Python, escrits sense espai; el 、 del final de la segona línia penja fora de la mida.

La diferència amb el xinès és als signes. Un llibre xinès del continent posa 、 i , a mitja amplada per defecte i 。 a amplada completa (Kaiming); un de japonès deixa tots els signes a amplada completa i només els estreny on se'n troben dos. El tall de línia xinès no té kana petits ni ー per apartar del començament de línia, així que ja-very-strict és un nivell a part.

#2 · El codi, en una lletra monoespaiada amb kana

script.js · línies 60–71al codi complet
// A ``` fence is set line by line as written, in codeStyle's face: the monospaced face,
// which has kana and kanji too, so a full-width character takes two half-width cells.
// The rest of the fence line (normalize.py) is the listing's title. Inline `code` is set
// in the same face, in the accent.
const codeStyle = {
  fontFamily: CODE, fontSize: pt(8), lineHeight: pt(12), color: col('ink'),
  background: col('tint'), snapToGrid: false, highlight: 'none', // one ink, as in print
  padding: { top: mm(2.5), right: mm(4), bottom: mm(3), left: mm(4) },
  marginTop: mm(2), marginBottom: mm(2),
  titleStyle: { fontFamily: CODE, fontSize: pt(7), fontWeight: 400, color: col('teal') },
  inline: { fontSize: pt(8.5), color: col('teal') },
};

El bloc és un bloc de codi: Postext en compon les línies tal com estan escrites, en la lletra que indica codeStyle, dins d'un requadre tenyit sota el títol normalize.py que porta la línia d'obertura (llistats de codi). highlight: 'none' deixa el llistat en una sola tinta, com la resta de la pàgina, i codeStyle.inline compon cada `nom` en la mateixa lletra, en verd blavós. La lletra hi compta: la cadena de l'exemple, ガイド ABC ①, necessita katakana de mitja amplada, lletres d'amplada completa i xifres encerclades, que una lletra de codi occidental no té. BIZ UDGothic compon el llatí de mitja amplada i el kana d'amplada completa amb pas fix, i un llistat compta cada caràcter d'amplada completa com dues cel·les, de manera que les columnes es mantenen.

#3 · 図3-1 i 表3-1

script.js · línies 252–268al codi complet
const FORMS = `入力\tNFC\tNFD\tNFKC
が(U+304C)\tU+304C\tU+304B U+3099\tU+304C
ガ(U+FF76 U+FF9E)\tそのまま\tそのまま\tガ(U+30AC)
ABC(全角)\tそのまま\tそのまま\tABC
①\tそのまま\tそのまま\t1
㍻\tそのまま\tそのまま\t平成`;
const resources = [
  { id: 'tbl:forms', typeId: 'table', kind: 'table', createdAt: 0, updatedAt: 0,
    placement: { position: 'here' }, // at its ::resource line, under the paragraph citing it
    caption: '日本語の文字と四つの正規化形式(NFKDは、NFKCで合成された文字を分解した形になる)',
    table: { model: { ...parseTSV(FORMS), headerRowCount: 1, columnWidths: [34, 18, 26, 22] } } },
  { id: 'fig:bytes', typeId: 'figure', kind: 'svg', createdAt: 0, updatedAt: 0,
    caption: '「が」の二つの表し方。上段が符号位置、下段がUTF-8のバイト列',
    altText: 'が as one code point U+304C, three UTF-8 bytes E3 81 8C; and as U+304B and the '
      + 'combining voiced mark U+3099, six bytes E3 81 8B E3 82 99.',
    svg: { fileId: 'bytes.svg', width: 1175, height: 400 } },
];

defaultResourceTypes('ja') defineix els tipus 図 i 表 i els numera per capítol amb un guionet, i continuation.headings fa d'aquest el capítol 3, així que la primera figura és 図3-1. Un document ja ajunta l'etiqueta i el número i posa un espai ideogràfic després del número, com imprimeixen els llibres japonesos 図3-1 「が」の二つの表し方, de manera que l'estil de peu només tria la lletra i els colors. La taula va a 'here', sota el paràgraf que la cita. Els rètols de la figura són només llatins, U+304C i E3 81 8C: l'SVG indica la lletra de codi al seu estil i loadSvg hi incrusta el fitxer de la font abans de dibuixar la imatge.

#4 · Notes per pàgina, a la japonesa

script.js · línies 129–133al codi complet
  footnotes: { fontSize: pt(7.5), lineHeight: pt(12), color: col('ink'),
    separator: { color: col('rule') } }, // at the column foot, 1 on each page, superscript
  // A link in a note prints its address after the text, in parentheses: the reader of the
  // printed book can type it. 'short' drops https:// and www.; the PDF keeps the full link.
  links: { print: 'inline', urlDisplay: 'short' },

Les notes no necessiten cap paràmetre a part del cos. En un document japonès horitzontal, els valors per defecte són els que JLReq descriu per als llibres horitzontals: la nota al peu de la columna on es cita, numerada des d'1 a cada pàgina, amb la crida volada i un filet d'un terç de la mida (Notes a peu de pàgina). La crida va abans del punt, 保存していた[^hfs]。, i així el 。 no obre mai la línia següent separat d'ella.

La nota 2 cita l'informe d'Unicode que defineix les quatre formes, i la cita és un enllaç: [Unicode Standard Annex #15「…」](https://www.unicode.org/reports/tr15/). Una nota no pot portar una altra nota, així que un enllaç dins d'ella imprimeix la seva adreça després del text, entre parèntesis; links.urlDisplay: 'short' treu https:// i www., i el PDF conserva l'enllaç sencer. links.print: 'inline' fa el mateix amb un enllaç del text (Enllaços en paper). La nota comença amb paraules japoneses, perquè la primera línia s'ompli abans del títol llatí, que és llarg.

#5 · Un títol d'apartat de tres línies

script.js · línies 75–90al codi complet
const BAND = 74; // mm from the trim's top
const opener = { enabled: true, minHeight: pt(PITCH * 10), slot: { elements: [ // text: line 11
  { kind: 'box', id: 'band', reserve: false, style: { backgroundColor: col('tint') },
    placement: { anchor: { to: 'page', edge: 'top-left' },
      size: { width: 'fill', height: mm(BAND) } } },
  { kind: 'text', id: 'kicker', content: 'CHAPTER', fontFamily: GOTHIC, fontSize: pt(8),
    fontWeight: 700, letterSpacing: pt(1.6), color: col('teal'), align: 'left',
    placement: { anchor: { to: 'container', edge: 'top-left' }, offset: { y: mm(0) } } },
  { kind: 'text', id: 'number', content: '{numberDecimal}', fontFamily: GOTHIC, fontSize: pt(64),
    lineHeight: 1, fontWeight: 700, color: col('teal'), align: 'left',
    placement: { anchor: { to: '#kicker', edge: 'below' }, offset: { y: mm(1) } } },
  { kind: 'text', id: 'title', content: '{titleText}', fontFamily: GOTHIC,
    fontSize: pt(20), fontWeight: 700, color: col('ink'), align: 'left', overflow: 'wrap',
    placement: { anchor: { to: '#number', edge: 'below' }, offset: { y: mm(5) },
      size: { width: mm(MEASURE) } } },
] } };

L'obertura del capítol és un disseny sobre l'H1: una banda verd blavós, el número del capítol a 64 pt pres de {numberDecimal} i el títol. Els títols d'apartat fan servir lineSpan: 3, el 行取り (gyōdori): cadascun ocupa exactament tres línies de text, amb el text centrat dins seu, de manera que el text que el segueix continua al pas de la retícula. headings.balancing.enabled: false impedeix que el motor afegeixi línies sobre els títols per igualar una pàgina.

La recepta completa

Sandbox
// ═══ Postext Cookbook · Nº 123 · A Japanese technical manual: kana, kanji and Latin ═══
// https://postext.dev/en/cookbook/japanese-technical-manual
// Code: MIT · Text: original (CC BY 4.0) · Pictures: drawn in code
// Fonts: Noto Serif JP, Noto Sans JP, BIZ UDGothic (SIL OFL 1.1) · Needs postext ≥ 1.65.0
import {
  buildDocument, withLoadedFonts, renderPageToCanvas, defaultResourceTypes, parseTSV,
  registerResourceImage, inlineSvgFonts,
} from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';

const LANG = 'es'; // @lang: the language of the frame; the chapter is Japanese in both
const RECIPE = 'japanese-technical-manual';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: ink, one deep teal for numbers, rules and labels, a pale tint for code
const palette = {
  ink: '#1d2327', // text: a cool near-black
  teal: '#0e5a6e', // the one accent: chapter number, heads' numbers, labels, the point box
  tint: '#e7f0f2', // the opener band, the listing's ground
  rule: '#b9c6cc', // hairlines: table rules, the note rule
  muted: '#5b666d', // running heads, folios, colophon
  paper: '#ffffff',
};
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = Object.entries({ ...palette, 'main-color': palette.teal })
  .map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
// #endregion
const [MINCHO, GOTHIC, CODE] = ['Noto Serif JP', 'Noto Sans JP', 'BIZ UDGothic'];
const [BODY, PITCH] = [9, 16]; // pt: 9 pt text on a 16 pt line, 1.78 × the size
const [CHARS, LINES] = [36, 29]; // the type area in characters: 36 to a line, 29 lines
const MEASURE = CHARS * BODY * 25.4 / 72; // mm: 114.3

// #region answer: Japanese rules from the tag, written out; the quarter-em Latin space
// locale 'ja' turns on JLReq composition: kinsoku at its strictest, full-width marks squeezed
// where two meet (」、 takes one em, not two), a closing mark keeps its half em at a line
// end, 、。 may hang past it, and a paragraph opening with 「 sets the bracket in the indent.
// The values below are the ones 'auto' picks for 'ja'; they are spelled out to be seen.
const cjk = {
  lineBreak: 'ja-very-strict', // no line starts with ー, small kana, 々, 」、。?・ or :
  punctuationWidth: 'fullwidth', // 、。「」 keep their em inside the line (JLReq §3.1.2)
  hangingPunctuation: 'allow', // 、。 hang only when the line would otherwise break before them
  paragraphStartBracket: 'half', // 「 at a paragraph start sits in the indent's second half
  latinSpacing: em(0.25), // 四分アキ between kana or kanji and Latin letters or digits
  grid: { enabled: true, charsPerLine: CHARS, linesPerPage: LINES }, // whole ems, whole lines
};
// The Latin is the Japanese face's own proportional Latin, at the text's size: never
// full-width A or a second face for the words in parentheses.
const bodyText = {

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 que el kana petit i ー obrin línia

ja-strict és la regla de JLReq per als llibres generals: っ, ゃ i ー poden obrir línia, cosa que dona al tallador més punts de tall i menys línies espaiades.

-  lineBreak: 'ja-very-strict', // no line starts with ー, small kana, 々, 」、。?・ or :
+  lineBreak: 'ja-strict', // small kana, ー and 々 may open a line

#Sense espai entre el japonès i el llatí

Algunes editorials componen les paraules llatines enganxades al kana, sense el quart de quadratí.

-  latinSpacing: em(0.25), // 四分アキ between kana or kanji and Latin letters or digits
+  latinSpacing: em(0), // Unicodeでは, set solid

Errors freqüents

Error freqüent

Etiqueta un text japonès 'ja', mai zh-Hans ni LANG

Les edicions d'una recepta són en i es, però una mostra japonesa és japonesa en totes dues: `locale: LANG` l'etiquetaria com a anglès o castellà, i una etiqueta xinesa la compondria amb les regles xineses (puntuació Kaiming, kana petit lliure de començar línia, 图 en lloc de 図, formes xineses dels caràcters al PDF). 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 qualsevol etiqueta que no sigui 'ja' dona altres formes de glif que les japoneses (les xineses, amb una etiqueta xinesa) i altres talls de línia. Escriu 'ja': tria la regió del Japó (tall i puntuació de la JLReq, punts de sèsam, repartiment dels furigana, etiquetes 図 i 表) i desactiva la partició de mots. El lint falla un text amb kana sota una etiqueta zh o ko. Tall de línies japonès (kinsoku) →

Error freqüent

Compon el japonès amb una font japonesa

Noto Serif SC i TC tenen kana, però dibuixen els kanji amb formes xineses (直, 骨 i 角 canvien) i el kana amb un disseny xinès. Compon el text en Noto Serif JP o Shippori Mincho B1 i els títols en Noto Sans JP, carregades amb loadCjkFonts. Els fitxers japonesos de Fontsource no tenen hentaigana ni altres kana històrics (U+1B000–1B16F): loadCjkFonts hi falla i el PDF imprimeix caixes, així que escriu el kana modern o porta als recursos de la recepta una font que els tingui. Shippori Mincho tampoc no té les vocals amb macró ō i ū: compon el rōmaji amb una font llatina. Kana, kanji i rōmaji →

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 →

  • Una paraula llatina no es pot tallar dins d'una línia japonesa, així que una de llarga al final de línia deixa l'anterior espaiada entre els caràcters. El primer esborrany d'aquest capítol glossava els termes en anglès, 正準等価(canonical equivalence), i dues línies van sortir fluixes; es van treure els termes anglesos allà on no ajudaven el lector.
  • Tria la lletra del codi pels caràcters que conté. M PLUS 1 Code, la primera que es va provar aquí, no té katakana de mitja amplada: la pantalla va recórrer a una lletra del sistema per a ガイド i al PDF hi faltaven els glifs.
  • Un llistat es divideix entre línies d'una pàgina a l'altra, amb almenys dues línies a cada costat (codeStyle.splitMinLines). A la pàgina 43, l'espai que queda sota 3.3 no admet el títol i dues línies, així que el llistat sencer obre la pàgina 44; keepTogether: true manté cada llistat d'una peça.
  • En una retícula de caràcters la pàgina porta les seves 29 línies faci el que faci un paràgraf o una llista en el canvi de pàgina, així que la llista de les quatre formes deixaria el primer element, NFC, sol al peu de la pàgina 42. shortListSplit: 'avoid' amb shortListMaxItems: 4 passa la llista sencera a la pàgina 43, i la pàgina 42 acaba una línia abans, sobre les notes a peu de pàgina.

Crèdits

Text
Text original, CC BY 4.0
Imatges
  • Figure 3-1, the bytes of が, drawn in code in the page’s palette · Postext Cookbook · CC BY 4.0
Fonts
Noto Serif JP (SIL OFL 1.1) · Noto Sans JP (SIL OFL 1.1) · BIZ UDGothic (SIL OFL 1.1)
SandboxPDF