--------------------------------------------------------------------------------
---  HIGHLIGHT MANUAL - Version 2.2-6 ------------------------ NOVEMBER 2004 ---
--------------------------------------------------------------------------------

OSI Certified Open Source Software

Deutsche Anleitung: README_DE

--------------------------------------------------------------------------------

Highlight converts sourcecode to HTML, XHTML, RTF, LaTeX, TeX or XSL-FO files
with syntax highlighting. Its language definitions, colour themes and
indentation schemes are customizable.


CONTENT:
--------------------------------------------------------------------------------

0.  Quick introduction
1.  Platforms
2.  Supported programming/markup languages
3.  Features
4.  User instructions
5.  Highlight file format
6.  Defining new language definitions
7.  Defining new colour themes
8.  Defining new indentation schemes
9.  Defining new keyword groups
10. Configuration file
11. Scripts
12. Python binding
13. Contact


0.  Quick introduction
--------------------------------------------------------------------------------

The following examples show how to produce a highlighted C++ file (main.cpp).

- Generate HTML with external CSS definition:
  highlight -i main.cpp -o main.cpp.html
  or
  highlight < main.cpp > main.cpp.html -Sc

  You will find the HTML file and a file highlight.css in the working dir.
  If you use IO redirection, you have to define the syntax type with -S.

- Generate HTML with internal CSS definition and line numbers:
  highlight -i main.cpp -o main.cpp.html -I -l

- Generate HTML using "ANSI" source formatting style and "neon" colour theme:
  highlight -i main.cpp -o main.cpp.html -F ansi -s neon

- Generate LaTeX:
  highlight -L -i main.cpp -o main.cpp.html

  Other output formats are XHTML (-X), TeX (-T), RTF (-R), XSL-FO (-Y), ANSI (-A).
  HTML is the default output format.

- Define a target directory:
  highlight -O some/target/dir/ *.cpp *.h

Type highlight --help or see chapter 3 for more details.


1. PLATFORMS:
--------------------------------------------------------------------------------

Highlight is written in ISO C++. There exist three versions:
- UNIX console application
- W32 console application
- W32 GUI application

The source package is known to compile with gcc3.x, MS Visual .NET, and MW
Codewarrior 8.


2. SUPPORTED PROGRAMMING / MARKUP LANGUAGES:
--------------------------------------------------------------------------------

Currently, highlight supports the following programming languages, markup
languages and configuration files:

Action Script, ADA 95, Agda, AMPL, Aspect, Assembler, Amtrix, Avenue, (G)AWK,
Bash, BlitzBasic, BibTex, BMS, C, C++, C#, ClearBasic, Clipper, Cobol, Coldfusion
MX, CSS, DOS-Batch, Eiffel, Erlang, Euphoria, Express, Felix, Fortran, Frink,
Haskell, HTML, httpd.conf, Icon, IDL, INI, IO, Jasmin, Java, JavaScript, JSP,
LaTeX, LDIF, Lisp, Lotos, Lotus Script, Lua, Make,Maya, Matlab, Maple, Modelica,
Modula 3, Nasal, OCaml, (Object) Pascal, Objective C, Paradox, PATROL, Perl,
PHP, Pike, PL/1, PL/SQL, PostScript, POV Ray, Progress, Prolog, Python, Relax
NG Compact, Rexx, RPM Spec, Ruby, Small, SML, SNMPv2, Spin, Squirrel, Sybase,
VHDL, Visual Basic, XML.


3. FEATURES:
--------------------------------------------------------------------------------

- highlighting of keywords, types, strings, numbers, escape sequences, comments,
  symbols and directive lines
- highlighting of custom keyword classes
- coloured output in HTML, XHTML 1.1, RTF, TeX, LaTeX or XSL-FO format
- customizable reformatting and indentation of C, C++, C# and Java source code
- wrapping of long lines
- output of line numbers
- choice to embed the CSS-definitions in the output (X)HTML file or to save them
  in a separate CSS-file
- customizable colour themes
- recursive batch processing of directories
- conversion of plain text to a given output format without highlighting


4. USER INSTRUCTIONS:
--------------------------------------------------------------------------------

You can get the help screen by typing highlight -h:

 USAGE: highlight [afghlpqrvwzACEILPRTXYVWZ] [-i input file] [-o output file]
                  [-S syntax] [-O outdir] [-B wildcard]
                  [-t num] [-c css_outfile] [-e css_infile] [-s CSS_style]
                  [-D new data dir] [-E data dir] [input files]


 General options:

 -B, --batch-recursive=<wc>     convert all matching files in current directory
                                and its subdirectories
                                (Example: highlight -b '*.cpp')
 -D, --data-dir=<directory>     set path to data directory
 -E, --add-data-dir=<directory> set path to an additional data directory, which
                                is searched first
 -h, --help                     print this help
 -H, --help-int=<lang>          print help in given language
                                <lang> = ["en", "de", "es", "fr"]
 -i, --input=<file>             name of single input file
 -o, --output=<file>            name of single output file
 -O, --outdir=<directory>       name of output directory
 -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
     --version                  print version and copyright information


 Output formats:

 -A, --ansi                     generate ANSI terminal control sequences
 -L, --latex                    generate LaTeX file
 -R, --rtf                      generate RTF file
 -T, --tex                      generate TeX file
 -X, --xhtml                    generate XHTML 1.1 file
 -Y, --xsl-fo                   generate XSL-FO file (experimental)
 -Z, --xml                      generate XML file


 Output formatting options:

 -f, --fragment                 omit file header and footer
 -F, --format-style=<style>     reformat and indent output in given style
                                <style> = ["ansi", "gnu", "java", "kr", "linux"]
 -l, --linenumbers              print line numbers in output file
 -s, --style=<style>            specify colour style which should be applied
 -t, --replace-tabs=<num>	replace tabs by <num> spaces
 -V, --wrap-simple              wrap long lines without indenting function
                                parameters and statements
 -W, --wrap                     wrap long lines
 -z, --zeroes                   fill leading space of line numbers with 0's


 (X)HTML output options:

 -a, --anchors                  attach anchor to line numbers
 -c, --css-outfile=<file>       name of CSS definition file
 -C, --print-index              print index file with hyperlinks to output files
 -e, --css-infile=<file>        file to be included in css-outfile
 -I, --include-css              include CSS definition


 LaTeX output options:

 -r, --replace-quotes           replace double quotes by \dq{} (assumes -f)


 XSL-FO output options:

 -g, --fop-compatible           generate FO for Apache FOP (see README)

 -t will be ignored if -F is set.
 -i and -o will be ignored if -b or -B is set.
 -r will be ignored if -f is not set.
 If no in- or output files are specified, stdin and stdout will be used for
 in- or output.
 HTML will be generated, if no other output format is given.
 CSS definitions are stored in highlight.css if neither -c nor -I is given.
 Reformatting code will only work with C, C++, C# and Java input files.
 Wrapping lines with -V or -W will cause faulty highlighting of long single
 line comments and directives. Use with caution.


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 -S c < hello.c
highlight -S c < hello.c > hello.html

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

If no input filename is given, you have to pass highlight the usual file suffix
of the sourcecode file by -S. Example: If you want to convert a Python file,
highlight looks after the py.lang file. The correct parameter of -S would be
"py". If you pass the filename directly to highlight, the program fetches the
.py extension, but if you use IO-redirection, the -S parameter is required.

If there exist multiple suffixes (like C, cc, cpp, h with C++ - files),
highlight tries to fetch the matching language definition file (see the file
extensions.conf in the highlight directory*).

In batch mode, highlight will save the generated files with the original
filename, appending .html, .xhtml, .rtf, .tex or .fo, according to the chosen
output type. The -O option is useful with -b. Use --quiet to improve performance
(recommended for usage in shell scripts).

Example:
--------

highlight -X  -B '*.cpp' -O /home/you/html_code/
converts all *.cpp files in the current directory and its subdirectories to
xhtml files, and stores the output in /home/you/html_code.

highlight -L  * -O /home/you/latex_code/
converts all files to LaTeX, stored in /home/you/latex_code/.


Concerning (X)HTML output:
---------------------

The (X)HTML output is formatted by Cascading Style Sheets (CSS).
The CSS definitions may be stored in an external file, which is referenced by
the generated HTML code, or it can be included in the HTML output (--include-css
option). The usage of referenced CSS definitions has the advantage to have all
formatting information in a central place, which affects all referencing HTML
files.
If highlight is invoked without --include-css, a file highlight.css is written
to the current working directory, and a link to "highlight.css" is included in
HTML output. Name and path of the CSS file may be modified with --css-outfile.
The --css-infile option defines another CSS file to be included in the final CSS
definition.
If the --outdir option is given, all generated output, including CSS files, is
stored in that directory.


Concerning XSL-FO output:
--------------------

XSL-FO output is experimental. The current output is compatible with Apache
FOP and xsltproc/xmlto, but there are still problems:

 *xsltproc and xmlto*

 Version xsltproc:
 Using libxml 20604, libxslt 10102 and libexslt 802
 xsltproc was compiled against libxml 20604, libxslt 10102 and libexslt 802
 libxslt 10102 was compiled against libxml 20604
 libexslt 802 was compiled against libxml 20604

 Version xmlto: 0.0.18

 Problem: The generated files are big, processing takes long.


 *Apache FOP*

 Version: 0.20.5

 FO output will be modified for FOP with the --fop-compatible option.
 Problem: There is a bug in FOP, which causes empty lines after line breaks.

 Statement from the Apache site:
 "Due to a bug in current versions of FOP, setting white-space-collapse='false'
  will also preserve line breaks in the text. Do not rely on this behavior, as
  it is non-conformant and will be changed."


Concerning RTF output:
-----------------

RTF always uses white background colour.


Concerning ANSI escape output:
------------------------

You can browse source code comfortably in a terminal with the command
highlight -A <inputfile> | less -R
Since there are limited colours defined for terminal output, there exists only
one hard coded colour theme.


Concerning text processing:
----------------------

If the language definition is specified as txt, no highlighting takes place, the
input file is converted to the given output format.

Example:

highlight -S txt -L README > README.tex


5. HIGHLIGHT FILE FORMAT
--------------------------------------------------------------------------------

All Highlight configuration files are stored in plain ASCII text files. The
format is simple:

$ParamName=ParamValue

ParamName is the identifier of the parameter, ParamValue is its value.
The parameter names are not case sensitive.
The value may be a single character or a list of words. Lists may be split in
multiple lines.

Comments start with # as the first character in a line.


6. DEFINING NEW LANGUAGE DEFINITIONS:
--------------------------------------------------------------------------------

A language definition is a text file, where keywords and symbols of a program-
ming language are assigned to several categories.
Save the new file in DATADIR/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 DATADIR/extensions.conf*.

FILE FORMAT:

# List of keywords; <class> is the name of the keyword class
# The class must be defined in the applied colour theme to provide a matching
# highlighting style
$KW_LIST(<class>)=<List>

# Prefix which determines keywords
# The class must be defined in the applied colour theme to provide a matching
# highlighting style
$KW_PREFIX(<class>)=<Character>

# Delimiters for keywords
# The class must be defined in the applied colour theme to provide a matching
# highlighting style
$KW_DELIM(<class>)=<open close>

# Tag open and close delimiters
# Tags are formatted like keywords of specified class
$TAG_DELIM(<class>)=<tag_open tag_close>

# List of String delimiters
$STRINGDELIMITERS=<List>

# List of escape characters in Strings (ie. "\")
$ESCCHAR=<List>

# List of escape characters which may occour outside of strings
$ESCCHAR_EXT=<list>

# Prefix which disables highlighting of escape characters within a string
$RAWSTRINGPREFIX=<Character>

# Delimiters of multi line comments
$ML_COMMENT=<comment_begin comment_close>

# List of strings which start single line comments
$SL_COMMENT=<List>

# Set true if single line comments have to start in first coloumn
$FL_COMMENT=<true / false>

# Opening string of preprocessor directive lines
$DIRECTIVE=<prefix>

# Character which continues a compiler directive after a line break
$CONTINUATIONSYMBOL=<symbol>

# Set true if language source code may be reformatted (only C-style languages!)
$REFORMATTING=<true / false>

# Symbols (brackets or operators)
$SYMBOLS=<List>

# List of special characters which may occour in keywords
$ALLOWEDCHARS=<character list>

# Set to true if multiple line comments may be nested
$ALLOWNESTEDCOMMENTS=false

# Set to true if programming language is not case sensitive
$IGNORECASE=<true / false>

# Include another language definition stored in the same data directory
$INCLUDE=<language definition>


Example:

#Content of pas.lang (Pascal/Objekt Pascal)

$KW_LIST(kwa)=true false if else then nil maxint case goto label and div downto in
mod not of or packed with do for do repeat while to until procedure function
program begin end const var type unit interface implementation uses private
public

$KW_LIST(kwb)=array boolean char integer file pointer real set string text record

$STRINGDELIMITERS=" '
$SL_COMMENT=//
$ML_COMMENT={ }
$IGNORECASE=true

HINT: If you do not want to save new language definitions in the default
      installation directory (DATADIR), you can pass highlight another search
      path with the --add-data-dir option.


7. DEFINING NEW THEME DEFINITIONS
--------------------------------------------------------------------------------

Colour themes are stored in plain ASCII files, defining the formatting of the
output. The RTF output ignores the background colour attribute. The files have
to be stored as *.style in DATADIR/themes*. You can apply a style with the
-s option.

FILE FORMAT:

#<ColourAttr> = RR GG BB
#RR GG BB describes the red/green/blue hex-values which define the colour.
#(Value range: 00 (none) - FF (full))

#<FormatAttr> = <bold> <italic> <underline>
#Bold, italic und underline are optional attributes and may be combined.


# Colour of unrecognized text
$DEFAULTCOLOUR=<ColourAttr>

# Background colour (ignored by RTF output)
$BGCOLOUR=<ColourAttr>

# Font size
$FONTSIZE=<number>

# Formatting of keywords, which belong to the corresponding keyword class
$KW_CLASS(<class>)=<ColourAttr> ( <FormatAttr> )

# Formatting of numbers
$NUMBER=<ColourAttr> ( <FormatAttr> )

# Formatting of escape characters
$ESCAPECHAR=<ColourAttr> ( <FormatAttr> )

# Formatting of strings
$STRING=<ColourAttr> ( <FormatAttr> )

# Formatting of strings within compiler directives
$STRING_DIRECTIVE=<ColourAttr> ( <FormatAttr> )

# Formatting of comments
$COMMENT=<ColourAttr> ( <FormatAttr> )

# Formatting of single line comments
$SL-COMMENT=<ColourAttr> ( <FormatAttr> )

# Formatting of compiler directives
$DIRECTIVE=<ColourAttr> ( <FormatAttr> )

# Formatting of symbols (optional, equals to $DEFAULTCOLOUR if omitted)
$SYMBOL=<ColourAttr> ( <FormatAttr> )

# Formatting of line numbers
$LINE=<ColourAttr> ( <FormatAttr> )


Example:

# Golden.style
$DEFAULTCOLOUR=dd bb 00
$BGCOLOUR=00 00 00
$FONTSIZE=10
$KW_CLASS(kwa)=dd bb 00 bold
$KW_CLASS(kwb)=dd bb 00
$NUMBER=ff ff ff
$ESCAPECHAR=ff 00 00
$STRING=ff 00 00
$STRING_DIRECTIVE=ff 00 00
$COMMENT=97 83 45 italic
$DIRECTIVE=ff dd aa
$LINE=97 83 45


8.  DEFINING NEW INDENTATION SCHEMES
--------------------------------------------------------------------------------

You can define custom indentation and formatting schemes. To enable reformatting
for your programming language, a $REFORMATTING=true switch has to be added to
the language definition. Note that the Artistic Style parser was designed to
only handle C-style languages (C++, Java, C#) correctly.
Indentation schemes are stored as *.indent in DATADIR/indentSchemes*.
Apply your scheme with the option --format-style.

FILE FORMAT:

# Brackets handling:
# "break":  Break brackets from pre-block code (i.e. ANSI C/C++ style).
# "attach": Attach brackets to pre-block code (i.e. Java/K&R style).
# "linux":  Break definition-block brackets and attach command-block brackets.
# "break-closing-headers": Break brackets before closing headers (e.g. 'else',
#                          'catch', ..).  Should be appended to $brackets=attach
#                          or $brackets=linux.
$BRACKETS=<break | attach | linux | break-closing-headers>

# Insert empty lines around unrelated blocks, labels, classes, ...
# "true": default mode
# "all": also insert empty lines around closing headers
#        (e.g. 'else', 'catch', ...).
$BREAK-BLOCKS=<true | false | all>

# Break 'else if()' statements into two different lines.
$BREAK-ELSEIFS=<true / false>

# Add extra indentation entire blocks (including brackets).
$INDENT-BLOCKS=<true / false>

# Add extra indentation to '{' and '}' block brackets.
$INDENT-BRACKETS=<true / false>

# Indent 'case XXX:' lines, so that they are flush with
# their bodies.
$INDENT-CASES=<true / false>

# Indent 'class' blocks, so that the inner 'public:', 'protected:' and 'private:'
# headers are indented in relation to the class block.
$INDENT-CLASSES=<true / false>

# Indent labels so that they appear one indent less than the current indentation
# level, rather than being flushed completely to the left (which is the default).
$INDENT-LABELS=<true / false>

# Indent the contents of namespace blocks.
$INDENT-NAMESPACES=<true / false>

# Indent multi-line #define statements
INDENT-PREPROCESSOR=<true / false>

# Indent using <num> spaces per indent. Not specifying <num>  will result in a
# default  of 4 spacec per indent.
$INDENT-SPACES=<num>

# Indent 'switch' blocks, so that the inner 'case XXX:' headers are indented in
# relation to the switch block.
$INDENT-SWITCHES=<true / false>

# Indent a Java source file
$JAVA-STYLE=<true / false>

# Indent a maximal <num> spaces in a continuous statement, relatively to the
# previous line.
$MAX-INSTATEMENT-INDENT=<num>

# Indent a minimal <num> spaces in a continuous conditional belonging to a
# conditional header.
$MIN-CONDITIONAL-INDENT=<num>

# Do not break single lines of code:
# "keep-blocks"    : Don't break one-line blocks.
# "keep-statements": Don't break complex statements and multiple statements
#                    residing in a single line.
$ONE-LINE=<keep-blocks | keep-statements>

# Surround symbols with whitespace:
# "paren": Insert space paddings around parenthesies only
# "oper":  Insert space paddings around operators only.
# "all":   Insert space paddings around operators AND parenthesies.
$PAD=<paren | oper | all>


Example:

# K&R indentation scheme
$indent-brackets=false
$indent-spaces=4
$brackets=attach
$indent-classes=false
$indent-switches=false
$indent-namespaces=false

See the file README_INDENT for indentation output examples.


9.  DEFINING NEW 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 class in your language definition:

 To define a keyword class, use one of the following elements:

 $KW_LIST(<class>)
 $KW_PREFIX(<class>)
 $KW_DELIM(<class>)
 $TAG_DELIM(<class>)

 The class-attribute is the name of the new keyword group.
 You can use the same class name for different groups.

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

 To define a corresponding colour style in the theme file, use this statement:

 $KW_CLASS(class) = RR GG BB <bold> <italic> <underline>

 Note that every class name which is listed in a language definition should be
 defined in the used colour theme.
 The keyword classes "kwa" and "kwb" are predefined for all themes, they replace
 the old hard coded classes "keyword" and "type".

Example:

# Some language definition...
$KW_LIST(kwa)=for repeat while [...]
$KW_LIST(debug)=ASSERT DEBUG
$ML_COMMENT=/* */
# ...

# Some colour theme...
$KW_CLASS(kwa)=dd bb 00 bold
$KW_CLASS(debug)=ff 00 00 bold
$COMMENT=97 83 45 italic
# ...


10. CONFIGURATION FILE:
--------------------------------------------------------------------------------

Only the console executables read a configuration file.
A plain ASCII text file  has to be stored in the following path, depending
on your platform:

UNIX: $HOME/.highlightrc
W32 : <Path of highlight.exe>\highlight.conf

The options in the file behave like their equivalent long command line options
of the same name. Flags (options without parameter) expect true or false as
value.

Following options are supported:

$add-data-dir        $outdir
$anchors             $print-index
$data-dir            $replace-quotes
$css-infile          $rtf
$css-outfile         $quiet
$replace-tabs        $style
$fop-compatible      $tex
$format-style        $verbose
$fragment            $wrap
$include-css         $wrap-simple
$latex               $xhtml
$linenumbers         $xsl-fo
$progress            $zeroes

Example:

$style=emacs
$linenumbers=true
$css-outfile=format.css
$format-style=gnu

The options defined in this file may be redefined by command line parameters
(except flags).



11. SCRIPTS
--------------------------------------------------------------------------------

See the /examples subdirectory in the highlight installation for some scripts
which make use of highlight:

examples/cgi/perl/highlight.cgi

a Perl script which invokes highlight and outputs HTML.

examples/cgi/php/SyntaxHighlighter.php

A PHP Wiki plugin.



12. PYTHON BINDING
--------------------------------------------------------------------------------

A Python 2.3 binding is located in /exampless/python-binding.
See README_PYTHON for installation instructions and example.py for a programming
reference.



13. CONTACT
--------------------------------------------------------------------------------

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

---
* The highlight directory DATADIR may be one of the directories listed in INSTALL.
For UNIX, this is usually /usr/share/highlight, for Windows, it is the path
of the highlight executable. You can redefine this directory at run time by
the --data-dir option, or during compile time (see INSTALL for details).
Highlight expects the subdirectories langDefs/, themes/ and indentSchemes within a
data directory.