leeno-aggiorna-manuale

name	leeno-aggiorna-manuale
description	Skill per aggiornare sistematicamente il manuale ufficiale di LeenO (MANUALE_LeenO.fodt) partendo dalle modifiche apportate al codice, evitando duplicazioni grazie a un file di tracking.

LeenO – Aggiornamento Manuale con Tracciamento

Questa skill ha l'obiettivo di mantenere sincronizzato il manuale utente di LeenO (documentazione/MANUALE_LeenO.fodt) con le ultime modifiche al codice, assicurandosi di non ripetere il lavoro su commit o funzionalità già documentate.

File Chiave

• Manuale: w:\_dwg\ULTIMUSFREE\_SRC\leeno\documentazione\MANUALE_LeenO.fodt (formato XML)
• Registro Aggiornamenti: w:\_dwg\ULTIMUSFREE\_SRC\leeno\documentazione\TRACKING_MANUALE.md
• Mappa Sezioni: MAPPA_SEZIONI.md (nella directory di questa skill)

Risorse della Skill

• scripts/genera_mappa.py — Script Python per rigenerare la mappa delle sezioni del manuale.

---

Sorgenti di Informazione

Per individuare le novità da documentare, non limitarti ai soli file Python. Consulta tutte le seguenti sorgenti:

Sorgente	Percorso	Cosa cercare
Codice Python	src/Ultimus.oxt/python/pythonpath/*.py	Nuove funzioni MENU_*, modifiche a flussi utente
Menù e sotto-menù	src/Ultimus.oxt/Addons.xcu	Nuove voci di menù, riorganizzazione menù, etichette
Scorciatoie da tastiera	src/Ultimus.oxt/Accelerators.xcu	Nuove scorciatoie, modifiche a scorciatoie esistenti
Finestre di dialogo	src/Ultimus.oxt/dialogs/*.xdl	Nuove finestre, nuovi controlli, campi rinominati
File di proprietà	src/Ultimus.oxt/dialogs/*.properties	Etichette e testi dei dialoghi
Configurazione	src/Ultimus.oxt/python/pythonpath/LeenoConfig.py	Nuove opzioni di configurazione

[!IMPORTANT] Quando documenti una funzionalità nel manuale, verifica sempre il percorso di menù reale in Addons.xcu e le scorciatoie in Accelerators.xcu, in modo che le istruzioni nel manuale riflettano fedelmente l'interfaccia utente.

---

Procedura Operativa

Fase 0: Consultare la Mappa delle Sezioni

1. Apri MAPPA_SEZIONI.md (nella directory di questa skill) con view_file.
2. Individua la sezione più adatta in cui inserire la nuova documentazione.
3. Annota il numero di riga e il nome del bookmark del punto di inserimento.

[!TIP] Se il manuale è stato modificato di recente e la mappa potrebbe non essere aggiornata, rigenera la mappa:

python .agent/skills/leeno-aggiorna-manuale/scripts/genera_mappa.py

Fase 1: Verifica dello Storico (Tracking)

1. Apri e leggi il file documentazione/TRACKING_MANUALE.md utilizzando il tool view_file.
2. Controlla la tabella per capire quali sono le ultime funzionalità o gli ultimi commit (Commit Hash) già documentati. In questo modo saprai esattamente da quale punto temporale o da quale modifica ripartire.

Fase 2: Individuazione delle Novità da Documentare

1. Chiedi all'utente su quale commit/file sta lavorando o usa git log per vedere gli ultimi commit sul codice sorgente.
2. Confronta queste novità con il file di tracking.
3. Seleziona le funzionalità o le modifiche che non sono ancora presenti nella tabella di TRACKING_MANUALE.md e che necessitano di una spiegazione nel manuale utente.
4. Per ciascuna novità, consulta anche:
   • Addons.xcu per il percorso di menù esatto e le etichette visibili all'utente.
   • Accelerators.xcu per le scorciatoie da tastiera associate.
   • I file .xdl e .properties dei dialoghi per i nomi dei campi e i testi dei pulsanti.

Fase 3: Modifica del Manuale (FODT)

Essendo il file MANUALE_LeenO.fodt un file XML di grandi dimensioni (oltre 3 MB e 37.000 righe):

1. NON usare script complessi o editor massivi che potrebbero corrompere la struttura XML.
2. Usa la Mappa Sezioni (MAPPA_SEZIONI.md) per trovare la posizione di inserimento senza dover scansionare l'intero file.
3. Usa view_file con il numero di riga dalla mappa per ispezionare il contesto XML del punto di inserimento.
4. Usa Python per effettuare un semplice replace testuale stringa-per-stringa sulla riga interessata. Esempio di snippet sicuro:

   import sys
   p = 'w:/_dwg/ULTIMUSFREE/_SRC/leeno/documentazione/MANUALE_LeenO.fodt'
   with open(p, 'r', encoding='utf-8') as f:
       text = f.read()
   target = "vecchio testo esatto compresi i tag XML"
   replacement = "nuovo testo con le nuove istruzioni"
   if target in text:
       text = text.replace(target, replacement)
       with open(p, 'w', encoding='utf-8') as f:
           f.write(text)
       print("Sostituzione completata")
   else:
       print("Testo target non trovato")
   

5. Scrivi il testo in italiano chiaro e formale, orientato all'utente finale (senza terminologia informatica, a meno che non si parli di tasti o menu).

Fase 4: Aggiornamento del Tracking

Una volta che la modifica al manuale è andata a buon fine, devi aggiornare il registro in modo che nessuno ripeta questo lavoro in futuro.

1. Edita documentazione/TRACKING_MANUALE.md accodando una nuova riga alla tabella in fondo al file.
2. La riga dovrà contenere: | YYYY-MM-DD | Hash del commit o Nome del file modificato | Breve descrizione della modifica nel codice | Sezione del manuale in cui hai scritto |

Fase 5: Rigenera la Mappa delle Sezioni

Dopo aver modificato il manuale, rigenera sempre la mappa per mantenerla aggiornata:

python .agent/skills/leeno-aggiorna-manuale/scripts/genera_mappa.py

Fase 6: Conclusione

Comunica all'utente l'avvenuto aggiornamento del manuale, mostrando la porzione di testo inserita, e conferma l'avvenuta registrazione in TRACKING_MANUALE.md.