การแก้ไขปัญหา: ฟอนต์ การทำ subset และการแท็ก

ขอบเขต

รายการต่อไปนี้ครอบคลุมความล้มเหลวในการค้นหาฟอนต์และการแยกวิเคราะห์ที่เกิดขึ้นผ่าน NextPDF\Exception\FontNotFoundException และ NextPDF\Exception\FontParsingException รวมถึงการวินิจฉัยความครอบคลุมของภาษาจีน ญี่ปุ่น และเกาหลี (CJK) และปัญหา structure tree ที่ส่งผลต่อเอาต์พุตที่มีการแท็ก แต่ละรายการระบุข้อยกเว้นหรือการทดสอบที่เฉพาะเจาะจง เพื่อให้ตรวจสอบสาเหตุได้

รายการ: ไม่พบฟอนต์

• อาการ FontNotFoundException พร้อมข้อความรูปแบบ Font "<name>" not found. Searched: [<paths>]
• สาเหตุที่เป็นไปได้ ตระกูลฟอนต์หรือพาธของไฟล์ที่ร้องขอไม่มีอยู่ ไม่สามารถอ่านได้ หรืออยู่ในไดเรกทอรีฟอนต์ที่ runtime เข้าถึงไม่ได้ ข้อมูลฟอนต์อาจถูกต้อง แต่เอนจินยังเข้าถึงข้อมูลฟอนต์ไม่ได้
• หลักฐาน / การวินิจฉัย getContext() จะคืนค่า font_name, search_paths และ fallback_attempted ใช้ search_paths เพื่อตรวจสอบทุกตำแหน่งที่เอนจินพยายามค้นหา ใช้ fallback_attempted เพื่อยืนยันว่ามีการเรียกใช้ fallback ไปแล้วหรือไม่
• การแก้ไข

1. เปรียบเทียบ font_name ที่ร้องขอกับไฟล์ฟอนต์ที่มีอยู่จริง
2. เพิ่มไดเรกทอรีที่มีฟอนต์อยู่เข้าไปยังไดเรกทอรีฟอนต์ที่กำหนดค่าไว้ หรือแก้ไขพาธที่ส่งเข้ามาให้ถูกต้อง
3. ตรวจสอบว่าผู้ใช้ของ runtime สามารถอ่านไฟล์ได้
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. เรียกใช้งานอีกครั้ง

• ที่เกี่ยวข้อง ข้อมูลอ้างอิงข้อยกเว้น

รายการ: การทำ subset ล้มเหลวเนื่องจากตารางฟอนต์ผิดรูปแบบ

• อาการ 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
• สาเหตุที่เป็นไปได้ ฟอนต์ผ่านการโหลดเริ่มต้นแล้ว แต่ตารางที่จำเป็นสำหรับการทำ subset ถูกตัดทอนหรือไม่สามารถ unpack ได้ ตัวทำ subset จะปฏิเสธฟอนต์แทนที่จะสร้าง subset ที่เสียหาย
• หลักฐาน / การวินิจฉัย เมื่อตาราง head, hhea หรือ maxp สั้นเกินไปหรือการ unpack ล้มเหลว src/Typography/FontSubsetter.php จะส่ง FontParsingException โดยใช้โทเค็นตามตัวอักษร font-subset เป็นชื่อไฟล์ โทเค็นนี้บ่งบอกว่าความล้มเหลวเกิดขึ้นระหว่างการทำ subset ไม่ใช่ระหว่างการโหลดเริ่มต้น
• การแก้ไข

1. แทนที่ฟอนต์ต้นทางด้วยสำเนาที่สมบูรณ์และไม่ถูกตัดทอนของฟอนต์หน้าตาเดียวกัน
2. หากมีเครื่องมือ build สร้างฟอนต์ขึ้น ให้สร้างฟอนต์ใหม่และตรวจสอบว่าตาราง head, hhea และ maxp สมบูรณ์
3. เรียกใช้งาน build อีกครั้ง

• ที่เกี่ยวข้อง การตรวจสอบความถูกต้องของ PDF/A และ PDF/UA

รายการ: ข้อความ CJK แสดงผลโดยมีกลีฟขาดหายไป

• อาการ ข้อความภาษาจีน ญี่ปุ่น หรือเกาหลีแสดงผลเป็นกล่องว่างหรืออักขระขาดหายไป และความครอบคลุม CJK ของฟอนต์ยังไม่แน่ชัด
• สาเหตุที่เป็นไปได้ ฟอนต์ที่เลือกไม่ครอบคลุมบล็อก Unicode ที่สคริปต์ต้องการ สคริปต์ CJK แต่ละแบบต้องใช้บล็อกเฉพาะเพิ่มเติมจากบล็อกอักษรภาพที่ใช้ร่วมกัน
• หลักฐาน / การวินิจฉัย src/Typography/CjkFontValidator.php มี validateCoverage(FontInfo $font, CjkScript $script) ซึ่งคืนค่า CjkCoverageResult พร้อมเปอร์เซ็นต์ความครอบคลุมและบล็อกใด ๆ ที่ต่ำกว่าเกณฑ์การรายงาน 50% ตัวตรวจสอบจะสุ่มตัวอย่าง codepoint เพื่อใช้เป็นเครื่องมือวินิจฉัย และจะไม่เปลี่ยนการโหลดฟอนต์
• การแก้ไข

1. เรียกใช้ CjkFontValidator::validateCoverage() สำหรับฟอนต์และสคริปต์เป้าหมาย
2. อ่าน missingRanges เพื่อดูว่าบล็อกใดไม่ถูกครอบคลุม เช่น Bopomofo สำหรับภาษาจีนตัวเต็ม Hiragana และ Katakana สำหรับภาษาญี่ปุ่น และ Hangul Syllables สำหรับภาษาเกาหลี
3. เลือกฟอนต์ที่ครอบคลุมบล็อกเหล่านั้น หรือเพิ่มฟอนต์ fallback ที่ครอบคลุม
4. เรียกใช้การเรนเดอร์อีกครั้งและตรวจสอบความครอบคลุมอีกครั้ง

• ที่เกี่ยวข้อง ข้อมูลอ้างอิงข้อยกเว้น

รายการ: CMap ที่กำหนดไว้ล่วงหน้าไม่ตรงกับสคริปต์ CJK

• อาการ ข้อความ CJK ถูกแมปไปยังกลีฟที่ไม่ถูกต้อง หรือเอกสารใช้ CMap ที่กำหนดไว้ล่วงหน้าซึ่งไม่ตรงกับภาษาของเอกสาร
• สาเหตุที่เป็นไปได้ สคริปต์ที่ตรวจพบจะกำหนดชื่อ CMap ที่กำหนดไว้ล่วงหน้าของ Adobe ฟอนต์ที่ครอบคลุมเฉพาะบล็อกอักษรภาพที่ใช้ร่วมกัน แต่ไม่มีบล็อกเฉพาะของสคริปต์ จะถูกตรวจพบเป็นภาษาจีนตัวย่อตามการออกแบบ
• หลักฐาน / การวินิจฉัย CjkFontValidator::detectScript() จะคืนค่าสคริปต์ที่ตรวจพบ และ resolvePredefinedCMapName() จะแมปสคริปต์นั้น: ภาษาจีนตัวย่อไปยัง UniGB-UTF16-H ภาษาจีนตัวเต็มไปยัง UniCNS-UTF16-H ภาษาญี่ปุ่นไปยัง UniJIS-UTF16-H และภาษาเกาหลีไปยัง UniKS-UTF16-H หากไม่มีบล็อกเฉพาะของสคริปต์ การตรวจหาจะถอยกลับไปเป็นภาษาจีนตัวย่อ
• การแก้ไข

1. ยืนยันว่าฟอนต์มาพร้อมบล็อกเฉพาะของสคริปต์: Bopomofo สำหรับภาษาจีนตัวเต็ม Hiragana หรือ Katakana สำหรับภาษาญี่ปุ่น และ Hangul สำหรับภาษาเกาหลี
2. หากเอกสารเป็นภาษาจีนตัวเต็มแต่ฟอนต์ไม่มีบล็อก Bopomofo ให้เลือกฟอนต์ที่มีบล็อกดังกล่าว เพื่อให้การตรวจหาแก้ไขไปยังสคริปต์ที่ต้องการ
3. เรียกใช้การเรนเดอร์อีกครั้ง

• ที่เกี่ยวข้อง ข้อมูลอ้างอิงข้อยกเว้น

รายการ: เนื้อหาแบบแท็กไม่สร้าง structure tree ที่ใช้งานได้

• อาการ การ build แบบแท็กไม่สร้างโครงสร้าง หรือการตรวจสอบการช่วยการเข้าถึงในขั้นถัดไปรายงานว่า structure tree ว่างเปล่าหรือขาดหายไป
• สาเหตุที่เป็นไปได้ การ build สร้างเนื้อหานอกเส้นทางการแท็ก จึงไม่ได้สร้างองค์ประกอบโครงสร้างใด ๆ และ structure tree จะยังคงว่างเปล่า
• หลักฐาน / การวินิจฉัย src/Accessibility/StructureTree.php และ src/Accessibility/TaggedContentEmitter.php จะสร้าง structure tree จากเนื้อหาแบบแท็ก การทดสอบ tests/Integration/Accessibility/EmptyTaggedPdfDoesNotAdvertisePdfUa2Test.php ยืนยันว่า structure tree ที่ว่างเปล่าจะไม่ประกาศตัวเป็น PDF/UA-2
• การแก้ไข

1. ยืนยันว่ามีการสร้างเนื้อหาผ่านเส้นทางการแท็ก เพื่อให้องค์ประกอบโครงสร้างถูกสร้างขึ้น
2. ตรวจสอบว่าลำดับ marked-content แต่ละชุดถูกแมปไปยังองค์ประกอบโครงสร้าง
3. เรียกใช้งาน build อีกครั้งและตรวจสอบ structure tree

• ที่เกี่ยวข้อง การตรวจสอบความถูกต้องของ PDF/A และ PDF/UA

รายการ: แท็กภาษาขององค์ประกอบโครงสร้างถูกปฏิเสธ

• อาการ การ build ล้มเหลวเนื่องจากค่าภาษาบนองค์ประกอบโครงสร้างหรือบนเอกสารไม่ใช่แท็กที่ถูกต้อง
• สาเหตุที่เป็นไปได้ ภาษาที่ระบุไม่ใช่แท็ก BCP-47 ที่ถูกต้อง ตัวตรวจสอบจะปฏิเสธแท็กที่มีรูปแบบไม่ถูกต้องแทนที่จะสร้างแท็กเหล่านั้นออกมา
• หลักฐาน / การวินิจฉัย src/Accessibility/Bcp47Validator.php จะตรวจสอบความถูกต้องของแท็ก แท็กที่ไม่ถูกต้องจะทำให้เกิด src/Accessibility/InvalidBcp47TagException.php ส่วน tests/Unit/Conformance/PdfUa2Section844LangStrictTest.php ทดสอบข้อกำหนดด้านภาษาที่เข้มงวดของ PDF/UA-2
• การแก้ไข

1. แทนที่ค่าภาษาด้วยแท็ก BCP-47 ที่ถูกต้อง เช่น en-US, de-DE หรือ zh-Hant-TW
2. กำหนดภาษาบนองค์ประกอบโครงสร้างที่เฉพาะเจาะจง เมื่อข้อความบางส่วนแตกต่างจากภาษาของเอกสาร
3. เรียกใช้งาน build อีกครั้ง

• ที่เกี่ยวข้อง การตรวจสอบความถูกต้องของ PDF/A และ PDF/UA

กรณีขอบเขตและข้อควรระวัง

• FontNotFoundException และ FontParsingException รายงานความล้มเหลวคนละประเภท ไม่พบ หมายความว่าไม่สามารถเข้าถึงไฟล์ได้ การแยกวิเคราะห์ หมายความว่าเข้าถึงไฟล์ได้แล้ว แต่ไบต์ของไฟล์ใช้งานไม่ได้ อ่านคลาสเพื่อระบุว่าความล้มเหลวใดเกิดขึ้น
• font-subset ใน font_file เป็นเครื่องหมายที่กำหนดไว้โดยเจตนาสำหรับขั้นการทำ subset ไม่ใช่พาธจริง อย่ามองหาไฟล์ที่ชื่อ font-subset
• CjkFontValidator สุ่มตัวอย่าง codepoint แทนการตรวจสอบทุกตัว ดังนั้นค่าความครอบคลุมจึงเป็นค่าประมาณสำหรับการเลือกฟอนต์ ไม่ใช่การตรวจสอบที่แม่นยำระดับไบต์
• structure tree ที่ว่างเปล่าจะถูกรายงานว่าไม่เป็น PDF/UA-2 ตามการออกแบบ นี่คือพฤติกรรมของเอนจินที่มีการบันทึกไว้ ไม่ใช่ข้อบกพร่อง

ดูเพิ่มเติม

• ข้อมูลอ้างอิงข้อยกเว้น
• การตรวจสอบความถูกต้องของ PDF/A และ PDF/UA
• ดัชนีฐานความรู้

อภิธานศัพท์: การทำ subset ฟอนต์ · ความครอบคลุม CJK · structure tree