콘텐츠로 이동
NextPDF

문제 해결: 글꼴, 서브셋 및 태깅

범위

섹션 제목: “범위”

이 문서는 엔진이 NextPDF\Exception\FontNotFoundException 및 NextPDF\Exception\FontParsingException을 통해 발생시키는 글꼴 확인 및 파싱 실패를 다룹니다. 또한 CJK 커버리지 진단과 태그된 출력에 영향을 미치는 구조 트리 문제도 다룹니다. 각 항목은 정확한 예외나 테스트를 명시하므로 원인을 확인할 수 있습니다.

항목: 글꼴을 찾을 수 없음

섹션 제목: “항목: 글꼴을 찾을 수 없음”
  • 증상. FontNotFoundException이 Font "<name>" not found. Searched: [<paths>] 형식의 메시지와 함께 발생합니다.
  • 유력한 원인. 요청한 글꼴 패밀리나 파일 경로가 존재하지 않거나 읽을 수 없거나, 구성된 글꼴 디렉터리에 접근할 수 없는 상태입니다. 글꼴 데이터 자체는 유효할 수 있지만 엔진이 해당 위치까지 도달하지 못합니다.
  • 증거 / 진단. getContext()는 font_name, search_paths, fallback_attempted를 반환합니다. search_paths에서 엔진이 시도한 모든 위치를 확인하십시오. fallback_attempted에서 폴백이 이미 시도되었는지 확인하십시오.
  • 해결.
    1. 요청한 font_name이 실제로 존재하는 파일과 일치하는지 비교하십시오.
    2. 글꼴이 들어 있는 디렉터리를 구성된 글꼴 디렉터리에 추가하거나, 전달한 경로를 수정하십시오.
    3. 런타임 사용자가 해당 파일을 읽을 수 있는지 확인하십시오.
    4. 호출을 다시 실행하십시오.
  • 관련 항목. 예외 레퍼런스.

항목: 글꼴 파일 파싱 실패

섹션 제목: “항목: 글꼴 파일 파싱 실패”
  • 증상. FontParsingException이 Failed to parse font file "<file>": <reason> 형식의 메시지와 함께 발생합니다.
  • 유력한 원인. 글꼴 파일은 찾았지만 내용을 사용할 수 없습니다. 잘린 헤더, 잘못된 테이블 디렉터리 또는 head, hhea, OS/2 같은 필수 테이블 누락이 원인일 수 있습니다.
  • 증거 / 진단. getContext()는 font_file과 parse_error를 반환합니다. parse_error 필드는 구조적 문제를 가리킵니다.
  • 해결.
    1. 반환된 parse_error를 읽어 구조적 결함을 식별하십시오.
    2. 글꼴 파일을 정상으로 확인된 동일 서체의 사본으로 교체하십시오.
    3. 호출을 다시 실행하십시오.
  • 관련 항목. 예외 레퍼런스.

항목: 잘못된 형식의 글꼴 테이블로 인해 서브셋이 실패함

섹션 제목: “항목: 잘못된 형식의 글꼴 테이블로 인해 서브셋이 실패함”
  • 증상. FontParsingException이 font_file 값 font-subset 및 다음과 같은 parse_error와 함께 발생합니다: Invalid head table: too short, Invalid hhea table: too short, Invalid maxp table: too short, 또는 Failed to unpack font data.
  • 유력한 원인. 글꼴이 초기 로딩은 통과했지만 서브셋에 필요한 테이블이 잘려 있거나 언팩할 수 없습니다. 서브셋터는 손상된 서브셋을 내보내는 대신 글꼴을 거부합니다.
  • 증거 / 진단. head, hhea 또는 maxp 테이블이 너무 짧거나 언팩이 실패하면, src/Typography/FontSubsetter.php가 FontParsingException을, 파일 이름으로 리터럴 토큰 font-subset을 사용하여 발생시킵니다. 이 토큰은 실패가 초기 로드가 아니라 서브셋 단계에서 발생했음을 알려 줍니다.
  • 해결.
    1. 소스 글꼴을 동일한 서체의 잘리지 않은 사본으로 교체하십시오.
    2. 글꼴이 빌드 도구로 생성되는 경우, 재생성한 뒤 head, hhea, maxp 테이블이 완전한지 확인하십시오.
    3. 빌드를 다시 실행하십시오.
  • 관련 항목. PDF/A 및 PDF/UA 검증.

항목: CJK 텍스트가 글리프 누락으로 렌더링됨

섹션 제목: “항목: CJK 텍스트가 글리프 누락으로 렌더링됨”
  • 증상. 중국어, 일본어, 한국어 텍스트가 빈 상자나 누락된 문자로 렌더링되며, 글꼴의 CJK 커버리지가 의심됩니다.
  • 유력한 원인. 선택한 글꼴에 해당 스크립트에 필요한 유니코드 블록이 포함되어 있지 않습니다. 각 CJK 스크립트에는 공유 표의문자 블록 외에도 특정 블록이 필요합니다.
  • 증거 / 진단. src/Typography/CjkFontValidator.php는 validateCoverage(FontInfo $font, CjkScript $script)를 제공합니다. 이 메서드는 커버리지 백분율과 50% 보고 임계값 미만인 블록을 담은 CjkCoverageResult를 반환합니다. 검증기는 코드 포인트를 샘플링합니다. 이는 진단용이며 글꼴 로딩을 수정하지 않습니다.
  • 해결.
    1. 해당 글꼴과 대상 스크립트에 대해 CjkFontValidator::validateCoverage()를 실행하십시오.
    2. 반환된 missingRanges를 읽어 어떤 블록이 포함되지 않았는지 확인하십시오. 예를 들어 번체 중국어의 경우 주음부호, 일본어의 경우 히라가나와 가타카나, 한국어의 경우 한글 음절입니다.
    3. 해당 블록을 포함하는 글꼴을 선택하거나, 해당 블록을 포함하는 폴백 글꼴을 추가하십시오.
    4. 렌더링을 다시 실행하고 커버리지를 다시 확인하십시오.
  • 관련 항목. 예외 레퍼런스.

항목: 미리 정의된 CMap이 CJK 스크립트와 일치하지 않음

섹션 제목: “항목: 미리 정의된 CMap이 CJK 스크립트와 일치하지 않음”
  • 증상. CJK 텍스트가 잘못된 글리프에 매핑되거나, 문서의 언어와 일치하지 않는 미리 정의된 CMap이 선택됩니다.
  • 유력한 원인. 감지된 스크립트에 따라 Adobe 미리 정의된 CMap 이름이 결정됩니다. 스크립트별 블록 없이 공유 표의문자 블록만 포함하는 글꼴은 설계상 간체 중국어로 감지됩니다.
  • 증거 / 진단. CjkFontValidator::detectScript()는 감지된 스크립트를 반환하고, resolvePredefinedCMapName()는 이를 매핑합니다: 간체 중국어는 UniGB-UTF16-H, 번체 중국어는 UniCNS-UTF16-H, 일본어는 UniJIS-UTF16-H, 한국어는 UniKS-UTF16-H로 매핑합니다. 스크립트별 블록이 없으면 감지 결과는 간체 중국어로 폴백됩니다.
  • 해결.
    1. 글꼴에 스크립트별 블록이 포함되어 있는지 확인하십시오. 번체 중국어의 경우 주음부호, 일본어의 경우 히라가나 또는 가타카나, 한국어의 경우 한글입니다.
    2. 문서가 번체 중국어인데 글꼴에 주음부호 블록이 없으면, 주음부호 블록이 있는 글꼴을 선택하여 감지 결과가 의도한 스크립트로 확인되도록 하십시오.
    3. 렌더링을 다시 실행하십시오.
  • 관련 항목. 예외 레퍼런스.

항목: 태그된 콘텐츠가 사용 가능한 구조 트리를 생성하지 않음

섹션 제목: “항목: 태그된 콘텐츠가 사용 가능한 구조 트리를 생성하지 않음”
  • 증상. 태그된 빌드가 구조를 생성하지 않거나, 다운스트림 접근성 검사에서 빈 구조 트리 또는 누락된 구조 트리를 보고합니다.
  • 유력한 원인. 콘텐츠가 태깅 경로를 거치지 않고 내보내져 구조 요소가 생성되지 않았습니다. 그 결과 구조 트리는 비어 있는 상태로 유지됩니다.
  • 증거 / 진단. src/Accessibility/StructureTree.php와 src/Accessibility/TaggedContentEmitter.php는 태그된 콘텐츠에서 구조 트리를 구성합니다. tests/Integration/Accessibility/EmptyTaggedPdfDoesNotAdvertisePdfUa2Test.php 테스트는 빈 구조 트리가 PDF/UA-2를 표방하지 않음을 확인합니다.
  • 해결.
    1. 콘텐츠가 태깅 경로를 통해 내보내져 구조 요소가 생성되는지 확인하십시오.
    2. 각 표시 콘텐츠 시퀀스가 구조 요소에 매핑되는지 확인하십시오.
    3. 빌드를 다시 실행하고 구조 트리를 검사하십시오.
  • 관련 항목. PDF/A 및 PDF/UA 검증.

항목: 구조 요소 언어 태그가 거부됨

섹션 제목: “항목: 구조 요소 언어 태그가 거부됨”
  • 증상. 구조 요소나 문서의 언어 값이 유효한 태그가 아니어서 빌드가 실패합니다.
  • 유력한 원인. 제공된 언어 값이 유효한 BCP-47 태그가 아닙니다. 검증기는 잘못된 형식의 태그를 내보내는 대신 거부합니다.
  • 증거 / 진단. src/Accessibility/Bcp47Validator.php가 태그를 검증합니다. 유효하지 않은 태그는 src/Accessibility/InvalidBcp47TagException.php를 발생시킵니다. 엄격한 PDF/UA-2 언어 요구 사항은 tests/Unit/Conformance/PdfUa2Section844LangStrictTest.php에 의해 검증됩니다.
  • 해결.
    1. 언어 값을 유효한 BCP-47 태그로 교체하십시오. 예를 들어 en-US, de-DE, 또는 zh-Hant-TW입니다.
    2. 특정 구절이 문서 언어와 다른 경우 해당 구조 요소에 언어를 설정하십시오.
    3. 빌드를 다시 실행하십시오.
  • 관련 항목. PDF/A 및 PDF/UA 검증.

엣지 케이스 및 주의 사항

섹션 제목: “엣지 케이스 및 주의 사항”
  • FontNotFoundException과 FontParsingException은 서로 다릅니다. 찾을 수 없음은 파일에 접근하지 못했음을 의미합니다. 파싱은 파일에는 접근했지만 그 바이트를 사용할 수 없음을 의미합니다. 어느 쪽인지 확인하려면 클래스를 확인하십시오.
  • 여기에서 font-subset 값이 font_file에 나타나는 것은 실제 경로가 아니라 서브셋 단계를 나타내는 의도적인 마커입니다. font-subset이라는 이름의 파일을 찾지 마십시오.
  • CjkFontValidator는 모든 코드 포인트를 검사하는 대신 샘플링하므로, 커버리지 수치는 바이트 단위의 정확한 감사 결과가 아니라 글꼴 선택에 적합한 추정치입니다.
  • 빈 구조 트리는 설계상 PDF/UA-2가 아닌 것으로 보고됩니다. 이는 결함이 아니라 엔진의 문서화된 동작입니다.

참고 항목

섹션 제목: “참고 항목”

용어집: 글꼴 서브셋 · CJK 커버리지 · 구조 트리