PostgreSQL has four primary documentation formats: Plain text, for pre-installation information HTML, for on-line browsing and reference PDF or PostScript, 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 and PostScript 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. 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 variant of the DocBook DTD, but to build man pages you also need the XML variant of the same version. ISO 8879 character entities These are required by DocBook but are distributed separately because they are maintained by ISO. DocBook DSSSL Stylesheets These contain the processing instructions for converting the DocBook sources to other formats, such as HTML. DocBook XSL Stylesheets This is another stylesheet for converting DocBook to other formats. We currently use this to produce man pages and optionally HTMLHelp. You can also use this toolchain to produce HTML or PDF output, but official PostgreSQL releases use the DSSSL stylesheets for that. OpenJade This is the base package of SGML processing. It contains an SGML parser, a DSSSL processor (that is, a program to convert SGML to other formats using DSSSL stylesheets), as well as a number of related tools. Jade is now being maintained by the OpenJade group, no longer by James Clark. Libxslt for xsltproc This is the processing tool to use with the XSLT stylesheets (like jade is the processing tool for DSSSL stylesheets). JadeTeX If you want to, you can also install JadeTeX to use TeX as a formatting backend for Jade. JadeTeX can create PostScript or PDF files (the latter with bookmarks). However, the output from JadeTeX is inferior to what you get from the RTF backend. Particular problem areas are tables and various artifacts of vertical and horizontal spacing. Also, there is no opportunity to manually polish the results. 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. Most vendors provide a complete RPM set for DocBook processing in their distribution. Look for an SGML option while installing, or the following packages: sgml-common, docbook, stylesheets, openjade (or jade). Possibly sgml-tools will be needed as well. If your distributor does not provide these then you should be able to make use of the packages from some other, reasonably compatible vendor. 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/sp textproc/openjade textproc/iso8879 textproc/dsssl-docbook-modular textproc/docbook-420 A number of things from /usr/ports/print (tex, jadetex) might also be of interest. It's possible that the ports do not update the main catalog file in /usr/local/share/sgml/catalog.ports or order isn't proper . Be sure to have the following lines in begining of file: CATALOG "openjade/catalog" CATALOG "iso8879/catalog" CATALOG "docbook/dsssl/modular/catalog" CATALOG "docbook/4.2/catalog" If you do not want to edit the file you can also set the environment variable SGML_CATALOG_FILES to a colon-separated list of catalog files (such as the one above). 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-dsssl docbook-xsl openjade xsltproc 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 OpenJade offers a GNU-style ./configure; make; make install build process. Details can be found in the OpenJade source distribution. In a nutshell: ./configure --enable-default-catalog=/usr/local/share/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 jade later on. (This method is also an option if OpenJade is already installed and you want to install the rest of the tool chain locally.) Additionally, you should install the files dsssl.dtd, fot.dtd, style-sheet.dtd, and catalog from the dsssl directory somewhere, perhaps into /usr/local/share/sgml/dsssl. It's probably easiest to copy the entire directory: cp -R dsssl /usr/local/share/sgml Finally, create the file /usr/local/share/sgml/catalog and add this line to it: CATALOG "dsssl/catalog" (This is a relative path reference to the file installed in . Be sure to adjust it if you chose your installation layout differently.) 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.) To install the style sheets, unzip and untar the distribution and move it to a suitable place, for example /usr/local/share/sgml. (The archive will automatically create a subdirectory.) $ gunzip docbook-dsssl-1.xx.tar.gz $ tar -C /usr/local/share/sgml -xf docbook-dsssl-1.xx.tar The usual catalog entry in /usr/local/share/sgml/catalog can also be made: CATALOG "docbook-dsssl-1.xx/catalog" Because stylesheets change rather often, and it's sometimes beneficial to try out alternative versions, PostgreSQL doesn't use this catalog entry. See for information about how to select the stylesheets instead. To install and use JadeTeX, you will need a working installation of TeX and LaTeX2e, including the supported tools and graphics packages, Babel, AMS fonts and AMS-LaTeX, the PSNFSS extension and companion kit of the 35 fonts, the dvips program for generating PostScript, the macro packages fancyhdr, hyperref, minitoc, url and ot2enc. All of these can be found on your friendly neighborhood CTAN site. The installation of the TeX base system is far beyond the scope of this introduction. Binary packages should be available for any system that can run TeX. Before you can use JadeTeX with the PostgreSQL documentation sources, you will need to increase the size of TeX's internal data structures. Details on this can be found in the JadeTeX installation instructions. Once that is finished you can install JadeTeX: $ gunzip jadetex-xxx.tar.gz $ tar xf jadetex-xxx.tar $ cd jadetex $ make install $ mktexlsr The last two need to be done as root. 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 openjade... openjade checking for DocBook V4.2... yes checking for DocBook stylesheets... /usr/share/sgml/docbook/stylesheet/dsssl/modular checking for collateindex.pl... /usr/bin/collateindex.pl checking for xsltproc... xsltproc checking for osx... osx If neither onsgmls nor nsgmls were found then some of the following tests will be skipped. nsgmls is part of the Jade package. You can pass the environment variables JADE and 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 Jade can find it, or you have not set up the catalog files correctly. See the installation hints above. The DocBook stylesheets are looked for in a number of relatively standard places, but if you have them some other place then you should set the environment variable DOCBOOKSTYLE to the location and rerun configure afterwards. 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$ gmake html This is also the default target. The output appears in the subdirectory html. To create a proper index, the build might process several identical stages. If you do not care about the index, and just want to proof-read the output, use draft: doc/src/sgml$ gmake draft 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: cd doc/src/sgml gmake man If you want to use JadeTex to produce a printable rendition of the documentation, you can use one of the following commands: To generate PostScript via DVI in A4 format: doc/src/sgml$ gmake postgres-A4.ps In U.S. letter format: doc/src/sgml$ gmake postgres-US.ps To make a PDF: doc/src/sgml$ gmake postgres-A4.pdf or: doc/src/sgml$ gmake postgres-US.pdf (Of course you can also make a PDF version from the PostScript, but if you generate PDF directly, it will have hyperlinks and other enhanced features.) When using JadeTeX to build the PostgreSQL documentation, you will probably need to increase some of TeX's internal parameters. These can be set in the file texmf.cnf. The following settings worked at the time of this writing: hash_extra.jadetex = 200000 hash_extra.pdfjadetex = 200000 pool_size.jadetex = 2000000 pool_size.pdfjadetex = 2000000 string_vacancies.jadetex = 150000 string_vacancies.pdfjadetex = 150000 max_strings.jadetex = 300000 max_strings.pdfjadetex = 300000 save_size.jadetex = 15000 save_size.pdfjadetex = 15000 Occasionally text is too wide for the printed margins, and in extreme cases, too wide for the printed page, e.g. non-wrapped text, wide tables. Overly wide text generates Overfull hbox messages in the TeX log output file, e.g. postgres-US.log or postgres-A4.log. There are 72 points in an inch so anything reported as over 72 points too wide will probably not fit on the printed page (assuming one inch margins). To find the SGML text causing the overflow, find the first page number mentioned above the overflow message, e.g. [50 ###] (page 50), and look at that page in the PDF file to see the overflow text and adjust the SGML accordingly. You can also create a printable version of the PostgreSQL documentation by converting it to RTF and applying minor formatting corrections using an office suite. Depending on the capabilities of the particular office suite, you can then convert the documentation to PostScript of PDF. The procedure below illustrates this process using Applixware. It appears that current versions of the PostgreSQL documentation trigger some bug in or exceed the size limit of OpenJade. If the build process of the RTF version hangs for a long time and the output file still has size 0, then you might have hit that problem. (But keep in mind that a normal build takes 5 to 10 minutes, so don't abort too soon.) OpenJade omits specifying a default style for body text. In the past, this undiagnosed problem led to a long process of table of contents generation. However, with great help from the Applixware folks the symptom was diagnosed and a workaround is available. Generate the RTF version by typing: doc/src/sgml$ gmake postgres.rtf Repair the RTF file to correctly specify all styles, in particular the default style. If the document contains refentry sections, one must also replace formatting hints which tie a preceding paragraph to the current paragraph, and instead tie the current paragraph to the following one. A utility, fixrtf, is available in doc/src/sgml to accomplish these repairs: doc/src/sgml$ ./fixrtf --refentry postgres.rtf The script adds {\s0 Normal;} as the zeroth style in the document. According to Applixware, the RTF standard would prohibit adding an implicit zeroth style, though Microsoft Word happens to handle this case. For repairing refentry sections, the script replaces \keepn tags with \keep. Open a new document in Applixware Words and then import the RTF file. Generate a new table of contents (ToC) using Applixware. Select the existing ToC lines, from the beginning of the first character on the first line to the last character of the last line. Build a new ToC using ToolsBook BuildingCreate Table of Contents. Select the first three levels of headers for inclusion in the ToC. This will replace the existing lines imported in the RTF with a native Applixware ToC. Adjust the ToC formatting by using FormatStyle, selecting each of the three ToC styles, and adjusting the indents for First and Left. Use the following values: Style First Indent (inches) Left Indent (inches) TOC-Heading 1 0.4 0.4 TOC-Heading 2 0.8 0.8 TOC-Heading 3 1.2 1.2 Work through the document to: Adjust page breaks. Adjust table column widths. Replace the right-justified page numbers in the Examples and Figures portions of the ToC with correct values. This only takes a few minutes. Delete the index section from the document if it is empty. Regenerate and adjust the table of contents. Select the ToC field. Select ToolsBook BuildingCreate Table of Contents. Unbind the ToC by selecting ToolsField EditingUnprotect. Delete the first line in the ToC, which is an entry for the ToC itself. Save the document as native Applixware Words format to allow easier last minute editing later. Print the document to a file in PostScript format. Several files are distributed as plain text, for reading during the installation process. 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 gmake INSTALL. This will create a file INSTALL.html that can be saved as text with Netscape Navigator and put into the place of the existing file. Netscape seems to offer the best quality for HTML to text conversions (over lynx and w3m). The file HISTORY can be created similarly, using the command gmake HISTORY. For the file src/test/regress/README the command is gmake regress_README. 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$ gmake 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-default-dtd-file "./reference.ced") (setq sgml-exposed-tags nil) (setq sgml-catalog-files '("/usr/local/share/sgml/catalog")) (setq sgml-ecat-files nil) (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) )) The PostgreSQL distribution includes a parsed DTD definitions file reference.ced. 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. 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. 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.