Bên trong NextPDF

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

Tổng quan nhanh

Insider_ là phần tài liệu giải thích vì sao NextPDF hoạt động theo cách hiện tại. Phần tham chiếu cho bạn biết một phương thức trả về gì. Insider_ cho bạn biết vì sao nó trả về giá trị đó, cũng như tiêu chuẩn hoặc bài kiểm thử nào củng cố lập luận ấy.

Nó được viết cho một kỹ sư senior đã quen với PDF và các codebase PHP. Người đọc đó thà đọc một trang trung thực còn hơn mười trang chỉ nhằm trấn an.

Vì sao điều này quan trọng

PDF là một định dạng lâu đời, nghiêm ngặt và đầy quy ước chặt chẽ: nó không dung thứ cho phỏng đoán. Một thư viện che giấu điều đó khỏi bạn có thể tạo cảm giác dễ chịu, cho đến khi một tài liệu đã ký không qua được kiểm định trong môi trường vận hành mà không ai nói được vì sao.

Insider_ chọn lập trường ngược lại. Mỗi trang nêu rõ ranh giới của điều mình khẳng định, chỉ ra bằng chứng đứng sau khẳng định đó, và nói thẳng các giới hạn trước khi bạn phải tự phát hiện chúng. Mục tiêu không phải là gây ấn tượng với bạn. Mục tiêu là giúp bạn đưa ra một quyết định mà bạn có thể bảo vệ được trong một buổi review.

Phiên bản ngắn gọn

Các trang Insider_ mang tính biên tập và giải thích, không phải tài liệu tham chiếu API.
Mỗi trang đều có một hàng huy hiệu nêu tên các tiêu chuẩn liên quan và loại bằng chứng làm cơ sở cho trang đó.
Mỗi trang tuân theo cùng một bố cục mười mục, nên bạn có thể lướt nhanh đến mục mình cần mà không phải học lại bố cục mỗi lần.
Không có nội dung nào ở đây nhắc lại một chỉ số ngay trong dòng văn; các con số nằm trên trang sở hữu phép đo đó, nên một con số không thể âm thầm trở nên lỗi thời trong văn bản.

Cách NextPDF tiếp cận vấn đề này

Mỗi trang Insider_ bao quát một chủ đề duy nhất, tự đứng vững, và đặt phát biểu hữu ích nhất ở gần đầu trang. Cấu trúc đó là có chủ đích. Nó tuân theo hướng dẫn về thiết kế thông tin: người đọc tìm thấy thứ mình cần nhanh hơn khi nội dung liên quan được nhóm lại và thứ bậc được thể hiện rõ. Nó cũng giữ cho trang dùng được với trình đọc màn hình, vì thứ tự trên màn hình chính là thứ tự trong markup.

Một trang đi từ bối cảnh đến khẳng định rồi đến giới hạn, theo thứ tự này:

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

Cách một trang Insider_ được cấu trúc, từ trên xuống dưới: người đọc có thể dừng ở bất kỳ bước nào và vẫn có một câu trả lời đầy đủ, có thể bảo vệ được.

Bằng chứng nói gì

Insider_ không yêu cầu bạn phải tin nó. Mỗi trang khai báo một cấp bằng chứng, và hàng huy hiệu hiển thị nó:

Evidence: Code-backed — khẳng định được kiểm tra dựa trên chính mã nguồn của engine hoặc một ví dụ có thể chạy.
Evidence: Standard-backed — khẳng định được neo vào một điều khoản trong một tiêu chuẩn đã công bố, được diễn giải lại và trích dẫn, không bao giờ trích nguyên văn từ một tài liệu có bản quyền.
Evidence: Test-backed — khẳng định được bảo vệ bởi một bài kiểm thử trong bộ kiểm thử.
Evidence: Design principle — trang nêu một quyết định thiết kế có chủ đích, được lập luận thay vì đo lường.

Khi một trang kết hợp nhiều loại này, nó nói rõ điều đó bằng Evidence: Mixed evidence thay vì khẳng định quá mức về một cơ sở duy nhất. Các tiêu chuẩn mà một trang dựa vào được nêu tên trong hàng huy hiệu bằng định danh chính xác của chúng — ví dụ Spec: ISO 32000-2, §7 cho cú pháp PDF, hoặc Spec: ETSI EN 319 142-1 cho PAdES — để bạn có thể tự đối chiếu tham chiếu với nguồn gốc.

Ví dụ thực tế

Việc đọc một trang Insider_ được thiết kế để diễn ra nhanh chóng. Để quyết định liệu cách xử lý chữ ký của NextPDF có phù hợp với một quy trình chịu sự quản lý hay không, bạn sẽ mở Cách chữ ký nằm trong một tệp PDF, đọc Tổng quan nhanh và Phiên bản ngắn gọn, rồi nhảy thẳng đến Giới hạn và ranh giới. Ba mục ngắn trả lời câu hỏi “tôi có thể bảo vệ lựa chọn này không”. Hàng huy hiệu đã cho bạn biết khẳng định này được tiêu chuẩn hậu thuẫn ngay cả trước khi bạn đọc một chữ nào trong phần nội dung chính.

Nếu câu trả lời là có, Tài liệu liên quan sẽ dẫn bạn đi tiếp — Các hồ sơ cơ sở PAdES và Kiểm định dài hạn — mà không cần tìm kiếm.

Hiểu lầm phổ biến

Insider_ đôi khi bị nhầm là tài liệu tiếp thị: một nơi để ca ngợi engine. Theo thiết kế, nó hoàn toàn ngược lại. Một trang sẵn sàng cho bạn biết khi nào không nên dùng NextPDF cũng như khi cho bạn biết cách dùng nó. Nó không bao giờ so sánh NextPDF với một đối thủ theo hướng kém hơn — hay tốt hơn. Chủ thể duy nhất ở đây là NextPDF và các tiêu chuẩn mà nó tuân theo.

Giới hạn và ranh giới

Trang này là phần định hướng, không phải một bản đặc tả. Bản thân nó không khẳng định bất kỳ hành vi nào của engine. Mọi khẳng định về hành vi đều nằm trên trang chủ đề sở hữu nó và mang cấp bằng chứng của trang đó. Nội dung Insider_ mang tính biên tập và thuộc về chính nextpdf-docs. Nó được viết ở đây, được review ở đây, và không được tổng hợp từ cây mã nguồn của bất kỳ gói nào. Khi một chủ đề chạm đến một tiêu chuẩn có bản quyền, trang sẽ diễn giải lại và trích dẫn điều khoản đó. Nó không bao giờ sao chép nguyên văn tiêu chuẩn.

Tài liệu liên quan

Triết lý thiết kế của NextPDF — các nguyên tắc mà mọi trang đều được đối chiếu.
Bức tranh toàn cảnh về các tiêu chuẩn — bản đồ các tiêu chuẩn mà NextPDF theo dõi và cách một điều khoản trở thành hành vi.
Tài liệu như một sản phẩm — kỷ luật đứng sau những trang này.
Kỷ luật trích dẫn — một cấp bằng chứng có ý nghĩa gì và vì sao các tiêu chuẩn được diễn giải lại.

Thuật ngữ

Insider_ — mục biên tập giải thích lập luận đứng sau NextPDF, tách biệt với tài liệu tham chiếu API. Dấu gạch dưới ở cuối là một phần của tên mục; nó chỉ được tạo kiểu để nhấn mạnh.
Cấp bằng chứng — cơ sở được khai báo cho các khẳng định trên một trang (code-backed, standard-backed, test-backed, benchmark-backed, artifact-backed, design-principle, editorial, hoặc mixed).
Hàng huy hiệu — dải ở đầu mỗi trang Insider_ nêu tên các tiêu chuẩn liên quan và cấp bằng chứng của trang.
nextpdf-docs-native — nội dung được viết và sở hữu ngay trong chính trang tài liệu, không bắt nguồn từ một kho mã của gói nào.