Update build-related documentation and comments

1 files changed, 39 insertions, 36 deletions

diff --git a/manual/packaging.rst b/manual/packaging.rst
index 6ff77e51..50f8fc60 100644
--- a/manual/packaging.rst
+++ b/manual/packaging.rst
@@ -9,6 +9,10 @@ chapter is for you. Otherwise, feel free to skip.
 Build Options
 -------------
 
+For a detailed discussion of build options, please refer to
+:ref:`build-options`. This section calls attention to options that are
+particularly useful to packagers.
+
 - 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.
@@ -16,31 +20,23 @@ Build Options
 - 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.
+- Use of ``SHOW_FAILED_TEST_OUTPUT`` is recommended for building in
+  continuous integration or other automated environments as it makes
+  it possible to see test failures in build logs. This should be
+  combined with either ``ctest --verbose`` or ``ctest
+  --output-on-failure``.
+
+- qpdf's install targets do not install completion files by default
+  since there is no standard location for them. 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. See the :file:`completions/README.md`
+  file for more information.
+
+- Starting with qpdf 11, qpdf's default installation installs source
+  files from the examples directory with documentation. Prior to qpdf
+  11, this was a recommendation for packagers but was not done
+  automatically.
 
 .. _packaging-doc:
 
@@ -54,27 +50,34 @@ 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.
+  installed in the documentation directory. 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
+  available from the qpdf release site do. You can find the pre-built
   documentation in the release area in the file
-  :file:`qpdf-{version}-doc.zip`.
+  :file:`qpdf-{version}-doc.zip`. For an example of this approach,
+  look at qpdf's GitHub actions build scripts. The
+  :file:`build-scripts/build-doc` script builds with
+  ``-DBUILD_DOC_DIST=1`` to create the documentation distribution. The
+  :file:`build-scripts/build-windows` script extracts it into the
+  build tree and builds with ``-DINSTALL_MANUAL=1`` to include it in
+  the installer.
 
 - **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.
+  sure to pass ``-DBUILD_DOC_DIST=1`` and ``-DINSTALL_MANUAL=1`` to
+  cmake. 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.
+
+.. _doc-packaging-rationale:
 
 Documentation Packaging Rationale
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~