Configuração: listas e matemática

#Listas com marcadores

A propriedade unorderedLists controla como são renderizadas as listas com marcadores (-, *, +) e as listas de tarefas do GFM (- [ ], - [x]). São aceitos até cinco níveis de aninhamento.

#Padrões das listas com marcadores

#Extensões para listas de tarefas

Os itens de tarefa do GFM (- [ ] …, - [x] …) são renderizados como itens com marcador, com uma caixa de seleção no lugar do marcador. O próprio motor desenha a caixa, um quadrado em contorno com uma marca quando a tarefa está concluída: nenhuma fonte é consultada, então ela é igual em todas as máquinas, no canvas, no PDF, no HTML e no EPUB, e as tecnologias assistivas leem ☐ ou ☑. O lado mede 0,6 em do tamanho do marcador (bulletFontSize, ou o fontSize do nível), e esse é o espaço que ela ocupa antes do gap; no tamanho do texto, ela se apoia na linha de base da primeira linha do item. O traço segue o fontWeight do marcador, e a cor, o color do marcador. Os campos a seguir se aplicam só aos itens de tarefa:

#Substituições por nível (listas com marcadores)

Cada entrada de levels se refere a uma profundidade (1–5) e pode substituir qualquer um dos seguintes:

Cascata de recuos. O nível 1 sempre começa no valor geral de indent (por padrão 0 em: os marcadores ficam presos à borda da coluna). Nos níveis 2–5, se você deixar indent indefinido, o motor põe o marcador no início do texto do nível anterior (recuo do pai + largura do marcador + gap). Defina um indent explícito num nível para interromper a cascata e fixar essa profundidade onde quiser.

unorderedLists: {
  bulletChar: '—',
  gap: { value: 0.4, unit: 'em' },
  hangingIndent: true,
  levels: [
    { level: 2, bulletChar: '·' },
    { level: 3, bulletChar: '◦', color: { hex: '#666666', model: 'hex' } },
  ],
}

#Listas numeradas

A propriedade orderedLists controla as listas numeradas (1., 2) etc.). São aceitos até cinco níveis de aninhamento, e cada profundidade pode usar um formato de número diferente.

#Padrões das listas numeradas

#Substituições por nível (listas numeradas)

Cada entrada de levels pode substituir numberFormat, prefix, separator, fontFamily, fontSize, color, fontWeight, italic, indent, verticalOffset e o estilo do separador (separatorFontFamily, separatorFontWeight, separatorItalic, separatorColor, separatorGap); vale a mesma cascata de recuos das listas com marcadores. O estilo do separador de um nível herda o estilo do número desse mesmo nível, a menos que a configuração do separador para a lista inteira seja informada.

Alinhamento à direita. O pipeline mede o número formatado mais largo de uma sequência e recua todos os itens dessa sequência para que os números se alinhem pela borda direita. Numa lista de dez itens renderizada como 1. – 10., os números de um dígito recebem preenchimento à esquerda para que o separador fique na mesma coluna.

orderedLists: {
  numberFormat: 'arabic',
  separator: '.',
  levels: [
    { level: 2, numberFormat: 'lower-alpha' },
    { level: 3, numberFormat: 'lower-roman', separator: ')' },
  ],
}

Isso produz a mistura aninhada clássica:

1. First item
   a. Sub-item
      i) Deep note
   b. Sub-item
2. Second item

A hierarquia dos documentos chineses (GB/T 15834—2011, Anexo B.3) tem cinco níveis: 一、, depois （一）, depois 1., depois （1） e depois ①:

orderedLists: {
  levels: [
    { level: 1, numberFormat: 'simp-chinese-informal', separator: '、' },
    { level: 2, numberFormat: 'simp-chinese-informal', prefix: '（', separator: '）' },
    { level: 3, numberFormat: 'arabic', separator: '.' },
    { level: 4, numberFormat: 'arabic', prefix: '（', separator: '）' },
    { level: 5, numberFormat: 'circled-decimal', separator: '' },
  ],
}

#Matemática

A propriedade math controla como são analisadas e renderizadas as fórmulas LaTeX entre os delimitadores $...$ (em linha) e $$...$$ (em destaque). O motor por trás é o MathJax (o pacote mathjax-full) no modo de saída SVG, rasterizado no canvas e incorporado como glifos escaláveis no PDF.

interface MathConfig {
  enabled?: boolean;        // Renderiza o LaTeX. Com false, os trechos passam como TeX literal.
  fontSizeScale?: number;   // × o tamanho do texto ao redor (o tamanho do corpo nas fórmulas em destaque).
  color?: ColorValue;       // Cor das fórmulas; herda a cor do corpo se omitida.
  marginTop?: Dimension;    // Espaço acima dos blocos de fórmula em destaque.
  marginBottom?: Dimension; // Espaço mínimo abaixo; o ajuste à grade de linhas de base pode aumentá-lo.
  indentAfterDisplay?: boolean; // Recua um parágrafo que vem depois de uma fórmula em destaque.
  keepWithLeadIn?: boolean; // Mantém uma fórmula em destaque com a linha que a introduz.
  equationNumbering?: {      // Numera as fórmulas em destaque que levam um \label.
    enabled?: boolean;           // padrão true
    numberingTemplate?: string;  // '{n}'; '{h1}.{n}' numera por capítulo
    resetOn?: ResourceCounterReset; // 'never' | 'h1' … 'h6'
    counterFormat?: ResourceCounterFormat; // 'decimal'
    format?: string;             // '({n})': o que a fórmula e \eqref imprimem
  };
}

math: {
  enabled: true,
  fontSizeScale: 1.0,
  color: { hex: '#295AA3', model: 'hex' },
  marginTop: { value: 1, unit: 'em' },
  marginBottom: { value: 1, unit: 'em' },
}

Tamanho das fórmulas, alterado no postext 1.5. O MathJax dá a caixa de uma fórmula em ex, e um ex da sua fonte TeX equivale a 0,442 em. Até o postext 1.4 o motor o tomava como meio em, de modo que toda fórmula era composta cerca de 13% maior que bodyText.fontSize × fontSizeScale. Agora as fórmulas saem no tamanho documentado, e as linhas e páginas com fórmulas são recompostas. Uma configuração escrita em código para a 1.4 mantém o tamanho de fórmula da 1.4 se passar por pinLegacyMathSize, de postext/bundle, uma única vez, tal como foi escrita:

import { pinLegacyMathSize } from 'postext/bundle';
 
config = pinLegacyMathSize(config); // as fórmulas, e o espaço em volta das fórmulas em destaque, como a 1.4 as compunha

Outras mudanças de regras na 1.5 também podem mexer nas suas páginas: as quebras dos títulos, o espaço em volta de uma figura em linha (no texto corrido e nos boxes), as marcas em linha dos seus títulos, o tamanho das suas capitulares, o espaço reservado sob uma linha terminada em dois-pontos para a lista que ela introduz, as linhas que o corte de um boxe deixa de um parágrafo ou de um item de lista, as quebras de linha depois de um travessão, a quebra do texto em bandeira, a divisão de um parágrafo sob um título, as quebras de linha depois do hífen de uma palavra composta e o espaço sob um contêiner :::paragraphs. migrateConfig, executado uma vez com o markdown que a configuração diagrama, fixa as que esse texto precisa, o tamanho das fórmulas incluído (veja Pacotes escritos pelo postext 1.4 ou anterior):

import { migrateConfig } from 'postext/bundle';
 
config = migrateConfig(config, undefined, { content: markdown }); // quebras de títulos, fórmulas, espaços em linha, marcas de títulos, capitulares, linhas com dois-pontos, cortes de boxes, quebras após travessão, quebras de compostos, texto em bandeira, divisões sob um título e espaço dos contêineres como a 1.4 os compunha

Isso segura o que essas mudanças de regras moveriam, mas não preserva todas as páginas da 1.4. A versão 1.5 também corrige bugs de layout, e uma correção não tem fixação: uma configuração antiga a recebe como uma nova, então uma página afetada por ela ainda pode mudar. Entre elas: um título na largura da página sem design próprio é medido na largura da página e composto na entrelinha do seu nível; nada é reservado sob a linha de base de uma capitular num design de título; uma capitular toma a cor de paleta da seção e é composta mesmo num texto de design cujo overflow não é 'wrap', que então quebra linhas; um parágrafo num boxe pinta o tracking com que foi medido; um boxe dividido mantém a coluna do ícone em todos os fragmentos; uma linha de boxe que esticaria os espaços além de 3× é composta em bandeira, como no texto corrido; o recurso de parágrafo frouxo nunca compõe uma linha justificada mais larga do que maxWordSpacing permite; um boxe flutuante mantém uma marginBottom (numa faixa superior) ou uma marginTop (numa faixa inferior) maior que o espaço entre flutuantes; um texto de design centralizado ou alinhado à direita com tracking (um cabeço, o título de uma abertura) é posicionado pelas suas letras, sem o tracking depois da última; sob uma abertura na largura da página, o texto que abre a segunda coluna começa onde começaria o texto logo abaixo da abertura, também quando um título segue a abertura; os pontos do sumário param antes do número de página numa fonte cujo kerning afasta uma sequência de pontos; um cabeço lê um título tal como foi escrito, sem espaço onde uma das suas linhas termina depois de um hífen ou de um travessão ou dentro de uma palavra cortada por largura (MEDIOAMBIENTALES, não MEDIOAMBIENTALE S), e o {titleText} de um design de título o lê do mesmo jeito (thousand-colour, não thousand- colour); um texto ancorado no pé ou no meio da faixa de um design de título mantém a faixa alta o bastante para contê-lo, de modo que ele não sobe mais sobre o texto acima do título; uma palavra mais larga que a sua linha, cortada junto a um hífen que ela própria tem, é cortada depois desse hífen e não recebe um segundo; o item depois de uma lista aninhada noutra recebe o itemSpacing da sua própria lista, não o da lista aninhada; e o resto de uma palavra cortada por ser mais larga que a sua linha mantém os seus próprios pontos de quebra, de modo que um endereço web continua quebrando nas suas junções, e uma palavra composta nos seus hifens, em vez de nas sílabas do dicionário.

pinLegacyMathSize multiplica a escala por 1,1312 (0,5 ÷ 0,442) e divide pelo mesmo fator as margens das fórmulas em destaque em em. Só a escala não basta para um livro com fórmulas em destaque: as margens delas são medidas do tamanho da própria fórmula, então cresceriam os mesmos 13% e empurrariam para baixo o texto abaixo delas. Escritos por extenso para as margens padrão, os três valores são:

math: {
  fontSizeScale: 1.131,
  marginTop: { value: 0.7072, unit: 'em' },
  marginBottom: { value: 0.7072, unit: 'em' },
} // fórmulas do tamanho que a 1.4 compunha, com o espaço que a 1.4 deixava em volta

Quando se sabe onde a configuração estava guardada, o motor faz isso por você: openBundle / readBundle num pacote .postext escrito antes da 1.5 (veja Pacotes escritos pelo postext 1.4 ou anterior), e o Sandbox nos livros, na cópia de trabalho e nos arquivos postext-config.json salvos naquela época (veja Sandbox → Persistência). Eles são lidos por meio de migrateConfig, que fixa o tamanho (pinLegacyMathSize): fontSizeScale passa a ser a escala guardada (1 quando não definida) × 1,1312, e uma margem de fórmula em destaque em em ou rem (uma medida do tamanho da própria fórmula) é dividida pelo mesmo fator, de modo que o espaço em volta de uma fórmula em destaque fica como a 1.4 o deixava (os 0,8 em padrão passam a 0,7072 em). Uma margem numa unidade de página (pt, mm…) fica como está, assim como uma configuração com enabled: false ou uma cujo livro não tem nenhum $. O livro antigo é então diagramado como a 1.4 o diagramava, e a sua seção math mostra o tamanho em que é composto. Para compor esse livro no tamanho atual, redefina esses valores: Fórmulas → Escala de tamanho, Margem acima (destaque) e Margem abaixo (destaque) no Sandbox, ou em código:

math: { ...config.math, fontSizeScale: 1, marginTop: undefined, marginBottom: undefined } // tamanho e margens atuais

Equações numeradas. Uma fórmula em destaque com número ocupa a sua medida (a coluna, ou a largura interna do boxe em que está): a equação fica centralizada e o seu número, alinhado à direita na linha da equação, em cada linha numerada de um align. O número vem de um \label{eq:x} (desde o postext 1.19): as fórmulas rotuladas, e as linhas rotuladas de um align, gather, alignat, flalign ou eqnarray, são numeradas em ordem de leitura com equationNumbering, a menos que uma linha diga \nonumber ou \notag. Ambientes como equation não são numerados por si sós: uma fórmula sem rótulo não tem número. \tag{…} imprime o rótulo que você der, entre parênteses, e \tag*{…}, tal como foi escrito; nenhum dos dois é contado, e um \label ao lado de um deles lhe dá um nome. Uma equação numerada mais larga que a sua medida transborda para a direita, como qualquer fórmula em destaque. (Até o postext 1.4 uma fórmula com \tag não era desenhada; até a 1.18 só \tag numerava uma fórmula.)

\eqref{eq:x} no texto imprime o número no seu format, (3), e \ref{eq:x}, o número sozinho; o mesmo fazem :ref{id="eq:x"} e @eq:x (veja Referências cruzadas), e dentro de uma fórmula \eqref o imprime como texto. Num livro diagramado capítulo por capítulo, o contador continua a partir do capítulo anterior: continuationAfter o leva em LayoutContinuation.statementCounters (equation), e o esboço do livro dá a cada rótulo o seu número (OutlineEntry.numberLabel), de modo que uma referência a uma equação de outro capítulo a imprime.

math: {
  equationNumbering: { numberingTemplate: '{h1}.{n}', resetOn: 'h1' }, // (1.1), (1.2)… (2.1)
}

O resolvedor e o redutor seguem o padrão das outras seções:

import {
  DEFAULT_MATH_CONFIG,
  resolveMathConfig,
  stripMathDefaults,
} from 'postext';
 
const resolved = resolveMathConfig(config.math);
const minimal  = stripMathDefaults(config.math);

#Inicializar o motor de fórmulas

O MathJax é carregado sob demanda, não junto com o resto do motor. Quando você diagrama na thread principal, inicialize-o antes de construir um documento que tenha fórmulas:

import { buildDocument, initMathEngine, renderPage } from 'postext';
 
await initMathEngine(); // carrega o MathJax uma vez; as chamadas seguintes resolvem na hora
const doc = buildDocument({ markdown: 'Euler: $e^{i\\pi}+1=0$.' }, config);
document.body.append(renderPage(doc.pages[0], doc));

• Até o motor rodar, as fórmulas são marcadores de posição. Cada uma é diagramada como uma caixa cinza de tamanho estimado. Se um documento com fórmulas for diagramado sem que initMathEngine() tenha sido chamado alguma vez, o console mostra um aviso dizendo isso.
• O worker de layout o inicializa por você. Uma construção em postext/worker chama initMathEngine() por conta própria quando o markdown contém um $.
• Diagramar agora e de novo quando estiver pronto. isMathReady() diz se o motor está rodando. onMathReady(fn) chama fn assim que ele estiver (na hora, se já estiver) e devolve uma função que cancela a chamada. Um editor pode mostrar os marcadores de posição de imediato e diagramar de novo quando o MathJax chegar; nenhum aviso é impresso enquanto initMathEngine() está em andamento.
• Falha. initMathEngine() rejeita quando o MathJax não pode ser carregado, e uma chamada posterior tenta de novo.
• Qualquer bundler, Node ou uma CDN. O MathJax vem dentro do pacote como um único módulo pré-empacotado (cerca de 1,8 MB antes da compressão, baixado só por initMathEngine). O simples import { initMathEngine } from 'https://esm.sh/postext' funciona; não é preciso ?bundle. O pacote mathjax-full só é necessário para compilar o postext, então instalar o postext não o instala. O MathJax e o analisador mhchem que ele inclui têm licença Apache-2.0: os avisos deles e o texto da licença acompanham o módulo, em dist/math/THIRD_PARTY_LICENSES.txt.
• Um motor por página. O motor e o seu cache de fórmulas renderizadas são compartilhados por tudo o que importa postext no mesmo realm JavaScript (veja Estado global compartilhado numa página).

Para a gramática do lado do documento ($...$, $$...$$, como escapar um cifrão literal), veja Formato do documento.