Stop adding pre-built documentation to the source distribution

1 files changed, 120 insertions, 0 deletions

diff --git a/manual/packaging.rst b/manual/packaging.rst
new file mode 100644
index 00000000..6ff77e51
--- /dev/null
+++ b/manual/packaging.rst
@@ -0,0 +1,120 @@
+.. _packaging:
+
+Notes for Packagers
+===================
+
+If you are packaging qpdf for an operating system distribution, this
+chapter is for you. Otherwise, feel free to skip.
+
+Build Options
+-------------
+
+- Perl must be present at build time. Prior to qpdf version 9.1.1,
+  there was a runtime dependency on perl, but this is no longer the
+  case.
+
+- Make sure you are getting the intended behavior with regard to crypto
+  providers. Read :ref:`crypto.build` for details.
+
+- Passing :samp:`--enable-show-failed-test-output` to
+  :command:`./configure` will cause any failed test
+  output to be written to the console. This can be very useful for
+  seeing test failures generated by autobuilders where you can't access
+  qtest.log after the fact.
+
+- If qpdf's build environment detects the presence of autoconf and
+  related tools, it will check to ensure that automatically generated
+  files are up-to-date with recorded checksums and fail if it detects a
+  discrepancy. This feature is intended to prevent you from
+  accidentally forgetting to regenerate automatic files after modifying
+  their sources. If your packaging environment automatically refreshes
+  automatic files, it can cause this check to fail. Suppress qpdf's
+  checks by passing :samp:`--disable-check-autofiles`
+  to :command:`/.configure`. This is safe since qpdf's
+  :command:`autogen.sh` just runs autotools in the
+  normal way.
+
+- QPDF's :command:`make install` does not install completion files by
+  default, but as a packager, it's good if you install them wherever
+  your distribution expects such files to go. You can find completion
+  files to install in the :file:`completions` directory.
+
+- Packagers are encouraged to install the source files from the
+  :file:`examples` directory along with qpdf development packages.
+
+.. _packaging-doc:
+
+Packaging Documentation
+-----------------------
+
+Starting in qpdf version 10.5, pre-built documentation is no longer
+distributed with the qpdf source distribution. Here are a few options
+you may want to consider for your packages:
+
+- **Do nothing**
+
+  When you run ``make install``, the file :file:`README-doc.txt` is
+  installed in ``$(docdir)``. That file tells the reader where to find
+  the documentation online and where to go to download offline copies
+  of the documentation. This is the option selected by the debian
+  packages.
+
+- **Embed pre-built documentation**
+
+  You can obtain pre-built documentation and extract its contents into
+  your distribution. This is what the Windows binary distributions
+  available from the qpdf release site do. You can find the pre-build
+  documentation in the release area in the file
+  :file:`qpdf-{version}-doc.zip`.
+
+- **Build the documentation yourself**
+
+  You can build the documentation as part of your build process. Be
+  sure to pass ``--enable-doc-maintenance`` to ``./configure``, and
+  install it with ``make doc-dist DOC_DEST=...``. This is what the
+  AppImage build does. The latest version of Sphinx at the time of the
+  initial conversion a sphinx-based documentation was 4.3.2. Older
+  versions are not guaranteed to work.
+
+Documentation Packaging Rationale
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section describes the reason for things being the way they are.
+It's for information only; you don't have to know any of this to
+package qpdf.
+
+What is the reason for this change? Prior to qpdf 10.5, the qpdf
+manual was a docbook XML file. The generated documents were the
+product of running the file through build-time style sheets and
+contained no copyrighted material of their own. Starting with version
+10.5, the manual is written produced with `Sphinx
+<https://www.sphinx-doc.org>`__. This change was made to make it much
+easier to automatically generate portions of the documentation and to
+make the documentation easier to work with. The HTML output of Sphinx
+is also much more readable, usable, and suitable for online
+consumption than the output of the docbook style sheets. The downsides
+are that the generated HTML documentation now contains Javascript code
+and embedded fonts, and the PDF version of the documentation is no
+longer as suitable for printing (at least as of the 10.5 distribution)
+since external link targets are no longer shown and cross references
+no longer contain page number information. The presence of copyrighted
+material in the generated documentation, even though things are
+licensed with MIT and BSD licenses, complicates the job of the
+packager in various ways. For one thing, it means the
+:file:`NOTICE.md` file in the source repository would have to keep up
+with the copyright information for files that are not controlled in
+the repository. Additionally, some distributions (notably
+Debian/Ubuntu) discourage inclusion of sphinx-generated documentation
+in packages, preferring you instead to build the documentation as part
+of the package build process and to depend at runtime on a shared
+package that contains the code. At the time of the conversion of the
+qpdf manual from docbook to sphinx, newer versions of both sphinx and
+the html theme were required than were available in some of most of
+the Debian/Ubuntu versions for which qpdf was packaged.
+
+Since always-on Internet connectivity is much more common than it used
+to be, many users of qpdf would prefer to consume the documentation
+online anyway, and the lack of pre-built documentation in the
+distribution won't be as big of a deal. However there are still some
+people who can't or choose not to view documentation online. For them,
+pre-built documentation is still available.