[[project @ 2002-07-03 10:02:19 by simonmar]
simonmar**20020703100219
Add documentation on building the documentation. (I've moved the
section on building documentation from the User's Guide, it doesn't
really seem appropriate there).
] {
hunk ./docs/building/building.sgml 1299
-
- 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
- pre-supposed: DocBook
- DocBook, pre-supposed
-
- All our documentation is written in SGML, using the
- DocBook DTD. Instructions on installing and configuring
- the DocBook tools are in the installation guide (in the
- GHC user guide).
-
-
-
-
- TeX
- pre-supposed: TeX
- TeX, pre-supposed
-
- A decent TeX distribution is required if you want to
- produce printable documentation. We recomment teTeX,
- which includes just about everything you need.
-
-
-
-
- In order to actually build any documentation, you need to
- set SGMLDocWays in your
- build.mk. Valid values to add to this list
- are: dvi, ps,
- pdf, html, and
- rtf.
-
-
hunk ./docs/building/building.sgml 1316
+
+ More tools are required if you want to format the documentation
+ that comes with GHC and other fptools projects. See .
hunk ./docs/building/building.sgml 3169
+
+ Building the documentation
+
+
+ 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
+ pre-supposed: DocBook
+ DocBook, pre-supposed
+
+ Much of our documentation is written in SGML, using
+ the DocBook DTD. Instructions on installing and
+ configuring the DocBook tools are below.
+
+
+
+
+ TeX
+ pre-supposed: TeX
+ TeX, pre-supposed
+
+ 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
+
+
+ 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.
+
+
+
+
+
+
+ Installing the DocBook tools
+
+
+ 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.
+
+
+
+ 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.
+
+
+
+ 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).
+
+
+
+
+ Installing the DocBook tools from source
+
+
+ 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.
+
+
+
+ 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.
+
+
+
+
+
+ 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.
+
+
+
+ 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.
+
+
+
+ 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).
+
+
+
+ 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.
+
+
+
+
+
}