Stop adding pre-built documentation to the source distribution

Jay Berkenbilt
1 parent e058247b
Showing 25 changed files with 250 additions and 163 deletions
.github/workflows/main.yml
.gitignore
ChangeLog
Makefile
README-doc.txt
README-maintainer
README-windows-install.txt
README.md
appimage/build-appimage
build-scripts/build-doc
build-scripts/build-linux
build-scripts/prebuild
make/installwin.mk
make/libtool.mk
make_dist
manual/README
manual/build.mk
manual/conf.py
manual/fix-qdf.1.in
manual/index.rst
@@ -21,14 +21,13 @@ on:
 jobs:
   Prebuild:
     # Run steps that are needed by the Windows build but are easier to
-    # build on Linux. Although only the Windows builds need this,
-    # other jobs depend on it to force it to run early.
+    # build on Linux. Also create the documentation distribution.
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
       - name: 'Run pre-build steps'
         run: build-scripts/prebuild
-      - name: 'Upload extra distribution files'
+      - name: 'Upload documentation for later build steps'
         uses: actions/upload-artifact@v1
         with:
           name: doc
@@ -38,6 +37,11 @@ jobs:
         with:
           name: external-libs
           path: external-libs-dist
+      - name: 'Upload doc distribution'
+        uses: actions/upload-artifact@v1
+        with:
+          name: distribution
+          path: distribution
   Linux:
     runs-on: ubuntu-latest
     steps:
@@ -5,8 +5,6 @@ autoconf.mk
 autom4te.cache/
 config.log
 config.status
-doc
-doc.zip
 examples/build/
 external-libs
 fuzz/build/
+2021-12-21  Jay Berkenbilt  <ejb@ql.org>
+
+	* Discontinue inclusion of the pre-built documentation in the
+	source distribution. Consult the packaging documentation in the
+	manual for details. The file README-doc.txt is installed in the
+	doc directory by default and contains information that users will
+	need to know to find the documentation.
+
 2021-12-19  Jay Berkenbilt  <ejb@ql.org>
  
 	* C API: clarify documentation around string lengths. Add two new
@@ -106,7 +106,6 @@ distclean: clean
  
 maintainer-clean: distclean
 	$(RM) -r install-mingw* install-msvc* external-libs
-	$(RM) -rf doc
  
 .PHONY: $(TEST_TARGETS)
  
+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: html/index.html
+* SINGLE-PAGE HTML: singlehtml/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.
@@ -4,10 +4,6 @@ ROUTINE DEVELOPMENT
  
 Default:
  
-./configure CXX="g++ --std=c++14" --enable-werror
-
-Doc:
-
 ./configure CXX="g++ --std=c++14" --enable-werror --enable-doc-maintenance
  
 Debugging:
@@ -363,13 +359,6 @@ rsync -vrlcO ./ jay_berkenbilt,qpdf@frs.sourceforge.net:/home/frs/project/q/qp/q
  
 OTHER NOTES
  
-To construct a source distribution from a pristine checkout,
-`make_dist` does the following:
-
-./configure --enable-doc-maintenance --enable-werror
-make build_manual
-make distclean
-
 For local iteration on the AppImage generation, it works to just
 ./build-scripts/build-appimage and get the resulting AppImage from
 the distribution directory. You can also pass -e SKIP_TESTS=1
@@ -6,6 +6,7 @@ have the bin directory in your path. To compile with qpdf, just add
 the lib directory to your library path and the include directory to
 your include path. If you are going to use Pl_DCT in your code, you
 will also need to have jpeg library development files in your build
-environment. Detailed documentation may be found in the doc directory.
+environment. Detailed documentation may be found in the doc directory
+and at https://qpdf.readthedocs.io.
  
 Enjoy!
@@ -67,10 +67,6 @@ Please see the section on crypto providers in the manual for more details.
  
 The PDF file format used to rely on RC4 for encryption. Using 256-bit keys always uses AES instead, and with 128-bit keys, you can elect to use AES. qpdf does its best to warn when someone is writing a file with weak cryptographic algorithms, but qpdf must always retain support for being able to read and even write files with weak encryption to be able to fully support older PDF files and older PDF readers.
  
-# Building from a pristine checkout
-
-When building qpdf from a pristine checkout from version control, generated HTML and PDF documentation files are not present. You don't need them unless you are going to run `make install` and want the documentation to be installed. If you want them, you can either extract the `doc` directory from a source distribution, or you can satisfy the additional requirements for building documentation and pass `--enable-doc-maintenance` to `./configure`.
-
 # Building from source distribution on UNIX/Linux
  
 For UNIX and UNIX-like systems, you can usually get by with just
@@ -81,7 +77,9 @@ make
 make install
 ```
  
-Packagers may set DESTDIR, in which case make install will install inside of DESTDIR, as is customary with many packages.  For more detailed general information, see the "INSTALL" file in this directory.  If you are already accustomed to building and installing software that uses autoconf, there's nothing new for you in the INSTALL file. Note that qpdf uses `autoconf` but not `automake`. We have our own system of Makefiles that allows cross-directory dependencies, doesn't use recursive make, and works better on non-UNIX platforms.
+Packagers may set DESTDIR, in which case make install will install inside of DESTDIR, as is customary with many packages.  Please also see the "Notes for Packagers" section of the manual.
+
+For more detailed general information, see the "INSTALL" file in this directory. If you are already accustomed to building and installing software that uses autoconf, there's nothing new for you in the INSTALL file. Note that qpdf uses `autoconf` but not `automake`. We have our own system of Makefiles that allows cross-directory dependencies, doesn't use recursive make, and works better on non-UNIX platforms.
  
 # Building without wchar_t
  
@@ -101,12 +99,14 @@ Note qpdf will never define QPDF_NO_WCHAR_T using autoconf or any other automate
  
 QPDF is known to build and pass its test suite with mingw (latest version tested: gcc 7.2.0), mingw64 (latest version tested: 7.2.0) and Microsoft Visual C++ 2015, both 32-bit and 64-bit versions.  MSYS2 is required to build as well in order to get make and other related tools.  See [README-windows.md](README-windows.md) for details on how to build under Windows.
  
+# Building Documentation
+
+The QPDF manual is written in reStructured Text format and is build with [sphinx](https://www.sphinx-doc.org). The sources to the user manual can be found in the `manual` directory. For more detailed information, consult the [Building and Installing QPDF section of the manual](manual/installation.rst) or consult the [build-doc script used in CI](build-scripts/build-doc).
+
 # Additional Notes on Build
  
 QPDF's build system can optionally use its own built-in rules rather than using libtool and obeying the compiler specified with configure.  This can be enabled by passing `--with-buildrules=buildrules` where buildrules corresponds to one of the `.mk` files (other than `rules.mk`) in the make directory. This should never be necessary on a UNIX system, but may be necessary on a Windows system.  See [README-windows.md](README-windows.md) for details.
  
-The QPDF package provides some executables and a software library.  A user manual can be found in the "doc" directory.  The sources to the user manual can be found in the `manual` directory.
-
 The software library is just `libqpdf`, and all the header files are in the `qpdf` subdirectories of `include` and `libqpdf`. If you link statically with `-lqpdf`, then you will also need to link with `-lz` and `-ljpeg`. The shared qpdf library is linked with `-lz` and `-ljpeg`, none of qpdf's public header files directly include files from `libz`, and only `Pl_DCT.hh` includes files from `libjpeg`, so for most cases, qpdf's development files are self contained. If you need to use `Pl_DCT` in your application code, you will need to have the header files for some libjpeg distribution in your include path.
  
 To learn about using the library, please read comments in the header files in `include/qpdf`, especially `QPDF.hh`, `QPDFObjectHandle.hh`, and
@@ -100,6 +100,7 @@ mkdir -p $appdir
  
 # Install build result into AppDir:
 make install DESTDIR=$appdir; find $appdir
+make doc-dist DOC_DEST=appdir/usr/share/doc/qpdf
  
 # Change into build directory:
 cd $here/build
+#!/bin/bash
+# The manual references this file.
+cd $(dirname $0)/..
+set -ex
+sudo apt-get update
+sudo apt-get -y install \
+   autoconf build-essential zlib1g-dev libjpeg-dev \
+   python3-pip texlive-latex-extra latexmk
+pip3 install sphinx sphinx_rtd_theme
+./configure --enable-doc-maintenance
+make -j$(nproc) doc-dist DOC_DEST=doc
+zip -r doc.zip doc
+version=$(egrep '^release' manual/conf.py | cut -d"'" -f 2)
+mv doc qpdf-${version}-doc
+mkdir distribution
+zip -r distribution/qpdf-${version}-doc.zip qpdf-${version}-doc
+sha256sum distribution/*
@@ -3,10 +3,8 @@ set -ex
 sudo apt-get update
 sudo apt-get -y install \
    autoconf build-essential zlib1g-dev libjpeg-dev libgnutls28-dev \
-   libssl-dev python3-pip texlive-latex-extra latexmk \
-   inkscape imagemagick libtiff-tools ghostscript
-pip3 install sphinx sphinx_rtd_theme
-./configure --enable-werror --enable-doc-maintenance \
+   libssl-dev libtiff-tools ghostscript
+./configure --enable-werror \
     --enable-crypto-native --enable-crypto-openssl --enable-crypto-gnutls \
     --enable-show-failed-test-output --enable-test-compare-images
 make -j$(nproc) -k
@@ -16,7 +14,7 @@ for i in $(./qpdf/build/qpdf --show-crypto); do
 done
 export TMPDIR=$PWD/dist-tmp
 rm -rf $TMPDIR
-./make_dist --ci --no-tests
+./make_dist --ci
 mkdir distribution
 cp $TMPDIR/qpdf*-ci.tar.gz distribution
 sha256sum distribution/*
 #!/bin/bash
 cd $(dirname $0)/..
-set -ex
-sudo apt-get update
-sudo apt-get -y install \
-   autoconf build-essential zlib1g-dev libjpeg-dev \
-   python3-pip texlive-latex-extra latexmk inkscape imagemagick
-pip3 install sphinx sphinx_rtd_theme
-./configure --enable-doc-maintenance
-make -j$(nproc) build_manual
-zip -r doc.zip doc/*html doc/*.pdf
+build-scripts/build-doc
 build-scripts/download-external-libs
@@ -8,7 +8,6 @@ installwin: all
 	mkdir $(DEST)/lib
 	mkdir $(DEST)/include
 	mkdir $(DEST)/include/qpdf
-	mkdir $(DEST)/doc
 	cp libqpdf/$(OUTPUT_DIR)/$(IMPORT_LIB_NAME) $(DEST)/lib
 	cp libqpdf/$(OUTPUT_DIR)/qpdf*.dll $(DEST)/bin
 	perl copy_dlls libqpdf/$(OUTPUT_DIR)/qpdf*.dll $(DEST)/bin $(OBJDUMP) $(WINDOWS_WORDSIZE)
@@ -17,12 +16,6 @@ installwin: all
 	cp qpdf/$(OUTPUT_DIR)/fix-qdf.exe $(DEST)/bin
 	cp include/qpdf/*.h $(DEST)/include/qpdf
 	cp include/qpdf/*.hh $(DEST)/include/qpdf
-	if [ -f doc/qpdf-manual.pdf ]; then \
-	    cp doc/qpdf-manual.pdf $(DEST)/doc; \
-	fi
-	if [ -d doc/html ]; then \
-	    cp -r doc/html $(DEST)/doc; \
-	fi
-	if [ -d doc/singlehtml ]; then \
-	    cp -r doc/singlehtml $(DEST)/doc; \
+	if [ -d doc ]; then \
+	    cp -r doc $(DEST); \
 	fi
@@ -137,13 +137,5 @@ install: all install-libs
 	$(LIBTOOL) --mode=install ./install-sh \
 		qpdf/$(OUTPUT_DIR)/fix-qdf \
 		$(DESTDIR)$(bindir)/fix-qdf
-	if [ -f doc/qpdf-manual.pdf ]; then \
-		./install-sh -m 0644 doc/qpdf-manual.pdf $(DESTDIR)$(docdir); \
-	fi
-	if [ -d doc/html ]; then \
-		cp -r doc/html $(DESTDIR)/$(docdir); \
-	fi
-	if [ -d doc/singlehtml ]; then \
-		cp -r doc/singlehtml $(DESTDIR)/$(docdir); \
-	fi
-	./install-sh -m 0644 doc/*.1 $(DESTDIR)$(mandir)/man1
+	./install-sh -m 0644 README-doc.txt $(DESTDIR)$(docdir); \
+	./install-sh -m 0644 manual/$(OUTPUT_DIR)/*.1 $(DESTDIR)$(mandir)/man1
 #!/usr/bin/env perl
 #
 # This program creates a source distribution of qpdf.  For details,
-# see README-maintainer.md.
+# see README-maintainer.
 #
  
 require 5.008;
@@ -16,7 +16,6 @@ use File::Path qw(rmtree make_path);
 my $whoami = basename($0);
  
 my $tmp = $ENV{'TMPDIR'} || '/tmp';
-my $run_tests = 1;
 my $keep_tmp = 0;
 my $ci_mode = 0;
 my $version = undef;
@@ -24,7 +23,7 @@ foreach my $arg (@ARGV)
 {
     if ($arg eq '--no-tests')
     {
-	$run_tests = 0;
+        # ignore for compatibility
     }
     elsif ($arg eq '--keep-tmp')
     {
@@ -93,19 +92,8 @@ if ($version_error)
     die "$whoami: version numbers are not consistent\n";
 }
  
-run("./configure --disable-shared --enable-doc-maintenance --enable-werror");
-run("make -j8 build_manual");
-run("make distclean");
 cd($tmp);
 run("tar czvf $distname.tar.gz-candidate $distname");
-if ($run_tests)
-{
-    cd($tmpdir);
-    run("./configure");
-    run("make -j8");
-    run("make check");
-    cd($tmp);
-}
 my $distfile = ($ci_mode ? "$distname-ci.tar.gz" : "$distname.tar.gz");
 rename "$distname.tar.gz-candidate", $distfile or die;
  
-This directory contains sources to the documentation.  If you are
-looking for pre-built documentation, please look in the "doc"
-directory.
@@ -6,7 +6,10 @@ HTML_TARGET := $(HTML_OUT)/index.html
 PDF_OUT := $(DOC_OUT)/latex
 PDF_TARGET := $(PDF_OUT)/qpdf.pdf
  
-TARGETS_manual := doc/qpdf.1 doc/fix-qdf.1 doc/zlib-flate.1
+TARGETS_manual := \
+    $(DOC_OUT)/qpdf.1 \
+    $(DOC_OUT)/fix-qdf.1 \
+    $(DOC_OUT)/zlib-flate.1
 ifeq ($(BUILD_HTML),1)
 TARGETS_manual += $(HTML_TARGET) $(S_HTML_TARGET)
 endif
@@ -22,23 +25,31 @@ MANUAL_DEPS = $(wildcard manual/*.rst) manual/conf.py
 # the error "_pickle.UnpicklingError: pickle data was truncated"
 $(HTML_TARGET): $(MANUAL_DEPS)
 	$(SPHINX) -M html manual $(DOC_OUT) -W
-	mkdir -p doc
-	rm -rf doc/html
-	cp -r $(DOC_OUT)/html doc
  
 $(S_HTML_TARGET): $(MANUAL_DEPS) | $(HTML_TARGET)
 	$(SPHINX) -M singlehtml manual $(DOC_OUT) -W
-	mkdir -p doc
-	rm -rf doc/singlehtml
-	cp -r $(DOC_OUT)/singlehtml doc
  
 $(PDF_TARGET): $(MANUAL_DEPS) | $(S_HTML_TARGET) $(HTML_TARGET)
 	$(SPHINX) -M latexpdf manual $(DOC_OUT) -W
-	mkdir -p doc
-	cp $(PDF_TARGET) doc/qpdf-manual.pdf
  
-doc/%.1: manual/%.1.in
-	mkdir -p doc
-	sed -e 's:@PACKAGE_VERSION@:$(PACKAGE_VERSION):g' \
-	    -e 's:@docdir@:$(docdir):g' \
-	    < $< > $@
+$(DOC_OUT)/%.1: manual/%.1.in
+	sed -e 's:@PACKAGE_VERSION@:$(PACKAGE_VERSION):g' < $< > $@
+
+# The doc-dist target must not removed $(DOC_DEST) so that it works to
+# do stuff like make doc-dist DOC_DEST=$(DESTDIR)/$(docdir). Make sure
+# what this does is consistent with ../README-doc.txt and the
+# information in the manual and ../README.md.
+.PHONY: doc-dist
+doc-dist: build_manual
+	@if test x"$(DOC_DEST)" = x; then \
+	    echo DOC_DEST must be set 1>& 2; \
+	    false; \
+	fi
+	if test -d $(DOC_DEST); then \
+	    $(RM) -rf $(DOC_DEST)/*html $(DOC_DEST)/*.pdf; \
+	else \
+	    mkdir -p $(DOC_DEST); \
+	fi
+	cp -r $(DOC_OUT)/html doc
+	cp -r $(DOC_OUT)/singlehtml doc
+	cp $(PDF_TARGET) $(DOC_DEST)/qpdf-manual.pdf
@@ -11,6 +11,7 @@ import sphinx_rtd_theme  # noQA F401
 project = 'QPDF'
 copyright = '2005-2021, Jay Berkenbilt'
 author = 'Jay Berkenbilt'
+# make_dist and the CI build lexically find the release version from this file.
 release = '10.5.0'
 version = release
 extensions = [
@@ -14,8 +14,6 @@ the same file with stream lengths, cross-reference table entries, and
 object stream offset tables regenerated.
 .PP
 For details about fix-qdf and about PDF files in QDF mode, please see
-the qpdf manual, which can be found in @docdir@/html/index.html or
-@docdir@/qpdf-manual.pdf. The latest version of the documentation can
-be found at https://qpdf.readthedocs.io.
+the qpdf manual, which can be found at https://qpdf.readthedocs.io.
 .SH "SEE ALSO"
 qpdf(1)
@@ -21,6 +21,7 @@ documentation, please visit `https://qpdf.readthedocs.io
    license
    download
    installation
+   packaging
    cli
    qdf
    library
@@ -60,14 +60,7 @@ suite. Note that in no case are these items required to use qpdf.
 If you do not enable this, then you do not need to have tiff and
 ghostscript.
  
-Pre-built documentation is distributed with qpdf, so you should
-generally not need to rebuild the documentation. In order to build the
-documentation from source, you need to install `Sphinx
-<https://sphinx-doc.org>`__ along with the ``sphinx_rtd_doc`` theme
-(``pip install sphinx sphinx_rtd_theme``). To build the PDF version of
-the documentation, you need ``pdflatex``, ``latexmk``, and a fairly
-complete LaTeX installation. Detailed requirements can be found in the
-Sphinx documentation.
+For information on building the documentation, see :ref:`build-doc`.
  
 .. _building:
  
@@ -113,6 +106,23 @@ hand-crafted non-recursive Makefile that requires gnu make. If you&#39;re
 really interested, please read the comments in the top-level
 :file:`Makefile`.
  
+.. _build-doc:
+
+Building Documentation
+----------------------
+
+The qpdf manual is written in reStructured Text and built with `Sphinx
+<https://www.sphinx-doc.org>`__ using the `Read the Docs Sphinx Theme
+<https://sphinx-rtd-theme.readthedocs.io>`__. In order to build the
+HTML documentation from source, you need to install sphinx and the
+theme, which you can typically do with ``pip install sphinx
+sphinx_rtd_theme``. To build the PDF version of the documentation, you
+need ``pdflatex``, ``latexmk``, and a fairly complete LaTeX
+installation. Detailed requirements can be found in the Sphinx
+documentation. To see how the documentation is built for the qpdf
+distribution, refer to the :file:`build-scripts/build-doc` file in the
+qpdf source distribution.
+
 .. _crypto:
  
 Crypto Providers
@@ -298,46 +308,3 @@ provide their own implementations for basic filters like
 Implementing the registration functions and internal storage of
 registered providers was also easier using C++-11's functional
 interfaces, which was another reason to require C++-11 at this time.
-
-.. _packaging:
-
-Notes for Packagers
--------------------
-
-If you are packaging qpdf for an operating system distribution, here are
-some things you may want to keep in mind:
-
-- Starting in qpdf version 9.1.1, qpdf no longer has a runtime
-  dependency on perl. This is because fix-qdf was rewritten in C++.
-  However, qpdf still has a build-time dependency on perl.
-
-- 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:
+
+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.
@@ -15,6 +15,4 @@ options for inspecting or checking PDF files, some of which are
 useful primarily to PDF developers.
 .PP
 For a summary of qpdf's options, please run \fBqpdf \-\-help\fR. A
-complete manual can be found in @docdir@/html/index.html or
-@docdir@/qpdf-manual.pdf. The latest version of the documentation can
-be found at https://qpdf.readthedocs.io.
+complete manual can be found at https://qpdf.readthedocs.io.
@@ -6,29 +6,25 @@ Release Notes
 For a detailed list of changes, please see the file
 :file:`ChangeLog` in the source distribution.
  
-10.5.0: December 20, 2021
+10.5.0: December 21, 2021
   - Packaging changes
  
-    - The structure of the ``doc`` directory is different. The PDF
-      documentation is in the same place, but the files for the
-      previous HTML documentation are no longer there. Instead, there
-      are ``html`` and ``singlehtml`` directories, each of which
-      contain ``index.html`` and other files and directories. The
-      distribution files and ``make install`` target handle this, but
-      if you are building your own packages and including
-      documentation, please double check to make sure that you are
-      including the right documentation files.
+    - Pre-built documentation is no longer distributed with the source
+      distribution. The AppImage and Windows binary distributions
+      still contain embedded documentation, and a separate ``doc``
+      distribution file is available from the qpdf release site.
+      Documentation is now available at `https://qpdf.readthedocs.io
+      <https://qpdf.readthedocs.io>`__ for every major/minor version
+      starting with version 10.5. Please see :ref:`packaging-doc` for
+      details on how packagers should handle documentation.
  
     - The documentation sources have been switched from docbook to
       reStructuredText processed with `Sphinx
-      <https://sphinx-doc.org>`__. This will break previous
+      <https://www.sphinx-doc.org>`__. This will break previous
       documentation links. A redirect is in place on the main website.
       A top-to-bottom review of the documentation is planned for an
       upcoming release.
  
-    - Documentation is now available at `https://qpdf.readthedocs.io
-      <https://qpdf.readthedocs.io>`__.
-
   - Library Enhancements
  
     - Since qpdf version 8, using object accessor methods on an
@@ -21,8 +21,6 @@ This program should not be used as a general purpose compression
 tool.  Use something like gzip(1) instead.
 .PP
 For details about qpdf, please see the qpdf manual, which can be found
-in @docdir@/html/index.html or @docdir@/qpdf-manual.pdf. The latest
-version of the documentation can be found at
-https://qpdf.readthedocs.io.
+at https://qpdf.readthedocs.io.
 .SH "SEE ALSO"
 qpdf(1), gzip(1)