From: simonmar Date: Wed, 3 Jul 2002 10:02:19 +0000 (+0000) Subject: [project @ 2002-07-03 10:02:19 by simonmar] X-Git-Tag: Approx_11550_changesets_converted~1898 X-Git-Url: http://git.megacz.com/?a=commitdiff_plain;h=ce4f38f00b2d591aba7e59c8f292d74060e9a990;p=ghc-hetmet.git [project @ 2002-07-03 10:02:19 by simonmar] 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). --- diff --git a/docs/building/building.sgml b/docs/building/building.sgml index efe108d..669f321 100644 --- a/docs/building/building.sgml +++ b/docs/building/building.sgml @@ -1296,46 +1296,6 @@ $ cvs checkout nofib/spectral - - 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. - - Other useful tools @@ -1353,6 +1313,10 @@ $ cvs checkout nofib/spectral + + More tools are required if you want to format the documentation + that comes with GHC and other fptools projects. See . @@ -3202,6 +3166,266 @@ $ make way=p + + 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. + + + + + Porting GHC