docu_build/doc/plan_fortna_extraktion.md

# Konzept: Fortna-Extraktion nach chapters/ + Projektordner fortna/

Status: **Umgesetzt** (erster vollständiger Durchlauf inkl. PDF-Build). Antworten aus der
Rückfragerunde sind eingearbeitet (siehe Abschnitt "Entscheidungen"). Der tatsächliche
Ist-Stand ist unten unter "Umsetzung / Ist-Stand" dokumentiert.

## Umsetzung / Ist-Stand

Implementiert wurden vier Python-Skripte in `lib/` mit `bin/`-Wrappern (`.bat` + `.sh`):

| Skript | Zweck | Wrapper |
|---|---|---|
| `lib/fortna_inventory.py` | Scannt das Rohmaterial, ordnet jede Datei Sprache + Zielkapitel + Aktion zu, schreibt `results/fortna_inventory.json`. | `bin/fortna_inventory.*` |
| `lib/fortna_convert_chapters.py` | Volltext+Bilder für die 5 DE-Hauptanleitungen, Verzeichnislisten (`index.de.rst`) für alle übrigen Kapitel. `--dry-run` (Default) / `--apply`. | `bin/fortna_convert_chapters.*` |
| `lib/fortna_init_project.py` | Legt `projekte/fortna/` an (`anlage.json`, `overrides/`, `images/`, `README.md`). | `bin/fortna_init_project.*` |
| `lib/build_index.py` | Generiert `index.rst` mit toctrees aus allen `chapters/**/*.de.rst`. | (in `build_pdf.*`) |
| `bin/build_pdf.*` | Kompletter PDF-Build: index → `sphinx-build -b latex` → `latexmk -lualatex`. | — |

Ergebnis des ersten Laufs:

- 5 Hauptanleitungen volltextig konvertiert (Betriebs-/Wartungsanleitung, Funktionsbeschreibung
  ILS/OMNIFLO/LoadingLoop), zusammen ~13.500 Textblöcke + mehrere Hundert entduplizierte Bilder.
- 9 Verzeichnislisten erzeugt (Zertifikate, Lieferantendoku nach Gewerk, Notstopp, Prüfberichte).
- `projekte/fortna/` mit `anlage.json`-Platzhalter angelegt.
- **Vollständiger PDF-Build erfolgreich**: `_build/latex/Fortna_Dokumentation_DE.pdf`, ~670 Seiten,
  `latexmk`-Exit 0, keine LaTeX-Fehler.

### Umgebung / Build-Voraussetzungen (bereits erfüllt)

- Sphinx 9.1.0 + myst-parser 5.1.0 im `.venv` (ergänzt in `requirements.txt`).
- LaTeX: MiKTeX unter `C:\Program Files\MiKTeX\` (lualatex/latexmk vorhanden).
- `conf.py` erzeugt: LaTeX-Engine **lualatex**, **babel** statt polyglossia
  (polyglossia 2.13 wirft unter lualatex einen bidi-Fehler), **`iconpackage=none`**
  (FontAwesome7 in MiKTeX bricht unter lualatex ab). Beides in `conf.py` kommentiert.

### Extraktion: neues Modul `lib/pdf_extract.py`

Die Volltext-Konvertierung der 5 Hauptanleitungen läuft über das neue Modul
`lib/pdf_extract.py` (`extract_manual()`), das gegenüber der ersten Version deutlich
sauberere `.rst` erzeugt:

- **Keine doppelte Nummerierung mehr:** Die im PDF vorhandene Gliederungsnummer
  (z. B. „1.7 Wichtige Informationen") wird nur zur Bestimmung der Überschriften-Ebene
  ausgewertet und im RST-Text **entfernt**. Sphinx/LaTeX nummeriert selbst → vorher
  „3.2.1  1.1 Wichtige Informationen", jetzt nur noch „3.2.1 Wichtige Informationen".
- **Überschriften-Erkennung** nur bei führender PDF-Gliederungsnummer (kein „fett allein"),
  damit Tabellenzellen nicht fälschlich zu Überschriften werden.
- **Bilder positionsbasiert extrahiert und referenziert:** pro Seite werden Text und Bilder
  nach Y-Position verwoben; jedes Bild wird als `.. figure::` mit korrektem Pfad und – falls
  vorhanden – der folgenden „Abbildung N: …"-Zeile als Caption eingebaut. (625 figure-Refs,
  0 fehlende Bilddateien.) Duplikate werden per MD5 entfernt, Titelseiten-Deko und
  Vollseiten-Hintergründe herausgefiltert.
- **Symbole/Warnzeichen zentral:** Kleine (≤ 260 px), mehrfach vorkommende Bilder (Warndreiecke,
  Piktogramme) werden per Perceptual-Hash (aHash + Hamming-Distanz ≤ 6) erkannt, **einmal** zentral
  nach `assets/shared/symbols/symbol_<hash>.png` abgelegt und im RST als `.. image::` (12 mm,
  zentriert) auf die eine Quelle verwiesen – dokumentübergreifend. Vorher lag dasselbe Warndreieck
  z. B. 8× als `img_003/018/020/025/026/031/035…` in einem einzigen Kapitel. Auch großformatige
  Inhaltsbild-Duplikate werden über den aHash zusammengeführt (nur einmal abgelegt, mehrfach
  referenziert). Wirkung: omniflo-`images/` von 83 → 62, Warndreieck 1× statt 58× gespeichert.
- **Fragment-„Überschriften" unterdrückt:** Bildlegenden/Tabellenzellen mit führender Nummer
  („POS", „li.", „re.", „bar, max. 10 bar") werden nicht mehr als Überschrift gesetzt.
- **Fließtext zu Absätzen zusammengeführt:** PDF-Zeilenumbrüche werden nicht mehr zu je einem
  Absatz; zusammenhängende Zeilen bilden einen Absatz, Satzende beendet ihn.
- **Aufzählungen als RST-Listen:** einzeln stehende Bullet-Zeichen werden mit der Folgezeile
  zusammengeführt, in eine Zeile zusammengelaufene Bullets aufgesplittet → `-`-Listenpunkte.
- **Änderungshistorie-/Dokumentinfo-Tabellen** am Dokumentanfang werden übersprungen (zerfielen
  vorher in sinnlose Einzelzellen), ebenso Inhaltsverzeichnis-Seiten und Kopf-/Fußzeilen.

### Behobene Extraktionsprobleme

- **Symbolfont-Zeichen** (Wingdings/Symbol Private-Use-Area, z. B. Aufzählungs-Bullet U+F0B7):
  via `clean_pua()` auf echte Unicode-Zeichen (•, →, ✓) gemappt, restliche PUA-Zeichen entfernt.
  Vorher erschienen leere Kästchen im PDF. (In `lib/pdf_extract.py`; die Variante in
  `extract_products.py` bleibt für die Produktprogramm-Extraktion bestehen.)
- **Fremd-Altdateien** aus früheren `convert_to_rst.py`-Testläufen (NORD-Getriebe/-Motor im
  Anhang, alte Risikobewertung/Contents/Konfig/Ersatzteile-Volltexte) wurden entfernt; die
  betroffenen Kapitel liegen konzeptkonform als Verzeichnisliste vor.

### Bekannte Restpunkte (nicht Teil des Auftrags-Scopes)

- Zwei **Fremd-Altdateien** aus früheren `convert_to_rst.py`-Testläufen sind noch im Baum und
  vom Build ausgeschlossen (`conf.py` + `build_index.py` SKIP-Liste):
  `02_sicherheit/risikobewertung/rb_fortna_...de.rst` (unvollständiger Bildbestand) und
  `00_inhaltsverzeichnis/contens_obsah_...de.rst` (keine RST-Überschrift). Zwei weitere
  Altdateien in `10_anhang/` (Motor/Getriebe) sind noch im toctree und zeigen typische
  Extraktionsartefakte – bei Bedarf mit `fortna_convert_chapters.py` sauber neu erzeugen.
- **Tabellen** (z. B. Änderungshistorie) werden weiterhin als Einzelzeilen extrahiert, nicht als
  RST-Tabelle rekonstruiert (wie im Konzept angekündigt).

---


## Ausgangslage

- Reales Fortna-Rohmaterial liegt in `c:\10-Develop\projekte\Fortna\` (zusätzliches
  Arbeitsverzeichnis dieser Session, **nicht** im Repo). Struktur wie in `doc/Fortna.txt`
  dokumentiert (00_CONTENTS_NOTES … 05_SUPPLIER_DOC), Versionsstände dort sind aktueller als in
  `doc/Fortna.txt` (z. B. Betriebsanleitung V2.4 statt V2.3, Wartungsanleitung V2.3, ILS V2.2,
  OMNIFLO V1.1, LoadingLoop V2.3). `doc/Fortna.txt`/`doc/Fortna-size.txt` sind nur noch als
  Struktur-Referenz zu verstehen, nicht als Quelle für den Extraktionslauf.
- `chapters/` (Base-Repo-Gerüst) existiert bereits vollständig mit `.gitkeep`-Platzhaltern gemäß
  `doc/kapitelstruktur.md`. `06_steuerung/loading_loop/` wurde testweise mit `convert_to_rst.py`
  aus der LoadingLoop-Word-Datei befüllt (2 RST + 74 Bilder). Qualität ist noch unzureichend:
  Kopf-/Fußzeilen (Firmenadresse, Kontaktdaten) landen als normale Absätze im Fließtext,
  Tabellen (Änderungshistorie) werden zu einzelnen Zeilen ohne Tabellenstruktur zerlegt. Das ist
  ein bekanntes Problem der aktuellen `_html_to_blocks`-Logik in `convert_to_rst.py` und wird im
  Zuge dieser Arbeit mit adressiert (siehe Abschnitt "Bekannte Schwachstellen").
- Vorhandene Skripte in `lib/` (siehe `doc/lib_skripte.md`):
  - `convert_to_rst.py`: `.docx`/Word-PDF → RST, erkennt Zielkapitel nur anhand Dateiname-Pattern
    im Root eines Ordners, kein Verständnis für den verschachtelten Fortna-Sprachordner-Baum.
  - `extract_products.py`: Produktprogramm-PDFs → Bilder + RST (bereits fertig genutzt für
    `data/Produktprogramm`).
  - `jsonFromXlsx.py`, `extract_ids.py`, `project_from_xlsx.py`: Stücklisten-Auswertung, für
    diese Aufgabe nicht direkt relevant.
- Kein Skript kennt bisher die komplette Fortna-Ordnerstruktur (Lieferantendoku-Baum, Layouts,
  Schaltpläne, Prüfberichte) und keines erzeugt den projektspezifischen Ordner (`anlage.json`,
  `overrides/`, `images/`) gemäß `doc/Kernkonzepte.md`.

## Entscheidungen (aus Rückfragen)

| Frage | Entscheidung |
|---|---|
| Lieferantendoku (~250 PDFs: SEW, Siemens, Leuze, Cognex, MiTek, Aventics, …) | **Nur Verzeichnisliste**, keine Kopie. RST-Referenztabelle mit Pfaden auf das Originalverzeichnis. |
| Sonstige PDFs (Zertifikate, Konfigurationsbeschreibung, Layouts, Schaltpläne, Notstopp/Bereichsstopp, Prüfberichte, Ersatzteilliste) | Gleiche Behandlung wie Lieferantendoku: **nur Verzeichnisliste**, keine Kopie nach `chapters/`. |
| Volltext-Konvertierung (Text + Bilder → RST) | **Nur die 5 Hauptanleitungen**: Betriebsanleitung, Wartungsanleitung, Funktionsbeschreibung ILS, Funktionsbeschreibung OMNIFLO, Funktionsbeschreibung LoadingLoop. |
| Projektordner-Ort | `projekte/fortna/` **innerhalb dieses Repos** (docu_build), pragmatisch für jetzt; spätere Auslagerung in eigenes Repo bleibt möglich. |
| Sprachumfang | **Nur Deutsch** in diesem Durchlauf. Namenskonvention `{name}.de.rst` einhalten, EN/CZ als späterer zweiter Durchlauf vorgesehen. |
| Quelle | `c:\10-Develop\projekte\Fortna\` (aktueller Stand), nicht `doc/Fortna.txt`. |
| Umgang mit bestehendem `chapters/06_steuerung/loading_loop/` | **Überschreiben/neu erzeugen** – konsistent aus einem Guss statt Altbestand stehen lassen. |

## Zielstruktur (Ergebnis nach Lauf)

```text
chapters/
  01_zertifikate/
    konformitaetserklaerung/index.de.rst        # Verzeichnisliste -> Originalpfade
    konfigurationsbeschreibung/index.de.rst
  02_sicherheit/                                  # unverändert (kein Fortna-Rohmaterial 1:1 zuordenbar)
  03_anlagenbeschreibung/                         # unverändert (Modul-Mechanismus, nicht Teil dieser Aufgabe)
  04_betrieb/betriebsanleitung/
    betriebsanleitung_500592_135776_v2_4.de.rst   # Volltext + Bilder
    images/img_001.png ...
  05_wartung/wartungsanleitung/
    wartungsanleitung_500592_v2_3.de.rst          # Volltext + Bilder
    images/...
  06_steuerung/
    ils/funktion_steuerung_ils_500592_v2_2.de.rst # Volltext + Bilder
    omniflo/funktion_steuerung_omniflo_500592_v1_1.de.rst
    loading_loop/funktion_steuerung_loadingloop_500592_v2_3.de.rst  # neu erzeugt, ersetzt Altbestand
  07_ersatzteile/index.de.rst                     # Verzeichnisliste -> Originalpfad SPARE_PARTS PDF
  08_lieferantendoku/
    antriebe/index.de.rst                         # Verzeichnisliste SEW, NORD, Leantechnik, DTS
    elektrik/index.de.rst                         # Siemens, Leuze, Cognex, Werma, ...
    pneumatik/index.de.rst                        # Aventics, ITS
    stahlbau/index.de.rst                         # MiTek (As-Built, Statik, Zertifikate, ...)
    sicherheitseinrichtungen/index.de.rst          # ABS Sicherheitslinie
  09_technische_unterlagen/
    layouts/mechanisch/index.de.rst
    layouts/elektrisch/index.de.rst
    schaltplaene/index.de.rst
    notstopp/index.de.rst
    bereichsstopp/index.de.rst
  10_anhang/
    pruefberichte/index.de.rst

projekte/
  fortna/
    anlage.json            # Projektmetadaten (Platzhalter/Vorschlag, manuell nachzuschärfen)
    overrides/              # leer angelegt, Struktur gemäß Kernkonzepte.md
    images/                 # leer angelegt (projektspezifische Bilder, Kundenlogo etc.)
    README.md               # kurze Erläuterung was hier reinkommt
```

Jede `index.de.rst`-Verzeichnisliste enthält eine Tabelle: Dateiname, Hersteller/Kategorie
(aus Ordnername abgeleitet), Originalpfad (relativ zu einer konfigurierbaren Basis, z. B.
`PV_FORTNA_SOURCE`), Dateigröße. Kein PDF wird kopiert oder eingebettet – das hält den
Kapitelbaum schlank und vermeidet Redundanz zum Rohmaterial, das ohnehin an anderer Stelle
(Nextcloud/Projektordner) verwaltet wird.

## Geplante Skripte (in `lib/`)

### 1. `fortna_inventory.py` (neu)

Scannt `c:\10-Develop\projekte\Fortna\` rekursiv und baut ein Inventar (JSON) aller Dateien mit:
Pfad, Größe, erkannte Sprache (aus Ordnername: `*_DE*`/`*_EN*`/`*_CZ*`/`*original*` → de),
vermutetem Fortna-Kapitel (oberste zwei Ebenen) und vermutetem Ziel-Kapitel gemäß Mapping-Tabelle
aus `doc/kapitelstruktur.md`. Dient als Kontrollartefakt (`results/fortna_inventory.json`), auf
dessen Basis sich beide folgenden Skripte konfigurieren bzw. dessen Output sich manuell prüfen
lässt, bevor tatsächlich geschrieben wird (`--dry-run` Default, `--apply` zum Ausführen).

Grund für ein separates Inventarskript: 387 Dateien über 6 Top-Level-Ordner mit inkonsistenter
Sprachordner-Benennung (`01_DE_original`, `01_EN_original`, `1_EN_original` [Tippfehler im
Quellbaum], `02_CZ`, `03_CZ_pro_celé_zařízení`, …) – ein Trockenlauf mit Report ist nötig, um
Mapping-Lücken zu erkennen, bevor Dateien verschoben/verarbeitet werden.

### 2. `fortna_convert_chapters.py` (neu)

Nutzt das Inventar aus Schritt 1 (oder scannt bei Bedarf direkt) und führt zwei Aktionsarten aus:

- **Volltext-Konvertierung** für die 5 Hauptanleitungen: ruft die vorhandene Konvertierungslogik
  aus `convert_to_rst.py` wieder, aber mit expliziter Quelldatei-Liste (kein Verzeichnis-Scan)
  und fest zugeordnetem Zielkapitel (aus der Tabelle unten), statt der generischen
  `CHAPTER_MAPPING`-Heuristik. Überschreibt bestehende Ziel-RSTs/Bilder vollständig
  (Ordnerinhalt vorher leeren, dann neu schreiben).
- **Verzeichnislisten-Generierung** für alle übrigen Kapitel (Zertifikate, Layouts, Schaltpläne,
  Notstopp/Bereichsstopp, Prüfberichte, Ersatzteile, Lieferantendoku): läuft über die im
  Inventar erkannten Dateien je Zielordner und rendert eine `index.de.rst` mit
  RST-list-table (Dateiname, Pfad, Größe).

Fest zugeordnete Hauptanleitungen (Quelle → Ziel):

| Quelldatei (DE, aktuellster Stand in `projekte/Fortna`) | Zielkapitel |
|---|---|
| `02_INSTRUCTIONS.../01_DE_original/01_BETRIEBSANLEITUNG_500592_135776_V2.4.pdf` | `04_betrieb/betriebsanleitung/` |
| `02_INSTRUCTIONS.../01_DE_original/02_WARTUNGSANLEITUNG_500592_V2.3.pdf` | `05_wartung/wartungsanleitung/` |
| `02_INSTRUCTIONS.../01_DE_original/03_FUNKTION_STEUERUNG_ILS_500592_V2.2.pdf` | `06_steuerung/ils/` |
| `02_INSTRUCTIONS.../01_DE_original/04_FUNKTION_STEUERUNG_OMNIFLO_500592_V1.1.pdf` | `06_steuerung/omniflo/` |
| `02_INSTRUCTIONS.../01_DE_original/05_FUNKTION_STEUERUNG_LOADING_LOOP_500592_V2.3.pdf` | `06_steuerung/loading_loop/` (ersetzt Altbestand) |

Alle fünf sind PDFs (keine `.docx` im Quellordner mehr vorhanden), daher wird der
`is_word_pdf()`-Pfad aus `convert_to_rst.py` verwendet (pdfminer-Textextraktion). Die extra
`extract_products.py`-Textheuristik (Schriftgrößen-basierte Überschriftenerkennung,
Kopf-/Fußzeilen-Ausschluss nach Y-Position) ist für Word-erstellte PDFs wie diese *robuster* als
die aktuelle `convert_to_rst.py`-Textheuristik (siehe Bekannte Schwachstellen) – Vorschlag: die
Extraktionsroutine aus `extract_products.py` (`extract_text_to_rst`, `_is_noise`,
`extract_images`) wiederverwenden/verallgemeinern statt der schwächeren `pdfminer`-Variante aus
`convert_to_rst.py`.

### 3. `fortna_init_project.py` (neu)

Legt `projekte/fortna/` an: `anlage.json` (Platzhalter mit Projektnummer 500592/KA135776,
Sprache `["de"]`, `normen_region` offen als TODO), leere `overrides/`- und `images/`-Ordner mit
`.gitkeep`, sowie ein kurzes `README.md`. Einmaliger Lauf, kein Datei-Scan nötig – im
Wesentlichen ein Gerüst-Generator.

## Bekannte Schwachstellen der bisherigen Konvertierung (zu beheben)

Der Altbestand in `chapters/06_steuerung/loading_loop/` zeigt zwei konkrete Probleme der
aktuellen `convert_to_rst.py`-Logik, die für die 5 Hauptanleitungen behoben werden sollten:

1. **Kopf-/Fußzeilen als Fließtext**: Firmenadresse, Kontaktdaten, Projektnummer erscheinen als
   normale Absätze mitten im Dokument (weil `pdfminer.high_level.extract_text` keine
   Positionsinformation liefert, mit der man Kopf-/Fußzeilen herausfiltern könnte).
   `extract_products.py` löst das bereits über `page.get_text("dict")` mit Y-Positions-Filter
   (`bbox[1] < 100` / `bbox[3] > page_height - 50`) – diese Technik übernehmen.
2. **Tabellen zerfallen in Einzelzeilen**: Die Änderungshistorie-Tabelle wird zu einer Folge
   einzelner Absätze ohne Tabellenstruktur. Vorschlag für ersten Wurf: Tabellen nicht als
   RST-Table rekonstruieren (zu fehleranfällig aus PDF-Text), sondern als eingerückten
   `.. code-block::` oder einfache Aufzählung kennzeichnen, mit `.. todo:: Tabelle manuell
   nachbearbeiten`-Marker – ehrlich statt falsch-schön.

## Offene Punkte / Annahmen, die ich getroffen habe

- Ich gehe davon aus, dass `PV_FORTNA_SOURCE` (oder ein `--source-dir`-Argument) als neue
  Umgebungsvariable/Parameter eingeführt wird, die auf `c:\10-Develop\projekte\Fortna\` zeigt,
  da dieser Pfad außerhalb des Repos liegt und nicht über `PV_DATA`/`PV_EXAMPLES` erreichbar ist.
- `02_sicherheit/` und `03_anlagenbeschreibung/` bleiben in diesem Durchlauf unangetastet – es
  gibt keine 1:1-Quelle dafür in `projekte/Fortna/` (Risikobewertung liegt als separate
  `.docx`-Dateien direkt im Repo-Root von `chapters/`, siehe Git-Status, nicht Teil dieser
  Aufgabe).
- Die generierten `index.de.rst`-Verzeichnislisten verweisen auf absolute oder
  repo-relative-konfigurierbare Pfade zum Rohmaterial – das bedeutet, das Zielsystem (Sphinx)
  bekommt keine eigenständig lauffähige Doku ohne Zugriff auf `projekte/Fortna/`. Das ist so
  gewollt gemäß der Entscheidung "nur Verzeichnisliste", sollte aber vor dem produktiven
  PDF-Build nochmal bewusst bestätigt werden (spätestens beim ersten `sphinx-build`-Versuch
  fehlen dann die Downloads/Links).

## Nächste Schritte

1. Dieses Konzept abstimmen (insb. Umgang mit `02_sicherheit`/Risikobewertung-Docx im Root von
   `chapters/`, sowie die Pfad-Referenzierung in den Verzeichnislisten).
2. `fortna_inventory.py` implementieren und Trockenlauf-Report gegen `projekte/Fortna/` prüfen.
3. `fortna_convert_chapters.py` implementieren (inkl. Wiederverwendung der
   `extract_products.py`-Textextraktion), auf 5 Hauptanleitungen anwenden, Ergebnis stichprobenhaft
   gegenlesen.
4. `fortna_init_project.py` implementieren, `projekte/fortna/` anlegen.
5. `bin/`-Wrapper-Skripte (`.bat`/`.sh`) für alle drei ergänzen, analog bestehender Konvention.