-------------------------------------------------------------------------------
---  HIGHLIGHT MANUAL - Version 3.9    --------------------------- May 2012 ---
-------------------------------------------------------------------------------

OSI Certified Open Source Software

Deutsche Anleitung: README_DE

CONTENT
-------------------------------------------------------------------------------

1. OVERVIEW
   1.1 INTENDED PURPOSE
   1.2 FEATURE LIST
   1.3 SUPPORTED PROGRAMMING AND MARKUP LANGUAGES

2. USAGE AND OPTIONS
   2.1 QUICK INTRODUCTION
   2.2 CLI OPTIONS
   2.3 GUI OPTIONS
   2.4 INPUT AND OUTPUT
   2.5 GNU SOURCE-HIGHLIGHT COMPATIBILITY
   2.6 ADVANCED OPTIONS
   2.7 TIPS AND TRICKS

3. CONFIGURATION
   3.1 FILE FORMAT
   3.2 REGULAR EXPRESSIONS
   3.3 LANGUAGE DEFINITIONS
   3.4 THEME DEFINITIONS
   3.5 KEYWORD GROUPS
   3.6 PLUG-INS
   3.7 FILE MAPPING

4. EMBEDDING HIGHLIGHT
   4.1 SAMPLE SCRIPTS
   4.2 SWIG INTERFACE
   4.3 THIRD PARTY SCRIPTS AND PLUG-INS

5. BUILDING AND INSTALLING
   5.1 PRECOMPILED PACKAGES
   5.2 BUILDING DEPENDENCIES
   5.3 PACKAGING EXAMPLE

6. DEVELOPER CONTACT


1. OVERVIEW
-------------------------------------------------------------------------------

Highlight converts sourcecode to HTML, XHTML, RTF, LaTeX, TeX, SVG, BBCode and
terminal escape sequences with coloured syntax highlighting.
Language definitions and colour themes are customizable.


1.1 INTENDED PURPOSE
-------------------------------------------------------------------------------

Highlight was designed to offer a flexible but easy to use syntax highlighter
for several output formats. Instead of hardcoded syntax or colouring
information, all relevant data is stored in configuration scripts. These
scripts may be altered or enhanced with plug-in scripts.


1.2 FEATURE LIST
-------------------------------------------------------------------------------

* highlighting of keywords, types, strings, numbers, escape sequences, comments,
  operators and preprocessor directives
* coloured output in HTML, XHTML 1.1, RTF, TeX, LaTeX, SVG, BBCode and terminal
  escape sequences
* supports referenced stylesheet files for HTML, LaTeX, TeX or SVG output
* syntax elements are defined as regular expressions or plain string lists
* customizable keyword groups
* recognition of nested languages within a file
* configuration files are Lua scripts
* supports plug-in scripts for language definitions and themes
* reformatting and indentation of C, C++, C# and Java source code
* wrapping of long lines
* output of line numbers


1.3 SUPPORTED PROGRAMMING AND MARKUP LANGUAGES
-------------------------------------------------------------------------------

Please see README_LANGLIST for the current set of supported languages.
You may also run "highlight --list-langs" to get a list of supported file
extensions.


2. USAGE AND OPTIONS
-------------------------------------------------------------------------------

2.1 QUICK INTRODUCTION
-------------------------------------------------------------------------------

The following examples show how to produce a highlighted C++ file, using an
input file called main.cpp:

- Generate HTML:
  highlight -i main.cpp -o main.cpp.html
  highlight < main.cpp > main.cpp.html --syntax cpp

  You will find the HTML file and highlight.css in the working directory.
  If you use IO redirection, you must define the programming language with
  --syntax.

- Generate HTML with embedded CSS definitions and line numbers:
  highlight -i main.cpp -o main.cpp.html --include-style --line-numbers

- Generate HTML with inline CSS definitions:
  highlight -i main.cpp -o main.cpp.html --inline-css

- Generate HTML using "horstmann" source formatting style and "neon" colour
  theme:
  highlight -i main.cpp -o main.cpp.html --reformat horstmann --style neon

- Generate LaTeX:
  highlight --out-format=latex -i main.cpp -o main.cpp.tex

  The following output formats may be defined with --out-format:
  html:     HTML 4.01
  xhtml:    XHTML 1.1
  tex:      Plain TeX
  latex:    LaTeX
  rtf:      RTF
  svg:      SVG
  bbcode:   BBCode
  ansi:     Terminal 16 color escape codes
  xterm256: Terminal 256 color escape codes

  Default output is HTML if no other format is specified.

- Customize font settings:
  highlight --syntax ada --out-format=xhtml --font-size 12 --font  Consolas,\'Courier\ New\'
  highlight --syntax ada --out-format=latex --font-size tiny --font sffamily

- Define an output directory:
  highlight -d some/target/dir/ *.cpp *.h

See "highlight --help" or "man highlight" for more details.


2.2 CLI OPTIONS
-------------------------------------------------------------------------------

The command line version of highlight offers following options:

USAGE: highlight [OPTIONS]... [FILES]...

General options:

 -B, --batch-recursive=<wc>     convert all matching files, searches subdirs
                                  (Example: -B '*.cpp')
 -D, --data-dir=<directory>     set path to data directory
     --add-config-dir=<dir>     set path to an additional config directory
     --config-file=<file>       set path to a lang or theme file
 -d, --outdir=<directory>       name of output directory
 -h, --help                     print this help
 -i, --input=<file>             name of single input file
 -o, --output=<file>            name of single output file
 -p, --list-langs               list installed language definitions
 -P, --progress                 print progress bar in batch mode
 -q, --quiet                    supress progress info in batch mode
 -S, --syntax=<type>            specify type of source code
 -v, --verbose                  print debug info
 -w, --list-themes              list installed colour themes
     --force                    generate output if input syntax is unknown
     --plug-in=<script>         execute Lua plug-in script; repeat option to
                                  apply multiple plug-ins
     --print-config             print path configuration
     --print-style              print stylesheet only (see --style-outfile)
     --skip=<list>              ignore listed unknown file types
                                  (Example: --skip='bak;c~;h~')
     --start-nested=<lang>      define nested language which starts input
                                  without opening delimiter
     --validate-input           test if input is text, remove Unicode BOM
     --version                  print version and copyright information


Output formatting options:

 -O, --out-format=<format>      output file in given format
                                  <format>=[html, xhtml, latex, tex,
                                  rtf, ansi, xterm256, bbcode, svg]
 -c, --style-outfile=<file>     name of style file or print to stdout, if
                                  'stdout' is given as file argument
 -e, --style-infile=<file>      file to be included in style-outfile
 -f, --fragment                 omit document header and footer
 -F, --reformat=<style>         reformats and indents output in given style
                                  <style>=[allman, banner, gnu,
                                  horstmann, java, kr, linux, otbs,
                                  stroustrup, whitesmith]
 -I, --include-style            include style definition
 -J, --line-length=<num>        line length before wrapping (see -W, -V)
 -j, --line-number-length=<num> line number width incl. left padding
 -k, --font=<font>              set font (specific to output format)
 -K, --font-size=<num?>         set font size (specific to output format)
 -l, --line-numbers             print line numbers in output file
 -m, --line-number-start=<cnt>  start line numbering with cnt (assumes -l)
 -s, --style=<style>            set colour style (see -w)
 -t, --replace-tabs=<num>       replace tabs by <num> spaces
 -T, --doc-title=<title>        document title
 -u, --encoding=<enc>           set output encoding which matches input file
                                  encoding; omit encoding info if enc=NONE
 -V, --wrap-simple              wrap long lines without indenting function
                                  parameters and statements
 -W, --wrap                     wrap long lines
 -z, --zeroes                   pad line numbers with 0's
     --kw-case=<case>           change case of case insensitive keywords
                                  <case> =  [upper, lower, capitalize]
     --delim-cr                 set CR as end-of-line delimiter (MacOS 9)
     --no-trailing-nl           omit trailing newline

(X)HTML output options:

 -a, --anchors                  attach anchor to line numbers
 -y, --anchor-prefix=<str>      set anchor name prefix
 -N, --anchor-filename          use input file name as anchor prefix
 -C, --print-index              print index with hyperlinks to output files
 -n, --ordered-list             print lines as ordered list items
     --class-name=<str>         set CSS class name prefix
     --inline-css               output CSS within each tag (verbose output)
     --enclose-pre              enclose fragmented output with pre tag
                                  (assumes -f)
     --ctags-file[=<file>]      read ctags file to include meta information as
                                  tooltips (default value: tags)

LaTeX output options:

 -b, --babel                    disable Babel package shorthands
 -r, --replace-quotes           replace double quotes by \dq{}
     --pretty-symbols           improve appearance of brackets and other symbols


RTF output options:

 -x, --page-size=<ps>           set page size
                                  <ps> = [a3, a4, a5, b4, b5, b6, letter]
     --char-styles              include character stylesheets


SVG output options:

     --height                   set image height (units allowed)
     --width                    set image width (see --height)


GNU source-highlight compatibility options:

     --doc                      create stand alone document
     --no-doc                   cancel the --doc option
     --css=filename             the external style sheet filename
     --src-lang=STRING          source language
 -t, --tab=INT                  specify tab length
 -n, --line-number[=0]          number all output lines, optional padding
     --line-number-ref[=p]      number all output lines and generate an anchor,
                                  made of the specified prefix p + the line
                                  number  (default='line')
     --output-dir=path          output directory
     --failsafe                 if no language definition is found for the
                                  input, it is simply copied to the output


2.3 GUI OPTIONS
-------------------------------------------------------------------------------

The Graphical User Interface offers a subset of the CLI's features. It includes
a dynamic preview of the output file's apperarance. Please see screenshots
and flash animations on the project website.


2.4 INPUT AND OUTPUT
-------------------------------------------------------------------------------

If no input or output file name is defined by --input and --output options,
highlight will use stdin and stdout for file processing.

If no input filename is defined by --input or given at the prompt, highlight is
not able to determine the language type by means of the file extension (but
some scripting languages are figured out by the shebang in the first input
line). In this case you have to pass highlight the given langage with --syntax
(this should be the file suffix of the source file in most cases).
Example: If you want to convert a Python file, highlight needs to load the
py.lang language definition. The correct argument of --syntax would be "py".
If you pass the filename directly to highlight, the program fetches the ".py"
extension from the file name.

highlight test.py
highlight < test.py --syntax py       # --syntax option necessary
cat test.py | highlight --syntax py

If there exist multiple suffixes (like C, cc, cpp, h for C++ - files),
you assign them to the matching language definition in the file
$CONF_DIR/filetypes.conf.

Highlight enters the batch processing mode if multiple input files are defined
or if --batch-recursive is set.
In batch mode, highlight will save the generated files with the original
filename, appending the extension of the chosen output type.
If files in the input directories happen to share the same name, the output
files will be prefixed with their source path name.
The --out-dir option is recommended in batch mode. Use --quiet to improve
performance (recommended for usage in shell scripts).

HTML, TeX, LaTeX and SVG output
-------------------------------

The HTML, TeX, LaTeX and SVG output formats allow to reference style definition
files which contain the formatting information (stylesheets).

In HTML and SVG output, this file contains CSS definitions and is saved as
'highlight.css'. In LaTeX and TeX, it contains macro definitions, and is saved
as 'highlight.sty'.

Name and path of the stylesheet may be modified with --style-outfile.
If the --outdir option is given, all generated output, including stylesheets,
are stored in this directory.

Use --include-style to embed the style information in the output documents
without referencing a stylesheet.

Referenced style definitions have the advantage to share all formatting
information in a single file, which affects all referencing documents.

With --style-infile you define a file to be included in the final formatting
information of the document. This way you enhance or redefine the default
highlight style definitions without editing generated code.

Terminal output:
----------------

Since there are limited colours defined for ANSI terminal output, there exists
only one hard coded colour theme with --out-format=ansi. You should therefore
use --out-format=xterm256 to enable output in 256 colours. The 256 colour mode
is supported by recent releases of xterm, rxvt and Putty (among others).

highlight --out-format=ansi <inputfile> | less -R
highlight --out-format=xterm256 <inputfile> | less -R

Text processing:
----------------

If the language definition is specified as "txt", no highlighting takes place.

highlight -S txt --out-format=latex README > README.tex


Examples
--------

The following commands write the content of hello.c to hello.html:

highlight -o hello.html -i hello.c
highlight -o hello.html hello.c
highlight -o hello.html --syntax c < hello.c
highlight --syntax c < hello.c > hello.html

Apart from hello.html, a file highlight.css is generated in the current working
directory.

highlight --out-format=xhtml  --batch-recursive '*.cpp' --outdir ~/html_code/
This command converts all *.cpp files in the current directory and its sub-
directories to xhtml files, and stores the output in /home/you/html_code.

highlight -out-format=latex  * --outdir /home/you/latex_code/
This command onverts all files to LaTeX, stored in /home/you/latex_code/.

highlight -c stdout -s seashell --print-style
This command prints only the CSS information to stdout (theme: Seashell).


2.5 GNU SOURCE-HIGHLIGHT COMPATIBILITY
-------------------------------------------------------------------------------

The command line interface is extensively harmonised with source-highlight
(http://www.gnu.org/software/src-highlite/).

The following highlight options have the same meaning as in source-highlight:
 --input, --output, --help, --version, --out-format, --title, --data-dir,
 --verbose, --quiet, --ctags-file

These options were added to enhance compatibility:
 --css, --doc, --failsafe, --line-number, --line-number-ref, --no-doc, --tab,
 --output-dir, --src-lang

These switches provide a common highlighter interface for scripts, plugins etc.


2.6 ADVANCED OPTIONS
-------------------------------------------------------------------------------

Adding Exuberant Ctags information
----------------------------------

HTML output can be enhanced with descriptive tooltips based on ctags data:
ctags *.*
highlight --ctags-file *.cpp

The default ctags-file parameter is "tags", so it is omitted in this example.
This command will add the type, namespace and definition file path of recognized
language tokens.
Example: "member | class:highlight::HtmlGenerator | htmlgenerator.h"

Prevent parsing of binary input files
-------------------------------------

If highlight could be invoked with all kinds of input, you can disable parsing
of binary files using --validate-input. This flag causes highlight to match the
input file header with a list of magic numbers. If a binary file type is
detected, highlight quits with an error message. This switch also removes an
UTF-8 BOM in the output.

Highlight nested code without starting delimiter
------------------------------------------------

If a file starts with an embedded code section which misses an appropriate opening
delimiter, the --start-nested option will switch to the nested language mode.
This can happen with LuaTeX files:
highlight luatex.tex --latex --start-nested=inc_luatex

The inc_luatex definition is a Lua language definition with TeX line comments.
Note that the nested code section has to end with the ending delimiter defined
in the host language definition.


2.7 TIPS AND TRICKS
-------------------------------------------------------------------------------

Test new configuration scripts:
-------------------------------

The option --config-file helps to test new config files before installing them.
The given file must be a lang or theme file.

highlight --config-file xxx.lang --config-file yyy.theme -I

Debug language definitions:
--------------------------

Use --verbose to display the Lua and syntax data.

Modify HTML line number formatting:
-----------------------------------

/* content of user.css */
 pre.hl {
   border-width: 1px;
   border-style:solid;
   border-left-color: silver;
   border-top-color: silver;
   border-right-color: gray;
   border-bottom-color: gray;
 }

 .hl.lin {
   border-right:1px solid #555555;
   padding-left:0.5em;
   padding-right:0.5em;
   margin-right:1em;
   text-decoration:none;
 }

Usage: highlight -l --style-infile user.css main.cpp

HTML list formatting tricks:
----------------------------

The following examples assume that HTML was generated as ordered list using
the --ordered-list switch. Include the CSS snippets with --style-infile.

/* highlight odd lines */
ol li:nth-child(odd) {
  background-color: #1f3030;
}

/* highlight every 5th line*/
ol li:nth-child(5n) {
  background-color: #1f3030;
}

/* highlight every 10th line number*/
ol li:nth-child(10n) {
  color: #ffff00;
}

Remove an UTF8 BOM:
-------------------

Use --validate-input to get rid of the UTF8 byte order mark.


3. CONFIGURATION
-------------------------------------------------------------------------------

3.1 FILE FORMAT
-------------------------------------------------------------------------------

The configuration files are Lua scripts. These constructs are sufficient to
edit the scripts:

Variable assigment:
name = value
(variables have no type, only values have)

Strings:
string1="string literal with escape: \n"
string2=[[raw string without escape sequence]]

If a raw string content starts with "[" or ends with "]", pad the paranthesis
with space to avoid a syntax error. Highlight will strip the string.

Comments:
-- line comment
--[[ block comment ]]

Arrays:
array = { first=1, second="2", 3, { 4,5 } }
Arrays may contain variables and can be nested.

Please refer to http://www.lua.org/manual/5.1/manual.html for more details
about the Lua syntax.

3.2 REGULAR EXPRESSIONS
-------------------------------------------------------------------------------

Please see README_REGEX for the supported regex constructs.


3.3 LANGUAGE DEFINITIONS
-------------------------------------------------------------------------------

A language definition describes all elements of a programming language which
will be highlighted by different colours and font types.
Save the new file in $HL_DIR/langDefs, using the following name convention:
<usual extension of sourcecode files>.lang

Examples: PHP -> php.lang, Java -> java.lang
If there exist multiple suffixes, list them in $HL_DIR/filetypes.conf.


Syntax elements:

Keywords = { Id, List|Regex, Group? }

  Id:    Integer, keyword group id (values 1-4, can be used for several keyword
	groups)
  List:  List, list of keywords
  Regex: String, regular expression
  Group: Integer, capturing group id of regular expression, defines part of regex
	which should be returned as keyword (optional; if not set, the match
	with the highest group number is returned (counts from left to right))


Comments = { {Block, Nested?, Delimiter={Open, Close?} }

  Block:     Boolean, true if comment is a block comment
  Nested:    Boolean, true if block comments can be nested (optional)
  Delimiter: List, contains open delimiter regex (line comment) or open and close
	    delimiter regexes (block comment)


Strings = { Delimiter|DelimiterPairs={Open, Close, Raw?}, Escape?, RawPrefix? }

  Delimiter:      String, regular expression which describes string delimiters
  DelimiterPairs: List, includes open and close delimiters if not equal (regex),
			includes optional Raw flag as boolean which marks
			delimiter pair to contain a raw string
  Escape:         String, regular expression of escape sequences (optional)
  RawPrefix:      String, defines raw string indicator (optional)


PreProcessor = { Prefix, Continuation? }

  Prefix:        String, regular expression which describes open delimiter
  Continuation:  String, contains continuation character (optional)


NestedSections = {Lang, Delimiter= {} }

  Lang:      String, name of nested language
  Delimiter: List, contains open and close delimiters of the code section


Description:       String, Defines syntax description

Digits:            String, Regular expression which defines digits (optional)

Identifiers:       String, Regular expression which defines identifiers
                   (optional)

Operators:         String,Regular expression which defines operators

EnableIndentation: Boolean, set true if syntax may be reformatted and indented

IgnoreCase:        Boolean, set true if keyword case should be ignored


Global variables:

The following variables are available within a language definition:

hl_lang_dir: path of language definition directory (use with Lua dofile function)

Identifiers: Default regex for identifiers
Digits:      Default regex for numbers

The following integer variables represent the internal highlighting states:

HL_STANDARD
HL_STRING
HL_NUMBER
HL_LINE_COMMENT
HL_BLOCK_COMMENT
HL_ESC_SEQ
HL_PREPROC
HL_PREPROC_STRING
HL_OPERATOR
HL_LINENUMBER
HL_KEYWORD
HL_STRING_END
HL_LINE_COMMENT_END
HL_BLOCK_COMMENT_END
HL_ESC_SEQ_END
HL_PREPROC_END
HL_OPERATOR_END
HL_KEYWORD_END
HL_EMBEDDED_CODE_BEGIN
HL_EMBEDDED_CODE_END
HL_IDENTIFIER_BEGIN
HL_IDENTIFIER_END
HL_UNKNOWN


Hook functions:

OnStateChange(oldState, newState, token, kwGroupID)

  Hook Event: Highlighting parser state change
  Parameters: oldState:  old state
              newState:  intended new state
              token:     the current token which triggered
	                 the new state
              kwGroupID: if newState is HL_KEYWORD, the parameter
                         contains the keyword group ID
  Returns:    Correct state to continue


Other functions:

AddKeyword(keyword, kwGroupID)

  Parameters: keyword:   string which should be added to a keyword list
              kwGroupID: keyword group ID of the keyword
  Returns:    true if successfull

Keywords added with AddKeyword will remain active for all files of the same
syntax if highlight is run in batch mode.

Example:
--------

Description="C and C++"

Keywords={
  {  Id=1,
   List={"goto", "break", "return", "continue", "asm", "case", "default",
         -- [..]
        }
  },
  -- [..]
}

Strings = {
  Delimiter=[["|']],
  RawPrefix="R",
}

Comments = {
   { Block=true,
     Nested=false,
     Delimiter = { [[\/\*]], [[\*\/]] }  },
   { Block=false,
     Delimiter = { [[//]] } }
}

IgnoreCase=false

PreProcessor = {
  Prefix=[[#]],
  Continuation="\\",
}

Operators=[[\(|\)|\[|\]|\{|\}|\,|\;|\.|\:|\&|\<|\>|\!|\=|\/|\*|\%|\+|\-|\~]]

EnableIndentation=true


3.4 THEME DEFINITIONS
-------------------------------------------------------------------------------

Colour themes contain the formatting information of the language elements which
are described in language definitions.

The files have to be stored as *.theme in HL_DIR/themes*.
Apply a theme with the --style option.


Format attributes:

Attributes = {Colour, Bold?, Italic?, Underline? }

Colour:    String, defines colour in HTML hex notation ("#rrggbb")
Bold:      Boolean, true if font should be bold (optional)
Italic:    Boolean, true if font should be italic (optional)
Underline: Boolean, true if font should be underlined (optional)


Theme elements:

Description:   String, Defines theme description

Default        = Attributes (Colour of unspecified text)

Canvas         = Attributes (Background colour )

Number         = Attributes (Formatting of numbers)

Escape         = Attributes (Formatting of escape sequences)

String         = Attributes (Formatting of strings)

PreProcessor   = Attributes (Formatting of preprocessor directives)

StringPreProc  = Attributes (Formatting of strings within
                            preprocessor directives)

BlockComment   = Attributes (Formatting of block comments)

LineComment    = Attributes (Formatting of line comments)

LineNum        = Attributes (Formatting of line numbers)

Operator       = Attributes (Formatting of operators)

Keywords= {
  Attributes1,
  Attributes2,
  Attributes3,
  Attributes4,
}

AttributesN: Formatting of keyword group N. There should be at least four items
             to match the number of keyword groups defined in the language
             definitions

Example:

Default        = { Colour="#000000" }
Canvas         = { Colour="#ffffff" }
Number         = { Colour="#000000" }
Escape         = { Colour="#bd8d8b" }
String         = { Colour="#bd8d8b" }
StringPreProc  = { Colour="#bd8d8b" }
BlockComment   = { Colour="#ac2020", Italic=true }
PreProcessor   = { Colour="#000000" }
LineNum        = { Colour="#555555" }
Operator       = { Colour="#000000" }
LineComment = BlockComment

Keywords = {
  { Colour= "#9c20ee", Bold=true },
  { Colour= "#208920" },
  { Colour= "#0000ff" },
  { Colour= "#000000" },
}


3.5 KEYWORD GROUPS
-------------------------------------------------------------------------------

You may define custom keyword groups and corresponding highlighting styles.
This is useful if you want to highlight functions of a third party library,
macros, constants etc.

You define a new group in two steps:

 1. Define a new group in your language definition (lang file):

    Keywords = {
      -- add your keyword description:
      {Id=5, List = {"ERROR", "DEBUG", "WARN"} }
    }

 2. Add a corresponding highlighting style in your colour theme (theme file):

    Keywords= {
      --add your keyword style as 5th item in the list:
      { Colour= "#ff0000", Bold=true },
    }

It is recommended to define keyword groups in user-defined plugin scripts to
avoid editing of original highlight files.
See the PLUG-IN SCRIPT section for details.


3.6 PLUG-INS
-------------------------------------------------------------------------------

The --plug-in option receives the path of a Lua script which overrides or
enhances the settings of theme and language definition files. Using plug-ins,
it is possible to apply costum settings without the need to edit installed
configuration files.
You can apply multiple plugins by using the --plug-in option more than once.

Format:

-- function definitions, variables etc

-- Plugin list:
Plugins={
  { Type, Chunk },
}

Type:  String, is one of ["theme", "lang"]
Chunk: Name of Lua function

If type is "theme", the chunk will applied to the colour theme.
If type is "lang", the chunk will applied to the language definition.

The chunk function will receive an optional parameter will contain a string
with the description of the theme or language ("Description" parameter).
The chunks are interpreted after the theme or lang file were loaded, so you
can refer to elements defined in these files.

The function AddKeyword can be invoked within a "lang" chunk.
If OnStateChange is defined as local function within the chunk, this hook
will become active. A predefined OnStateChange function of the language
definition will be overriden.


Example:

Description="Add syslog and kernel log levels to C and C++ keywords"

-- function to update language definition with syslog levels
function syntaxUpdate(desc)
  if desc=="C and C++" then
    table.insert( Keywords,
                  { Id=5, List={"LOG_EMERG", "LOG_CRIT", "LOG_ALERT",
                    "LOG_ERR", "LOG_WARNING","LOG_NOTICE","LOG_INFO",
                    "LOG_DEBUG"}
                  } )
  end
end

-- function to update theme definition
function themeUpdate(desc)
  if desc=="Kwrite Editor" then
    Canvas={ Colour="#E0EAEE" }
  end
  table.insert(Keywords, {Colour= "#ff0000", Bold=true})
end

Plugins={
  { Type="theme", Chunk=themeUpdate },
  { Type="lang", Chunk=syntaxUpdate },
}

See README_PLUGINS for a detailed description.


3.7 FILE MAPPING
-------------------------------------------------------------------------------

The script filetypes.conf assigns file extensions and shebang descriptions to
language definitions.

Format:

FileMapping={
  {  Lang, Extensions|Shebang },
}

Lang:       String, name of language definition
Extensions: list of strings, contains file extensions referring to "Lang"
Shebang:    String, Regular expression which matches the first line of the input
            file

Edit the file gui_files/ext/fileopenfilter.conf to add new syntax types to
the GUI's file open filter.


4. EMBEDDING HIGHLIGHT
-------------------------------------------------------------------------------

4.1 SAMPLE SCRIPTS
-------------------------------------------------------------------------------

See the /examples subdirectory in the highlight source directory for some
example scripts in PHP, Perl and Python  which invoke highlight and retrieve
its output as string. These scripts may be used to develop plug-ins for other
applications.

4.2 SWIG INTERFACE
-------------------------------------------------------------------------------

A SWIG interface file is located in /examples/swig.
See README_SWIG for installation instructions and the example scripts as
programming reference.


4.3 THIRD PARTY SCRIPTS AND PLUG-INS
-------------------------------------------------------------------------------

See the /examples/web_plugins subdirectory in the highlight installation for
some plugins which integrate highlight in Wiki and blogging software:

-DokuWiki
-MovableType
-Wordpress
-Serendipity

Other uses of highlight can be found online:

MediaWiki plugin
http://www.mediawiki.org/wiki/Extension:ASHighlight

MacOS X Quicklook plugin
http://code.google.com/p/qlcolorcode/

CamlHighlight (Ocsigen extension)
http://camlhighlight.forge.ocamlcore.org/

highlighter package for the R language
http://cran.r-project.org/web/packages/highlight/index.html

Inkscape plug-in
http://xico.freeshell.org/inksyntax/index.html


5. BUILDING AND INSTALLING
-------------------------------------------------------------------------------

5.1 PRECOMPILED PACKAGES
-------------------------------------------------------------------------------

Highlight is written in ISO C++. The following packages are available:
- UNIX console  and GUI application
- W32 console and GUI application
- statically and dynamically linked library

The website www.andre-simon.de offers links to precompiled packages for several
operating systems (like Debian, Arch Linux, Ubuntu, Darwin, FreeBSD).
The website distributes the latest upstream sources.
Threre is also a Sourceforge project available:
http://sourceforge.net/projects/syntaxhighlight/

Source tarball
Windows W32 executables
http://www.andre-simon.de

Arch Linux
http://www.archlinux.org/packages/community/i686/highlight/

Debian GNU/Linux
http://packages.debian.org/unstable/devel/highlight

Fedora
http://koji.fedoraproject.org/koji/packageinfo?packageID=2044

FreeBSD
http://www.freshports.org/textproc/highlight/

Gentoo Portage
http://www.gentoo-portage.com/app-text/highlight

Mac OS X
http://www.hmug.org/pub/MacOS_X/BSD/Applications/Text/highlight/

Slackware
http://sotirov-bg.net/slackpack/search.cgi?q=highlight

SuSE
http://packman.links2linux.de/package/highlight

Ubuntu
http://packages.ubuntu.com/oneiric/allpackages

The file INSTALL contains details about package contents and installation.


5.2 BUILDING DEPENDENCIES
-------------------------------------------------------------------------------

Highlight is known to compile with gcc and suncc.
It depends on Boost headers and Lua 5.1 developer packages.
The optional GUI depends on Qt4 developer packages.
Please see the makefile for further options.

5.3 PACKAGING EXAMPLE
-------------------------------------------------------------------------------

See http://andre-simon.de/dokuwiki/doku.php?id=packaging_resources for
Debian and Fedora packaging examples.


6. DEVELOPER CONTACT
-------------------------------------------------------------------------------

Andre Simon
andre.simon1@gmx.de
as@andre-simon.de
http://www.andre-simon.de/

http://wiki.andre-simon.de/
Because of repeated spamming abuse, you have to login to edit pages.
Wiki login: User "user", Password "h1gHL1te"

sf.net project with SVN repository, download mirror, bug tracker, help forum:
http://sourceforge.net/projects/syntaxhighlight/