<META

9.1. Tools for building the Documentation

The following additional tools are required if you want to format the documentation that comes with the fptools projects:

DocBook: Much of our documentation is written in SGML, using the DocBook DTD. Instructions on installing and configuring the DocBook tools are below.
TeX: A decent TeX distribution is required if you want to produce printable documentation. We recomment teTeX, which includes just about everything you need.
Haddock: Haddock is a Haskell documentation tool that we use for automatically generating documentation from the library source code. It is an fptools project in itself. To build documentation for the libraries (fptools/libraries) you should check out and build Haddock in fptools/haddock. Haddock requires GHC to build.

9.2. Installing the DocBook tools

9.2.1. Installing the DocBook tools on Linux

If you're on a recent RedHat system (7.0+), you probably have working DocBook tools already installed. The configure script should detect your setup and you're away.

If you don't have DocBook tools installed, and you are using a system that can handle RedHat RPM packages, you can probably use the Cygnus DocBook tools, which is the most shrink-wrapped SGML suite that we could find. You need all the RPMs except for psgml (i.e. docbook, jade, jadetex, sgmlcommon and stylesheets). Note that most of these RPMs are architecture neutral, so are likely to be found in a noarch directory. The SuSE RPMs also work; the RedHat ones don't in RedHat 6.2 (7.0 and later should be OK), but they are easy to fix: just make a symlink from /usr/lib/sgml/stylesheets/nwalsh-modular/lib/dblib.dsl to /usr/lib/sgml/lib/dblib.dsl.

9.2.2. Installing DocBook on FreeBSD

On FreeBSD systems, the easiest way to get DocBook up and running is to install it from the ports tree or a pre-compiled package (packages are available from your local FreeBSD mirror site).

To use the ports tree, do this:
$ cd /usr/ports/textproc/docproj $ make install
This installs the FreeBSD documentation project tools, which includes everything needed to format the GHC documentation.

9.2.3. Installing from binaries on Windows

It's a good idea to use Norman Walsh's installation notes as a guide. You should get version 3.1 of DocBook, and note that his file test.sgm won't work, as it needs version 3.0. You should unpack Jade into \Jade, along with the entities, DocBook into \docbook, and the DocBook stylesheets into \docbook\stylesheets (so they actually end up in \docbook\stylesheets\docbook).

9.2.4. Installing the DocBook tools from source

9.2.4.1. Jade

Install OpenJade (Windows binaries are available as well as sources). If you want DVI, PS, or PDF then install JadeTeX from the dsssl subdirectory. (If you get the error:
! LaTeX Error: Unknown option implicit=false' for package hyperref'.
your version of hyperref is out of date; download it from CTAN (macros/latex/contrib/supported/hyperref), and make it, ensuring that you have first removed or renamed your old copy. If you start getting file not found errors when making the test for hyperref, you can abort at that point and proceed straight to make install, or enter them as ../filename.)

Make links from virtex to jadetex and pdfvirtex to pdfjadetex (otherwise DVI, PostScript and PDF output will not work). Copy dsssl/*.{dtd,dsl} and catalog to /usr/[local/]lib/sgml.

9.2.4.2. DocBook and the DocBook stylesheets

Get a Zip of DocBook and install the contents in /usr/[local/]/lib/sgml.

Get the DocBook stylesheets and install in /usr/[local/]lib/sgml/stylesheets (thereby creating a subdirectory docbook). For indexing, copy or link collateindex.pl from the DocBook stylesheets archive in bin into a directory on your PATH.

Download the ISO entities into /usr/[local/]lib/sgml.

9.3. Configuring the DocBook tools

Once the DocBook tools are installed, the configure script will detect them and set up the build system accordingly. If you have a system that isn't supported, let us know, and we'll try to help.

9.4. Remaining problems

If you install from source, you'll get a pile of warnings of the form
DTDDECL catalog entries are not supported
every time you build anything. These can safely be ignored, but if you find them tedious you can get rid of them by removing all the DTDDECL entries from docbook.cat.

9.5. Building the documentation

To build documentation in a certain format, you can say, for example,

$ make html

to build HTML documentation below the current directory. The available formats are: dvi, ps, pdf, html, and rtf. Note that not all documentation can be built in all of these formats: HTML documentation is generally supported everywhere, and DocBook documentation might support the other formats (depending on what other tools you have installed).

All of these targets are recursive; that is, saying make html will make HTML docs for all the documents recursively below the current directory.

Because there are many different formats that the DocBook documentation can be generated in, you have to select which ones you want by setting the SGMLDocWays variable to a list of them. For example, in build.mk you might have a line:

SGMLDocWays = html ps

This will cause the documentation to be built in the requested formats as part of the main build (the default is not to build any documentation at all).

9.6. Installing the documentation

To install the documentation, use:

$ make install-docs

This will install the documentation into $(datadir) (which defaults to $(prefix)/share). The exception is HTML documentation, which goes into $(datadir)/html, to keep things tidy.

Note that unless you set $(SGMLDocWays) to a list of formats, the install-docs target won't do anything for SGML documentation.