En pocas palabras
Un capítulo de un libro japonés de programación, lleno de palabras inglesas, código y números. Postext compone la puntuación y los cortes de línea con las reglas japonesas y añade un espacio fino donde el japonés toca el latín.
Lo que vas a componer
Cinco páginas del capítulo 3 de un libro japonés de programación inventado, 実践 日本語テキスト処理 (Procesamiento práctico de texto japonés), sobre la normalización Unicode. Va compuesto como los libros japoneses de informática: A5, una columna de 36 caracteres por 29 líneas de Noto Serif JP a 9 pt, títulos en Noto Sans JP y código en BIZ UDGothic. Es el caso difícil de la composición japonesa, porque casi cada frase lleva una palabra latina, un punto de código, una cifra o un nombre de función: los cortes de línea siguen el 禁則処理 (kinsoku shori) más estricto de JLReq, la puntuación conserva su espaciado de ancho completo y un cuarto de cuadratín separa el japonés del latín sin que nadie teclee un espacio. Una figura, una tabla, un listado y notas al pie llevan rótulos japoneses: 図3-1, 表3-1 y números volados que se cuentan por página. Listados de código y teclas es la misma clase de página en inglés.
Esta receta responde a
- ¿Cómo espacio la puntuación japonesa: 、。「」 apretados donde se juntan, un espacio tras ?! y el corchete que abre un párrafo?
- ¿Por qué el kana pequeño, ー y los cierres no pueden empezar una línea en japonés, y cómo elijo lo estricta que es la regla?
- ¿Por qué mi texto japonés sale con reglas chinas: etiquetas 图, kana pequeño al principio de línea, kanji con formas chinas?
La respuesta corta
// 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,
};
Ingredientes
- Funciones
- Espaciado de la puntuación japonesa (yakumono)Corte de líneas japonés (kinsoku)Espacio entre chino y latínNotas de los libros japonesesNotas al pieDirecciones de los enlaces en papelPies numeradosFigura y Tabla en tu idiomaTítulos numeradosTítulos que ocupan líneas del texto (gyōdori)Retícula de caracteresFuentes chinas, japonesas y coreanasListados de códigoRecuadrosEstilo de tablasEstilo de los piesFiguras y tablas como recursosCabeceras y foliosAperturas diseñadasExportación a PDF
- También usa
- Citas en un estilo de citaCorte de líneas en chinoAnchura de la puntuación chinaEquilibrado de columnasReferencias cruzadasFiguras justo aquíCabeceras según el tipo de páginaEstilos de párrafoFuentes incrustadas en el PDFTipos de recurso propiosTablas a partir de datos
- Tipografía
- Noto Serif JP, Noto Sans JP, BIZ UDGothic (SIL OFL 1.1)
- Recursos
- La figura 3-1, los bytes de が, dibujada en código con la paleta de la página (Postext Cookbook, CC BY 4.0)
Elaboración
#1 · Las reglas japonesas vienen con la etiqueta
El código es la respuesta corta de arriba. locale: 'ja' activa las reglas de JLReq, los Requirements for Japanese Text Layout del W3C, y los valores escritos bajo cjk son los que 'auto' elige para el japonés (Tipografía de Asia oriental). Con ja-very-strict, ninguna línea empieza por ー, un kana pequeño, 々 o un signo de cierre, y ninguna acaba en un signo de apertura. La puntuación (約物, yakumono) conserva su cuadratín dentro de la línea, y dos signos que se juntan, como 」、, comparten uno. En la página 41, la línea que acaba en 実際に変換し、 saca su 、 más allá del margen derecho: es la ぶら下げ (burasage), y el motor solo la usa cuando, sin ella, tendría que pasar el signo a la línea siguiente. latinSpacing pone un cuarto de cuadratín (四分アキ, shibun aki) entre Unicode y では, y entre U+304C y を, aunque el Markdown no lleva espacio ahí. Solo se pone junto a una letra o una cifra: normalize() e is_normalized() acaban en paréntesis, así que el Markdown lleva un espacio entre ellos y 関数.

La diferencia con el chino está en los signos. Un libro chino del continente pone 、 y , a medio ancho por omisión y 。 a ancho completo (Kaiming); uno japonés deja todos los signos a ancho completo y solo los aprieta donde se juntan dos. Los cortes del chino no tienen kana pequeños ni ー que apartar del principio de línea, así que ja-very-strict es un nivel propio.
#2 · Código en una letra monoespaciada con 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 bloque delimitado es un bloque de código: Postext compone sus líneas tal como están escritas, en la letra que indica codeStyle, dentro de un recuadro tintado bajo el título normalize.py que trae la línea de apertura (listados de código). highlight: 'none' deja el listado en una sola tinta, como el resto de la página, y codeStyle.inline compone cada `nombre` en la misma letra, en verde azulado. La letra importa: la cadena del ejemplo, ガイド ABC ①, necesita katakana de medio ancho, letras de ancho completo y cifras en círculo, que una letra de código occidental no tiene. BIZ UDGothic compone el latín de medio ancho y el kana de ancho completo con paso fijo, y un listado cuenta cada carácter de ancho completo como dos celdas, así que las columnas se mantienen.
#3 · 図3-1 y 表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') llama a los tipos 図 y 表 y los numera por capítulo con un guion, y continuation.headings hace de este el capítulo 3, así que la primera figura es 図3-1. Un documento ja junta rótulo y número y pone un espacio ideográfico tras el número, como imprimen los libros japoneses 図3-1 「が」の二つの表し方, así que el estilo de pie solo elige la letra y los colores. La tabla va en 'here', debajo del párrafo que la cita. Los rótulos de la figura son solo latinos, U+304C y E3 81 8C: el SVG indica la letra de código en su estilo y loadSvg incrusta el archivo de la fuente antes de dibujar la imagen.
#4 · Notas por 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' },
Las notas no necesitan más ajuste que su cuerpo: en un documento japonés horizontal, los valores por omisión son los que JLReq describe para los libros horizontales, la nota al pie de la columna donde se cita, numerada desde 1 en cada página, con la llamada volada y un filete de un tercio de la medida (Notas al pie). La llamada va antes del punto, 保存していた[^hfs]。, así que el 。 nunca abre la línea siguiente separado de ella.
La nota 2 cita el informe de Unicode que define las cuatro formas, y la cita es un enlace: [Unicode Standard Annex #15「…」](https://www.unicode.org/reports/tr15/). Una nota no puede llevar otra nota, así que un enlace dentro de ella imprime su dirección tras el texto, entre paréntesis; links.urlDisplay: 'short' quita https:// y www., y el PDF conserva el enlace entero. links.print: 'inline' hace lo mismo con un enlace del texto (Enlaces en papel). La nota empieza con palabras japonesas, para que su primera línea se llene antes del título latino, que es largo.
#5 · Un título de apartado de tres líneas
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) } } },
] } };
La apertura del capítulo es un diseño sobre el H1: una banda verde azulado, el número del capítulo a 64 pt tomado de {numberDecimal} y el título. Los títulos de apartado usan lineSpan: 3, el 行取り (gyōdori): cada uno ocupa exactamente tres líneas del texto, con su texto centrado en ellas, así que el texto que sigue va al paso de la retícula. headings.balancing.enabled: false impide que el motor añada líneas sobre los títulos para igualar una página.
La receta 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 = {
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
#Deja que el kana pequeño y ー abran línea
ja-strict es la regla de JLReq para los libros generales: っ, ゃ y ー pueden abrir línea, lo que da al cortador más sitios donde cortar y menos líneas espaciadas.
- lineBreak: 'ja-very-strict', // no line starts with ー, small kana, 々, 」、。?・ or :
+ lineBreak: 'ja-strict', // small kana, ー and 々 may open a line#Sin espacio entre japonés y latín
Algunas editoriales componen las palabras latinas pegadas al kana, sin el cuarto de cuadratín.
- latinSpacing: em(0.25), // 四分アキ between kana or kanji and Latin letters or digits
+ latinSpacing: em(0), // Unicodeでは, set solidErrores frecuentes
Error frecuente
Etiqueta un texto japonés 'ja', nunca zh-Hans ni LANG
Las ediciones de una receta son en y es, pero una muestra japonesa es japonesa en las dos: `locale: LANG` la etiquetaría como inglés o español, y una etiqueta china la compondría con las reglas chinas (puntuación Kaiming, kana pequeño libre de empezar línea, 图 en lugar de 図, formas chinas de los caracteres en el PDF). Desde postext 1.30 la etiqueta es además el idioma en el que se compone el texto (en el que se mide, se pinta y se incrusta), así que cualquier etiqueta que no sea 'ja' da otras formas de glifo que las japonesas (las chinas, con una etiqueta china) y otros cortes de línea. Escribe 'ja': elige la región de Japón (corte y puntuación de la JLReq, puntos de sésamo, reparto de los furigana, etiquetas 図 y 表) y desactiva la separación silábica. El lint falla un texto con kana bajo una etiqueta zh o ko. Corte de líneas japonés (kinsoku) →
Error frecuente
Compón el japonés con una fuente japonesa
Noto Serif SC y TC tienen kana, pero dibujan los kanji con formas chinas (直, 骨 y 角 cambian) y el kana con un diseño chino. Compón el texto en Noto Serif JP o Shippori Mincho B1 y los títulos en Noto Sans JP, cargadas con loadCjkFonts. Los archivos japoneses de Fontsource no tienen hentaigana ni otros kana históricos (U+1B000–1B16F): loadCjkFonts falla con ellos y el PDF imprime cajas, así que escribe el kana moderno o lleva en los recursos de la receta una fuente que los tenga. Shippori Mincho tampoco tiene las vocales con macrón ō y ū: compón el rōmaji con una fuente latina. Kana, kanji y rōmaji →
Error frecuente
Las fuentes chinas se cargan por fragmentos, con el bloque cjk
Fontsource sirve una familia china, japonesa o coreana en un centenar de archivos por peso, cada uno con un intervalo de caracteres. loadFonts solo descarga el archivo latin, así que en pantalla los caracteres chinos salen de una fuente del sistema y se miden mal, y fontsourceProvider entrega al PDF ese archivo latin, que los imprime como cajas vacías. Añade el bloque cjk del kit, llama a loadCjkFonts(FONTS, markdown) después de loadFonts (una vez por voz, con el texto que compone, si el libro usa varias fuentes chinas) y pasa a renderToPdf fontProvider: cjkPdfProvider: ambos toman los archivos que contienen los caracteres del texto. Fuentes chinas, japonesas y coreanas →
- Una palabra latina no se puede cortar dentro de una línea japonesa, así que una larga al final de la línea deja la anterior espaciada entre sus caracteres. El primer borrador de este capítulo glosaba los términos en inglés, 正準等価(canonical equivalence), y dos líneas salieron flojas; se quitaron los términos ingleses donde no ayudaban al lector.
- Elige la letra del código por los caracteres que lleva. M PLUS 1 Code, la primera que se probó aquí, no tiene katakana de medio ancho: la pantalla recurrió a una letra del sistema para ガイド y al PDF le faltaban los glifos.
- Un listado se parte entre líneas de una página a otra, con al menos dos líneas a cada lado (
codeStyle.splitMinLines). En la página 43, el espacio que queda bajo 3.3 no admite el título y dos líneas, así que el listado entero abre la página 44;keepTogether: truemantiene cada listado de una pieza. - En una retícula de caracteres la página lleva sus 29 líneas haga lo que haga un párrafo o una lista en el cambio de página, así que la lista de las cuatro formas dejaría su primer elemento, NFC, solo al pie de la página 42.
shortListSplit: 'avoid'conshortListMaxItems: 4pasa la lista entera a la página 43, y la página 42 acaba una línea antes, sobre sus notas al pie.
Créditos
- Receta
- Ignacio Ferro
- Texto
- Texto original, CC BY 4.0
- Imágenes
- La figura 3-1, los bytes de が, dibujada en código con la paleta de la página · Postext Cookbook · CC BY 4.0
- Fuentes
- Noto Serif JP (SIL OFL 1.1) · Noto Sans JP (SIL OFL 1.1) · BIZ UDGothic (SIL OFL 1.1)
- Código
- MIT, como Postext
Editar este texto ↗ (se abre en una nueva pestaña)Carpeta de la receta en GitHub ↗ (se abre en una nueva pestaña)


