superdoc-0.1.2.5: Additional documentation markup and Unicode support

Safe HaskellNone
LanguageHaskell2010

Distribution.Superdoc

Contents

Description

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.

Synopsis

Documentation

How to use this package

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.

Markup

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

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 = ξ.

Using images

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".

Setting the image directory

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" }

Images via extra-html-files

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.

How it works

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 "☺".

API functions

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.

Default entry point

superdocMain :: IO () Source #

The main function for a Cabal setup script. Use this instead of defaultMain in your Setup.hs to enable the Superdoc documentation features. Typical usage:

import Distribution.Superdoc
main = superdocMain

See How to use this package for more information.

Parameters

data SuperdocArgs Source #

A data structure to hold Superdoc's parameters. Additional parameters may be added in the future, so to ensure forward compatibility, packages should always specify parameters by modifying defaultSuperdocArgs, for example like this:

let params = defaultSuperdocArgs { imageSource = ... }

Constructors

SuperdocArgs 

Fields

  • imageSource :: ImageSource

    Where to look for image files.

  • imageMissing :: ImageMissing

    What to do about missing image files.

  • bootstrap :: Bool

    Bootstrapping mode. Required to generate Superdoc's own documentation, because at that point, Superdoc is typically not yet installed. Other packages using Superdoc should not set this flag.

Instances

defaultSuperdocArgs :: SuperdocArgs Source #

The default Superdoc parameters.

data ImageSource Source #

This parameter specifies where to find image files that are linked to in the documentation.

Constructors

CopyFrom FilePath

Copy image files from the specified source directory, which is relative to the package root. The default is "images". Superdoc will copy the required images to their appropriate location within the generated HTML documentation. The image files should also be declared as extra-source-files in the .cabal file.

ExtraHtmlFiles

Assume the images are already present in the directory where the Haddock documentation is being generated. This is useful if the images have been declared as extra-html-files in the .cabal file. They will then have been copied to their rightful location by Cabal. Superdoc will check that the required images are present.

Instances

data ImageMissing Source #

This parameter specifies what to do when the documentation links to an image that does not exist.

Constructors

FailOnMissing

This is the default setting. Cabal will fail with an error message if the documentation links to an image that does not exist or cannot be found.

IgnoreMissing

Ignore missing image files. Superdoc will still generate HTML image tags, but will not fail if a corresponding image file does not exist. This setting may be useful for testing, or to build documentation when the image files are incomplete or missing. It is not recommended to use this setting for production purposes.

Instances

Alternate entry point

superdocMainArgs :: SuperdocArgs -> IO () Source #

Like superdocMain, but also accept parameters in the form of a SuperdocArgs argument. Typical use:

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

User hooks

superdocHooks :: UserHooks Source #

A predefined set of UserHooks for package maintainers who need to use the defaultMainWithHooks function from Distribution.Simple. The following is equivalent to superdocMain:

import Distribution.Simple
import Distribution.Superdoc
main = defaultMainWithHooks superdocHooks

superdocHooksArgs :: SuperdocArgs -> UserHooks Source #

Like superdocHooks, but also accept parameters in the form of a SuperdocArgs argument. Typical use:

import Distribution.Simple
import Distribution.Superdoc
main = defaultMainWithHooks superdocHooksArgs { imageSource = CopyFrom "imgdir" }