A Hundred Letters in a Single File

Say, inside the file itself, where one recipient ends and the next begins, with what the finishing needs.

See It in a Real PDF

Three Statements in One File

Four pages holding three customer account statements. Each statement declares the pages that belong to it, the customer it is meant for, the number of copies to print, and the attached file that comes with it.

Open the PDF The Whole Example

Also shown in: One Letter per Recipient, All in the Same File

Summary

A run of a hundred statements is one big file and a hundred different letters. The machine that prints and folds them has to know where to cut: two sheets for this one, one for that one. Usually it is told in a second file, kept apart — and the day the two fall out of step, a hundred envelopes go out wrong. Here the recipient's name, their town and their reference travel with the pages, so one single file goes to the workshop and stands on its own.

Technically

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

document_parts writes the /DPartRoot hierarchy of PDF 2.0: a tree whose leaves each claim a range of pages, and whose nodes carry the named values a finishing workshop reads. A leaf claims its pages either by naming the first and last number, or by counting on from where the document part before it left off; the two ways mix freely. What a document part states is a list of named values, never an object, because the order it is written in is the order it was given.

Request Schema

  • document_parts — object, optional, absent by default. Absent, the file is one single document.
  • document_parts.root — object, required. The part every other part hangs from.
  • document_parts.node_names — array of strings, optional, empty by default. What each level of the hierarchy is called, from the root down. A name a job ticket cannot read is refused.
  • document_parts.record_level — integer, optional. The level whose parts each stand for one recipient, counting the root as level zero.
  • A node has children (recursive array, empty by default) or claim, never both, never neither.
  • claim takes two shapes: {"pages": {"first": n, "last": n}} with two integers ≥ 1, a range ending before it starts being refused; or {"next_pages": n} with an integer ≥ 1, taking up where the document part before it left off. Two ranges that overlap are refused.
  • data — array, optional, empty by default. The named values the part states, in order.
  • data[].name — string, required. ASCII letters and digits, _, -, . and :, beginning with a letter, _ or :.
  • data[].value — required. Seven shapes: {"text": s}, {"date": s} in ISO 8601, {"integer": i}, {"real": f}, {"boolean": b}, {"list": …}, {"fields": …} for nested named values.
  • metadata — object, optional. What the part says about itself for a program reading the file, in a metadata packet of its own: {"facts": {…}}, written from the fields the document's own metadata takes, or {"packet": "part name"}, a packet supplied as a part and carried as it stands.

Document parts are described by clause 14.12 of ISO 32000-2; the example below states "version": "2.0", which is the version reading software wants to honour them.

A Whole Request That Creates a PDF

{
  "version": "2.0",
  "document_parts": {
    "root": {
      "children": [
        {
          "claim": { "next_pages": 1 },
          "data": [{ "name": "Recipient", "value": { "text": "Baker and Sons" } }]
        },
        {
          "claim": { "next_pages": 1 },
          "data": [{ "name": "Recipient", "value": { "text": "Westmill Dairy" } }]
        }
      ]
    }
  },
  "standard_fonts": [{ "name": "sans", "face": "helvetica" }],
  "items": [
    {
      "type": "text",
      "pages": [1],
      "rect": { "llx": 60, "lly": 740, "urx": 535, "ury": 762 },
      "content": ["Statement for Baker and Sons"],
      "font": "sans",
      "font_size": 13
    },
    {
      "type": "text",
      "pages": [2],
      "rect": { "llx": 60, "lly": 740, "urx": 535, "ury": 762 },
      "content": ["Statement for Westmill Dairy"],
      "font": "sans",
      "font_size": 13
    }
  ]
}

The line that sends it, in three languages

The document as a whole

The Numbers Reading Software Shows What the Document Says about Itself What the Document Says about Itself, Said Once Text Nobody Can Copy The Notes a Program Leaves in the File for Itself The Notes a Program Leaves on One Page The Data a Program Hangs on a Run of Ink A File Still Readable Decades from Now The Print Standard the Document Claims The Variable Print Standard the Document Claims The Password That Opens It, and What May Be Done with It An Invoice a Person and a Machine Both Read The Address Relative Links Are Read Against The PDF Version the File Declares The Extensions to PDF the File Says It Uses What a Picture Says about Itself, and How It Is Read The Attachments the Document Carries Beside Its Pages Files the Document Names without Carrying The Attachments Shown as a Portfolio Which Attachments a Page Claims Which Attachments a Font Claims The Identity Card a Single Font Carries Which Attachments the Document's Card Claims A Document Card Written Elsewhere The Areas of a Page a Reader Measures In The Identity Card a Single Page Carries The Accessibility Standard the Document Claims The Standards the Finished Document Is Measured Against

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