path: root/doc/haddock.xml

<?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>marlowsd@gmail.com</email></address>
    <author>
      <firstname>David</firstname>
      <surname>Waern</surname>
    </author>
    <address><email>david.waern@gmail.com</email></address>
    <copyright>
      <year>2010</year>
      <holder>Simon Marlow, David Waern</holder>
    </copyright>
    <abstract>
      <para>This document describes Haddock version 2.14.0, 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 a 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 obscure 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, LaTeX,
  and Hoogle backends, and it is structured in such a way that adding new
	backends 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 our public
      darcs repository.  The Haddock sources are at
      <literal>http://code.haskell.org/haddock</literal>.  See
      <ulink url="http://www.darcs.net/">darcs.net</ulink> for more
      information on the darcs version control utility.</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-2010, 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>Contributors</title>
      <para>Haddock was originally written by Simon Marlow. Since it is an open source
      project, many people have contributed to its development over the years.
      Below is a list of contributors in alphabetical order that we hope is
      somewhat complete. If you think you are missing from this list, please contact
      us.
      </para>
      <itemizedlist>
	<listitem><simpara>Ashley Yakeley</simpara></listitem>
	<listitem><simpara>Benjamin Franksen</simpara></listitem>
	<listitem><simpara>Brett Letner</simpara></listitem>
        <listitem><simpara>Clemens Fruhwirth</simpara></listitem>
        <listitem><simpara>Conal Elliott</simpara></listitem>
        <listitem><simpara>David Waern</simpara></listitem>
        <listitem><simpara>Duncan Coutts</simpara></listitem>
        <listitem><simpara>George Pollard</simpara></listitem>
        <listitem><simpara>George Russel</simpara></listitem>
        <listitem><simpara>Hal Daume</simpara></listitem>
        <listitem><simpara>Ian Lynagh</simpara></listitem>
        <listitem><simpara>Isaac Dupree</simpara></listitem>
        <listitem><simpara>Joachim Breitner</simpara></listitem>
        <listitem><simpara>Krasimir Angelov</simpara></listitem>
        <listitem><simpara>Lennart Augustsson</simpara></listitem>
        <listitem><simpara>Luke Plant</simpara></listitem>
        <listitem><simpara>Malcolm Wallace</simpara></listitem>
        <listitem><simpara>Manuel Chakravarty</simpara></listitem>
        <listitem><simpara>Mark Lentczner</simpara></listitem>
        <listitem><simpara>Mark Shields</simpara></listitem>
        <listitem><simpara>Mateusz Kowalczyk</simpara></listitem>
        <listitem><simpara>Mike Thomas</simpara></listitem>
        <listitem><simpara>Neil Mitchell</simpara></listitem>
        <listitem><simpara>Oliver Brown</simpara></listitem>
        <listitem><simpara>Roman Cheplyaka</simpara></listitem>
        <listitem><simpara>Ross Paterson</simpara></listitem>
        <listitem><simpara>Sigbjorn Finne</simpara></listitem>
        <listitem><simpara>Simon Hengel</simpara></listitem>
        <listitem><simpara>Simon Marlow</simpara></listitem>
        <listitem><simpara>Simon Peyton-Jones</simpara></listitem>
        <listitem><simpara>Stefan O'Rear</simpara></listitem>
        <listitem><simpara>Sven Panne</simpara></listitem>
        <listitem><simpara>Thomas Schilling</simpara></listitem>
        <listitem><simpara>Wolfgang Jeltsch</simpara></listitem>
        <listitem><simpara>Yitzchak Gale</simpara></listitem>
      </itemizedlist>
    </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 the members
      of <email>haskelldoc@haskell.org</email>,
      <email>haddock@projects.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 (.hs) or a Literate Haskell source
    module (.lhs) or just a module name.</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
    identifiers 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>Note that while older version would fail on invalid markup, this is considered a bug in the
    new versions. If you ever get failed parsing message, please report it.</para>

    <para>You must also specify an option for the output format.
    Currently only the <option>-h</option> option for HTML and the
    <option>--hoogle</option> option for outputting Hoogle data are
    functional.</para>

    <para>The packaging
    tool <ulink url="http://www.haskell.org/ghc/docs/latest/html/Cabal/index.html">Cabal</ulink>
    has Haddock support, and is often used instead of invoking Haddock
    directly.</para>

    <para>The following options are available:</para>

    <variablelist>

      <varlistentry>
	<term>
          <indexterm><primary><option>-B</option></primary></indexterm>
          <option>-B</option> <replaceable>dir</replaceable>
        </term>
	<listitem>
	  <para>Tell GHC that that its lib directory is
    <replaceable>dir</replaceable>. Can be used to override the default path.</para>
	</listitem>
      </varlistentry>

      <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>-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 Haddock auxiliary files (themes, javascript, etc...) in <replaceable>dir</replaceable>.</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>-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><replaceable>module</replaceable>.html</filename></term>
	      <term><filename>mini_<replaceable>module</replaceable>.html</filename></term>
	      <listitem>
		<para>An HTML page for each
		<replaceable>module</replaceable>, and a "mini" page for
		each used when viewing in frames.</para>
	      </listitem>
	    </varlistentry>
	    <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>doc-index.html</filename></term>
	      <term><filename>doc-index-<replaceable>X</replaceable>.html</filename></term>
	      <listitem>
		<para>The alphabetic index, possibly split into multiple
		pages if big enough.</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><filename>frames.html</filename></term>
	      <listitem>
		<para>The top level document when viewing in frames.</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><filename><replaceable>some</replaceable>.css</filename></term>
	      <term><filename><replaceable>etc...</replaceable></filename></term>
	      <listitem>
		<para>Files needed for the themes used. Specify your themes
		using the <option>--theme</option> option.</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><filename>haddock-util.js</filename></term>
	      <listitem>
		<para>Some JavaScript utilities used to implement some of the
		dynamic features like collapsible sections, and switching to
		frames view.</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>
	</listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>--latex</option></primary></indexterm>
          <option>--latex</option>
        </term>
        <listitem>
          <para>Generate documentation in LaTeX 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><replaceable>package</replaceable>.tex</filename></term>
	      <listitem>
                <para>The top-level LaTeX source file; to format the
                documentation into PDF you might run something like
                  this:</para>
<screen>
$ pdflatex <replaceable>package</replaceable>.tex</screen>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term><filename>haddock.sty</filename></term>
              <listitem>
                <para>The default style.  The file contains
                definitions for various macros used in the LaTeX
                sources generated by Haddock; to change the way the
                formatted output looks, you might want to override
                these by specifying your own style with
                the <option>--latex-style</option> option.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term><filename><replaceable>module</replaceable>.tex</filename></term>
              <listitem>
                <para>The LaTeX documentation for
                each <replaceable>module</replaceable>.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>--latex-style</option></primary></indexterm>
          <option>--latex-style=<replaceable>style</replaceable></option>
        </term>
        <listitem>
          <para>This option lets you override the default style used
            by the LaTeX generated by the <option>--latex</option> option.
            Normally Haddock puts a
            standard <filename>haddock.sty</filename> in the output
            directory, and includes the
            command <literal>\usepackage{haddock}</literal> in the
            LaTeX source.  If this option is given,
            then <filename>haddock.sty</filename> is not generated,
            and the command is
            instead <literal>\usepackage{<replaceable>style</replaceable>}</literal>.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <indexterm><primary><option>-S</option></primary></indexterm>
          <option>-S</option>
        </term>
	<term>
	  <indexterm><primary><option>--docbook</option></primary></indexterm>
          <option>--docbook</option>
        </term>
	<listitem>
	  <para>Reserved for future use (output documentation in DocBook XML
	  format).</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <indexterm><primary><option>--source-base</option></primary></indexterm>
          <option>--source-base</option>=<replaceable>URL</replaceable>
        </term>
	<term>
	  <indexterm><primary><option>--source-module</option></primary></indexterm>
          <option>--source-module</option>=<replaceable>URL</replaceable>
        </term>
	<term>
	  <indexterm><primary><option>--source-entity</option></primary></indexterm>
          <option>--source-entity</option>=<replaceable>URL</replaceable>
        </term>
	<listitem>
	  <para>Include links to the source files in the generated
	  documentation. Use the <option>--source-base</option> option to add a
	  source code link in the header bar of the contents and index pages.
	  Use the <option>--source-module</option> to add a source code link in
	  the header bar of each module page. Use the
	  <option>--source-entity</option> option to add a source code link
	  next to the documentation for every value and type in each module.
	  </para>

	  <para>In each case <replaceable>URL</replaceable> is the base URL
	  where the source files can be found.  For the per-module and
	  per-entity URLs, the following substitutions are made within the
	  string <replaceable>URL</replaceable>:</para>

	  <itemizedlist>
	    <listitem>
	      <para>The string <literal>%M</literal> or <literal>%{MODULE}</literal>
	      is replaced by the module name. Note that for the per-entity URLs
	      this is the name of the <emphasis>exporting</emphasis> module.</para>
	    </listitem>
	    <listitem>
	      <para>The string <literal>%F</literal> or <literal>%{FILE}</literal>
	      is replaced by the original source file name. Note that for the
	      per-entity URLs this is the name of the <emphasis>defining</emphasis>
	      module.</para>
	    </listitem>
	    <listitem>
	      <para>The string <literal>%N</literal> or <literal>%{NAME}</literal>
	      is replaced by the name of the exported value or type. This is
	      only valid for the <option>--source-entity</option> option.</para>
	    </listitem>
	    <listitem>
	      <para>The string <literal>%K</literal> or <literal>%{KIND}</literal>
	      is replaced by a flag indicating whether the exported name is a value
	      '<literal>v</literal>' or a type '<literal>t</literal>'. This is
	      only valid for the <option>--source-entity</option> option.</para>
	    </listitem>
	    <listitem>
	      <para>The string <literal>%L</literal> or <literal>%{LINE}</literal>
	      is replaced by the number of the line where the exported value or
	      type is defined. This is only valid for the
	      <option>--source-entity</option> option.</para>
	    </listitem>
	    <listitem>
	      <para>The string <literal>%%</literal> is replaced by
	      <literal>%</literal>.</para>
      </listitem>

	  </itemizedlist>

	  <para>For example, if your sources are online under some directory,
	  you would say
	  <literal>haddock --source-base=<replaceable>url</replaceable>/
	  --source-module=<replaceable>url</replaceable>/%F</literal></para>

	  <para>If you have html versions of your sources online with anchors
	  for each type and function name, you would say
	  <literal>haddock --source-base=<replaceable>url</replaceable>/
	  --source-module=<replaceable>url</replaceable>/%M.html
	  --source-entity=<replaceable>url</replaceable>/%M.html#%N</literal></para>

	  <para>For the <literal>%{MODULE}</literal> substitution you may want to
	  replace the '<literal>.</literal>' character in the module names with
	  some other character (some web servers are known to get confused by
	  multiple '<literal>.</literal>' characters in a file name). To
	  replace it with a character <replaceable>c</replaceable> use
	  <literal>%{MODULE/./<replaceable>c</replaceable>}</literal>.</para>

	  <para>Similarly, for the <literal>%{FILE}</literal> substitution
          you may want to replace the '<literal>/</literal>' character in
          the file names with some other character (especially for links
          to colourised entity source code with a shared css file).  To replace
          it with a character <replaceable>c</replaceable> use
          <literal>%{FILE///<replaceable>c</replaceable>}</literal>/</para>

          <para>One example of a tool that can generate syntax-highlighted
          HTML from your source code, complete with anchors suitable for use
          from haddock, is
          <ulink url="http://www.cs.york.ac.uk/fp/darcs/hscolour">hscolour</ulink>.</para>

	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <indexterm><primary><option>-s</option></primary></indexterm>
          <option>-s</option> <replaceable>URL</replaceable>
        </term>
	<term>
	  <indexterm><primary><option>--source</option></primary></indexterm>
          <option>--source</option>=<replaceable>URL</replaceable>
        </term>
	<listitem>
	  <para>Deprecated aliases for <option>--source-module</option></para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <indexterm><primary><option>--comments-base</option></primary></indexterm>
          <option>--comments-base</option>=<replaceable>URL</replaceable>
        </term>
	<term>
	  <indexterm><primary><option>--comments-module</option></primary></indexterm>
          <option>--comments-module</option>=<replaceable>URL</replaceable>
        </term>
	<term>
	  <indexterm><primary><option>--comments-entity</option></primary></indexterm>
          <option>--comments-entity</option>=<replaceable>URL</replaceable>
        </term>
	<listitem>
	  <para>Include links to pages where readers may comment on the
	  documentation. This feature would typically be used in conjunction
	  with a Wiki system.</para>

	  <para>Use the <option>--comments-base</option> option to add a
	  user comments link in the header bar of the contents and index pages.
	  Use the <option>--comments-module</option> to add a user comments
	  link in the header bar of each module page. Use the
	  <option>--comments-entity</option> option to add a comments link
	  next to the documentation for every value and type in each module.
	  </para>

	  <para>In each case <replaceable>URL</replaceable> is the base URL
	  where the corresponding comments page can be found.  For the
	  per-module and per-entity URLs the same substitutions are made as
	  with the <option>--source-module</option> and
	  <option>--source-entity</option> options above.</para>

	  <para>For example, if you want to link the contents page to a wiki
	  page, and every module to subpages, you would say
	  <literal>haddock --comments-base=<replaceable>url</replaceable>
	  --comments-module=<replaceable>url</replaceable>/%M</literal></para>

	  <para>If your Wiki system doesn't like the '<literal>.</literal>' character
	  in Haskell module names, you can replace it with a different character. For
	  example to replace the '<literal>.</literal>' characters with
	  '<literal>_</literal>' use <literal>haddock
	  --comments-base=<replaceable>url</replaceable>
	  --comments-module=<replaceable>url</replaceable>/%{MODULE/./_}</literal>
	  Similarly, you can replace the '<literal>/</literal>' in a file name (may
	  be useful for entity comments, but probably not.) </para>

	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <indexterm><primary><option>--theme</option></primary></indexterm>
          <option>--theme</option>=<replaceable>path</replaceable>
        </term>
	<listitem>
	  <para>Specify a theme to be used for HTML (<option>--html</option>)
	  documentation. If given multiple times then the pages will use the
	  first theme given by default, and have alternate style sheets for
	  the others. The reader can switch between themes with browsers that
	  support alternate style sheets, or with the "Style" menu that gets
	  added when the page is loaded. If
	  no themes are specified, then just the default built-in theme
	  ("Ocean") is used.
	  </para>

	  <para>The <replaceable>path</replaceable> parameter can be one of:
	  </para>

	  <itemizedlist>
	    <listitem>
	      <para>A <emphasis>directory</emphasis>: The base name of
	      the directory becomes the name of the theme. The directory
	      must contain exactly one
	      <filename><replaceable>some</replaceable>.css</filename> file.
	      Other files, usually image files, will be copied, along with
	      the <filename><replaceable>some</replaceable>.css</filename>
	      file, into the generated output directory.</para>
	    </listitem>
	    <listitem>
	      <para>A <emphasis>CSS file</emphasis>: The base name of
	      the file becomes the name of the theme.</para>
	    </listitem>
	    <listitem>
	      <para>The <emphasis>name</emphasis> of a built-in theme
	      ("Ocean" or "Classic").</para>
	    </listitem>
	  </itemizedlist>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <indexterm><primary><option>--built-in-themes</option></primary></indexterm>
          <option>--built-in-themes</option>
        </term>
	<listitem>
	  <para>Includes the built-in themes ("Ocean" and "Classic").
	  Can be combined with <option>--theme</option>. Note that order
	  matters: The first specified theme will be the default.</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>Deprecated aliases for <option>--theme</option></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>-q</option></primary></indexterm>
          <option>-q</option> <replaceable>mode</replaceable>
        </term>
        <term>
          <indexterm><primary><option>--qual</option></primary></indexterm>
          <option>--qual</option>=<replaceable>mode</replaceable>
        </term>
        <listitem>
            <para>
                Specify how identifiers are qualified.
            </para>
            <para>
                <replaceable>mode</replaceable> should be one of
                <itemizedlist>
                    <listitem>
                        <para>none (default): don't qualify any identifiers</para>
                    </listitem>
                    <listitem>
                        <para>full: always qualify identifiers completely</para>
                    </listitem>
                    <listitem>
                        <para>local: only qualify identifiers that are not part
                            of the module</para>
                    </listitem>
                    <listitem>
                        <para>relative: like local, but strip name of the module
                            from qualifications of identifiers in submodules</para>
                    </listitem>
                </itemizedlist>
            </para>
            <para>
                Example: If you generate documentation for module A, then the
                identifiers A.x, A.B.y and C.z are qualified as follows.
            </para>
            <para>
                <itemizedlist>
                    <listitem>
                        <simpara>none: x, y, z</simpara>
                    </listitem>
                    <listitem>
                        <simpara>full: A.x, A.B.y, C.z</simpara>
                    </listitem>
                    <listitem>
                        <simpara>local: x, A.B.y, C.z</simpara>
                    </listitem>
                    <listitem>
                        <simpara>relative: x, B.y, C.z</simpara>
                    </listitem>
                </itemizedlist>
	        </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>--version</option></primary></indexterm>
          <option>--version</option>
        </term>
	<listitem>
	  <para>Output version information 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>--use-contents</option></primary></indexterm>
          <option>--use-contents=<replaceable>URL</replaceable></option>
        </term>
        <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 Contents and/or Index link on each page to
	  <replaceable>URL</replaceable>.  This option is intended for
	  use in conjunction with <option>--gen-contents</option> and/or
	  <option>--gen-index</option> for
	  generating a separate contents and/or index covering multiple
	  libraries.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>--gen-contents</option></primary></indexterm>
          <option>--gen-contents</option>
        </term>
        <term>
          <indexterm><primary><option>--gen-index</option></primary></indexterm>
          <option>--gen-index</option>
        </term>
	<listitem>
	  <para>Generate an HTML contents and/or 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 contents and/or index for multiple
	  sets of Haddock documentation.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <indexterm><primary><option>--ignore-all-exports</option></primary>
	  </indexterm>
	  <option>--ignore-all-exports</option>
	</term>
	<listitem>
	  <para>Causes Haddock to behave as if every module has the
	    <literal>ignore-exports</literal> attribute (<xref
	      linkend="module-attributes" />).  This might be useful for
	    generating implementation documentation rather than interface
	    documentation, for example.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <indexterm><primary><option>--hide</option></primary>
	  </indexterm>
	  <option>--hide</option>&nbsp;<replaceable>module</replaceable>
	</term>
	<listitem>
	  <para>Causes Haddock to behave as if module
	    <replaceable>module</replaceable> has the <literal>hide</literal>
	    attribute. (<xref linkend="module-attributes" />).</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <indexterm><primary><option>--show-extensions</option></primary>
	  </indexterm>
	  <option>--show-extensions</option>&nbsp;<replaceable>module</replaceable>
	</term>
	<listitem>
	  <para>Causes Haddock to behave as if module
	    <replaceable>module</replaceable> has the <literal>show-extensions</literal>
	    attribute. (<xref linkend="module-attributes" />).</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
          <indexterm><primary><option>--optghc</option></primary></indexterm>
          <option>--optghc</option>=<replaceable>option</replaceable>
        </term>
	<listitem>
	  <para>Pass <replaceable>option</replaceable> to GHC. Note that there is a double dash there, unlike for GHC.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>-w</option></primary></indexterm>
          <option>-w</option>
        </term>
        <term>
          <indexterm><primary><option>--no-warnings</option></primary></indexterm>
          <option>--no-warnings</option>
        </term>
	<listitem>
	  <para>Turn off all warnings.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>--compatible-interface-versions</option></primary></indexterm>
          <option>--compatible-interface-versions</option>
        </term>
	<listitem>
          <para>
            Prints out space-separated versions of binary Haddock interface files that this version is compatible
            with.
          </para>
	</listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <indexterm><primary><option>--no-tmp-comp-dir</option></primary></indexterm>
          <option>--no-tmp-comp-dir</option>
        </term>
	<listitem>
          <para>
          Do not use a temporary directory for reading and writing compilation output files
          (<literal>.o</literal>, <literal>.hi</literal>, and stub files). Instead, use the
          present directory or another directory that you have explicitly told GHC to use
          via the <literal>--optghc</literal> flag.
          </para>
          <para>
          This flag can be used to avoid recompilation if compilation files already exist.
          Compilation files are produced when Haddock has to process modules that make use of
          Template Haskell, in which case Haddock compiles the modules using the GHC API.
          </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <section id="cpp">
      <title>Using literate or pre-processed source</title>

      <para>Since Haddock uses GHC internally, both plain and
            literate Haskell sources are accepted without the need for the user
            to do anything. To use the C pre-processor, however,
            the user must pass the the <option>-cpp</option> option to GHC
            using <option>--optghc</option>.
      </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 itself may be documented with multiple fields
      that can then be displayed by the backend. In particular, the
      HTML backend displays all the fields it currently knows
      about. We first show the most complete module documentation
      example and then talk about the fields.</para>

<programlisting>
{-|
Module      : W
Description : Short description
Copyright   : (c) Some Guy, 2013
                  Someone Else, 2014
License     : GPL-3
Maintainer  : sample@email.com
Stability   : experimental
Portability : POSIX

Here is a longer description of this module, containing some
commentary with @some markup@.
-}
module W where
...
</programlisting>

      <para>The <quote>Module</quote> field should be clear. It
      currently doesn't affect the output of any of the backends but
      you might want to include it for human information or for any
      other tools that might be parsing these comments without the
      help of GHC.</para>

      <para>The <quote>Description</quote> field accepts some short text
      which outlines the general purpose of the module. If you're
      generating HTML, it will show up next to the module link in
      the module index.</para>

      <para>The <quote>Copyright</quote>, <quote>License</quote>,
      <quote>Maintainer</quote> and <quote>Stability</quote> fields
      should be obvious. An alternative spelling for the
      <quote>License</quote> field is accepted as
      <quote>Licence</quote> but the output will always prefer
      <quote>License</quote>.</para>

      <para>The <quote>Portability</quote> field has seen varied use
      by different library authors. Some people put down things like
      operating system constraints there while others put down which
      GHC extensions used. Note that you might want to consider using
      the <quote>show-extensions</quote> module flag for the
      latter.</para>

      <para>Finally, 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.
      All usual Haddock markup is valid in this comment.</para>

      <para>All fields are optional but they must be in order if they
      do appear. Multi-line fields are accepted but the consecutive
      lines have to start indented more than their label. If your
      label is indented one space as is often the case with
      <quote>--</quote> syntax, the consecutive lines have to start at
      two spaces at the very least. Please note that we do not enforce
      the format for any of the fields and the established formats are
      just a convention.</para>

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

<programlisting>
module Foo where

-- * This heading will now appear before foo.

-- | Documentation for 'foo'.
foo :: Integer
foo = 5
</programlisting>

      </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 id="hyperlinking">
      <title>Hyperlinking and re-exported entities</title>

      <para>When Haddock renders a type in the generated
      documentation, it hyperlinks all the type constructors and class
      names in that type to their respective definitions.  But for a
      given type constructor or class there may be several modules
      re-exporting it, and therefore several modules whose
      documentation contains the definition of that type or class
      (possibly including the current module!) so which one do we link
      to?</para>

      <para>Let's look at an example.  Suppose we have three modules
      <literal>A</literal>, <literal>B</literal> and
      <literal>C</literal> defined as follows:</para>

<programlisting>
module A (T) where
data T a = C a

module B (f) where
import A
f :: T Int -> Int
f (C i) = i

module C (T, f) where
import A
import B
</programlisting>

      <para>Module <literal>A</literal> exports a datatype
      <literal>T</literal>.  Module <literal>B</literal> imports
      <literal>A</literal> and exports a function <literal>f</literal>
      whose type refers to <literal>T</literal>.  Also, both
	<literal>T</literal> and <literal>f</literal> are re-exported from
	module C.</para>

      <para>Haddock takes the view that each entity has a
	<emphasis>home</emphasis> module; that is, the module that the library
	designer would most like to direct the user to, to find the
	documentation for that entity.  So, Haddock makes all links to an entity
	point to the home module.  The one exception is when the entity is also
      exported by the current module: Haddock makes a local link if it
	can.</para>

      <para>How is the home module for an entity determined?
	Haddock uses the following rules:</para>

      <itemizedlist>
	<listitem>
	  <para>If modules A and B both export the entity, and module A imports
	    (directly or indirectly) module B, then B is preferred.</para>
	</listitem>
	<listitem>
	  <para>A module with the <literal>hide</literal> attribute is never
	    chosen as the home.</para>
	</listitem>
	<listitem>
	  <para>A module with the <literal>not-home</literal> attribute is only
	    chosen if there are no other modules to choose.</para>
	</listitem>
      </itemizedlist>

      <para>If multiple modules fit the criteria, then one is chosen at
	random.  If no modules fit the criteria (because the candidates are all
      hidden), then Haddock will issue a warning for each reference to an
	entity without a home.</para>

      <para>In the example above, module <literal>A</literal> is chosen as the
	home for <literal>T</literal> because it does not import any other
	module that exports <literal>T</literal>.  The link from
	<literal>f</literal>'s
	type in module <literal>B</literal> will therefore point to
	<literal>A.T</literal>.  However, <literal>C</literal> also exports
	<literal>T</literal> and <literal>f</literal>, and the link from
	<literal>f</literal>'s type in <literal>C</literal> will therefore
	point locally to <literal>C.T</literal>.</para>
    </section>

    <section id="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 an
      <literal>{-# OPTIONS_HADDOCK ... #-}</literal> pragma at the
      top of the module, either before or after the module
      description.  For example:</para>

<programlisting>
{-# OPTIONS_HADDOCK hide, prune, ignore-exports #-}

-- |Module description
module A where
...
</programlisting>

      <para>The options and module description can be in either order.</para>

      <para>The following attributes are currently understood by
      Haddock:</para>

      <variablelist>
	<varlistentry>
          <term>
            <indexterm><primary><literal>hide</literal></primary></indexterm>
            <literal>hide</literal>
          </term>
	  <listitem>
	    <para>Omit this module from the generated documentation,
	    but nevertheless propagate definitions and documentation
	    from within this module to modules that re-export those
	    definitions.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
          <term>
            <indexterm><primary><literal>hide</literal></primary></indexterm>
            <literal>prune</literal>
          </term>
	  <listitem>
	    <para>Omit definitions that have no documentation
	    annotations from the generated documentation.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
          <term>
            <indexterm><primary><literal>ignore-exports</literal></primary></indexterm>
            <literal>ignore-exports</literal>
          </term>
	  <listitem>
	    <para>Ignore the export list.  Generate documentation as
	    if the module had no export list - i.e. all the top-level
	    declarations are exported, and section headings may be
	    given in the body of the module.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
	    <indexterm><primary><literal>not-home</literal></primary></indexterm>
      <literal>not-home</literal>
	  </term>
	  <listitem>
	    <para>Indicates that the current module should not be considered to
	      be the home module for each entity it exports,
	      unless that entity is not exported from any other module.  See
	      <xref linkend="hyperlinking" /> for more details.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
	    <indexterm><primary><literal>show-extensions</literal></primary></indexterm>
      <literal>show-extensions</literal>
	  </term>
	  <listitem>
	    <para>Indicates that we should render the extensions used in this module in the
            resulting documentation. This will only render if the output format supports it.
            If Language is set, it will be shown as well and all the extensions implied by it won't.
            All enabled extensions will be rendered, including those implied by their more powerful versions.</para>
	  </listitem>
	</varlistentry>

      </variablelist>

    </section>

    <section>
      <title>Markup</title>

      <para>Haddock understands certain textual cues inside
      documentation annotations that tell it how to render the
      documentation.  The cues (or <quote>markup</quote>) have been
      designed to be simple and mnemonic in ASCII so that the
      programmer doesn't have to deal with heavyweight annotations
      when editing documentation comments.</para>

      <section>
	<title>Paragraphs</title>

	<para>One or more blank lines separates two paragraphs in a
	documentation comment.</para>
      </section>

      <section>
	<title>Special characters</title>

	<para>The following characters have special meanings in
	documentation comments: <literal>\</literal>, <literal>/</literal>,
	<literal>'</literal>, <literal>`</literal>,
	<literal>"</literal>, <literal>@</literal>,
	<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>

        <para>Furthermore, the character sequence <literal>&gt;&gt;&gt;</literal>
        has a special meaning at the beginning of a line. To
        escape it, just prefix the characters in the sequence with a
        backslash.</para>
      </section>

      <section>
	<title>Character references</title>

	<para>Although Haskell source files may contain any character
	from the Unicode character set, the encoding of these characters
	as bytes varies between systems, so that only source files
	restricted to the ASCII character set are portable.  Other
	characters may be specified in character and string literals
	using Haskell character escapes.  To represent such characters
	in documentation comments, Haddock supports SGML-style numeric
	character references of the forms
	<literal>&amp;#</literal><replaceable>D</replaceable><literal>;</literal>
	and
	<literal>&amp;#x</literal><replaceable>H</replaceable><literal>;</literal>
	where <replaceable>D</replaceable> and <replaceable>H</replaceable>
	are decimal and hexadecimal numbers denoting a code position
	in Unicode (or ISO 10646).  For example, the references
	<literal>&amp;#x3BB;</literal>, <literal>&amp;#x3bb;</literal>
	and <literal>&amp;#955;</literal> all represent the lower-case
	letter lambda.</para>
      </section>

      <section>
	<title>Code Blocks</title>

	<para>Displayed blocks of code are indicated by surrounding a
	paragraph with <literal>@...@</literal> or by preceding each
	line of a paragraph with <literal>&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>Examples</title>

	<para> Haddock has markup support for examples of interaction with a
  <emphasis>read-eval-print loop (REPL)</emphasis>.  An
	example is introduced with
	<literal>&gt;&gt;&gt;</literal> followed by an expression followed
	by zero or more result lines:</para>

<programlisting>
-- | Two examples are given below:
--
-- &gt;&gt;&gt; fib 10
-- 55
--
-- &gt;&gt;&gt; putStrLn "foo\nbar"
-- foo
-- bar
</programlisting>
	<para>Result lines that only contain the string
	<literal>&lt;BLANKLINE&gt;</literal> are rendered as blank lines in the
	generated documentation.</para>
      </section>

      <section>
	<title>Properties</title>
        <para>
          Haddock provides markup for properties:
<programlisting>
-- | Addition is commutative:
--
-- prop> a + b = b + a
</programlisting>
          This allows third-party applications to extract and verify them.
        </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, Bold and Monospaced text</title>

	<para>Emphasis may be added by surrounding text with
	<literal>/.../</literal>. Other markup is valid inside emphasis. To have a forward
        slash inside of emphasis, just escape it: <literal>/fo\/o/</literal></para>

        <para>Bold (strong) text is indicated by surrounding it with <literal>__...__</literal>.
        Other markup is valid inside bold. For example, <literal>__/foo/__</literal> will make the emphasised
        text <literal>foo</literal> bold. You don't have to escape a single underscore if you need it bold:
        <literal>__This_text_with_underscores_is_bold__</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>

        <para>A basic check is done on the syntax of the header name to ensure that it is valid
        before turning it into a link but unlike with identifiers, whether the module is in scope isn't checked
        and will always be turned into a link.
        </para>

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

      <para>Lists of the same type don't have to be separated by a newline:</para>
<programlisting>
-- | This is an enumerated list:
--
--     (1) first item
--     2. second item
--
-- This is a bulleted list:
--
--     * first item
--     * second item
</programlisting>

      <para>You can have more than one line of content in a list element:
      </para>
<programlisting>
-- |
-- * first item
-- and more content for the first item
-- * second item
-- and more content for the second item
</programlisting>

     <para>You can even nest whole paragraphs inside of list elements. The rules
     are 4 spaces for each indentation level. You're required to use a newline before
     such nested paragraph:
     </para>
<programlisting>
{-|
* Beginning of list
This belongs to the list above!

    > nested
    > bird
    > tracks

    * Next list
    More of the indented list.

        * Deeper

            @
            even code blocks work
            @

            * Deeper

                    1. Even deeper!
                    2. No newline separation even in indented lists.
-}
</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. You can escape <literal>]</literal> with a backslash as usual.</para>

      <para>Same rules about nesting and no newline separation as for bulleted and numbered lists apply.
      </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>

        <para>The URL can be followed by an optional label:</para>
<programlisting>
&lt;http://example.com label&gt;
</programlisting>
      <para>The label is then used as a descriptive text for the hyperlink, if the
        output format supports it.</para>

      <para>If Haddock sees something that looks like a URL (such as something starting with
      <literal>http://</literal> or <literal>ssh://</literal>) where the URL markup is valid,
      it will automatically make it a hyperlink.</para>
      </section>

      <section>
	<title>Images</title>

	<para>An image can be included in a documentation comment by
	surrounding it in double angle brackets:
	<literal>&lt;&lt;...&gt;&gt;</literal>.  If the output format supports
	it, the image will be rendered inside the documentation.</para>

        <para>Title text can be included using an optional label:</para>
<programlisting>
&lt;&lt;pathtoimage.png title&gt;&gt;
</programlisting>

      </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>
	<title>Headings</title>
        <para>Headings inside of comment documentation are possible be preceding them with
        a number of <literal>=</literal>s. From 1 to 6 are accepted. Extra <literal>=</literal>s will
        be treated as belonging to the text of the heading. Note that it's up to the output format to decide
        how to render the different levels.
        </para>

<programlisting>
-- |
-- = Heading level 1 with some __bold__
-- Something underneath the heading.
--
-- == /Subheading/
-- More content.
--
-- === Subsubheading
-- Even more content.
</programlisting>

        <para>Note that while headings have to start on a new paragraph, we allow paragraph-level content to
        follow these immediately.
        </para>

<programlisting>
-- |
-- = Heading level 1 with some __bold__
-- Something underneath the heading.
--
-- == /Subheading/
-- More content.
--
-- === Subsubheading
-- >>> examples are only allowed at the start of paragraphs
</programlisting>

      </section>

    </section>
  </chapter>
  <index/>
</book>