GX-TXT Python Script Workspace: formattare le note Markdown e gestire immagini PNG

Le note associate a un file Python possono essere formattate e arricchite con immagini senza eseguire il programma. Questa guida mostra i comandi realmente disponibili nell’editor Notes: Note format, Note images, Resources, Properties, Save e Publish New. L’esempio comprende un piccolo grafico di misure sintetiche: è un’immagine di documentazione, non un Dataset numerico generato da un Job.

1. Documentare il sorgente senza cambiare il programma

Nel Python Script Workspace, ogni file di un Project può avere una nota Markdown distinta. La scheda Notes serve per spiegare ipotesi, ingressi, risultato atteso, limiti e figure illustrative. Modificare questa nota non modifica le istruzioni del file main.py e non avvia l’interprete Python. Le revisioni della documentazione e il contenuto del codice sono quindi due cose differenti.

2. Aprire una nota esistente

Aprire un Project con un file Python già salvato e selezionare main.py. Scegliere Edit → Edit Notes. Nell’esempio la nota contiene già titoli, un elenco e riferimenti al modulo helpers/calibration.py. Per lavorare con risorse persistenti, occorre una Session valida e la possibilità di salvare il documento associato. In assenza di tale contesto si può leggere la nota, ma non si deve presumere che le immagini siano registrabili.

3. I comandi del menu Note format

Quando la scheda Notes è attiva, il menu Edit → Note format mette a disposizione Heading (con Heading 1, 2 e 3), Bold, Italic, Inline code, Code block, Text color, Bullet list, Numbered list, Insert table, Insert link, Insert quote e Insert rule. Sono comandi di inserimento o trasformazione del testo Markdown, non funzioni per modificare il codice Python.

Menu Note format del Python Script Workspace, con Bold, Italic, titoli ed elenchi.
Figura 1. Il menu reale Note format contiene i comandi per titoli, evidenziazione, liste e blocchi.

4. Applicare Bold a una selezione

Nella vista Source della nota, selezionare una parola o frase e scegliere Note format → Bold. L’editor aggiunge i delimitatori ** attorno alla selezione: per esempio **Python project entrypoint**. Nel pannello Rendered preview si vede il testo in grassetto. Il markup resta visibile in Source ed è modificabile come testo normale.

Testo Markdown in Source modificato con Bold e anteprima Rendered affiancata.
Figura 2. Una selezione è stata formattata con Bold; Source e anteprima mostrano la differenza.

5. Italic e annullamento delle modifiche

Il comando Italic usa gli asterischi singoli, ad esempio *esempio*. Per annullare una formattazione, usare Undo sul documento Markdown e controllare nuovamente Source. In alcuni casi i due delimitatori di una selezione sono inseriti come operazioni di modifica separate: un singolo Undo può non ripristinare interamente la frase. Verificare sempre il testo risultante prima di proseguire.

6. Heading: creare una gerarchia leggibile

I comandi Heading 1, Heading 2 e Heading 3 inseriscono i corrispondenti livelli Markdown, utili per strutturare una relazione tecnica. Per esempio, # Scopo identifica un titolo principale e ## Procedura una sottosezione. Evitare di scegliere un livello soltanto per ottenere caratteri più grandi: la gerarchia è importante anche nella navigazione Outline.

7. Inline code e Code block

Inline code evidenzia brevi identificatori come scale_readings o main.py. Code block delimita invece un frammento su più righe. In una nota scientifica queste funzioni distinguono le istruzioni riproducibili dalle spiegazioni. Un blocco di codice inserito nella nota non viene eseguito: il Runner usa il vero sorgente Python.

8. Elenchi puntati e numerati

Bullet list e Numbered list inseriscono modelli testuali per descrivere prerequisiti e passaggi. Una sequenza numerata è indicata per un protocollo; un elenco puntato per ipotesi e limiti. Il testo rimane in Markdown e può essere riordinato manualmente. Dopo l’inserimento controllare l’anteprima: una riga vuota fuori posto può interrompere un elenco.

9. Tabelle, collegamenti, citazioni e separatori

Il menu offre Insert table per una tabella Markdown con intestazioni e righe; Insert link per un collegamento; Insert quote per un blocco citato e Insert rule per una linea di separazione. I contenuti generati sono modelli da completare e verificare. Text color riguarda la presentazione del documento: non attribuisce significato numerico o qualità di misura ai dati.

10. Esempio minimo di nota tecnica

Il seguente frammento è un esempio di documentazione da inserire nella vista Source, non uno script da eseguire.

# Calibration notes

## Input
- Five synthetic temperature readings.
- One illustrative calibration figure.

## Interpretation
**Illustrative only:** these values are not a published result.
The Python entrypoint is `main.py`.

In Rendered preview controllare la struttura prima di pubblicare.

11. Modifica del documento e Save

La scheda Notes segnala le modifiche non ancora salvate. File → Save registra la nota nel contesto autorizzato; non è equivalente a salvare o lanciare main.py. È prudente salvare prima di iniziare a gestire immagini, per distinguere le modifiche di formattazione da quelle alle risorse.

12. Perché allegare una figura PNG

Una figura può illustrare uno schema, una curva di calibrazione, una microfotografia o la disposizione di un esperimento. Nella prova si usa un grafico sintetico, con cinque osservazioni, preparato come file PNG. L’immagine serve unicamente a spiegare la procedura; non costituisce un output di calcolo del Workspace e non sostituisce un Dataset scientifico con unità e provenienza.

13. I comandi del menu Note images

Con la nota attiva, aprire Edit → Note images: le voci disponibili sono Insert image…, Replace image… e Remove image. Le stesse operazioni principali sono accessibili dal pannello Resources con i pulsanti Add, Replace e Remove. La disponibilità delle voci dipende dal documento, dalle autorizzazioni e dalla presenza di risorse selezionabili.

Menu Note images originale del Workspace con comandi per inserimento, sostituzione e rimozione PNG.
Figura 3. Il menu Note images presenta Insert image, Replace image e Remove image.

14. Inserire un file PNG nella nota

Posizionare il cursore nel punto desiderato del testo e scegliere Note images → Insert image…. La finestra originale di scelta file filtra i PNG. Selezionare un’immagine locale compatibile e confermare con Open. L’editor acquisisce una risorsa gestita: non si limita a inserire il percorso assoluto del file, che non sarebbe portabile.

15. Limiti delle risorse gestite

Nella versione considerata l’immagine deve essere un PNG valido, non superiore a 4 MiB, con larghezza e altezza tra 1 e 4096 pixel. Per un documento sono previsti al massimo 32 elementi e un totale gestito non superiore a 16 MiB. Il nome logico deve avere un formato portabile. Questi limiti sono vincoli d’ingresso, non criteri di qualità scientifica dell’immagine.

16. Il riferimento inserito nel Markdown

Dopo Insert image… la vista Source contiene un riferimento simile a questo:

![Image](assets/calibration_figure.png)

La parte assets/ indica una risorsa gestita dal documento, non una directory da creare manualmente. Il nome effettivo deriva dal file scelto o dalla risorsa associata. Rendered preview visualizza la figura utilizzando i dati registrati nell’editor.

Nota Markdown di main.py con immagine PNG di misure sintetiche inserita e anteprima.
Figura 4. L’immagine sintetica è stata inserita come risorsa gestita e appare nell’anteprima.

17. Salvare testo e immagine insieme

Dopo l’inserimento, usare File → Save. La nota associa il testo e l’immagine al documento Markdown persistente. Verificare che scompaia l’indicatore di modifica e che il grafico sia ancora visibile in Rendered preview. La sola anteprima di una risorsa non dimostra che il file sia stato salvato.

Nota Markdown di main.py salvata insieme alla prima risorsa PNG, senza eseguire Python.
Figura 5. File Save rende persistente il testo Markdown e la prima risorsa PNG.

18. Sostituire un’immagine senza cambiare il collegamento

Aprire Note images → Replace image… dopo avere scelto la risorsa da sostituire in Resources. Selezionare il nuovo PNG e verificare l’anteprima. Nell’esempio il grafico blu viene sostituito da uno rosso: il nome logico nel riferimento Markdown rimane uguale, ma cambiano i dati binari dell’immagine. È necessario un nuovo Save per rendere persistente la sostituzione.

Anteprima della figura sintetica dopo Replace image: immagine rossa al posto della blu.
Figura 6. Replace image aggiorna i dati dell’immagine conservando il suo nome logico.

19. Non confondere nome e contenuto della risorsa

Un riferimento assets/nome.png individua la risorsa logica del documento. Dopo Replace image…, quel nome può continuare a comparire invariato mentre l’immagine mostrata è diversa. Per questo è importante controllare Rendered preview e, quando serve, le informazioni mostrate in Resources. Una modifica dell’immagine non significa automaticamente che siano cambiate le misure scientifiche.

20. Aggiungere una seconda immagine temporanea

Per comprendere la rimozione, si può inserire un secondo PNG di prova con Insert image… e selezionarlo nell’elenco delle risorse. Nell’esempio si tratta di una copia illustrativa destinata a essere tolta. È utile controllare il nome prima di procedere, soprattutto quando le immagini hanno nomi molto simili.

Nota con una seconda immagine PNG temporanea prima dell’operazione Remove image.
Figura 7. Una seconda risorsa temporanea mostra come selezionare l’elemento da rimuovere.

21. Remove image non cancella automaticamente il Markdown

Selezionare la risorsa e utilizzare Remove image. L’operazione la toglie dalle risorse gestite, ma lascia nel testo il riferimento Markdown che era stato inserito. Un riferimento rimasto senza risorsa provoca una figura non disponibile nell’anteprima. Quindi cercare la riga ![...](assets/...) relativa a quell’immagine, eliminarla manualmente e salvare la nota.

Nota dopo la rimozione della risorsa temporanea e del relativo collegamento Markdown.
Figura 8. Dopo Remove image, eliminare anche il collegamento Markdown alla risorsa rimossa.

22. Verificare il pannello Resources

Aprire View → Note panes and zoom → Resources. La tabella mostra il nome della risorsa, la dimensione in byte e la risoluzione in pixel. Selezionando una riga compaiono dettagli e i pulsanti Add, Replace e Remove. Tenere aperto questo pannello durante gli interventi sulle immagini; chiuderlo quando si torna all’editing ordinario per conservare spazio nel sorgente.

Pannello Resources reale con PNG 640 per 300, anteprima e comandi Add Replace Remove.
Figura 9. Resources mostra l’immagine, le sue dimensioni e i pulsanti Add, Replace e Remove.

23. Controllare versione e associazione con Properties

Aprire View → Note panes and zoom → Properties per esaminare l’identità del documento, il file sorgente associato e la condizione della sorgente. Nell’esempio compare Source filename: main.py e Source status: current. Si tratta di proprietà informative, non di un editor diretto della sorgente o dei metadati scientifici. La verifica di identità viene ripetuta quando si salva.

Pannello Properties con associazione corrente alla sorgente Python main.py.
Figura 10. Properties indica Source status: current e la sorgente Python associata.

24. La differenza fra Save e Publish New

Save aggiorna il documento principale associato al file Python, quando la Session e la revisione lo consentono. Publish New crea invece una copia Markdown distinta, con un nuovo identificativo di Dataset; il documento primario non deve essere sostituito o riassegnato automaticamente. È una scelta utile quando si vuole conservare una versione autonoma per la consultazione.

25. Aprire Publish New e comprendere i campi

Con Source attivo, la scorciatoia Ctrl+Shift+S della nota apre la finestra Publish New document copy. Il campo richiede un identificativo canonico nuovo. I pulsanti Publish New e Cancel permettono rispettivamente di creare la copia e abbandonare l’operazione. Usare un nome distinto e significativo, senza confonderlo con l’identità del file main.py.

Dialogo Publish New document copy per creare un documento Markdown distinto.
Figura 11. La finestra Publish New richiede un nuovo identificativo e offre Cancel.

26. Cancel e copia effettivamente pubblicata

Se si sceglie Cancel, la finestra si chiude e la nota principale resta invariata. Se si conferma Publish New con un identificativo valido, nasce un altro documento Markdown: il nuovo Dataset non rimpiazza la nota collegata al sorgente. Nel nostro esempio la copia mantiene anche la risorsa PNG presente nel documento. La pubblicazione della copia non equivale all’esecuzione di un Job.

Nota principale ancora aperta dopo la pubblicazione separata di una copia Markdown.
Figura 12. La copia autonoma pubblicata non sostituisce la nota principale associata al sorgente.

27. Controlli prima di chiudere la nota

Verificare che il documento non segnali modifiche non salvate, che l’anteprima non contenga riferimenti immagine orfani e che Properties riporti l’associazione corretta al sorgente. Le operazioni sulle note richiedono la Session pertinente; una fonte cambiata o un documento già modificato altrove può comportare un rifiuto del salvataggio. In tal caso conservare la bozza e verificare la versione corretta prima di riprovare. Non aggirare i controlli ricorrendo a funzioni interne.

Usare View → Show Notes per nascondere la nota e recuperare l’area di editing del sorgente, preferibilmente con i pannelli laterali non necessari chiusi. Le figure restano nella documentazione già salvata e il file main.py rimane un normale sorgente Python. Le operazioni trattate qui non hanno richiesto Script Library, Runner, Debugger o Jobs: il capitolo riguarda esclusivamente la preparazione e la conservazione di note Markdown illustrate.

Editor Python High Contrast Dark con sorgente originale e schede note nascoste.
Figura 13. Con le note nascoste, l’editor Python ritorna al normale sorgente in High Contrast Dark.