Safe Haskell	None
Language	Haskell2010

Distribution.Superdoc.Hooks

Contents

Superdoc parameters
Hooks for the setup program

Description

This module defines Superdoc's parameters, as well as the Cabal user hooks that do Superdoc's "real" work. For an explanation of what that work is, see here: Distribution.Superdoc.

Further, this module exposes some low-level functions that are not exposed in Distribution.Superdoc, but that may be useful for some specialized applications.

Synopsis

Superdoc 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

Eq SuperdocArgs Source #
Methods (==) :: SuperdocArgs -> SuperdocArgs -> Bool # (/=) :: SuperdocArgs -> SuperdocArgs -> Bool #
Show SuperdocArgs Source #
Methods showsPrec :: Int -> SuperdocArgs -> ShowS # show :: SuperdocArgs -> String # showList :: [SuperdocArgs] -> ShowS #

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

Eq ImageSource Source #
Methods (==) :: ImageSource -> ImageSource -> Bool # (/=) :: ImageSource -> ImageSource -> Bool #
Show ImageSource Source #
Methods showsPrec :: Int -> ImageSource -> ShowS # show :: ImageSource -> String # showList :: [ImageSource] -> ShowS #

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

Eq ImageMissing Source #
Methods (==) :: ImageMissing -> ImageMissing -> Bool # (/=) :: ImageMissing -> ImageMissing -> Bool #
Show ImageMissing Source #
Methods showsPrec :: Int -> ImageMissing -> ShowS # show :: ImageMissing -> String # showList :: [ImageMissing] -> ShowS #

Hooks for the setup program

A hook for Haddock

haddockhook :: SuperdocArgs -> PackageDescription -> LocalBuildInfo -> UserHooks -> HaddockFlags -> IO () Source #

A hook for Haddock. This simply adds a command line option to the subordinate Haddock process, instructing it to use the superdoc-armor preprocessor. Its purpose is to replace UTF8-encoded Unicode characters by their ASCII armor.

A post-Haddock hook

posthaddock :: SuperdocArgs -> Args -> HaddockFlags -> PackageDescription -> LocalBuildInfo -> IO () Source #

A hook to run after Haddock completes. This resolves Superdoc markup and ASCII armor in all generated HTML files. It also copies all of the linked images to the HTML directory (depending on the imageSource and imageMissing parameters). Finally, it checks for the "--hyperlink-source" option, and if necessary, calls the posthscolour hook as well (because it is not run from inside Cabal in this situation).

The first argument hold the Superdoc parameters, and the remaining arguments are as for any postHaddock hook.

do_posthaddock :: SuperdocArgs -> FilePath -> IO () Source #

Do the actual work of the posthaddock hook, given a path to the documentation directory.

handle_images :: ImageSource -> ImageMissing -> Set FilePath -> FilePath -> IO () Source #

Perform the action described by ImageSource and ImageMissing, for the given set of images. The last argument is the path for the documentation directory.

A post-HsColour hook

posthscolour :: SuperdocArgs -> Args -> HscolourFlags -> PackageDescription -> LocalBuildInfo -> IO () Source #

A hook to run after HsColour completes. This goes through the files generated by HsColour and replaces UTF8 characters by their corresponding HTML escapes.

do_posthscolour :: FilePath -> IO () Source #

Do the actual work of the posthaddock hook, given a path to the documentation directory.