Writing a PDF by hand

Status: outline

This chapter is scaffolded, not written. Section 1 and the failure modes below are real; sections 2 to 5 are placeholders. PRD 15.3 fixes the seven-part shape used here and states the standard: a dedicated chapter that takes a reader from novice to able to implement — not a literature dump and not a proof, but a constructive path. Do not delete a section heading to avoid filling it in.

1. The problem in one paragraph

A template must print at exactly 1:1, on a free Fusion licence, with the add-in in control of every dimension on the page. Fusion’s own export paths are licence-gated in ways that conflict with that requirement, and every candidate PDF library pulls a compiled dependency that reinstates the per-platform ABI matrix choosing Python was meant to avoid. So the add-in writes the file itself: a PDF is a header, a small graph of indirect objects, one content stream of drawing operators, a cross-reference table and a trailer. Sixty-six lines produced a page whose MediaBox was exact and whose calibration rectangle measured 99.835 x 50.044 mm against 100 x 50 drawn, at a raster resolution where one pixel is 84.7 micrometers (PRD 8.1, 8.2, PRD 11.13).

2. The minimum background

To be written. Develop the notation from scratch, defining every symbol at first use.

3. The derivation

To be written. In steps small enough that a reader can check each one individually.

4. The algorithm

To be written. Pseudocode using the real function names in this codebase, so a reader can move from the page to the source without a translation step.

5. A worked numerical example

To be written. With actual numbers a reader can reproduce, and the expected output printed in full. This section is what separates a chapter that can be implemented from one that can only be admired.

6. Failure modes

  • Confusing units. PDF user space is points, 1/72 inch; everything else in this project is millimeters. The transform belongs in one place.

  • Getting the cross-reference table byte offsets wrong, which produces a file most viewers repair silently and one viewer refuses.

  • Non-ASCII annotation text. O with a stroke, German component names and characters outside Latin-1 must round-trip; this is a failure class a library would have handled, so it is covered explicitly by PRD 13.3 T15.

7. References