PostgreSQL has four primary documentation formats: Plain text, for pre-installation information HTML, for on-line browsing and reference Postscript, for printing man pages, for quick reference. Additionally, a number of plain-text README-type files can be found throughout the PostgreSQL source tree, documenting various implementation issues. The documentation is organized into several books: Tutorial: introduction for new users User's Guide: documents the SQL implementation Reference Manual: reference pages for programs and SQL commands Administrator's Guide: installation and server maintenance Programmer's Guide: programming client applications and server extensions Developer's Guide: assorted information for developers of PostgreSQL proper All books are available as HTML and Postscript. The Reference Manual contains reference entries which are also shipped as man pages. HTML documentation and man pages are part of a standard distribution and are installed by default. 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 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 may be optional, as noted. DocBook DTD This is the definition of DocBook itself. We currently use version 3.1; you cannot use later or earlier versions. Note that there is also an XML version of DocBook -- do not use that. ISO 8879 character entities These are required by DocBook but are distributed separately because they are maintained by ISO. 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. DocBook DSSSL Stylesheets These contain the processing instructions for converting the DocBook sources to other formats, such as HTML. DocBook2X tools This optional package is used to create man pages. It has a number of prerequisite packages of its own. Check the web site. 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 may be some other packaged distributions for these tools. Please report package status to the docs mailing list and we will include that information here. Many vendors provide a complete RPM set for DocBook processing in their distribution, which is usually based on the docbook-tools effort at Red Hat Software. 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/docbook-310 textproc/iso8879 textproc/dsssl-docbook-modular 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. Be sure to have the following line in there: CATALOG "/usr/local/share/sgml/docbook/3.1/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 jade apt-get install docbook apt-get install docbook-stylesheets 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 toolchain 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 V3.1 distribution. Create the directory /usr/local/share/sgml/docbook31 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/docbook31 $ cd /usr/local/share/sgml/docbook31 Unpack the archive. $ unzip -a ...../docbk31.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 "docbook31/docbook.cat" Optionally, you can edit the file docbook.cat and comment out or remove the line containing DTDDECL. If you do not then you will get warnings from jade, but there is no further harm. 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/docbook31 $ 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 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 V3.1... yes checking for DocBook stylesheets... /usr/lib/sgml/stylesheets/nwalsh-modular checking for sgmlspl... sgmlspl If neither onsgmls nor nsgmls were found then you will not see the remaining 4 lines. nsgmls is part of the Jade package. If DocBook V3.1 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 following commands: (Remember to use GNU make.) To build the HTML version of the Administrator's Guide: doc/src/sgml$ gmake admin.html For the RTF version of the same: doc/src/sgml$ gmake admin.rtf To get a DVI version via JadeTeX: doc/src/sgml$ gmake admin.dvi And Postscript from the DVI: doc/src/sgml$ gmake admin.ps The official Postscript format documentation is generated differently. See below. The other books can be built with analogous commands by replacing admin with one of developer, programmer, tutorial, or user. Using postgres builds an integrated version of all 5 books, which is practical since the browser interface makes it easy to move around all of the documentation by just clicking. When building HTML documentation in doc/src/sgml, some of the resulting files will possibly (or quite certainly) have conflicting names between books. Therefore the files are not in that directory in the regular distribution. Instead, the files belonging to each book are stored in a tar archive that is unpacked at installation time. To create a set of HTML documentation packages use the commands cd doc/src gmake tutorial.tar.gz gmake user.tar.gz gmake admin.tar.gz gmake programmer.tar.gz gmake postgres.tar.gz gmake install In the distribution, these archives live in the doc directory and are installed by default with gmake install. We use the docbook2man utility 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 page package, use the commands cd doc/src gmake man which will result in a tar file being generated in the doc/src directory. The man build leaves a lot of confusing output, and special care must be taken to produce quality results. There is still room for improvement in this area. The hardcopy Postscript documentation is generated by converting the SGML source code to RTF, then importing into Applixware. After a little cleanup (see the following section) the output is printed to a postscript file. Several areas are addressed while generating Postscript hardcopy, including RTF repair, ToC generation, and page break adjustments. jade, an integral part of the hardcopy procedure, omits specifying a default style for body text. In the past, this undiagnosed problem led to a long process of Table of Contents (ToC) generation. However, with great help from the Applixware folks the symptom was diagnosed and a workaround is available. Generate the RTF input by typing (for example): % cd doc/src/sgml % make tutorial.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: % cd doc/src/sgml % fixrtf tutorial.rtf or % cd doc/src/sgml % fixrtf --refentry reference.rtf The script adds {\s0 Normal;} as the zero-th style in the document. According to Applixware, the RTF standard would prohibit adding an implicit zero-th style, though M$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 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 Tools.BookBuilding.CreateToC. 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 Format.Style, 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. Insert figures into the document. Center each figure on the page using the centering margins button on the Applixware toolbar. Not all documents have figures. You can grep the SGML source files for the string graphic to identify those parts of the documentation that may have figures. A few figures are replicated in various parts of the documentation. Replace the right-justified page numbers in the Examples and Figures portions of the ToC with correct values. This only takes a few minutes per document. Delete the index section from the document if it is empty. Regenerate and adjust the table of contents. Select the ToC field. Select Tools->Book Building->Create Table of Contents. Unbind the ToC by selecting Tools->Field Editing->Unprotect. 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. Compress the Postscript file using gzip. Place the compressed file into the doc directory. Several files are distributed as plain text, for reading during the installation process. The INSTALL file corresponds to the chapter in the Administrator's Guide, 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. 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) )) Currently, each SGML source file has the following block at the end of the file: <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t sgml-parent-document:nil sgml-default-dtd-file:"./reference.ced" sgml-exposed-tags:nil sgml-local-catalogs:("/usr/lib/sgml/catalog") sgml-local-ecat-files:nil End: --> This will set up a number of editing mode parameters even if you do not set up your ~/.emacs file, but it is a bit unfortunate, since if you followed the installation instructions above, then the catalog path will not match your location. Hence you might need to turn off local variables: (setq inhibit-local-variables t) The PostgreSQL distribution includes a parsed DTD definitions file reference.ced. You may 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 V3.1//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 may 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 may be used. Exit Status If the program uses 0 for success and non-zero for failure, then you don't 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, Usage, Diagnostics, 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 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.