QpdfRuby

Patch & polish PDFs so that PAC 2024 finally turns green.

QpdfRuby is a very small Ruby wrapper around the battle‑tested QPDF >= 12 C++ library. Right now the library focuses on only three specialised tasks that are needed when PDFs are printed from Chromium‑based browsers and subsequently audited with the PAC 2024 accessibility checker:

1. Export the structure tree as XML – handy for debugging.
2. Mark vector path objects as /Artifact so that decorative lines, boxes, &c. are ignored by assistive technologies.
3. Add missing /BBox entries to every /Figure element (derived from the page’s graphic operators) so that screen readers know the physical extent of each image.

Together these tweaks eliminate the most common complaints PAC 2024 has about browser‑generated PDFs.

¹Internally the gem parses each page’s content stream, maps image /MCIDs to their transformation matrix, computes the bounding box (courtesy of a little linear algebra) and finally writes the result into the structure tree.

• Ruby >= 3.1
• QPDF >= 12.0.0 (headers & libs)

brew install qpdf
bundle config set --local build.qpdf_ruby "--with-qpdf-dir=$(brew --prefix qpdf)"

# on Debian 11/Ubuntu 20.04 you may need newer packages from testing
sudo apt-get update && sudo apt-get install -y libqpdf-dev qpdf

If apt cannot provide QPDF ≥ 12 you can compile it yourself or pull the package from testing/unstable – see the Dockerfile for a working apt preferences snippet.

bundle add qpdf_ruby
# …or without bundler:
# gem install qpdf_ruby -- --with-qpdf-include=/usr/local/include/qpdf --with-qpdf-lib=/usr/local/lib

require "qpdf_ruby"

pdf = QpdfRuby::Document.new("input.pdf")

# 1. tag decorative paths
pdf.mark_paths_as_artifacts

# 2. add BBox to every <Figure>
pdf.ensure_bbox

# 3. introspect structure tree (optional)
File.write("structure.xml", pdf.show_structure)

# 4. save 🎉
pdf.write("fixed.pdf")

Run PAC 2024 on fixed.pdf – it should report far fewer (or zero!) errors compared to the original browser output.

git clone https://github.com/dieter-medium/qpdf_ruby.git
cd qpdf_ruby
bin/setup        # install gem + test deps
autotest         # guard & RSpec

• Bump version.rb → bundle exec rake release to push a new gem.

If you tinker with QPDF itself, point Bundler to your custom prefix:

bundle config set --local build.qpdf_ruby "--with-qpdf-include=$HOME/opt/qpdf/include --with-qpdf-lib=$HOME/opt/qpdf/lib"

TBD

Bug reports & pull requests are welcome at https://github.com/dieter-medium/qpdf_ruby.

• C++ 17, clang‑format enforced
• Ruby 3.2, rubocop default rules

MIT – see LICENSE.txt for full text.