Update documentation build/installation

6 files changed, 32 insertions, 36 deletions

diff --git a/manual/build.mk b/manual/build.mk
index 6d38bc3a..b07bf830 100644
--- a/manual/build.mk
+++ b/manual/build.mk
@@ -8,10 +8,10 @@ PDF_TARGET := $(PDF_OUT)/qpdf.pdf
 
 TARGETS_manual := doc/qpdf.1 doc/fix-qdf.1 doc/zlib-flate.1
 ifeq ($(BUILD_HTML),1)
-TARGETS_manual += doc/qpdf-manual.html $(HTML_TARGET)
+TARGETS_manual += $(HTML_TARGET) $(S_HTML_TARGET)
 endif
 ifeq ($(BUILD_PDF),1)
-TARGETS_manual += doc/qpdf-manual.pdf
+TARGETS_manual += $(PDF_TARGET)
 endif
 
 MANUAL_DEPS = $(wildcard manual/*.rst) manual/conf.py
@@ -22,33 +22,20 @@ 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
-
-# This depends on sphinx-build's singlehtml target creating index.html
-# and a _static directory. If that changes, this code has to be
-# adjusted. It will also be necessary to adjust the install target in
-# make/libtool.mk.
-doc/qpdf-manual.html: $(S_HTML_TARGET)
-	mkdir -p doc
-	@if [ "$(shell find $(S_HTML_OUT)/ -mindepth 1 -type d -print)" != \
-             "$(S_HTML_OUT)/_static" ]; then \
-	    echo "***"; \
-	    echo Expected only directory in $(S_HTML_OUT) to be _static; \
-	    echo "***"; \
-	    false; \
-	fi
-	cp $< $@
-	mkdir -p doc/_static
-	cp -p $(S_HTML_OUT)/_static/* doc/_static
-
-doc/qpdf-manual.pdf: $(PDF_TARGET)
 	mkdir -p doc
-	cp $< $@
+	cp $(PDF_TARGET) doc/qpdf-manual.pdf
 
 doc/%.1: manual/%.1.in
 	mkdir -p doc
diff --git a/manual/fix-qdf.1.in b/manual/fix-qdf.1.in
index b14f4304..dbc4c106 100644
--- a/manual/fix-qdf.1.in
+++ b/manual/fix-qdf.1.in
@@ -14,5 +14,5 @@ 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@/qpdf-manual.html or
+the qpdf manual, which can be found in @docdir@/html/index.html or
 @docdir@/qpdf-manual.pdf.
diff --git a/manual/installation.rst b/manual/installation.rst
index 8862034d..d7989e66 100644
--- a/manual/installation.rst
+++ b/manual/installation.rst
@@ -64,7 +64,7 @@ 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>`__. To build the PDF version of the
-documentation, you need `pdflatex`, `latexmk`, and a fairly complete
+documentation, you need ``pdflatex``, ``latexmk``, and a fairly complete
 LaTeX installation. Detailed requirements can be found in the Sphinx
 documentation.
 
diff --git a/manual/qpdf.1.in b/manual/qpdf.1.in
index 18c6f704..7d8112dd 100644
--- a/manual/qpdf.1.in
+++ b/manual/qpdf.1.in
@@ -16,4 +16,4 @@ 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@/qpdf-manual.html or @docdir@/qpdf-manual.pdf.
+@docdir@/html/index.html or @docdir@/qpdf-manual.pdf.
diff --git a/manual/release-notes.rst b/manual/release-notes.rst
index 5a8fd307..adb2a48d 100644
--- a/manual/release-notes.rst
+++ b/manual/release-notes.rst
@@ -7,6 +7,25 @@ For a detailed list of changes, please see the file
 :file:`ChangeLog` in the source distribution.
 
 10.5.0: XXX Month dd, YYYY
+  - 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.
+
+    - The documentation sources have been switched from docbook to
+      reStructuredText processed with `Sphinx
+      <https://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.
+
   - Library Enhancements
 
     - Since qpdf version 8, using object accessor methods on an
@@ -58,16 +77,6 @@ For a detailed list of changes, please see the file
 
     - Add ``qpdf_oh_get_type_code`` and ``qpdf_oh_get_type_name``.
 
-  - Documentation change
-
-    - The documentation sources have been switched from docbook to
-      reStructuredText processed with `Sphinx
-      <https://sphinx-doc.org>`__. This is mostly transparent (other
-      than format change) with the exception that all section links
-      have changed. What used to be `#ref.something` is now
-      `#something`. A top-to-bottom review of the documentation is
-      planned for an upcoming release.
-
 10.4.0: November 16, 2021
   - Handling of Weak Cryptography Algorithms
 
diff --git a/manual/zlib-flate.1.in b/manual/zlib-flate.1.in
index e74eb3f5..77349c36 100644
--- a/manual/zlib-flate.1.in
+++ b/manual/zlib-flate.1.in
@@ -21,6 +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@/qpdf-manual.html or @docdir@/qpdf-manual.pdf.
+in @docdir@/html/index.html or @docdir@/qpdf-manual.pdf.
 .SH "SEE ALSO"
 qpdf(1), gzip(1)