diff options
| -rw-r--r-- | doc/haddock.sgml | 150 |
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> |