Bên trong NextPDF

Spec: ISO 32000-2Spec: WCAG 2.2

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. Tài liệu 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ề như vậy, cũng như tiêu chuẩn, bài kiểm thử, nguồn hay bằng chứng nào hậu thuẫn cho lập luận ấy.

Nó được viết cho kỹ sư senior đã quen với PDF và codebase PHP. Nhóm độc giả này 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à có nhiều 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 đó có thể tạo cảm giác dễ chịu, cho đến khi một tài liệu đã ký không vượt qua kiểm định trong môi trường vận hành mà không ai giải thích được vì sao.

Insider_ chọn lập trường ngược lại. Các trang nêu rõ ranh giới của những gì chúng khẳng định, gọi tên tiêu chuẩn, bài kiểm thử, nguồn hoặc 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 quyết định mà bạn có thể bảo vệ 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.
Khi một trang dựa trên các tiêu chuẩn, một hàng huy hiệu nêu tên chúng ở đầu trang.
Các bài viết dùng chung một khuôn mẫu mục lặp lại, 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; bài viết sẽ bỏ qua những bước không có nội dung trung thực để đưa vào.
Không có nội dung nào ở đây nhắc lại số liệu ngay trong câu văn; các con số nằm trên trang chịu trách nhiệm về 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_ chỉ bao quát một chủ đề, có thể đứng độc lập, và đặt phát biểu hữu ích nhất ở gần đầu trang. Cấu trúc đó có chủ đích. Cách làm này 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 bài viết đi từ bối cảnh đến khẳng định rồi đến giới hạn, qua các mục lặp lại theo thứ tự này:

At a glanceWhat this page is, in two sentences.
Why this mattersThe cost of getting it wrong.
The short versionThe answer, before the detail.
How NextPDF approaches itThe reasoning and the mechanism.
Practical exampleA small, runnable shape.
Common misconceptionThe trap, named.
Limits and boundariesWhere the claim stops.

Khuôn dạng lặp lại của một bài viết Insider_, 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. Không phải bài viết nào cũng dùng đủ mọi bước.

Hàng huy hiệu, thứ tự mục cố định và điểm nhấn màu ấm trên dấu gạch dưới cuối của Insider_ là những lựa chọn thiết kế dựa trên hướng dẫn về yếu tố con người, chứ không phải trang trí đơn thuần. Điểm nhấn này đánh dấu mục mà không trở thành yếu tố gây nhiễu. Nó không bao giờ chuyển động, là điểm nhấn màu duy nhất dành riêng cho Insider trong nhãn điều hướng, và trong phần điều hướng, dấu gạch dưới trang trí được ẩn khỏi công nghệ hỗ trợ — từ được đọc lên ở đó là “Insider”; trong văn xuôi, dấu gạch dưới đơn giản là một phần của cái tên được viết ra. Ý nghĩa ở đây không bao giờ chỉ dựa vào màu sắc. Mỗi huy hiệu cũng có một nhãn văn bản và một từ chỉ vai trò.

Khuôn mẫu đó áp dụng cho các bài viết. Trang mở đầu này bổ sung hai mục định hướng riêng — Bắt đầu từ đâu và Bản đồ đọc — đóng vai trò điều hướng cho mục này, chứ không thuộc khuôn mẫu bài viết.

Bắt đầu từ đâu

Sáu mươi bài viết là một thư viện, chứ không phải một hàng đợi. Nếu bạn mới bắt đầu với mục này, hãy đọc một bài từ mỗi cụm, theo thứ tự sau — mỗi bước đều có thể đứng riêng, và khi ghép lại, chúng đi qua toàn bộ phạm vi đúng một lần:

Nếu bạn muốn tin tưởng mục này trước khi dành thời gian cho nó, hãy đọc Kỷ luật trích dẫn sớm — đây là tham chiếu chuẩn mực cho cách các trang gắn khẳng định với các tiêu chuẩn tương ứng. Và nếu bạn muốn biết ai đứng sau engine này, cũng có một trang riêng: Công ty đứng sau NextPDF.

Bản đồ đọc

Thư viện bài viết được tổ chức thành mười một cụm theo thứ tự đọc; bên cạnh trang mở đầu này còn có Công ty đứng sau NextPDF, một trang đứng riêng. Mỗi cụm bên dưới nêu phạm vi của cụm cùng vài bài viết tiêu biểu; thanh bên liệt kê mọi bài viết trong mọi cụm.

Gu kỹ thuật

Cách engine xác định thế nào là tốt. Hãy đọc cụm này trước; nó đặt khung cho mọi nội dung còn lại.

PHP 8.4 & kiến trúc

Nền tảng cho lập luận của một kỹ sư senior: nền tảng ngôn ngữ, kỷ luật kiểu, và pipeline được các kiểu ấy bảo vệ.

Cẩm nang thực địa về PDF

Nói về chính định dạng này, không kéo theo nghi thức rườm rà của bản đặc tả — những điểm dễ gây rắc rối, được giải thích theo cách một kỹ sư đang làm việc thực tế cần.

Tạo đầu ra cho đúng

Tính đúng đắn vượt ra ngoài các byte: màu sắc, khả năng tiếp cận, kích thước, tốc độ và tính tất định — những phẩm chất quyết định liệu một tệp PDF hợp lệ về mặt kỹ thuật có thực sự tốt hay không.

Bảo mật & quyền riêng tư

Mã hóa, che mật và làm sạch thực sự bảo vệ điều gì — và mỗi thao tác có thể che lấp những kiểu thất bại nào khi được làm cẩu thả.

Ký & sự tin cậy

Làm chữ ký số cho đúng: cấu trúc, hồ sơ, độ bền lâu dài, thời gian, xác thực và quy mô, theo đúng thứ tự phụ thuộc.

Ký đủ điều kiện & ký bằng HSM

Khóa được phần cứng hậu thuẫn và chữ ký đủ điều kiện — ranh giới thật sự của khóa nằm ở đâu, và “đủ điều kiện” đòi hỏi những gì theo eIDAS.

Phòng thí nghiệm chất lượng

Cách engine được giữ trung thực: các tầng kiểm thử, các đầu ra được ghim cố định, và những con số đáng tin.

Tiêu chuẩn & tay nghề

Kỷ luật nền tảng đứng sau engine và những trang tài liệu này: tiêu chuẩn nào ràng buộc, một điều khoản trở thành hành vi như thế nào, và một khẳng định có được trích dẫn ra sao — trong bất kỳ ngôn ngữ nào.

Lý lẽ chọn NextPDF

Một lập luận chọn dùng trung thực: bạn gánh điều gì khi tự xây, bạn đánh đổi điều gì khi chọn dùng, engine này phù hợp ở đâu — và không phù hợp ở đâu.

Trong thực tế

Các kịch bản từ đầu đến cuối kết hợp mọi thứ ở trên. Hãy đọc phần này cuối cùng; mỗi kịch bản đều giả định các nền tảng trước đó.

Ví dụ thực tế

Một trang Insider_ được thiết kế để đọc nhanh. Để quyết định liệu cách NextPDF xử lý chữ ký có phù hợp với một quy trình chịu sự điều chỉnh hay không, bạn sẽ mở Chữ ký nằm ở đâu trong tệp PDF, đọc Tổng quan nhanh và Phiên bản ngắn gọn, rồi chuyển thẳng đến Giới hạn và ranh giới. Ba mục ngắn này 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 trên trang được tiêu chuẩn hậu thuẫn ngay cả trước khi bạn đọc bất kỳ dòng 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 — Hồ sơ baseline PAdES và Xác thực 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ư cách dùng nó. Nó không bao giờ đưa ra phép so sánh kiểu bảng điểm với một đối thủ: khi một bài viết nêu tên một thư viện khác, đó chỉ là để giải thích mức độ phù hợp, rủi ro khi di chuyển hay ranh giới phân loại — không bao giờ để xếp hạng. Chủ thể ở đâ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ủ đề chịu trách nhiệm cho khẳng định đó và có trích dẫn riêng. 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 dùng để đối chiếu mục này.
Bức tranh tổng quan 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 — các khẳng định được trích dẫn ra sao 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.
Hàng huy hiệu — dải ở đầu các trang Insider_ được tiêu chuẩn hậu thuẫn, nêu tên các tiêu chuẩn mà trang dựa vào.
nextpdf-docs-native — nội dung được viết và sở hữu ngay trong chính site tài liệu, không bắt nguồn từ kho mã của bất kỳ gói nào.