Documentare gli script Octave con Notes Markdown
In Octave Script Workspace si possono affiancare a uno script GNU Octave delle Notes Markdown: un documento testuale per spiegare lo scopo dell’esperimento, le unità, le ipotesi e il significato delle variabili. Le note si leggono e si modificano in un editor distinto da quello del codice.
Le schermate si riferiscono a GX-TXT DEV112 con patch P005, modulo Octave Script Workspace 1.8.3. I comandi dell’interfaccia restano in inglese. L’esempio impiega dati sintetici; visualizzare o modificare una nota non esegue lo script Octave.
1. Partire da uno script registrato
Per associare le note a una sorgente occorre innanzitutto avere uno script registrato in GX-TXT. Aprire Octave Scripts, creare o selezionare uno script e controllare Scope, Script ID e Name. Con File → Save registrare il sorgente, se ancora nuovo.

Il nostro esempio utilizza due vettori che descrivono misure sintetiche:
% Synthetic voltage measurements in volts.
time_s = [0, 1, 2, 3, 4];
voltage_V = [0, 0.2, 0.4, 0.8, 1.0];
Il codice rimane il contenuto eseguibile dello script. Le Notes non ne diventano istruzioni né cambiano il significato dei vettori.
2. Aprire Edit Notes
Selezionare la scheda del sorgente desiderato e poi Edit → Edit Notes. Si apre un’altra scheda, riconoscibile dal suffisso — Notes. All’inizio il documento è vuoto: a sinistra appare il Markdown Source e a destra l’anteprima Preview.

La nuova scheda è associata al sorgente selezionato. Per proseguire nella scrittura non è necessario chiudere il codice, né aprire un secondo Workspace.
3. Scrivere Markdown e osservare l’anteprima
Nell’editor a sinistra si scrive Markdown normale. Il carattere # introduce un titolo principale, ## un sottotitolo, - un elemento di elenco, mentre **testo** evidenzia in grassetto.
Per esempio:
# Notes on a synthetic voltage study
## Purpose
Explain the meaning of **voltage_V** without executing it.
## Measurements
- Time: seconds
- Voltage: volts
- Source: synthetic teaching example
L’anteprima a destra interpreta il testo mostrando intestazioni, grassetti, paragrafi ed elenchi.

La vista formattata è un aiuto alla lettura: ciò che si modifica è il Markdown Source. Non vengono eseguiti comandi Octave o funzioni matematiche attraverso l’anteprima.
4. Dedicare tutta la finestra all’anteprima
Nel menu View → Note panes and zoom disattivare Source lasciando attivo Rendered preview. L’anteprima occupa l’area disponibile e consente di rileggere il documento senza il testo Markdown grezzo.

Per ritornare alla composizione affiancata basta riabilitare Source nello stesso menu.
5. Scrivere con il solo Markdown Source
Si può anche fare l’operazione inversa: disattivare Rendered preview mantenendo Source. In questo modo lo spazio dell’editor è riservato al testo da modificare.

È una modalità pratica per documenti con molte righe, elenchi o frammenti di codice. Riattivando la voce Rendered preview si recupera l’anteprima senza perdere il testo.
6. Navigare con Outline
Il comando View → Note panes and zoom → Outline mostra l’indice delle intestazioni presenti nel Markdown. L’editor riconosce i titoli di livello # e ## e li riporta in un albero.

Selezionare una voce, per esempio Interpretation, per riportare il cursore all’inizio della riga corrispondente del Markdown Source.

Questa funzione serve a navigare: non aggiunge intestazioni nuove e non modifica il contenuto dello script o delle note.
7. Consultare Properties e Resources
Sempre dal menu Note panes and zoom si possono mostrare altre due sezioni.
Properties presenta le informazioni sul documento e sullo stato di salvataggio, inclusi il Dataset canonico, l’associazione alla sorgente e la presenza di modifiche ancora non salvate.

Resources mostra le risorse del documento, in particolare le immagini associate, con colonne per nome, dimensione in byte e dimensioni in pixel.

Nel nostro esempio non sono state aggiunte immagini: l’elenco è quindi vuoto. L’inserimento, la sostituzione e la rimozione delle risorse richiedono un flusso distinto, con controlli sulle associazioni e sui contenuti.
8. Nascondere e riaprire le note con Show Notes
Quando si vuole tornare al codice, aprire View → Show Notes e disattivare la voce. La scheda Notes viene nascosta, mentre torna disponibile la scheda Octave.

Riabilitando Show Notes, la stessa scheda riappare con il Markdown che si stava modificando.

Nascondere la scheda non equivale a salvarla. Finché il documento contiene modifiche non registrate, è necessario conservarne consapevolmente la bozza e non confondere questa operazione con la chiusura definitiva.
9. Zoom e ripristino del layout
Il menu View → Note panes and zoom include Zoom in, Zoom out, Reset zoom e Reset note layout. I primi due comandi modificano la dimensione di lettura nell’editor e nell’anteprima.

Reset zoom riporta il fattore iniziale. Reset note layout ripristina la disposizione ordinaria con Markdown Source e Rendered preview affiancati, senza modificare le righe scritte.

10. Distinguere codice, bozza e nota registrata
| Elemento | Funzione |
|---|---|
| Octave Source | Contiene le istruzioni dello script. |
| Notes — Source | Contiene il testo Markdown della documentazione. |
| Rendered preview | Mostra una rappresentazione formattata del Markdown. |
| Outline | Permette di raggiungere i titoli del documento. |
| Properties | Mostra identità, associazione e stato del documento. |
| Resources | Presenta le immagini e le risorse associate. |
| Show Notes | Nasconde o mostra la scheda, conservando il lavoro in corso nell’editor. |
Le Notes sono associate all’identità del sorgente, ma la registrazione permanente del documento è distinta da quella del codice. In questa procedura abbiamo lavorato su una bozza non pubblicata: il pannello Properties non mostra ancora un Dataset canonico.
Quando si intende conservarle oltre la sessione di modifica, occorre usare il flusso esplicito di salvataggio della nota e verificare l’associazione prevista. La gestione delle revisioni, delle immagini e della pubblicazione del documento è trattata separatamente.
Le Notes consentono quindi di mantenere spiegazioni e contesto scientifico accanto allo script, senza inserire documentazione estesa nel codice eseguibile e senza dover aprire pannelli non necessari durante la programmazione.