From 561a83a29182b00bda9237ae30343d76a68dcdf4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20K=C4=99pie=C5=84?= Date: Thu, 12 Oct 2023 14:24:42 +0200 Subject: [PATCH] Remove PDF-related bits from the build system Read the Docs is capable of building the PDF version of the BIND 9 ARM using just the contents of the doc/arm/ directory - it does not need the build system to facilitate that. Since the BIND 9 ARM is also built in other formats when "make doc" is run, drop the parts of the build system that enable building the PDF version as they pull in complexity without bringing much added value in return. Update related files accordingly. --- .gitlab-ci.yml | 2 -- .gitlab/issue_templates/Release.md | 2 +- CONTRIBUTING.md | 2 +- Makefile.docs | 3 --- README.md | 11 ++++++++++- configure.ac | 4 ---- doc/arm/.gitattributes | 7 ------- doc/arm/Makefile.am | 12 +----------- 8 files changed, 13 insertions(+), 30 deletions(-) delete mode 100644 doc/arm/.gitattributes diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 33c1578de1..105fb6e3f1 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -497,7 +497,6 @@ cross-version-config-tests: script: - *configure - make -j${BUILD_PARALLEL_JOBS:-1} -k doc V=1 - - qpdf --check doc/arm/_build/latex/Bv9ARM.pdf - find doc/man/ -maxdepth 1 -name "*.[0-9]" -exec mandoc -T lint "{}" \; | ( ! grep -v -e "skipping paragraph macro. sp after" -e "unknown font, skipping request. ft C" -e "input text line longer than 80 bytes" ) .respdiff: &respdiff_job @@ -1364,7 +1363,6 @@ release: - mv "${BIND_DIRECTORY}"/{CHANGES*,COPYRIGHT,LICENSE,README.md,srcid} . - rm -rf "${BIND_DIRECTORY}" - mv "../doc/arm/_build/html" doc/arm/ - - mv "../doc/arm/_build/latex/Bv9ARM.pdf" doc/arm/ - mv "../doc/arm/_build/epub/Bv9ARM.epub" doc/arm/ - echo 'Redirect' > "RELEASE-NOTES-${BIND_DIRECTORY}.html" - popd diff --git a/.gitlab/issue_templates/Release.md b/.gitlab/issue_templates/Release.md index 82d635e70d..9aee063af4 100644 --- a/.gitlab/issue_templates/Release.md +++ b/.gitlab/issue_templates/Release.md @@ -52,7 +52,7 @@ ### Before the ASN Deadline (for ASN Releases) or the Public Release Date (for Regular Releases) - - [ ] ***(QA)*** Check that the formatting is correct for HTML and PDF versions of release notes. + - [ ] ***(QA)*** Check that the formatting is correct for the HTML version of release notes. - [ ] ***(QA)*** Check that the formatting of the generated man pages is correct. - [ ] ***(QA)*** Verify GitLab CI results [for the tags](https://gitlab.isc.org/isc-private/bind9/-/pipelines?scope=tags) created and sign off on the releases to be published. - [ ] ***(QA)*** Update GitLab settings for all maintained branches to allow merging to them again: [public](https://gitlab.isc.org/isc-projects/bind9/-/settings/repository), [private](https://gitlab.isc.org/isc-private/bind9/-/settings/repository) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c108dbeec6..a013c4ea73 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -173,7 +173,7 @@ of documentation in the BIND source tree: they document, in files ending in `.rst`: for example, the `named` man page is `bin/named/named.rst`. * The *BIND 9 Administrator Reference Manual* is in the .rst files in - `doc/arm/`; the PDF and HTML versions are automatically generated from + `doc/arm/`; the HTML version is automatically generated from the `.rst` files. * API documentation is in the header file describing the API, in Doxygen-formatted comments. diff --git a/Makefile.docs b/Makefile.docs index 674f51d2fc..a205c5efc7 100644 --- a/Makefile.docs +++ b/Makefile.docs @@ -25,11 +25,8 @@ common_SPHINXOPTS = \ -a \ $(SPHINX_V) -# The "today" variable set below is not directly used in the ARM, but its value -# is implicitly inserted on the title page of the PDF file produced by Sphinx. ALLSPHINXOPTS = \ $(common_SPHINXOPTS) \ - -D today="$(RELEASE_DATE)" \ -D rst_epilog="$$(printf "$${RST_EPILOG}")" \ $(SPHINXOPTS) \ $(srcdir) diff --git a/README.md b/README.md index ad2b29bbc8..e05a114862 100644 --- a/README.md +++ b/README.md @@ -141,9 +141,18 @@ parallel test driver; unit tests are also run by `make check`. The *BIND 9 Administrator Reference Manual* (ARM) is included with the source distribution, and in .rst format, in the `doc/arm` -directory. HTML and PDF versions are automatically generated and can +directory. The HTML version is automatically generated and can be viewed at [https://bind9.readthedocs.io/en/latest/index.html](https://bind9.readthedocs.io/en/latest/index.html). +The PDF version can be built by running: + + cd doc/arm/ + sphinx-build -b latex . pdf/ + make -C pdf/ all-pdf + +The above requires TeX Live in order to work. The PDF will be written to +`doc/arm/pdf/Bv9ARM.pdf`. + Man pages for some of the programs in the BIND 9 distribution are also included in the BIND ARM. diff --git a/configure.ac b/configure.ac index e6d286c161..cce13b499f 100644 --- a/configure.ac +++ b/configure.ac @@ -1271,10 +1271,6 @@ AC_ARG_VAR([SPHINX_BUILD], [path to sphinx-build binary used to build the docume AC_PATH_PROG([SPHINX_BUILD], [sphinx-build], []) AM_CONDITIONAL([HAVE_SPHINX_BUILD], [test -n "$SPHINX_BUILD"]) -AC_PATH_PROG([XELATEX], [xelatex], []) -AC_PATH_PROG([LATEXMK], [latexmk], []) -AM_CONDITIONAL([HAVE_XELATEX], [test -n "$XELATEX" && test -n "$LATEXMK"]) - # # Build the man pages only if we have prebuilt manpages or we can build them from RST sources # diff --git a/doc/arm/.gitattributes b/doc/arm/.gitattributes deleted file mode 100644 index 967c07a8e2..0000000000 --- a/doc/arm/.gitattributes +++ /dev/null @@ -1,7 +0,0 @@ - -Bv9ARM.ch* -diff -merge -Bv9ARM.pdf -diff -merge -Bv9ARM.xml text -Bv9ARM.conf text - -*.xml auto=text diff --git a/doc/arm/Makefile.am b/doc/arm/Makefile.am index 5c53d56634..bef634a4ac 100644 --- a/doc/arm/Makefile.am +++ b/doc/arm/Makefile.am @@ -102,17 +102,7 @@ install-epub: $(INSTALL) -d $(DESTDIR)/$(docdir) $(INSTALL_DATA) $(SPHINXBUILDDIR)/epub/*.epub $(DESTDIR)/$(docdir)/ -if HAVE_XELATEX -pdf-local: - $(AM_V_SPHINX)$(SPHINX_BUILD) -b latex -d $(SPHINXBUILDDIR)/.doctrees/latex $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/latex - $(MAKE) -C $(SPHINXBUILDDIR)/latex all-pdf - -install-pdf-local: - $(INSTALL) -d $(DESTDIR)/$(docdir) - $(INSTALL_DATA) $(SPHINXBUILDDIR)/latex/*.pdf $(DESTDIR)/$(docdir)/ -endif - clean-local: -rm -rf $(SPHINXBUILDDIR) -doc-local: html singlehtml pdf epub +doc-local: html singlehtml epub