[haddock @ 2004-08-16 19:59:36 by panne]

XMLification

1 files changed, 1437 insertions, 0 deletions

diff --git a/doc/haddock.xml b/doc/haddock.xml
new file mode 100644
index 00000000..b0592eb9
--- /dev/null
+++ b/doc/haddock.xml
@@ -0,0 +1,1437 @@
+<?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.6, 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 &amp; 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>-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 SGML DocBook
+	  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>-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>Include links to the source files in the generated
+	  documentation, where <replaceable>URL</replaceable> is the
+	  base URL where the source files can be found.</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
+	  &ldquo;Description&rdquo;.  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 documentstation.</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>
+    </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 &mdash; 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
+      &mdash; 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>--&nbsp;|</literal></quote> or
+	<quote><literal>--&nbsp;^</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>--&nbsp;*</literal></quote>,
+      <quote><literal>--&nbsp;**</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>--&nbsp;$</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>--&nbsp;$</literal></quote>, and it may be
+	  referred to by the same name in the export list.</para>
+	</listitem>
+      </itemizedlist>
+    </section>
+
+    <section>
+      <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>: the hyperlink in
+      <literal>f</literal>'s signature will point to the definition of
+      <literal>T</literal> in the documentation for module
+      <literal>A</literal>.</para>
+
+      <para>Now, module <literal>C</literal> exports both
+      <literal>T</literal> and <literal>f</literal>.  We have a choice
+      about where to point the hyperlink to <literal>T</literal> in
+      <literal>f</literal>'s type: either the definition exported by
+      module <literal>C</literal> or the definition exported by module
+      <literal>A</literal>.  Haddock takes the view that in this case
+      pointing to the definition in <literal>C</literal> is better,
+      because the programmer might not wish to expose
+      <literal>A</literal> to the programmer at all:
+      <literal>A</literal> might be a module internal to the
+      implementation of the library in which <literal>C</literal> is
+      the external interface, so linking to definitions in the current
+      module is preferrable over an imported module.</para>
+
+      <para>The general rule is this: when attempting to link an
+      instance of a type constructor or class to its definition, the
+      link is made to</para>
+      <itemizedlist>
+	<listitem>
+	  <para>the current module, if the current module exports the
+	  relevant definition, or</para>
+	</listitem>
+	<listitem>
+	  <para>the module that the entity was imported from,
+	  otherwise.  If the entity was imported via multiple routes,
+	  then Haddock picks the module listed earliest in the imports
+	  of the current module.</para>
+	</listitem>
+      </itemizedlist>
+    </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>{-&nbsp;#&nbsp;...&nbsp;-}</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 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>hide</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>
+      </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>&lt;</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>&gt;</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>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>&gt;</literal> (we often
+	call these &ldquo;bird tracks&rdquo;).  For
+	example:</para>
+
+<programlisting>
+-- | This documentation includes two blocks of code:
+--
+-- @
+--     f x = x + x
+-- @
+--
+-- &gt;  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 &lsquo;<literal>></literal>&rsquo; 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'&nbsp;a&nbsp;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
+	&ldquo;definition term&rdquo; 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>&lt;...&gt;</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>
+</book>