Chapter 2. Invoking Haddock

Table of Contents

2.1. Using literate or pre-processed source

Haddock is invoked from the command line, like so:

haddock [option...] file...

Where each file is a filename containing a Haskell source module. Only plain Haskell source files are accepted (but see Section 2.1, “Using literate or pre-processed source” for instructions on how to pre-process source files for feeding to Haddock).

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.

The following options are available:

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


Like --read-interface, but use ghc-pkg to locate the interface file and HTML documentation for package, to reference when generating the documentation.

Multiple --use-package 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:


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


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.


A small piece of JavaScript for collapsing sections of the generated 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 (search for “HTML Help compiler”).


Microsoft HTML Help Viewer

Distributed with Microsoft Windows


a CHM viewer for UNIX (Linux, *BSD, Solaris), written by Razvan Cojocaru

JouleData Solutions' CHM Viewer

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.

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}.

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=url --comments-module=url/%{MODULE/./_}

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

-n , --no-implicit-prelude

Don't automatically import Prelude in every module. Used when producing documentation for the Prelude itself.

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


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.


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.

-k P , --package=P

Set the package name for these modules to P. In a combined index generated with --gen-index, the package name for each module is shown in the right-hand column.


Causes Haddock to behaves as if every module has the ignore-exports attribute (Section 3.8, “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.8, “Module Attributes”).

2.1. Using literate or pre-processed source

Haddock only accepts plain, non-literate, Haskell source. This means that if you program in Literate Haskell, or you need to use the C pre-processor in your Haskell source, then you need to pre-process the files before feeding them to Haddock. This is easily accomplished using GHC; for example, suppose we have a Literate Haskell source file Foo.lhs, on which we also need to run the C pre-processor:

$ ghc -cpp -E -optP-P -D__HADDOCK__ Foo.lhs -o Foo.hs
$ haddock -h Foo.hs ...

The -E option to GHC says "stop after pre-processing", the -cpp option turns on the C pre-processor, the -optP-P option tells the C pre-processor not to leave any extra dropping behind (see the description of the -P option in the gcc manual for details), and the -D__HADDOCK__ option defines the symbol __HADDOCK__ when pre-processing (this is sometimes handy if you need to any pre-processing conditionals in your source which depend on whether the source is going to be fed to Haddock).

[1] Haddock interface files are not the same as Haskell interface files, I just couldn't think of a better name.