PostgreSQL has four primary documentation formats: Plain text, for pre-installation information HTML, for on-line browsing and reference PDF, for printing man pages, for quick reference. Additionally, a number of plain-text README files can be found throughout the PostgreSQL source tree, documenting various implementation issues. HTML documentation and man pages are part of a standard distribution and are installed by default. PDF format documentation is available separately for download. The documentation sources are written in DocBook, which is a markup language superficially similar to HTML. Both of these languages are applications of the Standard Generalized Markup Language, SGML, which is essentially a language for describing other languages. In what follows, the terms DocBook and SGML are both used, but technically they are not interchangeable. The PostgreSQL documentation is currently being transitioned from DocBook SGML and DSSSL style sheets to DocBook XML and XSLT style sheets. Be careful to look at the instructions relating to the PostgreSQL version you are dealing with, as the procedures and required tools will change. DocBook 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 OASIS group. The official DocBook site has good introductory and reference documentation and a complete O'Reilly book for your online reading pleasure. The NewbieDoc Docbook Guide is very helpful for beginners. The FreeBSD Documentation Project also uses DocBook and has some good information, including a number of style guidelines that might be worth considering. The following tools are used to process the documentation. Some might be optional, as noted. DocBook DTD This is the definition of DocBook itself. We currently use version 4.2; you cannot use later or earlier versions. You need the SGML and the XML variant of the DocBook DTD of the same version. These will usually be in separate packages. ISO 8879 character entities These are required by DocBook SGML but are distributed separately because they are maintained by ISO. DocBook XSL Stylesheets These contain the processing instructions for converting the DocBook sources to other formats, such as HTML. The minimum required version is currently 1.77.0, but it is recommended to use the latest available version for best results. OpenSP This is the base package of SGML processing. Note that we no longer need OpenJade, the DSSSL processor, only the OpenSP package for converting SGML to XML. Libxml2 for xmllint This library and the xmllint tool it contains are used for processing XML. Many developers will already have Libxml2 installed, because it is also used when building the PostgreSQL code. Note, however, that xmllint might need to be installed from a separate subpackage. Libxslt for xsltproc xsltproc is an XSLT processor, that is, a program to convert XML to other formats using XSLT stylesheets. FOP This is a program for converting, among other things, XML to PDF. 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. 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 especially the stylesheets or if no packages are available at all. See the --nonet option for xmllint and xsltproc for more information. To install the required packages, use: yum install docbook-dtds docbook-style-xsl fop libxslt opensp The FreeBSD Documentation Project is itself a heavy user of DocBook, so it comes as no surprise that there is a full set of ports of the documentation tools available on FreeBSD. The following ports need to be installed to build the documentation on FreeBSD. textproc/docbook-sgml textproc/docbook-xml textproc/docbook-xsl textproc/dsssl-docbook-modular textproc/libxslt textproc/fop textproc/opensp To install the required packages with pkg, use: pkg install docbook-sgml docbook-xml docbook-xsl fop libxslt opensp When building the documentation from the doc directory you'll need to use gmake, because the makefile provided is not suitable for FreeBSD's make. More information about the FreeBSD documentation tools can be found in the FreeBSD Documentation Project's instructions. There is a full set of packages of the documentation tools available for Debian GNU/Linux. To install, simply use: apt-get install docbook docbook-xml docbook-xsl fop libxml2-utils opensp xsltproc If you use MacPorts, the following will get you set up: sudo port install docbook-sgml-4.2 docbook-xml-4.2 docbook-xsl fop libxslt opensp The manual installation process of the DocBook tools is somewhat complex, so if you have pre-built packages available, use them. We describe here only a standard setup, with reasonably standard installation paths, and no fancy features. For details, you should study the documentation of the respective package, and read SGML introductory material. The installation of OpenSP offers a GNU-style ./configure; make; make install build process. Details can be found in the OpenSP source distribution. In a nutshell: ./configure --enable-default-catalog=/usr/local/etc/sgml/catalog make make install Be sure to remember where you put the default catalog; you will need it below. You can also leave it off, but then you will have to set the environment variable SGML_CATALOG_FILES to point to the file whenever you use any programs from OpenSP later on. (This method is also an option if OpenSP is already installed and you want to install the rest of the toolchain locally.) Obtain the DocBook V4.2 distribution. Create the directory /usr/local/share/sgml/docbook-4.2 and change to it. (The exact location is irrelevant, but this one is reasonable within the layout we are following here.) $ mkdir /usr/local/share/sgml/docbook-4.2 $ cd /usr/local/share/sgml/docbook-4.2 Unpack the archive: $ unzip -a ...../docbook-4.2.zip (The archive will unpack its files into the current directory.) Edit the file /usr/local/share/sgml/catalog (or whatever you told jade during installation) and put a line like this into it: CATALOG "docbook-4.2/docbook.cat" Download the ISO 8879 character entities archive, unpack it, and put the files in the same directory you put the DocBook files in: $ cd /usr/local/share/sgml/docbook-4.2 $ unzip ...../ISOEnts.zip Run the following command in the directory with the DocBook and ISO files: perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat (This fixes a mixup between the names used in the DocBook catalog file and the actual names of the ISO character entity files.) Before you can build the documentation you need to run the configure script as you would when building the PostgreSQL programs themselves. Check the output near the end of the run, it should look something like this: checking for onsgmls... onsgmls checking for DocBook V4.2... yes checking for dbtoepub... dbtoepub checking for xmllint... xmllint checking for xsltproc... xsltproc checking for osx... osx checking for fop... fop If neither onsgmls nor nsgmls were found then some of the following tests will be skipped. nsgmls is part of the OpenSP package. You can pass the environment variable NSGMLS to configure to point to the programs if they are not found automatically. If DocBook V4.2 was not found then you did not install the DocBook DTD kit in a place where OpenSP can find it, or you have not set up the catalog files correctly. See the installation hints above. Once you have everything set up, change to the directory doc/src/sgml and run one of the commands described in the following subsections to build the documentation. (Remember to use GNU make.) To build the HTML version of the documentation: doc/src/sgml$ make html This is also the default target. The output appears in the subdirectory html. To produce HTML documentation with the stylesheet used on postgresql.org instead of the default simple style use: doc/src/sgml$ make STYLE=website html We use the DocBook XSL stylesheets to convert DocBook refentry pages to *roff output suitable for man pages. The man pages are also distributed as a tar archive, similar to the HTML version. To create the man pages, use the commands: doc/src/sgml$ make man To produce a PDF rendition of the documentation using FOP, you can use one of the following commands, depending on the preferred paper format: For A4 format: doc/src/sgml$ make postgres-A4.pdf For U.S. letter format: doc/src/sgml$ make postgres-US.pdf Because the PostgreSQL documentation is fairly big, FOP 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 ~/.foprc, for example: # FOP binary distribution FOP_OPTS='-Xmx1000m' # Debian JAVA_ARGS='-Xmx1000m' # Red Hat ADDITIONAL_FLAGS='-Xmx1000m' 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. Other XSL-FO processors can also be used manually, but the automated build process only supports FOP. 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 INSTALL file corresponds to , with some minor changes to account for the different context. To recreate the file, change to the directory doc/src/sgml and enter make INSTALL. In the past, the release notes and regression testing instructions were also distributed as plain text, but this practice has been discontinued. 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: doc/src/sgml$ make check SGML and DocBook do not suffer from an oversupply of open-source authoring tools. The most common tool set is the Emacs/XEmacs editor with appropriate editing mode. On some systems these tools are provided in a typical full installation. PSGML is the most common and most powerful mode for editing SGML documents. When properly configured, it will allow you to use Emacs to insert tags and check markup consistency. You could use it for HTML as well. Check the PSGML web site for downloads, installation instructions, and detailed documentation. There is one important thing to note with PSGML: its author assumed that your main SGML DTD directory would be /usr/local/lib/sgml. If, as in the examples in this chapter, you use /usr/local/share/sgml, you have to compensate for this, either by setting SGML_CATALOG_FILES environment variable, or you can customize your PSGML installation (its manual tells you how). Put the following in your ~/.emacs environment file (adjusting the path names to be appropriate for your system): ; ********** for SGML mode (psgml) (setq sgml-omittag t) (setq sgml-shorttag t) (setq sgml-minimize-attributes nil) (setq sgml-always-quote-attributes t) (setq sgml-indent-step 1) (setq sgml-indent-data t) (setq sgml-parent-document nil) (setq sgml-exposed-tags nil) (setq sgml-catalog-files '("/usr/local/share/sgml/catalog")) (autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t ) and in the same file add an entry for SGML into the (existing) definition for auto-mode-alist: (setq auto-mode-alist '(("\\.sgml$" . sgml-mode) )) You might find that when using PSGML, a comfortable way of working with these separate files of book parts is to insert a proper DOCTYPE declaration while you're editing them. If you are working on this source, for instance, it is an appendix chapter, so you would specify the document as an appendix instance of a DocBook document by making the first line look like this: <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.2//EN"> This means that anything and everything that reads SGML will get it right, and I can verify the document with nsgmls -s docguide.sgml. (But you need to take out that line before building the entire documentation set.) GNU Emacs ships with a different SGML mode, which is not quite as powerful as PSGML, but it's less confusing and lighter weight. Also, it offers syntax highlighting (font lock), which can be very helpful. src/tools/editors/emacs.samples contains sample settings for this mode. Norm Walsh offers a major mode specifically for DocBook which also has font-lock and a number of features to reduce typing. 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 PostgreSQL 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. 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 Usage section. Name This section is generated automatically. It contains the command name and a half-sentence summary of its functionality. Synopsis 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. Description Several paragraphs explaining what the command does. Options A list describing each command-line option. If there are a lot of options, subsections can be used. Exit Status 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. Usage 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. Environment List all environment variables that the program might use. Try to be complete; even seemingly trivial variables like SHELL might be of interest to the user. Files 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. Diagnostics 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. Notes Anything that doesn't fit elsewhere, but in particular bugs, implementation flaws, security considerations, compatibility issues. Examples Examples History If there were some major milestones in the history of the program, they might be listed here. Usually, this section can be omitted. Author Author (only used in the contrib section) See Also Cross-references, listed in the following order: other PostgreSQL command reference pages, PostgreSQL SQL command reference pages, citation of PostgreSQL manuals, other reference pages (e.g., operating system, other packages), other documentation. Items in the same group are listed alphabetically. 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.