Pemecahan masalah: fon, subsetting, dan penandaan

Cakupan

Entri-entri ini mencakup kegagalan resolusi dan parsing fon yang muncul melalui NextPDF\Exception\FontNotFoundException dan NextPDF\Exception\FontParsingException. Entri-entri ini juga mencakup diagnostik cakupan bahasa Tionghoa, Jepang, dan Korea (CJK) serta masalah pohon struktur yang memengaruhi output bertanda. Setiap entri menyebutkan eksepsi atau pengujian yang tepat agar Anda dapat memverifikasi penyebabnya.

Entri: fon tidak ditemukan

• Gejala. FontNotFoundException dengan pesan berbentuk Font "<name>" not found. Searched: [<paths>].
• Kemungkinan penyebab. Famili fon atau jalur berkas yang diminta tidak ada, tidak dapat dibaca, atau berada di direktori fon yang tidak dapat diakses oleh runtime. Data fon mungkin valid, tetapi mesin tetap tidak dapat mengaksesnya.
• Bukti / diagnosis. getContext() mengembalikan font_name, search_paths, dan fallback_attempted. Gunakan search_paths untuk memeriksa setiap lokasi yang dicoba oleh mesin. Gunakan fallback_attempted untuk memastikan apakah fallback sudah dijalankan.
• Penyelesaian.
  1. Bandingkan font_name yang diminta dengan berkas fon yang sebenarnya ada.
  2. Tambahkan direktori yang berisi fon tersebut ke direktori fon yang dikonfigurasi, atau perbaiki jalur yang Anda berikan.
  3. Verifikasi bahwa pengguna runtime dapat membaca berkas tersebut.
  4. Jalankan kembali pemanggilan tersebut.
• Terkait. Referensi eksepsi.

Entri: berkas fon gagal di-parse

• Gejala. FontParsingException dengan pesan berbentuk Failed to parse font file "<file>": <reason>.
• Kemungkinan penyebab. Mesin menemukan berkas fon, tetapi tidak dapat memakai isinya: header yang terpotong, direktori tabel yang tidak valid, atau tabel wajib yang hilang seperti head, hhea, atau OS/2.
• Bukti / diagnosis. getContext() mengembalikan font_file dan parse_error. parse_error menyebutkan masalah strukturalnya.
• Penyelesaian.
  1. Baca parse_error untuk mengidentifikasi cacat strukturalnya.
  2. Ganti berkas fon dengan salinan tepercaya dari muka huruf yang sama.
  3. Jalankan kembali pemanggilan tersebut.
• Terkait. Referensi eksepsi.

Entri: subsetting gagal pada tabel fon yang cacat

• Gejala. FontParsingException dengan nilai font_file berupa font-subset dan parse_error seperti Invalid head table: too short, Invalid hhea table: too short, Invalid maxp table: too short, atau Failed to unpack font data.
• Kemungkinan penyebab. Fon berhasil melewati pemuatan awal, tetapi sebuah tabel yang diperlukan untuk subsetting terpotong atau tidak dapat dibongkar. Subsetter menolak fon tersebut alih-alih menghasilkan subset yang rusak.
• Bukti / diagnosis. Ketika tabel head, hhea, atau maxp terlalu pendek atau pembongkaran gagal, src/Typography/FontSubsetter.php memunculkan FontParsingException dengan token harfiah font-subset sebagai nama berkas. Token tersebut memberi tahu Anda bahwa kegagalan terjadi selama subsetting, bukan pemuatan awal.
• Penyelesaian.
  1. Ganti fon sumber dengan salinan utuh yang tidak terpotong dari muka huruf yang sama.
  2. Jika sebuah alat build menghasilkan fon, hasilkan ulang dan verifikasi bahwa tabel head, hhea, dan maxp lengkap.
  3. Jalankan kembali build.
• Terkait. Validasi PDF/A dan PDF/UA.

Entri: teks CJK ditampilkan dengan glif yang hilang

• Gejala. Teks bahasa Tionghoa, Jepang, atau Korea ditampilkan sebagai kotak kosong atau karakter yang hilang, dan cakupan CJK pada fon tersebut belum pasti.
• Kemungkinan penyebab. Fon yang dipilih tidak mencakup blok Unicode yang dibutuhkan oleh skrip tersebut. Setiap skrip CJK membutuhkan blok-blok tertentu selain blok ideograf bersama.
• Bukti / diagnosis. src/Typography/CjkFontValidator.php menyediakan validateCoverage(FontInfo $font, CjkScript $script). Fungsi ini mengembalikan CjkCoverageResult dengan persentase cakupan dan blok apa pun yang berada di bawah ambang pelaporan 50%. Validator ini mengambil sampel titik kode. Validator ini bersifat diagnostik dan tidak mengubah pemuatan fon.
• Penyelesaian.
  1. Jalankan CjkFontValidator::validateCoverage() untuk fon dan skrip target.
  2. Baca missingRanges untuk melihat blok mana yang tidak tercakup, misalnya Bopomofo untuk bahasa Tionghoa Tradisional, Hiragana dan Katakana untuk bahasa Jepang, dan Hangul Syllables untuk bahasa Korea.
  3. Pilih fon yang mencakup blok-blok tersebut, atau tambahkan fon fallback yang mencakupnya.
  4. Jalankan kembali proses rendering dan periksa ulang cakupannya.
• Terkait. Referensi eksepsi.

Entri: CMap pradefinisi tidak cocok dengan skrip CJK

• Gejala. Teks CJK dipetakan ke glif yang salah, atau dokumen menggunakan CMap pradefinisi yang tidak cocok dengan bahasanya.
• Kemungkinan penyebab. Skrip yang terdeteksi menentukan nama CMap pradefinisi Adobe. Fon yang hanya mencakup blok ideograf bersama, tanpa blok khusus skrip, terdeteksi sebagai bahasa Tionghoa Sederhana sesuai rancangan.
• Bukti / diagnosis. CjkFontValidator::detectScript() mengembalikan skrip yang terdeteksi, dan resolvePredefinedCMapName() memetakannya: bahasa Tionghoa Sederhana ke UniGB-UTF16-H, bahasa Tionghoa Tradisional ke UniCNS-UTF16-H, bahasa Jepang ke UniJIS-UTF16-H, dan bahasa Korea ke UniKS-UTF16-H. Jika tidak ada blok khusus skrip yang tersedia, deteksi akan kembali ke bahasa Tionghoa Sederhana.
• Penyelesaian.
  1. Pastikan fon menyertakan blok khusus skrip: Bopomofo untuk bahasa Tionghoa Tradisional, Hiragana atau Katakana untuk bahasa Jepang, dan Hangul untuk bahasa Korea.
  2. Jika dokumen berbahasa Tionghoa Tradisional tetapi fon tidak memiliki blok Bopomofo, pilih fon yang menyertakannya agar deteksi menghasilkan skrip yang dimaksud.
  3. Jalankan kembali proses rendering.
• Terkait. Referensi eksepsi.

Entri: konten bertanda tidak menghasilkan pohon struktur yang dapat dipakai

• Gejala. Build bertanda tidak menghasilkan struktur, atau pemeriksaan aksesibilitas di tahap hilir melaporkan pohon struktur yang kosong atau hilang.
• Kemungkinan penyebab. Build memancarkan konten di luar jalur penandaan, sehingga elemen struktur tidak dibuat. Pohon struktur tetap kosong.
• Bukti / diagnosis. src/Accessibility/StructureTree.php dan src/Accessibility/TaggedContentEmitter.php membangun pohon struktur dari konten bertanda. Pengujian tests/Integration/Accessibility/EmptyTaggedPdfDoesNotAdvertisePdfUa2Test.php memastikan bahwa pohon struktur kosong tidak menyatakan diri sebagai PDF/UA-2.
• Penyelesaian.
  1. Pastikan konten dipancarkan melalui jalur penandaan agar elemen struktur dibuat.
  2. Verifikasi bahwa setiap urutan marked-content dipetakan ke sebuah elemen struktur.
  3. Jalankan kembali build dan periksa pohon strukturnya.
• Terkait. Validasi PDF/A dan PDF/UA.

Entri: tag bahasa elemen struktur ditolak

• Gejala. Build gagal karena nilai bahasa pada sebuah elemen struktur atau pada dokumen bukan tag valid.
• Kemungkinan penyebab. Bahasa yang diberikan bukan tag BCP 47 yang valid. Validator menolak tag yang cacat alih-alih memancarkannya.
• Bukti / diagnosis. src/Accessibility/Bcp47Validator.php memvalidasi tag tersebut. Tag yang tidak valid memunculkan src/Accessibility/InvalidBcp47TagException.php. tests/Unit/Conformance/PdfUa2Section844LangStrictTest.php menguji persyaratan bahasa PDF/UA-2 yang ketat.
• Penyelesaian.
  1. Ganti nilai bahasa dengan tag BCP 47 yang valid, seperti en-US, de-DE, atau zh-Hant-TW.
  2. Atur bahasa pada elemen struktur tertentu ketika sebuah bagian berbeda dari bahasa dokumen.
  3. Jalankan kembali build.
• Terkait. Validasi PDF/A dan PDF/UA.

Kasus khusus & jebakan

• FontNotFoundException dan FontParsingException melaporkan kegagalan yang berbeda. Tidak ditemukan berarti berkas tidak dapat dijangkau. Parsing berarti berkas dapat dijangkau, tetapi byte-nya tidak dapat digunakan. Baca kelas tersebut untuk mengidentifikasi kegagalan mana yang terjadi.
• font-subset di dalam font_file adalah penanda yang memang disengaja untuk tahap subsetting, bukan jalur yang sebenarnya. Jangan mencari berkas bernama font-subset.
• CjkFontValidator mengambil sampel titik kode alih-alih memeriksa setiap titik kode, sehingga angka cakupannya merupakan perkiraan untuk pemilihan fon, bukan audit yang akurat byte demi byte.
• Pohon struktur kosong dilaporkan sebagai bukan PDF/UA-2 sesuai rancangan. Ini adalah perilaku mesin yang terdokumentasi, bukan cacat.

Lihat juga

• Referensi eksepsi
• Validasi PDF/A dan PDF/UA
• Indeks basis pengetahuan

Glosarium: subsetting fon · cakupan CJK · pohon struktur