PageWright Developer Manual

This is the PageWright™ Developer Manual. PageWright is a PDF page-layout engine: you describe a document as a JSON spec - its pages, text, tables, images, charts, forms and structure - and the engine flows it onto pages and writes a tagged, standards-compliant PDF.

Every page of this manual was produced by the engine itself from a JSON spec (sample/guide-developer-manual.json), so it doubles as a worked example: the cover, the table of contents, the running heads and folios, the code boxes, the reference tables, and the index and glossary at the back are all ordinary engine features described in these pages.

The engine's central idea is two passes. Many layout decisions depend on facts that are only known after layout - the total page count printed in a footer, the page a heading lands on for its table-of-contents entry, the page a threaded story is continued on. The engine resolves these by laying the document out more than once:

1. A counting pass runs the full layout against a metrics-only target that measures glyphs and boxes but draws nothing. It records where every heading, index term and frame landed.
2. Because the resolved numbers can themselves change the layout (a table of contents that grows by a line pushes everything down), the counting pass repeats as a fixed-point loop until the page numbers stop moving - usually two or three iterations.
3. A final render pass then draws the document once, pouring in the now-exact numbers and emitting the PDF.

Counting passes are cheap (no ink, no font embedding), so the loop converges fast. The table of contents, {{pages}} totals, the index and glossary, and article-threading jump lines all ride this one mechanism.

Why the loop converges

A naive worry is that resolving a page number changes the layout, which changes the page number, forever. It converges because each unknown reserves a fixed amount of space the moment its flag is set, independent of the digits it will eventually show: a {{pages}} footer is one line tall whether the total is 9 or 99; a TOC row is one line whether it points to page 3 or 30; a jump line reserves one line whether it reads "page 4" or "page 14". So the geometry stabilizes in the first pass or two; only the printed numerals refine afterwards, and they cannot move anything. In practice two or three counting passes suffice, and the engine stops as soon as a pass changes no page number.

Engine math is double, in PDF points, with a top-left origin and y increasing downward - the space the layout map and position use. The backend flips to PDF's bottom-left, y-up convention at emit time.

The engine never calls the PDF library directly. It speaks only to an abstract IRenderTarget, which has two implementations: APDFLRenderTarget (writes PDF via the Adobe PDF Library) and MetricsOnlyTarget (measures only - the counting pass). This boundary keeps the layout math unit-testable and leaves room for a non-APDFL backend.

Pagination is built on block fragmentation: a block's Place() returns the fragment that fit plus an optional remainder to continue on the next page or column. A paragraph splits between lines, a table between (or within) rows, a container between its children - and each remainder carries the tagging and style context so the continuation stays correct.

Between the characters in the spec and the glyphs in the content stream sit four transforms, in this order:

Bidi: UAX #9 over ICU

The bidi pass is a thin wrapper over ICU's ubidi API. It resolves the paragraph level, splits the text into runs of uniform embedding level, and hands the layout code pieces it can lay out left-to-right. The visual reorder happens at draw, not at measure: line breaking works in logical order, and only when a line is committed are its pieces emitted in visual order.

A reversed piece carries /ActualText naming the logical string it stands for. That is what keeps copy, search and a screen reader reading the sentence the author wrote rather than the order the glyphs were painted in.

Shaping and the fallback path

The engine parses the face's GSUB table, including the contextual lookup types (5 and 6) that Devanagari reordering needs. Arabic joining and the lam-alef ligature come out of the same machinery, and so do Indic clusters and reph.

When a face has no usable GSUB, Arabic falls back to the Unicode presentation forms block - the precomposed isolated/initial/medial/final codepoints. The text is readable, but it is a different mechanism with different limits: presentation forms have no joints, so kashida justification has nothing to elongate and silently does nothing. The gate distinguishes the two paths by signature rather than trusting either.

Why the engine authors its own /ToUnicode

A shaped run is drawn by glyph id, not by character code. Nothing in the font's own encoding maps those ids back to what the author typed - a ligature glyph is not f followed by i, and a Devanagari conjunct is not any single character. So the engine builds the /ToUnicode CMap itself, from the character-to-glyph correspondence shaping recorded on the way through.

The oracles

None of the above is verified by looking at a page. Each stage is checked against an independent implementation, and each check carries a negative control that proves it can fail:

One of these oracles was itself wrong for a while, which is worth knowing before you trust a green result. The drawn-order check used to union every /ToUnicode CMap in the file into one lookup, assuming a code meant the same character in every subset. It does not - subset encodings are per font, and one document embedding two RTL faces had 75 colliding codes. It produced false failures, and the same wrong decode could equally have masked a real reordering. It now decodes per font.

A spec is one JSON object. The keys most documents use - Appendix A lists all 56, generated from the schema:

Metadata is written twice for interoperability: Unicode-safe into the /Info dictionary (PDDocSetInfoAsASText) and into an XMP packet (PDDocSetXAPMetadata), so a reader that trusts either source sees the same values. Two fields have defaults you never have to set: /Creator is PageWright (the tool that laid the page out), and /Producer is Appligent PageWright (the library that wrote the file) - the latter in both /Info and XMP pdf:Producer. Override the producer when you ship the engine inside your own application:

{
  "title": "Quarterly Report",
  "author": "Finance",
  "producer": "Acme Report Server 4.2",
  "blocks": [
    {
      "type": "paragraph",
      "text": "..."
    }
  ]
}

The complete grammar is published as a JSON Schema (draft 2020-12) at aplayout.schema.json - every block type, style key, color form, page-setup key, chart and form field. The engine checks every spec against it on the way in, whichever way the spec arrives - a single render, a batch or the server:

The engine finds the schema at $APLAYOUT_SCHEMA when that is set, then in the Appligent home (-aphome), then in /usr/local/appligent/aplayout/ and /Applications/Appligent/; when it finds none it says the spec was not checked. Point an editor at the same file for completion and inline validation as you type. A CI job without the engine can use any JSON Schema validator, such as check-jsonschema --schemafile aplayout.schema.json mydoc.json. The schema is the contract; this manual is the explanation.

pagewrightapp renders one spec to one PDF:

pagewrightapp spec.json out.pdf            # render
pagewrightapp spec.json out.pdf -map out.map.json   # + a layout map
pagewrightapp -batch jobs.txt               # many documents, ONE process
pagewrightapp -batch jobs.txt -jobs auto    # ... across several worker processes
pagewrightapp -fonts                        # list embeddable system fonts (JSON)

A relative asset src resolves against the spec file's directory, so a spec travels with its images and placed PDFs. The output path is resolved against the working directory, like any other command-line tool.

For applications that render many documents, the engine ships as an apDocLib server command, LayoutDocument, driven over stdin exactly as a host application (for example a Xojo app via Lib_Shell) drives it. The library and fonts initialize once, so each subsequent render costs only its own layout time:

printf 'LayoutDocument -infile spec.json -outfile out.pdf\nexit\n' \
  | apdoclibapp -start

The engine is not distributed as a standalone library. It is delivered as the command-line tool, the apDocLib server and the PageWright Studio designer; an application that needs to render documents drives the server, which is the supported integration path and the one Part VII measures.

This chapter is here so the internals are legible, not as an interface to build against. Appligent's own applications link LayoutEngine against an APDFLRenderTarget: the model is built from JSON (or constructed directly), and Render runs the two-pass flow, optionally returning a layout map.

LayoutDocument doc;
LoadDocumentFromFile("spec.json", doc, err);

APDFLRenderTarget target(pdfDoc, doc.info);
LayoutMap map;
LayoutEngine engine;
engine.Render(doc, target, &map);               // counting + render
engine.WriteLayoutMap(map, "out.map.json", err);

Server integration is mechanical: declare Do_LayoutDocument, add a LayoutDocument case to the command dispatcher, parse the spec into the model, run the engine against an APDFLRenderTarget, and save.

Four features exist so an interactive editor can sit on top of the engine. The first is the layout map (-map): alongside the PDF the engine writes where everything landed, collected on the final pass. Each block is keyed by a JSON Pointer into the source spec, so a tool hit-tests a click to a path, mutates that node, and re-renders.

{
  "version": 1,
  "units": "pt",
  "origin": "top-left",
  "pages": [
    {
      "width": 612,
      "height": 792,
      "label": "1",
      "content": {
        "x": 64,
        "y": 64,
        "w": 484,
        "h": 664
      }
    }
  ],
  "blocks": [
    {
      "path": "/sections/1/blocks/3",
      "type": "table",
      "id": "ledger",
      "fragments": [
        {
          "page": 2,
          "x": 64,
          "y": 64,
          "w": 484,
          "h": 503
        },
        {
          "page": 3,
          "x": 64,
          "y": 64,
          "w": 484,
          "h": 96
        }
      ]
    }
  ]
}

Coordinates are points with a top-left origin, matching a raster of the page after scaling by dpi / 72. The map records spec blocks only - engine- synthesized content (running bands, footnote bodies, repeated table headers, watermarks) has no pointer and is deliberately absent. Ancestry is derivable from the path string, so a tool resolves a click to the deepest entry and walks outward. Engine API: LayoutEngine::Render(doc, target, &map) then WriteLayoutMap(map, path, err).

The other three editor features:

• Absolute positioning (position on any block) - direct manipulation and form overlays onto existing PDFs. Map visual rect equals position rect, so a drag writes straight back to the spec.
• Named stylesheets (styles + basedOn) - the "edit once, document follows" primitive: keep styles in the table, reference by name, and one edit restyles every use on the next render.
• Font enumeration (pagewrightapp -fonts) - a picker offers only fonts the engine can actually resolve and embed.

The companion PageWright Studio application is a full document/form designer built on exactly these four hooks: render with -map, raster the page, drag the visual rectangles, write new position values back through the JSON Pointers, re-render (the server mode renders in ~10 ms).

With "tagged": true the engine builds a logical structure tree and marks the content stream so each span belongs to a structure element. The block -> tag mapping:

The engine assigns its own MCIDs (page-scoped, reset per page) so the raw operator stream and the embedded-text PDE containers share one numbering, then builds the StructTreeRoot, the /K child arrays in reading order, and a ParentTree mapping page + annotation entries back to elements. The StructTreeRoot also gets a /RoleMap when a non-standard type is present, and under PDF/UA-2 a /Namespaces array - with /NS on the Document root and on every Aside, a type that exists only in PDF 2.0. The catalog gets /MarkInfo, /Lang, /ViewerPreferences/DisplayDocTitle, and the XMP gets pdfuaid:part.

Three things about that mapping are the author's choice, not the engine's. sectionTags decides whether a heading opens a nested Sect at all (auto / pages / none); a container's role decides whether the box is a structure element or nothing; and a table with rowGroups produces a different tree entirely - one Table across every page it runs to, group headings lifted into rowspanned TH cells in synthetic leading columns, and /Headers derived on every cell. All of it is PDF/UA-1 clean either way; what differs is what a screen reader walks through. The Users Manual, Part VIII covers the authoring side.

Two backend mechanisms make the last of those possible, and they are the only places the structure tree is allowed to diverge from the order content is drawn in. OpenStructDeferred / AdoptStruct open an element with no parent and let a later row adopt it as the head of its children - that is how a heading drawn in its own full-width row becomes the first cell of the row beneath it without the ink moving. HoldStructOpen / ReleaseHeldStruct keep one element open across a page break, which is what makes a single Table legal over three pages: an element's /K holds marked-content references that each name their own /Pg, so one element may reference content on any number of pages. A deferred element that is never adopted refuses the document rather than being written dangling.

The structure-event API

The layout engine emits structure through IRenderTarget hooks that are no-ops on the metrics/counting targets - so counting passes build no tags, and only the final pass produces the tree. Five carry ordinary tagging:

bool Tagging() const;                  // gate: skip tagging when off
void BeginStruct(const StructAttr&);   // open P / H1 / Figure / Table / Aside / ...
void EndStruct();
void BeginArtifact(ArtifactKind);      // Pagination | Layout | Page
void EndArtifact();

Four more exist for the one case where the tree must diverge from the order content is drawn in - a hierarchical table. They are deliberately generic rather than table-specific, and SuspendStructure / ResumeStructure complete the set by parking the open scope while a footnote body or running band is drawn mid-flow:

int  OpenStructDeferred(const StructAttr&); // an element with NO parent; returns a handle
void AdoptStruct(int handle);               // make it a child of the CURRENTLY open element
int  HoldStructOpen();                      // the innermost element outlives its caller's scope
void ReleaseHeldStruct(int handle);         // ...which is how ONE <Table> spans a page break

StructAttr carries eleven fields - {type, alt, actualText, lang, mathML, scope, listNumbering, colSpan, rowSpan, id, headers} - and the last four are what make PDF/UA table association expressible: id names a cell, headers lists the cells that govern it. RAII guards (TagScope / ArtifactScope) keep the open/close balanced.

Structure elements are created per Place call by default, so a paragraph split across pages becomes two valid <P> and a split table re-emits a complete <Table> per fragment with its header rows re-tagged. That is this engine's habit, not a rule of the format: an element's /K holds marked-content references that each name their own /Pg, so one element may span pages. A rowGroups table does exactly that - one <Table> for the whole run via HoldStructOpen / ReleaseHeldStruct, with the repeated column band on later pages artifacted - and a split call-out re-opens its <Aside> on each continuation page.

Adding virtuals shifts the IRenderTarget vtable, so every translation unit must be rebuilt.

Four things make a tagged file actually pass PDF/UA-1, each learned from a real veraPDF failure:

1. All fonts embedded (7.21.4.1) - Base-14 cannot embed, so a tagged doc with no embedFont auto-embeds a Helvetica subset.
2. No inconsistent /CIDSet (7.21.4.2) - APDFL's subsetter writes one that veraPDF rejects; StripCIDSets() removes it (and recurses into imported Form-XObject resources for placed PDFs).
3. Links fully tagged (7.18) - the Link element, an OBJR to the annotation, /Contents, and a /StructParent round-tripped through the ParentTree.
4. A /RoleMap for any non-standard type - <Aside> does not exist before PDF 2.0, so emitting one without mapping it fails outright. Whenever an Aside is present and the target is not PDF/UA-2, the engine writes /RoleMap << /Aside /Div >> on the StructTreeRoot. Under PDF/UA-2 the type is standard and is namespaced instead, so no map is written - remapping a standard type there would describe it as something it is not.

The authoritative check is verapdf --flavour ua1 out.pdf; every tagged sample passes with zero failures.

Form widgets and per-element language

Two more cases the engine handles so authors do not have to. A form widget is wrapped in its own <Form> element that holds only the widget's OBJR (PDF/UA clause 7.18.4) - the visible label is a sibling <P>, and a radio group becomes several <Form>s, one per option, each with a /StructParent and a /TU accessible name. A pre-filled text or choice value is stored as a UTF-16BE string so its appearance font embeds, satisfying 7.21.4.1.

Per-element language threads through too: a block lang sets /Lang on its element (and on every fragment of a page-split paragraph), while a run lang wraps just that run in a <Span> with /Lang, grouped as one Span per contiguous same-language run - not per word.

pdfa selects an ISO 19005-2 level. At FinishDocument the engine emits the conformance machinery: an /OutputIntents entry (/S /GTS_PDFA1) whose /DestOutputProfile is a bundled ICC profile - sRGB by default, or U.S. Web Coated SWOP v2 (or the document's outputProfile) when colorMode is cmyk - so the file is self-contained; a pdfaid XMP packet with the part and conformance letter; and enforced font embedding. Level 2a additionally turns tagging on and emits a pdfuaid extension-schema description so the one file is valid PDF/A-2a and PDF/UA.

The /OutputIntents entry the engine writes onto the catalog, with the ICC profile embedded as a compressed stream so the file is self-contained:

/OutputIntents [ <<
  /Type /OutputIntent  /S /GTS_PDFA1
  /OutputConditionIdentifier (sRGB IEC61966-2.1)
  /Info (sRGB IEC61966-2.1)
  /DestOutputProfile <ICC stream, /N 3, FlateDecode>
>> ]

The sRGB and SWOP profile bytes are bundled in the binary, so there is no runtime dependency on an installed profile. /S /GTS_PDFA1 is the subtype for every PDF/A part. The XMP gains pdfaid:part + pdfaid:conformance; a 2a file additionally carries a pdfuaid extension-schema description (PDF/A only permits predefined or PDF/A-extension schemas, and pdfuaid is neither), without which --flavour 2a fails clause 6.6.2.3.1.

Print furniture lives in pageSetup. bleed (a scalar or per-edge insets) grows the MediaBox and sets TrimBox/BleedBox for imposition while content stays in trim coordinates. marks strokes crop marks and registration targets - in a real /Separation /All ink so they print on every plate - outside the bleed. background, colorBars and slug complete the slug area. All of it is drawn as a Page artifact, so a tagged PDF/A-2a file with bleed and marks still passes both --flavour 2a and --flavour ua1.

The engine is fast; the one large cost is font embedding, and it is paid once per process, not per document:

Tagging itself is nearly free (about 7 ms on a 27-page document); but PDF/UA requires embedded fonts, and the first embed triggers a ~540 ms system-font load that APDFL then caches process-globally. On the long-running server that cost is amortized to near zero - which is the whole reason to prefer the server for batches. Body layout runs ~2 ms/page (Base-14); the per-page Flate compression of the content stream is the next-largest cross-cutting cost. Building at -O2 roughly halves the pure-layout path.

Feature isolation

Cost of turning on one feature at a time, on a 400-paragraph (~27-page) document (warm minimum, milliseconds):

Scaling

Everything is linear except tagged tables of hundreds of rows, where re-tagging repeated header rows across many page fragments compounds - fine for ordinary documents, a consideration for data-table-heavy output.

CLI versus server, measured

Successive LayoutDocument requests to one warm server process (the embed doc - four embedded font variants):

For raster-heavy documents, the top-level images policy trims file size: maxPpi downsamples images placed above a resolution, format chooses pass-through JPEG vs lossless Flate vs re-encode, jpegQuality tunes re-encode quality, and predictor applies PNG row predictors to lossless images. minPpi changes nothing in the file: it reports, with the block's pointer, any image block placed below that effective resolution - a preflight for print.

{
  "images": {
    "maxPpi": 200,
    "format": "auto",
    "jpegQuality": 80,
    "predictor": true
  }
}

A new capability touches the same five layers, in order. The article-threading feature (frame blocks + stories) is a representative case study:

1. Model - a FrameBlock type and a Story / stories container on LayoutDocument.
2. JSON - parse the new block and the top-level stories into the model.
3. Layout - FrameBlock::Place runs a column loop that pulls from a resumable story cursor and threads the overflow forward.
4. Engine - own the per-document story pool, reset it each sweep, and resolve the jump-line page numbers in the fixed-point loop.
5. Render - usually nothing new: frames reuse the existing absolute-placement and cross-reference machinery, so no backend change was needed.

Most features follow this shape; the render layer changes only when a genuinely new drawing primitive is required (as FillPolygon was for pie and radar charts).

The Place / Measure contract

Every block implements two methods. Measure reports the height a block wants at a given width (used by tables, floats and keep-together decisions). Place draws as much as fits in the available band and returns a remainder - the part that did not fit - or none. The remainder is itself a block (often a lightweight PreflowedText / WrappedFlow carrying pre-broken lines), so the engine simply places it again at the top of the next column or page. This single contract is what makes pagination, column flow, and threaded frames all fall out of the same loop.

A new drawing primitive - when a feature truly needs one - is added to IRenderTarget and implemented on both targets (a real draw on APDFLRenderTarget, a no-op on the metrics target). FillPolygon, added for pie wedges and radar fills, is the model: a handful of lines on each target, emitted inside the chart's Figure so it stays PDF/UA-clean. Adding a virtual shifts the vtable, so rebuild every translation unit.

Every top-level spec key, with where it is covered:

Every top-level spec key. This table is GENERATED from aplayout.schema.json at build time - the hand-maintained version of it named 23 of the 56 keys and called itself complete, which is the failure mode a generated table cannot have:

CLI - pagewrightapp:

pagewrightapp <spec.json> <out.pdf> [-map <out.map.json>] [-impose <booklet.pdf>]
pagewrightapp -batch <jobs.txt> [-jobs N|auto]
pagewrightapp -checkschema <spec.json> [<spec.json> ...]
pagewrightapp -fonts [-fontdir <dir>]  # JSON list of embeddable fonts
pagewrightapp -license               # licence status as JSON

Server - the LayoutDocument command on apdoclibapp:

LayoutDocument -infile <spec.json> -outfile <out.pdf> [-mapfile <map.json>]

Validate - against the published schema:

pagewrightapp -checkschema <spec.json>
check-jsonschema --schemafile aplayout.schema.json <spec.json>   # without the engine

Verify output - accessibility and archival conformance:

verapdf --flavour ua1 <out.pdf>     # PDF/UA-1
verapdf --flavour 2a  <out.pdf>     # PDF/A-2a
qpdf --check <out.pdf>              # structural check

The engine's dependencies, and what each is used for:

Base-14
The fourteen fonts every PDF reader provides built in (Helvetica, Times, Courier families, Symbol, ZapfDingbats); usable with no embedding.

Bleed
Extra printed area past the trim edge so ink runs to the edge after cutting; set with pageSetup.bleed.

Block
One unit of content in a spec (paragraph, heading, list, table, image, chart, …), identified by its type.

Embedded font
A font subset stored inside the PDF so it renders identically anywhere; required for tagged and PDF/A output.

Frame
An absolutely-positioned box that pours a story into its columns; frames referencing one story form a thread (article threading).

OutputIntent
A PDF/A color-characterization dictionary naming the target color space via an embedded ICC profile (sRGB or CMYK).

PDF/A
ISO 19005 archival PDF: self-contained and reproducible. Levels 2b, 2u, 2a in this engine.

PDF/UA
ISO 14289 universal-accessibility PDF: a tagged logical structure tree with reading order and alternate text.

Point
The PDF unit of length, 1/72 inch. All coordinates and sizes in a spec are points unless written as a percentage.

Run
A span of text within a paragraph carrying its own style, link, footnote or language.

Section
A run of pages with its own page setup; a document is one implicit section (blocks) or several explicit ones (sections).

Spot color
A named ink (e.g. a Pantone) emitted as a PDF /Separation color space with a CMYK alternate; see Color Spaces.

Story
A free-standing list of blocks, not in the normal flow, poured into a thread of frames.

Tagged PDF
A PDF carrying a logical structure tree (the basis of PDF/UA accessibility).

Counting pass
A metrics-only layout pass that draws nothing; it measures the document so forward references (TOC, totals, index) resolve before any ink is committed.

Render target
The IRenderTarget interface between the layout engine and a backend; APDFLRenderTarget writes PDF, MetricsOnlyTarget only measures.

Form XObject
A reusable PDF content stream; the engine imports an external PDF page or a letterhead as one, vector and unrasterized.

MCID
Marked-content identifier: a per-page integer linking a span of page content to its element in the structure tree via the parent tree.

Layout map
The -map sidecar JSON: for every spec block, the page and rectangles where it landed, keyed by a JSON Pointer into the source spec.

Structure tree
The logical tree of elements (Document, H1, P, Table, …) that makes a PDF tagged and accessible.