Text in paragraphs, with indents and tab stops

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 piece for real running text: several paragraphs one under another, as in a letter or a contract. You decide the first line's indent, the space left between two paragraphs, and how the lines settle: against the left edge, in the middle, or stretched out to both edges. You can also ask for a bulleted list, where the bullet stands alone on the left and the text lines up neatly beneath it. And if you want a row of little dots running from a heading across to a price, the way a table of contents does, you simply ask for it.

For a developer

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

A flow item takes its text as a single string: a newline ends a paragraph, a tabulation advances to the next tab stop. The whole block is set in one font at one size, which leaves the room for paragraph settings: left, right and first-line indents, space before and after, the position of the first baseline, the alignment of a paragraph's last line, and a leader character. Tab stops are set in relative steps, typewriter style, or from an explicit ruler, each stop aligned left, centre, right or on a decimal character. The hanging list is a shorthand that sets the left indent, the first-line indent and the body stop in one go.

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: rect; content, a single string; font; font_size. Optional: align (default left, then right, center, justify); last_align, the alignment of each paragraph's last line (absent: as the rest, except under justify, where it settles flush left); overlong (overflow by default, break); leading (default 1.2 × font_size); break_after; color (default black); shadow (dx, dy, color, all three required); left_indent, right_indent, first_line_indent, numbers of points, the last one accepting a negative value that hangs the first line out to the left of the others; space_before, space_after; first_baseline, one of "leading" (default), "ascender", "cap_height" or {"points": n}; leader, one character; tabs, an object of method (relative by default, typewriter, ruler), size ({"fraction": n} or {"points": n}, default 7.5 % of the line), ruler (array of numbers, default empty), alignments (array of left, center, right, decimal, default empty) and align_char (default .); hanging_list, an object of marker and body, both numbers, both required; pages (default empty); id; relative_to; transform; rotate; layer. Cross refusals: hanging_list with left_indent, first_line_indent, tabs.method or tabs.ruler; transform with rotate.

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": "serif", "face": "times_roman"}],
  "items": [
    {
      "type": "flow",
      "rect": {"llx": 72, "lly": 640, "urx": 523, "ury": 780},
      "content": "First paragraph, set in one font.\nSecond paragraph, indented.",
      "font": "serif",
      "font_size": 11,
      "first_line_indent": 14,
      "space_after": 6
    }
  ]
}

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.

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.

baseline

The invisible line letters sit on, the one ruled across a page of exercise paper. Where a line of text lands is said by where its baseline lands, and the gap between two of them is what makes text look airy or cramped.

Every word the site explains