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!