update manual and readme

This commit is contained in:
VALLONGOL 2025-06-18 09:23:58 +02:00
parent dc4088b9e3
commit f3f2edae57
3 changed files with 329 additions and 49 deletions

148
README.md
View File

@ -1,16 +1,142 @@
# MarkdownConverter
# Markdown Converter
A brief description of MarkdownConverter.
<!-- Inserisci qui uno screenshot dell'applicazione in funzione -->
![App Screenshot](https://via.placeholder.com/800x600.png?text=Application+Screenshot)
## Features
- Feature 1
- Feature 2
Un'applicazione desktop per convertire file Markdown in documenti DOCX e PDF professionali, utilizzando un potente sistema di template e profili per automatizzare la creazione di documenti standardizzati.
## Getting Started
...
---
## Contributing
...
## ITALIANO
## License
...
### 🇮🇹 Panoramica
**Markdown Converter** è uno strumento progettato per semplificare e standardizzare la creazione di documenti tecnici e manuali. Invece di gestire manualmente la formattazione in un word processor, puoi scrivere i contenuti in semplice Markdown e lasciare che l'applicazione si occupi di applicare un template DOCX complesso, sostituendo dinamicamente i segnaposto (placeholder) con i valori specificati.
L'applicazione è costruita attorno a un **sistema di profili**, che permette di salvare diverse configurazioni (template + valori dei placeholder) per diversi progetti, massimizzando la riusabilità e riducendo gli errori.
### Caratteristiche Principali
* **Gestione a Profili:** Crea, rinomina ed elimina profili nominativi. Ogni profilo lega un set di valori a un template specifico, perfetto per gestire più progetti o clienti con lo stesso layout.
* **Scansione Dinamica dei Placeholder:** L'applicazione scansiona automaticamente il template `.docx` selezionato e genera dinamicamente i campi di input per ogni placeholder `%%PLACEHOLDER_NAME%%` trovato.
* **Placeholder Strutturali e Dinamici:** Distingue tra placeholder da riempire manualmente (es. `%%DOC_PROJECT%%`) e placeholder strutturali gestiti automaticamente (es. `%%REVISION_RECORD%%`, `%%DOC_TOC%%`), che vengono mostrati nella GUI a scopo informativo.
* **Triplo Percorso di Conversione:**
1. **MD → DOCX:** Converte il Markdown in un file DOCX formattato, usando il template e i valori del profilo.
2. **MD → PDF (Diretto):** Crea un PDF "pulito" direttamente dal Markdown, ideale per bozze rapide.
3. **DOCX → PDF (Alta Fedeltà):** Converte il file DOCX generato in un PDF. Questo permette una revisione manuale in Word/LibreOffice prima della "cristallizzazione" finale in PDF, garantendo la massima fedeltà del layout.
* **Rilevamento Automatico dei Convertitori:** Per la conversione DOCX → PDF, l'applicazione cerca prima Microsoft Word e, se non lo trova, ripiega automaticamente su LibreOffice.
* **Nomi File Dinamici:** Suggerisce nomi di file di output standardizzati e "sanificati" basati sui valori dei placeholder (progetto, numero, revisione, ecc.).
* **Persistenza dei Dati:** Salva l'ultimo profilo usato, l'ultimo file Markdown e tutti i valori inseriti per ogni profilo, rendendo il lavoro tra una sessione e l'altra più rapido ed efficiente.
### Installazione e Avvio
#### Prerequisiti
1. **Python 3.8+**
2. **Dipendenze esterne (per una funzionalità completa):**
* **wkhtmltopdf:** Necessario per la conversione diretta da Markdown a PDF. Assicurati che sia installato e, se non è nel PATH di sistema, il percorso è configurato nel codice (`core.py`).
* **Microsoft Word** o **LibreOffice:** Necessario per la conversione ad alta fedeltà da DOCX a PDF.
#### Setup
1. **Clona il repository:**
```bash
git clone <URL_DEL_TUO_REPOSITORY>
cd MarkdownConverter
```
2. **Crea un ambiente virtuale (raccomandato):**
```bash
python -m venv venv
source venv/bin/activate # Su Windows: venv\Scripts\activate
```
3. **Installa le librerie Python:**
```bash
pip install -r requirements.txt
```
*(Assicurati di creare un file `requirements.txt` con le seguenti librerie: `ttkbootstrap`, `pypandoc`, `python-docx`, `docx2pdf`, `pdfkit`, `markdown`)*
4. **Avvia l'applicazione:**
```bash
python -m markdownconverter
```
### Flusso di Lavoro Consigliato
1. **Crea un Profilo:** Clicca su "Manage..." e poi "New...". Assegna un nome al profilo (es. "Manuale Progetto X") e seleziona il file template `.docx` che vuoi associare.
2. **Seleziona il Profilo:** Scegli il profilo appena creato dal menu a tendina "Active Profile".
3. **Compila i Dati:** La GUI mostrerà automaticamente tutti i placeholder trovati nel template. Inserisci i valori desiderati.
4. **Seleziona il File Sorgente:** Seleziona il file `.md` da convertire.
5. **Converti:**
* Clicca **"MD -> DOCX"**. I valori che hai inserito verranno salvati automaticamente nel profilo.
* Apri il DOCX generato, aggiorna l'indice dei contenuti e fai le modifiche finali.
* Clicca **"DOCX -> PDF"** per creare il documento finale.
---
## ENGLISH
### 🇬🇧 Overview
**Markdown Converter** is a tool designed to simplify and standardize the creation of technical documents and manuals. Instead of manually handling formatting in a word processor, you can write content in plain Markdown and let the application apply a complex DOCX template, dynamically replacing placeholders with your specified values.
The application is built around a **profile system**, allowing you to save different configurations (template + placeholder values) for various projects, maximizing reusability and reducing errors.
### Key Features
* **Profile-based Management:** Create, rename, and delete named profiles. Each profile links a set of values to a specific template, perfect for managing multiple projects or clients with the same layout.
* **Dynamic Placeholder Scanning:** The application automatically scans the selected `.docx` template and dynamically generates input fields for every `%%PLACEHOLDER_NAME%%` it finds.
* **Structural & Dynamic Placeholders:** It distinguishes between manually-filled placeholders (e.g., `%%DOC_PROJECT%%`) and automatically-managed structural placeholders (e.g., `%%REVISION_RECORD%%`, `%%DOC_TOC%%`), which are displayed for informational purposes.
* **Triple Conversion Workflow:**
1. **MD → DOCX:** Converts Markdown to a fully formatted DOCX file using the profile's template and values.
2. **MD → PDF (Direct):** Creates a clean PDF directly from Markdown, ideal for quick drafts.
3. **DOCX → PDF (High-Fidelity):** Converts the generated DOCX file to a PDF. This allows for a final manual review in Word/LibreOffice before "freezing" the document, ensuring maximum layout fidelity.
* **Automatic Converter Detection:** For the DOCX → PDF conversion, the application first tries to use Microsoft Word and automatically falls back to LibreOffice if Word is not found.
* **Dynamic Filenames:** Suggests standardized and sanitized output filenames based on placeholder values (project, number, revision, etc.).
* **Data Persistence:** Saves the last-used profile, the last Markdown file, and all entered values for each profile, making work between sessions faster and more efficient.
### Installation & Setup
#### Prerequisites
1. **Python 3.8+**
2. **External Dependencies (for full functionality):**
* **wkhtmltopdf:** Required for the direct Markdown to PDF conversion. Ensure it's installed and, if not in the system PATH, its path is configured in the code (`core.py`).
* **Microsoft Word** or **LibreOffice:** Required for the high-fidelity DOCX to PDF conversion.
#### Setup
1. **Clone the repository:**
```bash
git clone <YOUR_REPOSITORY_URL>
cd MarkdownConverter
```
2. **Create a virtual environment (recommended):**
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
3. **Install Python libraries:**
```bash
pip install -r requirements.txt
```
*(Make sure to create a `requirements.txt` file containing at least: `ttkbootstrap`, `pypandoc`, `python-docx`, `docx2pdf`, `pdfkit`, `markdown`)*
4. **Run the application:**
```bash
python -m markdownconverter
```
### Recommended Workflow
1. **Create a Profile:** Click "Manage..." and then "New...". Give the profile a name (e.g., "Project X Manual") and select the associated `.docx` template file.
2. **Select the Profile:** Choose the newly created profile from the "Active Profile" dropdown menu.
3. **Fill in the Data:** The GUI will automatically display all placeholders found in the template. Fill in the desired values.
4. **Select the Source File:** Choose the `.md` file you want to convert.
5. **Convert:**
* Click **"MD -> DOCX"**. The values you entered will be automatically saved to the profile.
* Open the generated DOCX, update the table of contents, and make any final manual adjustments.
* Click **"DOCX -> PDF"** to create the final, polished document.

View File

@ -1,24 +1,101 @@
# MarkdownConverter - English Manual
# Markdown Converter - User Manual
## Introduction
Welcome to MarkdownConverter. This document provides an overview of how to install, use, and understand the project.
## 1. Overview and Purpose
## Installation
Describe the installation steps here. For example:
1. Clone the repository: `git clone <repository_url>`
2. Navigate to the project directory: `cd MarkdownConverter`
3. Install dependencies: `pip install -r requirements.txt` (if applicable)
**Markdown Converter** is a desktop application designed to automate and standardize the creation of professional documents. It allows users to write content in the simple and clean Markdown format and convert it into beautifully formatted `.docx` and `.pdf` documents, using an advanced template and profile system.
## Usage
Explain how to run and use the application.
- To run the application: `python -m markdownconverter`
- Command-line arguments (if any).
- GUI interaction (if any).
The main goal is to eliminate the need for manual, repetitive formatting in a word processor, ensuring consistency across documents and speeding up the workflow, especially for technical documentation, user manuals, and reports.
## Development
Information for developers contributing to the project.
- Code structure.
- How to run tests.
## 2. System Requirements
## Troubleshooting
Common issues and their solutions.
To use all the application's features, ensure the following components are present on your system:
* **Python 3.8+**: Required to run the application.
* **wkhtmltopdf**: Essential for the direct Markdown to PDF conversion. It must be installed and preferably added to the system's PATH.
* **Microsoft Word** OR **LibreOffice**: At least one of these software packages is required for the high-fidelity conversion from `.docx` to `.pdf`. The application will automatically detect which software is available.
## 3. Installation and Launch
1. **Clone the Repository**: Get a local copy of the project from the Gitea server.
2. **Create a Virtual Environment**: It is good practice to isolate the project's dependencies.
```bash
python -m venv venv
# On Windows
venv\Scripts\activate
# On Linux/macOS
source venv/bin/activate
```
3. **Install Dependencies**:
```bash
pip install -r requirements.txt
```
4. **Run the Application**:
```bash
python -m markdownconverter
```
## 4. The User Interface
The main interface is divided into logical sections to guide the user through the conversion process.
### 4.1. Profile & Source File
This is the starting section where you define the context of your work.
* **Active Profile**: A dropdown menu to select the conversion profile to use. A profile is a set of configurations that links a template to its placeholder values.
* **Manage...**: Opens the profile management window, where you can create, rename, and delete profiles.
* **Markdown File**: The field to select the source `.md` file containing your content.
* **Browse...**: Opens a dialog to browse for the `.md` file on your computer.
### 4.2. Placeholders
This panel is **dynamic** and represents the core of the application. Once a valid profile is selected, this panel automatically populates with all placeholders (`%%...%%`) found in the associated template.
* **Dynamic Placeholders**: Editable text fields where you enter values (e.g., project name, revision number).
* **Structural Placeholders**: Read-only fields (`<Automatic>`) indicating anchor points for auto-generated content, such as the revision history (`%%REVISION_RECORD%%`) and the table of contents (`%%DOC_TOC%%`).
### 4.3. Options
* **Add TOC**: If checked, a Table of Contents will be generated and inserted into the final document.
* **Open Source Folder**: Opens the folder containing the source Markdown file.
### 4.4. Conversion Actions
This section contains the buttons to perform conversions. Each action has a text field showing the proposed output path (which can be edited) and an "Open" button to open the generated file.
* **MD → DOCX**: Converts the Markdown file into a `.docx` document using the active profile's template and values.
* **MD → PDF**: Converts the Markdown file directly into a clean `.pdf`, without using the DOCX template.
* **DOCX → PDF**: Converts the generated `.docx` file into a high-fidelity `.pdf`. This button is enabled only after a successful MD → DOCX conversion.
### 4.5. Log Viewer
Displays real-time log messages from the application, which is useful for monitoring the process and diagnosing any issues.
## 5. Recommended Workflow
1. **Create a DOCX Template**: Prepare a `.docx` file with your desired formatting (styles, headers, footers) and insert placeholders at the appropriate locations (e.g., `%%DOC_PROJECT%%`). Don't forget to include the structural placeholders `%%REVISION_RECORD%%`, `%%DOC_TOC%%`, and `%%DOC_CONTENT%%`.
2. **Create a Profile**:
* Launch the application and click **"Manage..."**.
* In the "Manage Profiles" window, click **"New..."**.
* Give the profile a descriptive name (e.g., "Product Alpha Manual").
* Select the `.docx` template file you created.
3. **Work with the Profile**:
* In the main window, select your new profile from the **"Active Profile"** dropdown.
* The "Placeholders" area will populate automatically. Fill in the values for your specific document.
* Select the `.md` file you want to convert.
* The output paths will be generated automatically, but you can edit them if needed.
4. **Convert and Finalize**:
* Click **"MD → DOCX"**. The application will generate the `.docx` file. The values you entered will be saved to the profile for future use.
* Click "Open" next to the DOCX path to open it in Word or LibreOffice.
* **Crucial Step:** Update the table of contents (usually by right-clicking it and selecting "Update Field"). Make any other minor manual adjustments and save the file.
* Return to the application and click **"DOCX → PDF"**. This will create the final PDF version, identical to the DOCX you just reviewed.
## 6. Profile Management
The **"Manage Profiles"** window allows you to:
* **New...**: Create a new profile, associating it with a name and a template.
* **Rename...**: Rename an existing profile without losing its saved values.
* **Delete**: Permanently remove a profile. This action will require confirmation.

View File

@ -1,24 +1,101 @@
# MarkdownConverter - Manuale Italiano
# Markdown Converter - Manuale Utente
## Introduzione
Benvenuto in MarkdownConverter. Questo documento fornisce una panoramica su come installare, utilizzare e comprendere il progetto.
## 1. Panoramica e Scopo
## Installazione
Descrivi i passaggi di installazione qui. Ad esempio:
1. Clona il repository: `git clone <repository_url>`
2. Naviga nella directory del progetto: `cd MarkdownConverter`
3. Installa le dipendenze: `pip install -r requirements.txt` (se applicabile)
**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.
## Utilizzo
Spiega come eseguire e utilizzare l'applicazione.
- Per eseguire l'applicazione: `python -m markdownconverter`
- Argomenti da riga di comando (se presenti).
- Interazione con la GUI (se presente).
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.
## Sviluppo
Informazioni per gli sviluppatori che contribuiscono al progetto.
- Struttura del codice.
- Come eseguire i test.
## 2. Requisiti di Sistema
## Risoluzione dei problemi
Problemi comuni e relative soluzioni.
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.