Chapter 2. Invoking Haddock

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
identifiers it couldn't resolve.

The modules should not be mutually
recursive, as Haddock don't like swimming in circles.

Note that while older version would fail on invalid markup, this is considered a bug in the
new versions. If you ever get failed parsing message, please report it.

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:

-Bdir

Tell GHC that that its lib directory is
dir. Can be used to override the default path.

-odir
, --odir=dir

Generate files into dir
instead of the current directory.

-ldir
, --lib=dir

Use Haddock auxiliary files (themes, javascript, etc...) in dir.

-ipath,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.

-Dfile
, --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.

-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:

module.html, mini_module.html

An HTML page for each
module, and a "mini" page for
each used when viewing in frames.

index.html

The top level page of the documentation: lists
the modules available, using indentation to represent
the hierarchy if the modules are hierarchical.

Files needed for the themes used. Specify your themes
using the --theme option.

haddock-util.js

Some JavaScript utilities used to implement some of the
dynamic features like collapsible sections, and switching to
frames view.

--latex

Generate documentation in LaTeX format. Several files
will be generated into the current directory (or the
specified directory if the -o option is
given), including the following:

package.tex

The top-level LaTeX source file; to format the
documentation into PDF you might run something like
this:

$ pdflatex package.tex

haddock.sty

The default style. The file contains
definitions for various macros used in the LaTeX
sources generated by Haddock; to change the way the
formatted output looks, you might want to override
these by specifying your own style with
the --latex-style option.

module.tex

The LaTeX documentation for
each module.

--latex-style=style

This option lets you override the default style used
by the LaTeX generated by the --latex option.
Normally Haddock puts a
standard haddock.sty in the output
directory, and includes the
command \usepackage{haddock} in the
LaTeX source. If this option is given,
then haddock.sty is not generated,
and the command is
instead \usepackage{style}.

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.
--source-entity-line is a flag that gets used for
entities that need to link to an exact source location rather than a
name, eg. since they were defined inside a Template Haskell splice.

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.

-sURL
, --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=url
--comments-module=url/%{MODULE/./_}
Similarly, you can replace the '/' in a file name (may
be useful for entity comments, but probably not.)

--theme=path

Specify a theme to be used for HTML (--html)
documentation. If given multiple times then the pages will use the
first theme given by default, and have alternate style sheets for
the others. The reader can switch between themes with browsers that
support alternate style sheets, or with the "Style" menu that gets
added when the page is loaded. If
no themes are specified, then just the default built-in theme
("Ocean") is used.

The path parameter can be one of:

A directory: The base name of
the directory becomes the name of the theme. The directory
must contain exactly one
some.css file.
Other files, usually image files, will be copied, along with
the some.css
file, into the generated output directory.

A CSS file: The base name of
the file becomes the name of the theme.

The name of a built-in theme
("Ocean" or "Classic").

--built-in-themes

Includes the built-in themes ("Ocean" and "Classic").
Can be combined with --theme. Note that order
matters: The first specified theme will be the default.

-cfile
, --css=file

Deprecated aliases for --theme

-pfile
, --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).

-ttitle
, --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!).

-qmode
, --qual=mode

Specify how identifiers are qualified.

mode should be one of

none (default): don't qualify any identifiers

full: always qualify identifiers completely

local: only qualify identifiers that are not part
of the module

relative: like local, but strip name of the module
from qualifications of identifiers in submodules

Example: If you generate documentation for module A, then the
identifiers A.x, A.B.y and C.z are qualified as follows.

none: x, y, z

full: A.x, A.B.y, C.z

local: x, A.B.y, C.z

relative: x, B.y, C.z

-?
, --help

Display help and exit.

-V
, --version

Output version information 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).

--use-contents=URL
, --use-index=URL

When generating HTML, do not generate an index.
Instead, redirect the Contents and/or Index link on each page to
URL. This option is intended for
use in conjunction with --gen-contents and/or
--gen-index for
generating a separate contents and/or index covering multiple
libraries.

--gen-contents
, --gen-index

Generate an HTML contents and/or index containing entries pulled
from all the specified interfaces (interfaces are specified using
-i or --read-interface).
This is used to generate a single contents and/or index for multiple
sets of Haddock documentation.

--ignore-all-exports

Causes Haddock to behave 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
documentation, for example.

Pass option to GHC. Note that there is a double dash there, unlike for GHC.

-w
, --no-warnings

Turn off all warnings.

--compatible-interface-versions

Prints out space-separated versions of binary Haddock interface files that this version is compatible
with.

--no-tmp-comp-dir

Do not use a temporary directory for reading and writing compilation output files
(.o, .hi, and stub files). Instead, use the
present directory or another directory that you have explicitly told GHC to use
via the --optghc flag.

This flag can be used to avoid recompilation if compilation files already exist.
Compilation files are produced when Haddock has to process modules that make use of
Template Haskell, in which case Haddock compiles the modules using the GHC API.

2.1. Using literate or pre-processed source

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.