diff options
Diffstat (limited to 'doc/src/sgml/docguide.sgml')
| -rw-r--r-- | doc/src/sgml/docguide.sgml | 656 |
1 files changed, 656 insertions, 0 deletions
diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml new file mode 100644 index 0000000..2d8d5cd --- /dev/null +++ b/doc/src/sgml/docguide.sgml @@ -0,0 +1,656 @@ +<!-- doc/src/sgml/docguide.sgml --> + +<appendix id="docguide"> + <title>Documentation</title> + + <para> + <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> + PDF, for printing + </para> + </listitem> + <listitem> + <para> + man pages, for quick reference. + </para> + </listitem> + </itemizedlist> + + Additionally, a number of plain-text <filename>README</filename> files can + be found throughout the <productname>PostgreSQL</productname> source tree, + documenting various implementation issues. + </para> + + <para> + <acronym>HTML</acronym> documentation and man pages are part of a + standard distribution and are installed by default. PDF + format documentation is available separately for + download. + </para> + + <sect1 id="docguide-docbook"> + <title>DocBook</title> + <para> + The documentation sources are written in + <firstterm>DocBook</firstterm>, which is a markup language + defined in <acronym>XML</acronym>. In what + follows, the terms DocBook and <acronym>XML</acronym> are both + used, but technically they are not interchangeable. + </para> + + <para> + <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 + maintained by the <ulink url="https://www.oasis-open.org"> + OASIS group</ulink>. The <ulink url="https://www.oasis-open.org/docbook/"> + official DocBook site</ulink> has good introductory and reference documentation and + a complete O'Reilly book for your online reading pleasure. The + <ulink url="http://newbiedoc.sourceforge.net/metadoc/docbook-guide.html"> + NewbieDoc Docbook Guide</ulink> is very helpful for beginners. + The <ulink url="https://www.freebsd.org/docproj/"> + FreeBSD Documentation Project</ulink> also uses DocBook and has some good + information, including a number of style guidelines that might be + worth considering. + </para> + </sect1> + + + <sect1 id="docguide-toolsets"> + <title>Tool Sets</title> + + <para> + The following tools are used to process the documentation. Some + might be optional, as noted. + + <variablelist> + <varlistentry> + <term><ulink url="https://www.oasis-open.org/docbook/">DocBook DTD</ulink></term> + <listitem> + <para> + This is the definition of DocBook itself. We currently use version + 4.5; you cannot use later or earlier versions. You need + the <acronym>XML</acronym> variant of the DocBook DTD, not + the <acronym>SGML</acronym> variant. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><ulink url="https://github.com/docbook/wiki/wiki/DocBookXslStylesheets">DocBook XSL Stylesheets</ulink></term> + <listitem> + <para> + These contain the processing instructions for converting the + DocBook sources to other formats, such as + <acronym>HTML</acronym>. + </para> + + <para> + The minimum required version is currently 1.77.0, but it is recommended + to use the latest available version for best results. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <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> + + <varlistentry> + <term><ulink url="http://xmlsoft.org/XSLT/">Libxslt</ulink> for <command>xsltproc</command></term> + <listitem> + <para> + <command>xsltproc</command> is an XSLT processor, that is, a program to + convert XML to other formats using XSLT stylesheets. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><ulink url="https://xmlgraphics.apache.org/fop/">FOP</ulink></term> + <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> + </variablelist> + </para> + + <para> + We have documented experience with several installation methods for + the various tools that are needed to process the documentation. + These will be described below. There might be some other packaged + distributions for these tools. Please report package status to the + documentation mailing list, and we will include that information + here. + </para> + + <sect2> + <title>Installation on Fedora, RHEL, and Derivatives</title> + + <para> + To install the required packages, use: +<programlisting> +yum install docbook-dtds docbook-style-xsl libxslt fop +</programlisting> + </para> + </sect2> + + <sect2> + <title>Installation on FreeBSD</title> + + <para> + To install the required packages with <command>pkg</command>, use: +<programlisting> +pkg install docbook-xml docbook-xsl libxslt fop +</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> + </sect2> + + <sect2> + <title>Debian Packages</title> + + <para> + There is a full set of packages of the documentation tools + available for <productname>Debian GNU/Linux</productname>. + To install, simply use: +<programlisting> +apt-get install docbook-xml docbook-xsl libxml2-utils xsltproc fop +</programlisting> + </para> + </sect2> + + <sect2> + <title>macOS</title> + + <para> + 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> + The Homebrew-supplied programs require the following environment variable + to be set. For Intel based machines, use this: +<programlisting> +export XML_CATALOG_FILES=/usr/local/etc/xml/catalog +</programlisting> + On Apple Silicon based machines, use this: +<programlisting> +export XML_CATALOG_FILES=/opt/homebrew/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"> + <title>Detection by <command>configure</command></title> + + <para> + Before you can build the documentation you need to run the + <filename>configure</filename> script, as you would when building + the <productname>PostgreSQL</productname> programs themselves. + Check the output near the end of the run; it should look something + like this: +<screen> +checking for xmllint... xmllint +checking for xsltproc... xsltproc +checking for fop... fop +checking for dbtoepub... dbtoepub +</screen> + 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. + </para> + + <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> + </sect2> + </sect1> + + <sect1 id="docguide-build"> + <title>Building the Documentation</title> + + <para> + Once you have everything set up, change to the directory + <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> + + <sect2> + <title>HTML</title> + + <para> + To build the <acronym>HTML</acronym> version of the documentation: +<screen> +<prompt>doc/src/sgml$ </prompt><userinput>make html</userinput> +</screen> + This is also the default target. The output appears in the + subdirectory <filename>html</filename>. + </para> + + <para> + To produce HTML documentation with the stylesheet used on <ulink + url="https://www.postgresql.org/docs/current/">postgresql.org</ulink> instead of the + default simple style use: +<screen> +<prompt>doc/src/sgml$ </prompt><userinput>make STYLE=website html</userinput> +</screen> + </para> + + <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> + </sect2> + + <sect2> + <title>Manpages</title> + + <para> + We use the DocBook XSL stylesheets to + convert <productname>DocBook</productname> + <sgmltag>refentry</sgmltag> pages to *roff output suitable for man + pages. To create the man pages, use the command: +<screen> +<prompt>doc/src/sgml$ </prompt><userinput>make man</userinput> +</screen> + </para> + </sect2> + + <sect2> + <title>PDF</title> + + <para> + 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: + + <itemizedlist> + <listitem> + <para> + For A4 format: +<screen> +<prompt>doc/src/sgml$ </prompt><userinput>make postgres-A4.pdf</userinput> +</screen> + </para> + </listitem> + + <listitem> + <para> + For U.S. letter format: +<screen> +<prompt>doc/src/sgml$ </prompt><userinput>make postgres-US.pdf</userinput> +</screen> + </para> + </listitem> + </itemizedlist> + </para> + + <para> + 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: +<programlisting> +# FOP binary distribution +FOP_OPTS='-Xmx1500m' +# Debian +JAVA_ARGS='-Xmx1500m' +# Red Hat +ADDITIONAL_FLAGS='-Xmx1500m' +</programlisting> + 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. + </para> + + <para> + Other XSL-FO processors can also be used manually, but the automated build + process only supports FOP. + </para> + </sect2> + + <sect2> + <title>Plain Text Files</title> + + <para> + The installation instructions are also distributed as plain text, + in case they are needed in a situation where better reading tools + are not available. The <filename>INSTALL</filename> file + corresponds to <xref linkend="installation"/>, with some minor + changes to account for the different context. To recreate the + file, change to the directory <filename>doc/src/sgml</filename> + and enter <userinput>make INSTALL</userinput>. Building text output + requires <productname>Pandoc</productname> version 1.13 or newer as an + additional build tool. + </para> + + <para> + In the past, the release notes and regression testing instructions + were also distributed as plain text, but this practice has been + discontinued. + </para> + </sect2> + + <sect2> + <title>Syntax Check</title> + + <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> +<prompt>doc/src/sgml$ </prompt><userinput>make check</userinput> +</screen> + </para> + </sect2> + </sect1> + + + <sect1 id="docguide-authoring"> + <title>Documentation Authoring</title> + + <para> + 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. + </para> + + <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> + + <sect2> + <title>Emacs</title> + + <para> + <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. + </para> + + <para> + <filename>src/tools/editors/emacs.samples</filename> contains + recommended settings for this mode. + </para> + </sect2> + + </sect1> + + + <sect1 id="docguide-style"> + <title>Style Guide</title> + + <sect2> + <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 + can be omitted. Additional top-level sections should only be used + in special circumstances; often that information belongs in the + <quote>Usage</quote> section. + + <variablelist> + <varlistentry> + <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> + + <varlistentry> + <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> + + <varlistentry> + <term>Description</term> + <listitem> + <para> + Several paragraphs explaining what the command does. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Options</term> + <listitem> + <para> + A list describing each command-line option. If there are a + lot of options, subsections can be used. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Exit Status</term> + <listitem> + <para> + If the program uses 0 for success and non-zero for failure, + then you do not need to document it. If there is a meaning + behind the different non-zero exit codes, list them here. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <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> + + <varlistentry> + <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> + + <varlistentry> + <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> + + <varlistentry> + <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> + + <varlistentry> + <term>Notes</term> + <listitem> + <para> + Anything that doesn't fit elsewhere, but in particular bugs, + implementation flaws, security considerations, compatibility + issues. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Examples</term> + <listitem> + <para> + Examples + </para> + </listitem> + </varlistentry> + + <varlistentry> + <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> + + <varlistentry> + <term>Author</term> + <listitem> + <para> + Author (only used in the contrib section) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <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, + Outputs, Notes, Examples, Compatibility, History, See + Also. The Parameters section is like the Options section, but + there is more freedom about which clauses of the command can be + 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 + 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> +</appendix> |