Configuració de Postext

Cada decisió de composició a Postext la controla un únic objecte de configuració.

PostextConfig controla les dimensions de pàgina, la disposició de columnes, la tipografia del text de cos, els estils d'encapçalament, la llengua del document (locale) i més. Totes les propietats són opcionals — Postext inclou valors per defecte assenyats, inspirats en la tipografia tradicional de llibres. Només cal que especifiquis el que vulguis canviar.

import { buildDocument } from 'postext';
 
const document = buildDocument(content, {
  page: { sizePreset: '21x28', dpi: 300 },
  layout: { layoutType: 'double', gutterWidth: { value: 0.5, unit: 'cm' } },
  bodyText: { fontFamily: 'EB Garamond', fontSize: { value: 9, unit: 'pt' } }, // 9 pt sobreescriu el valor per defecte de 8 pt
  headings: { fontFamily: 'Open Sans' },
});

Per a una visió general de com el motor processa aquesta configuració, consulta la pàgina d'Arquitectura.

#Índex

Aquesta referència és llarga. Aquests són els blocs principals:

• Pàgina — mida, marges, retícula de base, marques de tall, enquadernació.
• Disposició — nombre de columnes, espai entre columnes, filets, escriptura vertical.
• Capçaleres i peus — elements de text i de línia per pàgina amb marcadors, paritat i alineació.
• Text de cos — tipografia, partició de mots, vídues i òrfenes.
• Llengua del document — el locale de primer nivell: alternativa per a la partició de mots, tipus de recurs integrats i cadenes de continuació de taules i d'avisos partits, llengua etiquetada en un PDF accessible; les xifres (numerals) i la direcció del text (direction) que se'n desprenen; i les llengües i escriptures que Postext compon. La guia dels llibres de dreta a esquerra és Composició àrab.
• Tipografia de l'Àsia oriental — cjk: les convencions regionals i el tall de línia del text en xinès, japonès i coreà, com s'eixamplen les seves línies justificades, les amplades de la puntuació i la puntuació penjada, l'espai entre xinès i llatí, la retícula de caràcters, els números que van drets en text vertical, i les marques, el ruby i les notes warichu. La guia de tot plegat és Composició xinesa.
• Encapçalaments — valors generals i sobreescriptures H1–H6.
• Llistes no ordenades i Llistes ordenades — vinyetes, numeració, imbricació.
• Matemàtiques — renderització LaTeX, escala, color, marges.
• Tipus de recurs — numeració tipada per a figures, taules i tipus personalitzats.
• Estil de taules (amb estils de taula amb nom) i Estil de peus de recurs — tipografia i decoració de les taules-recurs i els seus peus.
• Estil de diagrames — recoloració a una sola tinta dels diagrames SVG incrustats per a impressió amb tinta plana.
• Estils de paràgraf — estils amb nom per a contenidors :::paragraphs: bibliografies, glossaris, notes.
• Estils d'avís — notes, consells i objectius en caixa per a contenidors :::callout.
• Parts — pàgines separadores de part per a contenidors :::part: paritat, àrea de cos, disseny d'obertura, tipografia del cos.
• Estils d'encapçalament — estils amb nom per a encapçalaments {style="…"}: capítols sense numerar, preliminars amb capçaleres pròpies, geometria i paleta.
• Sumari — el que imprimeix :::toc: tipografia de les entrades, línies de punts, números de pàgina, línies d'autors, files de part.
• Índex analític — el que imprimeix :::index: tipografia de les entrades, sagnats, separadors i intervals de pàgines, grups per inicial, llengua d'ordenació.
• Unitats i colors + Paleta de colors — Dimension, ColorValue, colors amb nom.
• Fonts personalitzades — declarar famílies tipogràfiques pujades per l'usuari al costat de Google Fonts.
• Visor HTML — amplada objectiu de columna i talls per al backend HTML.
• Generació de PDF (configuració) — outlines, sortida accessible (etiquetada) i espai de color forçat per al backend PDF.
• Visor Folio (configuració) — paper, enquadernació, superfície i llum del visor del llibre en 3D.
• Depuració — superposicions visuals i avisos d'autoria per a l'editor.
• Ús programàtic — buildDocument, els avisos que registra, resolvers, memòries cau.
• Executar la composició en un Web Worker — builds fora del fil principal amb cancel·lació.
• Integrar el visor HTML i Generació de PDF — receptes completes.
• Llibres EPUB — fitxers EPUB 3 de maquetació fixa i fluida a partir de la mateixa maquetació, i com comprovar-los amb EPUBCheck.

#Pàgina

La propietat page controla les dimensions físiques i l'aparença de la pàgina.

#Marges simètrics (mirall)

Els llibres es llegeixen per plecs, i el marge interior sol ser diferent de l'exterior. margins.mirror converteix els quatre marges en marges de pàgines enfrontades:

{
  "page": {
    "margins": {
      "top": { "value": 2, "unit": "cm" },
      "bottom": { "value": 2.5, "unit": "cm" },
      "left": { "value": 2.2, "unit": "cm" },
      "right": { "value": 1.4, "unit": "cm" },
      "mirror": true
    }
  }
}

Amb aquesta configuració tota pàgina senar té 2,2 cm de marge a l'esquerra (el llom) i 1,4 cm a la dreta (el tall davanter); tota pàgina parella té 1,4 cm a l'esquerra (el tall davanter) i 2,2 cm a la dreta (el llom). Cada pàgina composta porta el seu propi contentArea a la VDTPage, així que tot el que se'n deriva — columnes, bandes de flotants a tota l'amplada, contenidors de capçalera i peu, i bandes d'obertura amb span: 'page' — segueix automàticament la geometria emmirallada. Els marcs de pàgina i de sang que fan servir els elements de disseny ancorats a 'page' / 'bleed' no se'n veuen afectats: descriuen el plec físic, no els marges.

#Enquadernació

«Els documents xinesos compostos en vertical s'enquadernen pel costat dret, i els compostos en horitzontal per l'esquerre» (clreq §7.1.1.1). page.binding: 'right' compon un llibre per a la vora dreta:

• La pàgina 1 continua sent senar i continua sent la pàgina senar del plec (recto), així que breakBefore.parity, :::pagebreak{parity}, els elements de disseny amb parity i el recompte de pàgines conserven el seu sentit. El que canvia és el costat on queda la senar: la pàgina esquerra del plec. Un capítol que comença en senar comença en una pàgina esquerra (clreq §7.1.3.3).
• Amb margins.mirror, left continua sent el marge interior, però són les pàgines senars les que el canvien de costat: la pàgina 1 té el marge interior a la seva dreta i la 2 a la seva esquerra. La columna lateral de oneAndHalf en 'outer' / 'inner', el flotant girat que es recolza al llom, els marges de les pàgines de part i les icones de cantonada 'outer' / 'inner' de les caixes segueixen la mateixa regla.
• El document ho indica (VDTDocument.binding: 'right'), de manera que qui el mostra no ha de llegir la configuració: el Sandbox ensenya els plecs com [3 | 2], amb la pàgina 1 sola a l'esquerra del llom, i el seu visor HTML ordena les pàgines de dreta a esquerra, s'obre per l'extrem dret i la fletxa esquerra passa a la pàgina següent. renderToHtml en mode múltiple ordena la fila de dreta a esquerra.
• El PDF porta /ViewerPreferences << /Direction /R2L >> i /PageLayout /TwoPageRight (la pàgina 1 sola i després per parells), etiquetat o no. Acrobat i Foxit els respecten; el visor integrat de Chrome no fa cas de cap dels dos.

Els folis i les capçaleres no canvien de costat per si sols: una plantilla que posa el número de pàgina a la cantonada exterior necessita els seus elements de pàgina parella i senar preparats per a la vora dreta (els elements admeten parity).

Un llibre escrit de dreta a esquerra (àrab, persa, hebreu…) també s'enquaderna per la dreta: 'auto' dona la vora dreta quan la direction del document resulta 'rtl'. Un llibre així emmiralla a més tot el seu flux: la primera columna és la de la dreta, i els sagnats, els marcadors de llista, els flotants i les notes queden a la dreta; les ranures de capçalera i peu continuen sent físiques. Vegeu Composició àrab.

#Mides de pàgina predefinides

#Retícula de base

La retícula de base és el ritme del text de cos: línies separades per l'interlineat del cos, comptades des de la vora superior de l'àrea de contingut. La maquetació la fa servir tant si es dibuixa com si no: els encapçalaments, els finals de llista, els requadres, les figures i les fórmules en bloc tornen el text a la retícula (llevat que el seu propi snapToGrid estigui desactivat), de manera que les línies de columnes veïnes queden alineades. enabled només dibuixa les línies, al llenç, al PDF i a les vistes del Sandbox, per comprovar aquest ritme; activar-la o desactivar-la no mou res. Les línies cobreixen només el text real de la pàgina — des de la primera línia de text fins a l'última — de manera que les bandes de flotants, les pàgines en blanc per paritat i l'espai sobrant al final no mostren retícula.

page: {
  baselineGrid: { enabled: true, color: { hex: '#e0e0e0', model: 'hex' } }
}

#Marques de tall

En activar-se, el llenç s'expandeix per incloure una zona de sang i el motor dibuixa marques de tall a cada cantonada per a producció impresa.

El plec creix bleed + markOffset + markLength per cada costat, i la pàgina tallada queda al centre. Cada cantonada del tall porta dues marques de markLength de llarg, cadascuna a la prolongació d'una de les vores que s'hi troben. Una marca comença a markOffset del tall, o a la vora de la sang si bleed és el més gran dels dos, de manera que cap marca no cau sobre una imatge que s'estén fins a la sang. Amb els valors per defecte (3 mm de sang i 3 mm de separació), les marques van de 3 a 8 mm fora del tall, i per fora d'elles queda una franja en blanc de 3 mm al voltant del plec. cropMarkSegments(page, doc.config.page, doc.trimOffset) retorna les vuit marques d'una pàgina en píxels, les mateixes que dibuixen el canvas i el PDF. El tercer argument és la distància a què queda el tall dins del plec, el valor amb què s'escriu el TrimBox del PDF; si falta, es calcula a partir de cutLines de la mateixa manera.

Fora de la sang només s'imprimeixen les marques. Tot el que pinta la pàgina, inclosos els elements de disseny ancorats a 'page' o a 'bleed', es retalla a la caixa de sang al canvas, al PDF i a la sortida HTML, com ho retalla una exportació de maquetació: una banda o una imatge que surt de la sang a propòsit es talla a la vora de la sang, on la guillotina la perdria de tota manera. Fins a postext 1.4 un element així continuava per damunt de les marques fins a la vora del plec.

Al PDF (postext-pdf), la MediaBox de cada pàgina és el plec sencer. La pàgina porta a més una TrimBox, la pàgina tallada, i una BleedBox, el tall més la sang, que llegeixen les eines d'imposició i de preflight. Quan el PDF s'escriu en CMYK (colorSpace: 'cmyk', o pdfGeneration.forceColorSpace amb colorSpace: 'cmyk'), les marques es pinten en color de registre, la separació /All, i s'imprimeixen en totes les planxes. Els PDF en RGB i en escala de grisos les pinten en color.

#Numeració

El bloc page.pageNumbering controla com es formaten les etiquetes de pàgina i on comença el comptador. Defineix únicament el valor per defecte de tot el document — per reiniciar la numeració al mig del document (per exemple, números romans a les pàgines preliminars que passen a decimal des d'1 als capítols), fes servir la directiva :::numbering (consulta Format del document → Directives).

L'etiqueta calculada s'emmagatzema a cada VDTPage com a pageLabel i és el valor que resol el marcador {pageNumber} a capçaleres i peus. Els PDF emeten un arbre /PageLabels de manera que l'indicador de pàgina i la navegació «Vés a la pàgina» de Preview / Acrobat coincideixen exactament amb les etiquetes impreses. Un estil sense codi en PDF (els numerals xinesos, les xifres en cercle i les d'amplada completa) s'escriu pàgina a pàgina, de manera que el lector mostra també 一, 二, 三.

Grafies dels formats de numeració

Tres paràmetres trien un format de numeració, i cadascun va créixer amb la seva pròpia grafia: les etiquetes de pàgina (page.pageNumbering.format i :::numbering{format=…}) diuen lower-roman, les llistes numerades (orderedLists.numberFormat) diuen arabic per al decimal i els tipus de recurs (counterFormat) diuen roman-lower. Tots accepten totes les grafies de la taula, així que un format copiat d'un paràmetre funciona en els altres. Els noms no distingeixen majúscules; les formes d'un sol caràcter sí (i i I són diferents).

Els estils de l'Àsia oriental conserven el seu nom de CSS Counter Styles en els tres paràmetres. Els numerals xinesos informals escriuen 十 del 10 al 19 sense un 一 al davant (十二, però 一百一十), un sol 零 per cada tram de zeros dins del número (一百零一, 一千零五十), i 万 o 萬 per a la desena de miler, 亿 o 億 per als cent milions (一万零一十). Només cjk-decimal fa servir 〇, xifra a xifra, com s'escriuen els anys (二〇二六, GB/T 15835—2011). Els troncs arriben al 10, les branques al 12 i les xifres en cercle al 50; més enllà, el número s'imprimeix en xifres. 一 i 壹 segueixen l'escriptura del locale del document: tradicional per a zh-Hant, zh-TW o zh-HK, simplificada en els altres casos. Algunes edicions antigues escriuen 101 com 一百一, sense 零; Postext no imprimeix aquesta forma.

Els estils àrabs conserven el nom CSS quan n'hi ha (arabic-indic, persian; urdu i maghrebi-abjad, de la nota del W3C Ready-made Counter Styles, es llegeixen com persian i arabic-abjad-maghrebi). arabic manté el sentit de sempre: les xifres europees. arabic-abjad escriu els numerals abjad additius de l'àrab clàssic i de la foliació de manuscrits, el valor més gran primer: 11 és يا, 1446 غتمو, i el nombre de milers va abans de غ (2000 بغ, 1002 غب); a partir de 999 999 el número s'imprimeix en xifres. La nota del W3C fa servir aquest nom per a una sèrie de 28 lletres en què 11 és ك; Postext anomena aquesta sèrie abjad, la que lletreja els elements de llista en ordre abjad (أ، ب، ج، د، هـ), i hijai l'ordre alfabètic (أ، ب، ت، ث). Totes dues escriuen la primera lletra amb la seva hamza (أ) i una he que quedaria aïllada com هـ, amb tatweel, perquè no es llegeixin com les xifres ١ i ٥; passades les 28 lletres es dupliquen, com lower-alpha (أأ, أب). Els valors magribins segueixen la regla mnemotècnica صعفض قرست ثخذ ظغش (ص 60, ض 90); la llista del W3C intercanvia ص i ض. Una sola أ no distingeix les dues sèries de lletres, així que el seu token són les seves quatre primeres lletres: {1:أبجد}, {1:أبتث}. Les xifres del document mateix es trien amb numerals.

Les altres grafies són per a les configuracions que res no comprova en tipus: els presets en JSON i el JavaScript sense tipus. Els tipus de TypeScript continuen anomenant només la grafia pròpia de cada paràmetre —la que escriu el Sandbox i retorna resolveAllConfig, amb els noms de l'Àsia oriental inclosos—, així que un PostextConfig tipat s'hi cenyeix, i una altra grafia necessita una conversió de tipus (cast).

// JavaScript o un preset en JSON (en TypeScript, la grafia pròpia de cada paràmetre)
orderedLists: { numberFormat: 'decimal' },          // igual que 'arabic'
page: { pageNumbering: { format: 'roman-lower' } }, // igual que 'lower-roman'
resourceTypes: [{ id: 'lamina', counterFormat: 'upper-roman', … }], // igual que 'roman-upper'

resolveAllConfig porta els formats de llistes i de pàgina a la grafia del seu propi paràmetre —'decimal' es resol com a 'arabic' a orderedLists, 'roman-lower' com a 'lower-roman' a page.pageNumbering— i stripConfigDefaults elimina qualsevol grafia del valor per defecte. Els taulers del Sandbox mostren cadascun dels tres paràmetres en la seva pròpia grafia, sigui quina sigui la que faci servir la configuració. Qualsevol altre valor —roman, 01, una errada— numera en decimal en lloc d'imprimir undefined, i es notifica com a avís de configuració. Les plantilles de numeració dels encapçalaments accepten els mateixos noms després dels dos punts ({1:roman-upper} equival a {1:I}), al costat del seu propi {1:01} amb zero a l'esquerra.

#Disposició

La propietat layout controla com s'organitzen les columnes dins de l'àrea de contingut.

#Escriptura vertical

Amb writingMode: 'vertical-rl' una pàgina es compon com una pàgina horitzontal girada un quart de volta en el sentit de les agulles del rellotge. El flux es compon en un marc tan ample com alt és el plec; les seves línies són les columnes del text vertical, que es llegeixen des de la dreta, i tot el que el motor fa amb les línies (talls, justificació, flotants, notes a peu de pàgina, regles de cohesió) funciona en aquest marc. Al plec, per tant:

• Una columna de la disposició és un pis (栏): layoutType: 'double' dona dos pisos apilats de dalt a baix, que s'omplen des de la cantonada superior dreta; gutterWidth és el buit entre ells i el filet de columna, una línia horitzontal entre tots dos. Els pisos no s'igualen al final d'un capítol (clreq §7.1.3.4): l'equilibri de columnes està desactivat en un document vertical tret que es fixi headings.balancing.enabled.
• El que el flux anomena «dalt» és la vora dreta del plec, on comença la lectura: un flotant superior queda a la dreta de la pàgina, un d'inferior a l'esquerra, una obertura a tota la pàgina és una franja al llarg de la vora dreta i les notes a peu de pàgina cauen a l'extrem esquerre de cada pis. Un element de disseny ancorat a la part superior de la pàgina (un disseny de títol, una caixa fixa) s'ancora a la vora dreta. A sideColumnSide, 'left' és el pis de dalt i 'right' el de baix; 'outer' i 'inner' valen com 'right' i 'left'.
• Els marges del flux són els del plec girats: el marge dret és la part superior del flux i el superior, la seva esquerra. page.margins conserven els seus noms al plec.
• Els encapçalaments, els folis, les marques de tall i el fons de pàgina continuen al plec, en horitzontal, com descriu clreq per als llibres verticals.
• Les figures i les taules es mantenen dretes. Una figura ocupa l'alçada del seu pis fins on ho permet el seu peu, i com a molt l'amplada de la pàgina; l'amplada que pren és l'espai que ocupa en el flux. El seu peu es compon en horitzontal sota seu, igual que les cel·les d'una taula: tots dos es mesuren com a text horitzontal. Una taula es compon dreta a l'amplada de la pàgina i, si és més alta que el pis, les seves files es reparteixen entre pisos. placement.align col·loca la figura a dalt ('left'), al mig o al peu del seu pis. Un placement.rotate no s'aplica quan la figura se cita per primer cop en text vertical: la composició n'avisa amb rotateIgnoredVertical. Una secció horitzontal del llibre (un estil de títol el layout del qual fixa 'horizontal-tb') gira les seves figures tal com se li demana.
• Les imatges d'un disseny (la il·lustració d'una obertura o d'una pàgina de part) també queden dretes. La seva caixa en el flux es dimensiona amb l'amplada i l'alçada de la imatge intercanviades, de manera que size.width és el que la imatge ocupa al llarg de la columna, i la seva amplada al plec surt de les seves proporcions.
• Caràcters: els hanzi, els kana i les formes d'amplada completa queden drets, a un quadratí cadascun; les paraules llatines i els números s'ajeuen amb la seva amplada horitzontal; la puntuació pren la forma vertical de la font. Els signes de pausa i de final no es giren mai: una font de la Xina continental posa 、。，． a la cantonada superior dreta de la cel·la i ！？：； a la seva meitat dreta, i una de Taiwan o Hong Kong els centra (cjk.region). Els parèntesis i les cometes prenen la seva forma vertical, i “ ” ‘ ’ es llegeixen com a 『』「」 en text de la Xina continental. Els guions llargs, els punts suspensius i la titlla d'ona prenen la forma vertical de la font quan en té (Noto CJK lliga la de — a vert juntament amb fwid: un filet pel centre de la cel·la); si no, es giren amb la tinta centrada en l'eix de la columna. El 破折号 (——) d'un text xinès és un sol filet al llarg de la columna: les seves formes verticals deixarien blanc als dos extrems de cada cel·la, així que cada guió es gira amb la línia i s'estira com en el text horitzontal (vegeu Amplades de la puntuació). Un número de dues xifres com a molt queda dret en una sola cel·la, excepte dins d'una frase llatina, les paraules de la qual segueix (vegeu Números en text vertical). El punt volat (·) ocupa mitja cel·la en text de la Xina continental i una cel·la sencera en el de Taiwan i Hong Kong. Els signes que Unicode posa drets (× © ± § ℃ ① i semblants) ocupen una cel·la pròpia, també dins d'un número: 3×4 són el 3 i el 4 ajaguts amb el × dret entre ells. Un apòstrof o un punt volat entre dues lletres d'una paraula llatina (don’t, l·l) continua a la paraula, ajagut. Un paràgraf llatí dins d'un flux vertical segueix les mateixes regles. Les fórmules en línia, les fitxes i les mostres de color s'ajeuen amb la línia.
• Cada caràcter es mesura tal com es pinta: una cel·la avança la seva cel·la al llarg de la línia, un tram ajagut la seva amplada horitzontal. El text que queda horitzontal al plec (titolets, folis, peus, cel·les de taula) es mesura en horitzontal.
• Les amplades de la puntuació, la puntuació penjada i l'espai entre xinès i llatí s'apliquen al llarg de la línia vertical igual que en l'horitzontal. El blanc que va davant d'un dibuix queda a sobre i el que va darrere, a sota: un 、 kaiming ocupa mitja cel·la, 」「 es comprimeixen a cel·la i mitja, un parèntesi d'obertura retallat al cap d'una línia comença mitja cel·la més amunt, un 。 penjat queda sota el peu de la seva línia, i l'espai entre xinès i llatí és un quart de quadratí de columna damunt i sota d'una paraula ajaguda. ：；？！ conserven la cel·la sencera en text vertical a totes les regions.
• La retícula de caràcters compta els caràcters al llarg de la línia i les línies a l'amplada de la pàgina: charsPerLine fixa el que mesura un pis, linesPerPage quantes línies porta una pàgina, i layoutType: 'double' dona dos pisos de caràcters sencers amb un espai entre columnes de quadratins sencers entre ells.

Per a qui llegeix la composició: una pàgina vertical porta VDTPage.flow. El seu contentArea, les seves columnes, blocs, línies, flotants, àrees de notes, banda d'obertura i superposicions de disseny dels blocs són en coordenades del flux; width, height, header i footer són al plec. flowToPage, pageToFlow, flowRectToPage i pageRectToFlow passen de les unes a les altres, i verticalOrientation(char, region) diu com queda un caràcter. flow.centralBaselines dona, per família tipogràfica, l'eix sobre el qual la composició ha centrat els caràcters drets: el centre de la tinta de 中, el traç llarg del qual ocupa l'alçada del quadratí (0,38 quadratins sobre la línia de base a Noto Serif i Noto Sans, SC i TC per igual), i que tenen totes les fonts xineses, japoneses i coreanes. Cada línia es centra en aquest eix: la línia de base d'una línia vertical queda, des de la vora de la seva caixa, a la meitat del seu interlineat més la línia de base central de la família (la d'una línia horitzontal, a 0,8 de l'interlineat), així que una columna de caràcters queda al centre del seu pas i un filet traçat entre dues columnes a un pas sencer cau a mig camí entre elles. Un text de disseny vertical es compon igual en les seves pròpies línies. El canvas pinta la pàgina vertical pel seu compte; per pintar la puntuació amb les formes verticals pròpies de la font, un amfitrió al navegador carrega, una vegada per família, una font bessona amb aquestes formes activades: loadVerticalAlternates(family, faces), on faces són els orígens de la família (URL o bytes) i els seus descriptors. La bessona només es queda si el navegador aplica la funció al text del canvas (Chrome 140 i posteriors): dibuixa 「（《 amb la bessona i amb una còpia de les mateixes fonts carregada sense la funció, en el pes i l'estil de les fonts rebudes, i es queda amb la bessona quan la tinta és diferent. Una crida posterior amb altres fonts d'una família la bessona de la qual ja és en ús (la negreta després de la rodona) les hi afegeix. El Sandbox ho fa amb totes les famílies d'un document vertical. Sense bessona, els parèntesis es giren sobre el centre del seu quadratí i els signes de pausa i de final de la Xina continental es desplacen dins de la seva cel·la allà on els posen les formes verticals de la font: 、。，． a la cantonada superior dreta (a menys de 0,07 quadratins de les formes verticals de Noto Serif SC) i ！？：； mig quadratí a la dreta i una mica cap amunt (a menys de 0,02). El PDF i l'HTML componen la mateixa pàgina: vegeu Text vertical al PDF i la taula d'En què es diferencia la sortida HTML del canvas i del PDF. Comparats cel·la a cel·la amb HarfBuzz (composició vertical amb vert) a Noto Serif TC i SC, tots els caràcters de 「賈雨村」云云，宜乎？故曰！；：、。“引”‘單’…… queden a menys de 0,02 quadratins d'aquest al canvas i al PDF, i a menys de 0,05 a l'HTML (Chrome centra un glif girat al mig de l'ascendent i el descendent de la font, que a Noto queda 0,05 quadratins per sobre del centre del quadratí). flow.dashAdvances dona, per família, l'avanç horitzontal en quadratins de cada guió que la pàgina estira fins a omplir la seva cel·la (— – ― ⸺ ⸻ －), per a qui pinta sense mètriques de font pròpies: l'HTML estira el guió amb aquest valor, com el canvas i el PDF ho fan amb les seves. Les capçaleres i els folis també poden anar en vertical: vegeu Elements de text verticals.

#Filet de columna

Dibuixa una línia vertical fina a l'espai entre columnes per separar visualment les columnes.

Sota un encapçalament de pàgina completa (span: 'page'), el filet comença on comença el text de les columnes, sota la banda de l'encapçalament, tant si la pinta l'obertura per defecte com un disseny propi. Fins a postext 1.4 baixava des del principi de la caixa de text, travessant la banda.

Un estil d'encapçalament pot fixar el seu propi filet al seu layout (vegeu Estils d'encapçalament), i les pàgines de la seva secció dibuixen aquest. Un camp que l'estil deixa sense fixar pren el valor del document, així que una secció que només canvia les columnes conserva el filet del document. Fins a postext 1.4 el filet d'un estil no es dibuixava mai: totes les pàgines dibuixaven el del document.

#Tipus de disposició

• 'single' — Una columna que ocupa tota l'amplada del contingut. Ideal per a pàgines estretes o contingut amb paràgrafs llargs.

• 'double' — Dues columnes d'igual amplada. La disposició editorial clàssica — manté l'amplada de línia en el rang òptim de 40–50 caràcters per a una lectura còmoda.

• 'oneAndHalf' — Una disposició asimètrica amb una columna principal i una columna lateral més estreta. La columna lateral (controlada per sideColumnPercent) és ideal per a notes al marge, figures petites o contingut complementari. Els valors entre el 25–40% funcionen bé, i un canal estret per numerar línies o posar marques al marge ocupa al voltant del 10–15%. La columna lateral ocupa el sideColumnPercent % de l'amplada de l'àrea de contingut i la principal, el que queda després de l'espai entre columnes — així, amb el 50% la lateral és un espai entre columnes més ampla que la principal. Qualsevol valor es compon tal qual mentre les dues columnes conservin com a mínim l'1% de l'amplada de l'àrea de contingut; un que en deixaria alguna més estreta — 0 o menys, o un de tan gran que la principal desapareix després de l'espai entre columnes — s'ajusta al valor més proper que respecti totes dues, i un valor que no és un nombre pren el valor per defecte, 33. Els configWarnings del document porten llavors { kind: 'sideColumnPercentClamped', path: 'layout.sideColumnPercent', value, used } — la ruta del layout propi d'un estil d'encapçalament anomena l'estil, com a headingStyles[2].layout.sideColumnPercent, i es mesura amb els marges d'aquest estil —, que el Sandbox mostra al tauler Revisió; collectConfigWarnings(config) retorna la mateixa llista sense compondre res. Una disposició que no és 'oneAndHalf' no llegeix el valor, i tampoc no n'avisa. Amb sideColumnRole: 'floats' el text corregut no entra mai a la columna lateral: es converteix en un canal per a les figures, taules i requadres col·locats amb span: 'side'. Una figura o taula lateral s'apila des del cap del canal a la pàgina que la cita per primer cop: la figura marginal d'un llibre de text queda a dalt de tot de la seva pàgina encara que el text la citi més avall, i si no cap en el que queda del canal espera al de la pàgina següent. Un requadre lateral s'apila al costat del text que interromp; si la resta del canal no el pot allotjar allà, puja a la posició més baixa on hi cap (el seu peu al peu del canal) o espera a la pàgina següent. Quan el text que segueix la tanca d'un requadre continua a la pàgina següent (la columna és plena, o les regles de tall porten aquest text més enllà), el requadre es queda a la seva tanca, al costat del text anterior; un estil amb sideAtColumnEnd: 'after' el posa en canvi a l'altura de la primera línia del text que segueix la tanca, al canal de la pàgina següent, com necessiten els números de línia i els titolets marginals escrits abans de la seva línia. Un element del disseny d'un encapçalament que cau al canal —un numeral de capítol ancorat al marge exterior— també queda fora de la pila (vegeu Alçada reservada). Els flotants i requadres span: 'page' continuen creuant totes dues columnes, i un flotant de columna amb placement.captionSide posa el seu peu al canal, a l'altura de la figura. Combinada amb marges emmirallats i sideColumnSide: 'outer', el canal queda a la vora exterior de cada pàgina — la columna marginal d'un manual.

#Capçaleres i peus

Les propietats header i footer controlen els blocs de capçalera i peu de pàgina. Les capçaleres i els peus es dibuixen dins dels marges de pàgina existents — no reserven espai addicional ni redueixen l'àrea de contingut.

Marc del contenidor. Un element ancorat a 'container' es col·loca a la franja de marge entre el cos i la vora de tall, amb l'amplada de l'àrea de contingut. El contenidor de la capçalera va des de la vora superior de tall fins a la part superior del cos; el del peu, des de la part inferior del cos fins a la vora inferior de tall. Així, els ancoratges top-* de la capçalera i bottom-* del peu es mesuren des de la vora de tall, mentre que els bottom-* de la capçalera i top-* del peu es mesuren des de la vora del cos. El contenidor no inclou mai la zona de sang ni la franja de les marques de tall, de manera que una capçalera o un peu queda a la mateixa posició a la pàgina tallada tant si page.cutLines està activat com si no. Ancora a 'page' (la caixa de tall) o a 'bleed' per sortir de l'amplada de l'àrea de contingut o arribar a la zona de sang.

Els blocs utilitzen el model unificat de ranura de disseny: cada element defineix un placement amb un anchor (al contenidor o a un altre element per #id), un offset opcional i un size opcional. Els camps plans heretats align, marginFromBody, marginFromEdge i width: 'full' continuen acceptant-se com a entrada i es migren automàticament al format nou; a sota es documenta l'equivalència.

Cada bloc conté una llista d'elements de text, línia (rule) i caixa (box). L'ordre de l'array és l'ordre de pintura (el primer element es pinta primer, l'últim es pinta a sobre). Això es compleix siguin quins siguin els ancoratges: un element es pot ancorar a un altre que apareix després a la llista (anchor.to: '#ttl'), de manera que una caixa de fons pot anar primer i col·locar-se respecte al text que es pinta a sobre seu.

Valors per defecte inclosos. Quan header o footer són undefined, postext aplica un valor per defecte raonable en lloc d'un bloc buit:

• Capçalera per defecte: {title} alineat a la dreta a les pàgines senars, {chapterTitle} alineat a l'esquerra a les pàgines parelles i una línia a tota l'amplada — tots en el color principal de la paleta, Open Sans 8pt/600, marginFromBody 16pt (text) / 13pt (línia).
• Peu per defecte: {pageNumber} centrat a totes les pàgines en el color principal de la paleta, Open Sans 8pt/600, marginFromBody 16pt.

Per renunciar als valors per defecte, estableix header: { elements: [] } (o footer: { elements: [] }). Un array elements buit explícit es conserva com a «sense elements» — només undefined activa els valors per defecte.

#Elements de text

Els elements de text renderitzen una plantilla amb substitució de marcadors. Els marcadors fan servir la sintaxi {nombre}; {{ i }} s'emeten com a claus literals.

Els valors per defecte de la taula següent són els d'un element de text que afegeixes tu. La capçalera i el peu integrats descrits a Valors per defecte inclosos són elements ja fets amb els seus propis valors (Open Sans 8pt/600 en el color principal de la paleta), no els valors per defecte de l'element.

Marcadors disponibles:

• {pageNumber} — número de pàgina actual (1-indexed).
• {totalPages} — total de pàgines del document. En un llibre compost capítol a capítol (el Sandbox, buildBundle) cada capítol és un document, de manera que és el recompte del mateix capítol.
• {bookTotalPages} — total de pàgines del llibre sencer: tots els capítols, pàgines en blanc incloses. En un document compost tot sol coincideix amb {totalPages}. Consulta Recompte de pàgines del llibre més avall.
• {title}, {subtitle}, {author}, {publishDate} — valors llegits de content.metadata. Les metadades desconegudes o buides es renderitzen com a cadena buida (i generen un avís al sandbox).
• {chapterTitle} — text de l'H1 més recent a la pàgina actual o abans. Se salta un H1 l'estil d'encapçalament del qual fixa runningChapter: false (una làmina, un mapa).
• {chapterTitleAtTop}, {chapterNumberAtTop} — títol i número del capítol vigent al cap de la pàgina, que no coincideixen amb {chapterTitle} i {chapterNumber} en una pàgina on un capítol nou comença sota un altre text. Consulta Capítol al cap de pàgina més avall.
• {partTitle}, {partNumber} — títol i número de la part actual (la pàgina :::part més recent a la pàgina actual o abans; les pàgines en blanc de paritat just abans d'una pàgina de part ja hi pertanyen). Buits abans de la primera part.
• {firstMark.<clave>}, {lastMark.<clave>} — la primera i l'última paraula guia de la pàgina: un títol d'un nivell (h1–h6) o una entrada d'un estil de paràgraf. Consulta Paraules guia més avall.

Recompte de pàgines del llibre

{bookTotalPages} imprimeix el nombre de pàgines del llibre sencer, el que el lector veu a «pàgina 12 de 348». Compta pàgines físiques, les blanques incloses, com {totalPages}, però al llarg de tots els capítols:

• Un document compost tot sol (buildDocument sense continuation) és el llibre sencer: {bookTotalPages} coincideix amb {totalPages}.
• buildBundle compon el llibre, suma les pàgines de tots els capítols i el compon un cop més amb aquest total, de manera que tots els capítols imprimeixen el mateix nombre. El recompte mai no mou un salt de pàgina, així que n'hi ha prou amb una volta més; una configuració que no imprimeix {bookTotalPages} no paga res.
• El Sandbox lliura el total a tots els capítols tan bon punt coneix les pàgines de cadascun. Fins llavors, un capítol imprimeix les pàgines fins al seu propi final. L'exportació del llibre sencer a la pestanya PDF compta les pàgines que maqueta: si un capítol va imprimir un altre recompte, perquè encara no se'n coneixien les pàgines, torna a maquetar el llibre amb el total al qual van arribar els capítols.
• Un amfitrió que compon els capítols pel seu compte passa el total com a continuation.bookPageCount (també al primer capítol). Sense això, {bookTotalPages} compta les pàgines fins al final del document (continuation.pageIndexOffset més les seves), cosa que només és exacta per a l'últim capítol.

footer: {
  elements: [{
    kind: 'text', id: 'folio', content: '{pageNumber} / {bookTotalPages}',
    fontSize: { value: 8, unit: 'pt' },
    placement: { anchor: { to: 'container', edge: 'top' }, size: { width: 'auto', height: 'auto' } },
  }],
}

configUsesPlaceholder(config, 'bookTotalPages') diu a un amfitrió si val la pena calcular el recompte.

Paraules guia: primera i última marca

Un diccionari imprimeix a la capçalera el primer i l'últim lema de cada pàgina («Abacà – Àncora»); una obra de consulta, la primera i l'última secció. {firstMark.<clave>} i {lastMark.<clave>} els imprimeixen. La clau diu què marca una pàgina:

• De h1 a h6: un títol d'aquest nivell. La marca és el seu text, sense el número.
• L'id d'un estil de paràgraf (entry): un paràgraf d'un contenidor :::paragraphs{style="entry"}. La marca és el tram en negreta amb què obre el paràgraf, el lema, sense la puntuació final: **Abacá.** Planta de… marca Abacá. Un paràgraf que no obre en negreta no posa marca.

{firstMark.<clave>} és la primera marca que comença a la pàgina i {lastMark.<clave>} l'última. Una pàgina en què no en comença cap (una entrada llarga que continua) imprimeix en tots dos la marca vigent, l'última anterior. Les pàgines anteriors a la primera marca no imprimeixen res; en un llibre maquetat capítol a capítol és la primera marca del capítol, perquè les marques no passen d'un capítol al següent. Un títol o un paràgraf partit entre pàgines marca només la pàgina en què comença. La clau s'escriu després del punt amb lletres, dígits, _ i -, començant per una lletra o _; una clau desconeguda no imprimeix res.

:::paragraphs{style="entry"}
**Abacà.** Planta de les Filipines de la fibra de la qual es fan caps.
 
**Abarloar.** Situar un vaixell al costat d'un altre o al costat d'un moll.
:::

header: {
  elements: [{
    kind: 'text', id: 'guia', content: '{firstMark.entry} – {lastMark.entry}',
    fontSize: { value: 8, unit: 'pt' },
    placement: { anchor: { to: 'container', edge: 'bottom' }, size: { width: 'auto', height: 'auto' } },
  }],
}

Les paraules guia són capçaleres: es resolen a les ranures de capçalera i peu (també al header i al footer d'un estil de títol) i no imprimeixen res als dissenys de títol, de part i de l'índex; als de títol i de part, el tauler Revisió els assenyala com a marcadors desconeguts. Per mostrar el primer lema als versos i l'últim als rectos, fes servir dos elements amb parity: 'even' i parity: 'odd'. Un H1 l'estil d'encapçalament del qual fixa runningChapter: false no posa marca h1.

Capítol al cap de pàgina

{chapterTitle} i {chapterNumber} anomenen l'últim capítol començat a la pàgina o abans. En un llibre els capítols del qual van seguits, sense salt de pàgina entre ells, una pàgina que tanca un capítol i comença el següent a prop del peu porta llavors el títol del capítol nou sobre un text que encara pertany a l'anterior. {chapterTitleAtTop} i {chapterNumberAtTop} anomenen en canvi el capítol vigent al cap de la pàgina, com fan les novel·les de capítols seguits i moltes obres de consulta:

• una pàgina el primer bloc de la qual és l'H1 d'un capítol anomena aquest capítol;
• qualsevol altra pàgina anomena el capítol que continua, encara que més avall en comenci un de nou;
• una pàgina en blanc afegida per paritat va amb la pàgina que la segueix, i la separadora dels modes always-* amb la que la precedeix (consulta Pertinença de les pàgines en blanc); si la pàgina que segueix una blanca de paritat comença amb el final d'un capítol i no amb el seu H1, la blanca també es queda amb aquest capítol;
• se salta un H1 amb runningChapter: false.

header: {
  elements: [{
    kind: 'text', id: 'chapter', content: '{chapterTitleAtTop}', parity: 'odd', pages: 'body',
    fontSize: { value: 8, unit: 'pt' },
    placement: { anchor: { to: 'container', edge: 'bottom-right' }, size: { width: 'auto', height: 'auto' } },
  }],
}

Com les paraules guia, tots dos són capçaleres: es resolen a les ranures de capçalera i peu i no imprimeixen res als dissenys de títol, de part i de l'índex. {attr.<clave>} llegeix sempre l'últim capítol començat.

Alineació implícita per vora

Quan un element de text té placement.anchor.to apuntant a un altre element mitjançant #id, la vora de l'ancoratge implica una alineació per defecte per a les línies ajustades:

• right-of i align-left impliquen align: 'left' — les línies ajustades flueixen cap a la dreta des de l'ancoratge.
• left-of i align-right impliquen align: 'right' — les línies ajustades s'enganxen al costat més proper a l'element de referència.

L'editor d'encapçalaments del sandbox aplica aquestes alineacions implícites automàticament en canviar la vora o el destí de l'ancoratge. Mantenen el text ajustat visualment lligat a l'element amb què es relaciona (de manera que, p. ex., la "P" d'un "Postext" ajustat queda verticalment sota la "I" d'"Introducció").

Marques en línia i contorns

Un element de text compon el seu text en una sola font per defecte: **, ^ i els altres signes de marca de Markdown s'imprimeixen tal qual. Amb inlineMarks: true el text resolt es llegeix com a Markdown en línia, amb les mateixes marques que admet el text de cos (vegeu Format del document → Format en línia):

• **negrita** compon amb gruix 700 (o amb el fontWeight de l'element si és més gruixut); *cursiva* inverteix la inclinació de l'element, de manera que l'èmfasi dins d'un element en cursiva surt en rodona; ***ambas*** fa totes dues coses. També valen les formes amb guió baix (__negrita__, _cursiva_).
• ^superíndice^ i ~subíndice~ es componen al 58 % de la mida, el superíndex elevat un terç d'aquesta i el subíndex baixat 0,15; un subíndex i un superíndex que es toquen (T~0~^2^) s'apilen, com al cos.
• Una barra inversa compon el mateix signe de marca (\*, \_, \^, \~). Un enllaç conserva el seu text; els accents greus de codi desapareixen.

Les marques es llegeixen després de substituir els marcadors, així que un valor les pot portar: la línia d'autors d'un atribut de l'encapçalament rep els seus números de filiació com a superíndexs. L'ajust de línia, la justificació, els modes d'el·lipsi, dropCap i paragraphIndent funcionen amb text marcat; tots els trams conserven el color de l'element.

{ "kind": "text", "id": "authors", "content": "{attr.authors}", "inlineMarks": true, "overflow": "wrap",
  "fontSize": { "value": 11, "unit": "pt" },
  "placement": { "anchor": { "to": "#title", "edge": "below" }, "offset": { "y": { "value": 6, "unit": "pt" } } } }

# Innivació i cabal dels rius {authors="Ana Ruiz^1^, Luis Gil^2^ i Marta Sanz^1,3^"}

stroke traça un contorn al voltant de les lletres: width és el gruix de la línia, centrada a les vores dels glifs (la meitat cau dins de les lletres i la meitat fora; l'amplada mesurada del text no canvia), color és per defecte el del text i hollow: true deixa les lletres sense farciment, de manera que només es veu el contorn: una xifra de titular perfilada, un títol que es desenganxa d'una fotografia. El contorn es pinta sobre el farciment, igual al llenç, en HTML (-webkit-text-stroke) i al PDF (mode de renderització de text 2, o 1 si és buit).

{ "kind": "text", "id": "year", "content": "1863", "fontFamily": "Bitter", "fontSize": { "value": 120, "unit": "pt" }, "fontWeight": 700,
  "color": { "hex": "#1d3557", "model": "hex" },
  "stroke": { "width": { "value": 1.5, "unit": "pt" }, "hollow": true },
  "placement": { "anchor": { "to": "page", "edge": "bottom-right" }, "offset": { "x": { "value": -15, "unit": "mm" }, "y": { "value": -20, "unit": "mm" } } } }

Al PDF, els trams en negreta i en cursiva incrusten les variants corresponents de la família de l'element, així que el proveïdor de fonts les ha de subministrar.

Valors per defecte del text i paranys de l'ancoratge

Un element de text que escrius tu parteix d'aquests valors, i algun sorprèn:

• overflow val 'ellipsis-end'. Un text massa ample per al seu espai es talla en una línia amb …. Fes servir overflow: 'wrap' per a una adreça, una signatura o qualsevol títol que es pugui allargar. Un salt de línia en el contingut (un salt real, o \n a la plantilla o al valor d'un atribut) comença una línia nova en tots els modes; els modes d'el·lipsi tallen cada línia per separat.
• align val 'center' i verticalAlign val 'middle'. Un element d'amplada automàtica s'ajusta a la seva línia més llarga, de manera que les seves línies queden centrades entre si; fes servir align: 'left' per a un bloc alineat a l'esquerra (un element d'amplada automàtica ancorat a un altre element alinea les seves línies tot sol del costat del seu ancoratge, vegeu més amunt).
• La font és EB Garamond de 8 pt, en negre, amb lineHeight de 1.2, sigui quina sigui la del text de cos. A diferència dels altres interlineats de la configuració, el lineHeight d'un text de disseny sol ser un múltiple sense unitat (1.2); un Dimension també val (vegeu més amunt).

Un element sense placement.size.width (o amb 'auto') pren la mida del seu text, però només dins de l'espai que va del seu punt d'ancoratge a la vora del contenidor cap a la qual creix; per a un ancoratge top o bottom, el doble de la distància a la vora més propera. El seu offset compta. Un desplaçament que l'allunya d'aquesta vora no li treu res: una capçalera corrent ancorada a top-left amb una x negativa (que penja al marge esquerre) no perd espai, perquè creix cap a la dreta. Un desplaçament cap a aquesta vora li'n treu el mateix (el doble en un ancoratge top o bottom), i un que empeny el punt d'ancoratge més enllà de la vora el deixa sense espai: un ancoratge top-right amb una x menor que menys l'amplada del contenidor, o un ancoratge top desplaçat de costat més de la meitat d'aquesta amplada. Sense espai, un mode d'el·lipsi no imprimeix res i 'wrap' apila un caràcter per línia. Hi ha tres sortides:

• donar a l'element un size.width fix: les amplades fixes mai no es retallen;
• ancorar-lo a 'page' o a 'bleed', que converteix el marc de la pàgina (o de l'àrea de sang) en el seu espai;
• ancorar-lo a la vora oposada del contenidor.

El contenidor de la capçalera va de la vora superior de tall al cos, i el del peu, del cos a la vora inferior de tall: a la capçalera, els ancoratges top-* es mesuren des de la vora de tall i els bottom-* des del cos, i a l'inrevés al peu (vegeu Marc del contenidor més amunt). Una capçalera o un peu mai no desplacen el text de cos i es pinten a sobre, així que un element empès a l'àrea del cos tapa el text. Una banda d'obertura, en canvi, es pinta sota el text de cos; l'espai que ocupa en el flux es descriu a Alçada reservada.

#Elements de text verticals

Un element de text amb writingMode: 'vertical-rl' es compon en vertical en un bloc el text del qual és horitzontal: les capçaleres i els folis de qualsevol llibre, que es queden al plec, i qualsevol disseny d'una pàgina horitzontal. Es compon com un text horitzontal en un marc propi girat un quart de volta en el sentit de les agulles del rellotge, i es retorna girat a la pàgina:

• La seva caixa queda on la posa la col·locació. La seva alçada és la llargada d'una línia: la fixa size.height (o 'auto', el que mesura el text; 'fill', fins a la vora del contenidor), size.width fixa quantes línies hi caben d'amplada i size.maxWidth limita la llargada d'una línia.
• align col·loca les línies al llarg de la caixa ('left' a dalt), verticalAlign d'amplada ('top' a la dreta, on va la primera línia), i el farciment d'una caixa es queda al costat per al qual està escrit.
• Els caràcters es mesuren i es pinten com en una pàgina vertical: els hanzi drets, a un quadratí cadascun; la puntuació, en la seva forma vertical; les paraules llatines, ajagudes; els nombres curts, en una casella (cjk.uprightDigits). El canvas, el PDF i l'HTML ho posen al mateix rectangle.
• Amb inlineMarks: true les marques d'orientació separen un tram com al cos: 第:tcy[3.0]回 posa 3.0 en una casella, :upright[GDP] posa les lletres dretes una sota l'altra, :sideways[…] ajau un tram; una línia mai no es talla dins d'una d'elles. Un element horitzontal les ignora.
• Un element vertical no porta caplletra.
• En el flux d'una pàgina vertical (una obertura, una pàgina de part, el títol d'un requadre) el text ja va cap avall i writingMode no canvia res.

Els llibres xinesos verticals posen capçaleres i folis en un de tres llocs (clreq §7.2; per al japonès, JLREQ §2.6):

Les capçaleres del marge exterior, tal com les afegeix el Sandbox (Encapçalament › Capçaleres al marge exterior (vertical)), aquí per a un cos de 10 pt (el Sandbox les posa al 80 % del cos del text):

{
  "page": { "pageNumbering": { "format": "trad-chinese-informal" } },
  "header": { "elements": [
    { "kind": "text", "id": "head", "content": "{chapterTitle}", "writingMode": "vertical-rl",
      "fontSize": { "value": 8, "unit": "pt" }, "overflow": "clip", "align": "left",
      "placement": { "anchor": { "to": "outer", "edge": "top" }, "offset": { "y": { "value": 4, "unit": "em" } } } },
    { "kind": "text", "id": "folio", "content": "{pageNumber}", "writingMode": "vertical-rl",
      "fontSize": { "value": 8, "unit": "pt" }, "overflow": "clip", "align": "left",
      "placement": { "anchor": { "to": "outer", "edge": "bottom" }, "offset": { "y": { "value": -5, "unit": "em" } } } }
  ] }
}

anchor.to: 'outer' (vegeu Posicionament d'elements) és el marge exterior de cada pàgina, així que els dos elements baixen per la vora esquerra d'una pàgina senar i per la dreta d'una de parella en un llibre enquadernat per la dreta (page.binding). {pageNumber} surt en el format de la numeració: trad-chinese-informal dona 一百零三 a la pàgina 103, i cjk-decimal, 一〇三. Les regles de cada bloc continuen valent: pages: 'body' treu una capçalera de les obertures de capítol. Un ornament curt entre capçalera i foli (una cua de peix ︻, un filet) és un element més ancorat al mateix marc.

Al VDT un bloc vertical porta vertical (VDTDesignTextBlock.vertical: la regió, les xifres dretes i l'eix central de cada família); les seves línies són al marc girat del mateix bloc: xOffset cap avall des de la vora superior de la caixa i baselineY cap a l'esquerra des de la seva vora dreta. Un tram d'una línia amb marques porta tcy o orientation, com un segment del cos.

#Elements de línia

Els elements de línia dibuixen una línia: horitzontal al llarg de l'amplada del bloc, o vertical al llarg de la seva alçada.

#Elements de caixa

Els elements de caixa pinten un rectangle arrodonit dins del bloc — útils com a fons darrere d'un text en obertures de capítol, columnes laterals o peus. Les caixes es posicionen exclusivament mitjançant el camp placement; no tenen variant plana heretada. L'emplenament, el traç i el radi de cantonada viuen a l'objecte niat style (ElementBoxStyle), com a l'exemple JSON de «Posicionament d'elements».

#Elements d'imatge

Un element image dibuixa un recurs de mapa de bits o SVG del document — el logotip de l'editorial a la portada, una marca en una capçalera. La seva mida la fixa placement.size: si un dels costats width / height queda en 'auto' (el valor per defecte), l'altre segueix la proporció de la imatge; amb tots dos fixats, la imatge s'ajusta dins de la caixa, centrada. Un recurs inexistent o que no sigui una imatge no dibuixa res.

{
  kind: 'image', id: 'logo', resourceId: 'logo-editorial',
  placement: { anchor: { to: 'page', edge: 'top-left' }, offset: { x: { value: 64, unit: 'mm' }, y: { value: 233, unit: 'mm' } }, size: { width: { value: 83, unit: 'mm' }, height: 'auto' } },
}

resourceId admet els mateixos marcadors que el content d'un element de text, de manera que un mateix disseny pot dibuixar una imatge diferent a cada encapçalament. Amb resourceId: '{attr.vineta}' en un estil d'encapçalament, # Capítulo I {style="apertura" vineta="tronco"} dibuixa el recurs tronco i # Capítulo II {style="apertura" vineta="peluca"} dibuixa peluca: els capítols comparteixen l'estil en lloc de clonar-lo per a cada imatge. Una capçalera o un peu llegeixen els atributs del capítol de la pàgina, com {attr.<clave>} en un titolet, i també hi serveixen els altres marcadors ('mapa-{chapterNumber}'). Un id que queda buit, com el d'un encapçalament sense l'atribut, no dibuixa res. Des de postext 1.8.

El backend PDF incrusta el recurs com una figura (un SVG amb màster d'impressió l'utilitza); el visor HTML el resol mitjançant resourceImageUrl.

Una imatge que dibuixa un disseny és contingut quan el seu recurs la descriu: l'altText del recurs, o el seu peu com a text sense format quan no en té (una etiqueta :chip es llegeix pel seu text i una :ref pel seu text si en porta), passa al VDT (VDTDesignImageBlock.altText), és l'alt del seu <img> en HTML i una Figure amb /Alt en un PDF etiquetat, que es llegeix just després del text del seu disseny (la làmina d'un capítol, després del títol del capítol). Una imatge el recurs de la qual no té ni l'una cosa ni l'altra, i una marcada com a decorative, és ornament: alt="" amb role="presentation", i un artefacte al PDF. La imatge d'una capçalera o un peu es repeteix a totes les pàgines, així que es tracta com un element de paginació digui el que digui el seu recurs: sense altText al VDT, alt="" amb role="presentation" en HTML i un artefacte de la pàgina al PDF.

#Posicionament d'elements

ElementPlacement és el model unificat de posicionament que fan servir tots els tipus d'elements (text, línia, caixa) dins de qualsevol ranura de disseny — capçalera de pàgina, peu de pàgina o ranura de disseny avançat d'un encapçalament. Tres camps descriuen un placement:

interface ElementPlacement {
  /** A què s'ancora aquest element i a quina vora d'aquest destí. */
  anchor: {
    to: 'container' | 'page' | 'bleed' | 'outer' | `#${string}`; // container = el bloc; page = caixa de tall; bleed = caixa de tall + sang; outer = el marge exterior (capçalera, peu); #id = un altre element
    edge: AnchorEdge;
  };
  /** Distància des del punt d'ancoratge. */
  offset?: { x?: Dimension; y?: Dimension };
  /** Amplada / alçada opcional. L'amplada admet també 'fill' (estendre al llarg del bloc).
   *  `maxWidth` limita una amplada 'auto' (text): l'element continua ajustant-se al seu
   *  contingut, de manera que els elements que s'hi ancoren no se'n desenganxen, però un text llarg
   *  es talla o es plega allà — una capçalera pot reservar lloc per a l'etiqueta que
   *  en penja en comptes d'expulsar-la. */
  size?: { width?: Dimension | 'fill' | 'auto'; height?: Dimension | 'fill' | 'auto'; maxWidth?: Dimension };
}

AnchorEdge admet:

• Vores del contenidor (quan anchor.to és 'container', 'page' o 'bleed'): top, top-left, top-right, bottom, bottom-left, bottom-right, left, right.
• Vores relatives a un altre element (quan anchor.to === '#someId'): right-of, left-of, below, above, align-top, align-bottom, align-left, align-right.

Cada vora relativa a un altre element posa una cantonada de l'element sobre una cantonada de l'element al qual s'ancora, i offset el desplaça des d'allà:

• right-of: la seva cantonada superior esquerra sobre la superior dreta del de referència (al costat, amb les parts superiors a la mateixa alçada); left-of: la seva cantonada superior dreta sobre la superior esquerra del de referència;
• below: la seva cantonada superior esquerra sobre la inferior esquerra del de referència (a sota, amb les vores esquerres alineades); above: la seva cantonada inferior esquerra sobre la superior esquerra del de referència;
• align-top i align-left: la seva cantonada superior esquerra sobre la superior esquerra del de referència. Els dos noms donen la mateixa col·locació: s'alineen alhora les vores superiors i les esquerres;
• align-bottom: la seva cantonada inferior esquerra sobre la inferior esquerra del de referència;
• align-right: la seva cantonada superior dreta sobre la superior dreta del de referència.

Una vora relativa a un altre element usada amb 'container', 'page' o 'bleed', i una vora de contenidor usada amb '#id', es llegeixen com la cantonada superior esquerra.

anchor.to: 'page' ancora l'element a la caixa de tall (la pàgina física un cop tallada) i 'bleed' a la caixa de tall ampliada per cutLines.bleed a tots els costats (idèntica a la caixa de tall mentre les marques de tall estiguin desactivades). Tots dos marcs passen a ser també la referència de size: 'fill' i del retall automàtic d'amplada, de manera que una banda de color pot anar de vora a vora independentment dels marges de pàgina:

{ "kind": "box", "id": "band", "placement": { "anchor": { "to": "bleed", "edge": "top-left" }, "size": { "width": "fill", "height": { "value": 6, "unit": "cm" } } }, "style": { "backgroundColor": { "hex": "#1d3557", "model": "hex" } } }

Amb les marques de tall activades, el que un element pinta fora de la caixa de sang es retalla (vegeu Marques de tall).

anchor.to: 'outer' (blocs de capçalera i peu) ancora l'element al marge exterior de la pàgina: de la vora de la caixa de text a la vora de tall al costat contrari al llom, i del cap de la caixa de text al seu peu. Queda a la dreta d'una pàgina senar i a l'esquerra d'una parella en un llibre enquadernat per l'esquerra, i al revés en un d'enquadernat per la dreta (page.binding), de manera que un sol element serveix per a les dues pàgines d'un plec: una capçalera pel marge exterior (vegeu Elements de text verticals). En qualsevol altre bloc es llegeix com 'container'. L'offset d'un element de text pot anar en em, quadratins del seu propi fontSize: quatre caràcters per sota del cap de la caixa de text és { "y": { "value": 4, "unit": "em" } }.

Dins de la ranura de disseny avançat d'un encapçalament, els elements ancorats a la pàgina o a la sang no augmenten l'alçada reservada per a l'encapçalament llevat que s'estenguin per sota de la seva vora superior (una banda a la part superior de la pàgina queda darrere de l'obertura; una banda que baixi més enllà de l'encapçalament empeny el cos cap avall). Fes servir advancedDesign.minHeight per reservar una alçada fixa d'obertura en qualsevol cas, i reserve: false en un element que no hagi d'empènyer el text de cap manera. Les regles completes són a Alçada reservada.

Cada element té un id estable (que assigna automàticament el sandbox; també el pots establir a mà). Els elements ancorats a altres elements formen un petit graf de dependències que el motor resol abans de mesurar, així un element es pot encadenar a un altre sense coordenades manuals.

La forma heretada align + marginFromBody + marginFromEdge s'interpreta a l'entrada i es reescriu a un placement en el moment de resoldre la configuració, de manera que les configuracions existents continuen funcionant sense canvis.

#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.

#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 i en xinès, en caràcters simplificats i tradicionals; 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). 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, 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. 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 en horitzontal i en vertical. Composició xinesa explica com es compon el xinès i quins ajustos el 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 i el coreà passen pel mateix compositor i es componen sense partició de mots, però amb els valors per defecte de la Xina continental: les seves regles pròpies (JLREQ, 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 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. 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.
3. 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.
4. 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.

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.

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)
  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' | '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:

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.
}

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 \tag{…} 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 etiquetada d'un align. \tag*{…} imprimeix l'etiqueta tal qual, sense parèntesis. Només les etiquetes explícites imprimeixen número; entorns com equation no es numeren per si sols. 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.)

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.

#Notes a peu de pàgina

La propietat footnotes fixa on van les notes citades amb [^id], com es numeren i quin aspecte tenen. El marcatge es descriu a Format del document.

interface FootnotesConfig {
  placement?: 'column' | 'chapterEnd'; // Peu de la columna que cita, o després del capítol.
  numbering?: 'chapter' | 'document' | 'page' | 'column'; // Reiniciar a cada capítol, continuar, o reiniciar a cada pàgina / columna.
  numberFormat?: string;      // decimal, lower-roman, circled-decimal (①)…
  markerPosition?: 'auto' | 'superscript' | 'inline'; // Volada, o sobre la línia de base.
  markerSize?: Dimension;     // Mida de la crida en línia; em és el text que l'envolta.
  chapterEndAlign?: 'foot' | 'text';   // chapterEnd: notes al peu de la columna, o sota el text.
  fontSize?: Dimension;       // Cos de la nota; em és el cos del text.
  lineHeight?: Dimension;     // Interlineat de la nota; em és el cos de la nota.
  color?: ColorValue;         // Color de la nota; sense valor, el del cos.
  textAlign?: TextAlign;      // Sense valor, l'alineació del cos.
  hangingIndent?: Dimension;  // Sagnat de les línies següents d'una nota.
  spaceBetween?: Dimension;   // Espai entre dues notes.
  spaceAbove?: Dimension;     // Espai entre el text i el filet; em és el cos del text.
  spaceBelowRule?: Dimension; // Espai entre el filet i la primera nota.
  separator?: {
    enabled?: boolean;        // Dibuixar el filet.
    width?: number;           // Longitud del filet, fracció de l'amplada de columna.
    lineWidth?: Dimension;    // Gruix del filet.
    color?: ColorValue;       // Sense valor, el color de les notes.
  };
}

footnotes: {
  fontSize: { value: 7.5, unit: 'pt' },
  lineHeight: { value: 9.5, unit: 'pt' },
  hangingIndent: { value: 0.8, unit: 'em' },
  separator: { width: 0.25, lineWidth: { value: 0.4, unit: 'pt' } },
}

Com es componen les notes al peu de columna:

• La nota i la seva crida comparteixen columna. Abans de col·locar una línia, la maquetació suma l'alçada de les notes que aquella línia cita per primer cop (i la del filet, en la primera nota de la columna). Una línia les notes de la qual no caben a sota passa a la columna següent amb la resta del seu paràgraf, segons les regles de vídues i òrfenes. L'àrea de text de la columna s'escurça en l'alçada de les notes, de manera que l'equilibrat de columnes i la banda de tancament d'un capítol només compten el text.
• Diverses notes en una columna s'apilen en l'ordre de cita sota un únic filet. Una nota citada de nou més endavant conserva el seu número i no es torna a compondre.
• Flotants al peu. Una figura que ocupa el peu d'una columna després que les seves notes s'hagin compost queda damunt d'elles; les notes compostes després de la figura queden damunt d'ella.
• Requadres. Una nota citada dins d'un requadre (en línia, flotant o fix) va al peu de la columna on continua el text després del requadre, normalment la mateixa. Un requadre que tanca el document deixa les seves notes al peu de la columna on ha acabat el text.
• Límits. Una nota mai no es parteix: una de més alta que la columna la desborda. Les crides en peus de figura, cel·les de taula i títols no es llegeixen (s'imprimeixen tal qual).
• Sortida. El canvas, l'HTML i el PDF pinten les notes, les crides (un número volat) i el filet. Al PDF cada crida enllaça amb la seva nota, i un PDF etiquetat marca cada nota com a element Note amb un /ID únic llistat a l'/IDTree de l'arbre d'estructura (PDF/UA-1). Les notes són VDTBlock amb footnoteNote, a page.floats; els filets són a page.footnoteAreas.
• Avisos. undefinedFootnote (una crida sense definició: el número s'imprimeix sobre una nota buida) i unusedFootnote (una definició que cap crida no cita: no es compon).

El resolutor i el depurador segueixen el patró de les altres seccions:

import { DEFAULT_FOOTNOTES_CONFIG, resolveFootnotesConfig, stripFootnotesDefaults } from 'postext';

#Referències creuades

La propietat crossRefs fixa les paraules que una referència creuada imprimeix al voltant d'un número o d'una pàgina, i l'estil que pren un :ref que no n'indica cap. Cada plantilla porta {n} on va el número; una que no el porta rep el número després d'un espai no separable ("§" imprimeix § 3.2). Una plantilla sense definir segueix la llengua del document: capítulo / sección / pág. en castellà, chapter / section / p. en anglès, 第{n}章 / 第{n}节 / 第{n}页 en xinès, i el mateix per al francès, l'alemany, l'italià, el portuguès, el català i el neerlandès.

interface CrossRefsConfig {
  chapter?: string;  // Words around a level-1 heading's number: "chapter {n}".
  section?: string;  // Around any other heading's number: "section {n}".
  page?: string;     // Around a page number: "p. {n}".
  defaultStyle?: 'default' | 'number' | 'title' | 'page'; // A :ref without style=.
}

Les referències prenen el color, el pes i la inclinació de totes les referències (bodyText.referenceColor, referenceBold, referenceItalic).

#Cites

La propietat citations tria l'estil de cita i com es veuen les cites i la bibliografia. El marcatge es descriu a Cites i bibliografia; l'estil l'aplica el paquet postext-citeproc.

interface CitationsConfig {
  style?: string;          // 'apa', 'ieee', 'chicago-notes-bibliography'… or 'custom'
  customStyle?: string;    // a whole CSL style (.csl XML), used with style: 'custom'
  locale?: string;         // CSL locale; the document language when unset
  link?: boolean;          // citations link to their entries
  marker?: 'style' | 'brackets' | 'parentheses' | 'superscript' | 'corner';
  collapseRanges?: boolean;
  notes?: 'footnote' | 'warichu';
  bibliography?: {
    title?: string;        // unset: the document language's word; '' or ' ': none
    scope?: 'book' | 'chapter';
    auto?: boolean;
    fontSize?: Dimension;
    lineHeight?: Dimension;
    hangingIndent?: Dimension;
    entrySpacing?: Dimension;
    labelWidth?: Dimension;
    labelAlign?: 'left' | 'right';
    doi?: 'link' | 'text' | 'hide';
    includeUncited?: boolean;
    groupByLanguage?: boolean;
  };
}