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:

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

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

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:

uv run python build_windows.py

Manuelle Generierung

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:

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

Version ändern

Schritt 1: Version in pyproject.toml ändern:

version = "0.2.0"

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

#define MyAppVersion "0.2.0"

Schritt 3: Build neu ausführen:

uv run python build_windows.py

Die Versionsinformationen werden automatisch neu generiert.

Versionsnummern-Schema

DocuMentor verwendet Semantic Versioning:

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

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

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):

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):

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:

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/