--------------------------------------------------------------------------------
---  HIGHLIGHT MANUAL - Version 2.0-25 --------------------------- JUNE 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 and colour themes are
customizable.


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

1.  Platforms
2.  Supported programming/markup languages
3.  Features
4.  User instructions
5.  Defining new language definitions
6.  Defining new colour themes
7.  Configuration file
8.  Highlight API
9.  Scripts
10. Python binding
11. Contact


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

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

For other platforms, see the highlight homepage. 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, Spin, Squirrel, SuperX++, Sybase,
VHDL, Visual Basic, XML.


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

- highlighting of keywords, types, strings, numbers, escape sequences, comments,
  symbols and directive lines
- coloured output in HTML, XHTML 1.1, RTF, TeX, LaTeX or XSL-FO format
- 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
- 50 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 [afhlpqvwCEILPRTXYVW] [-i input file] [-o output file]
                  [-S syntax] [-O outdir] [-b wildcard] [-B wildcard]
                  [-t num] [-c css_outfile] [-e css_infile] [-s CSS_style]
                  [-D newDataDir] [input files]

 -b, --batch=<wildcard>         convert all matching files in current directory
                                (Example: highlight -b '*.cpp')
 -B, --batch-recursive=<wc>     like -b, but uses recursive search
 -D, --data-dir                 set path to highlight data directory
 -E, --add-data-dir=<directory> set path to an additional data directory, which
                                is searched first 
 -f, --fragment                 omit file header and footer
 -F, --format-style=<style>     reformats and indents output in given style
                                <style> = ["ansi", "gnu", "kr", "java", "linux"]
 -h, --help                     print this help
 -H, --help-int=<lng>           prints help in given language <lng>=[en, de, fr]
 -i, --input=<file>             name of single input file
 -l, --linenumbers              print line numbers in output file
 -o, --output=<file>            name of single output file
 -O, --outdir=<directory>       name of output directory                                
 -s, --style=<style>            specify colour style which should be applied
 -S, --syntax=<type>            specify type of source code
 -t, --deletetabs=<num>         replace tabs by <num> spaces
 -v, --verbose                  print debug info
 -p, --listlangs                list installed language definitions
 -P, --progress                 print progress bar in batch mode
 -q, --quiet                    supress progress info in batch mode
 -w, --listthemes               list installed colour themes
 -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)
 -V, --wrap-simple              wrap long lines without indenting function 
                                parameters and statements (see -W)
 -W, --wrap                     wrap long lines
     --version                  print version and copyright information
     
 (X)HTML output options:
 -a, --anchors                  attach anchor to line numbers
 -c, --css-outfile=<file>       name of CSS definition file
 -e, --css-infile=<file>        file to be included in css-outfile
 -C, --printindex               print index file with hyperlinks to output files
 -I, --includecss               include CSS-definition in (X)HTML-file

 LaTeX output options:
 -r, --replace-quotes           replace double quotes by \dq (assumes -f is set)

 XSL-FO - options:
 -A, --fop-compatible           generate FO for Apache FOP (see README)

-c will be ignored if -I is set.  
-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 highlighted 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 param,eter 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/.

About (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 (--includecss
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 --includecss, 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.

About 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."

About RTF output:
-----------------

RTF always uses white background colour.

About text processing:
----------------------

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

Example:

highlight -S txt -L README > README.tex


5. 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 the highlight directory/langDefs* with the following name:

<usual extension of sourcecode files>.lang

Examples: PHP -> php.lang, Java -> java.lang

If there exist multiple suffixes, list them in extensions.conf*.

FILE FORMAT:

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

Highlight will read the following parameters:

# List of keywords:
$KEYWORDS=<List>

# Prefix which determines keywords
$KEYWORDPREFIX=<Character>

# List of types and type modifiers
$TYPES=<List>

# Delimiters for keywords
$KEYWORDDELIMITERS=<open close>

# Delimiters for types or variables
$TYPEDELIMITERS=<open close>

# Tag open and close delimiters
# Tags are formatted like keywords
$TAGDELIMITERS=<tag_open tag_close>

# Prefix which determines variables
$VARIABLEPREFIX=<Character>

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

# List of String delimiters
$STRINGDELIMITERS=<List>

# Pair of string delimiters which are not the same character
# Example : s" " in Forth
$STRINGDELIMITERPAIR=<open close>

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

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

# Opening string of preprocessor directive lines
# Ending symbols are not recogniced yet (like Pascal {$..} )
$DIRECTIVE=<1 string>

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

# Symbols which should be coloured (brackets etc)
$SYMBOLS=<List>

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

# Set to false if multiple line comments must not ne nested
$ALLOWNESTEDMULTILINECOMMENTS=false

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

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

NOTE: The parameter names are case insensitive.
      Keyword lists may be split in multiple lines.

Example:

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

$KEYWORDS=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

$TYPESMODS=array boolean char integer file pointer real set string text record

$STRINGDELIMITERS=" '
$SINGLELINECOMMENT=//
$MULTILINECOMMENT={ }
$ISCASESENSITIVE=false

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


6. 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 the highlight directory/themes*. You can apply a 
style with the -s option.

FILE FORMAT:

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

# Colour of unrecognized text
$DEFAULTCOLOUR=RR GG BB

# Background colour (ignored by RTF)
$BGCOLOUR=RR GG BB

# Font size
$FONTSIZE=<number>

# Formatting of keywords
$KEYWORD=RR GG BB <bold> <italic> <underline>

# Formatting of types
$TYPE=RR GG BB <bold> <italic> <underline>

# Formatting of numbers
$NUMBER=RR GG BB <bold> <italic> <underline>

# Formatting of escape characters
$ESCAPECHAR=RR GG BB <bold> <italic> <underline>

# Formatting of strings
$STRING=RR GG BB <bold> <italic> <underline>

# Formatting of strings within compiler directives
$STRING_DIRECTIVE=RR GG BB <bold> <italic> <underline>

# Formatting of comments
$COMMENT=RR GG BB <bold> <italic> <underline>

# Formatting of compiler directives
$DIRECTIVE=RR GG BB <bold> <italic> <underline>

# Formatting of symbols (optional, equals to $DEFAULTCOLOUR if omitted)
$SYMBOL=RR GG BB <bold> <italic> <underline>

# Formatting of line numbers
$LINE=RR GG BB <bold> <italic> <underline>

RR GG BB describes the red/green/blue hex-values which define the colour.
(Value range: 00 (none) - FF (full))
Bold, italic und underline are optional attributes and may be combined.

Example:

# Golden.style
$DEFAULTCOLOUR=dd bb 00
$BGCOLOUR=00 00 00
$FONTSIZE=10
$KEYWORD=dd bb 00 bold
$TYPE=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


7. 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             $printindex
$data-dir            $replace-quotes
$css-infile          $rtf
$css-outfile         $quiet
$deletetabs          $style
$fop-compatible      $tex
$format-style        $verbose
$fragment            $wrap
$includecss          $wrap-simple
$latex               $xhtml
$linenumbers         $xsl-fo
$progress 

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).


8. Highlight API:
--------------------------------------------------------------------------------

If you want to include the highlight parser in your application, you have to
fulfill the requirements of the GNU General Public License. See the file COPYING.

See main.cpp how to integrate the parser in your program.


9. Scripts
--------------------------------------------------------------------------------

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

./cgi/perl/highlight.cgi

a Perl script which invokes highlight and outputs HTML.

./cgi/php/CodeHighLight.php
./cgi/php/SyntaxHighlighter.php

Two PHP Wiki plugins.

See the homepage for a PyQt frontend.


10. Python binding
--------------------------------------------------------------------------------

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


11. Contact
--------------------------------------------------------------------------------

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

---
* The highlight directory 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/ and themes/ within a data
directory.