This package extends Cabal's documentation building capabilities. It extends the Haddock markup language with syntax for subscripts, superscripts, and more. Recent version of Haddock already support bold text and the inclusion of images; however, we continue to provide markup for these for backward compatibility with earlier versions of Superdoc.

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 in your own packages is very easy. In most cases, only three or four simple steps are required:

1. Set the package property "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 property 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]

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-doc-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 post-processing the 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 post-process the output of Haddock to interpret Superdoc markup tags, as described in "Markup".
2. We post-process the output of HsColour. The HsColour program 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.