--------------------------------------------------------------------------------
---  HIGHLIGHT MANUAL - Version 2.0-22 -------------------------- APRIL 2004 ---
--------------------------------------------------------------------------------

OSI Certified Open Source Software

English manual: README

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

Highlight konvertiert Sourcecode in XHTML, HTML, RTF, TeX, LaTeX oder XSL-FO-
Dateien mit Syntaxhervorhebung.

INHALT
--------------------------------------------------------------------------------

1.  Betriebsysteme
2.  Untersttzte Programmier- und Auszeichnungssprachen
3.  Funktionen
4.  Bedienung
5.  Neue Sprachdefinitionen definieren
6.  Neue Farbstile definieren
7.  Konfigurationsdatei
8.  Highlight API
9.  Skripte
10. Kontakt


1.BETRIEBSSYSTEME
--------------------------------------------------------------------------------

Highlight ist in ISO C++ geschrieben. Es existieren 3 Versionen:
- UNIX Konsolenanwendung
- W32 Konsolenanwendung
- W32 GUI

Der Sourcecode ist mit gcc 3.x, MS Visual .NET und MW Codewarrior8 kompilierbar.


2. UNTERSTTZTE PROGRAMMIER- UND AUSZEICHNUNGSSPRACHEN:
--------------------------------------------------------------------------------

Momentan untersttzt Highlight folgende Programmiersprachen, Auszeichnungs-
sprachen und Konfigurationsdateien:

Action Script, ADA 95, Agda, AMPL, Aspect, Assembler, Amtrix, Avenue, (G)AWK,
Bash, BlitzBasic, BibTex, BMS, C, C++, C#, ClearBasic, Clipper, Cobol, 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. FUNKTIONEN:
--------------------------------------------------------------------------------

- Farbige Hervorhebung von Schlsselwrtern, Typbezeichnern, Strings, Zahlen, 
  Escapesequenzen, Symbolen, Direktiven und Kommentaren
- Neuformatierung und Einrckung von C, C++, C# und Java Sourcecode
- Automatisches Umbrechen von berlangen Zeilen
- Ausgabe im HTML-, XHTML-, RTF-, TeX, LaTeX oder XSL-FO - Format
- Ausgabe von Zeilennummern
- Speichern der CSS-Definition wahlweise in separater Datei oder innerhalb der
  Ausgabedatei
- 65 Farbstile
- Konvertierung von ASCII Textdateien ohne Highlighting in eines der
  Ausgabeformate


4. BEDIENUNG:
--------------------------------------------------------------------------------

Die Hilfe wird mit "highlight -d" aufgerufen:

 USAGE: highlight [afhlpvwCILPRTXYVW] [-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>         konvertiert alle passenden Dateien mit im
                                aktuellen Verzeichnis 
                                (Beispiel: highlight -b '*.cpp')
 -B, --batch-recursive=<wc>     wie -b, sucht aber rekursiv
 -D, --data-dir=<directory>     setzt den Pfad zum Highlight Datenverzeichnis
 -E, --add-data-dir=<directory> setzt zustzlichen Suchpfad zum Inst-Verzeichnis
 -f, --fragment                 Header und Footer weglassen
 -F, --format-style=<style>     formatiert Ausgabe im angegebenen Stil,
                                <style> = ["ansi", "gnu", "kr", "java", "linux"]
 -h, --help                     prints english help
 -H, --help-int=<lng>           gibt Hilfe in angegebener Sprache aus
                                <lng>=[en, de, fr]
 -i, --input=<file>             Name einer einzelnen Eingabedatei
 -l, --linenumbers              gibt Zeilennummern in Ausgabe aus
 -o, --output=<file>            Name einer einzelnen Ausgabedatei
 -O, --outdir=<directory>       Name des Ausgabeverzeichnisses
 -s, --style=<style>            gibt den zu verwendenden Farbstil an 
 -S, --syntax=<type>            gibt den Typ des Quelltextes an
 -t, --deletetabs=<num>         ersetzt Tabs durch <num> Leerzeichen
 -v, --verbose                  gibt Debug-Info nach stderr aus
 -p, --listlangs                listet installierte Sprachdefinitionen auf
 -P, --progress                 gibt im Batch-Modus Fortschrittsanzeige aus
 -q, --quiet                    keine Infos ber Fortschritt im Batch-Modus
 -w, --listthemes               listet installierte Themes auf
 -L, --latex                    gibt eine LaTeX - Datei aus
 -R, --rtf                      gibt eine RTF- Datei aus
 -T, --tex                      gibt eine TeX - Datei aus
 -X, --xhtml                    gibt eine XHTML 1.1 - Datei aus
 -Y, --xsl-fo                   gibt eine XSL-FO - Datei aus
 -V, --wrap-simple              bricht lange Zeilen um, rckt Funktionsparameter
                                und Zuweisungen nicht neu ein
 -W, --wrap                     bricht lange Zeilen um
     --version                  gibt Versionshinweis aus
     
 (X)HTML - Optionen:
 -a, --anchors                  fgt Anker an Zeilennummerierung an
 -c, --css-outfile=<file>       Name der CSS-Definitionsdatei
 -e, --css-infile=<file>        Datei, die in css-outfile eingefgt werden soll
 -C, --printindex               erzeugt Indexdatei mit Links auf Ausgabedateien
 -I, --includecss               fgt CSS-Definition in (X)HTML-Datei ein

 LaTeX Optionen:
 -r, --replace-quotes           ersetzt Anfhrungszeichen durch \dq (setzt
                                -f voraus)

 XSL-FO - Optionen:
 -A, --fop-compatible           erzeugt FO fr Apache FOP (siehe README)

-c wird ignoriert falls -I gesetzt ist. 
-i und -o werden ignoriert, falls -b gesetzt ist.
-t wird ignoriert, falls -F gesetzt ist.
-r wird ignoriert, falls -f nicht gesetzt ist.
Wenn keine Ein- oder Ausgabedatei angegeben wird, wird stdin bzw. stdout
fr Ein- oder Ausgabe benutzt. 
Es wird HTML erzeugt, wenn kein Ausgabeformat angegeben ist.
CSS-Definitionen werden in highlight.css gespeichert, wenn weder -I noch -c
gesetzt sind.
Die Neuformatierung der Ausgabe funktioniert nur mit C, C++, C# und Java Code.
Der automatische Zeilenumbruch (-V, -W) fhrt bei berlangen einzeiligen 
Kommentaren und Direktiven zu fehlerhafter Hervorhebung (vorsichtig einsetzen).

Folgende Aufrufe schreiben den Inhalt von hallo.c nach hallo.html:

highlight -o hallo.html -i hallo.c
highlight -o hallo.html hallo.c
highlight -o hallo.html -S c < hallo.c
highlight -S c < hallo.c > hallo.html

Bei jedem Aufruf wird neben der Ausgabe "hallo.html" auch eine Datei 
"highlight.css" ins aktuelle Arbeitsverzeichnis geschrieben.

Wenn kein Name der Eingabedatei angegeben wird, muss mit -S die bliche
Endung dieser Datei angegeben werden. Bei einer Python-Datei sucht highlight
nach der Sprachdefinitionsdatei py.lang.
Wird der Dateiname direkt an Highlight bergeben, stellt das Programm anhand der
Dateiendung selbstndig den Typ der Datei fest. Wird allerdings durch die Shell
die Eingabe umgeleitet, muss -S angegeben werden. 

Falls mehrere gebruchliche Endungen fr eine Programmiersprache existieren,
versucht highlight die passende lang-Datei zu finden (z.B. C, cpp, cc, h bei 
C++ -Sourcecode). Die Zuordnung zwischen Endungen und passender Sprachdefinition 
befindet sich in /usr/share/highlight/extensions.conf*.

Im Batchmodus speichert Highlight die generierten Dateien unter dem Original-
namen mit der Endung html, xhtml, tex, rtf oder fo ab, je nachdem welches 
Ausgabeformat gewhlt wurde. Mit --quiet wird die Verarbeitungsgeschwindigkeit
besser, empfohlen fr den Einsatz in Skripten. 

Beispiel:

highlight -X -B '*.cpp' -O /home/du/html_code/
Konvertiert alle *.cpp Dateien im aktuellen Verzeichnis und in den Unterver-
zeichnissen in XHTML-Dateien, die in /home/du/html_code/ geschrieben werden.

highlight -L  * -O /home/you/latex_code/
konvertiert alle Dateien im LaTeX-Format nach /home/you/latex_code/.


Zur (X)HTML-Ausgabe:
--------------------

HTML wird mit Cascading Style Sheets (CSS) formatiert. Die CSS-Definitionen
knnen entweder in eine externe Datei geschrieben werden, die von den erzeugten
HTML-Dateien referenziert wird, oder direkt in die HTML-Ausgabe eingebunden 
werden (Option --includecss). Die Verwendung refenzierter CSS-Dateien hat den 
Vorteil, die Formatierung aller HTML-Dateien an einer zentralen Stelle verwalten
zu knnen.
Wird Highlight ohne --includecss aufgerufen, legt es eine Datei highlight.css
im aktuellen Arbeitsverzeichnis ab und fgt einen Verweis "highlight.css" in der
HTML-Ausgabe ein. Mit --css-outfile kann der Name und der Pfad der CSS-Datei
angepasst werden. Mit --css-infile kann eine weitere CSS-Datei angegeben werden,
die in die sptere CSS-Definiton eingefgt wird.
Wenn die --outdir Option gegeben ist, wird die komplette Ausgabe inklusive CSS-
Datei ins angegebene Verzeichnis geschrieben.

Zur XSL-FO - Ausgabe:
---------------------

Die XSL-FO Ausgabe ist experimentell. Das jetzige Ergebnis ist kompatibel zu
Apache FOP bzw. xsltproc/xmlto, aber es gibt noch einige Probleme:

 *xsltproc und 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: 
 Die erzeugten Dateien sind sehr gro, die Verarbeitung dauert lange.

 *Apache FOP*
  
 Version: 0.20.5

 Die FO Ausgabe wird mit der --fop-compatible Option an FOP angepasst.

 Problem: 
 Die aktuelle FOP Version erzeugt zustzliche Leerzeilen nach Zeilenumbrchen.

 Zitat von der Apache Homepage:
 "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."

Zur RTF-Ausgabe:
----------------

RTF wird immer mit weier Hintergrundfarbe ausgegeben.

Zur Text-Ausgabe:
-----------------

Wird als Sprachdefinition txt angegeben, findet keine Hervorhebung statt.

Beispiel:

highlight -S txt -L README > readme.tex


5. NEUE SPRACHDEFINITIONEN DEFINIEREN:
--------------------------------------------------------------------------------

Eine Sprachdefinitionen ist eine Textdatei, in der Schlsselwrter und Symbole 
einer Programmiersprache mehreren Kategorien zugeordnet werden.
Die Datei muss im Installatinverzeichnis in langDefs/ unter folgendem Namen 
gespeichert werden:

<bliche Endung der Sourcecodedateien>.lang

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

Sollte es mehrere gebruchliche Endungen geben, kann man diese in der Datei 
extensions.conf* notieren.

Format der Datei:

Kommentare beginnen mit # als erstem Zeichen in der Zeile.

Highlight liest folgende Parameter ein:

# Liste der Schlsselwrter
$KEYWORDS=<Liste.>

# Prfix, die Schlsselwrter markiert
$KEYWORDPREFIX=<Character>

# Liste der Typen und Typ-Modifizierer
$TYPES=<Liste.>

# Begrenzer fr Schlsselwrter
$KEYWORDDELIMITERS=<open close>

# Begrenzer fr Typen oder Variablen
$TYPEDELIMITERS=<open close>

# Tagbegrenzer
# Tags werden wie Schlsselwrter formatiert
$TAGDELIMITERS=<tag_open tag_close>

# Prfix, die Variablen markiert
$VARIABLEPREFIX=<Character>

# Prfix, die das Hervorheben von Escapesequenzen in "Simplified Strings"
# (C#) verhindert
$RAWSTRINGPREFIX=<Character>

# Liste der Stringbegrenzer
$STRINGDELIMITERS=<Liste>

# Paar von sich unterscheidenden Stringbegrenzern
$STRINGDELIMITERPAIR=<open close>

# Liste der Bezeichner, die einen einzeiligen Kommentar einleiten
$SINGLELINECOMMENT=<Liste>

# Kommentarbeginn  und -ende beim mehrzeiligen Kommentar
$MULTILINECOMMENT=<Kommentarbeginn  Kommentarende>

# Einleitender Bezeichner von Compilerdirektiven
# zur Zeit werden keine abschliessenden Symbole erkannt, wie sie zB in Pascal
# ntig wren ( {$..} )
$DIRECTIVE=<1 Bez.>

# Liste der Escapecharacter innerhalb von Strings (normalerweise \)
$ESCCHAR=<Liste>

# Symbole wie zB Klammern, die hervorgeheoben werden sollen
$SYMBOLS=<List>

# Charactser, die in Keyword oder Typbezeichnern auftreten
$ALLOWEDCHARS=<character list>

# Falls mehrzeilige Kommentare nicht verschachtelt werden drfen, auf false
# setzen
$AllowNestedMultiLineComments=false

# Falls Programmiersprache case-sensitive ist, auf true setzen
$ISCASESENSITIVE=<true / false>

# Fge eine andere Sprachdefinition aus dem selben Verzeichnis ein
$INCLUDE=<language definition>

Die Bezeichner sind nicht case sensitive.
Wortlisten knnen sich ber mehrere Zeilen erstrecken.

Beim Erstellen neuer Dateien kann man die Schlsselwrter aus Dateien anderer
Programme mit Syntaxhighlighting (z.B VIM, UltraEdit) kopieren.

Beispiel:

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

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

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


6. NEUE FARBSTILE DEFINIEREN:
--------------------------------------------------------------------------------

Die Farbstile bestehen aus einfachen ASCII-Dateien, in denen man die Format-
eigenschaften der Ausgabe festlegt. Die RTF- Ausgabe ignoriert die Hintergrund- 
farbe. Die Dateien mssen mit der Endung .style im highlight - 
Verzeichnis/themes* gespeichert werden. Mit der -s Option wird das Farbschema 
angewandt.

DATEIFORMART:

Kommentare beginnen mit # als erstem Zeichen in der Zeile.

Highlight liest folgende Parameter ein:

# Farbe des nicht erkannten Textes
$DEFAULTCOLOUR=RR GG BB

# Hintergrundfarbe
$BGCOLOUR=RR GG BB

# Schriftgrsse
$FONTSIZE=<number>

# Formatierung der Schlsselwrter
$KEYWORD=RR GG BB <bold> <italic> <underline>

# Formatierung der Typen
$TYPE=RR GG BB <bold> <italic> <underline>

# Formatierung der Zahlen
$NUMBER=RR GG BB <bold> <italic> <underline>

# Formatierung der Escape Character
$ESCAPECHAR=RR GG BB <bold> <italic> <underline>

# Formatierung der Strings
$STRING=RR GG BB <bold> <italic> <underline>

# Formatierung der Strings innerhalb von Compilerdirektiven
$STRING_DIRECTIVE=RR GG BB <bold> <italic> <underline>

# Formatierung der Kommentare
$COMMENT=RR GG BB <bold> <italic> <underline>

# Formatierung der Compilerdirektiven
$DIRECTIVE=RR GG BB <bold> <italic> <underline>

# Formatierung von Klammern (optional, falls nicht angegeben wird $DEFAULTCOLOR
# verwendet)
$SYMBOL=RR GG BB <bold> <italic> <underline>

# Formatierung der Zeilenummern
$LINE=RR GG BB <bold> <italic> <underline>

RR GG BB steht dabei fr die hexadezimalen Rot/Grn/Blau - Werte, die die
gewnschte Farbe definieren. Bold, italic und underline sind optional und
knnen kombiniert werden.

Beispiel:

# 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. KONFIGURATIONSDATEI:
--------------------------------------------------------------------------------

Nur die Konsolen-Versionen von Highlight lesen Konfigurationdateien ein. Die
Datei wird unter folgendem Pfad gespeichert:

UNIX: $HOME/.highlightrc
W32 : <Pfad der highlight.exe>\highlight.conf

Die Optionen der Datei entsprechen den gleichnamigen langen Kommandozeilen-
optionen. Flags (Optionen ohne Parameter) erwarten true oder false als Wert.

Folgende Optionen werden ausgewertet:

$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

Beispiel:

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

Diese Optionen knnen bis auf die Flags von Kommandozeilenparametern ber-
schrieben werden.


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

Um den Highlight Parser in eigenen Anwendungen zu benutzen, mssen die
Bedingungen der GNU General Public license beachtet werden (Siehe COPYING).

Main.cpp liegt als Implementierungsbeispiel vor.


10. Skripte
--------------------------------------------------------------------------------

Im /utils Unterverzeichnis der highlight Installation befinden sich einige 
Skripte, die Highlight integrieren:

./cgi/perl/highlight.cgi

Ein Perl Skript, das HTML erzeugt und ausgibt.

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

Zwei PHP Wiki Plugins.

Auf der Homepage befindet sich ein PyQt-Frontend.

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

---
* Das Highlight Installationsverzeichnis ist eines der in INSTALL aufgelisteten
Verzeichnisse. Unter Unix lautet der Pfad blicherweise /usr/share/highlight,
unter Windows ist es der Pfad der highlight.exe. Sie knnen dieses Verzeichnis
zur Laufzeit mit --data-dir ndern, oder auch zur Compile-Zeit auf einen anderen 
Wert setzen(siehe INSTALL fr nhere Infos).
Highlight erwartet in dem angegebenen Verzeichnis die Unterverzeichnisse 
langDefs/ bzw. themes/.
