102 lines
6.0 KiB
Markdown
102 lines
6.0 KiB
Markdown
# 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.
|