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.