Fehlerbehebung: Schriftarten, Subsetting und Tagging

Geltungsbereich

Diese Einträge behandeln Fehler bei der Schriftauflösung und beim Parsing, die die Engine über NextPDF\Exception\FontNotFoundException und NextPDF\Exception\FontParsingException auslöst. Außerdem behandeln sie die CJK-Abdeckungsdiagnose und Probleme mit dem Strukturbaum, die getaggte Ausgaben betreffen. Jeder Eintrag nennt die genaue Exception oder den genauen Test, damit Sie die Ursache bestätigen können.

Eintrag: Schriftart nicht gefunden

• Symptom. FontNotFoundException mit einer Meldung der Form Font "<name>" not found. Searched: [<paths>].
• Wahrscheinliche Ursache. Die angeforderte Schriftfamilie oder der angegebene Dateipfad ist nicht vorhanden oder nicht lesbar, oder das konfigurierte Schriftenverzeichnis ist nicht erreichbar. Die Schriftdaten können gültig sein; die Engine kann jedoch nicht darauf zugreifen.
• Belege / Diagnose. getContext() liefert font_name, search_paths und fallback_attempted. Prüfen Sie search_paths, um jeden Ort zu sehen, den die Engine geprüft hat. Prüfen Sie fallback_attempted, um festzustellen, ob bereits ein Fallback versucht wurde.
• Lösung.
  1. Vergleichen Sie den angeforderten font_name mit der tatsächlich vorhandenen Datei.
  2. Fügen Sie das Verzeichnis, das die Schriftart enthält, dem konfigurierten Schriftenverzeichnis hinzu, oder korrigieren Sie den übergebenen Pfad.
  3. Stellen Sie sicher, dass die Datei für den ausführenden Benutzer lesbar ist.
  4. Führen Sie den Aufruf erneut aus.
• Verwandt. Exception-Referenz.

Eintrag: Schriftdatei lässt sich nicht parsen

• Symptom. FontParsingException mit einer Meldung der Form Failed to parse font file "<file>": <reason>.
• Wahrscheinliche Ursache. Die Schriftdatei wurde gefunden, ihr Inhalt ist jedoch nicht nutzbar: etwa wegen eines abgeschnittenen Headers, eines ungültigen Tabellenverzeichnisses oder einer fehlenden Pflichttabelle wie head, hhea oder OS/2.
• Belege / Diagnose. getContext() liefert font_file und parse_error. Das Feld parse_error nennt das strukturelle Problem.
• Lösung.
  1. Lesen Sie parse_error, um den strukturellen Defekt zu identifizieren.
  2. Ersetzen Sie die Schriftdatei durch eine als funktionierend bekannte Kopie desselben Schriftschnitts.
  3. Führen Sie den Aufruf erneut aus.
• Verwandt. Exception-Referenz.

Eintrag: Subsetting scheitert an einer fehlerhaften Schrifttabelle

• Symptom. FontParsingException mit einem font_file-Wert von font-subset und einem parse_error wie Invalid head table: too short, Invalid hhea table: too short, Invalid maxp table: too short oder Failed to unpack font data.
• Wahrscheinliche Ursache. Die Schriftart hat das erste Laden bestanden, aber eine für das Subsetting erforderliche Tabelle ist abgeschnitten oder kann nicht entpackt werden. Der Subsetter weist die Schriftart zurück, anstatt ein defektes Subset auszugeben.
• Belege / Diagnose. Wenn eine head-, hhea- oder maxp-Tabelle zu kurz ist oder das Entpacken fehlschlägt, löst src/Typography/FontSubsetter.php FontParsingException mit dem literalen Token font-subset als Dateiname aus. Das Token zeigt Ihnen, dass der Fehler aus der Subsetting-Stufe stammt und nicht aus dem ersten Laden.
• Lösung.
  1. Ersetzen Sie die Quellschrift durch eine nicht abgeschnittene Kopie desselben Schriftschnitts.
  2. Wenn die Schriftart von einem Build-Tool erzeugt wird, erzeugen Sie sie neu und prüfen Sie, ob die Tabellen head, hhea und maxp vollständig sind.
  3. Führen Sie den Build erneut aus.
• Verwandt. PDF/A- und PDF/UA-Validierung.

Eintrag: CJK-Text wird mit fehlenden Glyphen gerendert

• Symptom. Chinesischer, japanischer oder koreanischer Text wird mit leeren Kästchen oder fehlenden Zeichen gerendert; außerdem ist die CJK-Abdeckung der Schriftart fraglich.
• Wahrscheinliche Ursache. Die ausgewählte Schriftart deckt die Unicode-Blöcke nicht ab, die das Schriftsystem benötigt. Jedes CJK-Schriftsystem braucht neben den gemeinsamen Ideogramm-Blöcken bestimmte spezifische Blöcke.
• Belege / Diagnose. src/Typography/CjkFontValidator.php stellt validateCoverage(FontInfo $font, CjkScript $script) bereit. Die Methode liefert ein CjkCoverageResult mit dem Abdeckungsprozentsatz und den Blöcken unterhalb der 50-%-Berichtsschwelle. Der Validator tastet Codepoints ab; er dient der Diagnose und verändert das Laden der Schriftart nicht.
• Lösung.
  1. Führen Sie CjkFontValidator::validateCoverage() für die Schriftart und das Zielschriftsystem aus.
  2. Lesen Sie missingRanges, um zu sehen, welche Blöcke nicht abgedeckt sind: zum Beispiel Bopomofo für traditionelles Chinesisch, Hiragana und Katakana für Japanisch sowie Hangul-Silben für Koreanisch.
  3. Wählen Sie eine Schriftart, die diese Blöcke abdeckt, oder fügen Sie eine Fallback-Schriftart hinzu, die das tut.
  4. Rendern Sie erneut und prüfen Sie die Abdeckung erneut.
• Verwandt. Exception-Referenz.

Eintrag: vordefinierte CMap passt nicht zum CJK-Schriftsystem

• Symptom. CJK-Text wird falschen Glyphen zugeordnet, oder es wird eine vordefinierte CMap ausgewählt, die nicht zur Dokumentsprache passt.
• Wahrscheinliche Ursache. Das erkannte Schriftsystem bestimmt den Namen der vordefinierten Adobe-CMap. Eine Schriftart, die nur den gemeinsamen Ideogramm-Block ohne schriftsystemspezifischen Block abdeckt, wird per Design als vereinfachtes Chinesisch erkannt.
• Belege / Diagnose. CjkFontValidator::detectScript() gibt das erkannte Schriftsystem zurück, und resolvePredefinedCMapName() bildet es ab: vereinfachtes Chinesisch auf UniGB-UTF16-H, traditionelles Chinesisch auf UniCNS-UTF16-H, Japanisch auf UniJIS-UTF16-H, Koreanisch auf UniKS-UTF16-H. Wenn kein schriftsystemspezifischer Block vorhanden ist, fällt die Erkennung auf vereinfachtes Chinesisch zurück.
• Lösung.
  1. Bestätigen Sie, dass die Schriftart den schriftsystemspezifischen Block enthält: Bopomofo für traditionelles Chinesisch, Hiragana oder Katakana für Japanisch, Hangul für Koreanisch.
  2. Wenn das Dokument traditionelles Chinesisch verwendet, die Schriftart aber keinen Bopomofo-Block enthält, wählen Sie eine Schriftart, die diesen Block enthält, damit die Erkennung das beabsichtigte Schriftsystem bestimmt.
  3. Rendern Sie erneut.
• Verwandt. Exception-Referenz.

Eintrag: getaggter Inhalt erzeugt keinen nutzbaren Strukturbaum

• Symptom. Ein Build mit Tagging erzeugt keine Struktur, oder eine nachgelagerte Prüfung der Barrierefreiheit meldet einen leeren oder fehlenden Strukturbaum.
• Wahrscheinliche Ursache. Inhalt wurde ausgegeben, ohne den Tagging-Pfad zu durchlaufen; dadurch wurden keine Strukturelemente erstellt. Der Strukturbaum bleibt leer.
• Belege / Diagnose. src/Accessibility/StructureTree.php und src/Accessibility/TaggedContentEmitter.php bauen den Strukturbaum aus getaggten Inhalten auf. Der Test tests/Integration/Accessibility/EmptyTaggedPdfDoesNotAdvertisePdfUa2Test.php bestätigt, dass ein leerer Strukturbaum nicht als PDF/UA-2 ausgewiesen wird.
• Lösung.
  1. Bestätigen Sie, dass Inhalte über den Tagging-Pfad ausgegeben werden, damit Strukturelemente erstellt werden.
  2. Prüfen Sie, ob jede Marked-Content-Sequenz auf ein Strukturelement abgebildet wird.
  3. Führen Sie den Build erneut aus und inspizieren Sie den Strukturbaum.
• Verwandt. PDF/A- und PDF/UA-Validierung.

Eintrag: Sprach-Tag eines Strukturelements wird abgelehnt

• Symptom. Ein Build scheitert, weil ein Sprachwert an einem Strukturelement oder am Dokument kein gültiges Tag ist.
• Wahrscheinliche Ursache. Die angegebene Sprache ist kein gültiges BCP-47-Tag. Der Validator lehnt fehlerhafte Tags ab, anstatt sie auszugeben.
• Belege / Diagnose. src/Accessibility/Bcp47Validator.php validiert das Tag. Ein ungültiges Tag führt zur Exception in src/Accessibility/InvalidBcp47TagException.php. Die strikte Sprachanforderung von PDF/UA-2 wird von tests/Unit/Conformance/PdfUa2Section844LangStrictTest.php geprüft.
• Lösung.
  1. Ersetzen Sie den Sprachwert durch ein gültiges BCP-47-Tag, zum Beispiel en-US, de-DE oder zh-Hant-TW.
  2. Setzen Sie die Sprache am konkreten Strukturelement, wenn sich eine Passage von der Dokumentsprache unterscheidet.
  3. Führen Sie den Build erneut aus.
• Verwandt. PDF/A- und PDF/UA-Validierung.

Grenzfälle & Fallstricke

• FontNotFoundException und FontParsingException sind verschieden. Nicht gefunden bedeutet, dass die Datei nicht erreicht werden konnte. Parsing bedeutet, dass die Datei erreicht wurde, ihre Bytes aber nicht nutzbar sind. Prüfen Sie die Klasse, um zu unterscheiden, welcher Fall vorliegt.
• Der Wert font-subset in font_file ist ein bewusster Marker für die Subsetting-Stufe, kein tatsächlicher Pfad. Suchen Sie nicht nach einer Datei mit dem Namen font-subset.
• CjkFontValidator tastet Codepoints ab, statt jeden einzelnen zu prüfen. Deshalb ist seine Abdeckungszahl eine Schätzung, die für die Schriftauswahl genügt, aber kein bytegenaues Audit.
• Ein leerer Strukturbaum wird per Design als nicht PDF/UA-2-konform gemeldet. Das ist das dokumentierte Verhalten der Engine, kein Defekt.

Siehe auch

• Exception-Referenz
• PDF/A- und PDF/UA-Validierung
• Index der Wissensdatenbank

Glossar: Font-Subsetting · CJK-Abdeckung · Strukturbaum