+url="http://www.berkshire.net/~norm/docbook/dsssl">Modular DocBook
+Stylesheets.
+
+Currently, hardcopy is produced by importing Rich Text
+Format (
RTF) output from
+
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
+stylesheets.
+
+
+
Styles and Conventions
+
+
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.
+
-
-
-
-
Building Documentation
-
-HTML documentation packages can be generated from the SGML source by typing
-
+
+
+
+
Document Writing
+
+
+
Document Structure
+
+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:
+
+
+
+postgres.sgml
+
+This is the integrated document, including all other documents.
+
+
+
+
+
+tutorial.sgml
+
+The introductory tutorial, with examples. Does not include programming topics,
+and is intended to help get someone unfamiliar with
SQL started.
+
+
+
+
+
+user.sgml
+
+The User's Guide. Includes information on data types and user-level interfaces.
+This is the place to put information on "why".
+
+
+
+
+
+reference.sgml
+
+The Reference Manual. Includes
Postgres SQL syntax.
+
+
+
+
+
+programming.sgml
+
+The Programmer's Guide. Includes information on
Postgres+extensibility and on the programming interfaces.
+
+
+
+
+
+admin.sgml
+
+The Administrator's Guide. Include installation and release notes.
+
+
+
+
+
+
+
Authoring Tools
+
+The current
Postgres documentation set is written using
+a plain text editor (or emacs/psgml; see below) with the content marked up using
+
+
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.
+
+
+
emacs/psgml
+
+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".
+
+
+
+
+
+
+
Building Documentation
+
+GNU
make is used to build documentation from the DocBook sources.
+There are a few environment definitions which may need to be set or modified for your installation.
+The Makefile looks for
+doc/../src/Makefile
+and (implicitly) for
+doc/../src/Makefile.custom
+to obtain environment information. On my system, the src/Makefile.custom looks like
+
+# Makefile.custom
+# Thomas Lockhart 1998-03-01
+
+POSTGRESDIR= /opt/postgres/current
+CFLAGS+= -m486
+YFLAGS+= -v
+
+# documentation
+
+HSTYLE= /home/tgl/SGML/db107.d/docbook/html
+PSTYLE= /home/tgl/SGML/db107.d/docbook/print
+
+
+where HSTYLE and PSTYLE determine the path to
docbook.dsl for
HTML+and hardcopy (print) stylesheets, respectively. These stylesheet file names are for Norm Walsh's
+Modular Style Sheets; if other stylesheets are used then one can define HDSL and PDSL as the full path
+and file name for the stylesheet, as is done above for HSTYLE and PSTYLE.
+On many systems, these stylesheets will be found in packages installed in
+/usr/lib/sgml/,
+/usr/share/lib/sgml/,
+or
+/usr/local/lib/sgml/.
+
+
HTML documentation packages can be generated from the
SGML source by
+typing
% cd doc/src
% make tutorial.tar.gz
% make user.tar.gz
% make programmer.tar.gz
% make postgres.tar.gz
% make install
-ProgramListing>
-Para>
+programlisting>
+para>
-These packages can be installed from the main documentation directory by typing
+These packages can be installed from the main documentation directory
+by typing
% cd doc
% make install
-
-
-
-
-
Toolsets
-
-
-
<ProductName>jade</ProductName>
-
-The current stable release of
jade is version 1.0.1.
-
-
-
-
Installation for Linux
-
-for
jade and related packages.
-
-
-
-
-
Installation for non-Linux Platforms
-
-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.
-
-
-
-
-
<ProductName>Modular Style Sheets</ProductName>
-
-The current stable release of the
Modular Style Sheets is version 1.0.7.
-
-
-
-
Hardcopy Generation for v6.3
-
-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:
-
+
+
+
+
+
Hardcopy Generation for v6.3
+
+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
-
-
-
-
RTF Cleanup Procedure
-
-Several items must be addressed in generating Postscript hardcopy:
-
-
Applixware RTF Cleanup
-
-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
+
+
+
+
<acronym>RTF</acronym> Cleanup Procedure
+
+Several items must be addressed in generating Postscript
+hardcopy:
+
+
Applixware <acronym>RTF</acronym> Cleanup
+
+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
+
+
+
+
+
+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,
+
+
+
+
+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.
-
-
-
-
+
+
+
+
+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.
-
-
-
-
-
-
-
-
-
Alternate Toolsets
-
-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.
-
-
-
-
<ProductName>sgml-tools</ProductName>
-
+
+
+
+
+Compress the Postscript file using
gzip.
+Place the compressed file into the doc directory.
+
+
+
+
+
+
+
+
+
Toolsets
+
+We have documented experience with two installation methods for the
+various tools that are needed to process the documentation. One is
+installation from
RPMs on
+
Linux, the other is a general installation
+from original distributions of the individual tools. Both will be
+described below.
+
+We understand that there are some other packaged distributions for
+these tools.
FreeBSD seems to have them
+available. Please report package status to the docs mailing list and
+we will include that information here.
+
+
+
<acronym>RPM</acronym> installation on</div>
<div class="diff add">+<productname>Linux</productname>
+
+and related packages.
+
+
+
+
+
Manual installation of tools
+
+
This is a brief run-through of the process of obtaining and+installing the software you'll need to edit DocBook source with Emacs
+and process it with Norman Walsh's DSSSL style sheets to create
HTML+
+Prerequisites
+
+
+
+
A working installation of GCC 2.7.2+
A working installation of Emacs 19.19 or later+
An unzip program for UNIX to unpack things+
+
+
+
+
+
+
+James Clark's
Jade version 1.1
+
+
+
+
+Norman Walsh's
Modular Stylesheets+version 1.07
+
+
+Lennart Staflin's
PSGML version 1.0.1
+
+
+
+
+
+
+
+The
Modular Stylesheets web page
+
+Steve Pepper's Whirlwind Guide
+Robin Cover's database of
SGML software
+
+
+
+
+
+
+Installing Jade
+
+
First, read the installation instructions at the above listed+URL.
+
+
Unzip the distribution kit in a suitable place. The command to do+this will be something like
+unzip -aU jade1_1.zip
+
+
+
+
GNU Autoconf, so you'll need to edit a
+Makefile yourself. Since James Clark has been
+good enough to prepare his kit for it, it is a good idea to make a
+build directory (named for your machine architecture, perhaps) under
+the main directory of the
Jade+distribution, copy the file Makefile from the
+main directory into it, edit it there, and then run
+make there.
+
+
However, the Makefile does need to be+edited. There is a file called Makefile.jade in
+the main directory, which is intended to be used with make -f
+Makefile.jade when building
Jade+(as opposed to just
SP, the
SGML parser kit
+that
Jade is built upon). We suggest that
+you don't do that, though, since there is more that you need to change
+than what is in Makefile.jade, so you'd have to
+edit one of them anyway.
+
+
Go through the Makefile, reading James'+instructions and editing as needed. There are various variables that
+need to be set. Here is a collected summary of the most important
+ones, with typical values:
+prefix = /usr/local
+XDEFINES = -DSGML_CATALOG_FILES_DEFAULT=\"/usr/local/share/sgml/catalog\"
+XLIBS = -lm
+RANLIB = ranlib
+srcdir = ..
+XLIBDIRS = grove spgrove style
+XPROGDIRS = jade
+
+Note the specification of where to find the default catalog of
+
SGML support files -- you may want to change that
+to something more suitable for your own installation. If your system
+doesn't need the above settings for the math library and the
+ranlib command, leave them as they are in the
+Makefile.
+
+
+
Now type make to build Jade and the various+
+
Once the software is built, make install will+do the obvious.
+
+
+
+Installing the <productname>DocBook</productname></div>
<div class="diff add">+<acronym>DTD</acronym> kit
+
+
You'll want to place the files that make up the+directory you built
Jade to expect them in,
+which, if you followed our suggestion above, is
+/usr/local/share/sgml/. In addition to the
+actual
DocBook files, you'll need to have a
+catalog file in place, for the mapping of
+document type specifications and external entity references to actual
+files in that directory. You'll also want the
ISO+character set mappings, and probably one or more versions of
+
+
One way to install the various DTD and+support files and set up the catalog file, is to
+collect them all into the above mentioned directory, use a single file
+named CATALOG to describe them all, and then
+create the file catalog as a catalog pointer to
+the former, by giving it the single line of content:
+CATALOG /usr/local/share/sgml/CATALOG
+
+The CATALOG file should then contain three types
+of lines. The first is the (optional)
SGML+declaration, thus:
+SGMLDECL docbook.dcl
+
+Next, the various references to
DTD and entity
+files must be resolved. For the
DocBook+files, these lines look like this:
+PUBLIC "-//Davenport//DTD DocBook V3.0//EN" docbook.dtd
+PUBLIC "-//USA-DOD//DTD Table Model 951010//EN" cals-tbl.dtd
+PUBLIC "-//Davenport//ELEMENTS DocBook Information Pool V3.0//EN" dbpool.mod
+PUBLIC "-//Davenport//ELEMENTS DocBook Document Hierarchy V3.0//EN" dbhier.mod
+PUBLIC "-//Davenport//ENTITIES DocBook Additional General Entities V3.0//EN" dbgenent.mod
+
+Of course, a file containing these comes with the
+
DocBook kit. Note that the last item on
+each of these lines is a file name, given here without a path. You
+can put the files in subdirectories of your main
+
SGML directory if you like, of course, and modify
+the reference in the CATALOG file.
+
DocBook also references the
+
ISO character set entities, so you need to fetch
+and install these (they are available from several sources, and are
+easily found by way of the URLs listed above), along with catalog
+entries for all of them, such as:
+PUBLIC "ISO 8879-1986//ENTITIES Added Latin 1//EN" ISO/ISOlat1
+
+Note how the file name here contains a directory name, showing that
+we've placed the
ISO entity files in a subdirectory
+named ISO. Again, proper catalog entries should
+accompany the entity kit you fetch.
+
+
+
+
+Installing Norman Walsh's <acronym>DSSSL</acronym></div>
<div class="diff add">+style sheets
+
+
First, read the installation instructions at the above listed+URL.
+
+
To install Norman's style sheets, simply unzip the distribution+kit in a suitable place. A good place to dot this would be
+/usr/local/share, which places the kit in a
+directory tree under /usr/local/share/docbook.
+The command will be something like
+unzip -aU db107.zip
+
+
+
+
One way to test the installation is to build the+
HTML and
RTF forms of the
+
PostgreSQL manual. Go to the
SGML source
+directory, doc/src/sgml, and say
+jade -t sgml -d /usr/local/share/docbook/html/docbook.dsl -D ../graphics postgres.sgml
+
+to build the
HTML files ("book1.htm" is the top level node), and
+jade -t rtf -d /usr/local/share/docbook/print/docbook.dsl -D ../graphics postgres.sgml
+
+to generate the
RTF output, ready for importing
+into your favorite word processing system and printing.
+
+
+
+Installing <productname>PSGML</productname>
+
+
First, read the installation instructions at the above listed+URL.
+
+
Unpack the distribution file, run configure, make and make+install to put the byte-compiled files and info library in place.
+Then add the following lines to your
+/usr/local/share/emacs/site-lisp/site-start.el
+file to make
Emacs properly load
+(setq load-path
+ (cons "/usr/local/share/emacs/site-lisp/psgml" load-path))
+(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t)
+
+If you want to use
PSGML when editing
+
HTML too, also add this:
+(setq auto-mode-alist
+ (cons '("\\.s?html?\\'" . sgml-mode) auto-mode-alist))
+
+
+
+
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. You can set the
+SGML_CATALOG_FILES environment variable, you can
+customize your
PSGML installation (its
+manual tells you how), or you can even edit the source file
+psgml.el before compiling and installing
+
PSGML, changing the hard-coded paths to
+match your own default.
+
+
+
+Optional: installing <productname>JadeTeX</productname>
+
+
If you want to, you can also install+
TeX as a formatting backend for
+
Jade. Note that this is still quite
+unpolished software, and will generate printed output that is inferior
+to what you get from the
RTF backend. Still, it
+works all right, especially for simpler documents that don't use
+tables, and as both
JadeTeX and the style
+sheets are under continuous improvement, it will certainly get better
+over time.
+
+
To install and use JadeTeX, you will+need a working installation of
TeX and
+
LaTeX2e, including the supported
+fonts and
AMS-LaTeX, the
+companion kit of "the 35 fonts", the
dvips+program for generating
PostScript, the
+macro packages
fancyhdr,
+
JadeTeX itself. All of these can be found
+on your friendly neighborhood
CTAN site.
+
+
JadeTeX does not at the time of+writing come with much of an installation guide, but there is a
+makefile which shows what is needed. It also
+includes a directory cooked, wherein you'll find
+some of the macro packages it needs, but not all, and not complete --
+at least last we looked.
+
+
Before building the jadetex.fmt format+file, you'll probably want to edit the
+jadetex.ltx file, to change the configuration of
+
Babel to suit your locality. The line to
+change looks something like
+\RequirePackage[german,french,english]{babel}[1997/01/23]
+
+and you should obviously list only the languages you actually need,
+and have configured
Babel for.
+
+
With JadeTeX working, you should be+able to generate and format
TeX output for
+the
PostgreSQL manuals by giving the
+commands (as above, in the doc/src/sgml
+directory)
+jade -t tex -d /usr/local/share/docbook/print/docbook.dsl -D ../graphics postgres.sgml
+jadetex postgres.tex
+jadetex postgres.tex
+dvips postgres.dvi
+
+Of course, when you do this,
TeX will stop
+during the second run, and tell you that its capacity has been
+exceeded. This is, as far as we can tell, because of the way
+
JadeTeX generates cross referencing
+information.
TeX can, of course, be
+compiled with larger data structure sizes. The details of this will
+vary according to your installation.
+
+
+
+
+
+
+
+
+
Alternate Toolsets
+
+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
+
+
+
+
<productname>sgml-tools</productname>
+
Install
-<ProductName>sgml-tools-0.99.0ame>
-Para>
-
-<Para>
-Apply
-
url="http://alumni.caltech.edu/~lockhart/postgres/linuxdoc/sgml-tools-patches-0.99.0.tar.gz">-<ProductName>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.
-
-
-<Sect2>
-
<ProductName>sgml2latex</ProductName>
-
-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 url="http://alumni.caltech.edu/~lockhart/postgres/linuxdoc/sgml2latex-format.1.4.tar.gz">-<ProductName>sgml2latex
-ULink>.
-
-
-<Sect2>
-
<ProductName>latex</ProductName>
-
-Get and install
texmf,
teTeX,
- or another package providing full tex/latex functionality.
-Para>
-
-<Para>
+<productname>sgml-tools-0.99.0ame>
+para>
+
+<para>
+url="http://alumni.caltech.edu/~lockhart/postgres/linuxdoc/sgml-tools-patches-0.99.0.tar.gz">
+<productname>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
+url="http://alumni.caltech.edu/~lockhart/postgres/linuxdoc/sgml2latex-format.1.4.tar.gz">
+<productname>sgml2latex .
+para>
+
+
+
+
teTeX, or another package providing full
+tex/latex functionality.
+para>
+
+<para>
Add the
- 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 -)
-
+
+url="http://alumni.caltech.edu/~lockhart/postgres/linuxdoc/latex-styles-0.99.0.tar.gz">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.
-Run
texhash to update the tex database.
-
+% cat latex-styles-0.99.0.tar.gz | (cd texmf/tex/latex/tools/; tar zxvf -)
+
+Run
texhash to update the tex database.
+
-Appendix>
+appendix>
projects / postgresql.git / commitdiff