# Writing a PDF by hand

```{admonition} Status: outline
:class: warning

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

- **ISO 32000-1 / PDF 1.7**, published free by Adobe.
  <https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/PDF32000_2008.pdf>. The
  authority. Sections 7.5 (file structure) and 8.5 (path construction and painting) are the
  two you need.