--------------------------------------------------------------------------------
---  HIGHLIGHT MANUAL - Version 2.4.2   -------------------------- SEPT 2005 ---
--------------------------------------------------------------------------------

OSI Certified Open Source Software

Deutsche Anleitung: README_DE

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

Highlight converts sourcecode to HTML, XHTML, RTF, LaTeX, TeX, XSL-FO and XML
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.  Input/Output
5.  Highlight file format
6.  Language definitions
7.  Colour themes
8.  Indentation schemes
9.  Keyword groups
10. Configuration file
11. Scripts
12. SWIG interface
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
  highlight < main.cpp > main.cpp.html -Sc

You will find the HTML file and a file highlight.css in the working directory.
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 --include-style --linenumbers

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

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

  Other output formats:
  XHTML (--xhtml), TeX (--tex), RTF (--rtf), XSL-FO (--xsl-fo), ANSI (--ansi),
  XML (--xml).
  HTML is the default output format if no other format is specified.

- Define font shape and size:
  highlight -S ada -X --font-size 12 --font Verdana
  highlight -S ada -L --font-size tiny --font sffamily

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

Type highlight --help 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.

You will find more language definitions at http://wiki.andre-simon.de/.


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

* highlighting of keywords, types, strings, numbers, escape sequences, comments,
  symbols and directive lines
* highlighting of custom keyword classes, which may be defined using regular
  expressions
* coloured output in HTML, XHTML 1.1, RTF, TeX, LaTeX, XSL-FO, ANSI escape
  sequences and XML 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 style-information in the output HTML, LaTeX or TeX file
  or to save them in a separate style file, which is referenced by the documents
* customizable colour themes
* recursive batch processing of directories


4. INPUT/OUTPUT:
--------------------------------------------------------------------------------

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

If no input filename is given by --input, 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 language definition. The correct parameter of -S would be "py".
If you pass the filename directly to highlight, the program fetches the ".py"
extension, only if you use IO-redirection the -S parameter is required.

If there exist multiple suffixes (like C, cc, cpp, h with C++ - files),
you can assign them to the matching language definition in the file
HL_DIR/extensions.conf.

Highlight enters the batch processing mode if the --batch-recursive option
was given or if multiple input files were defined.
In batch mode, highlight will save the generated files with the original
filename, appending the extension of the chosen output type.
The -O option is useful with -B. Use --quiet to improve performance
(recommended for usage in shell scripts).


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

The HTML, TeX and LaTeX formats allow to reference style files which contain
the formatting information.

In HTML output, this style file contains CSS definitions and is named
'highlight.css' by default.

In LaTeX and TeX, the file contains some macro definitions, and is saved as
'highlight.sty' if not otherwise stated.

Name and path of the style file may be modified with --style-outfile.
The --style-infile option defines another style file to be included in the
final style definition.
If the --outdir option is given, all generated output, including style files,
is stored in that directory.

You can use the --include-style switch to force highlight to save the style
information embedded in the output documents.

The usage of referenced style definitions has the advantage to have all
formatting information in a central place, which affects all referencing
documents.

If you want to process LaTeX files in UTF-8 encoding, you may have to install
the latex ucs package (see INSTALL).


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


RTF output
----------

RTF always uses white background colour.


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.


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

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

highlight -S txt -L 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 -X  --batch-recursive '*.cpp' --outdir /home/you/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 -L  * --outdir /home/you/latex_code/
Converts all files to LaTeX, stored in /home/you/latex_code/.

highlight --fragment --style-outfile hilite.css
Generates a CSS file without parsing any source file.


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, a list of words or a regular expression.
Lists may be split in multiple lines.

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


6. 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 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/extensions.conf*.

FILE FORMAT:

# Regular expression to describe valid number tokens
# Default value: (?:0x|0X)[0-9a-fA-F]+|\d*[\.]?\d+(?:[eE][\-\+]\\d+)?[lLuU]?
$DIGIT=regex(<RE>)

# Regular expression to describe valid identifier tokens
# Default value: [a-zA-Z_]\w*
$IDENTIFIER=regex(<RE>)

# 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>

# Regular expression which describes keywords
$KW_RE(<class>)=regex(<RE>)

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

# List of String delimiters
$STRINGDELIMITERS=<List>

# List of string delimiters which are not equal (open != close)
$STRING_UNEQUAL=<open close>

# List of escape characters in Strings (ie. "\") or regular expression
$ESCCHAR=<List> | regex(<RE>)

# Set true if escape characters may appear outside of strings
$ALLOWEXTESCAPE=<true|false>

# 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> | regex(<RE>)

# Opening string of preprocessor directive lines
$DIRECTIVE=<prefix> | regex(<RE>)

# 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>

# Set to true if multiple line comments may be nested
$ALLOWNESTEDCOMMENTS=<true | 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>

See the file README_REGEX for a detailed description of the regular expression
syntax.

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 (HL_DIR), you can pass highlight another search
      path with the --add-data-dir option.


7. THEME DEFINITIONS
--------------------------------------------------------------------------------

Colour themes are stored as plain ASCII files, defining the formatting of the
output. The files have to be stored as *.style in HL_DIR/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 comm. (optional, equals to $COMMENT if omitted
$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. 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 HL_DIR/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. 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 group, use one of the following elements:
    $KW_LIST(<group>)
    $KW_RE(<group>)
    $TAG_DELIM(<group>)

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

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

    Define a corresponding colour style in your theme file:
    $KW_CLASS(group) = RR GG BB <bold> <italic> <underline>

Note that every group name which is listed in a language definition should be
defined in the used colour theme. The keyword groups "kwa"-"kwd" are defined
for all colour themes.


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.


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. SWIG INTERFACE
--------------------------------------------------------------------------------

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



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

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

http://wiki.andre-simon.de/
Because or repeated spamming abuse, you have to login to edit pages.
The wiki login: user, Password h1gHL1te

---
* The highlight directory HL_DIR 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.
