Changes between Version 5 and Version 6 of Building/Docs


Ignore:
Timestamp:
Mar 31, 2009 10:38:06 AM (6 years ago)
Author:
simonmar
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Building/Docs

    v5 v6  
    1 [[PageOutline]]
     1
    22
    33= Building the documentation =
    44
    5    
    65== Haddock documentation ==
    76
    8 In order to build haddock documentation for the libraries, simply put
     7The GHC build includes Haddock, and the Haddock documentation for libraries is built and installed by default.  It is also possible to process the libraries sources using [http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hscolour HsColour], and for the Haddock documentation to include links to the !HsColoured source code; in order to do this, just install `HsColour` and run `./configure`.  The configure script will tell you whether it found `HsColour` at the end.
    98
    10 {{{
    11 HADDOCK_DOCS = YES
    12 }}}
    139
    14 in `mk/build.mk` before running `make`.
     10== !DocBook documentation ==
    1511
    16 == Tools for building the Documentation ==
     12The rest of the documentation, in particular the Users' Guide and Cabal documentation, are in [http://www.docbook.org/ DocBook] XML format.  In order to process the documentation into HTML or printable formats, you need appropriate tools installed.  The `configure` script searches for the appropriate tools, and will tell you whether it found any.
    1713
    18 The following additional tools are required if you want to
    19 format the documentation that comes with GHC:
    20      
    21  * {{{DocBook}}}
    22    Much of our documentation is written in !DocBook XML, instructions
    23    on installing and configuring the !DocBook tools are below.
     14To install the tools necessary for building the documentation, see [wiki:Building/Prerequisites].
    2415
    25  * {{{TeX}}}
    26    A decent TeX distribution is required if you want to
    27    produce printable documentation.  We recomment teTeX,
    28    which includes just about everything you need.
    29 
    30  * {{{Haddock}}}
    31    Haddock is a Haskell documentation tool that we use
    32    for automatically generating documentation from the
    33    library source code.  To build documentation for the
    34    libraries ({{{$(GHC_TOP)/libraries}}}) you
    35    should build and install Haddock.  Haddock requires GHC
    36    to build.
    37 
    38 == Installing the !DocBook tools ==
    39 
    40 === Installing the !DocBook tools on Linux ===
    41 
    42 If you're on a recent !RedHat (7.0+) or SuSE (8.1+) system,
    43 you probably have working !DocBook tools already installed. The
    44 configure script should detect your setup and you're away.
    45 
    46 If you don't have !DocBook tools installed, and you are
    47 using a system that can handle RPM packages, you can use
    48 [http://rpmfind.net/ Rpmfind.net] to find suitable
    49 packages for your system. Search for the packages
    50 {{{docbook-dtd}}},
    51 {{{docbook-xsl-stylesheets}}},
    52 {{{libxslt}}},
    53 {{{libxml2}}},
    54 {{{fop}}},
    55 {{{xmltex}}}, and
    56 {{{dvips}}}.
    57 
    58 === Installing !DocBook on FreeBSD ===
    59 
    60 On FreeBSD systems, the easiest way to get !DocBook up
    61 and running is to install it from the ports tree or a
    62 pre-compiled package (packages are available from your local
    63 FreeBSD mirror site).
    64 
    65 To use the ports tree, do this:
    66 {{{
    67 $ cd /usr/ports/textproc/docproj
    68 $ make install
    69 }}}
    70 This installs the FreeBSD documentation project tools, which
    71 includes everything needed to format the GHC
    72 documentation.
    73 
    74 === Installing from binaries on Windows ===
    75        
    76 Probably the fastest route to a working !DocBook environment on
    77 Windows is to install [http://www.cygwin.com/ Cygwin]
    78 with the complete {{{Doc}}} category. If you are using
    79 ["http://www.mingw.org/ MinGW] for compilation, you
    80 have to help {{{configure}}} a little bit: Set the
    81 environment variables {{{XmllintCmd}}} and
    82 {{{XsltprocCmd}}} to the paths of the Cygwin executables
    83 {{{xmllint}}} and {{{xsltproc}}},
    84 respectively, and set {{{fp_cv_dir_docbook_xsl}}} to the path
    85 of the directory where the XSL stylesheets are installed,
    86 e.g. {{{c:/cygwin/usr/share/docbook-xsl}}}.
    87        
    88 
    89 If you want to build HTML Help, you have to install the
    90 [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hworiHTMLHelpStartPage.asp HTML Help SDK],
    91 too, and make sure that {{{hhc}}} is in your {{{PATH}}}.
    92 
    93 == Configuring the !DocBook tools ==
    94 
    95 Once the !DocBook tools are installed, the configure script
    96 will detect them and set up the build system accordingly. If you
    97 have a system that isn't supported, let us know, and we'll try
    98 to help.
    99 
    100 == Building the documentation ==
    101 
    102 To build documentation in a certain format, you can
    103 say, for example,
    104 
    105 {{{
    106 $ make html
    107 }}}
    108 
    109 to build HTML documentation below the current directory.
    110 The available formats are: {{{dvi}}},
    111 {{{ps}}}, {{{pdf}}},
    112 {{{html}}}, and {{{rtf}}}.  Note that
    113 not all documentation can be built in all of these formats: HTML
    114 documentation is generally supported everywhere, and !DocBook
    115 documentation might support the other formats (depending on what
    116 other tools you have installed).
    117 
    118 All of these targets are recursive; that is, saying
    119 {{{make html}}} will make HTML docs for all the
    120 documents recursively below the current directory.
    121 
    122 Because there are many different formats that the !DocBook
    123 documentation can be generated in, you have to select which ones
    124 you want by setting the {{{XMLDocWays}}} variable
    125 to a list of them.  For example, in
    126 {{{build.mk}}} you might have a line:
    127 {{{
    128 XMLDocWays = html ps
    129 }}}
    130 This will cause the documentation to be built in the requested
    131 formats as part of the main build (the default is not to build
    132 any documentation at all).
    133 
    134 == Installing the documentation ==
    135 
    136 To install the documentation, use:
    137 {{{
    138 $ make install-docs
    139 }}}
    140 This will install the documentation into
    141 {{{$(datadir)}}} (which defaults to
    142 {{{$(prefix)/share}}}).  The exception is HTML
    143 documentation, which goes into
    144 {{{$(datadir)/html}}}, to keep things tidy.
    145 
    146 Note that unless you set {{{$(XMLDocWays)}}}
    147 to a list of formats, the {{{install-docs}}} target
    148 won't do anything for !DocBook XML documentation.
     16At the moment, we are not able to build documentation in PDF format due to tool flakiness.  If you manage to find a way to process the documentation into readable PDF, please let us know!