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

XMLification

1 files changed, 0 insertions, 1435 deletions

diff --git a/doc/haddock.sgml b/doc/haddock.sgml
deleted file mode 100644
index b0e4204f..00000000
--- a/doc/haddock.sgml
+++ /dev/null
@@ -1,1435 +0,0 @@
-<!DOCTYPE BOOK PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
-
-<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>