83 lines
1.8 KiB
Markdown
83 lines
1.8 KiB
Markdown
# 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**:
|
||
|
||
```text
|
||
Chapter 1. Einführung
|
||
```
|
||
|
||
…statt:
|
||
|
||
```text
|
||
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
|