# Configurazione: testo e titoli

> Tipografia del testo corrente, sillabazione e lingua del documento; titoli, elenchi puntati e numerati, e formule matematiche

- Versione HTML: https://postext.dev/it/docs/configuration-text
- Ultimo aggiornamento: 2026-10-10
- Tempo di lettura: 11 min
- Altre lingue: [en](https://postext.dev/en/docs/configuration-text.md), [es](https://postext.dev/es/docs/configuration-text.md), [ca](https://postext.dev/ca/docs/configuration-text.md), [de](https://postext.dev/de/docs/configuration-text.md), [fr](https://postext.dev/fr/docs/configuration-text.md), [pt](https://postext.dev/pt/docs/configuration-text.md), [zh](https://postext.dev/zh/docs/configuration-text.md), [ja](https://postext.dev/ja/docs/configuration-text.md), [ar](https://postext.dev/ar/docs/configuration-text.md)

## In breve

Questa pagina riguarda le impostazioni delle parole sulla pagina. Scegli il font, la dimensione e l’interlinea del testo principale, e come si dividono le parole a fine riga. Indichi a Postext in quale lingua è scritto il libro. Stabilisci l’aspetto di ogni livello di titolo e come si disegnano gli elenchi puntati e numerati. L’ultima sezione imposta la dimensione e il colore delle formule matematiche.

## Testo corrente

La proprietà `bodyText` controlla la tipografia di tutto il testo dei paragrafi.

> **Figura: Scala tipografica**
> Gerarchia tipografica da H1 fino al testo piccolo, con le dimensioni relative di titoli, testo corrente e didascalie.
>
> *Una scala coerente rende la gerarchia leggibile a colpo d’occhio.*

> **Figura: Scala delle spaziature**
> Una scala di spaziature a passi, con i valori crescenti usati per margini, spaziature interne e intervalli.
>
> *I passi di spaziatura creano un ritmo prevedibile in tutta l’impaginazione.*

| Proprietà | Tipo | Predefinito | Descrizione |
| --- | --- | --- | --- |
| `fontFamily` | `string` | `'EB Garamond'` | Famiglia di caratteri del testo corrente. Qualsiasi Google Font, font di sistema o famiglia personalizzata dichiarata in [`customFonts`](https://postext.dev/it/docs/configuration-fonts-colors-viewers.md#font-personalizzati). Una sola famiglia, non uno stack di font CSS (vedi più sotto). |
| `fontSize` | `Dimension` | `8 pt` | Corpo di base del testo corrente. |
| `lineHeight` | `Dimension` | `1.5 em` | Spaziatura verticale tra le righe. Le unità relative (em, rem) si adattano al corpo del carattere. |
| `paragraphSpacing` | `boolean` | `false` | Se attivo, inserisce una riga vuota (pari a `lineHeight`) tra paragrafi consecutivi, per una separazione di tipo editoriale. |
| `color` | `ColorValue` | `#000000` | Colore del testo. |
| `boldColor` | `ColorValue` | Colore principale (`#295AA3`) | Colore applicato ai tratti in grassetto/strong. Viene risolto rispetto alla voce `main-color` della tavolozza predefinita, quindi cambiare il colore della tavolozza ricolora tutti i tratti in grassetto del documento. |
| `italicColor` | `ColorValue` | Colore principale (`#295AA3`) | Colore applicato ai tratti in corsivo/enfasi. Stesso valore predefinito legato alla tavolozza di `boldColor`. |
| `referenceColor` | `ColorValue` | Colore principale (`#295AA3`) | Colore applicato alle etichette `:ref` in linea (rimandi alle risorse). Stesso valore predefinito legato alla tavolozza di `boldColor`. Segue la tavolozza da postext 1.5; fino alla 1.4 restava `#295AA3` qualunque fosse il colore principale. |
| `referenceBold` | `boolean` | `true` | Compone le etichette `:ref` in linea con il carattere grassetto. Un rimando conserva l’enfasi del testo che lo circonda (dentro `***…***` resta in grassetto corsivo con entrambi i valori); questa opzione si limita ad aggiungere il grassetto. |
| `referenceItalic` | `boolean` | `false` | Compone le etichette `:ref` in linea in corsivo. Un rimando dentro un testo in corsivo resta in corsivo con entrambi i valori. |
| `emphasis` | `'auto' \| 'italic' \| 'bold' \| 'color' \| 'overline'` | `'auto'` | Come viene composto `*…*`: in corsivo, nel carattere grassetto con `boldColor`, in tondo con `italicColor`, o in tondo con un filetto sopra le parole. `'auto'` vale `'bold'` in un documento scritto in caratteri arabi e `'italic'` in qualsiasi altro. Vedi [Testo arabo](https://postext.dev/it/docs/configuration-text.md#testo-arabo). |
| `tashkil` | `'keep' \| 'strip' \| 'strip-vowels'` | `'keep'` | Segni vocalici arabi: composti come sono scritti, tolti tutti, o tolti tranne la shadda. Vedi [Testo arabo](https://postext.dev/it/docs/configuration-text.md#testo-arabo). |
| `textAlign` | `'left' \| 'justify' \| 'start' \| 'end'` | `'justify'` | Allineamento del testo. `'left'` (o `'start'`) è il lato da cui comincia una riga: la destra di un paragrafo da destra a sinistra (vedi [Direzione del testo](https://postext.dev/it/docs/configuration-text.md#direzione-del-testo)). Il testo giustificato distribuisce la spaziatura su ogni riga per avere margini regolari. Le ultime righe dei paragrafi giustificati vengono composte in bandiera alla loro larghezza naturale, tranne quando Knuth-Plass ha accettato un’ultima riga troppo piena contando sulla compressione degli spazi: in quel caso gli spazi tra le parole si stringono in modo che la riga occupi esattamente la giustezza (la semantica di composizione della glue di TeX, applicata allo stesso modo nei backend canvas, HTML e PDF). |
| `fontWeight` | `number` | `400` | Peso del testo normale (100–900). |
| `boldFontWeight` | `number` | `700` | Peso del testo in grassetto/strong (100–900). |
| `hyphenation` | `HyphenationConfig` | attiva, `'en-us'` | Impostazioni della sillabazione automatica. Vedi più sotto. |
| `firstLineIndent` | `Dimension` | `1.5em` | Rientro applicato alla prima riga di ogni paragrafo (o a tutte le righe tranne la prima quando è attivo il rientro sporgente). |
| `hangingIndent` | `boolean` | `false` | Se attivo, il rientro si applica a tutte le righe tranne la prima (rientro sporgente, alla francese). |
| `indentAfterHeading` | `boolean` | `true` | Se impostato a `false`, il primo paragrafo subito dopo un titolo viene composto senza rientro della prima riga: una convenzione tipografica comune nelle pubblicazioni scientifiche e in molti stili librari. Lo stesso vale per un paragrafo subito dopo una riga [`:::space`](https://postext.dev/it/docs/document-format.md#space). Un riquadro collocato fuori dal testo tra i due (nella colonna laterale, `span: 'side'`, flottante in testa o al piede di una pagina, o fisso) e una figura flottante vengono ignorati: nella sua colonna il paragrafo segue ancora il titolo, e viene composto senza rientro. Un riquadro collocato nel testo (`placement: 'here'`) conta, e il paragrafo che lo segue riceve il rientro. Non ha effetto quando `hangingIndent` è attivo. |
| `maxWordSpacing` | `number` | `2` | Limite superiore della spaziatura tra le parole nel testo giustificato, espresso come moltiplicatore della larghezza normale dello spazio. Knuth-Plass mantiene entro questo limite ogni riga che il paragrafo consente, sillabando una parola o distribuendo prima il gioco sulle righe vicine; una riga che nessuna combinazione di a capo riesce a mantenere entro il limite lo supera, e una che va oltre 3× lo spazio normale viene composta in bandiera. Le righe che superano questo rapporto sono considerate «lasche»: vedi [Righe che l’algoritmo non riesce a riempire](https://postext.dev/it/docs/justification.md#righe-che-il-motore-non-riesce-a-riempire), e `maxJustifyTracking` per lasciare che prendano invece un po’ di tracking. |
| `minWordSpacing` | `number` | `0.6` | Limite inferiore della spaziatura tra le parole nel testo giustificato, come moltiplicatore della larghezza normale dello spazio. Entrambi i limiti vincolano la variazione di ogni spazio rispetto alla sua larghezza, contata in spazi del carattere regular: una riga che contiene uno spazio in corsivo o in grassetto, più stretto o più largo di quello regular, viene disegnata qualche centesimo di spazio sotto o sopra il limite entro cui è stata divisa. `lineWordSpacing(line)` dà il numero vincolato dai limiti; vedi [Giustificazione](https://postext.dev/it/docs/justification.md#limplementazione-di-postext). |
| `maxJustifyTracking` | `number` | `0` | Tracking massimo che una riga giustificata può prendere, in millesimi di em in un senso o nell’altro (l’unità di InDesign: 10 = 0,01 em per carattere), quando i soli spazi tra le parole si allargherebbero oltre `maxWordSpacing` o si stringerebbero oltre `minWordSpacing`. La parte della correzione che eccede il limite passa nelle lettere, così gli spazi di una riga lasca tornano a `maxWordSpacing` e una riga stretta ci sta a `minWordSpacing`. Knuth-Plass ne tiene conto quando sceglie gli a capo, e solo per le righe che la sola spaziatura tra le parole porterebbe oltre i limiti: le altre, l’ultima riga di un paragrafo (a meno che non sbordi), una riga di una sola parola e una riga che contiene un chip non ne prendono. La riga lo registra come `letterSpacing`, e il canvas, l’HTML e il PDF lo disegnano. Richiede `optimalLineBreaking`. `0` lo disattiva. Vedi [Il tracking come ultima risorsa](https://postext.dev/it/docs/justification.md#il-tracking-come-ultima-risorsa). |
| `kashida` | `'auto' \| 'none'` | `'auto'` in un documento in scrittura araba, altrimenti `'none'` | Giustificazione con kashida: una riga giustificata di testo in scrittura araba prende il suo gioco negli spazi tra le parole (fino a un quarto della loro larghezza) e poi in kashida, tatweel interi (U+0640) inseriti tra due lettere legate, mai come spaziatura tra lettere. Knuth-Plass conta l’allungamento di ogni parola come elasticità. Mai nelle parole latine, nelle cifre, nei titoli, nelle righe in bandiera o nell’ultima riga di un paragrafo. I tatweel vengono disegnati ma restano fuori dal testo semplice e da quello copiato. Vedi [La kashida nel testo arabo](https://postext.dev/it/docs/justification.md#la-kashida-nel-testo-arabo). |
| `kashidaPatterns` | `'auto' \| 'naskh' \| 'simple' \| 'nastaliq'` | `'auto'` | Quali raccordi ricevono una kashida, e in che ordine: le regole classiche del naskh, le priorità di Microsoft, o le regole del naskh adattate al nastaʿlīq (secondo raqim-kashida). `'auto'` legge il font del corpo: nessuna in un carattere ruqʿa o dīwānī (Aref Ruqaa), regole nastaʿlīq in un carattere nastaʿlīq, naskh negli altri casi. |
| `kashidaPerWord` | `number` | `1` | Numero massimo di allungamenti in una parola. |
| `kashidaMaxLength` | `number` | `0.6` | Allungamento massimo in un raccordo, in em; prende tutti i tatweel interi che ci stanno. |
| `optimalLineBreaking` | `boolean` | `true` | Usa la divisione in righe ottimale di Knuth-Plass invece di quella greedy, che riempie una riga alla volta. Produce una spaziatura tra le parole più uniforme in tutto il paragrafo. Un paragrafo cinese, giapponese o coreano (vedi [Tipografia dell’Asia orientale](https://postext.dev/it/docs/configuration-east-asian.md#tipografia-dellasia-orientale)), o uno con una parola più larga della colonna, viene comunque composto riga per riga; un paragrafo latino che cita qualche parola CJK la mantiene. Anche il testo in bandiera la usa con `optimalRagged`. Vedi [Sillabazione e giustificazione](https://postext.dev/it/docs/justification.md). |
| `optimalRagged` | `boolean` | `true` | Divide in righe con Knuth-Plass anche il testo corrente in bandiera: testo corrente, citazioni e voci di elenco allineati a sinistra, a destra o centrati, e gli stili di paragrafo in bandiera, i corpi dei riquadri e i corpi delle parti e degli stili di sezione. Gli spazi tra le parole mantengono la loro larghezza. L’algoritmo valuta quanto ogni riga resta corta rispetto alla giustezza (una riga corta di 3 em costa quanto una riga giustificata a `maxWordSpacing`), così uniforma il margine invece di riempire ogni riga prima della successiva, e le regole sulle righe finali troppo corte (`avoidRunts`, `tightenRunts`) e `hyphenateAcrossColumns` funzionano sul testo in bandiera come su quello giustificato. Con `hyphenation.ragged` è ancora la zona a decidere quali sillabe possono chiudere una riga (vedi [Testo in bandiera](https://postext.dev/it/docs/configuration-text.md#testo-in-bandiera)). I titoli, le didascalie, le note, le celle di tabella e l’indice in bandiera vengono ancora composti riga per riga. Richiede `optimalLineBreaking`. `false` compone il testo in bandiera riga per riga, come fino a postext 1.4; le configurazioni salvate prima che compongono in bandiera parte del testo corrente vengono lette con questo valore (vedi [Pacchetti scritti da postext 1.4 o precedenti](https://postext.dev/it/docs/configuration-programmatic-usage.md#pacchetti-scritti-da-postext-14-o-precedenti)). |
| `breakAfterDashes` | `boolean` | `true` | Consente a una riga di terminare dopo una lineetta lunga o media unita alle parole: `say—that’s`, `riddles.—I`, `Hamburg–Berlin`, anche dove la parola dopo la lineetta è composta in un altro stile (`see—*and*`). Knuth-Plass la tratta come uno spazio tra parole, e la riga termina sulla lineetta senza aggiungere nulla. Mai dopo una lineetta che apre un inciso o una battuta di dialogo (`—dijo`, `said "—Hola`, `sagte »—Ich`: uno spazio, o uno spazio e una virgoletta, prima della lineetta; dopo una virgoletta che chiude una parola, come in `"no"—and`, nel tedesco `„nein“—und` o nel francese `« non »—et`, la riga può terminare), prima della punteggiatura (`él—,`), prima di una virgoletta o di una parentesi (`thinking—" and`, `says—“no”`, `says—(no)`: una virgoletta dopo una lineetta chiude spesso la battuta che la lineetta ha interrotto), dentro una serie di lineette, o dentro un intervallo di numeri composto con una lineetta media (`1914–1918`). `false` mantiene gli a capo della 1.4: Knuth-Plass non va mai a capo dopo una lineetta, e l’algoritmo riga per riga del testo in bandiera formattato o sillabato va a capo solo tra due lettere; le configurazioni salvate prima il cui testo contiene una lineetta del genere vengono lette con questo valore (vedi [Pacchetti scritti da postext 1.4 o precedenti](https://postext.dev/it/docs/configuration-programmatic-usage.md#pacchetti-scritti-da-postext-14-o-precedenti)). Si applica al testo corrente, ai titoli, agli elenchi, alle citazioni e ai riquadri. Le didascalie, le note, le celle di tabella e l’indice mantengono gli a capo della 1.4, e un semplice paragrafo in bandiera composto riga per riga segue in ogni caso le regole proprie di pretext. |
| `breakAfterHyphens` | `boolean` | `true` | Consente a una riga di terminare dopo il trattino di una parola composta, un trattino tra due lettere (`well-` · `known`, `vencer-` · `se`), in ogni paragrafo che Knuth-Plass divide in righe. La riga termina sul trattino e non si aggiunge nulla; l’a capo costa quanto una divisione in sillabe. Mai dopo un trattino accanto a una cifra o a un simbolo (`COVID-19`, `-5 °C`). Un paragrafo giustificato senza formattazione in linea va a capo lì solo con due lettere per lato del trattino, quindi nessuna riga termina sull’`e-` di `e-mail`. `false` mantiene gli a capo della 1.4: un paragrafo giustificato senza formattazione in linea non va mai a capo lì, mentre lo fanno lo stesso paragrafo con una parola in corsivo in qualsiasi punto, un paragrafo in bandiera e un paragrafo composto riga per riga; le configurazioni salvate prima il cui testo contiene una parola composta vengono lette con questo valore (vedi [Pacchetti scritti da postext 1.4 o precedenti](https://postext.dev/it/docs/configuration-programmatic-usage.md#pacchetti-scritti-da-postext-14-o-precedenti)). Si applica al testo corrente, ai titoli, agli elenchi, alle citazioni e ai riquadri. Vedi [Parole composte](https://postext.dev/it/docs/justification.md#parole-composte). |
| `repeatHyphen` | `boolean` | `false` | Fa cominciare anche con un trattino la riga che segue un a capo sul trattino di una parola composta: `vencer-` · `-se`, come chiede l’ortografia portoghese, e `léxico-` · `-semántico`, come chiedono le regole della Real Academia Española dal 2010. Il trattino ripetuto viene misurato e disegnato con la sua riga, che lo registra come `repeatedHyphen`; i suoi `plainStart` e `sourceStart` puntano oltre il trattino, così i link, le testatine e la Sandbox leggono la parola come è scritta. Il PDF lo disegna sotto un `/ActualText` che lo esclude, quindi il testo copiato o estratto dal PDF legge la parola una volta sola. Un indirizzo web non lo riceve mai. Si applica al testo corrente, ai titoli, agli elenchi, alle citazioni e ai riquadri; un paragrafo senza formattazione che contiene una parola composta viene allora diviso in righe dall’algoritmo che compone il testo formattato. |
| `hardLineBreaks` | `boolean` | `true` | Legge una barra rovesciata che chiude una riga della sorgente, e `\\` prima di uno spazio, come un a capo forzato dentro un paragrafo, una citazione o una voce di elenco (l’a capo forzato di CommonMark): le parole successive cominciano una nuova riga dello stesso paragrafo, e la riga precedente viene composta alla sua larghezza naturale, come un’ultima riga. Una barra rovesciata che chiude il paragrafo viene stampata, e due spazi alla fine di una riga non sono un a capo (vedi [Formato del documento › A capo](https://postext.dev/it/docs/document-format.md#a-capo)). `false` mantiene la lettura della 1.22: le barre rovesciate vengono stampate e le righe si uniscono con uno spazio; le configurazioni salvate prima il cui testo contiene una barra rovesciata del genere vengono lette con questo valore (vedi [Pacchetti scritti da postext 1.4 o precedenti](https://postext.dev/it/docs/configuration-programmatic-usage.md#pacchetti-scritti-da-postext-14-o-precedenti)). Titoli, didascalie, note e celle di tabella vanno a capo a `\\` in ogni caso. |
| `scriptContext` | `boolean` | `true` | Esegue lo shaping di una parola senza lettere (`46.`, `1367)`, `».`: solo cifre, punteggiatura o simboli) nella scrittura del testo che la circonda. Un carattere può disegnare questi segni in base alla scrittura (Amiri compone un punto fermo e le parentesi latini nel testo latino e arabi negli altri casi, di altre larghezze), e un motore di shaping che riceve la parola da sola sceglie una scrittura con una regola propria, che cambia tra le versioni dei browser e nel PDF. Con questa opzione attiva, la parola prende la scrittura della lettera più vicina che la precede nel suo isolato (altrimenti di quella che la segue), della lettera da destra a sinistra più vicina quando viene disegnata da destra a sinistra, e della lingua del documento quando non ci sono lettere vicine; l’impaginazione la misura in quella scrittura, e il canvas, l’HTML, l’EPUB a layout fisso e il PDF disegnano quelle forme a quella larghezza. Agisce nei contesti latini, greci, cirillici, arabi ed ebraici, e solo con un carattere la cui punteggiatura o le cui cifre cambiano con la scrittura; una parola modellata in scrittura araba non riceve spaziatura tra lettere. Un pezzo senza lettere di una parola che ne ha (`10.1006/` e `.2001` di un DOI che va a capo nelle sue giunture) prende la scrittura che ha dentro la parola. In un documento cinese o giapponese un’ellissi o una lineetta doppia (`……`, `——`) citata in una frase di un’altra scrittura mantiene le forme del testo han. I marcatori di elenco, le etichette dei rimandi, il testo grafico, il lettering dei fumetti e i paragrafi composti dal compositore CJK non vengono toccati. `false` esegue lo shaping di una parola del genere da sola, come fino a postext 1.27; una configurazione salvata prima di `configVersion` 12 viene letta con questo valore (`pinLegacyScriptContext`). Vedi [Parole senza lettere](https://postext.dev/it/docs/arabic-layout.md#parole-senza-lettere). |
| `shapingLanguage` | `'document' \| 'host'` | `'document'` | La lingua in cui viene eseguito lo shaping del testo: misurato, disegnato e incorporato. Un font risponde con altri glifi a seconda della lingua (OpenType `locl`): Noto Serif SC compone le cifre in un altro modo in cinese, un carattere con una forma catalana disegna `l·l` in un altro modo, uno con la regola turca tiene separati `fi`. `'document'` (il valore predefinito da postext 1.30): quella del documento (`locale`, altrimenti la lingua della sillabazione; un documento che non ne indica nessuna è inglese, `en-US`, e uno il cui `locale` non è un tag di lingua viene modellato senza lingua), e quella propria di un tratto dove ne indica una (`:ltr[…]{lang=en}`). L’impaginazione la imposta su ogni contesto con cui misura, quindi un documento va a capo nello stesso modo in una pagina di qualsiasi lingua e in un worker di impaginazione; il canvas disegna in quella lingua, il visualizzatore HTML e l’EPUB la dichiarano sul documento e su ogni pagina, e il PDF esegue lo shaping con il sistema di lingua OpenType di quella lingua. Da postext 1.30 il testo viene misurato in quella lingua così come viene disegnato. Una stringa ha un’unica larghezza qualunque cosa sia stata misurata prima: Chrome conserva le parole che ha già modellato, e Noto Serif SC compone `2026` largo 2,20 em in una stringa senza caratteri oltre U+00FF e 2,23 em in una che ne ha, quindi i due tipi di stringa vengono misurati su contesti separati. Una parola da destra a sinistra viene misurata da destra a sinistra in qualsiasi carattere. Una parola che l’algoritmo di divisione in righe può spezzare (in una sillaba o a un trattino) viene misurata intera e composta intera dove resta su una riga, sul canvas, nel visualizzatore HTML e nel PDF, in qualsiasi paragrafo (da postext 1.31: fino alla 1.30.1 un paragrafo senza formattazione misurava da solo ogni pezzo di una parola del genere, quindi ciò che un carattere disegna a cavallo di un punto di sillabazione, la `ff` di `of·fice` in EB Garamond o il punto largo catalano di Crimson Pro in `l·l`, compariva in una parola di un paragrafo con un corsivo e non nella stessa parola di un paragrafo semplice). Con `'host'` un paragrafo senza formattazione misura ancora da solo ogni pezzo di una parola del genere. Di una parola divisa a fine riga, ogni parte viene misurata come il testo disegnato: la parte che apre la riga successiva come un testo a sé, e la prima parte di un `col·lecció` catalano come `col-`. Un testo grafico (una testatina, un’apertura, la grafica di un titolo) viene misurato tratto per tratto, ogni tratto nella direzione in cui viene disegnato. Il PDF esegue lo shaping parola per parola come fa il canvas del browser (una parola termina a uno spazio, a una tabulazione, a U+3000 o a U+200B, e prima di un carattere han), compone uno alla volta i caratteri cinesi e giapponesi che l’impaginazione ha misurato così, e prende ogni carattere dal file del font da cui l’ha preso il browser quando il fornitore di font lo indica (vedi [Font cinesi, giapponesi e coreani](https://postext.dev/it/docs/configuration-programmatic-usage.md#font-cinesi-giapponesi-e-coreani)). `'host'`: come fino a postext 1.28, l’impaginazione misura nella lingua della pagina che la ospita (nessuna in un worker) e il canvas disegna in quella stessa lingua; il visualizzatore HTML dichiara la lingua di un documento cinese, giapponese, coreano o da destra a sinistra. Un documento con `'host'` conserva le larghezze e il PDF che aveva; in un paragrafo con formattazione anche il suo canvas e il suo visualizzatore HTML compongono intera una parola che resta su una riga (fino a postext 1.29.2 la disegnavano a pezzi). Con questo valore la parte di una parola divisa che apre la riga successiva viene misurata come la parola intera meno la sua prima parte, quindi un carattere la cui forma per la lingua ha bisogno delle lettere ai due lati dell’a capo (la `l·l` catalana di Crimson Pro, un punto largo composto solo tra due `l`) lascia un vuoto dopo il resto della parola, un terzo di em in quel carattere, in una pagina in quella lingua. Il valore predefinito era `'document'` solo in postext 1.29.0, il cui canvas e il cui PDF non seguivano la misura, `'host'` nella 1.29.1 e nella 1.29.2, e di nuovo `'document'` dalla 1.30.0. Una configurazione salvata prima di `configVersion` 14 che non indica l’impostazione riceve `'host'` scritto esplicitamente (`pinLegacyShapingLanguage`), così un documento salvato conserva le sue righe; una che indica un valore lo conserva. Un browser il cui canvas non ha `lang` (Chrome prima della 136, e Firefox e Safari dove manca) non riceve nessuna lingua e conserva le forme che ha sempre misurato, e la riga di comando impagina sempre con `'host'` (vedi [Differenze rispetto alla Sandbox](https://postext.dev/it/docs/command-line.md#differenze-rispetto-alla-sandbox)). |
| `tabStops` | `TabStop[]` | non impostato | Punti di tabulazione di ogni paragrafo, voce di elenco e citazione: dove una tabulazione (`:tab`, o un carattere di tabulazione nel testo) manda le parole che la seguono. Uno stile di paragrafo o il corpo di un riquadro che imposta i propri li sostituisce. Se non è impostato, un carattere di tabulazione è uno spazio tra parole, come prima, e lo è anche un `:tab` senza un punto di tabulazione a cui andare. Vedi [Punti di tabulazione](https://postext.dev/it/docs/configuration-text.md#punti-di-tabulazione). Da postext 1.23. |
| `tabInterval` | `Dimension` | non impostato | Punti di tabulazione predefiniti a ogni intervallo dall’inizio della giustezza, oltre l’ultimo di `tabStops`. Se non è impostato, una tabulazione oltre l’ultimo punto è uno spazio tra parole. Da postext 1.23. |
| `blockquote` | `BlockquoteConfig` | vedi più sotto | Come vengono composte le citazioni Markdown (`> …`): colore, corsivo e rientri. Vedi [Citazioni in blocco](https://postext.dev/it/docs/configuration-text.md#citazioni-in-blocco). |

### Citazioni in blocco

Una citazione (righe che cominciano con `>`) prende la famiglia, il corpo, l’interlinea, i pesi, l’allineamento e la sillabazione del testo corrente. `bodyText.blockquote` imposta il resto; se non è impostato, una citazione ha l’aspetto che aveva fino a postext 1.4: grigia, in corsivo, con il rientro della prima riga del testo corrente e senza rientro laterale.

| Proprietà | Tipo | Predefinito | Descrizione |
| --- | --- | --- | --- |
| `color` | `ColorValue` | `#666666` | Colore del testo. Un colore legato a una voce della tavolozza (`paletteId`) segue quella voce, come ovunque; i colori del grassetto, del corsivo e dei rimandi del testo corrente non si applicano dentro una citazione. |
| `italic` | `boolean` | `true` | Compone il testo in corsivo. Un tratto `*…*` al suo interno torna in tondo; con `false` è in corsivo come in un paragrafo. |
| `indent` | `Dimension` | `0` | Rientro di ogni riga dal bordo sinistro della colonna o del riquadro. La giustezza si restringe di altrettanto, quindi le righe giustificate terminano al bordo destro. `em` è il corpo del testo corrente. |
| `firstLineIndent` | `Dimension` | quello del testo corrente | Rientro della prima riga di ogni paragrafo citato, contato da `indent` (con l’`hangingIndent` del testo corrente, il rientro di tutte le righe tranne la prima). Se non è impostato: `bodyText.firstLineIndent`. |

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

Nella Sandbox queste impostazioni sono il gruppo **Citazioni** della sezione Testo corrente.

### Versi

Una poesia `:::verse` le cui righe non contengono un separatore di emistichi viene composta riga per riga (vedi [Formato del documento › `:::verse`](https://postext.dev/it/docs/document-format.md#verse)). `bodyText.verse` dà i valori predefiniti di queste poesie; un attributo con lo stesso nome sulla recinzione di una poesia lo imposta per quella poesia.

| Proprietà | Tipo | Predefinito | Descrizione |
| --- | --- | --- | --- |
| `layout` | `'auto' \| 'bayt'` | `'auto'` | Come viene composta una poesia la cui recinzione non indica un layout. `'auto'`: come bayt quando una riga contiene un separatore (`\|\|`), riga per riga negli altri casi. `'bayt'`: sempre come bayt, e una poesia senza separatore come emistichi singoli centrati, come fino a postext 1.22. |
| `indentStep` | `Dimension` | `0.5em` | Larghezza di uno spazio iniziale di un verso (una tabulazione ne vale quattro, uno spazio ideografico due); `em` è il corpo della poesia. |
| `turnover` | `'hang' \| 'right'` | `'hang'` | Come va a capo un verso più largo della giustezza: con rientro sporgente sulla riga successiva, o allineato alla fine della giustezza dopo `turnoverMark`. |
| `hang` | `Dimension` | `2em` | Rientro di una continuazione sporgente dall’inizio della sua riga, quando lo stile di paragrafo della poesia non imposta un `hangingIndent`. |
| `turnoverMark` | `string` | `'['` | Il segno prima di una continuazione allineata a destra. |
| `stanzaSpace` | `number` | `1` | Spazio tra le strofe, in righe dell’interlinea della poesia. Sulla griglia della linea di base risulta in righe intere della griglia; uno stile di paragrafo con `snapToGrid: false` lo mantiene esatto. |
| `keepStanzas` | `number` | `0` | Tiene intera in una colonna ogni strofa di questo numero di versi o meno. `0` la disattiva. |
| `tighten` | `boolean` | `true` | Stringe gli spazi tra le parole di un verso poco più largo della giustezza, fino a `bodyText.minWordSpacing` della loro larghezza naturale, e lo tiene su una riga; va a capo solo un verso ancora troppo largo. Per questo non si aggiunge mai tracking alle lettere. `false` manda a capo ogni verso più largo della giustezza, come faceva postext 1.23. L’EPUB a layout fluido, le cui righe sono divise dal sistema di lettura, non stringe. |

```ts
bodyText: {
  // Turnovers flush right behind a bracket; tankas kept whole.
  verse: { turnover: 'right', keepStanzas: 5 },
}
```

Una configurazione salvata prima di queste impostazioni (`configVersion` 8 o precedente) che impagina una poesia senza separatore viene letta con `layout: 'bayt'`, così la poesia conserva le righe centrate che le dava postext 1.22. Una salvata da postext 1.23 (`configVersion` 9) che impagina una poesia riga per riga viene letta con `tighten: false`, così i suoi versi vanno a capo dove andavano nella 1.23.

Nella Sandbox queste impostazioni sono il gruppo **Versi** della sezione Testo corrente.

### Punti di tabulazione

`bodyText.tabStops` elenca i punti a cui va una tabulazione: `:tab`, o un carattere di tabulazione in un paragrafo che ha punti di tabulazione (vedi [Formato del documento › Tabulazioni e punti di tabulazione](https://postext.dev/it/docs/document-format.md#tabulazioni-e-tabulatori) per il markup e per come viene composta una riga). I `tabStops` di uno stile di paragrafo li sostituiscono per i suoi paragrafi, e il `body.tabStops` di uno stile di riquadro dentro i suoi riquadri; un elenco vuoto non ne imposta nessuno. Ogni punto è un `TabStop`:

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

| Proprietà | Tipo | Predefinito | Descrizione |
| --- | --- | --- | --- |
| `position` | `Dimension \| 'end' \| 0` | obbligatorio | Dove si trova il punto, dal bordo d’inizio della giustezza del paragrafo (dopo l’`indent` di uno stile di paragrafo; `em` è il corpo proprio del paragrafo): una lunghezza, `'end'` per il bordo finale della giustezza, o una quota della giustezza (`'50%'`). Nel testo da destra a sinistra il bordo d’inizio è quello destro. |
| `align` | `'start' \| 'end' \| 'center' \| 'decimal'` | `'start'` | Come si colloca al punto il testo dopo la tabulazione: comincia lì, finisce lì (il testo fino alla tabulazione successiva o alla fine del paragrafo), è centrato su di esso, o vi ha sopra il separatore decimale (un tratto che non ne ha finisce lì). |
| `leader` | `string` | nessuno | Ripetuto nello spazio prima del punto: `'.'`, `'. '`, `'·'`, `'_'`, `'-'` o qualsiasi testo breve, nel carattere e nel colore del paragrafo; `'rule'` traccia una linea poco sotto la linea di base. La linea guida termina allineata alla fine del suo spazio, così le linee guida di più righe si allineano. Viene misurata come un unico tratto, come quella di una riga dell’indice. |
| `leaderGap` | `Dimension` | `0.5em` | Spazio lasciato tra la linea guida e il testo da entrambi i lati, come il `leader.gap` dell’indice. Nessuno prima della linea guida quando la tabulazione apre la riga, nessuno dopo quando non segue nulla. |
| `decimalChar` | `string` | quello della lingua del documento | Il separatore su cui si allinea un punto `'decimal'`: `.` in inglese, cinese, giapponese e arabo, `,` in spagnolo, catalano, portoghese, francese, tedesco e altre lingue. |

`tabInterval` aggiunge punti a ogni intervallo dall’inizio della giustezza, oltre l’ultimo punto dell’elenco; senza, una tabulazione oltre l’ultimo punto è uno spazio tra parole. Un carattere di tabulazione digitato nel testo è una tabulazione solo in un paragrafo il cui stile ha punti o un intervallo, propri o del testo corrente; ovunque altrove resta lo spazio tra parole che è sempre stato, quindi un documento salvato viene impaginato come prima e non ha bisogno di vincoli.

I punti vengono verificati con il resto della configurazione (vedi [Avvisi di configurazione](https://postext.dev/it/docs/configuration-fonts-colors-viewers.md#avvisi-di-configurazione)): una chiave sconosciuta in un punto (`leaders`) viene segnalata come `unknownConfigKey` con la chiave a cui somiglia di più; un `align` che non è nessuno dei quattro come `unknownConfigValue`, e il punto viene impostato come `'start'`; una `position` che non è una lunghezza, `'end'` o una percentuale come `unknownConfigValue` con `used: 'none'`, e il punto viene scartato.

Il colore e il carattere della linea guida sono quelli del paragrafo; per ora non hanno un’impostazione propria.

### Capilettera

Un paragrafo del testo corrente può aprirsi con un capolettera: la sua prima lettera composta grande accanto alle prime righe, che vengono accorciate della larghezza della lettera più uno spazio e composte come qualsiasi altra riga (divise da Knuth–Plass, giustificate, sillabate). Uno stile di paragrafo ne dà uno al primo paragrafo di ogni gruppo `:::paragraphs` con quello stile (a ogni paragrafo con `each: true`, per un catalogo di voci); un livello di titolo o uno stile di titolo ne dà uno al primo paragrafo del testo corrente dopo il titolo (vedi il campo `dropCap` di [Personalizzazioni per livello](https://postext.dev/it/docs/configuration-text.md#sovrascritture-per-livello), [Stili di paragrafo](https://postext.dev/it/docs/configuration-styles.md#stili-di-paragrafo) e [Stili dei titoli](https://postext.dev/it/docs/configuration-styles.md#stili-dei-titoli)). Il paragrafo dopo il titolo viene trovato oltre le recinzioni dei contenitori, le direttive, i riquadri usciti dal flusso e le figure flottanti, come lo trova `indentAfterHeading`; un paragrafo dentro un riquadro, una voce di elenco, una citazione, una poesia o una nota non ne riceve mai uno. Nel testo, `{dropcap}`, `{dropcap=false}` e `{dropcap=N}` su una riga di titolo o su una recinzione `:::paragraphs` lo attivano, lo disattivano o ne impostano le righe per quel capitolo o gruppo (vedi [Formato del documento › Capilettera](https://postext.dev/it/docs/document-format.md#capilettera)). Da postext 1.23.

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

| Proprietà | Tipo | Predefinito | Descrizione |
| --- | --- | --- | --- |
| `lines` | `number` | `3` | Righe occupate dall’iniziale, dalla sommità delle sue maiuscole alla sua linea di base. `1` con un `fontSize` maggiore è un’iniziale rialzata che poggia sulla prima linea di base. |
| `sink` | `number` | `lines` | Righe di cui l’iniziale scende nel testo: poggia sulla linea di base della riga `sink`, e quelle righe vengono accorciate. Un valore minore di `lines` la alza sopra la prima riga. |
| `characters` | `number` | `1` | Cluster di grafemi composti grandi: *É*, una lettera con un segno combinante o un carattere fuori dal Basic Multilingual Plane contano come uno. Non oltre la prima parola. |
| `fontFamily`, `fontWeight`, `italic` | `string`, `number`, `boolean` | quelli del paragrafo; `false` | Carattere dell’iniziale. Viene caricato e incorporato con gli altri caratteri del documento. |
| `fontSize` | `Dimension` | vedi più sotto | Corpo dell’iniziale. Se non è impostato: il corpo che porta la sommità delle sue maiuscole al livello delle maiuscole della prima riga mentre poggia `lines` righe più in basso. |
| `color` | `ColorValue` | quello del paragrafo | Un colore legato alla tavolozza segue le tavolozze delle parti e delle sezioni. |
| `gap` | `Dimension` | `0.15em` | Spazio tra l’iniziale e le righe accorciate, dove `em` è il corpo del testo. |
| `punctuation` | `'with-cap' \| 'hang' \| 'text'` | `'with-cap'` | Una virgoletta di apertura, `¿`, `¡` o una parentesi prima della lettera: composta grande come parte dell’iniziale, sporgente al corpo del testo fuori dalla giustezza prima dell’iniziale, o composta al corpo del testo all’inizio della prima riga, dopo l’iniziale. |
| `leadIn` | `{ words, smallCaps, uppercase }` | nessuno | Le prime `words` parole dopo l’iniziale in maiuscoletto (il valore predefinito) o in maiuscolo (`uppercase: true`); `words: 'line'` prende le parole della prima riga. Un attacco esteso alla prima riga viene contato in una prima composizione e applicato in una seconda: in maiuscoletto la riga può allora contenere una parola in più, composta come è scritta. |
| `shortParagraph` | `'reserve' \| 'shrink' \| 'skip'` | `'reserve'` | Un paragrafo di meno righe di `sink`: mantiene il blocco alto `sink` righe così il blocco successivo libera l’iniziale, compone l’iniziale sulle righe del paragrafo stesso, o compone il paragrafo senza capolettera. Ogni caso genera un avviso di contenuto `dropCap`. |
| `each` | `boolean` | `false` | Solo stili di paragrafo: ogni paragrafo del gruppo si apre con il capolettera, non solo il primo. |

Come viene composta la lettera:

- **Corpo.** Entrambe le altezze delle maiuscole, quella del testo e quella dell’iniziale, vengono misurate dai rispettivi caratteri (l’inchiostro di una `H`; dell’iniziale stessa nel testo cinese o giapponese), e un carattere che non fornisce metriche dell’inchiostro conta le sue maiuscole come 0,72 del suo corpo. Il corpo predefinito si adatta a qualsiasi coppia di caratteri, quindi non serve una correzione per carattere. Il `dropCap` di un testo grafico mantiene il suo valore fisso di 0,72 (vedi [Elementi di testo](https://postext.dev/it/docs/configuration-page-layout.md#elementi-di-testo)).
- **La lettera e la sua parola.** L’iniziale prende cluster di grafemi interi. Il resto della prima parola continua dopo di essa senza spazio; una parola di una sola lettera (*A*, *Y*) mantiene il suo spazio all’inizio della prima riga. Il rientro della prima riga del paragrafo viene eliminato. La copia, la ricerca, la mappa della sorgente e il cursore della Sandbox leggono il paragrafo come è scritto: il testo semplice del blocco include la lettera, il `plainStart` della prima riga conta oltre la lettera, e `VDTBlock.dropCap` contiene il suo intervallo e la sua geometria sul frammento con la prima riga.
- **Un’iniziale rialzata** (`lines: 1` con un `fontSize` maggiore, o `sink` minore di `lines`) si alza sopra la prima riga, e il paragrafo tiene libero quello spazio sopra di sé, in righe intere della griglia, così non si sovrappone al testo soprastante.
- **Divisione.** Il paragrafo non si divide mai prima della riga `sink`: passa invece intero alla colonna o alla pagina successiva, a meno che non sia solo in una colonna vuota che non può contenere quelle righe, nel qual caso si divide comunque e genera un avviso `dropCap`. Un titolo tenuto unito al suo testo tiene sotto di sé quelle righe. La parte che continua nella colonna successiva non ha iniziale e ha righe a piena larghezza; divise di nuovo per una colonna di un’altra larghezza, le prime righe mantengono il loro rientro. Il bilanciamento delle colonne può comporre il paragrafo più largo o più stretto come qualsiasi altro, e non aggiunge mai spazio tra le righe accorciate.
- **Scritture.** Le righe vengono accorciate sul lato d’inizio: la sinistra nel testo latino, la destra in arabo ed ebraico. Una lettera che si unisce alla successiva (arabo, siriaco, N’Ko) non viene staccata, e il paragrafo genera un avviso `dropCap`; il cinese e il giapponese orizzontali ricevono un’iniziale di un carattere (首字下沉). Il testo verticale non ne riceve (avviso). Nemmeno un paragrafo che si apre senza una lettera o una cifra (un rimando, una formula, un richiamo di nota) ne riceve (avviso).
- **Output.** Il canvas, il visualizzatore HTML e l’EPUB a layout fisso disegnano l’iniziale accanto alle righe; l’HTML la scrive subito prima del testo della prima riga senza nulla in mezzo, così uno screen reader legge la parola intera. In un PDF marcato l’iniziale fa parte del `P` del paragrafo e, con il resto della sua parola, di uno `Span` il cui `/ActualText` è la parola: l’estrazione del testo legge *Long before*, mai *L ong before*. Un EPUB a layout fluido la compone come `initial-letter` CSS (righe, discesa), flottante dove il sistema di lettura non lo supporta.

Le impostazioni vengono verificate con il resto della configurazione (vedi [Avvisi di configurazione](https://postext.dev/it/docs/configuration-fonts-colors-viewers.md#avvisi-di-configurazione)): una chiave sconosciuta in un capolettera o nel suo attacco viene segnalata come `unknownConfigKey`, un `punctuation` o uno `shortParagraph` che non è una delle sue parole, o un `lines`, un `sink` o un `characters` che non è un numero intero a partire da 1, come `unknownConfigValue`, e si usa il valore predefinito. I capilettera sono disattivati per impostazione predefinita, quindi nessun documento salvato cambia.

### Una sola famiglia per `fontFamily`

`fontFamily`, qui e in ogni altro campo di famiglia di caratteri (`headings.fontFamily`, `tableStyle.bodyFontFamily`, `separatorFontFamily`, il `fontFamily` di uno stile di chip o di un elemento grafico…), indica **una sola** famiglia. Il canvas, l’output HTML e il PDF devono comporre con lo stesso carattere, e il PDF incorpora un font per famiglia senza catena di ripiego, quindi uno stack di font CSS non ha nulla su cui ripiegare. Uno stack viene composto nella sua prima famiglia e segnalato come [avviso di configurazione](https://postext.dev/it/docs/configuration-fonts-colors-viewers.md#avvisi-di-configurazione):

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

Carica quella famiglia prima di impaginare (vedi [Font personalizzati](https://postext.dev/it/docs/configuration-fonts-colors-viewers.md#font-personalizzati) e il fornitore di font in [Generare PDF](https://postext.dev/it/docs/configuration-programmatic-usage.md#generare-pdf)); se manca, il browser misura con il suo font predefinito, qualunque cosa dica il resto dello stack. Una virgola tra virgolette fa parte di un nome (`'"Foo, Bar"'` è una sola famiglia).

### Sillabazione

Quando l’allineamento del testo è impostato a `'justify'`, la sillabazione evita una spaziatura eccessiva tra le parole dividendo le parole lunghe tra le sillabe. Il motore usa i pattern TeX/Liang per trovare i punti di divisione naturali tra le sillabe. Vedi [Sillabazione e giustificazione](https://postext.dev/it/docs/justification.md) per una spiegazione dettagliata. Il testo in bandiera viene sillabato solo se lo chiedi: vedi [Testo in bandiera](https://postext.dev/it/docs/configuration-text.md#testo-in-bandiera) più sotto.

| Proprietà | Tipo | Predefinito | Descrizione |
| --- | --- | --- | --- |
| `enabled` | `boolean` | `true` | Se consentire la sillabazione. |
| `locale` | `LocaleTag` | `locale` di primo livello, altrimenti `'en-us'` | Regole della lingua per la divisione in sillabe: una delle lingue supportate elencate più sotto, o qualsiasi tag BCP 47 (`'es-ES'`, `'pt-BR'`). |
| `ragged` | `boolean` | `false` | Sillaba anche il testo in bandiera (allineato a sinistra, a destra o centrato), entro la `zone`. Vedi [Testo in bandiera](https://postext.dev/it/docs/configuration-text.md#testo-in-bandiera). |
| `zone` | `Dimension` | `3em` | Zona di sillabazione del testo in bandiera: una parola che non ci sta viene divisa solo quando mandarla intera alla riga successiva lascerebbe un vuoto più largo di questo valore. `em` è relativo al corpo del testo stesso. Ignorata nel testo giustificato. |
| `compounds` | `boolean` | `true` | Lascia che il dizionario divida le parole di un composto, una parola con un trattino tra due lettere (`af-ter-dinner`). `false` tiene intera una parola del genere tranne che al suo trattino, dove la riga può ancora terminare (`after-` · `dinner`), come fa TeX. Un trattino facoltativo digitato nella parola continua a dividerla, e un composto più largo dell’intera riga viene comunque diviso. Si applica al testo corrente, ai titoli, agli elenchi, alle citazioni e ai riquadri; le didascalie, le note, le celle di tabella e l’indice continuano a dividere i composti. Vedi [Parole composte](https://postext.dev/it/docs/justification.md#parole-composte). |
| `exceptions` | `string[]` | nessuna | Parole che il dizionario non deve dividere, o può dividere solo dove indica la voce: `'Alice'` non viene mai divisa, `'You-Tube'` solo al suo trattino. Vedi [Parole tenute intere](https://postext.dev/it/docs/configuration-text.md#parole-tenute-intere). |
| `capitalized` | `boolean` | `true` | Divide le parole con l’iniziale maiuscola come tutte le altre. `false` tiene intera ogni parola che comincia con una maiuscola (`Alice`, `Ámsterdam`, `UNESCO`), compresa la prima parola di una frase. Vedi [Parole tenute intere](https://postext.dev/it/docs/configuration-text.md#parole-tenute-intere). |

**Lingue supportate:** `'en-us'` (inglese), `'es'` (spagnolo), `'fr'` (francese), `'de'` (tedesco), `'it'` (italiano), `'pt'` (portoghese), `'ca'` (catalano), `'nl'` (olandese).

Le sottoparti di regione, scrittura e variante vengono ignorate nella scelta dei pattern, e così le maiuscole e i separatori `_`: `'es-ES'`, `'es-MX'` ed `'es_419'` sillabano con `'es'`, `'pt-BR'` con `'pt'`, e ogni tag inglese (`'en'`, `'en-GB'`) con `'en-us'`, gli unici pattern inglesi inclusi, quindi il testo britannico riceve divisioni americane. Una lingua senza pattern inclusi (`'sv'`, `'pl'`, `'fi'`…) viene sillabata con i pattern `'en-us'`, il che dà divisioni sbagliate invece di nessuna; il motore lo segnala una volta per tag con un `console.warn`, e la Sandbox lo elenca nel pannello Verifiche. Imposta `enabled: false` per un documento del genere; così sparisce anche l’avviso. Cinese, giapponese e coreano (`zh`, `ja`, `ko`, qualunque sia la regione o la scrittura) non hanno bisogno di pattern e non stampano avvisi: un documento in una di queste lingue viene composto senza sillabazione. Per dividere le parole latine citate al suo interno, imposta `enabled: true` e indica la loro lingua in `locale` (`'en-us'` per l’inglese). `enabled: true` senza `locale`, o con una lingua cinese, giapponese o coreana, lascia la sillabazione disattivata e lo dice una volta nella console. `matchHyphenationLocale(tag)` restituisce la lingua inclusa a cui corrisponde un tag (`undefined` quando non ce n’è nessuna), e `HYPHENATION_LOCALES` elenca quelle incluse. La configurazione risolta (`doc.config.bodyText.hyphenation`) indica in `locale` i pattern effettivamente usati, e conserva in `tag` il tag che hai dato quando è diverso. Il backend PDF dichiara la lingua del documento dal `locale` di primo livello, e da questo tag solo quando `locale` non è impostato (vedi [Lingua del documento](https://postext.dev/it/docs/configuration-text.md#lingua-del-documento)).

```ts
import { matchHyphenationLocale } from 'postext';

matchHyphenationLocale('es-MX'); // 'es'
matchHyphenationLocale('en-GB'); // 'en-us'
matchHyphenationLocale('sv');    // undefined: hyphenated with 'en-us', with a console warning
```

Le parole di meno di 5 caratteri non vengono mai sillabate. Il motore richiede almeno 2 caratteri prima e 3 caratteri dopo un punto di divisione.

#### Parole tenute intere

Un dizionario divide un nome come divide qualsiasi parola: `Al-ice`, `Áms-ter-dam`, `You-Tu-be`. Tre impostazioni tengono intere le parole, e per tutte e tre il valore predefinito è quello che fa il dizionario.

`hyphenation.exceptions` è un elenco di parole, come il `\hyphenation{…}` di TeX. Una voce scritta senza trattino non viene mai divisa; una voce scritta con trattini viene divisa solo lì, quindi `'You-Tube'` dà `You-` · `Tube` e nient’altro. Una voce corrisponde a una sequenza di lettere, qualunque cosa la circondi: `'Alice'` copre `(Alice,` e `Alice’s`, e un composto viene confrontato parte per parte (`Blender-based` corrisponde a `'Blender'`). Una forma flessa è un’altra parola e ha bisogno di una voce propria. Una voce in minuscolo corrisponde alla parola in qualsiasi combinazione di maiuscole (`'blender'` copre `Blender` e `BLENDER`); una voce con l’iniziale maiuscola corrisponde solo alle occorrenze che cominciano con una maiuscola, quindi `'Rose'` tiene intero il nome e lascia `rose` al dizionario. Le voci contengono solo lettere e trattini; tutto il resto viene scartato.

`hyphenation.capitalized: false` tiene intera ogni parola che comincia con una maiuscola: nomi propri, sigle, e anche la prima parola di ogni frase. Corrisponde all’opzione «Sillaba parole in maiuscolo» di InDesign disattivata, e al `\uchyph=0` di TeX. Una voce di `exceptions` con trattini continua a dividere la sua parola in quei punti. Il tedesco scrive in maiuscolo ogni sostantivo, quindi l’opzione lascerebbe a un testo tedesco quasi nessuna parola da dividere: lì indica le parole in `exceptions`, oppure usa `citations.hyphenateNames`.

`citations.hyphenateNames: false` tiene interi i cognomi degli autori che il documento cita, ovunque si trovino: in una citazione, nel testo corrente e nell’elenco dei riferimenti. Vedi [Citazioni](https://postext.dev/it/docs/configuration-notes-references.md#citazioni).

```ts
const config: PostextConfig = {
  locale: 'es',
  bodyText: {
    hyphenation: { exceptions: ['Ámsterdam', 'Blender', 'You-Tube'] },
  },
};
```

Le tre impostazioni raggiungono ogni testo che il dizionario divide: testo corrente, titoli, elenchi, riquadri, didascalie, celle di tabella, note, testatine e gli altri testi grafici. È un ambito più ampio di quello di `compounds`, che le didascalie, le note, le celle e l’indice ignorano. Due cose restano come sono. Un trattino facoltativo digitato in un’occorrenza di una parola decide ancora quell’occorrenza, e un trattino facoltativo prima della prima lettera tiene intera un’occorrenza senza bisogno di un elenco (vedi [Dove una riga non va mai a capo](https://postext.dev/it/docs/justification.md#dove-una-riga-non-si-divide-mai)). E una parola più larga della sua intera giustezza viene comunque divisa: nei punti della sua voce quando ne ha, altrimenti nelle sillabe del dizionario. Meno parole divise lasciano a una colonna giustificata stretta meno modi di riempire le righe, quindi controlla la spaziatura tra le parole dopo aver disattivato `capitalized` in una pagina a tre colonne. L’EPUB a layout fluido lascia la sillabazione al sistema di lettura, che non sa nulla di queste regole.

#### Testo in bandiera

Per impostazione predefinita viene sillabato solo il testo giustificato: con `textAlign: 'left'`, e negli stili di paragrafo allineati a sinistra, centrati o a destra, ogni parola resta intera per quanto il margine diventi irregolare, tranne dove c’è un trattino facoltativo (U+00AD) digitato nel testo. Imposta `hyphenation.ragged: true` per sillabare anche il testo in bandiera.

Una riga in bandiera non viene mai allargata, quindi dividere ogni parola che non ci sta frangerebbe il margine di trattini. La **zona di sillabazione** lo limita, come fa il compositore a riga singola di un programma di impaginazione. Quando una parola non ci sta alla fine di una riga, il motore guarda il vuoto che lascerebbe mandandola intera alla riga successiva. Se quel vuoto è più largo di `zone`, la parola viene divisa all’ultima sillaba che ci sta; altrimenti scende intera. Una zona in `em` è relativa al corpo del testo stesso. Il valore predefinito, `3em`, divide solo le parole che lascerebbero una riga visibilmente corta. Una zona più ampia dà meno trattini e un margine più irregolare; `0` divide ogni parola che non ci sta. Nella composizione riga per riga, non più di due righe consecutive terminano con una sillaba. I trattini fissi (`enseñanza-aprendizaje`), le giunture degli URL, i trattini facoltativi digitati nel testo e le parole più larghe dell’intera riga vanno a capo come sempre: la zona e il limite delle due righe governano solo le sillabe del dizionario.

L’impostazione vale per tutto il documento. Si applica al testo corrente e alle citazioni quando sono in bandiera, e a ogni stile di paragrafo e corpo di riquadro in bandiera la cui `hyphenation` propria è attiva (per impostazione predefinita vale l’`hyphenation.enabled` del testo corrente), quindi `hyphenation: false` tiene intere le parole di uno stile. Titoli, didascalie, note, celle di tabella e indice non vengono sillabati; lì, come ovunque, viene divisa solo una parola più larga dell’intera giustezza. Il testo grafico (testatine, aperture, pagine di parte) segue il flag `hyphenate` di ciascun elemento di testo, che le aperture a pagina intera e le pagine di parte predefinite impostano, e usa anch’esso il dizionario del documento. Il testo giustificato ignora `ragged` e `zone`.

```ts
const config: PostextConfig = {
  locale: 'es',
  bodyText: {
    textAlign: 'left',
    // A little more hyphenation than the 3 em default.
    hyphenation: { ragged: true, zone: { value: 2, unit: 'em' } },
  },
};
```

Con `optimalRagged` (il valore predefinito) il testo corrente in bandiera viene diviso in righe con Knuth-Plass, e la zona mantiene lì il suo significato: una parola viene divisa solo quando non ci sta nel resto della riga e mandarla giù intera lascerebbe vuoto più della zona. Due sillabe consecutive non vengono rifiutate ma costano quanto due trattini consecutivi nel testo giustificato, quindi una terza è rara. Con `optimalRagged: false`, o `optimalLineBreaking: false`, ogni riga viene riempita prima della successiva, come fino a postext 1.4.

La sillabazione in bandiera impagina i paragrafi con l’algoritmo di divisione in righe che usano sempre i paragrafi con formattazione in linea (grassetto, corsivo, link, formule), quindi attivarla può spostare qualche a capo oltre a quelli con trattino. Su una riga in bandiera, oltre agli spazi e alle sillabe del dizionario, quell’algoritmo va a capo dopo un trattino fisso o una lineetta tra due parole (`largas—separadas`; con `breakAfterDashes`, qualsiasi lineetta unita alle parole, anche `riddles.—I` e `riddles—*and*`), alle giunture degli URL e tra gli ideogrammi, e tiene unita una parola composta in più tratti (`**Nota**:`, `(*véase*`). Senza sillabazione in bandiera, un paragrafo in bandiera senza formattazione viene diviso da Knuth-Plass quando `optimalRagged` è attivo (il valore predefinito): agli spazi tra le parole, dopo un trattino fisso tra due lettere (`meta-` · `analyses`), come fa l’altro algoritmo, e, con `breakAfterDashes`, dopo le lineette unite. Nella composizione riga per riga passa dall’algoritmo di pretext, che differisce in tre punti: può anche andare a capo prima di una lineetta che chiude un inciso o dopo una che lo apre (`él` · `— y`), dopo una barra quando sillaba (`km/` · `h`), e taglia una parola più larga della riga in un carattere qualsiasi senza trattino, dove l’altro algoritmo la divide prima in una sillaba.

Nella Sandbox l’interruttore è **Sillaba il testo in bandiera**, sotto l’allineamento dei paragrafi della sezione Testo corrente, con la zona sotto di esso. Con un testo corrente giustificato lo stesso interruttore si trova tra le impostazioni della giustificazione, per gli stili di paragrafo e i riquadri in bandiera.

### Lingua del documento

Il `locale` di primo livello è la lingua del documento nel suo insieme. Accetta gli stessi valori di `hyphenation.locale` ed è il ripiego quando quel campo non è impostato, quindi a un libro spagnolo basta `locale: 'es'` per sillabare in spagnolo. Sceglie anche la lingua delle diciture predefinite di continuazione delle tabelle e dei riquadri divisi (`(cont.)` / *Continued* contro *Continúa*, vedi [Tabelle più alte della pagina](https://postext.dev/it/docs/configuration-resources.md#tabelle-più-alte-della-pagina) e [Segni su un riquadro diviso](https://postext.dev/it/docs/configuration-styles.md#segni-su-un-riquadro-diviso)) e dei numeri dei titoli scritti in lettere (*Chapter One* contro *Capítulo uno*, vedi [Numeri in lettere](https://postext.dev/it/docs/configuration-text.md#numeri-in-lettere)), ed è la lingua marcata in un PDF accessibile. Se non è impostato, il motore assume `'en-us'`; la Sandbox ripiega sulla lingua dell’interfaccia e imposta il campo in **Grafica › Sistema di scrittura**.

Sceglie anche i tipi di risorsa predefiniti. Quando `resourceTypes` non è impostato, `buildDocument` numera e intitola le didascalie con `defaultResourceTypes(locale)`, quindi `locale: 'de'` da solo dà *Abbildung 1.1* e *Tabelle 1.1*. Quando `locale` non è impostato, lo sostituisce la lingua della sillabazione, sia per i tipi di risorsa sia per le diciture delle tabelle. Un elenco `resourceTypes` esplicito vince sempre. Le versioni precedenti usavano i tipi inglesi qualunque fosse il `locale`, a meno che non passassi tu stesso `defaultResourceTypes(locale)`; un documento che imposta `locale` e vuole mantenere le etichette inglesi passa `resourceTypes: defaultResourceTypes('en')`. I libri e i pacchetti della Sandbox hanno il proprio elenco, quindi non ne sono toccati.

Qui funziona qualsiasi tag BCP 47, come in `hyphenation.locale`: `'de-AT'` riceve le diciture tedesche. Le diciture predefinite esistono nelle otto lingue supportate dalla sillabazione, in cinese (in caratteri semplificati e tradizionali), in giapponese e in arabo; qualsiasi altra lingua riceve quelle inglesi.

Il cinese accetta `zh`, `zh-Hans`, `zh-Hant`, `zh-CN`, `zh-SG`, `zh-TW`, `zh-HK`, `zh-MO` e le forme lunghe (`zh-Hant-TW`), con qualsiasi combinazione di maiuscole e con `-` o `_`. Le diciture seguono la scrittura, letta con `Intl.Locale(tag).maximize()`: `zh`, `zh-CN` e `zh-SG` sono semplificati, `zh-TW`, `zh-HK` e `zh-MO` tradizionali. I valori tipografici predefiniti che dipendono dalla lingua seguono invece la regione, come raccomanda [clreq §1.2](https://www.w3.org/TR/clreq/#x1-2-basic-features-of-chinese-script): CN, SG e MY contano come Cina continentale, TW come Taiwan, HK e MO come Hong Kong, e un tag senza regione segue la sua scrittura (`zh-Hant` è Taiwan, `zh` e `zh-Hans` la Cina continentale). Il giapponese accetta `ja`, `ja-JP`, `ja-Jpan` e qualsiasi altro tag `ja` (`isJapaneseLanguage(tag)`); da postext 1.16 ha diciture proprie e una regione propria, `japan`, i cui valori tipografici predefiniti seguono JLReq (vedi [Impaginazione giapponese](https://postext.dev/it/docs/japanese-layout.md)). Una tabella di diciture senza voce giapponese dà l’inglese, mai il cinese. `localeScript(tag)`, `cjkRegionOf(tag)`, `stringsKeyOf(tag)` e `sameContentLocale(a, b)` danno queste letture, e `DOCUMENT_LANGUAGES` elenca le lingue con diciture predefinite, ciascuna con il nome nella propria lingua (日本語 tra le voci cinesi e العربية), come le mostra il menu Lingua del documento della Sandbox.

| Lingua | Figura: nome, plurale, etichetta breve | Tabella: nome, plurale, etichetta breve | Continuazione della tabella: `continuedSuffix`, `continuesMarker` |
| --- | --- | --- | --- |
| Inglese (`en`) | Figure, Figures, Fig. | Table, Tables, Tab. | (cont.), Continued |
| Spagnolo (`es`) | Figura, Figuras, Fig. | Tabla, Tablas, Tabla | (cont.), Continúa |
| Francese (`fr`) | Figure, Figures, Fig. | Tableau, Tableaux, Tabl. | (suite), À suivre |
| Tedesco (`de`) | Abbildung, Abbildungen, Abb. | Tabelle, Tabellen, Tab. | (Forts.), Wird fortgesetzt |
| Italiano (`it`) | Figura, Figure, Fig. | Tabella, Tabelle, Tab. | (segue), Continua |
| Portoghese (`pt`) | Figura, Figuras, Fig. | Tabela, Tabelas, Tab. | (cont.), Continua |
| Catalano (`ca`) | Figura, Figures, Fig. | Taula, Taules, Taula | (cont.), Continua |
| Olandese (`nl`) | Figuur, Figuren, Fig. | Tabel, Tabellen, Tab. | (vervolg), Wordt vervolgd |
| Cinese semplificato (`zh-Hans`, `zh`, `zh-CN`) | 图, 图, 图 | 表, 表, 表 | （续）, 接下页 |
| Cinese tradizionale (`zh-Hant`, `zh-TW`, `zh-HK`) | 圖, 圖, 圖 | 表, 表, 表 | （續）, 接下頁 |
| Giapponese (`ja`, `ja-JP`) | 図, 図, 図 | 表, 表, 表 | （続き）, 次ページへ続く |
| Arabo (`ar`, `ar-EG`, `ar-MA`…) | شكل, أشكال, شكل | جدول, جداول, جدول | (تابع), يتبع |

Il prefisso della didascalia è il nome del tipo (*Figure 1.1.*). I tipi cinesi numerano all’interno del capitolo con un trattino, `{h1}-{n}` (图 1-1); con le impostazioni della didascalia `labelNumberGap: ''` e `labelSeparator: '　'` la didascalia si legge 图1-1　标题 (vedi [Stile delle didascalie](https://postext.dev/it/docs/configuration-resources.md#stile-delle-didascalie)). Anche l’indice analitico segue la lingua: 见 e 另见 prima di un rimando, 符号 e 数字 sopra i simboli e i numeri in cinese semplificato; 見, 另見, 符號 e 數字 in cinese tradizionale. Il giapponese numera i suoi tipi allo stesso modo e compone le didascalie 図1-1　題 senza le due impostazioni, scrive i rimandi come 第3章, 2.3節 e 12ページ, intitola la bibliografia 参考文献, e il suo indice analitico stampa 記号 e 数字 sopra simboli e numeri e scrive i rimandi con una freccia, `→夏目漱石` per *vedi* e `→夏目漱石、森鷗外も見よ` dopo le pagine per *vedi anche*, con le etichette in tondo. L’arabo numera i suoi tipi allo stesso modo, `{h1}-{n}` (شكل 2-3), scrive i rimandi come الفصل 3, القسم 2-1 e ص 12, intitola la bibliografia المراجع, e il suo indice analitico stampa انظر / انظر أيضًا, رموز e أرقام, con la virgola e il punto e virgola arabi (، ؛).

Un documento cinese, giapponese o coreano dichiara la sua lingua nell’output HTML (`lang` sulla radice `.pt-doc`, `zh-Hant-TW` conservato intero) e sul canvas che disegna (`ctx.lang`, in Chrome 136 e successivi), così il browser disegna le forme dei glifi della regione: Unicode unifica i caratteri han, e uno stesso punto di codice ha un aspetto diverso in un font taiwanese e in uno giapponese. Da postext 1.30 lo fa anche ogni altro documento, nella lingua in cui viene eseguito lo shaping del suo testo ([`bodyText.shapingLanguage: 'document'`](https://postext.dev/it/docs/configuration-text.md#testo-corrente), il valore predefinito); con `'host'` gli altri documenti non hanno `lang`, e ogni canvas disegna nella lingua della pagina che lo ospita. Il PDF dichiara `/Lang` da `locale` per ogni documento, marcato o no, con la sua scrittura e la sua regione. Anche un documento in una lingua scritta da destra a sinistra (arabo, persiano, urdu, ebraico…) dichiara la sua lingua: le forme specifiche della lingua del font (`locl`) e il font di ripiego la seguono.

```ts
const config: PostextConfig = {
  locale: 'es',
  bodyText: { textAlign: 'justify', hyphenation: { enabled: true } }, // hyphenates in Spanish
};
```

#### Cifre del documento

`numerals` di primo livello imposta le cifre di ogni numero che il motore scrive: i numeri di pagina e le etichette di pagina dell’indice, dell’indice analitico e dei rimandi alle pagine; i numeri degli elenchi numerati e delle note; i contatori dei titoli e dei capitoli, `{chapterNumber}`; i `{h1}` e `{n}` del numero di una figura e di un rimando a essa; `{totalPages}`, `{bookTotalPages}` e `{numberDecimal}`. `'latn'` scrive 0–9, `'arab'` le cifre indo-arabe ٠–٩ e `'arabext'` le cifre persiane ۰–۹. Cambia solo il formato decimale (`decimal`, l’`arabic` degli elenchi, o un’impostazione lasciata al suo valore predefinito), quindi un formato indicato dall’autore viene stampato come indicato: `lower-roman` resta i, ii, iii, e `arabic-indic` in un documento latino scrive comunque ١, ٢, ٣. Il testo del documento non viene mai riscritto.

Il valore predefinito, `'auto'`, prende le cifre di `locale` (`defaultNumeralsFor(tag)`): `'arab'` per l’arabo senza regione o con qualsiasi regione fuori dal Maghreb (`ar`, `ar-EG`, `ar-SA`, `ar-AE`…), `'latn'` per `ar-MA`, `ar-DZ`, `ar-TN`, `ar-LY`, `ar-MR` e `ar-EH`, `'arabext'` per il persiano (`fa`), il pashto (`ps`) e l’urdu dell’India (`ur-IN`), e `'latn'` per tutto il resto, compreso l’urdu del Pakistan. CLDR dà `latn` per un `ar` semplice e per `ar-AE`; i libri arabi del Mashriq e del Golfo stampano ٠–٩, ed è questo che segue Postext. Un tag che indica le proprie cifre le conserva: `ar-MA-u-nu-arab`. Una pagina numerata con le cifre del documento registra `arabic-indic` o `persian` come suo `pageNumberFormat`, così le etichette di pagina del PDF mostrano le stesse cifre. Un valore sconosciuto segue la lingua e viene segnalato come `unknownNumerals`.

I numeri digitati dall’autore vengono letti in uno qualsiasi dei tre sistemi: una voce di elenco `٣.` comincia da 3, e `{startAt=٥}`, `:::numbering{startAt=٥}`, `:::space{lines=٢}` e `:::part{number="٣"}` (per `{numberDecimal}`) leggono il valore.

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

#### Direzione del testo

`direction` di primo livello imposta la direzione di base del documento: `'ltr'`, `'rtl'`, o `'auto'` (il valore predefinito), che vale `'rtl'` quando la scrittura di `locale` si scrive da destra a sinistra (arabo, persiano, urdu, ebraico, siriaco, thaana, N’Ko, adlam…, letta da `directionOf(tag)`) e `'ltr'` negli altri casi. Un documento da destra a sinistra viene impaginato in una cornice specchiata: le righe cominciano a destra, la prima colonna è quella di destra, i rientri, i marcatori di elenco, gli elementi flottanti, le note a piè di pagina e i riquadri stanno a destra, e [`page.binding: 'auto'`](https://postext.dev/it/docs/configuration-page-layout.md#rilegatura) lo rilega a destra. La configurazione risolta contiene `direction: 'rtl'` solo per un documento del genere, quindi un documento da sinistra a destra si risolve come prima. Un valore sconosciuto viene letto come `'auto'` e segnalato come `unknownConfigValue`. L’algoritmo bidirezionale Unicode (UAX #9) ordina i tratti di ogni riga in entrambe le direzioni: una citazione araba in un libro inglese si legge da destra a sinistra al suo posto.

All’interno del documento, un titolo o un contenitore `:::` accetta `{dir=ltr}` o `{dir=rtl}`, e `:ltr[…]` e `:rtl[…]` in linea isolano un tratto di testo (vedi [La direzione del testo nel markup](https://postext.dev/it/docs/document-format.md#la-direzione-del-testo-nel-markup)); una risorsa tabella accetta `table.direction`. Un blocco composto in direzione opposta a quella del documento conserva il proprio lato d’inizio: il rientro, i marcatori di elenco e l’estremità allineata della sua ultima riga passano al lato da cui comincia il suo testo.

Un’impostazione che nomina un lato indica un lato del testo o del flusso del corpo, mai del foglio, quindi un progetto grafico pensato per un libro inglese funziona quando il libro passa all’arabo. `'start'` ed `'end'` sono accettati come nomi espliciti:

| Impostazione | `'left'` / `'right'` | `'start'` / `'end'` |
| --- | --- | --- |
| `textAlign` del testo corrente, dei titoli, degli stili di paragrafo, delle parti, delle note a piè di pagina e dei corpi dei riquadri; `align` della didascalia e della nota della didascalia | I lati del testo: `'left'` è il lato da cui comincia una riga, la destra di un paragrafo arabo, dove va l’ultima riga di un paragrafo giustificato. | Sinonimi di `'left'` e `'right'`. Le configurazioni risolte contengono `'left'` / `'right'`; quelle salvate conservano ciò che è stato scritto. |
| `align` della cella di tabella | I lati del testo della cella, letti nella direzione della tabella (`table.direction`). | Sinonimi, letti nella direzione della tabella. |
| `placement.align` (elementi flottanti, figure strette) | I lati del flusso del corpo: in un libro da destra a sinistra `'left'` è la destra del foglio. | Sinonimi. |
| `stripe.side`, `icon.cornerSide`, `labelTab.position` (`'top-start'`, `'top-end'`) di un riquadro | I lati del flusso del corpo, gli stessi per ogni riquadro della pagina. | La direzione propria del riquadro (un `:::callout{dir=ltr}` in un libro arabo comincia dalla sinistra del foglio). |
| Spazi dell’intestazione e del piè di pagina; elementi grafici ancorati al foglio | I lati del foglio. | Solo elementi di testo: l’inizio e la fine della `direction` propria dell’elemento. |

`placement.rotate` mantiene il suo significato fisico su una pagina specchiata: una figura ruotata in senso orario è ruotata in senso orario sul foglio. Un host che legge l’impaginazione trova la cornice specchiata su ogni pagina (`VDTPage.flow` con `direction: 'rtl'`, `pageIsMirrored(page)`) e l’ordine visivo dei segmenti di ogni riga in `VDTLine.order`; `flowToPage` e `pageToFlow` convertono tra il flusso e il foglio. Vedi [Impaginazione araba](https://postext.dev/it/docs/arabic-layout.md#direzione-e-algoritmo-bidirezionale).

```ts
const arabic: PostextConfig = { locale: 'ar' };                        // right to left, bound on the right
const english: PostextConfig = { locale: 'en', direction: 'rtl' };     // forced; rarely what you want
```

### Lingue e scritture

Postext compone le scritture alfabetiche da sinistra a destra, e il cinese e il giapponese in orizzontale e in verticale. [Impaginazione cinese](https://postext.dev/it/docs/chinese-layout.md) e [Impaginazione giapponese](https://postext.dev/it/docs/japanese-layout.md) spiegano come vengono composti e quali impostazioni li controllano; le chiavi sono in [Tipografia dell’Asia orientale](https://postext.dev/it/docs/configuration-east-asian.md#tipografia-dellasia-orientale), [Scrittura verticale](https://postext.dev/it/docs/configuration-page-layout.md#scrittura-verticale) e [Rilegatura](https://postext.dev/it/docs/configuration-page-layout.md#rilegatura). Che cosa riceve ogni scrittura:

- **Il cinese** viene composto dal compositore CJK quando un paragrafo contiene più caratteri CJK che spazi tra parole: le sue righe vanno a capo tra i caratteri secondo le regole di inizio e fine riga di `cjk.lineBreak` (nessuna riga comincia con 。、」 o ー, nessuna termina con 「 o （), tengono interi —— e ……, un numero con i suoi segni e una parola latina, e una riga giustificata viene distribuita tra i suoi caratteri fino alla giustezza. Le larghezze della punteggiatura, la punteggiatura sporgente, lo spazio tra han e latino, la griglia dei caratteri, i punti di enfasi, i segni dei nomi propri e dei titoli di libri, il ruby e le note warichu seguono la regione di `locale`, in orizzontale o in verticale (`layout.writingMode: 'vertical-rl'`). Un paragrafo latino che cita qualche parola CJK mantiene la divisione in righe ottimale e può andare a capo accanto a esse; una parentesi CJK, il punto mediano o un segno a larghezza piena citati in un testo latino (〈h〉, ％) non cambiano nulla.
- **Il giapponese** passa dallo stesso compositore con regole proprie da postext 1.16, quelle dei *Requirements for Japanese Text Layout* (JLReq) del W3C e di JIS X 4051: un locale `ja` dà la regione `japan`, i cui valori automatici impostano i livelli di kinsoku di JLReq (i kana piccoli e ー non aprono mai una riga), la punteggiatura a larghezza piena con compressione delle coppie, un em dopo ？！, la parentesi che apre un paragrafo nella seconda metà del rientro, i segni di enfasi a sesamo sopra il testo, i titoli di libri tra 『』, i furigana spaziati 1:2:1, i classificatori giapponesi, le note e un indice analitico ordinato per lettura. Le versioni precedenti componevano il giapponese con i valori predefiniti del cinese continentale.
- **Il coreano** passa dallo stesso compositore e viene composto senza sillabazione, ma con i valori predefiniti del cinese continentale: le sue regole proprie (KLREQ) non sono implementate. Il testo coreano va a capo tra le sillabe oltre che ai suoi spazi.
- **L’arabo e le altre scritture da destra a sinistra** (persiano, urdu, ebraico…) vengono composti da destra a sinistra: [Impaginazione araba](https://postext.dev/it/docs/arabic-layout.md) spiega come. La [`direction`](https://postext.dev/it/docs/configuration-text.md#direzione-del-testo) del documento viene dalla scrittura di `locale`, l’algoritmo bidirezionale Unicode ordina le parole latine e i numeri dentro ogni riga, il libro è rilegato a destra con la prima colonna a destra, e ogni numero che il motore scrive prende le [cifre](https://postext.dev/it/docs/configuration-text.md#cifre-del-documento) della regione. Una parola che contiene una lettera in scrittura araba non viene mai sillabata, spaziata o tagliata, e una riga araba giustificata si allunga negli spazi e con le kashida. I segni vocalici, l’enfasi, le note a piè di pagina e le diciture dell’arabo sono in [Testo arabo](https://postext.dev/it/docs/configuration-text.md#testo-arabo). Persiano, urdu ed ebraico ricevono la direzione, le cifre e le regole delle parole intere, ma non hanno diciture predefinite proprie.

I pattern di sillabazione sono inclusi per otto lingue (`en-us`, `es`, `fr`, `de`, `it`, `pt`, `ca`, `nl`); i tipi di risorsa predefiniti e le diciture di continuazione esistono in queste otto, in cinese, in giapponese e in arabo. Il cinese, il giapponese, il coreano e le lingue scritte da destra a sinistra vengono composti senza sillabazione. Qualsiasi altra lingua viene sillabata con i pattern dell’inglese americano, con un avviso nella console, e riceve le diciture inglesi. Per un documento del genere, imposta `hyphenation.enabled: false` e passa `resourceTypes` e le diciture di continuazione di `tableStyle` nella sua lingua.

### Testo arabo

Queste impostazioni servono al testo in scrittura araba; nessuna cambia un documento scritto in un’altra scrittura. [Impaginazione araba](https://postext.dev/it/docs/arabic-layout.md) le spiega insieme al resto di un libro arabo: direzione, rilegatura, cifre, versi, indice e indice analitico.

- **Segni vocalici e interlinea.** I segni vocalici di un testo vocalizzato (fatḥa, kasra, shadda, tanwīn, l’alif soprascritta, i segni coranici) si impilano sopra e sotto le lettere, nello spazio dell’interlinea, che non cresce mai per loro. Ogni riga che contiene segni registra fin dove arriva il loro inchiostro (`VDTLine.markInk`), e il ritaglio della colonna dei renderer include i segni della prima e dell’ultima riga di una colonna. Quando un segno sopra una parola tocca le lettere o i segni che pendono sotto la parola soprastante, la compilazione segnala il paragrafo (`arabicMarksExceedLeading`, nel pannello Verifiche della Sandbox). Vengono confrontate solo le parole che stanno l’una sopra l’altra. Il testo parzialmente vocalizzato richiede circa 1,7–1,85 em di `lineHeight`, i versi vocalizzati per intero 1,9–2,1 em.
- **Enfasi.** Il carattere arabo non ha corsivo, quindi in un documento il cui `locale` si scrive in caratteri arabi `*…*` viene composto in grassetto per impostazione predefinita (`bodyText.emphasis: 'auto'`). `'color'` lo compone in tondo con `italicColor`, e `'overline'` traccia un filetto sopra le parole, il khaṭṭ fawqī dei libri arabi. L’impostazione raggiunge ogni testo composto nei caratteri del testo corrente: paragrafi, elenchi, citazioni, stili di paragrafo, corpi dei riquadri, note e titoli. Le didascalie, le celle di tabella, l’indice e l’indice analitico mantengono le proprie impostazioni di corsivo. Qualunque sia la scelta, il motore non inclina mai le lettere arabe: le parole arabe di un tratto composto in corsivo restano diritte e le sue parole latine mantengono il corsivo. In un documento del genere una citazione è in tondo per impostazione predefinita.
- **Tashkīl.** `bodyText.tashkil: 'strip'` toglie i segni vocalici e coranici dal testo che l’impaginazione compone, per un’edizione non vocalizzata ricavata da una sorgente vocalizzata: fatḥa, ḍamma, kasra e i loro tanwīn, sukūn, shadda, l’alif soprascritta (هٰذا diventa هذا) e i segni U+0656–U+065F e U+06D6–U+06ED. `'strip-vowels'` conserva la shadda, come la stampa la maggior parte dei libri moderni. Hamza e madda restano (أ إ آ sono lettere, anche quando sono digitate con segni combinanti). La sorgente conserva i suoi segni; le righe, i titoli e l’indice vengono composti senza, e ogni carattere composto continua a corrispondere alla sua posizione nella sorgente.
- **Note a piè di pagina.** `footnotes.markerTemplate: '({n})'` scrive i richiami «(١)» con le cifre del documento, `numbering: 'page'` li fa ricominciare a ogni pagina, e `noteNumberPosition: 'inline'` mette il numero proprio della nota sulla riga. Il filetto separatore e i numeri delle note stanno all’inizio della colonna, a destra in un libro da destra a sinistra.
- **Parole intere.** Una parola che contiene una lettera in scrittura araba non viene mai sillabata, tagliata o spaziata, in un libro arabo o citata in un altro. Uno stile che imposta `letterSpacing` su testo arabo viene segnalato (`joiningScriptLetterSpacing`), e una parola più larga della sua riga sborda e viene segnalata (`unbreakableWordOverflow`). Vedi [Impaginazione araba](https://postext.dev/it/docs/arabic-layout.md#shaping-e-parole-intere).
- **Kashida e versi.** Una riga araba giustificata si allunga con le kashida oltre che negli spazi (`bodyText.kashida`, vedi [La kashida nel testo arabo](https://postext.dev/it/docs/justification.md#la-kashida-nel-testo-arabo)), e una poesia classica viene composta un bayt per riga in due emistichi di uguale larghezza con `:::verse` (vedi [`:::verse`](https://postext.dev/it/docs/document-format.md#verse)).
- **Indice analitico.** Un indice analitico in arabo ordina in ordine alfabetico e ignora l’articolo ال (`index.ignoreArticle`), i segni vocalici e i supporti della hamza; vedi [Indice analitico](https://postext.dev/it/docs/configuration-notes-references.md#indice-analitico).

### Orfane, vedove, righe finali corte e regole per tenere unito

Vedi [Sillabazione e giustificazione](https://postext.dev/it/docs/justification.md) per i meccanismi dietro queste penalità. Questa sezione è il riferimento per le chiavi di `bodyText` che le governano.

Oltre ai limiti di sillabazione e di spaziatura, la configurazione del testo corrente espone le regole morbide che evitano divisioni dei paragrafi strutturalmente goffe. Tutte entrano nell’algoritmo di divisione in righe di Knuth-Plass come penalità (demerit): orientano l’impaginazione verso divisioni pulite senza mai imporre una regola rigida. Imposta a `0` i valori `*Penalty` per disattivare di fatto una qualsiasi di esse.

| Proprietà | Tipo | Predefinito | Descrizione |
| --- | --- | --- | --- |
| `avoidOrphans` | `boolean` | `true` | Scoraggia un paragrafo dal finire con meno di `orphanMinLines` righe in cima alla colonna successiva. Su una griglia di caratteri (`cjk.grid`) nella regione `japan` il valore predefinito è `false`. |
| `orphanMinLines` | `number` | `2` | Numero minimo di righe richieste in cima alla colonna successiva quando un paragrafo viene diviso. Attivo solo quando `avoidOrphans` è `true`. |
| `orphanPenalty` | `number` | `1000` | Penalità aggiunta quando un vincolo sulle orfane viene violato. Valori più alti spingono l’algoritmo con più forza contro le orfane; `0` disattiva la penalità. |
| `avoidOrphansInLists` | `boolean` | `true` | Se `true`, anche le voci di elenco ricevono la protezione dalle orfane (non solo i paragrafi). Ha effetto solo quando `avoidOrphans` è `true`. |
| `avoidWidows` | `boolean` | `true` | Scoraggia un paragrafo dal cominciare con meno di `widowMinLines` righe in fondo alla colonna corrente. Su una griglia di caratteri (`cjk.grid`) il valore predefinito è `false`: la pagina contiene le righe che conta la sua griglia. |
| `widowMinLines` | `number` | `2` | Numero minimo di righe richieste in fondo alla colonna corrente quando un paragrafo viene diviso. Attivo solo quando `avoidWidows` è `true`. |
| `widowPenalty` | `number` | `1000` | Penalità aggiunta quando un vincolo sulle vedove viene violato. `0` disattiva la penalità. |
| `avoidWidowsInLists` | `boolean` | `true` | Se `true`, anche le voci di elenco ricevono la protezione dalle vedove. Ha effetto solo quando `avoidWidows` è `true`. |
| `shortListSplit` | `'allow' \| 'warn' \| 'avoid'` | `'allow'` | Un elenco breve diviso tra due colonne o pagine: un elenco di al massimo `shortListMaxItems` voci nel testo corrente, come uno di tre voci composto 1 + 2. `avoidOrphansInLists` e `avoidWidowsInLists` tengono unite le righe di una voce; questa regola tiene unite le voci di un elenco. `'allow'` divide un elenco del genere dove finisce la colonna, come qualsiasi altro. `'warn'` lo impagina allo stesso modo e segnala ogni elenco diviso (un avviso `shortListSplit`, vedi [Avvisi nel documento](https://postext.dev/it/docs/configuration-programmatic-usage.md#avvisi-nel-documento)). `'avoid'` compone l’elenco intero: quando non ci sta nello spazio rimasto nella colonna apre la colonna successiva, e i titoli subito sopra e la riga con i due punti che lo introduce (`keepColonWithList`) lo seguono. Un elenco più alto di una colonna vuota viene diviso come qualsiasi altro, e segnalato. Gli elenchi dentro un `:::callout` seguono le regole di divisione del riquadro, e le voci di `:::toc` e `:::index` non sono elenchi. Da postext 1.28. |
| `shortListMaxItems` | `number` | `3` | Il numero massimo di voci che un elenco può avere per contare come breve ai fini di `shortListSplit`, comprese le voci dei suoi elenchi annidati. Un numero intero, almeno 1. Da postext 1.28. |
| `avoidRunts` | `boolean` | `true` | Scoraggia i paragrafi dal finire con un’ultima riga molto corta (in inglese *runt*), per esempio una sola parola breve isolata. Anche il testo in bandiera, con `optimalRagged`. Un paragrafo cinese, giapponese o coreano non termina su una riga che contiene un solo carattere, da solo o con i suoi segni di chiusura (孤字): la riga precedente gli cede il suo ultimo carattere quando quella riga può ancora essere giustificata entro il limite di tracking. Anche una riga allineata a sinistra, a destra o centrata cede il carattere e resta più corta di un carattere; con `cjk.grid.fullLines` (carta da manoscritto) conserva ogni quadretto, e il paragrafo può terminare su un carattere. |
| `runtMinCharacters` | `number` | `20` | Soglia per l’ultima riga di un paragrafo, contata in spazi tra parole, non in lettere: la riga è troppo corta quando è più stretta di `runtMinCharacters × normalSpaceWidth` pixel. Uno spazio tra parole è da un quarto a un terzo di em nella maggior parte dei caratteri da testo, circa mezza lettera minuscola, quindi il valore predefinito 20 coglie le ultime righe sotto 4–7 em, cioè all’incirca da 8 a 12 lettere. Per cogliere le ultime righe sotto circa N lettere, impostalo intorno a 2 × N. |
| `runtPenalty` | `number` | `1000` | Badness equivalente inserita nella formula delle penalità al quadrato di Knuth–Plass (sulla stessa scala della *badness* della riga, che satura a 10000). `0` disattiva la penalità. |
| `gradedRuntPenalty` | `boolean` | `false` | Gradua la penalità per la riga finale corta in base a quanto è corta l’ultima riga: un’ultima riga di larghezza *w* sotto la soglia *t* costa `runtPenalty × (1 − w / t)` invece dell’intera penalità. Una chiusa di due parole costa allora meno di una di una parola, e l’algoritmo porta giù una parola quando una riga sopra può cederla ('…sallies of' / 'our minds.' invece di '…sallies of our' / 'minds.'). Disattivato per impostazione predefinita: ogni riga finale corta costa lo stesso, e l’algoritmo mantiene le righe più strette sopra. |
| `avoidRuntsInLists` | `boolean` | `true` | Se `true`, anche le voci di elenco ricevono la penalità per la riga finale corta. Ha effetto solo quando `avoidRunts` è `true`. |
| `tightenRunts` | `boolean` | `true` | Quando la penalità non è riuscita a evitare una riga finale corta, compone invece il paragrafo con una riga in meno: gli spazi tra le parole si stringono (mai oltre `minWordSpacing`) e, se questo da solo non basta a far rientrare la riga, si aggiunge un po’ di tracking negativo. Una composizione più corta viene rifiutata, e la riga corta resta, quando allargherebbe una riga giustificata oltre `maxWordSpacing` o, quando il paragrafo ha già una riga giustificata più lasca, oltre quella riga, oppure quando comporrebbe in bandiera più righe (oltre 3× lo spazio normale) di quante ne avesse il paragrafo. Gli spazi tra le parole del testo in bandiera mantengono la loro larghezza, quindi lì interviene solo il tracking. Richiede `optimalLineBreaking` e `avoidRunts` (e `optimalRagged` per il testo in bandiera). |
| `maxRuntTracking` | `number` | `10` | Tracking massimo che la correzione di una riga finale corta può prendere, in millesimi di em (l’unità di InDesign: 10 = 0,01 em per carattere), applicato come restringimento. `0` lascia la correzione alla sola spaziatura tra le parole. |
| `slackWeight` | `number` | `10` | Peso applicato al costo al quadrato dello «spazio di colonna inutilizzato». Valori più alti fanno preferire all’impaginazione colonne riempite in modo serrato; `0` disattiva del tutto questa pressione. |
| `keepColonWithList` | `boolean` | `true` | Quando un paragrafo termina con i due punti che introducono direttamente un elenco, tiene l’ultima riga con i due punti unita all’elenco: se collocare il paragrafo non lasciasse spazio perché la prima voce dell’elenco cominci nella stessa colonna o pagina, l’ultima riga (o l’intero paragrafo, se è di una sola riga) viene spostata nella colonna successiva insieme all’elenco. Quanto spazio basta lo stabilisce `colonListRoom`. Quando questa regola spingerebbe avanti l’intero paragrafo e una serie di titoli lo precede subito nella colonna, anche quei titoli vengono portati avanti, così `headings.keepWithNext` continua a valere. |
| `colonListRoom` | `'item' \| 'line'` | `'item'` | Lo spazio che `keepColonWithList` chiede sotto la riga con i due punti. `'item'`: ciò che le regole delle orfane e delle vedove per gli elenchi lascerebbero della prima voce al piede della colonna, una riga quando la voce si può dividere lì, tutta la voce quando la tengono intera (una voce di due righe, per esempio). `'line'`: una riga, come fino a postext 1.4; una prima voce che quelle regole tengono intera passa allora da sola alla colonna successiva e lascia al piede la riga con i due punti. Una configurazione salvata prima di `configVersion` 6, in un libro che introduce un elenco con i due punti, viene letta con `'line'` (vedi [Pacchetti scritti da postext 1.4 o precedenti](https://postext.dev/it/docs/configuration-programmatic-usage.md#pacchetti-scritti-da-postext-14-o-precedenti)). Qualsiasi altro valore viene letto come `'item'`. |
| `hyphenateAcrossColumns` | `boolean \| 'withinPage'` | `true` | Consente a una colonna o a una pagina di terminare con una parola sillabata (il *Hyphenate Across Column* di InDesign). `false` divide di nuovo in righe il paragrafo che attraversa il cambio di colonna, in modo che la sua ultima riga nella colonna termini con una parola intera; gli spazi tra le parole delle righe sopra assorbono la differenza, entro `maxWordSpacing` e `minWordSpacing`. È una preferenza: dove nessuna divisione entro quei limiti lo evita, il trattino resta. Prova ogni cambio di colonna di un paragrafo: il primo, e quelli successivi che cadono dove finisce una colonna piena, in una nuova divisione; e un cambio successivo che cade altrove (una vedova conservata, un livellamento di fascia) in un’altra, a partire da quella colonna, che lascia ai loro a capo le righe già composte nelle colonne precedenti e divide solo il resto. `'withinPage'` protegge le righe che chiudono una pagina e nessun’altra: una parola può essere divisa tra due colonne di una stessa pagina, e l’ultima riga di una pagina termina con una parola intera ovunque i limiti lo consentano. Cambia meno righe di `false`, il che conta con tre o più colonne, dove due fine colonna su tre stanno dentro la pagina; in una sola colonna i due valori danno le stesse righe. Una colonna chiude la sua pagina quando nessuna colonna successiva della pagina riceve testo: non la riceve una colonna laterale riservata agli elementi flottanti, né una colonna riempita da una tabella o da una figura. I corpi dei riquadri non sono interessati. Con `optimalRagged`, un paragrafo in bandiera viene diviso di nuovo allo stesso modo: i suoi spazi tra le parole mantengono la loro larghezza, quindi si spostano solo le estremità delle righe. Ogni nuova divisione misura il paragrafo un’altra volta, quindi un libro con molti trattini a fine colonna si impagina un po’ più lentamente. Richiede `optimalLineBreaking`, e `optimalRagged` per il testo in bandiera. |
| `paragraphContainerSpacing` | `'collapse' \| 'add'` | `'collapse'` | Lo spazio sotto un contenitore `:::paragraphs` che si chiude su un paragrafo, tra quel paragrafo e il blocco che segue (vedi [Il contenitore `:::paragraphs`](https://postext.dev/it/docs/configuration-styles.md#il-contenitore-paragraphs)). `'collapse'`: il maggiore tra lo `spaceBetween` e il `marginBottom` dello stile e la spaziatura tra paragrafi del testo intorno al contenitore (una riga con `paragraphSpacing`; in un riquadro, quella del riquadro), fuso con lo spazio che il blocco successivo tiene sopra di sé, come tra due paragrafi del testo corrente: un titolo sotto una bibliografia sta al suo `marginTop` sotto di essa, non a quel margine più la spaziatura delle voci. `'add'`: come fino a postext 1.4, sotto l’ultima riga viene messo solo lo spazio dello stile prima dell’allineamento alla griglia, lo spazio proprio del blocco successivo viene aggiunto sotto, e la spaziatura tra paragrafi viene esclusa, quindi il paragrafo dopo il contenitore poteva finire più vicino a esso che a qualsiasi altro. Una configurazione salvata prima di `configVersion` 8 che dichiara uno stile di paragrafo, in un libro che contiene un contenitore del genere, viene letta con `'add'` (vedi [Pacchetti scritti da postext 1.4 o precedenti](https://postext.dev/it/docs/configuration-programmatic-usage.md#pacchetti-scritti-da-postext-14-o-precedenti)). Un `marginBottom` negativo tira su il blocco successivo in entrambi i casi. Uno stile di paragrafo può impostare una regola propria per i suoi contenitori (`containerSpacing`, da postext 1.28). |

**Le righe finali troppo corte.** Una riga finale troppo corta (runt) è l’ultima riga di un paragrafo troppo breve per sembrare una vera riga di testo: di solito una o due parole brevi rimaste isolate alla fine del paragrafo. Poiché la verifica si basa sulla lunghezza in pixel della riga rispetto alla larghezza normale dello spazio, `runtMinCharacters` si adatta automaticamente al corpo del carattere in uso. Una parola breve visivamente più larga di `runtMinCharacters × spaceWidth` va bene; una parola più stretta (o davvero isolata) attira la penalità. La soglia conta spazi tra parole, larghi circa la metà delle lettere: il valore predefinito 20 corrisponde a un’ultima riga di circa 8–12 lettere. Ogni riga finale corta costa l’intera penalità, quindi tra due chiuse sotto la soglia l’algoritmo mantiene le righe più strette sopra; `gradedRuntPenalty` invece le valuta in base a quanto sono corte, e vince la chiusa più lunga. Per chi è curioso della matematica: con la `runtPenalty` predefinita di 1000, evitare una riga finale corta prevale su qualsiasi insieme alternativo di a capo che richieda un allargamento della spaziatura tra le parole fino a circa r≈2,15.

**Morbide, non rigide.** Nessuna di queste regole può *impedire* una divisione: il motore produce sempre un’impaginazione. Sono penalità: l’algoritmo bilancia badness, costo della sillabazione, regolarità delle classi di riempimento e queste penalità strutturali in un’unica ottimizzazione globale e sceglie l’insieme di a capo con il costo totale più basso. Se ti serve una garanzia più forte, alza la penalità; se un certo documento si legge meglio con la penalità allentata, abbassala.

## Titoli

La proprietà `headings` controlla la tipografia di tutti i livelli di titolo (H1–H6). Puoi impostare valori predefiniti generali che valgono per tutti i livelli, e poi sovrascrivere proprietà specifiche per ciascun livello.

### Valori predefiniti generali

| Proprietà | Tipo | Predefinito | Descrizione |
| --- | --- | --- | --- |
| `fontFamily` | `string` | `'Open Sans'` | Famiglia di caratteri per tutti i titoli. |
| `lineHeight` | `Dimension` | `1.2 em` | Interlinea dei titoli. Più stretta di quella del testo del corpo. |
| `color` | `ColorValue` | Colore principale (`#295AA3`) | Colore del testo dei titoli. Collegato alla voce `main-color` della palette predefinita, quindi cambiando il colore della palette si ritingono tutti i titoli. |
| `textAlign` | `'left' \| 'justify' \| 'center' \| 'right' \| 'start' \| 'end'` | `'left'` | Allineamento di tutti i livelli di titolo (non esiste un valore per livello): a bandiera a sinistra, giustificato, centrato o a bandiera a destra. Un titolo giustificato compone l’ultima riga allineata a sinistra, come un paragrafo, quindi un titolo di una riga si legge come `'left'`. Canvas, HTML e PDF collocano le righe allo stesso modo, prefisso numerico compreso. Anche l’apertura predefinita di un titolo `span: 'page'` senza un progetto grafico avanzato lo segue (il giustificato si compone allineato a sinistra); un progetto grafico avanzato allinea i propri elementi di testo con il loro `align`. |
| `fontWeight` | `number` | `700` | Peso del carattere dei titoli (100–900). |
| `marginTop` | `Dimension` | `1.5 em` | Spazio sopra i titoli. Viene eliminato per un titolo che apre una colonna (vedi `columnHeadSpace`). |
| `marginBottom` | `Dimension` | `0.5 em` | Spazio sotto i titoli. |
| `keepWithNext` | `boolean` | `true` | Con `true`, un titolo non viene mai collocato come ultimo elemento di una colonna o di una pagina. Se il blocco successivo non avesse spazio per almeno `bodyText.widowMinLines` righe dopo il titolo (o per una riga quando `bodyText.avoidWidows` è `false`), il titolo viene spinto avanti così da restare unito al suo testo. Interagisce con `bodyText.keepColonWithList`: se quella regola deve spostare per intero un paragrafo che termina con i due punti, gli eventuali titoli che lo precedono nella colonna si spostano con esso invece di restare isolati. |
| `keepWithNextSpread` | `boolean` | `false` | Con `keepWithNext`, permette comunque a un titolo di chiudere l’ultima colonna di testo di una pagina pari, dato che il suo testo apre allora la pagina dispari a fronte della stessa doppia pagina (JLReq §4.1.7). Le doppie pagine sono la pagina 1 da sola, poi 2–3, 4–5…, contate con `pageIndexOffset`, nei libri rilegati a sinistra come in quelli rilegati a destra. Da postext 1.16. |
| `keepWithNextSplit` | `'rules' \| 'fill'` | `'rules'` | Come si divide il paragrafo sotto un titolo quando il titolo finisce al piede di una colonna e spostare per intero il paragrafo lascerebbe indietro il titolo. `'rules'`: il maggior numero di righe che entrano, purché almeno `bodyText.widowMinLines` restino sotto il titolo e almeno `bodyText.orphanMinLines` passino alla colonna successiva; quando nessuna divisione rispetta entrambe le condizioni, il titolo si sposta con il suo paragrafo, e il bilanciamento delle colonne riempie lo spazio che lascia. `'fill'`: quante più righe entrano, per poche che ne passino oltre, quindi un paragrafo di quattro righe con spazio per tre si divide 3 + 1. Fino a postext 1.4 ogni titolo si divideva così, e le configurazioni salvate prima di `configVersion` 8 mantengono questo comportamento (vedi [Pacchetti scritti da postext 1.4 o precedenti](https://postext.dev/it/docs/configuration-programmatic-usage.md#pacchetti-scritti-da-postext-14-o-precedenti)). Con `avoidWidows` o `avoidOrphans` disattivati, quel lato della regola viene abbandonato. |
| `snapToGrid` | `boolean` | `true` | Se il flusso torna sulla griglia della linea di base sotto un titolo. Con `true` il `marginBottom` del titolo viene arrotondato per eccesso a righe intere della griglia; con `false` si mantiene il margine esatto e il testo sotto il titolo può restare fuori griglia fino al punto di allineamento successivo (la fine di un elenco, una coda di `:::paragraphs`, una formula in display), come molti libri compongono una riga e mezza sotto un titolo. Un livello (`levels[].snapToGrid`) o uno stile di titolo può impostare un valore proprio; questo è quello che ereditano. |
| `columnHeadSpace` | `'none' \| 'remainder'` | `'none'` | Che cosa conserva del suo spazio superiore un titolo allineato alla griglia quando apre una colonna, in testa alla pagina o sotto una figura o una tabella in testa alla colonna. `'none'`: l’intero spazio viene eliminato e il titolo sta sulla prima riga della colonna, alla stessa altezza della colonna accanto; l’allineamento alla griglia mette poi sotto il titolo la frazione di riga che gli serve, quindi il suo testo può trovarsi più lontano da esso che dopo un paragrafo. `'remainder'`: lo spazio viene eliminato solo per righe intere della griglia e la frazione di riga che resta rimane sopra il titolo, così il testo sotto di esso comincia alla distanza a cui comincia dopo un paragrafo; il titolo comincia un po’ più in basso della testa della colonna e nessuna riga del testo del corpo si sposta. È adatto a un libro a una colonna, dove nessuna testa di colonna accanto mostra la differenza. Qualsiasi altro valore si legge come `'none'`. Non sotto un’apertura a tutta larghezza, e non per un titolo `span: 'page'`, `lineSpan`, nascosto o con progetto grafico (`advancedDesign`). Da postext 1.28. |
| `inlineMarks` | `boolean` | `true` | Se un titolo legge i suoi marcatori in linea come fa un paragrafo: `*italic*`, `**bold**`, `^superscript^`, `~subscript~`, `:smallcaps[…]` e i link. Un tratto in corsivo inverte l’inclinazione del titolo, quindi esce in tondo in un titolo in corsivo; un tratto in grassetto prende `bodyText.boldFontWeight`, o il peso proprio del titolo quando questo è più pesante. Anche l’indice riporta i tratti in grassetto e in corsivo; le testatine e i segnalibri PDF stampano solo il testo. Con `false` i marcatori vengono eliminati e le parole vengono stampate nello stile proprio del titolo, come fino a postext 1.4. Anche l’apertura predefinita di un titolo `span: 'page'` senza progetto grafico compone i tratti in grassetto, corsivo, apice e pedice; un progetto grafico del titolo (una banda di apertura progettata o un `advancedDesign` in colonna) stampa `{titleText}` come testo semplice in entrambi i casi, a meno che il suo elemento di testo non legga i marcatori in linea (`inlineMarks: true`): lì `{titleText}` mantiene i tratti in grassetto, corsivo e apice/pedice del titolo (da postext 1.19). Le configurazioni salvate in precedenza i cui titoli contengono marcatori vengono lette con `false` (vedi [Pacchetti scritti da postext 1.4 o precedenti](https://postext.dev/it/docs/configuration-programmatic-usage.md#pacchetti-scritti-da-postext-14-o-precedenti)). |
| `balancing` | `ColumnBalancingConfig` | attivo | Bilanciamento verticale delle colonne: spazio extra sopra i titoli perché le colonne finiscano a filo con il fondo della pagina. Vedi sotto. |

Titoli centrati per poesie o per gli atti di un’opera teatrale, senza slot di progetto grafico:

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

Passare un oggetto `headings` mantiene tutti i valori predefiniti dei livelli che non riscrivi, compresa l’interruzione di pagina dell’H1 (vedi [Sovrascritture per livello](https://postext.dev/it/docs/configuration-text.md#sovrascritture-per-livello)).

### Bilanciamento delle colonne

Gli editori si aspettano che ogni colonna cominci in cima alla pagina e finisca a filo con il suo fondo. Le regole di interruzione (protezione da orfane e vedove, titoli tenuti con il loro testo, figure indivisibili) lasciano per natura colonne corte: una o più righe vuote della griglia della linea di base in fondo. Quando il bilanciamento è attivo, il motore fa ciò che farebbe un compositore, applicando le sue leve in ordine di priorità editoriale:

1. **Un riquadro che chiude la colonna**: un riquadro che termina una colonna corta viene spinto in basso esattamente dello spazio che ha sotto il piede, così il suo bordo inferiore cade sull’ultima posizione della griglia della pagina, alla stessa altezza dell’ultima riga della colonna accanto. Prende quello spazio anche quando è meno di una riga, purché nulla passi in un’altra colonna. Per impostazione predefinita agisce prima di ogni altra leva e prende l’intero vuoto, quindi un riquadro che commenta il paragrafo sopra di esso può finire diverse righe più in basso; `closingBox: 'last'` lascia che i titoli, le fine degli elenchi e le altre leve di spaziatura prendano prima le righe intere, e al riquadro solo ciò che lasciano, e `closingBox: 'off'` non lo sposta mai.
2. **Immagini con una zona sicura**: un’immagine con una zona sicura (`Resource.safeArea`, vedi [Formato del documento › Zona sicura](https://postext.dev/it/docs/document-format.md#zona-sicura)) composta in linea nella colonna corta, o flottante in testa o al piede di essa sopra quella sola colonna, cresce di righe intere della griglia, ritagliata entro la sua zona sicura, finché la colonna non è piena o il ritaglio non raggiunge la zona sicura. Un’immagine più alta non lascia buchi nella pagina, quindi agisce prima che si aggiunga qualsiasi spazio; un elemento flottante in testa a una colonna in una pagina o in una banda le cui teste di colonna restano allineate (vedi sotto) non cresce. Registrata come `flexFigure`. Non ha un’impostazione propria: può crescere solo un’immagine la cui risorsa indica una zona sicura.
3. **Titoli**: si aggiungono righe intere della griglia al margine superiore dei titoli all’interno della colonna corta. Quando servono più righe e la colonna contiene più titoli, le righe vengono distribuite tra di essi, dando sempre la quota maggiore al titolo più importante (un `h2` ne riceve più di un `h3`). I titoli che stanno proprio in cima a una colonna non ricevono mai spazio extra, così le colonne continuano a cominciare in cima alla pagina, tranne un titolo subito sotto una figura o una tabella in testa alla sua colonna in una pagina che prosegue: lo spazio va sopra quel titolo, sotto la figura. Un titolo prende al massimo `maxLinesBeforeLoose` righe in questo modo (due per impostazione predefinita) prima di provare le leve sottostanti, e le righe ulteriori, fino a `maxLinesPerHeading`, solo quando queste non hanno più nulla da dare.
4. **Fine degli elenchi**: quando i titoli non riescono ad assorbire l’intero vuoto, si aggiunge una riga della griglia dove finisce un elenco o un’enumerazione (lo spazio dopo un elenco risulta naturale), con un limite per ogni fine di elenco.
5. **Sotto formule, riquadri e figure**: poi una riga della griglia va sotto una formula in display o un riquadro dopo cui il testo riprende (`stretchAfterDisplays`; si legge come il margine proprio dell’elemento), e sotto una figura o una tabella in testa alla colonna (`stretchAfterFloats`, limitato da `maxLinesAfterFloat`).
6. **Paragrafi allargati**: come ultima risorsa, un paragrafo della colonna viene ridiviso con una riga in più (il `\looseness=+1` di TeX), scegliendo il paragrafo più lungo così che la spaziatura extra tra le parole si diluisca senza vedersi. La soluzione allargata viene accettata solo quando ogni riga resta **sotto `bodyText.maxWordSpacing`**: il colore tipografico non supera mai il limite che hai già configurato. Richiede `bodyText.optimalLineBreaking`.

Su una griglia dei caratteri (`cjk.grid`, vedi [Impaginazione cinese › La griglia dei caratteri](https://postext.dev/it/docs/chinese-layout.md#la-griglia-dei-caratteri)) ogni carattere sta in una cella larga un em e ogni riga sul passo di riga della griglia, che è anche la griglia della linea di base. Lì il bilanciamento è disattivato per impostazione predefinita, come nel testo verticale: una pagina composta riga per riga su una griglia, come la GB/T 9704 conta 22 righe di 28 caratteri, lascia corta una colonna corta. Una configurazione che imposta `enabled: true` ottiene leve che rispettano la griglia: titoli, fine degli elenchi, formule in display e figure prendono righe intere della griglia, così il testo sotto di essi si sposta di righe intere, e `gridLines: 'off'` le esclude per uno standard che non ha righe vuote da cedere. Un paragrafo cinese o giapponese si allunga di una riga solo quando nessuno spazio tra due dei suoi caratteri si allarga oltre `maxTracking`, e non prende tracking sulle lettere: una riga a cui manca un carattere distribuisce un em sui suoi spazi, molto oltre il valore predefinito di 0,01 em, quindi su una griglia di celle intere la leva dei paragrafi allargati di solito non trova nulla. Il riquadro che chiude una colonna e le immagini con una zona sicura sono per costruzione fuori griglia e funzionano come ovunque.

L’ultima colonna di una pagina viene bilanciata solo quando la pagina prosegue naturalmente nella successiva: la pagina di chiusura di un capitolo può legittimamente finire corta. Una pagina del genere, e una banda di chiusura livellata da `trailing`, mantiene anche le teste di colonna allineate: non si aggiunge alcuna riga sotto una figura o una tabella in testa a una delle sue colonne (la leva dopo gli elementi flottanti), e un titolo o un riquadro che apre una colonna sotto una figura del genere resta in testa, qualunque cosa dica `stretchAfterFloats`, come il titolo composto subito sotto un’apertura `span: 'page'` nella colonna propria dell’apertura, così una colonna non comincia mai più in basso di quella accanto solo per allineare i piedi.

| Proprietà | Tipo | Predefinito | Descrizione |
| --- | --- | --- | --- |
| `enabled` | `boolean` | `true` | Se bilanciare il fondo delle colonne. Disattivato per impostazione predefinita nel testo verticale (`layout.writingMode: 'vertical-rl'`) e su una griglia dei caratteri (`cjk.grid.enabled`, da postext 1.25); `true` lo attiva anche lì. |
| `maxLinesPerHeading` | `number` | `4` | Numero massimo di righe extra della griglia che si possono aggiungere sopra un singolo titolo. |
| `maxLinesBeforeLoose` | `number` | `2` | Righe della griglia che un titolo può prendere prima di provare le leve che lo seguono: le fine degli elenchi, le formule e i riquadri, le figure e i paragrafi allargati. Un titolo ottiene le righe ulteriori, fino a `maxLinesPerHeading`, solo quando quelle non hanno più nulla da dare, così una pagina con un solo titolo non apre quattro righe sopra di esso mentre i suoi paragrafi potrebbero allungarsi di una riga. Un valore pari o superiore a `maxLinesPerHeading` dà prima ai titoli tutte le loro righe, come fino a postext 1.27; `0` prova le altre leve prima che qualsiasi riga vada sopra un titolo. Da postext 1.28; i documenti salvati in precedenza mantengono il vecchio ordine (`pinLegacyLooseOrder`). |
| `stretchAfterLists` | `boolean` | `true` | Permette righe extra della griglia dove finisce un elenco, quando i titoli non riescono ad assorbire l’intero vuoto. |
| `maxLinesAfterList` | `number` | `1` | Numero massimo di righe extra della griglia dopo la fine di un singolo elenco. |
| `stretchAfterDisplays` | `boolean` | `true` | Permette una riga extra della griglia sotto una formula in display, e sotto un riquadro, nella colonna corta, dopo la leva della fine degli elenchi: il blocco che segue scende di una riga. Impostalo su `false` per lasciare lo spazio sotto formule e riquadri come lo stabiliscono i loro margini; il vuoto passa alle leve successive, e la colonna finisce corta se non lo chiudono. Da postext 1.28. |
| `stretchAfterFloats` | `boolean` | `true` | Permette righe extra della griglia sotto una figura o una tabella in testa alla colonna corta (un elemento flottante in alto), dopo la leva della fine degli elenchi, così il testo sotto di essa scende invece di lasciare corta la colonna. Mai in una pagina che non prosegue (la pagina di chiusura di un capitolo) né in una banda di chiusura livellata da `trailing`: lì le teste di colonna restano allineate e l’ultima colonna può finire una riga più corta. Il primo blocco sotto la figura può essere il resto di un paragrafo cominciato nella pagina precedente: scende comunque, della riga che le regole di interruzione hanno lasciato libera al piede della colonna (una riga che la regola delle vedove ha tenuto vuota, o uno spazio tra paragrafi senza spazio per il testo successivo). Impostalo su `false` per tenere il testo subito sotto la figura. Sotto un elemento flottante su più colonne le colonne si spostano insieme o per niente, vedi `stretchAfterWideFloats`. |
| `maxLinesAfterFloat` | `number` | `1` | Numero massimo di righe extra della griglia sotto un singolo elemento flottante in alto. |
| `stretchAfterWideFloats` | `'flush' \| 'always'` | `'flush'` | Sotto una figura o una tabella che sta sopra due o più colonne di testo. Con `'flush'` una colonna scende sotto di essa solo quando ogni colonna di testo sotto l’elemento flottante prende le stesse righe, così le loro teste restano allineate, o quando le righe fanno finire quella colonna a filo; una riga che abbasserebbe la testa di una colonna lasciandola comunque corta non viene aggiunta, e il vuoto passa ai paragrafi allargati. `'always'` allunga una colonna del genere come sotto qualsiasi elemento flottante, come fino a postext 1.27. Qualsiasi altro valore si legge come `'flush'`. Da postext 1.28; i documenti salvati in precedenza mantengono `'always'` (`pinLegacyWideFloatStretch`). |
| `looseParagraphs` | `boolean` | `true` | Ultima risorsa: ridivide i paragrafi di una colonna corta in modo più largo (una riga in più ciascuno), entro `bodyText.maxWordSpacing`. |
| `maxLooseParagraphs` | `number` | `2` | Quanti paragrafi di una colonna corta possono allungarsi di una riga, a partire dal più lungo. |
| `trackParagraphs` | `boolean` | `true` | Quando la sola spaziatura tra le parole non basta a guadagnare la riga, un paragrafo allargato può prendere anche il tracking (spaziatura tra lettere) positivo più piccolo che ci riesce. |
| `maxTracking` | `number` | `10` | Limite superiore di quel tracking, in millesimi di em per carattere (10 = 0,01 em). |
| `trailing` | `boolean` | `true` | Livella la banda di chiusura di un capitolo e del documento: quando il flusso finisce prima che la pagina sia piena (a un’apertura di capitolo, a un `:::part`, a un riquadro `placement: 'fixed'` che chiude il capitolo o alla fine del documento) con le colonne disuguali, queste vengono tagliate alla stessa altezza (un limite di banda di `ceil(Σ used / N / grid)` righe, risolto dopo che le leve sopra hanno sistemato le pagine precedenti), così una bibliografia breve finisce alla stessa altezza in ogni colonna invece di riempire la prima colonna e lasciare l’ultima mezza vuota. Il taglio rispetta le regole che rispetta una banda non tagliata: quando un blocco che non può dividersi sul taglio (la coda di un paragrafo che i minimi di orfane e vedove tengono intera, un riquadro da tenere unito) lo supererebbe (e perderebbe le ultime righe, dato che i renderer ritagliano una colonna al suo riquadro) o un titolo chiuderebbe una colonna mentre il suo testo apre la successiva (con `headings.keepWithNext`, il valore predefinito), il taglio viene spostato una riga più in basso, fino a tre volte, e altrimenti abbandonato. Un blocco che non può cominciare nelle righe che il taglio lascia sotto una figura in testa a una colonna (lì un paragrafo ha bisogno del suo minimo di orfane) passa invece alla colonna successiva della banda, come farebbe da una colonna non tagliata, e la figura resta da sola nella sua colonna. Le colonne i cui piedi differiscono di una riga della griglia o meno restano come sono: una banda di chiusura la cui ultima colonna finisce una riga più corta è la conclusione abituale, e tagliarla sposterebbe solo una riga. Il taglio va alla banda in cui è stato misurato, e così il taglio che un riquadro a tutta larghezza chiede a metà pagina: fino a postext 1.4, quando il primo testo della pagina di chiusura era stato prima proposto a una banda senza spazio per esso (una pagina occupata per intero da un elemento flottante, la banda sottile che un riquadro a tutta larghezza lascia al piede della pagina precedente), il taglio veniva speso su quella banda e la pagina di chiusura teneva tutte le righe nella prima colonna. Le colonne di larghezze diverse (un’impaginazione a colonna e mezza con testo in entrambe) vengono tagliate per area, con l’altezza di ogni colonna pesata sulla sua larghezza, dato che una riga della colonna stretta contiene meno testo. Attivo solo quando `enabled` è true. |
| `trailingStep` | `'lines' \| 'grid'` | `'lines'` | L’unità del taglio livellato che prende `trailing` (e del taglio che prende `beforeSpan` dietro un riquadro che si sposta oltre). `'lines'`: una banda il cui testo è composto con un’interlinea propria (un indice analitico, una bibliografia, un contenitore in corpo minore) viene tagliata, e ritentata, per righe intere di quell’interlinea: l’altezza condivisa dalla maggior parte delle righe della banda, titoli e riquadri esclusi. Le sue colonne finiscono allora entro una riga l’una dall’altra, come fa una banda di testo del corpo. Una banda di testo del corpo, e una che mescola due interlinee in parti uguali, viene tagliata sulla griglia della linea di base come prima. Così anche una banda le cui righe hanno la stessa altezza e distano tra loro una frazione di riga (voci bibliografiche con uno spazio tra una voce e l’altra, gruppi di un indice su un margine impostato a mano): quattro righe su cinque di ogni colonna devono distare tra loro un numero intero di righe. `'grid'`: ogni taglio è un numero intero di righe della griglia della linea di base, come fino a postext 1.27, quando un taglio sulla griglia lasciava entrare una riga in più in una colonna di una banda fuori griglia e un taglio fallito veniva abbassato di più di una delle sue righe (colonne distanti fino a tre righe). Qualsiasi altro valore si legge come `'lines'`. Da postext 1.28; i documenti salvati in precedenza mantengono `'grid'` (`pinLegacyTrailingStep`). |
| `beforeSpan` | `boolean` | `true` | Livella la banda che un blocco a tutta larghezza lascia dietro di sé: quando un riquadro `span: 'page'` non entra sotto le colonne correnti nemmeno dopo un taglio livellato, e deve passare alla pagina successiva o dividersi (`calloutStyles[].keepTogether: false`), le colonne che interrompe vengono tagliate alla stessa altezza (lo stesso limite finale che riceve una banda di chiusura) invece di avere la prima che riempie la pagina e l’ultima che finisce corta. La pagina viene lasciata come interruzione esplicita, così le leve sopra non riallungano la sua ultima colonna fino al fondo della pagina; il riquadro, o la parte che ne entra, si colloca poi sotto le colonne livellate. Attivo solo quando `enabled` è true. |
| `closingBox` | `'first' \| 'last' \| 'off'` | `'first'` | Quando un riquadro che chiude una colonna corta prende lo spazio sotto il suo piede (leva 1, registrata come `trailingCallout`). `'first'`: prima di ogni altra leva, come fino a postext 1.4; il riquadro prende l’intero vuoto, anche di diverse righe, e i titoli sopra di esso non ne ricevono. `'last'`: dopo le leve dei titoli, delle fine degli elenchi, delle formule in display e degli elementi flottanti, che prendono prima le righe intere; il riquadro scende con il testo sopra di esso e poi prende solo ciò che hanno lasciato, di solito una frazione di riga, così il suo piede raggiunge comunque l’ultima posizione della griglia e resta vicino al testo che commenta. `'off'`: mai; il riquadro mantiene lo spazio sotto il suo piede, anche se le altre leve possono comunque spostarlo in basso di righe intere quando aggiungono spazio sopra di esso, e la frazione di riga lasciata sotto rimane. In una pagina di chiusura, dove il riquadro è l’unica leva che allinea il suo piede con la colonna accanto, `'off'` lo lascia dove lo ha messo il flusso. Qualsiasi altro valore si legge come `'first'`. Un riquadro che chiude l’unica colonna di testo della sua banda (una pagina a una colonna che finisce prima, con il blocco successivo che apre la pagina seguente) non viene mai spostato: non c’è alcuna colonna accanto con cui allinearsi (da postext 1.19). |
| `gridLines` | `'allow' \| 'off'` | `'allow'` | Su una griglia dei caratteri: se possono agire le leve che aggiungono righe intere della griglia (sopra un titolo, dove finisce un elenco, sotto una formula in display o un riquadro, sotto una figura in testa alla colonna). Mantengono ogni carattere nella sua cella; `'off'` è adatto a uno standard che conta le righe di una pagina, e lascia invece corta la colonna. Nessun effetto fuori dalla griglia. Qualsiasi altro valore si legge come `'allow'`. Da postext 1.25. |

#### Quale leva è intervenuta

L’impaginazione registra ogni leva che ha applicato, sul blocco a cui l’ha applicata: `block.balancing` nel VDT che restituisce `buildDocument`. Una bozza, un test o un rapporto possono dire perché una colonna finisce a filo, e quali colonne nessuna leva è riuscita a chiudere. I blocchi che il bilanciamento ha lasciato stare non portano alcun `balancing`, e un documento costruito con `enabled: false` non ne ha.

Su una griglia dei caratteri il documento dice perché una colonna può finire corta: `doc.gridBalancing` è `{ off: true }` quando il bilanciamento è disattivato perché la pagina è su una griglia e la configurazione non lo attiva, e `{ gridLines: 'off' }` quando agisce senza le leve a righe intere; una colonna ancora corta porta `column.gridRefused`, le leve che la griglia le ha negato (`'looseParagraph'` quando un paragrafo poteva guadagnare la sua riga solo spostando i caratteri fuori dalle loro celle, le leve a righe intere con `gridLines: 'off'`). Entrambi sono assenti fuori dalla griglia.

```ts
interface VDTBalancing {
  levers: BalanceLever[]; // usually one: a paragraph after a list can take the list-end line and run a line long too
  spaceAbove: number;     // px the spacing levers added above the block (0 when only looseParagraph or flexFigure fired)
  bodyGrowth?: number;    // flexFigure: px the picture grew, cropped within its safe area
  extraLines?: number;    // looseParagraph: lines the paragraph gained
  tracking?: number;      // looseParagraph: the tracking that gained them, in thousandths of an em (0 = word spacing alone)
}
type BalanceLever = 'trailingCallout' | 'flexFigure' | 'heading' | 'listEnd' | 'afterDisplay' | 'afterFloat' | 'looseParagraph';
```

| Leva | Registrata su | Che cosa ha fatto |
| --- | --- | --- |
| `trailingCallout` | il blocco cornice del riquadro | Un riquadro che chiude la colonna è sceso esattamente dello spazio sotto il suo piede (`spaceAbove`; una frazione di riga va bene). |
| `flexFigure` | il blocco dell’immagine (in linea) o l’elemento flottante | Un’immagine con una zona sicura composta `bodyGrowth` px più alta, per righe intere della griglia, ritagliata entro la zona sicura. Il `bodySource` del blocco della risorsa è la parte mostrata e `bodyFlex.delta` la stessa crescita. |
| `heading` | il titolo | Righe intere della griglia sopra il titolo, fino a `maxLinesPerHeading`. |
| `listEnd` | il primo blocco dopo l’elenco | Una riga della griglia dove finisce un elenco, fino a `maxLinesAfterList`. |
| `afterDisplay` | il blocco dopo la formula o il riquadro | Una riga della griglia sotto una formula in display o un riquadro. |
| `afterFloat` | il primo blocco della colonna | Una riga della griglia tra una banda di elementi flottanti in testa alla colonna e il suo testo, fino a `maxLinesAfterFloat`. |
| `looseParagraph` | il paragrafo | Il paragrafo ridiviso con `extraLines` righe in più, con il tracking più piccolo che ci è riuscito (`tracking`; `block.letterSpacing` è lo stesso valore in px). |

I tagli livellati vengono registrati sulle colonne che tagliano: `column.bandCapped` è true su ogni colonna tagliata alla stessa altezza (la banda che lascia un riquadro a tutta larghezza, una banda di chiusura), e `column.trailingCap` segna inoltre la banda di chiusura di un capitolo o del documento (`trailing`).

```ts
import { buildDocument } from 'postext';

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

### Sovrascritture per livello

Ogni livello di titolo può sovrascrivere i valori predefiniti generali tramite l’array `levels`. Per impostazione predefinita cambia solo `fontSize` (più il `breakBefore` dell’H1, indicato sotto): tutte le altre proprietà vengono ereditate dalle impostazioni generali dei titoli.

| Livello | Corpo predefinito | `breakBefore` predefinito |
| --- | --- | --- |
| H1 | `18 pt` | `{ enabled: true, parity: 'always-odd' }` |
| H2 | `15 pt` | `{ enabled: false, parity: 'any' }` |
| H3 | `12 pt` | `{ enabled: false, parity: 'any' }` |
| H4 | `10 pt` | `{ enabled: false, parity: 'any' }` |
| H5 | `9 pt` | `{ enabled: false, parity: 'any' }` |
| H6 | `8 pt` | `{ enabled: false, parity: 'any' }` |

Il valore predefinito dell’H1 riproduce l’impaginazione dei capitoli di un libro: ogni titolo di primo livello si apre su una pagina destra (dispari) nuova, con una pagina bianca di separazione obbligatoria dopo il capitolo precedente. Sovrascrivilo in `levels[0].breakBefore` se il tuo documento è più semplice di un libro.

Il `breakBefore` di un livello si fonde campo per campo con quel valore predefinito, e un oggetto `headings` che non lo menziona lo mantiene. `{ parity: 'odd' }` sull’H1 mantiene l’interruzione e cambia solo la parità; `{ enabled: false }` lascia che i capitoli si susseguano senza interruzione:

```ts
headings: {
  fontFamily: 'Merriweather',                               // H1 still breaks to a fresh recto (always-odd)
  levels: [{ level: 1, breakBefore: { parity: 'odd' } }],    // …or: a recto, with no mandatory blank
}

headings: { levels: [{ level: 1, breakBefore: { enabled: false } }] } // chapters run on
```

**Cambiato in postext 1.5.** Fino a postext 1.4, qualsiasi oggetto `headings` disattivava l’interruzione dell’H1 a meno che `levels[0].breakBefore` non venisse riscritto, e un `breakBefore` parziale riempiva il campo mancante con il valore predefinito senza interruzione. Quindi una configurazione scritta in codice per la 1.4 con un oggetto `headings` e senza interruzione dell’H1 ora apre ogni capitolo su un recto nuovo, con versi bianchi dove servono. Per mantenere i capitoli di seguito, dai un campo alla voce H1 di `levels`:

```ts
headings: { fontFamily: 'Merriweather', levels: [{ level: 1, breakBefore: { enabled: false } }] } // as 1.4 laid it out
```

Dove la configurazione è stata salvata, il motore può accorgersene e lo fa per te: la Sandbox per i libri e le configurazioni che ha salvato allora (vedi **Sandbox → Persistenza**), e `openBundle` / `readBundle` per un pacchetto `.postext` scritto da postext 1.4 o precedenti (vedi [Pacchetti scritti da postext 1.4 o precedenti](https://postext.dev/it/docs/configuration-programmatic-usage.md#pacchetti-scritti-da-postext-14-o-precedenti)). Una configurazione che hai salvato da te può passare per `migrateConfig(config)` di `postext/bundle`, che scrive esplicitamente le interruzioni che la 1.4 impaginava (`pinLegacyHeadingBreaks`): `enabled: false` su un H1 che non aveva interruzione, e `parity: 'any'` accanto a un `enabled: true` che non indicava alcuna parità, sull’H1 e sugli stili dei titoli. Fissa anche la dimensione delle formule, lo spazio attorno alle figure in linea (anche nei riquadri), i marcatori in linea dei titoli, le dimensioni dei capilettera, lo spazio sotto una riga con i due punti che introduce un elenco, le righe di un paragrafo o di una voce di elenco che lascia il taglio di un riquadro, gli a capo ai trattini, la divisione riga per riga del testo a bandiera, la divisione di un paragrafo sotto un titolo, gli a capo al trattino di una parola composta e lo spazio sotto i contenitori `:::paragraphs`, come li componeva la 1.4. Passa il markdown del libro come terzo argomento, `{ content }`, ed esclude la fissazione delle formule quando il testo non ha `$`, quelle degli intervalli quando nessuna riga incorpora una risorsa (quella dell’intervallo nei riquadri quando nessuna lo fa dentro un riquadro), quella dei marcatori dei titoli quando nessun titolo contiene un marcatore, quella della riga con i due punti quando nessun elenco segue una riga che termina con i due punti, quella del taglio dei riquadri quando il testo non apre alcun `:::callout`, quella dei trattini quando nessun trattino è composto chiuso tra due parole, quella della divisione sotto i titoli quando il testo non ha titoli, quella dei contenitori quando il testo non apre alcun contenitore `:::paragraphs`, e quella delle parole composte quando nessun trattino sta tra due lettere; la fissazione della divisione a bandiera va solo a una configurazione che compone a bandiera una parte del testo corrente, e quella dei contenitori solo a una che dichiara uno stile di paragrafo (vedi [Pacchetti scritti da postext 1.4 o precedenti](https://postext.dev/it/docs/configuration-programmatic-usage.md#pacchetti-scritti-da-postext-14-o-precedenti)). Per le sole interruzioni, chiama `pinLegacyHeadingBreaks(config)`.

Le sovrascritture per livello supportano le stesse proprietà dei valori predefiniti generali (`fontSize`, `lineHeight`, `fontFamily`, `color`, `fontWeight`, `marginTop`, `marginBottom`, `snapToGrid`) più questi campi propri dei livelli (che accetta anche uno [stile di titolo](https://postext.dev/it/docs/configuration-styles.md#stili-dei-titoli)):

| Proprietà | Tipo | Predefinito | Descrizione |
| --- | --- | --- | --- |
| `italic` | `boolean` | `false` | Compone il titolo in corsivo. Si applica in aggiunta a `fontWeight`. |
| `textTransform` | `'none' \| 'uppercase'` | `'none'` | Mette in maiuscolo il titolo (un prefisso di numerazione resta come scritto, come pure un chip e l’etichetta di un `:ref` al suo interno). Conserva la lunghezza così la mappa del sorgente dell’editor resta 1:1: i caratteri la cui forma maiuscola si espande (`ß` → `SS`) restano come sono. Il titolo trasformato alimenta anche il segnaposto `{titleText}` dei progetti grafici avanzati e delle aperture di capitolo. I segnalibri PDF mantengono il titolo come è scritto (*Author contributions*, non *AUTHOR CONTRIBUTIONS*), come il `text-transform` del CSS lascia stare il testo vero e proprio (fino a postext 1.4 prendevano le maiuscole). |
| `letterSpacing` | `Dimension` | `0` | Tracking dopo ogni glifo del titolo, spazi e prefisso di numerazione compresi, come il `letter-spacing` del CSS. Un valore positivo spazia le lettere (le maiuscole composte con `textTransform: 'uppercase'` di solito ne vogliono un po’: `{ value: 0.12, unit: 'em' }`), uno negativo stringe un corpo da titolo. Un valore in `em` è relativo al `fontSize` del livello. Le righe del titolo vengono misurate con esso, quindi vanno a capo dove finisce il testo spaziato, e canvas, HTML e PDF lo dipingono allo stesso modo. La spaziatura tra le lettere non cambia mai i glifi: le legature del carattere (fi, fl) restano, in ogni output. Una riga centrata o allineata a destra viene collocata in base alle sue lettere: il tracking dopo l’ultimo glifo viene escluso, come nel testo di progetto grafico, così un titolo centrato si allinea con l’apertura predefinita di un titolo `span: 'page'`. Un livello disegnato dal suo `advancedDesign` lo ignora, come gli altri campi tipografici qui: ogni elemento di testo del progetto grafico ha il proprio `letterSpacing`. Lo imposta anche uno [stile di titolo](https://postext.dev/it/docs/configuration-styles.md#stili-dei-titoli), per i titoli che lo usano. Fino a postext 1.4 i titoli non avevano tracking, e la chiave veniva scartata senza avviso. |
| `lineSpan` | `number` | non impostato | Righe occupate (行取り, JLReq §4.1.6): il titolo viene composto in una banda di altrettante righe del corpo, con i caratteri centrati al suo interno, al posto di `marginTop` e `marginBottom`; `3` è un titolo 3行取り. La banda comincia su una riga del corpo quando il titolo si allinea alla griglia, e il testo che lo segue resta sulla griglia, in entrambe le direzioni di scrittura e con `cjk.grid`; un titolo le cui righe hanno bisogno di più spazio prende il numero intero successivo. Il centro è quello dei caratteri (la linea di base meno il centro ideografico del carattere), come lo misura JLReq, non quello dei riquadri delle righe. Non si applica alle aperture (`span: 'page'`), ai titoli disegnati da un `advancedDesign`, ai titoli nascosti né ai titoli dentro i riquadri. Uno stile di titolo può impostare `0` per togliere quello del suo livello. Da postext 1.16. |
| `indent` | `Dimension` | `0` | Rientro del titolo dall’inizio della riga (字下げ), dove `em` è il corpo del **testo**, come i libri giapponesi contano i rientri dei titoli in caratteri del corpo (JLReq §4.1.3): `{ value: 6, unit: 'em' }` è 6字下げ qualunque sia il corpo del titolo. La giustezza si restringe di quel valore, e un titolo centrato si centra nello spazio restante. Da postext 1.16. |
| `firstLineIndent` | `Dimension` | `0` | Rientro della sola prima riga del titolo, misurato da `indent` e, come questo, in em del **testo**: le righe su cui va a capo un titolo lungo cominciano a `indent` (all’inizio della riga quando non è impostato), come la GB/T 9704 compone ogni livello di titolo rientrato di due celle con il seguito al margine: `{ value: 2, unit: 'em' }`. Con `cjk.grid` attivo, due em del testo sono due celle della griglia. Un titolo numerato stampa il suo numero dopo il rientro, quindi il modello di numerazione non ha bisogno di spazi ideografici, che verrebbero stampati anche nell’indice e nei segnalibri PDF. Funziona nel testo verticale (dalla cima della riga), con il compositore CJK (una parentesi di apertura all’inizio del titolo segue le regole di inizio riga, come in un paragrafo) e con Knuth–Plass. Un titolo centrato lo applica come un paragrafo centrato: la sua prima riga si centra nello spazio dopo il rientro. `{firstLineIndent=N}` dopo il titolo di un titolo imposta quel solo titolo, e `{firstLineIndent=0}` toglie quello del suo livello. Da postext 1.24. |
| `jidori` | `number` | non impostato | Spaziatura uniforme (字取り): un titolo di una riga più stretto di altrettanti em **propri** viene spaziato uniformemente fino a quella larghezza esatta, quindi `3` compone 序章 come 序　章. I titoli più larghi e i titoli di più righe restano come sono. `{jidori=N}` dopo il testo di un titolo imposta quel solo titolo, e `{jidori=0}` disattiva quello del suo livello. Da postext 1.16. |
| `dropCap` | `ParagraphDropCap \| false` | nessuno | Un capolettera che apre il primo paragrafo del corpo dopo un titolo di questo livello (vedi [Capilettera](https://postext.dev/it/docs/configuration-text.md#capilettera)): una sola impostazione dà a ogni capitolo la sua iniziale. Un titolo lo disattiva con `{dropcap=false}` o ne imposta le righe con `{dropcap=2}`. Da postext 1.23. |
| `numberingTemplate` | `string` | `''` | Modello del numero automatico del livello. Un token `{1}` … `{6}` stampa il contatore corrente di quel livello di titolo, facoltativamente formattato da un suffisso (`{1:I}` romano maiuscolo, `{1:i}` romano minuscolo, `{1:A}` / `{1:a}` alfabetico, `{1:01}` con zeri iniziali, `{1:words}` in lettere (*twenty-one*), `{1:ordinal}` come ordinale (*twenty-first*), `{1:一}` in numeri cinesi (giapponesi in un documento giapponese: 第百一章), `{1:〇}` cifra per cifra, `{1:壹}` in numeri finanziari e `{1:①}` cerchiato, o qualsiasi nome di [Grafie dei formati di numerazione](https://postext.dev/it/docs/configuration-page-layout.md#grafie-dei-formati-di-numerazione)), e qualsiasi altro testo è letterale (`'Chapter {1}. '`, `'{1}.{2}'`, `'第{1:一}回'` per 第一百二十回; una barra rovesciata rende letterale una graffa). Un token il cui contatore è ancora vuoto scompare insieme al separatore adiacente. Vuoto (il valore predefinito) significa nessun numero automatico. Il numero composto viene anteposto al titolo nel flusso, alimenta il segnaposto `{number}` di uno slot di progetto grafico avanzato (dove il prefisso in sé non viene anteposto) e viene stampato nell’indice. Vedi [Numeri in lettere](https://postext.dev/it/docs/configuration-text.md#numeri-in-lettere) per le parole, e [Stili dei titoli](https://postext.dev/it/docs/configuration-styles.md#stili-dei-titoli) per un modello proprio su alcuni titoli di un livello. |
| `numberSeparator` | `string` | `' '` | Che cosa sta tra il numero e il titolo: nella colonna, nell’apertura predefinita di un livello `span: 'page'`, nelle testatine che stampano la riga del titolo e nei segnalibri PDF. Il separatore del livello 1 unisce anche il numero e il titolo di una parte nella pagina di parte predefinita e nella riga di parte predefinita dell’indice. I titoli di capitolo cinesi prendono uno spazio ideografico o nulla (`'　'`: 第一回　甄士隱夢幻識通靈). L’indice mantiene la propria colonna dei numeri (`toc.levels[].numberGap`). Uno [stile di titolo](https://postext.dev/it/docs/configuration-styles.md#stili-dei-titoli) può impostarne uno proprio. Quando un titolo viene spezzato in due con `\\`, come i titoli a distico dei romanzi cinesi, le forme su una riga (la colonna, l’indice, le testatine) uniscono le due metà con uno spazio ideografico quando entrambi i lati sono caratteri cinesi o giapponesi, e con uno spazio negli altri casi. |
| `numberPosition` | `'before' \| 'replace'` | `'before'` | Dove sta il numero generato. `'before'`: prima del titolo, unito da `numberSeparator`. `'replace'`: il numero è l’intero titolo e il titolo scritto nel sorgente non viene stampato, quindi `# Night` sotto `numberingTemplate: 'الليلة {1:ordinal-feminine}'` stampa الليلة الثانية. L’indice riporta il numero come titolo della voce (senza colonna dei numeri), e lo leggono anche le testatine (`{chapterTitle}`, `{titleText}`) e i segnalibri PDF; `{number}` è vuoto per un titolo del genere. Solo per i titoli numerati con un modello (quello del livello o del loro stile); qualsiasi altro mantiene il suo titolo. Uno [stile di titolo](https://postext.dev/it/docs/configuration-styles.md#stili-dei-titoli) può impostare il proprio, `'before'` per mantenere i titoli che il suo livello sostituirebbe. |
| `breakBefore` | `HeadingBreakBeforeConfig` | H1: `{ enabled: true, parity: 'always-odd' }` H2–H6: `{ enabled: false, parity: 'any' }` | Forza un’interruzione di pagina prima di ogni titolo di questo livello. `parity: 'odd'` / `'even'` vincola inoltre il lato della doppia pagina su cui si apre il titolo: se serve viene inserita una pagina bianca di riempimento (contata comunque nella numerazione delle pagine). `'always-odd'` / `'always-even'` garantiscono in più almeno una pagina bianca di separazione obbligatoria tra il contenuto precedente e il nuovo titolo (la pagina di separazione appartiene al capitolo precedente; l’eventuale ulteriore riempimento di parità appartiene a quello nuovo). Quando il titolo è il primissimo blocco del documento e la prima pagina è ancora vuota, il vincolo di parità viene saltato: il titolo finisce a pagina 1 come è scritto. Un campo non impostato mantiene il valore predefinito del livello: il `{ parity: 'odd' }` dell’H1 interrompe comunque. |
| `hidden` | `boolean` | `false` | Un titolo strutturale: non stampa nulla e non occupa spazio nella colonna né in un riquadro (niente testo, niente margini, nessuna banda di apertura) ma fa tutto il resto che fa un titolo. Il suo `breakBefore` apre comunque una pagina, apre la sezione del suo stile, viene contato (a meno che il suo stile non dica `numbered: false`), e viene elencato da `:::toc`, nominato dalle testatine `{chapterTitle}` e inserito nei segnalibri del PDF. Per una dedica, una pagina con epigrafe o un colophon di cui hanno bisogno l’indice e i segnalibri del lettore, ma che la pagina non mostra. Impostalo su uno [stile di titolo](https://postext.dev/it/docs/configuration-styles.md#stili-dei-titoli) piuttosto che su un intero livello; un titolo lo sovrascrive con `{hidden="true"}` / `{hidden="false"}`. |

```ts
headings: {
  fontFamily: 'Merriweather',
  levels: [
    // Canonical book preset: chapters on a right-hand (odd) page.
    { level: 1, fontSize: { value: 24, unit: 'pt' }, breakBefore: { enabled: true, parity: 'odd' } },
    { level: 2, fontSize: { value: 18, unit: 'pt' }, italic: true },
  ]
}
```

Anche `snapToGrid` funziona per livello. Se non impostato, un livello segue `headings.snapToGrid`; se impostato, lo sovrascrive, così un documento può comporre i suoi H2 una riga e mezza sopra il loro testo, fuori griglia fino al punto di allineamento successivo, mentre i suoi H3 arrotondano lo spazio sotto di essi a righe intere della griglia. Può impostarlo anche uno stile di titolo, per i titoli che lo usano.

```ts
headings: {
  marginBottom: { value: 1.5, unit: 'em' },
  levels: [
    { level: 2, snapToGrid: false }, // exactly 1.5 em under every H2
    { level: 3 },                    // inherits headings.snapToGrid: true
  ],
}
```

### Interruzione prima del titolo

`breakBefore` è indipendente dai controlli di numerazione: attivarlo forza un’interruzione di pagina, ma il contatore numerico si azzera solo quando inserisci esplicitamente una direttiva `:::numbering`. Le pagine bianche di parità contano come pagine vere nella sequenza e ricevono intestazioni e piè di pagina secondo le normali regole per pagine dispari e pari.

Un `:::pagebreak` subito prima di un titolo del genere non sostituisce la sua interruzione: il titolo applica comunque la sua parità dopo la pagina aperta dalla direttiva, il che può aggiungere una pagina bianca. Vedi [Stili dei titoli](https://postext.dev/it/docs/configuration-styles.md#stili-dei-titoli) per un titolo che deve cominciare subito dopo un’interruzione manuale.

#### Valori di parità

| Valore | Comportamento |
| --- | --- |
| `'any'` (predefinito) | Nessun vincolo di parità. Il titolo si apre semplicemente nella pagina successiva. |
| `'odd'` | Garantisce che il titolo si apra su una pagina dispari (destra). Una sola pagina bianca viene inserita solo quando la pagina successiva naturale è pari. |
| `'even'` | Lo stesso, ma per una pagina pari (sinistra). |
| `'always-odd'` | Garantisce **almeno una pagina bianca di separazione obbligatoria** tra il contenuto precedente e il nuovo titolo, poi assicura la parità dispari. Utile quando ogni capitolo deve cominciare in una doppia pagina nuova. |
| `'always-even'` | Lo stesso, ma per una pagina pari. |

#### A chi appartengono le pagine bianche

Le pagine bianche inserite da `breakBefore` portano intestazioni con il titolo del capitolo in base al *motivo* per cui sono state inserite:

- Le pagine inserite per soddisfare un vincolo di parità (`'odd'`, `'even'`, o la coda di parità di `'always-*'`) appartengono al capitolo **seguente**. Il loro segnaposto di intestazione `{chapterTitle}` si risolve nel titolo del nuovo capitolo, perché la pagina bianca esiste solo per portare il nuovo capitolo sulla parità corretta.
- La pagina di separazione obbligatoria iniziale inserita da `'always-odd'` / `'always-even'` appartiene al capitolo **precedente**. È una pausa voluta di fine capitolo, quindi l’intestazione `{chapterTitle}` mostra ancora il titolo del vecchio capitolo.

Le testatine e la palette di una sezione con stile (vedi [Stili dei titoli](https://postext.dev/it/docs/configuration-styles.md#stili-dei-titoli)) seguono le stesse due regole nelle pagine bianche.

#### Eccezione per l’inizio del documento

Quando il primissimo blocco del documento è un titolo con `breakBefore` attivo (o il sorgente si apre con `:::pagebreak`), il vincolo di parità viene saltato finché la prima pagina è ancora vuota. Il titolo finisce a pagina 1 come è scritto, qualunque sia la parità configurata, così un documento che comincia con un `# Chapter 1` configurato con `parity: 'odd'` non eredita una pagina bianca iniziale indesiderata. Una volta collocato un qualsiasi contenuto, il vincolo di parità funziona normalmente.

### Estensione e progetto grafico avanzato

Ogni livello di titolo accetta due campi aggiuntivi che controllano come il titolo viene composto come apertura di capitolo a tutta pagina.

| Proprietà | Tipo | Predefinito | Descrizione |
| --- | --- | --- | --- |
| `span` | `'column' \| 'page'` | `'column'` | Con `'page'`, il titolo viene trattato come apertura di capitolo e il suo progetto grafico avanzato (se attivo) viene collegato alla pagina come banda di apertura sopra il corpo. Abbinalo a `breakBefore.enabled: true` perché l’apertura cominci sempre una nuova pagina. Senza un progetto grafico proprio, il titolo viene dipinto da un’apertura predefinita su tutta l’area del contenuto, nella tipografia e nell’interlinea del livello, con i suoi tratti in grassetto, corsivo e apice/pedice (`headings.inlineMarks`), e la banda viene misurata a quella larghezza. La banda contiene ogni riga che l’apertura dipinge: dove l’apertura prende più righe della giustezza propria del titolo (un titolo giustificato i cui spazi si stringerebbero su una riga, un a capo forzato `\\`), le prende anche la banda. Fino a postext 1.4 la banda veniva misurata con il titolo diviso alla larghezza della colonna, quindi un titolo che entra in una riga dell’area del contenuto prendeva una banda alta due righe, con la riga centrata al suo interno. Le altre colonne cominciano sotto la banda come la colonna propria del titolo. Il testo che apre una di esse comincia dove comincerebbe il testo subito sotto l’apertura, qualunque cosa segua l’apertura nella sua colonna: il `marginBottom` dell’apertura sotto il suo titolo o il suo progetto grafico, portato alla riga successiva della griglia quando il livello si allinea. Un titolo, una formula in display o una riga dell’indice che apre una di esse viene composta alla stessa altezza del primo titolo o della prima formula in display sotto l’apertura, margini compresi come lì; quando la colonna dell’apertura prosegue con qualcos’altro, comincia dove comincia quel testo. Un titolo nascosto sotto l’apertura non conta, e lo spazio che il [bilanciamento delle colonne](https://postext.dev/it/docs/configuration-text.md#bilanciamento-delle-colonne) aggiunge sopra il titolo sotto l’apertura non viene ripetuto nelle altre colonne. Ciò che queste colonne allineano alla griglia cade sulla griglia della pagina. Fino a postext 1.4 il loro primo blocco stava al piede della banda: fuori griglia quando la banda finiva tra due righe, e addossato alla banda, senza margine, quando un titolo seguiva l’apertura (una riga più in alto di adesso quando la banda finiva sulla griglia); un titolo lì perdeva anche il margine superiore che manteneva il titolo della prima colonna. |
| `spanBreak` | `boolean` | `true` | Se un titolo `span: 'page'` comincia una nuova pagina. `true` apre la pagina successiva (con il lato scelto da `breakBefore`). `false`, con `breakBefore.enabled: false`, lo apre dove arriva il testo, come fa un riquadro a tutta larghezza: le colonne sopra di esso finiscono alla stessa altezza (la banda viene bilanciata quando `headings.balancing.trailing` è attivo), il progetto grafico o l’apertura predefinita del titolo viene composto su tutta l’area del contenuto sotto di esse, e il testo prosegue in ogni colonna sottostante: un secondo articolo di un notiziario sotto la fine del primo. Quando lo spazio rimasto non conterrebbe il titolo e il minimo di righe per le vedove sotto di esso, apre la pagina successiva come con `true`. Il ruolo della pagina resta quello che le dà il suo primo blocco. Nessun effetto su un titolo `span: 'column'`. Anche su uno stile di titolo. Da postext 1.19. |
| `advancedDesign` | `HeadingAdvancedDesignConfig` | `{ enabled: false, slot: { elements: [] } }` | Slot di progetto grafico a composizione libera per questo livello. Quando è `enabled`, gli elementi dello slot compongono l’apertura. Usa `{titleText}` dentro un elemento di testo per comporre il testo del titolo; usa `{number}`, `{numberRoman}`, ecc. per inserire il numero formattato del titolo. |
| `advancedDesign.minHeight` | `Dimension` | — | Altezza minima riservata al titolo nel flusso della colonna. Il titolo prende `max(design content bottom, minHeight)`, poi il `marginBottom` del titolo sotto di esso (dal suo stile di titolo, dal suo livello o da `headings.marginBottom`; 0,5 em del corpo del titolo per impostazione predefinita), e la somma viene arrotondata per eccesso alla griglia della linea di base quando i titoli si allineano. Così un’apertura può spingere in basso il testo del corpo (o reclamare l’intera pagina) anche quando i suoi elementi sono bassi o ancorati alle cornici della pagina o dell’abbondanza sopra il titolo. Per una banda alta esattamente `minHeight`, imposta quel `marginBottom` a 0 e fai di `minHeight` un numero intero di righe della griglia. Si applica ogni volta che `enabled` è true, anche con uno slot vuoto. Vedi [Altezza riservata](https://postext.dev/it/docs/configuration-text.md#altezza-riservata) per che cosa conta come fondo del contenuto del progetto grafico. |

**Un’apertura alta quanto la pagina.** Quando l’altezza riservata arriva oltre il piede della colonna (una copertina il cui `minHeight` è l’altezza della pagina, un’immagine o un riquadro ancorato alla pagina o all’abbondanza che scende fino al rifilo), l’apertura reclama il resto della pagina: il testo che la segue comincia nella pagina successiva, in ogni colonna di un’impaginazione a due colonne come di una a colonna e mezza. Una copertina quindi non ha bisogno di un `:::pagebreak` dopo di sé (metterlo non fa danni: non aggiunge alcuna pagina bianca). Un titolo in colonna (`span: 'column'`) il cui progetto grafico è più alto della colonna reclama quella colonna, e il testo comincia in testa alla successiva. Il blocco del titolo scende allora fino al piede della colonna che reclama, e il suo progetto grafico viene impaginato su quella banda: gli elementi ancorati in alto restano dove sono ancorati, e quelli che seguono la banda (ancorati al suo centro o al suo piede, o alti `'fill'`) si attengono allo spazio che il titolo reclama, come si attengono all’altezza riservata quando questa entra (fino a postext 1.4 il blocco manteneva l’altezza del suo testo, quindi quegli elementi venivano impaginati su una banda alta quanto il titolo, e il testo che seguiva scorreva sotto il progetto grafico). Gli elementi fissi della pagina che non devono reclamarla (una banda lungo il taglio esterno per tutta la pagina, un ornamento al piede della pagina) vanno invece nel progetto grafico dell’intestazione o del piè di pagina: ancorati a `'page'` o `'bleed'` e mostrati con `pages: 'opener'`, vengono dipinti nella pagina di apertura e non riservano spazio nel corpo.

Esempio: un’apertura di capitolo minimalista che mostra «Chapter N» sopra il titolo:

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

Segnaposto dei titoli disponibili nello slot di progetto grafico di un livello:

- `{titleText}`: il testo semplice del titolo (senza prefisso di numerazione). Un a capo forzato nel titolo (`\\`) è qui un a capo, in una banda di apertura come in un progetto grafico in colonna (fino a postext 1.4 un progetto grafico in colonna stampava lì uno spazio, mentre la sua altezza veniva misurata con l’a capo). Le righe in cui il titolo nascosto va a capo nella sua colonna vengono ricongiunte nel titolo come è scritto: una parola spezzata dopo il proprio trattino mantiene il trattino senza spazio dopo, una parola che la colonna ha diviso torna intera senza il trattino aggiunto dalla divisione, un gruppo legato da uno spazio indivisibile che era più largo della colonna ed è stato separato in quello spazio riprende il suo spazio indivisibile (`Capítulo XVIII`, non `CapítuloXVIII`), e ogni altro a capo restituisce il suo spazio. Fino a postext 1.4 ogni a capo diventava uno spazio, quindi un titolo andato a capo a un trattino stampava `Word- Book`, e un a capo forzato in un titolo del genere veniva eliminato.
- `{number}`: il numero formattato secondo il `numberingTemplate` del livello.
- `{numberDecimal}`, `{numberRoman}`, `{numberRomanLower}`, `{numberAlpha}`, `{numberAlphaLower}`: il contatore del titolo (il conteggio corrente del suo livello, qualunque cosa stampi il modello) in altri formati numerici: il terzo capitolo dà `3`, `III`, `iii`, `C`, `c`, con o senza un `numberingTemplate`. Un titolo non numerato (uno stile con `numbered: false`) li lascia vuoti.
- `{numberWords}`, `{numberWordsLower}`, `{numberOrdinalWords}`, `{numberOrdinalWordsLower}`: lo stesso contatore in lettere, con l’iniziale maiuscola o in minuscolo: *Three* / *three*, *Third* / *third* (vedi [Numeri in lettere](https://postext.dev/it/docs/configuration-text.md#numeri-in-lettere)).
- `{numberHan}`: lo stesso contatore in numeri cinesi, nella scrittura del `locale` del documento: un’apertura composta con `第{numberHan}回` stampa 第十二回 per il dodicesimo capitolo mentre l’indice riporta `12`.
- `{chapterNumber}`, `{chapterTitle}`, `{pageNumber}`, `{totalPages}`, `{bookTotalPages}`, `{title}`, `{subtitle}`, `{author}`, `{publishDate}`: segnaposto di metadati condivisi.
- `{attr.<key>}`: un attributo scritto sulla riga del titolo stessa (`# Title {author="I. Zango Martín"}`), che ripiega sull’attributo dell’H1 del capitolo corrente. Gli attributi mancanti si risolvono in una stringa vuota senza avviso.

`{chapterNumber}` stampa ciò che le testatine stampano per il capitolo: il numero dell’H1 quando il suo livello (o stile) ha un `numberingTemplate`, altrimenti l’ordinale del capitolo (`1`, `2`…, che prosegue oltre i capitoli impaginati prima di questo) e nulla per un capitolo non numerato o per uno stile il cui modello è `''`. Il progetto grafico di un titolo legge il capitolo a cui appartiene il suo titolo: un titolo di livello 1 il proprio, un titolo inferiore l’ultimo titolo di livello 1 che lo precede. Questo vale anche dove due capitoli si incontrano in una pagina, mentre le testatine di quella pagina stampano il capitolo successivo. L’altezza che un’apertura riserva viene misurata con quello stesso valore. Fino a postext 1.4 veniva misurata con il prefisso numerico del titolo (vuoto senza modello), quindi un progetto grafico la cui altezza dipende da `{chapterNumber}` poteva dipingere più in alto dello spazio che prendeva; e il progetto grafico stampava il capitolo della pagina, quindi il primo di due capitoli che condividono una pagina mostrava il numero del secondo.

I segnaposto dei contatori seguono il libro attraverso i capitoli impaginati uno alla volta (i contatori che passa `continuationAfter()`), e l’attributo `startAt` di un titolo li fa ripartire (vedi **Formato del documento → Attributi dei titoli**). Un’apertura che dice *Chapter III* sopra un titolo numerato `3.` nel flusso e nell’indice:

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

#### Altezza riservata

Un titolo con un progetto grafico avanzato occupa spazio nella colonna come qualsiasi blocco: il testo del corpo che lo segue comincia sotto quello spazio. Lo spazio è la maggiore di tre altezze, tutte misurate verso il basso dalla cima del titolo (la cima dell’area del contenuto per un’apertura che comincia la sua pagina):

1. il testo proprio del titolo, composto nella tipografia del livello (è nascosto sotto il progetto grafico, ma mantiene le sue righe);
2. il fondo del contenuto del progetto grafico: il bordo inferiore più basso tra gli elementi che contano (vedi sotto);
3. `advancedDesign.minHeight`.

Dopo di esso si aggiunge il `marginBottom` del titolo (dal suo stile di titolo, dal suo livello o da `headings.marginBottom`; 0,5 em per impostazione predefinita), e il risultato viene arrotondato per eccesso alla griglia della linea di base quando i titoli si allineano. Per un’apertura (`span: 'page'`) la stessa banda viene tenuta libera in ogni colonna della pagina. Per un titolo in colonna che entra nella sua colonna, il progetto grafico viene impaginato nel riquadro del titolo, che è alto esattamente quanto quello spazio.

**Quali elementi contano.** Conta ogni elemento del progetto grafico (testi, filetti, riquadri e immagini allo stesso modo; fino a postext 1.4 un elemento `image` non contava mai, quindi il testo poteva cominciare sopra l’immagine di una banda a meno che `minHeight` non lo tenesse lontano), tranne:

- **gli elementi con `reserve: false`**: decorazioni che possono stare sotto il testo;
- **gli elementi che seguono la banda stessa**: ancorati alla fila centrale del contenitore (`left`, `center`, `right`) o alla fila inferiore (`bottom-left`, `bottom`, `bottom-right`), con un’altezza `'fill'` rispetto al contenitore (un riquadro o un filetto verticale senza altezza lo riempie per impostazione predefinita), e qualsiasi elemento ancorato a uno di questi. Il contenitore è la banda riservata, quindi questi elementi stanno sul suo piede o la attraversano: un filetto sotto la banda, un pannello colorato dietro il titolo. Seguono l’altezza; non la stabiliscono mai. Un testo tra di essi che mantiene la propria altezza ha comunque bisogno di spazio: un titolo ancorato al piede della banda rende la banda alta almeno quanto il titolo, così il titolo non comincia mai sopra la cima del titolo strutturale. Con `minHeight: 36mm` e il titolo ancorato `bottom-left`, il riquadro del titolo è 36 mm più il suo `marginBottom`, arrotondato per eccesso alla griglia, e il titolo sta al piede di quel riquadro, subito sopra il testo che segue; senza `minHeight`, un titolo che prende più righe del testo proprio del titolo rende la banda profonda quanto il titolo. Fino a postext 1.4 un titolo del genere veniva dipinto in alto sopra il testo che precede il titolo. Riquadri, filetti e immagini che seguono la banda non stabiliscono un minimo del genere, quindi un pannello ancorato al piede può arrivare sopra il titolo.

Gli elementi ancorati alla pagina e all’abbondanza contano per quanto arrivano sotto la cima del titolo. Una banda in cima alla pagina che finisce sopra il titolo non conta nulla; un’immagine al vivo che va oltre spinge il testo in basso fino al suo bordo inferiore. Lo stesso fa qualsiasi cosa in basso nella pagina: un sigillo 25 mm sopra il piede della pagina, una banda laterale a tutta altezza o una cornice riservano la pagina fino al loro bordo inferiore, e il testo di solito comincia nella pagina successiva. Marca queste decorazioni con `reserve: false` (vengono comunque dipinte e gli elementi possono comunque ancorarsi a esse) e dai al titolo lo spazio di cui ha bisogno con i suoi elementi di testo o con `minHeight`:

```json
{
  "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 elemento ancorato a uno che non riserva spazio conta comunque, a meno che non sia marcato anch’esso (una didascalia posta sul sigillo ha bisogno di un proprio `reserve: false`).

**Dove viene dipinto.** Il progetto grafico di un’apertura (`span: 'page'`) viene disegnato prima del corpo, quindi le decorazioni che non riservano nulla stanno sotto il testo. Il progetto grafico di un titolo in colonna viene disegnato con il blocco del titolo (sopra i blocchi che lo precedono nella colonna, sotto quelli che lo seguono) ovunque sia collocato sopra il piede della sua colonna: anche nei margini laterali, nel margine superiore, nell’abbondanza e nelle colonne vicine. Il piede della colonna lo taglia, nel canvas e nel PDF, perché il flusso finisce lì (vedi **Più alto della colonna** qui sotto). Fino a postext 1.4 il canvas e il PDF lo tagliavano anche in cima alla sua colonna, quindi una banda ancorata alla cima della pagina o dell’abbondanza entrava nei margini laterali ma si fermava al margine superiore. Le decorazioni ancorate al piede della pagina vanno in un’apertura, o nel progetto grafico del piè di pagina con `pages: 'opener'`.

**Più alto della colonna.** Quando lo spazio arriva oltre il piede della colonna (un `minHeight` alto quanto la pagina, un’immagine o una cornice che scende fino al rifilo), il titolo reclama il resto della sua pagina (un’apertura, in ogni colonna) o della sua colonna (un titolo in colonna), e il testo che lo segue comincia nella pagina o nella colonna successiva. Il suo blocco scende allora fino al piede della colonna, senza mai essere riportato all’altezza del suo testo, quindi la banda su cui viene impaginato il suo progetto grafico è lo spazio che reclama (`minHeight` compreso, fino al piede). Un progetto grafico più alto della pagina stessa (un lungo attacco su una pagina di schermo piccola) viene comunque tagliato al piede della pagina (un progetto grafico in colonna, a quello della sua colonna): la Sandbox lo elenca nel pannello **Verifiche** come *Grafica del titolo tagliata*. L’impaginazione non solleva alcun avviso per questo (una copertina che reclama la sua pagina è il caso abituale e non perde nulla), ma qualsiasi host può eseguire lo stesso controllo sull’impaginazione finita: `collectHeadingDesignCuts(doc)` restituisce un `{ kind: 'headingDesignCut', pageIndex, level, where, overflowPx, sourceStart, sourceEnd }` per ogni titolo il cui testo di progetto grafico sta oltre il piede del rifilo della pagina (`where: 'page'`, un’apertura) o della sua colonna (`where: 'column'`), e `formatWarning` descrive ciascuno. Vedi **Un’apertura alta quanto la pagina** in [Estensione e progetto grafico avanzato](https://postext.dev/it/docs/configuration-text.md#estensione-e-progetto-grafico-avanzato).

**La colonna laterale.** In un’impaginazione a colonna e mezza la cui colonna laterale contiene elementi flottanti (`sideColumnRole: 'floats'`), un elemento del progetto grafico di un titolo in colonna che sta nella colonna laterale (un numero di capitolo ancorato alla pagina nella colonna del margine esterno dell’apertura di un manuale) tiene lontana da sé la pila laterale. Ogni figura, tabella o riquadro `span: 'side'` che la pagina colloca dopo il titolo mantiene un intervallo da elemento flottante libero da ognuno di questi elementi: resta dove la pila lo mette quando entra sopra l’elemento, e altrimenti va sotto di esso, oppure aspetta la pagina successiva quando il resto della colonna laterale non può contenerlo lì. Così un numero in testa al canale tiene sotto di sé l’intera pila, mentre un numero di sezione appeso nel margine accanto a un titolo più in basso nella pagina lascia la testa del canale alle figure che la pagina cita (la figura a margine sta comunque in cima alla sua pagina). Ciò che la colonna laterale contiene già quando il titolo viene collocato non viene spostato: una figura impilata prima nella pagina che scende fino all’elemento del titolo resta dov’è, sotto l’elemento, quindi un progetto grafico il cui elemento sta nella colonna laterale a metà pagina vuole le sue figure citate dopo il titolo. Gli elementi con `reserve: false` lasciano libera la colonna laterale, come lasciano libero il testo. Un’apertura (`span: 'page'`) non ha bisogno di nulla del genere: la sua banda è riservata in ogni colonna, colonna laterale compresa. Fino a postext 1.4 una figura laterale citata in un’apertura del genere veniva collocata in testa alla colonna laterale, sopra il numero.

**Copertine.** Un titolo di copertina che riempie la sua pagina (`minHeight` alto quanto la pagina, o un’immagine a tutta pagina nel suo progetto grafico) manda quindi da solo il testo che lo segue alla pagina successiva, nelle impaginazioni a una colonna come in quelle a più colonne. Un `:::pagebreak` subito dopo è facoltativo e non fa danni: un’interruzione di pagina in una pagina ancora vuota non fa nulla, quindi non aggiunge mai una pagina bianca. Serve solo quando il progetto grafico della copertina si ferma prima del piede della pagina e il testo deve comunque cominciare in una pagina nuova.

```md
# Annual report 2026 {style="cover"}

:::pagebreak

# Letter from the chair
```

### Numeri in lettere

Due suffissi dei modelli di numerazione scrivono un contatore in lettere, nella lingua del documento (il `locale` di primo livello, altrimenti il locale della sillabazione; vedi [Lingua del documento](https://postext.dev/it/docs/configuration-text.md#lingua-del-documento)): `words` per il cardinale e `ordinal` per l’ordinale. Le maiuscole e minuscole del suffisso stabiliscono quelle delle parole, come fa `A` / `a` per le lettere:

| Token | Inglese (21) | Spagnolo (21) | Cinese (21) |
| --- | --- | --- | --- |
| `{1:words}` | twenty-one | veintiuno | 二十一 |
| `{1:Words}` | Twenty-one | Veintiuno | 二十一 |
| `{1:WORDS}` | TWENTY-ONE | VEINTIUNO | 二十一 |
| `{1:ordinal}` | twenty-first | vigesimoprimero | 第二十一 |
| `{1:Ordinal}` | Twenty-first | Vigesimoprimero | 第二十一 |
| `{1:ORDINAL}` | TWENTY-FIRST | VIGESIMOPRIMERO | 第二十一 |

Inglese, spagnolo, cinese e arabo vengono scritti in lettere; qualsiasi altra lingua prende le parole inglesi, come fanno le stringhe predefinite di continuazione delle tabelle. Il cinese scrive i numeri informali di `simp-chinese-informal` o `trad-chinese-informal`, secondo la scrittura di `locale` (一万 / 一萬), con 第 davanti a un ordinale; i caratteri Han non hanno maiuscole, quindi le tre grafie di un suffisso stampano la stessa cosa. L’inglese segue l’uso americano (*one hundred five*, senza *and*). Lo spagnolo usa le forme maschili, come si numera un *capítulo* o un *libro* (*capítulo primero*, *tercero*, *veintiuno*), e scrive gli ordinali da 13 a 29 in una sola parola, come preferisce la RAE (*decimotercero*, *vigesimoprimero*). I cardinali vengono scritti in lettere fino a 999 999 e gli ordinali spagnoli fino a 999; i numeri più grandi vengono stampati in cifre.

I numeri arabi concordano nel genere con il nome che contano, quindi il suffisso accetta un modificatore: `-feminine` (o `-f`) per un nome femminile, `-masculine` (`-m`, il valore predefinito) per uno maschile; `-classical` scrive le centinaia مائة, come fanno Bulaq e la maggior parte delle stampe egiziane, invece del moderno مئة. `{1:ordinal}` scrive l’ordinale determinato al nominativo che usa un titolo: `الفصل {1:ordinal}` dà *الفصل الأول*, *الفصل الحادي عشر*, *الفصل الحادي والعشرون*; `الليلة {1:ordinal-feminine}` dà *الليلة الأولى*, *الليلة الحادية عشرة*, *الليلة الحادية والعشرون*, *الليلة المئتان*, e oltre il cento la formula classica con «dopo»: *الليلة الخامسة والأربعون بعد الثلاثمئة*, *الليلة الحادية بعد الألف*. `{1:words}` scrive il cardinale (واحد وعشرون; al femminile إحدى عشرة, واحدة وعشرون). Gli ordinali vengono scritti in lettere fino a 9 999 e i cardinali fino a 99 999; i modificatori si combinano (`{1:ordinal-f-classical}`), e le altre lingue li ignorano. L’arabo non ha maiuscole, quindi le maiuscole e minuscole del suffisso non cambiano nulla. I segnaposto di progetto grafico `{numberWords}` e `{numberOrdinalWords}` scrivono le forme maschili; per un’apertura al femminile, metti l’ordinale nel modello del livello e stampalo con `{number}`.

In un progetto grafico del titolo, `{numberWords}` / `{numberWordsLower}` e `{numberOrdinalWords}` / `{numberOrdinalWordsLower}` scrivono in lettere il contatore del titolo allo stesso modo, così l’apertura può dire *Chapter One* mentre l’indice riporta `1`. Il `textTransform: 'uppercase'` di un elemento di testo dà le maiuscole:

```ts
// Spanish novel: "CAPÍTULO PRIMERO" above the title, "1." in the contents.
{ 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}', /* … */ },
  ] } } }
```

## Elenchi puntati

La proprietà `unorderedLists` controlla come vengono resi gli elenchi puntati (`-`, `*`, `+`) e gli elenchi di attività GFM (`- [ ]`, `- [x]`). Sono supportati fino a cinque livelli di annidamento.

### Valori predefiniti degli elenchi puntati

| Proprietà | Tipo | Predefinito | Descrizione |
| --- | --- | --- | --- |
| `fontFamily` | `string` | eredita `bodyText.fontFamily` | Font usato per il testo delle voci. |
| `color` | `ColorValue` | Colore principale (`#295AA3`) | Colore del testo e del punto elenco delle voci. Collegato alla voce `main-color` della palette predefinita. |
| `fontWeight` | `number` | `700` | Peso del testo delle voci (100–900). I punti elenco ereditano questo peso, salvo personalizzazioni per livello. |
| `italic` | `boolean` | `false` | Compone il testo delle voci in corsivo. |
| `bulletChar` | `string` | `'•'` | Glifo usato come segno di elenco. |
| `bulletFontSize` | `Dimension` | `1 em` | Dimensione del glifo del punto elenco. Le unità relative seguono il corpo del testo corrente. |
| `gap` | `Dimension` | `0.5 em` | Spazio orizzontale tra il punto elenco e il testo della voce. |
| `indent` | `Dimension` | `0 em` | Rientro di base del livello 1. I livelli più profondi partono a cascata dall’inizio del testo del livello superiore, salvo personalizzazioni (vedi sotto). |
| `bulletVerticalOffset` | `Dimension` | `0 em` | Regola finemente la posizione verticale del punto elenco. I valori negativi lo spostano in su, quelli positivi in giù. |
| `marginTop` / `marginBottom` | `Dimension` | `1.5 em` | Spazio prima e dopo l’elenco nel suo insieme. |
| `itemSpacing` | `Dimension` | `0 em` | Spazio verticale aggiuntivo inserito tra le voci, oltre all’interlinea. Attorno a un elenco annidato in una voce di un altro, lo spazio dell’elenco esterno si applica su entrambi i lati, prima della prima voce dell’elenco annidato e dopo l’ultima (fino a postext 1.4 la voce che seguiva un elenco annidato prendeva lo spazio dell’elenco annidato). |
| `snapTopToGrid` | `boolean` | `false` | Arrotonda per eccesso lo spazio sopra l’elenco perché il primo punto elenco cada sulla griglia della linea di base, come fa il testo sotto un titolo; `marginTop` diventa allora un minimo. La fine di un elenco riporta comunque il flusso sulla griglia, quindi con `itemSpacing` a 0 ogni voce si allinea al testo della colonna accanto. Disattivato per impostazione predefinita, come fino a postext 1.4: un `marginTop` che non è un numero intero di righe lascia le voci fuori griglia fino alla fine dell’elenco. Gli elenchi dentro i riquadri, il cui interno è fuori griglia, non sono interessati. |
| `hangingIndent` | `boolean` | `true` | Se è attivo, le righe successive si allineano al primo carattere del testo anziché sotto il punto elenco. |
| `levels` | `UnorderedListLevelConfig[]` | — | Personalizzazioni per i livelli 1–5. Vedi sotto. |

### Estensioni per gli elenchi di attività

Le voci di attività GFM (`- [ ] …`, `- [x] …`) sono rese come voci di elenco puntato con una casella al posto del punto elenco. Il motore disegna la casella da sé, un quadrato vuoto con un segno di spunta quando l’attività è completata: non richiede alcun font, quindi è identica su ogni macchina, nel canvas, nel PDF, nell’HTML e nell’EPUB, e le tecnologie assistive leggono `☐` o `☑`. Il suo lato misura 0,6 em della dimensione del segno (`bulletFontSize`, o il `fontSize` del livello), ed è lo spazio che occupa prima del `gap`; alla dimensione del testo poggia sulla linea di base della prima riga della voce. Il suo tratto segue il `fontWeight` del segno e il suo colore il `color` del segno. I campi seguenti valgono solo per le voci di attività:

| Proprietà | Tipo | Predefinito | Descrizione |
| --- | --- | --- | --- |
| `taskCheckboxChar` | `string` | `'☐'` | Carattere di un’attività non spuntata. Quello predefinito non viene composto come testo: la casella la disegna il motore. Qualsiasi altro carattere viene composto come testo nel carattere dell’elenco, che quindi deve contenerlo. |
| `taskCheckedChar` | `string` | `'☑'` | Carattere di un’attività completata. Anche quello predefinito viene disegnato, come una casella con un segno di spunta; qualsiasi altro carattere viene composto come testo nel carattere dell’elenco. |
| `taskBox` | `'drawn' \| 'character'` | `'drawn'` | Come vengono composti i due caratteri predefiniti. `'drawn'`: la casella la disegna il motore. `'character'`: `☐` e `☑` sono testo nel carattere dell’elenco, come fino a postext 1.28; in un carattere che non li contiene il browser sceglie un font di sistema, e il testo della voce comincia dopo la larghezza che dà quel font. Una configurazione salvata prima della versione 13 viene letta con `'character'`, così le sue righe restano dov’erano. |
| `taskCompletedStrikethrough` | `boolean` | `true` | Traccia una linea barrata sul testo delle attività completate. |
| `taskCompletedColor` | `ColorValue` | eredita il colore della voce | Colore facoltativo applicato al testo delle attività completate. Se manca, si usa il colore normale della voce. |

### Personalizzazioni per livello degli elenchi puntati

Ogni voce di `levels` riguarda un livello di profondità (1–5) e può ridefinire uno qualsiasi di questi campi:

| Proprietà | Tipo | Descrizione |
| --- | --- | --- |
| `bulletChar` | `string` | Glifo del punto elenco per questo livello. |
| `fontFamily` | `string` | Famiglia di caratteri delle voci per questo livello. |
| `fontSize` | `Dimension` | Dimensione del glifo del punto elenco per questo livello. |
| `color` | `ColorValue` | Colore della voce. |
| `fontWeight` | `number` | Peso della voce. |
| `italic` | `boolean` | Attiva il corsivo. |
| `indent` | `Dimension` | Rientro esplicito del punto elenco a questo livello. Vedi più sotto la regola della cascata. |
| `verticalOffset` | `Dimension` | Regolazione verticale fine del punto elenco a questo livello. |

**Cascata dei rientri.** Il livello 1 parte sempre dal valore generale di `indent` (per impostazione predefinita `0 em`: i punti elenco sono fissati al bordo della colonna). Per i livelli 2–5, se lasci `indent` non definito il motore colloca il punto elenco all’inizio del testo del livello *precedente* (rientro del livello superiore + larghezza del punto elenco + `gap`). Imposta un `indent` esplicito su un livello per interrompere la cascata e fissare quel livello dove preferisci.

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

## Elenchi numerati

La proprietà `orderedLists` controlla gli elenchi numerati (`1.`, `2)`, ecc.). Sono supportati fino a cinque livelli di annidamento e ogni livello può usare un formato di numerazione diverso.

### Valori predefiniti degli elenchi numerati

| Proprietà | Tipo | Predefinito | Descrizione |
| --- | --- | --- | --- |
| `fontFamily` | `string` | eredita `bodyText.fontFamily` | Font usato per il testo delle voci e per il numero. |
| `color` | `ColorValue` | Colore principale (`#295AA3`) | Colore del testo e del numero delle voci. Collegato alla voce `main-color` della palette predefinita. |
| `fontWeight` | `number` | `700` | Peso del testo delle voci e dei numeri (100–900). |
| `italic` | `boolean` | `false` | Compone il testo delle voci in corsivo. |
| `numberFormat` | `OrderedListNumberFormat` | `'arabic'` | Stile di numerazione: `'arabic'`, `'lower-alpha'`, `'upper-alpha'`, `'lower-roman'`, `'upper-roman'`. Funzionano anche le grafie delle altre impostazioni (`'decimal'`, `'roman-lower'`, `'i'`…; vedi [Grafie dei formati di numerazione](https://postext.dev/it/docs/configuration-page-layout.md#grafie-dei-formati-di-numerazione)); un valore sconosciuto numera in cifre arabe e viene segnalato. |
| `prefix` | `string` | `''` | Testo composto prima del numero, nello stile del separatore: con `'（'` qui e `'）'` come separatore un elenco cinese si legge （一）, （二）. Quando il separatore è disegnato come segmento a sé, lo è anche il prefisso, subito prima del numero. |
| `separator` | `string` | `'.'` | Carattere posto tra il numero e il testo, di solito `'.'` o `')'`. |
| `separatorFontFamily` | `string` | eredita `fontFamily` | Font del separatore. Quando uno qualsiasi degli stili del separatore differisce da quello del numero, il separatore è disegnato come segmento a sé dopo il numero (allineato a destra), per esempio `1` in Optima Bold nero seguito da `•` in DIN Pro Bold blu. |
| `separatorFontWeight` | `number` | eredita `fontWeight` | Peso del separatore (100–900). |
| `separatorItalic` | `boolean` | eredita `italic` | Compone il separatore in corsivo. |
| `separatorColor` | `ColorValue` | eredita `color` | Colore del separatore. I riferimenti alla palette vengono rispettati. |
| `separatorGap` | `Dimension` | `0 em` | Spazio tra il numero e il separatore. Il testo della voce comincia comunque `gap` dopo il separatore. |
| `numberFontSize` | `Dimension` | `1 em` | Dimensione del numero. |
| `gap` | `Dimension` | `0.5 em` | Spazio orizzontale tra il numero e il testo della voce. |
| `indent` | `Dimension` | `0 em` | Rientro di base del livello 1; i livelli più profondi partono a cascata dall’inizio del testo del livello superiore, salvo personalizzazioni. |
| `numberVerticalOffset` | `Dimension` | `0 em` | Regola finemente la posizione verticale del numero. |
| `marginTop` / `marginBottom` | `Dimension` | `1.5 em` | Spazio prima e dopo l’elenco nel suo insieme. |
| `itemSpacing` | `Dimension` | `0 em` | Spazio verticale aggiuntivo tra le voci. Attorno a un elenco annidato in una voce di un altro, lo spazio dell’elenco esterno si applica su entrambi i lati, prima della prima voce dell’elenco annidato e dopo l’ultima (fino a postext 1.4 la voce che seguiva un elenco annidato prendeva lo spazio dell’elenco annidato). |
| `snapTopToGrid` | `boolean` | `false` | Arrotonda per eccesso lo spazio sopra l’elenco perché il primo numero cada sulla griglia della linea di base, come fa il testo sotto un titolo; `marginTop` diventa allora un minimo. La fine di un elenco riporta comunque il flusso sulla griglia, quindi con `itemSpacing` a 0 ogni voce si allinea al testo della colonna accanto. Disattivato per impostazione predefinita, come fino a postext 1.4: un `marginTop` che non è un numero intero di righe lascia le voci fuori griglia fino alla fine dell’elenco. Gli elenchi dentro i riquadri, il cui interno è fuori griglia, non sono interessati. |
| `numberWidth` | `'run' \| 'level' \| 'item'` | `'run'` | Quanto è larga la colonna dei numeri di una voce, il che stabilisce dove comincia il suo testo; i numeri vi sono allineati a destra. `'run'`: il numero più largo della sequenza della voce, cioè le voci di uno stesso livello che hanno tra loro solo voci più profonde. Una figura, un paragrafo o un riquadro tra due voci apre una nuova sequenza, quindi `ii)` dopo una tabella può far cominciare il testo un po’ più a destra di `i)` prima di essa, e un elenco di nove voci compone il testo più a sinistra di un elenco di dodici. `'level'`: il numero più largo a quel livello in tutto il documento (il capitolo, in un libro), quindi ogni elenco, e ogni parte di un elenco interrotto, fa cominciare il testo nello stesso punto, come già fanno i rientri dei livelli più profondi. `'item'`: il numero della voce stessa, così il testo di ogni voce comincia un `gap` dopo la propria etichetta: 第九條 e 第十一條 sono seguiti dallo stesso spazio e i loro testi cominciano in punti diversi, come la Gazzetta ufficiale giapponese stampa gli articoli di una legge. Le righe successive seguono `hangingIndent`: `false` le riporta al rientro dell’elenco, `true` le appende sotto il testo della voce stessa. Il rientro di un livello più profondo resta un valore unico per livello. Da postext 1.28. |
| `numberAlign` | `'end' \| 'start'` | `'end'` | Come si colloca un numero nella sua colonna. `'end'`: contro il testo, così i numeri di una sequenza finiscono insieme e `9.` e `10.` si allineano sui punti. `'start'`: all’inizio della colonna (a sinistra in una pagina da sinistra a destra, a destra in una da destra a sinistra, in testa alla riga nel testo verticale), così le etichette di lunghezza diversa cominciano insieme, come gli articoli di una legge (第九條, 第十一條). La colonna mantiene la larghezza che le dà `numberWidth`, quindi il testo delle voci comincia comunque nello stesso punto; con un separatore in uno stile proprio, il separatore segue il suo numero. Da postext 1.26. Con `numberWidth: 'item'` la colonna è il numero stesso, quindi i due valori compongono lo stesso elenco. |
| `hangingIndent` | `boolean` | `true` | Le righe successive si allineano al primo carattere del testo anziché sotto il numero. |
| `levels` | `OrderedListLevelConfig[]` | — | Personalizzazioni per i livelli 1–5. |

### Personalizzazioni per livello degli elenchi numerati

Ogni voce di `levels` può ridefinire `numberFormat`, `prefix`, `separator`, `fontFamily`, `fontSize`, `color`, `fontWeight`, `italic`, `indent`, `verticalOffset` e lo stile del separatore (`separatorFontFamily`, `separatorFontWeight`, `separatorItalic`, `separatorColor`, `separatorGap`); vale la stessa cascata dei rientri degli elenchi puntati. Lo stile del separatore di un livello eredita lo stile del numero di quel livello, a meno che non sia data l’impostazione del separatore valida per tutto l’elenco.

**Allineamento a destra.** La pipeline misura il numero formattato più largo di una sequenza e fa rientrare tutte le voci di quella sequenza in modo che i numeri si allineino sul bordo destro. In un elenco di dieci voci reso come `1.` – `10.` i numeri di una cifra vengono spaziati fino ad allinearsi a destra, così il separatore resta nella stessa colonna.

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

Il risultato è il classico misto annidato:

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

La gerarchia dei documenti cinesi (GB/T 15834—2011, appendice B.3) prevede cinque livelli: 一、 poi （一） poi 1. poi （1） poi ①:

```ts
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: '' },
  ],
}
```

## Matematica

La proprietà `math` controlla come vengono analizzate e rese le formule LaTeX tra i delimitatori `$...$` (in linea) e `$$...$$` (in display). Il motore sottostante è MathJax (il pacchetto `mathjax-full`) in modalità di output SVG, rasterizzato sul canvas e incorporato nel PDF come glifi scalabili.

```ts
interface MathConfig {
  enabled?: boolean;        // Render LaTeX. When false, spans pass through as literal TeX.
  fontSizeScale?: number;   // × the surrounding text's size (the body size for display maths).
  color?: ColorValue;       // Formula colour; inherits body colour if omitted.
  marginTop?: Dimension;    // Space above display math blocks.
  marginBottom?: Dimension; // Minimum space below; baseline grid snap may enlarge it.
  indentAfterDisplay?: boolean; // Indent a paragraph that follows a display formula.
  keepWithLeadIn?: boolean; // Keep a display formula with the line that leads into it.
  equationNumbering?: {      // Number the display formulas that carry a \label.
    enabled?: boolean;           // default true
    numberingTemplate?: string;  // '{n}'; '{h1}.{n}' numbers by chapter
    resetOn?: ResourceCounterReset; // 'never' | 'h1' … 'h6'
    counterFormat?: ResourceCounterFormat; // 'decimal'
    format?: string;             // '({n})': what the formula and \eqref print
  };
}
```

| Proprietà | Tipo | Predefinito | Descrizione |
| --- | --- | --- | --- |
| `enabled` | `boolean` | `true` | Se è false, i segmenti `$...$` e `$$...$$` vengono comunque analizzati (quindi gli avvisi sui delimitatori non chiusi scattano ancora) ma sono resi come il loro sorgente TeX letterale. Utile quando il contenuto contiene di proposito il simbolo del dollaro o quando vuoi disattivare del tutto la resa delle formule. |
| `fontSizeScale` | `number` | `1.0` | Moltiplicatore applicato alla dimensione del testo circostante prima della resa: un em del font TeX della formula vale quella dimensione × `fontSizeScale`, cioè `bodyText.fontSize` per una formula in display e per la matematica in linea nel testo corrente, e la dimensione del blocco che la contiene per la matematica in linea in un titolo, in uno stile di paragrafo, in una didascalia o nel corpo di un riquadro. 1,0 corrisponde al testo circostante; valori tra 0,9 e 1,1 sono tipici quando il font matematico sembra un po’ più grande o più piccolo del font della prosa. **Cambiato in postext 1.5:** fino alla 1.4 le formule uscivano circa il 13% più grandi di così (vedi sotto). |
| `color` | `ColorValue` | eredita il colore del testo corrente | Colore della formula resa. Omettilo per ereditare `bodyText.color`. Impostalo esplicitamente quando vuoi che le formule abbiano una tinta diversa dalla prosa, per esempio in accordo con il colore d’accento di un titolo. |
| `marginTop` | `Dimension` | `0.8em` | Spazio sopra un blocco di formule in display. Ignorato per la matematica in linea. |
| `marginBottom` | `Dimension` | `0.8em` | Spazio sotto un blocco di formule in display. È un **minimo**: l’aggancio alla griglia può allungarlo perché la linea di base successiva cada su una riga della griglia (che `page.baselineGrid` disegni la griglia o no). |
| `indentAfterDisplay` | `boolean` | `true` | Fa rientrare la prima riga di un paragrafo che segue una formula in display, come qualsiasi altro paragrafo. Con `false` ogni paragrafo subito dopo una formula in display è composto senza rientro, come continuazione della frase che la formula ha interrotto («dove *L* è…»). Una formula scritta dentro un paragrafo, senza una riga vuota né sopra né sotto, è sempre seguita senza rientro: il testo sotto il suo `$$` di chiusura continua quel paragrafo e non rientra mai (vedi [Formule matematiche](https://postext.dev/it/docs/document-format.md#formule-matematiche)). |
| `keepWithLeadIn` | `boolean` | `false` | Tiene una formula in display nella colonna della riga che la introduce: la penalità predisplay di TeX. Quando la formula non entra sotto l’ultima riga del paragrafo che la precede, quella riga passa con la formula alla colonna o alla pagina successiva; quando le righe lasciate indietro sarebbero meno di `bodyText.widowMinLines` (meno di una se `bodyText.avoidWidows` è disattivato), un paragrafo che si apre in quella colonna passa avanti per intero (con i titoli che chiudono la colonna sopra di esso, secondo `headings.keepWithNext`). La riga portata avanti sta da sola in cima alla colonna successiva, qualunque cosa chieda la regola sulle orfane. Con `false` passa avanti solo la formula, e la riga che la introduce può chiudere la colonna sopra, o stare sopra una figura che apre la successiva. |
| `equationNumbering` | `{ enabled, numberingTemplate, resetOn, counterFormat, format }` | `true`, `'{n}'`, `'never'`, `'decimal'`, `'({n})'` | Come vengono numerate le formule in display che portano un `\label` (vedi *Equazioni numerate* più sotto). `numberingTemplate`, `resetOn` e `counterFormat` funzionano come quelli di un tipo di risorsa: `'{h1}.{n}'` con `resetOn: 'h1'` numera (2.1), (2.2)… per capitolo, `'{h1}.{h2}.{n}'` con `'h2'` per sezione. `format` è il numero come lo stampano la formula e `\eqref`, dove `{n}` sta per il numero: `'[{n}]'` compone [3]. `enabled: false` non numera nulla: un `\label` viene scartato e un rimando a esso stampa la sua pagina. Un segnaposto accetta anche uno stile dopo i due punti (`'{h1:A}.{n}'`: (A.1) in un’appendice contrassegnata da una lettera). |

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

**Dimensione delle formule, cambiata in postext 1.5.** MathJax fornisce il riquadro di una formula in `ex`, e un `ex` del suo font TeX vale 0,442 em. Fino a postext 1.4 il motore lo considerava mezzo em, quindi ogni formula veniva composta circa il 13% più grande di `bodyText.fontSize × fontSizeScale`. Ora le formule escono alla dimensione documentata, e le righe e le pagine con formule si ridistribuiscono. Una configurazione scritta in codice per la 1.4 mantiene la dimensione delle formule della 1.4 passando una volta per `pinLegacyMathSize` di `postext/bundle`, così com’è scritta:

```ts
import { pinLegacyMathSize } from 'postext/bundle';

config = pinLegacyMathSize(config); // formulas, and the space around display formulas, as 1.4 set them
```

Anche altri cambiamenti di regole della 1.5 possono spostarne le pagine: le interruzioni dei titoli, lo spazio attorno a una figura in linea (nel testo corrente e nei riquadri), i segni in linea dei suoi titoli, la dimensione dei suoi capilettera, lo spazio lasciato sotto una riga che termina con i due punti per l’elenco che introduce, le righe che il taglio di un riquadro lascia di un paragrafo o di una voce di elenco, gli a capo dopo una lineetta, la divisione in righe del testo non giustificato, la divisione di un paragrafo sotto un titolo, gli a capo dopo il trattino di una parola composta e lo spazio sotto un contenitore `:::paragraphs`. `migrateConfig`, eseguito una volta con il markdown che la configurazione impagina, fissa quelli di cui questo testo ha bisogno, dimensione delle formule compresa (vedi [Pacchetti scritti da postext 1.4 o precedenti](https://postext.dev/it/docs/configuration-programmatic-usage.md#pacchetti-scritti-da-postext-14-o-precedenti)):

```ts
import { migrateConfig } from 'postext/bundle';

config = migrateConfig(config, undefined, { content: markdown }); // heading breaks, formulas, inline gaps, heading marks, drop caps, colon lines, box cuts, dash breaks, compound breaks, ragged breaking, splits under a heading and container space as 1.4 set them
```

Questo trattiene ciò che quei cambiamenti di regole sposterebbero, ma non conserva ogni pagina della 1.4. La versione 1.5 corregge anche errori di impaginazione, e una correzione non si può fissare: una configurazione vecchia la riceve come una nuova, quindi una pagina che ne è toccata può comunque spostarsi. Tra queste correzioni: un titolo a tutta larghezza della pagina senza un design proprio viene misurato sulla larghezza della pagina e composto con l’interlinea del suo livello; in un design di titolo non si riserva nulla sotto la linea di base di un capolettera; un capolettera prende il colore della palette della sezione, e viene composto anche su un testo di design il cui `overflow` non è `'wrap'`, che allora va a capo; un paragrafo in un riquadro dipinge la spaziatura tra lettere con cui è stato misurato; un riquadro diviso mantiene la colonna dell’icona su ogni frammento; una riga di riquadro che allargherebbe i suoi spazi oltre 3× viene composta non giustificata, come nel testo corrente; la leva dei paragrafi troppo spaziati non compone mai una riga giustificata più larga di quanto consenta `maxWordSpacing`; un riquadro flottante mantiene un `marginBottom` (in una fascia in alto) o un `marginTop` (in una fascia in basso) più ampio dello spazio dei flottanti; un testo di design centrato o allineato a destra con spaziatura tra lettere (una testatina, il titolo di un’apertura) viene collocato in base alle sue lettere, senza la spaziatura dopo l’ultima; sotto un’apertura a tutta larghezza della pagina, il testo che apre la seconda colonna comincia dove comincerebbe il testo subito sotto l’apertura, anche quando un titolo segue l’apertura; i puntini dell’indice si fermano prima del numero di pagina in un carattere che con la crenatura allontana una sequenza di punti; una testatina legge un titolo così come è scritto, senza spazio dove una delle sue righe finisce dopo un trattino o una lineetta o dentro una parola tagliata per larghezza (`MEDIOAMBIENTALES`, non `MEDIOAMBIENTALE S`), e il `{titleText}` di un design di titolo lo legge allo stesso modo (`thousand-colour`, non `thousand- colour`); un testo ancorato al piede o al centro della fascia di un design di titolo mantiene la fascia abbastanza alta da contenerlo, così non sale più sopra il testo che precede il titolo; una parola più larga della sua riga, tagliata accanto a un trattino che contiene, viene tagliata dopo quel trattino e non ne riceve un secondo; la voce che segue un elenco annidato in un altro prende l’`itemSpacing` del proprio elenco, non quello dell’elenco annidato; e il resto di una parola tagliata perché più larga della sua riga mantiene i propri punti di divisione, così un indirizzo web continua a dividersi nelle sue giunture e una parola composta ai suoi trattini invece che nelle sillabe del dizionario.

`pinLegacyMathSize` moltiplica la scala per 1,1312 (0,5 ÷ 0,442) e divide per lo stesso fattore i margini delle formule in display espressi in `em`. La sola scala non basta per un libro con formule in display: i loro margini sono lunghezze relative alla dimensione della formula stessa, quindi crescerebbero dello stesso 13% e spingerebbero in giù il testo sottostante. Scritti per esteso per i margini predefiniti, i tre valori sono:

```ts
math: {
  fontSizeScale: 1.131,
  marginTop: { value: 0.7072, unit: 'em' },
  marginBottom: { value: 0.7072, unit: 'em' },
} // formulas as large as 1.4 set them, with the space 1.4 left around them
```

Dove la configurazione era salvata, il motore se ne accorge e lo fa per te: `openBundle` / `readBundle` per un pacchetto `.postext` scritto prima della 1.5 (vedi [Pacchetti scritti da postext 1.4 o precedenti](https://postext.dev/it/docs/configuration-programmatic-usage.md#pacchetti-scritti-da-postext-14-o-precedenti)), e la Sandbox per i libri, la copia di lavoro e i file `postext-config.json` salvati allora (vedi **Sandbox → Persistenza**). Vengono letti tramite `migrateConfig`, che fissa la dimensione (`pinLegacyMathSize`): `fontSizeScale` diventa la scala salvata (1 se non impostata) × 1,1312, e un margine delle formule in display in `em` o `rem`, che è una lunghezza relativa alla dimensione della formula stessa, viene diviso per lo stesso fattore, così lo spazio attorno a una formula in display resta quello che lasciava la 1.4 (il valore predefinito di 0,8 em diventa 0,7072 em). Un margine in un’unità di pagina (`pt`, `mm`…) resta com’è, e così una configurazione con `enabled: false` o il cui libro non contiene alcun `$`. Il vecchio libro viene allora impaginato come lo impaginava la 1.4, e la sua sezione `math` mostra la dimensione con cui è composto. Per comporre invece quel libro alla dimensione attuale, reimposta quei valori: **Formule → Scala del corpo**, *Margine superiore del display* e *Margine inferiore del display* nella Sandbox, oppure in codice:

```ts
math: { ...config.math, fontSizeScale: 1, marginTop: undefined, marginBottom: undefined } // today's size and margins
```

**Equazioni numerate.** Una formula in display con un numero occupa tutta la sua giustezza (la colonna, o la larghezza interna del riquadro in cui si trova): l’equazione è centrata e il suo numero è allineato a destra sulla riga dell’equazione, su ogni riga numerata di un `align`. Un numero nasce da un `\label{eq:x}` (da postext 1.19): le formule con etichetta, e le righe con etichetta di un `align`, `gather`, `alignat`, `flalign` o `eqnarray`, vengono numerate in ordine di lettura secondo `equationNumbering`, a meno che una riga non dica `\nonumber` o `\notag`. Ambienti come `equation` non vengono numerati di per sé: una formula senza etichetta non ha numero. `\tag{…}` stampa l’etichetta che gli dai, tra parentesi, e `\tag*{…}` così come è scritta; nessuno dei due viene contato, e un `\label` accanto a uno dei due gli dà un nome. Un’equazione numerata più larga della sua giustezza deborda a destra, come qualsiasi formula in display. (Fino a postext 1.4 una formula con `\tag` non veniva disegnata affatto; fino alla 1.18 solo `\tag` dava un numero.)

`\eqref{eq:x}` nel testo stampa il numero nel suo `format`, (3), e `\ref{eq:x}` il numero nudo; lo stesso fanno `:ref{id="eq:x"}` e `@eq:x` (vedi [Rimandi](https://postext.dev/it/docs/document-format.md#rimandi-e-ancore)), e dentro una formula `\eqref` lo stampa come testo. In un libro impaginato capitolo per capitolo il contatore prosegue dal capitolo precedente: `continuationAfter` lo porta in `LayoutContinuation.statementCounters` (`equation`), e lo schema del libro dà a ogni etichetta il suo numero (`OutlineEntry.numberLabel`), così un rimando a un’equazione di un altro capitolo la stampa.

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

Il resolver e lo stripper seguono le altre sezioni:

```ts
import {
  DEFAULT_MATH_CONFIG,
  resolveMathConfig,
  stripMathDefaults,
} from 'postext';

const resolved = resolveMathConfig(config.math);
const minimal  = stripMathDefaults(config.math);
```

### Avviare il motore matematico

MathJax viene caricato su richiesta, non insieme al resto del motore. Quando impagini nel thread principale, avvialo prima di costruire un documento che contiene formule:

```ts
import { buildDocument, initMathEngine, renderPage } from 'postext';

await initMathEngine(); // loads MathJax once; later calls resolve at once
const doc = buildDocument({ markdown: 'Euler: $e^{i\\pi}+1=0$.' }, config);
document.body.append(renderPage(doc.pages[0], doc));
```

- **Finché il motore non è avviato, le formule sono segnaposto.** Ognuna viene impaginata come un riquadro grigio di dimensione stimata. Se un documento con formule viene impaginato senza che `initMathEngine()` sia mai stato chiamato, la console mostra un avviso che lo segnala.
- **Il worker di impaginazione lo avvia per te.** Una build in `postext/worker` chiama da sé `initMathEngine()` quando il markdown contiene un `$`.
- **Impagina subito, e di nuovo quando è pronto.** `isMathReady()` dice se il motore è in funzione. `onMathReady(fn)` chiama `fn` appena lo è (subito, se lo è già) e restituisce una funzione che annulla la chiamata. Un editor può mostrare subito i segnaposto e impaginare di nuovo quando arriva MathJax; mentre `initMathEngine()` è in corso non viene stampato alcun avviso.
- **Errori.** `initMathEngine()` viene rifiutata quando MathJax non si può caricare, e una chiamata successiva riprova.
- **Qualsiasi bundler, Node o una CDN.** MathJax è incluso nel pacchetto come un unico modulo già impacchettato (circa 1,8 MB prima della compressione, scaricato solo da `initMathEngine`). Il semplice `import { initMathEngine } from 'https://esm.sh/postext'` funziona; non serve `?bundle`. Il pacchetto `mathjax-full` serve solo a compilare postext, quindi installare postext non lo installa. MathJax e il parser mhchem che include sono distribuiti con licenza Apache-2.0: le loro note e il testo della licenza sono distribuiti accanto al modulo, come `dist/math/THIRD_PARTY_LICENSES.txt`.
- **Un solo motore per pagina.** Il motore e la sua cache delle formule rese sono condivisi da tutto ciò che importa `postext` nello stesso realm JavaScript (vedi [Stato globale condiviso in una pagina](https://postext.dev/it/docs/configuration-programmatic-usage.md#stato-globale-condiviso-in-una-pagina)).

Per la grammatica lato documento (`$...$`, `$$...$$`, l’escape di un dollaro letterale), vedi [Formato del documento](https://postext.dev/it/docs/document-format.md#formule-matematiche).