[haddock @ 2002-04-10 14:30:58 by simonmar]

Add an introduction

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>