Linearized PDF for fast web view

Where this API stands

This is not something a renderer emits. It is applied to a finished file by a step that comes after rendering, so the honest answer is about where the boundary falls. This API has no linearisation option, and linearisation is not a property a renderer naturally produces: it is a rearrangement of the finished file, so it is a post-processing step by nature rather than by omission. One thing to be aware of if you do add it: applying this API's password protection writes an incremental update onto the end of the file, and anything appended after linearisation breaks it, because the point of the layout is that page one comes first and an update does not.

What the standard requires

The requirements as a checker enforces them, rather than as a procurement document paraphrases them. A file satisfies all of these or it satisfies none of them.

• A /Linearized parameter dictionary as the very first object in the file, giving the length of the first page section and the offset of the main cross-reference table.
• Every object needed to draw page one comes before everything else in the file.
• Hint streams describing where the remaining pages and shared objects live, so a reader can request exactly the byte range it needs.
• A first-page cross-reference table at the front and the main one at the back, which is why a linearized file has two.
• The layout only pays off over a transport that supports byte range requests, which in practice means HTTP with range support and a server that honours it.

Who asks for this

Anyone serving large PDFs to a browser viewer, where the difference is a first page in a second against a spinner until the whole file lands. Below a few megabytes nobody notices. Above fifty pages of images it is the difference between a usable document and an abandoned one.

What it looks like in a file

The concrete form of the thing being described, so you can recognise it in a document you have been handed rather than only in a specification.

# Last step, after signing, encryption, metadata and merging.
qpdf --linearize report.pdf report-web.pdf

# Confirm, and check the hint data is intact rather than just present.
qpdf --check report-web.pdf | grep -i linear

What to do about it

`qpdf --linearize in.pdf out.pdf` does it, it is fast, and it is the last step in the pipeline. Order matters: linearize after any signing, encryption, metadata or merging step, because all of those either append to the file or rewrite it. If you are storing documents and serving them later, linearize once at store time rather than on every request.

How to check a file rather than assume

`qpdf --check file.pdf` reports whether the file is linearized and whether the linearisation data is intact, which is more useful than the boolean alone because a broken hint table is worse than none. Acrobat shows it as "Fast Web View: Yes" in document properties.

The mistake people make here

Linearizing and then doing anything else to the file. Signing, encrypting and adding metadata all commonly write an incremental update, which leaves the /Linearized dictionary present and wrong. Readers cope, so nothing visibly breaks, and the benefit you paid for is gone while the properties panel still says yes.

Frequently asked

Standards this one is confused with

The neighbours that matter are the ones people mistake for this, not the ones that sort next to it.