Skip to content

Tagged PDF: PDF/UA-1 and PDF/A-3a from the boxes' roles - #114

Merged
czj merged 11 commits into
mainfrom
tagged-pdf
Nov 19, 2026
Merged

czj merged 11 commits into
mainfrom
tagged-pdf

Conversation

@czj

@czj czj commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

A screen reader reads the PDFs Gamba writes glyph by glyph, in drawing order: no headings, no tables, no language. #110 gave every native box a role; nothing read them yet.

pdf: :ua writes PDF/UA-1 and pdf_a: :a PDF/A-3a, alone or together, tagging the native boxes from their roles. Part of #76: the Prawn API's tag and artifact blocks, ActualText for ligatures and the cost on the benchmarks page come next.

  • Structure from roles: headings, paragraphs, lists, figures with their alt, and tables with column header cells, in the order boxes are placed. A paragraph or a table across pages stays one element; lang: on any box sets its language.
  • Artifacts: headers and footers (pagination artifacts), backgrounds, borders, page backgrounds, and the copy of a table's header atop later pages.
  • Rules raised where broken: a font not embedded (imported pages included), a figure without alt, a list item outside a list, anything drawn through document.prawn, and under pdf: :ua no lang, no title or a skipped heading level, raise PdfUaViolation (PdfAViolation under pdf_a: :a alone). In both modes, the default style's font is also the document's, looked up when first used, since Helvetica cannot be embedded.
  • Declared changes: in a tagged document, links and annotations raise, since Gamba does not tag them yet. pdf_a: now accepts only true, false, nil, :a and :b, and raises on anything else.
  • Known limits: a tagged document refuses to import a page with marked content of its own. The check reads the page's content streams, not its form XObjects. It errs on the side of refusing: optional-content layers (/OC … BDC), and text that happens to contain BDC or BMC as a word, count as marked content.
  • Tagged where placed: containers and the document tag a box when they place it (flow_tagged, paint_tagged), one tagged? check when untagged. A module prepended to every box class did it at first, and TruffleRuby skipped it.
  • veraPDF in CI: the PDF/A tests skipped in CI until now. CI installs veraPDF 1.30.4 (SHA-256 pinned, PGP signature checked), and a missing veraPDF fails there instead of skipping.
  • Nothing else moves: an untagged or PDF/A-3b document has the same bytes as on main, and tagged pages are pixel-identical to untagged ones with the same default font.
Proof
  • test/tagging_test.rb: veraPDF passes ua1 and 3a on a report (headings, a paragraph and a decorated stack across pages, lists, a figure, an 80-row table, a header, a French paragraph) under each mode and both together, and on the three bench/native documents tagged. qpdf reads back the structure tree, one paragraph and one table across pages with its header once, balanced marked content and MCIDs matching the ParentTree on every page, and the catalog and XMP. MuPDF renders tagged and untagged pages identically, also when a decorated stack moves to the next page before drawing. Tables in a figure and in a cell, and each raised rule, are covered too.
  • The layout fuzzer also runs a quarter of its trees as PDF/UA and checks every page's marked content. Its 250 tagged trees of seed 99 pass, and 26 trees from other seeds pass veraPDF ua1.
  • Untagged PDF and PDF/A-3b with Factur-X are byte-identical to main. bench/native, median of 15, no JIT then YJIT: report 385 / 303 ms on main against 388 / 309 ms here; catalog with YJIT interleaved 5 times 251 against 262 ms, within the noise of either side (237 to 278 ms). Same bytes, +0.1 % allocations (the lang slot).
  • CI green on every Ruby, TruffleRuby included, with veraPDF installed: 1405 runs. test_combined_pages_never_write_infinite_numbers failed here with the newer qpdf this workflow change pulled in; Combined pages always name their resources #115 fixed that on main, merged into this branch. RuboCop and the highlighted docs are clean.

czj added 4 commits November 19, 2026 11:54
pdf: :ua and pdf_a: :a tag the native boxes from their roles: a structure tree in reading order, marked content per page, artifacts for headers, footers, backgrounds, borders and repeated table headers. What breaks a rule raises where it is written. CI installs veraPDF, which checks PDF/A, PDF/UA and tagged documents.

Part of #76.

Assisted-by: Claude Opus 5.5 [Claude Code]
Marks are written at the first thing drawn, so a box moving to the next page leaves no empty sequence or decoration behind. Tables in a figure or a cell, list nesting, imported pages' fonts, page-create callbacks and a cell drawn alone are tagged or refused. The default style's font is looked up when first used, and style no longer places a waiting box.

Assisted-by: Claude Opus 5.5 [Claude Code]
…exts

A decoration moved beneath an artifact's content is written as an artifact of its own. Annotations, an alt that is blank or not text, and a lang that is not a language tag raise. The fuzzer turns one stack in three into an artifact and catches content painted outside any sequence.

Assisted-by: Claude Opus 5.5 [Claude Code]
A box's alt must be text and its lang a language tag, tagged or not; the document's lang too when tagged. A page with marked content of its own cannot go into a tagged document: its MCIDs would point at a structure tree left behind.

Assisted-by: Claude Opus 5.5 [Claude Code]
TruffleRuby skipped the module prepended from Node.inherited, so tagged documents raised there. Containers and the document now call flow_tagged and paint_tagged, which cost one tagged? check when untagged.

Assisted-by: Claude Opus 5.5 [Claude Code]
czj added a commit that referenced this pull request Nov 19, 2026
Gamba.combine copied a page without /Resources as it was, even though
ISO 32000-1 requires them, empty or inherited. qpdf 12.4 now warns about
such a page and repairs it, so
`test_combined_pages_never_write_infinite_numbers` fails on a Mac with
current Homebrew tools, and in CI once its package cache refreshes (it
does on #114).

A copied page with no resources of its own or inherited now gets an
empty dictionary, as pages Gamba draws already do.

- **Only invalid sources change**: a page that has resources, its own or
inherited, is copied as before.

<details><summary>Proof</summary>

- With qpdf 12.4.2 and MuPDF 1.28.6:
`test_combined_pages_never_write_infinite_numbers` fails on main and
passes here.
- Full `rake test` with the corpus fetched: 1387 runs, 0 failures.
RuboCop clean.
</details>

Co-authored-by: Clément Joubert <[email protected]>
czj added 6 commits November 19, 2026 15:46
LibreOffice writes /P<</MCID 0>>BDC with no space before the operator, which the imported page check let through. A blank info Title passed the PDF/UA title check.

Assisted-by: Claude Opus 5.5 [Claude Code]
…oad every box with Layout

The review of 860db65 found BDC missed before a delimiter (BDC[(a)]TJ) and Title: false accepted. Gamba::Layout loaded alone left Layout::Table undefined, which failed a roles test when it ran first (also on main).

Assisted-by: Claude Opus 5.5 [Claude Code]
… from layout

A title in ISO-8859-1 raised an encoding error, and titles or alts of only invisible characters passed. Gamba::Layout pointed at the document file broke requiring native/layout after gamba: layout.rb requires the table and the bands instead.

Assisted-by: Claude Opus 5.5 [Claude Code]
…read as binary

scrub turned invalid bytes into a visible replacement character, and a binary alt that converted to nothing was refused even in untagged documents.

Assisted-by: Claude Opus 5.5 [Claude Code]
…where given

524c772 checked a binary alt as UTF-8 but kept the bytes, which then failed to serialize in tagged documents.

Assisted-by: Claude Opus 5.5 [Claude Code]
@czj
czj enabled auto-merge (squash) November 19, 2026 16:33
@czj
czj merged commit 58407af into main Nov 19, 2026
14 checks passed
@czj
czj deleted the tagged-pdf branch November 19, 2026 16:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant