Thomas Lockhart 1998-02-26 Postgres documentation is written using the Standard Generalized Markup Language (SGML) DocBook Document Type Definition (DTD). 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. 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 to 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. HTML documentation packages can be generated from the SGML source by typing % cd doc/src % make tutorial.tar.gz % make user.tar.gz % make admin.tar.gz % make programmer.tar.gz % make postgres.tar.gz % make install These packages can be installed from the main documentation directory by typing % cd doc % make install The current stable release of jade is version 1.0.1. Install RPMs for jade and related packages. There are some other packaged distributions for jade. FreeBSD seems to have one available. Please report package status to the docs mailing list and we will include that information here. For other platforms, install sources for jade and related packages and build from scratch. The current stable release of the Modular Style Sheets is version 1.0.7. 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. Some figures were redrawn to avoid having bitmap GIF files in the hardcopy documentation. One figure, of the system catalogs, was sufficiently complex that there was not time to redraw it. It was converted to fit using the following commands: % convert -v -geometry 400x400'>' figure03.gif con.gif % convert -v -crop 400x380 con.gif connections.gif Several items must be addressed in generating Postscript hardcopy: Applixware does not seem to do a complete job of importing RTF generated by jade/MSS. In particular, all text is given the Header1 style attribute label, although the text formatting itself is acceptable. Also, the Table of Contents page numbers do not refer to the section listed in the table, but rather refer to the page of the ToC itself. Generate the RTF input by typing % cd doc/src/sgml % make tutorial.rtf Open a new document in Applix Words and then import the RTF file. Print out the existing Table of Contents, to mark up in the following few steps. Insert figures into the document. Center each figure on the page using the centering margins button. Not all documents have figures. You can grep the SGML source files for the string Graphic to identify those parts of the documentation which may have figures. A few figures are replicated in various parts of the documentation. Work through the document, adjusting page breaks and table column widths. If a bibliography is present, Applix Words seems to mark all remaining text after the first title as having an underlined attribute. Select all remaining text, turn off underlining using the underlining button, then explicitly underline each document and book title. Work through the document, marking up the ToC hardcopy with the actual page number of each ToC entry. Replace the right-justified incorrect page numbers in the ToC with correct values. This only takes a few minutes per document. Save the document as native Applix Words format to allow easier last minute editing later. Export the document to a file in Postscript format. Compress the Postscript file using gzip. Place the compressed file into the doc directory. The current stable release of sgml-tools is version 1.0.4. The v1.0 release includes some restructuring of the directory tree to more easily support additional document styles, possibly including DocBook. The only version of sgml-tools evaluated for Postgres was v0.99.0. Install sgml-tools-0.99.0 Apply sgml-tools-patches to the linuxdoc styles. These patches fix small problems with table formatting and with figure file names on conversion to postscript or html. The current stable release of sgml2latex is version 1.4. I have misplaced the original reference for this package, so will temporarily post it with this example. Install sgml2latex . Get and install texmf, teTeX, or another package providing full tex/latex functionality. Add the required styles linuxdoc-sgml.sty, linuxdoc-sgml-a4.sty isolatin.sty, qwertz.sty, and null.sty to texmf/tex/latex/tools/ or the appropriate area. % cat latex-styles-0.99.0.tar.gz | (cd texmf/tex/latex/tools/; tar zxvf -) Run texhash to update the tex database.