Text in Paragraphs, with Indents and Tab Stops
Lay several paragraphs in a frame, with a first-line indent, space between them, bulleted lists and neat columns of figures.
See It in a Real PDF
Lists Made from an Indent and a Tab Stop
Bulleted, numbered and nested lists, each built out of an indent that hangs out to the left and one tab stop rather than out of a dedicated list object: the marker sits in the room the indent opens, and every line below the first begins where the tabulation put the text.
Open the PDF The Whole Example
Also shown in: A Page Whose Letters Cost One Byte Each · Text Poured into Columns · Paragraph Indents and Spacing
Summary
A letter, a contract, a set of terms: text that runs on, and settles by itself as it goes. The lines can hold to the left edge, sit in the middle, or stretch out to both edges at once. A bullet stands alone in the margin while its text lines up neatly beneath it. And a row of little dots can run from a heading across to a price, the way a table of contents does.
Technically
Asked for with
"type": "flow"
A flow item takes its text as a single string: a newline ends a paragraph, a tabulation advances to the next tab stop, and the result goes into the page content stream as positioned text. The whole block is set in one font at one size, which leaves the room for paragraph settings, all measured in points: left, right and first-line indents, space before and after, the position of the first baseline and the room kept below the last one, 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.
Request Schema
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); justified_tightening, read under justify only, an object of word_gap (default 0.8, the narrowest a gap between two words is set, as a share of the blank), letter_spacing (default -0.02, the most each glyph closes up on the next, in ems of the text's size) and scaling (default 97, the narrowest the line is drawn, as a percentage of its width), the line closing up in that order to keep a word it would otherwise send to the next line, and keeping it only if the three at their limits make it fit, any other key refused; justified_short_line, read under justify only, the share of the width, from 0 to 1, a line must fill to be stretched across it, a shorter one being set flush left (default 0); overlong (overflow by default, break); leading (default 1.2 × font_size); break_after; break_at_punctuation; replacing, an object whose keys are single characters, each mapped to {"each": "…"}, put in place of every occurrence, or to {"run": "…"}, put once in place of every run of it, before the lines are broken, an empty string taking the character out; color (default black); outline, an object of width, a required number of points, color (default black) and filled (default false), the letters stroked round their edges and hollow unless filled draws them solid as well; 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}; last_baseline, one of "none" (default), "descender" or {"points": n}, the room the block keeps below its last baseline, which is what a leading filling a box is measured against, so that two blocks of unequal length end on one line of ink rather than on one line of baselines; 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; fill_leading, an object with one required limit, a number of points, the leading the lines take so that the last of them ends on the floor of the rectangle — the lines are moved apart and nothing else, the room kept around a paragraph, the drop under the last baseline and the height of the text itself standing where they are, and a limit below the leading the block would take leaves that leading where it is; fit_size, an object with one required floor, a number of points, the size the block works out for itself so that the whole of its text holds the rectangle — the sizes tried step down from the one the block asked for, each broken to the box and weighed against it, the largest that holds the text being the one it is set at, and a box no size can fill sets the text at the floor and lets it run past; absent, the block is set at the size it asked for, whatever runs past; pages (default empty); id; relative_to; transform; rotate; layer. Cross refusals: hanging_list with left_indent, first_line_indent, tabs.method or tabs.ruler; fill_leading with leading; transform with rotate. leader also takes an object in place of one character: text, required, the string repeated, of any length, ". " spacing the dots apart; font and font_size, the block's own by default; color, the block's by default; rise, how many points above the baseline the repeats sit, below it where negative, on it by default; fit, where the repeats stand in the room they fill: from_text (default), laid from the words outwards; from_edge, ending against the far edge; grid, on a grid of the repeat's width counted from the left edge of the box, so that the repeats of every line stand in the same columns; stretch, as many whole repeats as fit, spaced out to reach from one end of the room to the other. character_spacing, horizontal_scaling and cut_mark read as they read on a text block. Three keys carry the text on past its rectangle: continued_in, an array of rectangles each as wide as rect, the boxes the text goes on in once rect is full, in order; max_lines, an integer, the most lines one box takes whatever its height, zero read as one; box_break, one character read in the text as the end of a box, which ends its paragraph, draws nothing and sends the rest of the text to the next box, the form feed "\f" being the one a text written elsewhere carries for a page break. A block naming any of the three lays in each box the lines it holds and draws none of the lines left once the last box is full; a box of another width than rect is refused. rule_stacking, on a flow or a text item, says which of the rules and the letters covers the other: "over", the default, lays the rules after the letters and over them, and "under" lays them first and paints the letters over them.
A Whole Request That Creates a PDF
{
"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,
"replacing": {"*": {"each": ""}, " ": {"run": " "}},
"first_line_indent": 14,
"space_after": 6,
"first_baseline": "cap_height",
"last_baseline": "descender",
"overlong": "break",
"tabs": {
"method": "relative",
"size": { "points": 36 },
"ruler": [72, 180],
"alignments": ["left", "decimal"]
}
},
{
"type": "flow",
"rect": {"llx": 72, "lly": 600, "urx": 252, "ury": 630},
"content": "Delivery\t12.50",
"font": "serif",
"font_size": 11,
"leader": {"text": ". ", "fit": "grid"},
"tabs": {"method": "ruler", "ruler": [180], "alignments": ["right"]}
}
]
}
Text
A Block of Text Placed on the Page A Stamp Laid across the Page A Line of Words Set Along a Path A Row of Glyphs Asked for by Their Number Blocks Laid One under the Other, Page After Page
Where to Go Next
Every JSON key of a request, in one page The other twenty-two things you can draw