diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.md (renamed from doc/README) | 13 | ||||
| -rw-r--r-- | doc/haddock.xml | 97 |
2 files changed, 94 insertions, 16 deletions
diff --git a/doc/README b/doc/README.md index 5bc038bf..cf1fc31b 100644 --- a/doc/README +++ b/doc/README.md @@ -1,5 +1,4 @@ -Haddock documentation ---------------------- +# Haddock documentation The documentation is in DocBook XML format. You need some tools to process it: at least xsltproc, and the DocBook XML DTD and XSL @@ -8,19 +7,19 @@ process the documentation on your system, and a Makefile to actually do the processing (so, on Windows, you'll need Cygwin or MSys in addition to the DocBook XML tools). To build the HTML documentation: - $ autoconf - $ ./configure - $ make html + $ autoconf + $ ./configure + $ make html which leaves the HTML documentation in a haddock/ subdirectory. Printable documentation can also be produced, eg.: - $ make pdf + $ make pdf or - $ make ps + $ make ps Generating the printed formats requires more tools (fop or xmltex) and tends to be a bit harder. diff --git a/doc/haddock.xml b/doc/haddock.xml index 2ffd7d78..e805a437 100644 --- a/doc/haddock.xml +++ b/doc/haddock.xml @@ -12,7 +12,7 @@ <book id="haddock"> <bookinfo> - <date>2004-08-02</date> + <date>2015-06-02</date> <title>Haddock User Guide</title> <author> <firstname>Simon</firstname> @@ -24,12 +24,21 @@ <surname>Waern</surname> </author> <address><email>david.waern@gmail.com</email></address> + <author> + <firstname>Mateusz</firstname> + <surname>Kowalczyk</surname> + </author> + <address><email>fuuzetsu@fuuzetsu.co.uk</email></address> <copyright> <year>2010</year> <holder>Simon Marlow, David Waern</holder> </copyright> + <copyright> + <year>2013-2015</year> + <holder>Mateusz Kowalczyk</holder> + </copyright> <abstract> - <para>This document describes Haddock version 2.15.1, a Haskell + <para>This document describes Haddock version 2.16.2, a Haskell documentation tool.</para> </abstract> </bookinfo> @@ -336,11 +345,27 @@ <varlistentry> <term> <indexterm><primary><option>-i</option></primary></indexterm> - <option>-i</option> <replaceable>path</replaceable>,<replaceable>file</replaceable> + <option>-i</option> <replaceable>file</replaceable> + </term> + <term> + <indexterm><primary><option>-i</option></primary></indexterm> + <option>-i</option> <replaceable>docpath</replaceable>,<replaceable>file</replaceable> + </term> + <term> + <indexterm><primary><option>-i</option></primary></indexterm> + <option>-i</option> <replaceable>docpath</replaceable>,<replaceable>srcpath</replaceable>,<replaceable>file</replaceable> </term> <term> <indexterm><primary><option>--read-interface</option></primary></indexterm> - <option>--read-interface</option>=<replaceable>path</replaceable>,<replaceable>file</replaceable> + <option>--read-interface</option>=<replaceable>file</replaceable> + </term> + <term> + <indexterm><primary><option>--read-interface</option></primary></indexterm> + <option>--read-interface</option>=<replaceable>docpath</replaceable>,<replaceable>file</replaceable> + </term> + <term> + <indexterm><primary><option>--read-interface</option></primary></indexterm> + <option>--read-interface</option>=<replaceable>docpath</replaceable>,<replaceable>srcpath</replaceable>,<replaceable>file</replaceable> </term> <listitem> <para>Read the interface file in @@ -348,19 +373,25 @@ produced by running Haddock with the <option>--dump-interface</option> option. The interface describes a set of modules whose HTML documentation is - located in <replaceable>path</replaceable> (which may be a - relative pathname). The <replaceable>path</replaceable> is - optional, and defaults to <quote>.</quote>.</para> + located in <replaceable>docpath</replaceable> (which may be a + relative pathname). The <replaceable>docpath</replaceable> is + optional, and defaults to <quote>.</quote>. The + <replaceable>srcpath</replaceable> is optional but has no default + value.</para> <para>This option allows Haddock to produce separate sets of documentation with hyperlinks between them. The - <replaceable>path</replaceable> is used to direct hyperlinks + <replaceable>docpath</replaceable> is used to direct hyperlinks to point to the right files; so make sure you don't move the HTML files later or these links will break. Using a - relative <replaceable>path</replaceable> means that a + relative <replaceable>docpath</replaceable> means that a documentation subtree can still be moved around without breaking links.</para> + <para>Similarly to <replaceable>docpath</replaceable>, <replaceable>srcpath</replaceable> is used generate cross-package hyperlinks but + within sources rendered with <option>--hyperlinked-source</option> + option.</para> + <para>Multiple <option>--read-interface</option> options may be given.</para> </listitem> @@ -521,6 +552,43 @@ $ pdflatex <replaceable>package</replaceable>.tex</screen> <varlistentry> <term> + <indexterm><primary><option>--hyperlinked-source</option></primary></indexterm> + <option>--hyperlinked-source</option> + </term> + <listitem> + <para>Generate hyperlinked source code (as HTML web page). All + rendered files will be put into + <filename class='directory'>src/</filename> subfolder of output + directory.</para> + <para>Usually, this should be used in combination with + <option>--html</option> option - generated documentation will then + contain references to appropriate code fragments. Previously, this + behaviour could be achieved by generating sources using external + tool and specifying <option>--source-base</option>, + <option>--source-module</option>, <option>--source-entity</option> + and related options. Note that these flags are ignored once + <option>--hyperlinked-source</option> is set.</para> + <para>In order to make cross-package source hyperlinking possible, + appropriate source paths have to be set up when providing + interface files using <option>--read-interface</option> + option.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <indexterm><primary><option>--source-css</option></primary></indexterm> + <option>--source-css=<replaceable>style</replaceable></option> + </term> + <listitem> + <para>Use custom CSS file for sources rendered by the + <option>--hyperlinked-source</option> option. If no custom style + file is provided, Haddock will use default one.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> <indexterm><primary><option>-S</option></primary></indexterm> <option>-S</option> </term> @@ -2029,7 +2097,18 @@ This belongs to the list above! 2. No newline separation even in indented lists. -} </programlisting> + <para>The indentation of the first list item is honoured. That is, + in the following example the items are on the same level. Before + Haddock 2.16.1, the second item would have been nested under the + first item which was unexpected. + </para> +<programlisting> +{-| + * foo + * bar +-} +</programlisting> </section> <section> |