Table of Contents
Haddock is invoked from the command line, like so:
haddock
[option
...] file
...
Where each file
is a filename
containing a Haskell source module (.hs) or a Literate Haskell source
module (.lhs) or just a module name.
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.
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.
The modules should not be mutually recursive, as Haddock don't like swimming in circles.
You must also specify an option for the output format.
Currently only the -h
option for HTML and the
--hoogle
option for outputting Hoogle data are
functional.
The packaging tool Cabal has Haddock support, and is often used instead of invoking Haddock directly.
The following options are available:
-B
dir
Tell GHC that that its lib directory is
dir
. Can be used to override the default path.
--optghc
=option
Pass option
to GHC.
-o
dir
,
--odir
=dir
Generate files into dir
instead of the current directory.
-i
path
,file
,
--read-interface
=path
,file
Read the interface file in
file
, which must have been
produced by running Haddock with the
--dump-interface
option. The interface
describes a set of modules whose HTML documentation is
located in path
(which may be a
relative pathname). The path
is
optional, and defaults to “.”.
This option allows Haddock to produce separate sets of
documentation with hyperlinks between them. The
path
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 path
means that a
documentation subtree can still be moved around without
breaking links.
Multiple --read-interface
options may
be given.
-D
file
,
--dump-interface
=file
Produce an interface
file[1]
in the file file
. An interface
file contains information Haddock needs to produce more
documentation that refers to the modules currently being
processed - see the --read-interface
option
for more details. The interface file is in a binary format;
don't try to read it.
-l
dir
,
--lib
=dir
Use auxiliary files in dir
.
-S
,
--docbook
Reserved for future use (output documentation in DocBook XML format).
-h
,
--html
Generate documentation in HTML format. Several files
will be generated into the current directory (or the
specified directory if the -o
option is
given), including the following:
index.html
The top level page of the documentation: lists the modules available, using indentation to represent the hierarchy if the modules are hierarchical.
haddock.css
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
--css
option.
haddock-util.js
A small piece of JavaScript for collapsing sections of the generated HTML.
module
.html
An HTML page for each
module
.
doc-index.html
, doc-index-XX.html
The index, split into two (functions/constructors and types/classes, as per Haskell namespaces) and further split alphabetically.
-m
,
--html-help
(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.
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.
In order to create a compiled Microsoft help file, you also need the Microsoft HTML Help compiler, which is available free from http://www.microsoft.com/ (search for “HTML Help compiler”).
Viewers
Distributed with Microsoft Windows
a CHM viewer for UNIX (Linux, *BSD, Solaris), written by Razvan Cojocaru
a comercial 100% native Cocoa .chm file viewer for the Mac OS X platform
a CHM file viewer. It is designed to integrate nicely with Gnome.
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.
--source-base
=URL
,
--source-module
=URL
,
--source-entity
=URL
Include links to the source files in the generated
documentation. Use the --source-base
option to add a
source code link in the header bar of the contents and index pages.
Use the --source-module
to add a source code link in
the header bar of each module page. Use the
--source-entity
option to add a source code link
next to the documentation for every value and type in each module.
In each case URL
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 URL
:
The string %M
or %{MODULE}
is replaced by the module name. Note that for the per-entity URLs
this is the name of the exporting module.
The string %F
or %{FILE}
is replaced by the original source file name. Note that for the
per-entity URLs this is the name of the defining
module.
The string %N
or %{NAME}
is replaced by the name of the exported value or type. This is
only valid for the --source-entity
option.
The string %K
or %{KIND}
is replaced by a flag indicating whether the exported name is a value
'v
' or a type 't
'. This is
only valid for the --source-entity
option.
The string %L
or %{LINE}
is replaced by the number of the line where the exported value or
type is defined. This is only valid for the
--source-entity
option.
The string %%
is replaced by
%
.
For example, if your sources are online under some directory,
you would say
haddock --source-base=
url
/
--source-module=url
/%F
If you have html versions of your sources online with anchors
for each type and function name, you would say
haddock --source-base=
url
/
--source-module=url
/%M.html
--source-entity=url
/%M.html#%N
For the %{MODULE}
substitution you may want to
replace the '.
' character in the module names with
some other character (some web servers are known to get confused by
multiple '.
' characters in a file name). To
replace it with a character c
use
%{MODULE/./
.c
}
Similarly, for the %{FILE}
substitution
you may want to replace the '/
' 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 c
use
%{FILE///
/c
}
One example of a tool that can generate syntax-highlighted HTML from your source code, complete with anchors suitable for use from haddock, is hscolour.
-s
URL
,
--source
=URL
Deprecated aliases for --source-module
--comments-base
=URL
,
--comments-module
=URL
,
--comments-entity
=URL
Include links to pages where readers may comment on the documentation. This feature would typically be used in conjunction with a Wiki system.
Use the --comments-base
option to add a
user comments link in the header bar of the contents and index pages.
Use the --comments-module
to add a user comments
link in the header bar of each module page. Use the
--comments-entity
option to add a comments link
next to the documentation for every value and type in each module.
In each case URL
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 --source-module
and
--source-entity
options above.
For example, if you want to link the contents page to a wiki
page, and every module to subpages, you would say
haddock --comments-base=
url
--comments-module=url
/%M
If your Wiki system doesn't like the '.
' character
in Haskell module names, you can replace it with a different character. For
example to replace the '.
' characters with
'_
' use haddock
--comments-base=
Similarly, you can replace the 'url
--comments-module=url
/%{MODULE/./_}/
' in a file name (may
be useful for entity comments, but probably not.)
-c
file
,
--css
=file
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
file
,
--prologue
=file
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).
-t
title
,
--title
=title
Use title
as the page
heading for each page in the documentation.This will
normally be the name of the library being documented.
The title should be a plain string (no markup please!).
-d
,
--debug
Produce extra debugging output.
-?
,
--help
Display help and exit.
-v
,
--verbose
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 Prelude
).
-V
,
--version
Output version information and exit.
--use-index=URL
When generating HTML, do not generate an index.
Instead, redirect the Index link on each page to
URL
. This option is intended for
use in conjuction with --gen-index
for
generating a separate index covering multiple
libraries.
--gen-index
Generate an HTML index containing entries pulled from
all the specified interfaces (interfaces are specified using
-i
or --read-interface
).
This is used to generate a single index for multiple sets of
Haddock documentation.
--ignore-all-exports
Causes Haddock to behaves as if every module has the
ignore-exports
attribute (Section 3.7, “Module Attributes”). This might be useful for
generating implementation documentation rather than interface
documetnation, for example.
--hide
module
Causes Haddock to behaves as if module
module
has the hide
atribute. (Section 3.7, “Module Attributes”).
-w
,
--no-warnings
Turn off all warnings.
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 -cpp
option to GHC
using --optghc
.
[1] Haddock interface files are not the same as Haskell interface files, I just couldn't think of a better name.