initial commit

dokus/asciidoc/asciidoctor-theme-bug-workaround.md

@@ -0,0 +1,81 @@
+# Asciidoctor PDF: Kapitel bleibt „Chapter“ – Fehleranalyse & Workaround
+
+## 🧩 Problem
+
+Beim Generieren von PDFs mit `asciidoctor-pdf` (Version 2.3.19) wird die Kapitelüberschrift trotz korrekt gesetztem deutschen Theme und Sprache **nicht lokalisiert**:
+
+```
+Chapter 1. Einführung
+```
+
+…statt:
+
+```
+Kapitel 1. Einführung
+```
+
+---
+
+## ✅ Erwartete Konfiguration
+
+Folgendes wurde korrekt gesetzt:
+
+- `chapter.title: "Kapitel {counter:chapter-number}. "` im Theme
+- `locale: lang` im Theme
+- Fonts korrekt eingebunden
+- `:lang: de` entfernt aus `.adoc` (zur Sicherheit)
+- Keine `de.yml` verwendet
+- Keine Snap-Version oder Paketkonflikte
+- Theme definitiv geladen (`font_size`, `base`, etc. wirksam)
+
+---
+
+## ❌ Ergebnis
+
+Trotz aller Korrektheit:
+- Ausgabe bleibt auf Englisch
+- Lokalisierung über Theme wird ignoriert
+- Das Verhalten ist **reproduzierbar auf mehreren Rechnern und Installationen**
+
+---
+
+## 🧨 Vermutete Ursache
+
+Ein Bug oder ein Regressionseffekt in `asciidoctor-pdf` ab Version `2.3.0`, bei dem:
+- entweder `chapter.title` aus Theme nicht mehr greift
+- oder durch eine andere Sprachverarbeitung überschrieben wird
+
+---
+
+## ✅ Workaround
+
+Statt auf automatische Kapitelüberschriften zu setzen, diese manuell überschreiben:
+
+### Im `.adoc`:
+
+```asciidoc
+:sectnums!:
+
+[discrete]
+== Kapitel 1. Einführung
+```
+
+→ So wird die Kapitelzeile manuell gesetzt und `sectnums` deaktiviert.
+
+---
+
+## 📌 Empfehlung
+
+- In Projekten mit PDF-Export: Immer testen, ob `theme.yml` wirklich angewendet wird
+- Optional: eigene `make test-theme` Ziel im Makefile zur Überprüfung einbauen
+- Bis Bug behoben ist: Kapitel manuell beschriften oder alternative Engine verwenden
+
+---
+
+## 🔗 Betroffene Versionen
+
+- `asciidoctor-pdf 2.3.19`
+- `asciidoctor 2.0.23`
+- `ruby 3.1.x`
+- UTF-8 / Linux / WSL – identisches Verhalten
+