Re: MacOS: xsltproc fails with "warning: failed to load external entity" - Mailing list pgsql-hackers

I wrote:
> It's worse than that: I find that
>     export XML_CATALOG_FILES=/dev/null
> breaks the docs build on RHEL8 and Fedora 37 (latest) too, with the
> same "failed to load external entity" symptom.  I conclude from this
> that there is no version of xsltproc anywhere that can still download
> the required files automatically.  So we need to take out the advice
> that says you can rely on auto-download for everybody, not just macOS.

> If this is indeed the case, perhaps we ought to start inserting --nonet
> into the invocations.  There's not much use in allowing these tools to
> perform internet access when the best-case scenario is that they fail.

Concretely, I'm thinking something like the attached.  Notes:

1. I have not tested the meson changes.

2. As this is written, you can't override the --nonet options very
easily in the Makefile build (you could do so at runtime by setting
XSLTPROC, but not at configure time); and you can't override them at
all in the meson build.  Given the lack of evidence that it's still
useful to allow net access, I'm untroubled by that.  I did intentionally
skip using "override" in the Makefile, though, to allow that case.

3. For consistency with the directions for other platforms, I made
the package lists for macOS just mention libxslt.  That should
be enough to pull in libxml2 as well.

4. Use of --nonet changes the error message you get if xsltproc
can't find the DTDs.  I copied the error I get from MacPorts'
version of xsltproc, but can you confirm it's the same on Homebrew?

            regards, tom lane

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..cf9d4d4389 100644
--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
@@ -151,18 +151,6 @@
    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>

@@ -207,22 +195,38 @@ apt-get install docbook-xml docbook-xsl fop libxml2-utils xsltproc
   <sect2 id="docguide-toolsets-inst-macos">
    <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.
-   </para>
-
    <para>
     If you use MacPorts, the following will get you set up:
 <programlisting>
-sudo port install docbook-xml-4.5 docbook-xsl fop
+sudo port install docbook-xml docbook-xsl-nons fop libxslt
 </programlisting>
     If you use Homebrew, use this:
 <programlisting>
-brew install docbook docbook-xsl fop
+brew install docbook docbook-xsl fop libxslt
 </programlisting>
    </para>
+
+   <para>
+    The Homebrew-supplied programs require the following environment variable
+    to be set:
+<programlisting>
+export XML_CATALOG_FILES=/usr/local/etc/xml/catalog
+</programlisting>
+    Without it, <command>xsltproc</command> will throw errors like this:
+<programlisting>
+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">
@@ -253,12 +257,6 @@ checking for dbtoepub... dbtoepub
    these programs, for example
 <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>
   </sect2>
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..524a4e00e4 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'
   ]