Capitolo 3.2 · Parte II · Il mestiere
Configurazione: intestazioni e piè di pagina
Che cosa si stampa in cima e in fondo a ogni pagina: testi con segnaposto, filetti, riquadri, immagini e tracciati vettoriali, diversi per le pagine pari e dispari; e dove si colloca ogni elemento
In breve
Questa pagina riguarda ciò che viene stampato in alto e in basso su ogni pagina. Un’intestazione o un piè di pagina può contenere il numero di pagina, il titolo del libro o del capitolo, una linea, un riquadro o una piccola immagine. Le pagine di sinistra e di destra possono mostrare cose diverse. Ogni elemento può stare a sinistra, al centro o a destra, oppure nel margine accanto al testo. Intestazione e piè di pagina stanno dentro i margini, quindi non rimpiccioliscono mai l’area del testo.
#Intestazioni e piè di pagina
Le proprietà header e footer controllano gli spazi di intestazione e piè di pagina di ogni pagina. Intestazioni e piè di pagina si disegnano dentro i margini esistenti della pagina: non riservano spazio aggiuntivo e non riducono l’area del contenuto.
Area del contenitore. Un elemento ancorato a 'container' si colloca nella fascia di margine tra il testo e il bordo di rifilo, per tutta la larghezza dell’area del contenuto. Il contenitore dell’intestazione va dal bordo superiore di rifilo fino alla sommità del testo; quello del piè di pagina dalla base del testo fino al bordo inferiore di rifilo. Quindi le ancore top-* dell’intestazione e bottom-* del piè di pagina misurano dal bordo di rifilo, mentre le ancore bottom-* dell’intestazione e top-* del piè di pagina misurano dal bordo del testo. Il contenitore non comprende mai l’abbondanza né la fascia dei segni di taglio, quindi un’intestazione o un piè di pagina cade nella stessa posizione sulla pagina rifilata sia con page.cutLines attivo sia disattivato. Per andare oltre la larghezza dell’area del contenuto, o nell’abbondanza, ancora l’elemento a 'page' (il formato rifilato) o a 'bleed'.
Gli spazi usano il modello unificato degli spazi della grafica: ogni elemento ha un placement con un anchor (al contenitore o a un altro elemento tramite #id), un offset facoltativo e una size facoltativa. I vecchi campi piatti align, marginFromBody, marginFromEdge e width: 'full' sono ancora accettati in ingresso e vengono convertiti automaticamente nella nuova forma; la descrizione equivalente nella nuova forma è documentata più sotto.
Ogni spazio contiene un elenco di elementi text, rule, box, image e path (la decorazione di una pagina composta accetta anche i connettori, vedi Configurazione › Pagine composte). L’ordine dell’array è l’ordine di disegno (il primo elemento si disegna per primo, l’ultimo sopra tutti). Questo vale indipendentemente dagli ancoraggi: un elemento può ancorarsi a uno elencato dopo di lui (anchor.to: '#ttl'), così un riquadro di sfondo può venire per primo ed essere comunque posizionato rispetto al testo che gli sta davanti.
Valori predefiniti incorporati. Quando header o footer è undefined, postext applica un valore predefinito incorporato ragionevole invece di uno spazio vuoto:
- Intestazione predefinita:
{title}allineato a destra sulle pagine dispari,{chapterTitle}allineato a sinistra sulle pagine pari e un filetto a tutta larghezza, tutto nel colore principale della tavolozza, Open Sans 8pt/600,marginFromBody16pt(testo) /13pt(filetto). - Piè di pagina predefinito:
{pageNumber}centrato su ogni pagina nel colore principale della tavolozza, Open Sans 8pt/600,marginFromBody16pt.
Per rinunciare ai valori predefiniti incorporati, imposta header: { elements: [] } (o footer: { elements: [] }). Un array elements vuoto ed esplicito viene conservato come «nessun elemento»: solo undefined attiva i valori predefiniti.
| Proprietà | Tipo | Predefinito | Descrizione |
|---|---|---|---|
elements | HeaderFooterElement[] | valori predefiniti incorporati quando è undefined; [] li disattiva | Elenco ordinato di elementi di testo, filetti, riquadri, immagini e tracciati. |
#Elementi di testo
Gli elementi di testo disegnano una stringa modello sostituendo i segnaposto. I segnaposto usano la sintassi {name}; {{ e }} producono parentesi graffe letterali.
I valori predefiniti della tabella qui sotto sono quelli di un elemento di testo che aggiungi tu. L’intestazione e il piè di pagina incorporati descritti più sopra in Valori predefiniti incorporati sono elementi già pronti con valori propri (Open Sans 8pt/600 nel colore principale della tavolozza), non i valori predefiniti dell’elemento.
| Proprietà | Tipo | Predefinito | Descrizione |
|---|---|---|---|
kind | 'text' | — | Discriminante. |
id | string | — | Id stabile, unico all’interno dello spazio. Gli altri elementi vi si ancorano con anchor.to: '#id'. La Sandbox ne assegna uno alla creazione. |
content | string | '' | Stringa modello. Supporta i segnaposto elencati più sotto, più {attr.<key>}, un attributo scritto sulla riga del titolo H1 del capitolo corrente (# Title {author="I. Zango"}). Un attributo mancante si risolve in una stringa vuota senza avviso. Un a capo, o i due caratteri \n scritti nel modello o nel valore di un attributo, inizia sempre una nuova riga, qualunque sia l’overflow. Il testo che un segnaposto copia dal documento (un titolo, un campo del front matter) si stampa come è scritto: lì solo un vero a capo, come un’interruzione nel titolo, inizia una nuova riga. |
align | 'left' | 'center' | 'right' | 'justify' | 'start' | 'end' | 'center' | Allineamento orizzontale delle righe dentro il riquadro dell’elemento. 'justify' allarga gli spazi tra parole di ogni riga spezzata tranne l’ultima di ciascun paragrafo, così la riga riempie il riquadro; le righe accanto a un capolettera riempiono lo spazio accanto a esso. Con hyphenate, anche una parola che non entra nel resto di una riga giustificata viene divisa in sillabe per riempirla. L’ultima riga di un paragrafo, una riga senza spazi da allargare e un testo che non va a capo si compongono allineati a sinistra. Il testo giustificato si impagina paragrafo per paragrafo, quindi le righe vuote tra i paragrafi contano come una. Il canvas e il PDF collocano ogni parola dove l’ha messa l’impaginazione; l’HTML allarga gli spazi con word-spacing. 'start' e 'end' seguono la direction del testo: la destra e la sinistra di un testo da destra a sinistra. 'left' e 'right' sono i lati del riquadro stesso; in una grafica impaginata nel flusso di una pagina da destra a sinistra (una fascia di apertura, la grafica di un titolo) il flusso è speculare, quindi sono il suo inizio e la sua fine, come nel testo. |
direction | 'ltr' | 'rtl' | 'auto' | quella del documento | Direzione di base del testo: dove vanno i suoi caratteri neutri, l’ordine delle sue sequenze in una riga e i lati che 'start' e 'end' indicano. 'auto' legge la prima lettera forte del testo risolto e ricade sulla direction del documento. Le sequenze arabe ed ebraiche si leggono da destra a sinistra qualunque sia la base. Un testo che contiene una lettera araba non riceve mai spaziatura tra lettere (letterSpacing viene ignorato per tutto il testo) e le sue parole non vengono mai divise quando va a capo o viene troncato; una parola più larga del riquadro deborda e viene segnalata come unbreakableWordOverflow. |
parity | 'all' | 'odd' | 'even' | 'all' | Su quali pagine compare l’elemento (parità del numero di pagina: la pagina 1 è dispari). |
pages | 'all' | 'body' | 'opener' | 'part' | 'blank' | 'comic' | 'composed' | 'plate' | 'all' | Su quali ruoli di pagina compare l’elemento, in combinazione con parity. Dopo la collocazione ogni pagina viene classificata come 'blank' (riempimento di parità o di separazione, o nessun contenuto), 'part' (una pagina di parte), 'opener' (il suo primo blocco è un titolo il cui livello occupa tutta la pagina o forza un’interruzione di pagina prima di sé: la prima pagina di un capitolo), 'comic' (una pagina di fumetto, :::page), 'composed' (una pagina composta, o il role indicato dal suo modello) o 'body' (tutto il resto). pages: 'body' nasconde una testatina sulle aperture di capitolo; pages: 'opener' mostra un numero di pagina solo lì. Una pagina che una tavola copre fino al taglio o all'abbondanza (placement.) è 'plate': vi si disegna solo un elemento il cui pages nomina quel ruolo, non quelli con 'all'. |
when, unless | string | — | Testatine e decorazione di un modello di pagina: disegna l’elemento solo in una pagina composta il cui blocco imposta quell’attributo (when), o lo toglie da quella pagina (unless). Li accettano tutti i tipi di elemento. Vedi Disegnato quando la pagina lo dice. Da postext 1.50. |
fontFamily | string | 'EB Garamond' | Famiglia di caratteri. |
figureStyle | FigureStyle | quelle del font | Le cifre dell’elemento: numeri di pagina in 'oldstyle' accanto a un testo in cifre elzeviriane. L’elemento nomina una propria famiglia, quindi le cifre del corpo del testo non gli arrivano. Vedi Stili delle cifre. |
fontSize | Dimension | 8 pt | Corpo del carattere. |
fontWeight | number | 400 | Peso del carattere (100–900). |
italic | boolean | false | Disegna il testo in corsivo. |
color | ColorValue | #000000 | Colore del testo. |
overflow | 'wrap' | 'ellipsis-start' | 'ellipsis-middle' | 'ellipsis-end' | 'clip' | 'wrap' nella grafica dei titoli, delle parti e dei riquadri, altrimenti 'ellipsis-end' | Come il motore tratta il testo che supera la larghezza disponibile dell’elemento. 'wrap' divide la riga in più righe; le varianti con puntini di sospensione tengono ogni riga su una sola riga e la troncano con … all’inizio, al centro o alla fine; 'clip' taglia di netto sul riquadro di delimitazione dell’elemento senza inserire alcun carattere. Gli a capo del contenuto valgono in ogni modalità: le modalità con puntini e con taglio troncano o tagliano ogni riga per conto suo. Un elemento che omette overflow prende il valore predefinito del suo spazio: nella grafica di un titolo (advancedDesign.slot), in una pagina di parte (parts.design, parts.versoDesign) o nel progetto grafico di un riquadro (calloutStyles[].design) va a capo; in una testatina, in un numero di pagina o in una riga di parte dell’indice (toc.parts.design, una riga di altezza fissa) termina con …. Imposta 'wrap' su una testatina che può occupare più righe (un indirizzo), o i puntini su un occhiello che deve restare su una riga in un’apertura. Una riga troncata dai puntini, o tagliata con inchiostro oltre il riquadro, viene segnalata come avviso di contenuto designTextTruncated, una volta per elemento e pagina (una testatina o un numero di pagina, una volta per elemento e capitolo). Una configurazione salvata prima di postext 1.24 (configVersion 9 o precedente) viene letta con 'ellipsis-end' su ogni testo di titolo e di parte che non ne imposta uno, così le sue pagine non si spostano. Un testo con un dropCap va a capo qualunque sia il valore di questo campo; con 'clip' le sue righe vengono comunque tagliate al bordo di un riquadro di altezza fissa. 'ellipsis-end' e 'ellipsis-start' tagliano al confine di una parola (The history of…, non The history of th…) e nessuno spazio o punteggiatura di collegamento (virgola, due punti, trattino, barra, parentesi di apertura) tocca i puntini. Una parola viene tagliata dove serve solo quando il confine, tolta quella punteggiatura, conserverebbe meno della metà di ciò che entra: una sola parola lunga, o un URL (http://exampl…, non http…). Uno spazio non separabile o un trattino non separabile (U+2011, come in MS‑DOS) non è un confine di parola; 'ellipsis-middle' taglia ovunque ma elimina gli spazi accanto ai puntini. Fino a postext 1.4 ogni modalità tagliava all’ultimo carattere che entrava, spazi compresi. |
verticalAlign | 'top' | 'middle' | 'bottom' | 'middle' | Dove sta il testo dentro un riquadro più alto delle sue righe: un placement.size.height fisso, o un riquadro allungato da un vicino ancorato. Quando le righe sono più alte del riquadro (un grande numerale in un riquadro di altezza fissa, un lineHeight stretto), debordano dal lato che l’allineamento lascia libero, come fa l’allineamento flex dei CSS: 'bottom' tiene il piede dell’ultimo riquadro di riga sul piede del riquadro e deborda in alto, 'middle' deborda in misura uguale alle due estremità, 'top' al piede. Fino a postext 1.4 queste righe pendevano sempre dall’alto, qualunque fosse l’allineamento. Un dropCap si sposta con le sue righe (fino a postext 1.4 restava in cima a un riquadro in cui 'middle' o 'bottom' le spostavano in basso). |
lineHeight | number | Dimension | 1.2 | Interlinea delle righe dell’elemento. Un numero è un multiplo di fontSize. È accettata anche una Dimension, come si scrive ogni altra interlinea della configurazione: em / rem è lo stesso multiplo, e una lunghezza assoluta (pt, mm, px…) è la distanza tra le linee di base: { value: 15. imposta un’interlinea di 15,5 pt qualunque sia il corpo. Qualsiasi altro valore (zero, un numero negativo, una dimensione malformata) prende il valore predefinito. Fino a postext 1.4 una Dimension qui rendeva impossibile misurare l’altezza della grafica: un’apertura allora non riservava alcuno spazio, nemmeno il suo minHeight, e il testo scorreva sotto il titolo. |
letterSpacing | Dimension | 0 | Spaziatura tra le lettere (tracking): spazio aggiuntivo avanzato dopo ogni carattere, spazi compresi, esattamente come fa il letter-spacing dei CSS. Le larghezze misurate crescono di conseguenza, così un riquadro a larghezza automatica resta aderente. Non cambia mai i glifi: le legature del carattere restano nel canvas, nell’HTML, nell’EPUB e nel PDF (fino a postext 1.27 canvas e HTML le eliminavano dal testo grafico spaziato, che risultava più largo di quanto misurato). Una sequenza ebraica riceve la spaziatura come il testo latino; solo un testo con lettere arabe no. La spaziatura dopo l’ultimo carattere di una riga è esclusa dal suo allineamento e da un riquadro a larghezza automatica, così un titolo spaziato e centrato è centrato sulle sue lettere, uno allineato a destra termina sul bordo e l’ultima lettera di una riga giustificata raggiunge il bordo (fino a postext 1.4 stavano mezza unità di spaziatura, o una intera, più a sinistra, e un elemento ancorato alla destra di uno spaziato stava un’unità di spaziatura più lontano). Un valore negativo stringe le lettere (un titolo da display a 36 pt prende spesso { value: -0.) e le larghezze si riducono allo stesso modo; canvas, HTML e PDF lo disegnano allo stesso modo (fino a postext 1.4 un valore negativo veniva impostato a 0, senza avviso). |
textTransform | 'none' | 'uppercase' | 'none' | Trasformazione di maiuscole e minuscole applicata al testo risolto, segnaposto compresi: il titolo di una parte composto in maiuscole nell’indice. |
box | ElementBoxStyle | — | Sfondo e bordo facoltativi disegnati dietro il testo: backgroundColor, borderColor, borderWidth, borderRadius e un padding per lato che allarga il riquadro oltre il testo (vedi Elementi riquadro per i campi). |
dropCap | { lines, fontFamily, fontWeight, fontSize, color, gap } | — | Capolettera: la prima lettera composta in grande accanto alle prime lines righe (2 per impostazione predefinita), con carattere, peso e colore propri, a gap dal testo. La lettera poggia sulla linea di base dell’ultima riga che occupa, e fontSize vale per impostazione predefinita il corpo che porta la sua sommità al livello delle maiuscole della prima riga: il corpo del testo più lines − 1 interlinee, considerando le maiuscole pari a 0,72 del corpo di una lettera (un carattere le cui maiuscole sono molto più alte o più basse richiede un fontSize proprio). Un testo con capolettera va a capo qualunque sia il suo overflow; con 'clip' le sue righe vengono comunque tagliate al bordo di un riquadro di altezza fissa. Un color collegato alla tavolozza segue le tavolozze delle parti e delle sezioni come il resto della grafica. Nella grafica di un titolo la lettera non riserva spazio sotto il testo: la parte del suo riquadro di riga sotto la linea di base non spinge in basso il testo. Una lettera che scende sotto la linea di base (una Q o una J in molti caratteri) può allora arrivare nello spazio sotto la grafica: dai al titolo un marginBottom per questo. Fino a postext 1.4 il corpo predefinito rendeva la lettera alta quanto tutti i riquadri di riga che occupa, quindi la sua sommità stava sopra la prima riga; un overflow diverso da 'wrap' eliminava la lettera senza avviso; la tavolozza di una sezione o di una parte lasciava il suo colore invariato; e una lettera profonda quanto il testo accanto poteva spingere il testo una riga di griglia più in basso. Le configurazioni salvate in precedenza mantengono il corpo della 1.4, scritto come fontSize (vedi Pacchetti scritti da postext 1.4 o precedenti). Un capolettera nel testo corrente si imposta invece dagli stili di paragrafo e di titolo (vedi Capilettera), con le altezze delle maiuscole misurate dai caratteri. |
paragraphIndent | Dimension | 0 | Rientro della prima riga di ogni paragrafo dopo il primo. Un a capo nel contenuto, o i due caratteri \n per il testo che viene dal valore di un attributo, separa i paragrafi; più a capo consecutivi contano come uno. |
hyphenate | boolean | false | Quando è true e il testo va a capo (overflow: 'wrap', o un dropCap, che va sempre a capo), le parole lunghe che deborderebbero ancora dopo un normale a capo vengono divise in sillabe (con la lingua di sillabazione attiva del documento) con un trattino morbido nel punto di divisione. In un testo giustificato (align: 'justify') anche una parola che non entra nel resto di una riga viene divisa all’ultima sillaba che entra, per riempire la riga. |
inlineMarks | boolean | false | Legge il testo risolto, valori dei segnaposto compresi, come Markdown in linea: **bold**, *italic*, ^superscript^, ~subscript~. Se disattivato, i marcatori si stampano come sono scritti. Nella grafica di un titolo, {titleText} mantiene allora le sequenze in grassetto, corsivo, apice e pedice del titolo stesso (*Pneumocystis*, CO~2~), con gli altri caratteri protetti in modo che si stampino come sono scritti (da postext 1.19). Vedi Segni in linea e contorni. |
stroke | { width, color?, hollow? } | — | Contorno tracciato intorno alle lettere: width (una Dimension, centrata sui bordi dei glifi), color (predefinito: il colore del testo; un capolettera prende il proprio colore) e hollow (true disegna solo il contorno). Vedi Segni in linea e contorni. |
dotted | { spacing?, size? } | — | Disegna le lettere come file di puntini lungo il centro dei loro tratti, perché un bambino le ripassi: spacing tra due puntini (predefinito 0.1em) e size di un puntino (predefinito 0.05em), entrambi relativi al corpo del testo. L’impaginazione non cambia. Non vale per un testo verticale. Vedi Segni in linea e contorni. |
repeat | { gap?, count? } | — | Compone di nuovo un testo di una riga dopo sé stesso, a distanza gap (predefinito 1em), tante volte intere quante ne entrano nel suo spazio, o al massimo count volte: una fila di copie di una parola da ripassare. Le copie formano una sola riga, allineata in blocco e iniziata dal lato da cui parte la direzione del testo. Un testo che va a capo, uno verticale o uno con capolettera si compone una volta sola. |
writingMode | 'horizontal-tb' | 'vertical-rl' | 'horizontal-tb' | 'vertical-rl' compone il testo dall’alto in basso, le righe da destra a sinistra, i caratteri diritti: una testatina lungo il margine esterno, un titolo verticale accanto a un capitolo orizzontale. Vedi Elementi di testo verticale. |
reserve | boolean | true | Solo per la grafica dei titoli e i progetti grafici dei riquadri: se l’elemento conta nell’altezza che il titolo riserva nel flusso del testo, o nell’altezza della banda del progetto grafico di un riquadro (calloutStyles[].design). false per le decorazioni che possono stare sotto il testo (un sigillo al piede della pagina, una cornice, una fascia laterale). Vedi Altezza riservata. La grafica di intestazioni, piè di pagina e parti lo ignora. |
marginFromBody | Dimension | 6 pt | Distanza assoluta tra il bordo dell’elemento rivolto verso il testo e il bordo del testo. Indipendente dagli altri elementi. Convertito in placement.offset.y. |
marginFromEdge | Dimension | 0 pt | Rientro orizzontale dal bordo del contenuto a cui è allineato. Si applica solo quando align è 'left' o 'right'. Convertito in placement.offset.x. |
placement | ElementPlacement | derivato da align + marginFromBody + marginFromEdge | Collocazione avanzata (vedi più sotto). Quando è impostato, ha la precedenza sui vecchi campi piatti. |
Segnaposto disponibili:
{pageNumber}: numero della pagina corrente, a partire da 1.{totalPages}: numero totale di pagine del documento. In un libro impaginato capitolo per capitolo (la Sandbox,buildBundle) ogni capitolo è un documento, quindi questo è il conteggio del capitolo stesso.{bookTotalPages}: numero totale di pagine dell’intero libro: tutti i capitoli, pagine bianche comprese. Per un documento impaginato da solo è uguale a{totalPages}. Vedi Numero di pagine del libro più sotto.{title},{subtitle},{author},{publishDate}: valori letti dacontent.metadata. I metadati sconosciuti o vuoti producono una stringa vuota (e generano un avviso nella Sandbox).{chapterTitle}: testo dell’H1 più recente sulla pagina corrente o prima di essa. Un H1 il cui stile di titolo impostarunningChapter: false(una tavola, una mappa) viene saltato.{chapterNumber}: il numero di quel capitolo, cioè quello del suo H1 quando il livello o il suo stile di titolo ha unnumberingTemplate, altrimenti il suo ordinale (1,2…). Vuoto per un capitolo senza numero.{chapterTitleAtTop},{chapterNumberAtTop}: titolo e numero del capitolo in vigore in cima alla pagina, che differiscono da{chapterTitle}e{chapterNumber}su una pagina dove un nuovo capitolo inizia sotto altro testo. Vedi Il capitolo in cima alla pagina più sotto.{partTitle},{partNumber}: titolo e numero della parte corrente (la pagina:::partpiù recente sulla pagina corrente o prima di essa; le pagine bianche di parità appena prima di una pagina di parte le appartengono già). Vuoti prima della prima parte.{firstMark.<key>},{lastMark.<key>}: la prima e l’ultima parola guida della pagina: un titolo di un livello (h1–h6) o una voce di uno stile di paragrafo. Vedi Parole guida più sotto.
Numero di pagine del libro
{bookTotalPages} stampa il numero di pagine dell’intero libro, il conteggio che un lettore vede in «pagina 12 di 348». Conta le pagine fisiche, bianche comprese, come {totalPages}, ma su tutti i capitoli:
- Un documento impaginato da solo (
buildDocumentsenzacontinuation) è l’intero libro:{bookTotalPages}è uguale a{totalPages}. buildBundleimpagina il libro, somma le pagine di tutti i capitoli e lo impagina ancora una volta con quel totale, così ogni capitolo stampa lo stesso numero. Il conteggio non sposta mai un’interruzione di pagina, quindi basta un giro in più; una configurazione che non stampa{bookTotalPages}non costa nulla.- La Sandbox passa il totale a ogni capitolo quando le pagine di tutti i capitoli sono note. Fino ad allora, un capitolo stampa le pagine fino alla propria fine. L’esportazione dell’intero libro della scheda PDF conta le pagine che impagina: quando un capitolo ha stampato un altro conteggio, perché le sue pagine non erano ancora note, impagina il libro ancora una volta con il conteggio a cui sono arrivati i capitoli.
- Un host che impagina i capitoli da sé passa il totale come
continuation.bookPageCount(anche al primo capitolo). Senza di esso,{bookTotalPages}conta le pagine fino alla fine del documento (continuation.pageIndexOffsetpiù le sue pagine), il che è corretto solo per l’ultimo capitolo.
footer: {
elements: [{
kind: 'text', id: 'folio', content: '{pageNumber} / {bookTotalPages}',
fontSize: { value: 8, unit: 'pt' },
placement: { anchor: { to: 'container', edge: 'top' }, size: { width: 'auto', height: 'auto' } },
}],
}configUsesPlaceholder(config, 'bookTotalPages') dice a un host se vale la pena calcolare il conteggio.
Parole guida: primo e ultimo segno
Un dizionario stampa nella testatina la prima e l’ultima voce di ogni pagina («Aback – Anchor»); un’opera di consultazione stampa la prima e l’ultima sezione. {firstMark.<key>} e {lastMark.<key>} le stampano. La chiave indica che cosa marca una pagina:
- Da
h1ah6: un titolo di quel livello. Il segno è il suo testo, senza il numero. - L’id di uno stile di paragrafo (
entry): un paragrafo di un contenitore:::paragraphs{style="entry"}. Il segno è la sequenza in grassetto con cui si apre il paragrafo, il lemma, senza la punteggiatura finale:**Aback.** Said of…marcaAback. Un paragrafo che non si apre con testo in grassetto non imposta alcun segno.
{firstMark.<key>} è il primo segno che inizia sulla pagina e {lastMark.<key>} l’ultimo. Una pagina su cui non inizia alcun segno (una voce lunga che continua) stampa per entrambi il segno in vigore, l’ultimo prima di essa. Le pagine prima del primo segno non stampano nulla; in un libro impaginato capitolo per capitolo si tratta del primo segno del capitolo, perché i segni non passano da un capitolo al successivo. Un titolo o un paragrafo diviso tra più pagine marca solo la pagina in cui inizia. La chiave si scrive dopo il punto con lettere, cifre, _ e -, cominciando con una lettera o con _; una chiave sconosciuta non stampa nulla.
:::paragraphs{style="entry"}
**Aback.** Said of the sails when pressed back against the mast.
**Abaft.** Towards the stern, or behind a given point.
:::header: {
elements: [{
kind: 'text', id: 'guide', content: '{firstMark.entry} – {lastMark.entry}',
fontSize: { value: 8, unit: 'pt' },
placement: { anchor: { to: 'container', edge: 'bottom' }, size: { width: 'auto', height: 'auto' } },
}],
}Le parole guida sono testatine: si risolvono negli spazi di intestazione e piè di pagina (compresi header e footer di uno stile di titolo) e non stampano nulla nella grafica dei titoli, delle parti e dell’indice; nella grafica dei titoli e delle parti il pannello Verifiche le segnala come segnaposto sconosciuti. Per mostrare il primo lemma sui verso e l’ultimo sui recto, crea due elementi con parity: 'even' e parity: 'odd'. Un H1 il cui stile di titolo imposta runningChapter: false non imposta alcun segno h1.
Il capitolo in cima alla pagina
{chapterTitle} e {chapterNumber} indicano l’ultimo capitolo iniziato sulla pagina o prima di essa. In un libro i cui capitoli si susseguono senza interruzione di pagina, una pagina che chiude un capitolo e inizia il successivo vicino al piede mostra allora il titolo del nuovo capitolo sopra un testo che appartiene ancora al vecchio. {chapterTitleAtTop} e {chapterNumberAtTop} indicano invece il capitolo in vigore in cima alla pagina, come fanno i romanzi con capitoli consecutivi e molte opere di consultazione:
- una pagina il cui primo blocco è l’H1 di un capitolo indica quel capitolo;
- qualsiasi altra pagina indica il capitolo da cui prosegue, anche quando un nuovo capitolo inizia più in basso;
- una pagina bianca aggiunta per la parità va con la pagina che la segue, e il separatore delle modalità
always-*con la pagina che lo precede (vedi A chi appartengono le pagine bianche); quando la pagina dopo una bianca di parità si apre con la fine di un capitolo e non con il suo H1, anche la bianca resta a quel capitolo; - un H1 con
runningChapter: falseviene saltato.
header: {
elements: [{
kind: 'text', id: 'chapter', content: '{chapterTitleAtTop}', parity: 'odd', pages: 'body',
fontSize: { value: 8, unit: 'pt' },
placement: { anchor: { to: 'container', edge: 'bottom-right' }, size: { width: 'auto', height: 'auto' } },
}],
}Come le parole guida, entrambi sono testatine: si risolvono negli spazi di intestazione e piè di pagina e non stampano nulla nella grafica dei titoli, delle parti e dell’indice. {attr.<key>} legge sempre l’ultimo capitolo iniziato.
Allineamento implicito dal bordo
Quando il placement.anchor.to di un elemento di testo fa riferimento a un altro elemento tramite #id, il bordo di ancoraggio implica un allineamento predefinito del testo per le righe spezzate:
right-ofealign-leftimplicano un testoalign: 'left': le righe spezzate scorrono verso destra a partire dall’ancora.left-ofealign-rightimplicanoalign: 'right': le righe spezzate aderiscono al lato più vicino all’elemento di riferimento.
L’editor dei titoli della Sandbox applica automaticamente questi allineamenti impliciti quando cambi il bordo o l’elemento di ancoraggio. Così il testo su più righe resta visivamente ancorato all’elemento a cui si riferisce (così, per esempio, la «P» di un «Postext» spezzato si allinea verticalmente sotto la «I» di «Introduction»).
Segni in linea e contorni
Un elemento di testo compone il suo testo in un solo carattere per impostazione predefinita: **, ^ e gli altri marcatori Markdown si stampano come sono scritti. Con inlineMarks: true il testo risolto viene letto come Markdown in linea, con gli stessi segni che accetta il testo (vedi Formato del documento → Formattazione in linea):
**bold**imposta il peso 700 (o ilfontWeightdell’elemento stesso quando è più pesante);*italic*inverte l’inclinazione dell’elemento, così l’enfasi dentro un elemento in corsivo risulta in tondo;***both***fa entrambe le cose. Funzionano anche le forme con il trattino basso (__bold__,_italic_).^superscript^e~subscript~si compongono al 58% del corpo, l’apice alzato di un terzo del corpo e il pedice abbassato di 0,15; un pedice e un apice che si toccano (T~0~^2^) vengono impilati, come nel testo.- Una barra rovesciata compone il carattere marcatore stesso (
\*,\_,\^,\~). Un link conserva il suo testo; gli apici inversi del codice vengono eliminati.
I segni si leggono dopo che i segnaposto sono stati riempiti, quindi un valore può contenerli: una riga di autori in un attributo del titolo riceve i numeri di affiliazione come apici. L’a capo, la giustificazione, le modalità con puntini, dropCap e paragraphIndent funzionano tutti sul testo marcato; ogni sequenza conserva il colore dell’elemento.
{ "kind": "text", "id": "authors", "content": "{attr.authors}", "inlineMarks": true, "overflow": "wrap",
"fontSize": { "value": 11, "unit": "pt" },
"placement": { "anchor": { "to": "#title", "edge": "below" }, "offset": { "y": { "value": 6, "unit": "pt" } } } }# Snow cover and river flow {authors="Ana Ruiz^1^, Luis Gil^2^ and Marta Sanz^1,3^"}stroke traccia un contorno intorno alle lettere: width è lo spessore della linea, centrata sui bordi dei glifi (metà cade dentro le lettere, metà fuori; la larghezza misurata del testo non cambia), color vale per impostazione predefinita il colore del testo, e hollow: true lascia le lettere senza riempimento così che si veda solo il contorno: un numero da display a contorno, un titolo che si stacca da una fotografia. Il contorno si dipinge sopra il riempimento, allo stesso modo nel canvas, nell’HTML (-webkit-text-stroke) e nel PDF (modalità di rendering del testo 2, o 1 quando è vuoto).
{ "kind": "text", "id": "year", "content": "1863", "fontFamily": "Bitter", "fontSize": { "value": 120, "unit": "pt" }, "fontWeight": 700,
"color": { "hex": "#1d3557", "model": "hex" },
"stroke": { "width": { "value": 1.5, "unit": "pt" }, "hollow": true },
"placement": { "anchor": { "to": "page", "edge": "bottom-right" }, "offset": { "x": { "value": -15, "unit": "mm" }, "y": { "value": -20, "unit": "mm" } } } }dotted disegna le lettere come file di puntini che un bambino ripassa, l’esercizio di un quaderno di scrittura. Il testo si misura e si colloca come se fosse pieno; il browser lo disegna su un piccolo canvas e i puntini si dispongono lungo il centro di ogni tratto, a distanza spacing, così un corsivo scolastico legato conserva i suoi legamenti e una parola araba le sue forme. Un segno troppo piccolo per una fila (il puntino della i, un accento, un segno vocalico) diventa un solo puntino. Va bene qualunque peso, e il più sottile di una famiglia dà le file più regolari. I puntini prendono il colore del testo e sostituiscono il riempimento e lo stroke. Il canvas, l’HTML (un SVG sopra il testo, lasciato trasparente) e il PDF disegnano gli stessi puntini; il PDF mantiene sotto il testo, invisibile (modalità di rendering del testo 3), così lo si può ancora cercare, copiare e taggare.
repeat compone di nuovo un testo di una riga dopo sé stesso finché il suo spazio è pieno: con {boxText} come contenuto e una larghezza fill, uno stile di riquadro stampa una fila di copie della parola che il riquadro contiene nel Markdown, e cambiando la parola cambiano tutte le copie e i loro puntini.
{ "kind": "text", "id": "copies", "content": "{boxText}", "fontFamily": "Playwrite ES", "fontWeight": 100,
"fontSize": { "value": 20, "unit": "pt" }, "color": { "hex": "#4d5b76", "model": "hex" },
"dotted": { "size": { "value": 0.06, "unit": "em" } },
"repeat": { "gap": { "value": 8, "unit": "mm" } },
"placement": { "anchor": { "to": "container", "edge": "top-left" }, "size": { "width": "fill" } } }Nel PDF le sequenze in grassetto e in corsivo incorporano i caratteri corrispondenti della famiglia dell’elemento, quindi il provider di font deve fornirli.
Valori predefiniti del testo e trappole dell’ancoraggio
Un elemento di testo che scrivi tu parte da questi valori, alcuni dei quali sorprendono:
overflowdipende dallo spazio. Nella grafica di un titolo, in una pagina di parte o nel progetto grafico di un riquadro un titolo lungo va a capo su più righe; in una testatina, in un numero di pagina o in una riga di parte dell’indice un testo troppo largo per il suo spazio viene tagliato a una riga con…. Impostaoverflow: 'wrap'su una testatina che può allungarsi (un indirizzo, una firma) e controlla gli avvisidesignTextTruncatedper i testi tagliati. Un a capo nel contenuto (un fine riga, o\nnel modello o nel valore di un attributo) inizia una nuova riga in ogni modalità; le modalità con puntini tagliano ogni riga per conto suo.alignè'center'everticalAlignè'middle'. Un elemento a larghezza automatica si adatta alla sua riga più lunga, quindi le sue righe sono centrate l’una rispetto all’altra; impostaalign: 'left'per un blocco allineato a sinistra (un elemento a larghezza automatica ancorato a un altro elemento allinea da sé le righe sul lato della sua ancora, vedi sopra).- Il carattere è EB Garamond 8 pt, nero,
lineHeight1.2, qualunque carattere usi il testo corrente. A differenza delle altre interlinee della configurazione, illineHeightdi un testo grafico è di solito un semplice multiplo (1.2); funziona anche unaDimension(vedi sopra).
Un elemento senza placement.size.width (o con 'auto') si dimensiona sul suo testo, ma solo entro lo spazio tra il suo punto di ancoraggio e il bordo del contenitore verso cui cresce: per un’ancora top o bottom, il doppio della distanza dal bordo più vicino. Il suo offset conta. Uno scostamento in direzione opposta a quel bordo non costa nulla: una testatina ancorata top-left con una x negativa (che sporge nel margine sinistro) non perde spazio, perché cresce verso destra. Uno scostamento verso quel bordo riduce lo spazio della stessa misura (il doppio per un’ancora top o bottom), e uno che spinge l’ancora oltre il bordo non ne lascia: un’ancora top-right la cui x è inferiore a meno la larghezza del contenitore, o un’ancora top spostata di lato di più di metà di quella larghezza. Senza spazio, una modalità con puntini non stampa nulla e 'wrap' impila un carattere per riga. Tre vie d’uscita:
- dai all’elemento una
size.widthfissa: le larghezze fisse non vengono mai limitate; - ancoralo a
'page'o a'bleed', così lo spazio è delimitato dalla pagina (o dall’abbondanza); - ancoralo al bordo opposto del contenitore.
Il contenitore di un’intestazione va dal bordo superiore di rifilo fino al testo, e quello di un piè di pagina dal testo fino al bordo inferiore di rifilo: in un’intestazione le ancore top-* misurano dal bordo di rifilo e le ancore bottom-* dal testo, e viceversa in un piè di pagina (vedi Area del contenitore più sopra). Un’intestazione o un piè di pagina non sposta mai il testo e si dipinge sopra di esso, quindi un elemento spinto nell’area del testo copre il testo. Una fascia di apertura, invece, si dipinge sotto il testo; quanto spazio occupa nel flusso è descritto in Altezza riservata.
#Elementi di testo verticale
Un elemento di testo con writingMode: 'vertical-rl' si compone in verticale in uno spazio il cui testo è orizzontale: le testatine e i numeri di pagina di qualsiasi libro, che restano sul foglio, e tutta la grafica di una pagina orizzontale. Si impagina come un testo orizzontale in un proprio sistema di riferimento ruotato di un quarto di giro in senso orario, che poi viene riportato sulla pagina:
- Il suo riquadro resta dove lo mette la collocazione. La sua altezza è la lunghezza di una riga: la imposta
size.height(o'auto', la lunghezza del testo;'fill', fino al bordo del contenitore),size.widthimposta quante righe entrano in larghezza, esize.maxWidthlimita la lunghezza di una riga. aligncolloca le righe lungo il riquadro ('left'in alto),verticalAlignattraverso di esso ('top'a destra, dove sta la prima riga), e il padding di un riquadro resta sul lato per cui è scritto.- I caratteri si misurano e si dipingono come in una pagina verticale: gli Han diritti, un em ciascuno, la punteggiatura nella sua forma verticale, le parole latine di lato, i numeri brevi in una cella (
cjk.uprightDigits). Il canvas, il PDF e l’HTML lo collocano nello stesso rettangolo. - Con
inlineMarks: truei segni di orientamento distinguono una sequenza come nel testo:第:tcy[3.0]回compone 3.0 in una cella,:upright[GDP]mette le lettere diritte una sotto l’altra,:sideways[…]ruota una sequenza; una riga non va mai a capo al loro interno. Un elemento orizzontale li ignora. - Un capolettera non si compone su un elemento verticale.
- Nel flusso di una pagina verticale (un’apertura, una pagina di parte, il titolo di un riquadro) il testo scorre già verso il basso, e lì
writingModenon cambia nulla.
I libri cinesi verticali mettono testatine e numeri di pagina in uno di tre posti (clreq §7.2; JLREQ §2.6 per il giapponese):
| Convenzione | Dove | Come impostarla |
|---|---|---|
| Testa e piede orizzontali | Sopra e sotto la gabbia del testo, come nei libri orizzontali; la più comune. | L’intestazione e il piè di pagina così come sono. |
| Margine esterno (stile 中缝, a Taiwan 邊峰) | Lungo il margine esterno: il titolo del capitolo o del libro a partire da circa quattro caratteri sotto la testa della gabbia del testo, il numero di pagina che termina circa cinque caratteri sopra il suo piede, in numerali cinesi, a circa l’80% del corpo del testo. | Due elementi verticali ancorati a 'outer', più sotto. |
| Angolo esterno al piede | Il numero di pagina al piede della pagina, nell’angolo esterno (le regole di Taiwan per i libri 中式). | Un elemento orizzontale nel piè di pagina in 'bottom-left' con parity: 'odd' e uno in 'bottom-right' con parity: 'even' in un libro rilegato a destra (al contrario in uno rilegato a sinistra). |
Le testatine sul margine esterno, come le aggiunge la Sandbox (Intestazione › Testatine sul taglio (verticali)), qui per un testo a 10 pt (la Sandbox le imposta all’80% del corpo del testo):
{
"page": { "pageNumbering": { "format": "trad-chinese-informal" } },
"header": { "elements": [
{ "kind": "text", "id": "head", "content": "{chapterTitle}", "writingMode": "vertical-rl",
"fontSize": { "value": 8, "unit": "pt" }, "overflow": "clip", "align": "left",
"placement": { "anchor": { "to": "outer", "edge": "top" }, "offset": { "y": { "value": 4, "unit": "em" } } } },
{ "kind": "text", "id": "folio", "content": "{pageNumber}", "writingMode": "vertical-rl",
"fontSize": { "value": 8, "unit": "pt" }, "overflow": "clip", "align": "left",
"placement": { "anchor": { "to": "outer", "edge": "bottom" }, "offset": { "y": { "value": -5, "unit": "em" } } } }
] }
}anchor.to: 'outer' (vedi Collocazione degli elementi) è il margine esterno di ogni pagina, quindi in un libro rilegato a destra (page.binding) i due elementi scendono lungo il bordo sinistro di un recto e il bordo destro di un verso. {pageNumber} si stampa nel formato di numerazione delle pagine: trad-chinese-informal dà 一百零三 a pagina 103, cjk-decimal 一〇三. Le regole di ciascuno spazio valgono ancora: pages: 'body' tiene una testatina lontana dalle aperture di capitolo. Un piccolo ornamento tra testatina e numero di pagina (una coda di pesce ︻, un filetto) è un elemento ordinario ancorato allo stesso margine.
Nel VDT un blocco verticale ha vertical (VDTDesignTextBlock.vertical: la regione, le cifre diritte e l’asse centrale di ogni famiglia); le sue righe sono nel sistema di riferimento ruotato del blocco stesso, xOffset verso il basso a partire dalla sommità del riquadro, baselineY verso sinistra a partire dal suo bordo destro. Una sequenza di una riga marcata ha tcy o orientation, come un segmento del testo corrente.
#Elementi filetto
Gli elementi filetto disegnano una linea: orizzontale attraverso lo spazio, o verticale lungo di esso.
| Proprietà | Tipo | Predefinito | Descrizione |
|---|---|---|---|
kind | 'rule' | — | Discriminante. |
id | string | — | Id stabile, unico all’interno dello spazio, per i riferimenti anchor.to: '#id'. |
direction | 'horizontal' | 'vertical' | 'horizontal' | Un filetto orizzontale corre lungo placement.size.width ('fill' = fino al bordo del contenitore) ed è alto thickness. Un filetto verticale scende lungo placement.size.height ('fill' o non impostato = fino al bordo del contenitore) ed è largo thickness: un divisorio tra una testatina e un numero di pagina. |
color | ColorValue | #000000 | Colore del tratto. |
thickness | Dimension | 0.5 pt | Spessore della linea. Un filetto che lo omette viene disegnato con il valore predefinito (fino a postext 1.4 non disegnava nulla). |
width | Dimension | 'full' | 'full' | 'full' occupa tutta l’area del contenuto; una Dimension limita la linea a una lunghezza fissa posizionata da align. |
align | 'left' | 'center' | 'right' | 'center' | Allineamento quando width non è 'full'. |
marginFromBody | Dimension | 6 pt | Distanza assoluta tra il bordo del filetto rivolto verso il testo e il bordo del testo. Indipendente dagli altri elementi. |
marginFromEdge | Dimension | 0 pt | Rientro orizzontale dal bordo del contenuto a cui è allineato. Si applica solo quando width è una Dimension fissa e align è 'left' o 'right'. |
parity | 'all' | 'odd' | 'even' | 'all' | Su quali pagine compare il filetto. |
pages | 'all' | 'body' | 'opener' | 'part' | 'blank' | 'comic' | 'composed' | 'plate' | 'all' | Ruoli di pagina su cui compare il filetto (vedi il campo pages degli elementi di testo). |
reserve | boolean | true | Solo per la grafica dei titoli: se il filetto conta nell’altezza che il titolo riserva nel flusso del testo (vedi Altezza riservata). |
placement | ElementPlacement | derivato da align + marginFromBody + marginFromEdge | Collocazione avanzata (vedi Collocazione degli elementi). size.width / size.height impostano la lunghezza del filetto; width: 'fill' è il vecchio 'full'. |
#Elementi riquadro
Gli elementi riquadro dipingono un rettangolo arrotondato dentro lo spazio: utile come fondale dietro il testo nelle aperture di capitolo, nelle colonne laterali o nei piè di pagina. Gli elementi riquadro si posizionano esclusivamente tramite il campo placement; non hanno la vecchia forma abbreviata piatta. Riempimento, tratto e raggio degli angoli stanno nell’oggetto annidato style (ElementBoxStyle), come nell’esempio JSON in «Collocazione degli elementi».
| Proprietà | Tipo | Predefinito | Descrizione |
|---|---|---|---|
kind | 'box' | — | Discriminante. |
id | string | — | Id stabile, unico all’interno dello spazio. Gli elementi fratelli vi si ancorano con anchor.to: '#id'. La Sandbox ne assegna uno alla creazione. |
style.backgroundColor | ColorValue | transparent | Colore di riempimento. Imposta transparent per un riquadro con il solo contorno. |
style.borderColor | ColorValue | transparent | Colore del tratto. |
style.borderWidth | Dimension | 0 pt | Spessore del tratto. I tratti si dipingono all’interno del rettangolo di delimitazione del riquadro, così le dimensioni esterne restano costanti: il bordo esterno del tratto corre lungo il bordo del riquadro, e un riquadro arrotondato conserva il suo raggio esterno. Un tratto largo quanto il riquadro lo riempie. Canvas, HTML e PDF lo disegnano allo stesso modo (fino a postext 1.4 il canvas e il PDF centravano il tratto sul bordo, per metà fuori dal riquadro). |
style.borderRadius | Dimension | { topLeft?, topRight?, bottomRight?, bottomLeft? } | 0 pt | Raggio degli angoli. Limitato alla metà del lato più corto al momento del rendering. Da postext 1.48 un oggetto dà a ogni angolo il proprio raggio, e un angolo assente resta vivo: una fascia arrotondata solo sugli angoli superiori. |
style.borderSides | { top?, right?, bottom?, left? } | tutti i lati | Il bordo lato per lato, ciascuno { enabled?, color?, width? } sopra borderColor e borderWidth. Un lato si disegna quando ha un colore e uno spessore, a meno che non dica enabled: false: una fascia con un filetto solo al piede è borderSides: { top: { enabled: false }, right: { enabled: false }, left: { enabled: false } }. Da postext 1.48. |
placement | ElementPlacement | — | Obbligatorio. Vedi «Collocazione degli elementi» più sotto. |
parity | 'all' | 'odd' | 'even' | 'all' | Su quali pagine compare il riquadro. |
pages | 'all' | 'body' | 'opener' | 'part' | 'blank' | 'comic' | 'composed' | 'plate' | 'all' | Ruoli di pagina su cui compare il riquadro (vedi il campo pages degli elementi di testo). |
reserve | boolean | true | Solo per la grafica dei titoli: se il riquadro conta nell’altezza che il titolo riserva nel flusso del testo (vedi Altezza riservata). |
#Elementi immagine
Un elemento image disegna una risorsa bitmap o SVG del documento: il logo di un editore su un frontespizio, un marchio in una testatina. Si dimensiona con il suo placement.size: con uno tra width / height lasciato su 'auto' (il valore predefinito) l’altro lato segue le proporzioni dell’immagine; con entrambi impostati l’immagine viene adattata dentro il riquadro e centrata. Una risorsa mancante o che non è un’immagine non disegna nulla.
{
kind: 'image', id: 'logo', resourceId: 'logo-publisher',
placement: { anchor: { to: 'page', edge: 'top-left' }, offset: { x: { value: 64, unit: 'mm' }, y: { value: 233, unit: 'mm' } }, size: { width: { value: 83, unit: 'mm' }, height: 'auto' } },
}resourceId accetta i segnaposto che accetta il content di un elemento di testo, così un’unica grafica può disegnare un’immagine diversa per ogni titolo. Con resourceId: '{attr.vignette}' in uno stile di titolo, # Chapter I {style="opener" vignette="log"} disegna la risorsa log e # Chapter II {style="opener" vignette="wig"} disegna wig: i capitoli condividono lo stile invece di avere un clone per ogni immagine. Un’intestazione o un piè di pagina legge gli attributi del capitolo della pagina, come fa {attr.<key>} in una testatina, e funzionano anche gli altri segnaposto ('map-{chapterNumber}'). Un id che risulta vuoto, come un titolo senza l’attributo, non disegna nulla. Da postext 1.8.
| Proprietà | Tipo | Predefinito | Descrizione |
|---|---|---|---|
id | string | — | Identificatore stabile; altri elementi possono ancorarvisi come #id. |
resourceId | string | — | Id di una Resource bitmap o SVG del documento. Può contenere segnaposto, tra cui {attr.<key>}, riempiti per ogni titolo, parte, riquadro o pagina. |
decorative | boolean | false | L’immagine è solo decorativa (un ornamento, una fascia): non fornisce testo alternativo all’output nemmeno quando la sua risorsa ne ha uno (vedi più sotto). |
fit | 'contain' | 'cover' | 'contain' | Con width e height impostate: 'contain' fa entrare l’immagine intera nel riquadro, centrata; 'cover' riempie il riquadro e ritaglia ciò che avanza, come una fotografia al vivo. Il ritaglio di 'cover' tiene intera la zona sicura della risorsa (vedi Risorse); se la forma del riquadro non può contenerla, si mostra la finestra più piccola che la contiene e il riquadro resta non riempito in un senso. Ignorato se un lato è 'auto'. Da postext 1.38. Un’immagine che resta dritta nel flusso di una pagina verticale (il disegno di un titolo in un libro verticale) viene ritagliata come la mostra il foglio, da postext 1.39; fino alla 1.38 veniva adattata intera. |
focus | { x: number; y: number } | — | Il punto dell’immagine che il ritaglio 'cover' centra, in frazioni dell’immagine: { x: 0.5, y: 0.3 } per un volto nel terzo superiore. Il ritaglio lascia comunque in vista la zona sicura. Senza di esso i margini intorno alla zona sicura si ritagliano in proporzione alla loro misura, oppure l’immagine si centra. Nella Sandbox il Punto focale dell’editor dell’immagine mostra l’immagine con la parte che il ritaglio conserva riquadrata; un clic sull’immagine, o le frecce, fissano il punto (da postext 1.39). |
placement | ElementPlacement | — | Ancora, scostamento e dimensione (vedi Collocazione degli elementi). Un lato 'fill' arriva fino al bordo del contenitore. |
parity, pages | come sopra | 'all' | Su quali pagine compare l’immagine. |
reserve | boolean | true | Solo per la grafica dei titoli: se l’immagine conta nell’altezza che il titolo riserva nel flusso del testo (vedi Altezza riservata). |
Il backend PDF incorpora la risorsa come una figura (un SVG con un master di stampa usa quello); il visualizzatore HTML la risolve tramite resourceImageUrl.
Un’immagine disegnata dalla grafica conta come contenuto quando la sua risorsa la descrive: l’altText della risorsa, altrimenti la sua didascalia come testo semplice (un chip letto attraverso la sua etichetta, un :ref attraverso il suo text quando ne ha uno), entra nel VDT (VDTDesignImageBlock.altText), diventa l’alt del suo <img> nell’HTML e una Figure con /Alt in un PDF con tag, letta subito dopo il testo della sua grafica (la tavola di un capitolo dopo il titolo del capitolo). Un’immagine la cui risorsa non ha né l’uno né l’altra, e una marcata decorative, è decorazione: alt="" con role="presentation", e un artefatto nel PDF. L’immagine di una testatina o di un piè di pagina si ripete su ogni pagina, quindi è un elemento d’arredo, qualunque cosa indichi la sua risorsa: nessun altText nel VDT, alt="" con role="presentation" nell’HTML, un artefatto della pagina nel PDF.
#Elementi tracciato
Un elemento path disegna una forma vettoriale che un riquadro non sa fare: una barra che arriva al dorso con l’estremità obliqua, un nastro con una tacca, le frecce a chevron accanto a una testatina, la coda di un fumetto su una scheda. Il contorno è un dato di tracciato SVG, scritto per impostazione predefinita in frazioni del riquadro dell’elemento stesso, così la forma si allunga con il riquadro e lo segue quando il riquadro si sposta: un nastro dimensionato a { to: '#title', edge: 'right' } è lungo quanto il titolo in ogni lingua. Lo accetta ogni spazio della grafica: testatine, grafica dei titoli e delle parti, righe delle parti nell’indice, grafica dei riquadri e decorazione di una pagina composta. Da postext 1.48.
{
kind: 'path', id: 'ribbon',
d: 'M0 0 H1 L0.94 0.5 L1 1 H0 Z',
fill: { hex: '#c0392b', model: 'hex' },
placement: { anchor: { to: '#title', edge: 'align-left' }, size: { width: { to: '#title', edge: 'right' }, height: { value: 9, unit: 'mm' } } },
}| Proprietà | Tipo | Predefinito | Descrizione |
|---|---|---|---|
kind, id | 'path', string | — | Discriminante, e un id stabile a cui possono ancorarsi altri elementi. |
d | string | — | Dati di tracciato SVG: M L H V C S Q T A Z, assoluti e relativi, nelle unità di viewBox. Dati che non si possono leggere (manca lo spostamento iniziale, una lettera che non è un comando, un comando senza tutti i suoi numeri) non disegnano nulla e vengono segnalati come unknownConfigValue; il riquadro dell’elemento resta comunque per gli elementi ancorati a esso. |
viewBox | [number, number] | [1, 1] | La larghezza e l’altezza dello spazio in cui è scritto d. Con il valore predefinito, 1 è tutta la larghezza o tutta l’altezza del riquadro. Un tracciato copiato da un disegno conserva qui la dimensione del disegno ([24, 24]). |
preserveAspectRatio | 'none' | 'meet' | 'none' | 'none' allunga il viewBox sul riquadro lungo ciascun asse; 'meet' lo scala in modo uniforme perché entri, centrato: un’icona che non deve deformarsi. |
fill, stroke | ColorValue | riempimento nero | Il riempimento e il contorno. Senza nessuno dei due la forma si riempie di nero, come un tracciato SVG; con il solo stroke non ha riempimento. I colori legati alla tavolozza seguono le tavolozze della pagina e della parte. |
width, dash | Dimension, Dimension[] | 0.5pt, continuo | Lo spessore e lo schema di tratteggio del contorno, lunghezze della pagina che non si allungano con il riquadro, così una forma allungata mantiene una linea uniforme. |
placement | ElementPlacement | — | Collocato e dimensionato come un elemento riquadro (vedi Collocazione degli elementi): un lato non indicato, o 'fill', arriva al bordo del contenitore. |
parity, pages, pin, reserve | come gli elementi riquadro | 'all', false, true | Su quali pagine compare, se resta dove il modello disegna la sua cornice (decorazione di una pagina composta), e se conta per l’altezza riservata di un titolo. |
Un tracciato si disegna come forma vettoriale nel canvas, nel PDF, nel visualizzatore HTML e nell’EPUB a layout fisso, come artefatto di impaginazione in un PDF con tag, e resta fuori dall’EPUB a layout fluido insieme al resto dell’arredo della pagina. Un clic risponde sul suo inchiostro, non sul suo riquadro vuoto. Una chiave che l’elemento non ha è unknownConfigKey. In questa versione i tracciati non si ruotano.
#Collocazione degli elementi
ElementPlacement è il modello di posizionamento unificato usato da ogni tipo di elemento (testo, filetto, riquadro, immagine, tracciato) dentro qualsiasi spazio della grafica: intestazione della pagina, piè di pagina, o spazio della Grafica avanzata di un livello di titolo. Tre informazioni descrivono una collocazione:
interface ElementPlacement {
/** What this element anchors to and which edge of that target. */
anchor: {
to: 'container' | 'page' | 'bleed' | 'outer' | `#${string}`; // container = the slot; page = trim box; bleed = trim box + bleed; outer = the outer margin (header, footer); #id = another element
edge: AnchorEdge;
/** The point along the side `edge` names, on '#id': 'start' | 'center' | 'end' | 0…1. */
at?: 'start' | 'center' | 'end' | number;
};
/** Distance from the anchor point. */
offset?: { x?: Dimension; y?: Dimension };
/** Optional fixed width / height. Width also accepts 'fill' (span the slot).
* `maxWidth` caps an 'auto' width (text): the element still shrink-wraps its
* content, so elements anchored to it stay attached, but a long text wraps or
* ellipsizes there — a running head can reserve room for the label hanging
* off it instead of squeezing that label out. */
size?: { width?: Size; height?: Size; maxWidth?: Size; minHeight?: Size }; // Size: Dimension | 'fill' | 'auto' | { to, edge }
}AnchorEdge accetta:
- Bordi del contenitore (quando
anchor.toè'container','page','bleed'o'outer'):top,top-left,top-right,bottom,bottom-left,bottom-right,left,rightecenter, il centro della cornice. - Bordi relativi a un elemento (quando
anchor.to === '#someId'):right-of,left-of,below,above,align-top,align-bottom,align-left,align-right.
Ogni bordo relativo a un elemento mette un angolo dell’elemento su un angolo dell’elemento a cui si ancora, e offset lo sposta da lì:
right-of: il suo angolo in alto a sinistra sull’angolo in alto a destra dell’elemento di riferimento (accanto, con le sommità allineate);left-of: il suo angolo in alto a destra sull’angolo in alto a sinistra dell’elemento di riferimento;below: il suo angolo in alto a sinistra sull’angolo in basso a sinistra dell’elemento di riferimento (sotto, con i bordi sinistri allineati);above: il suo angolo in basso a sinistra sull’angolo in alto a sinistra dell’elemento di riferimento;align-topealign-left: il suo angolo in alto a sinistra sull’angolo in alto a sinistra dell’elemento di riferimento. I due nomi danno la stessa collocazione: si allineano sia i bordi superiori sia quelli sinistri;align-bottom: il suo angolo in basso a sinistra sull’angolo in basso a sinistra dell’elemento di riferimento;align-right: il suo angolo in alto a destra sull’angolo in alto a destra dell’elemento di riferimento.
Un bordo relativo a un elemento usato con 'container', 'page' o 'bleed', e un bordo del contenitore usato con '#id', vengono letti come l’angolo in alto a sinistra.
Un punto lungo un lato. In un ancoraggio a '#id' (un altro elemento o, in una pagina composta, una cornice o un gruppo), at sceglie un punto lungo il lato indicato dal bordo: 'start', 'center', 'end', oppure una frazione del lato dal suo inizio, da 0 a 1. Lungo il lato l’elemento si centra su quel punto; nell’altro senso il bordo mantiene il suo posto, quindi below con at: 'center' appende una tacca sotto il centro di una cornice e right-of con at: 0.5 mette un segno a metà del suo lato. Un lato orizzontale (top, bottom, below, above, align-top, align-bottom, e gli angoli, letti come il loro lato) comincia dove cominciano le righe della pagina: a destra in una pagina da destra a sinistra. Un lato verticale (left, right, right-of, left-of, align-left, align-right, start, end) comincia in alto. Un numero fuori dall’intervallo da 0 a 1 viene portato all’estremo più vicino; una parola diversa dalle tre viene segnalata come unknownConfigValue e ignorata, come at su 'container', 'page', 'bleed', 'outer' e su center. Da postext 1.48; senza at il bordo mantiene il suo punto, come prima.
{ "kind": "rule", "id": "tick", "direction": "vertical", "placement": { "anchor": { "to": "#card", "edge": "below", "at": "center" }, "size": { "height": { "value": 4, "unit": "mm" } } } }Bordi d’inizio e di fine. top-start, start, bottom-start, top-end, end e bottom-end (con 'container', 'page', 'bleed' o 'outer'), e align-start e align-end (con '#id'), indicano il lato da cui partono le righe della pagina invece di un lato fisso. In una pagina da sinistra a destra top-start è top-left; in una pagina da destra a sinistra, e in una pagina verticale, le cui righe si susseguono da destra, è top-right. Con questi bordi la x dello spostamento va dal lato d’inizio al lato di fine: in una pagina da destra a sinistra una x positiva sposta l’elemento verso sinistra, e l’elemento è lo specchio di quello da sinistra a destra. La decorazione di un modello e le testatine stanno sul foglio, quindi un occhiello scritto top-start resta sopra la cornice del titolo in un’edizione araba come in una italiana. Una cornice sta nel flusso della pagina, già specchiato o ruotato, dove start è sempre la sua sinistra, come left. Nel disegno di un titolo, anch’esso nel flusso, start è left. Nella Sandbox l’elenco Allineamento dell’editor dello slot ha Inizio e Fine, e gli elenchi dei bordi hanno i lati d’inizio e di fine. Da postext 1.39; fino alla 1.38 queste parole valevano top-left.
anchor.to: 'page' ancora l’elemento al formato rifilato (la pagina fisica dopo il taglio) e 'bleed' al formato rifilato allargato di cutLines.bleed su ogni lato (identico al formato rifilato finché i segni di taglio sono disattivati). Entrambi i riquadri diventano anche il riferimento per size: 'fill' e per il limite automatico della larghezza, così una fascia colorata può andare da bordo a bordo indipendentemente dai margini della pagina:
{ "kind": "box", "id": "band", "placement": { "anchor": { "to": "bleed", "edge": "top-left" }, "size": { "width": "fill", "height": { "value": 6, "unit": "cm" } } }, "style": { "backgroundColor": { "hex": "#1d3557", "model": "hex" } } }Una dimensione può anche arrivare fino a un bordo di un altro riquadro: { to, edge }, dove to nomina il riquadro come fa un ancoraggio ('container', 'page', 'bleed', 'outer', o '#id' di un altro elemento e, nella decorazione di una pagina composta, di una cornice o di un gruppo) e edge quale dei suoi bordi, 'top' o 'bottom' per un’altezza, 'left' o 'right' per una larghezza, oppure 'center' per il suo centro su entrambi gli assi (da postext 1.48): una fascia dal bordo sinistro di una cornice fino al centro della cornice accanto, un filetto verticale da sotto una scheda fino al centro della riga sottostante. La lunghezza va dal punto di ancoraggio dell’elemento fino a quel bordo, nel verso in cui l’elemento cresce; un bordo dietro il punto di ancoraggio dà 0, e un bordo dell’altro asse, o un riquadro che non c’è, si legge come 'fill'. Uno sfondo che va dal piede di una fascia fino all’abbondanza resta nel modello e segue la fascia quando questa si sposta. Da postext 1.38:
{ "kind": "box", "id": "ground", "placement": { "anchor": { "to": "#band", "edge": "below" }, "size": { "width": "fill", "height": { "to": "bleed", "edge": "bottom" } } }, "style": { "backgroundColor": { "hex": "#f6efe0", "model": "hex" } } }minHeight (da postext 1.64) è un minimo per un'altezza fissa o per una che arriva fino a un bordo: l'elemento non è mai più basso di così e cresce quando il bordo a cui arriva scende. La fascia di un'apertura di capitolo che arriva a qualche millimetro sotto l'occhiello (una scatola vuota leadPad appesa sotto di esso) mantiene l'altezza del design finché il titolo è breve e cresce con un titolo che occupa più righe; ciò che pende sotto la fascia la segue. Non ha effetto su un'altezza 'auto' o 'fill'.
{ "kind": "box", "id": "band", "placement": { "anchor": { "to": "bleed", "edge": "top-left" }, "size": { "width": "fill", "height": { "to": "#leadPad", "edge": "bottom" }, "minHeight": { "value": 101, "unit": "mm" } } }, "style": { "backgroundColor": { "hex": "#2b4acb", "model": "hex" } } }Con i segni di taglio attivi, tutto ciò che un elemento dipinge oltre il riquadro dell’abbondanza viene tagliato (vedi Segni di taglio).
anchor.to: 'outer' (spazi di intestazione e piè di pagina) ancora l’elemento al margine esterno della pagina: dal bordo della gabbia del testo al bordo di rifilo sul lato opposto al dorso, e dalla testa della gabbia del testo al suo piede. Sta a destra di un recto e a sinistra di un verso in un libro rilegato a sinistra, e al contrario in uno rilegato a destra (page.binding), così un solo elemento serve entrambe le pagine di una doppia pagina: una testatina lungo il margine esterno (vedi Elementi di testo verticale). In qualsiasi altro spazio vale come 'container'. L’offset di un elemento di testo si può scrivere in em, em del suo stesso fontSize: quattro caratteri sotto la testa della gabbia del testo è { "y": { "value": 4, "unit": "em" } }.
Nello spazio della Grafica avanzata di un titolo, gli elementi ancorati alla pagina e all’abbondanza non aumentano l’altezza riservata al titolo a meno che non si estendano sotto il bordo superiore del titolo (una fascia in cima alla pagina sta dietro l’apertura; una fascia che arriva sotto il titolo spinge in basso il testo). Usa advancedDesign.minHeight per riservare comunque un’altezza fissa all’apertura, e reserve: false su un elemento che non deve spingere affatto il testo. Le regole complete sono in Altezza riservata.
Ogni elemento ha un id stabile (assegnato automaticamente dalla Sandbox; puoi anche impostarlo a mano). Gli elementi ancorati ad altri elementi formano un piccolo grafo di dipendenze che il motore risolve prima di misurare, così un elemento può concatenarsi a un altro senza coordinate manuali.
La vecchia forma align + marginFromBody + marginFromEdge viene analizzata in ingresso e riscritta in una collocazione al momento della risoluzione della configurazione, così le configurazioni esistenti continuano a funzionare senza modifiche.