.PDF File Format – Document structure

The document catalog

A dictionary with /Type /Catalog, named by the trailer’s Root. Its keys in these versions:

The page tree

Pages are not kept in a list but in a balanced tree, so that a reader with a very long document can find page 5,000 without reading every page before it. The inner nodes have /Type /Pages; the leaves are page objects. A document with a handful of pages usually has one Pages node with all pages as its kids.

Page objects

A dictionary with /Type /Page, a leaf of the page tree. Its keys in these versions:

A minimal page:

2 0 obj
<< /Type /Page /Parent 3 0 R /Resources 6 0 R /Contents 4 0 R /MediaBox [0 0 15 14] >>
endobj
3 0 obj
<< /Type /Pages /MediaBox [0 0 15 14] /Count 1 /Kids [ 2 0 R ] >>
endobj

Inherited attributes

Four page keys can be set on a page tree node instead, and then apply to every page below it that does not set its own:

• Resources
• MediaBox
• CropBox
• Rotate

To find a page’s value, look in the page, then its parent, and so on up to the root. The value is taken whole: a page’s own Resources replaces its parent’s, it is not merged with it. MediaBox and Resources are required, so they must be found somewhere on the way up.

Resource dictionaries

A content stream names the fonts, images and other objects it uses by short names, such as /F1 or /Im3. The resource dictionary maps those names to objects, one subdictionary a kind:

ProcSet told PostScript printers which sets of procedures to load for a page. From PDF 1.4 Adobe called the feature obsolete, and readers ignore it. The dictionary in the small PDF 1.3 example is << /ProcSet [ /PDF ] /ColorSpace << /Cs1 7 0 R >> /ExtGState << /Gs1 8 0 R >> >>.

Name trees

A name tree maps strings to objects, sorted, in a tree that can hold any number of entries and be searched without reading all of it. The keys are strings, not names, despite the name. Each node is a dictionary:

To look up a key, start at the root and follow the kid whose Limits contain it, then search the leaf’s Names.

Number trees

The same as a name tree, but keyed by integers. Leaves have a Nums array of pairs, integer and value, sorted; Limits holds the smallest and largest integers. Page labels and the structure parent tree are number trees.

The name dictionary

From PDF 1.2 the catalog’s Names entry holds name trees for objects that are found by name rather than by reference:

The outline

The outline is the bookmarks panel: a tree of titled items, each going to a place in the document. The catalog’s Outlines points at the outline dictionary:

Each item is a dictionary in a doubly linked list of siblings:

A reader walks the list with First and Next, going down through First of each item, and should stop at loops, which damaged files have.

Destinations

A destination is a page and a view of it. Explicitly, it is an array whose first element is the page (a reference to a page object, or a page number in links to other files) and whose second is the kind of view:

A destination can also be named, so that a link survives a change of page. In PDF 1.1 the name is a name object, looked up in the catalog’s Dests dictionary. From PDF 1.2 it can be a string, looked up in the Dests name tree of the name dictionary. The value is the array, or a dictionary whose D entry is the array.

Page labels

From PDF 1.3 pages can have labels, such as i, ii, iii for the front matter and 1, 2, 3 for the rest. The catalog’s PageLabels is a number tree keyed by page index, counting from 0. Each entry starts a range of pages that runs to the next entry:

<< /Nums [0 << /S /r >> 4 << /S /D >>] >> labels pages i to iv, then 1, 2, 3 from the fifth page.

Article threads

From PDF 1.1 a thread joins parts of a page and later pages into one article that a reader can follow, as in a newspaper. The catalog’s Threads array lists thread dictionaries; each has F, its first bead, and I, a dictionary of information like the document’s. A bead is a dictionary:

Each page lists its own beads in B.

Viewer preferences

From PDF 1.2 the catalog’s ViewerPreferences asks a viewer to show the document a certain way:

Logical structure

From PDF 1.3 a document can carry its structure, separate from its layout: the headings, paragraphs, lists, tables and figures, in reading order. The catalog’s StructTreeRoot starts a tree of structure elements:

The content belongs to an element through marked content: /P << /MCID 3 >> BDC … EMC in the content stream, and 3 as a kid of the element. PDF 1.4 added Tagged PDF, a set of standard element types and rules that let text be reflowed and read aloud, and the catalog’s MarkInfo with /Marked true to say a document follows them.