The man page is incomplete. It gives the SYNOPSIS as: qpdf [ options ] infilename [ outfilename ] But neglects to resolve the “[options]”. The last sentence says: For a summary of qpdf's options, please run qpdf --help. A complete manual can be found at https://qpdf.readthedocs.io. Any reference to *.readthedocs.io has moral, ethical and practical problems because: - Not everyone is online. Not everyone has Internet at home or wherever they use qpdf (I do not, for example). - Cloudflare is an access-restricted walled-garden that discriminates¹ against several demographics of people. - Documentation jailed in this way struggles to satisfy FSF’s Free Documentation licensing. ¹ Normally Cloudflare blocks me as well, but at the moment I am able to reach the page from a cafe. Running “qpdf --help” litters every page with a reference to Cloudflare Inc’s walled-garden. I was trying to work out whether qpdf could do the equivalent of “mutool clean -a“, so I ran: ===8<------------------------------ $ qpdf --help=transformation ===8<------------------------------ That page mentions: ===8<------------------------------ … --object-streams: control use of object streams … For detailed help, visit the qpdf manual: https://qpdf.readthedocs.io ===8<------------------------------ That’s exremely vague and in fact lacks the actual syntax. So even if the user knows what control they can expect to have, they have no hope of running the tool without knowing the syntax. People who are targetted for discrimination by Cloudflare are actually effectively blocked from using qpdf due to the documentation blockade. As well as offline people who cannot even attempt to access an URL. The man page and --help pages make no mention of /usr/share/doc/qpdf/README-doc.txt, which states: ===8<------------------------------ WHERE TO FIND THE QPDF DOCUMENTATION Complete documentation for qpdf can be found online here: https://qpdf.readthedocs.io Some distributions include offline documentation typically in a location such as /usr/share/doc/qpdf. If it isn't there, you can find a zip file containing the documentation in the qpdf release area: https://github.com/qpdf/qpdf/releases Offline documentation contains the following: * PDF: qpdf-manual.pdf * HTML: manual-html/index.html * SINGLE-PAGE HTML: manual-single-page-html/index.html If you are reading this file from the source distribution, you can find the documentation sources in the "manual" directory. There is information in the manual about how to build and package the documentation. ===8<------------------------------ MS Github also discriminates against some demographics of people. It’s interesting see from the above reference that there exists a PDF manual and an HTML manual which some online people may have access to. There is no “manual” directory in the Debian release. It’s very much needed because without it we don’t even have a way of seeing the basic syntax in any of the 3 doc locations (man pages, --help, and /usr/share/doc). I also do not find that info on the website. The Debian convention described in the Debian docs is to create a separate package (<pkg>-doc) for large detailed supplemental documentation. But in the case at hand, the missing PDF/HTML docs could not even be considered supplemental. They are in fact *essential* because the syntax is not otherwise available. So I believe those documents should be included directly in the qpdf package in this case. Ideally, all information exclusively held in *.readthedocs.io should be packaged so that references into that private walled-garden can be removed. Ideally.
I am not unsympathetic to the concerns you raise about GitHub CloudFlare discrimination, etc., but I am not going to do anything about it in the packaging of qpdf. The qpdf-doc package contains a fully offline version of the manual in HTML and PDF format, which you can read without going to readthedocs.io or github.com. I will include mention of the qpdf-doc package in the manual page for the debian package because I agree that that's a good idea. Regarding your comment that the qpdf-doc package is essential, the reason the doc package is separated as that a minimal distribution doesn't require docs. If you are, for example, building a container image that uses the qpdf CLI, you would not want to include the docs in the container. qpdf works correctly without the doc package installed, so it is not essential. Hopefully the 12.4.0 package I intend to upload momentarily will at least address the fact that the manual page is silent on the qpdf-doc package's existence. As for the rest, we'll have to pick our battles, and I'm not planning on moving away from github.com and readthedocs.io or changing things that benefit the majority of users.
We believe that the bug you reported is fixed in the latest version of
qpdf, which is due to be installed in the Debian FTP archive.
A summary of the changes between this version and the previous one is
attached.
Thank you for reporting the bug, which will now be closed. If you
have further comments please address them to 1111421@bugs.debian.org,
and the maintainer will reopen the bug report if appropriate.
Debian distribution maintenance software
pp.
Jay Berkenbilt <qjb@debian.org> (supplier of updated qpdf package)
(This message was generated automatically at their request; if you
believe that there is a problem with it please contact the archive
administrators by mailing ftpmaster@ftp-master.debian.org)
Format: 1.8
Date: Sun, 09 Aug 2026 16:49:00 -0400
Source: qpdf
Architecture: source
Version: 12.4.0-1
Distribution: unstable
Urgency: medium
Maintainer: Jay Berkenbilt <qjb@debian.org>
Changed-By: Jay Berkenbilt <qjb@debian.org>
Closes: 1111421 1127788
Changes:
qpdf (12.4.0-1) unstable; urgency=medium
.
* New upstream release.
* This version includes completely rewritten bash and zsh completion
files that no longer invoke the qpdf executable. (Closes: #1127788)
* Update the manual page to reference the qpdf-doc package.
(Closes: #1111421)
* Standards version updated to 4.7.4; no changes needed.
Checksums-Sha1:
890e676a18e1413572121558b13213fe579be160 2405 qpdf_12.4.0-1.dsc
829ce85b097a16711e75c6c2c896ecfc12e05d53 19675978 qpdf_12.4.0.orig.tar.gz
a32028b6aacf355c060d3e99747f296ce3d846dc 833 qpdf_12.4.0.orig.tar.gz.asc
4f80d6188eda8f8f1720e1fd0d7d9470ab89c944 15816 qpdf_12.4.0-1.debian.tar.xz
7a631f11963475d563bf2077d0008636ac3eb5c7 12287 qpdf_12.4.0-1_amd64.buildinfo
Checksums-Sha256:
2465054647850be91f0785a7150309ee92260674a5aee651fb973bbbaa32ffde 2405 qpdf_12.4.0-1.dsc
2783a032f443cc886dad41aa6d5fae3dabf23dec00ee7ec2cfb27ef67ebcf529 19675978 qpdf_12.4.0.orig.tar.gz
ed14b50cb88bb0bc490811ea647320d4e27db19e65dcb5e98dfe9593b9a14edc 833 qpdf_12.4.0.orig.tar.gz.asc
4dd8597dc78ec558d2880659c7e87d44fbff925ff9d4314c2a4a246d537fbcbf 15816 qpdf_12.4.0-1.debian.tar.xz
5316cd103e878118cb2f2af0b8c36f655a44e065135fabd7cafa360f09f3401a 12287 qpdf_12.4.0-1_amd64.buildinfo
Files:
dd2b07a702efb2deac2ec6355d95a4f5 2405 libs optional qpdf_12.4.0-1.dsc
d3156920305cafe5b554dcf36cf3cfe7 19675978 libs optional qpdf_12.4.0.orig.tar.gz
39706d25604677d2bec0125a22766e70 833 libs optional qpdf_12.4.0.orig.tar.gz.asc
9bad7d8429e8035a59abbb02bb70c40b 15816 libs optional qpdf_12.4.0-1.debian.tar.xz
d7070da49d424d3938e47214c7d34c4f 12287 libs optional qpdf_12.4.0-1_amd64.buildinfo
-----BEGIN PGP SIGNATURE-----
iQJDBAEBCgAtFiEEwslrEAEf4Anm0d+CinXRCZgBLH4FAmp46dsPHHFqYkBkZWJp
YW4ub3JnAAoJEIp10QmYASx+US8P/1rhOtXPmhzkpZkNg8VQh/P2FqAIs1jUxf/W
2A1/72smJGjGcLfzKk9KuAOlTbtrME1WGJDeAgv7aGq/bdfCIBgGeWliZM/IrH02
cmaH/3j37ksQLS8mcQfEksPmQd0BRZUx3/5YBi6swJR2dojS2cJ6tynslKdBoQH+
YUkyPs+x/1IB4s7bzkxQGtCLZIZqyPttlbz9IQkCd0QNqlsVS/47mP1VxmVEpVzy
wKVPU4L57+00bvWk0kA020qh3uitFtvi3dB7Ok0ln93xphBUQpT6sAqJnvjyt8j1
ffr/c46tfstnMek8tAM2TxOX0tLt4iMvcQoVRgGynO3xhf/0wzC2aqV6Q6i8/miR
+DcSeU5A9jhFWqYGOQ049JjHU8pPKDsgMCUSdyoI1aJhnbKwbNSOdFV4i/PZjBcc
757COSIdpK0AnztBUSaF6DwK+8IYWBVuhY2XOwIzGzYVCFTRgvGI/QeqDfuVUhlz
akFPbz338xZOlgGnkzizGP9va1cBpwpsXzCbn0TIg5MV5cSNFDE9DUILW1vjp8ox
lMhupN4/m+GQGZkG434PpDseXuJVYJvj36uqdFQQsFZpAqjWMJJJch504TjVJeI0
fFI6g/v+roQ4UVx8GQKrMV+coUvAYV1bpVbOWDFg7o5i4Lk35XM/KnB7k85dM2a7
kDxOU2ja
=4O6i
-----END PGP SIGNATURE-----