Probleemoplossing: lettertypen, subsetting en tagging

Reikwijdte

Deze items behandelen fouten bij het vinden en parsen van lettertypen die via NextPDF\Exception\FontNotFoundException en NextPDF\Exception\FontParsingException worden opgeworpen. Ze behandelen ook diagnostiek voor de dekking van Chinees, Japans en Koreaans (CJK) en problemen met de structuurboom die van invloed zijn op getagde uitvoer. Elk item noemt de exacte exception of test, zodat je de oorzaak kunt verifiëren.

Item: lettertype niet gevonden

• Symptoom. FontNotFoundException met een bericht in de vorm Font "<name>" not found. Searched: [<paths>].
• Waarschijnlijke oorzaak. De gevraagde lettertypefamilie of bestandspad bestaat niet, is niet leesbaar of bevindt zich in een lettertypemap die de runtime niet kan benaderen. De lettertypegegevens kunnen geldig zijn, maar de engine kan ze toch niet bereiken.
• Bewijs / diagnose. getContext() retourneert font_name, search_paths en fallback_attempted. Bekijk met search_paths elke locatie die de engine heeft geprobeerd. Gebruik fallback_attempted om te bevestigen of er al fallback is uitgevoerd.
• Oplossing.
  1. Vergelijk de gevraagde font_name met het lettertypebestand dat daadwerkelijk aanwezig is.
  2. Voeg de map met het lettertype toe aan de geconfigureerde lettertypemap, of corrigeer het pad dat je hebt doorgegeven.
  3. Controleer of de runtime-gebruiker het bestand kan lezen.
  4. Voer de aanroep opnieuw uit.
• Gerelateerd. Exception-referentie.

Item: lettertypebestand kan niet worden geparseerd

• Symptoom. FontParsingException met een bericht in de vorm Failed to parse font file "<file>": <reason>.
• Waarschijnlijke oorzaak. De engine heeft het lettertypebestand gevonden, maar kan de inhoud niet gebruiken: door een afgekapte header, een ongeldige tabeldirectory of een ontbrekende verplichte tabel zoals head, hhea of OS/2.
• Bewijs / diagnose. getContext() retourneert font_file en parse_error. parse_error benoemt het structurele probleem.
• Oplossing.
  1. Lees parse_error om het structurele defect te identificeren.
  2. Vervang het lettertypebestand door een bekende goede kopie van hetzelfde lettertype.
  3. Voer de aanroep opnieuw uit.
• Gerelateerd. Exception-referentie.

Item: subsetting mislukt door een misvormde lettertypetabel

• Symptoom. FontParsingException met een font_file-waarde van font-subset en een parse_error zoals Invalid head table: too short, Invalid hhea table: too short, Invalid maxp table: too short of Failed to unpack font data.
• Waarschijnlijke oorzaak. Het lettertype is initieel geladen, maar een tabel die nodig is voor subsetting, is afgekapt of kan niet worden uitgepakt. De subsetter weigert het lettertype in plaats van een defecte subset te maken.
• Bewijs / diagnose. Wanneer een head-, hhea- of maxp-tabel te kort is of een uitpakbewerking mislukt, werpt src/Typography/FontSubsetter.php een FontParsingException op met het letterlijke token font-subset als bestandsnaam. Het token vertelt je dat de fout zich tijdens subsetting voordeed, niet tijdens het initiële laden.
• Oplossing.
  1. Vervang het bronlettertype door een volledige, niet-afgekapte kopie van hetzelfde lettertype.
  2. Als een buildtool het lettertype genereert, genereer het opnieuw en controleer of de tabellen head, hhea en maxp volledig zijn.
  3. Voer de build opnieuw uit.
• Gerelateerd. PDF/A- en PDF/UA-validatie.

Item: CJK-tekst wordt weergegeven met ontbrekende glyphs

• Symptoom. Chinese, Japanse of Koreaanse tekst wordt weergegeven als lege vakjes of ontbrekende tekens, en de CJK-dekking van het lettertype is onduidelijk.
• Waarschijnlijke oorzaak. Het geselecteerde lettertype dekt niet de Unicode-blokken die het schrift nodig heeft. Elk CJK-schrift vereist specifieke blokken naast de gedeelde ideograafblokken.
• Bewijs / diagnose. src/Typography/CjkFontValidator.php biedt validateCoverage(FontInfo $font, CjkScript $script). Het retourneert een CjkCoverageResult met het dekkingspercentage en eventuele blokken die onder de rapportagedrempel van 50% blijven. De validator neemt steekproeven van codepunten. Dit is diagnostiek en wijzigt het laden van lettertypen niet.
• Oplossing.
  1. Voer CjkFontValidator::validateCoverage() uit voor het lettertype en het doelschrift.
  2. Lees de missingRanges om te zien welke blokken niet worden gedekt, bijvoorbeeld Bopomofo voor Traditioneel Chinees, Hiragana en Katakana voor Japans, en Hangul Syllables voor Koreaans.
  3. Selecteer een lettertype dat die blokken dekt, of voeg een fallback-lettertype toe dat die blokken wel dekt.
  4. Voer de weergave opnieuw uit en controleer de dekking opnieuw.
• Gerelateerd. Exception-referentie.

Item: vooraf gedefinieerde CMap komt niet overeen met het CJK-schrift

• Symptoom. CJK-tekst wordt toegewezen aan de verkeerde glyphs, of het document gebruikt een vooraf gedefinieerde CMap die niet overeenkomt met de taal ervan.
• Waarschijnlijke oorzaak. Het gedetecteerde schrift bepaalt de naam van de vooraf gedefinieerde Adobe-CMap. Een lettertype dat alleen het gedeelde ideograafblok dekt en geen schriftspecifiek blok heeft, wordt opzettelijk gedetecteerd als Vereenvoudigd Chinees.
• Bewijs / diagnose. CjkFontValidator::detectScript() retourneert het gedetecteerde schrift, en resolvePredefinedCMapName() koppelt het daaraan: Vereenvoudigd Chinees aan UniGB-UTF16-H, Traditioneel Chinees aan UniCNS-UTF16-H, Japans aan UniJIS-UTF16-H en Koreaans aan UniKS-UTF16-H. Als er geen schriftspecifiek blok aanwezig is, valt de detectie terug op Vereenvoudigd Chinees.
• Oplossing.
  1. Bevestig dat het lettertype het schriftspecifieke blok bevat: Bopomofo voor Traditioneel Chinees, Hiragana of Katakana voor Japans, en Hangul voor Koreaans.
  2. Als het document Traditioneel Chinees is, maar het lettertype geen Bopomofo-blok heeft, selecteer dan een lettertype dat dat blok wel bevat, zodat de detectie tot het bedoelde schrift leidt.
  3. Voer de weergave opnieuw uit.
• Gerelateerd. Exception-referentie.

Item: getagde inhoud levert geen bruikbare structuurboom op

• Symptoom. Een getagde build produceert geen structuur, of een downstream toegankelijkheidscontrole rapporteert een lege of ontbrekende structuurboom.
• Waarschijnlijke oorzaak. De build heeft inhoud uitgevoerd buiten het taggingpad, waardoor er geen structuurelementen zijn gemaakt. De structuurboom blijft leeg.
• Bewijs / diagnose. src/Accessibility/StructureTree.php en src/Accessibility/TaggedContentEmitter.php bouwen de structuurboom op uit getagde inhoud. De test tests/Integration/Accessibility/EmptyTaggedPdfDoesNotAdvertisePdfUa2Test.php bevestigt dat een lege structuurboom geen PDF/UA-2 adverteert.
• Oplossing.
  1. Bevestig dat inhoud via het taggingpad wordt uitgevoerd, zodat er structuurelementen worden gemaakt.
  2. Controleer of elke marked-content-reeks aan een structuurelement wordt toegewezen.
  3. Voer de build opnieuw uit en inspecteer de structuurboom.
• Gerelateerd. PDF/A- en PDF/UA-validatie.

Item: taaltag van structuurelement wordt geweigerd

• Symptoom. Een build mislukt omdat een taalwaarde op een structuurelement of op het document geen geldige tag is.
• Waarschijnlijke oorzaak. De opgegeven taal is geen geldige BCP 47-tag. De validator weigert misvormde tags in plaats van ze naar de uitvoer te schrijven.
• Bewijs / diagnose. src/Accessibility/Bcp47Validator.php valideert de tag. Bij een ongeldige tag wordt src/Accessibility/InvalidBcp47TagException.php opgeworpen. tests/Unit/Conformance/PdfUa2Section844LangStrictTest.php test de strikte PDF/UA-2-taalvereiste.
• Oplossing.
  1. Vervang de taalwaarde door een geldige BCP 47-tag, zoals en-US, de-DE of zh-Hant-TW.
  2. Stel de taal in op het specifieke structuurelement wanneer een passage afwijkt van de documenttaal.
  3. Voer de build opnieuw uit.
• Gerelateerd. PDF/A- en PDF/UA-validatie.

Randgevallen en valkuilen

• FontNotFoundException en FontParsingException rapporteren verschillende fouten. Niet gevonden betekent dat het bestand niet kon worden bereikt. Parsen betekent dat het bestand wel werd bereikt, maar dat de bytes ervan niet bruikbaar zijn. Lees de exceptionklasse om vast te stellen welke fout zich voordeed.
• font-subset in font_file is een bewuste markering voor de subsettingfase, geen daadwerkelijk pad. Zoek niet naar een bestand met de naam font-subset.
• CjkFontValidator neemt steekproeven van codepunten in plaats van elk codepunt te controleren, dus het dekkingscijfer is een schatting voor lettertypeselectie, geen byte-exacte audit.
• Een lege structuurboom wordt opzettelijk gerapporteerd als niet PDF/UA-2. Dit is het gedocumenteerde gedrag van de engine, geen defect.

Zie ook

• Exception-referentie
• PDF/A- en PDF/UA-validatie
• Index van de kennisbank

Woordenlijst: font subsetting · CJK-dekking · structuurboom