Markdown Converter - Manuale Utente

1. Panoramica e Scopo

Markdown Converter è un'applicazione desktop progettata per automatizzare e standardizzare la creazione di documenti professionali. Permette agli utenti di scrivere contenuti nel semplice e pulito formato Markdown e di convertirli in documenti .docx e .pdf splendidamente formattati, utilizzando un sistema avanzato di template e profili.

Lo scopo principale è eliminare la necessità di formattazione manuale e ripetitiva in un word processor, garantendo coerenza tra i documenti e velocizzando il flusso di lavoro, specialmente per la documentazione tecnica, i manuali utente e i report.

2. Requisiti di Sistema

Per utilizzare tutte le funzionalità dell'applicazione, assicurati che sul tuo sistema siano presenti i seguenti componenti:

Python 3.8+: Necessario per eseguire l'applicazione.
wkhtmltopdf: Essenziale per la conversione diretta da Markdown a PDF. Deve essere installato e preferibilmente aggiunto al PATH di sistema.
Microsoft Word OPPURE LibreOffice: Almeno uno dei due software è richiesto per la conversione ad alta fedeltà da .docx a .pdf. L'applicazione rileverà automaticamente quale software è disponibile.

3. Installazione e Avvio

Clona il Repository: Ottieni una copia locale del progetto dal server Gitea.

Crea un Ambiente Virtuale: È una buona pratica isolare le dipendenze del progetto.

python -m venv venv
# Su Windows
venv\Scripts\activate
# Su Linux/macOS
source venv/bin/activate

Installa le Dipendenze:
```
pip install -r requirements.txt
```
Avvia l'Applicazione:
```
python -m markdownconverter
```

4. L'Interfaccia Utente

L'interfaccia principale è suddivisa in sezioni logiche per guidare l'utente attraverso il processo di conversione.

4.1. Profile & Source File

Questa è la sezione di partenza. Qui definisci il contesto del tuo lavoro.

Active Profile: Un menu a tendina per selezionare il profilo di conversione da utilizzare. Un profilo è un insieme di configurazioni che lega un template ai valori dei suoi placeholder.
Manage...: Apre la finestra di gestione dei profili, dove puoi creare, rinominare ed eliminare profili.
Markdown File: Il campo per selezionare il file sorgente .md che contiene il tuo contenuto.
Browse...: Apre una finestra di dialogo per cercare il file .md sul tuo computer.

4.2. Placeholders

Questo pannello è dinamico e rappresenta il cuore dell'applicazione. Una volta selezionato un profilo valido, questo pannello si popola automaticamente con tutti i placeholder (%%...%%) trovati nel template associato.

Placeholder Dinamici: Campi di testo modificabili dove inserire i valori (es. nome del progetto, numero di revisione).
Placeholder Strutturali: Campi di sola lettura (<Automatic>) che indicano i punti di ancoraggio per contenuti generati automaticamente, come la cronologia delle revisioni (%%REVISION_RECORD%%) e l'indice (%%DOC_TOC%%).

4.3. Opzioni

Add TOC: Se selezionata, verrà generato e inserito un Indice dei Contenuti (Table of Contents) nel documento finale.
Open Source Folder: Apre la cartella che contiene il file Markdown sorgente.

4.4. Conversion Actions

Questa sezione contiene i bottoni per eseguire le conversioni. Ogni azione ha un campo di testo che mostra il percorso di output proposto (modificabile) e un bottone "Open" per aprire il file generato.

MD → DOCX: Converte il file Markdown in un documento .docx usando il template e i valori del profilo attivo.
MD → PDF: Converte il file Markdown direttamente in un .pdf "pulito", senza usare il template DOCX.
DOCX → PDF: Converte il file .docx generato in un .pdf ad alta fedeltà. Questo bottone si attiva solo dopo una conversione MD → DOCX riuscita.

4.5. Log Viewer

Mostra in tempo reale i messaggi di log dell'applicazione, utile per monitorare il processo e diagnosticare eventuali problemi.

5. Flusso di Lavoro Consigliato

Crea un Template DOCX: Prepara un file .docx con la formattazione desiderata (stili, intestazioni, piè di pagina) e inserisci i placeholder nei punti appropriati (es. %%DOC_PROJECT%%). Non dimenticare di inserire i placeholder strutturali %%REVISION_RECORD%%, %%DOC_TOC%%, e %%DOC_CONTENT%%.
Crea un Profilo:
- Avvia l'applicazione e clicca su "Manage...".
- Nella finestra "Manage Profiles", clicca su "New...".
- Dai un nome descrittivo al profilo (es. "Manuale Prodotto Alpha").
- Seleziona il file template .docx che hai creato.
Lavora con il Profilo:
- Nella finestra principale, seleziona il tuo nuovo profilo dal menu a tendina "Active Profile".
- L'area "Placeholders" si popolerà automaticamente. Inserisci i valori per il tuo documento specifico.
- Seleziona il file .md che vuoi convertire.
- I percorsi di output verranno generati automaticamente, ma puoi modificarli se necessario.
Converti e Finalizza:
- Clicca "MD → DOCX". L'applicazione genererà il file .docx. I valori inseriti verranno salvati nel profilo per usi futuri.
- Clicca "Open" accanto al percorso del DOCX per aprirlo in Word o LibreOffice.
- Passo cruciale: Aggiorna l'indice dei contenuti (di solito cliccando con il destro sull'indice e scegliendo "Aggiorna campo"). Fai qualsiasi altra piccola modifica manuale necessaria e salva il file.
- Torna all'applicazione e clicca "DOCX → PDF". Questo creerà la versione PDF finale, identica al DOCX che hai appena revisionato.

6. Gestione dei Profili

La finestra "Manage Profiles" ti permette di:

New...: Creare un nuovo profilo, associandogli un nome e un template.
Rename...: Rinominare un profilo esistente senza perdere i valori salvati.
Delete: Rimuovere permanentemente un profilo. L'operazione richiederà una conferma.

6.0 KiB Raw Permalink Blame History