Landing places that carry a name

In plain words

Written for anybody. It says what this puts on a sheet of paper, and asks nothing of you beyond that.

Saying "see page 12" has a flaw: the day a page is added at the front, everything shifts and the reference is wrong. There is a better way: you stick a label at the place you mean, give it a name, and references point at that name. If the document moves, the label moves with it and the references stay right. You also decide what fills the screen on arrival: the whole page, its width, or a precise frame.

For a developer

Written for somebody who writes the calling program: the model, the units, and the settings that carry the weight.

destinations registers landing places under a name: each holds a page and how much of it fills the window. An action leading to a name states neither of those, so the landing place follows the document rather than the page number it happened to sit at. A link item leads there through action, in the form {"destination": "the name"}.

Every key, with its default

The reference: which keys are required, which are optional, what each one defaults to and which combinations the server declines.

• 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, required. The page the name stands for. A page the document does not have is refused.
• destinations[].fit — optional, whole_page by default. Eight shapes: "whole_page"; {"full_width": {"top": n}}; {"full_height": {"left": n}}; {"rectangle": {"x": n, "y": n, "width": n, "height": 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 draws it

Post this as it stands and a PDF comes back. Nothing has been left out of it.

{
  "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