Changes between Version 2 and Version 3 of Building/Docs

Oct 27, 2006 4:45:09 PM (9 years ago)

Initial import from docbook docs


  • Building/Docs

    v2 v3  
    33= Building the documentation =
    5 Material on building the documentation is currently here, but need to be moved onto this page.  Please!
     6== Tools for building the Documentation ==
     8The following additional tools are required if you want to
     9format the documentation that comes with GHC:
     11 * {{{DocBook}}}
     12   Much of our documentation is written in !DocBook XML, instructions
     13   on installing and configuring the !DocBook tools are below.
     15 * {{{TeX}}}
     16   A decent TeX distribution is required if you want to
     17   produce printable documentation.  We recomment teTeX,
     18   which includes just about everything you need.
     20 * {{{Haddock}}}
     21   Haddock is a Haskell documentation tool that we use
     22   for automatically generating documentation from the
     23   library source code.  To build documentation for the
     24   libraries ({{{$(GHC_TOP)/libraries}}}) you
     25   should build and install Haddock.  Haddock requires GHC
     26   to build.
     28== Installing the !DocBook tools ==
     30=== Installing the !DocBook tools on Linux ===
     32If you're on a recent !RedHat (7.0+) or SuSE (8.1+) system,
     33you probably have working !DocBook tools already installed. The
     34configure script should detect your setup and you're away.
     36If you don't have !DocBook tools installed, and you are
     37using a system that can handle RPM packages, you can use
     38[] to find suitable
     39packages for your system. Search for the packages
     45{{{xmltex}}}, and
     48=== Installing !DocBook on FreeBSD ===
     50On FreeBSD systems, the easiest way to get !DocBook up
     51and running is to install it from the ports tree or a
     52pre-compiled package (packages are available from your local
     53FreeBSD mirror site).
     55To use the ports tree, do this:
     57$ cd /usr/ports/textproc/docproj
     58$ make install
     60This installs the FreeBSD documentation project tools, which
     61includes everything needed to format the GHC
     64=== Installing from binaries on Windows
     66Probably the fastest route to a working !DocBook environment on
     67Windows is to install [ Cygwin]
     68with the complete {{{Doc}}} category. If you are using
     69[" MinGW] for compilation, you
     70have to help {{{configure}}} a little bit: Set the
     71environment variables {{{XmllintCmd}}} and
     72{{{XsltprocCmd}}} to the paths of the Cygwin executables
     73{{{xmllint}}} and {{{xsltproc}}},
     74respectively, and set {{{fp_cv_dir_docbook_xsl}}} to the path
     75of the directory where the XSL stylesheets are installed,
     76e.g. {{{c:/cygwin/usr/share/docbook-xsl}}}.
     79If you want to build HTML Help, you have to install the
     80[ HTML Help SDK],
     81too, and make sure that {{{hhc}}} is in your {{{PATH}}}.
     83== Configuring the !DocBook tools ==
     85Once the !DocBook tools are installed, the configure script
     86will detect them and set up the build system accordingly. If you
     87have a system that isn't supported, let us know, and we'll try
     88to help.
     90== Building the documentation ==
     92To build documentation in a certain format, you can
     93say, for example,
     96$ make html
     99to build HTML documentation below the current directory.
     100The available formats are: {{{dvi}}},
     101{{{ps}}}, {{{pdf}}},
     102{{{html}}}, and {{{rtf}}}.  Note that
     103not all documentation can be built in all of these formats: HTML
     104documentation is generally supported everywhere, and !DocBook
     105documentation might support the other formats (depending on what
     106other tools you have installed).
     108All of these targets are recursive; that is, saying
     109{{{make html}}} will make HTML docs for all the
     110documents recursively below the current directory.
     112Because there are many different formats that the !DocBook
     113documentation can be generated in, you have to select which ones
     114you want by setting the {{{XMLDocWays}}} variable
     115to a list of them.  For example, in
     116{{{}}} you might have a line:
     118XMLDocWays = html ps
     120This will cause the documentation to be built in the requested
     121formats as part of the main build (the default is not to build
     122any documentation at all).
     124== Installing the documentation ==
     126To install the documentation, use:
     128$ make install-docs
     130This will install the documentation into
     131{{{$(datadir)}}} (which defaults to
     132{{{$(prefix)/share}}}).  The exception is HTML
     133documentation, which goes into
     134{{{$(datadir)/html}}}, to keep things tidy.
     136Note that unless you set {{{$(XMLDocWays)}}}
     137to a list of formats, the {{{install-docs}}} target
     138won't do anything for !DocBook XML documentation.