PortLab

Un diagramma è una struttura, non un disegno

Uno schema di architettura come quelli che compaiono nelle pagine tecniche di questo sito non è un disegno libero: è una gerarchia — livelli, riquadri, riquadri dentro i riquadri — più un insieme di relazioni, le frecce. Chi lo costruisce trascinando rettangoli in un programma di grafica sta ridisegnando ogni volta, a mano, una struttura che il calcolatore saprebbe disporre da solo; e paga quel lavoro due volte, perché al primo testo che cambia le coordinate non tornano più.

Qui la scelta è l'opposta: si descrive la struttura, e la disposizione la calcola il programma. Le conseguenze pratiche sono tre, e sono il motivo per cui vale la pena scrivere un motore invece di aprire Inkscape.

• Si rigenera identico. Cambiare una parola sposta quel riquadro e riallinea tutto il resto, senza toccare nient'altro.
• Si traduce. Un diagramma in italiano e uno in inglese sono lo stesso file con le stringhe cambiate: la geometria si ricalcola, e il riquadro inglese, più corto, si stringe da solo.
• Si collauda. L'uscita è una stringa di testo, quindi si può verificare senza browser. La suite headless node-tools/test/portlab/diagramma_test.js controlla che nessun testo sbordi dal suo riquadro, che i livelli non si sovrappongano, che una freccia fra due riquadri incolonnati sia davvero verticale.

La disposizione: misurare, poi posizionare

Il motore fa due passate, che sono poi le due di ogni sistema di impaginazione, da TeX ai motori CSS. Nella prima, dal basso verso l'alto, ogni elemento dichiara quanto spazio gli serve come minimo: i suoi testi, più i figli disposti nella direzione richiesta, più il margine interno. Un contenitore non sa ancora dove finirà, sa solo quanto gli occorre. Nella seconda, dall'alto verso il basso, a ogni elemento viene assegnato un rettangolo, che è sempre grande almeno quanto il suo minimo; lo spazio in più si distribuisce ai figli.

Come si distribuisce è il solo parametro interessante. Senza Occupa tutta la larghezza lo spazio in eccesso resta ai bordi e il gruppo si allinea; con quell'opzione si spartisce fra i riquadri in proporzione alla loro larghezza naturale, così la riga arriva esattamente ai margini e le proporzioni fra i riquadri restano quelle dettate dai testi. È la glue di Knuth: spazio elastico che si allunga in proporzione a quanto è disposto a cedere.

Il diagramma intero è a sua volta un elemento — un contenitore verticale senza riquadro — e ogni livello è un contenitore orizzontale senza riquadro. Non esiste un caso particolare per il primo livello: la ricorsione è una sola e vale anche per la radice. È una scelta che si paga subito con un accorgimento: quel "senza riquadro, senza margine interno" è una proprietà dei contenitori di disposizione e non deve scendere per eredità, altrimenti azzera il margine interno di tutti i riquadri sottostanti e i testi vanno a toccare i bordi. Il motore tiene perciò due stili distinti per ogni nodo, quello proprio e quello che eredita.

Le frecce: attacchi e piste

Una freccia automatica esce dal centro del lato che guarda l'altro elemento ed entra dal centro del lato opposto: è il punto in cui l'occhio la cerca, e resta giusto quando un riquadro cambia larghezza. Se più frecce toccano lo stesso lato, i loro attacchi si raccolgono attorno al centro in ordine di dove sta l'altro capo, così vicino al riquadro non si incrociano. Se i due attacchi non sono allineati, la freccia fa un gomito nello spazio vuoto fra i due elementi.

Il problema vero comincia quando più gomiti attraversano lo stesso spazio. Con i tratti trasversali tutti alla stessa quota, dove due tratti si sovrappongono non si distingue più quale freccia va dove. Nell'instradamento dei circuiti è un problema noto da mezzo secolo, il channel routing: ogni tratto ha la sua pista, e le piste si riempiono con l'algoritmo del bordo sinistro di Hashimoto e Stevens. L'ordine delle piste non è libero. Se la coda con cui una freccia scende nel suo riquadro cade sotto il tratto di un'altra, l'altra deve correre più in alto, o la taglia. I vincoli si ordinano con l'ordinamento topologico di Kahn, e un ciclo di vincoli è un incrocio che nessun ordine può evitare. Nei diagrammi lo stesso passo si chiama nudging, ed è l'ultima fase dell'instradamento ortogonale dei connettori di Wybrow, Marriott e Stuckey.

Resta un caso che nessun ordine risolve: due frecce che si scambiano di posto fra colonne allineate, con la partenza dell'una proprio sopra l'arrivo dell'altra. Lì l'incrocio è inevitabile, e il motore sposta l'arrivo di mezzo passo perché le due frecce non abbiano un pezzo di coda in comune.

Perché non Graphviz, perché non Mermaid

Esistono strumenti eccellenti che disegnano grafi a livelli: l'algoritmo di riferimento è quello di Sugiyama, Tagawa e Toda (1981), che assegna i nodi ai livelli, riordina per ridurre gli incroci e poi assegna le coordinate; dot di Graphviz ne è l'implementazione classica, descritta da Gansner e North (2000). Mermaid, che molti conoscono dai file Markdown, lavora nello stesso spirito.

Quegli strumenti però possiedono la disposizione: si dichiarano i nodi e gli archi, e il risultato è quello che l'algoritmo ritiene migliore. Per una figura da pubblicare serve l'opposto — decidere quali riquadri stanno sulla stessa riga, quanto è grande il raggio dei vertici, che il geodatabase sia una fascia unica con dentro le sue tabelle. Qui i livelli li dichiara l'autore, e il motore si limita a misurare e allineare. Il prezzo è che il programma non evita gli incroci al posto nostro; il guadagno è che la figura esce come la si era pensata.

Perché l'uscita è SVG

Un diagramma è testo e linee: in SVG resta vettoriale a ogni ingrandimento, il testo si può selezionare e cercare dentro il file, e chi vuole ritoccarlo lo apre in Inkscape senza perdere nulla. Un canvas avrebbe dato subito dei pixel, e con essi il problema di scegliere una risoluzione prima ancora di sapere dove finirà la figura.

Il PNG si ottiene poi dall'SVG, disegnandolo su un canvas ingrandito del rapporto fra i dpi richiesti e i 96 convenzionali dello schermo: essendo la sorgente vettoriale, l'ingrandimento non sgrana. Due trappole vanno però disinnescate di proposito, perché nessuna delle due dà errore.

• I caratteri. Un SVG caricato come immagine è un documento isolato: non vede i @font-face della pagina che lo ha generato e non ha il permesso di scaricare nulla. Senza precauzioni il PNG uscirebbe con un carattere di ripiego — e senza dirlo. Perciò, al momento dell'esportazione, i file woff2 delle sole famiglie effettivamente usate vengono letti, codificati in base64 e incorporati nel disegno. I caratteri sono ospitati sul server (fonts/common/), quindi l'operazione non esce mai dal sito.
• La risoluzione dichiarata. Un PNG prodotto da un canvas non contiene il chunk pHYs, e un PNG senza pHYs viene letto a 96 dpi: un'immagine generata a 300 dpi, inserita in un documento, comparirebbe larga il triplo del dovuto, e l'utente la rimpicciolirebbe a mano vanificando il campo dei dpi. Il chunk lo scriviamo noi, con il proprio CRC-32; la specifica chiede che pHYs preceda il primo IDAT, e metterlo subito dopo IHDR lo garantisce sempre. Così l'immagine si impagina alla dimensione fisica giusta in Word e in LibreOffice.

Quanto è larga una scritta

La larghezza di una stringa la conosce solo il motore di rendering che la disegnerà: dipende dal font, dal corpo, dalle crenature. Nel browser la si chiede al canvas (measureText), e i riquadri stanno addosso al testo al pixel. Ne segue una conseguenza operativa poco ovvia: il primo disegno deve aspettare che i caratteri siano stati scaricati, perché misurare con un carattere di ripiego produrrebbe un impaginato sbagliato che poi non si corregge più da solo.

Fuori dal browser — nei test, o se un giorno si generassero figure sul server — il motore ricade su una stima per classe di carattere: caratteri stretti, cifre, maiuscole, lettere larghe, minuscole ordinarie. I coefficienti non sono inventati: sono i minimi quadrati su quindici stringhe misurate col canvas in Arial a 13 px, con errore tipico sotto l'1% e massimo del 4,5% su una stringa di sole maiuscole. Un fattore di sicurezza del 3% fa preferire un riquadro un filo largo a un testo che sborda: il primo è un difetto estetico, il secondo si vede.

Quello che questa pagina non ha scritto

Il motore del testo di questa pagina — la misura calibrata, l'interprete dei tag in linea, il disegno dei <tspan> — è esposto da diagramma.js e lo usa anche l'editor dei diagrammi di flusso, che per il resto ha un motore completamente diverso. Lo stesso per l'impalcatura: annullamento, copia di scorta, esportazione, zoom e tavolozza non sanno che cosa sia un diagramma e stanno in js/common/editor_svg.js. Sono cose delicate, e una correzione fatta una volta deve valere per entrambi i disegni.

Bibliografia

• K. Sugiyama, S. Tagawa, M. Toda, Methods for visual understanding of hierarchical system structures, IEEE Transactions on Systems, Man, and Cybernetics 11(2), 109–125, 1981. DOI 10.1109/TSMC.1981.4308636
• E. R. Gansner, S. C. North, An open graph visualization system and its applications to software engineering, Software: Practice and Experience 30(11), 1203–1233, 2000. DOI 10.1002/1097-024X(200009)30:11<1203::AID-SPE338>3.0.CO;2-N
• D. E. Knuth, The TeXbook, Addison-Wesley, 1984 — capitolo 12, Glue: il modello di scatole e spazio elastico da cui discendono tutti i motori di impaginazione successivi.
• A. Hashimoto, J. Stevens, Wire routing by optimizing channel assignment within large apertures, Proceedings of the 8th Design Automation Workshop (DAC '71), 155–169, 1971. DOI 10.1145/800158.805069
• A. B. Kahn, Topological sorting of large networks, Communications of the ACM 5(11), 558–562, 1962. DOI 10.1145/368996.369025
• M. Wybrow, K. Marriott, P. J. Stuckey, Orthogonal connector routing, Graph Drawing 2009, LNCS 5849, 219–231, Springer, 2010. DOI 10.1007/978-3-642-11805-0_22
• ISO/IEC 15948:2004, Portable Network Graphics (PNG): Functional specification — la struttura a chunk, il loro CRC-32 e il chunk pHYs delle dimensioni fisiche.
• W3C, Scalable Vector Graphics (SVG) 2, Candidate Recommendation. www.w3.org/TR/SVG2/

A che serve

A costruire schemi a blocchi — architetture, flussi di elaborazione, organigrammi — e a portarseli via come SVG (vettoriale, da ritoccare o da inserire in una pagina) o come PNG a una risoluzione scelta. Il diagramma si salva come file JSON e si riapre quando serve: non c'è niente nel database, il documento è il file.

Le tre parti della pagina

A sinistra la Struttura, che è l'albero del diagramma, e sotto le Proprietà di quello che si è selezionato. A destra il disegno, che si rifà a ogni modifica, e sotto la tabella delle Frecce. Si seleziona un riquadro dall'albero oppure cliccandolo direttamente nel disegno: il selezionato è contornato di azzurro tratteggiato.

Con Ctrl (o Cmd) premuto il clic aggiunge alla selezione invece di sostituirla, e ripremuto la toglie. Con più elementi selezionati i campi mostrano i valori dell'ultimo toccato — quello col contorno pieno — ma ogni modifica si applica a tutti: è il modo di dare lo stesso colore a sei elementi in una volta sola.

La casella in cima all'albero filtra: restano visibili solo le voci che contengono il testo cercato.

Da tastiera: ↑ e ↓ scorrono all'albero nell'ordine in cui si vede, filtro compreso; Invio porta il cursore nel testo di quello scelto; Canc lo elimina — tutti, se la selezione è multipla.

Nell'albero le voci si trascinano per riordinarle, fra pari grado: dentro un livello, o dentro lo stesso contenitore. Per spostare un riquadro dentro un altro restano i pulsanti, o il JSON.

L'anteprima è rimpicciolita per stare nella colonna. I tre comandi di zoom in fondo alla barra la riportano a dimensione reale e oltre: serve quando il diagramma è grande e i riquadri diventano troppo piccoli per cliccarli.

Livelli, riquadri, riquadri dentro i riquadri

Un livello è una riga del diagramma. Non ha un riquadro proprio: è un contenitore, e serve a dire che cosa sta sulla stessa altezza. Può avere un titolo, che diventa la scritta di sezione sopra la riga, e un testo.

Un riquadro è un elemento disegnato, con titolo (in grassetto) e testo. Il pulsante Riquadro dentro ne annida un altro al suo interno, e la cosa non ha limiti di profondità: è così che si ottiene la fascia del geodatabase con dentro le sue tabelle. Il pulsante Riquadro accanto ne aggiunge uno di pari livello, e Duplica ne fa una copia — con tutto il contenuto e tutto lo stile — accanto all'originale. Gli identificatori della copia vengono rinominati, altrimenti una freccia che punta a quell'id finirebbe su uno dei due a caso.

Riquadro attorno fa il contrario: mette una cornice nuova attorno a un gruppo che c'è già. Da un riquadro racchiude lui e tutti quelli accanto a lui, allo stesso livello; con più riquadri selezionati col Ctrl, solo quelli; da un livello, tutti i suoi. I riquadri racchiusi restano nello stesso ordine e con gli stessi identificatori, quindi le frecce restano dove sono; il riquadro nuovo si chiama nuovo gruppo, e basta cambiargli titolo e stile. La cornice ha un suo margine interno, che allargherebbe la riga: se i riquadri racchiusi hanno tutti una larghezza impostata si stringono loro, e la riga resta larga com'era. Se qualcuno ha la larghezza naturale, dettata dal testo, restano come sono e la cornice cresce attorno, perché stringerli manderebbe a capo le scritte.

La casella Disposizione dei figli dice se i riquadri annidati vanno in riga o in colonna. Occupa tutta la larghezza allarga i riquadri fino ai margini, mantenendo le proporzioni; senza, restano della loro larghezza naturale e il gruppo si centra.

Per andare a capo dentro un riquadro basta premere Invio nella casella del testo. Se si imposta una larghezza minima, il testo va a capo da solo per starci dentro.

Quando le righe finiscono per avere larghezze diverse, le rimette a posto Pareggia le larghezze, nelle proprietà del diagramma intero, dove una nota dice quanto è larga ciascuna. Porta ogni riga, col suo riquadro più esterno, alla larghezza scritta nel campo accanto; col campo vuoto, a quella più frequente fra le righe, o allo spazio del foglio se il foglio ha una larghezza imposta. La larghezza si spartisce fra i riquadri della riga in proporzione a quella che hanno, e dentro ogni contenitore si scende fino ai riquadri più interni, al netto di margini e distanze. Dopo, ogni riquadro ha una larghezza impostata, anche quelli che prima seguivano il testo. Una parola più lunga del suo riquadro non si spezza, e la sua riga resta più larga: la pagina lo segnala. Come ogni modifica, si annulla con Ctrl+Z.

Escape HTML: pedici, corsivi e simboli

La spunta Escape HTML, che sta sotto le caselle del testo, decide che cosa succede ai tag. Spuntata (è il valore predefinito) i tag si vedono scritti così come sono: PM<sub>2.5</sub> compare per intero nel disegno. Tolta la spunta, un piccolo elenco di tag viene interpretato:

• <b> e <strong> grassetto, <i> e <em> corsivo, <u> sottolineato, <s> e <del> barrato;
• <sub> pedice e <sup> apice — è così che si scrivono le specie chimiche e le unità: PM<sub>2.5</sub>, NO<sub>2</sub>, µg/m<sup>3</sup>;
• <br> per andare a capo;
• le entità numeriche (µ = µ) e le cinque canoniche (&, <, >, ", ', più  ).

Tutto il resto resta visibile come testo: un tag con attributi, o un tag che non è in questo elenco, non viene né interpretato né buttato via. Per il colore di una singola parola non c'è un tag: il colore si imposta sul riquadro.

La spunta è una proprietà di stile come le altre, quindi si eredita: toglierla una volta sul diagramma la toglie ovunque, ed è di solito quello che conviene fare. Le scritte laterali delle frecce hanno la loro spunta nella tabella delle frecce: finché non la si tocca mostra — e segue — quella del diagramma.

Stile e eredità

Carattere, corpo, colori, tratto, raggio dei vertici e spaziature si impostano al livello del diagramma e scendono a tutto quello che contiene; un livello o un riquadro ridefiniscono solo ciò che deve cambiare. Conviene quindi sistemare prima il diagramma (selezionandolo in cima all'albero) e poi ritoccare le eccezioni.

I campi delle proprietà mostrano sempre il valore in vigore, che sia proprio o ereditato; toccarne uno lo fissa su quel nodo. Il pulsante Torna allo stile ereditato cancella tutte le eccezioni del nodo selezionato e lo rimette a seguire il padre.

I corpi del carattere hanno un comando unico, nel gruppo Dimensioni dei caratteri del diagramma: Titoli, Testi e Scritte laterali. I testi sono il corpo di base, quello che scende a tutto; titoli e scritte laterali lo seguono finché il loro campo resta vuoto — i titoli alla stessa dimensione, le scritte laterali a 0,88 volte — e il valore in vigore si legge in grigio dentro il campo. Scritto un numero, il campo vale da sé; cancellato, torna a seguire i testi. Un livello o un riquadro con un corpo suo non viene raggiunto: il gruppo dice quanti sono, e il pulsante Applica a tutti toglie quelle eccezioni. Il titolo del diagramma resta 1,35 volte il corpo dei titoli.

Lo stesso gruppo, con Titoli e Testi, c'è anche su ogni livello e su ogni riquadro: vale per lui e per tutto quello che contiene, e un campo vuoto eredita dal contenitore, con il valore in vigore in grigio. È il modo di dare una volta sola il corpo a una riga di riquadri: si seleziona il livello e si scrive il numero. Anche qui Applica a tutti toglie le dimensioni fissate più in basso, ma solo dentro quel ramo.

Per sfondo e bordo la spunta nessuno li rende trasparenti: un riquadro senza sfondo e senza bordo diventa un semplice blocco di testo, che è il modo di mettere una scritta libera in un punto del diagramma.

I quadretti di Combinazioni di colore impostano con un clic sfondo, bordo e colore del testo insieme, già accordati fra loro: il bordo è la versione satura dello sfondo, e il testo resta leggibile sopra — compreso l'ultimo, scuro pieno, che porta con sé il testo bianco. Sceglierli a mano uno per uno è la via più corta per un diagramma che sembra fatto da mani diverse.

Allineamento verticale decide dove sta il contenuto quando il riquadro è più alto di quello che contiene, e succede di continuo: in una riga tutti prendono l'altezza del più alto, quindi quello con una riga di testo sola avanza spazio. Il valore predefinito è al centro; in alto e in basso appoggiano il testo a un bordo. Fa eccezione il contenitore con Occupa tutta la larghezza disposto in colonna, dove lo spazio in più se lo prendono i figli e non resta niente da spostare.

Frecce e scritte laterali

Ogni freccia collega due elementi chiamandoli per identificatore: sono quelli dell'albero, e compaiono nelle due tendine Da e A. Si possono collegare anche i livelli fra loro, ed è quello che si fa per le frecce del flusso principale. L'identificatore di ciò che è selezionato si legge accanto al suo nome, in cima alle proprietà, e si cambia nel campo Identificatore: le frecce si aggiornano da sole.

• Percorso automatico: la freccia esce dal centro del lato che guarda l'altro elemento ed entra dal centro del lato opposto — dal basso verso l'alto se uno sta sotto l'altro, di fianco se stanno affiancati. Se i due centri non sono allineati fa un gomito nello spazio vuoto fra i due; fra righe diverse, in quello che precede la riga d'arrivo. Più frecce sullo stesso lato si raccolgono attorno al centro, in ordine di dove sta l'altro capo, a una distanza che si regola nel campo Distanza fra frecce vicine delle proprietà del diagramma (16 px se non si tocca; meno, se il lato è corto). Più gomiti nello stesso spazio corrono a quote diverse, in un ordine che evita gli incroci. Di un livello contano i riquadri che contiene, non tutta la larghezza del diagramma.
• Dritto dove si può: il percorso automatico di prima. Se i due elementi sono incolonnati la freccia è un segmento verticale a metà della parte in comune; se sono sfalsati, un gomito fra i due centri. Serve quando molte frecce arrivano allo stesso riquadro da elementi che gli stanno già sopra: raccolte al centro farebbero un imbuto. L'esempio lo usa per le sorgenti.
• Corsia a sinistra o a destra: la freccia esce di fianco, corre lungo il margine e rientra dallo stesso lato. È la freccia di ritorno — il controllo dei job, i risultati che rientrano come dati. Se si scrive qualcosa nella colonna Scritta laterale, il testo compare ruotato lungo il tratto verticale. Più frecce sullo stesso lato si dispongono su corsie affiancate, e toccano i riquadri in punti diversi, nell'ordine in cui non si tagliano.
• Diretto: un segmento dal centro al centro, senza gomiti.

La colonna Verso stabilisce se la scritta laterale si legge dal basso in alto o dall'alto in basso. Con automatico vale la convenzione delle etichette degli assi: a sinistra dal basso in alto, a destra dall'alto in basso, così in entrambi i casi la testa delle lettere guarda verso l'esterno del disegno. Il verso è indipendente dal lato: si può volere una scritta a sinistra che si legga dall'alto in basso, e la si ottiene senza spostare la freccia.

Se una freccia nomina un elemento che non esiste più, la pagina lo dice in rosso sotto il disegno e disegna tutto il resto: non si perde il lavoro per un riferimento rotto.

Esportare

SVG è il formato da preferire: vettoriale, con i caratteri incorporati, pronto per la pubblicazione o per un ritocco in Inkscape.

I due pulsanti con la graffetta copiano negli appunti invece di scaricare: quello accanto a SVG copia il codice, quello accanto a PNG copia l'immagine alla risoluzione scelta, pronta da incollare in un documento o in un messaggio. Servono una connessione sicura, che il sito ha.

Il campo cm impone la larghezza con cui la figura esce. Non ridisegna niente: cambia la misura dichiarata nel file lasciando intatto il sistema di coordinate — con il vettoriale è esatto, non si perde nulla — e il PNG segue con i suoi dpi. Lasciato vuoto vale la dimensione naturale; quando è impostato, accanto alle misure compare una freccina.

Un file JSON si può anche trascinare direttamente sul disegno per aprirlo.

PDF è il formato che le riviste chiedono per le figure (con l'EPS, che se ne ricava): vettoriale, con i caratteri incorporati come sottoinsiemi e la pagina della misura esatta della figura — quella in cm, se è impostata. Lo produce il server con rsvg-convert, che usa i caratteri di sistema e non quelli incorporati nell'SVG: se una famiglia non è installata sul server, la sostituzione viene segnalata subito, dopo il download. La pagina Diagnostica ha il controllo corrispondente, con il comando di installazione.

Su più pagine. Il menu accanto a Esporta PDF sceglie il foglio: una pagina, della misura della figura come sopra, oppure A4 o A3, orizzontale o verticale. Con un foglio scelto il disegno non si rimpicciolisce: esce alla misura del campo cm (o alla naturale) e si divide in una griglia di pagine, da sinistra a destra e poi sotto, con margini di 1 cm. La barra dice prima quante pagine servono, e il piede di ognuna porta il nome del file, il numero e — se la griglia ha più righe e più colonne — la riga e la colonna, per riaccostarle. I tagli cadono nei varchi fra i blocchi, dove se ne attraversano meno: un riquadro più largo del foglio si taglia comunque. Oltre 100 pagine il PDF non si fa: si riduce la larghezza in cm o si sceglie un foglio più grande.

PNG serve quando il formato vettoriale non è accettato. Il campo dpi stabilisce la risoluzione: 96 corrisponde a quello che si vede a schermo, 150 va bene per una stampa corrente, 300 è il valore da usare per la tipografia e per le figure di un articolo. La risoluzione viene scritta dentro il file, così l'immagine si inserisce in un documento già alla dimensione fisica giusta invece di comparire enorme.

Accanto ai comandi di zoom si legge la dimensione del foglio in pixel e in centimetri: quella in centimetri è la misura con cui la figura si impagina in un documento, e non dipende dai dpi. Alzare i dpi non fa la figura più grande, la fa più nitida. Per cambiarne la dimensione si agisce sui corpi del carattere o sulla larghezza imposta del foglio.

Salva JSON scarica il modello: è il documento di lavoro, l'unico da conservare. Apri JSON lo rilegge. Esempio carica lo schema dell'architettura di UISH nella lingua della pagina, utile come punto di partenza; Nuovo riparte da un diagramma vuoto.

Annullare, e non perdere il lavoro

Le due frecce curve nella barra annullano e rifanno le modifiche, anche da tastiera con Ctrl+Z e Ctrl+Y. Si torna indietro di sessanta passi; una raffica di tasti nella stessa casella conta come un passo solo, così un annullamento cancella la parola e non la lettera. Dentro l'editor JSON comanda Ace, che ha la sua storia.

Il diagramma vive nel browser finché non lo si scarica, quindi ci sono tre reti. Nuovo, Esempio e Apri JSON chiedono conferma se c'è del lavoro non salvato. Chiudendo la scheda il browser avvisa. E a ogni modifica resta nel browser una copia di scorta: se la pagina viene ricaricata per sbaglio, alla riapertura compare una barra gialla che offre di riprendere quel diagramma o di scartarlo — non si carica da sola, perché chi arriva sulla pagina si aspetta l'esempio, non il lavoro di tre giorni prima.

La copia di scorta sta solo su questo computer e in questo browser, ed è una rete, non un archivio: il documento resta il file JSON.

Il JSON, per chi preferisce scrivere

Il pannello in fondo mostra il modello per esteso. La forma è questa:

{
  "titolo": "",
  "stile":  { "font": "IBM Plex Sans, Arial, sans-serif", "dim": 13, "raggio": 8,
              "allinea": "centro", "allinea_v": "centro" },
  "pagina": { "sfondo": "#ffffff", "margine": 22, "gap_livelli": 38 },
  "livelli": [
    { "id": "sorgenti", "riempi": true,
      "elementi": [
        { "id": "cams", "testo": "Analisi CAMS\n(modello europeo)",
          "stile": { "sfondo": "#fde8ef", "bordo": "#b8306a" } }
      ] },
    { "id": "dati",
      "elementi": [
        { "id": "gdb", "titolo": "Geodatabase", "riempi": true,
          "elementi": [ { "id": "t1", "testo": "isolinee" } ] }
      ] }
  ],
  "frecce": [
    { "da": "sorgenti", "a": "dati" },
    { "da": "gdb", "a": "cams", "percorso": "destra", "tratto": "tratteggiato",
      "etichetta": "i risultati rientrano come dati", "verso": "giu" }
  ]
}

La chiave elementi è la stessa a ogni profondità: è quella la ricorsione. Le chiavi omesse prendono il valore ereditato, e un diagramma valido può essere lungo tre righe. Premere Applica per portarlo nel disegno. Nello stile del diagramma, dim_titolo e dim_etichetta fissano i corpi di titoli e scritte laterali; omesse, seguono dim.

Limiti da conoscere

• Le frecce non girano attorno ai riquadri: una freccia che salta una riga la attraversa. Gli incroci fra i gomiti nello stesso spazio si evitano dove esiste un ordine senza incroci; per il resto la disposizione la decide chi scrive. Se due frecce si accavallano, conviene spostare un riquadro, usare una corsia laterale o il percorso dritto dove si può.
• Il diagramma non si salva sul server. La copia di scorta nel browser copre lo scivolone (ricaricamento, scheda chiusa per sbaglio), ma non è un archivio: sta su questa macchina, la cancella una pulizia dei dati del sito, e ce n'è una sola — aprendo un secondo diagramma prende il posto del primo. Il documento resta il file JSON.
• Nell'albero si trascina solo fra pari grado: spostare un riquadro dentro un altro contenitore si fa coi pulsanti o nel JSON.
• Nel PNG si incorporano solo le quattro famiglie ospitate dal sito (IBM Plex Sans, Nunito, Roboto, JetBrains Mono). Scegliendo Georgia o Arial si affida il risultato ai caratteri installati su chi lo aprirà: per una figura da pubblicare conviene restare sulle prime quattro.