Documentation sources include plain text files, man pages, and html. However, most new Postgres documentation will be written using the Standard Generalized Markup Language (SGML) DocBook Document Type Definition (DTD). Much of the existing documentation has been or will be converted to SGML.
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).
Documentation has accumulated from several sources. As we integrate and assimilate existing documentation into a coherent documentation set, the older versions will become obsolete and will be removed from the distribution. However, this will not happen immediately, and will not happen to all documents at the same time. To ease the transition, and to help guide developers and writers, we have defined a transition roadmap.
Here is the documentation plan for v6.5:
Start compiling index information for the User's and Administrator's Guides.
Write more sections for the User's Guide covering areas outside the reference pages. This would include introductory information and suggestions for approaches to typical design problems.
Merge information in the existing man pages into the reference pages and User's Guide. Condense the man pages down to reminder information, with references into the primary doc set.
Convert the new sgml reference pages to new man pages, replacing the existing man pages.
Convert all source graphics to CGM format files for portability. Currently we mostly have Applix Graphics sources from which we can generate .gif output. One graphic is only available in .gif and .ps, and should be redrawn or removed.
There are currently five separate documents written in DocBook. Each document has a container source document which defines the DocBook environment and other document source files. These primary source files are located in doc/src/sgml/, along with many of the other source files used for the documentation. The primary source files are:
This is the integrated document, including all other documents as parts. Output is generated in HTML since the browser interface makes it easy to move around all of the documentation by just clicking. The other documents are available in both HTML and hardcopy.
The introductory tutorial, with examples. Does not include programming topics, and is intended to help a reader unfamiliar with SQL. This is the "getting started" document.
The User's Guide. Includes information on data types and user-level interfaces. This is the place to put information on "why".
The Reference Manual. Includes Postgres SQL syntax. This is the place to put information on "how".
The Programmer's Guide. Includes information on Postgres extensibility and on the programming interfaces.
The Administrator's Guide. Include installation and release notes.