Sandbox: le anteprime

#Area di visualizzazione principale

Il lato destro dell’interfaccia mostra l’output reso. Sono disponibili cinque schede, una per modalità di rendering, in quest’ordine: Canvas, PDF, Folio, HTML ed EPUB 3. Cambiare scheda non rilancia l’impaginazione: lo stesso VDT alimenta ogni backend, quindi il contenuto che vedi è coerente tra le modalità. La scheda Folio viene offerta solo dove il browser ha WebGL2 e lo schermo non è quello di un telefono (vedi Scheda Folio).

Ogni area di visualizzazione esegue la pipeline di impaginazione dentro un Web Worker dedicato (postext/worker). Un hook useLayoutWorker per ogni area di visualizzazione possiede il riferimento al worker, vi invia i font come ArrayBuffer trasferibili, e pilota le build con un annullamento in cui vince l’ultima: un tasto premuto o il trascinamento di un cursore interrompe l’AbortSignal della build precedente prima che parta la successiva, così scrivere velocemente non accoda mai lavoro superato sul thread principale. Smontare un’area di visualizzazione ne elimina il worker e rifiuta ogni build in sospeso. Vedi Configurazione → Eseguire l’impaginazione in un Web Worker per lo schema di integrazione usato qui.

#Scheda Canvas

Rende un’anteprima rasterizzata del documento su un elemento HTML5 <canvas>. Offre una rappresentazione esatta al pixel di come apparirà il documento composto finale, compresi il posizionamento preciso del testo, la disposizione delle colonne e la collocazione delle risorse.

Una barra degli strumenti in cima all’area del canvas offre:

• Controlli dello zoom: ingrandisci e rimpicciolisci (1,25x per passo, intervallo 0,25x–4x). Lo zoom manuale disattiva la modalità di adattamento.
• Modalità di adattamento: adatta alla larghezza della pagina o all’altezza della pagina. Si attivano e disattivano; l’adattamento si ricalcola automaticamente quando la finestra cambia dimensioni.
• Modalità di visualizzazione: pagina singola (una pagina per riga) o doppia pagina (disposizione da libro in cui la prima pagina compare a destra come recto, e le pagine successive sono accoppiate in doppie pagine). Un libro rilegato a destra (page.binding, cinese verticale) mostra le sue doppie pagine al contrario: la pagina 1 da sola a sinistra, poi [3 | 2], [5 | 4]. Su una pagina verticale un clic cade sul carattere sotto il puntatore, e il cursore è una barra di traverso alla colonna.
• Anteprima di stampa (icona Printer): mostra le pagine come verranno stampate, disattivata per impostazione predefinita e ricordata dal browser: ogni colore separato tramite il profilo di output di Preparazione per la stampa e mostrato sul bianco proprio della carta, le grandi aree nere in nero ricco; un PDF forzato in scala di grigi si mostra nel solo inchiostro nero. Solo ciò che si stampa: niente guide a schermo e niente contorni (le segnalazioni del preflight sono in Verifiche). La scheda Folio condivide l’interruttore. Ridipinge le pagine e non le reimpagina mai.

Le pagine vengono rese in modo pigro tramite IntersectionObserver: sul canvas vengono disegnate solo le pagine visibili (più un margine di 200px), il che tiene basso l’uso di memoria della GPU nei documenti lunghi.

#Scheda PDF

Genera un PDF vero del documento corrente tramite il pacchetto postext-pdf e lo mostra in un visualizzatore PDF del browser incorporato. Il PDF viene ricostruito automaticamente al primo montaggio e a ogni rigenerazione successiva, usando lo stesso VDT che alimenta le schede canvas e HTML: così le divisioni in righe, i confini delle pagine e la collocazione delle risorse coincidono pixel per pixel tra i tre backend, fino alla compressione delle righe finali troppo piene che Knuth–Plass accetta di tanto in tanto.

Una barra degli strumenti fluttuante in basso a destra nell’area di visualizzazione offre:

• Rigenera (icona RefreshCw): ricostruisce il PDF dal markdown e dalla configurazione correnti. Utile dopo aver cambiato un’impostazione che non provoca da sola una ricostruzione, o quando i font hanno finito di caricarsi.
• Scarica (icona Download): salva su disco il PDF corrente. Il nome del file deriva dal primo titolo H1 del documento (con document.pdf come ripiego).
• Stampa (icona Printer): apre la finestra di stampa del browser sul visualizzatore PDF incorporato, che nella maggior parte dei browser permette di stampare o di salvare di nuovo come PDF.
• Capitolo corrente / Libro intero (selettore a sinistra della barra delle schede, nei libri con più di un capitolo): rende tutti i capitoli come un unico PDF continuo invece del capitolo attivo che prosegue dopo i precedenti (il comportamento predefinito). Cambiarlo rigenera il PDF. Il canvas ha un selettore tutto suo (vedi Libri e capitoli).

Dietro le quinte la Sandbox usa un helper createPdfFontProvider() che scarica file WOFF2 statici per peso dal CDN jsdelivr di Fontsource, gli stessi file con cui si misurano le sue anteprime, li decomprime in TTF nel browser e passa i byte a pdf-lib tramite renderToPdf. Servono font statici per peso (anziché un unico font variabile) perché il testo in grassetto venga davvero incorporato con il peso grassetto. Vedi Generare PDF per lo stesso schema usato fuori dalla Sandbox.

#Scheda Folio

Mostra il libro come oggetto stampato: le pagine impaginate dal motore, rilegate e aperte su una scrivania, in 3D (postext-folio, three.js). Le pagine sono gli stessi dipinti del canvas, mostrati un texel per pixel, quindi il testo è nitido come nella scheda Canvas; cambia tutto ciò che sta intorno. La carta, la rilegatura, la scrivania e la luce vengono dal gruppo Folio del pannello Grafica (la configurazione folio), e una sequenza :::paper nel testo stampa le sue pagine su un’altra carta (vedi Formato del documento › :::paper).

• Che cosa impagina. La scheda Folio segue il selettore Capitolo corrente / Libro intero del canvas. Un capitolo viene mostrato come parte del suo libro: le pagine prima e dopo vengono contate nello spessore dei due blocchi di pagine, e il capitolo si apre sul suo vero lato della doppia pagina. Un libro rilegato a destra (page.binding: 'right', o un libro verticale) giace a specchio e gira i suoi fogli verso sinistra.
• Girare le pagine. Prendi una pagina per il bordo e trascinala dall’altra parte; lasciala oltre la metà e si gira, prima di quel punto ricade indietro. Un clic su una pagina la gira (la pagina destra in avanti, quella sinistra indietro), e così fanno i pulsanti ‹ › della barra degli strumenti e i tasti freccia, Pag su/giù, Home e Fine quando il libro ha il focus. Ogni foglio si piega secondo la sua carta: la carta bibbia si arrotola stretta, il cartoncino gira con un arco ampio, il cartone e le copertine girano come lastre rigide.
• Salti lunghi. Una pagina a più di dieci pagine di distanza (digitata nel campo della pagina, indicata dal permalink, raggiunta da un link o dal cursore nel pannello Testo) si raggiunge in un solo movimento: il blocco di pagine intermedio si solleva tutto insieme, spesso quanto quelle pagine, e si posa dall’altra parte. Fino a dieci pagine, i fogli girano uno alla volta.
• Guardare intorno al libro. Un trascinamento con il tasto destro fa ruotare la vista intorno al libro, fino a 70° dalla verticale: per vedere il dorso, il taglio esterno o lo spessore del blocco. La vista resta dove la lasci, anche mentre le pagine girano, finché Reimposta la vista non la riporta dolcemente alla vista data dalle impostazioni (Inclinazione e Rotazione). Salva come vista predefinita memorizza in quelle impostazioni la vista così come la vedi, così il libro si apre lì e Reimposta la vista torna a essa.
• Che cosa fa il puntatore. Tre pulsanti nella barra degli strumenti scelgono che cosa fa il tasto sinistro (un dito, una penna) sul libro: Sfoglia le pagine a mano, il predefinito, come sopra; Ruota la vista, lo stesso di un trascinamento con il tasto destro, per un trackpad o un tablet; Seleziona il testo, che funziona come nella scheda Canvas sul libro così come lo si vede, inclinato o ruotato: un clic mette il cursore nel pannello Testo, un trascinamento seleziona, un doppio clic prende una parola, un clic su un link lo segue. La scelta viene ricordata; H, O e S la cambiano quando il libro ha il focus.
• Seguire l’editor. Il cursore e la selezione del pannello Testo vengono disegnati sulle pagine, e restano lì mentre scrivi: la pagina mostra la modifica appena viene reimpaginata. Spostare il cursore nell’editor su una pagina non visibile gira il libro fino a essa.
• Copertine. Con Copertine: una custodia intorno alle pagine il libro è rilegato in una custodia di tela, cartoncino o pelle del colore della copertina. Con Le pagine del documento la prima pagina è la copertina anteriore e l’ultima pagina (quando cade su una pagina sinistra) quella posteriore: il libro resta chiuso finché non si gira la copertina, e girare l’ultimo foglio lo richiude. Un libro spesso si apre con il dorso in piedi tra i due blocchi.
• La barra degli strumenti. Una barra fluttuante come quella del canvas: Ricalcola, Reimposta la vista, Salva come vista predefinita, le tre modalità del puntatore, Anteprima di stampa (la prova del canvas, sul bianco della carta del profilo di output, per cui nel frattempo la tonalità della carta del libro viene messa da parte; lo stesso interruttore del canvas), la puntina, ‹ › e il campo della pagina, che accetta un numero di pagina del libro e gira fino alla sua doppia pagina. La pagina a destra della doppia pagina aperta è quella indicata dal permalink (view=folio&page=N).
• Le impostazioni si applicano subito. Le impostazioni di Folio non fanno parte dell’impaginazione: cambiare la carta, la rilegatura o la luce ridisegna il libro senza reimpaginare alcuna pagina.
• Dove viene offerta. La scheda richiede WebGL2 e uno schermo il cui lato corto sia di almeno 600 px: su un telefono il libro 3D occupa più memoria di quanta il browser ne dia a una scheda, quindi lì la scheda non compare (né in un browser senza WebGL2). In un riquadro più stretto di 560 px il libro mostra una pagina alla volta; il foglio gira comunque sopra il dorso. Quando il sistema chiede movimento ridotto, le doppie pagine cambiano senza girare.
• Video sulla pagina. Un clic sul poster di un video lo riproduce sulla pagina, in qualunque delle tre modalità del puntatore, e l’immagine continua a muoversi mentre il foglio gira e si incurva. Un altro clic lo mette in pausa; avviarne un altro ferma il primo, a meno che non sia attivo Riproduci insieme ad altri video; il video si ferma quando il libro si posa su una doppia pagina che non lo mostra più. Spazio riproduce o mette in pausa il video della doppia pagina aperta. Un video con Riproduzione automatica attiva parte da solo la prima volta che si mostra la sua doppia pagina, con l’audio dopo che hai fatto clic sulla pagina (prima senza audio, e un clic lo riattiva); i due video della guida fanno così. I file caricati e i video a un indirizzo (MP4, HLS) si riproducono in questo modo quando il loro server consente letture tra origini diverse; i video di YouTube e Vimeo girano la pagina come prima (vedi Formato del documento › Video sulle pagine di Folio).
• Alternative testuali. Ogni pagina è disegnata come un’immagine; il suo nome accessibile rimanda alla scheda HTML e al pannello Testo per il suo testo.

#Scheda HTML

Rende l’output di postext dentro un contenitore Shadow DOM, garantendo un isolamento completo degli stili rispetto alla pagina host. Il CSS editoriale (tipografia, spaziature, filetti tra le colonne) viene iniettato dentro la shadow root, così non può essere influenzato dagli stili dell’applicazione circostante né riversarsi in essi.

I link Markdown sono attivi qui e nel PDF (vedi Formato del documento › Link). In questa scheda, un clic su un link apre la sua destinazione in una nuova scheda del browser, così la Sandbox resta aperta; i rimandi :ref saltano comunque all’interno del documento.

Qui i video si riproducono: un video di YouTube o Vimeo nel lettore della piattaforma, un file o un indirizzo nel lettore del browser (uno stream HLS tramite hls.js dove il browser non gestisce HLS da sé), con le opzioni del lettore di Stile video del pannello Grafica e di ogni video. I clic su un lettore vanno al lettore, non all’editor. Con Nel visualizzatore HTML impostato su Locandina, la scheda mostra il poster stampato, con un link al video.

Una barra degli strumenti in cima all’area di visualizzazione offre:

• Controlli del corpo del testo: riduci o ingrandisci il testo corrente conservando ogni misura relativa della configurazione.
• Modalità delle colonne: singola (un’unica colonna alta e scorrevole) o multipla (il numero di colonne la cui larghezza si avvicina di più alla giustezza configurata, con scroll-snap orizzontale tra le pagine). Un documento a due colonne conserva le sue pagine a due colonne, ma il visualizzatore può mostrare un numero dispari di colonne (tre invece di due allargate o quattro strette) quando è la soluzione più vicina; l’ultima appartiene allora alla pagina successiva, visibile per metà. Anche un documento o una sezione in Più colonne viene mostrato in pagine a due colonne: da tre a otto colonne di stampa sarebbero strisce sottilissime alla larghezza dello schermo, quindi il visualizzatore compone il suo testo a due colonne per pagina e ne mostra affiancate tante quante la giustezza consente. Un libro rilegato a destra (page.binding) scorre le sue pagine da destra a sinistra in modalità multipla: il visualizzatore si apre all’estremità destra e la freccia ‹ va alla pagina successiva. Un libro composto in verticale si legge solo in modalità multipla: il pulsante Singola è disattivato, con un tooltip che spiega perché, e la scelta che hai salvato torna con il libro orizzontale successivo.

La geometria delle colonne è guidata dalla sezione Lettore web (HTML) del pannello Grafica (Grafica → Esportazione): maxCharsPerLine imposta la giustezza desiderata in caratteri del font del testo corrente, columnGap la distanza orizzontale tra le colonne in modalità multipla, e optimalLineBreaking attiva o disattiva Knuth–Plass dentro il visualizzatore. Vedi il riferimento della configurazione del visualizzatore HTML e l’esempio di integrazione completo per lo stesso schema usato internamente dalla Sandbox.

#Scheda EPUB 3

Scrive l’intero libro come file EPUB 3 con il pacchetto postext-epub, lo mostra in un lettore dentro la scheda e lo scarica. Il file viene costruito nel browser a partire dalla stessa impaginazione capitolo per capitolo che la scheda PDF usa per Libro intero, quindi i suoi numeri di pagina, le note, i rimandi, l’indice e l’indice analitico sono quelli che stampa il PDF. La scheda non ha il selettore Capitolo corrente / Libro intero, perché un EPUB contiene sempre il libro intero. Al suo posto, a sinistra della barra delle schede, offre la resa (come icone su un telefono).

EPUB 3 ha due rese, indicate dalla proprietà rendition:layout del pacchetto:

• Layout fisso (pre-paginated, spesso chiamato FXL): ogni pagina com’è stampata. Ogni pagina è un documento a sé con le dimensioni della pagina, e il testo sta dove lo mette il PDF, nei font del libro, ma resta testo vero che si può selezionare, cercare e leggere ad alta voce. Le doppie pagine si accoppiano come in stampa, e un libro rilegato a destra (arabo, cinese verticale) gira da destra a sinistra. Conserva la grafica: colonne, elementi flottanti, testatine, aperture, le esatte divisioni in righe. Sceglilo per i libri le cui pagine sono progettate come pagine, come libri illustrati, manuali, cataloghi e riviste, e per i sistemi di lettura con uno schermo grande. Su uno schermo piccolo la pagina viene rimpicciolita, e il lettore deve ingrandirla per leggerla.
• Layout fluido (il predefinito su telefoni e computer, e il predefinito di EPUB): il testo, le figure e le tabelle nell’ordine di lettura, ricomposti dal sistema di lettura per il suo schermo e per il carattere, il corpo e i margini che il lettore sceglie. I paragrafi vengono ricostruiti dalle righe impaginate (i trattini aggiunti a fine riga vengono tolti), le figure e le tabelle seguono il testo che le cita, i riquadri diventano aside, le note a piè di pagina rimandano alle note alla fine di ogni capitolo e viceversa, e i numeri di pagina stampati si conservano come marcatori di pagina. Un foglio di stile derivato dalla grafica dà ai titoli, ai riquadri, alle tabelle e alle didascalie il loro aspetto, ma la geometria della pagina sparisce: niente colonne, niente testatine, niente divisioni in righe fisse. Sceglilo per il testo continuo, come romanzi, saggi e relazioni, e per telefoni e lettori a inchiostro elettronico.

Finché non se ne sceglie uno, la scheda si apre con il layout fisso su un tablet come un iPad, il cui schermo ha spazio per la pagina stampata, e con quello fluido ovunque altrove. La scelta viene ricordata tra una visita e l’altra (postext-sandbox-epub-layout), e cambiarla riscrive subito il file.

• Generazione. L’EPUB viene scritto la prima volta che si apre la scheda e di nuovo quando si preme Ricalcola. Una barra di avanzamento conta i capitoli in impaginazione, poi i passaggi dello scrittore (font, immagini e copertina; le pagine o i capitoli; il pacchetto), e gli screen reader annunciano quando il file è pronto o non è riuscito. Dopo una modifica, una freccia accanto a Ricalcola indica che il file non corrisponde più al testo, come nella scheda PDF. Lasciare la scheda o cambiare la resa ferma una generazione in corso. Un libro lungo richiede qualche secondo, durante il quale la pagina non risponde.
• Che cosa entra nel file. I metadati vengono dal front matter del primo capitolo: title, subtitle, author (un nome o un elenco), publishDate o date, isbn o identifier, publisher, rights e description; la lingua viene dal locale della configurazione. Un libro senza identificatore ne riceve uno ricavato dal progetto (o dal libro di esempio e dalla sua lingua), così ogni EPUB dello stesso libro conserva un’unica identità nella biblioteca di un lettore. Ogni famiglia di font nominata dalla grafica viene incorporata: le porzioni di Google Fonts solo dove il libro stampa caratteri che contengono, le famiglie personalizzate a meno che non siano marcate come non ridistribuibili. Le immagini entrano come sono memorizzate, mai come il master di stampa del PDF; ogni SVG porta le varianti nominate dal suo testo (famiglie personalizzate e famiglie di Google allo stesso modo), tranne le famiglie marcate come non ridistribuibili, che vengono segnalate. I file video entrano sotto media/ e si riproducono nel lettore del sistema di lettura; un file senza i suoi byte si riproduce dal suo indirizzo di produzione, che il pacchetto dichiara come risorsa remota, e un video di YouTube o Vimeo è il suo poster con un link al video. La copertina è l’immagine propria del libro quando è una bitmap larga almeno 600 px, altrimenti la prima pagina resa a 1.600 px di larghezza senza il margine dei segni di taglio.
• Il lettore. La scheda apre il file che ha appena scritto, gli stessi byte che scarichi, non un’anteprima separata. Il layout fisso mostra una pagina, o una doppia pagina quando il riquadro è abbastanza largo, ridimensionata per starci; il libro a layout fluido viene impaginato una schermata alla volta (dall’alto in basso per il cinese verticale), e le sue pagine proseguono da un capitolo al successivo. I link del libro spostano il lettore; i link web e di posta si aprono in una nuova scheda del browser. ← / →, Pag su / Pag giù, Home e Fine girano le pagine, e in un libro da destra a sinistra ← va avanti.
• La barra degli strumenti. Una barra fluttuante come quella della scheda PDF: Ricalcola, la puntina, Scarica l’EPUB con le dimensioni del file (il file prende il nome dal titolo del libro), un pulsante degli avvisi quando lo scrittore ha segnalato qualcosa, Indice (un elenco di salti tratto dall’indice del libro), Aumenta il corpo e Riduci il corpo (solo nel layout fluido, mantenendo la posizione), ‹ › e, in un layout fisso, il campo della pagina. Il campo della pagina conta le pagine nell’ordine di lettura del file, con la copertina come 1; i riquadri nominano ogni pagina con il suo numero stampato.
• Avvisi. Il pulsante degli avvisi elenca ciò che il file non ha potuto portare così come lo ha il libro: un’immagine senza file memorizzato (al suo posto c’è un riquadro vuoto), una famiglia, un peso o uno stile senza variante incorporata (i sistemi di lettura ne sostituiscono una), una famiglia lasciata fuori perché potrebbe non essere ridistribuibile, e tutto ciò che la resa non può esprimere. Gli stessi messaggi vanno nella console del browser.
• Verificare il file. Entrambe le rese della guida e dei libri di esempio superano W3C EPUBCheck 5.4 senza errori né avvisi. Per verificare il tuo libro, scaricalo ed esegui epubcheck book.epub, oppure leggilo in Apple Books, Thorium Reader o Calibre.

Vedi Libri EPUB per scrivere gli stessi file dal tuo codice.