<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <HTML ><HEAD ><TITLE >Tool Sets</TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK REV="MADE" HREF="mailto:pgsql-docs@postgresql.org"><LINK REL="HOME" TITLE="PostgreSQL 8.0.11 Documentation" HREF="index.html"><LINK REL="UP" TITLE="Documentation" HREF="docguide.html"><LINK REL="PREVIOUS" TITLE="Documentation" HREF="docguide.html"><LINK REL="NEXT" TITLE="Building The Documentation" HREF="docguide-build.html"><LINK REL="STYLESHEET" TYPE="text/css" HREF="stylesheet.css"><META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1"><META NAME="creation" CONTENT="2007-02-02T03:57:22"></HEAD ><BODY CLASS="SECT1" ><DIV CLASS="NAVHEADER" ><TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TH COLSPAN="5" ALIGN="center" VALIGN="bottom" >PostgreSQL 8.0.11 Documentation</TH ></TR ><TR ><TD WIDTH="10%" ALIGN="left" VALIGN="top" ><A HREF="docguide.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="10%" ALIGN="left" VALIGN="top" ><A HREF="docguide.html" >Fast Backward</A ></TD ><TD WIDTH="60%" ALIGN="center" VALIGN="bottom" >Appendix G. Documentation</TD ><TD WIDTH="10%" ALIGN="right" VALIGN="top" ><A HREF="docguide.html" >Fast Forward</A ></TD ><TD WIDTH="10%" ALIGN="right" VALIGN="top" ><A HREF="docguide-build.html" ACCESSKEY="N" >Next</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><DIV CLASS="SECT1" ><H1 CLASS="SECT1" ><A NAME="DOCGUIDE-TOOLSETS" >G.2. Tool Sets</A ></H1 ><P > The following tools are used to process the documentation. Some may be optional, as noted. <P ></P ></P><DIV CLASS="VARIABLELIST" ><DL ><DT ><A HREF="http://www.oasis-open.org/docbook/sgml/" TARGET="_top" >DocBook DTD</A ></DT ><DD ><P > This is the definition of DocBook itself. We currently use version 4.2; you cannot use later or earlier versions. Note that there is also an <ACRONYM CLASS="ACRONYM" >XML</ACRONYM > version of DocBook — do not use that. </P ></DD ><DT ><A HREF="http://www.oasis-open.org/cover/ISOEnts.zip" TARGET="_top" >ISO 8879 character entities</A ></DT ><DD ><P > These are required by DocBook but are distributed separately because they are maintained by ISO. </P ></DD ><DT ><A HREF="http://openjade.sourceforge.net" TARGET="_top" >OpenJade</A ></DT ><DD ><P > This is the base package of <ACRONYM CLASS="ACRONYM" >SGML</ACRONYM > processing. It contains an <ACRONYM CLASS="ACRONYM" >SGML</ACRONYM > parser, a <ACRONYM CLASS="ACRONYM" >DSSSL</ACRONYM > processor (that is, a program to convert <ACRONYM CLASS="ACRONYM" >SGML</ACRONYM > to other formats using <ACRONYM CLASS="ACRONYM" >DSSSL</ACRONYM > stylesheets), as well as a number of related tools. <SPAN CLASS="PRODUCTNAME" >Jade</SPAN > is now being maintained by the OpenJade group, no longer by James Clark. </P ></DD ><DT ><A HREF="http://docbook.sourceforge.net/projects/dsssl/index.html" TARGET="_top" >DocBook DSSSL Stylesheets</A ></DT ><DD ><P > These contain the processing instructions for converting the DocBook sources to other formats, such as <ACRONYM CLASS="ACRONYM" >HTML</ACRONYM >. </P ></DD ><DT ><A HREF="http://docbook2x.sourceforge.net" TARGET="_top" >DocBook2X tools</A ></DT ><DD ><P > This optional package is used to create man pages. It has a number of prerequisite packages of its own. Check the web site. </P ></DD ><DT ><A HREF="http://jadetex.sourceforge.net" TARGET="_top" >JadeTeX</A ></DT ><DD ><P > If you want to, you can also install <SPAN CLASS="PRODUCTNAME" >JadeTeX</SPAN > to use <SPAN CLASS="PRODUCTNAME" >TeX</SPAN > as a formatting backend for <SPAN CLASS="PRODUCTNAME" >Jade</SPAN >. <SPAN CLASS="APPLICATION" >JadeTeX</SPAN > can create Postscript or <ACRONYM CLASS="ACRONYM" >PDF</ACRONYM > files (the latter with bookmarks). </P ><P > However, the output from <SPAN CLASS="APPLICATION" >JadeTeX</SPAN > is inferior to what you get from the <ACRONYM CLASS="ACRONYM" >RTF</ACRONYM > backend. Particular problem areas are tables and various artifacts of vertical and horizontal spacing. Also, there is no opportunity to manually polish the results. </P ></DD ></DL ></DIV ><P> </P ><P > We have documented experience with several installation methods for the various tools that are needed to process the documentation. These will be described below. There may be some other packaged distributions for these tools. Please report package status to the documentation mailing list, and we will include that information here. </P ><DIV CLASS="SECT2" ><H2 CLASS="SECT2" ><A NAME="AEN74866" >G.2.1. <SPAN CLASS="PRODUCTNAME" >Linux</SPAN > <ACRONYM CLASS="ACRONYM" >RPM</ACRONYM > Installation</A ></H2 ><P > Most vendors provide a complete RPM set for DocBook processing in their distribution. Look for an <SPAN CLASS="QUOTE" >"SGML"</SPAN > option while installing, or the following packages: <TT CLASS="FILENAME" >sgml-common</TT >, <TT CLASS="FILENAME" >docbook</TT >, <TT CLASS="FILENAME" >stylesheets</TT >, <TT CLASS="FILENAME" >openjade</TT > (or <TT CLASS="FILENAME" >jade</TT >). Possibly <TT CLASS="FILENAME" >sgml-tools</TT > will be needed as well. If your distributor does not provide these then you should be able to make use of the packages from some other, reasonably compatible vendor. </P ></DIV ><DIV CLASS="SECT2" ><H2 CLASS="SECT2" ><A NAME="AEN74878" >G.2.2. FreeBSD Installation</A ></H2 ><P > The FreeBSD Documentation Project is itself a heavy user of DocBook, so it comes as no surprise that there is a full set of <SPAN CLASS="QUOTE" >"ports"</SPAN > of the documentation tools available on FreeBSD. The following ports need to be installed to build the documentation on FreeBSD. <P ></P ></P><UL ><LI ><P ><TT CLASS="FILENAME" >textproc/sp</TT ></P ></LI ><LI ><P ><TT CLASS="FILENAME" >textproc/openjade</TT ></P ></LI ><LI ><P ><TT CLASS="FILENAME" >textproc/iso8879</TT ></P ></LI ><LI ><P ><TT CLASS="FILENAME" >textproc/dsssl-docbook-modular</TT ></P ></LI ></UL ><P> Apparently, there is no port for the DocBook V4.2 SGML DTD available right now. You will need to install it manually. </P ><P > A number of things from <TT CLASS="FILENAME" >/usr/ports/print</TT > (<TT CLASS="FILENAME" >tex</TT >, <TT CLASS="FILENAME" >jadetex</TT >) might also be of interest. </P ><P > It's possible that the ports do not update the main catalog file in <TT CLASS="FILENAME" >/usr/local/share/sgml/catalog</TT >. Be sure to have the following line in there: </P><PRE CLASS="PROGRAMLISTING" >CATALOG "/usr/local/share/sgml/docbook/4.2/docbook.cat"</PRE ><P> If you do not want to edit the file you can also set the environment variable <TT CLASS="ENVAR" >SGML_CATALOG_FILES</TT > to a colon-separated list of catalog files (such as the one above). </P ><P > More information about the FreeBSD documentation tools can be found in the <A HREF="http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/tools.html" TARGET="_top" >FreeBSD Documentation Project's instructions</A >. </P ></DIV ><DIV CLASS="SECT2" ><H2 CLASS="SECT2" ><A NAME="AEN74905" >G.2.3. Debian Packages</A ></H2 ><P > There is a full set of packages of the documentation tools available for <SPAN CLASS="PRODUCTNAME" >Debian GNU/Linux</SPAN >. To install, simply use: </P><PRE CLASS="PROGRAMLISTING" >apt-get install jade apt-get install docbook apt-get install docbook-stylesheets</PRE ><P> </P ></DIV ><DIV CLASS="SECT2" ><H2 CLASS="SECT2" ><A NAME="AEN74910" >G.2.4. Manual Installation from Source</A ></H2 ><P > 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 <SPAN CLASS="QUOTE" >"fancy"</SPAN > features. For details, you should study the documentation of the respective package, and read <ACRONYM CLASS="ACRONYM" >SGML</ACRONYM > introductory material. </P ><DIV CLASS="SECT3" ><H3 CLASS="SECT3" ><A NAME="AEN74915" >G.2.4.1. Installing OpenJade</A ></H3 ><DIV CLASS="PROCEDURE" ><OL TYPE="1" ><LI CLASS="STEP" ><P > The installation of OpenJade offers a GNU-style <TT CLASS="LITERAL" >./configure; make; make install</TT > build process. Details can be found in the OpenJade source distribution. In a nutshell: </P><PRE CLASS="SYNOPSIS" >./configure --enable-default-catalog=/usr/local/share/sgml/catalog make make install</PRE ><P> Be sure to remember where you put the <SPAN CLASS="QUOTE" >"default catalog"</SPAN >; you will need it below. You can also leave it off, but then you will have to set the environment variable <TT CLASS="ENVAR" >SGML_CATALOG_FILES</TT > to point to the file whenever you use <SPAN CLASS="APPLICATION" >jade</SPAN > later on. (This method is also an option if OpenJade is already installed and you want to install the rest of the toolchain locally.) </P ></LI ><LI CLASS="STEP" ><A NAME="DOC-OPENJADE-INSTALL" ></A ><P > Additionally, you should install the files <TT CLASS="FILENAME" >dsssl.dtd</TT >, <TT CLASS="FILENAME" >fot.dtd</TT >, <TT CLASS="FILENAME" >style-sheet.dtd</TT >, and <TT CLASS="FILENAME" >catalog</TT > from the <TT CLASS="FILENAME" >dsssl</TT > directory somewhere, perhaps into <TT CLASS="FILENAME" >/usr/local/share/sgml/dsssl</TT >. It's probably easiest to copy the entire directory: </P><PRE CLASS="SYNOPSIS" >cp -R dsssl /usr/local/share/sgml</PRE ><P> </P ></LI ><LI CLASS="STEP" ><P > Finally, create the file <TT CLASS="FILENAME" >/usr/local/share/sgml/catalog</TT > and add this line to it: </P><PRE CLASS="PROGRAMLISTING" >CATALOG "dsssl/catalog"</PRE ><P> (This is a relative path reference to the file installed in <A HREF="docguide-toolsets.html#DOC-OPENJADE-INSTALL" >step 2</A >. Be sure to adjust it if you chose your installation layout differently.) </P ></LI ></OL ></DIV ></DIV ><DIV CLASS="SECT3" ><H3 CLASS="SECT3" ><A NAME="AEN74939" >G.2.4.2. Installing the <SPAN CLASS="PRODUCTNAME" >DocBook</SPAN > <ACRONYM CLASS="ACRONYM" >DTD</ACRONYM > Kit</A ></H3 ><DIV CLASS="PROCEDURE" ><OL TYPE="1" ><LI CLASS="STEP" ><P > Obtain the <A HREF="http://www.docbook.org/sgml/4.2/docbook-4.2.zip" TARGET="_top" >DocBook V4.2</A > distribution. </P ></LI ><LI CLASS="STEP" ><P > Create the directory <TT CLASS="FILENAME" >/usr/local/share/sgml/docbook-4.2</TT > and change to it. (The exact location is irrelevant, but this one is reasonable within the layout we are following here.) </P><PRE CLASS="SCREEN" ><SAMP CLASS="PROMPT" >$ </SAMP ><KBD CLASS="USERINPUT" >mkdir /usr/local/share/sgml/docbook-4.2</KBD > <SAMP CLASS="PROMPT" >$ </SAMP ><KBD CLASS="USERINPUT" >cd /usr/local/share/sgml/docbook-4.2</KBD ></PRE ><P> </P ></LI ><LI CLASS="STEP" ><P > Unpack the archive. </P><PRE CLASS="SCREEN" ><SAMP CLASS="PROMPT" >$ </SAMP ><KBD CLASS="USERINPUT" >unzip -a ...../docbook-4.2.zip</KBD ></PRE ><P> (The archive will unpack its files into the current directory.) </P ></LI ><LI CLASS="STEP" ><P > Edit the file <TT CLASS="FILENAME" >/usr/local/share/sgml/catalog</TT > (or whatever you told jade during installation) and put a line like this into it: </P><PRE CLASS="PROGRAMLISTING" >CATALOG "docbook-4.2/docbook.cat"</PRE ><P> </P ></LI ><LI CLASS="STEP" ><P > Download the <A HREF="http://www.oasis-open.org/cover/ISOEnts.zip" TARGET="_top" >ISO 8879 character entities</A > archive, unpack it, and put the files in the same directory you put the DocBook files in. </P><PRE CLASS="SCREEN" ><SAMP CLASS="PROMPT" >$ </SAMP ><KBD CLASS="USERINPUT" >cd /usr/local/share/sgml/docbook-4.2</KBD > <SAMP CLASS="PROMPT" >$ </SAMP ><KBD CLASS="USERINPUT" >unzip ...../ISOEnts.zip</KBD ></PRE ><P> </P ></LI ><LI CLASS="STEP" ><P > Run the following command in the directory with the DocBook and ISO files: </P><PRE CLASS="PROGRAMLISTING" >perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat</PRE ><P> (This fixes a mixup between the names used in the DocBook catalog file and the actual names of the ISO character entity files.) </P ></LI ></OL ></DIV ></DIV ><DIV CLASS="SECT3" ><H3 CLASS="SECT3" ><A NAME="AEN74975" >G.2.4.3. Installing the DocBook <ACRONYM CLASS="ACRONYM" >DSSSL</ACRONYM > Style Sheets</A ></H3 ><P > To install the style sheets, unzip and untar the distribution and move it to a suitable place, for example <TT CLASS="FILENAME" >/usr/local/share/sgml</TT >. (The archive will automatically create a subdirectory.) </P><PRE CLASS="SCREEN" ><SAMP CLASS="PROMPT" >$</SAMP > <KBD CLASS="USERINPUT" >gunzip docbook-dsssl-1.<TT CLASS="REPLACEABLE" ><I >xx</I ></TT >.tar.gz</KBD > <SAMP CLASS="PROMPT" >$</SAMP > <KBD CLASS="USERINPUT" >tar -C /usr/local/share/sgml -xf docbook-dsssl-1.<TT CLASS="REPLACEABLE" ><I >xx</I ></TT >.tar</KBD ></PRE ><P> </P ><P > The usual catalog entry in <TT CLASS="FILENAME" >/usr/local/share/sgml/catalog</TT > can also be made: </P><PRE CLASS="PROGRAMLISTING" >CATALOG "docbook-dsssl-1.<TT CLASS="REPLACEABLE" ><I >xx</I ></TT >/catalog"</PRE ><P> Because stylesheets change rather often, and it's sometimes beneficial to try out alternative versions, <SPAN CLASS="PRODUCTNAME" >PostgreSQL</SPAN > doesn't use this catalog entry. See <A HREF="docguide-toolsets.html#DOCGUIDE-TOOLSETS-CONFIGURE" >Section G.2.5</A > for information about how to select the stylesheets instead. </P ></DIV ><DIV CLASS="SECT3" ><H3 CLASS="SECT3" ><A NAME="AEN74993" >G.2.4.4. Installing <SPAN CLASS="PRODUCTNAME" >JadeTeX</SPAN ></A ></H3 ><P > To install and use <SPAN CLASS="PRODUCTNAME" >JadeTeX</SPAN >, you will need a working installation of <SPAN CLASS="PRODUCTNAME" >TeX</SPAN > and <SPAN CLASS="PRODUCTNAME" >LaTeX2e</SPAN >, including the supported <SPAN CLASS="PRODUCTNAME" >tools</SPAN > and <SPAN CLASS="PRODUCTNAME" >graphics</SPAN > packages, <SPAN CLASS="PRODUCTNAME" >Babel</SPAN >, <SPAN CLASS="PRODUCTNAME" ><ACRONYM CLASS="ACRONYM" >AMS</ACRONYM > fonts</SPAN > and <SPAN CLASS="PRODUCTNAME" >AMS-LaTeX</SPAN >, the <SPAN CLASS="PRODUCTNAME" ><ACRONYM CLASS="ACRONYM" >PSNFSS</ACRONYM ></SPAN > extension and companion kit of <SPAN CLASS="QUOTE" >"the 35 fonts"</SPAN >, the <SPAN CLASS="PRODUCTNAME" >dvips</SPAN > program for generating <SPAN CLASS="PRODUCTNAME" >PostScript</SPAN >, the macro packages <SPAN CLASS="PRODUCTNAME" >fancyhdr</SPAN >, <SPAN CLASS="PRODUCTNAME" >hyperref</SPAN >, <SPAN CLASS="PRODUCTNAME" >minitoc</SPAN >, <SPAN CLASS="PRODUCTNAME" >url</SPAN > and <SPAN CLASS="PRODUCTNAME" >ot2enc</SPAN >. All of these can be found on your friendly neighborhood <A HREF="http://www.ctan.org" TARGET="_top" ><ACRONYM CLASS="ACRONYM" >CTAN</ACRONYM ></A > site. The installation of the <SPAN CLASS="APPLICATION" >TeX</SPAN > base system is far beyond the scope of this introduction. Binary packages should be available for any system that can run <SPAN CLASS="APPLICATION" >TeX</SPAN >. </P ><P > Before you can use <SPAN CLASS="APPLICATION" >JadeTeX</SPAN > with the <SPAN CLASS="PRODUCTNAME" >PostgreSQL</SPAN > documentation sources, you will need to increase the size of <SPAN CLASS="APPLICATION" >TeX</SPAN >'s internal data structures. Details on this can be found in the <SPAN CLASS="APPLICATION" >JadeTeX</SPAN > installation instructions. </P ><P > Once that is finished you can install <SPAN CLASS="APPLICATION" >JadeTeX</SPAN >: </P><PRE CLASS="SCREEN" ><SAMP CLASS="PROMPT" >$</SAMP > <KBD CLASS="USERINPUT" >gunzip jadetex-<TT CLASS="REPLACEABLE" ><I >xxx</I ></TT >.tar.gz</KBD > <SAMP CLASS="PROMPT" >$</SAMP > <KBD CLASS="USERINPUT" >tar xf jadetex-<TT CLASS="REPLACEABLE" ><I >xxx</I ></TT >.tar</KBD > <SAMP CLASS="PROMPT" >$</SAMP > <KBD CLASS="USERINPUT" >cd jadetex</KBD > <SAMP CLASS="PROMPT" >$</SAMP > <KBD CLASS="USERINPUT" >make install</KBD > <SAMP CLASS="PROMPT" >$</SAMP > <KBD CLASS="USERINPUT" >mktexlsr</KBD ></PRE ><P> The last two need to be done as <SPAN CLASS="SYSTEMITEM" >root</SPAN >. </P ></DIV ></DIV ><DIV CLASS="SECT2" ><H2 CLASS="SECT2" ><A NAME="DOCGUIDE-TOOLSETS-CONFIGURE" >G.2.5. Detection by <TT CLASS="COMMAND" >configure</TT ></A ></H2 ><P > Before you can build the documentation you need to run the <TT CLASS="FILENAME" >configure</TT > script as you would when building the <SPAN CLASS="PRODUCTNAME" >PostgreSQL</SPAN > programs themselves. Check the output near the end of the run, it should look something like this: </P><PRE CLASS="SCREEN" ><SAMP CLASS="COMPUTEROUTPUT" >checking for onsgmls... onsgmls checking for openjade... openjade checking for DocBook V4.2... yes checking for DocBook stylesheets... /usr/lib/sgml/stylesheets/nwalsh-modular checking for sgmlspl... sgmlspl</SAMP ></PRE ><P> If neither <TT CLASS="FILENAME" >onsgmls</TT > nor <TT CLASS="FILENAME" >nsgmls</TT > were found then you will not see the remaining 4 lines. <TT CLASS="FILENAME" >nsgmls</TT > is part of the Jade package. If <SPAN CLASS="QUOTE" >"DocBook V4.2"</SPAN > 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 variable <TT CLASS="ENVAR" >DOCBOOKSTYLE</TT > to the location and rerun <TT CLASS="FILENAME" >configure</TT > afterwards. </P ></DIV ></DIV ><DIV CLASS="NAVFOOTER" ><HR ALIGN="LEFT" WIDTH="100%"><TABLE SUMMARY="Footer navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" ><A HREF="docguide.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="index.html" ACCESSKEY="H" >Home</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" ><A HREF="docguide-build.html" ACCESSKEY="N" >Next</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >Documentation</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="docguide.html" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" >Building The Documentation</TD ></TR ></TABLE ></DIV ></BODY ></HTML >