Risoluzione dei problemi: font, subsetting e tagging

Ambito

Queste voci coprono gli errori di risoluzione e parsing dei font che il motore solleva tramite NextPDF\Exception\FontNotFoundException e NextPDF\Exception\FontParsingException. Coprono inoltre la diagnostica della copertura CJK e i problemi dell’albero della struttura relativi all’output con tagging. Ogni voce indica l’eccezione o il test esatto, così da confermare la causa.

Voce: font non trovato

• Sintomo. FontNotFoundException con un messaggio nella forma Font "<name>" not found. Searched: [<paths>].
• Causa probabile. La famiglia di font richiesta o il percorso del file indicato non esiste, non è leggibile oppure la directory dei font configurata è inaccessibile. I dati del font possono essere validi, ma il motore non riesce ad accedervi.
• Evidenze / diagnosi. getContext() restituisce font_name, search_paths e fallback_attempted. Consultare search_paths per vedere ogni posizione provata dal motore. Consultare fallback_attempted per verificare se è già stato tentato un fallback.
• Risoluzione.
  1. Confrontare il font_name richiesto con il file effettivamente presente.
  2. Aggiungere la directory che contiene il font alla configurazione delle directory dei font oppure correggere il percorso passato.
  3. Verificare che il file sia leggibile dall’utente con cui viene eseguito il runtime.
  4. Eseguire di nuovo la chiamata.
• Argomenti correlati. Riferimento delle eccezioni.

Voce: il parsing del file di font fallisce

• Sintomo. FontParsingException con un messaggio nella forma Failed to parse font file "<file>": <reason>.
• Causa probabile. Il file di font è stato trovato, ma il suo contenuto non è utilizzabile: per esempio un’intestazione troncata, una directory delle tabelle non valida o una tabella obbligatoria mancante come head, hhea o OS/2.
• Evidenze / diagnosi. getContext() restituisce font_file e parse_error. Il campo parse_error descrive il problema strutturale.
• Risoluzione.
  1. Leggere parse_error per identificare il difetto strutturale.
  2. Sostituire il file di font con una copia integra dello stesso carattere.
  3. Eseguire di nuovo la chiamata.
• Argomenti correlati. Riferimento delle eccezioni.

Voce: il subsetting fallisce su una tabella di font malformata

• Sintomo. FontParsingException con un valore di font_file pari a font-subset e un parse_error come Invalid head table: too short, Invalid hhea table: too short, Invalid maxp table: too short o Failed to unpack font data.
• Causa probabile. Il font ha superato il caricamento iniziale, ma una tabella necessaria al subsetting è troncata o non può essere decompressa. Il subsetter rifiuta il font, evitando di produrre un subset difettoso.
• Evidenze / diagnosi. Quando una tabella head, hhea o maxp è troppo corta o una decompressione fallisce, src/Typography/FontSubsetter.php solleva FontParsingException con il token letterale font-subset come nome del file. Il token indica che l’errore proviene dalla fase di subsetting e non dal caricamento iniziale.
• Risoluzione.
  1. Sostituire il font di origine con una copia completa, non troncata, dello stesso font.
  2. Se il font viene generato da uno strumento di build, rigenerarlo e verificare che le tabelle head, hhea e maxp siano complete.
  3. Eseguire di nuovo la build.
• Argomenti correlati. Validazione PDF/A e PDF/UA.

Voce: il testo CJK viene reso con glifi mancanti

• Sintomo. Il testo cinese, giapponese o coreano viene reso con riquadri vuoti o caratteri mancanti e la copertura CJK del font deve essere verificata.
• Causa probabile. Il font selezionato non copre i blocchi Unicode richiesti dallo script. Oltre ai blocchi di ideogrammi condivisi, ogni script CJK richiede blocchi specifici.
• Evidenze / diagnosi. src/Typography/CjkFontValidator.php fornisce validateCoverage(FontInfo $font, CjkScript $script). Restituisce un CjkCoverageResult con la percentuale di copertura e i blocchi al di sotto della soglia di segnalazione del 50%. Il validatore campiona i code point: è uno strumento diagnostico e non modifica il caricamento dei font.
• Risoluzione.
  1. Eseguire CjkFontValidator::validateCoverage() per il font e lo script di destinazione.
  2. Consultare missingRanges per vedere quali blocchi non sono coperti, per esempio Bopomofo per il cinese tradizionale, Hiragana e Katakana per il giapponese, Hangul Syllables per il coreano.
  3. Selezionare un font che copra tali blocchi oppure aggiungere un font di fallback che li copra.
  4. Eseguire di nuovo il rendering e verificare nuovamente la copertura.
• Argomenti correlati. Riferimento delle eccezioni.

Voce: la CMap predefinita non corrisponde allo script CJK

• Sintomo. Il testo CJK viene mappato sui glifi errati oppure viene selezionata una CMap predefinita non coerente con la lingua del documento.
• Causa probabile. Lo script rilevato determina il nome della CMap predefinita di Adobe. Un font che copre solo il blocco di ideogrammi condivisi, senza alcun blocco specifico dello script, viene rilevato come cinese semplificato per progettazione.
• Evidenze / diagnosi. CjkFontValidator::detectScript() restituisce lo script rilevato, mentre resolvePredefinedCMapName() lo mappa: cinese semplificato su UniGB-UTF16-H, cinese tradizionale su UniCNS-UTF16-H, giapponese su UniJIS-UTF16-H, coreano su UniKS-UTF16-H. In assenza di un blocco specifico dello script, il rilevamento ricade sul cinese semplificato.
• Risoluzione.
  1. Verificare che il font includa il blocco specifico dello script — Bopomofo per il cinese tradizionale, Hiragana o Katakana per il giapponese, Hangul per il coreano.
  2. Se il documento è in cinese tradizionale ma il font non contiene alcun blocco Bopomofo, selezionare un font che lo contenga affinché il rilevamento restituisca lo script previsto.
  3. Eseguire di nuovo il rendering.
• Argomenti correlati. Riferimento delle eccezioni.

Voce: il contenuto con tag non produce un albero della struttura utilizzabile

• Sintomo. Una build con tag non produce alcuna struttura oppure un controllo di accessibilità successivo segnala un albero della struttura vuoto o mancante.
• Causa probabile. Il contenuto è stato emesso senza passare attraverso il percorso di tagging, quindi non è stato creato alcun elemento di struttura. L’albero della struttura rimane quindi vuoto.
• Evidenze / diagnosi. src/Accessibility/StructureTree.php e src/Accessibility/TaggedContentEmitter.php costruiscono l’albero della struttura a partire dal contenuto con tag. Il test tests/Integration/Accessibility/EmptyTaggedPdfDoesNotAdvertisePdfUa2Test.php conferma che un albero della struttura vuoto non dichiara la conformità PDF/UA-2.
• Risoluzione.
  1. Verificare che il contenuto passi attraverso il percorso di tagging affinché vengano creati gli elementi di struttura.
  2. Verificare che ogni sequenza di contenuto contrassegnato sia mappata su un elemento di struttura.
  3. Eseguire di nuovo la build e ispezionare l’albero della struttura.
• Argomenti correlati. Validazione PDF/A e PDF/UA.

Voce: il tag di lingua dell’elemento di struttura viene rifiutato

• Sintomo. Una build fallisce perché un valore di lingua su un elemento di struttura o sul documento non è un tag valido.
• Causa probabile. Il valore di lingua fornito non è un tag BCP-47 valido. Il validatore rifiuta i tag malformati invece di emetterli.
• Evidenze / diagnosi. src/Accessibility/Bcp47Validator.php convalida il tag. Un tag non valido fa sollevare src/Accessibility/InvalidBcp47TagException.php. Il requisito rigoroso di PDF/UA-2 sulla lingua è verificato da tests/Unit/Conformance/PdfUa2Section844LangStrictTest.php.
• Risoluzione.
  1. Sostituire il valore di lingua con un tag BCP-47 valido, per esempio en-US, de-DE o zh-Hant-TW.
  2. Impostare la lingua sull’elemento di struttura specifico quando un passaggio ha una lingua diversa da quella del documento.
  3. Eseguire di nuovo la build.
• Argomenti correlati. Validazione PDF/A e PDF/UA.

Casi limite e insidie

• FontNotFoundException e FontParsingException sono distinte. Non trovato significa che non è stato possibile raggiungere il file. Parsing significa che il file è stato raggiunto, ma i suoi byte non sono utilizzabili. Consultare la classe dell’eccezione per distinguere i due casi.
• Il valore font-subset in font_file è un marcatore deliberato della fase di subsetting, non un percorso effettivo. Non cercare un file denominato font-subset.
• CjkFontValidator campiona i code point invece di controllarli tutti, quindi la sua percentuale di copertura è una stima adeguata per la selezione dei font, non un controllo byte per byte.
• Un albero della struttura vuoto viene segnalato come non conforme a PDF/UA-2 per progettazione. Questo è il comportamento documentato del motore, non un difetto.

Vedere anche

• Riferimento delle eccezioni
• Validazione PDF/A e PDF/UA
• Indice della knowledge base

Glossario: subsetting dei font · copertura CJK · albero della struttura