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
// 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
- Funcions
- Espaiat de la puntuació japonesa (yakumono)Tall de línies japonès (kinsoku)Espai entre xinès i llatíNotes dels llibres japonesosNotes a peu de pàginaAdreces dels enllaços en paperPeus numeratsFigura i Taula en la teva llenguaTítols numeratsTítols que ocupen línies del text (gyōdori)Retícula de caràctersFonts xineses, japoneses i coreanesLlistats de codiRequadresEstil de taulesEstil dels peusFigures i taules com a recursosCapçaleres i folisObertures dissenyadesExportació a PDF
- També fa servir
- Cites en un estil de citaTall de línies en xinèsAmplada de la puntuació xinesaEquilibri de columnesReferències creuadesFigures just aquíCapçaleres segons el tipus de pàginaEstils de paràgrafFonts incrustades al PDFTipus de recurs propisTaules a partir de dades
- 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 関数.

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
// 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
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
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
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
// ═══ 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 solidErrors 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: truemanté 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'ambshortListMaxItems: 4passa 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
- Recepta
- Ignacio Ferro
- 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)
- Codi
- MIT, com Postext
Editar aquest text ↗ (s'obre en una pestanya nova)Carpeta de la recepta a GitHub ↗ (s'obre en una pestanya nova)


