Inside NextPDF

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

At a glance

Insider_ is the part of the documentation that explains why NextPDF behaves the way it does. The reference tells you what a method returns. Insider_ tells you why it returns that value, and which standard or test holds the reasoning in place.

It is written for a senior engineer who is already comfortable with PDF and PHP codebases. That reader would rather read one honest page than ten reassuring ones.

Why this matters

PDF is an old, strict format with firm conventions: it does not tolerate guesses. A library that hides that from you is pleasant until a signed document fails validation in production and nobody can say why.

Insider_ takes the opposite stance. Every page states the boundary of what it claims, names the evidence behind the claim, and points at the limits before you find them yourself. The goal is not to impress you. It is to help you make a decision you can defend in a review.

The short version

Insider_ pages are editorial and explanatory, not API reference.
Every page carries a badge row that names the relevant standards and the kind of evidence the page rests on.
Every page follows the same ten-section shape, so you can skim to the section you need without re-learning the layout each time.
Nothing here restates a metric inline; numbers live with the page that owns the measurement, so a figure cannot quietly go stale in prose.

How NextPDF approaches it

Each Insider_ page covers a single topic, stands on its own, and puts the most useful statement near the top. That structure is deliberate. It follows information-design guidance: readers find what they need faster when related material is grouped and the hierarchy is visible. It also keeps the page usable with a screen reader, because the order on screen is the order in the markup.

A page moves from context to claim to limit, in this order:

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.

How an Insider_ page is structured, top to bottom: a reader can stop at any step and still have a complete, defensible answer.

What the evidence says

Insider_ does not ask you to trust it. Each page declares an evidence level, and the badge row shows it:

Evidence: Code-backed — the claim is checked against the engine’s own source or a runnable example.
Evidence: Standard-backed — the claim is anchored to a clause in a published standard, paraphrased and cited, never quoted from a licensed document.
Evidence: Test-backed — the claim is held in place by a test in the suite.
Evidence: Design principle — the page states a deliberate design decision, argued rather than measured.

When a page blends these, it says so with Evidence: Mixed evidence rather than overclaiming a single basis. The standards a page relies on are named in the badge row using their exact identifiers — for example Spec: ISO 32000-2, §7 for PDF syntax, or Spec: ETSI EN 319 142-1 for PAdES — so you can take the reference to the source yourself.

Practical example

Reading an Insider_ page is meant to be quick. To decide whether NextPDF’s signature handling fits a regulated workflow, you would open How signatures sit in a PDF, read At a glance and The short version, then jump straight to Limits and boundaries. Three short sections answer “can I defend this choice”. The badge row has already told you the claim is standard-backed before you read a word of body text.

If the answer is yes, Related docs routes you onward — PAdES baseline profiles and Long-term validation — without a search.

Common misconception

Insider_ is sometimes mistaken for marketing: a place where the engine is praised. It is the opposite by design. A page is as willing to tell you when not to use NextPDF as how to use it. It never compares NextPDF unfavourably — or favourably — to a competitor. The only subject here is NextPDF and the standards it answers to.

Limits and boundaries

This page is orientation, not a specification. It asserts no engine behaviour of its own. Every behavioural claim lives on the topic page that owns it and carries that page’s evidence level. Insider_ content is editorial and nextpdf-docs-native. It is written here, reviewed here, and is not aggregated from any package’s source tree. Where a topic touches a licensed standard, the page paraphrases and cites the clause. It never reproduces the standard’s text.

The NextPDF design philosophy — the principles every page is measured against.
The standards landscape — the map of standards NextPDF tracks and how a clause becomes behaviour.
Documentation as a product — the discipline behind these pages.
Citation discipline — what an evidence level means and why standards are paraphrased.

Glossary

Insider_ — the editorial section explaining the reasoning behind NextPDF, distinct from the API reference. The trailing underscore is part of the section name; it is accented for emphasis only.
Evidence level — the declared basis for a page’s claims (code-backed, standard-backed, test-backed, benchmark-backed, artifact-backed, design-principle, editorial, or mixed).
Badge row — the strip at the top of every Insider_ page naming the relevant standards and the page’s evidence level.
nextpdf-docs-native — content authored and owned in the documentation site itself, not derived from a package repository.