A rectangle, filled or outlined

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 simplest brick: a rectangle. You give its four corners and choose to fill it with a colour, to draw its outline alone, or to do both. Filled, it makes the grey band behind a section heading or the coloured box in a table; outlined alone, it makes the frame around a photo or an area to cut out. The fill goes down first, so the outline stays visible over it.

For a developer

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

A rect is a closed path whose four points you are spared: the same painting keys as a free path, the same clips, the same graphics state, the same placement. Its corners take expressions, which gives a band hugging the margins of a page whose width is unknown when the request is written. The fill takes a declared gradient, which makes it the usual carrier of a graded background. Drawing order follows item order: a rectangle placed after a text covers 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 key: rect, an object of llx, lly, urx, ury, each a number or an expression. Optional: fill, a colour or {"shading": "name"}; stroke, an object with a required width plus color, dash, cap and join; clip, an object with a required segments and a rule (nonzero by default, even_odd); graphics_state, the name of a declared graphics state; pages, an array of one-based integers, default empty; transform, six numbers; rotate, degrees counter-clockwise about the centre of the box; layer, the name of a declared layer. Cross refusals: transform together with rotate; a clip whose segments are empty. A rectangle takes fill, stroke, or both.

A whole request that draws it

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

{
  "items": [
    {
      "type": "rect",
      "rect": {"llx": 72, "lly": 700, "urx": 523, "ury": 740},
      "fill": [0.85, 0.89, 0.95],
      "stroke": {"width": 1.0, "color": [0.11, 0.31, 0.55]}
    }
  ]
}

The line that sends it, in three languages

Glossary

gradient

A colour that changes across the space it fills, with no step anywhere between one end and the other: a header that fades out, a bar with some depth to it. It is described once, in a handful of numbers, and painted wherever it is wanted, so it stays sharp at any size and weighs almost nothing.

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.

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