From the outset, PDF has been intended to be cross-platform, application-neutral, and completely compatible. It does a remarkable job considering its age and complexity, but there are some features which can become confusing. My example is variously known as a Table of Contents, Outline and/or Bookmarks. You know things aren’t going to end so well when apps can’t even agree on a single term for them.

These refer to two slightly different features. Outlines or Tables of Contents are normally intended to be built into the structure of a document – chapters, sections, and so on – and can be generated automatically during creation of the PDF. They’re usually hierarchical structures, sometimes becoming quite deep. Bookmarks, though, are user-defined, reference points which you add to aid your navigation, and have flat structure. We don’t have sub-bookmarks, for instance.

A few apps support both, but implementations also vary, and some apps do their own thing regardless of the fact that no other app understands what they are doing.

I took a vanilla three-page PDF created using the Quartz 2D engine in Mojave, and tried to add an Outline or Bookmarks using each of the PDF editors I have to hand:

• Adobe Acrobat ‘Pro’ was happy to Bookmark each section or page, but didn’t offer an Outline, apart from its Content view, which might sound similar but is actually based on the structure of the PDF rather than document content.
• PDF Expert was happy for me to create an Outline and/or Bookmarks, but didn’t try to create an Outline automatically.
• PDFpenPro offered me a Table of Contents, which I had to construct manually.
• Preview offered me both a Table of Contents and Bookmarks, but only seems to support manual placement of Bookmarks and provides no visible means of constructing a Table of Contents.

In most cases, whether called a Table of Contents, Outline or Bookmarks, the marked locations are written using a PDF /Outlines scheme, to a series of objects in the PDF source. The notable exception to this is Preview, which encodes Bookmark data in an XML stream rather than using /Outlines or any simple PDF objects.

All the apps are able to read Outlines or Bookmarks which use the /Outlines scheme. However, Preview’s XML stream doesn’t work in any other app of those tested. So if you want to write a PDF document with Bookmarks which only work properly in a single app, Preview seems a good choice. Its Bookmarks appear a law unto themselves, and no other PDF reader or editor will be able to find or display them.

If, on the other hand, you want to be able to use those Bookmarks anywhere else, don’t write them in Preview.

Unless the app generating the original PDF document creates an Outline or Table of Contents automatically, whatever you add to the PDF document later will effectively be both its Bookmarks and its Outline, and should appear as either or both depending on which term your PDF reader uses.

Other aspects of PDF which are even further from standard are annotations and forms. I’ll look at those in future articles.