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.