Stop recommending auto-download of DTD files, and indeed disable it.

It appears no longer possible to build the SGML docs without a local
installation of the DocBook DTD, because sourceforge.net now only
permits HTTPS access, and no common version of xsltproc supports that.
Hence, remove the bits of our documentation suggesting that that's
possible or useful.

In fact, we might as well add the --nonet option to the build recipes
automatically, for a bit of extra security.

Also fix our documentation-tool-installation recipes for macOS to
ensure that xmllint and xsltproc are pulled in from MacPorts or
Homebrew.  The previous recipes assumed you could use the
Apple-supplied versions of these tools; which still works, except that
you'd need to set an environment variable to ensure that they would
find DTD files provided by those package managers.  Simpler and easier
to just recommend pulling in the additional packages.

In HEAD, also document how to build docs using Meson, and adjust
"ninja docs" to just build the HTML docs, for consistency with the
default behavior of doc/src/sgml/Makefile.

In a fit of neatnik-ism, I also made the ordering of the package
lists match the order in which the tools are described at the head
of the appendix.

Aleksander Alekseev, Peter Eisentraut, Tom Lane

Discussion: https://postgr.es/m/CAJ7c6TO8Aro2nxg=EQsVGiSDe-TstP4EsSvDHd7DSRsP40PgGA@mail.gmail.com

4 files changed, 70 insertions, 36 deletions

diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index 4f0e39223c..b96c7cbf22 100644
--- a/doc/src/sgml/Makefile
+++ b/doc/src/sgml/Makefile
@@ -41,11 +41,15 @@ endif
 
 XMLINCLUDE = --path .
 
-ifndef XMLLINT
+ifdef XMLLINT
+XMLLINT := $(XMLLINT) --nonet
+else
 XMLLINT = $(missing) xmllint
 endif
 
-ifndef XSLTPROC
+ifdef XSLTPROC
+XSLTPROC := $(XSLTPROC) --nonet
+else
 XSLTPROC = $(missing) xsltproc
 endif
 
diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
index 787caef70d..35c4afc81a 100644
--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
@@ -136,6 +136,7 @@
      <listitem>
       <para>
        This is a program for converting, among other things, XML to PDF.
+       It is needed only if you want to build the documentation in PDF format.
       </para>
      </listitem>
     </varlistentry>
@@ -151,25 +152,13 @@
    here.
   </para>
 
-  <para>
-   You can get away with not installing DocBook XML and the DocBook XSLT
-   stylesheets locally, because the required files will be downloaded from the
-   Internet and cached locally.  This may in fact be the preferred solution if
-   your operating system packages provide only an old version of these files,
-   or if no packages are available at all.
-   If you want to prevent any attempt to access the Internet while building
-   the documentation, you need to pass the <option>--nonet</option> option
-   to <command>xmllint</command> and <command>xsltproc</command>; see below
-   for an example.
-  </para>
-
   <sect2 id="docguide-toolsets-inst-fedora-et-al">
    <title>Installation on Fedora, RHEL, and Derivatives</title>
 
    <para>
     To install the required packages, use:
 <programlisting>
-yum install docbook-dtds docbook-style-xsl fop libxslt
+yum install docbook-dtds docbook-style-xsl libxslt fop
 </programlisting>
    </para>
   </sect2>
@@ -180,7 +169,7 @@ yum install docbook-dtds docbook-style-xsl fop libxslt
    <para>
     To install the required packages with <command>pkg</command>, use:
 <programlisting>
-pkg install docbook-xml docbook-xsl fop libxslt
+pkg install docbook-xml docbook-xsl libxslt fop
 </programlisting>
    </para>
 
@@ -199,7 +188,7 @@ pkg install docbook-xml docbook-xsl fop libxslt
     available for <productname>Debian GNU/Linux</productname>.
     To install, simply use:
 <programlisting>
-apt-get install docbook-xml docbook-xsl fop libxml2-utils xsltproc
+apt-get install docbook-xml docbook-xsl libxml2-utils xsltproc fop
 </programlisting>
    </para>
   </sect2>
@@ -208,21 +197,37 @@ apt-get install docbook-xml docbook-xsl fop libxml2-utils xsltproc
    <title>macOS</title>
 
    <para>
-    On macOS, you can build the HTML and man documentation without installing
-    anything extra.  If you want to build PDFs or want to install a local copy
-    of DocBook, you can get those from your preferred package manager.
+    If you use MacPorts, the following will get you set up:
+<programlisting>
+sudo port install docbook-xml docbook-xsl-nons libxslt fop
+</programlisting>
+    If you use Homebrew, use this:
+<programlisting>
+brew install docbook docbook-xsl libxslt fop
+</programlisting>
    </para>
 
    <para>
-    If you use MacPorts, the following will get you set up:
+    The Homebrew-supplied programs require the following environment variable
+    to be set:
 <programlisting>
-sudo port install docbook-xml-4.5 docbook-xsl fop
+export XML_CATALOG_FILES=/usr/local/etc/xml/catalog
 </programlisting>
-    If you use Homebrew, use this:
+    Without it, <command>xsltproc</command> will throw errors like this:
 <programlisting>
-brew install docbook docbook-xsl fop
+I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd
+postgres.sgml:21: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
+...
 </programlisting>
    </para>
+
+   <para>
+    While it is possible to use the Apple-provided versions
+    of <command>xmllint</command> and <command>xsltproc</command>
+    instead of those from MacPorts or Homebrew, you'll still need
+    to install the DocBook DTD and stylesheets, and set up a catalog
+    file that points to them.
+   </para>
   </sect2>
 
   <sect2 id="docguide-toolsets-configure">
@@ -254,18 +259,19 @@ checking for dbtoepub... dbtoepub
 <screen>
 ./configure ... XMLLINT=/opt/local/bin/xmllint ...
 </screen>
-   Also, if you want to ensure that <filename>xmllint</filename>
-   and <filename>xsltproc</filename> will not perform any network access,
-   you can do something like
-<screen>
-./configure ... XMLLINT="xmllint --nonet" XSLTPROC="xsltproc --nonet" ...
-</screen>
+  </para>
+
+  <para>
+   If you prefer to build <productname>PostgreSQL</productname> using
+   Meson, instead run <command>meson setup</command> as described in
+   <xref linkend="install-meson"/>, and then see
+   <xref linkend="docguide-build-meson"/>.
   </para>
   </sect2>
  </sect1>
 
  <sect1 id="docguide-build">
-  <title>Building the Documentation</title>
+  <title>Building the Documentation with Make</title>
 
   <para>
    Once you have everything set up, change to the directory
@@ -410,6 +416,30 @@ ADDITIONAL_FLAGS='-Xmx1500m'
  </sect1>
 
 
+ <sect1 id="docguide-build-meson">
+  <title>Building the Documentation with Meson</title>
+
+   <para>
+    Two options are provided for building the documentation using Meson.
+    Change to the <filename>build</filename> directory before running
+    one of these commands, or add <option>-C build</option> to the command.
+   </para>
+
+   <para>
+    To build just the <acronym>HTML</acronym> version of the documentation:
+<screen>
+<prompt>build$ </prompt><userinput>ninja docs</userinput>
+</screen>
+    To build all forms of the documentation:
+<screen>
+<prompt>build$ </prompt><userinput>ninja alldocs</userinput>
+</screen>
+    The output appears in the
+    subdirectory <filename>build/doc/src/sgml</filename>.
+   </para>
+ </sect1>
+
+
  <sect1 id="docguide-authoring">
   <title>Documentation Authoring</title>
 
diff --git a/doc/src/sgml/images/Makefile b/doc/src/sgml/images/Makefile
index f9e356348b..645519095d 100644
--- a/doc/src/sgml/images/Makefile
+++ b/doc/src/sgml/images/Makefile
@@ -9,7 +9,7 @@ ALL_IMAGES = \
 
 DITAA = ditaa
 DOT = dot
-XSLTPROC = xsltproc
+XSLTPROC = xsltproc --nonet
 
 all: $(ALL_IMAGES)
 
diff --git a/doc/src/sgml/meson.build b/doc/src/sgml/meson.build
index b9f4c6a05b..38f1b8e7b1 100644
--- a/doc/src/sgml/meson.build
+++ b/doc/src/sgml/meson.build
@@ -87,7 +87,8 @@ postgres_full_xml = custom_target('postgres-full.xml',
   input: 'postgres.sgml',
   output: 'postgres-full.xml',
   depfile: 'postgres-full.xml.d',
-  command: [xmllint, '--noent', '--valid', '--path', '@OUTDIR@', '-o', '@OUTPUT@', '@INPUT@'],
+  command: [xmllint, '--nonet', '--noent', '--valid',
+            '--path', '@OUTDIR@', '-o', '@OUTPUT@', '@INPUT@'],
   depends: doc_generated,
   build_by_default: false,
 )
@@ -100,6 +101,7 @@ alldocs += postgres_full_xml
 #
 if xsltproc_bin.found()
   xsltproc_flags = [
+    '--nonet',
     '--stringparam', 'pg.version', pg_version,
     '--param', 'website.stylesheet', '1'
   ]
@@ -205,9 +207,7 @@ if xsltproc_bin.found()
     command: [xsltproc, '--path', '@OUTDIR@', '-o', '@OUTDIR@/', xsltproc_flags, '@INPUT@'],
     build_by_default: false,
   )
-
-  # build by default as part of docs target
-  docs += man
+  alldocs += man
 endif