From bfd47453c76c7fb849c50eed750f61e28dc5cbdb Mon Sep 17 00:00:00 2001
From: Ben Gamari <ben@smart-cactus.org>
Date: Sun, 7 Feb 2016 11:21:42 -0500
Subject: doc: Switch to Sphinx
---
doc/.gitignore | 1 +
doc/Makefile | 10 +-
doc/README.md | 23 +-
doc/aclocal.m4 | 174 ----
doc/conf.py | 69 ++
doc/config.mk.in | 15 -
doc/configure.ac | 12 -
doc/docbook-xml.mk | 130 ---
doc/fptools.css | 36 -
doc/ghc.mk | 9 +-
doc/haddock.xml | 2329 ----------------------------------------------------
doc/index.rst | 21 +
doc/intro.rst | 164 ++++
doc/invoking.rst | 454 ++++++++++
doc/markup.rst | 887 ++++++++++++++++++++
15 files changed, 1613 insertions(+), 2721 deletions(-)
create mode 100644 doc/.gitignore
delete mode 100644 doc/aclocal.m4
create mode 100644 doc/conf.py
delete mode 100644 doc/config.mk.in
delete mode 100644 doc/configure.ac
delete mode 100644 doc/docbook-xml.mk
delete mode 100644 doc/fptools.css
delete mode 100644 doc/haddock.xml
create mode 100644 doc/index.rst
create mode 100644 doc/intro.rst
create mode 100644 doc/invoking.rst
create mode 100644 doc/markup.rst
diff --git a/doc/.gitignore b/doc/.gitignore
new file mode 100644
index 00000000..1bf230d1
--- /dev/null
+++ b/doc/.gitignore
@@ -0,0 +1 @@
+.build-html
\ No newline at end of file
diff --git a/doc/Makefile b/doc/Makefile
index 5f88b708..f4356f43 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -1,6 +1,8 @@
-include config.mk
+SPHINX_BUILD ?= sphinx-build
-XML_DOC = haddock
-INSTALL_XML_DOC = haddock
+all : html
-include docbook-xml.mk
+.PHONY : html
+
+html :
+ $(SPHINX_BUILD) -b html . .build-html
diff --git a/doc/README.md b/doc/README.md
index cf1fc31b..947d7f93 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -1,25 +1,10 @@
# 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
-stylesheets. There's a configure script to detect the right way to
-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:
+The documentation is in ReStructuredText format. You need
+[Sphinx](http://www.sphinx-doc.org/) to process it. To build the HTML
+documentation,
- $ autoconf
- $ ./configure
$ make html
-which leaves the HTML documentation in a haddock/ subdirectory.
+which leaves the HTML documentation the `.build-html/` subdirectory.
-Printable documentation can also be produced, eg.:
-
- $ make pdf
-
-or
-
- $ make ps
-
-Generating the printed formats requires more tools (fop or xmltex) and
-tends to be a bit harder.
diff --git a/doc/aclocal.m4 b/doc/aclocal.m4
deleted file mode 100644
index 97ffcb76..00000000
--- a/doc/aclocal.m4
+++ /dev/null
@@ -1,174 +0,0 @@
-# FP_GEN_DOCBOOK_XML
-# ------------------
-# Generates a DocBook XML V4.2 document in conftest.xml.
-AC_DEFUN([FP_GEN_DOCBOOK_XML],
-[rm -f conftest.xml
-cat > conftest.xml << EOF
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-<book id="test">
- <title>A DocBook Test Document</title>
- <chapter id="id-one">
- <title>A Chapter Title</title>
- <para>This is a paragraph, referencing <xref linkend="id-two"/>.</para>
- </chapter>
- <chapter id="id-two">
- <title>Another Chapter Title</title>
- <para>This is another paragraph, referencing <xref linkend="id-one"/>.</para>
- </chapter>
-</book>
-EOF
-]) # FP_GEN_DOCBOOK_XML
-
-
-# FP_PROG_XSLTPROC
-# ----------------
-# Sets the output variable XsltprocCmd to the full path of the XSLT processor
-# xsltproc. XsltprocCmd is empty if xsltproc could not be found.
-AC_DEFUN([FP_PROG_XSLTPROC],
-[AC_PATH_PROG([XsltprocCmd], [xsltproc])
-if test -z "$XsltprocCmd"; then
- AC_MSG_WARN([cannot find xsltproc in your PATH, you will not be able to build the documentation])
-fi
-])# FP_PROG_XSLTPROC
-
-
-# FP_DIR_DOCBOOK_XSL(XSL-DIRS)
-# ----------------------------
-# Check which of the directories XSL-DIRS contains DocBook XSL stylesheets. The
-# output variable DIR_DOCBOOK_XSL will contain the first usable directory or
-# will be empty if none could be found.
-AC_DEFUN([FP_DIR_DOCBOOK_XSL],
-[AC_REQUIRE([FP_PROG_XSLTPROC])dnl
-if test -n "$XsltprocCmd"; then
- AC_CACHE_CHECK([for DocBook XSL stylesheet directory], fp_cv_dir_docbook_xsl,
- [FP_GEN_DOCBOOK_XML
- fp_cv_dir_docbook_xsl=no
- for fp_var in $1; do
- if $XsltprocCmd ${fp_var}/html/docbook.xsl conftest.xml > /dev/null 2>&1; then
- fp_cv_dir_docbook_xsl=$fp_var
- break
- fi
- done
- rm -rf conftest*])
-fi
-if test x"$fp_cv_dir_docbook_xsl" = xno; then
- AC_MSG_WARN([cannot find DocBook XSL stylesheets, you will not be able to build the documentation])
- DIR_DOCBOOK_XSL=
-else
- DIR_DOCBOOK_XSL=$fp_cv_dir_docbook_xsl
-fi
-AC_SUBST([DIR_DOCBOOK_XSL])
-])# FP_DIR_DOCBOOK_XSL
-
-
-# FP_PROG_XMLLINT
-# ----------------
-# Sets the output variable XmllintCmd to the full path of the XSLT processor
-# xmllint. XmllintCmd is empty if xmllint could not be found.
-AC_DEFUN([FP_PROG_XMLLINT],
-[AC_PATH_PROG([XmllintCmd], [xmllint])
-if test -z "$XmllintCmd"; then
- AC_MSG_WARN([cannot find xmllint in your PATH, you will not be able to validate your documentation])
-fi
-])# FP_PROG_XMLLINT
-
-
-# FP_CHECK_DOCBOOK_DTD
-# --------------------
-AC_DEFUN([FP_CHECK_DOCBOOK_DTD],
-[AC_REQUIRE([FP_PROG_XMLLINT])dnl
-if test -n "$XmllintCmd"; then
- AC_MSG_CHECKING([for DocBook DTD])
- FP_GEN_DOCBOOK_XML
- if $XmllintCmd --valid --noout conftest.xml > /dev/null 2>&1; then
- AC_MSG_RESULT([ok])
- else
- AC_MSG_RESULT([failed])
- AC_MSG_WARN([cannot find a DTD for DocBook XML V4.2, you will not be able to validate your documentation])
- AC_MSG_WARN([check your XML_CATALOG_FILES environment variable and/or /etc/xml/catalog])
- fi
- rm -rf conftest*
-fi
-])# FP_CHECK_DOCBOOK_DTD
-
-
-# FP_GEN_FO
-# ------------------
-# Generates a formatting objects document in conftest.fo.
-AC_DEFUN([FP_GEN_FO],
-[rm -f conftest.fo
-cat > conftest.fo << EOF
-<?xml version="1.0"?>
-<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
- <fo:layout-master-set>
- <fo:simple-page-master master-name="blank">
- <fo:region-body/>
- </fo:simple-page-master>
- </fo:layout-master-set>
- <fo:page-sequence master-reference="blank">
- <fo:flow flow-name="xsl-region-body">
- <fo:block>
- Test!
- </fo:block>
- </fo:flow>
- </fo:page-sequence>
-</fo:root>
-EOF
-]) # FP_GEN_FO
-
-
-# FP_PROG_FOP
-# -----------
-# Set the output variable 'FopCmd' to the first working 'fop' in the current
-# 'PATH'. Note that /usr/bin/fop is broken in SuSE 9.1 (unpatched), so try
-# /usr/share/fop/fop.sh in that case (or no 'fop'), too.
-AC_DEFUN([FP_PROG_FOP],
-[AC_PATH_PROGS([FopCmd1], [fop])
-if test -n "$FopCmd1"; then
- AC_CACHE_CHECK([for $FopCmd1 usability], [fp_cv_fop_usability],
- [FP_GEN_FO
- if "$FopCmd1" -fo conftest.fo -ps conftest.ps > /dev/null 2>&1; then
- fp_cv_fop_usability=yes
- else
- fp_cv_fop_usability=no
- fi
- rm -rf conftest*])
- if test x"$fp_cv_fop_usability" = xyes; then
- FopCmd=$FopCmd1
- fi
-fi
-if test -z "$FopCmd"; then
- AC_PATH_PROGS([FopCmd2], [fop.sh], , [/usr/share/fop])
- FopCmd=$FopCmd2
-fi
-AC_SUBST([FopCmd])
-])# FP_PROG_FOP
-
-
-# FP_PROG_FO_PROCESSOR
-# --------------------
-# Try to find an FO processor. PassiveTeX output is sometimes a bit strange, so
-# try FOP first. Sets the output variables FopCmd, XmltexCmd, DvipsCmd, and
-# PdfxmltexCmd.
-AC_DEFUN([FP_PROG_FO_PROCESSOR],
-[AC_REQUIRE([FP_PROG_FOP])
-AC_PATH_PROG([XmltexCmd], [xmltex])
-AC_PATH_PROG([DvipsCmd], [dvips])
-if test -z "$FopCmd"; then
- if test -z "$XmltexCmd"; then
- AC_MSG_WARN([cannot find an FO => DVI converter, you will not be able to build DVI or PostScript documentation])
- else
- if test -z "$DvipsCmd"; then
- AC_MSG_WARN([cannot find a DVI => PS converter, you will not be able to build PostScript documentation])
- fi
- fi
- AC_PATH_PROG([PdfxmltexCmd], [pdfxmltex])
- if test -z "$PdfxmltexCmd"; then
- AC_MSG_WARN([cannot find an FO => PDF converter, you will not be able to build PDF documentation])
- fi
-elif test -z "$XmltexCmd"; then
- AC_MSG_WARN([cannot find an FO => DVI converter, you will not be able to build DVI documentation])
-fi
-])# FP_PROG_FO_PROCESSOR
diff --git a/doc/conf.py b/doc/conf.py
new file mode 100644
index 00000000..d6b8bda8
--- /dev/null
+++ b/doc/conf.py
@@ -0,0 +1,69 @@
+# -*- coding: utf-8 -*-
+
+import sys
+import os
+import shlex
+
+extensions = []
+
+source_suffix = '.rst'
+master_doc = 'index'
+
+# General information about the project.
+project = u'Haddock'
+copyright = u'2016, Simon Marlow'
+author = u'Simon Marlow'
+version = '1.0'
+release = '1.0'
+
+language = 'en'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['.build']
+todo_include_todos = False
+
+# Syntax highlighting
+highlight_language = 'haskell'
+pygments_style = 'tango'
+
+# -- Options for HTML output ----------------------------------------------
+
+html_theme = 'alabaster'
+htmlhelp_basename = 'Haddockdoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = { }
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+# author, documentclass [howto, manual, or own class]).
+latex_documents = [
+ (master_doc, 'Haddock.tex', u'Haddock Documentation',
+ u'Simon Marlow', 'manual'),
+]
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ (master_doc, 'haddock', u'Haddock Documentation',
+ [author], 1)
+]
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+# dir menu entry, description, category)
+texinfo_documents = [
+ (master_doc, 'Haddock', u'Haddock Documentation',
+ author, 'Haddock', 'One line description of project.',
+ 'Miscellaneous'),
+]
+
diff --git a/doc/config.mk.in b/doc/config.mk.in
deleted file mode 100644
index e286794c..00000000
--- a/doc/config.mk.in
+++ /dev/null
@@ -1,15 +0,0 @@
-#-----------------------------------------------------------------------------
-# DocBook XML stuff
-
-XSLTPROC = @XsltprocCmd@
-XMLLINT = @XmllintCmd@
-FOP = @FopCmd@
-XMLTEX = @XmltexCmd@
-PDFXMLTEX = @PdfxmltexCmd@
-DVIPS = @DvipsCmd@
-
-DIR_DOCBOOK_XSL = @DIR_DOCBOOK_XSL@
-
-XSLTPROC_LABEL_OPTS = --stringparam toc.section.depth 3 \
- --stringparam section.autolabel 1 \
- --stringparam section.label.includes.component.label 1
diff --git a/doc/configure.ac b/doc/configure.ac
deleted file mode 100644
index acf459e8..00000000
--- a/doc/configure.ac
+++ /dev/null
@@ -1,12 +0,0 @@
-
-AC_INIT([Haddock docs], [1.0], [simonmar@microsoft.com], [])
-
-AC_CONFIG_SRCDIR([Makefile])
-
-dnl ** check for DocBook toolchain
-FP_CHECK_DOCBOOK_DTD
-FP_DIR_DOCBOOK_XSL([/usr/share/xml/docbook/stylesheet/nwalsh/current /usr/share/xml/docbook/stylesheet/nwalsh /usr/share/sgml/docbook/docbook-xsl-stylesheets* /usr/share/sgml/docbook/xsl-stylesheets* /opt/kde?/share/apps/ksgmltools2/docbook/xsl /usr/share/docbook-xsl /usr/share/sgml/docbkxsl /usr/local/share/xsl/docbook /sw/share/xml/xsl/docbook-xsl /usr/share/xml/docbook/xsl-stylesheets-*])
-FP_PROG_FO_PROCESSOR
-
-AC_CONFIG_FILES([config.mk])
-AC_OUTPUT
diff --git a/doc/docbook-xml.mk b/doc/docbook-xml.mk
deleted file mode 100644
index f6048187..00000000
--- a/doc/docbook-xml.mk
+++ /dev/null
@@ -1,130 +0,0 @@
-#-----------------------------------------------------------------------------
-# DocBook XML
-
-.PHONY: html html-no-chunks chm HxS fo dvi ps pdf
-
-ifneq "$(XML_DOC)" ""
-
-all :: html
-
-# multi-file XML document: main document name is specified in $(XML_DOC),
-# sub-documents (.xml files) listed in $(XML_SRCS).
-
-ifeq "$(XML_SRCS)" ""
-XML_SRCS = $(wildcard *.xml)
-endif
-
-XML_HTML = $(addsuffix /index.html,$(basename $(XML_DOC)))
-XML_HTML_NO_CHUNKS = $(addsuffix .html,$(XML_DOC))
-XML_CHM = $(addsuffix .chm,$(XML_DOC))
-XML_HxS = $(addsuffix .HxS,$(XML_DOC))
-XML_FO = $(addsuffix .fo,$(XML_DOC))
-XML_DVI = $(addsuffix .dvi,$(XML_DOC))
-XML_PS = $(addsuffix .ps,$(XML_DOC))
-XML_PDF = $(addsuffix .pdf,$(XML_DOC))
-
-$(XML_HTML) $(XML_NO_CHUNKS_HTML) $(XML_FO) $(XML_DVI) $(XML_PS) $(XML_PDF) :: $(XML_SRCS)
-
-html :: $(XML_HTML)
-html-no-chunks :: $(XML_HTML_NO_CHUNKS)
-chm :: $(XML_CHM)
-HxS :: $(XML_HxS)
-fo :: $(XML_FO)
-dvi :: $(XML_DVI)
-ps :: $(XML_PS)
-pdf :: $(XML_PDF)
-
-CLEAN_FILES += $(XML_HTML_NO_CHUNKS) $(XML_FO) $(XML_DVI) $(XML_PS) $(XML_PDF)
-
-FPTOOLS_CSS = fptools.css
-
-clean ::
- $(RM) -rf $(XML_DOC).out $(basename $(XML_DOC)) $(basename $(XML_DOC))-htmlhelp
-
-validate ::
- $(XMLLINT) --valid --noout $(XMLLINT_OPTS) $(XML_DOC).xml
-endif
-
-#-----------------------------------------------------------------------------
-# DocBook XML suffix rules
-#
-
-%.html : %.xml
- $(XSLTPROC) --output $@ \
- --stringparam html.stylesheet $(FPTOOLS_CSS) \
- $(XSLTPROC_LABEL_OPTS) $(XSLTPROC_OPTS) \
- $(DIR_DOCBOOK_XSL)/html/docbook.xsl $<
-
-%/index.html : %.xml
- $(RM) -rf $(dir $@)
- $(XSLTPROC) --stringparam base.dir $(dir $@) \
- --stringparam use.id.as.filename 1 \
- --stringparam html.stylesheet $(FPTOOLS_CSS) \
- $(XSLTPROC_LABEL_OPTS) $(XSLTPROC_OPTS) \
- $(DIR_DOCBOOK_XSL)/html/chunk.xsl $<
- cp $(FPTOOLS_CSS) $(dir $@)
-
-# Note: Numeric labeling seems to be uncommon for HTML Help
-%-htmlhelp/index.html : %.xml
- $(RM) -rf $(dir $@)
- $(XSLTPROC) --stringparam base.dir $(dir $@) \
- --stringparam manifest.in.base.dir 1 \
- --stringparam htmlhelp.chm "..\\"$(basename $<).chm \
- $(XSLTPROC_OPTS) \
- $(DIR_DOCBOOK_XSL)/htmlhelp/htmlhelp.xsl $<
-
-%-htmlhelp2/collection.HxC : %.xml
- $(RM) -rf $(dir $@)
- $(XSLTPROC) --stringparam base.dir $(dir $@) \
- --stringparam use.id.as.filename 1 \
- --stringparam manifest.in.base.dir 1 \
- $(XSLTPROC_OPTS) \
- $(DIR_DOCBOOK_XSL)/htmlhelp2/htmlhelp2.xsl $<
-
-# TODO: Detect hhc & Hxcomp via autoconf
-#
-# Two obstacles here:
-#
-# * The reason for the strange "if" below is that hhc returns 0 on error and 1
-# on success, the opposite of what shells and make expect.
-#
-# * There seems to be some trouble with DocBook indices, but the *.chm looks OK,
-# anyway, therefore we pacify make by "|| true". Ugly...
-#
-%.chm : %-htmlhelp/index.html
- ( cd $(dir $<) && if hhc htmlhelp.hhp ; then false ; else true ; fi ) || true
-
-%.HxS : %-htmlhelp2/collection.HxC
- ( cd $(dir $<) && if Hxcomp -p collection.HxC -o ../$@ ; then false ; else true ; fi )
-
-%.fo : %.xml
- $(XSLTPROC) --output $@ \
- --stringparam draft.mode no \
- $(XSLTPROC_LABEL_OPTS) $(XSLTPROC_OPTS) \
- $(DIR_DOCBOOK_XSL)/fo/docbook.xsl $<
-
-ifeq "$(FOP)" ""
-ifneq "$(PDFXMLTEX)" ""
-%.pdf : %.fo
- $(PDFXMLTEX) $<
- if grep "LaTeX Warning: Label(s) may have changed.Rerun to get cross-references right." $(basename $@).log > /dev/null ; then \
- $(PDFXMLTEX) $< ; \
- $(PDFXMLTEX) $< ; \
- fi
-endif
-else
-%.ps : %.fo
- $(FOP) $(FOP_OPTS) -fo $< -ps $@
-
-%.pdf : %.fo
- $(FOP) $(FOP_OPTS) -fo $< -pdf $@
-endif
-
-ifneq "$(XMLTEX)" ""
-%.dvi : %.fo
- $(XMLTEX) $<
- if grep "LaTeX Warning: Label(s) may have changed.Rerun to get cross-references right." $(basename $@).log > /dev/null ; then \
- $(XMLTEX) $< ; \
- $(XMLTEX) $< ; \
- fi
-endif
diff --git a/doc/fptools.css b/doc/fptools.css
deleted file mode 100644
index 5c7fc47b..00000000
--- a/doc/fptools.css
+++ /dev/null
@@ -1,36 +0,0 @@
-div {
- font-family: sans-serif;
- color: black;
- background: white
-}
-
-h1, h2, h3, h4, h5, h6, p.title { color: #005A9C }
-
-h1 { font: 170% sans-serif }
-h2 { font: 140% sans-serif }
-h3 { font: 120% sans-serif }
-h4 { font: bold 100% sans-serif }
-h5 { font: italic 100% sans-serif }
-h6 { font: small-caps 100% sans-serif }
-
-pre {
- font-family: monospace;
- border-width: 1px;
- border-style: solid;
- padding: 0.3em
-}
-
-pre.screen { color: #006400 }
-pre.programlisting { color: maroon }
-
-div.example {
- background-color: #fffcf5;
- margin: 1ex 0em;
- border: solid #412e25 1px;
- padding: 0ex 0.4em
-}
-
-a:link { color: #0000C8 }
-a:hover { background: #FFFFA8 }
-a:active { color: #D00000 }
-a:visited { color: #680098 }
diff --git a/doc/ghc.mk b/doc/ghc.mk
index 73d6b7f0..52a2f2a5 100644
--- a/doc/ghc.mk
+++ b/doc/ghc.mk
@@ -10,6 +10,11 @@
#
# -----------------------------------------------------------------------------
-utils/haddock/doc_DOCBOOK_SOURCES = utils/haddock/doc/haddock.xml
+INSTALL_HTML_DOC_DIRS += utils/haddock/doc/haddock
+
+html : html_utils/haddock/doc
+
+html_utils/haddock/doc :
+ make -C utils/haddock/doc html SPHINX_BUILD=$(SPHINXBUILD)
+ cp -R utils/haddock/doc/.build-html utils/haddock/doc/haddock
-$(eval $(call docbook,utils/haddock/doc,haddock))
diff --git a/doc/haddock.xml b/doc/haddock.xml
deleted file mode 100644
index e805a437..00000000
--- a/doc/haddock.xml
+++ /dev/null
@@ -1,2329 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
- <!ENTITY nbsp ' '>
- <!ENTITY frac12 '½'>
- <!ENTITY mdash '—'>
- <!ENTITY lsquo '’'>
- <!ENTITY rsquo '‚'>
- <!ENTITY ldquo '“'>
- <!ENTITY rdquo '”'>
-] >
-
-<book id="haddock">
- <bookinfo>
- <date>2015-06-02</date>
- <title>Haddock User Guide</title>
- <author>
- <firstname>Simon</firstname>
- <surname>Marlow</surname>
- </author>
- <address><email>marlowsd@gmail.com</email></address>
- <author>
- <firstname>David</firstname>
- <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.16.2, a Haskell
- documentation tool.</para>
- </abstract>
- </bookinfo>
-
- <!-- Table of contents -->
- <toc></toc>
-
- <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 a 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 obscure the code and to make reading and writing
- documentation annotations easy. The easier it is to write
- documentation, the more likely the programmer is to do it.
- 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 not only
- non-exported entities from the interface, but also 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, LaTeX,
- and Hoogle backends, and it is structured in such a way that adding new
- backends 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 our public
- darcs repository. The Haddock sources are at
- <literal>http://code.haskell.org/haddock</literal>. See
- <ulink url="http://www.darcs.net/">darcs.net</ulink> for more
- information on the darcs version control utility.</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-2010, 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>
-
- <section>
- <title>Contributors</title>
- <para>Haddock was originally written by Simon Marlow. Since it is an open source
- project, many people have contributed to its development over the years.
- Below is a list of contributors in alphabetical order that we hope is
- somewhat complete. If you think you are missing from this list, please contact
- us.
- </para>
- <itemizedlist>
- <listitem><simpara>Ashley Yakeley</simpara></listitem>
- <listitem><simpara>Benjamin Franksen</simpara></listitem>
- <listitem><simpara>Brett Letner</simpara></listitem>
- <listitem><simpara>Clemens Fruhwirth</simpara></listitem>
- <listitem><simpara>Conal Elliott</simpara></listitem>
- <listitem><simpara>David Waern</simpara></listitem>
- <listitem><simpara>Duncan Coutts</simpara></listitem>
- <listitem><simpara>George Pollard</simpara></listitem>
- <listitem><simpara>George Russel</simpara></listitem>
- <listitem><simpara>Hal Daume</simpara></listitem>
- <listitem><simpara>Ian Lynagh</simpara></listitem>
- <listitem><simpara>Isaac Dupree</simpara></listitem>
- <listitem><simpara>Joachim Breitner</simpara></listitem>
- <listitem><simpara>Krasimir Angelov</simpara></listitem>
- <listitem><simpara>Lennart Augustsson</simpara></listitem>
- <listitem><simpara>Luke Plant</simpara></listitem>
- <listitem><simpara>Malcolm Wallace</simpara></listitem>
- <listitem><simpara>Manuel Chakravarty</simpara></listitem>
- <listitem><simpara>Mark Lentczner</simpara></listitem>
- <listitem><simpara>Mark Shields</simpara></listitem>
- <listitem><simpara>Mateusz Kowalczyk</simpara></listitem>
- <listitem><simpara>Mike Thomas</simpara></listitem>
- <listitem><simpara>Neil Mitchell</simpara></listitem>
- <listitem><simpara>Oliver Brown</simpara></listitem>
- <listitem><simpara>Roman Cheplyaka</simpara></listitem>
- <listitem><simpara>Ross Paterson</simpara></listitem>
- <listitem><simpara>Sigbjorn Finne</simpara></listitem>
- <listitem><simpara>Simon Hengel</simpara></listitem>
- <listitem><simpara>Simon Marlow</simpara></listitem>
- <listitem><simpara>Simon Peyton-Jones</simpara></listitem>
- <listitem><simpara>Stefan O'Rear</simpara></listitem>
- <listitem><simpara>Sven Panne</simpara></listitem>
- <listitem><simpara>Thomas Schilling</simpara></listitem>
- <listitem><simpara>Wolfgang Jeltsch</simpara></listitem>
- <listitem><simpara>Yitzchak Gale</simpara></listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Acknowledgements</title>
-
- <para>Several documentation systems provided the inspiration for
- Haddock, most notably:</para>
-
- <itemizedlist>
- <listitem>
- <para><ulink
- url="http://www.cse.unsw.edu.au/~chak/haskell/idoc/">
- IDoc</ulink></para>
- </listitem>
- <listitem>
- <para><ulink
- url="http://www.fmi.uni-passau.de/~groessli/hdoc/">HDoc</ulink></para>
- </listitem>
- <listitem>
- <para><ulink url="http://www.stack.nl/~dimitri/doxygen/">
- Doxygen</ulink></para>
- </listitem>
- </itemizedlist>
-
- <para>and probably several others I've forgotten.</para>
-
- <para>Thanks to the the members
- of <email>haskelldoc@haskell.org</email>,
- <email>haddock@projects.haskell.org</email> and everyone who
- contributed to the many libraries that Haddock makes use
- of.</para>
- </section>
-
- </chapter>
-
- <chapter id="invoking">
- <title>Invoking Haddock</title>
- <para>Haddock is invoked from the command line, like so:</para>
-
- <cmdsynopsis>
- <command>haddock</command>
- <arg rep="repeat"><replaceable>option</replaceable></arg>
- <arg rep="repeat" choice="plain"><replaceable>file</replaceable></arg>
- </cmdsynopsis>
-
- <para>Where each <replaceable>file</replaceable> is a filename
- containing a Haskell source module (.hs) or a Literate Haskell source
- module (.lhs) or just a module name.</para>
-
- <para>All the modules specified on the command line will be
- processed together. When one module refers to an entity in
- another module being processed, the documentation will link
- directly to that entity.</para>
-
- <para>Entities that cannot be found, for example because they are
- in a module that isn't being processed as part of the current
- batch, simply won't be hyperlinked in the generated
- documentation. Haddock will emit warnings listing all the
- identifiers it couldn't resolve.</para>
-
- <para>The modules should <emphasis>not</emphasis> be mutually
- recursive, as Haddock don't like swimming in circles.</para>
-
- <para>Note that while older version would fail on invalid markup, this is considered a bug in the
- new versions. If you ever get failed parsing message, please report it.</para>
-
- <para>You must also specify an option for the output format.
- Currently only the <option>-h</option> option for HTML and the
- <option>--hoogle</option> option for outputting Hoogle data are
- functional.</para>
-
- <para>The packaging
- tool <ulink url="http://www.haskell.org/ghc/docs/latest/html/Cabal/index.html">Cabal</ulink>
- has Haddock support, and is often used instead of invoking Haddock
- directly.</para>
-
- <para>The following options are available:</para>
-
- <variablelist>
-
- <varlistentry>
- <term>
- <indexterm><primary><option>-B</option></primary></indexterm>
- <option>-B</option> <replaceable>dir</replaceable>
- </term>
- <listitem>
- <para>Tell GHC that that its lib directory is
- <replaceable>dir</replaceable>. Can be used to override the default path.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <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>Generate files into <replaceable>dir</replaceable>
- instead of the current directory.</para>
- </listitem>
- </varlistentry>
-
- <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 Haddock auxiliary files (themes, javascript, etc...) in <replaceable>dir</replaceable>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary><option>-i</option></primary></indexterm>
- <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>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
- <replaceable>file</replaceable>, which must have been
- 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>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>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>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>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary><option>-D</option></primary></indexterm>
- <option>-D</option> <replaceable>file</replaceable>
- </term>
- <term>
- <indexterm><primary><option>--dump-interface</option></primary></indexterm>
- <option>--dump-interface</option>=<replaceable>file</replaceable>
- </term>
- <listitem>
- <para>Produce an <firstterm>interface
- file</firstterm><footnote><para>Haddock interface files are
- not the same as Haskell interface files, I just couldn't
- think of a better name.</para> </footnote>
- in the file <replaceable>file</replaceable>. An interface
- file contains information Haddock needs to produce more
- documentation that refers to the modules currently being
- processed - see the <option>--read-interface</option> option
- for more details. The interface file is in a binary format;
- don't try to read it.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary><option>-h</option></primary></indexterm>
- <option>-h</option>
- </term>
- <term>
- <indexterm><primary><option>--html</option></primary></indexterm>
- <option>--html</option>
- </term>
- <listitem>
- <para>Generate documentation in HTML 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>module</replaceable>.html</filename></term>
- <term><filename>mini_<replaceable>module</replaceable>.html</filename></term>
- <listitem>
- <para>An HTML page for each
- <replaceable>module</replaceable>, and a "mini" page for
- each used when viewing in frames.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><filename>index.html</filename></term>
- <listitem>
- <para>The top level page of the documentation: lists
- the modules available, using indentation to represent
- the hierarchy if the modules are hierarchical.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><filename>doc-index.html</filename></term>
- <term><filename>doc-index-<replaceable>X</replaceable>.html</filename></term>
- <listitem>
- <para>The alphabetic index, possibly split into multiple
- pages if big enough.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><filename>frames.html</filename></term>
- <listitem>
- <para>The top level document when viewing in frames.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><filename><replaceable>some</replaceable>.css</filename></term>
- <term><filename><replaceable>etc...</replaceable></filename></term>
- <listitem>
- <para>Files needed for the themes used. Specify your themes
- using the <option>--theme</option> option.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><filename>haddock-util.js</filename></term>
- <listitem>
- <para>Some JavaScript utilities used to implement some of the
- dynamic features like collapsible sections, and switching to
- frames view.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </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>--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>
- <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>--source-base</option></primary></indexterm>
- <option>--source-base</option>=<replaceable>URL</replaceable>
- </term>
- <term>
- <indexterm><primary><option>--source-module</option></primary></indexterm>
- <option>--source-module</option>=<replaceable>URL</replaceable>
- </term>
- <term>
- <indexterm><primary><option>--source-entity</option></primary></indexterm>
- <option>--source-entity</option>=<replaceable>URL</replaceable>
- </term>
- <term>
- <indexterm><primary><option>--source-entity-line</option></primary></indexterm>
- <option>--source-entity-line</option>=<replaceable>URL</replaceable>
- </term>
- <listitem>
- <para>Include links to the source files in the generated
- documentation. Use the <option>--source-base</option> option to add a
- source code link in the header bar of the contents and index pages.
- Use the <option>--source-module</option> to add a source code link in
- the header bar of each module page. Use the
- <option>--source-entity</option> option to add a source code link
- next to the documentation for every value and type in each module.
- <option>--source-entity-line</option> is a flag that gets used for
- entities that need to link to an exact source location rather than a
- name, eg. since they were defined inside a Template Haskell splice.
- </para>
-
- <para>In each case <replaceable>URL</replaceable> is the base URL
- where the source files can be found. For the per-module and
- per-entity URLs, the following substitutions are made within the
- string <replaceable>URL</replaceable>:</para>
-
- <itemizedlist>
- <listitem>
- <para>The string <literal>%M</literal> or <literal>%{MODULE}</literal>
- is replaced by the module name. Note that for the per-entity URLs
- this is the name of the <emphasis>exporting</emphasis> module.</para>
- </listitem>
- <listitem>
- <para>The string <literal>%F</literal> or <literal>%{FILE}</literal>
- is replaced by the original source file name. Note that for the
- per-entity URLs this is the name of the <emphasis>defining</emphasis>
- module.</para>
- </listitem>
- <listitem>
- <para>The string <literal>%N</literal> or <literal>%{NAME}</literal>
- is replaced by the name of the exported value or type. This is
- only valid for the <option>--source-entity</option> option.</para>
- </listitem>
- <listitem>
- <para>The string <literal>%K</literal> or <literal>%{KIND}</literal>
- is replaced by a flag indicating whether the exported name is a value
- '<literal>v</literal>' or a type '<literal>t</literal>'. This is
- only valid for the <option>--source-entity</option> option.</para>
- </listitem>
- <listitem>
- <para>The string <literal>%L</literal> or <literal>%{LINE}</literal>
- is replaced by the number of the line where the exported value or
- type is defined. This is only valid for the
- <option>--source-entity</option> option.</para>
- </listitem>
- <listitem>
- <para>The string <literal>%%</literal> is replaced by
- <literal>%</literal>.</para>
- </listitem>
-
- </itemizedlist>
-
- <para>For example, if your sources are online under some directory,
- you would say
- <literal>haddock --source-base=<replaceable>url</replaceable>/
- --source-module=<replaceable>url</replaceable>/%F</literal></para>
-
- <para>If you have html versions of your sources online with anchors
- for each type and function name, you would say
- <literal>haddock --source-base=<replaceable>url</replaceable>/
- --source-module=<replaceable>url</replaceable>/%M.html
- --source-entity=<replaceable>url</replaceable>/%M.html#%N</literal></para>
-
- <para>For the <literal>%{MODULE}</literal> substitution you may want to
- replace the '<literal>.</literal>' character in the module names with
- some other character (some web servers are known to get confused by
- multiple '<literal>.</literal>' characters in a file name). To
- replace it with a character <replaceable>c</replaceable> use
- <literal>%{MODULE/./<replaceable>c</replaceable>}</literal>.</para>
-
- <para>Similarly, for the <literal>%{FILE}</literal> substitution
- you may want to replace the '<literal>/</literal>' character in
- the file names with some other character (especially for links
- to colourised entity source code with a shared css file). To replace
- it with a character <replaceable>c</replaceable> use
- <literal>%{FILE///<replaceable>c</replaceable>}</literal>/</para>
-
- <para>One example of a tool that can generate syntax-highlighted
- HTML from your source code, complete with anchors suitable for use
- from haddock, is
- <ulink url="http://www.cs.york.ac.uk/fp/darcs/hscolour">hscolour</ulink>.</para>
-
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary><option>-s</option></primary></indexterm>
- <option>-s</option> <replaceable>URL</replaceable>
- </term>
- <term>
- <indexterm><primary><option>--source</option></primary></indexterm>
- <option>--source</option>=<replaceable>URL</replaceable>
- </term>
- <listitem>
- <para>Deprecated aliases for <option>--source-module</option></para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary><option>--comments-base</option></primary></indexterm>
- <option>--comments-base</option>=<replaceable>URL</replaceable>
- </term>
- <term>
- <indexterm><primary><option>--comments-module</option></primary></indexterm>
- <option>--comments-module</option>=<replaceable>URL</replaceable>
- </term>
- <term>
- <indexterm><primary><option>--comments-entity</option></primary></indexterm>
- <option>--comments-entity</option>=<replaceable>URL</replaceable>
- </term>
- <listitem>
- <para>Include links to pages where readers may comment on the
- documentation. This feature would typically be used in conjunction
- with a Wiki system.</para>
-
- <para>Use the <option>--comments-base</option> option to add a
- user comments link in the header bar of the contents and index pages.
- Use the <option>--comments-module</option> to add a user comments
- link in the header bar of each module page. Use the
- <option>--comments-entity</option> option to add a comments link
- next to the documentation for every value and type in each module.
- </para>
-
- <para>In each case <replaceable>URL</replaceable> is the base URL
- where the corresponding comments page can be found. For the
- per-module and per-entity URLs the same substitutions are made as
- with the <option>--source-module</option> and
- <option>--source-entity</option> options above.</para>
-
- <para>For example, if you want to link the contents page to a wiki
- page, and every module to subpages, you would say
- <literal>haddock --comments-base=<replaceable>url</replaceable>
- --comments-module=<replaceable>url</replaceable>/%M</literal></para>
-
- <para>If your Wiki system doesn't like the '<literal>.</literal>' character
- in Haskell module names, you can replace it with a different character. For
- example to replace the '<literal>.</literal>' characters with
- '<literal>_</literal>' use <literal>haddock
- --comments-base=<replaceable>url</replaceable>
- --comments-module=<replaceable>url</replaceable>/%{MODULE/./_}</literal>
- Similarly, you can replace the '<literal>/</literal>' in a file name (may
- be useful for entity comments, but probably not.) </para>
-
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary><option>--theme</option></primary></indexterm>
- <option>--theme</option>=<replaceable>path</replaceable>
- </term>
- <listitem>
- <para>Specify a theme to be used for HTML (<option>--html</option>)
- documentation. If given multiple times then the pages will use the
- first theme given by default, and have alternate style sheets for
- the others. The reader can switch between themes with browsers that
- support alternate style sheets, or with the "Style" menu that gets
- added when the page is loaded. If
- no themes are specified, then just the default built-in theme
- ("Ocean") is used.
- </para>
-
- <para>The <replaceable>path</replaceable> parameter can be one of:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>A <emphasis>directory</emphasis>: The base name of
- the directory becomes the name of the theme. The directory
- must contain exactly one
- <filename><replaceable>some</replaceable>.css</filename> file.
- Other files, usually image files, will be copied, along with
- the <filename><replaceable>some</replaceable>.css</filename>
- file, into the generated output directory.</para>
- </listitem>
- <listitem>
- <para>A <emphasis>CSS file</emphasis>: The base name of
- the file becomes the name of the theme.</para>
- </listitem>
- <listitem>
- <para>The <emphasis>name</emphasis> of a built-in theme
- ("Ocean" or "Classic").</para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary><option>--built-in-themes</option></primary></indexterm>
- <option>--built-in-themes</option>
- </term>
- <listitem>
- <para>Includes the built-in themes ("Ocean" and "Classic").
- Can be combined with <option>--theme</option>. Note that order
- matters: The first specified theme will be the default.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary><option>-c</option></primary></indexterm>
- <option>-c</option> <replaceable>file</replaceable>
- </term>
- <term>
- <indexterm><primary><option>--css</option></primary></indexterm>
- <option>--css</option>=<replaceable>file</replaceable>
- </term>
- <listitem>
- <para>Deprecated aliases for <option>--theme</option></para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary><option>-p</option></primary></indexterm>
- <option>-p</option> <replaceable>file</replaceable>
- </term>
- <term>
- <indexterm><primary><option>--prologue</option></primary></indexterm>
- <option>--prologue</option>=<replaceable>file</replaceable>
- </term>
- <listitem>
- <para>Specify a file containing documentation which is
- placed on the main contents page under the heading
- “Description”. The file is parsed as a normal
- Haddock doc comment (but the comment markers are not
- required).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary><option>-t</option></primary></indexterm>
- <option>-t</option> <replaceable>title</replaceable>
- </term>
- <term>
- <indexterm><primary><option>--title</option></primary></indexterm>
- <option>--title</option>=<replaceable>title</replaceable>
- </term>
- <listitem>
- <para>Use <replaceable>title</replaceable> as the page
- heading for each page in the documentation.This will
- normally be the name of the library being documented.</para>
-
- <para>The title should be a plain string (no markup
- please!).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary><option>-q</option></primary></indexterm>
- <option>-q</option> <replaceable>mode</replaceable>
- </term>
- <term>
- <indexterm><primary><option>--qual</option></primary></indexterm>
- <option>--qual</option>=<replaceable>mode</replaceable>
- </term>
- <listitem>
- <para>
- Specify how identifiers are qualified.
- </para>
- <para>
- <replaceable>mode</replaceable> should be one of
- <itemizedlist>
- <listitem>
- <para>none (default): don't qualify any identifiers</para>
- </listitem>
- <listitem>
- <para>full: always qualify identifiers completely</para>
- </listitem>
- <listitem>
- <para>local: only qualify identifiers that are not part
- of the module</para>
- </listitem>
- <listitem>
- <para>relative: like local, but strip name of the module
- from qualifications of identifiers in submodules</para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Example: If you generate documentation for module A, then the
- identifiers A.x, A.B.y and C.z are qualified as follows.
- </para>
- <para>
- <itemizedlist>
- <listitem>
- <simpara>none: x, y, z</simpara>
- </listitem>
- <listitem>
- <simpara>full: A.x, A.B.y, C.z</simpara>
- </listitem>
- <listitem>
- <simpara>local: x, A.B.y, C.z</simpara>
- </listitem>
- <listitem>
- <simpara>relative: x, B.y, C.z</simpara>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary><option>-?</option></primary></indexterm>
- <option>-?</option>
- </term>
- <term>
- <indexterm><primary><option>--help</option></primary></indexterm>
- <option>--help</option>
- </term>
- <listitem>
- <para>Display help and exit.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary><option>-V</option></primary></indexterm>
- <option>-V</option>
- </term>
- <term>
- <indexterm><primary><option>--version</option></primary></indexterm>
- <option>--version</option>
- </term>
- <listitem>
- <para>Output version information and exit.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary><option>-v</option></primary></indexterm>
- <option>-v</option>
- </term>
- <term>
- <indexterm><primary><option>--verbose</option></primary></indexterm>
- <option>--verbose</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>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary><option>--use-contents</option></primary></indexterm>
- <option>--use-contents=<replaceable>URL</replaceable></option>
- </term>
- <term>
- <indexterm><primary><option>--use-index</option></primary></indexterm>
- <option>--use-index=<replaceable>URL</replaceable></option>
- </term>
- <listitem>
- <para>When generating HTML, do not generate an index.
- Instead, redirect the Contents and/or Index link on each page to
- <replaceable>URL</replaceable>. This option is intended for
- use in conjunction with <option>--gen-contents</option> and/or
- <option>--gen-index</option> for
- generating a separate contents and/or index covering multiple
- libraries.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary><option>--gen-contents</option></primary></indexterm>
- <option>--gen-contents</option>
- </term>
- <term>
- <indexterm><primary><option>--gen-index</option></primary></indexterm>
- <option>--gen-index</option>
- </term>
- <listitem>
- <para>Generate an HTML contents and/or index containing entries pulled
- from all the specified interfaces (interfaces are specified using
- <option>-i</option> or <option>--read-interface</option>).
- This is used to generate a single contents and/or index for multiple
- sets of Haddock documentation.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary><option>--ignore-all-exports</option></primary>
- </indexterm>
- <option>--ignore-all-exports</option>
- </term>
- <listitem>
- <para>Causes Haddock to behave as if every module has the
- <literal>ignore-exports</literal> attribute (<xref
- linkend="module-attributes" />). This might be useful for
- generating implementation documentation rather than interface
- documentation, for example.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary><option>--hide</option></primary>
- </indexterm>
- <option>--hide</option> <replaceable>module</replaceable>
- </term>
- <listitem>
- <para>Causes Haddock to behave as if module
- <replaceable>module</replaceable> has the <literal>hide</literal>
- attribute. (<xref linkend="module-attributes" />).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary><option>--show-extensions</option></primary>
- </indexterm>
- <option>--show-extensions</option> <replaceable>module</replaceable>
- </term>
- <listitem>
- <para>Causes Haddock to behave as if module
- <replaceable>module</replaceable> has the <literal>show-extensions</literal>
- attribute. (<xref linkend="module-attributes" />).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary><option>--optghc</option></primary></indexterm>
- <option>--optghc</option>=<replaceable>option</replaceable>
- </term>
- <listitem>
- <para>Pass <replaceable>option</replaceable> to GHC. Note that there is a double dash there, unlike for GHC.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary><option>-w</option></primary></indexterm>
- <option>-w</option>
- </term>
- <term>
- <indexterm><primary><option>--no-warnings</option></primary></indexterm>
- <option>--no-warnings</option>
- </term>
- <listitem>
- <para>Turn off all warnings.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary><option>--compatible-interface-versions</option></primary></indexterm>
- <option>--compatible-interface-versions</option>
- </term>
- <listitem>
- <para>
- Prints out space-separated versions of binary Haddock interface files that this version is compatible
- with.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary><option>--no-tmp-comp-dir</option></primary></indexterm>
- <option>--no-tmp-comp-dir</option>
- </term>
- <listitem>
- <para>
- Do not use a temporary directory for reading and writing compilation output files
- (<literal>.o</literal>, <literal>.hi</literal>, and stub files). Instead, use the
- present directory or another directory that you have explicitly told GHC to use
- via the <literal>--optghc</literal> flag.
- </para>
- <para>
- This flag can be used to avoid recompilation if compilation files already exist.
- Compilation files are produced when Haddock has to process modules that make use of
- Template Haskell, in which case Haddock compiles the modules using the GHC API.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary><option>--print-missing-docs</option></primary></indexterm>
- <option>--print-missing-docs</option>
- </term>
- <listitem>
- <para>
- Print extra information about any undocumented entities.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <section id="cpp">
- <title>Using literate or pre-processed source</title>
-
- <para>Since Haddock uses GHC internally, both plain and
- literate Haskell sources are accepted without the need for the user
- to do anything. To use the C pre-processor, however,
- the user must pass the the <option>-cpp</option> option to GHC
- using <option>--optghc</option>.
- </para>
- </section>
-
- </chapter>
-
- <chapter id="markup">
- <title>Documentation and Markup</title>
-
- <para>Haddock understands special documentation annotations in the
- Haskell source file and propagates these into the generated
- documentation. The annotations are purely optional: if there are
- no annotations, Haddock will just generate documentation that
- contains the type signatures, data type declarations, and class
- declarations exported by each of the modules being
- processed.</para>
-
- <section>
- <title>Documenting a top-level declaration</title>
-
- <para>The simplest example of a documentation annotation is for
- documenting any top-level declaration (function type signature,
- type declaration, or class declaration). For example, if the
- source file contains the following type signature:</para>
-
-<programlisting>
-square :: Int -> Int
-square x = x * x
-</programlisting>
-
- <para>Then we can document it like this:</para>
-
-<programlisting>
--- |The 'square' function squares an integer.
-square :: Int -> Int
-square x = x * x
-</programlisting>
-
-
- <para>The <quote><literal>-- |</literal></quote> syntax begins a
- documentation annotation, which applies to the
- <emphasis>following</emphasis> declaration in the source file.
- Note that the annotation is just a comment in Haskell — it
- will be ignored by the Haskell compiler.</para>
-
- <para>The declaration following a documentation annotation
- should be one of the following:</para>
- <itemizedlist>
- <listitem>
- <para>A type signature for a top-level function,</para>
- </listitem>
- <listitem>
- <para>A <literal>data</literal> declaration,</para>
- </listitem>
- <listitem>
- <para>A <literal>newtype</literal> declaration,</para>
- </listitem>
- <listitem>
- <para>A <literal>type</literal> declaration</para>
- </listitem>
- <listitem>
- <para>A <literal>class</literal> declaration,</para>
- </listitem>
- <listitem>
- <para>A <literal>data family</literal> or
- <literal>type family</literal> declaration, or</para>
- </listitem>
- <listitem>
- <para>A <literal>data instance</literal> or
- <literal>type instance</literal> declaration.</para>
- </listitem>
- </itemizedlist>
-
- <para>If the annotation is followed by a different kind of
- declaration, it will probably be ignored by Haddock.</para>
-
- <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.
-square x = x * x
-</programlisting>
-
- <para>Note that Haddock doesn't contain a Haskell type system
- — 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>
-
-<programlisting>
--- |The 'square' function squares an integer.
--- It takes one argument, of type 'Int'.
-square :: Int -> Int
-square x = x * x
-</programlisting>
-
- <para>You can also use Haskell's nested-comment style for
- documentation annotations, which is sometimes more convenient
- when using multi-line comments:</para>
-
-<programlisting>
-{-|
- The 'square' function squares an integer.
- It takes one argument, of type 'Int'.
--}
-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>-- |</literal></quote> or
- <quote><literal>-- ^</literal></quote>
- annotations:</para>
-
-<programlisting>
-class C a where
- -- | This is the documentation for the 'f' method
- f :: a -> Int
- -- | This is the documentation for the 'g' method
- g :: Int -> a
-</programlisting>
- </section>
-
- <section>
- <title>Constructors and record fields</title>
-
- <para>Constructors are documented like so:</para>
-
-<programlisting>
-data T a b
- -- | This is the documentation for the 'C1' constructor
- = C1 a b
- -- | This is the documentation for the 'C2' constructor
- | C2 a b
-</programlisting>
-
- <para>or like this:</para>
-
-<programlisting>
-data T a b
- = C1 a b -- ^ This is the documentation for the 'C1' constructor
- | C2 a b -- ^ This is the documentation for the 'C2' constructor
-</programlisting>
-
- <para>Record fields are documented using one of these
- styles:</para>
-
-<programlisting>
-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 =
- C { a :: a -- ^ This is the documentation for the 'a' field
- , b :: b -- ^ This is the documentation for the 'b' field
- }
-</programlisting>
-
- <para>Alternative layout styles are generally accepted by
- Haddock - for example doc comments can appear before or after
- the comma in separated lists such as the list of record fields
- above.</para>
-
- <para>In case that more than one constructor exports a field
- with the same name, the documentation attached to the first
- occurence of the field will be used, even if a comment is not
- present.
- </para>
-
-<programlisting>
-data T a = A { someField :: a -- ^ Doc for someField of A
- }
- | B { someField :: a -- ^ Doc for someField of B
- }
-</programlisting>
-
- <para>In the above example, all occurences of
- <literal>someField</literal> in the documentation are going to
- be documented with <literal>Doc for someField of A</literal>.
- Note that Haddock versions 2.14.0 and before would join up
- documentation of each field and render the result. The reason
- for this seemingly weird behaviour is the fact that
- <literal>someField</literal> is actually the same (partial)
- function.</para>
-
- </section>
-
- <section>
- <title>Function arguments</title>
-
- <para>Individual arguments to a function may be documented
- like this:</para>
-
-<programlisting>
-f :: Int -- ^ The 'Int' argument
- -> Float -- ^ The 'Float' argument
- -> IO () -- ^ The return value
-</programlisting>
- </section>
- </section>
-
- <section>
- <title>The module description</title>
-
- <para>A module itself may be documented with multiple fields
- that can then be displayed by the backend. In particular, the
- HTML backend displays all the fields it currently knows
- about. We first show the most complete module documentation
- example and then talk about the fields.</para>
-
-<programlisting>
-{-|
-Module : W
-Description : Short description
-Copyright : (c) Some Guy, 2013
- Someone Else, 2014
-License : GPL-3
-Maintainer : sample@email.com
-Stability : experimental
-Portability : POSIX
-
-Here is a longer description of this module, containing some
-commentary with @some markup@.
--}
-module W where
-...
-</programlisting>
-
- <para>The <quote>Module</quote> field should be clear. It
- currently doesn't affect the output of any of the backends but
- you might want to include it for human information or for any
- other tools that might be parsing these comments without the
- help of GHC.</para>
-
- <para>The <quote>Description</quote> field accepts some short text
- which outlines the general purpose of the module. If you're
- generating HTML, it will show up next to the module link in
- the module index.</para>
-
- <para>The <quote>Copyright</quote>, <quote>License</quote>,
- <quote>Maintainer</quote> and <quote>Stability</quote> fields
- should be obvious. An alternative spelling for the
- <quote>License</quote> field is accepted as
- <quote>Licence</quote> but the output will always prefer
- <quote>License</quote>.</para>
-
- <para>The <quote>Portability</quote> field has seen varied use
- by different library authors. Some people put down things like
- operating system constraints there while others put down which GHC
- extensions are used in the module. Note that you might want to
- consider using the <quote>show-extensions</quote> module flag for the
- latter.</para>
-
- <para>Finally, a module may contain a documentation comment
- before the module header, in which case this comment is
- interpreted by Haddock as an overall description of the module
- itself, and placed in a section entitled
- <quote>Description</quote> in the documentation for the module.
- All usual Haddock markup is valid in this comment.</para>
-
- <para>All fields are optional but they must be in order if they
- do appear. Multi-line fields are accepted but the consecutive
- lines have to start indented more than their label. If your
- label is indented one space as is often the case with
- <quote>--</quote> syntax, the consecutive lines have to start at
- two spaces at the very least. Please note that we do not enforce
- the format for any of the fields and the established formats are
- just a convention.</para>
-
- </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
- exported by that module, even if they were re-exported by
- another module. The only exception is when Haddock can't see
- the declaration for the re-exported entity, perhaps because it
- isn't part of the batch of modules currently being
- processed.</para>
-
- <para>However, to Haddock the export list has even more
- significance than just specifying the entities to be included in
- the documentation. It also specifies the
- <emphasis>order</emphasis> that entities will be listed in the
- generated documentation. This leaves the programmer free to
- implement functions in any order he/she pleases, and indeed in
- any <emphasis>module</emphasis> he/she pleases, but still
- specify the order that the functions should be documented in the
- export list. Indeed, many programmers already do this: the
- export list is often used as a kind of ad-hoc interface
- documentation, with headings, groups of functions, type
- signatures and declarations in comments.</para>
-
- <para>You can insert headings and sub-headings in the
- documentation by including annotations at the appropriate point
- in the export list. For example:</para>
-
-<programlisting>
-module Foo (
- -- * Classes
- C(..),
- -- * Types
- -- ** A data type
- T,
- -- ** A record
- R,
- -- * Some functions
- f, g
- ) where
-</programlisting>
-
- <para>Headings are introduced with the syntax
- <quote><literal>-- *</literal></quote>,
- <quote><literal>-- **</literal></quote> and so on, where
- the number of <literal>*</literal>s indicates the level of the
- heading (section, sub-section, sub-sub-section, etc.).</para>
-
- <para>If you use section headings, then Haddock will generate a
- table of contents at the top of the module documentation for
- you.</para>
-
- <para>The alternative style of placing the commas at the
- beginning of each line is also supported. eg.:</para>
-
-<programlisting>
-module Foo (
- -- * Classes
- , C(..)
- -- * Types
- -- ** A data type
- , T
- -- ** A record
- , R
- -- * Some functions
- , f
- , g
- ) where
-</programlisting>
-
- <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
- list:</para>
-
-<programlisting>
-module A (
- module B,
- module C
- ) where
-</programlisting>
-
- <para>What will the Haddock-generated documentation for this
- module look like? Well, it depends on how the modules
- <literal>B</literal> and <literal>C</literal> are imported.
- If they are imported wholly and without any
- <literal>hiding</literal> qualifiers, then the documentation
- will just contain a cross-reference to the documentation for
- <literal>B</literal> and <literal>C</literal>. However, if
- the modules are not <emphasis>completely</emphasis>
- re-exported, for example:</para>
-
-<programlisting>
-module A (
- module B,
- module C
- ) where
-
-import B hiding (f)
-import C (a, b)
-</programlisting>
-
- <para>then Haddock behaves as if the set of entities
- re-exported from <literal>B</literal> and <literal>C</literal>
- had been listed explicitly in the export
- list<footnote><para>NOTE: this is not fully implemented at the
- time of writing (version 0.2). At the moment, Haddock always
- inserts a cross-reference.</para>
- </footnote>.</para>
-
- <para>The exception to this rule is when the re-exported
- module is declared with the <literal>hide</literal> attribute
- (<xref linkend="module-attributes"/>), in which case the module
- 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>
-
-<programlisting>module Foo where</programlisting>
-
- <para>this is equivalent to an export list which mentions
- every entity defined at the top level in this module, and
- Haddock treats it in the same way. Furthermore, the generated
- documentation will retain the order in which entities are
- defined in the module. In this special case the module body
- may also include section headings (normally they would be
- ignored by Haddock).</para>
-
-<programlisting>
-module Foo where
-
--- * This heading will now appear before foo.
-
--- | Documentation for 'foo'.
-foo :: Integer
-foo = 5
-</programlisting>
-
- </section>
- </section>
-
- <section>
- <title>Named chunks of documentation</title>
-
- <para>Occasionally it is desirable to include a chunk of
- documentation which is not attached to any particular Haskell
- declaration. There are two ways to do this:</para>
-
- <itemizedlist>
- <listitem>
- <para>The documentation can be included in the export list
- directly, e.g.:</para>
-
-<programlisting>
-module Foo (
- -- * A section heading
-
- -- | Some documentation not attached to a particular Haskell entity
- ...
- ) 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
- structure, then it can be given a name and placed out of
- line in the body of the module. This is achieved with a
- special form of documentation annotation
- <quote><literal>-- $</literal></quote>:</para>
-
-<programlisting>
-module Foo (
- -- * A section heading
-
- -- $doc
- ...
- ) where
-
--- $doc
--- Here is a large chunk of documentation which may be referred to by
--- the name $doc.
-</programlisting>
-
- <para>The documentation chunk is given a name, which is the
- sequence of alphanumeric characters directly after the
- <quote><literal>-- $</literal></quote>, and it may be
- referred to by the same name in the export list.</para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section id="hyperlinking">
- <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
- given type constructor or class there may be several modules
- re-exporting it, and therefore several modules whose
- documentation contains the definition of that type or class
- (possibly including the current module!) so which one do we link
- to?</para>
-
- <para>Let's look at an example. Suppose we have three modules
- <literal>A</literal>, <literal>B</literal> and
- <literal>C</literal> defined as follows:</para>
-
-<programlisting>
-module A (T) where
-data T a = C a
-
-module B (f) where
-import A
-f :: T Int -> Int
-f (C i) = i
-
-module C (T, f) where
-import A
-import B
-</programlisting>
-
- <para>Module <literal>A</literal> exports a datatype
- <literal>T</literal>. Module <literal>B</literal> imports
- <literal>A</literal> and exports a function <literal>f</literal>
- whose type refers to <literal>T</literal>. Also, both
- <literal>T</literal> and <literal>f</literal> are re-exported from
- module C.</para>
-
- <para>Haddock takes the view that each entity has a
- <emphasis>home</emphasis> module; that is, the module that the library
- designer would most like to direct the user to, to find the
- documentation for that entity. So, Haddock makes all links to an entity
- point to the home module. The one exception is when the entity is also
- exported by the current module: Haddock makes a local link if it
- can.</para>
-
- <para>How is the home module for an entity determined?
- Haddock uses the following rules:</para>
-
- <itemizedlist>
- <listitem>
- <para>If modules A and B both export the entity, and module A imports
- (directly or indirectly) module B, then B is preferred.</para>
- </listitem>
- <listitem>
- <para>A module with the <literal>hide</literal> attribute is never
- chosen as the home.</para>
- </listitem>
- <listitem>
- <para>A module with the <literal>not-home</literal> attribute is only
- chosen if there are no other modules to choose.</para>
- </listitem>
- </itemizedlist>
-
- <para>If multiple modules fit the criteria, then one is chosen at
- random. If no modules fit the criteria (because the candidates are all
- hidden), then Haddock will issue a warning for each reference to an
- entity without a home.</para>
-
- <para>In the example above, module <literal>A</literal> is chosen as the
- home for <literal>T</literal> because it does not import any other
- module that exports <literal>T</literal>. The link from
- <literal>f</literal>'s
- type in module <literal>B</literal> will therefore point to
- <literal>A.T</literal>. However, <literal>C</literal> also exports
- <literal>T</literal> and <literal>f</literal>, and the link from
- <literal>f</literal>'s type in <literal>C</literal> will therefore
- point locally to <literal>C.T</literal>.</para>
- </section>
-
- <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 an
- <literal>{-# OPTIONS_HADDOCK ... #-}</literal> pragma at the
- top of the module, either before or after the module
- description. For example:</para>
-
-<programlisting>
-{-# OPTIONS_HADDOCK hide, prune, ignore-exports #-}
-
--- |Module description
-module A where
-...
-</programlisting>
-
- <para>The options and module description can be in either order.</para>
-
- <para>The following attributes are currently understood by
- Haddock:</para>
-
- <variablelist>
- <varlistentry>
- <term>
- <indexterm><primary><literal>hide</literal></primary></indexterm>
- <literal>hide</literal>
- </term>
- <listitem>
- <para>Omit this module from the generated documentation,
- but nevertheless propagate definitions and documentation
- from within this module to modules that re-export those
- definitions.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary><literal>hide</literal></primary></indexterm>
- <literal>prune</literal>
- </term>
- <listitem>
- <para>Omit definitions that have no documentation
- annotations from the generated documentation.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary><literal>ignore-exports</literal></primary></indexterm>
- <literal>ignore-exports</literal>
- </term>
- <listitem>
- <para>Ignore the export list. Generate documentation as
- if the module had no export list - i.e. all the top-level
- declarations are exported, and section headings may be
- given in the body of the module.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary><literal>not-home</literal></primary></indexterm>
- <literal>not-home</literal>
- </term>
- <listitem>
- <para>Indicates that the current module should not be considered to
- be the home module for each entity it exports,
- unless that entity is not exported from any other module. See
- <xref linkend="hyperlinking" /> for more details.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <indexterm><primary><literal>show-extensions</literal></primary></indexterm>
- <literal>show-extensions</literal>
- </term>
- <listitem>
- <para>Indicates that we should render the extensions used in this module in the
- resulting documentation. This will only render if the output format supports it.
- If Language is set, it will be shown as well and all the extensions implied by it won't.
- All enabled extensions will be rendered, including those implied by their more powerful versions.</para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- </section>
-
- <section>
- <title>Markup</title>
-
- <para>Haddock understands certain textual cues inside
- documentation annotations that tell it how to render the
- documentation. The cues (or <quote>markup</quote>) have been
- designed to be simple and mnemonic in ASCII so that the
- programmer doesn't have to deal with heavyweight annotations
- when editing documentation comments.</para>
-
- <section>
- <title>Paragraphs</title>
-
- <para>One or more blank lines separates two paragraphs in a
- documentation comment.</para>
- </section>
-
- <section>
- <title>Special characters</title>
-
- <para>The following characters have special meanings in
- documentation comments: <literal>\</literal>, <literal>/</literal>,
- <literal>'</literal>, <literal>`</literal>,
- <literal>"</literal>, <literal>@</literal>,
- <literal><</literal>. To insert a literal occurrence of
- one of these special characters, precede it with a backslash
- (<literal>\</literal>).</para>
-
- <para>Additionally, the character <literal>></literal> has
- a special meaning at the beginning of a line, and the
- following characters have special meanings at the beginning of
- a paragraph:
- <literal>*</literal>, <literal>-</literal>. These characters
- can also be escaped using <literal>\</literal>.</para>
-
- <para>Furthermore, the character sequence <literal>>>></literal>
- has a special meaning at the beginning of a line. To
- escape it, just prefix the characters in the sequence with a
- backslash.</para>
- </section>
-
- <section>
- <title>Character references</title>
-
- <para>Although Haskell source files may contain any character
- from the Unicode character set, the encoding of these characters
- as bytes varies between systems, so that only source files
- restricted to the ASCII character set are portable. Other
- characters may be specified in character and string literals
- using Haskell character escapes. To represent such characters
- in documentation comments, Haddock supports SGML-style numeric
- character references of the forms
- <literal>&#</literal><replaceable>D</replaceable><literal>;</literal>
- and
- <literal>&#x</literal><replaceable>H</replaceable><literal>;</literal>
- where <replaceable>D</replaceable> and <replaceable>H</replaceable>
- are decimal and hexadecimal numbers denoting a code position
- in Unicode (or ISO 10646). For example, the references
- <literal>&#x3BB;</literal>, <literal>&#x3bb;</literal>
- and <literal>&#955;</literal> all represent the lower-case
- letter lambda.</para>
- </section>
-
- <section>
- <title>Code Blocks</title>
-
- <para>Displayed blocks of code are indicated by surrounding a
- paragraph with <literal>@...@</literal> or by preceding each
- line of a paragraph with <literal>></literal> (we often
- call these “bird tracks”). For
- example:</para>
-
-<programlisting>
--- | This documentation includes two blocks of code:
---
--- @
--- f x = x + x
--- @
---
--- > g x = x * 42
-</programlisting>
-
- <para>There is an important difference between the two forms
- of code block: in the bird-track form, the text to the right
- of the ‘<literal>></literal>’ is interpreted
- literally, whereas the <literal>@...@</literal> form
- interprets markup as normal inside the code block.</para>
- </section>
-
- <section>
- <title>Examples</title>
-
- <para> Haddock has markup support for examples of interaction with a
- <emphasis>read-eval-print loop (REPL)</emphasis>. An
- example is introduced with
- <literal>>>></literal> followed by an expression followed
- by zero or more result lines:</para>
-
-<programlisting>
--- | Two examples are given below:
---
--- >>> fib 10
--- 55
---
--- >>> putStrLn "foo\nbar"
--- foo
--- bar
-</programlisting>
- <para>Result lines that only contain the string
- <literal><BLANKLINE></literal> are rendered as blank lines in the
- generated documentation.</para>
- </section>
-
- <section>
- <title>Properties</title>
- <para>
- Haddock provides markup for properties:
-<programlisting>
--- | Addition is commutative:
---
--- prop> a + b = b + a
-</programlisting>
- This allows third-party applications to extract and verify them.
- </para>
- </section>
-
- <section>
- <title>Hyperlinked Identifiers</title>
-
- <para>Referring to a Haskell identifier, whether it be a type,
- class, constructor, or function, is done by surrounding it
- with single quotes:</para>
-
-<programlisting>
--- | This module defines the type 'T'.
-</programlisting>
-
- <para>If there is an entity <literal>T</literal> in scope in
- the current module, then the documentation will hyperlink the
- reference in the text to the definition of
- <literal>T</literal> (if the output format supports
- hyperlinking, of course; in a printed format it might instead
- insert a page reference to the definition).</para>
-
- <para>It is also possible to refer to entities that are not in
- scope in the current module, by giving the full qualified name
- of the entity:</para>
-
-<programlisting>
--- | The identifier 'M.T' is not in scope
-</programlisting>
-
- <para>If <literal>M.T</literal> is not otherwise in scope,
- then Haddock will simply emit a link pointing to the entity
- <literal>T</literal> exported from module <literal>M</literal>
- (without checking to see whether either <literal>M</literal>
- or <literal>M.T</literal> exist).</para>
-
- <para>To make life easier for documentation writers, a quoted
- identifier is only interpreted as such if the quotes surround
- a lexically valid Haskell identifier. This means, for
- example, that it normally isn't necessary to escape the single
- quote when used as an apostrophe:</para>
-
-<programlisting>
--- | I don't have to escape my apostrophes; great, isn't it?
-</programlisting>
-
- <para>Nothing special is needed to hyperlink identifiers which
- contain apostrophes themselves: to hyperlink
- <literal>foo'</literal> one would simply type
- <literal>'foo''</literal>. To hyperlink identifiers written in
- infix form, simply put them in quotes as always:
- <literal>'`elem`'</literal>.</para>
-
- <para>For compatibility with other systems, the following
- alternative form of markup is accepted<footnote><para>
- We chose not to use this as the primary markup for
- identifiers because strictly speaking the <literal>`</literal>
- character should not be used as a left quote, it is a grave accent.</para>
- </footnote>: <literal>`T'</literal>.</para>
- </section>
-
- <section>
- <title>Emphasis, Bold and Monospaced text</title>
-
- <para>Emphasis may be added by surrounding text with
- <literal>/.../</literal>. Other markup is valid inside emphasis. To have a forward
- slash inside of emphasis, just escape it: <literal>/fo\/o/</literal></para>
-
- <para>Bold (strong) text is indicated by surrounding it with <literal>__...__</literal>.
- Other markup is valid inside bold. For example, <literal>__/foo/__</literal> will make the emphasised
- text <literal>foo</literal> bold. You don't have to escape a single underscore if you need it bold:
- <literal>__This_text_with_underscores_is_bold__</literal>.
- </para>
-
- <para>Monospaced (or typewriter) text is indicated by
- surrounding it with <literal>@...@</literal>. Other markup is
- valid inside a monospaced span: for example
- <literal>@'f' a b@</literal> will hyperlink the
- identifier <literal>f</literal> inside the code fragment.</para>
- </section>
-
- <section>
- <title>Linking to modules</title>
-
- <para>Linking to a module is done by surrounding the module
- name with double quotes:</para>
-
-<programlisting>
--- | This is a reference to the "Foo" module.
-</programlisting>
-
- <para>A basic check is done on the syntax of the header name to ensure that it is valid
- before turning it into a link but unlike with identifiers, whether the module is in scope isn't checked
- and will always be turned into a link.
- </para>
-
- </section>
-
- <section>
- <title>Itemized and Enumerated lists</title>
-
- <para>A bulleted item is represented by preceding a paragraph
- with either <quote><literal>*</literal></quote> or
- <quote><literal>-</literal></quote>. A sequence of bulleted
- paragraphs is rendered as an itemized list in the generated
- documentation, eg.:</para>
-
-<programlisting>
--- | This is a bulleted list:
---
--- * first item
---
--- * second item
-</programlisting>
-
- <para>An enumerated list is similar, except each paragraph
- must be preceded by either
- <quote><literal>(<replaceable>n</replaceable>)</literal></quote>
- or
- <quote><literal><replaceable>n</replaceable>.</literal></quote>
- where <replaceable>n</replaceable> is any integer. e.g.</para>
-
-<programlisting>
--- | This is an enumerated list:
---
--- (1) first item
---
--- 2. second item
-</programlisting>
-
- <para>Lists of the same type don't have to be separated by a newline:</para>
-<programlisting>
--- | This is an enumerated list:
---
--- (1) first item
--- 2. second item
---
--- This is a bulleted list:
---
--- * first item
--- * second item
-</programlisting>
-
- <para>You can have more than one line of content in a list element:
- </para>
-<programlisting>
--- |
--- * first item
--- and more content for the first item
--- * second item
--- and more content for the second item
-</programlisting>
-
- <para>You can even nest whole paragraphs inside of list elements. The rules
- are 4 spaces for each indentation level. You're required to use a newline before
- such nested paragraph:
- </para>
-<programlisting>
-{-|
-* Beginning of list
-This belongs to the list above!
-
- > nested
- > bird
- > tracks
-
- * Next list
- More of the indented list.
-
- * Deeper
-
- @
- even code blocks work
- @
-
- * Deeper
-
- 1. Even deeper!
- 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>
- <title>Definition lists</title>
-
- <para>Definition lists are written as follows:</para>
-
-<programlisting>
--- | This is a definition list:
---
--- [@foo@]: The description of @foo@.
---
--- [@bar@]: The description of @bar@.
-</programlisting>
-
- <para>To produce output something like this:</para>
-
- <variablelist>
- <varlistentry>
- <term><literal>foo</literal></term>
- <listitem>
- <para>The description of <literal>foo</literal>.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>bar</literal></term>
- <listitem>
- <para>The description of <literal>bar</literal>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>Each paragraph should be preceded by the
- “definition term” enclosed in square brackets and followed by a colon.
- Other markup operators may be used freely within the
- definition term. You can escape <literal>]</literal> with a backslash as usual.</para>
-
- <para>Same rules about nesting and no newline separation as for bulleted and numbered lists apply.
- </para>
-
- </section>
-
- <section>
- <title>URLs</title>
-
- <para>
- A URL can be included in a documentation comment by surrounding it in
- angle brackets, for example:
- </para>
-
-<programlisting>
-<http://example.com>
-</programlisting>
-
- <para>
- If the output format supports it, the URL will be turned into a
- hyperlink when rendered.
- </para>
-
- <para>If Haddock sees something that looks like a URL (such as something starting with
- <literal>http://</literal> or <literal>ssh://</literal>) where the URL markup is valid,
- it will automatically make it a hyperlink.</para>
- </section>
-
- <section>
- <title>Links</title>
-
- <para>
- Haddock supports Markdown syntax for inline links. A link consists
- of a link text and a URL. The link text is enclosed in square
- brackets and followed by the URL enclosed in regular parentheses, for
- example:
- </para>
-
-<programlisting>
-[some link](http://example.com)
-</programlisting>
- <para>
- The link text is used as a descriptive text for the URL, if the
- output format supports it.
- </para>
- </section>
-
- <section>
- <title>Images</title>
- <para>
- Haddock supports Markdown syntax for inline images. This resembles
- the syntax for links, but starts with an exclamation mark. An
- example looks like this:
- </para>
-
-<programlisting>
-
-</programlisting>
- <para>
- If the output format supports it, the image will be rendered inside
- the documentation. The image description is used as relpacement text
- and/or image title.
- </para>
- </section>
-
- <section>
- <title>Anchors</title>
-
- <para>Sometimes it is useful to be able to link to a point in
- the documentation which doesn't correspond to a particular
- entity. For that purpose, we allow <emphasis>anchors</emphasis> to be
- included in a documentation comment. The syntax is
- <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
- containing the anchor, and <replaceable>label</replaceable> is
- the anchor label. The module does not have to be local, it can
- be imported via an interface. Please note that in Haddock
- versions 2.13.x and earlier, the syntax was
- <literal>"<replaceable>module</replaceable>\#<replaceable>label</replaceable>"</literal>.
- It is considered deprecated and will be removed in the future.</para>
- </section>
-
- <section>
- <title>Headings</title>
- <para>Headings inside of comment documentation are possible be preceding them with
- a number of <literal>=</literal>s. From 1 to 6 are accepted. Extra <literal>=</literal>s will
- be treated as belonging to the text of the heading. Note that it's up to the output format to decide
- how to render the different levels.
- </para>
-
-<programlisting>
--- |
--- = Heading level 1 with some /emphasis/
--- Something underneath the heading.
---
--- == /Subheading/
--- More content.
---
--- === Subsubheading
--- Even more content.
-</programlisting>
-
- <para>Note that while headings have to start on a new paragraph, we allow paragraph-level content to
- follow these immediately.
- </para>
-
-<programlisting>
--- |
--- = Heading level 1 with some __bold__
--- Something underneath the heading.
---
--- == /Subheading/
--- More content.
---
--- === Subsubheading
--- >>> examples are only allowed at the start of paragraphs
-</programlisting>
-
- <para>As of 2.15.1, there's experimental (read: subject to
- change or get removed) support for collapsible headers: simply
- wrap your existing header title in underscores, as per bold
- syntax. The collapsible section will stretch until the end of
- the comment or until a header of equal or smaller number of
- <literal>=</literal>s.</para>
-
-<programlisting>
--- |
--- === __Examples:__
--- >>> Some very long list of examples
---
--- ==== This still falls under the collapse
--- Some specialised examples
---
--- === This is does not go into the collapsable section.
--- More content.
-</programlisting>
-
- </section>
-
- <section>
- <title>Metadata</title>
- <para>Since Haddock 2.16.0, some support for embedding
- metadata in the comments has started to appear. The use of
- such data aims to standardise various community conventions in
- how such information is conveyed and to provide uniform
- rendering.
- </para>
-
- <section>
- <title>Since</title>
- <para><literal>@since</literal> annotation can be used to
- convey information about when the function was introduced or
- when it has changed in the way significant to the user.
- <literal>@since</literal> is a paragraph-level element.
- While multiple such annotations are not an error, only the
- one to appear in the comment last will be used.
- <literal>@since</literal> has to be followed with a version
- number, no further description is currently allowed. The
- meaning of this feature is subject to change in the future
- per user feedback.
- </para>
-
-<programlisting>
--- |
--- Some comment
---
--- @since 1.2.3
-</programlisting>
-
- </section>
-
- </section>
-
- </section>
- </chapter>
- <index/>
-</book>
diff --git a/doc/index.rst b/doc/index.rst
new file mode 100644
index 00000000..dc30c45f
--- /dev/null
+++ b/doc/index.rst
@@ -0,0 +1,21 @@
+Welcome to Haddock's documentation!
+===================================
+
+This is Haddock, a tool for automatically generating documentation from
+annotated Haskell source code.
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ intro
+ invoking
+ markup
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`
diff --git a/doc/intro.rst b/doc/intro.rst
new file mode 100644
index 00000000..fcdc67f1
--- /dev/null
+++ b/doc/intro.rst
@@ -0,0 +1,164 @@
+Introduction
+============
+
+This is Haddock, a tool for automatically generating documentation from
+annotated Haskell source code. Haddock was designed with several goals
+in mind:
+
+- 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.
+
+- There is a 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.
+
+- Documentation annotations in the source code should be easy on the
+ eye when editing the source code itself, so as not to obscure the
+ code and to make reading and writing documentation annotations easy.
+ The easier it is to write documentation, the more likely the
+ programmer is to do it. Haddock therefore uses lightweight markup in
+ its annotations, taking several ideas from
+ `IDoc <http://www.cse.unsw.edu.au/~chak/haskell/idoc/>`__. In fact,
+ Haddock can understand IDoc-annotated source code.
+
+- 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.
+
+ Haddock therefore understands the Haskell module system and can
+ generate documentation which hides not only non-exported entities
+ from the interface, but also 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.
+
+- 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.
+
+- We might want documentation in multiple formats - online and printed,
+ for example. Haddock comes with HTML, LaTeX, and Hoogle backends, and
+ it is structured in such a way that adding new backends is
+ straightforward.
+
+Obtaining Haddock
+-----------------
+
+Distributions (source & binary) of Haddock can be obtained from its `web
+site <http://www.haskell.org/haddock/>`__.
+
+Up-to-date sources can also be obtained from our public darcs
+repository. The Haddock sources are at
+``http://code.haskell.org/haddock``. See
+`darcs.net <http://www.darcs.net/>`__ for more information on the darcs
+version control utility.
+
+License
+-------
+
+The following license covers this documentation, and the Haddock source
+code, except where otherwise indicated.
+
+ Copyright 2002-2010, Simon Marlow. All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ - Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+
+ - 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.
+
+ 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.
+
+Contributors
+------------
+
+Haddock was originally written by Simon Marlow. Since it is an open
+source project, many people have contributed to its development over the
+years. Below is a list of contributors in alphabetical order that we
+hope is somewhat complete. If you think you are missing from this list,
+please contact us.
+
+- Ashley Yakeley
+- Benjamin Franksen
+- Brett Letner
+- Clemens Fruhwirth
+- Conal Elliott
+- David Waern
+- Duncan Coutts
+- George Pollard
+- George Russel
+- Hal Daume
+- Ian Lynagh
+- Isaac Dupree
+- Joachim Breitner
+- Krasimir Angelov
+- Lennart Augustsson
+- Luke Plant
+- Malcolm Wallace
+- Manuel Chakravarty
+- Mark Lentczner
+- Mark Shields
+- Mateusz Kowalczyk
+- Mike Thomas
+- Neil Mitchell
+- Oliver Brown
+- Roman Cheplyaka
+- Ross Paterson
+- Sigbjorn Finne
+- Simon Hengel
+- Simon Marlow
+- Simon Peyton-Jones
+- Stefan O'Rear
+- Sven Panne
+- Thomas Schilling
+- Wolfgang Jeltsch
+- Yitzchak Gale
+
+Acknowledgements
+----------------
+
+Several documentation systems provided the inspiration for Haddock, most
+notably:
+
+- `IDoc <http://www.cse.unsw.edu.au/~chak/haskell/idoc/>`__
+
+- `HDoc <http://www.fmi.uni-passau.de/~groessli/hdoc/>`__
+
+- `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`__
+
+and probably several others I've forgotten.
+
+Thanks to the the members of haskelldoc@haskell.org,
+haddock@projects.haskell.org and everyone who contributed to the many
+libraries that Haddock makes use of.
diff --git a/doc/invoking.rst b/doc/invoking.rst
new file mode 100644
index 00000000..38ba7551
--- /dev/null
+++ b/doc/invoking.rst
@@ -0,0 +1,454 @@
+Invoking Haddock
+================
+
+Haddock is invoked from the command line, like so:
+
+.. code-block:: none
+
+ haddock [option ...] file ...
+
+Where each ``file`` is a filename containing a Haskell source module (.hs)
+or a Literate Haskell source module (.lhs) or just a module name.
+
+All the modules specified on the command line will be processed
+together. When one module refers to an entity in another module being
+processed, the documentation will link directly to that entity.
+
+Entities that cannot be found, for example because they are in a module
+that isn't being processed as part of the current batch, simply won't be
+hyperlinked in the generated documentation. Haddock will emit warnings
+listing all the identifiers it couldn't resolve.
+
+The modules should *not* be mutually recursive, as Haddock don't like
+swimming in circles.
+
+Note that while older version would fail on invalid markup, this is
+considered a bug in the new versions. If you ever get failed parsing
+message, please report it.
+
+You must also specify an option for the output format. Currently only
+the :option:`-h` option for HTML and the :option:`--hoogle` option for outputting
+Hoogle data are functional.
+
+The packaging tool
+`Cabal <http://www.haskell.org/ghc/docs/latest/html/Cabal/index.html>`__
+has Haddock support, and is often used instead of invoking Haddock
+directly.
+
+The following options are available:
+
+.. program:: haddock
+
+.. option:: -B <dir>
+
+ Tell GHC that that its lib directory is dir. Can be used to override
+ the default path.
+
+.. option:: -o <dir>
+ --odir=<dir>
+
+ Generate files into dir instead of the current directory.
+
+.. option:: -l <dir>
+ --lib=<dir>
+
+ Use Haddock auxiliary files (themes, javascript, etc...) in dir.
+
+.. option:: -i <file>
+ --read-interface=<file>
+ -i <docpath>,<file>
+ --read-interface=<docpath>,<file>
+ -i <docpath>,<srcpath>,<file>
+ --read-interface=<docpath>,<srcpath>,<file>
+
+ Read the interface file in file, which must have been produced by
+ running Haddock with the :option:`--dump-interface` option. The interface
+ describes a set of modules whose HTML documentation is located in
+ docpath (which may be a relative pathname). The docpath is optional,
+ and defaults to “.”. The srcpath is optional but has no default
+ value.
+
+ This option allows Haddock to produce separate sets of documentation
+ with hyperlinks between them. The docpath 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
+ docpath means that a documentation subtree can still be moved around
+ without breaking links.
+
+ Similarly to docpath, srcpath is used generate cross-package
+ hyperlinks but within sources rendered with :option:`--hyperlinked-source`
+ option.
+
+ Multiple :option:`--read-interface` options may be given.
+
+.. option:: -D <file>
+ --dump-interface=<file>
+
+ Produce an interface file [1]_ in the file file. An interface file
+ contains information Haddock needs to produce more documentation
+ that refers to the modules currently being processed - see the
+ :option:`--read-interface` option for more details. The interface file is
+ in a binary format; don't try to read it.
+
+.. [1]
+ Haddock interface files are not the same as Haskell interface files,
+ I just couldn't think of a better name.
+
+.. option:: -h
+ --html
+
+ Generate documentation in HTML format. Several files will be
+ generated into the current directory (or the specified directory if
+ the :option:`-o` option is given), including the following:
+
+ ``module.html``; ``mini_module.html``
+ An HTML page for each module, and a "mini" page for each used
+ when viewing in frames.
+
+ ``index.html``
+ The top level page of the documentation: lists the modules
+ available, using indentation to represent the hierarchy if the
+ modules are hierarchical.
+
+ ``doc-index.html``; ``doc-index-X.html``
+ The alphabetic index, possibly split into multiple pages if big
+ enough.
+
+ ``frames.html``
+ The top level document when viewing in frames.
+
+ ``some.css``; ``etc...``
+ Files needed for the themes used. Specify your themes using the
+ :option:`--theme` option.
+
+ ``haddock-util.js``
+ Some JavaScript utilities used to implement some of the dynamic
+ features like collapsible sections, and switching to frames
+ view.
+
+.. option:: --latex
+
+ Generate documentation in LaTeX format. Several files will be
+ generated into the current directory (or the specified directory if
+ the :option:`-o` option is given), including the following:
+
+ ``package.tex``
+ The top-level LaTeX source file; to format the documentation
+ into PDF you might run something like this: ::
+
+ $ pdflatex package.tex
+
+ ``haddock.sty``
+ 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.
+
+ ``module.tex``
+ The LaTeX documentation for each module.
+
+.. option:: --latex-style=<style>
+
+ This option lets you override the default style used by the LaTeX
+ generated by the :option:`--latex` option. Normally Haddock puts a
+ standard ``haddock.sty`` in the output directory, and includes the
+ command ``\usepackage{haddock}`` in the LaTeX source. If this option
+ is given, then ``haddock.sty`` is not generated, and the command is
+ instead ``\usepackage{style}``.
+
+.. option:: --hyperlinked-source
+
+ Generate hyperlinked source code (as HTML web page). All rendered
+ files will be put into ``src/`` subfolder of output directory.
+
+ Usually, this should be used in combination with :option:`--html` 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:`--source-module`, :option:`--source-entity` and
+ related options. Note that these flags are ignored once
+ :option:`--hyperlinked-source` is set.
+
+ 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:: --source-css=<style>
+
+ Use custom CSS file for sources rendered by the
+ :option:`--hyperlinked-source` option. If no custom style file is
+ provided, Haddock will use default one.
+
+.. option:: -S, --docbook
+
+ Reserved for future use (output documentation in DocBook XML
+ format).
+
+.. option:: --source-base=<url>
+ --source-module=<url>
+ --source-entity=<url>
+ --source-entity-line=<url>
+
+ Include links to the source files in the generated documentation.
+ Use the :option:`--source-base` option to add a source code link in the
+ header bar of the contents and index pages. Use the
+ :option:`--source-module` to add a source code link in the header bar of
+ each module page. Use the :option:`--source-entity` option to add a source
+ code link next to the documentation for every value and type in each
+ module. :option:`--source-entity-line` is a flag that gets used for
+ entities that need to link to an exact source location rather than a
+ name, eg. since they were defined inside a Template Haskell splice.
+
+ In each case URL is the base URL where the source files can be
+ found. For the per-module and per-entity URLs, the following
+ substitutions are made within the string URL:
+
+ - The string ``%M`` or ``%{MODULE}`` is replaced by the module
+ name. Note that for the per-entity URLs this is the name of the
+ *exporting* module.
+
+ - The string ``%F`` or ``%{FILE}`` is replaced by the original
+ source file name. Note that for the per-entity URLs this is the
+ name of the *defining* module.
+
+ - The string ``%N`` or ``%{NAME}`` is replaced by the name of the
+ exported value or type. This is only valid for the
+ :option:`--source-entity` option.
+
+ - The string ``%K`` or ``%{KIND}`` is replaced by a flag indicating
+ whether the exported name is a value ``v`` or a type
+ ``t``. This is only valid for the :option:`--source-entity` option.
+
+ - The string ``%L`` or ``%{LINE}`` is replaced by the number of the
+ line where the exported value or type is defined. This is only
+ valid for the :option:`--source-entity` option.
+
+ - The string ``%%`` is replaced by ``%``.
+
+ For example, if your sources are online under some directory, you
+ would say ``haddock --source-base=url/ --source-module=url/%F``
+
+ If you have html versions of your sources online with anchors for
+ each type and function name, you would say
+ ``haddock --source-base=url/ --source-module=url/%M.html --source-entity=url/%M.html#%N``
+
+ For the ``%{MODULE}`` substitution you may want to replace the
+ ``.`` character in the module names with some other character
+ (some web servers are known to get confused by multiple ``.``
+ characters in a file name). To replace it with a character c use
+ ``%{MODULE/./c}``.
+
+ Similarly, for the ``%{FILE}`` substitution you may want to replace
+ the ``/`` character in the file names with some other character
+ (especially for links to colourised entity source code with a shared
+ css file). To replace it with a character c use ``%{FILE///c}``/
+
+ One example of a tool that can generate syntax-highlighted HTML from
+ your source code, complete with anchors suitable for use from
+ haddock, is
+ `hscolour <http://www.cs.york.ac.uk/fp/darcs/hscolour>`__.
+
+.. option:: -s <url>
+ --source=<url>
+
+ Deprecated aliases for :option:`--source-module`
+
+.. option:: --comments-base=<url>
+ --comments-module=<url>
+ --comments-entity=<url>
+
+ documentation. This feature would typically be used in conjunction
+ with a Wiki system.
+
+ Use the :option:`--comments-base` option to add a user comments link in
+ the header bar of the contents and index pages. Use the
+ :option:`--comments-module` to add a user comments link in the header bar
+ of each module page. Use the :option:`--comments-entity` option to add a
+ comments link next to the documentation for every value and type in
+ each module.
+
+ In each case URL is the base URL where the corresponding comments
+ page can be found. For the per-module and per-entity URLs the same
+ substitutions are made as with the :option:`--source-module` and
+ :option:`--source-entity` options above.
+
+ For example, if you want to link the contents page to a wiki page,
+ and every module to subpages, you would say
+ ``haddock --comments-base=url --comments-module=url/%M``
+
+ If your Wiki system doesn't like the ``.`` character in Haskell
+ module names, you can replace it with a different character. For
+ example to replace the ``.`` characters with ``_`` use
+ ``haddock --comments-base=url --comments-module=url/%{MODULE/./_}``.
+ Similarly, you can replace the ``/`` in a file name (may be useful for
+ entity comments, but probably not).
+
+.. option:: --theme=<path>
+
+ Specify a theme to be used for HTML (:option:`--html`) documentation. If
+ given multiple times then the pages will use the first theme given
+ by default, and have alternate style sheets for the others. The
+ reader can switch between themes with browsers that support
+ alternate style sheets, or with the "Style" menu that gets added
+ when the page is loaded. If no themes are specified, then just the
+ default built-in theme ("Ocean") is used.
+
+ The path parameter can be one of:
+
+ - A *directory*: The base name of the directory becomes the name of
+ the theme. The directory must contain exactly one ``some.css``
+ file. Other files, usually image files, will be copied, along
+ with the ``some.css`` file, into the generated output directory.
+
+ - A *CSS file*: The base name of the file becomes the name of the
+ theme.
+
+ - The *name* of a built-in theme ("Ocean" or "Classic").
+
+.. option:: --built-in-themes
+
+ Includes the built-in themes ("Ocean" and "Classic"). Can be
+ combined with :option:`--theme`. Note that order matters: The first
+ specified theme will be the default.
+
+.. option:: -c <file>
+ --css=<file>
+
+ Deprecated aliases for :option:`--theme`
+
+.. option:: -p <file>
+ --prologue=<file>
+
+ Specify a file containing documentation which is placed on the main
+ contents page under the heading “Description”. The file is parsed as
+ a normal Haddock doc comment (but the comment markers are not
+ required).
+
+.. option:: -t <title>
+ --title=<title>
+
+ Use title as the page heading for each page in the
+ documentation.This will normally be the name of the library being
+ documented.
+
+ The title should be a plain string (no markup please!).
+
+.. option:: -q <mode>
+ --qual=<mode>
+
+ Specify how identifiers are qualified.
+
+ mode should be one of
+
+ - ``none`` (default): don't qualify any identifiers
+
+ - ``full``: always qualify identifiers completely
+
+ - ``local``: only qualify identifiers that are not part of the module
+
+ - ``relative``: like local, but strip name of the module from
+ qualifications of identifiers in submodules
+
+ Example: If you generate documentation for module A, then the
+ identifiers A.x, A.B.y and C.z are qualified as follows.
+
+ - none: x, y, z
+
+ - full: A.x, A.B.y, C.z
+
+ - local: x, A.B.y, C.z
+
+ - relative: x, B.y, C.z
+
+.. option:: -?
+ --help
+
+ Display help and exit.
+
+.. option:: -V
+ --version
+
+ Output version information and exit.
+
+.. option:: -v
+ --verbose
+
+ 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 ``Prelude``).
+
+.. option:: --use-contents=<url>
+ --use-index=<url>
+
+ When generating HTML, do not generate an index. Instead, redirect
+ the Contents and/or Index link on each page to URL. This option is
+ intended for use in conjunction with :option:`--gen-contents` and/or
+ :option:`--gen-index` for generating a separate contents and/or index
+ covering multiple libraries.
+
+.. option:: --gen-contents
+ --gen-index
+
+ Generate an HTML contents and/or index containing entries pulled
+ from all the specified interfaces (interfaces are specified using
+ :option:`-i` or :option:`--read-interface`). This is used to generate a single
+ contents and/or index for multiple sets of Haddock documentation.
+
+.. option:: --ignore-all-exports
+
+ Causes Haddock to behave as if every module has the
+ ``ignore-exports`` attribute (:ref:`module-attrs`). This might be useful for
+ generating implementation documentation rather than interface
+ documentation, for example.
+
+.. option:: --hide <module>
+
+ Causes Haddock to behave as if module module has the ``hide``
+ attribute. (:ref:`module-attrs`).
+
+.. option:: --show-extensions <module>
+
+ Causes Haddock to behave as if module module has the
+ ``show-extensions`` attribute. (:ref:`module-attrs`).
+
+.. option:: --optghc=<option>
+
+ Pass option to GHC. Note that there is a double dash there, unlike
+ for GHC.
+
+.. option:: -w
+ --no-warnings
+
+ Turn off all warnings.
+
+.. option:: --compatible-interface-versions
+
+ Prints out space-separated versions of binary Haddock interface
+ files that this version is compatible with.
+
+.. option:: --no-tmp-comp-dir
+
+ Do not use a temporary directory for reading and writing compilation
+ output files (``.o``, ``.hi``, and stub files). Instead, use the
+ present directory or another directory that you have explicitly told
+ GHC to use via the :option:`--optghc` flag.
+
+ This flag can be used to avoid recompilation if compilation files
+ already exist. Compilation files are produced when Haddock has to
+ process modules that make use of Template Haskell, in which case
+ Haddock compiles the modules using the GHC API.
+
+.. option:: --print-missing-docs
+
+ Print extra information about any undocumented entities.
+
+Using literate or pre-processed source
+--------------------------------------
+
+Since Haddock uses GHC internally, both plain and literate Haskell
+sources are accepted without the need for the user to do anything. To
+use the C pre-processor, however, the user must pass the the :option:`-cpp`
+option to GHC using :option:`--optghc`.
+
diff --git a/doc/markup.rst b/doc/markup.rst
new file mode 100644
index 00000000..a2274ad6
--- /dev/null
+++ b/doc/markup.rst
@@ -0,0 +1,887 @@
+Documentation and Markup
+========================
+
+Haddock understands special documentation annotations in the Haskell
+source file and propagates these into the generated documentation. The
+annotations are purely optional: if there are no annotations, Haddock
+will just generate documentation that contains the type signatures, data
+type declarations, and class declarations exported by each of the
+modules being processed.
+
+Documenting a top-level declaration
+-----------------------------------
+
+The simplest example of a documentation annotation is for documenting
+any top-level declaration (function type signature, type declaration, or
+class declaration). For example, if the source file contains the
+following type signature: ::
+
+ square :: Int -> Int
+ square x = x * x
+
+Then we can document it like this: ::
+
+ -- |The 'square' function squares an integer.
+ square :: Int -> Int
+ square x = x * x
+
+The ``-- |`` syntax begins a documentation annotation, which applies
+to the *following* declaration in the source file. Note that the
+annotation is just a comment in Haskell — it will be ignored by the
+Haskell compiler.
+
+The declaration following a documentation annotation should be one of
+the following:
+
+- A type signature for a top-level function,
+
+- A ``data`` declaration,
+
+- A ``newtype`` declaration,
+
+- A ``type`` declaration
+
+- A ``class`` declaration,
+
+- A ``data family`` or ``type family`` declaration, or
+
+- A ``data instance`` or ``type instance`` declaration.
+
+If the annotation is followed by a different kind of declaration, it
+will probably be ignored by Haddock.
+
+Some people like to write their documentation *after* the declaration;
+this is possible in Haddock too: ::
+
+ square :: Int -> Int
+ -- ^The 'square' function squares an integer.
+ square x = x * x
+
+Note that Haddock doesn't contain a Haskell type system — 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.
+
+Documentation annotations may span several lines; the annotation
+continues until the first non-comment line in the source file. For
+example: ::
+
+ -- |The 'square' function squares an integer.
+ -- It takes one argument, of type 'Int'.
+ square :: Int -> Int
+ square x = x * x
+
+You can also use Haskell's nested-comment style for documentation
+annotations, which is sometimes more convenient when using multi-line
+comments: ::
+
+ {-|
+ The 'square' function squares an integer.
+ It takes one argument, of type 'Int'.
+ -}
+ square :: Int -> Int
+ square x = x * x
+
+Documenting parts of a declaration
+----------------------------------
+
+In addition to documenting the whole declaration, in some cases we can
+also document individual parts of the declaration.
+
+Class methods
+~~~~~~~~~~~~~
+
+Class methods are documented in the same way as top level type
+signatures, by using either the ``-- |`` or ``-- ^`` annotations: ::
+
+ class C a where
+ -- | This is the documentation for the 'f' method
+ f :: a -> Int
+ -- | This is the documentation for the 'g' method
+ g :: Int -> a
+
+Constructors and record fields
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Constructors are documented like so: ::
+
+ data T a b
+ -- | This is the documentation for the 'C1' constructor
+ = C1 a b
+ -- | This is the documentation for the 'C2' constructor
+ | C2 a b
+
+or like this: ::
+
+ data T a b
+ = C1 a b -- ^ This is the documentation for the 'C1' constructor
+ | C2 a b -- ^ This is the documentation for the 'C2' constructor
+
+Record fields are documented using one of these styles: ::
+
+ 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 =
+ C { a :: a -- ^ This is the documentation for the 'a' field
+ , b :: b -- ^ This is the documentation for the 'b' field
+ }
+
+Alternative layout styles are generally accepted by Haddock - for
+example doc comments can appear before or after the comma in separated
+lists such as the list of record fields above.
+
+In case that more than one constructor exports a field with the same
+name, the documentation attached to the first occurence of the field
+will be used, even if a comment is not present. ::
+
+ data T a = A { someField :: a -- ^ Doc for someField of A
+ }
+ | B { someField :: a -- ^ Doc for someField of B
+ }
+
+In the above example, all occurences of ``someField`` in the
+documentation are going to be documented with
+``Doc for someField of A``. Note that Haddock versions 2.14.0 and before
+would join up documentation of each field and render the result. The
+reason for this seemingly weird behaviour is the fact that ``someField``
+is actually the same (partial) function.
+
+Function arguments
+~~~~~~~~~~~~~~~~~~
+
+Individual arguments to a function may be documented like this: ::
+
+ f :: Int -- ^ The 'Int' argument
+ -> Float -- ^ The 'Float' argument
+ -> IO () -- ^ The return value
+
+The module description
+----------------------
+
+A module itself may be documented with multiple fields that can then be
+displayed by the backend. In particular, the HTML backend displays all
+the fields it currently knows about. We first show the most complete
+module documentation example and then talk about the fields. ::
+
+ {-|
+ Module : W
+ Description : Short description
+ Copyright : (c) Some Guy, 2013
+ Someone Else, 2014
+ License : GPL-3
+ Maintainer : sample@email.com
+ Stability : experimental
+ Portability : POSIX
+
+ Here is a longer description of this module, containing some
+ commentary with @some markup@.
+ -}
+ module W where
+ ...
+
+The “Module” field should be clear. It currently doesn't affect the
+output of any of the backends but you might want to include it for human
+information or for any other tools that might be parsing these comments
+without the help of GHC.
+
+The “Description” field accepts some short text which outlines the
+general purpose of the module. If you're generating HTML, it will show
+up next to the module link in the module index.
+
+The “Copyright”, “License”, “Maintainer” and “Stability” fields should
+be obvious. An alternative spelling for the “License” field is accepted
+as “Licence” but the output will always prefer “License”.
+
+The “Portability” field has seen varied use by different library
+authors. Some people put down things like operating system constraints
+there while others put down which GHC extensions are used in the module.
+Note that you might want to consider using the “show-extensions” module
+flag for the latter.
+
+Finally, a module may contain a documentation comment before the module
+header, in which case this comment is interpreted by Haddock as an
+overall description of the module itself, and placed in a section
+entitled “Description” in the documentation for the module. All usual
+Haddock markup is valid in this comment.
+
+All fields are optional but they must be in order if they do appear.
+Multi-line fields are accepted but the consecutive lines have to start
+indented more than their label. If your label is indented one space as
+is often the case with “--” syntax, the consecutive lines have to start
+at two spaces at the very least. Please note that we do not enforce the
+format for any of the fields and the established formats are just a
+convention.
+
+Controlling the documentation structure
+---------------------------------------
+
+Haddock produces interface documentation that lists only the entities
+actually exported by the module. The documentation for a module will
+include *all* entities exported by that module, even if they were
+re-exported by another module. The only exception is when Haddock can't
+see the declaration for the re-exported entity, perhaps because it isn't
+part of the batch of modules currently being processed.
+
+However, to Haddock the export list has even more significance than just
+specifying the entities to be included in the documentation. It also
+specifies the *order* that entities will be listed in the generated
+documentation. This leaves the programmer free to implement functions in
+any order he/she pleases, and indeed in any *module* he/she pleases, but
+still specify the order that the functions should be documented in the
+export list. Indeed, many programmers already do this: the export list
+is often used as a kind of ad-hoc interface documentation, with
+headings, groups of functions, type signatures and declarations in
+comments.
+
+You can insert headings and sub-headings in the documentation by
+including annotations at the appropriate point in the export list. For
+example: ::
+
+ module Foo (
+ -- * Classes
+ C(..),
+ -- * Types
+ -- ** A data type
+ T,
+ -- ** A record
+ R,
+ -- * Some functions
+ f, g
+ ) where
+
+Headings are introduced with the syntax ``-- *``, ``-- **`` and so
+on, where the number of ``*``\ s indicates the level of the heading
+(section, sub-section, sub-sub-section, etc.).
+
+If you use section headings, then Haddock will generate a table of
+contents at the top of the module documentation for you.
+
+The alternative style of placing the commas at the beginning of each
+line is also supported. e.g.: ::
+
+ module Foo (
+ -- * Classes
+ , C(..)
+ -- * Types
+ -- ** A data type
+ , T
+ -- ** A record
+ , R
+ -- * Some functions
+ , f
+ , g
+ ) where
+
+Re-exporting an entire module
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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 list: ::
+
+ module A (
+ module B,
+ module C
+ ) where
+
+What will the Haddock-generated documentation for this module look like?
+Well, it depends on how the modules ``B`` and ``C`` are imported. If
+they are imported wholly and without any ``hiding`` qualifiers, then the
+documentation will just contain a cross-reference to the documentation
+for ``B`` and ``C``. However, if the modules are not *completely*
+re-exported, for example: ::
+
+ module A (
+ module B,
+ module C
+ ) where
+
+ import B hiding (f)
+ import C (a, b)
+
+then Haddock behaves as if the set of entities re-exported from ``B``
+and ``C`` had been listed explicitly in the export list [2]_.
+
+.. [2]
+ NOTE: this is not fully implemented at the time of writing (version
+ 0.2). At the moment, Haddock always inserts a cross-reference.
+
+The exception to this rule is when the re-exported module is declared
+with the ``hide`` attribute (:ref:`module-attrs`), in which case the module is
+never cross-referenced; the contents are always expanded in place in the
+re-exporting module.
+
+Omitting the export list
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+If there is no export list in the module, how does Haddock generate
+documentation? Well, when the export list is omitted, e.g.: ::
+
+ module Foo where
+
+this is equivalent to an export list which mentions every entity defined
+at the top level in this module, and Haddock treats it in the same way.
+Furthermore, the generated documentation will retain the order in which
+entities are defined in the module. In this special case the module body
+may also include section headings (normally they would be ignored by
+Haddock). ::
+
+ module Foo where
+
+ -- * This heading will now appear before foo.
+
+ -- | Documentation for 'foo'.
+ foo :: Integer
+ foo = 5
+
+Named chunks of documentation
+-----------------------------
+
+Occasionally it is desirable to include a chunk of documentation which
+is not attached to any particular Haskell declaration. There are two
+ways to do this:
+
+- The documentation can be included in the export list directly, e.g.: ::
+
+ module Foo (
+ -- * A section heading
+
+ -- | Some documentation not attached to a particular Haskell entity
+ ...
+ ) where
+
+- If the documentation is large and placing it inline in the export
+ list might bloat the export list and obscure the structure, then it
+ can be given a name and placed out of line in the body of the module.
+ This is achieved with a special form of documentation annotation
+ “``-- $``”: ::
+
+ module Foo (
+ -- * A section heading
+
+ -- $doc
+ ...
+ ) where
+
+ -- $doc
+ -- Here is a large chunk of documentation which may be referred to by
+ -- the name $doc.
+
+ The documentation chunk is given a name, which is the sequence of
+ alphanumeric characters directly after the “``-- $``”, and it may be
+ referred to by the same name in the export list.
+
+Hyperlinking and re-exported entities
+-------------------------------------
+
+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 given type constructor or class
+there may be several modules re-exporting it, and therefore several
+modules whose documentation contains the definition of that type or
+class (possibly including the current module!) so which one do we link
+to?
+
+Let's look at an example. Suppose we have three modules ``A``, ``B`` and
+``C`` defined as follows: ::
+
+ module A (T) where
+ data T a = C a
+
+ module B (f) where
+ import A
+ f :: T Int -> Int
+ f (C i) = i
+
+ module C (T, f) where
+ import A
+ import B
+
+Module ``A`` exports a datatype ``T``. Module ``B`` imports ``A`` and
+exports a function ``f`` whose type refers to ``T``. Also, both ``T``
+and ``f`` are re-exported from module C.
+
+Haddock takes the view that each entity has a *home* module; that is,
+the module that the library designer would most like to direct the user
+to, to find the documentation for that entity. So, Haddock makes all
+links to an entity point to the home module. The one exception is when
+the entity is also exported by the current module: Haddock makes a local
+link if it can.
+
+How is the home module for an entity determined? Haddock uses the
+following rules:
+
+- If modules A and B both export the entity, and module A imports
+ (directly or indirectly) module B, then B is preferred.
+
+- A module with the ``hide`` attribute is never chosen as the home.
+
+- A module with the ``not-home`` attribute is only chosen if there are
+ no other modules to choose.
+
+If multiple modules fit the criteria, then one is chosen at random. If
+no modules fit the criteria (because the candidates are all hidden),
+then Haddock will issue a warning for each reference to an entity
+without a home.
+
+In the example above, module ``A`` is chosen as the home for ``T``
+because it does not import any other module that exports ``T``. The link
+from ``f``'s type in module ``B`` will therefore point to ``A.T``.
+However, ``C`` also exports ``T`` and ``f``, and the link from ``f``'s
+type in ``C`` will therefore point locally to ``C.T``.
+
+.. _module-attrs:
+
+Module Attributes
+-----------------
+
+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 an
+``{-# OPTIONS_HADDOCK ... #-}`` pragma at the top of the module, either
+before or after the module description. For example: ::
+
+ {-# OPTIONS_HADDOCK hide, prune, ignore-exports #-}
+
+ -- |Module description
+ module A where
+ ...
+
+The options and module description can be in either order.
+
+The following attributes are currently understood by Haddock:
+
+``hide`` ``hide``
+ Omit this module from the generated documentation, but nevertheless
+ propagate definitions and documentation from within this module to
+ modules that re-export those definitions.
+
+``hide`` ``prune``
+ Omit definitions that have no documentation annotations from the
+ generated documentation.
+
+``ignore-exports`` ``ignore-exports``
+ Ignore the export list. Generate documentation as if the module had
+ no export list - i.e. all the top-level declarations are exported,
+ and section headings may be given in the body of the module.
+
+``not-home`` ``not-home``
+ Indicates that the current module should not be considered to be the
+ home module for each entity it exports, unless that entity is not
+ exported from any other module. See ? for more details.
+
+``show-extensions`` ``show-extensions``
+ Indicates that we should render the extensions used in this module
+ in the resulting documentation. This will only render if the output
+ format supports it. If Language is set, it will be shown as well and
+ all the extensions implied by it won't. All enabled extensions will
+ be rendered, including those implied by their more powerful
+ versions.
+
+Markup
+------
+
+Haddock understands certain textual cues inside documentation
+annotations that tell it how to render the documentation. The cues (or
+“markup”) have been designed to be simple and mnemonic in ASCII so that
+the programmer doesn't have to deal with heavyweight annotations when
+editing documentation comments.
+
+Paragraphs
+~~~~~~~~~~
+
+One or more blank lines separates two paragraphs in a documentation
+comment.
+
+Special characters
+~~~~~~~~~~~~~~~~~~
+
+The following characters have special meanings in documentation
+comments: ``\\``, ``/``, ``'``, ``\```, ``"``, ``@``, ``<``. To insert a
+literal occurrence of one of these special characters, precede it with a
+backslash (``\\``).
+
+Additionally, the character ``>`` has a special meaning at the beginning
+of a line, and the following characters have special meanings at the
+beginning of a paragraph: ``*``, ``-``. These characters can also be
+escaped using ``\\``.
+
+Furthermore, the character sequence ``>>>`` has a special meaning at the
+beginning of a line. To escape it, just prefix the characters in the
+sequence with a backslash.
+
+Character references
+~~~~~~~~~~~~~~~~~~~~
+
+Although Haskell source files may contain any character from the Unicode
+character set, the encoding of these characters as bytes varies between
+systems, so that only source files restricted to the ASCII character set
+are portable. Other characters may be specified in character and string
+literals using Haskell character escapes. To represent such characters
+in documentation comments, Haddock supports SGML-style numeric character
+references of the forms ``&#``\ D\ ``;`` and ``&#x``\ H\ ``;`` where D
+and H are decimal and hexadecimal numbers denoting a code position in
+Unicode (or ISO 10646). For example, the references ``λ``,
+``λ`` and ``λ`` all represent the lower-case letter lambda.
+
+Code Blocks
+~~~~~~~~~~~
+
+Displayed blocks of code are indicated by surrounding a paragraph with
+``@...@`` or by preceding each line of a paragraph with ``>`` (we often
+call these “bird tracks”). For example: ::
+
+ -- | This documentation includes two blocks of code:
+ --
+ -- @
+ -- f x = x + x
+ -- @
+ --
+ -- > g x = x * 42
+
+There is an important difference between the two forms of code block: in
+the bird-track form, the text to the right of the ‘\ ``>``\ ’ is
+interpreted literally, whereas the ``@...@`` form interprets markup as
+normal inside the code block.
+
+Examples
+~~~~~~~~
+
+Haddock has markup support for examples of interaction with a
+*read-eval-print loop (REPL)*. An example is introduced with ``>>>``
+followed by an expression followed by zero or more result lines: ::
+
+ -- | Two examples are given below:
+ --
+ -- >>> fib 10
+ -- 55
+ --
+ -- >>> putStrLn "foo\nbar"
+ -- foo
+ -- bar
+
+Result lines that only contain the string ``<BLANKLINE>`` are rendered
+as blank lines in the generated documentation.
+
+Properties
+~~~~~~~~~~
+
+Haddock provides markup for properties: ::
+
+ -- | Addition is commutative:
+ --
+ -- prop> a + b = b + a
+
+This allows third-party applications to extract and verify them.
+
+Hyperlinked Identifiers
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Referring to a Haskell identifier, whether it be a type, class,
+constructor, or function, is done by surrounding it with single quotes: ::
+
+ -- | This module defines the type 'T'.
+
+If there is an entity ``T`` in scope in the current module, then the
+documentation will hyperlink the reference in the text to the definition
+of ``T`` (if the output format supports hyperlinking, of course; in a
+printed format it might instead insert a page reference to the
+definition).
+
+It is also possible to refer to entities that are not in scope in the
+current module, by giving the full qualified name of the entity: ::
+
+ -- | The identifier 'M.T' is not in scope
+
+If ``M.T`` is not otherwise in scope, then Haddock will simply emit a
+link pointing to the entity ``T`` exported from module ``M`` (without
+checking to see whether either ``M`` or ``M.T`` exist).
+
+To make life easier for documentation writers, a quoted identifier is
+only interpreted as such if the quotes surround a lexically valid
+Haskell identifier. This means, for example, that it normally isn't
+necessary to escape the single quote when used as an apostrophe: ::
+
+ -- | I don't have to escape my apostrophes; great, isn't it?
+
+Nothing special is needed to hyperlink identifiers which contain
+apostrophes themselves: to hyperlink ``foo'`` one would simply type
+``'foo''``. To hyperlink identifiers written in infix form, simply put
+them in quotes as always: ``'`elem`'``.
+
+For compatibility with other systems, the following alternative form of
+markup is accepted [3]_: ```T'``.
+
+.. [3]
+ We chose not to use this as the primary markup for identifiers
+ because strictly speaking the ````` character should not be used as a
+ left quote, it is a grave accent.
+
+Emphasis, Bold and Monospaced text
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Emphasis may be added by surrounding text with ``/.../``. Other markup
+is valid inside emphasis. To have a forward slash inside of emphasis,
+just escape it: ``/fo\/o/``
+
+Bold (strong) text is indicated by surrounding it with ``__...__``.
+Other markup is valid inside bold. For example, ``__/foo/__`` will make
+the emphasised text ``foo`` bold. You don't have to escape a single
+underscore if you need it bold:
+``__This_text_with_underscores_is_bold__``.
+
+Monospaced (or typewriter) text is indicated by surrounding it with
+``@...@``. Other markup is valid inside a monospaced span: for example
+``@'f' a b@`` will hyperlink the identifier ``f`` inside the code
+fragment.
+
+Linking to modules
+~~~~~~~~~~~~~~~~~~
+
+Linking to a module is done by surrounding the module name with double
+quotes: ::
+
+ -- | This is a reference to the "Foo" module.
+
+A basic check is done on the syntax of the header name to ensure that it
+is valid before turning it into a link but unlike with identifiers,
+whether the module is in scope isn't checked and will always be turned
+into a link.
+
+Itemized and Enumerated lists
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A bulleted item is represented by preceding a paragraph with either
+“``*``” or “``-``”. A sequence of bulleted paragraphs is rendered as an
+itemized list in the generated documentation, eg.: ::
+
+ -- | This is a bulleted list:
+ --
+ -- * first item
+ --
+ -- * second item
+
+An enumerated list is similar, except each paragraph must be preceded by
+either “``(n)``” or “``n.``” where n is any integer. e.g. ::
+
+ -- | This is an enumerated list:
+ --
+ -- (1) first item
+ --
+ -- 2. second item
+
+Lists of the same type don't have to be separated by a newline: ::
+
+ -- | This is an enumerated list:
+ --
+ -- (1) first item
+ -- 2. second item
+ --
+ -- This is a bulleted list:
+ --
+ -- * first item
+ -- * second item
+
+You can have more than one line of content in a list element: ::
+
+ -- |
+ -- * first item
+ -- and more content for the first item
+ -- * second item
+ -- and more content for the second item
+
+You can even nest whole paragraphs inside of list elements. The rules
+are 4 spaces for each indentation level. You're required to use a
+newline before such nested paragraph: ::
+
+ {-|
+ * Beginning of list
+ This belongs to the list above!
+
+ > nested
+ > bird
+ > tracks
+
+ * Next list
+ More of the indented list.
+
+ * Deeper
+
+ @
+ even code blocks work
+ @
+
+ * Deeper
+
+ 1. Even deeper!
+ 2. No newline separation even in indented lists.
+ -}
+
+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. ::
+
+ {-|
+ * foo
+
+ * bar
+ -}
+
+Definition lists
+~~~~~~~~~~~~~~~~
+
+Definition lists are written as follows: ::
+
+ -- | This is a definition list:
+ --
+ -- [@foo@]: The description of @foo@.
+ --
+ -- [@bar@]: The description of @bar@.
+
+To produce output something like this:
+
+``foo``
+ The description of ``foo``.
+
+``bar``
+ The description of ``bar``.
+
+Each paragraph should be preceded by the “definition term” enclosed in
+square brackets and followed by a colon. Other markup operators may be
+used freely within the definition term. You can escape ``]`` with a
+backslash as usual.
+
+Same rules about nesting and no newline separation as for bulleted and
+numbered lists apply.
+
+URLs
+~~~~
+
+A URL can be included in a documentation comment by surrounding it in
+angle brackets, for example: ::
+
+ <http://example.com>
+
+If the output format supports it, the URL will be turned into a
+hyperlink when rendered.
+
+If Haddock sees something that looks like a URL (such as something
+starting with ``http://`` or ``ssh://``) where the URL markup is valid,
+it will automatically make it a hyperlink.
+
+Links
+~~~~~
+
+Haddock supports Markdown syntax for inline links. A link consists of a
+link text and a URL. The link text is enclosed in square brackets and
+followed by the URL enclosed in regular parentheses, for example: ::
+
+ [some link](http://example.com)
+
+The link text is used as a descriptive text for the URL, if the output
+format supports it.
+
+Images
+~~~~~~
+
+Haddock supports Markdown syntax for inline images. This resembles the
+syntax for links, but starts with an exclamation mark. An example looks
+like this: ::
+
+ 
+
+If the output format supports it, the image will be rendered inside the
+documentation. The image description is used as relpacement text and/or
+image title.
+
+Anchors
+~~~~~~~
+
+Sometimes it is useful to be able to link to a point in the
+documentation which doesn't correspond to a particular entity. For that
+purpose, we allow *anchors* to be included in a documentation comment.
+The syntax is ``#label#``, where label is the name of the anchor. An
+anchor is invisible in the generated documentation.
+
+To link to an anchor from elsewhere, use the syntax ``"module#label"``
+where module is the module name containing the anchor, and label is the
+anchor label. The module does not have to be local, it can be imported
+via an interface. Please note that in Haddock versions 2.13.x and
+earlier, the syntax was ``"module\#label"``. It is considered deprecated
+and will be removed in the future.
+
+Headings
+~~~~~~~~
+
+Headings inside of comment documentation are possible be preceding them
+with a number of ``=``\ s. From 1 to 6 are accepted. Extra ``=``\ s will
+be treated as belonging to the text of the heading. Note that it's up to
+the output format to decide how to render the different levels. ::
+
+ -- |
+ -- = Heading level 1 with some /emphasis/
+ -- Something underneath the heading.
+ --
+ -- == /Subheading/
+ -- More content.
+ --
+ -- === Subsubheading
+ -- Even more content.
+
+Note that while headings have to start on a new paragraph, we allow
+paragraph-level content to follow these immediately. ::
+
+ -- |
+ -- = Heading level 1 with some __bold__
+ -- Something underneath the heading.
+ --
+ -- == /Subheading/
+ -- More content.
+ --
+ -- === Subsubheading
+ -- >>> examples are only allowed at the start of paragraphs
+
+As of 2.15.1, there's experimental (read: subject to change or get
+removed) support for collapsible headers: simply wrap your existing
+header title in underscores, as per bold syntax. The collapsible section
+will stretch until the end of the comment or until a header of equal or
+smaller number of ``=``\ s. ::
+
+ -- |
+ -- === __Examples:__
+ -- >>> Some very long list of examples
+ --
+ -- ==== This still falls under the collapse
+ -- Some specialised examples
+ --
+ -- === This is does not go into the collapsable section.
+ -- More content.
+
+Metadata
+~~~~~~~~
+
+Since Haddock 2.16.0, some support for embedding metadata in the
+comments has started to appear. The use of such data aims to standardise
+various community conventions in how such information is conveyed and to
+provide uniform rendering.
+
+Since
+^^^^^
+
+``@since`` annotation can be used to convey information about when the
+function was introduced or when it has changed in the way significant to
+the user. ``@since`` is a paragraph-level element. While multiple such
+annotations are not an error, only the one to appear in the comment last
+will be used. ``@since`` has to be followed with a version number, no
+further description is currently allowed. The meaning of this feature is
+subject to change in the future per user feedback. ::
+
+ -- |
+ -- Some comment
+ --
+ -- @since 1.2.3
--
cgit v1.2.3
From bae468bb60c31ed0a24193ba50fa5f6953d10d3a Mon Sep 17 00:00:00 2001
From: Ben Gamari <ben@smart-cactus.org>
Date: Mon, 8 Feb 2016 00:37:13 +0100
Subject: Document --use-unicode flag
---
doc/invoking.rst | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/doc/invoking.rst b/doc/invoking.rst
index 38ba7551..c69c9031 100644
--- a/doc/invoking.rst
+++ b/doc/invoking.rst
@@ -312,6 +312,10 @@ The following options are available:
combined with :option:`--theme`. Note that order matters: The first
specified theme will be the default.
+.. option:: --use-unicode
+
+ Enable use of Unicode characters in HTML output.
+
.. option:: -c <file>
--css=<file>
--
cgit v1.2.3