index

Annote

This page is http://www.math.columbia.edu/~bayer/Haskell/Annote/

Annote version 0.1 (61)

Annote is a Unix command line tool written in Haskell, and compiled using the Glasgow Haskell Compiler (GHC). These web pages are produced using Annote.

The following executable and source tarballs are available:

Annote compiles and runs successfully using GHC Haskell 6.8.1 on Mac OS X (Intel). This version has not been tested elsewhere; previous versions also compiled and ran on Linux, using older versions of GHC.

This is work in progress, implementing a literate programming source code documentation system. At the moment it only support generic and Haskell source files, but the intention is to provide custom support for a variety of languages such as Macaulay2.

Various target languages has their own preferred system for generating documentation web pages, e.g. Haddock for Haskell. These systems have an independent goal, to document a library for users without exposing its internal structure. Annote works in conjunction with such systems; one embeds markup for the other system in special block comments that Annote can be trained to ignore.

Documentation source is written to be processed using the Markdown text-to-HTML conversion tool. One can substitute any HTML markup processor that plays nice with the HTML elements that Annote itself generates.

Here is the current Haskell source code for Annote, applied to itself:

Here is an example tutorial page on Haskell lists, in the form of a self-contained working program documented using Annote. The documentation makes calls to ghci to show types, and to ghc to show the program output:

Lists

Here are examples in other languages:

Annote is designed to be used with a text editor that supports foldings, such as TextMate. Otherwise, the documentation text can become a distraction while coding.

Documentation source is taken from block comments. For example, in Haskell one can write

{-
`getDoc` is called when the remaining lines `txt` of a source file begin
with a here document, terminated by the line `eof`. It returns a pair
consisting of the here document, and the rest of the source file.
-}
getDoc :: String -> [String] -> (String,[String])
getDoc eof txt =
   let (doc,rest) = break (== eof) txt
   in  (unlines doc, drop 1 rest)

and Annote will produce the following documented code:

getDoc is called when the remaining lines txt of a source file begin with a here document, terminated by the line eof. It returns a pair consisting of the here document, and the rest of the source file.

getDoc :: String -> [String] -> (String,[String])
getDoc eof txt =
   let (doc,rest) = break (== eof) txt
   in  (unlines doc, drop 1 rest)

One can also execute shell commands within documentation; this can be used to execute the source code under discussion. For example, in Haskell one can write

{-
@shell echo >temp; ls t*
@shell rm -f temp; ls t*
-}

and Annote will produce the following output:

temp

ls: t*: No such file or directory