aboutsummaryrefslogtreecommitdiff
path: root/doc/haddock.sgml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/haddock.sgml')
-rw-r--r--doc/haddock.sgml150
1 files changed, 148 insertions, 2 deletions
diff --git a/doc/haddock.sgml b/doc/haddock.sgml
index 717c0f17..a305a2be 100644
--- a/doc/haddock.sgml
+++ b/doc/haddock.sgml
@@ -14,13 +14,159 @@
<holder>Simon Marlow</holder>
</copyright>
<abstract>
- <para>This document describes Haddock, a Haskell documentation tool.
+ <para>This document describes Haddock, a Haskell documentation
+ tool.</para>
+ </abstract>
</bookinfo>
<!-- Table of contents -->
<toc></toc>
- <chapter id="happy-introduction">
+ <chapter id="introduction">
+ <title>Introduction</title>
+
+ <para>This is Haddock, a tool for automatically generating
+ documentation from annotated Haskell source code. Haddock was
+ designed with several goals in mind:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>When documenting APIs, it is desirable to keep the
+ documentation close to the actual interface or implementation
+ of the API, preferably in the same file, to reduce the risk
+ that the two become out of sync. Haddock therefore lets you
+ write the documentation for an entity (function, type, or
+ class) next to the definition of the entity in the source
+ code.</para>
+ </listitem>
+ <listitem>
+ <para>There is s tremendous amount of useful API documentation
+ that can be extracted from just the bare source code,
+ including types of exported functions, definitions of data
+ types and classes, and so on. Haddock can therefore generate
+ documentation from a set of straight Haskell 98 modules, and
+ the documentation will contain precisely the interface that is
+ available to a programmer using those modules.</para>
+ </listitem>
+ <listitem>
+ <para>Documentation annotations in the source code should be
+ easy on the eye when editing the source code itself, so as not
+ to obsure the code and to make reading and writing
+ documentation annotations easy. 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 the internal module
+ structure of the interface. A documentation annotation can
+ still be placed next to the implementation, and it will be
+ propagated to the external module in the generated
+ documentation.</para>
+ </listitem>
+ <listitem>
+ <para>Being able to move around the documentation by following
+ hyperlinks is essential. Documentation generated by Haddock
+ is therefore littered with hyperlinks: every type and class
+ name is a link to the corresponding definition, and
+ user-written documentation annotations can contain identifiers
+ which are linked automatically when the documentation is
+ generated.</para>
+ </listitem>
+ <listitem>
+ <para>We might want documentation in multiple formats - online
+ and printed, for example. Haddock comes with HTML and DocBook
+ backends, and it is structured in such a way that adding new
+ back-ends is straightforward.</para>
+ </listitem>
+ </itemizedlist>
+
+ <section id="obtaining">
+ <title>Obtaining Haddock</title>
+
+ <para>Distributions (source & binary) of Haddock can be obtained
+ from its <ulink url="http://www.haskell.org/haddock/">web
+ site</ulink>.</para>
+
+ <para>Up-to-date sources can also be obtained from CVS. The
+ Haddock sources are under <literal>fptools/haddock</literal> in
+ the <literal>fptools</literal> CVS repository, which also
+ contains GHC, Happy, and several other projects. See <ulink
+ url="http://www.haskell.org/ghc/docs/latest/building/sec-cvs.html">Using
+ The CVS Repository</ulink> for information on how to access the
+ CVS repository. Note that you need to check out the
+ <literal>fpconfig</literal> module first to get the generic
+ build system (the <literal>fptools</literal> directory), and
+ then check out <literal>fptools/haddock</literal> to get the
+ Haddock sources.</para>
+ </section>
+
+ <section id="license">
+ <title>License</title>
+
+ <para>The following license covers this documentation, and the
+ Haddock source code, except where otherwise indicated.</para>
+
+ <blockquote>
+ <para>Copyright 2002, Simon Marlow. All rights reserved.</para>
+
+ <para>Redistribution and use in source and binary forms, with
+ or without modification, are permitted provided that the
+ following conditions are met:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Redistributions of source code must retain the above
+ copyright notice, this list of conditions and the
+ following disclaimer.</para>
+ </listitem>
+ <listitem>
+ <para>Redistributions in binary form must reproduce the
+ above copyright notice, this list of conditions and the
+ following disclaimer in the documentation and/or other
+ materials provided with the distribution.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS "AS
+ IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
+ SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY DIRECT,
+ INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
+ OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
+ THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
+ OF SUCH DAMAGE.</para>
+ </blockquote>
+ </section>
+ </chapter>
+
+ <chapter id="invoking">
+ <title>Invoking Haddock</title>
+ <para></para>
+ </chapter>
+
+ <chapter id="markup">
+ <title>Documentation and Markup</title>
+ <para></para>
</chapter>
</book>