What the document says it is made of

In plain words

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

Ink on a page has no order of its own. A person sees that the big words at the top are a heading and that the two columns are read one after the other, but a program sees only marks placed at coordinates, in whatever order they were drawn. This is where you tell it: this is the heading, these are the paragraphs, this is a figure, and this is the order they are read in. Once that is written, a document can be read aloud correctly, copied without scrambling, and reflowed on a small screen. You can also say a passage is in another language, so it is pronounced properly, and give a picture a sentence describing it for somebody who cannot see it.

For a developer

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

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

structure is what the document says it is made of, in reading order: the elements that hold the marked runs the items left behind. An item opens a marked run with tag and mark; the tree then claims that run by its label, which is what ties the ink to the meaning. Absent, the file says nothing about itself and a reader reads it in the order the ink went down. lang is the tongue the words are written in, as a BCP 47 tag, and a node states its own where a passage is in another. roles lets the request use tags of its own, each said to be read as one the standard names. A node either holds children, or claims a marked run through content, or reaches a branch built elsewhere.

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.

structure — object, optional. Absent, the file says nothing about itself.
structure.lang — string, optional, a BCP 47 tag. The tongue the document's words are written in.
structure.roles — array, optional. Tags of the request's own, each an object of tag and standard, the standard tag it is read as.
structure.children — array, optional. The elements at the head of the tree, in reading order.
A node takes tag, required, the standard's name for what it is (Document, Sect, H1, P, Figure); and then children, other nodes; or content, the label of a marked run an item left behind; or branch, the name of a branch built elsewhere.
A node also takes namespace, lang for a passage in another tongue, alt, a sentence describing what cannot be seen, and actual_text, what a passage really says when its ink does not spell it.

Scope: the whole document. It is what accessible is judged against; on its own it costs nothing and is simply read by whoever wants the order and the meaning rather than the coordinates.

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" }],
  "structure": {
    "lang": "en-GB",
    "children": [
      {
        "tag": "Document",
        "children": [
          { "tag": "H1", "content": "heading" },
          { "tag": "P", "content": "opening" }
        ]
      }
    ]
  },
  "items": [
    {
      "type": "text",
      "rect": { "llx": 72, "lly": 720, "urx": 523, "ury": 760 },
      "content": ["What this document is"],
      "font": "sans",
      "font_size": 20,
      "tag": "H1",
      "mark": "heading"
    },
    {
      "type": "text",
      "rect": { "llx": 72, "lly": 660, "urx": 523, "ury": 710 },
      "content": ["It is read in the order the tree gives, not the order of the ink."],
      "font": "sans",
      "font_size": 11,
      "tag": "P",
      "mark": "opening"
    }
  ]
}

The line that sends it, in three languages

Finding one's way through it

The order one field leads to the next The clickable contents down the side Landing places that carry a name Following an article column by column How the document opens and prints

Where to go next

Every key of a request, in one page The other thirty-two settings of a request

See the prices See the examples

Glossary

standard: A rule argued out in committee, published under a number anybody may buy and read, and identical for every firm claiming it. A claim to follow one can therefore be checked against the text. A way of working that merely spread because it worked is a habit of the trade: useful, widespread, and answerable to no text at all.
CMYK: The four inks a printing press lays down: cyan, magenta, yellow and black. A screen mixes light instead, so a document going to a press states its colours in inks, not in screen colours.
tagged PDF: A PDF that carries the structure of its own text alongside the drawing: this is a heading, this is a table, this cell belongs to that column. It is what lets a reading aid, or a program pulling data back out, make sense of the page.
reading order: The order a document is meant to be read in, which is not always the order it was drawn in. On a page in two columns the ink may go down one column and then the other, or jump between them; software reading the page aloud follows the stated order rather than guessing.
request: One call to the service: you send what the document should say, and get the document back. Your bill counts these calls, one for each document. The number of pages inside a document is never counted.

Every word the site explains