Formattare le Notes Markdown e gestire le immagini negli script Octave
Le Notes di GX-TXT Octave Script Workspace permettono di costruire un documento scientifico accanto al sorgente GNU Octave: titoli, testo formattato, elenchi, tabelle e immagini possono essere organizzati e conservati come nota associata. In questo capitolo vediamo come utilizzare i comandi di formattazione, riconoscere le risorse PNG gestite e verificare un salvataggio effettivo.
Le etichette dei comandi sono quelle dell’interfaccia inglese di GX-TXT DEV112 con patch P005, Octave Script Workspace 1.8.3. Si usano solo valori sintetici. Modificare le Notes non esegue lo script e non crea un Job di calcolo.
1. Preparare il Source Octave
Aprire uno script già registrato nel Workspace. Per un esempio introduttivo basta una sorgente contenente due vettori numerici:
% Synthetic voltage measurements in volts.
time_s = [0, 1, 2, 3, 4];
voltage_V = [0, 0.2, 0.4, 0.8, 1.0];
Con File → Save, salvare il codice prima di aggiungere la documentazione. La scheda Source è distinta dalla scheda Notes.

2. Scrivere una nota e distinguere Source e Preview
Con la scheda dello script selezionata, aprire Edit → Edit Notes. Nella nuova scheda — Notes il riquadro scuro è il testo Markdown modificabile; Preview mostra la lettura formattata.

La sintassi Markdown si può digitare direttamente. Per esempio, **voltage_V** dà il grassetto, mentre ## Measurements introduce un’intestazione. I contenuti sono documentazione: nessuna riga della nota viene interpretata come istruzione Octave.
3. Usare Edit → Note format
Selezionare un’espressione nell’editor delle Notes, quindi aprire Edit → Note format. Il menu contiene Heading con i livelli 1–3, Bold, Italic, Inline code e altri strumenti di formattazione. La modifica viene applicata al Markdown reale, non soltanto all’aspetto della Preview.

Per esempio:
### Dataset review
A saved *Octave* script contains **five synthetic voltage samples**.
The Notes do not submit a `Run Job`.
Inline code è indicato per nomi di variabili, funzioni e comandi; non equivale all’esecuzione del testo contrassegnato.
4. Aggiungere struttura con elenchi, citazioni e tabelle
Sempre in Note format sono disponibili Bullet list, Numbered list, Insert quote, Insert table, Code block, Insert link e Insert rule. Le operazioni introducono una struttura Markdown da completare con i contenuti scientifici desiderati.

La tabella introdotta dal comando è inizialmente un modello con intestazioni e valori generici. Sostituire i segnaposto con nomi delle grandezze, valori e unità; controllare la rappresentazione effettivamente mostrata nella Preview prima di considerarla pronta per la pubblicazione.
5. Inserire un’immagine PNG nella nota
Le immagini non sono soltanto collegamenti arbitrari a file del disco: il documento utilizza risorse gestite, identificate da un nome logico. Quando viene aggiunta un’immagine, il Markdown riceve un riferimento del tipo:


Il grafico raffigurato è un’illustrazione sintetica predisposta per la nota, non l’output dell’esecuzione dello script Octave mostrato all’inizio. È opportuno che titolo, origine, unità ed eventuali elaborazioni siano chiariti nel testo della documentazione.
6. Esaminare Resources e i dati dell’immagine
Selezionare View → Note panes and zoom → Resources. Il pannello elenca le risorse della nota: nome, dimensione in byte e dimensioni in pixel. Selezionando una voce, si possono leggere il percorso logico assets/..., lo SHA-256 e il formato.

Queste informazioni servono a distinguere il riferimento scritto nel Markdown dal contenuto binario PNG che la Preview deve poter caricare. Il nome logico deve rimanere coerente con quello usato nel documento.
7. Sostituire un’immagine mantenendo il riferimento
Replace image permette di sostituire il contenuto di una risorsa già presente. Quando si riutilizza lo stesso nome logico, il riferimento Markdown non ha bisogno di cambiare: è invece il contenuto PNG, con il suo SHA-256, a essere aggiornato.

Il menu Edit → Note images presenta Insert image…, Replace image… e Remove image. Sono le operazioni principali per lavorare sulle risorse senza confonderle con la modifica del testo.

8. Rimozione, riferimenti mancanti e ripristino
Remove image elimina la risorsa selezionata dall’insieme gestito, ma non cancella automaticamente la riga Markdown che la richiama. Un riferimento rimasto senza immagine può produrre nella Preview l’indicazione Image unavailable. Prima di salvare, verificare quindi che non esistano collegamenti a risorse rimosse.
È possibile reinserire il PNG e ristabilire lo stesso nome logico, controllando poi che nel Markdown compaia una sola riga di riferimento all’immagine voluta.

Le immagini devono essere PNG regolari; il gestore verifica formato, dimensioni e limiti delle risorse. Un file che non soddisfa tali controlli non deve essere considerato una risorsa valida.
9. Salvare una nota collegata alla sorgente
La nota può contenere testo e immagini senza essere ancora pubblicata come documento persistente. Prima del salvataggio, verificare che la sorgente Octave sia registrata nella Session corretta. In caso di aggiornamento della sorgente o dell’associazione mentre una bozza è aperta, l’applicazione può rifiutare un salvataggio basato su una revisione precedente: non sovrascrive silenziosamente una versione più recente. Conservare la bozza, riaprire la nota corrente e rivedere le modifiche.

Usare File → Save con la scheda Notes attiva. Il risultato può essere verificato da View → Note panes and zoom → Properties: compaiono l’identità del Canonical Dataset, il produttore del documento, l’associazione alla sorgente e lo stato Unsaved changes: 0.

Il Dataset della nota contiene Markdown e risorse; non coincide con lo script .m e non rappresenta il risultato di un Job numerico.
10. Riaprire la nota e tornare al codice
La verifica più importante dopo il salvataggio consiste nel chiudere e riaprire la scheda Notes della medesima sorgente, controllando che ricompaiano sia il testo completo sia il PNG nell’anteprima.

Con View → Show Notes si può nascondere la scheda documentale e tornare alla normale superficie dell’editor Octave, senza alterare il sorgente.

| Operazione | Che cosa cambia |
|---|---|
| Note format | Il testo Markdown della nota. |
| Note images → Insert / Replace / Remove | L’insieme delle risorse PNG gestite e, nell’inserimento, il riferimento Markdown. |
| File → Save nella scheda Notes | Il documento associato, con le sue risorse, nella Session attiva. |
| Properties | Mostra identità e stato di salvataggio del documento. |
| Show Notes | La visibilità della scheda documentale, non il codice eseguibile. |
La pratica consigliata è rivedere la Preview, controllare Resources, salvare e riaprire la nota. In questo modo la documentazione dello script rimane verificabile, mentre l’editor del codice può restare essenziale e leggibile.