Skip to content

Commit 7f8778f

Browse files
tglsfdctglsfdc
committed
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
1 parent 0801345 commit 7f8778f

File tree

3 files changed

+34
-31
lines changed

3 files changed

+34
-31
lines changed

‎doc/src/sgml/Makefile

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,11 +41,15 @@ endif
4141

4242
XMLINCLUDE = --path .
4343

44-
ifndef XMLLINT
44+
ifdef XMLLINT
45+
XMLLINT := $(XMLLINT) --nonet
46+
else
4547
XMLLINT = $(missing) xmllint
4648
endif
4749

48-
ifndef XSLTPROC
50+
ifdef XSLTPROC
51+
XSLTPROC := $(XSLTPROC) --nonet
52+
else
4953
XSLTPROC = $(missing) xsltproc
5054
endif
5155

‎doc/src/sgml/docguide.sgml

Lines changed: 27 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,7 @@
136136
<listitem>
137137
<para>
138138
This is a program for converting, among other things, XML to PDF.
139+
It is needed only if you want to build the documentation in PDF format.
139140
</para>
140141
</listitem>
141142
</varlistentry>
@@ -151,25 +152,13 @@
151152
here.
152153
</para>
153154

154-
<para>
155-
You can get away with not installing DocBook XML and the DocBook XSLT
156-
stylesheets locally, because the required files will be downloaded from the
157-
Internet and cached locally. This may in fact be the preferred solution if
158-
your operating system packages provide only an old version of these files,
159-
or if no packages are available at all.
160-
If you want to prevent any attempt to access the Internet while building
161-
the documentation, you need to pass the <option>--nonet</option> option
162-
to <command>xmllint</command> and <command>xsltproc</command>; see below
163-
for an example.
164-
</para>
165-
166155
<sect2>
167156
<title>Installation on Fedora, RHEL, and Derivatives</title>
168157

169158
<para>
170159
To install the required packages, use:
171160
<programlisting>
172-
yum install docbook-dtds docbook-style-xsl fop libxslt
161+
yum install docbook-dtds docbook-style-xsl libxslt fop
173162
</programlisting>
174163
</para>
175164
</sect2>
@@ -180,7 +169,7 @@ yum install docbook-dtds docbook-style-xsl fop libxslt
180169
<para>
181170
To install the required packages with <command>pkg</command>, use:
182171
<programlisting>
183-
pkg install docbook-xml docbook-xsl fop libxslt
172+
pkg install docbook-xml docbook-xsl libxslt fop
184173
</programlisting>
185174
</para>
186175

@@ -199,7 +188,7 @@ pkg install docbook-xml docbook-xsl fop libxslt
199188
available for <productname>Debian GNU/Linux</productname>.
200189
To install, simply use:
201190
<programlisting>
202-
apt-get install docbook-xml docbook-xsl fop libxml2-utils xsltproc
191+
apt-get install docbook-xml docbook-xsl libxml2-utils xsltproc fop
203192
</programlisting>
204193
</para>
205194
</sect2>
@@ -208,21 +197,37 @@ apt-get install docbook-xml docbook-xsl fop libxml2-utils xsltproc
208197
<title>macOS</title>
209198

210199
<para>
211-
On macOS, you can build the HTML and man documentation without installing
212-
anything extra. If you want to build PDFs or want to install a local copy
213-
of DocBook, you can get those from your preferred package manager.
200+
If you use MacPorts, the following will get you set up:
201+
<programlisting>
202+
sudo port install docbook-xml docbook-xsl-nons libxslt fop
203+
</programlisting>
204+
If you use Homebrew, use this:
205+
<programlisting>
206+
brew install docbook docbook-xsl libxslt fop
207+
</programlisting>
214208
</para>
215209

216210
<para>
217-
If you use MacPorts, the following will get you set up:
211+
The Homebrew-supplied programs require the following environment variable
212+
to be set:
218213
<programlisting>
219-
sudo port install docbook-xml-4.5 docbook-xsl fop
214+
export XML_CATALOG_FILES=/usr/local/etc/xml/catalog
220215
</programlisting>
221-
If you use Homebrew, use this:
216+
Without it, <command>xsltproc</command> will throw errors like this:
222217
<programlisting>
223-
brew install docbook docbook-xsl fop
218+
I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd
219+
postgres.sgml:21: warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
220+
...
224221
</programlisting>
225222
</para>
223+
224+
<para>
225+
While it is possible to use the Apple-provided versions
226+
of <command>xmllint</command> and <command>xsltproc</command>
227+
instead of those from MacPorts or Homebrew, you'll still need
228+
to install the DocBook DTD and stylesheets, and set up a catalog
229+
file that points to them.
230+
</para>
226231
</sect2>
227232

228233
<sect2 id="docguide-toolsets-configure">
@@ -253,12 +258,6 @@ checking for dbtoepub... dbtoepub
253258
these programs, for example
254259
<screen>
255260
./configure ... XMLLINT=/opt/local/bin/xmllint ...
256-
</screen>
257-
Also, if you want to ensure that <filename>xmllint</filename>
258-
and <filename>xsltproc</filename> will not perform any network access,
259-
you can do something like
260-
<screen>
261-
./configure ... XMLLINT="xmllint --nonet" XSLTPROC="xsltproc --nonet" ...
262261
</screen>
263262
</para>
264263
</sect2>

‎doc/src/sgml/images/Makefile

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ ALL_IMAGES = \
99

1010
DITAA = ditaa
1111
DOT = dot
12-
XSLTPROC = xsltproc
12+
XSLTPROC = xsltproc --nonet
1313

1414
all: $(ALL_IMAGES)
1515

0 commit comments

Comments
 (0)