Solución de problemas: fuentes, creación de subconjuntos y etiquetado

Alcance

Estas entradas cubren los fallos de resolución y análisis de fuentes que el motor lanza mediante NextPDF\Exception\FontNotFoundException y NextPDF\Exception\FontParsingException. También cubren el diagnóstico de cobertura CJK y los problemas del árbol de estructura que afectan a la salida etiquetada. Cada entrada indica la excepción o la prueba exacta para poder confirmar la causa.

Entrada: fuente no encontrada

• Síntoma. FontNotFoundException con un mensaje de la forma Font "<name>" not found. Searched: [<paths>].
• Causa probable. La familia de fuentes o la ruta de archivo solicitada no existen o no se pueden leer, o el directorio de fuentes configurado no es accesible. Los datos de la fuente pueden ser válidos, pero el motor no puede acceder a ellos.
• Evidencia y diagnóstico. getContext() devuelve font_name, search_paths y fallback_attempted. Consultar search_paths permite ver todas las ubicaciones que el motor intentó. Consultar fallback_attempted permite saber si ya se intentó un respaldo.
• Resolución.
  1. Comparar el font_name solicitado con el archivo que existe realmente.
  2. Agregar el directorio que contiene la fuente al directorio de fuentes configurado o corregir la ruta indicada.
  3. Verificar que el usuario del entorno de ejecución pueda leer el archivo.
  4. Volver a ejecutar la llamada.
• Relacionado. Referencia de excepciones.

Entrada: el archivo de fuente no se puede analizar

• Síntoma. FontParsingException con un mensaje de la forma Failed to parse font file "<file>": <reason>.
• Causa probable. El archivo de fuente se encontró, pero su contenido no es utilizable: puede tener un encabezado truncado, un directorio de tablas no válido o faltar una tabla obligatoria como head, hhea u OS/2.
• Evidencia y diagnóstico. getContext() devuelve font_file y parse_error. El campo parse_error indica el problema estructural.
• Resolución.
  1. Leer parse_error para identificar el defecto estructural.
  2. Reemplazar el archivo de fuente por una copia en buen estado del mismo tipo de letra.
  3. Volver a ejecutar la llamada.
• Relacionado. Referencia de excepciones.

Entrada: la creación de subconjuntos falla por una tabla de fuente malformada

• Síntoma. FontParsingException con un valor de font_file de font-subset y un parse_error como Invalid head table: too short, Invalid hhea table: too short, Invalid maxp table: too short o Failed to unpack font data.
• Causa probable. La fuente superó la carga inicial, pero alguna tabla necesaria para la creación de subconjuntos está truncada o no se puede desempaquetar. El generador de subconjuntos rechaza la fuente en lugar de emitir un subconjunto dañado.
• Evidencia y diagnóstico. Cuando una tabla head, hhea o maxp es demasiado corta o falla un desempaquetado, src/Typography/FontSubsetter.php lanza FontParsingException con el token literal font-subset como nombre de archivo. El token indica que el fallo se produjo en la etapa de creación de subconjuntos, no durante la carga inicial.
• Resolución.
  1. Reemplazar la fuente de origen por una copia no truncada del mismo tipo de letra.
  2. Si la fuente la genera una herramienta de compilación, volver a generarla y verificar que las tablas head, hhea y maxp estén completas.
  3. Volver a ejecutar la compilación.
• Relacionado. Validación de PDF/A y PDF/UA.

Entrada: el texto CJK se renderiza con glifos faltantes

• Síntoma. El texto en chino, japonés o coreano se renderiza con cuadros en blanco o caracteres faltantes, y hay dudas sobre la cobertura CJK de la fuente.
• Causa probable. La fuente seleccionada no cubre los bloques Unicode que requiere la escritura. Cada escritura CJK necesita bloques específicos además de los bloques de ideogramas compartidos.
• Evidencia y diagnóstico. src/Typography/CjkFontValidator.php proporciona validateCoverage(FontInfo $font, CjkScript $script). Devuelve un CjkCoverageResult con el porcentaje de cobertura y los bloques que quedan por debajo del umbral de informe del 50%. El validador muestrea puntos de código: sirve como diagnóstico y no modifica la carga de fuentes.
• Resolución.
  1. Ejecutar CjkFontValidator::validateCoverage() para la fuente y la escritura de destino.
  2. Consultar los missingRanges para ver qué bloques están sin cubrir; por ejemplo, Bopomofo para chino tradicional, Hiragana y Katakana para japonés, sílabas Hangul para coreano.
  3. Seleccionar una fuente que cubra esos bloques o agregar una fuente de respaldo que lo haga.
  4. Volver a renderizar y comprobar de nuevo la cobertura.
• Relacionado. Referencia de excepciones.

Entrada: el CMap predefinido no coincide con la escritura CJK

• Síntoma. El texto CJK se asigna a los glifos equivocados, o se selecciona un CMap predefinido que no corresponde al idioma del documento.
• Causa probable. La escritura detectada determina el nombre del CMap predefinido de Adobe. Una fuente que solo cubre el bloque de ideogramas compartido, sin ningún bloque específico de la escritura, se detecta como chino simplificado por diseño.
• Evidencia y diagnóstico. CjkFontValidator::detectScript() devuelve la escritura detectada, y resolvePredefinedCMapName() hace la asignación correspondiente: chino simplificado a UniGB-UTF16-H, chino tradicional a UniCNS-UTF16-H, japonés a UniJIS-UTF16-H, coreano a UniKS-UTF16-H. Si no hay ningún bloque específico de la escritura, la detección recurre al chino simplificado.
• Resolución.
  1. Confirmar que la fuente incluya el bloque específico de la escritura: Bopomofo para chino tradicional, Hiragana o Katakana para japonés, Hangul para coreano.
  2. Si el documento es chino tradicional pero la fuente no incluye el bloque Bopomofo, seleccionar una que sí lo haga para que la detección resuelva la escritura prevista.
  3. Volver a renderizar.
• Relacionado. Referencia de excepciones.

Entrada: el contenido etiquetado no produce un árbol de estructura utilizable

• Síntoma. Una compilación etiquetada no genera ninguna estructura, o una comprobación de accesibilidad posterior indica que el árbol de estructura está vacío o falta.
• Causa probable. El contenido se emitió sin pasar por la ruta de etiquetado; por eso no se crearon elementos de estructura. El árbol de estructura queda vacío.
• Evidencia y diagnóstico. src/Accessibility/StructureTree.php y src/Accessibility/TaggedContentEmitter.php construyen el árbol de estructura a partir del contenido etiquetado. La prueba tests/Integration/Accessibility/EmptyTaggedPdfDoesNotAdvertisePdfUa2Test.php confirma que un árbol de estructura vacío no anuncia PDF/UA-2.
• Resolución.
  1. Confirmar que el contenido se emita por la ruta de etiquetado para que se creen los elementos de estructura.
  2. Verificar que cada secuencia de contenido marcado se asigne a un elemento de estructura.
  3. Volver a ejecutar la compilación e inspeccionar el árbol de estructura.
• Relacionado. Validación de PDF/A y PDF/UA.

Entrada: se rechaza la etiqueta de idioma de un elemento de estructura

• Síntoma. Una compilación falla porque el valor de idioma de un elemento de estructura o del documento no es una etiqueta válida.
• Causa probable. El valor de idioma proporcionado no es una etiqueta BCP-47 válida. El validador rechaza las etiquetas malformadas en lugar de emitirlas.
• Evidencia y diagnóstico. src/Accessibility/Bcp47Validator.php valida la etiqueta. Si la etiqueta no es válida, se lanza src/Accessibility/InvalidBcp47TagException.php. El requisito estricto de idioma de PDF/UA-2 se prueba mediante tests/Unit/Conformance/PdfUa2Section844LangStrictTest.php.
• Resolución.
  1. Reemplazar el valor de idioma por una etiqueta BCP-47 válida, por ejemplo en-US, de-DE o zh-Hant-TW.
  2. Establecer el idioma en el elemento de estructura específico cuando un pasaje difiere del idioma del documento.
  3. Volver a ejecutar la compilación.
• Relacionado. Validación de PDF/A y PDF/UA.

Casos límite y trampas

• FontNotFoundException y FontParsingException son distintas. Una fuente no encontrada significa que no se pudo acceder al archivo. Un error de análisis significa que se accedió al archivo, pero sus bytes no son utilizables. Consultar la clase permite saber cuál es.
• El valor font-subset en font_file es un marcador deliberado para la etapa de creación de subconjuntos, no una ruta real. No buscar un archivo llamado font-subset.
• CjkFontValidator muestrea puntos de código en lugar de comprobarlos todos, por lo que su cifra de cobertura es una estimación adecuada para la selección de fuentes, no una auditoría exacta byte a byte.
• Un árbol de estructura vacío se informa como no conforme con PDF/UA-2 por diseño. Este es el comportamiento documentado del motor, no un defecto.

Ver también

• Referencia de excepciones
• Validación de PDF/A y PDF/UA
• Índice de la base de conocimientos

Glosario: creación de subconjunto de fuentes · cobertura CJK · árbol de estructura