J.2. Tool Sets
The following tools are used to process the documentation. Some might be optional, as noted.
- DocBook DTD
This is the definition of DocBook itself. We currently use version 4.2; you cannot use later or earlier versions. You need theSGML variant of the DocBook DTD, but to build man pages you also need theXML variant of the same version.
- ISO 8879 character entities
These are required by DocBook but are distributed separately because they are maintained by ISO.
- DocBook DSSSL Stylesheets
These contain the processing instructions for converting the DocBook sources to other formats, such asHTML.
- DocBook XSL Stylesheets
This is another stylesheet for converting DocBook to other formats. We currently use this to produce man pages and optionally HTMLHelp. You can also use this toolchain to produce HTML or PDF output, but official Postgres Pro releases use the DSSSL stylesheets for that.
The minimum required version is currently 1.74.0.
- OpenJade
This is the base package ofSGML processing. It contains anSGML parser, aDSSSL processor (that is, a program to convertSGML to other formats usingDSSSL stylesheets), as well as a number of related tools.Jade is now being maintained by the OpenJade group, no longer by James Clark.
- Libxml2 for
xmllint This library and the
xmllinttool it contains are used for processing XML. Many developers will already haveLibxml2 installed, because it is also used when building the Postgres Pro code. Note, however, thatxmllintmight need to be installed from a separate subpackage.- Libxslt for
xsltproc This is the processing tool to use with the XSLT stylesheets (like
jadeis the processing tool for DSSSL stylesheets).- JadeTeX
If you want to, you can also installJadeTeX to useTeX as a formatting backend forJade.JadeTeX can create PostScript orPDF files (the latter with bookmarks).
However, the output fromJadeTeX is inferior to what you get from theRTF backend. Particular problem areas are tables and various artifacts of vertical and horizontal spacing. Also, there is no opportunity to manually polish the results.
To install the required packages, use:
yum install docbook-dtds docbook-style-dsssl docbook-style-xsl libxslt openjade
A number of things from/usr/ports/print (tex,jadetex) might also be of interest.
More information about the FreeBSD documentation tools can be found in the FreeBSD Documentation Project's instructions.
J.2.3. Debian Packages
There is a full set of packages of the documentation tools available forDebian GNU/Linux. To install, simply use:
apt-get install docbook docbook-dsssl docbook-xsl libxml2-utils openjade1.3 opensp xsltproc
J.2.4. OS X
If you use MacPorts, the following will get you set up:
sudo port install docbook-dsssl docbook-sgml-4.2 docbook-xml-4.2 docbook-xsl libxslt openjade opensp
J.2.5. Manual Installation from Source
The manual installation process of the DocBook tools is somewhat complex, so if you have pre-built packages available, use them. We describe here only a standard setup, with reasonably standard installation paths, and no“fancy” features. For details, you should study the documentation of the respective package, and readSGML introductory material.
./configure --enable-default-catalog=/usr/local/share/sgml/catalogmakemake install
cp -R dsssl /usr/local/share/sgml
Finally, create the file
/usr/local/share/sgml/catalogand add this line to it:CATALOG "dsssl/catalog"
(This is a relative path reference to the file installed inStep 2. Be sure to adjust it if you chose your installation layout differently.)
J.2.5.2. Installing theDocBookDTD Kit
Create the directory
/usr/local/share/sgml/docbook-4.2and change to it. (The exact location is irrelevant, but this one is reasonable within the layout we are following here.)$mkdir /usr/local/share/sgml/docbook-4.2$cd /usr/local/share/sgml/docbook-4.2Unpack the archive:
$unzip -a ...../docbook-4.2.zip(The archive will unpack its files into the current directory.)
Edit the file
/usr/local/share/sgml/catalog(or whatever you told jade during installation) and put a line like this into it:CATALOG "docbook-4.2/docbook.cat"
Download the ISO 8879 character entities archive, unpack it, and put the files in the same directory you put the DocBook files in:
$cd /usr/local/share/sgml/docbook-4.2$unzip ...../ISOEnts.zipRun the following command in the directory with the DocBook and ISO files:
perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat
(This fixes a mixup between the names used in the DocBook catalog file and the actual names of the ISO character entity files.)
J.2.5.3. Installing the DocBookDSSSL Style Sheets
$gunzip docbook-dsssl-1.xx.tar.gz$tar -C /usr/local/share/sgml -xf docbook-dsssl-1.xx.tar
The usual catalog entry in/usr/local/share/sgml/catalog can also be made:
CATALOG "docbook-dsssl-1.xx/catalog"Because stylesheets change rather often, and it's sometimes beneficial to try out alternative versions,Postgres Pro doesn't use this catalog entry. SeeSection J.2.6 for information about how to select the stylesheets instead.
J.2.5.4. InstallingJadeTeX
To install and useJadeTeX, you will need a working installation ofTeX andLaTeX2e, including the supportedtools andgraphics packages,Babel,AMS fonts andAMS-LaTeX, thePSNFSS extension and companion kit of“the 35 fonts”, thedvips program for generatingPostScript, the macro packagesfancyhdr,hyperref,minitoc,url andot2enc. All of these can be found on your friendly neighborhoodCTAN site. The installation of theTeX base system is far beyond the scope of this introduction. Binary packages should be available for any system that can runTeX.
Before you can useJadeTeX with thePostgres Pro documentation sources, you will need to increase the size ofTeX's internal data structures. Details on this can be found in theJadeTeX installation instructions.
Once that is finished you can installJadeTeX:
$gunzip jadetex-xxx.tar.gz$tar xf jadetex-xxx.tar$cd jadetex$make install$mktexlsr
The last two need to be done asroot.
J.2.6. Detection byconfigure
Before you can build the documentation you need to run theconfigure script as you would when building thePostgres Pro programs themselves. Check the output near the end of the run, it should look something like this:
checking for onsgmls... onsgmlschecking for openjade... openjadechecking for DocBook V4.2... yeschecking for DocBook stylesheets... /usr/share/sgml/docbook/stylesheet/dsssl/modularchecking for collateindex.pl... /usr/bin/collateindex.plchecking for xsltproc... xsltprocchecking for osx... osx If neitheronsgmls nornsgmls were found then some of the following tests will be skipped.nsgmls is part of the Jade package. You can pass the environment variablesJADE andNSGMLS to configure to point to the programs if they are not found automatically. If“DocBook V4.2” was not found then you did not install the DocBook DTD kit in a place where Jade can find it, or you have not set up the catalog files correctly. See the installation hints above. The DocBook stylesheets are looked for in a number of relatively standard places, but if you have them some other place then you should set the environment variableDOCBOOKSTYLE to the location and rerunconfigure afterwards.