Formato del documento: direttive

#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

Due attributi cambiano ciò che stampa un singolo indice, qualunque cosa dica la configurazione. levels elenca i livelli di titolo che riporta: un intervallo (levels="1-2"), un solo livello (levels="2") o un elenco (levels="1,3"); un livello a cui toc.levels non dà uno stile prende quello del livello più vicino sopra di esso. keep tiene ogni blocco dell’indice in una sola colonna e pagina, come fa toc.groups.keepTogether: keep="part" tiene una riga di parte con i suoi capitoli, keep="1" (fino a "6") un titolo di quel livello con le voci che gli stanno sotto, e keep="none" disattiva il raggruppamento configurato. Un blocco che non entra passa intero alla colonna o alla pagina successiva; uno più alto di una colonna viene tagliato, e la colonna in cui prosegue si apre di nuovo con la sua riga di testa, seguita da una dicitura di continuazione come (segue).

# Contents {style="front-matter" toc="false"}
 
:::toc{keep="part" levels="1-2"}

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

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

#Pagine composte

Una pagina composta si impagina a partire da un modello di pagina della configurazione (pageTemplates), e il suo contenuto viene versato per nome nelle cornici del modello. La guida, con gli avvisi, è Pagine composte.

• ::::page{template="…"} … :::: è la pagina: quattro o più due punti, chiusi da una riga che ne contiene soltanto lo stesso numero. I recinti a tre due punti al suo interno (:::frame, :::callout, :::figure…) funzionano come ovunque, e un ::: da solo non chiude mai la pagina. Un :::page a tre due punti resta una pagina di fumetto.
• :::frame{slot="…" label="…"} … ::: contiene il contenuto della cornice con quel nome: qualsiasi Markdown.
• slot="…" su un titolo (## Retos {slot="retos-titulo"}), su ::resource{id="…" slot="…"}, su un recinto di codice o su un contenitore ::: manda solo quel blocco. Il contenuto senza slot va nella cornice di flusso del modello.
• :::figure{resource="…" slot="…"} … ::: colloca una risorsa con le sue righe ::label[TEXT]{at="…" style="…"}, dove at è un’ancora dell’immagine o un punto "x% y%". Una figura funziona anche nel testo corrente.