How the document opens and prints

Ask the reading software what to show on opening, how to lay the pages out, and what to offer when printing.

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

In plain words

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

A document can arrive already set up. It opens with its contents unfolded down the side, at the right page, at the right size. A book shows two pages side by side, like a real open book. And when printing time comes, the dialogue already offers double-sided, two copies, and the pages that matter. These are wishes: the reading software follows them where it can, and nothing breaks where it does otherwise.

For a developer

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

reading carries seventeen settings, all optional, describing what the request asks of the reader: the side panel, the page layout, the opening page and its framing, the window's trappings, the reading order, and the wishes a print dialogue reads. Every field stays out of the document until the request writes it: a request asking for one thing asks for that one thing and leaves the rest of the reader alone.

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.

  • reading — object, optional, absent by default. Seventeen keys, all optional.
  • open_mode — string. What the reader shows beside the page on opening. Six values: page_only, bookmarks, thumbnails, full_screen, layers, attachments.
  • page_layout — string. Six values: single_page, one_column, two_columns_odd_left, two_columns_odd_right, two_pages_odd_left, two_pages_odd_right.
  • open_on — object. page integer ≥ 1 required, fit optional, whole_page by default, the eight framing shapes being those of destinations.
  • hide_toolbar, hide_menu_bar, hide_window_controls, fit_window, center_window, show_title — booleans.
  • after_full_screen — string. What is shown beside the page once full screen is left. Four values: page_only, bookmarks, thumbnails, layers.
  • reading_order — string. Two values: left_to_right, right_to_left.
  • print_scaling — string. Two values: viewer, actual_size.
  • lock_actual_size — boolean, false by default. Tells the reader it may offer no size but the one asked for.
  • duplex — string. Three values: one_sided, short_edge, long_edge.
  • tray_by_page_size — boolean.
  • copies — integer ≥ 1.
  • print_runs — array, empty by default. Each entry carries first_page and last_page, integers ≥ 1, both required.

The print wishes ask for PDF 1.7 at least; lock_actual_size asks for PDF 2.0. A document declaring a version below what it carries is refused when it is written, and the answer names the part that asked for more.

A whole request that draws it

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

{
  "reading": {
    "open_mode": "bookmarks",
    "page_layout": "two_pages_odd_right",
    "open_on": { "page": 1, "fit": "whole_page" }
  },
  "bookmarks": [{ "title": "The cover", "page": 1 }],
  "standard_fonts": [{ "name": "sans", "face": "helvetica" }],
  "items": [
    {
      "type": "text",
      "rect": { "llx": 60, "lly": 700, "urx": 535, "ury": 740 },
      "content": ["The handbook"],
      "font": "sans",
      "font_size": 28
    }
  ]
}

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

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

bookmark
The list of headings a PDF reader shows down the side of a document, each line leading straight to its place in it. It is the table of contents the software owns rather than the one printed on a page, and a long document without it is one nobody can find their way around.
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