Dépannage : polices, sous-ensembles de polices et balisage

Périmètre

Ces entrées couvrent les échecs de résolution et d’analyse des polices que le moteur signale via NextPDF\Exception\FontNotFoundException et NextPDF\Exception\FontParsingException. Elles couvrent aussi le diagnostic de la couverture CJK et les problèmes d’arbre de structure qui affectent la sortie balisée. Chaque entrée indique l’exception ou le test exact afin que tu puisses confirmer la cause.

Entrée : police introuvable

• Symptôme. FontNotFoundException avec un message de la forme Font "<name>" not found. Searched: [<paths>].
• Cause probable. La famille de police demandée ou le chemin de fichier demandé n’existe pas ou n’est pas lisible, ou le répertoire de polices configuré est inaccessible. Les données de police peuvent être valides, mais le moteur ne peut pas y accéder.
• Preuves / diagnostic. getContext() renvoie font_name, search_paths et fallback_attempted. Consulte search_paths pour voir chaque emplacement que le moteur a essayé. Consulte fallback_attempted pour voir si un repli a déjà été tenté.
• Résolution.
  1. Compare le font_name demandé avec le fichier réellement présent.
  2. Ajoute le répertoire qui contient la police au répertoire de polices configuré, ou corrige le chemin que tu as transmis.
  3. Vérifie que le fichier est lisible par l’utilisateur d’exécution.
  4. Relance l’appel.
• Voir aussi. Référence des exceptions.

Entrée : l’analyse du fichier de police échoue

• Symptôme. FontParsingException avec un message de la forme Failed to parse font file "<file>": <reason>.
• Cause probable. Le fichier de police a été trouvé, mais son contenu est inutilisable : en-tête tronqué, répertoire de tables non valide ou table obligatoire manquante, comme head, hhea ou OS/2.
• Preuves / diagnostic. getContext() renvoie font_file et parse_error. Le champ parse_error indique le problème structurel.
• Résolution.
  1. Lis parse_error pour identifier le défaut structurel.
  2. Remplace le fichier de police par une copie connue comme correcte de la même fonte.
  3. Relance l’appel.
• Voir aussi. Référence des exceptions.

Entrée : la création du sous-ensemble de police échoue sur une table de police malformée

• Symptôme. FontParsingException avec une valeur font_file de font-subset et un parse_error tel que Invalid head table: too short, Invalid hhea table: too short, Invalid maxp table: too short, ou Failed to unpack font data.
• Cause probable. La police a bien été chargée au départ, mais une table nécessaire à la création du sous-ensemble est tronquée ou ne peut pas être décompressée. Le sous-ensembleur rejette la police plutôt que de produire un sous-ensemble défectueux.
• Preuves / diagnostic. Lorsqu’une table head, hhea ou maxp est trop courte ou qu’une décompression échoue, src/Typography/FontSubsetter.php lève FontParsingException avec le jeton littéral font-subset comme nom de fichier. Ce jeton t’indique que l’échec vient de l’étape de sous-ensemble, et non du chargement initial.
• Résolution.
  1. Remplace la police source par une copie non tronquée de la même fonte.
  2. Si la police est générée par un outil de build, régénère-la et vérifie que les tables head, hhea et maxp sont complètes.
  3. Relance le build.
• Voir aussi. Validation PDF/A et PDF/UA.

Entrée : le texte CJK s’affiche avec des glyphes manquants

• Symptôme. Le texte chinois, japonais ou coréen s’affiche avec des cases vides ou des caractères manquants, et la couverture CJK de la police semble en cause.
• Cause probable. La police sélectionnée ne couvre pas les blocs Unicode nécessaires à l’écriture. Chaque écriture CJK exige des blocs spécifiques en plus des blocs d’idéogrammes partagés.
• Preuves / diagnostic. src/Typography/CjkFontValidator.php fournit validateCoverage(FontInfo $font, CjkScript $script). Elle renvoie un CjkCoverageResult avec le pourcentage de couverture et les blocs sous le seuil de signalement de 50 %. Le validateur échantillonne des points de code : il s’agit d’un diagnostic, qui ne modifie pas le chargement des polices.
• Résolution.
  1. Exécute CjkFontValidator::validateCoverage() pour la police et l’écriture cible.
  2. Consulte les missingRanges pour voir quels blocs ne sont pas couverts : par exemple, le Bopomofo pour le chinois traditionnel, les Hiragana et les Katakana pour le japonais, les syllabes Hangul pour le coréen.
  3. Sélectionne une police qui couvre ces blocs, ou ajoute une police de repli qui les couvre.
  4. Relance le rendu et revérifie la couverture.
• Voir aussi. Référence des exceptions.

Entrée : la CMap prédéfinie ne correspond pas à l’écriture CJK

• Symptôme. Le texte CJK est mappé sur les mauvais glyphes, ou la CMap prédéfinie sélectionnée ne correspond pas à la langue du document.
• Cause probable. L’écriture détectée détermine le nom de la CMap prédéfinie Adobe. Une police qui ne couvre que le bloc d’idéogrammes partagé, sans bloc spécifique à une écriture, est détectée comme chinois simplifié, par conception.
• Preuves / diagnostic. CjkFontValidator::detectScript() renvoie l’écriture détectée, et resolvePredefinedCMapName() l’associe ainsi : le chinois simplifié à UniGB-UTF16-H, le chinois traditionnel à UniCNS-UTF16-H, le japonais à UniJIS-UTF16-H, le coréen à UniKS-UTF16-H. En l’absence de bloc spécifique à une écriture, la détection se rabat sur le chinois simplifié.
• Résolution.
  1. Confirme que la police intègre le bloc spécifique à l’écriture : le Bopomofo pour le chinois traditionnel, les Hiragana ou les Katakana pour le japonais, le Hangul pour le coréen.
  2. Si le document est en chinois traditionnel mais que la police ne contient aucun bloc Bopomofo, sélectionne une police qui en contient un afin que la détection résolve l’écriture attendue.
  3. Relance le rendu.
• Voir aussi. Référence des exceptions.

Entrée : le contenu balisé ne produit pas d’arbre de structure exploitable

• Symptôme. Un build avec balisage ne produit aucune structure, ou une vérification d’accessibilité ultérieure signale un arbre de structure vide ou manquant.
• Cause probable. Le contenu a été émis sans emprunter le chemin de balisage ; aucun élément de structure n’a donc été créé. L’arbre de structure reste vide.
• Preuves / diagnostic. src/Accessibility/StructureTree.php et src/Accessibility/TaggedContentEmitter.php construisent l’arbre de structure à partir du contenu balisé. Le test tests/Integration/Accessibility/EmptyTaggedPdfDoesNotAdvertisePdfUa2Test.php confirme qu’un arbre de structure vide n’annonce pas PDF/UA-2.
• Résolution.
  1. Assure-toi que le contenu est émis via le chemin de balisage pour que les éléments de structure soient créés.
  2. Vérifie que chaque séquence de contenu marqué correspond à un élément de structure.
  3. Relance le build et inspecte l’arbre de structure.
• Voir aussi. Validation PDF/A et PDF/UA.

Entrée : la balise de langue d’un élément de structure est rejetée

• Symptôme. Un build échoue parce qu’une valeur de langue définie sur un élément de structure ou sur le document n’est pas une balise valide.
• Cause probable. La langue fournie n’est pas une balise BCP-47 valide. Le validateur rejette les balises malformées plutôt que de les émettre.
• Preuves / diagnostic. src/Accessibility/Bcp47Validator.php valide la balise. Une balise non valide lève src/Accessibility/InvalidBcp47TagException.php. L’exigence stricte de langue PDF/UA-2 est vérifiée par tests/Unit/Conformance/PdfUa2Section844LangStrictTest.php.
• Résolution.
  1. Remplace la valeur de langue par une balise BCP-47 valide, par exemple en-US, de-DE, ou zh-Hant-TW.
  2. Définis la langue sur l’élément de structure spécifique lorsqu’un passage diffère de la langue du document.
  3. Relance le build.
• Voir aussi. Validation PDF/A et PDF/UA.

Cas limites et pièges

• FontNotFoundException et FontParsingException sont distinctes. Introuvable signifie que le fichier n’a pas pu être atteint. Analyse signifie que le fichier a été atteint, mais que ses octets sont inutilisables. Consulte la classe levée pour savoir laquelle s’applique.
• La valeur font-subset dans font_file est un marqueur volontaire de l’étape de sous-ensemble, pas un chemin réel. Ne cherche pas un fichier nommé font-subset.
• CjkFontValidator échantillonne des points de code plutôt que de tous les vérifier ; son chiffre de couverture est donc une estimation suffisante pour la sélection de police, pas un audit exact à l’octet.
• Un arbre de structure vide est signalé comme non PDF/UA-2, par conception. C’est le comportement documenté du moteur, pas un défaut.

Voir aussi

• Référence des exceptions
• Validation PDF/A et PDF/UA
• Index de la base de connaissances

Glossaire : sous-ensemble de police · couverture CJK · arbre de structure