Formato del documento

Postext legge di proposito un dialetto di markdown ridotto.

Il parser è un tokenizzatore scritto a mano, non un’implementazione completa di CommonMark, quindi il formato sorgente è ristretto e prevedibile. Lo scopo è duplice: mantenere il motore piccolo e veloce, e rendere i documenti facilmente trasferibili tra Postext e qualsiasi altro lettore CommonMark (Obsidian, Pandoc, VS Code…). Tutto ciò che non è elencato in questa pagina viene trattato come testo semplice oppure rimosso dal flusso in linea.

Se costruisci un documento da codice, la funzione parseMarkdown (vedi Configurazione › Parsing) ti restituisce l’esatta struttura a blocchi che il motore di impaginazione consuma.

#Frontmatter

Un documento può iniziare con un blocco frontmatter YAML facoltativo, racchiuso tra marcatori ---:

---
title: Chapter One
author: Jane Doe
publishDate: 2026-04-15
---
 
# Chapter One
 
The story begins here…

Chiama extractFrontmatter(source) per separare il frontmatter dal corpo. L’oggetto dei metadati analizzati viene restituito insieme al markdown rimanente e alla posizione (in caratteri) in cui inizia il corpo: utile se devi ricondurre errori o posizioni del cursore al sorgente originale.

Il frontmatter viene analizzato con gray-matter, quindi è accettata qualsiasi forma di YAML. Postext guarda solo title, subtitle, author e publishDate; le altre chiavi restano in PostextContent.metadata e puoi usarle come vuoi.

Un blocco che non è YAML valido (una virgoletta non chiusa, testo dopo un valore tra virgolette) non ferma l’impaginazione: extractFrontmatter non restituisce metadati, restituisce come corpo il testo dopo il --- di chiusura e mette in error il motivo indicato dal parser. Il documento viene composto senza i suoi metadati, e la costruzione elenca una voce invalidFrontmatter in contentWarnings (la Sandbox la mostra come Front matter non valido).

YAML assegna un tipo ai suoi valori: 1984 è un numero, 2026-04-15 una data, [Ana Gil, Luis Paz] un elenco. Postext stampa ciascuno di questi quattro campi come testo, qualunque sia il suo tipo:

• un numero nella sua forma decimale semplice, e un booleano come true o false (title: 1984 stampa 1984). YAML legge un numero come valore, non cifra per cifra: 1.50 stampa 1.5, 017 (ottale) 15, 1:30 (base 60) 90;
• una data come giorno del calendario, scritta per esteso nella lingua del documento (l’impostazione locale, altrimenti la lingua di sillabazione): publishDate: 2026-04-15 stampa April 15, 2026 in inglese, 15 de abril de 2026 in spagnolo, 15. April 2026 in tedesco. Le date in arabo usano il calendario gregoriano a meno che il tag non ne indichi un altro (ar-u-ca-islamic stampa la data dell’Egira), con le cifre che il tag implica (ar-EG: ١٥ أبريل ٢٠٢٦; ar-u-nu-latn: 15 أبريل 2026). Una data con un orario stampa il giorno della sua ora UTC e scarta l’orario: 2026-09-24T23:30:00-05:00 corrisponde alle 04:30 UTC del 25 e stampa September 25, 2026;
• un elenco come le sue voci separate da virgole (author: [Ana Gil, Luis Paz] stampa Ana Gil, Luis Paz).

Metti un valore tra virgolette per stamparlo esattamente come è scritto (un numero che deve conservare le sue cifre, una data che deve conservare il suo giorno): publishDate: "15/04/2026", title: "1984". Il testo arriva a doc.metadata, ai segnaposto ({title}, {publishDate}…) e al titolo e all’autore del PDF. Uno dei quattro campi che non ha una forma testuale (una mappa annidata, un title: vuoto) viene lasciato fuori da doc.metadata. extractFrontmatter restituisce comunque i valori con il tipo che YAML ha dato loro; metadataText(value, locale) fornisce il testo che Postext stampa per uno di essi.

#Costrutti di blocco

Postext riconosce sette tipi di blocco di prosa e i listati di codice, più le direttive e gli inserimenti di risorse trattati più avanti in questa pagina. I blocchi terminano sempre con una riga vuota o con l’inizio di un altro blocco.

Una sola riga vuota tra due voci di elenco è tollerata: l’elenco resta unito. Due o più righe vuote chiudono l’elenco.

Gli elenchi di tipo misto alla stessa profondità sono accettati (puoi passare da puntato a numerato a metà sequenza), ma il motore tratta le sequenze come separate ai fini della numerazione. In pratica, tieni un solo tipo per profondità, a meno che tu non abbia un motivo per mescolarli.

#Attributi dei titoli

Una riga di titolo può terminare con un blocco di attributi tra parentesi graffe, con la stessa sintassi key="value" delle direttive:

# The Long Road {author="I. Zango Martín" year=1998}

Le graffe e il loro contenuto vengono tolti dal testo del titolo (il titolo qui sopra viene mostrato come The Long Road) e conservati sul titolo come attrs. Sono esposti agli slot di design come segnaposto {attr.<key>}: nello slot di design avanzato del titolo stesso, e nelle intestazioni e nei piè di pagina, dove si risolvono a partire dall’H1 del capitolo corrente. Viene riconosciuto solo un blocco bilanciato, senza graffe interne, proprio alla fine della riga, dopo uno spazio oppure, dato che i titoli cinesi si scrivono senza, subito dopo un carattere cinese o giapponese (# 回目{style="x"}). Il blocco viene preso solo quando la sintassi degli attributi descritta qui sotto lo legge per intero: {x, y}, {紅樓|hóng lóu} e un {} isolato restano nel titolo, e così anche gli indicatori da soli attaccati al titolo (# 第一回{draft}). Gli attributi sono separati da spazi, quindi anche un blocco con virgole ({a="1", b="2"}) e il {.class} di Pandoc restano nel titolo. L’identificatore {#id} di Pandoc invece viene letto: equivale a id="…" e dà un nome al titolo per i rimandi. Una chiave scritta in un’altra scrittura viene letta e scartata con un avviso (vedi sotto), quindi # 回目{style="x" 作者=曹雪芹} prende comunque style. Vedi Configurazione → Intestazioni e piè di pagina.

Un valore stampato da un testo di design può occupare più righe: i due caratteri \n iniziano lì una nuova riga, qualunque sia l’overflow dell’elemento (to="Firma X\nStrasse 1\n10115 Berlin" stampa un indirizzo su tre righe). Con inlineMarks sull’elemento valgono anche i segni in linea del valore: authors="Ana Ruiz^1^, Luis Gil^2^" compone in apice i numeri di affiliazione. Questo escape riguarda i valori degli attributi (e i modelli del design stesso): i caratteri \n nel testo di un titolo, per esempio in un segmento di codice, vengono stampati così come sono.

Due attributi hanno un significato proprio. style="<id>" applica al titolo uno stile di titolo con nome: una prefazione o un elenco di autori con il proprio design di apertura, testatine, geometria della pagina e tipografia del testo, e senza numero di capitolo quando lo stile indica numbered: false. toc="false" (o "true") stabilisce se il titolo compare in :::toc:

# Preface {style="front-matter"}
 
# Contents {style="front-matter" toc="false"}

Altri due cambiano ciò che un titolo stampa e come viene contato. hidden="true" (o "false") prevale sull’hidden del livello o dello stile del titolo: un titolo nascosto non stampa nulla e non occupa spazio (nel flusso come dentro un riquadro :::callout), ma apre comunque la sua pagina, conta e compare nell’indice, nelle testatine {chapterTitle} e nei segnalibri del PDF. jidori=N distribuisce un titolo di una riga in modo uniforme sulla larghezza di N dei suoi caratteri (字取り: # 序章 {jidori=3} stampa 序　章), e jidori=0 disattiva la spaziatura uniforme impostata dal suo livello o stile (vedi Configurazione › Sostituzioni per livello). indent=N abbassa un singolo titolo di N caratteri del testo corrente rispetto all’inizio della riga (字下げ: ## 一 {indent=5}), prevalendo sull’indent del suo livello o stile; un numero semplice conta in em del testo corrente, 0 compone il titolo a inizio riga, e funziona allo stesso modo nel testo verticale e in quello orizzontale. firstLineIndent=N fa rientrare solo la prima riga di un singolo titolo, prevalendo sul firstLineIndent del suo livello o stile, mentre le altre righe iniziano dove le colloca indent (i titoli della GB/T 9704: ## 关于加强管理的通知 {firstLineIndent=2}); legge le lunghezze come indent, e 0 annulla quello del livello. startAt=N, un intero positivo, imposta il contatore del livello del titolo a N invece di farlo avanzare; i titoli successivi continuano a contare da lì, anche nei capitoli seguenti, e i livelli inferiori ripartono sotto di esso come al solito. Con uno stile di titolo che indica le appendici con lettere (numberingTemplate: 'Appendix {1:A}'), la prima appendice fa ripartire il conteggio così da leggersi Appendix A invece di proseguire dai capitoli:

# To my mother {hidden="true" toc="false"}
 
# Survey instrument {style="appendix" startAt=1}
 
# Raw data {style="appendix"}

#Capilettera

Un paragrafo si apre con un capolettera quando il livello o lo stile del suo titolo, o lo stile di paragrafo del suo gruppo :::paragraphs, ne imposta uno (vedi Configurazione › Capilettera): la prima lettera viene composta in grande accanto alle prime righe, che si accorciano per girarle intorno. Nel paragrafo non c’è nessun markup; il testo si scrive come al solito, e la lettera resta parte della sua parola per la copia, la ricerca e la mappa del sorgente. Un attributo dropcap lo attiva o lo disattiva per un capitolo o per un gruppo:

# Lost {dropcap=false}
 
# The mines {dropcap=2}
 
:::paragraphs{style="entry" dropcap}
The lamp of the first entry opens with an initial.
:::

Su una riga di titolo, dropcap=false lascia il paragrafo che segue quel titolo senza il capolettera impostato dal suo livello o stile, dropcap=N lo compone su N righe, e un dropcap semplice dà un capolettera a quel paragrafo (tre righe, nel carattere del paragrafo) dove il livello non ne imposta nessuno. Sulla recinzione di :::paragraphs l’attributo fa lo stesso per il primo paragrafo del gruppo, o per ogni paragrafo quando lo stile indica each: true. Il paragrafo che segue un titolo viene cercato oltre recinzioni, direttive, riquadri usciti dal flusso e figure flottanti; un paragrafo dentro un riquadro, una voce di elenco, una citazione o una poesia non prende mai un capolettera. Da postext 1.23.

#Blocchi di codice

Un listato va tra due recinzioni di tre o più apici inversi (o tre o più tilde), ciascuna su una riga a sé, con al massimo tre spazi di rientro. Tutto ciò che sta tra le due viene conservato come è scritto: spazi iniziali e sequenze di spazi, tabulazioni, righe vuote e righe che iniziano con #, -, 1., >, $ o :::. Nulla al suo interno viene letto come Markdown: niente enfasi, niente :ref, niente formule, niente chip, niente direttive, niente titoli. La recinzione di chiusura usa il carattere di quella di apertura ed è lunga almeno quanto lei, quindi un listato che mostra una recinzione va dentro una più lunga o tra tilde:

```bash {title="backup.sh" lineNumbers start=12 highlight="3,5-7"}
#!/usr/bin/env bash
# Copy the photos to the backup disk
rsync -a --delete ~/Photos/ /Volumes/Backup/Photos/
echo "done: $(date)"
```

La stringa informativa dopo la recinzione di apertura indica il linguaggio (la sua prima parola: js, ts, python, bash, console, json…), e il resto viene letto come attributi nella sintassi degli attributi, tra graffe o senza (title="app.js" lineNumbers). Qualsiasi altra cosa dopo il linguaggio è il titolo: ```console Terminal e ```python normalize.py stampano Terminal e normalize.py sopra il listato.

Una recinzione chiude il paragrafo che la precede, con o senza riga vuota, e il testo dopo la recinzione di chiusura inizia un nuovo paragrafo. Una recinzione lasciata aperta prosegue fino alla fine del testo e viene segnalata (unclosedCodeBlock). Una recinzione dentro un :::callout è un riquadro annidato in esso; dentro :::paragraphs il listato mantiene lo stile del codice, non lo stile di paragrafo. Postext non prevede la continuazione delle voci di elenco, quindi una recinzione dopo una voce di elenco chiude l’elenco. I segni d’indice e le ancore scritti dentro un listato restano come sono scritti.

Il codice rientrato (quattro spazi o una tabulazione, dopo una riga vuota) viene letto come listato solo quando codeStyle.indentedCode è attivo: i testi di Postext spesso rientrano con spazi, e le voci di elenco annidate leggono gli spazi iniziali.

L’aspetto di un listato (il carattere, il riquadro, la larghezza della tabulazione, che cosa succede a una riga più larga del riquadro, i numeri di riga, i colori dei suoi token) si imposta con codeStyle; vedi Configurazione › Listati di codice. Il codice in linea (`x`) resta nel carattere del testo, a meno che codeStyle.inline non gliene assegni uno. Un libro salvato prima di postext 1.23 con recinzioni nel testo le legge come allora, come Markdown (codeStyle.blocks: false). Da postext 1.23.

#Direttive

Le direttive sono tag di controllo su una sola riga, scritti come :::name o :::name{attrs} su una riga a sé. Non producono output visibile: guidano la pipeline di posizionamento e numerazione.

I valori degli attributi possono essere tra virgolette doppie ("…"), tra virgolette singole ('…') o senza virgolette (startAt=17). Una chiave senza = viene trattata come un flag presente ma vuoto.

Oggi solo pagebreak, numbering, columnbreak, space, toc e index sono riconosciute come direttive su una sola riga (e references, verse, page e strip come blocchi delimitati): qualsiasi altra riga :::name che non sia un contenitore (vedi sotto) viene letta come paragrafo e fa comparire nella Sandbox un avviso Direttiva sconosciuta. Anche il motore la registra, come voce unknownDirective nei contentWarnings del documento (vedi Configurazione › Avvisi nel documento).

#Valori degli attributi

La stessa sintassi key="value" viene letta dagli attributi dei titoli, dai delimitatori di direttive e contenitori (:::name{…}), dai rimandi in linea (:ref{…}), dai chip (:chip[…]{…}), dai campioni di colore (:swatch{…}) e dai marcatori d’indice (:index[…]{…}). Le sue regole:

• Chiavi: cominciano con una lettera ASCII o con _ e proseguono con lettere ASCII, cifre, _ o -. Gli spazi attorno a = vanno bene, il ＝ a larghezza piena che digita un metodo di input cinese vale come =, una chiave ripetuta tiene l’ultimo valore e una chiave senza = è un flag con valore vuoto. Una chiave in un’altra scrittura (作者=曹雪芹) non viene letta e solleva un avviso attributeKeyInvalid; le altre chiavi del blocco restano valide. I valori possono essere in qualsiasi scrittura.
• Valori tra virgolette. Un valore tra virgolette doppie può contenere tutto tranne ", virgolette singole comprese; uno tra virgolette singole tutto tranne '. Quindi un valore con virgolette doppie va tra virgolette singole: lead='He said "hi"'. Non esistono sequenze di escape (una barra rovesciata è un carattere qualunque), perciò un valore che ha bisogno di entrambe le virgolette ASCII usa quelle tipografiche (“…”, ’). Un valore può anche aprirsi con la virgoletta curva “ o con la parentesi ad angolo 「 che digita un metodo di input cinese, e in quel caso arriva fino alla ” o alla 」 corrispondente, spazi compresi: title=“甲戌本 眉批”, title=「脂批」.
• Valori senza virgolette (startAt=17, year=1998): arrivano fino allo spazio successivo: title=Hello world equivale a title="Hello" più un flag world.
• Niente graffe. { e } non vanno mai in un valore. La prima } chiude il blocco: un delimitatore il cui valore ne contiene una non è più una direttiva ma un paragrafo, e in linea il resto del valore si riversa nel testo. In un titolo, una graffa in un valore lascia l’intero blocco nel titolo: # Title {note="a {b"} viene composto così come è scritto. (Fino a postext 1.8 una { dopo uno spazio faceva ripartire il blocco e b veniva letto come flag.)
• Il simbolo del dollaro è testo semplice. Gli attributi vengono letti prima della matematica in linea, quindi lead="from $5 to $6" è solo testo.
• Una sola riga. Un blocco di attributi non occupa mai più righe.

# The Long Road {lead='A "road novel", they said' price="$18"}
 
:::callout{type="note" title='The "fast" path'}
…
:::

::resource{id="…"} è più rigido: l’id tra virgolette doppie e nessun altro attributo (vedi Risorse).

#Contenitori

Un contenitore racchiude una sequenza di blocchi tra due delimitatori: una riga di apertura :::name o :::name{attrs}, poi qualsiasi contenuto ordinario (paragrafi, titoli, elenchi, citazioni, formule, perfino altre direttive) e una riga di chiusura che contiene solo :::. I contenitori si possono annidare; ogni ::: di chiusura chiude il contenitore aperto più interno.

:::callout{type="note"}
Keep the lantern lit **every** night.

- Check the wick.
- Trim it at dusk.
:::

Nel flusso del testo sono riconosciuti cinque nomi di contenitore. Ciò che ciascuno disegna si imposta nella relativa sezione della configurazione:

Gli attributi accettati da ogni contenitore, e il modo in cui ognuno viene stilizzato, sono documentati in Configurazione. I valori degli attributi seguono la stessa grammatica delle direttive. Un delimitatore :::callout accetta type (l’id di uno stile di riquadro configurato: i tipi sconosciuti o mancanti ripiegano sul primo stile), title (sostituisce il titolo predefinito dello stile) e span / placement (column, page o side; here, top, bottom o fixed) per sostituire, per quel riquadro, l’estensione e la posizione dello stile:

:::callout{type="objectives" title="What you will learn" span="page" placement="top"}
- Name the parts of the lantern.
- Trim the wick without touching the glass.
:::

Un riquadro flottante (placement auto, top o bottom) accetta anche columns, il numero di colonne adiacenti che occupa su una pagina a più colonne, come in :::callout{placement="top" columns="2"} (da postext 1.18).

Un riquadro può anche far scorrere accanto a sé il testo che lo segue: wrap (left, right, start o end), width (la sua quota della colonna, da 0 a 1; layout.wrap.defaultWidth quando non è impostato) e wrapGap (una lunghezza, come 6pt), come in :::callout{wrap="right" width=0.4} (vedi Testo che scorre attorno; da postext 1.24).

Un riquadro si impagina come un blocco: un titolo facoltativo, poi il contenuto composto con la tipografia del testo e degli elenchi propria dello stile. Per impostazione predefinita resta unito e si sposta intero alla colonna o alla pagina successiva quando non entra (un riquadro più alto di un’intera colonna si divide comunque, invece di debordare); uno stile con keepTogether: false gli permette di dividersi tra i suoi blocchi, o tra le righe, lasciando almeno splitMinLines righe di testo (oppure una figura, una tabella, una formula in display o un riquadro annidato) su ogni lato del taglio (un taglio dentro un paragrafo o una voce di elenco lascia inoltre almeno layout.boxChildSplitMinLines delle sue righe su ogni lato: due per impostazione predefinita, splitMinLines quando è più basso; i libri salvati prima della 1.5 i cui capitoli contengono un riquadro vengono letti con 1, il taglio della 1.4). Ogni parte dopo la prima si apre senza l’icona, anche se il testo mantiene la colonna dell’icona, e senza il titolo, a meno che lo stile non lo ripeta (repeatTitle: «Punti chiave (segue)»); uno stile può anche mettere un indicatore «Continua» sotto ogni parte che prosegue (continuesMarkerEnabled): vedi Indicatori su un riquadro diviso. I riquadri a tutta larghezza (span="page") dividono la pagina in fasce di colonne; i riquadri span="side" escono dal flusso ed entrano nella colonna laterale riservata agli elementi flottanti di un’impaginazione a colonna e mezza (layout.sideColumnRole: 'floats'), impilati accanto al testo che interrompono, e si impaginano come riquadri di colonna dove quella colonna non c’è; i riquadri placement="fixed" escono dal flusso e vengono fissati a coordinate della pagina (per esempio un badge di autovalutazione nell’angolo in basso a sinistra dell’ultima pagina di un capitolo), mentre le colonne che coprono rinunciano a quella zona; i riquadri flottanti (placement="top" / "bottom") escono dal flusso nel punto in cui si trovano e occupano la prima fascia libera dopo quella posizione (il piede della pagina, o la testa o il piede della successiva), mentre il testo che li segue riempie la pagina che hanno lasciato. Uno stile con floatBarrier: true (di solito il riquadro «punti chiave» che chiude un capitolo) rende il riquadro una barriera per gli elementi flottanti: ogni figura o tabella richiamata prima di esso viene posizionata prima di esso (negli spazi liberi della pagina, o su pagine aperte prima del riquadro), così nessun elemento flottante sfugge oltre la fine del suo capitolo. Un delimitatore :::name sconosciuto non è un contenitore: la riga viene trattata come testo, esattamente come una direttiva sconosciuta.

Un delimitatore :::part accetta number (come vuoi che venga stampato: "I", "IV", "3"; viene anche interpretato, così il progetto grafico può riformattarlo) e title; entrambi sono facoltativi. Un terzo attributo, palette="band=#hex" (più coppie id=#hex separate da virgole), ricolora ogni colore del progetto grafico collegato a quegli id della tavolozza (testatine, fascia di apertura, progetti delle parti) e i colori del flusso del testo che condividono il loro valore di base (titoli, grassetto, rimandi, punti elenco, didascalie, tabelle, riquadri, chip) per la parte e per i capitoli che la seguono, fino alla parte successiva; vedi Configurazione › Parti. Il contenitore apre sempre una pagina a sé: un’interruzione di pagina con la parità configurata prima, una sola colonna di testo ai margini parts.margins, il progetto di apertura su tutta la pagina e un’altra interruzione di pagina dopo il delimitatore di chiusura. Il corpo (di solito l’elenco dei capitoli che la parte raggruppa, oppure niente) viene composto con parts.bodyStyle:

:::part{number="I" title="Foundations"}
1. The lantern and its parts
2. Trimming the wick
:::

# The lantern and its parts

Con le impostazioni predefinite dei titoli ne risulta la sequenza classica: pagina di parte su una pagina di destra, pagina di sinistra bianca, capitolo sulla pagina di destra successiva. La pagina viene segnalata come role: 'part', così intestazioni e piè di pagina possono saltarla, e {partTitle} / {partNumber} si risolvono nella parte corrente su ogni pagina successiva. Vedi Parti nel riferimento della configurazione.

Un delimitatore non ha bisogno di una riga vuota prima: un delimitatore di apertura o di chiusura attaccato subito sotto un paragrafo, un elenco o una citazione chiude quel blocco. Un contenitore lasciato aperto alla fine del documento viene chiuso lì automaticamente, e la Sandbox segnala un avviso Contenitore non chiuso che punta alla riga di apertura. Un ::: isolato senza alcun contenitore aperto resta nel testo come paragrafo visibile invece di essere eliminato in silenzio.

#:::columns

Un gruppo :::columns{count=2} … ::: compone i blocchi tra i suoi delimitatori in count colonne di uguale larghezza (da 2 a 6), e il testo che segue torna a occupare tutta la larghezza. Dentro un :::callout le colonne si dividono la larghezza interna del riquadro, distanziate del columnGap dello stile, con la tipografia del testo e degli elenchi del riquadro, e il riquadro cresce fino alla colonna più alta. Nel testo corrente (da postext 1.25) si dividono la colonna di testo, distanziate di una riga del testo corrente, e i blocchi mantengono la tipografia del testo; con span="page", su una pagina a più colonne, il gruppo divide la pagina in una fascia come fa un riquadro a tutta larghezza: le colonne sopra di esso chiudono allineate, il gruppo viene composto su tutta la larghezza del contenuto (distanziato dell’intercolonna) e il testo prosegue in ogni colonna sotto di esso. Su una pagina a una colonna span="page" lo compone nella colonna. I titoli dentro un gruppo mantengono stile, numero e voce nell’indice, una nota a piè di pagina citata al suo interno va al piede della colonna di testo e le figure che cita flottano come al solito.

Un gruppo composto per intero viene tagliato dove le sue colonne si allineano meglio (tra blocchi, o tra le righe di un paragrafo o di una voce di elenco, la cui coda prosegue in testa alla colonna successiva senza il punto elenco), a meno che breaks non fissi l’inizio delle colonne, senza tagli dentro un paragrafo: una colonna di testo accanto a una colonna di figure.

Lo spazio attorno a un gruppo. Nel testo corrente un gruppo è seguito dalla spaziatura tra paragrafi del testo (una riga con bodyText.paragraphSpacing, nessuna senza), e dentro un riquadro da nessuno spazio proprio. marginTop e marginBottom sul delimitatore lo impostano: :::columns{count=3 span="page" marginBottom="0.75em"}. Ognuno è un minimo che si fonde con lo spazio che il blocco adiacente riserva per sé, come fanno i margini di un riquadro. Nel testo corrente il flusso torna sulla griglia della linea di base sotto il gruppo, quindi lo spazio risulta in righe intere, e un gruppo diviso tra colonne o pagine mantiene il margine superiore per la prima parte e quello inferiore per l’ultima. Un em è il corpo del testo in cui si trova il gruppo; un valore che non è una lunghezza, o uno negativo, viene ignorato.

:::callout{type="summary"}
:::columns{count=2}
- Every element is one kind of atom.
- Electrons live in orbitals.
- A bond shares or transfers electrons.
:::
:::

Come conta breaks. breaks numera in ordine i blocchi del gruppo (paragrafi, voci di elenco, un blocco ciascuna, formule in display, figure e tabelle), e un :::callout annidato conta come un solo blocco, qualunque cosa contenga. Le direttive non sono blocchi: un :::space tra due strofe non sposta il conteggio. Un numero inferiore a 2, oltre l’ultimo blocco del gruppo o non successivo all’interruzione precedente viene ignorato. Dentro un gruppo :::space separa due blocchi come in qualsiasi altro punto di un riquadro, e scompare in cima al gruppo e in testa a ciascuna delle sue colonne (una posizione di breaks o un taglio di allineamento): per aprire il gruppo più in basso, metti lo spazio prima del delimitatore :::columns. Due colonne che portano la stessa spaziatura si allineano quindi strofa per strofa:

:::callout{type="verse"}
:::columns{count=2 breaks="4"}
The lamp is lit at dusk,
 
and trimmed before the dawn.
 
:::space
 
The keeper sleeps by day.
 
La lámpara se enciende al anochecer,
 
y se despabila antes del alba.
 
:::space
 
El farero duerme de día.
:::
:::

Qui il quarto blocco, «La lámpara…», apre la seconda colonna; le due righe :::space non vengono contate e lasciano lo stesso spazio in entrambe le colonne.

Dividere un gruppo

Da postext 1.25 un gruppo che non entra nello spazio che ha (il resto della sua colonna nel testo corrente, o la parte di un riquadro che si divide, con keepTogether: false o perché più alto di una colonna) viene tagliato tra le sue colonne e prosegue nella colonna o nella pagina successiva, in un riquadro a sé se il gruppo è in un riquadro:

• flow="snake", il predefinito senza breaks: i blocchi del gruppo scorrono come un’unica bozza in colonna, come il testo di un articolo di giornale. Una parte che prosegue riempie le sue colonne una dopo l’altra, il più allineate possibile secondo i tagli, tagliando tra blocchi o tra le righe di un paragrafo o di una voce di elenco (almeno layout.boxChildSplitMinLines delle sue righe su ogni lato, due per impostazione predefinita); l’ultima parte viene bilanciata come un gruppo intero.
• flow="parallel", il predefinito con breaks: ogni sequenza che le interruzioni fanno cominciare è un flusso che mantiene la propria colonna. Una parte riempie ogni flusso fino allo spazio che ha, e ognuno prosegue nella stessa colonna della parte successiva, così una poesia e la sua traduzione composte affiancate restano allineate strofa per strofa. Un gruppo parallelo senza breaks prosegue come un gruppo a serpentina.

Un riquadro annidato in un gruppo resta intero e passa alla parte successiva, e un gruppo dentro un riquadro annidato non viene mai tagliato. Un gruppo che entra viene composto esattamente come prima. layout.flowColumns: false mantiene le regole di postext 1.24: un delimitatore fuori da un riquadro viene ignorato e un gruppo non viene mai tagliato; i libri salvati prima della 1.25 che contengono un gruppo :::columns vengono letti così. La Sandbox segnala un flow che non conosce (Flusso di colonne sconosciuto) e colonne più strette di sei em del loro testo (Colonne troppo strette).

## Briefs
 
:::columns{count=3 span="page" rule}
**Harbour.** The new pier opens on Monday…
 
**Market.** Stall rents stay as they are…
 
**Weather.** Rain from the west by the evening…
:::

Un delimitatore :::callout accetta anche label="…": il testo che uno stile con una linguetta label stampa nell’angolo superiore del riquadro (:::callout{type="box" label="BOX 1-1" title="The octet rule"}).

Un :::callout dentro un altro è un riquadro a sé: per esempio una scheda di esercizi che contiene riquadri per le risposte. Prende il proprio stile (sfondo, bordo, raggio, spaziatura interna, titolo, icona) alla piena larghezza interna del riquadro esterno e si impila tra gli altri blocchi; i suoi span e placement vengono ignorati, perché un riquadro annidato scorre sempre dentro il suo genitore. Ogni delimitatore chiude il riquadro più interno ancora aperto:

:::callout{type="card"}
The statement of the exercise.
 
:::callout{type="answer"}
A white answer box with its own border and padding.
:::
 
:::callout{type="answer"}
A second answer box.
:::
:::

Quando il riquadro esterno si divide tra colonne o pagine (keepTogether: false, o perché più alto di una colonna), un riquadro annidato passa intero al frammento successivo, a meno che il suo stile non gli permetta di dividersi a sua volta; ogni frammento ridisegna le cornici che contiene, e un riquadro annidato che prosegue perde l’icona, e il titolo a meno che il suo stile non lo ripeta (repeatTitle).

#:::paper

Un libro può cambiare carta per una sequenza di pagine: una sezione di tavole su carta patinata lucida in un libro stampato su carta usomano, un inserto in cartoncino, qualche foglio di carta colorata. Racchiudi quel contenuto in un contenitore :::paper:

:::paper{type=coatedGloss grammage=130}
## Plates
::resource{id="plate-1"}
::resource{id="plate-2"}
:::

Una carta copre fogli interi, quindi il contenuto tra i delimitatori comincia su una nuova pagina, e anche ciò che segue il ::: di chiusura comincia su una nuova pagina. Una sequenza che chiude il documento non lascia una pagina bianca dopo di sé. Le figure e le tabelle citate dentro la sequenza vengono posizionate prima che si chiuda. Ogni pagina composta con contenuto proveniente dall’interno del contenitore porta la carta nell’impaginazione (VDTPage.paper, gli attributi così come li scrive il delimitatore); le pagine fuori non portano nulla. Il visualizzatore Folio la legge e disegna quei fogli con il colore, la superficie, lo spessore e la rigidità della carta. Gli output canvas, PDF e HTML la ignorano: le pagine vengono composte e stampate come tutte le altre.

Gli attributi sono quelli delle impostazioni folio.paper, e sono tutti facoltativi. Uno che il delimitatore omette segue la carta del documento e, oltre quella, i valori predefiniti della carta:

Un :::paper dentro un altro sostituisce solo gli attributi che imposta, e anch’esso comincia e finisce con un’interruzione di pagina. Dentro un :::callout i delimitatori vengono ignorati. Un valore che il motore non riesce a leggere viene scartato, e la Sandbox lo elenca come avviso Attributo della carta non valido (paperAttributeInvalid nei contentWarnings del documento).

#:::pagebreak

La direttiva di per sé non impone la parità: agisce solo sull’impaginazione del blocco successivo. Usala per chiudere una prefazione, mettere una dedica su una pagina a sé o segnare la fine di una sezione. Quando nello stesso punto servono sia un’interruzione di pagina sia un azzeramento della numerazione, scrivi :::pagebreak seguita da :::numbering: il cambio di numerazione si applica alla pagina nuova che :::pagebreak ha appena creato.

Un’interruzione di pagina su una pagina ancora vuota non fa nulla, quindi non aggiunge mai una pagina bianca. Non sostituisce nemmeno il breakBefore di un titolo che la segue subito (il livello 1 ne ha uno per impostazione predefinita): il titolo applica comunque la sua parità, che può aggiungere una pagina bianca dopo quella aperta dalla direttiva. Per far cominciare un titolo esattamente lì, disattiva la sua interruzione (vedi Configurazione → Stili dei titoli). Dopo un titolo di copertina che riempie la sua pagina l’interruzione è facoltativa: la copertina occupa già il resto della sua pagina, nelle impaginazioni a una o a più colonne, e un :::pagebreak subito dopo non fa danni. Serve solo dopo una copertina il cui progetto grafico si ferma prima del piede della pagina, quando il testo deve comunque cominciare alla pagina successiva (vedi Configurazione → Altezza riservata).

The old chapter ends here.
 
:::pagebreak{parity="odd"}
 
# A new chapter

Il flag center (:::pagebreak{center}, disattivato con center=false) centra il testo della pagina che l’interruzione apre tra la testa e il piede della gabbia del testo, in orizzontale nel testo verticale: il ページの左右中央 dell’occhiello di parte o della dedica di un libro giapponese. Elementi flottanti, note e testatine restano dove sono, e una pagina già piena resta com’è. Il flag non chiude la pagina: chiudila con un altro :::pagebreak.

:::pagebreak{center}
 
# 上　先生と私
 
:::pagebreak

Attributo di parità

L’attributo parity accetta gli stessi cinque valori di headings.levels[*].breakBefore.parity:

• 'any': il predefinito, nessun vincolo di parità; l’interruzione apre semplicemente una nuova pagina.
• 'odd' / 'even': la nuova pagina si apre sul lato richiesto della doppia pagina; si inserisce una sola pagina bianca solo quando la pagina successiva naturale cade sul lato sbagliato.
• 'always-odd' / 'always-even': garantiscono almeno una pagina bianca di separazione obbligatoria tra il contenuto precedente e la nuova pagina, poi impongono la parità. La pagina bianca di separazione appartiene al capitolo precedente; qualsiasi ulteriore pagina di riempimento per la parità appartiene a ciò che segue.

A chi appartengono le pagine bianche

I due tipi di pagina bianca che :::pagebreak (e breakBefore) possono introdurre si distinguono nel modello VDTPage:

• blankForParity: true: inserita per soddisfare un vincolo di parità. Nelle intestazioni con {chapterTitle} questa pagina porta il titolo del capitolo successivo, perché la pagina bianca esiste solo per spingere quel capitolo sulla parità giusta.
• blankForForce: true: il separatore iniziale obbligatorio di una modalità 'always-*'. Appartiene al capitolo precedente: una pausa voluta a fine capitolo, non un riempimento di parità per il capitolo successivo.

Le stesse due regole danno a una pagina bianca le testatine e la tavolozza di una sezione stilizzata: vedi Configurazione › Stili dei titoli.

Eccezione all’inizio del documento

Quando :::pagebreak è il primissimo costrutto di un documento (o un titolo con breakBefore ne introdurrebbe uno), l’imposizione della parità viene saltata finché la prima pagina è ancora vuota. Il blocco successivo cade a pagina 1 così come è scritto, qualunque sia la parità richiesta: nessuna pagina bianca iniziale spuria.

#:::numbering

:::numbering è il modo per far ripartire il contatore delle pagine a metà documento. L’esempio canonico di un libro:

---
title: "A Book With Front Matter"
---
 
# Preface
 
…
 
:::pagebreak{parity="odd"}
:::numbering{format="decimal" startAt=1}
 
# Chapter 1

Le pagine della prefazione sono numerate i, ii, iii, …; il primo capitolo si apre su una pagina di destra numerata 1.

I cambi solo di formato (senza startAt) lasciano scorrere il contatore: utile, per esempio, per passare da lower-alpha a upper-alpha senza azzerarlo.

format accetta qualsiasi grafia di un formato di numerazione: roman-lower e i funzionano come lower-roman, arabic come decimal, 一 e あ come japanese-informal e hiragana (vedi Configurazione › Grafie dei formati di numerazione). Un valore che non corrisponde a nessuno di essi lascia il formato com’era, e la Sandbox lo segnala.

lines fa ripartire il conteggio dei numeri di riga, non il contatore delle pagine: la riga successiva che viene contata prende il numero indicato, qualunque cosa dica lineNumbers.restart. Un valore che non è un numero intero pari o superiore a 0 viene ignorato.

## Act II
 
:::numbering{lines=1}

#:::space

:::space lascia uno spazio verticale tra due blocchi: per separare una riga di chiusura dal testo sopra, per spingere un po’ più in basso un’epigrafe o una firma, o per aprire uno stacco tra due parti di testo. Le righe vuote in più nel Markdown non lo fanno: come in qualsiasi Markdown, una sequenza di righe vuote è un solo separatore di paragrafo, e questo impedisce che un documento cambi impaginazione quando un editor o un formattatore aggiunge o toglie spazi bianchi.

The last paragraph of the scene.
 
:::space
 
A new scene begins one line lower.
 
:::space{lines=2}
 
Two lines lower still.

• lines: quanto spazio, in righe del testo corrente (la griglia della linea di base). Predefinito 1. I numeri interi mantengono ogni riga di testo sulla griglia, così le colonne restano allineate su tutta la pagina; una frazione (lines=0.5) viene rispettata esattamente, al prezzo di perdere quell’allineamento fino al blocco successivo che si aggancia alla griglia. Un valore che non è un numero maggiore di 0 e al massimo 20 ripiega su una riga, e la Sandbox lo segnala (Dimensione dello spazio non valida).
• Si somma. Lo spazio si aggiunge al margine che già separa i due blocchi (il margine superiore di un titolo, il margine inferiore di un elenco) invece di fondersi con esso. Due righe :::space consecutive aggiungono due righe.
• Viene scartato a un’interruzione, come il \vspace di LaTeX: in cima a una colonna o a una pagina scompare, così una pagina non si apre mai con un buco; e quando non entra al piede di una colonna chiude semplicemente quella colonna, senza riportare il resto.
• Il paragrafo che segue è composto senza rientro. Quando bodyText.indentAfterHeading è disattivato, un paragrafo subito dopo :::space perde il rientro della prima riga, come dopo un titolo: la convenzione abituale per il testo che riprende dopo una riga vuota.
• Dentro un riquadro (o un gruppo :::columns) separa allo stesso modo i figli del riquadro, misurato nelle righe del testo del riquadro stesso. Prima del primo blocco del riquadro viene scartato, come in cima a una colonna (la spaziatura interna separa già il contenuto dalla cornice), tranne in due casi in cui apre quello spazio: subito sotto il titolo del riquadro e in un riquadro che non contiene nient’altro (un riquadro per la risposta, uno spazio per scrivere, dimensionato in righe). Scompare sempre in cima a un gruppo :::columns, in testa a ciascuna delle sue colonne e in cima alla parte di un riquadro diviso che prosegue nella colonna o nella pagina successiva. Dentro un contenitore :::paragraphs funziona come tra paragrafi del testo corrente.
• Tenere con il successivo lo conta: un titolo seguito da :::space passa oltre quando lo spazio e le prime righe del suo testo non entrano sotto di esso.

Un riquadro per la risposta in una scheda di esercizi è un riquadro il cui unico contenuto è spazio: la domanda nel titolo, quattro righe di spazio sotto.

:::callout{type="answer" title="1. Name the three parts of the lantern."}
:::space{lines=4}
:::

Per un’interruzione fissa invece che uno spazio, usa :::columnbreak o :::pagebreak.

#:::verse

Una poesia. :::verse la compone in una di due impaginazioni: verso per verso, come si stampa la maggior parte delle poesie, oppure nell’impaginazione araba classica di una qaṣīda, con ogni bayt in due emistichi affiancati. Una poesia i cui versi portano un separatore di emistichi (||, o un \\ circondato da spazi) prende l’impaginazione araba, qualsiasi altra quella verso per verso; layout=lines o layout=bayt sul delimitatore ne indica una.

Verso per verso

Scrivi la poesia come viene stampata: un verso per riga di Markdown, una riga vuota tra le strofe e spazi prima di un verso per rientrarlo.

:::verse
Whose woods these are I think I know.
His house is in the village though;
  He will not see me stopping here
  To watch his woods fill up with snow.
 
My little horse must think it queer
To stop without a farmhouse near
:::

• Versi. Ogni riga non vuota è un verso, letto a sé come Markdown in linea: corsivo, maiuscoletto, note e rimandi funzionano tutti. Una sequenza di righe vuote è un’unica separazione tra strofe.
• Rientri. Ogni spazio iniziale è largo indentStep, 0,5 em per impostazione predefinita, quindi due spazi rientrano un verso di un em; una tabulazione conta quattro spazi e uno spazio ideografico (U+3000) due.
• A capo dei versi lunghi. Un verso poco più largo della giustezza prima stringe gli spazi tra le parole, fino a bodyText.minWordSpacing della loro larghezza naturale (il limite a cui si restringe il testo giustificato), e resta su una riga; tighten=false sul delimitatore, o bodyText.verse.tighten: false, lo manda invece a capo. Un verso ancora più largo va a capo a uno spazio tra parole. Con turnover=hang (il predefinito) il resto pende sulla riga successiva, rientrato di hang rispetto all’inizio del verso: l’hangingIndent dello stile di paragrafo della poesia, altrimenti 2 em (bodyText.verse.hang). Con turnover=right viene composto a filo con la fine della giustezza dietro una parentesi aperta (turnoverMark, [ per impostazione predefinita), l’uso delle edizioni inglesi e spagnole. I versi non vengono sillabati, a meno che il loro stile di paragrafo non imposti esso stesso hyphenation: true. Un verso e il suo a capo non si separano mai a un’interruzione di colonna o di pagina.
• Strofe. Lo spazio tra due strofe è una riga dell’interlinea della poesia; stanzaSpace=0.5 lo rende di mezza riga, e una lunghezza (stanzaSpace=6pt) lo fissa esattamente. Sulla griglia della linea di base risulta in righe intere della griglia. Colonne e pagine si interrompono prima tra le strofe; dentro una strofa si interrompono secondo le regole di orfane e vedove, che allora contano i versi della strofa. keepStanzas=N mantiene intera qualsiasi strofa di N versi o meno: un haiku prende keepStanzas=3, un tanka keepStanzas=5.
• Posizione. La poesia viene centrata nella giustezza sul suo verso più lungo, con ogni verso a filo con l’inizio della poesia (align=center, l’impostazione abituale per una poesia citata in prosa); align=start la compone a filo con l’inizio della giustezza, il predefinito nel testo verticale. Il paragrafo che introduce la poesia tiene la sua ultima riga con i primi versi.
• Versi a gradino. Un verso scritto + … comincia dove è finito il verso sopra, uno spazio tra parole più in là, come un verso drammatico diviso tra due personaggi. Scrivi \+ per un verso che comincia con un segno più.
• Cesure. Con keepSpaces sul delimitatore, una sequenza di due o più spazi dentro un verso mantiene la sua larghezza; senza, gli spazi si riducono come in qualsiasi paragrafo.
• Carattere e direzione. style indica uno stile di paragrafo, che dà il carattere, il corpo, l’interlinea, indent e lo spazio sopra e sotto la poesia. dir e lang ne impostano la direzione e la lingua: una poesia latina in un libro arabo (dir=ltr) viene rientrata dal proprio lato iniziale. Nel testo verticale ogni verso è una colonna, rientrata dalla testa.

bodyText.verse imposta i valori predefiniti per tutte le poesie (vedi Configurazione › Versi). Il testo semplice conserva la poesia come è scritta, un a capo tra i versi e una riga vuota tra le strofe, così un passo copiato e una ricerca la leggono verso per verso; l’EPUB a layout fluido compone una strofa come un elemento i cui versi fanno pendere i loro a capo, e il PDF con tag marca una strofa come paragrafo.

Numeri di riga. Con lineNumbers attivo, i versi di una poesia vengono contati (vedi Configurazione › Numeri di riga). Ogni verso conta una volta: un a capo non prende numero e lo spazio tra le strofe non viene contato. Per impostazione predefinita ogni quinto verso stampa il suo numero nel margine esterno e il conteggio riparte a ogni poesia. Una poesia nell’impaginazione araba classica conta una riga per bayt. Il delimitatore regola una singola poesia: lineStart=N dà un numero al suo primo verso, interval=N il suo intervallo proprio e numbered=false la esclude.

:::verse{lineStart=37}
…
:::

Con l’intervallo predefinito di 5, questa poesia stampa 40, 45 e così via accanto ai suoi versi.

Impaginazione araba classica

Una poesia nell’impaginazione araba classica (una qaṣīda, una qiṭʿa): ogni verso, il bayt, su una riga in due metà, il ṣadr sul lato iniziale (la destra in arabo) e l’ʿajuz sul lato finale, con uno spazio tra loro. Scrivi un bayt per riga, con gli emistichi separati da || (funziona anche un \\ con uno spazio per lato, come nei testi di Wikisource). Una riga senza separatore è un emistichio singolo, centrato sulla poesia.

فأنشد يقول:
 
:::verse
يَا حُرْقَةَ الدَّهْرِ كُفِّي || إِنْ لَمْ تَكُفِّي فَعِفِّي
فَلَا بِحَظِّيَ أُعْطِي || وَلَا بِصَنْعَةِ كَفِّي
:::

• Una sola larghezza. Ogni emistichio della poesia viene composto alla stessa larghezza, così ogni ṣadr comincia sulla stessa verticale e ogni ʿajuz finisce su un’altra, e le lettere della rima si allineano lungo la poesia. La larghezza è quella dell’emistichio più largo, al massimo metà della giustezza meno lo spazio centrale; width la imposta (width=55mm). Ogni emistichio viene portato a quella larghezza prima con le kashida (il verso si allunga più della prosa: il doppio di bodyText.kashidaMaxLength), poi con gli spazi tra le parole; un emistichio di una sola parola che non riesce a riempirla lascia il resto nello spazio centrale.
• Lo spazio centrale è di 2 em per impostazione predefinita; gap lo imposta (gap=3em, un numero senza unità è in em). ornament stampa un segno al suo centro (ornament="٭"), che non fa parte del testo.
• Troppo largo. Un emistichio più largo della larghezza comune prima stringe gli spazi tra le parole fino a bodyText.minWordSpacing. Se ancora non entra, il suo bayt viene composto sfalsato: il ṣadr a filo con il lato iniziale su una riga a sé, l’ʿajuz a filo con il lato finale sulla successiva.
• Posizione. La poesia viene centrata nella colonna; align=start la compone a filo con il lato iniziale. Un bayt non viene mai diviso tra colonne o pagine, e la poesia segue le regole di orfane e vedove dei paragrafi (una poesia di tre bayt o meno resta intera). Il paragrafo prima della poesia, che la introduce («فأنشد يقول:»), tiene la sua ultima riga con i primi bayt.
• Carattere. La poesia prende il carattere, il corpo e l’interlinea del testo corrente; style le assegna uno stile di paragrafo (style="verse"), ed è così che una poesia vocalizzata ottiene l’interlinea in più di cui hanno bisogno le sue harakat. dir=ltr o dir=rtl ne imposta la direzione come per qualsiasi blocco; una poesia in caratteri latini in un libro da sinistra a destra ha il ṣadr a sinistra.

Il testo semplice della poesia tiene separati emistichi e bayt (una tabulazione e un a capo), così una ricerca o un passo copiato la leggono come è scritta; le kashida e l’ornamento vengono esclusi.

#:::toc

:::toc stampa l’indice nel punto in cui si trova. Si espande in blocchi ordinari (uno per ogni titolo dei livelli elencati da toc.levels, il livello 1 per impostazione predefinita, e uno per ogni :::part), così l’indice scorre tra colonne e pagine come qualsiasi altro testo e un clic su una voce porta alla riga della direttiva. Una voce mostra il numero del titolo (l’output del suo numberingTemplate, altrimenti l’ordinale del capitolo), il suo titolo, una linea di puntini di guida e l’etichetta della pagina in cui comincia e, quando toc.subtitle è attivo, una seconda riga con un attributo del titolo come l’{author="…"} del capitolo. Una parte ha una riga propria, disegnata da toc.parts.design e colorata con la palette della parte stessa. I titoli il cui stile ha numbered: false vengono elencati senza numero; {toc="false"} su un titolo lo esclude (di solito il titolo dell’indice stesso).

# Contents {style="front-matter" toc="false"}
 
:::toc

I numeri di pagina sono quelli che il documento stampa davvero. Un documento impaginato da solo viene reimpaginato con le etichette della passata precedente finché non si spostano più: con la numerazione che riparte dopo le pagine preliminari (la ricetta :::numbering vista sopra) basta una passata in più. Un capitolo impaginato da solo (le anteprime della Sandbox) riceve invece dal suo host lo schema dell’intero libro. Vedi Indice nel riferimento della configurazione.

#:::index

:::index stampa l’indice analitico nel punto in cui si trova: i termini marcati con :index[…] o :index{term="…"} in tutto il libro, con le loro pagine, che seguono il testo quando si sposta. È descritto insieme ai marcatori in Indice analitico. Una colonna non finisce mai dopo la prima voce di un gruppo, né prima dell’ultima: due voci del gruppo restano e due proseguono, oppure il gruppo si sposta intero (index.groups.splitMinEntries).

# Index {style="index"}
 
:::index

#A capo

Le righe di un paragrafo si uniscono con uno spazio. Per chiudere una riga dentro un paragrafo senza cominciarne uno nuovo (un indirizzo, il saluto di una lettera, una dedica), termina la riga sorgente con una barra rovesciata, l’a capo forzato di CommonMark, oppure scrivi \\ seguito da uno spazio:

To the keeper of the lighthouse,\
at the end of the northern pier.
 
Ana Ruiz \\ Calle Mayor 4 \\ 28013 Madrid

• La riga prima di un a capo viene composta alla sua larghezza naturale, come l’ultima riga di un paragrafo, mai allungata alla giustezza. Il testo che segue apre una nuova riga dello stesso paragrafo, senza rientro della prima riga e senza spazio sopra; sotto un rientro sporgente pende come qualsiasi riga dopo la prima.
• Lo accettano paragrafi, citazioni (> First line\ sopra > second line), note a piè di pagina e voci di elenco. Una voce di elenco è una sola riga sorgente, quindi va a capo con \\.
• Una barra rovesciata che chiude il paragrafo viene stampata, come in CommonMark, e due a capo consecutivi ne fanno uno: per una riga vuota, comincia un nuovo paragrafo o aggiungi un :::space.
• Un \\ attaccato al carattere successivo non è un a capo: \\* stampa una barra rovesciata e un asterisco con escape, C:\\Temp entrambe le barre. Nel codice in linea e in una formula le barre rovesciate appartengono al codice e alla formula.
• Due spazi a fine riga, l’altro a capo forzato di CommonMark, non lo sono: non si vedono in un editor e molti editor li lasciano in giro, quindi spezzerebbero righe che nessuno voleva spezzare.
• Il testo copiato dal visualizzatore HTML ha un a capo nel punto dell’interruzione, l’EPUB a layout fluido un <br/>, il testo del PDF una fine riga e un’esportazione Word un’interruzione di riga manuale (Maiusc+Invio), che l’importazione da Word rilegge come a capo.
• Una poesia mantiene versi, rientri e strofe in un blocco :::verse, senza barra rovesciata su ogni riga.

Fino a postext 1.22 la barra rovesciata veniva stampata e le righe si univano con uno spazio. Un libro salvato allora il cui testo chiude una riga con una barra rovesciata, o mette \\ prima di uno spazio, mantiene quella lettura (bodyText.hardLineBreaks: false, vedi Configurazione › Pacchetti scritti da postext 1.4 o precedenti).

#A capo nei titoli

Scrivi \\ dentro un titolo (o dentro l’attributo title di una parte) per forzare un a capo dove il titolo viene mostrato come titolo: il titolo nella colonna continua a scorrere e lì mostra uno spazio, mentre il {titleText} di un progetto di apertura va a capo in quel punto (in ogni modalità overflow dell’elemento di testo). Le testatine, {chapterTitle}, {partTitle} e i segnalibri del PDF mostrano sempre il titolo su una riga. In cinese o in giapponese l’a capo si legge come uno spazio ideografico tra due caratteri della scrittura (un titolo a distico); dove uno di essi incontra una cifra o un testo latino (关于举办 \\ 2026年…) la pagina mette lo spazio tra han e latino, e i segnalibri del PDF e il titolo del documento uniscono le due metà senza nulla, come si scrive il cinese semplice.

# Concepts of health and illness. \\ Community health {author="I. Zango Martín"}

#Formattazione in linea

Il markup in linea viene riconosciuto dentro qualsiasi blocco di testo (titoli, paragrafi, citazioni, voci di elenco). In un titolo segue headings.inlineMarks, attivo per impostazione predefinita: il corsivo, il grassetto, gli apici e i pedici, il maiuscoletto e i link del titolo si stampano come in un paragrafo, e una sequenza in corsivo in un titolo in corsivo risulta in tondo. Con l’opzione disattivata i marcatori vengono eliminati e il titolo si stampa nello stile proprio del titolo; le configurazioni salvate da postext 1.4 o precedenti i cui titoli contengono segni vengono lette in questo modo (vedi Configurazione › Titoli). Il progetto di un titolo stampa {titleText} come testo semplice in entrambi i casi.

Markup	Sintassi	Note
Grassetto	bold o bold	Si disegna con bodyText.boldFontWeight. Un bodyText.boldColor facoltativo sostituisce il colore predefinito del testo per le sequenze in grassetto.
Corsivo	italic o italic	Si disegna con la variante corsiva della famiglia di caratteri corrente. Un bodyText.italicColor facoltativo sostituisce il colore predefinito del testo per le sequenze in corsivo. Un trattino basso marca l’enfasi solo al confine di una parola, come in CommonMark: uno tra due lettere o cifre (snake_case_name, il SR_AIR_EN.pdf di un URL) è testo (anche per bold); dentro una parola, usa gli asterischi (unbelievable). Le lettere cinesi, giapponesi e coreane qui non contano, perché quelle scritture non hanno spazi: 中文_斜体_中文 e 中文__粗体__中文 sono corsivo e grassetto. Un __ che non produce grassetto non diventa mai corsivo: foo__bar__baz resta testo.
Grassetto corsivo	both o both	I due attributi si combinano.
Apice	^text^	Composto al 58% del corpo del testo e alzato di un terzo: un esponente (10^-8^), la carica di uno ione (Na^+^). Il testo marcato inizia e termina con un carattere diverso dallo spazio; un accento circonflesso isolato nella prosa resta letterale, e così le faccine ^_^ e ^o^ (n.^o^ e 1^o^ sono comunque apici).
Pedice	~text~	Stesso corpo, abbassato di 0,15 del corpo del testo, così resta entro i discendenti: un indice chimico (H~2~O, pK~a~). Una tilde con una cifra su ciascun lato è un intervallo e resta letterale: 3~5 days, 需要3~5天. Lo stesso vale per una tilde tra due parole cinesi, che non apre un pedice: 周一~周五, 北京~上海; un pedice si chiude comunque prima di un carattere cinese (F~合~等于). Si combina con grassetto e corsivo (H~2~O). Un pedice e un apice scritti insieme, senza nulla in mezzo, vengono impilati come in una formula: T~0~^2^ mette il 2 sopra lo 0, qualunque dei due venga prima, con il pedice abbassato di 0,25 del corpo del testo per liberare l’apice, e la coppia prende la larghezza del più largo. Uno spazio o una lettera tra di essi li compone uno dopo l’altro; lo fa anche un word joiner (U+2060), senza nulla di visibile in mezzo. Una coppia impilata non si separa mai a un a capo: una parola troppo larga per la riga va a capo prima della coppia.
Maiuscoletto	:smallcaps[text]	Le lettere minuscole si compongono come maiuscole al 70% del corpo del testo: il nome di un personaggio in un’opera teatrale, una sigla nel testo corrente. Accetta altri segni al suo interno e intorno; vedi Maiuscoletto.
Orientamento nel testo verticale	:tcy[12], :upright[GDP], :sideways[12]	Nel testo verticale: una cella diritta (tate-chu-yoko), ogni carattere diritto in una cella propria, o l’intera sequenza ruotata. Nessun effetto nel testo orizzontale; vedi Orientamento nel testo verticale.
Segni cinesi	:dots[不可], :name[賈寶玉], :book[石頭記]	Punti di enfasi (着重号), la linea dei nomi propri (专名号) e il segno dei titoli di libri (书名号: 《》 o una linea ondulata, secondo cjk.bookTitleMark). Il testo resta come è scritto; vedi Segni cinesi, ruby e warichu.
Ruby	:ruby[紅樓]{rt="hóng lóu"} o {紅樓|hóng|lóu}	Letture pinyin o zhuyin sopra (o accanto a) i caratteri di base. La forma compatta richiede una base in Han, kana o bopomofo, quindi {x|x>0} resta testo.
Warichu	:warichu[note]{open="〔" close="〕"}	Una nota composta in due righe a metà grandezza dentro la riga (双行夹注), divisa tra righe e pagine.
Codice in linea	code	Gli apici inversi vengono eliminati; la sequenza si disegna come testo semplice, esattamente come è scritta: un , un chip, una formula, un link o un marcatore di enfasi al suo interno si stampa letteralmente, ed è così che un testo mostra la sintassi. Si compone nel carattere del testo, oppure, con codeStyle.inline, nel carattere del codice come un’unità (vedi Configurazione › Listati di codice). Un listato va in un blocco di codice.
Escape	, , , , ,	Una barra rovesciata compone il carattere marcatore stesso invece di aprire una sequenza: l’asterisco di una nota di tabella (), un accento circonflesso letterale, un simbolo del dollaro che non apre una formula. Funziona nel testo, nei chip e in didascalie, celle e note. (Fino a postext 1.4 didascalie, celle, note e chip stampavano la barra rovesciata di .)
Spazio non separabile	il carattere stesso: U+00A0, U+202F, U+2007	Incolla le parole ai suoi lati, così una riga non va mai a capo tra di esse: un numero e la sua unità (37 °C), un riferimento di pagina (p. 12), un gruppo di migliaia (225 000). Lo spazio non separabile (U+00A0), lo spazio stretto non separabile (U+202F) e lo spazio cifra (U+2007) incollano tutti, nel testo, nelle didascalie, nelle celle, nei riquadri e nelle testatine, e ognuno conserva la propria larghezza: la giustificazione allarga solo gli spazi tra parole. Molti caratteri non hanno un glifo per lo spazio stretto non separabile o per lo spazio cifra; in quel caso si compongono come li compongono i browser, nel canvas, nell’HTML e nel PDF allo stesso modo: mezzo spazio tra parole e la larghezza di una cifra. Praticamente ogni carattere ha U+00A0, quindi è la scelta sicura. Un gruppo incollato in questo modo che è più largo dell’intera riga va a capo al suo ultimo spazio non separabile invece che dentro una parola. Il word joiner (U+2060) incolla senza occupare spazio. Digita il carattere stesso: un’entità HTML come si stampa come è scritta. Vedi Dove una riga non va mai a capo.
Trattino morbido	il carattere stesso: U+00AD	Un punto in cui la parola può essere divisa, con l’aggiunta di un trattino quando lì termina una riga: solo tra due lettere o cifre. Una parola che ne contiene uno non riceve altre divisioni dal dizionario, quindi il trattino morbido è la sua unica divisione; digitato prima della prima lettera di una parola non divide nulla e mantiene intera quell’occorrenza. Accanto a una parentesi, a una virgoletta o a un segno di punteggiatura non fa nulla. Vedi Dove una riga non va mai a capo.
Link	text	Il testo visibile resta nel flusso, composto esattamente come senza il link. L’URL rende le parole un link attivo nell’output HTML e PDF; vedi Link.
Immagine		Il markdown di un’immagine in linea viene rimosso dal testo. Le immagini vanno dichiarate in PostextContent.resources così che il motore di impaginazione possa collocarle secondo le regole di resourcePlacement.
Chip	:chip[text]	Una sequenza di testo in un riquadro che va a capo come un’unità: una banca di parole, un tasto, un’etichetta. Lo stile viene da chipStyles; vedi Chip in linea.
Tabulazione	:tab, :tab{at=120mm align=end leader="."}	Manda le parole che la seguono al tabulatore successivo: uno dei tabulatori dello stile del paragrafo, o quello impostato dai suoi attributi. Un carattere di tabulazione digitato nel testo è una tabulazione solo dove lo stile imposta dei tabulatori. Vedi Tabulazioni e tabulatori.
Formula in linea	$…$	Una formula LaTeX che scorre con il testo circostante, per esempio $e^+1=0$. Composta da MathJax e disegnata come tracciati vettoriali in ogni backend. Usa \$ per un simbolo del dollaro letterale. Il ridimensionamento, la forma in display ($$ … $$) e la gestione degli errori sono trattati in Formule matematiche.

#Link

Un link Markdown, [text](url), mantiene il suo testo nel flusso esattamente come verrebbe composto senza: il link non cambia mai gli a capo, la spaziatura o il colore. Conserva il suo URL per gli output che possono seguirlo:

• HTML (renderToHtml): le parole collegate vengono racchiuse in <a href="…" rel="noopener noreferrer">, che prende il colore del testo e non ha sottolineatura. C’è un’ancora per ogni sequenza di parole collegate su una riga.
• PDF (postext-pdf): ogni sequenza di parole collegate su una riga diventa un’annotazione di link URI cliccabile. In un PDF con tag è un elemento Link il cui testo sono le parole collegate.
• Canvas: dipinto come testo semplice, perché un canvas non ha una superficie cliccabile.

Read the [configuration guide](https://postext.dev/en/docs/configuration "Configuration")
or write to [the team](mailto:team@example.com).

• La destinazione può avere un titolo, che viene ignorato ([text](https://example.com "Title")). Può anche essere racchiusa tra parentesi angolari, dove gli spazi diventano %20 ([text](<https://example.com/a b>)).
• Si conservano solo le destinazioni sicure: http:, https:, mailto:, tel:, ftp: e gli URL relativi (../guide, #top). Qualsiasi altro schema (javascript:, data:, file:…) compone il testo senza link. Il PDF collega solo URL assoluti.
• La destinazione può contenere parentesi purché siano bilanciate, come in CommonMark: [photo](https://commons.wikimedia.org/wiki/File:Bike_(Unsplash).jpg) collega l’intero URL. Una barra rovesciata protegge un carattere (\(, \_). Quando le parentesi non sono bilanciate, la destinazione termina alla sua prima ) e il testo si compone senza link; codifica una parentesi isolata come %28 o %29. Anche uno spazio termina la destinazione, a meno che non sia racchiusa tra parentesi angolari.
• Una parola attaccata al testo del link condivide il link. In see [the site](https://example.com). il punto fa parte dell’area cliccabile.
• Il testo del link può contenere enfasi ([**bold** words](…)) e può stare dentro un’enfasi (**[words](…)**).
• I link funzionano in paragrafi, voci di elenco, citazioni, riquadri, didascalie, note e celle di tabella, e nei titoli finché headings.inlineMarks è attivo (il valore predefinito). Le testatine, la struttura e le righe del sommario ricavate da un titolo conservano solo il testo, e lo stesso vale per il testo di un :chip[…].
• I link in stile riferimento ([text][id]) e gli autolink (<https://…>) non vengono riconosciuti (vedi Che cosa NON è supportato).

Nel VDT la destinazione sta su ogni segmento collegato, come VDTLineSegment.href. Il parser conserva i link di una sequenza come intervalli del suo testo, in InlineSpan.links, e non divide mai una sequenza per un link: per questo un link non può cambiare l’impaginazione.

#Chip in linea

:chip[text] compone text in un riquadro (un «chip» arrotondato e colorato) che scorre con la riga: le parole di una banca di parole o di un esercizio di classificazione, i tasti della tastiera, le etichette. :chip[text]{style="key"} sceglie uno stile con nome da chipStyles (vedi il riferimento della configurazione); senza style, o con un id che nessuno stile dichiara, il chip prende il primo stile (uno stile chip incorporato quando la configurazione non ne ha; la Sandbox avvisa di un id sconosciuto).

Classify: :chip[battery] :chip[cable] :chip[switch] :chip[bulb]
 
Press :chip[Ctrl]{style="key"} + :chip[C]{style="key"} to copy.

• Un’unità. Un chip non viene mai diviso né sillabato al suo interno; la riga va a capo tra i chip, negli spazi tra parole che li circondano. Un chip più largo dell’intera riga deborda invece di dividersi.
• Larghezza. Il suo avanzamento è il testo più il padding orizzontale e il contorno su entrambi i lati. La giustificazione allarga solo gli spazi tra parole, mai l’interno di un chip. Il gap dello stile è lo spazio minimo mantenuto tra il riquadro e una parola o un chip vicino attraverso uno spazio: uno spazio più stretto viene integrato (non a un bordo della riga, e non contro una punteggiatura attaccata come :chip[a],).
• Altezza. Il riquadro è una fascia intorno alla linea di base, 0,8 em sopra e 0,25 em sotto al corpo del chip, allargata dal padding verticale e dal contorno. Il padding verticale si dipinge fuori dal riquadro di riga e non cambia mai l’interlinea, così la griglia della linea di base regge; un riquadro più alto del passo di riga può invadere un chip della riga sopra o sotto, e la Sandbox segnala due chip su righe diverse che si sovrappongono («Chip che toccano la riga successiva») così che padding, contorno o corpo si possano ridurre.
• Testo. Il testo del chip accetta i propri segni in linea (:chip[**bold** word], :chip[x^2^]) e l’enfasi intorno (**:chip[a]**); lo stile può impostarne famiglia, corpo, colore, grassetto e corsivo. Scrivi \] per una parentesi quadra letterale al suo interno. Rimandi, campioni di colore e formule dentro un chip restano letterali, e \$ stampa un simbolo del dollaro (fino a postext 1.4 stampava anche la barra rovesciata).
• Vuoto. Un chip fatto solo di spazi (:chip[ ], spazi non separabili compresi) è un riquadro vuoto (uno spazio per la risposta, un segno di fine): largo quanto il padding orizzontale e il contorno del suo stile, alto quanto un chip con parole. Dimensiona lo spazio con il paddingX di uno stile (:chip[ ]{style="blank"}). Senza nulla tra le parentesi, :chip[] resta testo letterale.
• Dove. Paragrafi, voci di elenco, citazioni, riquadri, celle di tabella, didascalie e note. I titoli conservano :chip[…] come testo letterale.
• Output. Canvas, HTML e PDF dipingono il riquadro e compongono le parole come testo vero: selezionabile nell’HTML, estraibile e nell’ordine di lettura nel PDF (in un PDF con tag il riquadro è un artefatto di impaginazione e le parole appartengono al paragrafo).

#Maiuscoletto

:smallcaps[text] compone text in maiuscoletto: i nomi dei personaggi in un’opera teatrale, una sigla nel testo corrente, le prime parole di un capitolo. Le lettere minuscole si compongono come maiuscole al 70% del corpo del testo, mentre maiuscole, cifre e punteggiatura mantengono il corpo pieno, quindi :smallcaps[Hamlet] stampa una H a corpo pieno seguita da AMLET in maiuscoletto.

Enter :smallcaps[Hamlet] and :smallcaps[Horatio], reading.
 
The :smallcaps[unesco] report and the :smallcaps[who] guidelines.

• Sintetizzato. Il maiuscoletto si ricava dalle maiuscole del carattere stesso, allo stesso modo nel canvas, nell’HTML e nel PDF, così il testo si misura e va a capo in modo identico ovunque. Il vero maiuscoletto di un carattere (la funzione OpenType smcp) non viene usato; per averlo, componi il testo in una famiglia di maiuscoletto (per esempio una famiglia il cui nome termina con «SC») tramite uno stile di paragrafo.
• Segni. Il testo accetta i propri segni in linea (:smallcaps[**Ophelia**]) e l’enfasi intorno (*:smallcaps[Act I]*); scrivi \] per una parentesi quadra letterale al suo interno. Anche un rimando o un chip al suo interno si compone in maiuscoletto, e un rimando resta un unico link nell’HTML e nel PDF; una formula no.
• A capo. Le parole vanno a capo e si sillabano come al solito; la sillabazione legge ogni parola con le sue maiuscole e minuscole originali.
• Dove. Paragrafi, voci di elenco, citazioni, riquadri, celle di tabella, didascalie e note, e i titoli finché headings.inlineMarks è attivo (il valore predefinito); se è disattivato, il markup viene rimosso dal titolo e il testo si stampa come è scritto.
• Paragrafi interi. Uno stile di paragrafo o il corpo di un riquadro con smallCaps: true compone tutto il suo testo in questo modo (vedi Stili di paragrafo).
• Testo. Il canvas, l’HTML e il PDF riportano le lettere come sono dipinte: copiando :smallcaps[Hamlet] si ottiene «HAMLET».

#Tabulazioni e tabulatori

Una tabulazione manda le parole che la seguono a un tabulatore sulla riga: il prezzo di un piatto a filo con la fine della giustezza dietro una fila di puntini, l’attore dopo il ruolo in un elenco del cast, il punteggio di una domanda d’esame al margine. Scrivi :tab dove va la tabulazione; gli spazi intorno vengono assorbiti. I tabulatori si impostano nella configurazione: bodyText.tabStops per ogni paragrafo, voce di elenco e citazione, i tabStops di uno stile di paragrafo per i paragrafi di un gruppo :::paragraphs, e i body.tabStops di uno stile di riquadro dentro i suoi riquadri (vedi Configurazione › Tabulatori). Un menu i cui prezzi terminano alla fine della giustezza, dietro i puntini:

paragraphStyles: [
  { id: 'menu', firstLineIndent: { value: 0, unit: 'em' }, tabStops: [{ position: 'end', align: 'end', leader: '. ' }] },
],

:::paragraphs{style="menu"}
Onion soup :tab 8.50
 
Grilled sea bream with fennel and lemon :tab 21.00
:::

:tab{…} imposta un tabulatore solo per quella tabulazione, senza stile: lo spazio da compilare di un modulo fino alla fine della riga, un importo allineato sulla virgola decimale.

Name and surname :tab{at=end leader=rule}
 
Total due :tab{at=80% align=decimal} 1,234.50

• Dove va una tabulazione. Al primo tabulatore oltre il testo che la precede, tra i tabulatori successivi a quello preso dalla tabulazione precedente della riga, quindi la seconda tabulazione di una riga di solito prende il secondo tabulatore. Oltre l’ultimo tabulatore, tabInterval imposta altri tabulatori a ogni intervallo dall’inizio della giustezza; senza di esso la tabulazione è uno spazio tra parole.
• Caratteri di tabulazione. Una tabulazione digitata nel testo (U+0009) è una tabulazione solo in un paragrafo il cui stile imposta tabStops o tabInterval. Ovunque altrove è lo spazio tra parole che è sempre stata, così un documento scritto con tabulazioni al posto degli spazi mantiene la sua impaginazione. Più caratteri di tabulazione di fila avanzano di altrettanti tabulatori. Una tabulazione all’inizio di una riga del sorgente viene eliminata con gli altri spazi iniziali della riga: scrivi :tab per far iniziare una riga a un tabulatore.
• Che cosa resta testo. Un :tab seguito da una lettera (3:table), e un :tab nel codice in linea, in una formula, nell’indirizzo di un link o negli attributi di una direttiva.
• Dove. Paragrafi, voci di elenco, citazioni, riquadri e gruppi :::paragraphs. Titoli, didascalie, celle di tabella e il testo dei progetti (aperture, testatine) non hanno tabulatori.
• Testo oltre il tabulatore. Quando il testo prima di una tabulazione ha già superato tutti i tabulatori rimasti sulla sua riga, un tabulatore end, center o decimal porta l’ultima parola prima della tabulazione alla riga successiva insieme al testo al tabulatore, e il testo che la precede si compone più stretto, come una riga del sommario manda a capo il titolo per tenere il numero di pagina. Un tabulatore start va a capo prima della tabulazione, e il testo che la segue inizia la riga successiva al suo tabulatore. Una tabulazione che apre la sua riga e non trova comunque un tabulatore non occupa spazio.
• Guide. Una guida riempie lo spazio prima del suo tabulatore e termina a filo con la fine di quello spazio, così i puntini di più righe si allineano qualunque sia il testo che li precede. gap la tiene staccata dal testo su entrambi i lati; non c’è spazio prima quando la tabulazione apre la riga, né dopo quando non segue nulla. Una guida si compone con tre ripetizioni o più; uno spazio sufficiente per una o due resta vuoto, come nel sommario.
• Divisione in righe. Un paragrafo che contiene una tabulazione si compone riga per riga, mai con Knuth–Plass. Nel testo giustificato solo gli spazi tra parole dopo l’ultima tabulazione di una riga assorbono il gioco, e l’ultima riga del paragrafo non viene allargata (vedi Giustificazione › Righe con tabulazioni). Un paragrafo centrato o allineato a destra compone le sue righe con tabulazioni dal lato iniziale, perché i tabulatori sono posizioni sulla giustezza. Da destra a sinistra, i tabulatori si misurano da destra e un tabulatore end sta a sinistra (vedi Composizione araba). Nel testo verticale una tabulazione è uno spazio tra parole, e un :tab lì genera l’avviso di contenuto tabInVerticalText.
• Testo e output. Il testo semplice ha un carattere di tabulazione (\t) in corrispondenza di ogni tabulazione; le guide non sono testo, e copia, ricerca e mappa del sorgente le escludono. Il canvas, il visualizzatore HTML e l’EPUB a layout fisso le dipingono (nascoste agli screen reader nell’HTML); un PDF con tag le marca come artefatti, così il suo testo si legge Onion soup 8.50. L’EPUB a layout fluido non può conservare esattamente i tabulatori: ogni riga di un paragrafo con tabulazioni diventa una fila delle parti tra le sue tabulazioni, dove un tabulatore end, center o decimal, o uno con guida, spinge la parte successiva alla fine della fila (la sua guida diventa un bordo punteggiato o continuo), e un tabulatore start mantiene la parte che lo precede alla sua larghezza stampata. Un’esportazione in Word scrive :tab come tabulazione di Word, e l’importazione da Word rilegge una tabulazione nel testo come :tab con il tabulatore che Word le ha assegnato (vedi Sandbox › Documenti Word).

#Orientamento nel testo verticale

Nel testo verticale (layout.writingMode: 'vertical-rl') i caratteri cinesi stanno diritti, le parole latine e i numeri lunghi vengono ruotati di lato, e un numero di al massimo due cifre sta diritto in una cella, a meno che non si trovi in una frase latina, di cui segue le parole (vedi Configurazione › Numeri nel testo verticale). Tre segni distinguono a mano una sequenza:

第:tcy[120]回，:upright[GDP]增長:sideways[12]倍。

• :tcy[…] (tate-chu-yoko, 縱中橫) compone il suo testo affiancato in una cella diritta di un em, compresso in larghezza quando è più largo: :tcy[120], :tcy[3.0], :tcy[A+]. Si leggono bene fino a circa quattro caratteri.
• :upright[…] mette ogni carattere diritto in una cella propria, con le lettere latine centrate: una sigla letta lettera per lettera lungo la colonna. Una riga non va mai a capo al suo interno.
• :sideways[…] ruota l’intera sequenza con la riga, anche i caratteri cinesi: un numero di due cifre che l’autore vuole di lato.
• Il testo resta nel testo semplice; i segni accettano al loro interno altri segni in linea (:tcy[**12**]), un link (:sideways[[iPhone](https://…)]) e l’uno l’altro, con la precedenza al più interno (:tcy[:upright[AB]] mette A e B diritte), e si scrive \] per una parentesi quadra letterale. Nel testo orizzontale non cambiano nulla.
• Un rimando, un richiamo di nota, una formula, un chip o un campione di colore dentro un segno mantiene la propria composizione: :sideways[iPhone[^1]] ruota iPhone e lascia il numero della nota composto come ogni numero di nota; il numero di un rimando sta in una cella secondo cjk.uprightDigits, come qualsiasi numero breve.
• Anche un elemento di testo di progetto con inlineMarks: true li accetta quando è composto in verticale (vedi Configurazione › Elementi di testo verticale).
• Per la divisione in righe e la giustificazione, una cella :tcy e ogni carattere :upright contano come caratteri cinesi, e accanto a essi non si inserisce lo spazio tra Han e latino.

#Segni cinesi, ruby e warichu

Le edizioni cinesi e giapponesi marcano il testo tra le righe invece che con il corsivo o la sottolineatura, glossano i caratteri con le loro letture e compongono il commento dentro la riga. Lo fanno sette direttive. Composizione cinese e Composizione giapponese spiegano le convenzioni che stanno dietro. Le direttive conservano il loro testo: i caratteri tra le parentesi quadre restano nel paragrafo (la ricerca, il sommario, le ancore dell’indice e il testo copiato li leggono come sono scritti), e accettano gli altri segni in linea al loro interno e intorno, compresi quelli annidati. Scrivi \] per una parentesi quadra letterale.

此事:dots[不可]輕忽。:name[賈寶玉]與:name[林黛玉]讀:book[西廂記]。
 
{滿紙|mǎn|zhǐ}荒唐言，:ruby[一把]{rt="yì bǎ"}辛酸淚！:ruby[都]{rt="ㄉㄡ"}云作者痴。
 
寶玉:warichu[甲戌側批：此是第一首標題詩。]{open="〔" close="〕"}道：……
 
{東京|とう|きょう}の:ruby[紫陽花]{rt="あじさい"}は*とんと*:sideline[見事]だ。:book[こころ]を読む。
 
:kunten[學]{okuri="ビテ"}而:kunten[時]{okuri="ニ"}:kunten[習]{kaeri="二" okuri="フ"}:kunten[之]{kaeri="一" okuri="ヲ"}。

• :dots[text] mette un punto di enfasi (着重号) sotto ogni carattere nel testo orizzontale, alla sua destra nel testo verticale, e nessuno sulla punteggiatura o sugli spazi. style="dot|circle|sesame" (predefinito dot), fill="open" per un contorno, pos="over|under" per l’altro lato. L’enfasi Markdown *…* su caratteri cinesi o giapponesi fa lo stesso con cjk.emphasis: 'dots', il valore predefinito in un documento cinese o giapponese; le lettere latine nella stessa enfasi restano in corsivo. Gli attributi omessi prendono cjk.emphasisMark: un punto sotto il testo in cinese, un sesamo sopra (alla sua destra nel testo verticale) in giapponese.
• :name[text] traccia la linea dei nomi propri (专名号) sotto il testo (alla sua sinistra nel testo verticale), e :book[text] il segno dei titoli di libri (书名号): 《》 intorno al titolo (〈〉 per un titolo dentro un altro), la linea ondulata delle edizioni classiche e di Taiwan, o nulla, secondo cjk.bookTitleMark (per impostazione predefinita le parentesi nella Cina continentale e in Giappone, la linea ondulata a Taiwan e a Hong Kong). In un documento giapponese le parentesi sono 『』, e 「」 per un titolo dentro un altro (cjk.bookTitleBrackets). Un solo sorgente serve un’edizione moderna continentale e una classica. Due nomi o titoli affiancati mantengono separate le loro linee.
• :ruby[base]{rt="…"} compone letture sopra la base (pinyin), o a destra di ogni carattere (zhuyin, il valore predefinito per le letture in bopomofo). Con tante letture quanti sono i caratteri, separate da spazi o da |, ogni carattere riceve la propria e una riga può andare a capo tra di essi (ruby mono); group, o un numero che non corrisponde, compone una sola lettura centrata sull’intera base, che non si divide mai. pos="over|under|right" sceglie il lato. La forma compatta {紅樓|hóng|lóu} (una lettura per ogni |) o {紅樓|hónglóu} (una lettura per l’intera base) si legge allo stesso modo, solo quando la base contiene un carattere Han, kana o bopomofo, fuori da formule, codice e attributi, quindi {x|x>0} nella prosa latina resta testo. Una barra rovesciata prima della parentesi graffa o della barra verticale mantiene come testo anche una base cinese: \{紅|hóng} e {紅\|hóng} stampano {紅|hóng}. Una base che apre o chiude una riga si allinea a quel bordo insieme alla sua lettura. mode=mono|group|jukugo sceglie come le letture si dispongono sopra la base (mode=group equivale a group), e align=center|jis|start come si spazia una lettura più corta della sua base. In un documento giapponese la forma per carattere di una parola di due o più caratteri ({東京|とう|きょう}, rt="とう|きょう") è ruby jukugo: ogni carattere conserva la sua lettura, che può sporgere sul carattere successivo della parola, la riga può andare a capo tra di essi, e le letture si spaziano e sporgono sui kana secondo cjk.ruby.align e cjk.ruby.overhang; una sola lettura per l’intera base ({紫陽花|あじさい}, il 《》 di Aozora) è ruby di gruppo; mode=mono mantiene una lettura per carattere senza sporgere sui vicini.
• :sideline[text] traccia una linea laterale (傍線) accanto al testo, punteggiatura e spazi compresi: sotto nel testo orizzontale e a destra nel testo verticale. style="solid|double|wavy|dotted" (predefinito solid), pos="over|under" (nel testo verticale over è a destra, under a sinistra; funziona anche position=). Funziona con qualsiasi scrittura, compresa una frase inglese sottolineata.
• :warichu[note] compone una nota (双行夹注) in due righe a metà del corpo del testo dentro la riga, letta prima la riga superiore (quella di destra nel testo verticale). Una nota lunga riempie ciò che resta della riga e prosegue nella riga, colonna o pagina successiva, con almeno due dei suoi caratteri su ciascun lato della divisione (cjk.warichu.minChars). open e close la racchiudono tra parentesi al corpo del testo; cjk.warichu imposta il corpo, il colore e le parentesi predefinite (（） in un documento giapponese). Una nota in scrittura latina va a capo tra le parole.
• :kunten[字]{kaeri="…" okuri="…" tate} compone i segni kanbun dell’ultimo carattere tra le parentesi quadre: kaeri il segno di ritorno (レ, 一 二 三, 上 中 下, 甲 乙 丙, 天 地 人, e 一レ 上レ 甲レ 天レ; i punti di codice ㆑ ㆒ … si leggono allo stesso modo), okuri gli okurigana (le parentesi di Aozora （ヲ） vengono eliminate), e l’indicatore tate il tatesen che lo unisce al carattere successivo. Il testo non viene riordinato: i segni si compongono a metà grandezza accanto a esso (cjk.kunten), e il testo copiato si legge 學ビテ而時ニ習フ之ヲ, con gli okurigana e senza i segni di ritorno. Un ruby al suo interno funziona per i caratteri letti due volte: :kunten[:ruby[未]{rt="ザル" pos=under}]{kaeri="レ" okuri="ダ"}.

Il passo di riga non cambia mai: segni e letture stanno nell’interlinea, e la build avvisa quando lo spazio tra le righe di un paragrafo è troppo stretto per essi (cjkMarksExceedLeading, rubyExceedsLeading, kuntenExceedsLeading), e quando i segni sotto una riga e le letture sopra la successiva non entrano nello spazio che condividono, in un paragrafo o tra due. Dai ai paragrafi annotati uno stile di paragrafo con più interlinea. Segni, letture e note si disegnano in paragrafi, titoli, voci di elenco, citazioni e riquadri, e anche in didascalie, celle di tabella e note, la cui interlinea viene verificata allo stesso modo; nelle testatine e nei progetti il testo si stampa senza di essi. Con cjk.bookTitleMark: 'brackets' le 《》 di un titolo sono punteggiatura del testo: didascalie, celle, note, righe del sommario, segnalibri e voci dell’indice le conservano. Vedi Configurazione › Segni, ruby e warichu.

#La direzione del testo nel markup

Un documento scorre nella direzione che il suo locale implica (direction nella configurazione: da destra a sinistra per arabo, persiano, urdu o ebraico). Al suo interno il markup imposta la direzione di un blocco o di una sequenza di testo, per una citazione inglese in un libro arabo o una araba in un libro inglese.

• Un titolo o un contenitore: {dir=ltr} o {dir=rtl} nei suoi attributi, # Introduction {dir=ltr}, :::paragraphs{dir=ltr}, :::callout{dir=rtl}. Ogni blocco dentro un contenitore prende la direzione, fino a un contenitore o a un titolo annidato che ne imposta un’altra. Un paragrafo semplice, un elenco o una citazione non hanno attributi propri: racchiudili in :::paragraphs{dir=…}. Altri valori vengono ignorati. Il lang di un contenitore (:::paragraphs{dir=ltr lang=en}) indica allo stesso modo la lingua dei blocchi al suo interno: i loro elenchi numerati usano le cifre di quella lingua.
• Una sequenza di testo: :ltr[…] e :rtl[…] isolano il loro testo (gli LRI…PDI e RLI…PDI dell’algoritmo bidirezionale Unicode): viene ordinato al suo interno, e il paragrafo intorno vede un solo carattere neutro. {lang=…} marca la lingua della sequenza nell’HTML e nel PDF. Un richiamo di nota, un :ref o una formula al suo interno fa parte dell’isolamento, e gli isolamenti si annidano.

:::paragraphs{dir=ltr}
The opening of the *Nights* in Lane's translation.
:::
 
ترجمها :ltr[Edward William Lane]{lang=en} سنة ١٨٣٩.

Un blocco composto contro la direzione del documento mantiene il proprio lato iniziale: il rientro, i marcatori di elenco e la fine a filo della sua ultima riga si spostano sul lato da cui inizia il suo testo. Usa un isolamento quando un titolo latino termina con un carattere neutro (un punto, una parentesi) che altrimenti si unirebbe all’arabo circostante. Anche i caratteri di controllo Unicode stessi (U+2066–2069, U+202A–202E, U+200E, U+200F, U+061C) vengono rispettati. Nell’editor della Sandbox ogni riga scorre nella direzione della sua prima lettera. Vedi Composizione araba.

#Note a piè di pagina

Una nota a piè di pagina ha due parti: il richiamo [^id] dove la nota è citata, e la definizione, un paragrafo a sé che si apre con [^id]: in qualsiasi punto del capitolo.

The keeper climbed the tower every evening.[^steps] The wind put out his candle,
so he learned to count the steps in the dark.
 
[^steps]: The cast-iron staircase has 112 steps; the tower was built in 1861.

• Richiamo. [^id] stampa il numero della nota come apice, attaccato alla parola che lo precede (scrivilo dopo la punteggiatura, come sopra). L’id accetta lettere, cifre, -, _, . e :. Il richiamo funziona in paragrafi, voci di elenco, citazioni e riquadri; in titoli, didascalie e celle di tabella si stampa come è scritto.
• Definizione. Un paragrafo che inizia con [^id]:; il suo testo prosegue fino alla riga vuota successiva e accetta i consueti segni in linea (grassetto, corsivo, link, :ref, formule, chip). Le definizioni escono dal flusso ovunque siano scritte, quindi possono stare sotto il paragrafo che le cita o tutte insieme alla fine del capitolo. Vale la prima definizione di un id.
• Numeri. Le note si numerano nell’ordine in cui vengono citate la prima volta, ricominciando a ogni capitolo (un titolo di livello 1, e ogni documento di un libro); una nota citata due volte mantiene il primo numero e si compone una volta sola. footnotes.numbering: 'document' prosegue la numerazione per tutto il libro, e 'page' la fa ripartire a ogni pagina, come nei libri cinesi; footnotes.numberFormat: 'circled-decimal' scrive ① ② ③ sulla linea di base. footnotes.numberFormat: 'symbols' le marca *, †, ‡, §, ‖, ¶, poi raddoppiati, ricominciando a ogni pagina, come nelle riviste.
• Testo giapponese. Scrivi il richiamo prima di un 。 finale di frase (先生[^1]。): resta con il carattere che lo precede, e 。 non apre mai una riga. Un libro giapponese verticale compone per impostazione predefinita i richiami （1） a destra della riga e le note dopo il capitolo; footnotes.markerPosition: 'side' compone un piccolo richiamo accanto alla parola, senza occupare spazio nella riga, e footnotes.placement: 'spread' compone le note accanto al testo di ogni doppia pagina (vedi Configurazione › Note a piè di pagina).
• Dove va la nota. Per impostazione predefinita al piede della colonna che contiene la riga che la cita, sotto un breve filetto: la riga e la sua nota condividono sempre una colonna, e una riga la cui nota non entra si sposta insieme a essa. In un’impaginazione a una colonna è il piede della pagina. footnotes.placement: 'chapterEnd' compone invece tutte le note di un capitolo dopo il suo ultimo blocco, per impostazione predefinita al piede della colonna che chiudono. Vedi Note a piè di pagina nel riferimento della configurazione per i corpi, il filetto e la spaziatura.
• Verifiche. Un richiamo senza definizione (undefinedFootnote) stampa il suo numero sopra una nota vuota; una definizione che nessun richiamo cita (unusedFootnote) non viene composta. La Sandbox le elenca entrambe nel pannello Verifiche.

#Rimandi e ancore

Un rimando indica un punto del libro e ne stampa il numero, il titolo o la pagina: vedi la sezione 3.2, come spiega il capitolo 4, a p. 112. Le parole e i numeri seguono il testo, quindi spostare una sezione, rinumerare i capitoli o reimpaginare il libro aggiorna ogni rimando. Nel PDF, nell’HTML e nelle anteprime della Sandbox ogni rimando è un link: un clic porta il lettore alla destinazione, anche in un altro capitolo.

Ancore. Un rimando ha bisogno di qualcosa a cui puntare:

• Un titolo con un identificatore: ## Method {#sec-method} (la forma di Pandoc; funziona anche id="sec-method").
• Un riquadro o un altro contenitore aperto con un identificatore: :::callout{#box-safety title="Safety"}. A un riquadro di uno stile numerato (un teorema) si rimanda con la sua etichetta e il suo numero: Teorema 2.
• Una formula in display con un \label{eq:x} (vedi Formule matematiche): un rimando ne stampa il numero come lo stampa la formula, (3).
• Un punto nel testo: :anchor{#key-idea} imposta un’ancora invisibile; [the key idea]{#key-idea} conserva le sue parole e dà loro un nome.

Un identificatore accetta lettere, cifre, -, _, . e :. Deve essere unico nel libro: il pannello Verifiche elenca un identificatore impostato due volte (duplicateAnchor), e i rimandi raggiungono la sua prima occorrenza.

Rimandi. :ref{id="…"} indica un’ancora nello stesso modo in cui indica una figura o una tabella:

## Method {#sec-method}
 
The results of :ref{id="sec-method"} hold on :ref{id="sec-method" style=page}.

Anche \eqref{x} e \ref{x} di LaTeX funzionano nel testo: \eqref come un rimando senza stile, \ref come style=number, quindi \ref{thm:main} stampa 2 e \ref{fig:map} il numero di una figura. Un ~ subito prima è uno spazio non separabile (Theorem~\ref{thm:main}). Dentro $…$ appartengono alla formula.

text="…" stampa parole tue e mantiene il link; case=capitalize fa iniziare l’etichetta con una maiuscola (Sezione 3.2 all’inizio di una frase). Le parole seguono la lingua del documento (sección 3.2, 第3.2节, S. 112) e si possono cambiare in Rimandi nella configurazione; un numero di titolo che il suo modello già scrive per esteso (Capitolo 4, 第四章) si stampa così com’è.

A capo. Un rimando che stampa parole va a capo nei suoi spazi come il testo circostante: il testo di un’ancora ([close the lever so that it points backwards]{#step}), un titolo, il tuo text="…". I suoi spazi sono spazi della riga, quindi in una riga giustificata si allargano con gli altri, e il rimando resta un unico link, in due pezzi quando si estende su due righe. Le sue parole non vengono mai sillabate. Dentro un’etichetta di questo tipo un numero, un numero romano o una singola lettera resta con la parola che lo precede, quindi text="Fig. 1a" o text="plate IV" non viene mai separato. Un’etichetta che contiene un numero o una pagina (sezione 3.2, p. 112, Fig. 1.7, Teorema 2) non va mai a capo, qualunque spazio contenga il suo modello, e uno spazio non separabile dentro un’etichetta incolla come ovunque. crossRefs.breakLabels: false mantiene intera ogni etichetta, come fino a postext 1.27, quando un’etichetta era una sola parola che non poteva risalire alla riga precedente; vedi Rimandi.

I rimandi alle pagine si conoscono solo quando il libro è impaginato. Il motore impagina di nuovo il documento con le pagine del passaggio precedente finché non si stabilizzano, come fa per il sommario; fino ad allora una pagina stampa ?.

pandoc-crossref. Il testo scritto per pandoc-crossref si legge allo stesso modo: @sec:method, [@fig:map], e [-@tbl:data] per il solo numero. Il prefisso (sec, fig, tbl, eq, lst) può far parte dell’identificatore ({#sec:method}) o esserne omesso ({#method}). Una @ attaccata a una parola, come in un indirizzo e-mail, resta testo.

Un rimando a un id che nulla imposta stampa ? e il pannello Verifiche lo elenca (unknownResourceId). Nell’editor della Sandbox, @ propone le figure, le tabelle, i titoli con un id e le ancore del libro.

#Citazioni e bibliografia

Scrivi le citazioni come le legge Pandoc, tieni i riferimenti nel documento e scegli lo stile di citazione nelle impostazioni: passare da APA a IEEE, o alle note Chicago, cambia l’impostazione dello stile, non il testo. Ogni citazione è un link alla sua voce nella bibliografia.

#Citare

As [@garcia2020, p. 33] shows, reading on paper is faster [see @lopez2019, chap. 2; @bringhurst2004].
@garcia2020 [p. 4] says it plainly; the 2020 study [-@garcia2020] agrees.

• [@key] cita tra parentesi; più opere vanno in una sola coppia di parentesi quadre, separate da ;.
• Localizzatore: dopo una virgola, p. 33, pp. 4–6, chap. 2, sec. IV, fig. 3, vol. 2, n. 12, l. 4, § 4.2; un numero semplice è una pagina. Funzionano anche le parole spagnole (pág., cap.) e cinesi (页, 章). Un intervallo si scrive con un trattino medio o con i due trattini di TeX: pp. 4--6 stampa 4–6.
• Prefisso e suffisso: testo prima della @ (see) e dopo la chiave o il localizzatore (, emphasis added). Il suffisso conserva la virgola scritta prima, con o senza localizzatore: [@brown2020, inter alia] stampa (Brown et al., 2020, inter alia), come fa Pandoc; scritto senza virgola ([@brown2020 inter alia]) non ne ha. L’enfasi in un prefisso o in un suffisso si compone come enfasi in ogni stile: [*e.g.*, @brown2020, *inter alia*].
• [-@key] omette l’autore, per una frase che nomina già l’autore.
• @key cita nella frase (García (2020)); @key [p. 4] aggiunge un localizzatore.
• Nelle didascalie: la didascalia di una figura o di una tabella, e la sua nota, citano come il testo (Prior best from [@cobbe2021].). Le loro opere entrano nella bibliografia senza nocite, e uno stile numerato le numera dove la risorsa viene collocata: dopo le citazioni del paragrafo che vi fa riferimento per primo (il suo blocco ::resource o il primo :ref). Una citazione in una cella di tabella resta testo.
• Una @ attaccata a una lettera o a una cifra (un indirizzo e-mail), una @ nel codice in linea e \@ sono testo. Una citazione per cui il libro non ha un riferimento si stampa come è scritta, quindi un documento senza riferimenti si legge come prima. In una citazione di più opere, una chiave che nessun riferimento definisce si stampa in grassetto dopo le altre ((Glen, 1955) **@nye1953**), così l’opera mancante si vede sulla pagina oltre che tra gli avvisi. I due punti dopo una citazione sono testo: [@french2018]: the land….
• Nel testo cinese, giapponese e coreano una citazione segue l’ultimo carattere senza spazio (周明远@zhou2019认为), e una citazione autore-data prende i segni a larghezza piena del testo circostante: （施雅风等，1988；刘时银等，2015）.

#Riferimenti

I riferimenti si scrivono nel documento, in forma CSL (il modello di dati di Zotero e Pandoc):

---
references:
  - id: garcia2020
    type: book
    author: [{family: García, given: Ana}]
    title: Tipografía y lectura
    issued: 2020
    publisher: Trea
nocite: "@lopez2019"
---

oppure in un blocco :::references, in BibTeX (un’esportazione di Zotero, JabRef o Google Scholar), CSL-JSON o CSL-YAML:

:::references{format=bibtex}
@article{lopez2019, author = {López, Luis and Ruiz, Eva}, title = {Leer en pantalla},
  journal = {Revista de Letras}, year = 2019, volume = 12, pages = {45--67}, doi = {10.1000/xyz}}
:::

Il blocco non stampa nulla. nocite elenca opere senza citarle (@*: tutte). In un libro, i riferimenti scritti in qualsiasi capitolo valgono per tutto il libro.

In un elenco di nomi BibTeX, and others sta per i nomi omessi (author = {Tan, Wei and others}): ogni stile stampa al suo posto et al. In YAML, scrivi others come ultimo nome dell’elenco.

#La bibliografia

:::bibliography compone l’elenco delle opere citate dove si trova; senza di esso, l’elenco segue l’ultimo capitolo, intitolato nella lingua del documento (References, Referencias, 参考文献). :::bibliography{title="Works cited"} cambia il titolo e title="" lo omette; scope=chapter elenca le opere che il capitolo cita (un volume collettaneo). Ogni voce è un’ancora (ref-<key>), quindi un link Markdown a #ref-garcia2020 la raggiunge, e il PDF la marca come BibEntry.

scope=new elenca le opere citate fino a quel punto del documento che nessun elenco precedente ha stampato, nell’ordine dello stile e con i suoi numeri: un :::bibliography{scope=new} dopo il testo principale e un altro dopo i Metodi danno i due elenchi di un articolo di Nature, il secondo numerato di seguito al primo. Uno stile numerato conta le sue citazioni per tutto il libro; con citations.numbering: 'chapter' ogni capitolo (ogni documento, e ogni titolo di livello 1 dopo una citazione) numera le proprie a partire da 1, e il suo elenco di capitolo prende quei numeri, come fanno i rapporti di un bollettino o gli articoli di un volume di atti.

#Stili

Lo stile decide che cosa dicono una citazione e una voce. Gli stili inclusi sono elencati qui sotto; qualsiasi altro stile CSL (nel repository di stili di Zotero ce ne sono più di diecimila) si può caricare dal suo file .csl in Impostazioni → Citazioni.

Con uno stile a note ogni citazione diventa una nota a piè di pagina, collocata e numerata secondo le impostazioni delle note; le citazioni successive della stessa opera prendono una forma breve. Nel testo cinese, citations.notes: 'warichu' le compone come note su due righe dentro la riga (夹注); una nota seguita da un segno cinese (，, 。) elimina il proprio punto finale.

Cinese. Gli stili GB/T 7714-2015 scrivono i codici del tipo di documento ([M], [J], [D], [EB/OL]), mantengono interi i nomi cinesi e scrivono 等 dopo tre autori di un’opera cinese ed et al. dopo quelli di un’opera occidentale, scegliendo in base al language di ogni opera. Nel testo verticale un numero in apice sta a destra del suo carattere; citations.marker: 'corner' scrive 〔1〕, che resta diritto.

Motore. Le citazioni vengono formattate dal pacchetto postext-citeproc (citeproc-js e gli stili CSL). La Sandbox lo carica per i documenti che citano; nel tuo codice, registralo prima di impaginare:

import 'postext-citeproc/register';

Il pannello Verifiche elenca una chiave che nessun riferimento definisce (unknownCitationKey) e un blocco di riferimenti che non si riesce a leggere (referencesUnreadable).

#Indice analitico

Un indice analitico elenca i termini di un libro con le pagine in cui compaiono. Marca ogni termine dove il testo ne parla e stampa l’indice con :::index dove deve stare, di solito in un capitolo a sé alla fine. Il motore trova la pagina di ogni segno dopo l’impaginazione, quindi i numeri seguono il testo: aggiungi un paragrafo, sposta un capitolo o cambia il formato, e l’indice stampa le nuove pagine.

Iron-deficiency :index[anaemia] is the most common kind.
The pulse is taken at the wrist.:index{term="Pulse!radial" main}
 
# Index {style="index"}
 
:::index

#Segni dell’indice

• :index[text] stampa text e lo registra sotto le sue stesse parole. I segni in linea al suo interno si stampano e vengono tolti dalla voce. Gli attributi dopo la parentesi quadra lo registrano altrove: :index[iron deficiency]{term="Anaemia!iron-deficiency"}.
• :index{term="…"} non stampa nulla. Il segno prende la pagina della parola scritta subito prima sulla sua riga, oppure, quando apre una riga, della parola che lo segue. Una riga che contiene solo segni viene rimossa, quindi un segno su una riga a sé non divide mai un paragrafo né aggiunge spazio.
• Dove. Paragrafi, titoli, voci di elenco, citazioni, riquadri e definizioni di note a piè di pagina. In didascalie, celle di tabella ed elementi di progetto un segno si stampa come è scritto. Dentro il codice in linea, e dopo una barra rovesciata (\:index), è testo.

Un segno senza termine (:index{} o :index{see="…"} da solo) non indicizza nulla e genera indexMarkInvalid.

#Stampare l’indice

:::index stampa l’indice principale dove si trova, e :::index{index="names"} un indice con nome. La direttiva si espande in blocchi ordinari, uno per voce, che scorrono tra colonne e pagine come il testo: sotto un titolo il cui stile di titolo imposta un layout a due colonne, dà il consueto indice a due colonne. Un clic su una voce porta alla riga della direttiva.

# Index of names {style="index"}
 
:::index{index="names"}
 
# Index of subjects {style="index"}
 
:::index

• Ordine. Le voci si ordinano nell’ordine alfabetico della lingua del documento (locale, o index.locale): una lettera accentata va con la sua lettera di base (Árbol sotto A), e in spagnolo la ñ viene dopo la n, sotto un’intestazione propria. Le voci che iniziano con un simbolo vengono per prime, poi quelle che iniziano con una cifra, poi le lettere. Le sottovoci si ordinano allo stesso modo sotto la loro voce, rientrate di un passo per livello. Un indice giapponese ordina per lettura secondo la JIS X 4061 e raggruppa per riga gojūon (あ行, か行…), con le voci latine prima dei kana (vedi Composizione giapponese › Indice in ordine gojūon).
• Gruppi. Ogni nuova iniziale apre un gruppo: un’intestazione con la lettera (index.groups) e una riga di spazio sopra (nessuna sopra il primo gruppo). L’intestazione si compone in un unico blocco con la prima voce del gruppo, quindi non chiude mai una colonna da sola; una voce senza pagine proprie (una che fa solo da capo alle sue sottovoci) si compone con la sua prima sottovoce per lo stesso motivo.
• Numeri di pagina. Le etichette stampate dalle pagine, comprese quelle romane delle pagine preliminari. Le pagine di una voce si ordinano e ciascuna si elenca una sola volta; le pagine consecutive si uniscono in un intervallo (12–14, index.mergeRanges), una pagina che cade dentro un intervallo della stessa voce vi confluisce (una pagina principale lì rende l’intervallo in grassetto), e index.rangeFormat: 'chicago' abbrevia il secondo numero (234–37). Le pagine in grassetto (principali) restano separate. Nel PDF ogni numero è un link alla sua pagina.
• I rinvii chiudono la voce: Term. See Target quando la voce non ha pagine, Term, 12. See also Target quando ne ha. Le etichette seguono la lingua del documento (See, Véase…) e si possono impostare in index.see.
• Libri. In un libro impaginato capitolo per capitolo (la Sandbox, buildBundle) il capitolo che stampa l’indice riceve i segni di tutti i capitoli con le loro pagine, e viene reimpaginato solo quando uno di essi si sposta. Un documento che contiene sia i suoi segni sia il suo indice viene reimpaginato finché i numeri non si stabilizzano, come con :::toc.

Vedi Indice analitico nel riferimento della configurazione per la tipografia, i rientri e i separatori.

#Formule matematiche

Il supporto per la matematica è una parte a pieno titolo del formato del documento. Postext analizza $…$ per le formule in linea e $$…$$ per le formule in evidenza (di blocco), e le disegna con MathJax in modalità SVG. Gli stessi tracciati vettoriali alimentano tutti e tre i backend, quindi l’anteprima su canvas, l’esportazione HTML e l’output PDF coincidono pixel per pixel, e il PDF resta interamente vettoriale a qualsiasi livello di zoom.

• In linea: $…$. Riconosciuta in qualsiasi blocco di testo (paragrafo, titolo, citazione, voce di elenco). Aggiunge alla riga un unico riquadro atomico e indivisibile; Knuth–Plass la tratta come una parola che non si può spezzare. Se l’altezza naturale della formula sforasse il riquadro della riga, viene ridotta in modo uniforme così da preservare la griglia della linea di base: le espressioni molto alte vanno in modalità in evidenza.
• In evidenza: $$…$$. Su una riga a sé ($$\int_0^1 x^2\,dx$$) oppure su più righe tra recinzioni, con i marcatori $$ su righe proprie. Viene disegnata centrata nella colonna e agganciata alla griglia della linea di base con margini superiore e inferiore configurabili (math.marginTop, math.marginBottom): è esattamente lo stesso meccanismo di correzione dei titoli, così il paragrafo dopo la formula torna sulla griglia.
• Testo intorno a una formula in evidenza: una formula in evidenza su una riga a sé interrompe un paragrafo anche senza una riga vuota sopra. Il testo che la precede è un paragrafo che la introduce; il testo scritto subito sotto il $$ di chiusura, senza riga vuota, prosegue il paragrafo interrotto e viene composto senza rientro di prima riga, come TeX compone il «dove …» dopo una formula in evidenza. Una formula separata dal testo sopra da una riga vuota (o che segue un elenco, una citazione o un titolo) non interrompe nulla: il testo che la segue è un nuovo paragrafo, rientrato come al solito, con o senza riga vuota (math.indentAfterDisplay: false lo compone anch’esso senza rientro). Solo una formula in evidenza intera interrompe un paragrafo: una sola formula sulla riga, oppure una recinzione $$ chiusa prima della riga vuota successiva; una riga come $$a$$ and $$b$$ resta testo. math.keepWithLeadIn tiene una formula nella colonna della riga che la introduce. (Fino a postext 1.4 una riga $$…$$ senza riga vuota sopra veniva letta come parte del paragrafo e stampata così com’era scritta.)
• Numeri delle equazioni: \label{eq:x} in una formula in evidenza la numera, in ordine di lettura: (1), (2)… Una formula con numero occupa tutta la colonna (o la larghezza interna del riquadro), con l’equazione centrata e il suo numero allineato a destra sulla stessa riga. In un align, gather, alignat, flalign o eqnarray ogni riga che porta un \label riceve il proprio numero, a meno che la riga non indichi \nonumber o \notag. Una formula senza \label non viene numerata, come non lo è mai stata $$…$$. \tag{…} numera ancora una formula con il testo che le dai (\tag*{…} senza parentesi) e non viene contato; un \label accanto a esso dà un nome a quel testo. Il formato, i numeri di capitolo o di sezione (2.3) e gli azzeramenti si impostano in math.equationNumbering. Metti il \label al livello più esterno della formula o della sua riga: non dentro aligned, split o cases.
• Rimandi alle equazioni: \eqref{eq:x} nel testo stampa il numero come lo stampa la formula, (3), e \ref{eq:x} il numero nudo, 3; entrambi sono link, come ogni rimando. Eq.~\eqref{eq:x} tratta la ~ come fa LaTeX: uno spazio indivisibile. Anche :ref{id="eq:x"} e @eq:x stampano (3). Dentro una formula, \eqref e \ref stampano il numero (non un link). Un’etichetta che nessuna formula imposta stampa ? e compare nel pannello Verifiche.
• Escape: \$ è un simbolo del dollaro letterale. I delimitatori $ o $$ senza corrispondenza producono una voce unclosedMath nel pannello Verifiche della Sandbox, con un’ancora al sorgente che porta il cursore lì con un clic.
• Didascalie, note e celle di tabella compongono anch’esse la matematica in linea (da postext 1.19), nella riga insieme al testo e con l’allineamento della cella, alla dimensione del frammento. Lì un $ apre una formula solo secondo la regola di Pandoc: nessuno spazio dopo il $ di apertura, nessuno spazio prima di quello di chiusura e nessuna cifra subito dopo, così i prezzi di $5 to $10 restano testo; \$ stampa un simbolo del dollaro, quindi una stringa con l’escape si legge allo stesso modo nel testo e in una tabella. L’etichetta di un chip non accetta formule. Fino a postext 1.18 un $ in quei punti veniva sempre stampato così com’era.
• Errori: il sorgente TeX che MathJax rifiuta (macro non definite, errori di sintassi) emerge come avviso invalidMath. La formula viene sostituita da un piccolo segnaposto rosso, così la geometria dell’impaginazione resta valida.
• Configurazione: la sezione math della configurazione espone enabled, fontSizeScale (relativo alla dimensione del testo circostante: a 1,0 un em della formula ha quella dimensione, cioè il corpo del testo corrente per le formule in evidenza e per la matematica in linea nel testo corrente; da postext 1.5, che compone le formule circa il 13% più piccole rispetto alla 1.4, mentre i pacchetti e i libri della Sandbox salvati con la 1.4 conservano la loro dimensione; vedi Dimensione delle formule), color (eredita il colore del testo corrente quando non è impostato) e i margini delle formule in evidenza.
• Il motore: MathJax si carica su richiesta. La Sandbox e il worker di impaginazione lo avviano da soli; nel tuo codice, esegui await initMathEngine() prima di buildDocument, altrimenti ogni formula viene impaginata come un riquadro segnaposto grigio (vedi Avviare il motore matematico).

The Euler identity $e^{i\pi}+1=0$ links the five fundamental constants.
 
$$
\int_0^{\infty} e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}
$$

Una formula a metà frase, e la frase che prosegue dopo di essa senza rientro:

For a pendulum of length $L$ the period is
$$T_0 = 2\pi\sqrt{L/g}$$
where $g$ is the acceleration of free fall.

Equazioni numerate e i rimandi a esse:

The energy is conserved,
$$
\begin{align}
E &= T + V \label{eq:energy} \\
  &= \tfrac12 m v^2 + m g h \nonumber
\end{align}
$$
and Eq.~\eqref{eq:energy} holds at every instant.

Teoremi, lemmi e dimostrazioni. Uno stile di riquadro con numbering conta i suoi riquadri, come l’amsthm di LaTeX conta gli ambienti di teorema: ogni riquadro si apre con la sua etichetta e il suo numero in grassetto, «Teorema 2.», il title della recinzione dopo il numero tra parentesi, «Teorema 2 (Bradley–Terry).», e un rimando al suo {#id} stampa «Teorema 2» (\ref{thm:x} o style=number il solo 2). Gli stili che indicano lo stesso contatore lo condividono, quindi un lemma che segue un teorema è il Lemma 3. L’endMark di uno stile di dimostrazione chiude i suoi riquadri con ∎ o □, allineato a destra sull’ultima riga. Vedi Enunciati numerati e dimostrazioni per gli stili.

:::callout{type="theorem" #thm:main title="Bradley–Terry"}
Every reward class holds one reparameterised reward.
:::
 
:::callout{type="proof"}
Apply the projection of \eqref{eq:projection} to any member of the class.
:::
 
By :ref{id="thm:main"}, the objective is unchanged.

#Risorse

Immagini, SVG, tabelle e video non si scrivono in linea. Si dichiarano una volta come risorse (gestite nel pannello Risorse della Sandbox, che si occupa del caricamento di immagini e SVG, di un editor interattivo delle tabelle, dei video di YouTube, Vimeo o caricati, e della modifica di didascalie e collocazione) e poi si collegano alla prosa tramite id. Fare riferimento a una risorsa basta per incorporarla: la citi una volta con un :ref{id="…"} in linea e il motore fa flottare la figura o la tabella nel primo spazio libero dopo quel rimando (il fondo della colonna in cui la citi, la cima della colonna successiva, una fascia della pagina seguente), proprio come farebbe un compositore tipografico. Non devi collocarla una seconda volta.

Entrambe le forme qui sotto sono sintassi nuova che non entra in conflitto con CommonMark, quindi un documento che le usa si legge ancora come testo semplice in qualsiasi altro visualizzatore markdown.

#Rimando in linea (la forma principale)

Fai riferimento a una risorsa dall’interno della prosa con :ref{id="…"}. Il primo rimando incorpora la risorsa (che quindi viene collocata sulla pagina) e insieme mostra il suo numero calcolato, preceduto per impostazione predefinita dall’etichetta breve del tipo:

As shown in :ref{id="lighthouse-diagram"}, the lantern room sits above the gallery.

viene reso come: As shown in Fig. 1.7, the lantern room sits above the gallery., mentre il diagramma flotta nel primo spazio libero dopo la frase (il fondo di questa colonna, la cima della successiva o una fascia della pagina seguente), e questa frase e il testo che la segue scorrono senza interruzioni.

Il testo corrente non viene mai spezzato nel punto del rimando. Dove finisce la risorsa (il primo spazio libero, oppure solo uno spazio in alto o in basso; in una sola colonna o su tutta la larghezza) dipende dalla sua collocazione (vedi Collocazione più sotto) e dal punto in cui la citi: la ricerca parte subito dopo il rimando.

#Inserimento di blocco (facoltativo, collocazione in linea esplicita)

A volte vuoi che una risorsa stia in un punto preciso del flusso invece di flottare. Escludila dagli elementi flottanti dando alla risorsa placement.position: "here" e inseriscila con ::resource{id="…"} su una riga a sé:

Here is the floor plan we discussed.
 
::resource{id="lighthouse-diagram"}
 
The keeper's quarters occupy the eastern wing.

Per una risorsa flottante la direttiva ::resource non serve: il :ref l’ha già collocata, e un ::resource superfluo per lo stesso id viene trattato semplicemente come un altro rimando, non come una seconda copia. Un ::resource disegna la risorsa in linea solo quando la sua collocazione risolta è "here". Una risorsa in linea mantiene sopra di sé lo spazio di una riga (la distanza degli elementi flottanti), come farebbe un elemento flottante, a meno che il blocco precedente non ne chieda di più. Nel testo corrente mantiene lo stesso spazio sotto di sé; poi il testo che segue torna sulla griglia della linea di base, il che può aggiungere fino a una riga in più. Un titolo, un elenco, un riquadro o un’altra risorsa in linea subito dopo condivide quello spazio con il proprio spazio superiore: si applica il maggiore dei due, non entrambi. (Fino a postext 1.4 lo spazio sotto era solo quello lasciato dall’aggancio alla griglia, da nulla a una riga; layout.inlineResourceGap: 'above' mantiene quella regola, e i libri salvati prima della 1.5 vengono letti con essa.) Dentro un riquadro (:::callout) la risorsa mantiene lo stesso spazio, una riga del testo del riquadro sopra di sé e, con 'around', sotto; in cima o in fondo al riquadro la separa invece il margine interno. (Fino a postext 1.4 stava a contatto con il testo del riquadro; layout.inlineResourceGapInBoxes: false mantiene quel comportamento, e i libri salvati prima della 1.5 i cui riquadri incorporano una risorsa vengono letti con esso.)

Una risorsa in linea la cui collocazione indica anche span: 'page' (placement: { position: 'here', span: 'page' }) occupa tutta la larghezza della pagina nel punto della sua direttiva in un’impaginazione a più colonne, come fa un riquadro a tutta larghezza: le colonne sopra di essa si chiudono pareggiate (bilanciate, oppure la risorsa passa in cima alla pagina seguente quando non è possibile), viene composta su tutta la larghezza del contenuto con lo stesso spazio sopra e sotto, e il testo prosegue in ogni colonna sotto di essa. Su una pagina a una colonna viene composta come prima, a piena giustezza. Una risorsa span: 'column' con columns impostato resta nella sua colonna quando è inserita in linea: le colonne contano solo per gli elementi flottanti. Da postext 1.19.

L’id deve corrispondere a una risorsa definita nel pannello Risorse. Il motore disegna la risorsa (bitmap, SVG o tabella) con la sua didascalia sotto, come piede di figura o di tabella. Il testo della didascalia è composto dal captionPrefix del tipo di risorsa, dal numero calcolato e dalla didascalia propria della risorsa, per esempio Figura 1.7. La pianta originale del faro. La sua tipografia è regolata da Configurazione › Stile delle didascalie: etichetta e descrizione condividono carattere e corpo, mentre l’etichetta mantiene impostazioni indipendenti di grassetto, corsivo e colore; la distanza sopra la didascalia è per impostazione predefinita 0.75em e l’allineamento a sinistra. La didascalia può invece stare sopra la risorsa (captionStyle.position: 'above', in generale o per tipo di risorsa), eventualmente su una barra colorata. Una risorsa può avere anche una note, una breve riga di fonte o di credito con la stessa formattazione in linea e gli stessi segni :ref della didascalia, composta in corpo più piccolo sotto la risorsa (sotto la didascalia quando la didascalia sta sotto, sotto il corpo quando sta sopra) e regolata con captionStyle.note.

A capo nelle didascalie e nelle note. Una didascalia o una nota è un unico paragrafo composto alla giustezza del suo spazio, e un a capo digitato al suo interno vale come spazio. Per iniziare una nuova riga scrivi \\ (l’a capo forzato dei titoli) oppure termina la riga con una barra rovesciata, l’a capo forzato di Markdown: ¹ Measured at 20 °C. \\ ² Mean of three runs. compone ogni nota di una tabella larga su una riga propria. La riga prima di un a capo conserva la sua larghezza naturale, senza mai essere allargata fino alla giustezza, e due a capo di seguito non creano una riga vuota (uno spazio indivisibile tra i due invece sì). In una cella di tabella \\ fa ciò che fa un a capo: apre un nuovo paragrafo; il rientro della riga che segue viene mantenuto, quindi due spazi iniziali annidano ancora una voce di elenco. Nel testo vero e proprio le due barre rovesciate sono sempre un a capo, senza escape: per stamparle, mettile in codice in linea, dove le barre rovesciate si stampano così come sono. Nella destinazione di un link restano parte dell’URL, e negli attributi di una direttiva (il text di un :ref) parte del valore; dentro un chip, che si compone su una riga sola, un a capo vale come spazio. (Fino a postext 1.4 le barre rovesciate venivano stampate, e una didascalia o una nota andava a capo solo dove finiva la giustezza.)

Le risorse tabella disegnano la propria griglia, regolata con Configurazione › Stile delle tabelle: le celle del corpo e quelle di intestazione hanno tipografie del tutto indipendenti, lo sfondo dell’intestazione è per impostazione predefinita #f0f0f0, i bordi 0.75pt e cellPadding 0.375em; ogni campo non impostato eredita dal testo corrente. Le larghezze delle colonne fanno parte della tabella stessa: TableModel.columnWidths contiene un peso relativo per colonna ([2, 1, 1] dà alla prima colonna metà della larghezza); se non è impostato, le colonne si dividono la larghezza in parti uguali. Una tabella può anche essere composta in una variante con nome: table.styleId sceglie uno dei tableStyles del documento (vedi Configurazione › Stili di tabella con nome), i cui campi non impostati ereditano da tableStyle; un id sconosciuto o assente mantiene tableStyle.

Una cella colloca il suo contenuto con TableCell.align (left, center, right; le voci di elenco restano allineate a sinistra) e TableCell.verticalAlign (top, il valore predefinito, middle o bottom). L’allineamento verticale sposta l’intero contenuto della cella (l’immagine e il testo sotto di essa, come un’unità) dentro una cella più alta del contenuto: una riga allungata da una cella vicina più lunga, o le righe coperte da un rowSpan. Vale in ogni output (canvas, HTML, PDF), nelle tabelle ruotate e in ciascuna parte di una tabella divisa su più pagine. Entrambi si impostano cella per cella dai pulsanti di allineamento della barra degli strumenti dell’editor delle tabelle della Sandbox.

Una cella di tabella può contenere anche un’immagine. TableCell.image indica per id una risorsa bitmap o SVG ({ "resourceId": "fig-arm", "width": 0.7 }): l’immagine viene disegnata dentro la cella (mai numerata, flottante o con didascalia), adattata alla larghezza interna della cella (o alla frazione indicata da width, predefinita 1) conservando le proporzioni, allineata come il testo della cella, e l’eventuale testo della cella scorre sotto di essa. La riga cresce per contenerla. Nell’editor delle tabelle della Sandbox il pulsante immagine della barra degli strumenti sceglie la risorsa per la cella attiva e un campo larghezza imposta la frazione. Un id che non corrisponde a nessuna risorsa immagine lascia la cella con il solo testo.

Una cella può avere un riempimento proprio. TableCell.background è un valore di colore ({ "hex": "#c1dfd6", "model": "hex" }, eventualmente collegato a una voce della tavolozza del documento con paletteId) dipinto al posto dello sfondo di intestazione o di corpo dello stile: una matrice di compatibilità colora così le sue celle di verde, rosso e giallo. L’editor delle tabelle della Sandbox lo imposta dal controllo di riempimento della barra degli strumenti. Per fare la legenda di questi riempimenti, la didascalia, la nota e qualsiasi blocco di testo accettano un campione di colore in linea: :swatch{color="#c1dfd6"} (un esadecimale, o l’id di una voce della tavolozza: :swatch{color="table-compatible"}) compone sulla linea di base un quadratino grande tre quarti del corpo, riempito con il colore e contornato nel colore del testo, così una nota può dire :swatch{color="ok"}: compatible; :swatch{color="no"}: incompatible. Un colore che non si risolve in nulla disegna un contorno vuoto. L’esadecimale può avere un canale alfa (#rrggbbaa, #rgba), e funzionano anche i colori rgb() / rgba(), così un riempimento di cella traslucido ha un campione altrettanto traslucido (vedi Configurazione › Trasparenza).

Le risorse SVG si possono inoltre ricolorare per la stampa con un solo colore piatto tramite diagramStyle.singleInk (predefinito false). Quando è attivo, ogni colore di un diagramma SVG viene rimappato su una tinta di diagramStyle.inkColor ricavata dalla luminanza (inkColor ha come valore predefinito il colore principale della tavolozza, #295AA3): il bianco diventa carta, il nero l’inchiostro pieno, così le figure si riproducono fedelmente quando il documento viene stampato con un unico colore piatto. Vedi Configurazione › Stile dei diagrammi.

Un inserimento malformato (id mancante o vuoto, id senza virgolette o tra apici singoli, attributi in più) non viene promosso a blocco di risorsa; ricade nell’analisi come paragrafo ordinario e resta visibile nell’output. Lo stesso vale per una riga di inserimento ben formata attaccata sotto una riga di paragrafo senza una riga vuota in mezzo: viene letta come parte di quel paragrafo. Entrambi i casi generano un avviso malformedEmbed, una voce Incorporamento composto come testo nel pannello Verifiche della Sandbox.

I rimandi in linea sono riconosciuti in qualsiasi blocco di testo (paragrafi, titoli, citazioni e voci di elenco) e possono stare accanto a grassetto, corsivo, codice in linea e matematica in linea.

Opzioni del rimando

La direttiva :ref accetta tre attributi facoltativi, in qualsiasi ordine. style sceglie come viene reso l’etichetta calcolata: style="number" stampa il numero nudo (1.7), style="full" stampa il nome completo del tipo più il numero (Figure 1.7), e quando style non è impostato si usa lo shortLabel del tipo più il numero (Fig. 1.7). case cambia maiuscole e minuscole solo nella parte dell’etichetta (lower, upper o capitalize), senza toccare il numero. text è una sostituzione letterale che rimpiazza qualsiasi etichetta calcolata e prevale sia su style sia su case. Le opzioni di resa a confronto:

Se un :ref (o un ::resource) indica un id senza risorsa corrispondente, l’etichetta ripiega su ? (viene stampata invece un’etichetta text=, sempre senza numero né link) e la Sandbox genera un avviso di risorsa sconosciuta. Il motore lo registra come voce unknownResourceId nei contentWarnings del documento, con l’intervallo del sorgente e la pagina del rimando, anche per un :ref dentro una didascalia, una nota o una cella di tabella di una risorsa usata dal testo.

#Numerazione al primo rimando

Il numero di una risorsa viene assegnato la prima volta che viene citata nell’ordine di lettura, che questa prima citazione sia un inserimento di blocco ::resource o un :ref in linea. Da lì in poi, ogni rimando allo stesso id stampa quello stesso numero.

Questo significa che i numeri seguono l’ordine in cui chi legge li incontra, non l’ordine in cui le risorse sono state create nel pannello:

• Se fai un :ref a una figura nell’introduzione e la inserisci (::resource) solo due pagine dopo, prende comunque il numero dell’introduzione: il rimando è venuto prima.
• Inserire un nuovo rimando prima nel documento rinumera automaticamente tutto ciò che segue. Non c’è nessuna numerazione manuale da tenere allineata.

La numerazione è per tipo di risorsa e rispetta l’ambito di azzeramento e il formato del contatore di ogni tipo: vedi Configurazione › Tipi di risorsa per i token del modello ({h1}, {n}), resetOn e counterFormat.

Viene contato solo ciò a cui il testo fa riferimento: una risorsa che solo un design disegna (per esempio un elemento immagine di un’apertura di capitolo) non riceve un numero e lascia il contatore com’era. E {h1} conta ogni titolo di livello 1 il cui stile non sia numbered: false, anche uno il cui numberingTemplate è vuoto, quindi un articolo il cui unico H1 è il titolo numera le sue figure 1.1, 1.2… per impostazione predefinita. Configurazione › Che cosa viene numerato riporta entrambe le regole e le impostazioni per Figura 1, 2….

#Collocazione

Ogni risorsa ha una collocazione che decide dove finisce il suo elemento flottante, risolta per risorsa (il suo placement), poi dal defaultPlacement del suo tipo, poi dal valore predefinito integrato auto / column:

Un elemento flottante va nel primo spazio libero dopo il suo primo rimando, in ordine di lettura: il fondo della colonna in cui si trova il rimando, poi la cima e il fondo della successiva colonna vuota della stessa pagina, poi le fasce della pagina successiva che il flusso apre (un elemento flottante a tutta larghezza prende il fondo della pagina quando ogni colonna ha ancora spazio per esso, altrimenti una fascia della pagina seguente). Conta anche una pagina aperta da una figura o una tabella in linea: un elemento flottante in attesa di quella pagina ne prende la cima, sopra la figura o la tabella, quando entrambi ci stanno; quando non ci stanno, la figura o la tabella tiene la pagina e l’elemento flottante aspetta la successiva. Fino a postext 1.4 una pagina del genere veniva saltata, e l’elemento flottante aspettava la pagina dopo anche quando entrambi ci stavano. Viene composto alla sua dimensione, a meno che il suo shrink non gli consenta di ridursi allo spazio di uno slot (vedi la tabella qui sopra), e non finisce mai prima del suo rimando. Gli elementi flottanti di una stessa sequenza di numerazione compaiono nell’ordine dei rimandi: una figura che non trova posto in una pagina trattiene le figure che la seguono (una tabella in attesa non trattiene una figura, né viceversa), così la figura 12 non compare mai prima della figura 11. Una tabella che altrimenti dovrebbe aspettare viene invece tagliata: se le si offre la cima di una colonna vuota, prende le righe che ci stanno e prosegue nello spazio successivo (la colonna accanto o la pagina seguente) con le righe di intestazione ripetute (vedi tableStyle.overflow). Un elemento flottante top o auto con citingPage attivo può invece stare in cima alla pagina (o alla colonna) in cui finisce la riga che lo cita, con il testo sopra il rimando che scende sotto di esso: viene allora disegnato sopra il suo rimando nella stessa pagina, mai in una precedente, e viene comunque letto dopo di esso in un PDF con tag e nell’HTML. Il motore lo stabilisce con qualche passata in più e lo mantiene solo finché la riga che lo cita resta su quella pagina.

Gli elementi flottanti non escono mai dal loro capitolo: a un’apertura di capitolo (un livello di titolo con breakBefore o span: 'page'), a un :::part, a uno stile di riquadro con floatBarrier: true (il riquadro dei «punti chiave» che chiude un capitolo) e alla fine del documento, ogni elemento flottante ancora in sospeso viene collocato prima: negli spazi liberi della pagina, oppure su pagine aperte prima del confine. Un elemento flottante citato per la prima volta dall’apertura stessa (un titolo di capitolo che nomina la sua figura), o dal primo blocco dopo un :::part, appartiene al nuovo capitolo: finisce dopo quella riga, come qualsiasi altro. Una figura o una tabella che chiedeva la cima di una pagina può allora prendere il fondo della pagina di chiusura del capitolo, sotto le sue colonne bilanciate, invece di una pagina propria. Un :::pagebreak manda semplicemente gli elementi flottanti in sospeso alla pagina che lo segue.

Sotto un’apertura a tutta pagina composta sopra due o più colonne di testo, la colonna dell’apertura conta come vuota in cima finché in essa non segue nulla all’apertura: un riquadro flottante racchiuso subito dopo l’apertura, o una risorsa inserita lì con ::resource, prende la cima della prima colonna, sotto l’apertura e alla stessa altezza delle cime delle altre colonne (su più colonne a partire da essa con columns), e il testo della colonna inizia sotto di esso. Un elemento flottante citato nel testo corrente segue comunque la sua riga di citazione. Fino a postext 1.24 la prima colonna non offriva spazio lì e un elemento flottante del genere finiva dalla seconda colonna in poi; layout.floatsUnderOpener: false mantiene quel comportamento (vedi Configurazione › Impaginazione).

Anche i riquadri laterali (span="side") restano nel loro capitolo. Un riquadro che la colonna laterale della sua pagina non riesce a contenere prende la colonna laterale della pagina seguente; dove finisce prima il capitolo, o il documento, ogni riquadro ancora in attesa viene composto nella colonna laterale di una pagina aperta dopo il testo, nell’ordine delle loro recinzioni, e una figura laterale citata dopo di essi sta dietro di loro. Una pagina del genere non contiene testo, quindi la costruzione segnala ogni riquadro e ogni figura che vi si trova (afterText). Un riquadro più alto di una colonna laterale vuota viene composto comunque e segnalato (calloutOverflow), e anche tutto ciò che non trova ancora una pagina viene segnalato (unplaced) invece di essere scartato. Fino a postext 1.24 veniva aperta solo la prima di queste pagine e i riquadri rimasti andavano persi senza avviso.

Le fasce degli elementi flottanti vengono corrette rispetto alla griglia della linea di base, così il testo intorno mantiene il ritmo verticale dell’intera pagina. Una fascia in alto allunga il proprio margine inferiore fino alla linea successiva della griglia, così il testo sotto l’elemento flottante resta allineato con le colonne vicine e con la pagina a fronte. Un elemento flottante in basso viene ancorato in modo che l’ultima riga della sua didascalia condivida la linea di base con l’ultima riga di testo delle altre colonne (un contenuto senza didascalia allinea il suo bordo inferiore all’ultima posizione della griglia): le pagine piene finiscono quindi alla stessa altezza in tutte le colonne e nelle pagine affiancate.

Nella pagina di chiusura di un capitolo, e del documento, nulla segue le figure e le tabelle a tutta pagina composte sotto l’ultima fascia di testo, quindi risalgono fino a stare a una distanza di elemento flottante sotto di essa, impilate nel loro ordine, invece di lasciare del bianco tra il testo e una figura al piede della pagina. Questo vale anche per un elemento flottante position: 'bottom'. Per tenerle al piede, come in ogni altra pagina, imposta layout.hugClosingFloats: false (vedi Configurazione › Impaginazione). Le pagine con una colonna laterale non le spostano mai.

Tutti e tre i backend (l’anteprima su canvas, il visualizzatore HTML e l’output PDF) disegnano le risorse. Nel backend HTML i contenuti delle immagini vivono fuori banda, quindi l’applicazione ospite li fornisce tramite l’opzione di risoluzione resourceImageUrl(fileId); quando la funzione di risoluzione manca (o non restituisce nulla per un file), la risorsa viene disegnata come un riquadro segnaposto neutro, così l’impaginazione resta stabile. Il file di un video arriva allo stesso modo tramite resourceVideoUrl(fileId) (vedi Video).

Dove può finire un elemento flottante

«Mai prima del suo rimando» si conta dalla riga che cita l’elemento flottante: l’elemento flottante aspetta che quella riga sia composta e prende il primo spazio libero dopo di essa in ordine di lettura; la cima della pagina su cui è composta la riga viene prima di essa. Un elemento flottante laterale (span: 'side', nella colonna laterale riservata agli elementi flottanti di un’impaginazione a colonna e mezza) è l’eccezione: si impila nella colonna laterale accanto al testo che lo cita e può stare più in alto sulla pagina rispetto alla riga che lo cita. Per una figura citata a pagina 5:

• Una pagina di apertura di capitolo segue le stesse regole: un elemento flottante auto o bottom a tutta larghezza citato nel primo paragrafo dell’apertura può prendere la fascia al piede di quella pagina, sotto il suo testo; uno top apre la pagina seguente. Per avere l’immagine sulla pagina che la cita, usa auto o bottom, oppure disegnala come elemento immagine del design dell’apertura.
• Due elementi flottanti di colonna citati nello stesso paragrafo prendono i due spazi successivi: di solito il primo il piede della colonna che li cita, il secondo la cima della colonna vuota successiva, affiancati sulla pagina.
• In un’impaginazione a una colonna un elemento flottante a tutta larghezza è un elemento flottante di colonna, e valgono le stesse regole: un elemento flottante top citato su una pagina finisce in cima alla successiva.
• Anche un paragrafo che passa da una pagina alla successiva conta dalla sua riga di citazione. Quando il paragrafo inizia al piede di pagina 5 e il rimando cade a pagina 6 (oppure l’intero paragrafo passa a pagina 6, perché al piede di pagina 5 non entrano abbastanza sue righe), il rimando è a pagina 6: un elemento flottante top apre pagina 7, e uno auto prende il piede di pagina 6 quando c’è spazio. Lo stesso vale tra le colonne di una pagina, e per un riquadro diviso su più pagine: una figura citata dalla sua seconda parte aspetta quella parte.
• Cambiato in postext 1.5. Fino a postext 1.4 un elemento flottante veniva messo in coda quando l’impaginazione raggiungeva il paragrafo che lo cita, quindi la pagina su cui un paragrafo del genere proseguiva (o si spostava) poteva aprirsi con l’elemento flottante, sopra la riga con il rimando. Ora una figura del genere finisce una pagina dopo, o al piede della pagina quando chiede auto; può seguirne una variazione del numero di pagine.

#Testo intorno alle immagini

Un’immagine, una tabella o un riquadro più stretti della loro colonna possono stare su un lato della colonna con il testo che scorre accanto, come in una rivista o in una newsletter. Dai alla sua collocazione un lato di wrap e, se vuoi, una width:

{ "id": "bed", "typeId": "figure", "kind": "svg", "caption": "The new planting bed.",
  "placement": { "position": "here", "wrap": "right", "width": 0.4 } }

• In linea ("here"). La risorsa sta sul suo lato della colonna, con la cima allineata alla cima della riga successiva nel punto della riga ::resource, e i paragrafi, le citazioni e le voci di elenco che seguono le scorrono accanto alla giustezza rimasta, poi sotto a piena giustezza. Un paragrafo che inizia accanto alla risorsa e finisce sotto resta un unico paragrafo: nessuna interruzione, nessuno spazio in più al piede dell’immagine. Ogni riga resta sulla griglia della linea di base; lo spazio sotto l’immagine è la sua distanza arrotondata per eccesso a righe intere della griglia.
• Un elemento flottante di colonna. Un elemento flottante span: "column" largo una colonna, in cima ("top", o "auto" in cima a una colonna) o al piede ("bottom", "auto") di una colonna, viene collocato nella sua fascia come ogni elemento flottante; le prime righe della colonna, o le ultime, gli scorrono poi accanto. Su una pagina a due colonne l’elemento flottante appartiene alla sua colonna, e l’altra resta a piena giustezza.
• Un riquadro. Un :::callout accetta le stesse impostazioni come attributi: :::callout{wrap="right" width=0.4} compone una citazione in evidenza o un box laterale nel punto in cui compare, con il testo che segue accanto, e placement="top" o "bottom" con wrap lo fa flottare in cima o al piede di una colonna. Un riquadro con testo intorno viene impaginato per intero e non si divide mai.
• Che cosa va sotto. Un titolo, una formula in evidenza, una figura o una tabella, un riquadro e una poesia non scorrono accanto a un elemento con testo intorno: vanno sotto di esso, e il bianco accanto all’elemento sopra di loro resta vuoto. Lasciare la colonna (il suo piede, un :::columnbreak, un’interruzione di pagina) chiude lì lo scorrimento: l’elemento appartiene alla sua colonna. Quando il blocco subito dopo una risorsa in linea non può scorrerle accanto, la risorsa prende la sua fascia, come senza wrap.
• Distanza e limiti. wrapGap (altrimenti layout.wrap.gap, altrimenti una riga di testo) separa l’elemento, didascalia compresa, dal testo accanto e dal testo sotto. Dove il testo accanto sarebbe più stretto di layout.wrap.minTextWidth (12 em di testo corrente), o l’elemento è più basso di layout.wrap.minLinesBeside righe (2), l’elemento prende la sua fascia per intero e un avviso textWrap lo segnala. Uno in linea troppo alto per lo spazio rimasto nella sua colonna passa alla successiva con la sua ancora, con lo stesso avviso.
• Lati. left e right sono lati del flusso del testo, come per align: in un libro da destra a sinistra left è il lato destro del foglio. start ed end indicano gli stessi lati.
• Output. Il canvas, il visualizzatore HTML, il PDF e l’EPUB a layout fisso compongono le righe come sono state impaginate; un PDF con tag legge l’immagine o il riquadro prima del paragrafo che le scorre accanto. Un EPUB a layout fluido lo fa flottare sul suo lato con il CSS, nella stessa proporzione della larghezza del testo.
• Non ancora. Testo su entrambi i lati di un’immagine, scorrimento lungo il contorno, scorrimento dentro il contenuto di un riquadro e scorrimento nel testo verticale (l’elemento mantiene la sua fascia, con un avviso). Le colonne con un elemento con testo intorno sono escluse dal bilanciamento delle colonne.

#Dimensione delle bitmap

Una bitmap dichiara i suoi pixel: bitmap.width e bitmap.height sono il numero di pixel del file, non una dimensione di stampa. Quanti di questi pixel stanno in un pollice decide quanto grande viene composta l’immagine prima che il suo spazio la limiti. Ci sono tre modi di dimensionarla:

• I suoi pixel ai dpi della pagina (il valore predefinito). Senza una risoluzione, un pixel dell’immagine è un pixel dell’impaginazione (page.dpi, 300 se non impostato): una fotografia di 2400 px è larga 8 in (203,2 mm) su una pagina a 300 dpi, e il doppio su una a 150 dpi.
• Una risoluzione. bitmap.resolution è la risoluzione in ppi dell’immagine alla sua dimensione di stampa naturale, quindi la sua larghezza naturale è width × page.dpi / resolution su una pagina con qualsiasi dpi: 2400 px a resolution: 300 sono larghi 203,2 mm su una pagina impaginata a 150 dpi o a 300. layout.bitmapResolution dà una risoluzione a ogni bitmap che non ne ha una propria: un numero (300), oppure 'file', la risoluzione dichiarata dal suo file (bitmap.fileResolution: il pHYs di un PNG, la densità JFIF o EXIF di un JPEG, l’EXIF di un WebP; per un’immagine importata da Word, la dimensione a cui Word la stampava). Fotocamere, screenshot ed esportazioni per il web dichiarano spesso 72 o 96 ppi quando non sanno nulla di una dimensione di stampa, quindi con 'file' questi due valori contano come non impostati e l’immagine mantiene i suoi pixel ai dpi della pagina; un 72 dichiarato sulla risorsa stessa viene preso così com’è scritto. 'document', il valore predefinito, è il primo modo.
• Una porzione della colonna. placement.width restringe un elemento flottante o un inserimento in linea a una frazione della sua colonna (o della pagina), e un’immagine più grande di quella porzione viene ridotta fino a essa, qualunque siano i suoi pixel (vedi Collocazione).

In ogni caso lo spazio limita l’immagine, conservandone le proporzioni, e un’immagine più piccola non viene mai ingrandita. La stessa dimensione naturale vale per un’immagine in una cella di tabella e per l’elemento image di un design con dimensione 'auto'. Il PDF incorpora il file così com’è, alla dimensione con cui è collocato. La verifica preliminare controlla la risoluzione a cui viene stampata ogni immagine, e il pannello Risorse della Sandbox la mostra per ciascuna immagine. Da postext 1.24.

{ "id": "harbour", "typeId": "figure", "kind": "bitmap", "caption": "The harbour at dawn.",
  "bitmap": { "fileId": "harbour.jpg", "format": "jpeg", "width": 2400, "height": 1600, "resolution": 300 } }

bitmapInfo(bytes) (da postext e postext/bundle) legge i pixel di un file e la risoluzione che dichiara, { width, height, resolution?: { x, y, source } }; un pacchetto aperto con 'file' ne riempie fileResolution, e la Sandbox lo conserva per ogni immagine che carica.

#Zona sicura

Una risorsa bitmap o SVG può indicare una zona sicura: il rettangolo dell’immagine che contiene ciò che conta (una persona e una striscia del paesaggio alle sue spalle, la parte tracciata di un grafico) e che viene sempre mostrato. È il safeArea della risorsa, quattro frazioni (0–1) della dimensione intrinseca dell’immagine misurate dal suo angolo in alto a sinistra: x e width sono frazioni della larghezza, y e height dell’altezza. Il nome dice che cosa va conservato; un riquadro di ritaglio direbbe dove tagliare.

const harbour: Resource = {
  id: 'harbour', typeId: 'figure', kind: 'bitmap', caption: 'The harbour at dawn.',
  createdAt: 0, updatedAt: 0,
  bitmap: { fileId: 'harbour.jpg', format: 'jpeg', width: 2400, height: 1600 },
  // the boats and the quay: 18–68 % of the width, 25–85 % of the height
  safeArea: { x: 0.18, y: 0.25, width: 0.5, height: 0.6 },
};

Viene ritagliata solo un’immagine con una zona sicura. Il motore può allora mostrarla con qualsiasi proporzione compresa tra l’immagine intera e la zona sicura: più alta della proporzione propria dell’immagine ritagliando i lati, al massimo fino alla larghezza della zona sicura, oppure più bassa ritagliando sopra e sotto, al massimo fino alla sua altezza. La larghezza della figura non cambia mai, solo la sua altezza. Ciò che sta fuori dalla zona sicura viene ritagliato su entrambi i lati in proporzione ai margini che vi si trovano, così un soggetto a sinistra del centro resta a sinistra del centro. Composto largo 60 mm, il porto qui sopra è alto 40 mm quando è intero, e può essere mostrato con un’altezza qualsiasi da 24 mm (sopra e sotto ritagliati fino al 60% dell’altezza) a 80 mm (i lati ritagliati fino a metà della larghezza). I valori oltre i bordi dell’immagine vengono limitati a essi; una zona con un valore che non è un numero o con un lato inferiore al 2% dell’immagine, o una che copre l’intera immagine, viene ignorata, e lo stesso vale per il campo su una tabella. Senza zona sicura un’immagine viene sempre mostrata intera, come prima.

Il motore usa questo margine in quattro punti:

• Lo spazio rimasto in una colonna. Un’immagine in linea (position: 'here') un po’ troppo alta per lo spazio rimasto nella sua colonna, compresa una la cui didascalia sborderebbe oltre il piede della pagina, viene ritagliata entro la sua zona sicura per restare lì, invece di passare alla colonna o alla pagina successiva lasciando questa corta.
• Pagine più basse della figura. Con layout.fitFiguresToPage, un’immagine troppo alta per la pagina viene prima ritagliata entro la sua zona sicura, mantenendo la larghezza, e ridotta solo se è ancora troppo alta (vedi Configurazione › Impaginazione).
• Fasce più basse della figura. Un elemento flottante il cui placement.shrink lo riduce allo spazio del suo slot viene prima ritagliato entro la sua zona sicura, mantenendo la larghezza, e solo dopo ridotto; la leva flexFigure descritta sotto non lo fa mai crescere oltre quello spazio.
• Bilanciamento delle colonne. Un’immagine con zona sicura composta in linea in una colonna corta, o flottante in cima o al piede di quella colonna sulla sola colonna, cresce di righe intere della griglia della linea di base per riempire le righe vuote della colonna. Un’immagine più alta non lascia un buco visibile, quindi questa leva, flexFigure, viene provata subito dopo il riquadro che chiude la colonna e prima di aggiungere spazio sopra i titoli o dopo gli elenchi. Un elemento flottante in cima a una colonna nella pagina di chiusura di un capitolo o in una fascia di chiusura non cresce, perché quelle cime di colonna restano allineate (vedi Configurazione › Bilanciamento delle colonne).

Il VDT registra il ritaglio sul blocco della risorsa: bodySource è la parte dell’immagine mostrata in bodyRect, nelle stesse frazioni (assente quando l’immagine intera lo riempie), e bodyFlex indica i px di cui il corpo potrebbe ancora ridursi e crescere e i px di cui le leve lo hanno già modificato ({ shrink, grow, delta }). L’anteprima su canvas e il PDF ritagliano sul corpo e disegnano l’immagine intera alla sua dimensione non ritagliata; il visualizzatore HTML e l’EPUB a layout fisso compongono l’immagine con object-fit: cover e un object-position corrispondente; un EPUB a layout fluido, che non ha una pagina da riempire, mostra l’immagine intera. Un’applicazione ospite che disegna da sé le immagini può usare le funzioni esportate da postext: resourceSafeArea e normalizeSafeArea (la zona come la legge il motore, o undefined), safeAreaHeightRange (il corpo più basso e più alto a una data larghezza), safeAreaSource (la parte mostrata a una data altezza) e uncroppedPictureBox (dove disegnare l’immagine intera prima del ritaglio), con il tipo ResourceSafeArea. Nella Sandbox il campo è Zona sicura su un’immagine del pannello Risorse.

La ricetta Nº 116 del Ricettario, Foto che crescono per riempire una colonna corta, compone due volte un servizio di rivista a due colonne, senza e con zone sicure, così puoi confrontare le pagine una accanto all’altra.

#Ancore dei personaggi e zone da evitare

Un’immagine che costituisce il disegno di una vignetta di fumetto può anche indicare dove si trovano i suoi personaggi, per il lettering (vedi Fumetti). anchors elenca un punto per ogni personaggio che parla e avoid le zone che nessuna nuvoletta copre, entrambi in frazioni dell’immagine come la zona sicura:

const radio: Resource = {
  id: 'lh-radio', typeId: 'figure', kind: 'bitmap', createdAt: 0, updatedAt: 0,
  bitmap: { fileId: 'lh-radio.jpg', format: 'jpeg', width: 1000, height: 1000 },
  safeArea: { x: 0, y: 0.36, width: 0.62, height: 0.56 },
  anchors: [
    // the keeper: mouth, head (for thought balloons) and face
    { id: 'tomas', x: 0.345, y: 0.52, head: { x: 0.38, y: 0.44 }, face: { x: 0.29, y: 0.4, width: 0.16, height: 0.18 } },
  ],
  avoid: [{ x: 0, y: 0.44, width: 0.22, height: 0.26 }], // the radio
};

L’id di un’ancora è la chiave del personaggio nella sceneggiatura (tomas: …), oppure sfx per il punto in cui si raccolgono gli effetti sonori della vignetta; x e y sono la bocca verso cui punta la coda di una nuvoletta di dialogo, head il punto verso cui puntano le bollicine di una nuvoletta di pensiero (la bocca se non è impostato) e face un rettangolo che nessuna nuvoletta copre. Il motore trasforma ogni punto secondo il ritaglio e il ribaltamento della vignetta, così una coda resta sul suo personaggio qualunque forma prenda la vignetta; un’ancora fuori dalla zona sicura genera comicAnchorOutsideSafeArea, perché un ritaglio potrebbe tagliarla via. Un terzo elenco, faces, contiene i volti delle persone che non parlano, come rettangoli simili a quelli di avoid: nessuna nuvoletta li copre, mentre una zona da evitare cede quando una vignetta non ha altro spazio. Le ancore appartengono all’immagine e servono a ogni traduzione del fumetto. Le leggono solo le vignette di fumetto; una figura le ignora. Nella Sandbox si segnano nella finestra Zona sicura e lettering del pannello Risorse.

#Video

Una risorsa video (kind: 'video') è un video di YouTube o Vimeo, oppure un video tuo: un file conservato nel libro (MP4, WebM) o uno a un indirizzo web, un file su un server o uno stream HLS (una playlist .m3u8). Viene collocato, dotato di didascalia, fatto flottare e citato come un’immagine, e numerato in una sequenza propria: il tipo integrato video stampa Video 1.1, Video 1.2… accanto a Figura 1.1 e Tabella 1.1 (vedi Configurazione › Tipi di risorsa). Ogni output lo mostra come può:

const talk: Resource = {
  id: 'keeper-talk', typeId: 'video', kind: 'video',
  caption: 'The keeper explains the lamp.',
  altText: 'A lighthouse keeper beside the lamp',
  createdAt: 0, updatedAt: 0,
  video: {
    source: 'youtube',                        // 'youtube' | 'vimeo' | 'file'
    url: 'https://youtu.be/aqz-KE-bpKQ',
    poster: { fileId: 'talk.jpg', format: 'jpeg', width: 1280, height: 720 },
    start: 30,                                // plays from 0:30; the printed link starts there too
  },
};

Il testo cita un video come cita una figura: :ref{id="keeper-talk"} stampa Video 1.1 e fa flottare il poster nel primo spazio libero dopo il rimando, e ::resource{id="keeper-talk"} con placement.position: 'here' lo compone in linea. I campi di Resource.video (ResourceVideo):

Il poster. Viene composto alla giustezza del suo spazio (o alla frazione placement.width di essa), nelle sue proporzioni, qualunque sia la sua dimensione in pixel: un fotogramma a dimensione di schermo viene ingrandito invece di essere stampato piccolo. Come una bitmap, può avere una zona sicura e seguire placement.align. Un video senza poster stampa un riquadro scuro nelle proporzioni del video (16:9 quando nulla le indica) con le sue sovrimpressioni, e genera un avviso sul contenuto videoWithoutPoster. Nella Sandbox il poster di un video di YouTube o Vimeo viene scaricato dalla piattaforma quando ne inserisci l’indirizzo, e quello di un file è un fotogramma che scegli nel video.

L’indirizzo. Il codice QR e il link del PDF aprono la pagina del video, https://youtu.be/<id> o https://vimeo.com/<id>, a partire da start. Un file non ha una pagina: aprono il suo indirizzo di produzione, che è anche l’indirizzo da cui viene riprodotto un video senza un file proprio (un MP4 su un server, uno stream HLS). Senza indirizzo, la stampa non ha codice QR né link (videoWithoutUrl), e un output HTML o EPUB che non contiene il file mostra il poster. Un indirizzo di YouTube o Vimeo che non indica nessun video di quella piattaforma genera videoUrlInvalid; al posto di un player viene mostrato il poster.

I player. Le opzioni del player (controlli, pulsante di download, schermo intero, menu della velocità, picture in picture, trasmissione, riproduzione automatica, avvio senza audio, ripetizione, precaricamento, incorporamenti con privacy avanzata) si impostano per l’intero libro in videoStyle.player e per un singolo video in video.player; ogni player rispetta ciò che può (vedi Configurazione › Stile dei video). Il backend HTML prende l’URL riproducibile di un file tramite l’opzione resourceVideoUrl(fileId), come prende le immagini tramite resourceImageUrl, e in sua assenza ripiega sull’indirizzo di produzione. La sua opzione videos: { files, streams, hls } sceglie tra player e poster per ogni sorgente, prevalendo su videoStyle.html (hls, un video riprodotto da un indirizzo HLS, segue files se non è impostato); la usa il generatore di EPUB. Un <video> che riproduce un indirizzo HLS porta data-pt-hls, così un’applicazione ospite può dargli un player nei browser senza HLS nativo (Safari e le versioni recenti di Chrome lo riproducono così com’è). In un libro da destra a sinistra il player e le sovrimpressioni del poster vengono raddrizzati come un’immagine, così il codice QR resta leggibile.

Nel VDT. Il blocco di risorsa di un video ha kind: 'video', il suo poster come fileId / format (disegnato come una bitmap) e video (VDTResourceVideo): il link a cui viene mandato chi legge, l’embedUrl di YouTube o Vimeo con le opzioni del player applicate, il fileId di un file, il mimeType di un video tuo (del suo file o del solo indirizzo, application/vnd.apple.mpegurl per HLS), l’intervallo start / end, il player risolto, linkPoster, html e le sovrimpressioni playMark e qr (i moduli del QR come righe di '0' / '1'), con rettangoli relativi all’angolo in alto a sinistra del corpo. Un’applicazione ospite che disegna da sé i video può usare le funzioni esportate da postext: parseVideoUrl, videoWatchUrl, resourceVideoLink, videoEmbedUrl, videoEmbedAllow, videoElementAttributes, mediaFragment, videoMimeType, videoFormatOfUrl, resourceVideoFormat, isHlsMimeType, HLS_MIME_TYPE, youtubePosterUrls, encodeQr, layoutVideo, playMarkTriangle e qrModuleRuns.

In un pacchetto. Un .postext contiene un file (resources/<id>.mp4) e il poster (resources/<id>.poster.jpg): la voce del manifest li indica in file e poster, dà la dimensione del poster in width / height e conserva il resto in video senza gli id dei file. bundleVideoUrl(bundle) è la funzione di risoluzione resourceVideoUrl sui file di un pacchetto. Un video riprodotto solo da un indirizzo non contiene file: la sua voce ha soltanto il poster. In un pacchetto bilingue una lingua può dare a un video il proprio poster e il proprio video (un altro montaggio, al suo indirizzo) in localized[…].resources.

Video sulle pagine di Folio

Nel libro 3D un video tuo si riproduce sulla pagina su cui è stampato. Un clic sul poster lo avvia lì, qualunque cosa faccia il puntatore sul libro (girare le pagine, ruotare la vista o selezionare il testo): lo shader della pagina disegna i fotogrammi del video sopra il poster, così l’immagine si piega e si incurva con la carta mentre il foglio gira, e la riproduzione continua durante la girata. Un clic su un video in riproduzione lo mette in pausa, un clic su uno in pausa lo riprende, e Spazio o Invio fanno lo stesso per il primo video della doppia pagina aperta. Avviare un altro video ferma quello in riproduzione (che torna al suo poster), e un video si ferma quando il libro si posa su una doppia pagina che non lo mostra più, oppure al suo end. Il puntatore diventa una mano sopra un video che può riprodurre; un trascinamento che parte da un video gira comunque la pagina o la vista. Un video impostato per partire da solo (video.player.autoplay) si avvia da sé la prima volta che il libro si posa sulla sua doppia pagina, una volta che il libro si è assestato (anche quando l’applicazione ospite lo impagina a passi), e mai più in quel visualizzatore.

Un video che si riproduce insieme agli altri (video.player.exclusive: false, da postext 1.18) cambia entrambe le regole. Avviarlo ferma solo i video esclusivi, quindi più video di questo tipo si riproducono insieme; avviare un video esclusivo ferma anche lui. Con autoplay parte, senza audio, ogni volta che il libro si posa sulla sua doppia pagina, e si ferma quando la doppia pagina viene girata: i loop muti (loop) di una pagina partono insieme ogni volta che chi legge ci arriva.

• Che cosa si riproduce. Un file (l’applicazione ospite trasforma il suo fileId in un URL con l’opzione videoUrl, un object URL nella Sandbox) oppure, in sua assenza, il suo indirizzo: MP4, WebM o uno stream HLS. Uno stream HLS si riproduce con hls.js ovunque il browser abbia le Media Source Extensions (caricato alla prima riproduzione; una dipendenza peer facoltativa di postext-folio), limitato alla variante più vicina alla dimensione dell’immagine sullo schermo, così un’immagine alta poche centinaia di pixel non scarica mai una variante 4K; in alternativa si usa l’HLS del browser. Le sue richieste portano una query pt-cors propria, così la cache del browser non restituisce mai loro una copia scaricata da un altro player senza CORS. YouTube e Vimeo si riproducono in iframe, che WebGL non può disegnare: un clic sul loro poster gira la pagina come in qualsiasi altro punto.
• Letture da altre origini. WebGL disegna un video solo quando il suo server consente la lettura (CORS, Access-Control-Allow-Origin). Un video che non si può leggere resta un poster, e onVideo riceve error.
• Audio. Il clic consente al video di partire con l’audio; un browser che rifiuta comunque lo riceve senza audio. Un video che parte da solo ha l’audio una volta che chi legge ha fatto clic o digitato sulla pagina (arrivarci girando le pagine conta); prima parte senza audio, e un clic su di esso attiva l’audio prima che il clic successivo lo metta in pausa. video.player.muted lo avvia senza audio, loop lo riproduce di nuovo, e start / end indicano la parte che viene riprodotta.
• Su ogni pagina. L’immagine viene disegnata dove la colloca l’impaginazione: ruotata con una risorsa ruotata, diritta su una pagina verticale e non specchiata in un libro da destra a sinistra, come il poster. Un poster ritagliato entro la sua zona sicura ritaglia il video allo stesso modo.
• Senza WebGL2, o con il movimento ridotto, il video si riproduce in un <video> HTML sovrapposto alla pagina.

const book = createFolioFromDocument(container, doc, {
  // An uploaded video's playable URL (an object URL over its bytes).
  videoUrl: (fileId) => urls.get(fileId),
  onVideo: ({ resourceId, state }) => console.log(resourceId, state), // playing | paused | stopped | error
});
book.stopVideo();

videos: false lo disattiva. toggleVideoAt({ page, x, y }) fa ciò che fa un clic in quel punto, e pageVideoSpots(page, doc) elenca dove si trova ogni video su una pagina, per un’applicazione ospite che disegna i propri controlli.

Due ricette del Ricettario compongono video: la Nº 131, Un programma di cineclub con codici QR sui poster, stampa ogni film come un cartello con il titolo, un simbolo di riproduzione e un codice QR, e la Nº 132, Una scheda di laboratorio i cui filmati si riproducono sullo schermo e nell’EPUB, imposta le opzioni del player per l’edizione HTML e include i propri filmati in un EPUB a layout fisso.

#Fumetti

Le pagine, le strisce e le doppie pagine a fumetti si scrivono in due blocchi delimitati il cui contenuto viene letto direttamente dal motore, riga per riga: :::page e :::strip. Al loro interno, le righe ::panel aprono le vignette e le righe di sceneggiatura le letterano. La guida, con le regole di impaginazione, il lettering e gli output, è Fumetti; le impostazioni sono in Configurazione › Fumetti.

#:::page

:::page{split="30 [30 | 20 | *] / *" gutter=4mm}
::panel{art=lh-arrive}
caption: Every summer, Maya spent a week at the lighthouse.
maya: Grandpa! I'm here!
::panel{art=lh-radio focus="40% 50%"}
tomas: Just in time.
::panel{art=lh-maya}
maya{thought}: That valve looks loose…
::panel{art=lh-beam bleed}
sfx{rotate=-8}: KRAK
:::

Un blocco :::page è una pagina a fumetti: apre una pagina nuova, la occupa tutta, e il testo che segue il ::: di chiusura comincia nella pagina successiva. I suoi attributi sono split (come la pagina viene divisa in celle: dimensioni in percentuale separate da / per le strisce e da | per le vignette affiancate, un elenco tra parentesi quadre per dividere di nuovo una cella, * per lo spazio restante, a~b per una linea obliqua), gutter (una lunghezza, o due: tra le strisce e tra le vignette; un numero senza unità è in millimetri), style (uno stile di vignetta con nome), bleed, direction (ltr o rtl, scritto anche dir) e spread (vedi Doppie pagine). Senza split le vignette vengono impilate in strisce uguali. Blocchi Markdown, contenitori e direttive non vengono letti all’interno del blocco; i <!-- comments --> sì.

#Vignette

Una riga ::panel{…} apre una vignetta, che occupa la cella successiva nell’ordine di lettura e prosegue fino alla riga ::panel seguente o al delimitatore di chiusura:

#Righe di sceneggiatura

Ogni riga di una vignetta è una nuvoletta, una didascalia o un effetto sonoro, scritta key{attributes}: text:

maya: Grandpa! I'm here!
tomas{whisper}: Shh. Listen.
caption{at=bottom-end}: Three streets away.
sfx{at="62% 40%" rotate=-8 size=1.4}: KRAK
ben{tail=start}: (from off the panel) Over here!
sfx{vertical size=2.6 font="Dela Gothic One"}: ドン
maya: This line goes on
  on the next line,\
  and breaks here.

• La chiave è un id di personaggio (lettere, cifre, _, ., -), uguale in ogni traduzione; caption, sfx e note sono riservate. I due punti possono essere quelli a larghezza piena ：.
• Una parola isolata tra le graffe è uno stile di nuvoletta (thought, whisper, shout, radio, inner o uno di comics.balloonStyles); style= indica la stessa cosa.
• at fissa la posizione della nuvoletta: un punto in percentuali dell’immagine della vignetta (at="62% 40%"), oppure un angolo o un lato (top-start, top-end, bottom-start, bottom-end, top, bottom). to punta la coda verso un punto dell’immagine; tail=none la elimina e tail=top|bottom|start|end|left|right la punta fuori dalla vignetta. join e join=false uniscono la nuvoletta alla precedente dello stesso personaggio o la tengono separata; break le permette di oltrepassare il bordo, e l’attraversamento non viene segnalato come sbordo. rotate (gradi), size (un fattore di scala, per gli effetti sonori), color e font ne modificano il lettering.
• vertical e horizontal (oppure mode=vertical, mode=horizontal) impostano la direzione di scrittura della riga al posto di quella del libro: un ドン non tradotto composto in colonna in un’edizione orizzontale, un’insegna scritta in orizzontale composta in riga in un’edizione verticale. Una colonna in un libro di un’altra lingua segue le regole del proprio testo (con i kana, quelle del giapponese). In un libro verticale, una riga senza caratteri cinesi o giapponesi viene comunque composta in orizzontale.
• Una riga rientrata di due spazi o di una tabulazione continua la nuvoletta precedente; una barra rovesciata a fine riga spezza il testo in quel punto. Le righe vuote vengono ignorate.
• Il testo è Markdown in linea: enfasi (letterata in grassetto corsivo), :tcy, :ruby (la lettura composta sopra la base, tranne che sopra una base da destra a sinistra), :ltr e :rtl (un tratto mantenuto nella propria direzione). Note a piè di pagina e marcatori :ref non vengono letti.

#:::strip

:::strip{split="* | * | *" aspect=3 span=page placement=top}
::panel{art=pip-1}
pip: Morning, Otto!
::panel{art=pip-2}
::panel{art=pip-3}
otto: Is it?
:::

Una :::strip ha lo stesso contenuto di una pagina ma si colloca nel testo come un unico riquadro indivisibile, diviso in vignette: span (column, il valore predefinito, o page), placement (here, il valore predefinito, dove è scritta; oppure top, bottom, auto, fatta flottare come una figura) e la sua dimensione, data da height (una lunghezza; un numero senza unità è in millimetri) o da aspect (larghezza su altezza: 3, 4/1, 4:1; per impostazione predefinita le proporzioni che rendono quadrate le sue vignette). Una striscia a tutta larghezza impostata su here in una pagina di più colonne taglia le colonne dove si trova, come fa un riquadro a tutta larghezza. width la rende più stretta della giustezza che occupa (il 60% di essa, o una lunghezza) e align la colloca all’inizio (start), al centro (center, il valore predefinito) o alla fine (end) di quella giustezza, nel senso del testo. caption="…" aggiunge sotto di essa una didascalia nello stile delle didascalie; con type=figure (un tipo di risorsa) la didascalia prende l’etichetta e il numero del tipo e la striscia entra nella sequenza di quel tipo, e con id=… un :ref la può citare. Senza split le vignette stanno affiancate. Le strisce vengono lette solo al livello più alto di un capitolo.

#Doppie pagine

:::page{spread} distende una pagina su due pagine affiancate: la divisione copre entrambe le gabbie unite al dorso, senza i loro margini interni, e una vignetta può attraversare il dorso. La doppia pagina si apre su una pagina pari, dopo una pagina bianca se serve. Vedi Fumetti › Doppie pagine.

#Che cosa NON è supportato

Postext non riconosce le seguenti funzionalità di CommonMark. Vengono trattate come testo semplice (e quindi compaiono alla lettera nell’output) oppure scartate senza avviso:

• Titoli in stile Setext: la forma con sottolineatura === / ---. Usa i titoli ATX (#).
• HTML passthrough: i <tags> grezzi non vengono interpretati. Nemmeno i tag in stile MDX sono supportati; il sorgente Postext è Markdown puro.
• Linee orizzontali: ---, ***, ___.
• Tabelle: le tabelle con barre verticali non vengono analizzate. Le tabelle sono modellate come risorse strutturate in PostextContent.resources.
• Link con riferimento: [text][id] più un blocco di definizione.
• Autolink: <https://example.com>.
• A capo forzati con due spazi finali: gli spazi vengono eliminati. Termina invece la riga con una barra rovesciata (vedi A capo).
• Barrato: ~~text~~. Il renderer del barrato è al momento riservato alle voci di attività completate.
• Note a margine: non implementate, e PostextContent.notes, che i tipi accettano, viene ignorato dal motore. Le note a piè di pagina e le note di fine capitolo si scrivono con [^id] (vedi Note a piè di pagina); fino a postext 1.5 dovevano essere composte come testo.

Questo elenco si accorcerà nel tempo. Fino ad allora, tutto ciò che non è elencato esplicitamente nella sezione delle funzionalità supportate va considerato testo letterale.

Al di là della sintassi, l’arabo e le altre scritture da destra a sinistra vengono composti da destra a sinistra, con l’algoritmo bidirezionale e la rilegatura a destra (vedi Impaginazione araba). Il cinese viene composto in orizzontale e in verticale, con la divisione in righe, le larghezze della punteggiatura, la giustificazione tra i caratteri, i segni, il ruby e il warichu che la sua regione si aspetta (vedi Impaginazione cinese). Il giapponese viene composto con regole proprie: kinsoku, spaziatura degli yakumono, furigana, segni di enfasi, segni kanbun e note (vedi Impaginazione giapponese); il coreano passa per lo stesso compositore con le regole del cinese continentale. I pattern di sillabazione sono inclusi per otto lingue, e le etichette predefinite per quelle otto, il cinese, il giapponese e l’arabo. Vedi Lingue e scritture.

#Convenzioni di scrittura

Alcune convenzioni fanno la differenza tra un documento che viene analizzato senza problemi e uno che ti riserva sorprese:

• Lascia una riga vuota tra i blocchi. Due paragrafi separati da una riga vuota sono due paragrafi. Due paragrafi su righe consecutive diventano uno solo: ogni riga confluisce nel paragrafo precedente.
• Le righe vuote in più non aggiungono spazio. Tre righe vuote separano due blocchi esattamente come una. Quando vuoi più spazio tra di essi, scrivi una riga :::space.
• Rientra una voce annidata fino al testo della voce precedente. Due spazi sotto un punto elenco (- ), tre sotto 1. , quattro sotto 10. , come CommonMark annida gli elenchi; anche due spazi sotto 1. annidano. Una voce si annida sotto la voce aperta più vicina il cui marcatore si trova almeno due colonne più a sinistra, quindi uno spazio non annida nulla e non si salta mai un livello, qualunque sia il passo (fino a postext 1.15 la profondità era floor(spaces / 2) + 1, e un 1. sotto 1. finiva al livello 4). Una tabulazione arriva al multiplo di quattro colonne successivo. La profondità massima è 5.
• Non rientrare la prima voce di un elenco. Le voci di livello 1 cominciano alla colonna 0. La prima voce di un elenco apre il livello 1 per quanto sia rientrata (fino a postext 1.15 i suoi spazi iniziali aumentavano la profondità), quindi per annidare serve una voce sopra sotto cui annidarsi.
• I marcatori di attività vanno tra parentesi quadre con un solo spazio. [ ], [x], [X], senza varianti. [*] o [-] non sono marcatori di attività; vengono resi come testo letterale.
• Le citazioni dentro gli elenchi non sono supportate. Comincia la citazione alla colonna 0, fuori dall’elenco.
• Immagini e tabelle stanno in resources. L’![alt](src) in linea viene eliminato proprio perché le immagini in linea compromettono il posizionamento consapevole delle colonne. Dichiara ogni immagine come risorsa e richiamala per id: sarà il motore a decidere se farla flottare, interrompere la colonna o spostarla in cima alla pagina successiva.
• Scrivi i simboli del dollaro come \$ quando non intendi una formula. Postext interpreta $…$ come LaTeX in linea, quindi un $ grezzo nel testo apre una formula. Prezzi, prompt della shell e qualunque altra cosa con un simbolo del dollaro isolato vanno scritti come \$.
• Digita il markup in ASCII, anche nel testo cinese e giapponese. Un metodo di input cinese o giapponese produce le forme a larghezza piena: ：：： per un delimitatore, ＃ per un titolo, ［＾1］ per un marcatore di nota, ｛…｝ per gli attributi, ＊＊ per il grassetto. Vengono stampate come testo, e la build segnala la riga con un avviso fullwidthMarkup che indica la forma ASCII da digitare. I valori degli attributi possono essere in qualunque scrittura e tra virgolette “…” o 「…」; le chiavi restano in ASCII.

#Esempio completo

Un breve documento che mette alla prova ogni costrutto supportato:

---
title: The Typesetter's Craft
author: Anon
---
 
# Opening
 
A good book reads itself. The **reader** should never notice the
typesetter's work — only the author's voice.
 
## What makes text readable
 
Three properties matter most:
 
1. Line measure — 40 to 75 characters per line.
2. Leading — 1.3 to 1.5 times the font size.
   a. Tighter at short measures.
   b. Looser at long measures.
3. Contrast between body and headings.
 
Common failure modes include:
 
- Lines that stretch across the whole page.
- Headings that float without a following paragraph.
- Orphans and widows at column boundaries.
 
> Typography is the craft of endowing human language with a durable
> visual form.
> — Robert Bringhurst
 
### Review checklist
 
- [x] Column width under 75 characters
- [x] Leading set to 1.5
- [ ] Orphan and widow pass
- [ ] Final proofread
 
### A note on formulas
 
Inline math such as $a^2 + b^2 = c^2$ flows with the surrounding text, and
display math sits centred on the baseline grid:
 
$$
\int_0^1 x^2\,dx = \tfrac{1}{3}
$$

Lo stesso documento, passato al motore di impaginazione, produce un VDTDocument strutturato le cui pagine contengono ciascuno di questi blocchi come voci tipizzate: vedi la pagina Architettura per capire come i blocchi diventano geometria.