Print PDF link URLs next to their text when supported #15

[diegocostares]

Related issues

Implements #15.

Problem

pdftotext — and therefore this gem — extracts only the visible text of a PDF. The URLs behind links live in the document's link annotations, not in the text stream, so they never make it into the output. Recovering them meant reaching for a second tool (pdfinfo -url), a second output format, and losing the association between a URL and the text that links to it.

What this does

poppler 26.09.0 added pdftotext -urls, which prints each link's URL next to its link text, e.g. link text [https://example.com/]. This PR wires that into PdfHandler:

• When the configured pdftotext supports -urls, it is passed automatically, so link URLs are part of the extracted text out of the box. Support is probed once per binary (pdftotext -h) and cached.
• Binaries that predate the option are detected and left untouched, so extraction keeps working unchanged on poppler < 26.09.0 — including the poppler-utils currently on ubuntu-latest in CI.
• pdftotext_urls: false opts out; pdftotext_urls: true forces the flag on for a binary that is not auto-detected (that binary must actually support it, otherwise pdftotext errors out and no text is extracted).
• -urls is skipped for a command that already carries it, or that uses a mode pdftotext rejects it with (-bbox, -bbox-layout, -tsv, -htmlmeta) — those exit non-zero and would silently yield empty text. A configured command without the __FILE__ placeholder no longer raises while the handler is built.

Default behaviour of every other handler is unchanged.

How to test

Unit specs cover the command assembly without needing poppler (they stub the capability probe), so they run in CI regardless of the installed version:

bundle exec rspec spec/lib/file_handler/external_command_handler/pdf_handler_spec.rb

They assert -urls is added by default when supported, omitted with pdftotext_urls: false, forced with true, skipped for incompatible/duplicate commands, and that a command without __FILE__ does not raise.

With poppler >= 26.09.0 installed, an integration example additionally extracts the fixture spec/fixtures/files/text-with-url.pdf (a link over the word "website") and asserts the URL is appended. On older poppler that one example is skipped, so the suite stays green there too.

Manual check:

pdftotext -enc UTF-8 -urls spec/fixtures/files/text-with-url.pdf -
# => ... Visit our website today [https://example.com/]

Open question

I made it on-by-default when the binary supports it, since the URL belongs with the text it annotates. This does mean the extracted text of a given PDF can change when the OS pdftotext is upgraded across the 26.09.0 boundary, without the gem itself changing — I noted it in the CHANGELOG as a behaviour change. If you'd rather keep it strictly opt-in (off unless pdftotext_urls: true), that's a one-line change in `urls_wanted?`; happy to flip it.

[jkraemer]

Thank you for this, however I'd rather not add a toggle for this. Overriding the pdftotext: array in
plaintext.yml is exactly what that file is for, and it already gets you there:

pdftotext:
  - /usr/bin/pdftotext
  - -enc
  - UTF-8
  - -urls
  - __FILE__
  - '-'

Repeating the binary path and -enc UTF-8 is the same thing every override
requires today (see the Mac section of the README). A per-flag boolean next to the
command arrays would be a second configuration mechanism for the same thing.