Packaged documentation is available in both HTML and Postscript formats. These are available as part of the standard Postgres installation. We discuss here working with the documentation sources and generating documentation packages.
Note: This is the first release of new Postgres documentation in three years. The content and environment are in flux and still evolving.
The purpose of SGML is to allow an author to specify the structure and content of a document (e.g. using the DocBook DTD), and to have the document style define how that content is rendered into a final form (e.g. using Norm Walsh's stylesheets).
See Introduction to DocBook for a nice "quickstart" summary of DocBook features. DocBook Elements provides a powerful cross-reference for features of DocBook.
This documentation set is constructed using several tools, including James Clark's jade and Norm Walsh's Modular DocBook Stylesheets.
Currently, hardcopy is produced by importing Rich Text Format (RTF) output from jade into ApplixWare for minor formatting fixups then exporting as a Postscript file.
TeX is a supported format for jade output, but was not used at this time for several reasons, including the inability to make minor format fixes before committing to hardcopy and generally inadequate table support in the TeX stylesheets.
DocBook has a rich set of tags and constructs, and a suprisingly large percentage are directly and obviously useful for well-formed documentation. The Postgres documentation set has only recently been adapted to SGML, and in the near future several sections of the set will be selected and maintained as prototypical examples of DocBook usage. Also, a short summary of DocBook tags will be included below.
The current Postgres documentation set is written using a plain text editor (or emacs/psgml; see below) with the content marked up using SGML.
SGML and DocBook do not suffer from an oversupply of open-source authoring tools. The most common toolset is the emacs/xemacs editing package with the psgml feature extension. On some systems (e.g. RedHat Linux) these tools are provided in a typical full installation.
When using emacs/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's 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 "-//Davenport//DTD DocBook V3.0//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".