Landing places that have a name

Register a place in the document under a name, so a link leads there without ever quoting a page number.

Summary

Saying « see page 12 » has a flaw: the day a page is added at the front, everything shifts and the reference is wrong. A label stuck at the place you mean moves with it, and every reference to it stays right. You also decide what fills the screen on arrival: the whole page, its width, or a precise frame.

Technically

Written at the top level of a request, under "destinations"

destinations registers landing places in the /Dests name tree, each under a name holding how much of the window is filled and either a page or an element of the structure tree. An action leading to a name states none of that, so the landing place follows the document rather than the page number it happened to sit at. A place standing for an element is written as a structure destination, /SD, with the page that element begins on beside it in /D for reading software that knows nothing of the structure; it is what the second part of the accessibility standard asks a way into a document to be. A link item leads there through action, in the form {"destination": "the name"}.

Request schema

  • destinations — array, optional, empty by default.
  • destinations[].name — string, required. The name the place is registered under. A name registered twice is refused.
  • destinations[].page — integer ≥ 1. The page the name stands for. A page the document does not have is refused, and so is a place naming a page and an element at once, or neither of the two.
  • destinations[].element — string. The identifier of the element of the structure tree the name stands for, spelled as that element's id spells it. The place is then the page that element begins on, so it follows the element rather than the page it landed on. A document carrying one is written as PDF 2.0, and an identifier no element of the tree carries is refused.
  • destinations[].fit — optional, whole_page by default. Eight shapes: "whole_page"; {"full_width": {"top": n}}; {"full_height": {"left": n}}; {"rectangle": {"llx": n, "lly": n, "urx": n, "ury": n}}; "whole_drawing"; {"drawing_width": {"top": n}}; {"drawing_height": {"left": n}}; {"fixed": {"left": n, "top": n, "zoom": n}} — each of those last three keys being optional on its own.

A whole request that creates a PDF

{
  "destinations": [{ "name": "annex", "page": 2 }],
  "standard_fonts": [{ "name": "sans", "face": "helvetica" }],
  "items": [
    {
      "type": "text",
      "pages": [1],
      "rect": { "llx": 60, "lly": 740, "urx": 535, "ury": 758 },
      "content": ["See the annex"],
      "font": "sans",
      "font_size": 12
    },
    {
      "type": "link",
      "pages": [1],
      "rect": { "llx": 60, "lly": 738, "urx": 160, "ury": 760 },
      "action": { "destination": "annex" }
    },
    {
      "type": "text",
      "pages": [2],
      "rect": { "llx": 60, "lly": 740, "urx": 535, "ury": 768 },
      "content": ["The annex"],
      "font": "sans",
      "font_size": 18
    }
  ]
}

The line that sends it, in three languages

Finding one's way through it

The order one field leads to the next What a page sets off as reading software comes and goes What the document says it is made of The clickable contents down the side Following an article column by column How the document opens and prints

Where to go next

Every JSON key of a request, in one page The other forty-one settings of a request

See the prices See the examples