Citation discipline

SpecSpec: ISO/IEC/IEEE 26514ISO/IEC/IEEE 26514SpecSpec: ISO 24495-1ISO 24495-1

At a glance

This is the page the rest of Insider_ points at when it explains how it cites a standard. It explains why these docs paraphrase specifications instead of quoting them, how a claim names the standard and the exact clause it rests on, and what a clean citation does and does not promise.

It is written for a senior engineer who, before trusting a claim, wants to know the rules used to make it — and is right to want that.

Why this matters

Every other Insider_ page makes claims and ties them to a named standard and clause. That citation is only worth something if the discipline behind it is explicit. If “standard-backed” could mean anything from “I read the spec carefully” to “I remember roughly what it said”, the citation is decoration.

There is also a harder constraint. Many of the documents NextPDF answers to — the ISO, ETSI, and similar specifications — are licensed. Reproducing their text, at any length, is not permitted. The discipline therefore has to solve two problems at once: make a claim traceable to its source, without reproducing that source. A precise citation plus a faithful paraphrase answers both, and this page is its specification.

The short version

• Insider_ paraphrases standards and never quotes licensed ones. A claim names the standard and the exact clause; it does not reproduce the standard’s words.
• Paraphrase is not a workaround; it is a comprehension test. Restating a requirement in NextPDF’s own voice forces the writer to understand it, and keeps terminology consistent with the glossary SpecSpec: ISO/IEC/IEEE 26514, §8ISO/IEC/IEEE 26514 §8.
• Every standard-backed claim names a specific clause or section, not a whole document, so the next reviewer can open that clause and confirm the paraphrase against it.
• A citation states the kind of source it rests on — a clause, the engine’s code, a test, a measurement — so an over-claim is visible at a glance.
• When a claim cannot be tied to a clause the writer has actually read, it is not faked. It is kept, marked unresolved, and the page stays unpublished — a documented protocol, not an improvisation.

How NextPDF approaches it

Paraphrase, not quotation

The strictest rule in the NextPDF style hierarchy overrides every upstream guide: no verbatim text from a licensed standards body, regardless of how short the excerpt is. Instead, a page names the standard and clause and paraphrases the requirement in its own voice.

This is usually framed as a licensing constraint, and it is one. The more useful framing is editorial. A verbatim quote proves only that you can copy. A faithful paraphrase shows that you understood the clause well enough to restate it without changing its meaning. It also lets the sentence stay in NextPDF’s consistent vocabulary rather than switching register mid-page, which the documentation-quality model requires SpecSpec: ISO/IEC/IEEE 26514, §8ISO/IEC/IEEE 26514 §8. Plain language is judged by whether a reader can find, understand, and use the content, not by whether the prose mirrors the source SpecSpec: ISO 24495-1, §IntroductionISO 24495-1 §Introduction; paraphrase serves that, quotation does not.

A claim names the clause, not just the document

The mechanism that makes a paraphrase checkable is precision. Every standard-backed claim names the exact clause or section it rests on — for example, ISO 32000-2 §6 — not just the document. A reviewer does not have to trust the writer’s memory; they open that clause and compare it against the restatement. The clause reference is the join between an unquotable source and a verifiable claim. It carries where to look without carrying the source’s text.

A citation says what kind of source this is

A citation answers “where from”. It also has to answer “what kind”. Saying a claim is backed by a clause of a standard is a different promise from saying it is backed by the engine’s own code, by a test, or by a measurement. NextPDF keeps those kinds distinct so a reader can weigh them: code and tests rank above runtime behaviour, runtime above metadata, and metadata above prose. A page like this one is editorial: it reasons from those ranked sources.

Kind of source	What it promises	What it does not promise
Code-backed	The claim is checked against the engine’s source or a runnable example	That a standard mandates it
Standard-backed	The claim is anchored to a cited, paraphrased clause	That the code currently implements it without exception
Test-backed	A test in the suite holds the behaviour in place	A performance figure
Benchmark-backed	A measurement under a stated method supports the figure	The same figure on your hardware
Artifact-backed	A produced artefact (a build output, a report) demonstrates it	A standards mandate
Design principle	A deliberate, argued design decision	An empirical measurement
Editorial	A reasoned explanation that organises other material	A new behavioural guarantee of its own
Mixed	The page blends bases and says which, per claim	A single clean basis

This page is editorial. It explains the discipline the other pages’ citations rely on.

When the source cannot be read

Access to a standard is not always immediate — a licensed spec may be one a writer has yet to obtain, or a clause may need a second read before its meaning is clear. The discipline’s integrity shows in what happens then. The writer does not guess. A claim that cannot yet be tied to a clause the writer has actually read is kept, attached to in-repo material and the standards reference the code itself declares, explicitly marked unresolved, and the page stays unpublished until the clause is properly cited.

The forbidden moves are enumerated and checkable: a clause number invented to look precise, a citation dressed up as if it were read when it was written from memory, or silently deleting the claim to dodge the citation. A correctly-marked open citation on a draft is debt with a note, not a defect. An offline, deterministic check enforces exactly that distinction.

Human-factors note:Human-factors note

Putting the standard and clause at the top of every page, before a word of body text, is a human-factors decision, not a stylistic one. It lets a reader judge the kind of source by recognition rather than by reading to the end and inferring it — the same reason the section structure is fixed and the Related-docs links are written so their destination is clear from the link text alone. A citation is only trustworthy if the standard it rests on is the first thing you see, not the last thing you reconstruct.

Practical example

The discipline is concrete: it is the structure of a page’s citations front-matter. Each entry ties a claim to its clause.

excerpt: an Insider_ page's citations front-matter

citations:
  - spec: "ISO 32000-2"
    clause: "§6"
    # NextPDF-worded topic — the paraphrase, never the standard's text
    topic: "A writer's created or amended PDF elements must conform and stay consistent"

There is no quote field, by design. The topic is NextPDF’s own restatement. The spec and clause are how a reviewer gets back to the exact source to check that restatement. The entry carries the pointer to the clause, not the clause’s words.

Common misconception

The trap is reading “paraphrase, don’t quote” as a hedge — a way to sound authoritative without committing. It is the reverse. A quotation commits nothing; it borrows someone else’s words. A cited paraphrase commits the writer to a restatement that a reviewer can falsify against the clause. The discipline makes claims more accountable, not less.

The second trap is treating “editorial” as a weaker grade of “standard-backed”. It is not a grade at all; it is a different kind. An editorial page like this one organises and explains other material. It is correctly labelled. And the label is the point: the system works because a page tells you what kind of source it rests on before you decide how much weight to give it.

Limits and boundaries

This page specifies the citation discipline; it is not the style sheet or the gate code. The authoritative artefacts are in-repo (docs/style/nextpdf-overrides.md §5 and the composer.jsondocs:* scripts) and take precedence over any summary here if they diverge.

The discipline binds the claim, not the reader’s conclusion. A faithfully cited paraphrase tells you what a clause requires. Behavioural pages also carry code- or test-backed citations, not standard-backed alone. An offline, deterministic check enforces the discipline.

Related docs

• Documentation as a product — the wider quality discipline this citation system is part of.
• The standards landscape — the standards these citations point at, and how a clause becomes documented behaviour.
• The NextPDF testing pyramid — what test-backed evidence means when a page rests on that basis instead of this one.

Glossary

• Citation discipline — the rule set governing how an Insider_ claim is tied to its source: paraphrase, name the exact clause, never quote a licensed standard.
• Paraphrase — a restatement of a requirement in NextPDF’s own, glossary-consistent voice; the comprehension test that replaces quotation.
• Clause reference — the exact clause or section a paraphrase rests on, recorded so a reviewer can open it and verify the restatement.
• Standard-backed claim — a claim anchored to a cited, paraphrased clause of a named standard, as distinct from one backed by the engine’s code, a test, a measurement, or editorial reasoning.
• Unresolved citation — a claim that cannot yet be tied to a clause the writer has read; kept, marked open, and held back from publication rather than faked.