Blocks laid one under the other, page after page

In plain words

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

Think of a report you write without ever deciding where a page ends. You put a title, then two paragraphs, then a table, then a picture, then a rule, in the order you want them read. You give one frame for the first sheet and one frame for the sheets after — the first is often shorter, because a letterhead sits above it. Everything then falls into place on its own: what does not fit at the bottom of a sheet carries on at the top of the next, a paragraph splits between two lines and a table between two rows, and the table's heading row is drawn again above the part that carried on. You can also say that a block must never be cut, and it moves to the next sheet whole rather than being split.

For a developer

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

Asked for with "type": "stack"

A stack item lays a list of blocks down the page in reading order and breaks the pages by itself: no block states an ordinate, each sits under whatever the block above came to, and what runs out of room carries on in the next box. It takes two boxes: first, the room on the page it starts on, and next, the room on every page after. A stack holding text is refused two boxes of two widths — its lines are broken once, to one width. Five kinds of block go in it: text, cut between pages line by line; table, cut row by row with its header rows redrawn; image, drawn at the size stated and never cut; rule, a line across the width of the box; and space, room left blank that draws nothing. A text block and a table block each take keep_together, which moves the whole block to the next page rather than cutting it.

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 keys: blocks, an array of blocks; first, an object of four coordinates llx, lly, urx, ury; next, the same object for every page after the first. A block is one of five shapes, each named by its own type. text takes content, ONE template string in which a newline ends a paragraph and a tabulation reaches the next stop, plus the setting keys of a flow written flat beside it (font, font_size, align, last_align, overlong, leading, word_spacing, break_after, color, shadow, left_indent, right_indent, first_line_indent, space_before), plus keep_together. table takes the body of a table item written flat, stating no box — the stack gives it the room it has left — plus keep_together. image takes image, the name of a supplied picture, with width and height in points. rule takes stroke alone, and stands as tall as that stroke is wide. space takes height alone. Optional keys on the stack: id, a string another item places itself against; start, where the stack begins, the first page by default; layer, the name of a declared layer. Refusals: first and next of two different widths when a text block is present.

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": "stack",
      "first": {"llx": 72, "lly": 72, "urx": 523, "ury": 700},
      "next": {"llx": 72, "lly": 72, "urx": 523, "ury": 780},
      "blocks": [
        {
          "type": "text",
          "content": "Conditions of carriage",
          "font": "sans",
          "font_size": 16,
          "keep_together": true
        },
        {"type": "space", "height": 8},
        {"type": "rule", "stroke": {"width": 0.8, "color": [0.7, 0.7, 0.75]}},
        {"type": "space", "height": 10},
        {
          "type": "text",
          "content": "Goods travel at the risk of the sender unless insured.",
          "font": "sans",
          "font_size": 10
        }
      ]
    }
  ]
}

The line that sends it, in three languages

Glossary

font

The drawing of every letter, digit and mark a document writes, held in a file of its own. A PDF carries the fonts it is set in inside itself, which is why it opens looking the same on a machine that has never had them. Leave them out and a reader puts another font in their place, and the layout moves.

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.

template

A PDF file made once and reused as the background of new pages: your letterhead, a plain sheet for the pages that follow, the page of terms you always attach at the end. The file is laid down exactly as it stands, to the millimetre, and the new text is written on top.

layer

A named group of things drawn on a page that a reader can switch on and off, like tracing paper laid over a plan. A drawing can hold its measurements on one and its notes on another, and a layer can be set to show on screen and stay off the printer.

Every word the site explains