Safe Haskell | None |
---|---|
Language | Haskell2010 |
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.
- superdocMain :: IO ()
- data SuperdocArgs = SuperdocArgs {}
- defaultSuperdocArgs :: SuperdocArgs
- data ImageSource
- data ImageMissing
- superdocMainArgs :: SuperdocArgs -> IO ()
- superdocHooks :: UserHooks
- superdocHooksArgs :: SuperdocArgs -> UserHooks
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:
- Set the package property "
build-type
" to "Custom
" in your.cabal
file; - Add "
superdoc
" to the "build-depends
" field in your.cabal
file; - (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; - 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
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:
- 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).
- We post-process the output of Haddock to convert the armored Unicode characters into proper HTML escape sequences, such as "☺".
- At the same time, we also post-process the output of Haddock to interpret Superdoc markup tags, as described in Markup.
- 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 = ... }
SuperdocArgs | |
|
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.
CopyFrom FilePath | Copy image files from the specified source directory, which
is relative to the package root. The default is " |
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 |
data ImageMissing Source #
This parameter specifies what to do when the documentation links to an image that does not exist.
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. |
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" }