hscolour-1.16: index.html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><title>hscolour</title></head>
<body bgcolor="#ffffff">
<table><tr><td width=700>
<center>
<h1>hscolour</h1>
</center>
<hr>
<p>
<b>hscolour</b> is a small Haskell script to colourise Haskell code.
It currently has six output formats: ANSI terminal codes, HTML 3.2 with
<font> tags, HTML 4.01 with CSS, XHTML 1.0 with inline CSS styling,
LaTeX, and mIRC chat client codes.
<h2>Example</h2>
<p>
Here's a little example of the HTML output:<br>
<pre> <u><font color=Green>module</font></u> Main <font color=Cyan>(</font>main<font color=Cyan>)</font> <u><font color=Green>where</font></u>
<u><font color=Green>import</font></u> Prelude
<font color=Blue>-- The notorious nfib "benchmark", but using Doubles.</font>
main <font color=Red>=</font> print <font color=Cyan>(</font>nfib <font color=Magenta>30</font><font color=Cyan>)</font>
nfib <font color=Red>::</font> Double <font color=Red>-></font> Double
nfib n <font color=Red>=</font> <u><font color=Green>if</font></u> n <font color=Cyan><=</font> <font color=Magenta>1</font>
<u><font color=Green>then</font></u> <font color=Magenta>1</font>
<u><font color=Green>else</font></u> nfib <font color=Cyan>(</font>n<font color=Cyan>`subtract`</font><font color=Magenta>1</font><font color=Cyan>)</font> <font color=Cyan>+</font> nfib <font color=Cyan>(</font>n<font color=Cyan>`subtract`</font><font color=Magenta>2</font><font color=Cyan>)</font> <font color=Cyan>+</font> <font color=Magenta>1</font>
</pre>
<h2>Download</h2>
<p>
<ul>
<li> Find it on <a href="http://hackage.haskell.org">Hackage</a>.
<li> Download a tarfile package from:
<a href="ftp://ftp.cs.york.ac.uk/pub/haskell/contrib/">
ftp://ftp.cs.york.ac.uk/pub/haskell/contrib/</a>
<a href="http://www.cs.york.ac.uk/fp/darcs/hscolour/hscolour-1.16.tar.gz">
http://www.cs.york.ac.uk/fp/darcs/hscolour/hscolour-1.16.tar.gz</a>
<a href="http://www.cs.york.ac.uk/fp/darcs/hscolour/hscolour-1.16.zip">
http://www.cs.york.ac.uk/fp/darcs/hscolour/hscolour-1.16.zip</a>
<li> Or use the <a href="http://darcs.net/">darcs</a> repository at<br>
<tt>darcs get http://www.cs.york.ac.uk/fp/darcs/hscolour</tt>
<li> Sources and history are browsable on-line through
<a href="http://www.cs.york.ac.uk/fp/darcs/">darcsweb</a>.
<li> An older Windows binary is available at
<a href="ftp://ftp.cs.york.ac.uk/pub/haskell/contrib/hscolour-1.3-win.zip">
ftp://ftp.cs.york.ac.uk/pub/haskell/contrib/hscolour-1.3-win.zip</a>
</ul>
<h2>Build</h2>
<p>
Just use one of the standard ways of building a Haskell program:
<ul>
<li><tt>cabal install hscolour</tt>
<li><tt>hmake HsColour</tt>
<li><tt>ghc --make HsColour</tt>
<li><tt>runhugs HsColour</tt>
<li><tt>runhaskell Setup.hs configure/build/install</tt>
</ul>
<h2>Use</h2>
<p>
<ul>
<li><pre>
HsColour [ -help | -version | -print-css ]
[ -oOUTPUT ]
[ -tty | -html | -css | -icss | -latex | -mirc ]
[ -lit | -lit-tex | -nolit ]
[ -anchor | -noanchor | -partial | -nopartial ]
[file.hs]*</pre>
</li></ul>
<p>
You can colourise a Haskell source file for either ANSI terminal codes
(option <tt>-tty</tt>), or HTML 3.2 with font tags (option
<tt>-html</tt>), or HTML 4.01 output with CSS (option <tt>-css</tt>), or
for XHTML 1.0 with inline CSS styling (option <tt>-icss</tt>), or for
LaTeX (option <tt>-latex</tt>), or for IRC (option <tt>-mirc</tt>). The
default is for terminal output.
<p>
If no file argument is given, it reads standard input. Output is
written to file OUTPUT (option -o), defaulting to stdout. Multiple input
files will be concatenated to the same output.
<p>
HsColour can add named anchors in HTML (option <tt>-anchor</tt>) to
top-level definitions in the source file (functions, datatypes,
classes). This enables you to make links to a specific location in the
generated file with the standard <tt>file.html#anchor</tt> notation
(e.g. from <a href="http://haskell.org/haddock">haddock</a>-generated
library documentation). <a href="#haddock">See below for details.</a>
<p>
If an input file is literate, that is, it has a suffix ".lhs" or ".ly"
or ".lx", then only the code fragments will be colourised, leaving the
commentary untouched. You can explicitly override this
filename-guessing of literate status: use the <tt>-lit</tt> option to
force literate colouring, or <tt>-nolit</tt> to force all text to be
colourised. (<tt>-lit-tex</tt> is an obsolete synonym for <tt>-lit</tt>)
<p>
For more advanced usage, if you are building documents in parts, and
you want to embed several individual colourised fragments into a
larger document, use the <tt>-partial</tt> option with each
fragment, to omit the HTML DOCTYPE header, CSS stylesheet link, or LaTeX
prologue.
<h2>Configuration of colours</h2>
<p>
If you use any output-format choice except <tt>-css</tt>, you can configure the
colours for different lexical entities by editing a configuration file
called <tt>.hscolour</tt> in the current directory.
(An <a href=".hscolour">example</a> is included in the distribution.)
For (non-inline) CSS output, it is sufficient to edit the
<a href="hscolour.css"><tt>hscolour.css</tt></a> file, also in the
distribution. (An alternative choice is supplied as
<a href="emacs.css"><tt>emacs.css</tt></a>.) The <tt>-print-css</tt> option
prints out the default CSS definitions, in case you lose the .css file.
<p>
The <tt>.hscolour</tt> file format is a simple Haskell value of type
ColourPrefs, constructed using named fields, as follows:
<pre> <u><font color=Green>data</font></u> ColourPrefs <font color=Red>=</font> ColourPrefs
<font color=Cyan>{</font> keyword<font color=Cyan>,</font> keyglyph<font color=Cyan>,</font> layout<font color=Cyan>,</font> comment
<font color=Cyan>,</font> conid<font color=Cyan>,</font> varid<font color=Cyan>,</font> conop<font color=Cyan>,</font> varop
<font color=Cyan>,</font> string<font color=Cyan>,</font> char<font color=Cyan>,</font> number <font color=Cyan>,</font> cpp
<font color=Cyan>,</font> selection<font color=Cyan>,</font> variantselection
<font color=Cyan>,</font> definition <font color=Red>::</font> <font color=Red>[</font>Highlight<font color=Red>]</font>
<font color=Cyan>}</font>
<u><font color=Green>data</font></u> Colour <font color=Red>=</font> Black <font color=Red>|</font> Red <font color=Red>|</font> Green <font color=Red>|</font> Yellow <font color=Red>|</font> Blue <font color=Red>|</font> Magenta <font color=Red>|</font> Cyan <font color=Red>|</font> White
<u><font color=Green>data</font></u> Highlight <font color=Red>=</font>
Normal
<font color=Red>|</font> Bold
<font color=Red>|</font> Dim
<font color=Red>|</font> Underscore
<font color=Red>|</font> Blink
<font color=Red>|</font> ReverseVideo
<font color=Red>|</font> Concealed
<font color=Red>|</font> Foreground Colour
<font color=Red>|</font> Background Colour
<font color=Red>|</font> Italic
</pre>
<p>
<h2>Use it as a library</h2>
If you want to incorporate hscolour-like functionality into your own
Haskell program, it is now (from 1.4) also available as a library,
thanks to Björn Bringert. The library is Cabal-ised, so just do
the usual thing to install it as a package:
<ul>
<li><tt>runhaskell Setup.hs configure</tt>
<li><tt>runhaskell Setup.hs build</tt>
<li><tt>runhaskell Setup.hs install</tt>
</ul>
There is
<a href="docs/hscolour/index.html">haddock documentation of the API</a>.
<p>
<a name="haddock"></a>
<h2>Using HsColour with Haddock</h2>
Let's say you want to generate some pretty-coloured HTML versions of
your source files, at the same time as you are generating library
documentation using <a href="http://haskell.org/haddock">Haddock</a>.
Haddock (0.8 onwards) has options to link the API docs to the source
code itself. Here is a quick summary of the shell commands to use:
<pre>
for file in $(SRCS)
do HsColour -html -anchor $file >docs/`dirname $file`/`basename $file .hs`.html
done
haddock --html --title="My Library" --odir=docs $(SRCS) \
--source-module="src/%{MODULE/.//}.html" \
--source-entity="src/%{MODULE/.//}.html#%{NAME}"
</pre>
<p>
<h2>Copyright and licence</h2>
<b>hscolour</b> is © Malcolm Wallace 2003-2009. It is distributed
under the Gnu GPL, which can be found in the file
<a href="LICENCE-GPL">LICENCE-GPL</a>.
<h2>Shortcomings</h2>
<p>
HsColour is not yet able to add anchors to class methods, nor to
<em>foreign</em> decls.
<h2>Alternatives</h2>
<p>
The <a href="http://www.cse.ogi.edu/~hallgren/Programatica/tools/pfe.cgi">
Programatica</a> project has a more sophisticated HTML
syntax-highlighter. It hyperlinks every usage of an identifier to its
definition, which is highly useful for browsing large amounts of code.
However, it is a more heavyweight solution as well - requiring the
entire front-end of a compiler not only to parse the Haskell code, but
to chase all its module dependencies as well. As a consequence, you need
source access to every definition used in your program, including the
Prelude and all library packages...
<h2>History</h2>
<p>
<dl>
<dt>1.16</dt><dd> deal with UTF-8 sources in ghc-6.12.x</dd>
<dt>1.15</dt><dd> makes -nopartial the default for literate files</dd>
<dt>1.14</dt><dd> merges the -lit and -lit-tex options, adds -lit guessing,
and permits multiple input files</dd>
<dt>1.13</dt><dd> added the new -icss output format, and italic highlights</dd>
<dt>1.12</dt><dd> changed the CSS class names to avoid clashes with other
web tools</dd>
<dt>1.11</dt><dd> new literate input option -lit-tex</dd>
<dt>1.10.1</dt><dd> reports the correct version with the --version flag</dd>
<dt>1.10</dt><dd> the title of HTML output is now the filename</dd>
<dt>1.9</dt><dd> added the -mirc and -lit options, and -print-css</dd>
<dt>1.8</dt><dd> added highlights for cpp lines
<br>tuple constructors now treated as ConIds
<br>checked for absence of pattern-match failure by Catch</dd>
<dt>1.7</dt><dd> renamed -anchorHTML -anchorCSS options to -anchor,
added -partial option</dd>
<dt>1.6</dt><dd> added -latex output mode</dd>
<dt>1.5</dt><dd> move generated HTML anchors to before comments/typesigs</dd>
<dt>1.4</dt><dd> made available as a Cabal-ised library</dd>
<dt>1.3</dt><dd> added HTML and CSS anchors</dd>
<dt>1.2</dt><dd> added CSS output mode (from Neil Mitchell)</dd>
<dt>1.1</dt><dd> fixed compatibility with ghc-6.4</dd>
<dt>1.0</dt><dd> first release</dd>
</dl>
<p>
This page last modified: 1st February 2010<br>
Malcolm Wallace<br>
</td></tr></table>
</body></html>