Fast web view
A browser opens a PDF from a server a piece at a time: it asks for the bytes it needs, by range, and shows a page as soon as it has them. That works when the file is linearized (ISO 32000-1, Annex F): page 1 and everything it draws come first, with hints that say where every other page is. In any other PDF the table that says where things are is at the end, so a viewer reads the end of the file before it can show a page. Lpdf writes a linearized file, which readers call fast web view, when the document asks for it in its output.
<document> <meta title="Spring catalogue"/> <output linearize="true"/> <section> <layout margin="48pt"> <text font-size="24pt">Spring catalogue</text> <text>Page 1 shows while the rest of the file is still on its way.</text> </layout> </section></document>L.document({ meta: { title: 'Spring catalogue' }, output: { linearize: true } }, [ L.section(NoAttr, [ L.layout({ margin: '48pt' }, [ L.text({ fontSize: '24pt' }, ['Spring catalogue']), L.text(NoAttr, ['Page 1 shows while the rest of the file is still on its way.']), ]), ]),])L.document(DocumentAttr(meta=DocumentMeta(title='Spring catalogue'), output=DocumentOutput(linearize=True)), [ L.section(NoAttr, [ L.layout(LayoutAttr(margin='48pt'), [ L.text(TextAttr(font_size='24pt'), ['Spring catalogue']), L.text(NoAttr, ['Page 1 shows while the rest of the file is still on its way.']) ]) ])])L.document(new DocumentAttr().meta(new DocumentMeta().title("Spring catalogue")).output(new DocumentOutput().linearize(true)), List.of( L.section(NoAttr, List.of( L.layout(new LayoutAttr().margin("48pt"), List.of( L.text(new TextAttr().fontSize("24pt"), List.of("Spring catalogue")), L.text(NoAttr, List.of("Page 1 shows while the rest of the file is still on its way.")) )) ))))L.Document(new() { Meta = new() { Title = "Spring catalogue" }, Output = new() { Linearize = true } }, [ L.Section(NoAttr, [ L.Layout(new() { Margin = "48pt" }, [ L.Text(new() { FontSize = "24pt" }, ["Spring catalogue"]), L.Text(NoAttr, ["Page 1 shows while the rest of the file is still on its way."]), ]), ]),])L::document(new DocumentAttr(meta: new DocumentMeta(title: 'Spring catalogue'), output: new DocumentOutput(linearize: true)), [ L::section(NoAttr, [ L::layout(new LayoutAttr(margin: '48pt'), [ L::text(new TextAttr(fontSize: '24pt'), ['Spring catalogue']), L::text(NoAttr, ['Page 1 shows while the rest of the file is still on its way.']), ]), ]),])The linearize attribute
Section titled “The linearize attribute”It is an attribute of output, the element of document that says how the file is written.
| Attribute | Type | Default | Description |
|---|---|---|---|
linearize |
boolean | false |
Writes the PDF linearized, for fast web view. It changes nothing a viewer shows |
It combines with every other attribute of output: a file can be encrypted, PDF/A, PDF/UA or PDF/X, and linearized too. What combines with what has the whole table.
A document built in code asks for it in its output, as a boolean: output: { linearize: true } in JavaScript, and DocumentOutput in the other SDKs, with linearize=True in Python, new DocumentOutput().linearize(true) in Java, Linearize = true in C# and linearize: true in PHP.
What changes in the file
Section titled “What changes in the file”- Page 1 comes first, with every font, image and object it draws, after a short dictionary that says the file is linearized and how long it is. A viewer that has those bytes shows page 1.
- A hint stream says where each other page starts, how long it is, and which objects it shares with other pages, so a viewer can fetch any page on its own.
- The other pages follow in page order, each with the objects only it draws, then the objects later pages share, then the rest of the document, such as its bookmarks.
- Each page names only the fonts and images it draws. A file that isn’t linearized names all of them on every page, which costs nothing there, but would put every image of the document before page 1.
Linearizing doesn’t shrink a file or change what it shows. It pays off for large documents read in a browser, such as statements, catalogues, reports and books. A one-page invoice gains nothing from it.
With encryption
Section titled “With encryption”With encrypt as well, the file is encrypted first and linearized last, so the hints point at the encrypted objects. The passwords come with the render call, as for any encrypted document.
<document> <output encrypt="aes-256" allow="print" linearize="true"/> <section> <layout margin="48pt"> <text>Statement for October</text> </layout> </section></document>L.document({ output: { encrypt: 'aes-256', allow: 'print', linearize: true } }, [ L.section(NoAttr, [ L.layout({ margin: '48pt' }, [ L.text(NoAttr, ['Statement for October']), ]), ]),])L.document(DocumentAttr(output=DocumentOutput(encrypt='aes-256', allow='print', linearize=True)), [ L.section(NoAttr, [ L.layout(LayoutAttr(margin='48pt'), [ L.text(NoAttr, ['Statement for October']) ]) ])])L.document(new DocumentAttr().output(new DocumentOutput().encrypt("aes-256").allow("print").linearize(true)), List.of( L.section(NoAttr, List.of( L.layout(new LayoutAttr().margin("48pt"), List.of( L.text(NoAttr, List.of("Statement for October")) )) ))))L.Document(new() { Output = new() { Encrypt = "aes-256", Allow = "print", Linearize = true } }, [ L.Section(NoAttr, [ L.Layout(new() { Margin = "48pt" }, [ L.Text(NoAttr, ["Statement for October"]), ]), ]),])L::document(new DocumentAttr(output: new DocumentOutput(encrypt: 'aes-256', allow: 'print', linearize: true)), [ L::section(NoAttr, [ L::layout(new LayoutAttr(margin: '48pt'), [ L::text(NoAttr, ['Statement for October']), ]), ]),])Serving the file
Section titled “Serving the file”A viewer fetches a PDF by range only when the server answers range requests. A static file server, object storage such as Amazon S3, and a CDN do. To check a server, fetch the first kilobyte of the file, and print the status of the answer:
curl -s -o /dev/null -w '%{http_code}\n' -r 0-1023 https://example.com/catalogue.pdf206 means the server sent only the bytes asked for. With 200 it sends the whole file every time, and a viewer shows page 1 only once it has all of it, as for any PDF. Ask with a GET, as this does: some servers that answer ranges answer a HEAD request with 200.
After the render
Section titled “After the render”Any change to the file after the render ends its linearization: a stamp, a signature, or pages merged in by another tool. The file still opens, but a viewer loads it whole before it shows a page. Make the change in the document and render it again, or linearize the changed file again with a tool such as qpdf --linearize.