深入認識 NextPDF

Spec Spec: ISO 32000-2 ISO 32000-2 Spec Spec: WCAG 2.2 WCAG 2.2 Evidence ¶ Editorial Evidence: Editorial

概覽

Insider_ 是文件中說明 NextPDF 為何會有這種行為的部分。 參考文件告訴你某個方法會回傳什麼。 Insider_ 則告訴你讓它回傳那個結果的推理，以及支撐這套推理的標準或測試。

它是為已經熟悉 PDF 與 PHP 程式碼庫的資深工程師而寫。比起十頁讓人安心的空話，這樣的讀者更願意讀一頁坦白的內容。

為何這很重要

PDF 是一種歷史悠久、慣例嚴謹的格式，而且它很嚴格：它不容許任何猜測。對你隱藏這一點的函式庫用起來會很愉快，直到某份已簽署的文件在正式環境中驗證失敗，卻沒人說得出原因為止。

Insider_ 採取相反的立場。每一頁都會說明其主張的邊界、指出主張背後的佐證，並在你自己發現之前先把限制講清楚。它的目的不是讓你留下深刻印象，而是讓你做出一個能在審查中站得住腳的決定。

簡短版本

• Insider_ 頁面屬於評述與說明性質，並非 API 參考文件。
• 每一頁都有一排徽章，標示出相關標準以及該頁所依據的佐證類型。
• 每一頁都遵循相同的十節結構，因此你可以直接略讀到需要的章節，而不必每次重新適應版面。
• 這裡不會在內文中重述任何量測數據；數字只會放在擁有該項量測的頁面上，這樣某個數值就不會在文字敘述中悄悄過時。

NextPDF 的處理方式

每一個 Insider_ 頁面都只談一個主題，可獨立閱讀，並經過編排，讓最有用的陳述靠近頁面頂端。這樣的結構是刻意安排的。它遵循資訊設計的指引：當相關內容被歸類在一起、層級結構清楚可見時，讀者能更快找到所需的資訊。它也讓頁面在螢幕報讀器下依然好用，因為畫面上的順序就是標記中的順序。

一個頁面會依照這個順序，從脈絡走向主張、再走向限制：

1. At a glance What this page is, in two sentences.
2. Why this matters The cost of getting it wrong.
3. The short version The answer, before the detail.
4. How NextPDF approaches it The reasoning and the mechanism.
5. What the evidence says The standard, code, or test — tagged.
6. Practical example A small, runnable shape.
7. Common misconception The trap, named.
8. Limits and boundaries Where the claim stops.

一個 Insider_ 頁面由上而下的結構：讀者可以在任一步驟停下，仍然能得到完整且站得住腳的答案。

Human-factors note: Human-factors note

徽章列、固定的章節順序，以及 Insider_ 結尾底線上那一抹暖色強調，都是立基於人因工程指引的設計選擇，而不是裝飾性的安排。這抹強調色標記出該章節， 卻不至於變成干擾。它從不以動畫呈現，是導覽中唯一的色彩訊號，而螢幕報讀器讀出的字仍然是 「Insider」。這裡的意義從不單靠色彩來傳達。每個徽章也都附有一個文字標籤與一個角色詞。

佐證怎麼說

Insider_ 不會要求你信任它。 每一頁都會宣告一個佐證等級，並由徽章列呈現出來：

• Evidence { } Code-backed Evidence: Code-backed — 該主張已對照引擎本身的原始碼或可執行範例進行驗證。
• Evidence § Standard-backed Evidence: Standard-backed — 該主張依據某份已發布標準中的某個條款，經改寫並引用，絕不會逐字引用授權文件的內容。
• Evidence ✓ Test-backed Evidence: Test-backed — 該主張由測試套件中的一項測試固定下來。
• Evidence ◇ Design principle Evidence: Design principle — 該頁陳述一項刻意的設計決策，以論證而非量測來支撐。

當某一頁同時使用多種佐證時，它會以 Evidence ⊕ Mixed evidence Evidence: Mixed evidence 明確標示，而不會誇大地宣稱自己只有單一依據。某一頁所依據的標準，會在徽章列中以其精確的識別碼標示——例如 Spec Spec: ISO 32000-2, §7 ISO 32000-2 §7 用於 PDF 語法，或 Spec Spec: ETSI EN 319 142-1 ETSI EN 319 142-1 用於 PAdES ——讓你可以自行拿著這個參照去追溯原始出處。

實際範例

閱讀一個 Insider_ 頁面理應很快。要判斷 NextPDF 的簽章處理是否適合受規範的工作流程，你會打開 簽章在 PDF 中的位置，讀過 At a glance 與 The short version，然後直接跳到 Limits and boundaries。三個簡短的章節就能回答「我能不能為這個選擇辯護？」。而且在你讀到任何一個字的內文之前，徽章列就已經告訴你這項主張是以標準為依據。

如果答案是肯定的，Related docs 會帶你繼續往下走——PAdES 基準設定檔 與 長期驗證——不必搜尋。

常見誤解

Insider_ 有時會被誤認為行銷文案：一個吹捧這套引擎的地方。它的設計正好相反。一個頁面樂於告訴你 何時不該使用 NextPDF，就如同它樂於告訴你該如何使用它一樣。它從不將 NextPDF 與競爭對手相比——無論是貶低對方，還是抬高對方。這裡唯一的主題就是 NextPDF，以及它所遵循的標準。

限制與邊界

本頁是入門導覽，而非規格說明。它本身不主張任何引擎行為。每一項行為主張都存在於擁有它的主題頁面上，並帶有該頁的佐證等級。Insider_ 的內容屬於評述性質，並且原生於 nextpdf-docs。它在這裡撰寫、在這裡審查，並非從任何套件的原始碼樹彙整而來。凡是某主題觸及受授權保護的標準之處，該頁都會改寫並引用該條款。它絕不會重現標準的原文。

相關文件

• NextPDF 的設計理念 — 用來衡量每一頁的原則。
• 標準全貌 — NextPDF 所追蹤的標準地圖，以及一個條款如何轉化為行為。
• 把文件當作產品 — 支撐這些頁面的紀律。
• 引用紀律 — 佐證等級代表什麼，以及為何要改寫標準。

詞彙表

• Insider_ — 說明 NextPDF 背後推理的評述章節，有別於 API 參考文件。結尾的底線是章節名稱的一部分；加上強調色只是為了凸顯。
• 佐證等級 — 單一頁面對其主張所宣告的依據（code-backed、standard-backed、test-backed、benchmark-backed、artifact-backed、design-principle、editorial 或 mixed）。
• 徽章列 — 位於每個 Insider_ 頁面頂端的那一條，標示出相關標準與該頁的佐證等級。
• nextpdf-docs-native — 在文件網站本身撰寫並擁有的內容，並非衍生自任何套件儲存庫。