Restructure README with OS install and standalone guidance

2026-03-02 18:03:21 +01:00
parent 1bb8820cf1
commit 54516a315a
1 changed files with 83 additions and 185 deletions
--- a/README.md
+++ b/README.md
@@ -1,153 +1,114 @@
 # PDF zu ICS Konverter - Dienstplan Importer

-Dieses Tool extrahiert Kalenderdaten aus Dienstplan-PDFs und konvertiert sie in das iCalendar-Format (ICS), das von den meisten Kalenderanwendungen importiert werden kann.
+Dieses Tool extrahiert Kalenderdaten aus Dienstplan-PDFs und konvertiert sie in das iCalendar-Format (ICS), das in gängigen Kalender-Apps importiert werden kann.

-## 🎯 Zwei Versionen verfügbar
+## 🎯 Varianten

-### 1. **GUI-Version** (Grafische Oberfläche) - Empfohlen!
-Benutzerfreundliche grafische Oberfläche mit Drag & Drop Support.
+### 1) GUI (empfohlen)
+Native Oberfläche mit wxPython:

 ```bash
 ./start_gui.sh
 ```

-**Features:**
- ✨ Drag & Drop für PDF-Dateien
- 📋 Mehrere PDFs gleichzeitig verarbeiten
- 📁 Ausgabe-Verzeichnis frei wählbar
- 📊 Live-Log und Fortschrittsanzeige
- 💾 Merkt sich letzte Verzeichnisse
+**Highlights:**
+- Drag & Drop für PDFs
+- Mehrere PDFs gleichzeitig
+- Frei wählbares Ausgabe-Verzeichnis
+- Live-Log mit Fortschritt
+- Optionale Filter:
+  - Ruhetage ausschließen
+  - Urlaub (060/0060) ausschließen

-**Voraussetzung:** wxPython muss installiert sein (wird automatisch versucht; siehe [WXPYTHON_README.md](WXPYTHON_README.md))
-
-### 2. **CLI-Version** (Kommandozeile)
-Textbasiertes Menü für die Kommandozeile.
+### 2) CLI
+Interaktives Textmenü:

 ```bash
 ./start.sh
 ```

-**Features:**
- ⚡ Funktioniert überall ohne zusätzliche Abhängigkeiten
- 🔄 Automatische Verarbeitung aller PDFs im Verzeichnis
- 📝 Textbasiertes interaktives Menü
+---

-## Features
+## ⚡ Schnellstart (60 Sekunden)

-✅ Extrahiert Dienstplan-Informationen aus PDFs
-✅ Erkennt Schicht-Zeitangaben (z.B. 04:51-15:46)
-✅ Handhabt Nachtschichten korrekt (über Mitternacht hinaus)
-✅ Erstellt Standard-konforme ICS-Dateien
-✅ Unterstützt mehrere PDFs gleichzeitig
-✅ GUI mit Drag & Drop (optional)
-✅ CLI-Menü für schnelle Nutzung
+1. GUI starten (`./start_gui.sh` oder `start_gui.cmd` unter Windows)
+2. PDF-Dateien hinzufügen
+3. Optional Filter aktivieren
+4. Auf **"ICS Datei erstellen"** klicken

-## Installation
-### Windows (Empfohlen)
+---

-1. Installieren Sie **Python 3.10+** und aktivieren Sie bei der Installation die Option **"Add Python to PATH"**.
-2. Öffnen Sie den Projektordner.
-3. Starten Sie die GUI per Doppelklick auf `start_gui.cmd`.
+## 🧩 Installation nach Betriebssystem

-Beim ersten Start wird automatisch eine virtuelle Umgebung (`.venv`) erstellt und alle benötigten Pakete installiert.
+### Linux (Ubuntu/Debian/Mint)

-**Alternative (CLI):** Doppelklick auf `start.cmd`.
-
-**Falls Python nicht gefunden wird (CMD im Projektordner):**
-
-```bat
-py -3 -m venv .venv --upgrade-deps
-.\.venv\Scripts\python.exe gui_wxpython.py
-```
-
-### Schnellstart (Empfohlen)
-
-**Für GUI-Version:**
 ```bash
 ./start_gui.sh
 ```
-Siehe [WXPYTHON_README.md](WXPYTHON_README.md) für wxPython-Hinweise.

-**Für CLI-Version:**
+Beim ersten Start wird automatisch `.venv` erstellt und alles installiert.
+
+Wenn `wxPython` nicht installiert werden kann, helfen häufig:
+
 ```bash
-./start.sh
+sudo apt-get update
+sudo apt-get install -y build-essential python3-dev libgtk-3-dev libglib2.0-dev libjpeg-dev libtiff-dev libpng-dev
 ```

-### GUI-Version (Empfohlen)
+Für systemweite Installation mit Menüeintrag siehe [INSTALL.md](INSTALL.md).
+
+### macOS

-1. Starten Sie die GUI:
 ```bash
 ./start_gui.sh
 ```
-2. Fügen Sie PDF-Dateien hinzu (Button oder Drag & Drop).
-3. Optional: Aktivieren Sie Filter wie „Ruhetage ausschließen“ und „Urlaub ausschließen (060, 0060)“.
-4. Klicken Sie auf „📄 ICS Datei erstellen“.

-Die GUI merkt sich Ihre letzten Verzeichnisse und Exportoptionen.
+Beim ersten Start wird `.venv` erstellt und die Abhängigkeiten werden installiert.

-### CLI-Version
+### Windows

-Starten Sie das interaktive Menü:
+1. Python 3.10+ installieren (Option **Add Python to PATH** aktivieren)
+2. `start_gui.cmd` per Doppelklick starten

-```bash
-./start.sh
-```
+Beim ersten Start wird `.venv` automatisch eingerichtet.

-Beide Skripte erstellen automatisch eine Python Virtual Environment und installieren alle benötigten Abhängigkeiten.
+---

-### Manuelle Installation
+## 🧱 Standalone-Apps (ohne Python beim Endnutzer)

+Für Build/Packaging auf Linux, macOS und Windows:

-Die erforderlichen Dependencies sind bereits installiert. Falls Sie das Projekt neu einrichten:
+- [BUILD_STANDALONE.md](BUILD_STANDALONE.md)

-```bash
-python3 -m venv .venv
-source .venv/bin/activate
-pip install pdfplumber icalendar pypdf2 pytz packaging
-```
+Dort enthalten:
+- Build-Skripte pro OS
+- Packaging-Skripte für Release-Artefakte
+- empfohlene Release-Reihenfolge

-## Verwendung
+---

-### Schnellstart (CLI)
+## 🖥️ CLI-Nutzung

-1. Kopieren Sie Ihre Dienstplan-PDF-Dateien in ein Verzeichnis
-2. Führen Sie das Skript aus:
-
-```bash
-python3 pdf_to_ics.py
-```
-
-Das Tool findet automatisch alle `.pdf` Dateien im aktuellen Verzeichnis und erstellt entsprechende `.ics` Dateien.
-
-### Kommandozeilen-Optionen
+### Beispiele

 ```bash
 # Alle PDFs im aktuellen Verzeichnis konvertieren
 python3 pdf_to_ics.py

-# PDFs aus einem bestimmten Verzeichnis konvertieren
-python3 pdf_to_ics.py --input ./pdfs
-
-# PDFs in anderes Verzeichnis speichern
+# Input/Output-Verzeichnis setzen
 python3 pdf_to_ics.py --input ./pdfs --output ./ics_dateien

 # Ruhetage ausschließen
 python3 pdf_to_ics.py --exclude-rest

-# Urlaub (060) ausschließen
+# Urlaub (060/0060) ausschließen
 python3 pdf_to_ics.py --exclude-vacation

-# Einzelne PDF-Datei konvertieren
+# Einzelne PDF-Datei
 python3 pdf_to_ics.py /pfad/zur/datei.pdf
-
-# Mit detaillierter Ausgabe
-python3 pdf_to_ics.py --input ./pdfs -v
-
-# Hilfe anzeigen
-python3 pdf_to_ics.py --help
 ```

-**Verfügbare Optionen:**
+### Optionen

 | Option | Kurzform | Beschreibung |
 |--------|----------|-------------|
@@ -155,106 +116,43 @@ python3 pdf_to_ics.py --help
 | `--output DIR` | `-o` | Ausgabe-Verzeichnis für ICS-Dateien (Standard: Eingabe-Verzeichnis) |
 | `--exclude-rest` | `-e` | Ruhetage ausschließen (Ruhe, R56, R36, vRWF48, RWE, vR48) |
 | `--exclude-vacation` | `-u` | Urlaub ausschließen (060, 0060) |
-| `--verbose` | `-v` | Detaillierte Ausgabe anzeigen |
+| `--verbose` | `-v` | Detaillierte Ausgabe |
 | `--help` | `-h` | Hilfe anzeigen |

-### Erweiterte Nutzung
+---

-Sie können auch direkt mit dem Python-Modul arbeiten:
+## 📅 ICS-Import

-```python
-from pdf_to_ics import extract_dienstplan_data, create_ics_from_dienstplan
+Die erzeugten `.ics`-Dateien lassen sich u. a. in folgende Kalender importieren:
+- Outlook
+- Google Kalender
+- Apple Kalender
+- Thunderbird
+- LibreOffice
+- Android-Kalender-Apps

-# PDF verarbeiten
-dienstplan = extract_dienstplan_data('meine_pdf.pdf')
+---

-# ICS erstellen
-create_ics_from_dienstplan(dienstplan, 'mein_kalender.ics')
+## 🛠️ Fehlerbehebung
+
+- **Keine Events gefunden:** PDF-Layout prüfen
+- **GUI startet nicht:** `.venv` löschen und neu starten
+  ```bash
+  rm -rf .venv
+  ./start_gui.sh
  ```
-
-## Dateiformat
-
-### ICS-Datei importieren
-
-Die erstellte `.ics` Datei kann in folgende Kalenderanwendungen importiert werden:
-
- **Outlook**: Datei → Öffnen und exportieren → Importieren
- **Google Kalender**: Einstellungen → Kalender importieren
- **iCal/macOS**: Doppelklick auf die .ics Datei
- **Thunderbird**: Kalender → Kalender importieren
- **Android**: Mit einer Kalender-App öffnen
- **LibreOffice**: Datei → Öffnen
-
-## Struktur der extrahierten Daten
-
-Das Tool extrahiert folgende Informationen aus der PDF:
-
- **Name und Personalnummer**: Des Mitarbeiters
- **Betriebshof**: Standort
- **Sollarbeitszeit**: Gewünschte Arbeitszeit pro Monat
- **Events**: Einzelne Schichten mit:
-  - Datum
-  - Dienstart (z.B. "36234", "Ruhe", "Dispo")
-  - Zeitangabe (falls vorhanden)
-
-## Output
-
-Für jede verarbeitete PDF wird eine entsprechende ICS-Datei erstellt:
-
-```
-2026-02-23 DB Köhler00100718_März2026.pdf  →  2026-02-23 DB Köhler00100718_März2026.ics
-```
-
-Die ICS-Datei enthält ein Event für jeden Arbeitstag mit:
- **Titel**: Name - Dienstart
- **Beschreibung**: Dienstart und Betriebshof
- **Zeit**: Mit aktueller Zeitzone (Europe/Berlin)
-
-## Fehlerbehebung
-
-### Keine Events gefunden?
- Stellen Sie sicher, dass die PDF das erwartete Tabellenformat hat
- Überprüfen Sie die Dateiname und die PDF-Struktur
-
-### Zeitzone falsch?
- Die aktuelle Einstellung ist Europe/Berlin
- Zum Ändern: Bearbeiten Sie die Zeile in `pdf_to_ics.py`:
-  ```python
-  tz = pytz.timezone('Europe/Berlin')  # Ändern SIe diesen Wert
-  ```
-
-## Technische Details
-
-### Projektstruktur
-
-```
-ICS-Import/
-├── pdf_to_ics.py          # Core-Konvertierungslogik
-├── gui_wxpython.py        # GUI-Version (wxPython)
-├── menu.py                # CLI-Menü
-├── start_gui.sh/cmd       # GUI-Startskripte
-├── start.sh/cmd           # CLI-Startskripte
-├── README.md              # Diese Datei
-└── WXPYTHON_README.md     # GUI-spezifische Dokumentation
-```
-
-### Technische Spezifikationen
-
- **Abhängigkeiten**: pdfplumber, icalendar, pytz, pypdf2, packaging
- **Optional für GUI**: wxPython (native Oberfläche)
- **Python-Version**: 3.6+
- **Format**: iCalendar 2.0 (RFC 5545)
- **Konfiguration**: `~/.pdf_to_ics_config.json` (GUI-Einstellungen)
-
-## Lizenz
-
-Dieses Tool ist zur privaten Verwendung gedacht.
+- **Zeitzone ändern:** in `pdf_to_ics.py` den Wert `Europe/Berlin` anpassen

 ---

 ## 📚 Weitere Dokumentation

- **[WXPYTHON_README.md](WXPYTHON_README.md)** - Ausführliche GUI-Dokumentation und wxPython-Hinweise
- **[BUILD_STANDALONE.md](BUILD_STANDALONE.md)** - Standalone-Builds für Linux, macOS und Windows
- **[QUICKSTART.md](QUICKSTART.md)** - Schnellanleitung für den Import in verschiedene Kalender
- **[ZUSAMMENFASSUNG.md](ZUSAMMENFASSUNG.md)** - Projekt-Übersicht und technische Details
+- [INSTALL.md](INSTALL.md) - Linux-Installation mit Menüeintrag
+- [WXPYTHON_README.md](WXPYTHON_README.md) - wxPython-spezifische Hinweise
+- [BUILD_STANDALONE.md](BUILD_STANDALONE.md) - Standalone-Builds/Packaging
+- [QUICKSTART.md](QUICKSTART.md) - Kurzanleitung Kalender-Import
+- [ZUSAMMENFASSUNG.md](ZUSAMMENFASSUNG.md) - Projekt- und Changelog-Übersicht
+
+## Lizenz
+
+Dieses Tool ist zur privaten Verwendung gedacht.