aboutsummaryrefslogtreecommitdiff
path: root/doc/haddock.xml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/haddock.xml')
-rw-r--r--doc/haddock.xml290
1 files changed, 115 insertions, 175 deletions
diff --git a/doc/haddock.xml b/doc/haddock.xml
index 9b87e3d5..a7688e4e 100644
--- a/doc/haddock.xml
+++ b/doc/haddock.xml
@@ -252,27 +252,30 @@
<varlistentry>
<term>
- <indexterm><primary><option>--optghc</option></primary></indexterm>
- <option>--optghc</option>=<replaceable>option</replaceable>
+ <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>Pass <replaceable>option</replaceable> to GHC.</para>
+ <para>Generate files into <replaceable>dir</replaceable>
+ instead of the current directory.</para>
</listitem>
</varlistentry>
-
<varlistentry>
<term>
- <indexterm><primary><option>-o</option></primary></indexterm>
- <option>-o</option> <replaceable>dir</replaceable>
+ <indexterm><primary><option>-l</option></primary></indexterm>
+ <option>-l</option> <replaceable>dir</replaceable>
</term>
<term>
- <indexterm><primary><option>--odir</option></primary></indexterm>
- <option>--odir</option>=<replaceable>dir</replaceable>
+ <indexterm><primary><option>--lib</option></primary></indexterm>
+ <option>--lib</option>=<replaceable>dir</replaceable>
</term>
<listitem>
- <para>Generate files into <replaceable>dir</replaceable>
- instead of the current directory.</para>
+ <para>Use Haddock auxiliary files (themes, javascript, etc...) in <replaceable>dir</replaceable>.</para>
</listitem>
</varlistentry>
@@ -334,35 +337,6 @@
<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 auxiliary files in <replaceable>dir</replaceable>.</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>-h</option></primary></indexterm>
<option>-h</option>
</term>
@@ -422,61 +396,81 @@
</varlistentry>
<varlistentry>
- <term>
- <indexterm><primary><option>-m</option></primary></indexterm>
- <option>-m</option>
- </term>
- <term>
- <indexterm><primary><option>--html-help</option></primary></indexterm>
- <option>--html-help</option>
+ <term>
+ <indexterm><primary><option>--latex</option></primary></indexterm>
+ <option>--latex</option>
</term>
- <listitem>
- <para>(In HTML mode only) Produce extra contents and index
- files for given HTML Help system. Currently supported Help
- systems are Microsoft HTML Help 1.3 and 2.0 and GNOME DevHelp.</para>
-
- <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 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>
- (search for <quote>HTML Help compiler</quote>).</para>
-
- <para>Viewers</para>
+ <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>Microsoft HTML Help Viewer</term>
- <listitem><para>Distributed with Microsoft Windows</para></listitem>
- </varlistentry>
- <varlistentry>
- <term><ulink url="http://xchm.sourceforge.net">xCHM</ulink></term>
- <listitem><para>a CHM viewer for UNIX (Linux, *BSD, Solaris), written by Razvan Cojocaru</para></listitem>
+ <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><ulink url="http://www.jouledata.com/MacProducts.html">JouleData Solutions' CHM Viewer</ulink></term>
- <listitem><para>a comercial 100% native Cocoa .chm file viewer for the Mac OS X platform</para></listitem>
+ <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><ulink url="http://gnochm.sourceforge.net">GnoCHM</ulink></term>
- <listitem><para>a CHM file viewer. It is designed to integrate nicely with Gnome.</para></listitem>
+ <term><filename><replaceable>module</replaceable>.tex</filename></term>
+ <listitem>
+ <para>The LaTeX documentation for
+ each <replaceable>module</replaceable>.</para>
+ </listitem>
</varlistentry>
- </variablelist>
+ </variablelist>
+ </listitem>
+ </varlistentry>
- <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>
+ <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>
@@ -657,70 +651,6 @@
</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>-p</option></primary></indexterm>
<option>-p</option> <replaceable>file</replaceable>
@@ -787,33 +717,33 @@ $ pdflatex <replaceable>package</replaceable>.tex</screen>
<varlistentry>
<term>
- <indexterm><primary><option>-v</option></primary></indexterm>
- <option>-v</option>
+ <indexterm><primary><option>-V</option></primary></indexterm>
+ <option>-V</option>
</term>
<term>
- <indexterm><primary><option>--verbose</option></primary></indexterm>
- <option>--verbose</option>
+ <indexterm><primary><option>--version</option></primary></indexterm>
+ <option>--version</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>
+ <para>Output version information and exit.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <indexterm><primary><option>-V</option></primary></indexterm>
- <option>-V</option>
+ <indexterm><primary><option>-v</option></primary></indexterm>
+ <option>-v</option>
</term>
<term>
- <indexterm><primary><option>--version</option></primary></indexterm>
- <option>--version</option>
+ <indexterm><primary><option>--verbose</option></primary></indexterm>
+ <option>--verbose</option>
</term>
<listitem>
- <para>Output version information and exit.</para>
+ <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>
@@ -875,19 +805,12 @@ $ pdflatex <replaceable>package</replaceable>.tex</screen>
</varlistentry>
<varlistentry>
- <term>
- <indexterm><primary><option>--no-tmp-comp-dir</option></primary></indexterm>
- <option>--no-tmp-comp-dir</option>
+ <term>
+ <indexterm><primary><option>--optghc</option></primary></indexterm>
+ <option>--optghc</option>=<replaceable>option</replaceable>
</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>
+ <para>Pass <replaceable>option</replaceable> to GHC.</para>
</listitem>
</varlistentry>
@@ -904,6 +827,23 @@ $ pdflatex <replaceable>package</replaceable>.tex</screen>
<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">