Pular para o conteúdo principal
Receita número 79

Receitas · Capítulo 5 · Estrutura do livro

Um índice de nomes chineses, por pinyin e por traços

As mesmas marcas :index em duas edições de uma antologia de 紅樓夢: index.groupBy agrupa os nomes pela inicial em pinyin em zh-Hans e por traços em zh-Hant.

Nesta página
Saída
Canvas · PDF
Postext
Testada com o Postext 1.65.0
Requer ≥ 1.28.0 · postext-pdf ≥ 1.28.0
Licença
Atualizada em 11 de out. de 2026
Código MIT · Texto CC BY 4.0

p. 6–7 de 16

  • Amostra em inglês: ainda sem edição em português
  • Refile 140 × 203 mm
  • 1 coluna
  • Noto Serif SC 10,5/18
  • LXGW WenKai TC
  • Ma Shan Zheng
  • Noto Sans SC
  • Noto Sans TC
  • Noto Serif TC
  • 16 páginas
  • Nível
  • Postext 1.65.0
  • Diagramado em 142 ms
  • 180 linhas de código

Em poucas palavras

Uma antologia curta de um grande romance chinês com um índice dos nomes dos personagens. As mesmas marcas dão duas edições: uma em ordem de som, outra pelo número de traços.

O que você vai compor

Uma antologia fina de 紅樓夢 (O Sonho da Câmara Vermelha) que reproduz, dos capítulos 1 a 3, os trechos em que cada personagem aparece pela primeira vez e termina com um índice dos 47 nomes, mais quatro remissões a partir de outros nomes. Ela sai em duas edições com as mesmas marcas. A da China continental, em caracteres simplificados, ordena os nomes pela inicial em pinyin, F, H, J…; a de Taiwan, em caracteres tradicionais, pelo número de traços do primeiro caractere, 三畫, 四畫… As duas são brochuras 大32开, de 140 × 203 mm, com 26 caracteres por linha em Noto Serif, os títulos de capítulo numa Kai e os chapéus, os fólios e as letras do índice em Noto Sans. O card amplia os primeiros grupos do índice simplificado, de F a L. Um índice onomástico e um índice de assuntos faz o mesmo tipo de índice para uma monografia em inglês.

Esta receita responde a

  • Como agrupo um índice de nomes chineses por pinyin ou por número de traços?
  • Como levo os caracteres chineses para o PDF sem caixas vazias?

A resposta curta

script.js · linhas 44–57no código completo
// Marks in the Markdown, one per passage; main is the page where the character enters:
//   字:index[士隐]{term="甄士隐" main}      :index{term="贾化" see="贾雨村"}
// Printed at the end of each edition: # 人名索引 {style="index"}, then :::index
const index = (e) => ({
  // 'auto' reads the same from the locale: pinyin for zh-Hans, strokes for zh-Hant.
  groupBy: e.locale === 'zh-Hans' ? 'pinyin' : 'stroke', // A B C… or 三畫 四畫…
  fontFamily: e.serif, fontSize: pt(9), lineHeight: pt(14),
  separator: '\u3000', locatorSeparator: ',', // 贾宝玉 4,6: an ideographic space, then ,
  see: { italic: false }, // 见 / 見 upright: Chinese has no italic (gotcha: cjk-no-italic)
  groups: { fontFamily: e.sans, fontSize: pt(9.5), fontWeight: 700, color: col('cinnabar'),
    marginTop: pt(6.25) }, // the three names of 九畫 stay whole at the foot of their column
});
const indexHeading = { id: 'index', numbered: false, breakBefore: { enabled: true, parity: 'any' },
  layout: { layoutType: 'double', gutterWidth: pt(21) } }; // two columns, 2 characters apart

Ingredientes

Tipografia
Noto Serif SC, Noto Sans SC, Ma Shan Zheng, Noto Serif TC, Noto Sans TC, LXGW WenKai TC (SIL OFL 1.1)
Materiais
Nenhum: todas as imagens são desenhadas em código

Preparo

#1 · Marcar cada nome onde o leitor o encontra

O código é a resposta curta lá em cima; o resto está no Markdown. Uma marca registra o nome completo, seja qual for a forma que o texto imprime: 字:index[士隐]{term="甄士隐" main} imprime 士隐 e registra uma página sob 甄士隐. main põe a página em negrito, e a nota sob o título do índice explica o que o negrito significa aqui: a página em que o personagem entra em cena. Jia Baoyu nasce no capítulo 2 sem ser nomeado (又生了一位公子), por isso a marca entra sem nada para imprimir, :index{term="贾宝玉"}, e a entrada fica 4, 6. Outros nomes e apelidos recebem uma remissão própria, :index[凤辣子]{term="凤辣子" see="王熙凤"}, que o Postext imprime à maneira chinesa, depois de um ponto e sem espaço: 凤辣子。见王熙凤 (marcas de índice).

#2 · Deixar o idioma escolher a ordem

script.js · linhas 30–37no código completo
// The mainland edition in Simplified characters and the Taiwan edition in Traditional ones.
// Each takes the Song (serif), Hei (sans) and Kai faces cut for its script. Fontsource has no
// Kai text face with mainland forms: LXGW WenKai TC draws 冷 the Taiwan way, so the mainland
// titles take Ma Shan Zheng, a brush Kai.
const EDITIONS = {
  hans: { locale: 'zh-Hans', serif: 'Noto Serif SC', sans: 'Noto Sans SC', kai: 'Ma Shan Zheng' },
  hant: { locale: 'zh-Hant', serif: 'Noto Serif TC', sans: 'Noto Sans TC', kai: 'LXGW WenKai TC' },
};

As duas edições compartilham a configuração, e locale é a única chave de que o índice precisa: groupBy: 'auto' agrupa um índice zh-Hans por pinyin e um zh-Hant por traços, e a resposta curta escreve os dois valores por extenso para você ver. As entradas se ordenam pelo mesmo critério dos títulos de grupo, de modo que os mesmos nomes trocam de lugar: 甄费 vem antes de 甄士隐 no Z (fèi antes de shì) e depois dele em 十四畫 (士 tem três traços; 費, doze); 宁国公 e 荣国公 se separam em N e R, enquanto 寧國公 e 榮國公 continuam juntos entre os nomes de catorze traços (índice remissivo). As leituras e os números de traços vêm da ordenação chinesa do navegador; um sobrenome que ela lê errado (曾, 单, 解) recebe uma chave sort escrita com caracteres que tenham a leitura certa.

#3 · Carregar cada fonte com os caracteres que ela compõe

script.js · linhas 270–279no código completo
const DIGITS = '0123456789';
const HEADS = '第回一二三四五六七八九十画畫ABCDEFGHIJKLMNOPQRSTUVWXYZ'; // 第一回, the index heads
const all = (md, re) => [...md.matchAll(re)].map((m) => m[1]).join('\n');
for (const [key, md] of [['hans', markdown], ['hant', traditional]]) {
  e = EDITIONS[key];
  await loadCjkFonts({ [e.serif]: ['400'] }, md); // the text, the index, the running heads
  await loadCjkFonts({ [e.serif]: ['700'] }, DIGITS); // the bold page numbers
  await loadCjkFonts({ [e.sans]: ['700'] }, all(md, /kicker="([^"]*)"/g) + HEADS + DIGITS);
  await loadCjkFonts({ [e.kai]: ['400'] }, all(md, /^# ([^{\n]*)/gm)); // the titles alone
}

A Fontsource corta cada peso de uma fonte chinesa em cerca de cem arquivos, e loadCjkFonts baixa os que seu texto toca. A Song recebe o livro inteiro, por isso os cabeços não custam nada a mais; o negrito, os algarismos das páginas principais; a Hei, o texto dos atributos kicker, os títulos de grupo do índice e os algarismos dos fólios; a Kai, os três dísticos e 人名索引. O PDF segue o mesmo caminho: cjkPdfProvider incorpora esses arquivos, cada um reduzido aos caracteres que as páginas usam, e nenhum caractere sai como uma caixa vazia. A Kai muda com a edição. A LXGW WenKai TC, a única Kai de texto da Fontsource, desenha formas herdadas, 冷 com o antigo pé 卩 de 令, e centra vírgulas e pontos, por isso os títulos da edição simplificada são compostos em Ma Shan Zheng, uma Kai de pincel com as formas do continente (fontes chinesas, japonesas e coreanas).

#4 · Pôr a nota na abertura do índice

script.js · linhas 61–81no código completo
const opener = (e, sink, kicker, note = []) => ({
  enabled: true,
  minHeight: pt(LEAD * sink), // the text starts on the same line after every opener
  slot: { elements: [
    { kind: 'text', id: 'kicker', content: kicker, fontFamily: e.sans, fontSize: pt(9),
      fontWeight: 700, letterSpacing: pt(2.7), color: col('cinnabar'), align: 'center',
      placement: { ...at('container', 'top', 0, 8), size: { width: 'fill', height: 'auto' } } },
    { kind: 'text', id: 'title', content: '{titleText}', fontFamily: e.kai, fontSize: pt(16),
      lineHeight: 1.45, color: col('ink'), align: 'center',
      overflow: 'wrap', // design text ends in an ellipsis by default
      placement: { ...at('#kicker', 'below', 0, 3), size: { width: 'fill', height: 'auto' } } },
    { kind: 'rule', id: 'rule', direction: 'horizontal', thickness: pt(0.5), color: col('rule'),
      placement: { ...at('#title', 'below', (MEASURE - 12) / 2, 4), size: { width: mm(12) } } },
    ...note,
  ] },
});
// The note (note="…" on the heading) sits above the columns: no paragraph for balancing to loosen.
const indexNote = (e) => [{ kind: 'text', id: 'note', content: '{attr.note}',
  fontFamily: e.serif, fontSize: pt(9), lineHeight: 1.6, color: col('muted'), align: 'center',
  overflow: 'wrap', placement: { ...at('#rule', 'below', -(MEASURE - 12) / 2, 4),
    size: { width: 'fill', height: 'auto' } } }];

A nota é um atributo do título, # 人名索引 {style="index" kicker="按汉语拼音排列" note="…"}, composto na medida inteira, acima das duas colunas. Como parágrafo dentro das colunas, ela servia de alavanca para o equilíbrio: para igualar a última página da edição tradicional, a diagramação a afrouxava para doze caracteres por linha numa coluna de catorze. A nota é uma frase só, 本索引收录前三回选文中的人物,粗体页码为人物出场之页;别名与原名另立参见条目。, que o design quebra em linhas: o texto de design de um livro chinês segue as regras de quebra de linha e as larguras dos sinais do corpo, de modo que ,; ficam em meia largura na edição simplificada e em largura cheia na tradicional, como no texto, e nenhuma linha da nota começa com um sinal. As aberturas de capítulo usam o mesmo design, com 第{numberHan}回 como chapéu, que imprime 第一回 na escrita do documento.

#5 · Mostrar as duas páginas de índice lado a lado

script.js · linhas 304–320no código completo
const indexPage = (doc) => doc.pages[doc.blocks.find((b) => b.headingStyleId === 'index')
  ?.pageIndex ?? doc.pages.length - 1];
const labels = { hans: t({ en: 'Simplified · by pinyin', es: 'Simplificado · por pinyin' }),
  hant: t({ en: 'Traditional · by strokes', es: 'Tradicional · por trazos' }) };
document.getElementById('pages').insertAdjacentHTML('beforebegin', `<section id="indexes" style="
  display:flex;flex-wrap:wrap;justify-content:center;gap:24px;padding:28px 16px;background:#e9e4da">
  ${Object.keys(docs).map((key) => `<figure style="margin:0;width:min(340px,44vw)">
  <canvas id="index-${key}" role="img" style="display:block;width:100%;background:#fff;
  box-shadow:0 18px 36px -18px rgb(0 0 0 / .45)"></canvas><figcaption style="margin-top:10px;
  font:600 11px/1 system-ui,sans-serif;letter-spacing:.14em;text-transform:uppercase;color:#5b534a">
  ${labels[key]}</figcaption></figure>`).join('')}</section>`);
for (const [key, doc] of Object.entries(docs)) {
  const canvas = document.getElementById(`index-${key}`);
  const page = indexPage(doc);
  canvas.setAttribute('aria-label', `${labels[key]}, ${page.pageLabel}`);
  renderPageToCanvas(page, doc, canvas, { scale: (2 * canvas.clientWidth) / page.width });
}

O pen compõe as duas edições e deixa a simplificada na mesa. Os botões 简体版 e 繁體版 trocam a edição da mesa, e cada troca oferece o PDF da edição que está à vista, chinese-name-index-hans.pdf ou chinese-name-index-hant.pdf. A captura registra as duas composições (capture.doc: ['first', 'last']): as oito primeiras páginas acima são da edição simplificada, e as quatro seguintes vêm da tradicional, a primeira página e o índice por traços. A faixa acima da mesa traz a primeira página de índice de cada edição. O PDF oferecido com a receita é o da edição simplificada.

A receita completa

Sandbox
// ═══ Postext Cookbook · Nº 079 · An index of Chinese names, by pinyin and by strokes ═══
// https://postext.dev/en/cookbook/chinese-name-index
// Code: MIT · Text: 紅樓夢 (1792), zh.wikisource revision 9685985 (CC BY-SA 4.0) · Pictures: none
// Fonts: Noto Serif/Sans SC/TC, Ma Shan Zheng, LXGW WenKai TC (OFL 1.1) · Needs postext ≥ 1.28.0
import { buildDocument, withLoadedFonts, renderPageToCanvas } from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';

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

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: ink on a warm paper, one cinnabar for the heads and the index letters
const palette = {
  ink: '#1f1b18', // text
  cinnabar: '#a3301f', // the one accent: 回 numbers, index heads
  muted: '#6b635a', // running heads, folios, colophon
  rule: '#d6cdbf', // the short rule under each title
  paper: '#fbf8f1',
};
// Each colour carries its hex and the palette entry it follows.
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, never the default blue.
  { id: 'main-color', name: 'accent (defaults)', value: { hex: palette.cinnabar, model: 'hex' } },
];
// #endregion

// #region editions: one book, two scripts; the locale decides the index order
// The mainland edition in Simplified characters and the Taiwan edition in Traditional ones.
// Each takes the Song (serif), Hei (sans) and Kai faces cut for its script. Fontsource has no
// Kai text face with mainland forms: LXGW WenKai TC draws 冷 the Taiwan way, so the mainland
// titles take Ma Shan Zheng, a brush Kai.
const EDITIONS = {
  hans: { locale: 'zh-Hans', serif: 'Noto Serif SC', sans: 'Noto Sans SC', kai: 'Ma Shan Zheng' },
  hant: { locale: 'zh-Hant', serif: 'Noto Serif TC', sans: 'Noto Sans TC', kai: 'LXGW WenKai TC' },
};
// #endregion
const LEAD = 18; // body leading in pt: 1.7 × the 10.5 pt text (五号)
const MEASURE = (26 * 10.5 * 25.4) / 72; // the grid's 26 characters of 10.5 pt, in mm
const at = (to, edge, x = 0, y = 0) => ({ anchor: { to, edge }, offset: { x: mm(x), y: mm(y) } });

// #region answer: the same marks, grouped by pinyin in zh-Hans and by strokes in zh-Hant
// Marks in the Markdown, one per passage; main is the page where the character enters:
//   字:index[士隐]{term="甄士隐" main}      :index{term="贾化" see="贾雨村"}
// Printed at the end of each edition: # 人名索引 {style="index"}, then :::index
const index = (e) => ({
  // 'auto' reads the same from the locale: pinyin for zh-Hans, strokes for zh-Hant.

O script.js montado funciona como está: cole-o como script de módulo em qualquer página ou abra a receita no CodePen. Pasta da receita no GitHub ↗ (abre em uma nova aba)

Variações

#Agrupar por pinyin um índice em caracteres tradicionais

Uma edição tradicional para leitores que procuram os nomes pela leitura pode ordená-los por pinyin. Defina groupBy: 'pinyin' nas duas edições: os títulos de grupo são A–Z e as entradas mantêm as formas tradicionais. O chapéu diz como o índice está ordenado, por isso mude-o também no Markdown tradicional, para kicker="依漢語拼音排列".

-  groupBy: e.locale === 'zh-Hans' ? 'pinyin' : 'stroke', // A B C… or 三畫 四畫…
+  groupBy: 'pinyin', // A B C… in both scripts

#Imprimir os nomes sem cabeçalhos

Uma lista curta de nomes fica boa de ler com uma linha em branco entre os grupos e nenhum título em cima. Mantenha o agrupamento e desative os títulos de grupo. groupBy: 'none' não resolve: ele só separa símbolos, números e palavras, e aqui todo nome começa com um caractere han, por isso os 47 correriam num bloco só.

-  groups: { fontFamily: e.sans, fontSize: pt(9.5), fontWeight: 700, color: col('cinnabar'),
-    marginTop: pt(6.25) }, // the three names of 九畫 stay whole at the foot of their column
+  groups: { enabled: false, marginTop: pt(14) }, // no heads; a blank line between groups

Erros comuns

Erro comum

Fontes chinesas são carregadas em fatias, pelo bloco cjk

O Fontsource serve uma família chinesa, japonesa ou coreana em cerca de cem arquivos por peso, cada um com um intervalo de caracteres. loadFonts baixa só o arquivo latin, então na tela os caracteres chineses vêm de uma fonte do sistema e são medidos errado, e o fontsourceProvider entrega ao PDF esse arquivo latin, que os imprime como caixas vazias. Inclua o bloco cjk do kit, chame loadCjkFonts(FONTS, markdown) depois de loadFonts (uma vez por voz, com o texto que ela compõe, quando o livro usa várias fontes CJK) e passe a renderToPdf fontProvider: cjkPdfProvider: os dois pegam os arquivos que contêm os caracteres do texto. Fontes chinesas, japonesas e coreanas →

Erro comum

O chinês não tem itálico

As famílias CJK não trazem itálico, e a tipografia chinesa marca a ênfase com pontos ao lado dos caracteres, não com inclinação. Em um documento marcado como chinês, *…* coloca pontos de ênfase nos caracteres chineses que abrange e deixa o itálico para as palavras latinas (cjk.emphasis: 'dots', o padrão para o chinês); :dots[…] os coloca em qualquer lugar. Com cjk.emphasis: 'italic', ou em um documento marcado como en ou es, *…* faz o canvas inclinar os glifos redondos, um oblíquo sintético que a tipografia chinesa nunca usa (o PDF recorre à fonte redonda): mantenha a marcação chinesa ou faça a ênfase em negrito ou em uma fonte Kai (LXGW WenKai) com um estilo de parágrafo ou de chip. Fontes chinesas, japonesas e coreanas →

Erro comum

Marque o documento como zh-Hans ou zh-Hant, não com LANG

As edições de uma receita são en e es, mas uma amostra chinesa é chinesa nas duas: `locale: LANG` a marcaria como inglês ou espanhol, hifenizaria as suas palavras latinas, chamaria as suas figuras de Figure ou Figura e daria ao PDF o idioma errado. Desde o postext 1.30 a marcação é também o idioma em que o texto é composto (em que é medido, pintado e incorporado), então, sob uma marcação inglesa ou espanhola, uma fonte chinesa compõe com outras formas os algarismos e a pontuação que divide com o texto latino, e as linhas quebram em outro ponto. Escreva você mesmo a marcação: 'zh-Hans' (convenções da China continental: quebra de linha GB, pontuação Kaiming) ou 'zh-Hant' (Taiwan: pontuação de largura inteira centralizada); 'zh-HK' para Hong Kong. Um 'zh' sozinho é lido como chinês simplificado continental. Uma amostra japonesa leva 'ja' (armadilha ja-locale-tag). Quebra de linha em chinês →

Erro comum

Componha a pontuação de cada região com uma fonte dessa região

As larguras da pontuação levam o branco de cada sinal para o lado em que a região do documento o coloca, não para o lado em que a fonte o desenha: com zh-Hans, uma vírgula Kaiming mantém a metade esquerda da sua caixa, onde uma fonte simplificada desenha o glifo, e cede a metade direita. Uma fonte tradicional centraliza ,。 na caixa, então a metade que sai leva parte do glifo e a vírgula fica colada no caractere seguinte. LXGW WenKai TC, a única Kai de texto do Fontsource, faz isso em texto simplificado. Componha o texto, as notas e as citações continentais em Noto Serif SC ou Noto Sans SC, deixe as fontes TC para zh-Hant e use uma fonte de pincel simplificada (Ma Shan Zheng) só em linhas de destaque, onde o texto de design não aplica larguras de pontuação. Ela também desenha formas herdadas que nem o padrão continental nem o de Taiwan imprimem, 為 com o topo 爫 de 爲 e 令 (em 冷, 領) com o pé de 卩: confira os caracteres que uma página compõe com ela. Largura da pontuação chinesa →

  • A configuração index pertence ao documento, de modo que um documento imprime uma única ordem. Um livro que queira um índice por pinyin e uma lista por traços é composto duas vezes, como este pen faz.
  • Numa grade de caracteres o equilíbrio de colunas vem desativado por padrão, e a última página de cada índice encheria a primeira coluna até o pé: o colofão da edição simplificada começaria embaixo do Z e terminaria no alto da segunda coluna. headings.balancing: { enabled: true } corta antes a primeira coluna dessa página, de modo que os nomes continuam na segunda e o colofão fica inteiro embaixo deles (Equilíbrio de colunas). O corte cai entre entradas e nunca deixa um nome de um grupo sozinho no pé ou no alto de uma coluna (index.groups.splitMinEntries, 2 por padrão), por isso as duas colunas só terminam niveladas quando os comprimentos permitem. Aqui cada colofão traz uma frase sobre a ordem do índice, e as colunas das duas páginas de fecho terminam a menos de um terço de linha uma da outra.

Créditos

Texto
Fontes
Noto Serif SC (SIL OFL 1.1) · Noto Sans SC (SIL OFL 1.1) · Ma Shan Zheng (SIL OFL 1.1) · Noto Serif TC (SIL OFL 1.1) · Noto Sans TC (SIL OFL 1.1) · LXGW WenKai TC (SIL OFL 1.1)
SandboxPDF