<commit_before><?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><EMAIL></email></address>
    <author>
      <firstname>David</firstname>
      <surname>Waern</surname>
    </author>
    <address><email><EMAIL></email></address>
    <copyright>
      <year>2010</year>
      <holder><NAME>, <NAME></holder>
    </copyright>
    <abstract>
      <para>This document describes Haddock version 2.8.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 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, LaTeX,
  and Hoogle 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 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, <NAME>.  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: <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>,
      <NAME>, <NAME>, <NAME>, the members
      of <email><EMAIL></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
    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>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 collapsable 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>-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>--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 conjuction 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 behaves as if every module has the
	    <literal>ignore-exports</literal> attribute (<xref
	      linkend="module-attributes" />).  This might be useful for
	    generating implementation documentation rather than interface
	    documetnation, for example.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <indexterm><primary><option>--hide</option></primary>
	  </indexterm>
	  <option>--hide</option>&nbsp;<replaceable>module</replaceable>
	</term>
	<listitem>
	  <para>Causes Haddock to behaves as if module
	    <replaceable>module</replaceable> has the <literal>hide</literal>
	    atribute. (<xref linkend="module-attributes" />).</para>
	</listitem>
      </varlistentry>
      
      <varlistentry>
	<term>
          <indexterm><primary><option>--optghc</option></primary></indexterm>
          <option>--optghc</option>=<replaceable>option</replaceable>
        </term>
	<listitem>
	  <para>Pass <replaceable>option</replaceable> to 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>--no-tmp-comp-dir</option></primary></indexterm>
          <option>--no-tmp-comp-dir</option>
        </term>
	<listitem>
          <para>If the input modules use Template Haskell, Haddock has to
          perform compilation (using GHC).  This results in .o, .hi, and stub files that
          are written to a temporary directory by default. When this flag is specified,
          however, the files are written to the present directory (or another path if you
          tell GHC, for example like this: <literal>--optghc=-odir --optghc=path</literal>).
          Note that not only will files be written to this directory, GHC will also look for
          already existing files there, and use them in order to skip compilation.
          </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<commit_msg>Improve docs for --no-tmp-comp-dir<commit_after><?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><EMAIL></email></address>
    <author>
      <firstname>David</firstname>
      <surname>Waern</surname>
    </author>
    <address><email><EMAIL></email></address>
    <copyright>
      <year>2010</year>
      <holder><NAME>, <NAME></holder>
    </copyright>
    <abstract>
      <para>This document describes Haddock version 2.8.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 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, LaTeX,
  and Hoogle 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 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, <NAME>.  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: <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME>,
      <NAME>, <NAME>, <NAME>, the members
      of <email><EMAIL></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
    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>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 collapsable 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>-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>--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 conjuction 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 behaves as if every module has the
	    <literal>ignore-exports</literal> attribute (<xref
	      linkend="module-attributes" />).  This might be useful for
	    generating implementation documentation rather than interface
	    documetnation, for example.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <indexterm><primary><option>--hide</option></primary>
	  </indexterm>
	  <option>--hide</option>&nbsp;<replaceable>module</replaceable>
	</term>
	<listitem>
	  <para>Causes Haddock to behaves as if module
	    <replaceable>module</replaceable> has the <literal>hide</literal>
	    atribute. (<xref linkend="module-attributes" />).</para>
	</listitem>
      </varlistentry>
      
      <varlistentry>
	<term>
          <indexterm><primary><option>--optghc</option></primary></indexterm>
          <option>--optghc</option>=<replaceable>option</replaceable>
        </term>
	<listitem>
	  <para>Pass <replaceable>option</replaceable> to 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>--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
{'fraction_non_alphanumeric': 0.12373590446901062, 'fraction_numerical': 0.000886598509406256, 'mean_word_length': 3.0159666203059805, 'pattern_counts': {'":': 0, '<': 2729, '<?xml version=': 2, '>': 2729, 'https://': 0, 'lorem ipsum': 0, 'www.': 18, 'xml': 4}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7171236', 'n_tokens_mistral': 21429, 'n_tokens_neox': 20168, 'n_words': 6157}