A patch of page a reader clicks

In plain words

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

This is the patch you click in a document shown on screen. It is invisible: it lies over whatever is already drawn, usually over a piece of text you coloured blue so people can see it is clickable. You choose what the click does: open a web address, or jump to another page of the same document, the way a table of contents does. On paper the sheet stays as it is; on screen, the patch turns your document into something you browse.

For a developer

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

A link is an annotation rectangle laid over the items already drawn: it makes do with the pages those items created, so a link named beyond the last page simply stays aside. Its target is written in two ways: the short form, which gives an address or a page number, or the full action, which further gives the view a page opens at, a named destination, a document part, a reading move, or the sending and the resetting of a form. Each link states one or the other, which keeps a single possible reading.

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.

Required key: rect. Exactly one target key: to, either {"uri": "address"} or {"page": n} with n ≥ 1; or action, one of {"uri": …} (a string, or an object with a required uri and track_pointer, default false), {"page": …} (an integer ≥ 1, or an object with a required page and a fit, default "whole_page"), {"destination": "name"}, {"part": n} with n ≥ 1, {"menu_item": …} being next_page, previous_page, first_page or last_page, {"reset_fields": {"fields": …}}, {"submit_fields": {…}} with a required url, an optional fields and a format (default {"fdf": {"with_no_value": false}}, also {"html": {"get": …, "with_click": …}}, "xfdf" and {"whole_document": {"get": …}}), or {"import_fields": {"file": "name"}}. A field set is written {"only": …} or {"all_but": …}; absent, it means the whole form. Optional: pages, an array of one-based integers, default empty. Cross refusals: to together with action; neither of the two; a page outside the document.

A whole request that draws it

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

{
  "standard_fonts": [{"name": "sans", "face": "helvetica"}],
  "items": [
    {
      "type": "text",
      "rect": {"llx": 72, "lly": 740, "urx": 300, "ury": 760},
      "content": ["Visit hqf-pdf.com"],
      "font": "sans",
      "font_size": 14,
      "color": [0.11, 0.31, 0.55]
    },
    {
      "type": "link",
      "rect": {"llx": 72, "lly": 740, "urx": 300, "ury": 760},
      "to": {"uri": "https://hqf-pdf.com/"}
    }
  ]
}

The line that sends it, in three languages

Glossary

annotation

Something laid over a page rather than drawn into it: a clickable rectangle, a box to type in, a button. It sits at its own place on the sheet and is what makes a PDF answer to a click at all.

Every word the site explains