フォント、サブセット化、タグ付けのトラブルシューティング

範囲

このページの各エントリでは、エンジンが NextPDF\Exception\FontNotFoundException および NextPDF\Exception\FontParsingException として発生させるフォントの resolve（解決）とパースの失敗を扱います。また、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 カバレッジが疑われます。
考えられる原因 選択したフォントが、そのスクリプトに必要な Unicode ブロックをカバーしていません。各 CJK スクリプトでは、共通の表意文字ブロックに加えて、固有のブロックが必要になります。
証拠 / 診断 src/Typography/CjkFontValidator.php は validateCoverage(FontInfo $font, CjkScript $script) を提供します。これは、カバレッジの割合と、50% の報告しきい値を下回るブロックを含む CjkCoverageResult を返します。バリデーターはコードポイントをサンプリングします。これは診断用であり、フォントのロードを変更することはありません。
解決方法
1. 対象のフォントとターゲットスクリプトに対して CjkFontValidator::validateCoverage() を実行します。
2. フィールド missingRanges で、どのブロックがカバーされていないかを確認できます。たとえば、繁体字中国語では注音、日本語ではひらがなとカタカナ、韓国語ではハングル音節文字です。
3. それらのブロックをカバーするフォントを選択するか、カバーできるフォールバックフォントを追加します。
4. レンダリングを再実行し、カバレッジを再確認します。
関連項目 例外リファレンス。

エントリ: 定義済み 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 ではないと報告されます。これは、エンジンの文書化された動作であり、欠陥ではありません。