diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml index 4b2a59602a3..03b6356134a 100644 --- a/doc/src/sgml/docguide.sgml +++ b/doc/src/sgml/docguide.sgml @@ -1,112 +1,280 @@ - - - - -Thomas -Lockhart - - -1998-02-26 - + + + + +Thomas +Lockhart + + +Tom Ivar +Helbekkmo + + +1998-04-28 + -Documentation +Documentation - -Postgres documentation is written using -the Standard Generalized Markup Language -(SGML) -DocBook -Document Type Definition (DTD). + +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. + +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. - - + + +This is the first release of new Postgres +documentation in three years. The content and environment are in flux +and still evolving. + + - -Introduction + +Introduction - -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). + +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. + +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. + +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. + +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. + + +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. - -Styles and Conventions + +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. + +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 + +Document Writing - -HTML documentation packages can be generated from the SGML source by typing + +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. + + +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 @@ -114,234 +282,574 @@ HTML documentation packages can be generated from the SGML source by typing % make programmer.tar.gz % make postgres.tar.gz % make install - - + + - -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 + +Hardcopy Generation for v6.3 - -<ProductName>jade</ProductName> + +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. - -The current stable release of jade is version 1.0.1. - + +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: - -Installation for Linux - - -Install RPMs -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: - - + % convert -v -geometry 400x400'>' figure03.gif con.gif % convert -v -crop 400x380 con.gif connections.gif - + - -RTF Cleanup Procedure + +<acronym>RTF</acronym> Cleanup Procedure - -Several items must be addressed in generating Postscript hardcopy: + +Several items must be addressed in generating Postscript +hardcopy: - -Applixware RTF Cleanup + +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. + +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 - + + +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. - - + + +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. - - + + +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. + + +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 + +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. - - + + +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, + + +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. - - + + +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. - - + + +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. - - + + +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. - - - + + +Compress the Postscript file using gzip. +Place the compressed file into the doc directory. + + + - - + + - -Alternate Toolsets + +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. - + +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. - -<ProductName>sgml-tools</ProductName> + +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 +<productname>Linux</productname> + + +Install +RPMs for Jade +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 +and RTF. + +Prerequisites + +What you need: + + +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 + + + + +What you must fetch: + + + + +James Clark's Jade version 1.1 + + + +DocBook version 3.0 + + + +Norman Walsh's Modular Stylesheets +version 1.07 + + + +Lennart Staflin's PSGML version 1.0.1 + + + + + +Important URLs: + + + +The Jade web page + +The DocBook web page + +The Modular Stylesheets web page + + + +The PSGML 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 + + + +Jade is not built using +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 +SP tools. + +Once the software is built, make install will +do the obvious. + + + +Installing the <productname>DocBook</productname> +<acronym>DTD</acronym> kit + +You'll want to place the files that make up the +DocBook DTD kit in 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 +HTML. + +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> +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 +PSGML when needed: + +(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 +JadeTeX to use +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 +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, and of course +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 +Postgres was v0.99.0. + + + +<productname>sgml-tools</productname> + + Install -sgml-tools-0.99.0 - +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. - + +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. + - -<ProductName>sgml2latex</ProductName> + +<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. - + +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 -. - + +Install +sgml2latex . + - -<ProductName>latex</ProductName> + +<productname>latex</productname> - -Get and install texmf, teTeX, - or another package providing full tex/latex functionality. - + +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. - +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. - +Run texhash to update the tex database. + - - +