aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/haddock.sgml117
1 files changed, 72 insertions, 45 deletions
diff --git a/doc/haddock.sgml b/doc/haddock.sgml
index 06386dfb..3d355d9b 100644
--- a/doc/haddock.sgml
+++ b/doc/haddock.sgml
@@ -21,7 +21,7 @@
<!-- Table of contents -->
<toc></toc>
-
+
<chapter id="introduction">
<title>Introduction</title>
@@ -99,7 +99,7 @@
<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>
@@ -162,7 +162,7 @@
<section>
<title>Acknowledgements</title>
-
+
<para>Several documentation systems provided the inspiration for
Haddock, most notably:</para>
@@ -223,7 +223,7 @@
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>
+ recursive, as Haddock don't like swimming in circles.</para>
<para>The following options are available:</para>
@@ -368,29 +368,56 @@
<varlistentry>
<term><option>-m</option></term>
- <term><option>--ms-help</option></term>
- <indexterm><primary><option>-m</option></primary></indexterm>
- <indexterm><primary><option>--ms-help</option></primary>
+ <term><option>--html-help</option></term>
+ <indexterm><primary><option>--html-help</option></primary>
</indexterm>
<listitem>
<para>(In HTML mode only) Produce extra contents and index
- files for the Microsoft HTML Help system. The files created
- will be named <filename>index.hhc</filename> and
- <filename>index.hhk</filename> respectively.</para>
+ files for given HTML Help system. Currently supported Help
+ systems are Microsoft HTML Help 1.3 and 2.0 and GNOME DevHelp.
<para>Using the Microsoft HTML Help system provides two
advantages over plain HTML: the help viewer gives you a nice
hierarchical folding contents pane on the left, and the
documentation files are compressed and therefore much
- smaller (roughly a factor of 10). The disadvantages are
- that the viewer is only available on Windows, and the help
- can't be viewed over the web.</para>
+ smaller (roughly a factor of 10). The disadvantage is that
+ the help can't be viewed over the web.</para>
<para>In order to create a compiled Microsoft help file, you
also need the Microsoft HTML Help compiler, which is
- available free from <ulink
- url="http://www.microsoft.com/">http://www.microsoft.com/</ulink>
+ available free from
+ <ulink url="http://www.microsoft.com/">http://www.microsoft.com/</ulink>
(search for <quote>HTML Help compiler</quote>).</para>
+
+ Viewers
+ <variablelist>
+ <varlistentry>
+ <term>Microsoft HTML Help Viewer</term>
+ <listitem>Distributed with Microsoft Windows</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><ulink url="http://xchm.sourceforge.net">xCHM</ulink></term>
+ <listitem>a CHM viewer for UNIX (Linux, *BSD, Solaris), written by Razvan Cojocaru</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><ulink url="http://www.jouledata.com/MacProducts.html">JouleData Solutions' CHM Viewer</ulink></term>
+ <listitem>a comercial 100% native Cocoa .chm file viewer for the Mac OS X platform</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><ulink url="http://gnochm.sourceforge.net">GnoCHM</ulink></term>
+ <listitem>a CHM file viewer. It is designed to integrate nicely with Gnome.</listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>The GNOME DevHelp also provides help viewer which looks like
+ MSHelp viewer but the documentation files aren't compressed.
+ The documentation can be viewed with any HTML browser but
+ DevHelp gives you a nice hierarchical folding contents and
+ keyword index panes on the left. The DevHelp expects to see
+ *.devhelp file in the folder where the documentation is placed.
+ The file contains all required information
+ to build the contents and index panes.
+ </para>
</listitem>
</varlistentry>
@@ -574,7 +601,7 @@ $ haddock -h Foo.hs ...
</section>
</chapter>
-
+
<chapter id="markup">
<title>Documentation and Markup</title>
@@ -640,7 +667,7 @@ square x = x * x
<para>Some people like to write their documentation
<emphasis>after</emphasis> the declaration; this is possible in
Haddock too:</para>
-
+
<programlisting>
square :: Int -> Int
-- ^The 'square' function squares an integer.
@@ -651,7 +678,7 @@ square x = x * x
&mdash; if you don't write the type signature for a function,
then Haddock can't tell what its type is and it won't be
included in the documentation.</para>
-
+
<para>Documentation annotations may span several lines; the
annotation continues until the first non-comment line in the
source file. For example:</para>
@@ -675,24 +702,24 @@ square x = x * x
square :: Int -> Int
square x = x * x
</programlisting>
-
+
</section>
<section>
<title>Documenting parts of a declaration</title>
-
+
<para>In addition to documenting the whole declaration, in some
cases we can also document individual parts of the
declaration.</para>
<section>
<title>Class methods</title>
-
+
<para>Class methods are documented in the same way as top
level type signatures, by using either the
<quote><literal>--&nbsp;|</literal></quote> or
<quote><literal>--&nbsp;^</literal></quote>
annotations:</para>
-
+
<programlisting>
class C a where
-- | This is the documentation for the 'f' method
@@ -710,9 +737,9 @@ class C a where
<programlisting>
data T a b
-- | This is the documentation for the 'C1' constructor
- = C1 a b
+ = C1 a b
-- | This is the documentation for the 'C2' constructor
- | C2 a b
+ | C2 a b
</programlisting>
<para>or like this:</para>
@@ -727,14 +754,14 @@ data T a b
styles:</para>
<programlisting>
-data R a b =
+data R a b =
C { -- | This is the documentation for the 'a' field
a :: a,
-- | This is the documentation for the 'b' field
b :: b
}
-data R a b =
+data R a b =
C { a :: a -- ^ This is the documentation for the 'a' field
, b :: b -- ^ This is the documentation for the 'b' field
}
@@ -748,7 +775,7 @@ data R a b =
<section>
<title>Function arguments</title>
-
+
<para>Individual arguments to a function may be documented
like this:</para>
@@ -775,10 +802,10 @@ module Foo where
...
</programlisting>
</section>
-
+
<section>
<title>Controlling the documentation structure</title>
-
+
<para>Haddock produces interface documentation that lists only
the entities actually exported by the module. The documentation
for a module will include <emphasis>all</emphasis> entities
@@ -849,7 +876,7 @@ module Foo (
<section>
<title>Re-exporting an entire module</title>
-
+
<para>Haskell allows you to re-export the entire contents of a
module (or at least, everything currently in scope that was
imported from a given module) by listing it in the export
@@ -859,7 +886,7 @@ module Foo (
module A (
module B,
module C
- ) where
+ ) where
</programlisting>
<para>What will the Haddock-generated documentation for this
@@ -876,7 +903,7 @@ module A (
module A (
module B,
module C
- ) where
+ ) where
import B hiding (f)
import C (a, b)
@@ -896,10 +923,10 @@ import C (a, b)
is never cross-referenced; the contents are always expanded in
place in the re-exporting module.</para>
</section>
-
+
<section>
<title>Omitting the export list</title>
-
+
<para>If there is no export list in the module, how does
Haddock generate documentation? Well, when the export list is
omitted, e.g.:</para>
@@ -937,7 +964,7 @@ module Foo (
) where
</programlisting>
</listitem>
-
+
<listitem>
<para>If the documentation is large and placing it inline in
the export list might bloat the export list and obscure the
@@ -954,7 +981,7 @@ module Foo (
...
) where
--- $doc
+-- $doc
-- Here is a large chunk of documentation which may be referred to by
-- the name $doc.
</programlisting>
@@ -968,8 +995,8 @@ module Foo (
</section>
<section>
- <title>Hyperlinking and re-exported entities</title>
-
+ <title>Hyperlinking and re-exported entities</title>
+
<para>When Haddock renders a type in the generated
documentation, it hyperlinks all the type constructors and class
names in that type to their respective definitions. But for a
@@ -1038,7 +1065,7 @@ import B
<section id="module-attributes">
<title>Module Attributes</title>
-
+
<para>Certain attributes may be specified for each module which
affects the way that Haddock generates documentation for that
module. Attributes are specified in a comma-separated list in a
@@ -1068,7 +1095,7 @@ module A where
definitions.</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term><literal>prune</literal></term>
<indexterm><primary><literal>hide</literal></primary></indexterm>
@@ -1077,7 +1104,7 @@ module A where
annotations from the generated documentation.</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term><literal>ignore-exports</literal></term>
<indexterm><primary><literal>hide</literal></primary></indexterm>
@@ -1103,7 +1130,7 @@ module A where
<section>
<title>Paragraphs</title>
-
+
<para>One or more blank lines separates two paragraphs in a
documentation comment.</para>
</section>
@@ -1263,7 +1290,7 @@ module A where
<section>
<title>Definition lists</title>
-
+
<para>Definition lists are written as follows:</para>
<programlisting>
@@ -1275,7 +1302,7 @@ module A where
</programlisting>
<para>To produce output something like this:</para>
-
+
<variablelist>
<varlistentry>
<term><literal>foo</literal></term>
@@ -1322,7 +1349,7 @@ module A where
<literal>#<replaceable>label</replaceable>#</literal>, where
<replaceable>label</replaceable> is the name of the anchor.
An anchor is invisible in the generated documentation.</para>
-
+
<para>To link to an anchor from elsewhere, use the syntax
<literal>"<replaceable>module</replaceable>#<replaceable>label</replaceable>"</literal>
where <replaceable>module</replaceable> is the module name