2010-09-20 22:08:53 +02:00
|
|
|
<!-- doc/src/sgml/docguide.sgml -->
|
1998-08-15 08:53:52 +02:00
|
|
|
|
2001-10-09 20:46:00 +02:00
|
|
|
<appendix id="docguide">
|
1999-05-27 17:49:08 +02:00
|
|
|
<title>Documentation</title>
|
|
|
|
|
|
|
|
<para>
|
2000-11-11 14:53:49 +01:00
|
|
|
<productname>PostgreSQL</productname> has four primary documentation
|
|
|
|
formats:
|
|
|
|
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Plain text, for pre-installation information
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
<acronym>HTML</acronym>, for on-line browsing and reference
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2017-04-07 04:03:52 +02:00
|
|
|
PDF, for printing
|
2000-11-11 14:53:49 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
man pages, for quick reference.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
|
2003-09-13 00:17:24 +02:00
|
|
|
Additionally, a number of plain-text <filename>README</filename> files can
|
|
|
|
be found throughout the <productname>PostgreSQL</productname> source tree,
|
2000-11-11 14:53:49 +01:00
|
|
|
documenting various implementation issues.
|
1999-05-27 17:49:08 +02:00
|
|
|
</para>
|
|
|
|
|
2000-11-11 14:53:49 +01:00
|
|
|
<para>
|
|
|
|
<acronym>HTML</acronym> documentation and man pages are part of a
|
2017-04-07 04:03:52 +02:00
|
|
|
standard distribution and are installed by default. PDF
|
|
|
|
format documentation is available separately for
|
2003-06-06 16:17:08 +02:00
|
|
|
download.
|
2000-11-11 14:53:49 +01:00
|
|
|
</para>
|
1999-05-27 17:49:08 +02:00
|
|
|
|
2003-06-06 16:17:08 +02:00
|
|
|
<sect1 id="docguide-docbook">
|
2000-11-11 14:53:49 +01:00
|
|
|
<title>DocBook</title>
|
1999-05-27 17:49:08 +02:00
|
|
|
<para>
|
2000-11-11 14:53:49 +01:00
|
|
|
The documentation sources are written in
|
|
|
|
<firstterm>DocBook</firstterm>, which is a markup language
|
2017-11-23 15:39:47 +01:00
|
|
|
defined in <acronym>XML</acronym>. In what
|
|
|
|
follows, the terms DocBook and <acronym>XML</acronym> are both
|
2004-02-17 03:53:03 +01:00
|
|
|
used, but technically they are not interchangeable.
|
1999-05-27 17:49:08 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2000-11-11 14:53:49 +01:00
|
|
|
<productname>DocBook</productname> allows an author to specify the
|
|
|
|
structure and content of a technical document without worrying
|
|
|
|
about presentation details. A document style defines how that
|
|
|
|
content is rendered into one of several final forms. DocBook is
|
2018-07-16 10:44:06 +02:00
|
|
|
maintained by the <ulink url="https://www.oasis-open.org">
|
|
|
|
OASIS group</ulink>. The <ulink url="https://www.oasis-open.org/docbook/">
|
2005-04-09 05:52:43 +02:00
|
|
|
official DocBook site</ulink> has good introductory and reference documentation and
|
2000-11-11 14:53:49 +01:00
|
|
|
a complete O'Reilly book for your online reading pleasure. The
|
2005-02-19 05:34:17 +01:00
|
|
|
<ulink url="http://newbiedoc.sourceforge.net/metadoc/docbook-guide.html">
|
2005-04-09 05:52:43 +02:00
|
|
|
NewbieDoc Docbook Guide</ulink> is very helpful for beginners.
|
2022-09-12 22:17:17 +02:00
|
|
|
The <ulink url="https://www.freebsd.org/docproj/">
|
2005-04-09 05:52:43 +02:00
|
|
|
FreeBSD Documentation Project</ulink> also uses DocBook and has some good
|
2000-11-11 14:53:49 +01:00
|
|
|
information, including a number of style guidelines that might be
|
|
|
|
worth considering.
|
1999-05-27 17:49:08 +02:00
|
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
|
|
|
|
|
2003-06-06 16:17:08 +02:00
|
|
|
<sect1 id="docguide-toolsets">
|
2002-03-22 20:20:45 +01:00
|
|
|
<title>Tool Sets</title>
|
1999-05-27 17:49:08 +02:00
|
|
|
|
|
|
|
<para>
|
2000-11-11 14:53:49 +01:00
|
|
|
The following tools are used to process the documentation. Some
|
Update documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
|
|
|
might be optional, as noted.
|
1999-05-27 17:49:08 +02:00
|
|
|
|
2000-11-11 14:53:49 +01:00
|
|
|
<variablelist>
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="docguide-toolsets-docbook-dtd">
|
2019-01-23 05:06:45 +01:00
|
|
|
<term><ulink url="https://www.oasis-open.org/docbook/">DocBook DTD</ulink></term>
|
2000-11-11 14:53:49 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2017-04-07 04:03:52 +02:00
|
|
|
This is the definition of DocBook itself. We currently use version
|
2019-08-13 08:38:21 +02:00
|
|
|
4.5; you cannot use later or earlier versions. You need
|
2017-11-23 15:39:47 +01:00
|
|
|
the <acronym>XML</acronym> variant of the DocBook DTD, not
|
|
|
|
the <acronym>SGML</acronym> variant.
|
2000-11-11 14:53:49 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
1998-12-29 03:24:47 +01:00
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="docguide-toolsets-docbook-xsl">
|
2017-08-16 20:44:26 +02:00
|
|
|
<term><ulink url="https://github.com/docbook/wiki/wiki/DocBookXslStylesheets">DocBook XSL Stylesheets</ulink></term>
|
2000-11-11 14:53:49 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2009-08-05 00:04:37 +02:00
|
|
|
These contain the processing instructions for converting the
|
|
|
|
DocBook sources to other formats, such as
|
|
|
|
<acronym>HTML</acronym>.
|
2000-11-11 14:53:49 +01:00
|
|
|
</para>
|
2011-08-27 22:28:55 +02:00
|
|
|
|
|
|
|
<para>
|
2017-04-07 04:03:52 +02:00
|
|
|
The minimum required version is currently 1.77.0, but it is recommended
|
|
|
|
to use the latest available version for best results.
|
2011-08-27 22:28:55 +02:00
|
|
|
</para>
|
2000-11-11 14:53:49 +01:00
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
1998-07-29 08:33:37 +02:00
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="docguide-toolsets-libxml2">
|
doc: Check DocBook XML validity during the build
Building the documentation with XSLT does not check the DTD, like a
DSSSL build would. One can often get away with having invalid XML, but
the stylesheets might then create incorrect output, as they are not
designed to handle that. Therefore, check the validity of the XML
against the DTD, using xmllint, during the build.
Add xmllint detection to configure, and add some documentation.
xmllint comes with libxml2, which is already in use, but it might be in
a separate package, such as libxml2-utils on Debian.
Reviewed-by: Fabien COELHO <coelho@cri.ensmp.fr>
2014-10-21 20:46:38 +02:00
|
|
|
<term><ulink url="http://xmlsoft.org/">Libxml2</ulink> for <command>xmllint</command></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
This library and the <command>xmllint</command> tool it contains are
|
|
|
|
used for processing XML. Many developers will already
|
|
|
|
have <application>Libxml2</application> installed, because it is also
|
|
|
|
used when building the PostgreSQL code. Note, however,
|
|
|
|
that <command>xmllint</command> might need to be installed from a
|
|
|
|
separate subpackage.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="docguide-toolsets-libxslt">
|
2009-08-05 00:04:37 +02:00
|
|
|
<term><ulink url="http://xmlsoft.org/XSLT/">Libxslt</ulink> for <command>xsltproc</command></term>
|
2008-09-12 10:43:53 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2017-04-07 04:03:52 +02:00
|
|
|
<command>xsltproc</command> is an XSLT processor, that is, a program to
|
|
|
|
convert XML to other formats using XSLT stylesheets.
|
2000-11-11 14:53:49 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
1998-07-29 08:33:37 +02:00
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="docguide-toolsets-fop">
|
2017-04-07 04:03:52 +02:00
|
|
|
<term><ulink url="https://xmlgraphics.apache.org/fop/">FOP</ulink></term>
|
2000-11-11 14:53:49 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2017-04-07 04:03:52 +02:00
|
|
|
This is a program for converting, among other things, XML to PDF.
|
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
2023-02-08 23:15:23 +01:00
|
|
|
It is needed only if you want to build the documentation in PDF format.
|
2000-11-11 14:53:49 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
2000-02-02 17:22:45 +01:00
|
|
|
</para>
|
1998-07-29 08:33:37 +02:00
|
|
|
|
2000-02-02 17:22:45 +01:00
|
|
|
<para>
|
2000-11-11 14:53:49 +01:00
|
|
|
We have documented experience with several installation methods for
|
|
|
|
the various tools that are needed to process the documentation.
|
Update documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
|
|
|
These will be described below. There might be some other packaged
|
2000-11-11 14:53:49 +01:00
|
|
|
distributions for these tools. Please report package status to the
|
2003-06-06 16:17:08 +02:00
|
|
|
documentation mailing list, and we will include that information
|
|
|
|
here.
|
2000-02-02 17:22:45 +01:00
|
|
|
</para>
|
1998-07-29 08:33:37 +02:00
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<sect2 id="docguide-toolsets-inst-fedora-et-al">
|
2014-10-21 16:43:09 +02:00
|
|
|
<title>Installation on Fedora, RHEL, and Derivatives</title>
|
1998-10-30 20:37:19 +01:00
|
|
|
|
2000-02-02 17:22:45 +01:00
|
|
|
<para>
|
2014-10-21 16:43:09 +02:00
|
|
|
To install the required packages, use:
|
|
|
|
<programlisting>
|
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
2023-02-08 23:15:23 +01:00
|
|
|
yum install docbook-dtds docbook-style-xsl libxslt fop
|
2014-10-21 16:43:09 +02:00
|
|
|
</programlisting>
|
2000-02-02 17:22:45 +01:00
|
|
|
</para>
|
2000-11-11 14:53:49 +01:00
|
|
|
</sect2>
|
1998-04-28 16:57:48 +02:00
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<sect2 id="docguide-toolsets-inst-freebsd">
|
2014-10-21 16:32:28 +02:00
|
|
|
<title>Installation on FreeBSD</title>
|
2000-02-02 17:22:45 +01:00
|
|
|
|
2017-03-22 03:09:40 +01:00
|
|
|
<para>
|
|
|
|
To install the required packages with <command>pkg</command>, use:
|
|
|
|
<programlisting>
|
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
2023-02-08 23:15:23 +01:00
|
|
|
pkg install docbook-xml docbook-xsl libxslt fop
|
2017-03-22 03:09:40 +01:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
When building the documentation from the <filename>doc</filename>
|
|
|
|
directory you'll need to use <command>gmake</command>, because the
|
|
|
|
makefile provided is not suitable for FreeBSD's <command>make</command>.
|
|
|
|
</para>
|
2000-02-02 17:22:45 +01:00
|
|
|
</sect2>
|
1998-03-01 09:16:16 +01:00
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<sect2 id="docguide-toolsets-inst-debian">
|
2000-11-11 14:53:49 +01:00
|
|
|
<title>Debian Packages</title>
|
1998-04-28 16:57:48 +02:00
|
|
|
|
2000-02-02 17:22:45 +01:00
|
|
|
<para>
|
2000-11-11 14:53:49 +01:00
|
|
|
There is a full set of packages of the documentation tools
|
|
|
|
available for <productname>Debian GNU/Linux</productname>.
|
|
|
|
To install, simply use:
|
|
|
|
<programlisting>
|
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
2023-02-08 23:15:23 +01:00
|
|
|
apt-get install docbook-xml docbook-xsl libxml2-utils xsltproc fop
|
2000-11-11 14:53:49 +01:00
|
|
|
</programlisting>
|
2000-02-02 17:22:45 +01:00
|
|
|
</para>
|
2000-11-11 14:53:49 +01:00
|
|
|
</sect2>
|
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<sect2 id="docguide-toolsets-inst-macos">
|
Refer to OS X as "macOS", except for the port name which is still "darwin".
We weren't terribly consistent about whether to call Apple's OS "OS X"
or "Mac OS X", and the former is probably confusing to people who aren't
Apple users. Now that Apple has rebranded it "macOS", follow their lead
to establish a consistent naming pattern. Also, avoid the use of the
ancient project name "Darwin", except as the port code name which does not
seem desirable to change. (In short, this patch touches documentation and
comments, but no actual code.)
I didn't touch contrib/start-scripts/osx/, either. I suspect those are
obsolete and due for a rewrite, anyway.
I dithered about whether to apply this edit to old release notes, but
those were responsible for quite a lot of the inconsistencies, so I ended
up changing them too. Anyway, Apple's being ahistorical about this,
so why shouldn't we be?
2016-09-25 21:40:57 +02:00
|
|
|
<title>macOS</title>
|
2012-08-23 08:28:47 +02:00
|
|
|
|
|
|
|
<para>
|
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
2023-02-08 23:15:23 +01:00
|
|
|
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>
|
2012-08-23 08:28:47 +02:00
|
|
|
</para>
|
1998-04-28 16:57:48 +02:00
|
|
|
|
2000-02-02 17:22:45 +01:00
|
|
|
<para>
|
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
2023-02-08 23:15:23 +01:00
|
|
|
The Homebrew-supplied programs require the following environment variable
|
2023-03-27 11:56:19 +02:00
|
|
|
to be set. For Intel based machines, use this:
|
2000-11-11 14:53:49 +01:00
|
|
|
<programlisting>
|
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
2023-02-08 23:15:23 +01:00
|
|
|
export XML_CATALOG_FILES=/usr/local/etc/xml/catalog
|
2023-03-27 11:56:19 +02:00
|
|
|
</programlisting>
|
2023-03-27 14:16:45 +02:00
|
|
|
On Apple Silicon based machines, use this:
|
2023-03-27 11:56:19 +02:00
|
|
|
<programlisting>
|
|
|
|
export XML_CATALOG_FILES=/opt/homebrew/etc/xml/catalog
|
2000-11-11 14:53:49 +01:00
|
|
|
</programlisting>
|
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
2023-02-08 23:15:23 +01:00
|
|
|
Without it, <command>xsltproc</command> will throw errors like this:
|
2001-10-09 20:46:00 +02:00
|
|
|
<programlisting>
|
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
2023-02-08 23:15:23 +01:00
|
|
|
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"
|
|
|
|
...
|
2001-10-09 20:46:00 +02:00
|
|
|
</programlisting>
|
2017-11-23 15:39:47 +01:00
|
|
|
</para>
|
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
2023-02-08 23:15:23 +01:00
|
|
|
|
|
|
|
<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>
|
2000-02-02 17:22:45 +01:00
|
|
|
</sect2>
|
2000-10-17 17:26:40 +02:00
|
|
|
|
2003-06-06 16:17:08 +02:00
|
|
|
<sect2 id="docguide-toolsets-configure">
|
|
|
|
<title>Detection by <command>configure</command></title>
|
1998-04-28 16:57:48 +02:00
|
|
|
|
1999-07-06 19:19:42 +02:00
|
|
|
<para>
|
2000-11-11 14:53:49 +01:00
|
|
|
Before you can build the documentation you need to run the
|
Remove configure-time probe for DocBook DTD.
Checking for DocBook being installed was valuable when we were on the
OpenSP docs toolchain, because that was rather hard to get installed
fully. Nowadays, as long as you have xmllint and xsltproc installed,
you're good, because those programs will fetch the DocBook files off
the net at need. Moreover, testing this at configure time means that
a network access may well occur whether or not you have any interest
in building the docs later. That can be slow (typically 2 or 3
seconds, though much higher delays have been reported), and it seems
not very nice to be doing an off-machine access without warning, too.
Hence, drop the PGAC_CHECK_DOCBOOK probe, and adjust related
documentation. Without that macro, there's not much left of
config/docbook.m4 at all, so I just removed it.
Back-patch to v11, where we started to use xmllint in the
PGAC_CHECK_DOCBOOK probe.
Discussion: https://postgr.es/m/E2EE6B76-2D96-408A-B961-CAE47D1A86F0@yesql.se
Discussion: https://postgr.es/m/A55A7FC9-FA60-47FE-98B5-139CDC57CE6E@gmail.com
2020-11-30 21:24:13 +01:00
|
|
|
<filename>configure</filename> script, as you would when building
|
2003-09-11 23:42:20 +02:00
|
|
|
the <productname>PostgreSQL</productname> programs themselves.
|
Remove configure-time probe for DocBook DTD.
Checking for DocBook being installed was valuable when we were on the
OpenSP docs toolchain, because that was rather hard to get installed
fully. Nowadays, as long as you have xmllint and xsltproc installed,
you're good, because those programs will fetch the DocBook files off
the net at need. Moreover, testing this at configure time means that
a network access may well occur whether or not you have any interest
in building the docs later. That can be slow (typically 2 or 3
seconds, though much higher delays have been reported), and it seems
not very nice to be doing an off-machine access without warning, too.
Hence, drop the PGAC_CHECK_DOCBOOK probe, and adjust related
documentation. Without that macro, there's not much left of
config/docbook.m4 at all, so I just removed it.
Back-patch to v11, where we started to use xmllint in the
PGAC_CHECK_DOCBOOK probe.
Discussion: https://postgr.es/m/E2EE6B76-2D96-408A-B961-CAE47D1A86F0@yesql.se
Discussion: https://postgr.es/m/A55A7FC9-FA60-47FE-98B5-139CDC57CE6E@gmail.com
2020-11-30 21:24:13 +01:00
|
|
|
Check the output near the end of the run; it should look something
|
2003-09-11 23:42:20 +02:00
|
|
|
like this:
|
2000-11-11 14:53:49 +01:00
|
|
|
<screen>
|
2017-04-07 04:03:52 +02:00
|
|
|
checking for xmllint... xmllint
|
2009-08-05 00:04:37 +02:00
|
|
|
checking for xsltproc... xsltproc
|
2017-04-07 04:03:52 +02:00
|
|
|
checking for fop... fop
|
Remove configure-time probe for DocBook DTD.
Checking for DocBook being installed was valuable when we were on the
OpenSP docs toolchain, because that was rather hard to get installed
fully. Nowadays, as long as you have xmllint and xsltproc installed,
you're good, because those programs will fetch the DocBook files off
the net at need. Moreover, testing this at configure time means that
a network access may well occur whether or not you have any interest
in building the docs later. That can be slow (typically 2 or 3
seconds, though much higher delays have been reported), and it seems
not very nice to be doing an off-machine access without warning, too.
Hence, drop the PGAC_CHECK_DOCBOOK probe, and adjust related
documentation. Without that macro, there's not much left of
config/docbook.m4 at all, so I just removed it.
Back-patch to v11, where we started to use xmllint in the
PGAC_CHECK_DOCBOOK probe.
Discussion: https://postgr.es/m/E2EE6B76-2D96-408A-B961-CAE47D1A86F0@yesql.se
Discussion: https://postgr.es/m/A55A7FC9-FA60-47FE-98B5-139CDC57CE6E@gmail.com
2020-11-30 21:24:13 +01:00
|
|
|
checking for dbtoepub... dbtoepub
|
2000-11-11 14:53:49 +01:00
|
|
|
</screen>
|
Remove configure-time probe for DocBook DTD.
Checking for DocBook being installed was valuable when we were on the
OpenSP docs toolchain, because that was rather hard to get installed
fully. Nowadays, as long as you have xmllint and xsltproc installed,
you're good, because those programs will fetch the DocBook files off
the net at need. Moreover, testing this at configure time means that
a network access may well occur whether or not you have any interest
in building the docs later. That can be slow (typically 2 or 3
seconds, though much higher delays have been reported), and it seems
not very nice to be doing an off-machine access without warning, too.
Hence, drop the PGAC_CHECK_DOCBOOK probe, and adjust related
documentation. Without that macro, there's not much left of
config/docbook.m4 at all, so I just removed it.
Back-patch to v11, where we started to use xmllint in the
PGAC_CHECK_DOCBOOK probe.
Discussion: https://postgr.es/m/E2EE6B76-2D96-408A-B961-CAE47D1A86F0@yesql.se
Discussion: https://postgr.es/m/A55A7FC9-FA60-47FE-98B5-139CDC57CE6E@gmail.com
2020-11-30 21:24:13 +01:00
|
|
|
If <filename>xmllint</filename> or <filename>xsltproc</filename> is not
|
|
|
|
found, you will not be able to build any of the documentation.
|
|
|
|
<filename>fop</filename> is only needed to build the documentation in
|
|
|
|
PDF format.
|
|
|
|
<filename>dbtoepub</filename> is only needed to build the documentation
|
|
|
|
in EPUB format.
|
1999-07-06 19:19:42 +02:00
|
|
|
</para>
|
1998-04-28 16:57:48 +02:00
|
|
|
|
Remove configure-time probe for DocBook DTD.
Checking for DocBook being installed was valuable when we were on the
OpenSP docs toolchain, because that was rather hard to get installed
fully. Nowadays, as long as you have xmllint and xsltproc installed,
you're good, because those programs will fetch the DocBook files off
the net at need. Moreover, testing this at configure time means that
a network access may well occur whether or not you have any interest
in building the docs later. That can be slow (typically 2 or 3
seconds, though much higher delays have been reported), and it seems
not very nice to be doing an off-machine access without warning, too.
Hence, drop the PGAC_CHECK_DOCBOOK probe, and adjust related
documentation. Without that macro, there's not much left of
config/docbook.m4 at all, so I just removed it.
Back-patch to v11, where we started to use xmllint in the
PGAC_CHECK_DOCBOOK probe.
Discussion: https://postgr.es/m/E2EE6B76-2D96-408A-B961-CAE47D1A86F0@yesql.se
Discussion: https://postgr.es/m/A55A7FC9-FA60-47FE-98B5-139CDC57CE6E@gmail.com
2020-11-30 21:24:13 +01:00
|
|
|
<para>
|
|
|
|
If necessary, you can tell <filename>configure</filename> where to find
|
|
|
|
these programs, for example
|
|
|
|
<screen>
|
|
|
|
./configure ... XMLLINT=/opt/local/bin/xmllint ...
|
|
|
|
</screen>
|
|
|
|
</para>
|
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
2023-02-08 23:15:23 +01:00
|
|
|
|
|
|
|
<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>
|
2003-06-06 16:17:08 +02:00
|
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
|
|
|
|
<sect1 id="docguide-build">
|
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
2023-02-08 23:15:23 +01:00
|
|
|
<title>Building the Documentation with Make</title>
|
2003-06-06 16:17:08 +02:00
|
|
|
|
1999-07-06 19:19:42 +02:00
|
|
|
<para>
|
2000-11-11 14:53:49 +01:00
|
|
|
Once you have everything set up, change to the directory
|
2003-06-06 16:17:08 +02:00
|
|
|
<filename>doc/src/sgml</filename> and run one of the commands
|
|
|
|
described in the following subsections to build the
|
|
|
|
documentation. (Remember to use GNU make.)
|
|
|
|
</para>
|
2000-11-11 14:53:49 +01:00
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<sect2 id="docguide-build-html">
|
2003-06-06 16:17:08 +02:00
|
|
|
<title>HTML</title>
|
2000-11-11 14:53:49 +01:00
|
|
|
|
2003-06-06 16:17:08 +02:00
|
|
|
<para>
|
|
|
|
To build the <acronym>HTML</acronym> version of the documentation:
|
2000-11-11 14:53:49 +01:00
|
|
|
<screen>
|
2014-02-12 23:29:19 +01:00
|
|
|
<prompt>doc/src/sgml$ </prompt><userinput>make html</userinput>
|
2000-11-11 14:53:49 +01:00
|
|
|
</screen>
|
2009-08-10 00:47:59 +02:00
|
|
|
This is also the default target. The output appears in the
|
|
|
|
subdirectory <filename>html</filename>.
|
2003-06-06 16:17:08 +02:00
|
|
|
</para>
|
2000-11-11 14:53:49 +01:00
|
|
|
|
2015-07-29 17:16:55 +02:00
|
|
|
<para>
|
|
|
|
To produce HTML documentation with the stylesheet used on <ulink
|
2018-07-16 10:44:06 +02:00
|
|
|
url="https://www.postgresql.org/docs/current/">postgresql.org</ulink> instead of the
|
2015-07-29 17:16:55 +02:00
|
|
|
default simple style use:
|
|
|
|
<screen>
|
|
|
|
<prompt>doc/src/sgml$ </prompt><userinput>make STYLE=website html</userinput>
|
2007-01-09 23:19:36 +01:00
|
|
|
</screen>
|
2003-06-06 16:17:08 +02:00
|
|
|
</para>
|
2020-02-15 03:38:35 +01:00
|
|
|
|
|
|
|
<para>
|
|
|
|
If the <literal>STYLE=website</literal> option is used, the generated HTML
|
|
|
|
files include references to stylesheets hosted on <ulink
|
|
|
|
url="https://www.postgresql.org/docs/current/">postgresql.org</ulink> and
|
|
|
|
require network access to view.
|
|
|
|
</para>
|
2000-11-11 14:53:49 +01:00
|
|
|
</sect2>
|
1999-07-06 19:19:42 +02:00
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<sect2 id="docguide-build-manpages">
|
1999-07-06 19:19:42 +02:00
|
|
|
<title>Manpages</title>
|
|
|
|
|
|
|
|
<para>
|
2009-08-05 00:04:37 +02:00
|
|
|
We use the DocBook XSL stylesheets to
|
1999-07-06 19:19:42 +02:00
|
|
|
convert <productname>DocBook</productname>
|
2003-06-06 16:17:08 +02:00
|
|
|
<sgmltag>refentry</sgmltag> pages to *roff output suitable for man
|
2017-11-23 15:39:47 +01:00
|
|
|
pages. To create the man pages, use the command:
|
2017-04-07 04:03:52 +02:00
|
|
|
<screen>
|
|
|
|
<prompt>doc/src/sgml$ </prompt><userinput>make man</userinput>
|
|
|
|
</screen>
|
1999-07-06 19:19:42 +02:00
|
|
|
</para>
|
2000-10-17 17:26:40 +02:00
|
|
|
</sect2>
|
1998-04-28 16:57:48 +02:00
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<sect2 id="docguide-build-pdf">
|
2017-04-07 04:03:52 +02:00
|
|
|
<title>PDF</title>
|
1998-04-28 16:57:48 +02:00
|
|
|
|
2003-06-06 16:17:08 +02:00
|
|
|
<para>
|
2017-04-07 04:03:52 +02:00
|
|
|
To produce a PDF rendition of the documentation
|
|
|
|
using <productname>FOP</productname>, you can use one of the following
|
|
|
|
commands, depending on the preferred paper format:
|
1998-04-28 16:57:48 +02:00
|
|
|
|
2003-06-06 16:17:08 +02:00
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2017-04-07 04:03:52 +02:00
|
|
|
For A4 format:
|
2003-06-06 16:17:08 +02:00
|
|
|
<screen>
|
2017-04-07 04:03:52 +02:00
|
|
|
<prompt>doc/src/sgml$ </prompt><userinput>make postgres-A4.pdf</userinput>
|
2003-06-06 16:17:08 +02:00
|
|
|
</screen>
|
|
|
|
</para>
|
|
|
|
</listitem>
|
2010-11-23 21:27:50 +01:00
|
|
|
|
2003-06-06 16:17:08 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2017-04-07 04:03:52 +02:00
|
|
|
For U.S. letter format:
|
2006-12-10 21:46:03 +01:00
|
|
|
<screen>
|
2014-02-12 23:29:19 +01:00
|
|
|
<prompt>doc/src/sgml$ </prompt><userinput>make postgres-US.pdf</userinput>
|
2003-06-06 16:17:08 +02:00
|
|
|
</screen>
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</para>
|
2006-12-10 03:37:40 +01:00
|
|
|
|
|
|
|
<para>
|
2017-04-07 04:03:52 +02:00
|
|
|
Because the PostgreSQL documentation is fairly
|
|
|
|
big, <productname>FOP</productname> will require a significant amount of
|
|
|
|
memory. Because of that, on some systems, the build will fail with a
|
|
|
|
memory-related error message. This can usually be fixed by configuring
|
|
|
|
Java heap settings in the configuration
|
|
|
|
file <filename>~/.foprc</filename>, for example:
|
2006-12-10 03:37:40 +01:00
|
|
|
<programlisting>
|
2017-04-07 04:03:52 +02:00
|
|
|
# FOP binary distribution
|
2017-12-05 21:29:24 +01:00
|
|
|
FOP_OPTS='-Xmx1500m'
|
2017-04-07 04:03:52 +02:00
|
|
|
# Debian
|
2017-12-05 21:29:24 +01:00
|
|
|
JAVA_ARGS='-Xmx1500m'
|
2017-04-07 04:03:52 +02:00
|
|
|
# Red Hat
|
2017-12-05 21:29:24 +01:00
|
|
|
ADDITIONAL_FLAGS='-Xmx1500m'
|
2006-12-10 03:37:40 +01:00
|
|
|
</programlisting>
|
2017-04-07 04:03:52 +02:00
|
|
|
There is a minimum amount of memory that is required, and to some extent
|
|
|
|
more memory appears to make things a bit faster. On systems with very
|
|
|
|
little memory (less than 1 GB), the build will either be very slow due to
|
|
|
|
swapping or will not work at all.
|
2006-12-10 03:37:40 +01:00
|
|
|
</para>
|
2010-06-01 00:14:20 +02:00
|
|
|
|
2023-03-24 22:18:40 +01:00
|
|
|
<para>
|
|
|
|
In its default configuration <productname>FOP</productname> will emit an
|
|
|
|
<literal>INFO</literal> message for each page. The log level can be
|
|
|
|
changed via <filename>~/.foprc</filename>:
|
|
|
|
<programlisting>
|
2023-03-25 18:22:59 +01:00
|
|
|
LOGCHOICE=-Dorg.apache.commons.logging.Log=&zwsp;org.apache.commons.logging.impl.SimpleLog
|
2023-03-24 22:18:40 +01:00
|
|
|
LOGLEVEL=-Dorg.apache.commons.logging.simplelog.defaultlog=WARN
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
1999-05-27 17:49:08 +02:00
|
|
|
<para>
|
2017-04-07 04:03:52 +02:00
|
|
|
Other XSL-FO processors can also be used manually, but the automated build
|
|
|
|
process only supports FOP.
|
2000-02-02 17:22:45 +01:00
|
|
|
</para>
|
2000-10-17 17:26:40 +02:00
|
|
|
</sect2>
|
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<sect2 id="docguide-build-syntax-check">
|
2003-06-06 16:17:08 +02:00
|
|
|
<title>Syntax Check</title>
|
1999-05-27 17:49:08 +02:00
|
|
|
|
2003-06-06 16:17:08 +02:00
|
|
|
<para>
|
|
|
|
Building the documentation can take very long. But there is a
|
|
|
|
method to just check the correct syntax of the documentation
|
|
|
|
files, which only takes a few seconds:
|
|
|
|
<screen>
|
2014-02-12 23:29:19 +01:00
|
|
|
<prompt>doc/src/sgml$ </prompt><userinput>make check</userinput>
|
2003-06-06 16:17:08 +02:00
|
|
|
</screen>
|
|
|
|
</para>
|
1999-05-27 17:49:08 +02:00
|
|
|
</sect2>
|
1999-10-09 04:29:15 +02:00
|
|
|
</sect1>
|
1998-04-28 16:57:48 +02:00
|
|
|
|
2000-10-17 17:26:40 +02:00
|
|
|
|
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
2023-02-08 23:15:23 +01:00
|
|
|
<sect1 id="docguide-build-meson">
|
|
|
|
<title>Building the Documentation with Meson</title>
|
|
|
|
|
|
|
|
<para>
|
2023-11-21 02:46:40 +01:00
|
|
|
To build 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.
|
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
2023-02-08 23:15:23 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
To build just the <acronym>HTML</acronym> version of the documentation:
|
|
|
|
<screen>
|
2023-11-21 02:46:40 +01:00
|
|
|
<prompt>build$ </prompt><userinput>ninja html</userinput>
|
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
2023-02-08 23:15:23 +01:00
|
|
|
</screen>
|
2023-11-21 02:46:40 +01:00
|
|
|
For a list of other documentation targets see
|
|
|
|
<xref linkend="targets-meson-documentation"/>.
|
|
|
|
|
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
2023-02-08 23:15:23 +01:00
|
|
|
The output appears in the
|
|
|
|
subdirectory <filename>build/doc/src/sgml</filename>.
|
|
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
|
|
|
|
|
2003-06-06 16:17:08 +02:00
|
|
|
<sect1 id="docguide-authoring">
|
2000-11-11 14:53:49 +01:00
|
|
|
<title>Documentation Authoring</title>
|
1998-04-28 16:57:48 +02:00
|
|
|
|
1999-10-09 04:29:15 +02:00
|
|
|
<para>
|
2018-07-13 21:23:41 +02:00
|
|
|
The documentation sources are most conveniently modified with an editor
|
|
|
|
that has a mode for editing XML, and even more so if it has some awareness
|
|
|
|
of XML schema languages so that it can know about
|
|
|
|
<productname>DocBook</productname> syntax specifically.
|
1999-10-09 04:29:15 +02:00
|
|
|
</para>
|
1998-04-28 16:57:48 +02:00
|
|
|
|
2018-07-13 21:23:41 +02:00
|
|
|
<para>
|
|
|
|
Note that for historical reasons the documentation source files are named
|
|
|
|
with an extension <filename>.sgml</filename> even though they are now XML
|
|
|
|
files. So you might need to adjust your editor configuration to set the
|
|
|
|
correct mode.
|
|
|
|
</para>
|
2000-11-11 14:53:49 +01:00
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<sect2 id="docguide-authoring-emacs">
|
2018-07-13 21:23:41 +02:00
|
|
|
<title>Emacs</title>
|
1998-04-28 16:57:48 +02:00
|
|
|
|
1999-10-09 04:29:15 +02:00
|
|
|
<para>
|
2018-07-13 21:23:41 +02:00
|
|
|
<productname>nXML Mode</productname>, which ships with
|
|
|
|
<productname>Emacs</productname>, is the most common mode for editing
|
|
|
|
<acronym>XML</acronym> documents with <productname>Emacs</productname>.
|
|
|
|
It will allow you to use <application>Emacs</application> to insert tags
|
|
|
|
and check markup consistency, and it supports
|
|
|
|
<productname>DocBook</productname> out of the box. Check the <ulink
|
|
|
|
url="https://www.gnu.org/software/emacs/manual/html_mono/nxml-mode.html">
|
|
|
|
nXML manual</ulink> for detailed documentation.
|
1999-10-09 04:29:15 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2018-07-13 21:23:41 +02:00
|
|
|
<filename>src/tools/editors/emacs.samples</filename> contains
|
|
|
|
recommended settings for this mode.
|
1999-10-09 04:29:15 +02:00
|
|
|
</para>
|
2000-11-11 14:53:49 +01:00
|
|
|
</sect2>
|
1998-04-28 16:57:48 +02:00
|
|
|
|
1999-10-09 04:29:15 +02:00
|
|
|
</sect1>
|
1998-04-28 16:57:48 +02:00
|
|
|
|
2002-07-28 17:22:21 +02:00
|
|
|
|
2003-06-06 16:17:08 +02:00
|
|
|
<sect1 id="docguide-style">
|
2002-07-28 17:22:21 +02:00
|
|
|
<title>Style Guide</title>
|
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<sect2 id="docguide-style-ref-pages">
|
2002-07-28 17:22:21 +02:00
|
|
|
<title>Reference Pages</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Reference pages should follow a standard layout. This allows
|
|
|
|
users to find the desired information more quickly, and it also
|
|
|
|
encourages writers to document all relevant aspects of a command.
|
|
|
|
Consistency is not only desired among
|
|
|
|
<productname>PostgreSQL</productname> reference pages, but also
|
|
|
|
with reference pages provided by the operating system and other
|
|
|
|
packages. Hence the following guidelines have been developed.
|
|
|
|
They are for the most part consistent with similar guidelines
|
|
|
|
established by various operating systems.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Reference pages that describe executable commands should contain
|
|
|
|
the following sections, in this order. Sections that do not apply
|
Update documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
|
|
|
can be omitted. Additional top-level sections should only be used
|
2002-07-28 17:22:21 +02:00
|
|
|
in special circumstances; often that information belongs in the
|
|
|
|
<quote>Usage</quote> section.
|
|
|
|
|
|
|
|
<variablelist>
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="docguide-style-ref-pages-name">
|
2002-07-28 17:22:21 +02:00
|
|
|
<term>Name</term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
This section is generated automatically. It contains the
|
|
|
|
command name and a half-sentence summary of its functionality.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="docguide-style-ref-pages-synopsis">
|
2002-07-28 17:22:21 +02:00
|
|
|
<term>Synopsis</term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
This section contains the syntax diagram of the command. The
|
|
|
|
synopsis should normally not list each command-line option;
|
|
|
|
that is done below. Instead, list the major components of the
|
|
|
|
command line, such as where input and output files go.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2010-11-23 21:27:50 +01:00
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="docguide-style-ref-pages-description">
|
2002-07-28 17:22:21 +02:00
|
|
|
<term>Description</term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Several paragraphs explaining what the command does.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2010-11-23 21:27:50 +01:00
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="docguide-style-ref-pages-options">
|
2002-07-28 17:22:21 +02:00
|
|
|
<term>Options</term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
A list describing each command-line option. If there are a
|
Update documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
|
|
|
lot of options, subsections can be used.
|
2002-07-28 17:22:21 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2010-11-23 21:27:50 +01:00
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="docguide-style-ref-pages-exit-status">
|
2002-07-28 17:22:21 +02:00
|
|
|
<term>Exit Status</term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
If the program uses 0 for success and non-zero for failure,
|
2003-02-19 05:06:28 +01:00
|
|
|
then you do not need to document it. If there is a meaning
|
2002-07-28 17:22:21 +02:00
|
|
|
behind the different non-zero exit codes, list them here.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2010-11-23 21:27:50 +01:00
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="docguide-style-ref-pages-usage">
|
2002-07-28 17:22:21 +02:00
|
|
|
<term>Usage</term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Describe any sublanguage or run-time interface of the program.
|
|
|
|
If the program is not interactive, this section can usually be
|
|
|
|
omitted. Otherwise, this section is a catch-all for
|
|
|
|
describing run-time features. Use subsections if appropriate.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2010-11-23 21:27:50 +01:00
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="docguide-style-ref-pages-environment">
|
2002-07-28 17:22:21 +02:00
|
|
|
<term>Environment</term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
List all environment variables that the program might use.
|
|
|
|
Try to be complete; even seemingly trivial variables like
|
|
|
|
<envar>SHELL</envar> might be of interest to the user.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2010-11-23 21:27:50 +01:00
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="docguide-style-ref-pages-files">
|
2002-07-28 17:22:21 +02:00
|
|
|
<term>Files</term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
List any files that the program might access implicitly. That
|
|
|
|
is, do not list input and output files that were specified on
|
|
|
|
the command line, but list configuration files, etc.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2010-11-23 21:27:50 +01:00
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="docguide-style-ref-pages-diagnostics">
|
2002-07-28 17:22:21 +02:00
|
|
|
<term>Diagnostics</term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Explain any unusual output that the program might create.
|
|
|
|
Refrain from listing every possible error message. This is a
|
|
|
|
lot of work and has little use in practice. But if, say, the
|
|
|
|
error messages have a standard format that the user can parse,
|
|
|
|
this would be the place to explain it.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2010-11-23 21:27:50 +01:00
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="docguide-style-ref-pages-notes">
|
2002-07-28 17:22:21 +02:00
|
|
|
<term>Notes</term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Anything that doesn't fit elsewhere, but in particular bugs,
|
|
|
|
implementation flaws, security considerations, compatibility
|
|
|
|
issues.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2010-11-23 21:27:50 +01:00
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="docguide-style-ref-pages-examples">
|
2002-07-28 17:22:21 +02:00
|
|
|
<term>Examples</term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Examples
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2010-11-23 21:27:50 +01:00
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="docguide-style-ref-pages-history">
|
2002-07-28 17:22:21 +02:00
|
|
|
<term>History</term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
If there were some major milestones in the history of the
|
|
|
|
program, they might be listed here. Usually, this section can
|
|
|
|
be omitted.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2010-11-23 21:27:50 +01:00
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="docguide-style-ref-pages-author">
|
2012-05-09 19:39:53 +02:00
|
|
|
<term>Author</term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Author (only used in the contrib section)
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="docguide-style-ref-pages-see-also">
|
2002-07-28 17:22:21 +02:00
|
|
|
<term>See Also</term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Cross-references, listed in the following order: other
|
|
|
|
<productname>PostgreSQL</productname> command reference pages,
|
|
|
|
<productname>PostgreSQL</productname> SQL command reference
|
|
|
|
pages, citation of <productname>PostgreSQL</productname>
|
|
|
|
manuals, other reference pages (e.g., operating system, other
|
|
|
|
packages), other documentation. Items in the same group are
|
|
|
|
listed alphabetically.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
</variablelist>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Reference pages describing SQL commands should contain the
|
|
|
|
following sections: Name, Synopsis, Description, Parameters,
|
2003-09-13 00:17:24 +02:00
|
|
|
Outputs, Notes, Examples, Compatibility, History, See
|
2002-07-28 17:22:21 +02:00
|
|
|
Also. The Parameters section is like the Options section, but
|
|
|
|
there is more freedom about which clauses of the command can be
|
2003-09-13 00:17:24 +02:00
|
|
|
listed. The Outputs section is only needed if the command returns
|
|
|
|
something other than a default command-completion tag. The Compatibility
|
|
|
|
section should explain to what extent
|
2002-07-28 17:22:21 +02:00
|
|
|
this command conforms to the SQL standard(s), or to which other
|
|
|
|
database system it is compatible. The See Also section of SQL
|
|
|
|
commands should list SQL commands before cross-references to
|
|
|
|
programs.
|
|
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
</sect1>
|
1998-04-28 16:57:48 +02:00
|
|
|
</appendix>
|