This package extends Cabal's documentation building capabilities. It extends the Haddock markup language with syntax for subscripts, superscripts, bold text, non-breaking spaces, and images. Moreover, it works around various bugs in Haddock's and HsColour's Unicode support, making it possible to use UTF8 encodings in both source code and documentation comments.

This package is designed to work transparently. It provides a custom main function that package maintainers can use in their Setup.hs file.

Using the extended markup and Unicode in your own packages is very easy. In most cases, only three or four simple steps are required:

1. Set the package propery "build-type" to "Custom" in your .cabal file;
2. Add "superdoc" to the "build-depends" field in your .cabal file;
3. (Optional): Add any image files to the "images" directory in your package root, and add the filenames to the "extra-source-files" package propery in your .cabal file;
4. Create a file Setup.hs containing the following two lines:

import Distribution.Superdoc
main = superdocMain

Then just mark up your sources and run "cabal haddock" as usual.

Superdoc recognizes the following markup, in addition to the usual Haddock markup:

• [super text]: superscript.
• [sup text]: superscript. A synonym for [super text].
• [sub text]: subscript.
• [exp text]: exponential function.
• [bold text]: bold.
• [center text]: centered.
• [nobr text]: inhibit line breaks.
• [image filename]: insert image. See Using images for more information.
• [uni nnnn]: Unicode character.
• [literal text]: literal text. Brackets '[' and ']' may only occur in nested pairs.

All tags except image, uni, and literal can be nested. Here are some examples:

Markup:                         Output:
2[super /n/]                    2n
2[sup /n/]                      2n
/x/[sub 2]                      x2
[exp /i/πθ]                     eiπθ
[bold this]                     this
[center this]                   this
[nobr Henry VIII]               Henry VIII
[image myimage.png]             
[uni 9786]                      ☺
[literal [bold text]]           [bold text]
2[sup [bold n][sub /i/]]        2ni

There are some cases where Haddock assigns special meaning to the bracket '[', notably at the beginning of a paragraph. In such cases, you must escape the '[' with a backslash to use it as a Superdoc tag. For example, to display an image on a line by itself, use

\[image myimage.png]

Unicode can be very useful in documentation, especially for mathematical applications. With Superdoc, you can use Unicode directly in your documentation markup, using the UTF8 encoding. You can also use Unicode in your Haskell sources. Here is an example of documentation markup:

Theorem. Let ξ ∈ ℤ[√2], and assume that ξ ≥ 0, ξ^• ≥ 0, and that p = ξ^•ξ is a prime ≡ 1 (mod 4) in ℤ. Then there exists some t ∈ ℤ[ω] such that t^†t = ξ.

You can embed images in your documentation using the tag [image filename]. By default, Superdoc looks for image files in the directory "images" at the root of your package. Superdoc takes care of copying the image files to their correct location within the generated HTML documentation. It is an error to link to an image that does not actually exist, and in this case "cabal haddock" will fail with an error message.

If you are using any images, you must also add them to the "extra-source-files" package property in your .cabal file, for example like this:

extra-source-files:  images/*.png

This ensures that the images will be included when you build a source distribution from your package with "cabal sdist".

By default, Superdoc looks for images in the "images" directory of your package. If your images reside in a different location, you can inform Superdoc of this by passing an imageSource parameter, as follows:

import Distribution.Superdoc
main = superdocMainArgs defaultSuperdocArgs { imageSource = CopyFrom "imgdir" }

Some newer versions of Cabal also support an "extra-html-files" package property. If you add your images to this, instead of "extra-source-files", then Cabal (and not Superdoc) will copy the images to their rightful location in the HTML documentation. In this case, you should tell Superdoc not to copy the images again. This can be done by setting imageSource to ExtraHtmlFiles:

import Distribution.Superdoc
main = superdocMainArgs defaultSuperdocArgs { imageSource = ExtraHtmlFiles }

In this case, Superdoc will not copy the images, but it will still check that Cabal has done so. It is still an error to link to a non-existing image.

Internally, this package is implemented as a bunch of Cabal hooks for pre- and post-processing the input and output of Haddock and HsColour. In this way, we do not actually have to modify Haddock and HsColour themselves. Here is a brief explanation of how it works:

1. We pre-process the input of Haddock by converting each Unicode character to an ASCII sequence, such as "uni_x_9786_x_". This process is called armoring. The armoring is done in a way that preserves the validity of Haskell identifiers and operators, i.e., the armored version of a valid upper- or lower-case identifier or operator is again a valid identifier or operator of the same kind. As a result, it is possible to use Unicode not only in documentation comments, but also in the source code itself. (Haskell already handles Unicode correctly anyway, but most Haddock versions don't).
2. We post-process the output of Haddock to convert the armored Unicode characters into proper HTML escape sequences, such as "☺".
3. At the same time, we also post-process the output of Haddock to interpret Superdoc markup tags, as described in Markup.
4. Finally, we also post-process the output of HsColour. The HsColour program natively just copies any Unicode characters to the output unchanged; however, the resulting pages may not display correctly in web browsers that are set to use a different character encoding. We therefore convert any such characters to encoding-independent HTML sequences such as "☺".

This module exports main functions that can be used in Setup.hs scripts. The standard entry point is superdocMain. Alternatively, the entry point superdocMainArgs can be used if additional package parameters need to be specified. We also provide predefined set of UserHooks that can be used with defaultMainWithHooks.