format/pdf: exact size, and the padding channel we had written down was wrong

PDF is the third format and the highest fidelity bar in Tier 1. Exact size,
byte determinism, pages and page size as properties, label in the footer and
in the document title.

The interesting part is what measurement overturned.

This project had recorded the padding channel as "a comment block before
%%EOF, no limit". The reasoning behind it was sound as far as it went -
objects and the cross reference table both sit earlier in the file, so a
comment at the end moves no offset. What it missed is how a reader finds that
table: by scanning backwards from the end of the file for startxref, over a
window each reader picks for itself. Xpdf 4.06 reads 1004 bytes of comment
there and fails at 1005. The Windows renderer reads any amount.

That is worse than a hard limit would be. A file that opens for one tester
and not for another is the one outcome a fixture generator must never
produce.

So the channel moved to a comment after the trailer and before startxref. The
tail from startxref to the end stays short whatever the padding size, and
startxref still points at the same offset because the table sits earlier.
Measured at 64 B, 4 KB, 100 KB, 1 MB, 2 MB and 10 MB against three
independent engines - Xpdf, exiftool and the Windows renderer used by the
system viewer. All three read the document and report the right page count.

This is the third claim written from memory that a few minutes of measurement
has disproved, after the 7Z tail and the size units.

Registering PDF also made the property test find two defects immediately. The
comment splitter could leave exactly one byte over, which cannot form a
comment line. And the seed test asked for the declared minimum with the label
on, while the declared minimum is the label free one - the message now says
so and offers --clean.

Fonts are not embedded. Helvetica is one of the fourteen every reader already
has, which keeps a font file and its licence out of this for now.

Fidelity is declared full and confirmed in three engines, not in Adobe.
Acrobat is installed here and stays a manual checklist item.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: donislawdev

CHANGELOG-DEV.md

@@ -6,6 +6,35 @@ configuration, architectural decisions. Anything a user would notice goes to
 
 ## Unreleased
 
+### 2026-08-01 - PDF, and an assumption of ours disproved
+
+- `pdf` is the third generator. Exact size, byte determinism, pages and page
+  size as properties, label in the footer and in the document title.
+- **The padding channel this project had written down was wrong, and
+  measurement caught it.** The note said "a comment block before %%EOF, no
+  limit". The reasoning behind it was sound as far as it went - objects and
+  the cross reference table sit earlier, so a comment at the end moves no
+  offset. What it missed is that a reader finds the table by scanning
+  backwards for startxref, and how far back is up to the reader. Xpdf 4.06
+  reads 1004 bytes of comment there and fails at 1005. The Windows renderer
+  reads any amount.
+- **That is worse than a hard limit**, because the file would open for one
+  tester and not for another. The channel moved to a comment after the
+  trailer and before startxref, where the tail stays short whatever the
+  padding size. Measured at 64 B, 4 KB, 100 KB, 1 MB, 2 MB and 10 MB against
+  Xpdf, exiftool and the Windows renderer.
+- This is the third time a claim written from memory has been disproved by a
+  few minutes of measurement, after the 7Z tail and the size units.
+- **The property test found two defects the moment PDF was registered.** The
+  comment splitter could leave exactly one byte over, which cannot be a
+  comment line. And the seed test asked for the declared minimum with a label
+  on, while the declared minimum is the label free one.
+- Fonts are not embedded. Helvetica is one of the fourteen a reader already
+  has, which keeps a font file and its licence out of the picture for now.
+- **Fidelity is declared full but not confirmed in Adobe.** Three engines
+  read it. Adobe Acrobat DC is installed and stays a manual checklist item.
+- Guards: 33, all still green with three formats registered.
+
 ### 2026-08-01 - review after the second format
 
 Another read through everything, this time with memory measured rather than

CHANGELOG.md

@@ -12,8 +12,11 @@ because it turns other people's test suites red.
 
 ### Added
 
-- `tfg generate` produces **text and PNG files** of an exact size. Ask for
-  10 485 761 bytes and you get exactly that.
+- `tfg generate` produces **text, PNG and PDF files** of an exact size. Ask
+  for 10 485 761 bytes and you get exactly that.
+- PDF takes `--set pages=` and `--set page_size=` (A4, A3, A5, Letter,
+  Legal). The label goes in the page footer and in the document title.
+  Checked against Xpdf, exiftool and the Windows PDF renderer.
 - PNG carries the label burned into the picture, and its size is made exact
   by a private chunk that decoders ignore. Checked against Pillow, FFmpeg,
   Tcl/Tk, the Windows Imaging Component and exiftool - all five read the

internal/format/all/all.go

@@ -8,6 +8,7 @@ package all
 
 import (
 	// Each format registers itself when its package is loaded.
+	_ "github.com/donislawdev/TestingFilesGenerator/internal/format/pdf"
 	_ "github.com/donislawdev/TestingFilesGenerator/internal/format/png"
 	_ "github.com/donislawdev/TestingFilesGenerator/internal/format/txt"
 )