Chapter 2. Invoking Haddock
Prev |  | Next

# Chapter 2. Invoking Haddock

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

`-B` `dir`

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

`-o` `dir` , `--odir`=`dir`

  Generate files into `dir` instead of the current directory.

`-l` `dir` , `--lib`=`dir`

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

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

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

  `doc-index.html`, `doc-index-`X`.html`

    The alphabetic index, possibly split into multiple pages if big enough.

  `frames.html`

    The top level document when viewing in frames.

  ``some`.css`, ``etc...``

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

`-S` , `--docbook`

  Reserved for future use (output documentation in DocBook XML format).

`--source-base`=`URL` , `--source-module`=`URL` , `--source-entity`=`URL` , `--source-entity-line`=`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. `--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.

`-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/./_}` 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.

`-c` `file` , `--css`=`file`

  Deprecated aliases for `--theme`

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

`-q` `mode` , `--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.

`--hide` `module`

  Causes Haddock to behave as if module `module` has the `hide` attribute. (Section 3.7, “Module Attributes”).

`--show-extensions` `module`

  Causes Haddock to behave as if module `module` has the `show-extensions` attribute. (Section 3.7, “Module Attributes”).

`--optghc`=`option`

  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.

`--print-missing-docs`

  Print extra information about any undocumented entities.

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

Prev |  | Next
1.4. Acknowledgements | Home | Chapter 3. Documentation and Markup