Literate HS to TeX Highlighter Helper
=====================================

Hi there,

welcome to the lhs2TeX-hl readme. lhs2TeX-hl is a tool for generating
formatting rules used by lhs2TeX. This tool is to be used in combination with
lhs2TeX. 


It aims to detect the `kind' of an identifier either by it's use or it's
declaration. Trying to detect both local declarations and usages.

Regards,
Alessandro Vermeulen

INSTALLING
----------

* Make sure you have cabal installed and run

  cabal install lhs2TeX-hl
  
* Or download the latest release from:
    http://hackage.haskell.org/package/lhs2TeX-hl
  and install in the standard way.

* Or visit the github page:
    https://github.com/spockz/lhs2texhl

USAGE or HOW-TO
---------------
Using lhs2TeX-hl is very simple. Just pass it your Haskell source file and it
will automatically generating formatting directives for you. Including but not
limited to formatting directives for data constructors and functions. Currently
`functions' that are strictly constants are not highlighted as functions.

----
lhs2TeX-hl -o <filename>.fmt <filename>.lhs
----

For more details see:

----
lhs2TeX-hl --help
----

Currently this is the only way to work with the tool.

In your .lhs file include the generated formatting files, like this:

----
%include polycode.fmt
%include <filename>.fmt
----

After this you'll need to provide the following LaTeX commands yourself:

* \lhsCHsyntax 
* \lhsCHkeyword
* \lhsCHprelude
* \lhsCHtype
* \lhsCHconstructor
* \lhsCHfunction
* \lhsCHinfixoperator
* \lhsCHclass

Check out the ./examples directory and the examples section for example themes.

This tool only generates formatting directives for identifiers (including
operators) for you. If you want to change the formatting of characters,
strings or literal numbers add the following directives:

----
%subst char a     = "\color{char}\text{\tt ''" a "''}"
%subst string a   = "\color{string}\text{\tt \char34 " a "\char34}"
%subst numeral a  = "\color{numeral}{ " a " }"
----

For other available substitutions consult the lhs2TeX manual.

Automatic markup
~~~~~~~~~~~~~~~~
For your convenience there are some automatic rewrites being done.

* If a identifier names in a sequence of digits, the digits will be
  typeset in subscript.
* If you have trailing underscores they will be omitted in the typesetting.
  This is so you can do something like:

  -----
    data Foo = Foo_ a;
  -----
  
  And have Foo highlighted as a type constructor, and Foo_ highlighted as
  `Foo' in a data constructor colour. 
  
* If there are underscores in the middle of your identifier, everything
  after the underscores will be typeset in subscript.

THEMES
------

emacs
~~~~~
[source, latex]
--------------------------------------------------------------------------------
% use package color
\definecolor{syntax}{RGB}{0, 0, 0}
\definecolor{datatype}{RGB}{196, 6, 11}
\definecolor{class}{RGB}{168,37,39}
\definecolor{fieldname}{RGB}{0,0,162}
\definecolor{prelude}{RGB}{64,80,117}
\definecolor{numeral}{RGB}{0,0,205}
\definecolor{infixoperator}{RGB}{19, 19, 168}
\definecolor{constructor}{RGB}{196, 6, 11}
\definecolor{keyword}{RGB}{4, 58, 252}
\definecolor{special1}{RGB}{159,138,0}
\definecolor{string}{RGB}{3, 106, 7}
\definecolor{char}  {RGB}{3, 106, 7}

\newcommand{\lhsCHsyntax}[1]{\color{syntax}{{#1}}}
\newcommand{\lhsCHfunction}[1]{\color{infixoperator}{{#1}}}
\newcommand{\lhsCHinfixoperator}[1]{\color{infixoperator}{{#1}}}
\newcommand{\lhsCHprelude}[1]{\color{prelude}{\mathbf{#1}}}
\newcommand{\lhsCHkeyword}[1]{\color{keyword}{\textbf{#1}}}
\newcommand{\lhsCHconstructor}[1]{\color{constructor}{\textbf{#1}}}
\newcommand{\lhsCHtype}[1]{\color{datatype}{{#1}}}
\newcommand{\lhsCHclass}[1]{\color{class}{{#1}}}

%subst char a    = "\color{char}\text{\tt ''" a "''}"
%subst string a  = "\color{string}\text{\tt \char34 " a "\char34}"
%subst numeral a = "\color{numeral}{ " a " }"
--------------------------------------------------------------------------------

KNOWN ISSUES
------------

* Infix operators may not work that great, or normal functions that are used
  `infix`. Sometimes you might get an `ambiguous infix operator' error.
* AGDA isn't supported yet unfortunately.
* Errors aren't that informative. :)

CHANGES
-------
0.1.3.3::
  * Fixed build error + cabal things
0.1.3.2::
  * Removed the MissingH dependency.
0.1.3.1::
  * Added the file Language.Markup
0.1.3.0::
  * Added automatic rewrite rules, see section `Automatic markup'.
0.1.2.2::
  * And classes are now also written to the output file, somewhere I was
    sleeping during all this. :)
0.1.2.1::  
  * Fixed a regression, detection of language pragmas was apparently broken and
    now they aren't anymore.
0.1.2.0::
  * Hopefully the ``ambiguous infix operator'' error shouldn't occur that often
    anymore.
  * Removed the AGDA dependency for until it actually works.
  * Classes are now detected.