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.

Summary

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.

Technically

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

reading carries seventeen settings, all optional, describing what the request asks of the reading software: /PageMode and /PageLayout in the catalogue for the side panel and the page layout, an /OpenAction for the opening page and its framing, and the rest into /ViewerPreferences — 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 reading software alone.

Request schema

  • reading — object, optional, absent by default. Seventeen keys, all optional.
  • open_mode — string. What reading software 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 reading software 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 has 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 what asked for more.

A whole request that creates a PDF

{
  "reading": {
    "open_mode": "bookmarks",
    "after_full_screen": "bookmarks",
    "duplex": "long_edge",
    "print_scaling": "actual_size",
    "reading_order": "left_to_right",
    "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 What a page sets off as reading software comes and goes What the document says it is made of The clickable contents down the side Landing places that have a name Following an article column by column

Where to go next

Every JSON key of a request, in one page The other forty-one settings of a request

See the prices See the examples