<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 2. Invoking Haddock</title><link rel="stylesheet" href="fptools.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"><link rel="start" href="index.html" title="Haddock User Guide"><link rel="up" href="index.html" title="Haddock User Guide"><link rel="prev" href="ch01s03.html" title="1.3. Acknowledgements"><link rel="next" href="markup.html" title="Chapter 3. Documentation and Markup"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 2. Invoking Haddock</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch01s03.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="markup.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="invoking"></a>Chapter 2. Invoking Haddock</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="invoking.html#cpp">2.1. Using literate or pre-processed source</a></span></dt></dl></div><p>Haddock is invoked from the command line, like so:</p><div class="cmdsynopsis"><p><code class="command">haddock</code> [<em class="replaceable"><code>option</code></em>...] <em class="replaceable"><code>file</code></em>... </p></div><p>Where each <em class="replaceable"><code>file</code></em> is a filename
containing a Haskell source module (.hs) or a Literate Haskell source
module (.lhs) or just a module name.</p><p>All the modules specified on the command line will be
processed together. When one module refers to an entity in
another module being processed, the documentation will link
directly to that entity.</p><p>Entities that cannot be found, for example because they are
in a module that isn't being processed as part of the current
batch, simply won't be hyperlinked in the generated
documentation. Haddock will emit warnings listing all the
indentifiers it couldn't resolve.</p><p>The modules should <span class="emphasis"><em>not</em></span> be mutually
recursive, as Haddock don't like swimming in circles.</p><p>You must also specify an option for the output format.
Currently only the <code class="option">-h</code> option for HTML and the
<code class="option">--hoogle</code> option for outputting Hoogle data are
functional.</p><p>The packaging
tool <a class="ulink" href="http://www.haskell.org/ghc/docs/latest/html/Cabal/index.html" target="_top">Cabal</a>
has Haddock support, and is often used instead of invoking Haddock
directly.</p><p>The following options are available:</p><div class="variablelist"><dl><dt><span class="term">
<a class="indexterm" name="id2495964"></a>
<code class="option">-B</code> <em class="replaceable"><code>dir</code></em>
</span></dt><dd><p>Tell GHC that that its lib directory is
<em class="replaceable"><code>dir</code></em>. Can be used to override the default path.</p></dd><dt><span class="term">
<a class="indexterm" name="id2495996"></a>
<code class="option">--optghc</code>=<em class="replaceable"><code>option</code></em>
</span></dt><dd><p>Pass <em class="replaceable"><code>option</code></em> to GHC.</p></dd><dt><span class="term">
<a class="indexterm" name="id2496028"></a>
<code class="option">-o</code> <em class="replaceable"><code>dir</code></em>
, </span><span class="term">
<a class="indexterm" name="id2496045"></a>
<code class="option">--odir</code>=<em class="replaceable"><code>dir</code></em>
</span></dt><dd><p>Generate files into <em class="replaceable"><code>dir</code></em>
instead of the current directory.</p></dd><dt><span class="term">
<a class="indexterm" name="id2496077"></a>
<code class="option">-i</code> <em class="replaceable"><code>path</code></em>,<em class="replaceable"><code>file</code></em>
, </span><span class="term">
<a class="indexterm" name="id2496098"></a>
<code class="option">--read-interface</code>=<em class="replaceable"><code>path</code></em>,<em class="replaceable"><code>file</code></em>
</span></dt><dd><p>Read the interface file in
<em class="replaceable"><code>file</code></em>, which must have been
produced by running Haddock with the
<code class="option">--dump-interface</code> option. The interface
describes a set of modules whose HTML documentation is
located in <em class="replaceable"><code>path</code></em> (which may be a
relative pathname). The <em class="replaceable"><code>path</code></em> is
optional, and defaults to “<span class="quote">.</span>”.</p><p>This option allows Haddock to produce separate sets of
documentation with hyperlinks between them. The
<em class="replaceable"><code>path</code></em> is used to direct hyperlinks
to point to the right files; so make sure you don't move the
HTML files later or these links will break. Using a
relative <em class="replaceable"><code>path</code></em> means that a
documentation subtree can still be moved around without
breaking links.</p><p>Multiple <code class="option">--read-interface</code> options may
be given.</p></dd><dt><span class="term">
<a class="indexterm" name="id2496175"></a>
<code class="option">-D</code> <em class="replaceable"><code>file</code></em>
, </span><span class="term">
<a class="indexterm" name="id2496192"></a>
<code class="option">--dump-interface</code>=<em class="replaceable"><code>file</code></em>
</span></dt><dd><p>Produce an <em class="firstterm">interface
file</em><sup>[<a name="id2496215" href="#ftn.id2496215" class="footnote">1</a>]</sup>
in the file <em class="replaceable"><code>file</code></em>. An interface
file contains information Haddock needs to produce more
documentation that refers to the modules currently being
processed - see the <code class="option">--read-interface</code> option
for more details. The interface file is in a binary format;
don't try to read it.</p></dd><dt><span class="term">
<a class="indexterm" name="id2496242"></a>
<code class="option">-l</code> <em class="replaceable"><code>dir</code></em>
, </span><span class="term">
<a class="indexterm" name="id2496260"></a>
<code class="option">--lib</code>=<em class="replaceable"><code>dir</code></em>
</span></dt><dd><p>Use auxiliary files in <em class="replaceable"><code>dir</code></em>.</p></dd><dt><span class="term">
<a class="indexterm" name="id2496290"></a>
<code class="option">-S</code>
, </span><span class="term">
<a class="indexterm" name="id2496305"></a>
<code class="option">--docbook</code>
</span></dt><dd><p>Reserved for future use (output documentation in DocBook XML
format).</p></dd><dt><span class="term">
<a class="indexterm" name="id2496330"></a>
<code class="option">-h</code>
, </span><span class="term">
<a class="indexterm" name="id2496344"></a>
<code class="option">--html</code>
</span></dt><dd><p>Generate documentation in HTML format. Several files
will be generated into the current directory (or the
specified directory if the <code class="option">-o</code> option is
given), including the following:</p><div class="variablelist"><dl><dt><span class="term"><code class="filename">index.html</code></span></dt><dd><p>The top level page of the documentation: lists
the modules available, using indentation to represent
the hierarchy if the modules are hierarchical.</p></dd><dt><span class="term"><code class="filename">haddock.css</code></span></dt><dd><p>The stylesheet used by the generated HTML. Feel
free to modify this to change the colors or
layout, or even specify your own stylesheet using the
<code class="option">--css</code> option.</p></dd><dt><span class="term"><code class="filename">haddock-util.js</code></span></dt><dd><p>A small piece of JavaScript for collapsing sections
of the generated HTML.</p></dd><dt><span class="term"><code class="filename"><em class="replaceable"><code>module</code></em>.html</code></span></dt><dd><p>An HTML page for each
<em class="replaceable"><code>module</code></em>.</p></dd><dt><span class="term"><code class="filename">doc-index.html</code>, </span><span class="term"><code class="filename">doc-index-XX.html</code></span></dt><dd><p>The index, split into two
(functions/constructors and types/classes, as per
Haskell namespaces) and further split
alphabetically.</p></dd></dl></div></dd><dt><span class="term">
<a class="indexterm" name="id2496487"></a>
<code class="option">-m</code>
, </span><span class="term">
<a class="indexterm" name="id2496502"></a>
<code class="option">--html-help</code>
</span></dt><dd><p>(In HTML mode only) Produce extra contents and index
files for given HTML Help system. Currently supported Help
systems are Microsoft HTML Help 1.3 and 2.0 and GNOME DevHelp.</p><p>Using the Microsoft HTML Help system provides two
advantages over plain HTML: the help viewer gives you a nice
hierarchical folding contents pane on the left, and the
documentation files are compressed and therefore much
smaller (roughly a factor of 10). The disadvantage is that
the help can't be viewed over the web.</p><p>In order to create a compiled Microsoft help file, you
also need the Microsoft HTML Help compiler, which is
available free from
<a class="ulink" href="http://www.microsoft.com/" target="_top">http://www.microsoft.com/</a>
(search for “<span class="quote">HTML Help compiler</span>”).</p><p>Viewers</p><div class="variablelist"><dl><dt><span class="term">Microsoft HTML Help Viewer</span></dt><dd><p>Distributed with Microsoft Windows</p></dd><dt><span class="term"><a class="ulink" href="http://xchm.sourceforge.net" target="_top">xCHM</a></span></dt><dd><p>a CHM viewer for UNIX (Linux, *BSD, Solaris), written by Razvan Cojocaru</p></dd><dt><span class="term"><a class="ulink" href="http://www.jouledata.com/MacProducts.html" target="_top">JouleData Solutions' CHM Viewer</a></span></dt><dd><p>a comercial 100% native Cocoa .chm file viewer for the Mac OS X platform</p></dd><dt><span class="term"><a class="ulink" href="http://gnochm.sourceforge.net" target="_top">GnoCHM</a></span></dt><dd><p>a CHM file viewer. It is designed to integrate nicely with Gnome.</p></dd></dl></div><p>The GNOME DevHelp also provides help viewer which looks like
MSHelp viewer but the documentation files aren't compressed.
The documentation can be viewed with any HTML browser but
DevHelp gives you a nice hierarchical folding contents and
keyword index panes on the left. The DevHelp expects to see
*.devhelp file in the folder where the documentation is placed.
The file contains all required information
to build the contents and index panes.
</p></dd><dt><span class="term">
<a class="indexterm" name="id2496629"></a>
<code class="option">--source-base</code>=<em class="replaceable"><code>URL</code></em>
, </span><span class="term">
<a class="indexterm" name="id2496647"></a>
<code class="option">--source-module</code>=<em class="replaceable"><code>URL</code></em>
, </span><span class="term">
<a class="indexterm" name="id2496665"></a>
<code class="option">--source-entity</code>=<em class="replaceable"><code>URL</code></em>
</span></dt><dd><p>Include links to the source files in the generated
documentation. Use the <code class="option">--source-base</code> option to add a
source code link in the header bar of the contents and index pages.
Use the <code class="option">--source-module</code> to add a source code link in
the header bar of each module page. Use the
<code class="option">--source-entity</code> option to add a source code link
next to the documentation for every value and type in each module.
</p><p>In each case <em class="replaceable"><code>URL</code></em> is the base URL
where the source files can be found. For the per-module and
per-entity URLs, the following substitutions are made within the
string <em class="replaceable"><code>URL</code></em>:</p><div class="itemizedlist"><ul type="disc"><li><p>The string <code class="literal">%M</code> or <code class="literal">%{MODULE}</code>
is replaced by the module name. Note that for the per-entity URLs
this is the name of the <span class="emphasis"><em>exporting</em></span> module.</p></li><li><p>The string <code class="literal">%F</code> or <code class="literal">%{FILE}</code>
is replaced by the original source file name. Note that for the
per-entity URLs this is the name of the <span class="emphasis"><em>defining</em></span>
module.</p></li><li><p>The string <code class="literal">%N</code> or <code class="literal">%{NAME}</code>
is replaced by the name of the exported value or type. This is
only valid for the <code class="option">--source-entity</code> option.</p></li><li><p>The string <code class="literal">%K</code> or <code class="literal">%{KIND}</code>
is replaced by a flag indicating whether the exported name is a value
'<code class="literal">v</code>' or a type '<code class="literal">t</code>'. This is
only valid for the <code class="option">--source-entity</code> option.</p></li><li><p>The string <code class="literal">%L</code> or <code class="literal">%{LINE}</code>
is replaced by the number of the line where the exported value or
type is defined. This is only valid for the
<code class="option">--source-entity</code> option.</p></li><li><p>The string <code class="literal">%%</code> is replaced by
<code class="literal">%</code>.</p></li></ul></div><p>For example, if your sources are online under some directory,
you would say
<code class="literal">haddock --source-base=<em class="replaceable"><code>url</code></em>/
--source-module=<em class="replaceable"><code>url</code></em>/%F</code></p><p>If you have html versions of your sources online with anchors
for each type and function name, you would say
<code class="literal">haddock --source-base=<em class="replaceable"><code>url</code></em>/
--source-module=<em class="replaceable"><code>url</code></em>/%M.html
--source-entity=<em class="replaceable"><code>url</code></em>/%M.html#%N</code></p><p>For the <code class="literal">%{MODULE}</code> substitution you may want to
replace the '<code class="literal">.</code>' character in the module names with
some other character (some web servers are known to get confused by
multiple '<code class="literal">.</code>' characters in a file name). To
replace it with a character <em class="replaceable"><code>c</code></em> use
<code class="literal">%{MODULE/./<em class="replaceable"><code>c</code></em>}</code>.</p><p>Similarly, for the <code class="literal">%{FILE}</code> substitution
you may want to replace the '<code class="literal">/</code>' character in
the file names with some other character (especially for links
to colourised entity source code with a shared css file). To replace
it with a character <em class="replaceable"><code>c</code></em> use
<code class="literal">%{FILE///<em class="replaceable"><code>c</code></em>}</code>/</p><p>One example of a tool that can generate syntax-highlighted
HTML from your source code, complete with anchors suitable for use
from haddock, is
<a class="ulink" href="http://www.cs.york.ac.uk/fp/darcs/hscolour" target="_top">hscolour</a>.</p></dd><dt><span class="term">
<a class="indexterm" name="id2496994"></a>
<code class="option">-s</code> <em class="replaceable"><code>URL</code></em>
, </span><span class="term">
<a class="indexterm" name="id2497012"></a>
<code class="option">--source</code>=<em class="replaceable"><code>URL</code></em>
</span></dt><dd><p>Deprecated aliases for <code class="option">--source-module</code></p></dd><dt><span class="term">
<a class="indexterm" name="id2497042"></a>
<code class="option">--comments-base</code>=<em class="replaceable"><code>URL</code></em>
, </span><span class="term">
<a class="indexterm" name="id2497060"></a>
<code class="option">--comments-module</code>=<em class="replaceable"><code>URL</code></em>
, </span><span class="term">
<a class="indexterm" name="id2497078"></a>
<code class="option">--comments-entity</code>=<em class="replaceable"><code>URL</code></em>
</span></dt><dd><p>Include links to pages where readers may comment on the
documentation. This feature would typically be used in conjunction
with a Wiki system.</p><p>Use the <code class="option">--comments-base</code> option to add a
user comments link in the header bar of the contents and index pages.
Use the <code class="option">--comments-module</code> to add a user comments
link in the header bar of each module page. Use the
<code class="option">--comments-entity</code> option to add a comments link
next to the documentation for every value and type in each module.
</p><p>In each case <em class="replaceable"><code>URL</code></em> is the base URL
where the corresponding comments page can be found. For the
per-module and per-entity URLs the same substitutions are made as
with the <code class="option">--source-module</code> and
<code class="option">--source-entity</code> options above.</p><p>For example, if you want to link the contents page to a wiki
page, and every module to subpages, you would say
<code class="literal">haddock --comments-base=<em class="replaceable"><code>url</code></em>
--comments-module=<em class="replaceable"><code>url</code></em>/%M</code></p><p>If your Wiki system doesn't like the '<code class="literal">.</code>' character
in Haskell module names, you can replace it with a different character. For
example to replace the '<code class="literal">.</code>' characters with
'<code class="literal">_</code>' use <code class="literal">haddock
--comments-base=<em class="replaceable"><code>url</code></em>
--comments-module=<em class="replaceable"><code>url</code></em>/%{MODULE/./_}</code>
Similarly, you can replace the '<code class="literal">/</code>' in a file name (may
be useful for entity comments, but probably not.) </p></dd><dt><span class="term">
<a class="indexterm" name="id2497204"></a>
<code class="option">-c</code> <em class="replaceable"><code>file</code></em>
, </span><span class="term">
<a class="indexterm" name="id2497222"></a>
<code class="option">--css</code>=<em class="replaceable"><code>file</code></em>
</span></dt><dd><p>Specify a stylesheet to use instead of the default one
that comes with Haddock. It should specify certain classes:
see the default stylesheet for details.</p></dd><dt><span class="term">
<a class="indexterm" name="id2497252"></a>
<code class="option">-p</code> <em class="replaceable"><code>file</code></em>
, </span><span class="term">
<a class="indexterm" name="id2497270"></a>
<code class="option">--prologue</code>=<em class="replaceable"><code>file</code></em>
</span></dt><dd><p>Specify a file containing documentation which is
placed on the main contents page under the heading
“Description”. The file is parsed as a normal
Haddock doc comment (but the comment markers are not
required).</p></dd><dt><span class="term">
<a class="indexterm" name="id2497307"></a>
<code class="option">-t</code> <em class="replaceable"><code>title</code></em>
, </span><span class="term">
<a class="indexterm" name="id2497324"></a>
<code class="option">--title</code>=<em class="replaceable"><code>title</code></em>
</span></dt><dd><p>Use <em class="replaceable"><code>title</code></em> as the page
heading for each page in the documentation.This will
normally be the name of the library being documented.</p><p>The title should be a plain string (no markup
please!).</p></dd><dt><span class="term">
<a class="indexterm" name="id2497362"></a>
<code class="option">-d</code>
, </span><span class="term">
<a class="indexterm" name="id2497376"></a>
<code class="option">--debug</code>
</span></dt><dd><p>Produce extra debugging output.</p></dd><dt><span class="term">
<a class="indexterm" name="id2497400"></a>
<code class="option">-?</code>
, </span><span class="term">
<a class="indexterm" name="id2497414"></a>
<code class="option">--help</code>
</span></dt><dd><p>Display help and exit.</p></dd><dt><span class="term">
<a class="indexterm" name="id2497439"></a>
<code class="option">-v</code>
, </span><span class="term">
<a class="indexterm" name="id2497453"></a>
<code class="option">--verbose</code>
</span></dt><dd><p>Increase verbosity. Currently this will cause Haddock
to emit some extra warnings, in particular about modules
which were imported but it had no information about (this is
often quite normal; for example when there is no information
about the <code class="literal">Prelude</code>).</p></dd><dt><span class="term">
<a class="indexterm" name="id2497489"></a>
<code class="option">-V</code>
, </span><span class="term">
<a class="indexterm" name="id2497503"></a>
<code class="option">--version</code>
</span></dt><dd><p>Output version information and exit.</p></dd><dt><span class="term">
<a class="indexterm" name="id2497527"></a>
<code class="option">--use-index=<em class="replaceable"><code>URL</code></em></code>
</span></dt><dd><p>When generating HTML, do not generate an index.
Instead, redirect the Index link on each page to
<em class="replaceable"><code>URL</code></em>. This option is intended for
use in conjuction with <code class="option">--gen-index</code> for
generating a separate index covering multiple
libraries.</p></dd><dt><span class="term">
<a class="indexterm" name="id2497564"></a>
<code class="option">--gen-index</code>
</span></dt><dd><p>Generate an HTML index containing entries pulled from
all the specified interfaces (interfaces are specified using
<code class="option">-i</code> or <code class="option">--read-interface</code>).
This is used to generate a single index for multiple sets of
Haddock documentation.</p></dd><dt><span class="term">
<a class="indexterm" name="id2497600"></a>
<code class="option">--ignore-all-exports</code>
</span></dt><dd><p>Causes Haddock to behaves as if every module has the
<code class="literal">ignore-exports</code> attribute (<a class="xref" href="module-attributes.html" title="3.7. Module Attributes">Section 3.7, “Module Attributes”</a>). This might be useful for
generating implementation documentation rather than interface
documetnation, for example.</p></dd><dt><span class="term">
<a class="indexterm" name="id2497741"></a>
<code class="option">--hide</code> <em class="replaceable"><code>module</code></em>
</span></dt><dd><p>Causes Haddock to behaves as if module
<em class="replaceable"><code>module</code></em> has the <code class="literal">hide</code>
atribute. (<a class="xref" href="module-attributes.html" title="3.7. Module Attributes">Section 3.7, “Module Attributes”</a>).</p></dd></dl></div><dt><span class="term">
<a class="indexterm" name="id2497770"></a>
<code class="option">-w</code>
, </span><span class="term">
<a class="indexterm" name="id2497784"></a>
<code class="option">--no-warnings</code>
</span></dt><dd><p>Turn off all warnings.</p></dd><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cpp"></a>2.1. Using literate or pre-processed source</h2></div></div></div><p>Since Haddock uses GHC internally, both plain and
literate Haskell sources are accepted without the need for the user
to do anything. To use the C pre-processor, however,
the user must pass the the <code class="option">-cpp</code> option to GHC
using <code class="option">--optghc</code>.
</p></div><div class="footnotes"><br><hr width="100" align="left"><div class="footnote"><p><sup>[<a name="ftn.id2496215" href="#id2496215" class="para">1</a>] </sup>Haddock interface files are
not the same as Haskell interface files, I just couldn't
think of a better name.</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch01s03.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="markup.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">1.3. Acknowledgements </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 3. Documentation and Markup</td></tr></table></div></body></html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
87b4172b3b1930a874e4a9620c298a79
>
files
>
24
