# 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

1.  **Clona il Repository**: Ottieni una copia locale del progetto dal server Gitea.
2.  **Crea un Ambiente Virtuale**: È una buona pratica isolare le dipendenze del progetto.
    ```bash
    python -m venv venv
    # Su Windows
    venv\Scripts\activate
    # Su Linux/macOS
    source venv/bin/activate
    ```
3.  **Installa le Dipendenze**:
    ```bash
    pip install -r requirements.txt
    ```
4.  **Avvia l'Applicazione**:
    ```bash
    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

1.  **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%%`.

2.  **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.

3.  **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.

4.  **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.