xsl-validator/docs/icon_and_version_info.md

# Icon und Versionsinformationen für Windows-Build

## Übersicht

DocuMentor unterstützt professionelle Windows-Builds mit:
- **Anwendungs-Icon** in allen benötigten Größen
- **Windows-Versionsinformationen** (Datei-Eigenschaften)
- Automatische Integration in Build-Prozess

## Icon-System

### Automatische Icon-Generierung

Das Build-Skript generiert automatisch ein Standard-Icon, falls keins vorhanden ist:

```bash
uv run python build_windows.py
```

Falls `resources/icon.ico` nicht existiert, wird automatisch ein Standard-Icon mit DocuMentor-Branding erstellt.

### Manuelles Icon erstellen

#### Option 1: Standard-Icon

```bash
uv run python create_icon.py
```

Erstellt ein einfaches Icon mit:
- Blauem Hintergrund (professionelles Blau: #2980B9)
- Weißem Dokument-Symbol
- "M" für Mentor (bei großen Icons)
- Umgeknickter Ecke
- Mehreren Größen (16×16 bis 256×256)

#### Option 2: Aus eigenem PNG

```bash
uv run python create_icon.py mein-logo.png
```

Konvertiert ein PNG-Bild zu einem Multi-Size Windows-Icon:
- Unterstützt Transparenz
- Erstellt alle benötigten Größen
- Optimiert für verschiedene Bildschirmauflösungen

**PNG-Anforderungen:**
- Idealerweise 256×256 Pixel oder größer
- Quadratisches Format
- PNG oder JPEG Format
- Transparenter Hintergrund empfohlen

### Icon-Größen

Das ICO-Format enthält folgende Auflösungen:

| Größe   | Verwendung                           |
|---------|--------------------------------------|
| 256×256 | Windows 7+, Taskleiste, große Icons  |
| 128×128 | Windows 7+, große Icons              |
| 64×64   | Hohe DPI-Displays                    |
| 48×48   | Standard Desktop-Icon                |
| 32×32   | Explorer Details-Ansicht             |
| 16×16   | Kleinstes Icon, Titelleiste          |

### Wo wird das Icon verwendet?

- **DocuMentor.exe** - Anwendungs-Icon
- **Setup.exe** - Installer-Icon (Inno Setup)
- **Desktop-Verknüpfung** - Erstellt beim Installieren
- **Start-Menü** - Windows-Programmgruppe
- **Taskleiste** - Beim Ausführen
- **Deinstallations-Programm** - System-Einstellungen

## Versionsinformationen

### Automatische Generierung

Versionsinformationen werden automatisch vom Build-Skript generiert:

```bash
uv run python build_windows.py
```

### Manuelle Generierung

```bash
uv run python create_version_info.py
```

### Inhalt der Versionsinformationen

Die `version_info.txt` enthält:

```
FileVersion:        0.1.0.0
ProductVersion:     0.1.0.0
CompanyName:        Ihr Name/Organisation
FileDescription:    Professionelle XSL-Transformations-Verwaltung und PDF-Generierung
InternalName:       DocuMentor
LegalCopyright:     © 2026 Ihr Name. Alle Rechte vorbehalten.
OriginalFilename:   DocuMentor.exe
ProductName:        DocuMentor
```

### Version aus pyproject.toml

Die Version wird automatisch aus `pyproject.toml` gelesen:

```toml
[project]
name = "DocuMentor"
version = "0.1.0"
description = "Professionelle XSL-Transformations-Verwaltung und PDF-Generierung"
```

### Version ändern

**Schritt 1:** Version in `pyproject.toml` ändern:

```toml
version = "0.2.0"
```

**Schritt 2:** Version in `installer.iss` ändern (Zeile 13):

```iss
#define MyAppVersion "0.2.0"
```

**Schritt 3:** Build neu ausführen:

```bash
uv run python build_windows.py
```

Die Versionsinformationen werden automatisch neu generiert.

### Versionsnummern-Schema

DocuMentor verwendet [Semantic Versioning](https://semver.org/lang/de/):

```
MAJOR.MINOR.PATCH

0.1.0 → Erste Beta-Version
1.0.0 → Erste stabile Version
1.1.0 → Neue Features
1.1.1 → Bugfixes
2.0.0 → Breaking Changes
```

### Windows-Eigenschaften anzeigen

Nach dem Build können Sie die Versionsinformationen in Windows anzeigen:

1. Rechtsklick auf `DocuMentor.exe`
2. **Eigenschaften** auswählen
3. Tab **Details** öffnen

Dort sehen Sie:
- Dateiversion
- Produktversion
- Beschreibung
- Copyright
- Produktname
- Original-Dateiname

## Integration in Build-Prozess

### DocuMentor.spec

```python
exe = EXE(
    # ...
    icon=str(project_root / 'resources' / 'icon.ico') if (project_root / 'resources' / 'icon.ico').exists() else None,
    version=str(project_root / 'version_info.txt') if (project_root / 'version_info.txt').exists() else None,
)
```

**Automatische Erkennung:**
- Icon wird verwendet, falls vorhanden
- Versionsinformationen werden verwendet, falls vorhanden
- Build funktioniert auch ohne Icon/Version (mit Warnung)

### installer.iss

```iss
SetupIconFile=dist\DocuMentor\icon.ico
UninstallDisplayIcon={app}\DocuMentor.exe
```

Das Icon wird automatisch vom `build_windows.py` nach `dist/DocuMentor/` kopiert.

## Anpassungen

### Company Name / Copyright

In `create_version_info.py` (Zeile ~65):

```python
StringStruct('CompanyName', 'Ihr Name/Organisation'),
StringStruct('LegalCopyright', '© {year} Ihr Name. Alle Rechte vorbehalten.'),
```

Ändern Sie "Ihr Name/Organisation" auf Ihren tatsächlichen Namen oder Firmennamen.

### Icon-Design

Falls Sie das Standard-Icon anpassen möchten, bearbeiten Sie `create_icon.py`:

**Farben ändern** (Zeile ~31):
```python
bg_color = (41, 128, 185)  # Blau - ändern Sie RGB-Werte
```

**Symbol ändern:**
- Bearbeiten Sie die `create_default_icon()` Funktion
- Oder erstellen Sie Ihr eigenes Icon in einem Grafikprogramm

## Best Practices

### Icon-Design

1. **Einfach und klar**: Funktioniert auch bei 16×16 Pixel
2. **Hoher Kontrast**: Gut lesbar auf hellem und dunklem Hintergrund
3. **Professionell**: Passend zum Business-Kontext
4. **Wiedererkennbar**: Symbolisiert die Anwendung

### Versionierung

1. **Semantische Versionierung**: MAJOR.MINOR.PATCH
2. **Vor jedem Release aktualisieren**
3. **Git-Tags verwenden**: `git tag v0.1.0`
4. **GUID beibehalten**: Nie die Inno Setup GUID ändern bei Updates!

## Troubleshooting

### Icon wird nicht angezeigt

**Problem**: DocuMentor.exe zeigt kein Icon

**Lösungen:**
1. Prüfen ob `resources/icon.ico` existiert
2. Build neu ausführen: `uv run python build_windows.py`
3. Windows Icon-Cache löschen und neu starten

### Versionsinformationen fehlen

**Problem**: Eigenschaften → Details zeigt keine Informationen

**Lösungen:**
1. Prüfen ob `version_info.txt` existiert
2. `uv run python create_version_info.py` ausführen
3. Build neu ausführen

### Pillow-Fehler beim Icon-Erstellen

**Problem**: `ImportError: No module named 'PIL'`

**Lösung:**
```bash
uv sync --all-groups
```

Dies installiert Pillow automatisch.

## Weiterführende Informationen

- **PyInstaller Icon-Dokumentation**: https://pyinstaller.org/en/stable/usage.html#icons
- **Windows ICO Format**: https://en.wikipedia.org/wiki/ICO_(file_format)
- **Semantic Versioning**: https://semver.org/lang/de/
- **Pillow Dokumentation**: https://pillow.readthedocs.io/