Configurazione: riquadri

#Stili dei riquadri

La proprietà calloutStyles dichiara gli stili di riquadro con nome che un documento applica con un contenitore :::callout{type="…"}: note, suggerimenti, avvertenze, obiettivi di apprendimento, qualsiasi contenuto separato dal testo corrente in un riquadro colorato o bordato. Per impostazione predefinita è incluso uno stile neutro, note (sfondo grigio chiaro, nessun bordo, nessuna fascia, nessuna icona, nessun titolo), così :::callout funziona senza alcuna configurazione; dichiarare calloutStyles sostituisce questo elenco predefinito.

const config: PostextConfig = {
  calloutStyles: [
    { id: 'note', name: 'Note' },
    {
      id: 'objectives',
      name: 'Learning objectives',
      title: 'Objectives',
      stripe: { enabled: true, side: 'left' },
      icon: { kind: 'glyph', glyph: '✓' },
      titleStyle: { textTransform: 'uppercase' },
      lists: { bulletChar: '–' },
    },
    {
      id: 'warning',
      title: 'Warning',
      backgroundEnabled: false,
      border: { enabled: true, color: { hex: '#AA0000', model: 'hex' }, width: { value: 1, unit: 'pt' } },
      borderRadius: { value: 1, unit: 'mm' },
      titleStyle: { color: { hex: '#AA0000', model: 'hex' } },
    },
  ],
};

:::callout{type="objectives"}
- Describe the parts of the lantern.
- Trim the wick at dusk.
:::
 
:::callout{type="warning" title="Do not touch the lens"}
The glass stays hot for an hour after the flame is out.
:::

#Il contenitore :::callout

Una riga :::callout{type="<id>"} apre il riquadro e una riga ::: da sola lo chiude. Il recinto accetta cinque attributi, type (l’id dello stile), title (sostituisce il titolo dello stile), span, placement e columns (sostituiscono i valori dello stile), e il contenuto tra le due righe si impagina dentro il riquadro: un titolo facoltativo, poi i paragrafi, gli elenchi, le citazioni in blocco, le formule o le risorse incorporate, ciascuno composto con la tipografia body / lists dello stile (i titoli mantengono i loro stili consueti). I margini tra i figli si fondono come nel testo corrente; l’interno esce dalla griglia della linea di base, e il flusso vi si riaggancia dopo il riquadro con almeno marginBottom sotto (vince la griglia; il margine è un minimo, la stessa convenzione seguita dalle risorse). Uno stile con snapToGrid: false mantiene invece il marginBottom esatto, e il testo dopo il riquadro resta fuori griglia fino al titolo successivo o alla fine di un elenco. Un titolo subito prima di un riquadro resta unito a esso.

Limiti di questa versione:

• Un riquadro resta intero a meno che il suo stile non imposti keepTogether: false. Quando non sta nello spazio rimanente della colonna passa intero alla colonna o alla pagina successiva, anche uscendo da una colonna vuota che fasce di elementi flottanti o un limite di fascia hanno accorciato, purché una colonna intera possa contenerlo. Un riquadro più alto di una colonna intera si divide invece, come uno divisibile; solo uno che nessun taglio può dividere (una figura o una tabella più alta della colonna, o uno splitMinLines che nessun taglio soddisfa) viene collocato comunque ed eccede; l’impaginazione registra allora un avviso calloutOverflow (VDTDocument.warnings), che la Sandbox elenca. Un gruppo :::columns si taglia come il riquadro che lo contiene, tra le sue sottocolonne (da postext 1.25); resta intero, e può eccedere allo stesso modo, solo con layout.flowColumns: false o dentro un riquadro annidato. Un riquadro divisibile lascia indietro la parte che ci sta (figli interi, o le righe di un paragrafo fino a splitMinLines su ciascun lato; una figura, una tabella o una formula in evidenza da sola basta per un lato) e prosegue in un riquadro senza icona nella colonna o pagina successiva, senza il titolo a meno che lo stile non lo ripeta, e facoltativamente con un segno sotto la parte che lascia (vedi Segni su un riquadro diviso).
• Gli elementi flottanti cedono il passo a un riquadro indivisibile. Quando il blocco subito dopo il richiamo di una figura è un riquadro keepTogether, uno slot che non lascerebbe al riquadro alcuna colonna della fascia corrente in cui finire (la colonna del richiamo o una vuota dopo di essa, che lo conteneva prima dell’elemento flottante) non viene preso: la figura passa al suo slot successivo, di solito la pagina successiva, e il riquadro resta nel flusso, come lo comporrebbe un compositore, invece di spingere il riquadro fuori dalla pagina lasciando la colonna con la sola figura.
• span: 'page' in un’impaginazione a più colonne fa del riquadro un blocco a tutta larghezza: si impagina all’intera larghezza del contenuto e divide la pagina in fasce di colonne; le colonne di testo sopra di esso si chiudono alla linea di taglio, il riquadro prende una propria colonna a tutta larghezza, e sotto di esso si apre una nuova fascia di colonne di testo, così il flusso prosegue sotto il riquadro in ogni colonna. Dove le colonne sono livellate (in cima a una pagina, subito sotto un titolo di apertura span: 'page', subito sotto un altro blocco a tutta larghezza, o subito sotto una fascia di elementi flottanti in testa) il riquadro taglia semplicemente lì. Quando arriva a metà pagina, con le colonne disuguali, si compone come farebbe un compositore: il testo sopra di esso viene tagliato alla stessa altezza in tutte le colonne (il motore ripete il posizionamento con le colonne della fascia accorciate allo stesso numero di righe della griglia, così il testo trabocca naturalmente da una colonna all’altra e tutte le regole su orfane, vedove e tieni con il successivo continuano ad applicarsi), il riquadro occupa tutta la larghezza della pagina, e le colonne riprendono sotto di esso. Il taglio richiede un paio di passaggi di posizionamento in più; quando la linea di taglio non lascerebbe spazio per il riquadro più il minimo di righe di testo per le vedove sotto di esso, o nessuna disposizione funziona dopo alcuni tentativi, il riquadro passa in cima alla pagina successiva. Il testo sopra rispetta il taglio: un paragrafo che non può iniziare nelle poche righe che una colonna sotto una figura conserva sopra di esso passa alla colonna successiva (la figura resta allora sola nella sua colonna), e quando un blocco supererebbe comunque il taglio, il taglio si prende una riga più in basso invece che dove termina quel blocco. Anche un riquadro diviso che apre la fascia viene tagliato lì, così il suo resto non supera mai il taglio. Con headings.balancing.beforeSpan (il valore predefinito) la fascia che lascia viene tagliata livellata dietro di esso, come la fascia di chiusura di un capitolo, e, quando lo stile consente la divisione (keepTogether: false), la parte del riquadro che sta sotto le colonne livellate chiude la pagina e il resto apre la successiva; con beforeSpan: false la pagina che lascia viene semplicemente bilanciata come al solito, senza forzare un’interruzione di pagina. Un titolo subito prima di un blocco a tutta larghezza non viaggia con esso. Nelle impaginazioni a una colonna span: 'page' è semplicemente in linea.
• placement: 'fixed' toglie il riquadro dal flusso: viene impaginato (width: 'auto' si adatta al titolo; 'fill' prende la larghezza della colonna di testo sotto il punto di ancoraggio) e fissato alla pagina in cui compare nel flusso, nella posizione descritta da fixed.anchor / fixed.offset (per impostazione predefinita l’angolo inferiore sinistro dell’area del contenuto). Le colonne di testo che copre cedono quella zona (tagliate dal basso, o dall’alto quando la colonna è ancora vuota), esattamente come una fascia di elementi flottanti; quando la zona contiene già testo, un elemento flottante o un blocco a tutta larghezza, il riquadro passa alla pagina successiva. Un riquadro fisso che chiude il capitolo (il blocco successivo è un’apertura di capitolo, un :::part, un riquadro barriera o la fine del documento) livella prima le colonne sopra di esso (headings.balancing.trailing), così una breve pagina di chiusura termina livellata con l’etichetta sottostante. La cornice e i figli vivono in page.floats e si disegnano fuori dal ritaglio delle colonne in ogni backend.
• placement: 'top' | 'bottom' fa flottare il riquadro come una risorsa: esce dal flusso nel punto in cui compare e prende la prima fascia libera dopo quel punto (il piede della pagina corrente, con 'bottom', o la testa / il piede della pagina successiva che il flusso apre) alla larghezza della colonna (span: 'column') o all’intera larghezza del contenuto (span: 'page'); il testo che lo segue riempie la pagina che ha lasciato. La sua cornice e i suoi figli vanno in page.floats, come per un riquadro fisso. Un riquadro flottante in testa a una pagina nuova si colloca prima delle figure in attesa di quella pagina, e una figura citata in una pagina precedente che ci sta poi sotto di esso prende il resto di quella pagina anche quando resterebbero meno di tre righe di testo (una pagina da galleria: riquadro più figura, senza testo in mezzo). Un riquadro span: 'side' non flotta mai: si impila accanto al testo qualunque sia il suo posizionamento. Con columns superiore a 1 (nello stile o come attributo del recinto, da postext 1.18) un riquadro span: 'column' occupa altrettante colonne adiacenti: la testa di una serie di colonne vuote che iniziano alla stessa altezza, o il piede della colonna corrente e di quelle vuote che la seguono, come in :::callout{placement="top" columns="2"}.
• width: 'auto' si adatta solo al titolo; i figli vengono ignorati.
• Un :::callout annidato dentro un altro riquadro è un riquadro a sé: si impagina con il proprio stile (sfondo, bordo, raggio, spaziatura interna, fascia, titolo, icona, segno, linguetta, tipografia) all’intera larghezza interna del genitore e si impila come uno dei suoi figli, con marginTop / marginBottom che si fondono con quelli dei vicini. I suoi span e placement (del recinto o dello stile) vengono ignorati, perché un riquadro annidato scorre sempre dentro il genitore, e così floatBarrier e snapToGrid. I riquadri si annidano a qualsiasi profondità e possono stare dentro un gruppo :::columns (ciascuno intero, in una colonna). Quando il genitore si divide, il taglio cade prima o dopo un riquadro annidato, o al suo interno quando lo stile annidato consente la divisione; ogni frammento ridisegna le cornici che attraversa, e un riquadro annidato che continua dal frammento precedente perde il titolo e l’icona, come una continuazione di primo livello.
• Un gruppo :::columns{count=N} … ::: tra i figli impagina quei figli in N colonne di uguale larghezza, a distanza columnGap, dentro il riquadro: la sequenza si taglia ai confini di blocco o di riga che livellano meglio le colonne (un paragrafo o un elemento di elenco tagliato a metà prosegue in testa alla colonna successiva senza il suo punto elenco), ogni colonna inizia alla sommità del gruppo e il gruppo è alto quanto la sua colonna più alta; i figli successivi tornano all’intera larghezza. Un riquadro che si divide (keepTogether: false, o più alto di una colonna) taglia anche dentro un gruppo, tra le sue colonne: un gruppo a serpentina riempie a turno le sue colonne e prosegue nel frammento successivo, uno parallelo (breaks) prosegue flusso per flusso (da postext 1.25; vedi Formato del documento › :::columns). Un gap sul recinto sostituisce columnGap per quel gruppo, e rule traccia un filetto lungo ogni intercolonna. Usalo per un riepilogo dei punti chiave su due colonne, o per affiancare le tabelle di un riquadro largo.
• Il sesto attributo del recinto, label, si stampa sulla linguetta dello stile (vedi label sopra): :::callout{type="box" label="BOX 1-1" title="The octet rule"}; senza uno stile label l’attributo viene ignorato.

Nel VDT il riquadro è un blocco cornice type: 'callout' la cui decorazione (sfondo, fascia, icona, titolo) vive in designOverlay, seguito dai suoi blocchi figli nella stessa colonna; la cornice e ogni figlio portano il containerId del recinto. Un riquadro annidato è una cornice type: 'callout' a sé tra i figli, seguita dai suoi blocchi; questi mantengono il containerId del recinto di primo livello (il posizionamento e il bilanciamento continuano a vedere un’unica unità) e aggiungono calloutPath, gli id dei contenitori dei recinti annidati che li circondano, dal più esterno (l’id proprio di una cornice annidata è l’ultima voce). Il PDF con tag dà a ogni riquadro annidato un Div dentro quello del genitore. Le immagini delle icone si risolvono come le immagini delle risorse: il registro delle immagini del canvas, l’opzione HTML resourceImageUrl e il provider PDF resourceBytes.

const resolved = resolveCalloutStylesConfig(config.calloutStyles, resolvedBodyText, resolvedHeadings, resolvedUnorderedLists, config.locale);
// => every inherited field filled from the resolved sections; the optional
//    locale picks the language of the continuation strings
 
const minimal  = stripCalloutStylesDefaults(config.calloutStyles);
// => undefined for the built-in `note` default; static defaults dropped

#Enunciati numerati e dimostrazioni

Uno stile con numbering conta i suoi riquadri, come amsthm di LaTeX conta gli ambienti teorema (da postext 1.19). Ogni riquadro stampa la sua etichetta e il suo numero («Theorem 2.» in apertura del suo primo paragrafo) e il title del recinto segue il numero tra parentesi: :::callout{type="theorem" title="Bradley–Terry"} si apre con «Theorem 2 (Bradley–Terry).». Un riquadro aperto con un identificatore ({#thm:main}) è una destinazione dei rimandi, che stampano «Theorem 2» (:ref{id="thm:main"}), e \ref{thm:main} o style=number stampa 2.

Una dimostrazione è uno stile con un’etichetta non numerata e un segno finale:

calloutStyles: [
  { id: 'theorem', numbering: { label: 'Theorem' }, body: { italic: true } },
  { id: 'lemma', numbering: { label: 'Lemma', counter: 'theorem' }, body: { italic: true } },
  { id: 'definition', numbering: { label: 'Definition' } },
  { id: 'proof', backgroundEnabled: false, endMark: '□',
    numbering: { label: 'Proof', counter: false, bold: false, italic: true } },
]

In un libro impaginato capitolo per capitolo i contatori proseguono dal capitolo precedente (LayoutContinuation.statementCounters, che continuationAfter compila), e la struttura del libro assegna all’ancora di ogni riquadro numerato la sua etichetta (OutlineEntry.numberLabel), così un rimando da un altro capitolo la stampa.

#Tipografia dentro un riquadro

Un riquadro compone il suo contenuto con la propria tipografia body e lists; tutto il resto mantiene gli stili del documento:

• I paragrafi prendono il body del riquadro: carattere, dimensione, interlinea, colore, colori dell’enfasi, pesi, italic, smallCaps, allineamento, sillabazione, rientro e spaziatura tra paragrafi. Un campo non impostato eredita da bodyText. Un colore dell’enfasi ereditato mantiene il suo collegamento alla tavolozza, quindi grassetto, corsivo ed etichette :ref in un riquadro cambiano con colorPalette come fanno fuori da esso. (Fino a postext 1.4 il grassetto in un riquadro restava #295AA3 qualunque fosse il colore principale.)
• Gli elenchi puntati prendono il lists del riquadro (carattere del punto elenco, colore, dimensione e peso del glifo, rientro, spazio, spaziatura tra gli elementi) al posto di unorderedLists, e il loro testo è il testo del riquadro. Un lists.bulletChar o lists.color diverso da quello del documento (unorderedLists) sostituisce il punto elenco o il colore di ogni livello; uno che lo ripete, o che resta non impostato, lascia a ogni livello il proprio (unorderedLists.levels), così i trattini annidati sopravvivono nel riquadro.
• Gli elenchi ordinati prendono lists.indent, gap e itemSpacing, e lists.color ogni volta che lo stile lo imposta, anche quando è il colore del punto elenco del documento; uno stile che lo lascia non impostato mantiene i numeri in orderedLists.color. (Fino a postext 1.4 il colore arrivava ai numeri solo quando era diverso da unorderedLists.color, quindi impostarlo proprio su quel colore non faceva nulla.) Il numero stesso (il suo carattere, la sua dimensione e il suo separatore) viene dall’orderedLists globale, perché lists ha solo campi per i punti elenco: definisci lì lo stile dei numeri di un riquadro.
• I :::paragraphs dentro un riquadro usano il loro stile di paragrafo, anche nei riquadri annidati. I campi che lo stile lascia non impostati ereditano dal bodyText del documento, non dal body del riquadro (né dal suo corsivo o dal suo maiuscoletto).
• I gruppi :::columns non hanno uno stile proprio: ogni colonna condivide la tipografia del testo e degli elenchi del riquadro, e columnGap imposta lo spazio tra di esse.
• Le citazioni in blocco prendono il carattere, la dimensione e i pesi del testo del riquadro (corsivo e grigio, come nel testo corrente), e il suo maiuscoletto. I titoli mantengono gli stili dei titoli; le formule in evidenza le impostazioni delle formule.
• Le figure e le tabelle mantengono gli stili delle didascalie e delle tabelle del documento, alla larghezza interna del riquadro; i loro pesi normale e grassetto seguono i pesi del body del riquadro.
• I chip mantengono il loro stile di chip; una dimensione in em si legge rispetto al corpo del testo del riquadro.
• :::space si misura in righe del testo del riquadro (vedi :::space per i casi in cui viene scartato).
• Un riquadro annidato prende per intero il proprio stile; i suoi span, placement, floatBarrier e snapToGrid vengono ignorati.

#Segni su un riquadro diviso

Quando un riquadro si divide tra colonne o pagine (keepTogether: false, o un riquadro più alto di una colonna), ogni parte dopo la prima si apre senza il titolo e l’icona, e per impostazione predefinita nulla dice al lettore che il riquadro prosegue. Due opzioni aggiungono i segni che usano un libro o una sceneggiatura:

• repeatTitle: true ripete il titolo in testa a ogni continuazione, seguito da continuedSuffix, per impostazione predefinita «Key points (cont.)». La ripetizione prende lo stile del titolo, quindi con textTransform: 'uppercase' dà il «HAMLET (CONT'D)» di una sceneggiatura. L’icona e la linguetta restano sulla prima parte.
• continuesMarkerEnabled: true colloca continuesMarker («Continued», o «Continúa» in un documento spagnolo) sotto l’ultima riga di ogni parte che prosegue, dentro il riquadro, nel carattere e nel corpo del testo del riquadro: in corsivo a meno che continuesMarkerItalic non sia false, allineato a destra a meno che continuesMarkerAlign non indichi 'left' o 'center'. Il segno occupa spazio nella parte che chiude, e il taglio viene scelto in modo che ci stia.

calloutStyles: [{
  id: 'speech',
  keepTogether: false,
  titleStyle: { textTransform: 'uppercase' },
  repeatTitle: true,
  continuedSuffix: "(CONT'D)",
  continuesMarkerEnabled: true,
  continuesMarker: '(MORE)',
  continuesMarkerAlign: 'center',
  continuesMarkerItalic: false,
}],

:::callout{type="speech" title="Hamlet"}
A speech long enough to run over the foot of the page…
:::

La parte che chiude la pagina termina con «(MORE)», e la pagina successiva si apre con «HAMLET (CONT'D)». Entrambi sono elementi di servizio dell’impaginazione: in un PDF accessibile sono artefatti e nell’HTML sono nascosti alle tecnologie assistive, così il titolo si legge una sola volta. Nel VDT sono blocchi di testo designOverlay contrassegnati artifact: true.