XMLINCLUDE = --path .

XMLLINT :=$(XMLLINT) --nonet

else

XMLLINT =$(missing) xmllint

XSLTPROC :=$(XSLTPROC) --nonet

else

XSLTPROC =$(missing) xsltproc

<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>

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-xslfoplibxslt

yum install docbook-dtds docbook-style-xsl libxslt fop

</programlisting>

</para>

</sect2>

<para>

To install the required packages with <command>pkg</command>, use:

<programlisting>

pkg install docbook-xml docbook-xslfoplibxslt

pkg install docbook-xml docbook-xsl libxslt fop

</programlisting>

</para>

available for <productname>Debian GNU/Linux</productname>.

To install, simply use:

<programlisting>

apt-get install docbook-xml docbook-xslfoplibxml2-utils xsltproc

apt-get install docbook-xml docbook-xsl libxml2-utils xsltproc fop

</programlisting>

</para>

</sect2>

<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">

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>

<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

</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>

DITAA = ditaa

DOT = dot

XSLTPROC = xsltproc

XSLTPROC = xsltproc --nonet

all:$(ALL_IMAGES)

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,

)

if xsltproc_bin.found()

xsltproc_flags= [

'--nonet',

'--stringparam','pg.version', pg_version,

'--param','website.stylesheet','1'

]

command: [xsltproc,'--path','@OUTDIR@','-o','@OUTDIR@/', xsltproc_flags,'@INPUT@'],

build_by_default:false,

)

docs+= man

alldocs+= man