82 lines
1.8 KiB
Markdown
82 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**:
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
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
|
|||
|
|
|