packages feed

hscolour-1.6: 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 four output formats: ANSI terminal codes, HTML with
&lt;font&gt; tags, HTML with CSS, and LaTeX.

<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>-&gt;</font> Double
    nfib n <font color=Red>=</font> <u><font color=Green>if</font></u> n <font color=Cyan>&lt;=</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> 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>
<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> A 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>hmake HsColour</tt>
<li><tt>ghc --make HsColour</tt>
<li><tt>runhugs HsColour</tt>
</ul>

<h2>Use</h2>
<p>
<ul>
<li><tt>HsColour [ -tty | -html | -css | -latex | -anchorHTML | -anchorCSS ] [file.hs]</tt>
</ul>
<p>
You can colourise a Haskell source file for either ANSI terminal codes
(option -tty), or HTML with font tags (option -html), or HTML output
with CSS (option -css), or for LaTeX.  The default is for terminal output.
<p>
If no file argument is given, it reads standard input.  Output is
always written to standard output.
<p>
HsColour can add named anchors (options -anchorHTML or -anchorCSS) 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>


<h2>Configuration of colours</h2>
<p>
If you use either -html, -tty, or -latex, 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 CSS output, it is sufficient to edit the
<a href="hscolour.css"><tt>hscolour.css</tt></a> file, also in
the distribution.

<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> selection<font color=Cyan>,</font> variantselection <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
</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&ouml;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 (1.8 onwards, currently only available in darcs) 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 -anchorHTML $file &gt;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 &copy; Malcolm Wallace 2003-2006.  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.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: 21st December 2006<br>
Malcolm Wallace<br>

</td></tr></table>
</body></html>