<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<book id="haddock">
<bookinfo>
<date>2004-08-02</date>
<title>Haddock User Guide</title>
<author>
<firstname>Simon</firstname>
<surname>Marlow</surname>
</author>
<address><email>simonmar@microsoft.com</email></address>
<copyright>
<year>2004</year>
<holder>Simon Marlow</holder>
</copyright>
<abstract>
<para>This document describes Haddock version 0.8, a Haskell
documentation tool.</para>
</abstract>
</bookinfo>
<!-- Table of contents -->
<toc></toc>
<chapter id="introduction">
<title>Introduction</title>
<para>This is Haddock, a tool for automatically generating
documentation from annotated Haskell source code. Haddock was
designed with several goals in mind:</para>
<itemizedlist>
<listitem>
<para>When documenting APIs, it is desirable to keep the
documentation close to the actual interface or implementation
of the API, preferably in the same file, to reduce the risk
that the two become out of sync. Haddock therefore lets you
write the documentation for an entity (function, type, or
class) next to the definition of the entity in the source
code.</para>
</listitem>
<listitem>
<para>There is s tremendous amount of useful API documentation
that can be extracted from just the bare source code,
including types of exported functions, definitions of data
types and classes, and so on. Haddock can therefore generate
documentation from a set of straight Haskell 98 modules, and
the documentation will contain precisely the interface that is
available to a programmer using those modules.</para>
</listitem>
<listitem>
<para>Documentation annotations in the source code should be
easy on the eye when editing the source code itself, so as not
to obsure the code and to make reading and writing
documentation annotations easy. The easier it is to write
documentation, the more likely the programmer is to do it.
Haddock therefore uses lightweight markup in its annotations,
taking several ideas from <ulink
url="http://www.cse.unsw.edu.au/~chak/haskell/idoc/">IDoc</ulink>.
In fact, Haddock can understand IDoc-annotated source
code.</para>
</listitem>
<listitem>
<para>The documentation should not expose any of the structure
of the implementation, or to put it another way, the
implementer of the API should be free to structure the
implementation however he or she wishes, without exposing any
of that structure to the consumer. In practical terms, this
means that while an API may internally consist of several
Haskell modules, we often only want to expose a single module
to the user of the interface, where this single module just
re-exports the relevant parts of the implementation
modules.</para>
<para>Haddock therefore understands the Haskell module system
and can generate documentation which hides not only
non-exported entities from the interface, but also the
internal module structure of the interface. A documentation
annotation can still be placed next to the implementation, and
it will be propagated to the external module in the generated
documentation.</para>
</listitem>
<listitem>
<para>Being able to move around the documentation by following
hyperlinks is essential. Documentation generated by Haddock
is therefore littered with hyperlinks: every type and class
name is a link to the corresponding definition, and
user-written documentation annotations can contain identifiers
which are linked automatically when the documentation is
generated.</para>
</listitem>
<listitem>
<para>We might want documentation in multiple formats - online
and printed, for example. Haddock comes with HTML and DocBook
backends, and it is structured in such a way that adding new
back-ends is straightforward.</para>
</listitem>
</itemizedlist>
<section id="obtaining">
<title>Obtaining Haddock</title>
<para>Distributions (source & binary) of Haddock can be obtained
from its <ulink url="http://www.haskell.org/haddock/">web
site</ulink>.</para>
<para>Up-to-date sources can also be obtained from CVS. The
Haddock sources are under <literal>fptools/haddock</literal> in
the <literal>fptools</literal> CVS repository, which also
contains GHC, Happy, and several other projects. See <ulink
url="http://www.haskell.org/ghc/docs/latest/html/building/sec-cvs.html">Using
The CVS Repository</ulink> for information on how to access the
CVS repository. Note that you need to check out the
<literal>fpconfig</literal> module first to get the generic
build system (the <literal>fptools</literal> directory), and
then check out <literal>fptools/haddock</literal> to get the
Haddock sources.</para>
</section>
<section id="license">
<title>License</title>
<para>The following license covers this documentation, and the
Haddock source code, except where otherwise indicated.</para>
<blockquote>
<para>Copyright 2002, Simon Marlow. All rights reserved.</para>
<para>Redistribution and use in source and binary forms, with
or without modification, are permitted provided that the
following conditions are met:</para>
<itemizedlist>
<listitem>
<para>Redistributions of source code must retain the above
copyright notice, this list of conditions and the
following disclaimer.</para>
</listitem>
<listitem>
<para>Redistributions in binary form must reproduce the
above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other
materials provided with the distribution.</para>
</listitem>
</itemizedlist>
<para>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS "AS
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
OF SUCH DAMAGE.</para>
</blockquote>
</section>
<section>
<title>Acknowledgements</title>
<para>Several documentation systems provided the inspiration for
Haddock, most notably:</para>
<itemizedlist>
<listitem>
<para><ulink
url="http://www.cse.unsw.edu.au/~chak/haskell/idoc/">
IDoc</ulink></para>
</listitem>
<listitem>
<para><ulink
url="http://www.fmi.uni-passau.de/~groessli/hdoc/">HDoc</ulink></para>
</listitem>
<listitem>
<para><ulink url="http://www.stack.nl/~dimitri/doxygen/">
Doxygen</ulink></para>
</listitem>
</itemizedlist>
<para>and probably several others I've forgotten.</para>
<para>Thanks to the following people for useful feedback,
discussion, patches, packaging, and moral support: Simon Peyton
Jones, Mark Shields, Manuel Chakravarty, Ross Patterson, Brett
Letner, Sven Panne, Hal Daume, George Russell, Oliver Braun,
Ashley Yakeley, Malcolm Wallace, Krasimir Angelov, the members
of <email>haskelldoc@haskell.org</email>, and everyone who
contributed to the many libraries that Haddock makes use
of.</para>
</section>
</chapter>
<chapter id="invoking">
<title>Invoking Haddock</title>
<para>Haddock is invoked from the command line, like so:</para>
<cmdsynopsis>
<command>haddock</command>
<arg rep="repeat"><replaceable>option</replaceable></arg>
<arg rep="repeat" choice="plain"><replaceable>file</replaceable></arg>
</cmdsynopsis>
<para>Where each <replaceable>file</replaceable> is a filename
containing a Haskell source module. Only plain Haskell source
files are accepted (but see <xref linkend="cpp"/> for instructions
on how to pre-process source files for feeding to Haddock).</para>
<para>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.</para>
<para>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.</para>
<para>The modules should <emphasis>not</emphasis> be mutually
recursive, as Haddock don't like swimming in circles.</para>
<para>The following options are available:</para>
<variablelist>
<varlistentry>
<term>
<indexterm><primary><option>-o</option></primary></indexterm>
<option>-o</option> <replaceable>dir</replaceable>
</term>
<term>
<indexterm><primary><option>--odir</option></primary></indexterm>
<option>--odir</option>=<replaceable>dir</replaceable>
</term>
<listitem>
<para>Generate files into <replaceable>dir</replaceable>
instead of the current directory.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<indexterm><primary><option>-i</option></primary></indexterm>
<option>-i</option> <replaceable>path</replaceable>,<replaceable>file</replaceable>
</term>
<term>
<indexterm><primary><option>--read-interface</option></primary></indexterm>
<option>--read-interface</option>=<replaceable>path</replaceable>,<replaceable>file</replaceable>
</term>
<listitem>
<para>Read the interface file in
<replaceable>file</replaceable>, which must have been
produced by running Haddock with the
<option>--dump-interface</option> option. The interface
describes a set of modules whose HTML documentation is
located in <replaceable>path</replaceable> (which may be a
relative pathname). The <replaceable>path</replaceable> is
optional, and defaults to <quote>.</quote>.</para>
<para>This option allows Haddock to produce separate sets of
documentation with hyperlinks between them. The
<replaceable>path</replaceable> 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 <replaceable>path</replaceable> means that a
documentation subtree can still be moved around without
breaking links.</para>
<para>Multiple <option>--read-interface</option> options may
be given.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<indexterm><primary><option>--use-package</option></primary></indexterm>
<option>--use-package</option>=<replaceable>package</replaceable>
</term>
<listitem>
<para>Like <option>--read-interface</option>, but use
<command>ghc-pkg</command> to locate the interface file and
HTML documentation for <replaceable>package</replaceable>,
to reference when generating the documentation.</para>
<para>Multiple <option>--use-package</option> options may
be given.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<indexterm><primary><option>-D</option></primary></indexterm>
<option>-D</option> <replaceable>file</replaceable>
</term>
<term>
<indexterm><primary><option>--dump-interface</option></primary></indexterm>
<option>--dump-interface</option>=<replaceable>file</replaceable>
</term>
<listitem>
<para>Produce an <firstterm>interface
file</firstterm><footnote><para>Haddock interface files are
not the same as Haskell interface files, I just couldn't
think of a better name.</para> </footnote>
in the file <replaceable>file</replaceable>. An interface
file contains information Haddock needs to produce more
documentation that refers to the modules currently being
processed - see the <option>--read-interface</option> option
for more details. The interface file is in a binary format;
don't try to read it.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<indexterm><primary><option>-l</option></primary></indexterm>
<option>-l</option> <replaceable>dir</replaceable>
</term>
<term>
<indexterm><primary><option>--lib</option></primary></indexterm>
<option>--lib</option>=<replaceable>dir</replaceable>
</term>
<listitem>
<para>Use auxiliary files in <replaceable>dir</replaceable>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<indexterm><primary><option>-S</option></primary></indexterm>
<option>-S</option>
</term>
<term>
<indexterm><primary><option>--docbook</option></primary></indexterm>
<option>--docbook</option>
</term>
<listitem>
<para>Reserved for future use (output documentation in DocBook XML
format).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<indexterm><primary><option>-h</option></primary></indexterm>
<option>-h</option>
</term>
<term>
<indexterm><primary><option>--html</option></primary></indexterm>
<option>--html</option>
</term>
<listitem>
<para>Generate documentation in HTML format. Several files
will be generated into the current directory (or the
specified directory if the <option>-o</option> option is
given), including the following:</para>
<variablelist>
<varlistentry>
<term><filename>index.html</filename></term>
<listitem>
<para>The top level page of the documentation: lists
the modules available, using indentation to represent
the hierarchy if the modules are hierarchical.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>haddock.css</filename></term>
<listitem>
<para>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
<option>--css</option> option.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>haddock.js</filename></term>
<listitem>
<para>A small piece of JavaScript for collapsing sections
of the generated HTML.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename><replaceable>module</replaceable>.html</filename></term>
<listitem>
<para>An HTML page for each
<replaceable>module</replaceable>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>doc-index.html</filename></term>
<term><filename>doc-index-XX.html</filename></term>
<listitem>
<para>The index, split into two
(functions/constructors and types/classes, as per
Haskell namespaces) and further split
alphabetically.</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term>
<indexterm><primary><option>-m</option></primary></indexterm>
<option>-m</option>
</term>
<term>
<indexterm><primary><option>--html-help</option></primary></indexterm>
<option>--html-help</option>
</term>
<listitem>
<para>(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.</para>
<para>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.</para>
<para>In order to create a compiled Microsoft help file, you
also need the Microsoft HTML Help compiler, which is
available free from
<ulink url="http://www.microsoft.com/">http://www.microsoft.com/</ulink>
(search for <quote>HTML Help compiler</quote>).</para>
<para>Viewers</para>
<variablelist>
<varlistentry>
<term>Microsoft HTML Help Viewer</term>
<listitem><para>Distributed with Microsoft Windows</para></listitem>
</varlistentry>
<varlistentry>
<term><ulink url="http://xchm.sourceforge.net">xCHM</ulink></term>
<listitem><para>a CHM viewer for UNIX (Linux, *BSD, Solaris), written by Razvan Cojocaru</para></listitem>
</varlistentry>
<varlistentry>
<term><ulink url="http://www.jouledata.com/MacProducts.html">JouleData Solutions' CHM Viewer</ulink></term>
<listitem><para>a comercial 100% native Cocoa .chm file viewer for the Mac OS X platform</para></listitem>
</varlistentry>
<varlistentry>
<term><ulink url="http://gnochm.sourceforge.net">GnoCHM</ulink></term>
<listitem><para>a CHM file viewer. It is designed to integrate nicely with Gnome.</para></listitem>
</varlistentry>
</variablelist>
<para>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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<indexterm><primary><option>--source-base</option></primary></indexterm>
<option>--source-base</option>=<replaceable>URL</replaceable>
</term>
<term>
<indexterm><primary><option>--source-module</option></primary></indexterm>
<option>--source-module</option>=<replaceable>URL</replaceable>
</term>
<term>
<indexterm><primary><option>--source-entity</option></primary></indexterm>
<option>--source-entity</option>=<replaceable>URL</replaceable>
</term>
<listitem>
<para>Include links to the source files in the generated
documentation. Use the <option>--source-base</option> option to add a
source code link in the header bar of the contents and index pages.
Use the <option>--source-module</option> to add a source code link in
the header bar of each module page. Use the
<option>--source-entity</option> option to add a source code link
next to the documentation for every value and type in each module.
</para>
<para>In each case <replaceable>URL</replaceable> 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 <replaceable>URL</replaceable>:</para>
<itemizedlist>
<listitem>
<para>The string <literal>%M</literal> or <literal>%{MODULE}</literal>
is replaced by the module name. Note that for the per-entity URLs
this is the name of the <emphasis>exporting</emphasis> module.</para>
</listitem>
<listitem>
<para>The string <literal>%F</literal> or <literal>%{FILE}</literal>
is replaced by the original source file name. Note that for the
per-entity URLs this is the name of the <emphasis>defining</emphasis>
module.</para>
</listitem>
<listitem>
<para>The string <literal>%N</literal> or <literal>%{NAME}</literal>
is replaced by the name of the exported value or type. This is
only valid for the <option>--source-entity</option> option.</para>
</listitem>
<listitem>
<para>The string <literal>%K</literal> or <literal>%{KIND}</literal>
is replaced by a flag indicating whether the exported name is a value
'<literal>v</literal>' or a type '<literal>t</literal>'. This is
only valid for the <option>--source-entity</option> option.</para>
</listitem>
</itemizedlist>
<para>For example, if your sources are online under some directory,
you would say
<literal>haddock --source-base=<replaceable>url</replaceable>/
--source-module=<replaceable>url</replaceable>/%F</literal></para>
<para>If you have html versions of your sources online with anchors
for each type and function name, you would say
<literal>haddock --source-base=<replaceable>url</replaceable>/
--source-module=<replaceable>url</replaceable>/%M.html
--source-entity=<replaceable>url</replaceable>/%M.html#%N</literal></para>
<para>For the <literal>%{MODULE}</literal> substitution you may want to
replace the '<literal>.</literal>' character in the module names with
some other character (some web servers are known to get confused by
multiple '<literal>.</literal>' characters in a file name). To
replace it with a character <replaceable>c</replaceable> use
<literal>%{MODULE/./<replaceable>c</replaceable>}</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<indexterm><primary><option>-s</option></primary></indexterm>
<option>-s</option> <replaceable>URL</replaceable>
</term>
<term>
<indexterm><primary><option>--source</option></primary></indexterm>
<option>--source</option>=<replaceable>URL</replaceable>
</term>
<listitem>
<para>Deprecated aliases for <option>--source-module</option></para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<indexterm><primary><option>--comments-base</option></primary></indexterm>
<option>--comments-base</option>=<replaceable>URL</replaceable>
</term>
<term>
<indexterm><primary><option>--comments-module</option></primary></indexterm>
<option>--comments-module</option>=<replaceable>URL</replaceable>
</term>
<term>
<indexterm><primary><option>--comments-entity</option></primary></indexterm>
<option>--comments-entity</option>=<replaceable>URL</replaceable>
</term>
<listitem>
<para>Include links to pages where readers may comment on the
documentation. This feature would typically be used in conjunction
with a Wiki system.</para>
<para>Use the <option>--comments-base</option> option to add a
user comments link in the header bar of the contents and index pages.
Use the <option>--comments-module</option> to add a user comments
link in the header bar of each module page. Use the
<option>--comments-entity</option> option to add a comments link
next to the documentation for every value and type in each module.
</para>
<para>In each case <replaceable>URL</replaceable> 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 <option>--source-module</option> and
<option>--source-entity</option> options above.</para>
<para>For example, if you want to link the contents page to a wiki
page, and every module to subpages, you would say
<literal>haddock --comments-base=<replaceable>url</replaceable>
--comments-module=<replaceable>url</replaceable>/%M</literal></para>
<para>If your Wiki system doesn't like the '<literal>.</literal>'
character in Haskell module names, you can replace it with a
different character. For example to replace the
'<literal>.</literal>' characters with '<literal>_</literal>' use
<literal>haddock --comments-base=<replaceable>url</replaceable>
--comments-module=<replaceable>url</replaceable>/%{MODULE/./_}</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<indexterm><primary><option>-c</option></primary></indexterm>
<option>-c</option> <replaceable>file</replaceable>
</term>
<term>
<indexterm><primary><option>--css</option></primary></indexterm>
<option>--css</option>=<replaceable>file</replaceable>
</term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<indexterm><primary><option>-p</option></primary></indexterm>
<option>-p</option> <replaceable>file</replaceable>
</term>
<term>
<indexterm><primary><option>--prologue</option></primary></indexterm>
<option>--prologue</option>=<replaceable>file</replaceable>
</term>
<listitem>
<para>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).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<indexterm><primary><option>-t</option></primary></indexterm>
<option>-t</option> <replaceable>title</replaceable>
</term>
<term>
<indexterm><primary><option>--title</option></primary></indexterm>
<option>--title</option>=<replaceable>title</replaceable>
</term>
<listitem>
<para>Use <replaceable>title</replaceable> as the page
heading for each page in the documentation.This will
normally be the name of the library being documented.</para>
<para>The title should be a plain string (no markup
please!).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<indexterm><primary><option>-n</option></primary></indexterm>
<option>-n</option>
</term>
<term>
<indexterm><primary><option>--no-implicit-prelude</option></primary></indexterm>
<option>--no-implicit-prelude</option>
</term>
<listitem>
<para>Don't automatically import <literal>Prelude</literal>
in every module. Used when producing documentation for the
<literal>Prelude</literal> itself.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<indexterm><primary><option>-d</option></primary></indexterm>
<option>-d</option>
</term>
<term>
<indexterm><primary><option>--debug</option></primary></indexterm>
<option>--debug</option>
</term>
<listitem>
<para>Produce extra debugging output.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<indexterm><primary><option>-?</option></primary></indexterm>
<option>-?</option>
</term>
<term>
<indexterm><primary><option>--help</option></primary></indexterm>
<option>--help</option>
</term>
<listitem>
<para>Display help and exit.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<indexterm><primary><option>-v</option></primary></indexterm>
<option>-v</option>
</term>
<term>
<indexterm><primary><option>--verbose</option></primary></indexterm>
<option>--verbose</option>
</term>
<listitem>
<para>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 <literal>Prelude</literal>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<indexterm><primary><option>-V</option></primary></indexterm>
<option>-V</option>
</term>
<term>
<indexterm><primary><option>--version</option></primary></indexterm>
<option>--version</option>
</term>
<listitem>
<para>Output version information and exit.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<indexterm><primary><option>--use-index</option></primary></indexterm>
<option>--use-index=<replaceable>URL</replaceable></option>
</term>
<listitem>
<para>When generating HTML, do not generate an index.
Instead, redirect the Index link on each page to
<replaceable>URL</replaceable>. This option is intended for
use in conjuction with <option>--gen-index</option> for
generating a separate index covering multiple
libraries.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<indexterm><primary><option>--gen-index</option></primary></indexterm>
<option>--gen-index</option>
</term>
<listitem>
<para>Generate an HTML index containing entries pulled from
all the specified interfaces (interfaces are specified using
<option>-i</option> or <option>--read-interface</option>).
This is used to generate a single index for multiple sets of
Haddock documentation.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<indexterm><primary><option>-k</option></primary></indexterm>
<option>-k</option> <replaceable>P</replaceable>
</term>
<term>
<indexterm><primary><option>--package</option></primary></indexterm>
<option>--package=</option><replaceable>P</replaceable>
</term>
<listitem>
<para>Set the package name for these modules to
<replaceable>P</replaceable>. In a combined index generated
with <option>--gen-index</option>, the package name for each
module is shown in the right-hand column.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<indexterm><primary><option>--ignore-all-exports</option></primary>
</indexterm>
<option>--ignore-all-exports</option>
</term>
<listitem>
<para>Causes Haddock to behaves as if every module has the
<literal>ignore-exports</literal> attribute (<xref
linkend="module-attributes" />). This might be useful for
generating implementation documentation rather than interface
documetnation, for example.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<indexterm><primary><option>--hide</option></primary>
</indexterm>
<option>--hide</option> <replaceable>module</replaceable>
</term>
<listitem>
<para>Causes Haddock to behaves as if module
<replaceable>module</replaceable> has the <literal>hide</literal>
atribute. (<xref linkend="module-attributes" />).</para>
</listitem>
</varlistentry>
</variablelist>
<section id="cpp">
<title>Using literate or pre-processed source</title>
<para>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 <filename>Foo.lhs</filename>, on
which we also need to run the C pre-processor:</para>
<screen>
$ ghc -cpp -E -optP-P -D__HADDOCK__ Foo.lhs -o Foo.hs
$ haddock -h Foo.hs ...
</screen>
<para>The <option>-E</option> option to GHC says "stop after
pre-processing", the <option>-cpp</option> option turns on the C
pre-processor, the <option>-optP-P</option> option tells the C
pre-processor not to leave any extra dropping behind (see the
description of the <option>-P</option> option in the gcc manual
for details), and the <option>-D__HADDOCK__</option> option
defines the symbol <literal>__HADDOCK__</literal> 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).</para>
</section>
</chapter>
<chapter id="markup">
<title>Documentation and Markup</title>
<para>Haddock understands special documentation annotations in the
Haskell source file and propagates these into the generated
documentation. The annotations are purely optional: if there are
no annotations, Haddock will just generate documentation that
contains the type signatures, data type declarations, and class
declarations exported by each of the modules being
processed.</para>
<section>
<title>Documenting a top-level declaration</title>
<para>The simplest example of a documentation annotation is for
documenting any top-level declaration (function type signature,
type declaration, or class declaration). For example, if the
source file contains the following type signature:</para>
<programlisting>
square :: Int -> Int
square x = x * x
</programlisting>
<para>Then we can document it like this:</para>
<programlisting>
-- |The 'square' function squares an integer.
square :: Int -> Int
square x = x * x
</programlisting>
<para>The <quote><literal>-- |</literal></quote> syntax begins a
documentation annotation, which applies to the
<emphasis>following</emphasis> declaration in the source file.
Note that the annotation is just a comment in Haskell — it
will be ignored by the Haskell compiler.</para>
<para>The declaration following a documentation annotation
should be one of the following:</para>
<itemizedlist>
<listitem>
<para>A type signature for a top-level function,</para>
</listitem>
<listitem>
<para>A <literal>data</literal> declaration,</para>
</listitem>
<listitem>
<para>A <literal>newtype</literal> declaration,</para>
</listitem>
<listitem>
<para>A <literal>type</literal> declaration, or</para>
</listitem>
<listitem>
<para>A <literal>class</literal> declaration.</para>
</listitem>
</itemizedlist>
<para>If the annotation is followed by a different kind of
declaration, it will probably be ignored by Haddock.</para>
<para>Some people like to write their documentation
<emphasis>after</emphasis> the declaration; this is possible in
Haddock too:</para>
<programlisting>
square :: Int -> Int
-- ^The 'square' function squares an integer.
square x = x * x
</programlisting>
<para>Note that Haddock doesn't contain a Haskell type system
— if you don't write the type signature for a function,
then Haddock can't tell what its type is and it won't be
included in the documentation.</para>
<para>Documentation annotations may span several lines; the
annotation continues until the first non-comment line in the
source file. For example:</para>
<programlisting>
-- |The 'square' function squares an integer.
-- It takes one argument, of type 'Int'.
square :: Int -> Int
square x = x * x
</programlisting>
<para>You can also use Haskell's nested-comment style for
documentation annotations, which is sometimes more convenient
when using multi-line comments:</para>
<programlisting>
{-|
The 'square' function squares an integer.
It takes one argument, of type 'Int'.
-}
square :: Int -> Int
square x = x * x
</programlisting>
</section>
<section>
<title>Documenting parts of a declaration</title>
<para>In addition to documenting the whole declaration, in some
cases we can also document individual parts of the
declaration.</para>
<section>
<title>Class methods</title>
<para>Class methods are documented in the same way as top
level type signatures, by using either the
<quote><literal>-- |</literal></quote> or
<quote><literal>-- ^</literal></quote>
annotations:</para>
<programlisting>
class C a where
-- | This is the documentation for the 'f' method
f :: a -> Int
-- | This is the documentation for the 'g' method
g :: Int -> a
</programlisting>
</section>
<section>
<title>Constructors and record fields</title>
<para>Constructors are documented like so:</para>
<programlisting>
data T a b
-- | This is the documentation for the 'C1' constructor
= C1 a b
-- | This is the documentation for the 'C2' constructor
| C2 a b
</programlisting>
<para>or like this:</para>
<programlisting>
data T a b
= C1 a b -- ^ This is the documentation for the 'C1' constructor
| C2 a b -- ^ This is the documentation for the 'C2' constructor
</programlisting>
<para>Record fields are documented using one of these
styles:</para>
<programlisting>
data R a b =
C { -- | This is the documentation for the 'a' field
a :: a,
-- | This is the documentation for the 'b' field
b :: b
}
data R a b =
C { a :: a -- ^ This is the documentation for the 'a' field
, b :: b -- ^ This is the documentation for the 'b' field
}
</programlisting>
<para>Alternative layout styles are generally accepted by
Haddock - for example doc comments can appear before or after
the comma in separated lists such as the list of record fields
above.</para>
</section>
<section>
<title>Function arguments</title>
<para>Individual arguments to a function may be documented
like this:</para>
<programlisting>
f :: Int -- ^ The 'Int' argument
-> Float -- ^ The 'Float' argument
-> IO () -- ^ The return value
</programlisting>
</section>
</section>
<section>
<title>The module description</title>
<para>A module may contain a documentation comment before the
module header, in which case this comment is interpreted by
Haddock as an overall description of the module itself, and
placed in a section entitled <quote>Description</quote> in the
documentation for the module. For example:</para>
<programlisting>
-- | This is the description for module "Foo"
module Foo where
...
</programlisting>
</section>
<section>
<title>Controlling the documentation structure</title>
<para>Haddock produces interface documentation that lists only
the entities actually exported by the module. The documentation
for a module will include <emphasis>all</emphasis> entities
exported by that module, even if they were re-exported by
another module. The only exception is when Haddock can't see
the declaration for the re-exported entity, perhaps because it
isn't part of the batch of modules currently being
processed.</para>
<para>However, to Haddock the export list has even more
significance than just specifying the entities to be included in
the documentation. It also specifies the
<emphasis>order</emphasis> that entities will be listed in the
generated documentation. This leaves the programmer free to
implement functions in any order he/she pleases, and indeed in
any <emphasis>module</emphasis> he/she pleases, but still
specify the order that the functions should be documented in the
export list. Indeed, many programmers already do this: the
export list is often used as a kind of ad-hoc interface
documentation, with headings, groups of functions, type
signatures and declarations in comments.</para>
<para>You can insert headings and sub-headings in the
documentation by including annotations at the appropriate point
in the export list. For example:</para>
<programlisting>
module Foo (
-- * Classes
C(..),
-- * Types
-- ** A data type
T,
-- ** A record
R,
-- * Some functions
f, g
) where
</programlisting>
<para>Headings are introduced with the syntax
<quote><literal>-- *</literal></quote>,
<quote><literal>-- **</literal></quote> and so on, where
the number of <literal>*</literal>s indicates the level of the
heading (section, sub-section, sub-sub-section, etc.).</para>
<para>If you use section headings, then Haddock will generate a
table of contents at the top of the module documentation for
you.</para>
<para>The alternative style of placing the commas at the
beginning of each line is also supported. eg.:</para>
<programlisting>
module Foo (
-- * Classes
, C(..)
-- * Types
-- ** A data type
, T
-- ** A record
, R
-- * Some functions
, f
, g
) where
</programlisting>
<section>
<title>Re-exporting an entire module</title>
<para>Haskell allows you to re-export the entire contents of a
module (or at least, everything currently in scope that was
imported from a given module) by listing it in the export
list:</para>
<programlisting>
module A (
module B,
module C
) where
</programlisting>
<para>What will the Haddock-generated documentation for this
module look like? Well, it depends on how the modules
<literal>B</literal> and <literal>C</literal> are imported.
If they are imported wholly and without any
<literal>hiding</literal> qualifiers, then the documentation
will just contain a cross-reference to the documentation for
<literal>B</literal> and <literal>C</literal>. However, if
the modules are not <emphasis>completely</emphasis>
re-exported, for example:</para>
<programlisting>
module A (
module B,
module C
) where
import B hiding (f)
import C (a, b)
</programlisting>
<para>then Haddock behaves as if the set of entities
re-exported from <literal>B</literal> and <literal>C</literal>
had been listed explicitly in the export
list<footnote><para>NOTE: this is not fully implemented at the
time of writing (version 0.2). At the moment, Haddock always
inserts a cross-reference.</para>
</footnote>.</para>
<para>The exception to this rule is when the re-exported
module is declared with the <literal>hide</literal> attribute
(<xref linkend="module-attributes"/>), in which case the module
is never cross-referenced; the contents are always expanded in
place in the re-exporting module.</para>
</section>
<section>
<title>Omitting the export list</title>
<para>If there is no export list in the module, how does
Haddock generate documentation? Well, when the export list is
omitted, e.g.:</para>
<programlisting>module Foo where</programlisting>
<para>this is equivalent to an export list which mentions
every entity defined at the top level in this module, and
Haddock treats it in the same way. Furthermore, the generated
documentation will retain the order in which entities are
defined in the module. In this special case the module body
may also include section headings (normally they would be
ignored by Haddock).</para>
</section>
</section>
<section>
<title>Named chunks of documentation</title>
<para>Occasionally it is desirable to include a chunk of
documentation which is not attached to any particular Haskell
declaration. There are two ways to do this:</para>
<itemizedlist>
<listitem>
<para>The documentation can be included in the export list
directly, e.g.:</para>
<programlisting>
module Foo (
-- * A section heading
-- | Some documentation not attached to a particular Haskell entity
...
) where
</programlisting>
</listitem>
<listitem>
<para>If the documentation is large and placing it inline in
the export list might bloat the export list and obscure the
structure, then it can be given a name and placed out of
line in the body of the module. This is achieved with a
special form of documentation annotation
<quote><literal>-- $</literal></quote>:</para>
<programlisting>
module Foo (
-- * A section heading
-- $doc
...
) where
-- $doc
-- Here is a large chunk of documentation which may be referred to by
-- the name $doc.
</programlisting>
<para>The documentation chunk is given a name, which is the
sequence of alphanumeric characters directly after the
<quote><literal>-- $</literal></quote>, and it may be
referred to by the same name in the export list.</para>
</listitem>
</itemizedlist>
</section>
<section id="hyperlinking">
<title>Hyperlinking and re-exported entities</title>
<para>When Haddock renders a type in the generated
documentation, it hyperlinks all the type constructors and class
names in that type to their respective definitions. But for a
given type constructor or class there may be several modules
re-exporting it, and therefore several modules whose
documentation contains the definition of that type or class
(possibly including the current module!) so which one do we link
to?</para>
<para>Let's look at an example. Suppose we have three modules
<literal>A</literal>, <literal>B</literal> and
<literal>C</literal> defined as follows:</para>
<programlisting>
module A (T) where
data T a = C a
module B (f) where
import A
f :: T Int -> Int
f (C i) = i
module C (T, f) where
import A
import B
</programlisting>
<para>Module <literal>A</literal> exports a datatype
<literal>T</literal>. Module <literal>B</literal> imports
<literal>A</literal> and exports a function <literal>f</literal>
whose type refers to <literal>T</literal>. Also, both
<literal>T</literal> and <literal>f</literal> are re-exported from
module C.</para>
<para>Haddock takes the view that each entity has a
<emphasis>home</emphasis> module; that is, the module that the library
designer would most like to direct the user to, to find the
documentation for that entity. So, Haddock makes all links to an entity
point to the home module. The one exception is when the entity is also
exported by the current module: Haddock makes a local link if it
can.</para>
<para>How is the home module for an entity determined?
Haddock uses the following rules:</para>
<itemizedlist>
<listitem>
<para>If modules A and B both export the entity, and module A imports
(directly or indirectly) module B, then B is preferred.</para>
</listitem>
<listitem>
<para>A module with the <literal>hide</literal> attribute is never
chosen as the home.</para>
</listitem>
<listitem>
<para>A module with the <literal>not-home</literal> atribute is only
chosen if there are no other modules to choose.</para>
</listitem>
</itemizedlist>
<para>If multiple modules fit the criteria, then one is chosen at
random. If no modules fit the criteria (because the candidates are all
hidden), then Haddock will issue a warning for each reference to an
entity without a home.</para>
<para>In the example above, module <literal>A</literal> is chosen as the
home for <literal>T</literal> because it does not import any other
module that exports <literal>T</literal>. The link from
<literal>f</literal>'s
type in module <literal>B</literal> will therefore point to
<literal>A.T</literal>. However, <literal>C</literal> also exports
<literal>T</literal> and <literal>f</literal>, and the link from
<literal>f</literal>'s type in <literal>C</literal> will therefore
point locally to <literal>C.T</literal>.</para>
</section>
<section id="deriving">
<title>Derived instances</title>
<para>The <literal>deriving</literal> keyword in Haskell
presents a small problem for Haddock. Lacking a full type
system, Haddock has to figure out what the shape of the derived
instance is. There is currently a partial implementation of
this, but for some data types Haddock can't determine the shape
of the derived instance, and you see something like
“???” in the documentation.</para>
<para>One workaround for this is to use CPP (<xref linkend="cpp"
/>) to give Haddock explicit instance headers. Here is an
example from the OpenGL library:</para>
<programlisting>
data VertexArrayDescriptor a =
VertexArrayDescriptor !NumComponents !DataType !Stride !(Ptr a)
#ifdef __HADDOCK__
-- Help Haddock a bit, because it doesn't do any instance inference.
instance Eq (VertexArrayDescriptor a)
instance Ord (VertexArrayDescriptor a)
instance Show (VertexArrayDescriptor a)
#else
deriving ( Eq, Ord, Show )
#endif
</programlisting>
<para>As a rule of thumb, try <literal>deriving</literal> first,
and if that doesn't work then use the above workaround.</para>
</section>
<section id="module-attributes">
<title>Module Attributes</title>
<para>Certain attributes may be specified for each module which
affects the way that Haddock generates documentation for that
module. Attributes are specified in a comma-separated list in a
<literal>-- #</literal> (or
<literal>{- # ... -}</literal>) comment at the
top of the module, either before or after the module
description. For example:</para>
<programlisting>
-- #hide, prune, ignore-exports
-- |Module description
module A where
...
</programlisting>
<para>The options and module description can be in either order, but
remember to separate them using a blank line if you are using the
<literal>--</literal> style comments. Without the blank line in the
example above, the module description would be assumed to be part of
the options, and Haddock would complain about unrecognised
options.</para>
<para>The following attributes are currently understood by
Haddock:</para>
<variablelist>
<varlistentry>
<term>
<indexterm><primary><literal>hide</literal></primary></indexterm>
<literal>hide</literal>
</term>
<listitem>
<para>Omit this module from the generated documentation,
but nevertheless propagate definitions and documentation
from within this module to modules that re-export those
definitions.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<indexterm><primary><literal>hide</literal></primary></indexterm>
<literal>prune</literal>
</term>
<listitem>
<para>Omit definitions that have no documentation
annotations from the generated documentation.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<indexterm><primary><literal>ignore-exports</literal></primary></indexterm>
<literal>ignore-exports</literal>
</term>
<listitem>
<para>Ignore the export list. Generate documentation as
if the module had no export list - i.e. all the top-level
declarations are exported, and section headings may be
given in the body of the module.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<indexterm><primary><literal>not-home</literal></primary>
</indexterm>
</term>
<listitem>
<para>Indicates that the current module should not be considered to
be the home module for each entity it exports,
unless that entity is not exported from any other module. See
<xref linkend="hyperlinking" /> for more details.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>Markup</title>
<para>Haddock understands certain textual cues inside
documentation annotations that tell it how to render the
documentation. The cues (or <quote>markup</quote>) have been
designed to be simple and mnemonic in ASCII so that the
programmer doesn't have to deal with heavyweight annotations
when editing documentation comments.</para>
<section>
<title>Paragraphs</title>
<para>One or more blank lines separates two paragraphs in a
documentation comment.</para>
</section>
<section>
<title>Special characters</title>
<para>The following characters have special meanings in
documentation comments: <literal>/</literal>,
<literal>'</literal>, <literal>`</literal>,
<literal>"</literal>, <literal>@</literal>,
<literal><</literal>. To insert a literal occurrence of
one of these special characters, precede it with a backslash
(<literal>\</literal>).</para>
<para>Additionally, the character <literal>></literal> has
a special meaning at the beginning of a line, and the
following characters have special meanings at the beginning of
a paragraph:
<literal>*</literal>, <literal>-</literal>. These characters
can also be escaped using <literal>\</literal>.</para>
</section>
<section>
<title>Character references</title>
<para>Although Haskell source files may contain any character
from the Unicode character set, the encoding of these characters
as bytes varies between systems, so that only source files
restricted to the ASCII character set are portable. Other
characters may be specified in character and string literals
using Haskell character escapes. To represent such characters
in documentation comments, Haddock supports SGML-style numeric
character references of the forms
<literal>&#</literal><replaceable>D</replaceable><literal>;</literal>
and
<literal>&#x</literal><replaceable>H</replaceable><literal>;</literal>
where <replaceable>D</replaceable> and <replaceable>H</replaceable>
are decimal and hexadecimal numbers denoting a code position
in Unicode (or ISO 10646). For example, the references
<literal>&#x3BB;</literal>, <literal>&#x3bb;</literal>
and <literal>&#955;</literal> all represent the lower-case
letter lambda.</para>
</section>
<section>
<title>Code Blocks</title>
<para>Displayed blocks of code are indicated by surrounding a
paragraph with <literal>@...@</literal> or by preceding each
line of a paragraph with <literal>></literal> (we often
call these “bird tracks”). For
example:</para>
<programlisting>
-- | This documentation includes two blocks of code:
--
-- @
-- f x = x + x
-- @
--
-- > g x = x * 42
</programlisting>
<para>There is an important difference between the two forms
of code block: in the bird-track form, the text to the right
of the ‘<literal>></literal>’ is interpreted
literally, whereas the <literal>@...@</literal> form
interprets markup as normal inside the code block.</para>
</section>
<section>
<title>Hyperlinked Identifiers</title>
<para>Referring to a Haskell identifier, whether it be a type,
class, constructor, or function, is done by surrounding it
with single quotes:</para>
<programlisting>
-- | This module defines the type 'T'.
</programlisting>
<para>If there is an entity <literal>T</literal> in scope in
the current module, then the documentation will hyperlink the
reference in the text to the definition of
<literal>T</literal> (if the output format supports
hyperlinking, of course; in a printed format it might instead
insert a page reference to the definition).</para>
<para>It is also possible to refer to entities that are not in
scope in the current module, by giving the full qualified name
of the entity:</para>
<programlisting>
-- | The identifier 'M.T' is not in scope
</programlisting>
<para>If <literal>M.T</literal> is not otherwise in scope,
then Haddock will simply emit a link pointing to the entity
<literal>T</literal> exported from module <literal>M</literal>
(without checking to see whether either <literal>M</literal>
or <literal>M.T</literal> exist).</para>
<para>To make life easier for documentation writers, a quoted
identifier is only interpreted as such if the quotes surround
a lexically valid Haskell identifier. This means, for
example, that it normally isn't necessary to escape the single
quote when used as an apostrophe:</para>
<programlisting>
-- | I don't have to escape my apostrophes; great, isn't it?
</programlisting>
<para>For compatibility with other systems, the following
alternative form of markup is accepted<footnote><para>
We chose not to use this as the primary markup for
identifiers because strictly speaking the <literal>`</literal>
character should not be used as a left quote, it is a grave accent.</para>
</footnote>: <literal>`T'</literal>.</para>
</section>
<section>
<title>Emphasis and Monospaced text</title>
<para>Emphasis may be added by surrounding text with
<literal>/.../</literal>.</para>
<para>Monospaced (or typewriter) text is indicated by
surrounding it with <literal>@...@</literal>. Other markup is
valid inside a monospaced span: for example
<literal>@'f' a b@</literal> will hyperlink the
identifier <literal>f</literal> inside the code fragment.</para>
</section>
<section>
<title>Linking to modules</title>
<para>Linking to a module is done by surrounding the module
name with double quotes:</para>
<programlisting>
-- | This is a reference to the "Foo" module.
</programlisting>
</section>
<section>
<title>Itemized and Enumerated lists</title>
<para>A bulleted item is represented by preceding a paragraph
with either <quote><literal>*</literal></quote> or
<quote><literal>-</literal></quote>. A sequence of bulleted
paragraphs is rendered as an itemized list in the generated
documentation, eg.:</para>
<programlisting>
-- | This is a bulleted list:
--
-- * first item
--
-- * second item
</programlisting>
<para>An enumerated list is similar, except each paragraph
must be preceded by either
<quote><literal>(<replaceable>n</replaceable>)</literal></quote>
or
<quote><literal><replaceable>n</replaceable>.</literal></quote>
where <replaceable>n</replaceable> is any integer. e.g.</para>
<programlisting>
-- | This is an enumerated list:
--
-- (1) first item
--
-- 2. second item
</programlisting>
</section>
<section>
<title>Definition lists</title>
<para>Definition lists are written as follows:</para>
<programlisting>
-- | This is a definition list:
--
-- [@foo@] The description of @foo@.
--
-- [@bar@] The description of @bar@.
</programlisting>
<para>To produce output something like this:</para>
<variablelist>
<varlistentry>
<term><literal>foo</literal></term>
<listitem>
<para>The description of <literal>foo</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>bar</literal></term>
<listitem>
<para>The description of <literal>bar</literal>.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Each paragraph should be preceded by the
“definition term” enclosed in square brackets.
The square bracket characters have no special meaning outside
the beginning of a definition paragraph. That is, if a
paragraph begins with a <literal>[</literal> character, then
it is assumed to be a definition paragraph, and the next
<literal>]</literal> character found will close the definition
term. Other markup operators may be used freely within the
definition term.</para>
</section>
<section>
<title>URLs</title>
<para>A URL can be included in a documentation comment by
surrounding it in angle brackets:
<literal><...></literal>. If the output format supports
it, the URL will be turned into a hyperlink when
rendered.</para>
</section>
<section>
<title>Anchors</title>
<para>Sometimes it is useful to be able to link to a point in
the documentation which doesn't correspond to a particular
entity. For that purpose, we allow <emphasis>anchors</emphasis> to be
included in a documentation comment. The syntax is
<literal>#<replaceable>label</replaceable>#</literal>, where
<replaceable>label</replaceable> is the name of the anchor.
An anchor is invisible in the generated documentation.</para>
<para>To link to an anchor from elsewhere, use the syntax
<literal>"<replaceable>module</replaceable>#<replaceable>label</replaceable>"</literal>
where <replaceable>module</replaceable> is the module name
containing the anchor, and <replaceable>label</replaceable> is
the anchor label. The module does not have to be local, it
can be imported via an interface.</para>
</section>
</section>
</chapter>
<index/>
</book>