You send out a hundred-page handbook. The person who opens it lands on the cover, half magnified, with no list of chapters in sight — and now somebody has to be told where to click. A PDF can say for itself how it wants to be opened: on this page, at this size, with the list of chapters already unfolded down the side. It is a wish and not an order. Desktop reading software such as Adobe Acrobat Reader follows most of it; the reading software built into a browser follows little of it, and each browser draws its own line. Open the document below in both, one after the other, and the difference takes five seconds to see.
Page three of it prints the whole list of what it asks for, so you can compare that list with what your own reading software actually did. It asks to open on the contents rather than the cover, so nobody starts on a title page they did not come for. It asks to fill the window with what is drawn rather than with the paper around it, so the words are readable without touching anything. It asks for the pages two at a time with the cover on its own, the way a book falls open. And it says what the print dialog should come up with — which pages, both sides, how many copies — so whoever prints it stops setting the same four settings every time. On a handbook, a catalogue or a price list that has to open the same way for everybody, that is the difference between a file and a document.
Nothing is left out and nothing is simplified: this is the program exactly as it runs, for the developer who uses this library. The third is the description itself: a plain list of what the page has to say, which is what the service is sent.
Read the Rust source Read the Python source Read the JSON source
The document is lighter than it was, and every page still looks exactly the same. See this document's row in the table of every example.
A plain first slide and thirteen more, each stating the effect it arrives by — the twelve the PDF standard (ISO 32000) defines — how long that effect takes and how long the slide stands before the next one comes. The file asks to open full screen, which is where the effects play, and a link on the first slide shows the screen again, brought in by dissolving.
A document made to be followed rather than looked at: every line of the contents lands on the page it names, and every page leads back to where it came from.
Links and marks hung on text the engine has already placed: a band behind a line, an underline, a boxed cell — every rectangle taken from what the layout and the table report afterwards, none of it measured by hand.
Pages numbered by their labels rather than their position.
Two stories over two pages: each one begins in a column of the front page and carries on in a column of the second, and the two swap sides on the way. The file says which column follows which, so reading software goes on with the story it is on.
Two sittings bound into one file. Each page carries a record of its own — what it is, whose hand wrote it, the day it was written — the photograph on the second page carries one too, and each transcription is tied to the page it transcribes rather than to the file at large.