Configuração: texto e títulos

#Texto do corpo

A propriedade bodyText controla a tipografia de todo o texto dos parágrafos.

#Citações

Uma citação em bloco (linhas que começam com >) usa a família, o tamanho, a entrelinha, os pesos, o alinhamento e a hifenização do corpo. bodyText.blockquote define o resto; sem definição, uma citação fica como era até o postext 1.4: cinza, em itálico, com o recuo de primeira linha do corpo e sem recuo lateral.

bodyText: {
  firstLineIndent: { value: 1.5, unit: 'em' },
  // Upright verse in the body colour, set in by 2 em, no first-line indent.
  blockquote: { color: { hex: '#241f26', model: 'hex' }, italic: false, indent: { value: 2, unit: 'em' }, firstLineIndent: { value: 0, unit: 'em' } },
}

No Sandbox, estas opções formam o grupo Citações da seção Texto do corpo.

#Verso

Um poema :::verse cujas linhas não trazem separador de hemistíquios é composto linha a linha (veja Formato do documento › :::verse). bodyText.verse dá os valores padrão desses poemas; um atributo de mesmo nome na abertura de um poema o define para esse poema.

bodyText: {
  // Restos à direita depois de um colchete; os tankas, inteiros.
  verse: { turnover: 'right', keepStanzas: 5 },
}

Uma configuração guardada antes destes ajustes (configVersion 8 ou anterior) que compõe um poema sem separador é lida com layout: 'bayt', de modo que o poema mantém as linhas centralizadas que o postext 1.22 lhe dava. Uma guardada com o postext 1.23 (configVersion 9) que compõe um poema verso a verso é lida com tighten: false, de modo que seus versos se partem onde a 1.23 os partia.

No Sandbox, estas opções formam o grupo Verso da seção Texto do corpo.

#Paradas de tabulação

bodyText.tabStops lista as paradas para onde vai uma tabulação: :tab, ou um caractere de tabulação num parágrafo que tem paradas (veja Formato do documento › Tabulações e paradas de tabulação para a marcação e para como uma linha é composta). O tabStops de um estilo de parágrafo as substitui nos seus parágrafos, e o body.tabStops de um estilo de boxe dentro dos seus boxes; uma lista vazia não define nenhuma. Cada parada é um TabStop:

bodyText: {
  tabStops: [
    { position: { value: 30, unit: 'mm' } },
    { position: 'end', align: 'end', leader: '.', leaderGap: { value: 2, unit: 'pt' } },
  ],
  tabInterval: { value: 10, unit: 'mm' },
}

tabInterval acrescenta paradas a cada intervalo a partir do início da medida, depois da última parada da lista; sem ele, uma tabulação depois da última parada é um espaço entre palavras. Um caractere de tabulação digitado no texto só é uma tabulação num parágrafo cujo estilo tem paradas ou um intervalo, próprios ou do corpo; em qualquer outro lugar continua sendo o espaço entre palavras que sempre foi, de modo que um documento salvo é diagramado como antes e não precisa de fixação.

As paradas são verificadas com o resto da configuração (veja Avisos de configuração): uma chave desconhecida numa parada (leaders) é avisada como unknownConfigKey, com a chave mais próxima; um align que não é nenhuma das quatro palavras, como unknownConfigValue, e a parada é composta como 'start'; uma position que não é um comprimento, 'end' nem uma porcentagem, como unknownConfigValue com used: 'none', e a parada é deixada de fora.

A cor e a fonte do preenchimento são as do parágrafo; ainda não há uma configuração própria para elas.

#Capitulares

Um parágrafo do corpo pode abrir com uma capitular: a primeira letra composta em tamanho grande ao lado das primeiras linhas, que são encurtadas pela largura da letra e por um espaço e compostas como quaisquer outras linhas (quebradas pelo Knuth-Plass, justificadas, hifenizadas). Um estilo de parágrafo a dá ao primeiro parágrafo de cada grupo :::paragraphs no estilo (a todos os parágrafos com each: true, para um catálogo de verbetes); um nível de título ou um estilo de título a dá ao primeiro parágrafo do corpo depois do título (veja o campo dropCap de Sobrescritas por nível, Estilos de parágrafo e Estilos de título). O parágrafo depois do título é procurado passando por aberturas e fechos de contêiner, diretivas, boxes que saíram do fluxo e figuras flutuantes, como faz indentAfterHeading; um parágrafo dentro de um boxe, de um item de lista, de uma citação, de um poema ou de uma nota nunca leva capitular. No texto, {dropcap}, {dropcap=false} e {dropcap=N} na linha de um título ou na abertura de um :::paragraphs a ligam, a desligam ou definem as suas linhas para aquele capítulo ou grupo (veja Formato do documento › Capitulares). Desde o postext 1.23.

headings: {
  levels: [
    { level: 1, dropCap: { lines: 3, fontFamily: 'Libre Bodoni', fontWeight: 700, color: { hex: '#8b2e2a', model: 'hex', paletteId: 'accent' }, leadIn: { words: 3 } } },
  ],
},

Como a letra é composta:

• Tamanho. As duas alturas das maiúsculas, a do texto e a da inicial, são medidas nas suas fontes (a tinta de um H; da própria inicial em texto chinês ou japonês), e uma fonte que não dá métricas de tinta conta as maiúsculas como 0,72 do seu tamanho. O tamanho padrão serve para qualquer par de fontes, então não é preciso uma correção por fonte. O dropCap de um texto de design mantém o seu 0,72 fixo (veja Elementos de texto).
• A letra e a sua palavra. A inicial toma agrupamentos de grafemas inteiros. O resto da primeira palavra continua depois dela sem espaço; uma palavra de uma letra só (A, E) mantém o seu espaço entre palavras no início da primeira linha. O recuo de primeira linha do próprio parágrafo é descartado. A cópia, a busca, o mapa de origem e o cursor do Sandbox leem o parágrafo como foi escrito: o texto simples do bloco inclui a letra, o plainStart da primeira linha conta a partir de depois dela, e VDTBlock.dropCap guarda o seu intervalo e a sua geometria no fragmento que tem a primeira linha.
• Uma inicial elevada (lines: 1 com um fontSize maior, ou sink abaixo de lines) sobe acima da primeira linha, e o parágrafo mantém essa elevação livre acima dele, em linhas inteiras da grade, para que ela não se sobreponha ao texto de cima.
• Quebra. O parágrafo nunca se divide antes da linha sink: em vez disso, passa inteiro para a coluna ou a página seguinte, a menos que esteja sozinho numa coluna vazia que não comporta essas linhas, e então se divide mesmo assim e emite um aviso dropCap. Um título mantido com o seu texto mantém essas linhas abaixo dele. A parte que continua na coluna seguinte não leva inicial e tem linhas de largura inteira; quebrado de novo para uma coluna de outra largura, as primeiras linhas mantêm o seu recuo. O balanceamento de colunas pode afrouxar ou apertar o parágrafo como qualquer outro, e nunca acrescenta espaço entre as linhas encurtadas.
• Escritas. As linhas são encurtadas do lado inicial: a esquerda no texto latino, a direita no árabe e no hebraico. Uma letra que se liga à seguinte (árabe, siríaco, N'Ko) não é separada, e o parágrafo emite um aviso dropCap; o chinês e o japonês horizontais levam uma inicial de um caractere (首字下沉). O texto vertical não leva nenhuma (aviso). Um parágrafo que não abre com uma letra ou um algarismo (uma referência, uma fórmula, uma chamada de nota) também não leva (aviso).
• Saídas. O canvas, o visualizador HTML e o EPUB de layout fixo pintam a inicial ao lado das linhas; o HTML a escreve logo antes do texto da primeira linha, sem nada entre as duas, para que um leitor de tela leia a palavra inteira. Num PDF etiquetado a inicial faz parte do P do parágrafo e, com o resto da sua palavra, de um Span cujo /ActualText é a palavra: a extração de texto lê Muito antes, nunca M uito antes. Um EPUB refluível a compõe como um initial-letter de CSS (linhas, descida), flutuante onde o sistema de leitura não oferece suporte a ele.

As configurações são verificadas com o resto da configuração (veja Avisos de configuração): uma chave desconhecida numa capitular ou na sua abertura é avisada como unknownConfigKey; um punctuation ou shortParagraph que não é nenhuma das suas palavras, ou um lines, sink ou characters que não é um número inteiro a partir de 1, como unknownConfigValue, e o padrão é usado. As capitulares vêm desligadas por padrão, então nenhum documento salvo muda.

#Uma família por fontFamily

fontFamily (aqui e em todos os outros campos de família tipográfica: headings.fontFamily, tableStyle.bodyFontFamily, separatorFontFamily, o fontFamily de um estilo de chip ou de um elemento de design…) nomeia uma família. O canvas, a saída HTML e o PDF precisam compor com a mesma fonte, e o PDF incorpora uma fonte por família, sem cadeia de alternativas, então não há para onde uma pilha de fontes CSS recorrer. Uma pilha é composta na primeira família e reportada como aviso de configuração:

bodyText: { fontFamily: "'EB Garamond', Georgia, serif" } // set in EB Garamond

Carregue essa família antes de diagramar (veja Fontes personalizadas e o provedor de fontes em Gerar PDFs); se ela estiver ausente, o navegador mede com a fonte padrão dele, diga o resto da pilha o que disser. Uma vírgula entre aspas faz parte de um nome ('"Foo, Bar"' é uma família).

#Hifenização

Quando o alinhamento do texto é 'justify', a hifenização evita o espaçamento excessivo entre palavras, dividindo as palavras longas nos limites de sílaba. O motor usa os padrões TeX/Liang para encontrar os pontos de quebra naturais entre sílabas. Veja Hifenização e justificação para uma explicação detalhada. O texto em bandeira só é hifenizado quando você pede: veja Texto em bandeira abaixo.

Idiomas suportados: 'en-us' (inglês), 'es' (espanhol), 'fr' (francês), 'de' (alemão), 'it' (italiano), 'pt' (português), 'ca' (catalão), 'nl' (holandês).

As subtags de região, escrita e variante são ignoradas na escolha dos padrões, assim como a caixa das letras e os separadores _: 'es-ES', 'es-MX' e 'es_419' hifenizam com 'es', 'pt-BR' com 'pt', e toda tag inglesa ('en', 'en-GB') com 'en-us', os únicos padrões ingleses incluídos, de modo que o texto britânico recebe quebras americanas. Um idioma sem padrões incluídos ('sv', 'pl', 'fi'…) é hifenizado com os padrões 'en-us', o que produz quebras erradas em vez de nenhuma; o motor o reporta uma vez por tag com um console.warn, e o Sandbox o lista no painel Verificações. Defina enabled: false para um documento assim; isso também silencia o aviso. Chinês, japonês e coreano (zh, ja, ko, qualquer que seja a região ou a escrita) não precisam de padrões nem geram aviso: um documento em um desses idiomas é composto sem hifenização. Para dividir as palavras latinas citadas nele, defina enabled: true e indique o idioma delas em locale ('en-us' para o inglês). enabled: true sem locale, ou com um idioma chinês, japonês ou coreano, deixa a hifenização desativada e avisa uma vez no console. matchHyphenationLocale(tag) devolve o idioma incluído que corresponde a uma tag (undefined quando não há nenhum), e HYPHENATION_LOCALES lista os incluídos. A configuração resolvida (doc.config.bodyText.hyphenation) indica em locale os padrões realmente usados e guarda em tag a tag que você informou, quando for diferente. O renderizador de PDF declara o idioma do documento a partir do locale do nível superior, e a partir desta tag só quando locale não está definido (veja Idioma do documento).

import { matchHyphenationLocale } from 'postext';
 
matchHyphenationLocale('es-MX'); // 'es'
matchHyphenationLocale('en-GB'); // 'en-us'
matchHyphenationLocale('sv');    // undefined: hifenizado com 'en-us', com um aviso no console

Palavras com menos de 5 caracteres nunca são hifenizadas. O motor exige pelo menos 2 caracteres antes e 3 caracteres depois de um ponto de quebra.

Texto em bandeira

Por padrão, só o texto justificado é hifenizado: com textAlign: 'left', e nos estilos de parágrafo alinhados à esquerda, ao centro ou à direita, toda palavra é mantida inteira, por mais irregular que a borda fique, exceto em um hífen condicional (U+00AD) digitado no texto. Defina hyphenation.ragged: true para hifenizar também o texto em bandeira.

Uma linha em bandeira nunca é esticada, então dividir toda palavra que não cabe encheria a borda de hífens. A zona de hifenização limita isso, como faz o compositor de linha única de um programa de editoração. Quando uma palavra não cabe no fim de uma linha, o motor olha o vazio que mandá-la inteira para a linha seguinte deixaria. Se esse vazio for maior que zone, a palavra é dividida na última sílaba que cabe; caso contrário, desce inteira. Uma zona em em é relativa ao tamanho da fonte do próprio texto. O padrão, 3em, só divide as palavras que deixariam uma linha visivelmente curta. Uma zona maior dá menos hífens e uma borda mais irregular; 0 divide toda palavra que não cabe. Na composição linha a linha, no máximo duas linhas seguidas terminam em sílaba. Hífens fixos (enseñanza-aprendizaje), junções de URL, hífens condicionais digitados no texto e palavras mais largas que a linha inteira quebram como sempre: a zona e o limite de duas linhas só regem as sílabas do dicionário.

A configuração vale para o documento inteiro. Aplica-se ao texto do corpo e às citações quando estão em bandeira, e a todo estilo de parágrafo e corpo de boxe em bandeira cuja hyphenation própria esteja ativada (por padrão, ela segue o hyphenation.enabled do corpo), de modo que hyphenation: false mantém inteiras as palavras de um estilo. Títulos, legendas, notas, células de tabela e o sumário não são hifenizados; ali, como em todo lugar, só uma palavra mais larga que a medida inteira é dividida. O texto de design (cabeços, aberturas, páginas de parte) segue a opção hyphenate de cada elemento de texto, que as aberturas de página inteira e as páginas de parte embutidas ativam, e usa também o dicionário do documento. O texto justificado ignora ragged e zone.

const config: PostextConfig = {
  locale: 'es',
  bodyText: {
    textAlign: 'left',
    // Um pouco mais de hifenização que o padrão de 3 em.
    hyphenation: { ragged: true, zone: { value: 2, unit: 'em' } },
  },
};

Com optimalRagged (o padrão), o texto corrido em bandeira é quebrado com Knuth-Plass, e a zona mantém o seu sentido ali: uma palavra só é dividida quando não cabe no restante da linha e mandá-la inteira para baixo deixaria vazio mais que a zona. Duas sílabas seguidas não são recusadas, mas custam o que custam dois hífens seguidos no texto justificado, então uma terceira é rara. Com optimalRagged: false, ou optimalLineBreaking: false, cada linha é preenchida antes da seguinte, como até o postext 1.4.

A hifenização do texto em bandeira diagrama os parágrafos com o algoritmo de quebra que os parágrafos com formatação inline (negrito, itálico, links, fórmulas) sempre usam, então ativá-la pode mudar algumas quebras além dos hífens. Em uma linha em bandeira, além dos espaços e das sílabas do dicionário, esse algoritmo quebra depois de um hífen fixo ou de um travessão entre duas palavras (largas—separadas; com breakAfterDashes, qualquer travessão colado entre palavras, também riddles.—I e riddles—*and*), nas junções de URL e entre ideogramas, e mantém junta uma palavra composta em vários trechos (**Nota**:, (*véase*). Sem a hifenização do texto em bandeira, um parágrafo em bandeira sem formatação é quebrado com Knuth-Plass quando optimalRagged está ativado (o padrão): nos espaços entre palavras, depois de um hífen fixo entre duas letras (meta- · analyses), como faz o outro algoritmo, e, com breakAfterDashes, depois de travessões colados. Na composição linha a linha, ele passa pelo algoritmo de quebra do pretext, que difere em três pontos: também pode quebrar antes de um travessão que fecha um aparte ou depois de um que o abre (él · — y), depois de uma barra ao hifenizar (km/ · h), e corta uma palavra mais larga que a linha em qualquer caractere, sem hífen, onde o outro algoritmo a divide primeiro em uma sílaba.

No Sandbox, a opção é Hifenizar texto em bandeira, abaixo do alinhamento de parágrafo da seção Texto do corpo, com a zona logo abaixo. Com o corpo justificado, a mesma opção fica junto das configurações de justificação, para os estilos de parágrafo e os boxes em bandeira.

#Idioma do documento

O locale de nível superior é o idioma do documento como um todo. Aceita os mesmos valores que hyphenation.locale e é o valor que esse campo usa quando não está definido, de modo que basta locale: 'es' para um livro em espanhol ser hifenizado em espanhol. Ele também escolhe o idioma das strings integradas de continuação de tabelas e de boxes divididos ((cont.) / Continued em vez de Continúa, veja Tabelas mais altas que a página e Marcas de um boxe dividido) e dos números de título escritos por extenso (Chapter One em vez de Capítulo uno, veja Números por extenso), e é o idioma marcado num PDF acessível. Sem definição, o motor assume 'en-us'; o Sandbox usa o idioma da interface e mostra o campo em Design › Sistema de escrita.

Ele escolhe também os tipos de recurso integrados. Quando resourceTypes não está definido, buildDocument numera e legenda com defaultResourceTypes(locale), então só locale: 'de' já dá Abbildung 1.1 e Tabelle 1.1. Quando locale não está definido, o idioma da hifenização ocupa o lugar dele, tanto para os tipos de recurso quanto para as strings das tabelas. Uma lista resourceTypes explícita sempre prevalece. As versões anteriores usavam os tipos em inglês qualquer que fosse o locale, a menos que você mesmo passasse defaultResourceTypes(locale); um documento que define locale e quer manter os rótulos em inglês passa resourceTypes: defaultResourceTypes('en'). Os livros do Sandbox e os pacotes levam a própria lista, então não são afetados.

Qualquer tag BCP 47 funciona aqui, como em hyphenation.locale: 'de-AT' recebe as strings em alemão. As strings integradas existem nos oito idiomas que a hifenização suporta, em chinês (em caracteres simplificados e tradicionais), em japonês e em árabe; qualquer outro idioma recebe as inglesas.

O chinês aceita zh, zh-Hans, zh-Hant, zh-CN, zh-SG, zh-TW, zh-HK, zh-MO e as formas longas (zh-Hant-TW), em maiúsculas ou minúsculas e com - ou _. As strings seguem a escrita, lida com Intl.Locale(tag).maximize(): zh, zh-CN e zh-SG são simplificado; zh-TW, zh-HK e zh-MO, tradicional. Já os padrões tipográficos que dependem do idioma seguem a região, como recomenda a clreq §1.2: CN, SG e MY contam como China continental, TW como Taiwan, HK e MO como Hong Kong, e uma tag sem região vale pela escrita (zh-Hant é Taiwan; zh e zh-Hans, a China continental). O japonês aceita ja, ja-JP, ja-Jpan e qualquer outra tag ja (isJapaneseLanguage(tag)); desde o postext 1.16 ele tem strings próprias e uma região própria, japan, cujos padrões tipográficos seguem a JLReq (veja Composição japonesa). Uma tabela de strings sem entrada em japonês dá inglês, nunca chinês. localeScript(tag), cjkRegionOf(tag), stringsKeyOf(tag) e sameContentLocale(a, b) dão essas leituras, e DOCUMENT_LANGUAGES lista os idiomas com strings integradas, cada um com o nome no próprio idioma (日本語 entre as entradas chinesas e العربية), como o seletor Idioma do documento do Sandbox os mostra.

O prefixo da legenda é o nome do tipo (Figura 1.1.). Os tipos chineses numeram dentro do capítulo com hífen, {h1}-{n} (图 1-1); com os ajustes de legenda labelNumberGap: '' e labelSeparator: '　' a legenda fica 图1-1　标题 (veja Estilo de legendas). O índice remissivo também segue o idioma: 见 e 另见 antes de uma referência cruzada, 符号 e 数字 sobre os símbolos e os números em chinês simplificado; 見, 另見, 符號 e 數字 em tradicional. O japonês numera seus tipos da mesma forma e compõe as legendas como 図1-1　題 sem os dois ajustes, escreve as referências cruzadas como 第3章, 2.3節 e 12ページ, dá à bibliografia o título 参考文献, e seu índice imprime 記号 e 数字 sobre os símbolos e os números e escreve as remissões com uma seta, →夏目漱石 para ver e →夏目漱石、森鷗外も見よ depois das páginas para ver também, com os rótulos em pé. O árabe numera seus tipos da mesma forma, {h1}-{n} (شكل 2-3), escreve as referências cruzadas como الفصل 3, القسم 2-1 e ص 12, dá à bibliografia o título المراجع, e seu índice imprime انظر / انظر أيضًا, رموز e أرقام, com a vírgula e o ponto e vírgula árabes (، ؛).

Um documento em chinês, japonês ou coreano declara o idioma na saída HTML (lang na raiz .pt-doc, com zh-Hant-TW inteiro) e no canvas que ele pinta (ctx.lang, no Chrome 136 e posteriores), para que o navegador desenhe as formas de glifo da região: o Unicode unifica os caracteres han, e um mesmo ponto de código tem aspecto diferente numa fonte taiwanesa e numa japonesa. Os demais documentos não levam lang, como antes. O PDF declara /Lang a partir de locale em todo documento, marcado ou não, com a escrita e a região. Um documento num idioma escrito da direita para a esquerda (árabe, persa, urdu, hebraico…) também declara o idioma: as formas linguísticas da fonte (locl) e a fonte substituta o seguem.

const config: PostextConfig = {
  locale: 'es',
  bodyText: { textAlign: 'justify', hyphenation: { enabled: true } }, // hifeniza em espanhol
};

Algarismos do documento

O numerals de nível superior define os algarismos de todo número que o motor escreve: números de página e os rótulos de página do sumário, do índice e das referências a páginas; números de listas numeradas e de notas de rodapé; contadores de títulos e capítulos, {chapterNumber}; o {h1} e o {n} do número de uma figura e de uma referência a ela; {totalPages}, {bookTotalPages} e {numberDecimal}. 'latn' escreve 0–9, 'arab' os algarismos arábico-índicos ٠–٩ e 'arabext' os algarismos persas ۰–۹. Só o formato decimal muda (decimal, o arabic das listas ou um ajuste deixado no padrão), então um formato que o autor nomeia sai como foi nomeado: lower-roman continua i, ii, iii, e arabic-indic num documento latino ainda escreve ١, ٢, ٣. O texto do documento nunca é reescrito.

O padrão, 'auto', usa os algarismos de locale (defaultNumeralsFor(tag)): 'arab' para o árabe sem região ou com qualquer região fora do Magrebe (ar, ar-EG, ar-SA, ar-AE…), 'latn' para ar-MA, ar-DZ, ar-TN, ar-LY, ar-MR e ar-EH, 'arabext' para o persa (fa), o pashto (ps) e o urdu da Índia (ur-IN), e 'latn' para todo o resto, inclusive o urdu do Paquistão. O CLDR dá latn para um ar sem região e para ar-AE; os livros árabes do Machrek e do Golfo imprimem ٠–٩, e é isso que o Postext segue. Uma tag que nomeia seus algarismos os mantém: ar-MA-u-nu-arab. Uma página numerada com os algarismos do documento registra arabic-indic ou persian como pageNumberFormat, para que os rótulos de página do PDF mostrem os mesmos algarismos. Um valor desconhecido segue o idioma e é avisado como unknownNumerals.

Os números que o autor digita são lidos em qualquer um dos três sistemas: um item de lista ٣. começa em 3, e {startAt=٥}, :::numbering{startAt=٥}, :::space{lines=٢} e :::part{number="٣"} (para {numberDecimal}) leem o valor.

const config: PostextConfig = { locale: 'ar' };                     // ١، ٢، ٣
const maghreb: PostextConfig = { locale: 'ar-MA' };                 // 1, 2, 3
const forced: PostextConfig = { locale: 'ar', numerals: 'latn' };   // 1, 2, 3

Direção do texto

O direction de nível superior define a direção base do documento: 'ltr', 'rtl' ou 'auto' (o padrão), que é 'rtl' quando a escrita de locale vai da direita para a esquerda (árabe, persa, urdu, hebraico, siríaco, thaana, n'ko, adlam…, lida por directionOf(tag)) e 'ltr' nos demais casos. Um documento da direita para a esquerda é diagramado num quadro espelhado: as linhas começam à direita, a primeira coluna é a da direita, recuos, marcadores de lista, flutuantes, notas de rodapé e boxes ficam à direita, e page.binding: 'auto' o encaderna pela direita. A configuração resolvida só leva direction: 'rtl' num documento assim, de modo que um documento da esquerda para a direita se resolve como antes. Um valor desconhecido é lido como 'auto' e avisado como unknownConfigValue. O algoritmo bidirecional do Unicode (UAX #9) ordena os trechos de cada linha em qualquer direção: uma citação em árabe num livro em inglês se lê da direita para a esquerda no próprio lugar.

Dentro do documento, um título ou um contêiner ::: aceita {dir=ltr} ou {dir=rtl}, e os inline :ltr[…] e :rtl[…] isolam um trecho de texto (veja Direção do texto na marcação); um recurso de tabela aceita table.direction. Um bloco composto contra a direção do documento mantém o próprio lado de início: o recuo, os marcadores de lista e o final alinhado da última linha passam para o lado em que o texto dele começa.

Um ajuste que nomeia um lado se refere a um lado do texto ou do fluxo do corpo, nunca da folha, então um design feito para um livro em inglês continua funcionando quando o livro passa para o árabe. 'start' e 'end' são aceitos como nomes explícitos:

placement.rotate mantém o sentido físico numa página espelhada: uma figura girada no sentido horário fica girada no sentido horário na folha. Um host que lê o layout encontra o quadro espelhado em cada página (VDTPage.flow com direction: 'rtl', pageIsMirrored(page)) e a ordem visual dos segmentos de cada linha em VDTLine.order; flowToPage e pageToFlow convertem entre o fluxo e a folha. Veja Composição árabe.

const arabic: PostextConfig = { locale: 'ar' };                        // da direita para a esquerda, encadernado pela direita
const english: PostextConfig = { locale: 'en', direction: 'rtl' };     // forçado; raramente é o que você quer

#Idiomas e escritas

O Postext compõe escritas alfabéticas da esquerda para a direita, e o chinês e o japonês na horizontal e na vertical. Composição chinesa e Composição japonesa explicam como são compostos e quais ajustes os controlam; as chaves estão em Tipografia do Leste Asiático, Escrita vertical e Encadernação. O que cada escrita recebe:

• O chinês é composto pelo compositor CJK quando um parágrafo tem mais caracteres CJK do que espaços entre palavras: as linhas quebram entre caracteres segundo as regras de início e fim de linha de cjk.lineBreak (nenhuma linha começa com 。、」 ou ー, nenhuma termina com 「 ou （), mantêm inteiros —— e ……, um número com seus sinais e uma palavra latina, e uma linha justificada é espaçada entre os caracteres até a medida. A largura da pontuação, a pontuação pendente, o espaço entre han e latim, a grade de caracteres, os pontos de ênfase, as marcas de nome próprio e de título de obra, o rubi e as notas warichu seguem a região de locale, na linha horizontal ou na vertical (layout.writingMode: 'vertical-rl'). Um parágrafo latino que cita algumas palavras CJK mantém a quebra de linha ótima e pode quebrar ao lado delas; um colchete CJK, o ponto médio ou um sinal de largura total citado em texto latino (〈h〉, ％) não muda nada.
• O japonês passa pelo mesmo compositor com regras próprias desde o postext 1.16, as dos Requirements for Japanese Text Layout (JLReq) do W3C e da JIS X 4051: um locale ja dá a região japan, cujos valores automáticos definem os níveis de kinsoku da JLReq (kana pequenos e ー nunca abrem uma linha), pontuação de largura total com compressão de pares, um eme depois de ？！, o parêntese que abre um parágrafo na segunda metade do recuo, marcas de ênfase em forma de gergelim sobre o texto, títulos de obras entre 『』, furigana espaçados 1:2:1, contadores japoneses, notas e um índice ordenado pela leitura. As versões anteriores compunham o japonês com os padrões da China continental.
• O coreano passa pelo mesmo compositor e é composto sem hifenização, mas com os padrões da China continental: as regras próprias dele (KLREQ) não estão implementadas. O texto coreano quebra entre sílabas e também nos espaços.
• O árabe e as outras escritas da direita para a esquerda (persa, urdu, hebraico…) são compostos da direita para a esquerda: Composição árabe explica como. A direction do documento vem da escrita de locale, o algoritmo bidirecional do Unicode ordena as palavras latinas e os números dentro de cada linha, o livro é encadernado pela direita com a primeira coluna à direita, e todo número que o motor escreve usa os algarismos da região. Uma palavra que contém uma letra da escrita árabe nunca é hifenizada, espaçada nem cortada, e uma linha árabe justificada se estica nos espaços e com kashidas. Sinais vocálicos, ênfase, notas de rodapé e as strings do árabe estão em Texto árabe. O persa, o urdu e o hebraico recebem a direção, os algarismos e as regras de palavra inteira, mas nenhuma string integrada própria.

Há padrões de hifenização para oito idiomas (en-us, es, fr, de, it, pt, ca, nl); os tipos de recurso integrados e as strings de continuação existem nesses oito, em chinês, em japonês e em árabe. Chinês, japonês, coreano e os idiomas escritos da direita para a esquerda são compostos sem hifenização. Qualquer outro idioma é hifenizado com os padrões do inglês dos EUA, com um aviso no console, e recebe as strings em inglês. Para um documento assim, defina hyphenation.enabled: false e passe resourceTypes e as strings de continuação de tableStyle no idioma dele.

#Texto árabe

Estes ajustes servem ao texto em escrita árabe; nenhum muda um documento escrito em outra escrita. Composição árabe os explica junto com o resto de um livro árabe: direção, encadernação, algarismos, verso, sumário e índice.

• Sinais vocálicos e entrelinha. Os sinais vocálicos de um texto vocalizado (fatḥa, kasra, shadda, tanwīn, o alef sobrescrito, os sinais corânicos) se empilham sobre e sob as letras, dentro da entrelinha, que nunca cresce por causa deles. Cada linha com sinais registra até onde vai a tinta deles (VDTLine.markInk), e o recorte de coluna dos renderizadores inclui os sinais da primeira e da última linha da coluna. Quando um sinal sobre uma palavra encosta nas letras ou nos sinais pendurados sob a palavra de cima, a composição avisa o parágrafo (arabicMarksExceedLeading, no painel Verificações do Sandbox). Só se comparam palavras que estão uma sobre a outra. Texto parcialmente vocalizado pede cerca de 1,7–1,85 em de lineHeight; verso totalmente vocalizado, 1,9–2,1 em.
• Ênfase. A tipografia árabe não tem itálico, então num documento cujo locale se escreve em escrita árabe *…* sai em negrito por padrão (bodyText.emphasis: 'auto'). 'color' o compõe em redondo com italicColor, e 'overline' traça um fio sobre as palavras, o khaṭṭ fawqī dos livros árabes. O ajuste vale para todo texto composto com as fontes do corpo: parágrafos, listas, citações em bloco, estilos de parágrafo, corpo dos boxes, notas e títulos. Legendas, células de tabela, o sumário e o índice mantêm os próprios ajustes de itálico. Seja qual for a escolha, o motor nunca inclina letras árabes: as palavras árabes de um trecho em itálico ficam em pé e as palavras latinas mantêm o itálico. Num documento assim, a citação em bloco é em redondo por padrão.
• Tashkīl. bodyText.tashkil: 'strip' tira os sinais vocálicos e corânicos do texto que o layout compõe, para uma edição sem vogais feita a partir de uma fonte vocalizada: fatḥa, ḍamma, kasra e seus tanwīn, sukūn, shadda, o alef sobrescrito (هٰذا vira هذا) e os sinais U+0656–U+065F e U+06D6–U+06ED. 'strip-vowels' mantém a shadda, como a maioria dos livros modernos a imprime. Hamza e madda ficam (أ إ آ são letras, também quando digitadas com sinais combinantes). O original mantém os sinais; as linhas, os títulos e o sumário são compostos sem eles, e cada caractere composto continua apontando para o seu lugar no original.
• Notas de rodapé. footnotes.markerTemplate: '({n})' escreve as chamadas «(١)» nos algarismos do documento, numbering: 'page' recomeça a numeração em cada página e noteNumberPosition: 'inline' põe o número da própria nota na linha. O fio separador e os números das notas ficam no início da coluna, à direita num livro da direita para a esquerda.
• Palavras inteiras. Uma palavra que contém uma letra da escrita árabe nunca é hifenizada, cortada ou espaçada, num livro árabe ou citada em outro. Um estilo que aplica letterSpacing a texto árabe é avisado (joiningScriptLetterSpacing), e uma palavra mais larga que a linha transborda dela e é avisada (unbreakableWordOverflow). Veja Composição árabe.
• Kashida e verso. Uma linha árabe justificada se estica com kashidas além dos espaços (bodyText.kashida, veja Kashida no texto árabe), e um poema clássico é composto um bayt por linha, em dois hemistíquios de mesma largura, com :::verse (veja :::verse).
• Índice. Um índice em árabe ordena alfabeticamente e ignora o artigo ال (index.ignoreArticle), os sinais vocálicos e os suportes da hamza; veja Índice remissivo.

#Órfãs, viúvas, linhas curtas e regras de manter junto

Veja Hifenização e justificação para a mecânica por trás destes deméritos. Esta seção é a referência das chaves de bodyText que os controlam.

Além da hifenização e dos limites de espaçamento, a configuração do texto do corpo expõe as regras flexíveis que evitam quebras de parágrafo estruturalmente desajeitadas. Todas entram no algoritmo de quebra de linhas de Knuth-Plass como deméritos: elas puxam o layout para quebras limpas sem nunca impor uma regra rígida. Defina os valores *Penalty como 0 para desativar, na prática, qualquer uma delas.

Sobre linhas curtas. Uma linha curta é a última linha de um parágrafo curta demais para parecer uma linha de texto de verdade, em geral uma ou duas palavras curtas isoladas no fim do parágrafo. Como a verificação se baseia no comprimento da linha em pixels em relação à largura do espaço normal, runtMinCharacters se adapta sozinho ao corpo da fonte atual. Uma palavra curta que, visualmente, é mais larga que runtMinCharacters × spaceWidth não tem problema; uma palavra mais estreita que isso (ou realmente sozinha) recebe a penalidade de linha curta. O limite conta espaços entre palavras, que têm cerca de metade da largura das letras: o padrão 20 corresponde a uma última linha de mais ou menos 8 a 12 letras. Toda linha curta custa a penalidade inteira, então entre dois finais abaixo do limite o algoritmo de quebra mantém as linhas mais apertadas acima; gradedRuntPenalty cobra cada um pelo que lhe falta, e o final mais longo vence. Para os curiosos de matemática: com o runtPenalty padrão de 1000, evitar uma linha curta supera qualquer conjunto de quebras alternativo que exija um esticamento do espaçamento entre palavras de até cerca de r≈2,15.

Flexíveis, não rígidas. Nenhuma destas regras pode impedir uma quebra: o motor sempre produz um layout. São deméritos: o algoritmo pondera badness, custo de hifenização, suavidade das classes de aptidão e estas penalidades estruturais numa única otimização global e escolhe o conjunto de quebras com o menor custo total. Se você precisa de uma garantia mais firme, aumente a penalidade; se um documento fica melhor com a penalidade mais branda, diminua-a.

#Títulos

A propriedade headings controla a tipografia de todos os níveis de título (H1–H6). Você pode definir padrões gerais que valem para todos os níveis e depois sobrescrever propriedades específicas por nível.

#Padrões gerais

Títulos centralizados para poemas ou os atos de uma peça, sem posição de design:

headings: {
  textAlign: 'center',
  levels: [{ level: 2, textTransform: 'uppercase' }],
}

Passar um objeto headings mantém todo padrão de nível que você não repetir, inclusive a quebra de página do H1 (veja Sobrescritas por nível).

#Equilíbrio de colunas

As editoras esperam que toda coluna comece no alto da página e termine alinhada com o pé. As regras de quebra (proteção contra órfãs e viúvas, títulos mantidos com o seu texto, figuras indivisíveis) deixam naturalmente colunas curtas, com uma ou mais linhas vazias da grade de linhas de base no pé. Com o equilíbrio ativado, o motor faz o que um compositor faria e aplica seus recursos na ordem de prioridade editorial:

1. Um boxe que fecha a coluna: um boxe que termina uma coluna curta é empurrado para baixo exatamente pelo espaço que sobra sob o seu pé, de modo que a borda inferior cai na última posição da grade da página, alinhada com a última linha da coluna ao lado. Ele ocupa esse espaço mesmo quando é menor que uma linha, desde que nada passe para outra coluna. Por padrão, roda antes de qualquer outro recurso e ocupa a lacuna inteira, então um boxe que comenta o parágrafo acima dele pode acabar várias linhas abaixo; closingBox: 'last' deixa os títulos, os finais de lista e os outros recursos de espaçamento ficarem primeiro com as linhas inteiras, e o boxe só com o que sobrar, e closingBox: 'off' nunca o move.
2. Imagens com área segura: uma imagem com área segura (Resource.safeArea, veja Formato do documento › Área segura) inserida na linha da coluna curta, ou flutuando no alto ou no pé dela só sobre essa coluna, cresce em linhas inteiras da grade, recortada dentro da área segura, até a coluna ficar cheia ou o recorte chegar à área segura. Uma imagem mais alta não deixa buraco na página, por isso roda antes de qualquer espaço ser somado; um flutuante no alto de uma coluna numa página ou faixa cujas cabeças de coluna ficam niveladas (veja abaixo) não cresce. Registrado como flexFigure. Não tem ajuste próprio: só cresce uma imagem cujo recurso marca uma área segura.
3. Títulos: linhas inteiras da grade são somadas à margem superior dos títulos dentro da coluna curta. Quando são necessárias várias linhas e a coluna tem vários títulos, as linhas se distribuem entre eles, sempre com a maior parte para o título mais importante (um h2 recebe mais que um h3). Títulos no alto de uma coluna nunca recebem espaço extra, para que as colunas continuem começando no alto da página, exceto um título logo abaixo de uma figura ou tabela que encabeça a coluna numa página que continua: o espaço vai acima desse título, sob a figura.
4. Finais de lista: quando os títulos não conseguem absorver a lacuna inteira, uma linha da grade é somada onde uma lista ou enumeração termina (espaço depois de uma lista soa natural), com um limite por final de lista.
5. Parágrafos frouxos: como último recurso, um parágrafo da coluna é quebrado de novo com uma linha a mais (o \looseness=+1 do TeX), escolhendo o parágrafo mais longo para que o espaçamento extra entre palavras se dilua sem ser notado. A solução frouxa só é aceita quando toda linha fica abaixo de bodyText.maxWordSpacing: a cor tipográfica nunca passa do limite que você já configurou. Requer bodyText.optimalLineBreaking.

Numa grade de caracteres (cjk.grid, veja Composição chinesa › A grade de caracteres) cada caractere ocupa uma célula de um em de largura e cada linha cai no passo de linhas da grade, que é também a grade de linhas de base. Ali o equilíbrio fica desativado por padrão, como no texto vertical: uma página composta linha a linha sobre uma grade, à maneira da GB/T 9704, que conta 22 linhas de 28 caracteres, deixa curta a coluna que termina curta. Uma configuração que define enabled: true recebe recursos que respeitam a grade: os títulos, os finais de lista, as fórmulas em destaque e as figuras ocupam linhas inteiras da grade, de modo que o texto abaixo deles se desloca em fileiras inteiras, e gridLines: 'off' deixa esses recursos de fora para uma norma que não tem nenhuma fileira vazia para ceder. Um parágrafo chinês ou japonês ganha uma linha só quando nenhum vão entre dois dos seus caracteres se abre mais que maxTracking, e não recebe tracking nas suas letras: uma linha a que falta um caractere distribui um em pelos seus vãos, muito acima dos 0,01 em do padrão, então numa grade de células inteiras o recurso dos parágrafos frouxos quase nunca encontra nada. O boxe que fecha uma coluna e as imagens com área segura ficam fora da grade por projeto e funcionam como em qualquer outra página.

A última coluna de uma página só é equilibrada quando a página continua naturalmente na seguinte: a página de fechamento de um capítulo pode, legitimamente, terminar curta. Uma página assim, e uma faixa de fechamento cortada por igual por trailing, também mantém niveladas as cabeças de coluna: nenhuma linha é somada sob uma figura ou tabela que encabeça uma das colunas (o recurso de depois do flutuante), e um título ou um boxe que abre uma coluna sob essa figura fica no alto dela, diga o que disser stretchAfterFloats, de modo que uma coluna nunca começa mais abaixo que a vizinha só para alinhar os pés.

Qual recurso atuou

O layout registra cada recurso aplicado no bloco em que o aplicou: block.balancing no VDT que buildDocument devolve. Uma prova, um teste ou um relatório pode dizer por que uma coluna termina alinhada, e quais colunas nenhum recurso conseguiu fechar. Os blocos que o equilíbrio não tocou não levam balancing, e um documento construído com enabled: false não tem nenhum.

Numa grade de caracteres o documento diz por que uma coluna pode terminar curta: doc.gridBalancing é { off: true } quando o equilíbrio está desativado porque a página está sobre uma grade e a configuração não o ativa, e { gridLines: 'off' } quando ele roda sem os recursos de linhas inteiras; uma coluna que continua curta leva column.gridRefused, os recursos que a grade lhe negou ('looseParagraph' quando um parágrafo só podia ganhar a sua linha tirando os caracteres das suas células, e os recursos de linhas inteiras com gridLines: 'off'). Nenhum dos dois aparece fora da grade.

interface VDTBalancing {
  levers: BalanceLever[]; // em geral um: um parágrafo depois de uma lista pode ficar com a linha do final de lista e também ganhar uma linha
  spaceAbove: number;     // px que os recursos de espaçamento somaram acima do bloco (0 quando só atuou looseParagraph ou flexFigure)
  bodyGrowth?: number;    // flexFigure: px que a imagem cresceu, recortada dentro da área segura
  extraLines?: number;    // looseParagraph: linhas que o parágrafo ganhou
  tracking?: number;      // looseParagraph: o tracking que as ganhou, em milésimos de eme (0 = só espaçamento entre palavras)
}
type BalanceLever = 'trailingCallout' | 'flexFigure' | 'heading' | 'listEnd' | 'afterDisplay' | 'afterFloat' | 'looseParagraph';

Os cortes por igual ficam registrados nas colunas que cortam: column.bandCapped é true em toda coluna cortada por igual (a faixa que um boxe de página inteira deixa, uma faixa de fechamento), e column.trailingCap marca também a faixa de fechamento de um capítulo ou do documento (trailing).

import { buildDocument } from 'postext';
 
const doc = buildDocument(content, config);
for (const page of doc.pages) {
  page.columns.forEach((column, i) => {
    const levers: string[] = column.blocks.flatMap((block) => block.balancing?.levers ?? []);
    if (column.trailingCap) levers.push('closing band cut level');
    else if (column.bandCapped) levers.push('band cut level');
    if (levers.length > 0) console.log(`page ${page.index + 1}, column ${i + 1}: ${levers.join(', ')}`);
  });
}
// page 3, column 1: heading, heading
// page 3, column 2: listEnd, looseParagraph

#Sobrescritas por nível

Cada nível de título pode sobrescrever os padrões gerais pelo array levels. Só fontSize (além do breakBefore do H1, comentado abaixo) muda por padrão; todas as outras propriedades herdam dos ajustes gerais de título.

O padrão do H1 reproduz a diagramação de capítulos de um livro: todo título de nível superior abre numa página nova à direita (ímpar), com uma página em branco separadora obrigatória depois do capítulo anterior. Sobrescreva-o em levels[0].breakBefore se o seu documento for mais simples que um livro.

O breakBefore de um nível é mesclado campo a campo sobre esse padrão, e um objeto headings que não o menciona o mantém. { parity: 'odd' } no H1 mantém a quebra e muda só a paridade; { enabled: false } deixa os capítulos seguirem em sequência:

headings: {
  fontFamily: 'Merriweather',                               // o H1 continua quebrando para um recto novo (always-odd)
  levels: [{ level: 1, breakBefore: { parity: 'odd' } }],    // …ou: um recto, sem página em branco obrigatória
}
 
headings: { levels: [{ level: 1, breakBefore: { enabled: false } }] } // capítulos em sequência

Mudou no postext 1.5. Até o postext 1.4, qualquer objeto headings desligava a quebra do H1 a menos que levels[0].breakBefore fosse repetido, e um breakBefore parcial completava o campo que faltava com o padrão sem quebra. Por isso, uma configuração escrita em código para a 1.4 com um objeto headings e sem quebra no H1 agora abre todo capítulo num recto novo, com versos em branco onde for preciso. Para manter os capítulos em sequência, dê um campo à entrada H1 de levels:

headings: { fontFamily: 'Merriweather', levels: [{ level: 1, breakBefore: { enabled: false } }] } // como a 1.4 diagramava

Onde a configuração ficou salva, o motor consegue perceber e faz isso por você: o Sandbox, nos livros e configurações que salvou na época (veja Sandbox → Persistência), e openBundle / readBundle, num pacote .postext gravado pelo postext 1.4 ou anterior (veja Pacotes gravados pelo postext 1.4 ou anterior). Uma configuração que você mesmo salvou pode passar por migrateConfig(config) de postext/bundle, que grava as quebras como a 1.4 as diagramava (pinLegacyHeadingBreaks): enabled: false num H1 que não tinha quebra, e parity: 'any' ao lado de um enabled: true que não indicava paridade, no H1 e nos estilos de título. Ele também fixa o tamanho das fórmulas, o espaço em volta das figuras na linha (também nos boxes), as marcas na linha dos títulos, o tamanho das capitulares, o espaço sob uma linha com dois-pontos que introduz uma lista, as linhas que o corte de um boxe deixa de um parágrafo ou de um item de lista, as quebras de linha em travessões, a quebra linha a linha do texto alinhado à esquerda, a divisão de um parágrafo sob um título, as quebras de linha no hífen de uma palavra composta e o espaço sob os contêineres :::paragraphs, como a 1.4 os compunha. Passe o markdown do livro como terceiro argumento, { content }, e ele deixa de fora a fixação das fórmulas quando o texto não tem nenhum $, as das lacunas quando nenhuma linha insere um recurso (a da lacuna nos boxes quando nenhuma o faz dentro de um boxe), a das marcas quando nenhum título tem marcas, a dos dois-pontos quando nenhuma lista vem depois de uma linha terminada em dois-pontos, a do corte de boxes quando o texto não abre nenhum :::callout, a dos travessões quando nenhum travessão está colado entre palavras, a da divisão sob título quando o texto não tem títulos, a dos contêineres quando o texto não abre nenhum contêiner :::paragraphs, e a das palavras compostas quando nenhum hífen está entre duas letras; a da quebra do texto alinhado à esquerda só vai para uma configuração que deixa algum texto corrido alinhado à esquerda, e a dos contêineres só para uma que declara um estilo de parágrafo (veja Pacotes gravados pelo postext 1.4 ou anterior). Para fixar só as quebras, chame pinLegacyHeadingBreaks(config).

As sobrescritas por nível aceitam as mesmas propriedades que os padrões gerais (fontSize, lineHeight, fontFamily, color, fontWeight, marginTop, marginBottom, snapToGrid) e mais estes campos exclusivos de nível (um estilo de título também os aceita):

headings: {
  fontFamily: 'Merriweather',
  levels: [
    // Predefinição canônica de livro: capítulos numa página à direita (ímpar).
    { level: 1, fontSize: { value: 24, unit: 'pt' }, breakBefore: { enabled: true, parity: 'odd' } },
    { level: 2, fontSize: { value: 18, unit: 'pt' }, italic: true },
  ]
}

snapToGrid também funciona por nível. Sem definição, um nível segue headings.snapToGrid; definido, o sobrescreve. Assim, um documento pode pôr os H2 a uma linha e meia do texto, fora da grade até o próximo ponto de ajuste, enquanto os H3 arredondam o espaço sob eles para linhas inteiras da grade. Um estilo de título também pode defini-lo, para os títulos que o usam.

headings: {
  marginBottom: { value: 1.5, unit: 'em' },
  levels: [
    { level: 2, snapToGrid: false }, // exatamente 1,5 em sob cada H2
    { level: 3 },                    // herda headings.snapToGrid: true
  ],
}

#Quebra antes

breakBefore é independente dos controles de numeração: ativá-lo força uma quebra de página, mas o contador numérico só recomeça quando você insere explicitamente uma diretiva :::numbering. As páginas em branco de paridade contam como páginas reais na sequência e recebem cabeçalhos e rodapés segundo as regras normais de par e ímpar.

Um :::pagebreak logo antes de um título assim não substitui a quebra dele: o título continua aplicando a paridade depois da página que a diretiva abriu, o que pode somar uma página em branco. Veja Estilos de título para um título que deve começar logo depois de uma quebra manual.

Valores de paridade

A quem pertencem as páginas em branco

As páginas em branco inseridas por breakBefore levam cabeçalhos com o título do capítulo conforme o motivo pelo qual foram inseridas:

• As páginas inseridas para cumprir uma restrição de paridade ('odd', 'even' ou a parte de paridade de 'always-*') pertencem ao capítulo seguinte. O marcador {chapterTitle} do cabeçalho delas resolve para o título do novo capítulo, porque a página em branco só existe para levar o novo capítulo à paridade certa.
• A separadora obrigatória inicial inserida por 'always-odd' / 'always-even' pertence ao capítulo anterior. É uma pausa deliberada de fim de capítulo, então o cabeçalho {chapterTitle} ainda mostra o título do capítulo antigo.

Os cabeços e a paleta de uma seção com estilo (veja Estilos de título) seguem as mesmas duas regras nas páginas em branco.

Exceção do início do documento

Quando o primeiríssimo bloco do documento é um título com breakBefore ativado (ou a fonte abre com :::pagebreak), a paridade não é aplicada enquanto a primeira página ainda está vazia. O título cai na página 1, como escrito, qualquer que seja a paridade configurada, de modo que um documento que começa com um # Chapter 1 configurado com parity: 'odd' não herda uma página em branco inicial espúria. Depois que algum conteúdo foi colocado, a paridade é aplicada normalmente.

#Largura e design avançado

Cada nível de título aceita dois campos adicionais que controlam como o título é renderizado como abertura de capítulo na largura da página inteira.

Uma abertura tão alta quanto a página. Quando a altura reservada passa do pé da coluna (uma capa cuja minHeight é a altura da página, uma imagem ou um boxe ancorado na página ou na sangria que desce até o refile), a abertura toma o resto da página: o texto que vem depois dela começa na página seguinte, em todas as colunas, tanto num layout de duas colunas quanto num de coluna e meia. Por isso uma capa não precisa de um :::pagebreak depois dela (um não faz mal: não acrescenta página em branco). Um título de coluna (span: 'column') cujo design é mais alto que sua coluna toma essa coluna, e o texto começa no topo da seguinte. O bloco do título desce então até o pé da coluna que ele toma, e seu design é composto contra essa faixa: os elementos ancorados no topo ficam onde estão ancorados, e os que acompanham a faixa (ancorados no meio ou no pé dela, ou com altura 'fill') se limitam ao espaço que o título toma, como se limitam à altura reservada quando ela cabe (até o postext 1.4 o bloco mantinha a altura do seu texto, de modo que esses elementos eram compostos contra uma faixa da altura de um título, e o texto seguinte continuava por baixo do design). Elementos fixos da página que não devem tomar a página (uma tarja na margem externa ao longo de toda a página, um ornamento no pé da página) ficam melhor no design do cabeço ou do rodapé: ancorados em 'page' ou 'bleed' e exibidos com pages: 'opener', são pintados na página de abertura e não reservam espaço no corpo.

Exemplo: uma abertura de capítulo minimalista que mostra “Chapter N” acima do título:

{
  "headings": {
    "levels": [
      {
        "level": 1,
        "span": "page",
        "breakBefore": { "enabled": true, "parity": "always-odd" },
        "advancedDesign": {
          "enabled": true,
          "slot": {
            "elements": [
              {
                "kind": "text",
                "id": "chapterLabel",
                "placement": {
                  "anchor": { "to": "container", "edge": "top" },
                  "offset": { "y": { "value": 48, "unit": "pt" } },
                  "size": { "width": "fill" }
                },
                "content": "Chapter {numberRoman}",
                "fontSize": { "value": 10, "unit": "pt" },
                "align": "center",
                "overflow": "ellipsis-end"
              },
              {
                "kind": "text",
                "id": "chapterTitle",
                "placement": {
                  "anchor": { "to": "#chapterLabel", "edge": "below" },
                  "offset": { "y": { "value": 12, "unit": "pt" } },
                  "size": { "width": "fill" }
                },
                "content": "{titleText}",
                "fontSize": { "value": 24, "unit": "pt" },
                "fontWeight": 700,
                "align": "center",
                "overflow": "wrap",
                "hyphenate": true
              }
            ]
          }
        }
      }
    ]
  }
}

Marcadores de título disponíveis dentro do espaço de design de um nível:

• {titleText}: o texto simples do título (sem o prefixo de numeração). Uma quebra forçada no título (\\) é aqui uma quebra de linha, tanto numa faixa de abertura quanto num design de coluna (até o postext 1.4 um design de coluna imprimia um espaço ali, embora sua altura fosse medida com a quebra). As linhas em que o título oculto se quebra na sua coluna são reunidas de novo no título tal como foi escrito: uma palavra quebrada depois do seu próprio hífen mantém o hífen, sem espaço depois dele; uma palavra que a coluna dividiu volta a ficar inteira, sem o hífen que a quebra acrescentou; um grupo unido por um espaço inseparável que era mais largo que a coluna e foi separado nesse espaço recupera o espaço inseparável (Capítulo XVIII, não CapítuloXVIII); e cada uma das outras quebras devolve o seu espaço. Até o postext 1.4 toda quebra de linha virava um espaço, de modo que um título quebrado num hífen imprimia Word- Book, e uma quebra forçada num título assim se perdia.
• {number}: o número formatado segundo o numberingTemplate do nível.
• {numberDecimal}, {numberRoman}, {numberRomanLower}, {numberAlpha}, {numberAlphaLower}: o contador do título (a contagem corrente do seu nível, seja o que for que o modelo imprima) em outros formatos de numeral: o terceiro capítulo dá 3, III, iii, C, c, com ou sem numberingTemplate. Um título não numerado (um estilo com numbered: false) os deixa vazios.
• {numberWords}, {numberWordsLower}, {numberOrdinalWords}, {numberOrdinalWordsLower}: o mesmo contador por extenso, com maiúscula inicial ou em minúsculas: Three / three, Third / third (veja Números por extenso).
• {numberHan}: o mesmo contador em numerais chineses, na escrita do locale do documento: uma abertura composta com 第{numberHan}回 imprime 第十二回 no décimo segundo capítulo, enquanto o sumário mostra 12.
• {chapterNumber}, {chapterTitle}, {pageNumber}, {totalPages}, {bookTotalPages}, {title}, {subtitle}, {author}, {publishDate}: marcadores de metadados compartilhados.
• {attr.<key>}: um atributo escrito na própria linha do título (# Title {author="I. Zango Martín"}), que recorre ao atributo do H1 do capítulo atual. Atributos ausentes resultam numa string vazia, sem aviso.

{chapterNumber} imprime o que os cabeços imprimem para o capítulo: o número do H1 quando o seu nível (ou estilo) tem um numberingTemplate; caso contrário, o ordinal do capítulo (1, 2…, continuando depois dos capítulos diagramados antes deste); e nada num capítulo não numerado ou num estilo cujo modelo é ''. O design de um título lê o capítulo ao qual o título pertence: um título de nível 1, o seu próprio; um título inferior, o último título de nível 1 antes dele. Isso vale também quando dois capítulos se encontram numa mesma página, embora os cabeços dessa página imprimam o capítulo posterior. A altura que uma abertura reserva é medida com esse mesmo valor. Até o postext 1.4 ela era medida com o prefixo de número do título (vazio sem modelo), de modo que um design cuja altura dependesse de {chapterNumber} podia ser pintado mais alto que o espaço que ocupava; e o design imprimia o capítulo da página, de modo que o primeiro de dois capítulos que dividiam uma página mostrava o número do segundo.

Os marcadores de contador acompanham o livro através de capítulos diagramados um de cada vez (os contadores que continuationAfter() repassa), e o atributo startAt de um título os reinicia (veja Formato do documento → Atributos de título). Uma abertura que diz Chapter III acima de um título numerado 3. no fluxo e no sumário:

{
  level: 1,
  span: 'page',
  numberingTemplate: '{1}.',
  advancedDesign: {
    enabled: true,
    slot: { elements: [
      { kind: 'text', id: 'label', content: 'Chapter {numberRoman}', fontSize: { value: 10, unit: 'pt' }, overflow: 'ellipsis-end',
        placement: { anchor: { to: 'container', edge: 'top-left' }, size: { width: 'fill', height: 'auto' } } },
      { kind: 'text', id: 'title', content: '{titleText}', fontSize: { value: 24, unit: 'pt' }, overflow: 'wrap',
        placement: { anchor: { to: '#label', edge: 'below' }, size: { width: 'fill', height: 'auto' } } },
    ] },
  },
}

Altura reservada

Um título com design avançado ocupa espaço na coluna como qualquer bloco: o texto do corpo que vem depois dele começa abaixo desse espaço. O espaço é a maior de três alturas, todas medidas para baixo a partir do topo do título (o topo da área de conteúdo, numa abertura que começa a sua página):

1. o próprio texto do título, composto na tipografia do nível (fica oculto sob o design, mas mantém suas linhas);
2. a base do conteúdo do design: a borda inferior mais baixa entre os elementos que contam (veja abaixo);
3. advancedDesign.minHeight.

A marginBottom do título é somada depois (do seu estilo de título, do seu nível ou de headings.marginBottom; 0,5 em por padrão), e o resultado é arredondado para cima até a grade de linhas de base quando os títulos se ajustam a ela. Numa abertura (span: 'page'), a mesma faixa fica livre em todas as colunas da página. Num título de coluna que cabe na sua coluna, o design é composto na caixa do título, que tem exatamente essa altura.

Quais elementos contam. Todos os elementos do design contam (textos, fios, caixas e imagens; até o postext 1.4 um elemento image nunca contava, de modo que o texto podia começar por cima de uma imagem da faixa, a menos que minHeight o afastasse), exceto:

• os elementos com reserve: false: decoração que pode ficar sob o texto;
• os elementos que acompanham a própria faixa: ancorados na linha do meio do contêiner (left, center, right) ou na linha de baixo (bottom-left, bottom, bottom-right), com altura 'fill' em relação ao contêiner (uma caixa ou um fio vertical sem altura o preenche por padrão), e qualquer elemento ancorado num deles. O contêiner é a faixa reservada, então esses elementos ficam no pé dela ou a atravessam: um fio sob a faixa, um painel colorido atrás do título. Eles acompanham a altura; nunca a definem. Um texto entre eles que mantém sua própria altura ainda precisa de espaço: um título ancorado no pé da faixa deixa a faixa pelo menos tão alta quanto o título, de modo que o título nunca começa acima do topo do título oculto. Com minHeight: 36mm e o título ancorado em bottom-left, a caixa do título tem 36 mm mais a sua marginBottom, arredondada para cima até a grade, e o título fica no pé dessa caixa, logo acima do texto que vem depois; sem minHeight, um título que ocupa mais linhas que o texto oculto deixa a faixa tão funda quanto o título. Até o postext 1.4 um título assim era pintado para cima, sobre o texto acima do título oculto. Caixas, fios e imagens que acompanham a faixa não impõem esse piso, então um painel ancorado no pé pode subir acima do título.

Os elementos ancorados na página e na sangria contam pelo quanto descem abaixo do topo do título. Uma faixa no alto da página que termina acima do título não conta nada; uma imagem sangrada que passa dele empurra o texto até a sua borda inferior. O mesmo acontece com tudo o que fica baixo na página: um selo a 25 mm do pé da página, uma faixa lateral de altura inteira ou uma moldura reservam a página até a sua borda inferior, e o texto em geral começa na página seguinte. Marque essa decoração com reserve: false (ela continua sendo pintada e outros elementos ainda podem se ancorar nela) e dê ao título o espaço de que ele precisa com os seus elementos de texto ou com minHeight:

{
  "kind": "image", "id": "seal", "resourceId": "seal", "reserve": false,
  "placement": {
    "anchor": { "to": "page", "edge": "bottom-right" },
    "offset": { "x": { "value": -25, "unit": "mm" }, "y": { "value": -25, "unit": "mm" } },
    "size": { "width": { "value": 30, "unit": "mm" } }
  }
}

Um elemento ancorado num elemento que não reserva espaço continua contando, a menos que também seja marcado (uma legenda posta no selo precisa do seu próprio reserve: false).

Onde é pintado. O design de uma abertura (span: 'page') é desenhado antes do corpo, então a decoração que não reserva nada fica sob o texto. O design de um título de coluna é desenhado junto com o bloco do título (por cima dos blocos acima dele na coluna, por baixo dos que vêm depois) onde quer que esteja posicionado acima do pé da sua coluna: também nas margens laterais, na margem superior, na sangria e nas colunas vizinhas. O pé da coluna o corta, no canvas e no PDF, porque o fluxo termina ali (veja Mais alto que a coluna, abaixo). Até o postext 1.4 o canvas e o PDF também o cortavam no topo da sua coluna, de modo que uma faixa ancorada no topo da página ou da sangria entrava nas margens laterais, mas parava na margem superior. Decoração ancorada no pé da página fica melhor numa abertura, ou no design do rodapé com pages: 'opener'.

Mais alto que a coluna. Quando o espaço passa do pé da coluna (uma minHeight tão alta quanto a página, uma imagem ou uma moldura que desce até o refile), o título toma o resto da sua página (uma abertura, em todas as colunas) ou da sua coluna (um título de coluna), e o texto que vem depois dele começa na página ou na coluna seguinte. Seu bloco vai então até o pé da coluna, nunca reduzido à altura do seu texto, de modo que a faixa contra a qual o design é composto é o espaço que ele toma (minHeight incluída, até o pé). Um design mais alto que a própria página (uma linha fina longa numa página de tela pequena) continua sendo cortado no pé da página (um design de coluna, no da sua coluna): o Sandbox o lista no painel Verificações como Design do título cortado. A diagramação não emite aviso por isso (uma capa que toma a sua página é o caso comum e não perde nada), mas qualquer aplicação pode fazer a mesma verificação no layout pronto: collectHeadingDesignCuts(doc) devolve um { kind: 'headingDesignCut', pageIndex, level, where, overflowPx, sourceStart, sourceEnd } para cada título cujo texto de design fica além do pé do refile da página (where: 'page', uma abertura) ou da sua coluna (where: 'column'), e formatWarning descreve cada um. Veja Uma abertura tão alta quanto a página em Largura e design avançado.

A coluna lateral. Num layout de coluna e meia cuja coluna lateral recebe flutuantes (sideColumnRole: 'floats'), um elemento do design de um título de coluna que fica na coluna lateral (um numeral de capítulo ancorado na página, na coluna da margem externa da abertura de um livro didático) mantém a pilha lateral longe dele. Cada figura, tabela ou boxe span: 'side' que a página compõe depois do título mantém um espaço entre flutuantes livre em relação a cada um desses elementos: fica onde a pilha o coloca quando cabe acima do elemento e, caso contrário, vai para baixo dele, ou espera a página seguinte quando o resto da coluna lateral não o comporta ali. Assim, um numeral no alto do canal mantém a pilha inteira abaixo dele, enquanto um número de seção pendurado na margem ao lado de um título mais abaixo na página deixa o alto do canal para as figuras que a página cita (a figura marginal continua no topo da sua página). O que a coluna lateral já contém quando o título é posicionado não se move: uma figura empilhada antes na página que desce até o elemento do título fica onde está, sob o elemento, então um design cujo elemento fica na coluna lateral no meio da página pede que as suas figuras sejam citadas depois do título. Os elementos com reserve: false deixam a coluna lateral livre, como deixam o texto. Uma abertura (span: 'page') não precisa de nada disso: a sua faixa é reservada em todas as colunas, inclusive na lateral. Até o postext 1.4 uma figura lateral citada numa abertura assim era composta no alto da coluna lateral, por cima do numeral.

Capas. Um título de capa que preenche a sua página (minHeight tão alta quanto a página, ou uma imagem de página inteira no seu design) manda, portanto, o texto que vem depois dele para a página seguinte por si só, em layouts de uma ou de várias colunas. Um :::pagebreak logo depois dele é opcional e não faz mal: uma quebra de página numa página ainda vazia não faz nada, então nunca acrescenta uma página em branco. Ele só é necessário quando o design da capa para antes do pé da página e o texto ainda assim deve começar numa página nova.

# Annual report 2026 {style="cover"}
 
:::pagebreak
 
# Letter from the chair

#Números por extenso

Dois sufixos de modelo de numeração escrevem um contador por extenso, no idioma do documento (o locale de nível superior ou, na falta dele, o idioma de hifenização; veja Idioma do documento): words para o cardinal e ordinal para o ordinal. A caixa do sufixo define a caixa das palavras, como A / a faz com as letras:

Inglês, espanhol, chinês e árabe são escritos por extenso; qualquer outro idioma usa as palavras em inglês, como fazem as strings de continuação de tabela embutidas. O chinês escreve os numerais informais de simp-chinese-informal ou trad-chinese-informal, conforme a escrita do locale (一万 / 一萬), com 第 antes de um ordinal; os caracteres Han não têm caixa, então as três grafias de um sufixo imprimem o mesmo. O inglês segue o uso americano (one hundred five, sem and). O espanhol usa formas masculinas, como se numera um capítulo ou um libro (capítulo primero, tercero, veintiuno), e escreve os ordinais de 13 a 29 numa só palavra, como prefere a RAE (decimotercero, vigesimoprimero). Os cardinais são escritos por extenso até 999 999, e os ordinais em espanhol até 999; números maiores saem em algarismos.

Os números em árabe concordam em gênero com o substantivo que contam, então o sufixo aceita um modificador: -feminine (ou -f) para um substantivo feminino, -masculine (-m, o padrão) para um masculino; -classical escreve as centenas مائة, como fazem Bulaq e a maioria das edições egípcias, em vez do moderno مئة. {1:ordinal} escreve o ordinal definido no nominativo que um título usa: الفصل {1:ordinal} dá الفصل الأول, الفصل الحادي عشر, الفصل الحادي والعشرون; الليلة {1:ordinal-feminine} dá الليلة الأولى, الليلة الحادية عشرة, الليلة الحادية والعشرون, الليلة المئتان, e acima de cem a fórmula clássica de “depois”: الليلة الخامسة والأربعون بعد الثلاثمئة, الليلة الحادية بعد الألف. {1:words} escreve o cardinal (واحد وعشرون; feminino إحدى عشرة, واحدة وعشرون). Os ordinais são escritos por extenso até 9 999 e os cardinais até 99 999; os modificadores se combinam ({1:ordinal-f-classical}), e os outros idiomas os ignoram. O árabe não tem maiúsculas, então a caixa do sufixo não muda nada. Os marcadores de design {numberWords} e {numberOrdinalWords} escrevem as formas masculinas; para uma abertura no feminino, ponha o ordinal no modelo do nível e imprima-o com {number}.

Num design de título, {numberWords} / {numberWordsLower} e {numberOrdinalWords} / {numberOrdinalWordsLower} escrevem o contador do título da mesma forma, de modo que a abertura pode dizer Chapter One enquanto o sumário mostra 1. O textTransform: 'uppercase' de um elemento de texto dá as maiúsculas:

// Romance em espanhol: "CAPÍTULO PRIMERO" acima do título, "1." no sumário.
{ level: 1, numberingTemplate: '{1}.', span: 'page',
  advancedDesign: { enabled: true, slot: { elements: [
    { kind: 'text', id: 'n', content: 'Capítulo {numberOrdinalWordsLower}', textTransform: 'uppercase', /* … */ },
    { kind: 'text', id: 't', content: '{titleText}', /* … */ },
  ] } } }

#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 um glifo de caixa de seleção no lugar 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.