Configuració: text i encapçalaments

#Text de cos

La propietat bodyText controla la tipografia de tot el text de paràgraf.

#Cites

Una cita (les línies que comencen per >) pren la família, el cos, l'interlineat, els pesos, l'alineació i la partició de mots del text de cos. bodyText.blockquote fixa la resta; si no es fixa, una cita es veu com fins a postext 1.4: grisa, en cursiva, amb el sagnat de primera línia del cos i sense sagnat lateral.

bodyText: {
  firstLineIndent: { value: 1.5, unit: 'em' },
  // Versos en rodona, en el color del cos, entrats 2 em i sense sagnat de primera línia.
  blockquote: { color: { hex: '#241f26', model: 'hex' }, italic: false, indent: { value: 2, unit: 'em' }, firstLineIndent: { value: 0, unit: 'em' } },
}

Al Sandbox són el grup Cites de la secció Text base.

#Vers

Un poema :::verse les línies del qual no porten separador d'hemistiquis es compon línia a línia (vegeu Format del document › :::verse). bodyText.verse dona els valors per defecte d'aquests poemes; un atribut del mateix nom a l'obertura d'un poema el fixa per a aquell poema.

bodyText: {
  // Restes a la dreta darrere d'un claudàtor; les tankes, senceres.
  verse: { turnover: 'right', keepStanzas: 5 },
}

Una configuració desada abans d'aquests ajustos (configVersion 8 o anterior) que compon un poema sense separador es llegeix amb layout: 'bayt', de manera que el poema conserva les línies centrades que li donava postext 1.22. Una desada amb postext 1.23 (configVersion 9) que compon un poema vers a vers es llegeix amb tighten: false, de manera que els seus versos es parteixen on els partia la 1.23.

Al Sandbox són el grup Vers de la secció Text base.

#Tabulacions

bodyText.tabStops enumera les tabulacions on va un tabulador: :tab, o un caràcter de tabulació en un paràgraf que té tabulacions (vegeu Format del document › Tabuladors i tabulacions per al marcatge i per a com es compon una línia). Els tabStops d'un estil de paràgraf les substitueixen als seus paràgrafs, i el body.tabStops d'un estil de requadre dins de les seves caixes; una llista buida no en fixa cap. Cada tabulació és un TabStop:

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

tabInterval afegeix tabulacions a cada interval des de l'inici de la mesura, passada l'última tabulació de la llista; sense aquest valor, un tabulador més enllà de l'última tabulació és un espai entre paraules. Un caràcter de tabulació escrit al text només és un tabulador en un paràgraf l'estil del qual té tabulacions o un interval, propis o del text de cos; a tot arreu més continua sent l'espai entre paraules que sempre ha estat, de manera que un document desat es compon com abans i no cal fixar-lo a cap versió.

Les tabulacions es comproven amb la resta de la configuració (vegeu Avisos de configuració): una clau desconeguda en una tabulació (leaders) es notifica com a unknownConfigKey amb la clau a què més s'assembla; un align que no és cap dels quatre, com a unknownConfigValue, i la tabulació es compon com a 'start'; una position que no és una longitud, 'end' ni un percentatge, com a unknownConfigValue amb used: 'none', i la tabulació es deixa fora.

El color i la lletra del farciment són els del paràgraf; encara no tenen cap ajust propi.

#Caplletres

Un paràgraf de cos pot començar amb una caplletra: la primera lletra, gran, al costat de les primeres línies, que s'escurcen en l'amplada de la lletra més un espai i es componen com qualsevol altra línia (tallades amb Knuth–Plass, justificades, partides per síl·labes). Un estil de paràgraf en dona una al primer paràgraf de cada grup :::paragraphs de l'estil (a tots els paràgrafs amb each: true, per a un catàleg d'entrades); un nivell d'encapçalament o un estil d'encapçalament en dona una al primer paràgraf de cos després de l'encapçalament (vegeu el camp dropCap de Configuració per nivell, Estils de paràgraf i Estils d'encapçalament). El paràgraf que segueix l'encapçalament es busca més enllà de les línies d'obertura i tancament dels contenidors, les directives, les caixes que han sortit del flux i les figures flotants, igual que el troba indentAfterHeading; un paràgraf dins d'una caixa, un element de llista, una cita, un poema o una nota no en porta mai. Al text, {dropcap}, {dropcap=false} i {dropcap=N} en una línia d'encapçalament o en la línia d'obertura d'un :::paragraphs l'activen, la desactiven o en fixen les línies per a aquell capítol o grup (vegeu Format del document › Caplletres). Des de 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 } } },
  ],
},

Com es compon la lletra:

• Mida. Les dues alçades de majúscula, la del text i la de la inicial, es mesuren a les seves fonts (la tinta d'una H; la de la inicial mateixa en text xinès o japonès), i una font que no dona mètriques de tinta compta les seves majúscules com a 0,72 del seu cos. La mida per defecte serveix per a qualsevol parell de fonts, així que no cal cap correcció per font. El dropCap d'un text de disseny conserva el seu 0,72 fix (vegeu Elements de text).
• La lletra i la seva paraula. La inicial pren grups de grafemes sencers. La resta de la primera paraula continua darrere seu sense espai; una paraula d'una sola lletra (A, I) conserva el seu espai entre paraules a l'inici de la primera línia. Es descarta el sagnat de primera línia propi del paràgraf. La còpia, la cerca, el mapa d'origen i el cursor del Sandbox llegeixen el paràgraf tal com està escrit: el text pla del bloc inclou la lletra, el plainStart de la primera línia compta a partir d'ella, i VDTBlock.dropCap en desa el rang i la geometria al fragment que porta la primera línia.
• Una inicial alçada (lines: 1 amb un fontSize més gran, o un sink inferior a lines) s'alça per damunt de la primera línia, i el paràgraf manté aquesta alçada lliure al damunt, en línies senceres de la retícula, perquè no se sobreimprimeixi al text anterior.
• Talls. El paràgraf no es talla mai abans de la línia sink: passa sencer a la columna o la pàgina següent, tret que estigui sol en una columna buida que no pot encabir aquestes línies; llavors es talla igualment i genera un avís dropCap. Un encapçalament lligat al seu text manté aquestes línies a sota. La part que continua a la columna següent no porta inicial i té les línies a amplada completa; si es torna a tallar per a una columna d'una altra amplada, les primeres línies conserven el seu sagnat. L'equilibratge de columnes pot compondre el paràgraf fluix o estret com qualsevol altre, i no afegeix mai espai entre les línies escurçades.
• Escriptures. Les línies s'escurcen pel costat d'inici: l'esquerra en text llatí, la dreta en àrab i hebreu. Una lletra que s'enllaça amb la següent (àrab, siríac, n'ko) no se separa, i el paràgraf genera un avís dropCap; el xinès i el japonès horitzontals prenen una inicial d'un caràcter (首字下沉). El text vertical no en porta (avís). Un paràgraf que no comença amb cap lletra ni xifra (una referència, una fórmula, una marca de nota) tampoc no en porta (avís).
• Sortides. El canvas, el visor HTML i l'EPUB de maquetació fixa pinten la inicial al costat de les línies; l'HTML l'escriu just abans del text de la primera línia, sense res entremig, de manera que un lector de pantalla llegeix la paraula sencera. En un PDF etiquetat la inicial forma part del P del paràgraf, i amb la resta de la seva paraula, d'un Span l'/ActualText del qual és la paraula: l'extracció de text llegeix Molt abans, mai M olt abans. Un EPUB de maquetació fluida la compon com un initial-letter de CSS (línies, enfonsament), flotant on el sistema de lectura no l'admet.

Els ajustos es comproven amb la resta de la configuració (vegeu Avisos de configuració): una clau desconeguda en una caplletra o en les seves paraules inicials es notifica com a unknownConfigKey; un punctuation o un shortParagraph que no és cap dels seus valors, o un lines, un sink o un characters que no és un nombre enter a partir d'1, com a unknownConfigValue, i es fa servir el valor per defecte. Les caplletres estan desactivades per defecte, de manera que cap document desat no canvia.

#Una sola família per fontFamily

fontFamily —aquí i en qualsevol altre camp de família tipogràfica (headings.fontFamily, tableStyle.bodyFontFamily, separatorFontFamily, el fontFamily d'un estil de xip o d'un element de disseny…)— anomena una família. El canvas, la sortida HTML i el PDF han de compondre amb la mateixa font, i el PDF incrusta una font per família, sense cadena de reserva, de manera que una llista de fonts CSS no té a què recórrer. Una llista es compon en la seva primera família i es notifica com a avís de configuració:

bodyText: { fontFamily: "'EB Garamond', Georgia, serif" } // es compon en EB Garamond

Carrega aquesta família abans de compondre (consulta Fonts personalitzades i el proveïdor de fonts a Generació de PDF); si falta, el navegador mesura amb la seva font per defecte, digui el que digui la resta de la llista. Una coma entre cometes forma part del nom ('"Foo, Bar"' és una sola família).

#Partició de mots

Quan l'alineació del text està configurada com a 'justify', la partició de mots evita l'espaiat excessiu entre paraules en trencar les paraules llargues pels límits sil·làbics. El motor utilitza patrons TeX/Liang per trobar punts de ruptura naturals en els límits sil·làbics. Vegeu Partició de mots i justificació per a una explicació detallada. El text en bandera només es divideix si es demana: vegeu Text en bandera més avall.

Llengües admeses: 'en-us' (anglès), 'es' (castellà), 'fr' (francès), 'de' (alemany), 'it' (italià), 'pt' (portuguès), 'ca' (català), 'nl' (neerlandès).

Per triar els patrons s'ignoren les subetiquetes de regió, escriptura i variant, les majúscules i els separadors _: 'es-ES', 'es-MX' i 'es_419' es divideixen amb 'es', 'pt-BR' amb 'pt' i qualsevol etiqueta anglesa ('en', 'en-GB') amb 'en-us', els únics patrons anglesos inclosos, de manera que el text britànic rep els talls nord-americans. Una llengua sense patrons inclosos ('sv', 'pl', 'fi'…) es divideix amb els d''en-us', cosa que dona talls equivocats en lloc de cap; el motor ho avisa un cop per etiqueta amb un console.warn, i el Sandbox ho mostra al seu tauler de revisió. Per a un document així, fixa enabled: false; això també fa callar l'avís. El xinès, el japonès i el coreà (zh, ja, ko, amb qualsevol regió o escriptura) no necessiten patrons ni imprimeixen cap avís: un document en una d'aquestes llengües es compon sense partició de mots. Per dividir les paraules llatines que cita, fixa enabled: true i anomena'n la llengua a locale ('en-us' per a l'anglès). Amb enabled: true sense locale, o amb un de xinès, japonès o coreà, la partició continua desactivada i la consola ho avisa un cop. matchHyphenationLocale(tag) retorna la llengua inclosa a la qual correspon una etiqueta (undefined si no n'hi ha cap), i HYPHENATION_LOCALES enumera les incloses. La configuració resolta (doc.config.bodyText.hyphenation) anomena a locale els patrons que s'usen de debò i conserva a tag l'etiqueta que vas donar quan és diferent. El backend PDF declara la llengua del document a partir de locale, a l'arrel de la configuració, i només fa servir aquesta etiqueta quan locale falta (consulta Llengua del document).

import { matchHyphenationLocale } from 'postext';
 
matchHyphenationLocale('es-MX'); // 'es'
matchHyphenationLocale('en-GB'); // 'en-us'
matchHyphenationLocale('sv');    // undefined: es divideix amb 'en-us', amb un avís a la consola

Les paraules de menys de 5 caràcters no es parteixen mai. El motor requereix com a mínim 2 caràcters abans i 3 caràcters després d'un punt de ruptura.

Text en bandera

Per defecte només es divideix el text justificat: amb textAlign: 'left', i en els estils de paràgraf alineats a l'esquerra, centrats o a la dreta, totes les paraules es mantenen senceres per irregular que quedi el marge, excepte en un guionet tou (U+00AD) escrit al text. Fixa hyphenation.ragged: true per partir mots també en el text en bandera.

Una línia en bandera no s'estira mai, de manera que dividir tota paraula que no hi cap ompliria el marge de guionets. La zona de partició ho limita, com fa el compositor d'una sola línia dels programes de maquetació. Quan una paraula no cap al final d'una línia, el motor mira el buit que deixaria passar-la sencera a la línia següent. Si aquest buit és més gran que zone, divideix la paraula per l'última síl·laba que hi cap; si no, la paraula baixa sencera. Una zona en em és relativa al cos del mateix text. La zona per defecte, 3em, només divideix les paraules que deixarien una línia clarament curta. Una zona més ampla dona menys guionets i un marge més irregular; amb 0 es divideix tota paraula que no hi cap. Línia a línia, mai no acaben més de dues línies seguides en síl·laba. Els guionets propis de la paraula (enseñanza-aprendizaje), les juntures de les URL, els guionets tous escrits al text i les paraules més amples que la línia sencera es tallen com sempre: la zona i el límit de dues línies només governen les síl·labes del diccionari.

L'ajust val per a tot el document. S'aplica al text de cos i a les cites quan van en bandera, i a tot estil de paràgraf i cos de requadre en bandera que tingui activada la seva pròpia hyphenation (que pren per defecte el hyphenation.enabled del cos), de manera que hyphenation: false manté senceres les paraules d'un estil. Els títols, els peus, les notes, les cel·les de taula i l'índex de continguts no es divideixen; en aquests, com arreu, només es talla una paraula més ampla que la mesura sencera. El text de disseny — capçaleres corregudes, portadelles, pàgines de part — segueix la marca hyphenate de cada element de text, que porten activada les portadelles de pàgina completa i les pàgines de part integrades, i també fa servir el diccionari del document. El text justificat ignora ragged i zone.

const config: PostextConfig = {
  locale: 'es',
  bodyText: {
    textAlign: 'left',
    // Una mica més de partició de mots que amb la zona per defecte de 3 em.
    hyphenation: { ragged: true, zone: { value: 2, unit: 'em' } },
  },
};

Amb optimalRagged (el valor per defecte), el text corregut en bandera es compon amb Knuth-Plass, i la zona conserva el seu sentit: una paraula només es divideix quan no cap en el que queda de línia i passar-la sencera a baix deixaria un buit més gran que la zona. Dues síl·labes seguides no es rebutgen, però costen el mateix que dos guionets seguits en el text justificat, de manera que una tercera és rara. Amb optimalRagged: false, o amb optimalLineBreaking: false, cada línia s'omple abans de passar a la següent, com fins a postext 1.4.

La partició de mots en bandera compon els paràgrafs amb el divisor de línies que fan servir sempre els paràgrafs amb format en línia (negreta, cursiva, enllaços, fórmules), de manera que activar-la pot moure algun tall que no és un guionet. En una línia en bandera, a més dels espais i de les síl·labes del diccionari, aquest divisor talla després d'un guionet o un guió entre dues paraules (largas—separadas; amb breakAfterDashes, després de qualsevol guió posat entre paraules sense espais, també I.—Que i calidad–*precio*), a les juntures de les URL i entre ideogrames, i manté unida una paraula escrita en diversos trams (**Nota**:, (*véase*). Sense partició de mots en bandera, un paràgraf en bandera sense format el talla Knuth-Plass quan optimalRagged està activat (el valor per defecte): als espais, després d'un guionet entre dues lletres (enseñanza- · aprendizaje), com l'altre divisor, i, amb breakAfterDashes, després dels guions entre paraules. Línia a línia, passa pel divisor de pretext, que difereix en tres coses: pot tallar també abans del guió que tanca un incís o després del que l'obre (él · — y), després d'una barra quan divideix síl·labes (km/ · h), i talla una paraula més ampla que la línia per qualsevol caràcter i sense guionet, on l'altre divisor la parteix abans per una síl·laba.

Al Sandbox l'interruptor és Partició de mots en bandera, sota l'alineació de paràgraf de la secció Text base, amb la zona a sota. Amb el cos justificat, el mateix interruptor apareix al costat dels ajustos de justificació, per als estils de paràgraf i requadres en bandera.

#Llengua del document

El locale de primer nivell és la llengua del document en conjunt. Admet els mateixos valors que hyphenation.locale i és el valor al qual recorre aquest camp quan no està definit, de manera que a un llibre en castellà li n'hi ha prou amb locale: 'es' per partir mots en castellà. També tria la llengua de les cadenes integrades de continuació de taules i d'avisos partits ((cont.) / Continued davant de Continúa, vegeu Taules més altes que la pàgina i Marques d'un requadre partit) i la dels números d'encapçalament escrits amb lletres (Chapter One davant de Capítulo uno, vegeu Números amb lletres), i és la llengua que s'etiqueta en un PDF accessible. Si no es defineix, el motor assumeix 'en-us'; el Sandbox recorre a l'idioma de la interfície i mostra el camp a Disseny › Escriptura.

També tria els tipus de recurs integrats. Quan resourceTypes no està definit, buildDocument numera i retola amb defaultResourceTypes(locale), de manera que amb locale: 'de' n'hi ha prou per obtenir Abbildung 1.1 i Tabelle 1.1. Si locale no està definit, el substitueix la llengua de la partició de mots, tant per als tipus de recurs com per a les cadenes de les taules. Una llista resourceTypes explícita sempre mana. Les versions anteriors feien servir els tipus en anglès fos quin fos el locale, tret que passessis tu mateix defaultResourceTypes(locale); un document que fixa locale i vol conservar les etiquetes angleses passa resourceTypes: defaultResourceTypes('en'). Els llibres del Sandbox i els paquets porten la seva pròpia llista, així que no els afecta.

Aquí val qualsevol etiqueta BCP 47, igual que a hyphenation.locale: 'de-AT' rep les cadenes alemanyes. Les cadenes integrades existeixen en les vuit llengües que admet la partició de mots, en xinès (en caràcters simplificats i tradicionals), en japonès i en àrab; qualsevol altra llengua rep les angleses.

El xinès admet zh, zh-Hans, zh-Hant, zh-CN, zh-SG, zh-TW, zh-HK, zh-MO i les formes llargues (zh-Hant-TW), en majúscules o minúscules i amb - o _. Les cadenes segueixen l'escriptura, llegida amb Intl.Locale(tag).maximize(): zh, zh-CN i zh-SG són xinès simplificat; zh-TW, zh-HK i zh-MO, tradicional. Els valors tipogràfics que depenen de la llengua segueixen en canvi la regió, com recomana clreq §1.2: CN, SG i MY compten com a Xina continental, TW com a Taiwan, HK i MO com a Hong Kong, i una etiqueta sense regió es regeix per la seva escriptura (zh-Hant és Taiwan; zh i zh-Hans, la Xina continental). El japonès admet ja, ja-JP, ja-Jpan i qualsevol altra etiqueta ja (isJapaneseLanguage(tag)); des de postext 1.16 té les seves pròpies cadenes i la seva pròpia regió, japan, els valors tipogràfics per defecte de la qual segueixen JLReq (vegeu Composició japonesa). Una taula de cadenes sense entrada japonesa dona l'anglès, mai el xinès. localeScript(tag), cjkRegionOf(tag), stringsKeyOf(tag) i sameContentLocale(a, b) retornen aquestes lectures, i DOCUMENT_LANGUAGES enumera les llengües amb cadenes integrades, cadascuna amb el seu nom en la seva pròpia llengua (日本語 entre les entrades xineses i العربية), tal com les mostra el selector de llengua del document del Sandbox.

El prefix del peu és el nom del tipus (Figura 1.1.). Els tipus xinesos numeren dins del capítol amb un guionet, {h1}-{n} (图 1-1); amb els ajustos de peu labelNumberGap: '' i labelSeparator: '　' el peu es llegeix 图1-1　标题 (vegeu Estil de peus de recurs). L'índex alfabètic també segueix la llengua: 见 i 另见 davant d'una remissió, 符号 i 数字 sobre els símbols i els números en xinès simplificat; 見, 另見, 符號 i 數字 en tradicional. El japonès numera els seus tipus de la mateixa manera i compon els seus peus com 図1-1　題 sense els dos ajustos, escriu les referències creuades com 第3章, 2.3節 i 12ページ, titula la bibliografia 参考文献, i el seu índex imprimeix 記号 i 数字 sobre els símbols i els números i escriu les remissions amb una fletxa, →夏目漱石 per a vegeu i →夏目漱石、森鷗外も見よ després de les pàgines per a vegeu també, amb les etiquetes en rodona. L'àrab numera els seus tipus de la mateixa manera, {h1}-{n} (شكل 2-3), escriu les referències creuades com الفصل 3, القسم 2-1 i ص 12, titula la bibliografia المراجع, i el seu índex imprimeix انظر / انظر أيضًا, رموز i أرقام, amb la coma i el punt i coma àrabs (، ؛).

Un document en xinès, japonès o coreà declara la seva llengua a la sortida HTML (lang a l'arrel .pt-doc, amb zh-Hant-TW complet) i al canvas que pinta (ctx.lang, a Chrome 136 i posteriors), de manera que el navegador dibuixa les formes de glif de la seva regió: Unicode unifica els caràcters han, i un mateix punt de codi es veu diferent en una font taiwanesa i en una de japonesa. Els altres documents no porten lang, com abans. El PDF declara /Lang a partir de locale per a tot document, etiquetat o no, amb la seva escriptura i la seva regió. Un document en una llengua que s'escriu de dreta a esquerra (àrab, persa, urdú, hebreu…) també declara la seva llengua: les formes de la llengua de la font (locl) i la font de reserva la segueixen.

const config: PostextConfig = {
  locale: 'es',
  bodyText: { textAlign: 'justify', hyphenation: { enabled: true } }, // parteix mots en castellà
};

Xifres del document

La clau numerals de primer nivell fixa les xifres de tots els números que escriu el motor: els números de pàgina i les etiquetes de pàgina de l'índex general, de l'índex alfabètic i de les referències a pàgina; els números de les llistes ordenades i de les notes; els comptadors de títols i capítols, {chapterNumber}; el {h1} i el {n} del número d'una figura i d'una referència a aquesta; {totalPages}, {bookTotalPages} i {numberDecimal}. 'latn' escriu 0–9, 'arab' les xifres aràbigues orientals ٠–٩ i 'arabext' les perses ۰–۹. Només canvia el format decimal —decimal, l'arabic de les llistes o un ajust que es deixa per defecte—, de manera que un format que l'autor anomena s'imprimeix tal com s'anomena: lower-roman continua sent i, ii, iii, i arabic-indic en un document llatí escriu ١, ٢, ٣. El text del document no es reescriu mai.

El valor per defecte, 'auto', pren les xifres de locale (defaultNumeralsFor(tag)): 'arab' per a l'àrab sense regió o amb qualsevol regió fora del Magrib (ar, ar-EG, ar-SA, ar-AE…), 'latn' per a ar-MA, ar-DZ, ar-TN, ar-LY, ar-MR i ar-EH, 'arabext' per al persa (fa), el paixtu (ps) i l'urdú de l'Índia (ur-IN), i 'latn' per a tota la resta, inclòs l'urdú del Pakistan. CLDR dona latn per a ar sense regió i per a ar-AE; els llibres àrabs del Màixriq i del Golf imprimeixen ٠–٩, i Postext segueix els llibres. Una etiqueta que anomena les seves xifres les conserva: ar-MA-u-nu-arab. Una pàgina numerada amb les xifres del document desa arabic-indic o persian com a pageNumberFormat, de manera que les etiquetes de pàgina del PDF mostren les mateixes xifres. Un valor desconegut segueix la llengua i s'avisa com a unknownNumerals.

Els números que escriu l'autor es llegeixen en qualsevol dels tres sistemes: un element de llista ٣. comença a 3, i {startAt=٥}, :::numbering{startAt=٥}, :::space{lines=٢} i :::part{number="٣"} (per a {numberDecimal}) llegeixen el valor.

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

Direcció del text

direction, al primer nivell, fixa la direcció base del document: 'ltr', 'rtl' o 'auto' (el valor predeterminat), que és 'rtl' quan l'escriptura del locale s'escriu de dreta a esquerra (àrab, persa, urdú, hebreu, siríac, thaana, n'ko, adlam…, segons directionOf(tag)) i 'ltr' en els altres casos. Un document de dreta a esquerra es compon en un marc emmirallat: les línies comencen a la dreta, la primera columna és la de la dreta, els sagnats, els marcadors de llista, els flotants, les notes a peu de pàgina i les caixes queden a la dreta, i page.binding: 'auto' l'enquaderna per la dreta. La configuració resolta només porta direction: 'rtl' en un document així, de manera que un document d'esquerra a dreta es resol igual que abans. Un valor desconegut es llegeix com a 'auto' i s'avisa com a unknownConfigValue. L'algorisme bidireccional d'Unicode (UAX #9) ordena els trams de cada línia en qualsevol de les dues direccions: una cita àrab en un llibre anglès es llegeix de dreta a esquerra al seu lloc.

Dins del document, un títol o un contenidor ::: admet {dir=ltr} o {dir=rtl}, i :ltr[…] i :rtl[…] aïllen un tram de text (vegeu Direcció del text al marcatge); un recurs de taula admet table.direction. Un bloc compost en contra de la direcció del document conserva el seu propi costat d'inici: el sagnat, els marcadors de llista i el final alineat de l'última línia passen al costat per on comença el seu text.

Un ajust que anomena un costat es refereix a un costat del text o del flux, mai del plec, de manera que un disseny fet per a un llibre anglès continua valent quan el llibre passa a l'àrab. 'start' i 'end' s'accepten com a noms explícits:

placement.rotate conserva el seu sentit físic en una pàgina emmirallada: una figura girada en el sentit de les agulles del rellotge queda girada així al plec. Qui llegeix la maquetació troba el marc emmirallat a cada pàgina (VDTPage.flow amb direction: 'rtl', pageIsMirrored(page)) i l'ordre visual dels segments de cada línia a VDTLine.order; flowToPage i pageToFlow passen del flux al plec i a l'inrevés. Vegeu Composició àrab.

const arab: PostextConfig = { locale: 'ar' };                          // de dreta a esquerra, enquadernat per la dreta
const angles: PostextConfig = { locale: 'en', direction: 'rtl' };      // forçat; poques vegades és el que vols

#Llengües i escriptures

Postext compon escriptures alfabètiques que s'escriuen d'esquerra a dreta, i el xinès i el japonès en horitzontal i en vertical. Composició xinesa i Composició japonesa expliquen com es componen i quins ajustos els governen; les claus són a Tipografia de l'Àsia oriental, Escriptura vertical i Enquadernació. El que rep cada escriptura:

• El xinès el compon el compositor CJK quan un paràgraf té més caràcters CJK que espais entre paraules: les seves línies es tallen entre caràcters amb les regles de principi i final de línia de cjk.lineBreak (cap línia no comença per 。、」 o ー, cap no acaba en 「 o （), mantenen senceres —— i ……, un número amb els seus signes i una paraula llatina, i una línia justificada s'eixampla entre els seus caràcters fins a la mesura. L'amplada de la puntuació, la puntuació penjada, l'espai entre xinès i llatí, la retícula de caràcters, els punts d'èmfasi, les marques de nom propi i de títol, el ruby i les notes warichu segueixen la regió de locale, al llarg de la línia horitzontal o de la vertical (layout.writingMode: 'vertical-rl'). Un paràgraf llatí que cita unes poques paraules CJK conserva la divisió òptima de línies i es pot tallar al costat d'aquestes; un signe d'obertura o tancament CJK, el punt volat o un signe d'amplada completa citats en text llatí (〈h〉, ％) no canvien res.
• El japonès passa pel mateix compositor amb regles pròpies des de postext 1.16, les dels Requisits per a la composició de textos japonesos del W3C (JLReq) i la JIS X 4051: un locale ja dona la regió japan, els valors automàtics de la qual fixen els nivells de kinsoku de JLReq (els kana petits i ー mai no obren línia), la puntuació d'amplada completa amb compressió de parelles, un quadratí després de ？！, el parèntesi que obre un paràgraf a la segona meitat del sagnat, marques d'èmfasi de sèsam sobre el text, títols d'obres entre 『』, furigana repartits 1:2:1, comptadors japonesos, notes i un índex ordenat per la lectura. Les versions anteriors componien el japonès amb els valors per defecte de la Xina continental.
• El coreà passa pel mateix compositor i es compon sense partició de mots, però amb els valors per defecte de la Xina continental: les seves regles pròpies (KLREQ) no estan implementades. El coreà es talla entre síl·labes a més de pels seus espais.
• L'àrab i les altres escriptures de dreta a esquerra (persa, urdú, hebreu…) es componen de dreta a esquerra; Composició àrab explica com. La direction del document surt de l'escriptura del locale, l'algorisme bidireccional d'Unicode ordena les paraules llatines i les xifres dins de cada línia, el llibre s'enquaderna per la dreta amb la primera columna a la dreta, i cada número que escriu el motor pren les xifres de la regió. Una paraula amb una lletra de l'alfabet àrab no es parteix, no s'espaia ni es talla mai, i una línia àrab justificada s'estira als espais i amb caixides. Els signes vocàlics, l'èmfasi, les notes a peu de pàgina i les cadenes de l'àrab són a Text àrab. El persa, l'urdú i l'hebreu reben la direcció, les xifres i les regles de paraula sencera, però no cadenes integrades pròpies.

Hi ha patrons de partició de mots per a vuit llengües (en-us, es, fr, de, it, pt, ca, nl); els tipus de recurs integrats i les cadenes de continuació existeixen en aquestes vuit, en xinès, en japonès i en àrab. El xinès, el japonès, el coreà i les llengües que s'escriuen de dreta a esquerra es componen sense partició de mots. Qualsevol altra llengua es divideix amb els patrons de l'anglès dels EUA, amb un avís a la consola, i rep les cadenes angleses. Per a un document així, fixa hyphenation.enabled: false i passa resourceTypes i les cadenes de continuació de tableStyle en la seva llengua.

#Text àrab

Aquests ajustos serveixen el text en alfabet àrab; cap no canvia un document escrit en una altra escriptura. Composició àrab els explica juntament amb la resta d'un llibre àrab: direcció, enquadernació, xifres, vers, índex general i índex analític.

• Signes vocàlics i interlineat. Els signes vocàlics d'un text vocalitzat (fatḥa, kasra, shadda, tanwīn, l'alif volat, els signes alcorànics) s'apilen sobre i sota les lletres, a l'interlineat, que no creix per ells. Cada línia amb signes anota fins on arriba la seva tinta (VDTLine.markInk), i el retall de columna dels renderitzadors inclou els signes de la primera i l'última línia de cada columna. Quan un signe sobre una paraula toca les lletres o els signes que pengen sota la paraula de sobre, la composició avisa del paràgraf (arabicMarksExceedLeading, al tauler Revisió del Sandbox). Només es comparen paraules que estan una sobre l'altra. El text vocalitzat en part demana uns 1,7–1,85 em de lineHeight, i el vers vocalitzat del tot 1,9–2,1 em.
• Èmfasi. La lletra àrab no té cursiva, així que en un document el locale del qual s'escriu en alfabet àrab *…* es compon per defecte en negreta (bodyText.emphasis: 'auto'). 'color' el compon en rodona amb italicColor, i 'overline' traça una ratlla per sobre de les paraules, el khaṭṭ fawqī dels llibres àrabs. L'ajust abasta tot text compost amb les fonts del cos: paràgrafs, llistes, cites, estils de paràgraf, cos dels requadres, notes i encapçalaments. Els peus, les cel·les de taula, l'índex general i l'índex analític conserven els seus propis ajustos de cursiva. Es triï el que es triï, el motor no inclina mai lletres àrabs: les paraules àrabs d'un tram en cursiva van en rodona i les seves paraules llatines conserven la cursiva. En un document així, les cites van en rodona per defecte.
• Tashkīl. bodyText.tashkil: 'strip' treu els signes vocàlics i alcorànics del text que es compon, per a una edició sense vocals feta a partir d'una font vocalitzada: fatḥa, ḍamma, kasra i els seus tanwīn, sukūn, shadda, l'alif volat (هٰذا passa a هذا) i els signes U+0656–U+065F i U+06D6–U+06ED. 'strip-vowels' conserva la shadda, tal com la imprimeixen la majoria dels llibres moderns. La hamza i la madda es queden (أ إ آ són lletres, també teclejades amb signes combinants). La font conserva els seus signes; les línies, els encapçalaments i l'índex general es componen sense aquests signes, i cada caràcter compost continua apuntant al seu lloc a la font.
• Notes a peu de pàgina. footnotes.markerTemplate: '({n})' escriu les crides «(١)» amb les xifres del document, numbering: 'page' les reinicia a cada pàgina i noteNumberPosition: 'inline' posa sobre la línia el número de la nota. El filet separador i els números de nota queden al principi de la columna, a la dreta en un llibre de dreta a esquerra.
• Paraules senceres. Una paraula amb una lletra de l'alfabet àrab no es parteix, no es talla ni s'espaia mai, en un llibre àrab o citada en un altre. Un estil que posa letterSpacing a un text àrab s'avisa (joiningScriptLetterSpacing), i una paraula més ampla que la seva línia la desborda i s'avisa (unbreakableWordOverflow). Vegeu Composició àrab.
• Caixida i vers. Una línia àrab justificada s'estira amb caixides a més dels espais (bodyText.kashida, vegeu Caixida en el text àrab), i un poema clàssic es compon un bayt per línia en dos hemistiquis d'una mateixa amplada amb :::verse (vegeu :::verse).
• Índex analític. Un índex en àrab ordena alfabèticament i no té en compte l'article ال (index.ignoreArticle), els signes vocàlics ni els suports de la hamza; vegeu Índex analític.

#Òrfenes, vídues, runts i regles de cohesió

Consulta Partició de mots i justificació per entendre la mecànica de demèrits que hi ha al darrere. Aquesta secció és la referència de les claus de bodyText que governen aquestes penalitzacions.

Més enllà de la partició de mots i els límits d'espaiat, la configuració del cos exposa les regles toves que eviten els salts de paràgraf estructuralment incòmodes. Totes s'injecten com a demèrits a l'algorisme de salt de línia Knuth-Plass: decanten la maquetació cap a salts nets sense imposar mai una regla dura. Posa a 0 qualsevol *Penalty per desactivar aquella penalització.

Sobre les línies curtes. Una línia curta (runt, en anglès) és l'última línia d'un paràgraf quan és massa curta per semblar una línia de text pròpiament dita, típicament una o dues paraules curtes encallades al final del paràgraf. Com que la comprovació es basa en l'amplada en píxels de la línia relativa a l'amplada de l'espai normal, runtMinCharacters s'adapta automàticament a la mida de font actual. Una paraula curta visualment més ampla que runtMinCharacters × anchoDeEspacio és vàlida; una paraula més estreta que això (o veritablement sola) dispara la penalització. El llindar compta espais entre paraules, que fan més o menys la meitat que una lletra: el valor per defecte, 20, equival a una última línia d'unes 8 a 12 lletres. Tota línia curta costa la penalització sencera, així que entre dos finals per sota del llindar l'algorisme conserva les línies més atapeïdes de dalt; gradedRuntPenalty valora cadascun segons el que li falta i guanya el final més llarg. Per a qui tingui curiositat matemàtica: amb el runtPenalty per defecte de 1000, evitar una línia curta domina sobre qualsevol alternativa que exigís un estirament de l'espai entre paraules de fins a aproximadament r≈2,15.

Toves, no dures. Cap d'aquestes regles no pot impedir un salt: el motor sempre produeix una maquetació. Són demèrits: l'algorisme combina en una única optimització global la "badness" (desigualtat), el cost de la partició de mots, la suavitat de classe d'encaix i aquestes penalitzacions estructurals, i tria el conjunt de salts amb el cost total més baix. Si necessites una garantia més dura, puja la penalització; si un document concret es llegeix millor amb la penalització relaxada, abaixa-la.

#Encapçalaments

La propietat headings controla la tipografia de tots els nivells d'encapçalament (H1–H6). Pots establir valors generals per defecte que s'apliquen a tots els nivells, i després sobreescriure propietats específiques per nivell.

#Valors generals per defecte

Encapçalaments centrats per a poemes o els actes d'una obra de teatre, sense ranura de disseny:

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

Un objecte headings conserva tots els valors per defecte de nivell que no repeteixis, inclòs el salt de pàgina d'H1 (vegeu Configuració per nivell).

#Equilibratge de columnes

Les editorials esperen que cada columna comenci a la part superior de la pàgina i acabi alineada amb la part inferior. Les regles de ruptura (protecció d'òrfenes i vídues, títols units al seu text, figures indivisibles) deixen columnes curtes de manera natural — una o més línies de retícula de base buides al final. Amb l'equilibratge activat, el motor fa el que faria un maquetista, aplicant les seves palanques en ordre de prioritat editorial:

1. Una caixa que tanca la columna — un callout que acaba una columna curta baixa exactament l'espai que queda sota el seu peu, de manera que la seva vora inferior cau a l'última casella de retícula de la pàgina, a nivell amb l'última línia de la columna contigua. Ocupa aquest espai encara que sigui menor que una línia, sempre que res no passi a una altra columna. Per defecte actua abans que qualsevol altra palanca i es queda tot el buit, de manera que un requadre que comenta el paràgraf de damunt pot acabar diverses línies per sota d'aquest; amb closingBox: 'last' els encapçalaments, els finals de llista i les altres palanques d'espai prenen abans les línies senceres, i el requadre només el que deixen, i amb closingBox: 'off' no es mou mai.
2. Imatges amb zona segura — una imatge amb zona segura (Resource.safeArea, vegeu Format del document › Zona segura) col·locada en línia a la columna curta, o flotada al seu cap o al seu peu i només sobre ella, creix en línies senceres de retícula, retallada dins de la zona segura, fins a omplir la columna o fins que el retall arriba a la zona segura. Una imatge més alta no deixa cap forat a la pàgina, així que actua abans d'afegir cap espai; un flotant al cap d'una columna d'una pàgina o banda on els caps de columna queden anivellats (vegeu més avall) no creix. S'anota com a flexFigure. No té cap ajust propi: només creix una imatge el recurs de la qual marca una zona segura.
3. Encapçalaments — s'afegeixen línies completes de retícula al marge superior dels encapçalaments de la columna curta. Quan calen diverses línies i la columna conté diversos encapçalaments, les línies es reparteixen entre ells, deixant sempre la major part a l'encapçalament més important (un h2 en rep més que un h3). Els encapçalaments situats al principi d'una columna no reben mai espai addicional, de manera que les columnes continuen començant a la part superior — llevat d'un encapçalament just sota una figura o taula que encapçala la seva columna en una pàgina que flueix cap a la següent: l'espai va damunt d'aquest encapçalament, sota la figura.
4. Finals de llista — quan els encapçalaments no poden absorbir tot el buit, s'afegeix una línia de retícula on acaba una llista o enumeració (l'aire després d'una llista es llegeix amb naturalitat), amb un màxim per llista.
5. Paràgrafs correguts — com a últim recurs, es recompon un paràgraf de la columna amb una línia més (el \looseness=+1 de TeX), triant el paràgraf més llarg perquè l'espaiat addicional es dilueixi de manera invisible. La solució correguda només s'accepta quan totes les seves línies queden per sota de bodyText.maxWordSpacing — el color tipogràfic mai no supera el límit que ja tinguis configurat. Requereix bodyText.optimalLineBreaking.

En una retícula de caràcters (cjk.grid, vegeu Composició xinesa › La retícula de caràcters) cada caràcter ocupa una casella d'un quadratí d'amplada i cada línia cau al pas de línies de la retícula, que és també la retícula de base. Allà l'equilibratge està desactivat per defecte, com en el text vertical: una pàgina composta línia a línia sobre una retícula, a la manera de la GB/T 9704, que compta 22 línies de 28 caràcters, deixa curta la columna que acaba curta. Una configuració que fixa enabled: true rep palanques que respecten la retícula: els encapçalaments, els finals de llista, les fórmules en bloc i les figures prenen línies senceres de la retícula, de manera que el text de sota es desplaça files senceres, i gridLines: 'off' deixa fora aquestes palanques per a una norma que no té cap fila buida per cedir. Un paràgraf xinès o japonès guanya una línia només quan cap espai entre dos dels seus caràcters no s'obre més de maxTracking, i no rep tracking a les seves lletres: una línia a la qual falta un caràcter reparteix un quadratí entre els seus espais, molt per sobre dels 0,01 em per defecte, així que en una retícula de caselles senceres la palanca de paràgrafs correguts gairebé mai no troba res. La caixa que tanca una columna i les imatges amb zona segura queden fora de la retícula per disseny i funcionen com a qualsevol altra pàgina.

L'última columna d'una pàgina només s'equilibra quan la pàgina flueix de manera natural cap a la següent — la pàgina final d'un capítol acaba curta de manera legítima. Aquesta pàgina, i una banda de tancament tallada a nivell per trailing, mantenen a més els caps de les seves columnes a la mateixa altura: no s'afegeix cap línia sota una figura o taula que encapçali una de les seves columnes (la palanca després de flotants), i un encapçalament o una caixa que obre una columna sota aquesta figura es queda al seu cap, digui el que digui stretchAfterFloats, de manera que cap columna no comença més avall que la veïna només per igualar els peus.

Quina palanca ha actuat

La maquetació deixa constància de cada palanca que aplica, al bloc sobre el qual l'aplica: block.balancing al VDT que retorna buildDocument. Una prova d'impremta, un test o un informe poden dir per què una columna acaba alineada — i quines columnes no va poder tancar cap palanca. Els blocs que l'equilibratge deixa com estaven no porten balancing, i un document compost amb enabled: false no el porta en cap.

En una retícula de caràcters el document diu per què una columna pot acabar curta: doc.gridBalancing és { off: true } quan l'equilibratge està desactivat perquè la pàgina va sobre una retícula i la configuració no l'activa, i { gridLines: 'off' } quan actua sense les palanques de línies senceres; una columna que continua curta porta column.gridRefused, les palanques que la retícula li ha negat ('looseParagraph' quan un paràgraf només podia guanyar la seva línia traient els caràcters de les seves caselles, i les palanques de línies senceres amb gridLines: 'off'). Cap dels dos no apareix fora de la retícula.

interface VDTBalancing {
  levers: BalanceLever[]; // normalment una: un paràgraf després d'una llista pot prendre la línia de final de llista i a més guanyar una línia
  spaceAbove: number;     // px que les palanques d'espaiat han afegit damunt del bloc (0 si només ha actuat looseParagraph o flexFigure)
  bodyGrowth?: number;    // flexFigure: px que ha crescut la imatge, retallada dins de la zona segura
  extraLines?: number;    // looseParagraph: línies que ha guanyat el paràgraf
  tracking?: number;      // looseParagraph: el tracking amb què les ha guanyades, en mil·lèsimes d'em (0 = només amb l'espaiat entre paraules)
}
type BalanceLever = 'trailingCallout' | 'flexFigure' | 'heading' | 'listEnd' | 'afterDisplay' | 'afterFloat' | 'looseParagraph';

Els talls anivellats es registren a les columnes que tallen: column.bandCapped val true a tota columna tallada a nivell (la banda que deixa un bloc d'amplada de pàgina, una banda de tancament), i column.trailingCap marca a més la banda de tancament d'un capítol o del document (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('banda de tancament anivellada');
    else if (column.bandCapped) levers.push('banda anivellada');
    if (levers.length > 0) console.log(`pàgina ${page.index + 1}, columna ${i + 1}: ${levers.join(', ')}`);
  });
}
// pàgina 3, columna 1: heading, heading
// pàgina 3, columna 2: listEnd, looseParagraph

#Configuració per nivell

Cada nivell d'encapçalament pot sobreescriure els valors generals a través de l'array levels. Només fontSize (més el breakBefore d'H1, indicat a sota) difereix per defecte — totes les altres propietats s'hereten de la configuració general d'encapçalaments.

El valor per defecte d'H1 reprodueix la maqueta clàssica d'un llibre: cada encapçalament de nivell superior s'obre en una pàgina dreta (senar) nova, amb una pàgina separadora en blanc obligatòria que tanca el capítol anterior. Anul·la levels[0].breakBefore si el teu document és més pla que un llibre.

El breakBefore d'un nivell es combina camp a camp amb aquest valor per defecte, i un objecte headings que no el menciona el conserva. { parity: 'odd' } a H1 manté el salt i només canvia la paritat; { enabled: false } deixa que els capítols vagin seguits:

headings: {
  fontFamily: 'Merriweather',                               // H1 continua saltant a una pàgina senar nova (always-odd)
  levels: [{ level: 1, breakBefore: { parity: 'odd' } }],    // …o: a una senar, sense pàgina en blanc obligatòria
}
 
headings: { levels: [{ level: 1, breakBefore: { enabled: false } }] } // capítols seguits

Canvia a postext 1.5. Fins a postext 1.4, qualsevol objecte headings desactivava el salt d'H1 llevat que es repetís levels[0].breakBefore, i un breakBefore parcial completava el camp que faltava amb el valor sense salt. Per això una configuració escrita en codi per a la 1.4 amb un objecte headings i sense salt d'H1 obre ara cada capítol en una pàgina senar nova, amb pàgines parelles en blanc on calgui. Perquè els capítols continuïn anant seguits, n'hi ha prou amb un camp a l'entrada d'H1 de levels:

headings: { fontFamily: 'Merriweather', levels: [{ level: 1, breakBefore: { enabled: false } }] } // com ho componia la 1.4

On la configuració estava desada, el motor ho pot saber i ho fa per tu: el Sandbox amb els llibres i les configuracions que va desar llavors (vegeu Sandbox → Persistència), i openBundle / readBundle amb un paquet .postext escrit per postext 1.4 o anterior (vegeu Paquets escrits per postext 1.4 o anterior). Una configuració que vas desar tu pot passar per migrateConfig(config) de postext/bundle, que escriu els salts tal com els componia la 1.4 (pinLegacyHeadingBreaks): enabled: false en un H1 que no tenia salt, i parity: 'any' al costat d'un enabled: true que no indicava paritat, a H1 i als estils d'encapçalament. També fixa la mida de les fórmules, l'espai al voltant de les figures en línia (també als requadres), les marques en línia dels encapçalaments, la mida de les caplletres, el lloc sota una línia de dos punts que introdueix una llista, les línies que deixa d'un paràgraf o d'un element de llista el tall d'una caixa, els talls de línia després d'un guió llarg, la composició línia a línia del text en bandera, la divisió d'un paràgraf sota un encapçalament, els talls de línia després del guionet d'un compost i l'espai sota els contenidors :::paragraphs, tal com els componia la 1.4. Si li passes el markdown del llibre com a tercer argument, { content }, omet la fixació de les fórmules quan el text no té cap $, les dels buits quan cap línia no insereix un recurs (la del buit als requadres quan cap no ho fa dins d'un requadre), la de les marques quan cap encapçalament no en porta cap, la dels dos punts quan cap llista no segueix una línia que acaba en dos punts, la del tall de les caixes quan el text no obre cap :::callout, la dels guions llargs quan cap guió llarg no va entre paraules sense espais, la de la divisió sota un encapçalament quan el text no té cap encapçalament, la dels contenidors quan el text no obre cap contenidor :::paragraphs, i la dels compostos quan cap guionet no va entre dues lletres; la del text en bandera només s'aplica a una configuració que posa en bandera algun text corregut, i la dels contenidors només a una que declara algun estil de paràgraf (vegeu Paquets escrits per postext 1.4 o anterior). Per fixar només els salts, crida pinLegacyHeadingBreaks(config).

Les configuracions per nivell admeten les mateixes propietats que els valors generals — fontSize, lineHeight, fontFamily, color, fontWeight, marginTop, marginBottom, snapToGrid — més aquests camps exclusius de cada nivell (un estil d'encapçalament també els admet):

headings: {
  fontFamily: 'Merriweather',
  levels: [
    // Preajust canònic de llibre: els capítols s'obren a la pàgina dreta (senar).
    { level: 1, fontSize: { value: 24, unit: 'pt' }, breakBefore: { enabled: true, parity: 'odd' } },
    { level: 2, fontSize: { value: 18, unit: 'pt' }, italic: true },
  ]
}

snapToGrid també funciona per nivell. Sense fixar, un nivell segueix headings.snapToGrid; fixat, el substitueix — així un mateix document pot deixar els seus H2 a línia i mitja del seu text, fora de la retícula fins al següent punt d'ajust, mentre els seus H3 arrodoneixen l'espai inferior a línies senceres de la retícula. Un estil d'encapçalament també el pot fixar, per als encapçalaments que l'usen.

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

#Saltar abans

breakBefore és ortogonal als controls de numeració: activar-lo força un salt de pàgina, però el comptador numèric només es reinicia quan insereixes explícitament una directiva :::numbering. Les pàgines de farciment per paritat compten com a pàgines reals a la seqüència i reben capçaleres/peus segons les seves regles normals de senar/parell.

Un :::pagebreak just abans d'un d'aquests encapçalaments no substitueix el seu salt: l'encapçalament aplica igualment la seva paritat després de la pàgina que va obrir la directiva, cosa que pot afegir una pàgina en blanc. Vegeu Estils d'encapçalament per a un encapçalament que hagi de començar just després d'un salt manual.

Valors de paritat

Pertinença de les pàgines en blanc

Les pàgines en blanc que insereix breakBefore reben la capçalera {chapterTitle} en funció del motiu de la inserció:

• Les pàgines inserides per satisfer una restricció de paritat ('odd', 'even', o la cua de paritat de 'always-*') pertanyen al capítol entrant. El seu marcador {chapterTitle} es resol al títol del nou capítol — perquè la pàgina en blanc només existeix per empènyer el nou capítol fins a la paritat correcta.
• La pàgina separadora obligatòria que insereix 'always-odd' / 'always-even' pertany al capítol anterior. És una pausa de tancament de capítol deliberada, així que {chapterTitle} continua mostrant el títol del capítol sortint.

Les capçaleres i la paleta d'una secció amb estil (vegeu Estils d'encapçalament) segueixen les mateixes dues regles a les pàgines en blanc.

Excepció a l'inici del document

Quan el primer bloc del document és un encapçalament amb breakBefore activat — o la font comença amb :::pagebreak —, la imposició de paritat s'omet mentre la primera pàgina continuï buida. L'encapçalament aterra a la pàgina 1 tal qual, independentment de la paritat configurada, de manera que un document que comença amb # Capítulo 1 amb parity: 'odd' no arrossega una pàgina en blanc inicial innecessària. Un cop s'ha col·locat qualsevol contingut, la imposició de paritat funciona de la manera habitual.

#Span i disseny avançat

Cada nivell d'encapçalament admet dos camps addicionals que controlen com es renderitza l'encapçalament com a obertura de capítol a pàgina completa.

Una obertura tan alta com la pàgina. Quan l'alçada reservada arriba més enllà del peu de la columna — una portada el minHeight de la qual és l'alçada de la pàgina, una imatge o una caixa ancorada a la pàgina o a la sang que baixa fins al tall —, l'obertura reclama la resta de la pàgina: el text que la segueix comença a la pàgina següent, igual a totes les columnes d'una disposició a dues columnes o de columna i mitja. Per això una portada no necessita un :::pagebreak darrere (posar-lo no fa mal: no afegeix cap pàgina en blanc). Un encapçalament de columna (span: 'column') el disseny del qual és més alt que la seva columna reclama aquesta columna, i el text comença al capdamunt de la següent. El bloc de l'encapçalament baixa llavors fins al peu de la columna que reclama, i el seu disseny es compon contra aquesta banda: els elements ancorats a dalt es queden on són ancorats, i els que segueixen la banda —ancorats al seu centre o al seu peu, o amb alçada 'fill'— s'ajusten a l'espai que reclama l'encapçalament, igual que s'ajusten a l'alçada reservada quan hi cap (fins a postext 1.4 el bloc conservava l'alçada del seu text, de manera que aquests elements es componien contra una banda de l'alçada del títol, i el text que el seguia s'esmunyia sota el disseny). Els adorns de pàgina que no l'han de reclamar — una franja al llarg de tot el tall davanter, un ornament al peu de la pàgina — van al disseny de la capçalera o del peu: ancorats a 'page' o a 'bleed' i mostrats amb pages: 'opener', es pinten a la pàgina d'obertura sense reservar espai del cos.

Exemple — una obertura de capítol minimalista que mostra «Capítol N» damunt del títol:

{
  "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": "Capítol {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
              }
            ]
          }
        }
      }
    ]
  }
}

Marcadors disponibles dins d'una ranura de disseny d'encapçalament:

• {titleText} — text pla de l'encapçalament (sense prefix numèric). Un salt forçat al títol (\\) és aquí un salt de línia, tant en una banda d'obertura com en un disseny dins de la columna (fins a postext 1.4 un disseny dins de la columna imprimia un espai, tot i que la seva alçada es mesurava amb el salt). Les línies en què l'encapçalament ocult es reparteix a la seva columna es tornen a unir al títol tal com està escrit: una paraula tallada després del seu propi guionet conserva el guionet i no porta espai darrere, una paraula que la columna va dividir torna a quedar sencera, sense el guionet que hi va afegir el tall, un grup unit per un espai de no separació que no cabia a la columna i es va partir en aquest espai el recupera (Capítulo XVIII, no CapítuloXVIII), i cadascun dels altres talls retorna el seu espai. Fins a postext 1.4 cada salt de línia es convertia en un espai, de manera que un títol partit en un guionet imprimia Word- Book, i en aquest títol es perdia un salt forçat.
• {number} — número formatat segons numberingTemplate.
• {numberDecimal}, {numberRoman}, {numberRomanLower}, {numberAlpha}, {numberAlphaLower} — el comptador de l'encapçalament (el compte acumulat del seu nivell, imprimeixi el que imprimeixi la plantilla) en altres formats de numeració: el tercer capítol dona 3, III, iii, C, c, amb numberingTemplate o sense. Un encapçalament sense numerar (un estil amb numbered: false) els deixa buits.
• {numberWords}, {numberWordsLower}, {numberOrdinalWords}, {numberOrdinalWordsLower} — el mateix comptador en lletres, amb majúscula inicial o en minúscula: Tres / tres, Tercero / tercero (vegeu Nombres en lletres).
• {numberHan} — el mateix comptador en numerals xinesos, en l'escriptura del locale del document: una obertura composta amb 第{numberHan}回 imprimeix 第十二回 al dotzè capítol mentre l'índex mostra 12.
• {chapterNumber}, {chapterTitle}, {pageNumber}, {totalPages}, {bookTotalPages}, {title}, {subtitle}, {author}, {publishDate} — metadades compartides.
• {attr.<clave>} — un atribut escrit a la mateixa línia de l'encapçalament (# Título {author="I. Zango Martín"}), amb l'atribut de l'H1 del capítol actual com a alternativa. Els atributs absents es resolen com una cadena buida sense avís.

{chapterNumber} imprimeix el mateix que les capçaleres per a aquest capítol: el número de l'H1 quan el seu nivell (o el seu estil) té numberingTemplate; si no, l'ordinal del capítol —1, 2…, continuant després dels capítols maquetats abans que aquest—, i res per a un capítol sense numerar o un estil la plantilla del qual és ''. El disseny d'un encapçalament llegeix el capítol al qual pertany el seu encapçalament: un de nivell 1, el seu; un de nivell inferior, el de l'últim encapçalament de nivell 1 anterior. També és així quan dos capítols coincideixen en una pàgina, encara que les capçaleres d'aquesta pàgina imprimeixin el segon. L'alçada que reserva una obertura es mesura amb aquest mateix valor. Fins a postext 1.4 es mesurava amb el prefix numèric de l'encapçalament (buit sense plantilla), així que un disseny l'alçada del qual depengués de {chapterNumber} podia pintar-se més alt que l'espai que havia reservat; i el disseny imprimia el capítol de la pàgina, de manera que el primer de dos capítols que compartien pàgina mostrava el número del segon.

Els marcadors del comptador segueixen el llibre al llarg dels capítols compostos un a un (els comptadors que lliura continuationAfter()), i l'atribut startAt d'un encapçalament els reinicia (vegeu Format de document → Atributs d'encapçalament). Una obertura que diu Capítol III damunt d'un títol numerat 3. en el flux i a l'índex:

{
  level: 1,
  span: 'page',
  numberingTemplate: '{1}.',
  advancedDesign: {
    enabled: true,
    slot: { elements: [
      { kind: 'text', id: 'label', content: 'Capítol {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' } } },
    ] },
  },
}

Alçada reservada

Un encapçalament amb disseny avançat ocupa espai a la columna com qualsevol bloc: el text de cos que el segueix comença a sota d'aquest espai. L'espai és la més gran de tres alçades, totes mesurades cap avall des de la part superior de l'encapçalament (la part superior de l'àrea de contingut en una obertura que comença la seva pàgina):

1. el mateix text de l'encapçalament, amb la tipografia del nivell (queda ocult sota el disseny, però conserva les seves línies);
2. el fons del contingut del disseny: la vora inferior més baixa entre els elements que compten (vegeu més avall);
3. advancedDesign.minHeight.

A continuació s'hi suma el marginBottom de l'encapçalament (el del seu estil d'encapçalament, el del seu nivell o headings.marginBottom; 0,5 em si cap no en fixa un altre) i el resultat s'ajusta cap amunt a la retícula de base quan els encapçalaments s'hi ajusten. En una obertura (span: 'page') la mateixa franja queda lliure a totes les columnes de la pàgina. En un encapçalament de columna que no la desborda, el disseny es compon dins de la caixa de l'encapçalament, que té exactament aquesta alçada.

Quins elements compten. Compten tots els elements del disseny —textos, filets, caixes i imatges per igual (fins a postext 1.4 un element image no comptava mai, de manera que el text podia començar damunt d'una imatge de banda si minHeight no ho impedia)—, excepte:

• els que tenen reserve: false: decoració que pot quedar sota el text;
• els que segueixen la mateixa franja: els ancorats a la fila central del contenidor (left, center, right) o a la inferior (bottom-left, bottom, bottom-right), els que tenen una alçada 'fill' respecte al contenidor (una caixa o una línia vertical sense alçada l'omplen per defecte) i qualsevol element ancorat a un d'ells. El contenidor és la franja reservada, així que aquests elements es recolzen al seu peu o l'abasten: una línia sota la franja, un plafó de color darrere del títol. Segueixen l'alçada; mai no la fixen. Un text d'entre ells que conserva la seva pròpia alçada sí que necessita lloc: un títol ancorat al peu de la franja fa que la franja mesuri almenys el que fa el títol, de manera que mai no comença per damunt de la vora superior de l'encapçalament. Amb minHeight: 36mm i el títol ancorat a bottom-left, la caixa de l'encapçalament fa 36 mm més el seu marginBottom, ajustada cap amunt a la retícula, i el títol queda al peu d'aquesta caixa, just damunt del text que segueix; sense minHeight, un títol que ocupa més línies que el text del mateix encapçalament fa la franja tan alta com el títol. Fins a postext 1.4 aquest títol es pintava cap amunt, damunt del text que precedeix l'encapçalament. Les caixes, els filets i les imatges que segueixen la franja no fixen aquest mínim, així que un plafó ancorat al peu pot sobresortir per damunt de l'encapçalament.

Els elements ancorats a la pàgina o a la sang compten segons quant baixin per sota de la part superior de l'encapçalament. Una banda al capdamunt de la pàgina que acaba per damunt de l'encapçalament no compta gens; una imatge a sang que el sobrepassa empeny el text fins a la seva vora inferior. El mateix passa amb tot el que és a baix de la pàgina: un segell a 25 mm del peu, una banda lateral a tota alçada o un marc reserven la pàgina fins a la seva vora inferior, i el text sol començar a la pàgina següent. Marca aquesta decoració amb reserve: false —es continua pintant i altres elements s'hi poden continuar ancorant— i dona a l'encapçalament l'espai que necessita amb els seus elements de text o amb 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" } }
  }
}

Un element ancorat a un altre que no reserva continua comptant tret que també el marquis (un rètol compost damunt del segell necessita el seu propi reserve: false).

On es pinta. El disseny d'una obertura (span: 'page') es dibuixa abans que el cos, així que la decoració que no reserva espai queda sota el text. El disseny d'un encapçalament de columna es dibuixa amb el bloc de l'encapçalament —damunt dels blocs que el precedeixen a la columna i sota dels que el segueixen— allà on estigui col·locat per damunt del peu de la seva columna: també als marges laterals, al marge superior, a la sang i a les columnes veïnes. El peu de la columna el talla, al llenç i al PDF, perquè allà acaba el flux (vegeu Més alt que la columna més avall). Fins a postext 1.4 el llenç i el PDF també el tallaven a la part alta de la seva columna, de manera que una banda ancorada a la part alta de la pàgina o de la sang entrava als marges laterals però s'aturava al marge superior. La decoració ancorada al peu de la pàgina va en una obertura, o al disseny del peu amb pages: 'opener'.

Més alt que la columna. Quan l'espai arriba més enllà del peu de la columna —un minHeight tan alt com la pàgina, una imatge o un marc que baixen fins al tall—, l'encapçalament reclama la resta de la seva pàgina (una obertura, a totes les seves columnes) o de la seva columna (un encapçalament de columna), i el text que el segueix comença a la pàgina o a la columna següent. El seu bloc arriba llavors fins al peu de la columna, sense retallar-se mai a l'alçada del seu text, de manera que la banda contra la qual es compon el seu disseny és l'espai que reclama (minHeight inclòs, fins al peu). Un disseny més alt que la mateixa pàgina —una entradeta llarga en una pàgina de pantalla petita— continua tallant-se al peu de la pàgina (un disseny de columna, al de la seva columna): el Sandbox ho assenyala al tauler Revisió com a Disseny de títol tallat. La maquetació no emet cap avís per això —una portada que reclama la seva pàgina és el més habitual i no perd res—, però qualsevol amfitrió pot fer la mateixa comprovació sobre la maquetació acabada: collectHeadingDesignCuts(doc) retorna un { kind: 'headingDesignCut', pageIndex, level, where, overflowPx, sourceStart, sourceEnd } per cada encapçalament el text de disseny del qual queda més enllà del peu del tall de la pàgina (where: 'page', una obertura) o de la seva columna (where: 'column'), i formatWarning en descriu cadascun. Vegeu Una obertura tan alta com la pàgina a Span i disseny avançat.

La columna lateral. En una disposició de columna i mitja la columna lateral de la qual acull flotants (sideColumnRole: 'floats'), un element del disseny d'un encapçalament de columna que cau a la columna lateral —un numeral de capítol ancorat a la pàgina a la columna del marge exterior, a l'obertura d'un llibre de text— manté la pila lateral apartada. Cada figura, taula o requadre amb span: 'side' que la pàgina col·loca després de l'encapçalament deixa un buit de flotant lliure al voltant de cadascun d'aquests elements: es queda on el posa la pila quan hi cap per damunt de l'element i, si no, passa per sota —o espera a la pàgina següent quan la resta de la columna lateral no el pot acollir allà—. Així, un numeral al capdamunt del canal manté tota la pila per sota, mentre que un número de secció penjat al marge al costat d'un encapçalament més avall de la pàgina deixa el capdamunt del canal a les figures que cita la pàgina (la figura marginal continua al capdamunt de la seva pàgina). El que la columna lateral ja acull quan es col·loca l'encapçalament no es mou: una figura apilada abans a la pàgina que arriba fins a l'element de l'encapçalament es queda on és, a sota de l'element; per això, si el disseny té un element a la columna lateral a mitja pàgina, convé citar-ne les figures després de l'encapçalament. Els elements amb reserve: false deixen lliure la columna lateral, igual que deixen lliure el text. Una obertura (span: 'page') no necessita res d'això: la seva banda es reserva a totes les columnes, la lateral inclosa. Fins a postext 1.4 una figura lateral citada en una obertura així es col·locava al capdamunt de la columna lateral, damunt del numeral.

Portades. Per això un encapçalament de portada que omple la seva pàgina —amb un minHeight tan alt com la pàgina, o amb una imatge a pàgina completa al seu disseny— envia tot sol el text que el segueix a la pàgina següent, tant en disposicions d'una columna com de diverses. Un :::pagebreak just darrere és opcional i no fa mal: un salt de pàgina en una pàgina encara buida no fa res, així que mai no afegeix una pàgina en blanc. Només cal quan el disseny de la portada acaba abans del peu de la pàgina i tot i així el text ha de començar en una pàgina nova.

# Memòria anual 2026 {style="portada"}
 
:::pagebreak
 
# Carta de la presidenta

#Nombres en lletres

Dos sufixos de les plantilles de numeració escriuen un comptador en lletres, en la llengua del document (el locale de primer nivell o, si no està definit, la llengua de partició — vegeu Llengua del document): words per al cardinal i ordinal per a l'ordinal. La caixa (majúscula o minúscula) del sufix fixa la de les paraules, com fan A / a amb les lletres:

S'escriuen en lletres l'anglès, l'espanyol, el xinès i l'àrab; qualsevol altra llengua pren les paraules en anglès, com fan les cadenes integrades de continuació de taules. El xinès escriu els numerals informals de simp-chinese-informal o trad-chinese-informal, segons l'escriptura de locale (一万 / 一萬), amb 第 davant de l'ordinal; els caràcters han no tenen caixa, així que les tres grafies d'un sufix imprimeixen el mateix. L'anglès segueix l'ús nord-americà (one hundred five, sense and). L'espanyol fa servir les formes masculines, com es numera un capítulo o un libro (capítulo primero, tercero, veintiuno), i escriu els ordinals del 13 al 29 en una sola paraula, com prefereix la RAE (decimotercero, vigesimoprimero). Els cardinals s'escriuen fins a 999 999 i els ordinals espanyols fins a 999; els nombres més grans s'imprimeixen en xifres.

Els nombres àrabs concorden en gènere amb el substantiu que compten, així que el sufix admet un modificador: -feminine (o -f) per a un substantiu femení, -masculine (-m, el valor per defecte) per a un de masculí; -classical escriu les centenes مائة, com les edicions de Bulaq i la majoria de les egípcies, en lloc del modern مئة. {1:ordinal} escriu l'ordinal definit en nominatiu que fa servir un títol: الفصل {1:ordinal} dona الفصل الأول, الفصل الحادي عشر, الفصل الحادي والعشرون; الليلة {1:ordinal-feminine} dona الليلة الأولى, الليلة الحادية عشرة, الليلة الحادية والعشرون, الليلة المئتان i, per damunt de cent, la fórmula clàssica de «després de»: الليلة الخامسة والأربعون بعد الثلاثمئة, الليلة الحادية بعد الألف. {1:words} escriu el cardinal (واحد وعشرون; en femení إحدى عشرة, واحدة وعشرون). Els ordinals s'escriuen en lletres fins a 9 999 i els cardinals fins a 99 999; els modificadors es combinen ({1:ordinal-f-classical}) i les altres llengües els ignoren. L'àrab no té majúscules, així que la caixa del sufix no canvia res. Els marcadors de disseny {numberWords} i {numberOrdinalWords} escriuen les formes masculines; per a una obertura en femení, posa l'ordinal a la plantilla del nivell i imprimeix-lo amb {number}.

En un disseny d'encapçalament, {numberWords} / {numberWordsLower} i {numberOrdinalWords} / {numberOrdinalWordsLower} escriuen el comptador de l'encapçalament de la mateixa manera, així l'obertura pot dir Capítulo uno mentre l'índex mostra 1. El textTransform: 'uppercase' d'un element de text dona les majúscules:

// Novel·la en espanyol: «CAPÍTULO PRIMERO» damunt del títol, «1.» a l'índex.
{ 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}', /* … */ },
  ] } } }

#Llistes no ordenades

La propietat unorderedLists controla com es renderitzen les llistes amb pics (-, *, +) i les llistes de tasques d'estil GFM (- [ ], - [x]). S'admeten fins a cinc nivells d'imbricació.

#Valors per defecte de les llistes no ordenades

#Extensions per a llistes de tasques

Els elements de tasca GFM (- [ ] …, - [x] …) es renderitzen com a elements de llista no ordenada substituint el pic per una casella. Els camps següents només s'apliquen a les tasques:

#Sobreescriptures per nivell (llistes no ordenades)

Cada entrada de levels apunta a una profunditat (1–5) i pot sobreescriure qualsevol de les propietats següents:

Encadenament de sagnats. El nivell 1 arrenca sempre amb l'indent general (per defecte 0 em — els pics queden enganxats a la vora de la columna). Per als nivells 2–5, si deixes indent sense definir, el motor col·loca el pic a l'inici de text del nivell anterior (sagnat del pare + amplada del pic + gap). Defineix un indent explícit en un nivell per trencar l'encadenament i fixar aquesta profunditat on prefereixis.

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

#Llistes ordenades

La propietat orderedLists controla les llistes numerades (1., 2), etc.). S'admeten fins a cinc nivells d'imbricació i cada profunditat pot fer servir un format de numeració diferent.

#Valors per defecte de les llistes ordenades

#Sobreescriptures per nivell (llistes ordenades)

Cada entrada de levels pot sobreescriure numberFormat, prefix, separator, fontFamily, fontSize, color, fontWeight, italic, indent, verticalOffset i l'estil del separador (separatorFontFamily, separatorFontWeight, separatorItalic, separatorColor, separatorGap) — s'hi aplica el mateix encadenament de sagnats que a les llistes no ordenades. L'estil del separador d'un nivell hereta l'estil del seu propi número, tret que s'indiqui l'opció general del separador.

Alineació a la dreta. El pipeline mesura el número formatat més ample dins de cada tram i sagna tots els elements d'aquest tram perquè els marcadors quedin alineats per la vora dreta. Una llista de deu elements mostrada com 1. – 10. desplaça els números d'una xifra cap a la dreta perquè el separador caigui sempre a la mateixa columna.

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

Això produeix la clàssica combinació niada:

1. Primer element
   a. Subelement
      i) Nota profunda
   b. Subelement
2. Segon element

La jerarquia dels documents xinesos (GB/T 15834—2011, annex B.3) té cinc nivells: 一、, després （一）, després 1., després （1） i després ①:

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àtiques

La propietat math controla com s'analitzen i es mostren les fórmules LaTeX escrites entre delimitadors $...$ (en línia) i $$...$$ (en bloc). El motor subjacent és MathJax (el paquet mathjax-full) en mode de sortida SVG, rasteritzat al canvas i incrustat com a glifs escalables al PDF.

interface MathConfig {
  enabled?: boolean;        // Mostrar el LaTeX. Si és false, els spans surten com a TeX literal.
  fontSizeScale?: number;   // × la mida del text que envolta la fórmula (la del cos en les fórmules en bloc).
  color?: ColorValue;       // Color de la fórmula; hereta el del cos si s'omet.
  marginTop?: Dimension;    // Espai damunt de les fórmules en bloc.
  marginBottom?: Dimension; // Espai mínim a sota; l'ajust a la retícula el pot augmentar.
  indentAfterDisplay?: boolean; // Sagnar el paràgraf que segueix una fórmula en bloc.
  keepWithLeadIn?: boolean; // Mantenir una fórmula en bloc amb la línia que la introdueix.
  equationNumbering?: {      // Numerar les fórmules en bloc que porten un \label.
    enabled?: boolean;           // per defecte true
    numberingTemplate?: string;  // '{n}'; '{h1}.{n}' numera per capítol
    resetOn?: ResourceCounterReset; // 'never' | 'h1' … 'h6'
    counterFormat?: ResourceCounterFormat; // 'decimal'
    format?: string;             // '({n})': el que imprimeixen la fórmula i \eqref
  };
}

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

Mida de les fórmules, canvia a postext 1.5. MathJax dona la caixa de cada fórmula en ex, i un ex de la seva font TeX mesura 0,442 em. Fins a postext 1.4 el motor el prenia per mig em, de manera que cada fórmula es componia al voltant d'un 13 % més gran que bodyText.fontSize × fontSizeScale. Ara les fórmules surten de la mida documentada, i les línies i pàgines amb matemàtiques es recomponen. Una configuració escrita en codi per a la 1.4 conserva la mida de les fórmules de la 1.4 si passa per pinLegacyMathSize, de postext/bundle, una sola vegada i tal com està escrita:

import { pinLegacyMathSize } from 'postext/bundle';
 
config = pinLegacyMathSize(config); // fórmules, i l'espai al voltant de les fórmules en bloc, com les componia la 1.4

Hi ha altres canvis de regles a la 1.5 que també poden moure les teves pàgines: els salts dels encapçalaments, l'espai al voltant d'una figura en línia (en el text corregut i en els requadres), les marques en línia dels encapçalaments, la mida de les caplletres, el lloc que es deixa sota una línia acabada en dos punts per a la llista que introdueix, les línies que el tall d'una caixa deixa d'un paràgraf o d'un element de llista, els salts de línia després d'un guió llarg, la composició del text en bandera, la divisió d'un paràgraf sota un encapçalament, els salts de línia després del guionet d'un compost i l'espai sota un contenidor :::paragraphs. migrateConfig, aplicada una sola vegada amb el markdown que compon la configuració, fixa els que aquest text necessita, també la mida de les fórmules (consulta Paquets escrits per postext 1.4 o anterior):

import { migrateConfig } from 'postext/bundle';
 
config = migrateConfig(config, undefined, { content: markdown }); // salts d'encapçalament, fórmules, espais en línia, marques dels encapçalaments, caplletres, dos punts, talls de les caixes, guions llargs, compostos, text en bandera, divisions sota un encapçalament i espai sota els contenidors com els componia la 1.4

Així s'evita el que moverien aquests canvis de regles, però no es conserven totes les pàgines de la 1.4. La 1.5 corregeix a més errors de composició, i una correcció no té fixació: una configuració antiga la rep igual que una de nova, de manera que una pàgina afectada encara es pot moure. Entre aquestes correccions: un encapçalament a tota la pàgina sense disseny propi es mesura a l'amplada de la pàgina i es compon amb l'interlineat del seu nivell; en un disseny d'encapçalament no es reserva res sota la línia de base d'una caplletra; una caplletra pren el color de la paleta de la secció i es compon també en un text de disseny el overflow del qual no és 'wrap', que llavors salta de línia; un paràgraf dins d'una caixa pinta el tracking amb què es va mesurar; una caixa partida conserva la columna de la icona a cada fragment; una línia d'una caixa que estiraria els espais més de 3× es compon en bandera, com en el text corregut; la palanca dels paràgrafs fluixos no deixa mai una línia justificada més ampla del que permet maxWordSpacing; una caixa flotant conserva un marginBottom (en una banda superior) o un marginTop (en una banda inferior) més gran que l'espai dels flotants; un text de disseny centrat o alineat a la dreta amb tracking (un titolet, el títol d'una obertura) es col·loca per les seves lletres, sense el tracking que segueix l'última; sota una obertura a tota la pàgina, el text que obre la segona columna comença on començaria el text just a sota de l'obertura, també quan l'obertura va seguida d'un encapçalament; la línia de punts de l'índex s'atura abans del número de pàgina en una font el kerning de la qual separa una sèrie de punts; un titolet llegeix l'encapçalament tal com està escrit, sense espai on una de les seves línies acaba després d'un guionet o un guió llarg o dins d'una paraula tallada per l'amplada (MEDIOAMBIENTALES, no MEDIOAMBIENTALE S), i el {titleText} del disseny d'un encapçalament el llegeix igual (thousand-colour, no thousand- colour); un text ancorat al peu o al centre de la franja d'un disseny d'encapçalament manté la franja prou alta per contenir-lo, de manera que ja no puja sobre el text que precedeix l'encapçalament; una paraula més ampla que la seva línia, tallada al costat d'un guionet que ja porta, es talla darrere d'aquest guionet i no en rep cap altre; l'element que segueix una llista niada dins d'una altra pren l'itemSpacing de la seva pròpia llista, no el de la niada; i la resta d'una paraula tallada per ser més ampla que la seva línia conserva els seus propis punts de tall, de manera que una adreça web continua tallant-se per les juntures i un compost pels guionets en lloc de per les síl·labes del diccionari.

pinLegacyMathSize multiplica l'escala per 1,1312 (0,5 ÷ 0,442) i divideix pel mateix factor els marges de les fórmules en bloc en em. Amb l'escala sola no n'hi ha prou en un llibre amb fórmules en bloc: els seus marges són mesures de la mida de la fórmula mateixa, de manera que creixerien el mateix 13 % i empènyerien cap avall el text que les segueix. Escrits per als marges per defecte, els tres valors són:

math: {
  fontSizeScale: 1.131,
  marginTop: { value: 0.7072, unit: 'em' },
  marginBottom: { value: 0.7072, unit: 'em' },
} // fórmules tan grans com les componia la 1.4, amb l'espai que els deixava al voltant

On la configuració estava desada, el motor ho pot saber i ho fa per tu: openBundle / readBundle amb un paquet .postext escrit abans de la 1.5 (consulta Paquets escrits per postext 1.4 o anterior), i el Sandbox amb els llibres, la configuració de treball i els fitxers postext-config.json que va desar llavors (consulta Sandbox → Persistència). Es llegeixen a través de migrateConfig, que fixa la mida (pinLegacyMathSize): fontSizeScale passa a ser l'escala desada (1 si no n'hi havia) × 1,1312, i un marge de les fórmules en bloc en em o rem — una mesura de la mida de la fórmula mateixa — es divideix pel mateix factor, de manera que l'espai al voltant d'una fórmula en bloc queda com el deixava la 1.4 (els 0,8 em per defecte passen a 0,7072 em). Un marge en una unitat de pàgina (pt, mm…) es queda com està, i també una configuració amb enabled: false o una el llibre de la qual no té cap $. Llavors el llibre antic es compon com el componia la 1.4, i la seva secció math mostra la mida amb què es compon. Per compondre aquell llibre a la mida actual, restableix aquests valors: Fórmules → Escala de mida, Marge superior de les fórmules en bloc i Marge inferior de les fórmules en bloc al Sandbox, o en codi:

math: { ...config.math, fontSizeScale: 1, marginTop: undefined, marginBottom: undefined } // mida i marges actuals

Equacions numerades. Una fórmula en bloc amb número ocupa tota la seva mesura (la columna, o l'amplada interior del requadre que la conté): l'equació va centrada i el seu número alineat a la dreta, a la línia de l'equació, a cada fila numerada d'un align. El número surt d'un \label{eq:x} (des de postext 1.19): les fórmules amb etiqueta, i les files amb etiqueta d'un align, gather, alignat, flalign o eqnarray, es numeren en ordre de lectura segons equationNumbering, tret que una fila digui \nonumber o \notag. Entorns com equation no es numeren per si sols: una fórmula sense etiqueta no porta número. \tag{…} imprimeix el text que li donis, entre parèntesis, i \tag*{…}, tal qual; cap dels dos no compta, i un \label al seu costat li dona nom. Una equació numerada més ampla que la seva mesura desborda per la dreta, com qualsevol fórmula en bloc. (Fins a postext 1.4, una fórmula amb \tag no s'arribava a dibuixar; fins a la 1.18, només \tag numerava una fórmula.)

\eqref{eq:x} al text imprimeix el número en el seu format, (3), i \ref{eq:x}, el número sol; el mateix fan :ref{id="eq:x"} i @eq:x (vegeu Referències creuades), i dins d'una fórmula \eqref l'imprimeix com a text. En un llibre compost capítol a capítol, el comptador continua des del capítol anterior: continuationAfter el porta a LayoutContinuation.statementCounters (equation), i l'esquema del llibre dona a cada etiqueta el seu número (OutlineEntry.numberLabel), de manera que una referència a una equació d'un altre capítol l'imprimeix.

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

El resolver i l'stripper segueixen el mateix patró que les altres seccions:

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

#Arrencar el motor de fórmules

MathJax es carrega a demanda, no amb la resta del motor. Quan compons al fil principal, arrenca'l abans de construir un document amb fórmules:

import { buildDocument, initMathEngine, renderPage } from 'postext';
 
await initMathEngine(); // carrega MathJax una vegada; les crides següents es resolen a l'instant
const doc = buildDocument({ markdown: 'Euler: $e^{i\\pi}+1=0$.' }, config);
document.body.append(renderPage(doc.pages[0], doc));

• Fins que el motor arrenca, les fórmules són provisionals. Cadascuna es compon com una caixa grisa de mida estimada. Si un document amb fórmules es compon sense haver cridat mai initMathEngine(), la consola mostra un avís, una sola vegada.
• El worker de composició l'arrenca per tu. Un build a postext/worker crida initMathEngine() pel seu compte quan el markdown conté un $.
• Compondre ja, i un altre cop quan estigui a punt. isMathReady() indica si el motor està en marxa. onMathReady(fn) crida fn tan bon punt ho està (a l'instant si ja ho estava) i retorna una funció que cancel·la la crida. Un editor pot mostrar les caixes provisionals de seguida i tornar a compondre quan arriba MathJax; mentre initMathEngine() està en curs no s'imprimeix cap avís.
• Errors. initMathEngine() es rebutja si MathJax no es pot carregar, i una crida posterior ho torna a intentar.
• Amb qualsevol bundler, a Node o des d'una CDN. MathJax viatja dins del paquet com un únic mòdul preempaquetat (uns 1,8 MB sense comprimir, que només baixa initMathEngine). L'import { initMathEngine } from 'https://esm.sh/postext' de sempre funciona; no cal ?bundle. El paquet mathjax-full només cal per compilar postext, de manera que instal·lar postext no l'instal·la. MathJax i l'analitzador mhchem que inclou tenen llicència Apache-2.0: els seus avisos i el text de la llicència viatgen al costat del mòdul, a dist/math/THIRD_PARTY_LICENSES.txt.
• Un motor per pàgina. El motor i la seva memòria cau de fórmules representades són compartits per tot el que importa postext en el mateix context de JavaScript (consulta Estat global compartit en una pàgina).

Per a la gramàtica del document ($...$, $$...$$, com escapar un dòlar literal), consulta Format del document.