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.

Octave Script Workspace con uno script GNU Octave salvato e due vettori numerici sintetici nell'editor Source.
Figura 1 — Uno script Octave salvato nel Workspace, prima di lavorare sulla sua documentazione.

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.

GX-TXT Notes con editor Markdown Source a sinistra e anteprima formattata del documento scientifico a destra.
Figura 2 — Il testo Markdown e l’anteprima della nota scientifica sono affiancati.

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.

Editor Notes GX-TXT con formattazione Heading, Bold, Italic e Inline code applicata al documento Markdown.
Figura 3 — Heading, Bold, Italic e Inline code applicati al contenuto della nota mediante i comandi nativi.

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.

Documento Notes Markdown contenente una tabella, una citazione e un elenco, visualizzati nell'editor GX-TXT.
Figura 4 — Un esempio con tabella Markdown, citazione ed elenco inseriti nella scheda Notes.

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:

![Synthetic voltage plot](assets/o13_voltage_curve.png)
GX-TXT Octave – Inserire immagini PNG nelle Notes Markdown
Figura 5 — Un PNG di esempio inserito nelle Notes e visualizzato nell’anteprima Markdown.

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.

Pannello Resources GX-TXT con immagine PNG selezionata, nome logico, dimensioni, formato e hash SHA-256.
Figura 6 — Il pannello Resources presenta l’immagine gestita selezionata, i metadati e i controlli relativi.

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.

Notes GX-TXT dopo Replace image, con risorsa PNG aggiornata e riferimento Markdown originale conservato.
Figura 7 — La sostituzione della risorsa aggiorna l’immagine conservando il medesimo riferimento nel testo.

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.

Menu Edit → Note images di GX-TXT Octave con i comandi Insert image, Replace image e Remove image.
Figura 8 — Le tre operazioni native del menu Note images, aperto sopra la nota salvata.

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.

Editor Notes Markdown dopo il ripristino di un'immagine PNG e del corrispondente riferimento valido nel documento.
Figura 9 — Dopo il ripristino della risorsa, la nota torna a presentare un riferimento PNG valido.

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.

Notes GX-TXT con testo Markdown e risorsa PNG associati alla revisione corrente del sorgente Octave.
Figura 10 — Markdown e PNG associati alla sorgente corrente prima del salvataggio definitivo.

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.

Pannello Properties delle Notes con Canonical Dataset, associazione al sorgente e stato Unsaved changes: 0.
Figura 11 — Properties conferma il Dataset canonico della nota, l’associazione corrente e l’assenza di modifiche non salvate.

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.

Notes Markdown riaperte dopo il salvataggio, con testo e immagine PNG nuovamente visibili nell'anteprima.
Figura 12 — La nota ricaricata dal Dataset canonico mostra di nuovo il Markdown e l’immagine associata.

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

Octave Script Workspace con Source GNU Octave nuovamente visibile, separato dalla documentazione Markdown salvata.
Figura 13 — Tornando al Source Octave, il codice è ancora disponibile e separato dalla documentazione salvata.
OperazioneChe cosa cambia
Note formatIl testo Markdown della nota.
Note images → Insert / Replace / RemoveL’insieme delle risorse PNG gestite e, nell’inserimento, il riferimento Markdown.
File → Save nella scheda NotesIl documento associato, con le sue risorse, nella Session attiva.
PropertiesMostra identità e stato di salvataggio del documento.
Show NotesLa 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.