Highlight Dokumentation

Highlight Handbuch

Inhalt

Übersicht
Gebrauch und Optionen
Konfiguration
Highlight integrieren
Kompilieren und installieren

Übersicht

Highlight konvertiert Sourcecode in XHTML, HTML, RTF, TeX, LaTeX, SVG, BBCode und Terminal Escape-Sequenzen mit farbiger Syntaxhervorhebung. Sprachdefinitionen und Farbstile sind konfigurierbar.

Sinn und Zweck

Highlight wurde mit dem Ziel entworfen, einen flexiblen und einfach zu bedienenden Syntaxhighlighter für mehrere Ausgabeformate anzubieten. Statt hartkodierter Sprachbeschreibungen und Farbschemata sind alle wichtigen Informationen in Konfigurationsskripten enthalten. Diese Skripte können mit Plug-Ins angepasst und erweitert werden.

Funktionsliste

Hervorhebung von Schlüsselwörtern, Typbezeichnern, Strings, Zahlen, Escapesequenzen, Operatoren, Präprozessor-Direktiven und Kommentaren
Farbige Ausgabe in HTML, XHTML, RTF, TeX, LaTeX, SVG, BBCode und Terminal- Escapesequenzen
Syntax-Elemente werden als Reguläre Ausdrücke oder als Stringlisten beschrieben
Erweiterbare Schlüsselwort-Gruppen
Erkennung mehrerer Sprachen innerhalb einer Datei
Alle Konfigurationsdateien sind Lua-Skripte
Unterstuetzt Plug-In Skripte zur Anpassung von Sprachdefinitionen und Themes
Neuformatierung und Einrückung von C, C++, C# und Java Code
Umbrechen von überlangen Zeilen
Anpassbare Ausgabe von Zeilennummern
Speichern von Stylesheets wahlweise in separater Datei oder innerhalb der Ausgabedatei (HTML, LaTeX, TeX, SVG)

Unterstützte Programmier- und Auszeichnungssprachen

Sehen Sie die Liste der mitgelieferten Sprachdefinitionen.

Gebrauch und Optionen

Schnelle Einführung

Folgende Beispiele zeigen, wie man die hervorgehobene Ausgabe einer C++-Datei namens main.cpp erzeugt:

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

  Sie werden die HTML-Datei und die CSS-Datei highlight.css im aktuellen
  Verzeichnis finden. Falls Sie Eingabe-Umleitung verwenden, geben Sie den Typ
  der Programmiersprache mit --syntax an.

- HTML mit eingebetteter CSS Definition und Zeilennummerierung ausgeben:
  highlight -i main.cpp -o main.cpp.html --include-style --line-numbers

- HTML mit direkter CSS-Formatierung ausgeben:
  highlight -i main.cpp -o main.cpp.html --inline-css

- HTML mit Code-Formatierung im "horstmann" Stil und dem Farbschema "Neon"
  ausgeben:
  highlight -i main.cpp -o main.cpp.html --reformat horstmann --style neon

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

  Folgende Ausgabeformate können mit --out-format bestimmt werden:
  html:     HTML 4.01
  xhtml:    XHTML 1.1
  tex:      Plain TeX
  latex:    LaTeX
  rtf:      RTF
  ansi:     Terminal 16 color escape codes
  xterm256: Terminal 256 color escape codes
  svg:      SVG
  bbcode:   BBCode

  HTML wird als Standard ausgegeben, wenn kein anderes Format mit --out-format
  angegeben ist.

- Font und Schriftgrösse anpassen:
  highlight --syntax ada --out-format=xhtml --font-size 12 --font  Consolas,\'Courier\ New\'
  highlight --syntax ada --out-format=latex --font-size tiny --font sffamily

- Ausgabeverzeichnis definieren:
  highlight -d some/target/dir/ *.cpp *.h

CLI Optionen

Die Kommandozeilenversion von highlight bietet folgende Optionen:

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

GUI Optionen

Die Graphische Oberfläche bietet eine Teilmenge der obigen Funktionen an. Sie enthält eine dynamische Vorschau der sichtbaren Ausgabe. Sehen Sie sich die Screenshots und die GUI Animation an.

Ein- und Ausgabe

Wenn kein Dateiname mit --input bzw. --output angegeben wird, benutzt highlight stdin bzw. stdout für die Ein- und Ausgabe.

Wird die Eingabedatei nicht direkt auf der Kommandozeile als Argument bzw. mit --input angegeben, kann Highlight die passende Sprachinformation nicht automatisch anhand der Dateiendung bestimmen. Lediglich einige Skriptsprachen werden anhand des Shebangs in der ersten Zeile erkannt. Mit der Option --syntax muss dann der Typ der Datei vom Benutzer angegeben werden (das Argument ist normalerweise die für die Programmiersprache übliche Dateierweiterung).

Beispiel: Wenn Sie eine Python-Datei konvertieren wollen, muss highlight die Sprachdefinition py.lang einlesen. Das korrekte Argument für --syntax ist also "py".

highlight test.py                   # Option --syntax nicht nötig
highlight < test.py --syntax py     # --syntax muss angegeben werden
cat test.py | highlight --syntax py

Sollte es mehrere Dateierweiterungen für Dateien einer Programmiersprache geben (wie z.B. C, cc, cpp, h bei C++), werden diese in der Datei $CONF_DIR/filetypes.conf einer Sprachdefinition zugewiesen.

Wenn mehrere Eingabedateien an Highlight übergeben werden oder --batch-recursive gesetzt ist, wechselt das Tool in den Batch-Modus. In diesem Modus werden die Ausgabedateien unter dem Namen der Eingabedateien gespeichert, lediglich die Dateierweiterung des gewählten Ausgabeformats wird angehangen. Die --outdir Option ist im Batchmodus besonders nützlich. In Skripten sollte --quiet angegeben werden, um die Geschwindigkeit der Verarbeitung zu erhöhen.

HTML, TeX, LaTeX und SVG Ausgabe

Die HTML, TeX, LaTeX und SVG-Formate erlauben die Einbindung von externen Dateien, welche die Formatierungsinformationen enthalten ("Stylesheets").

Bei der HTML- und SVG-Ausgabe enthält diese Datei CSS-Definitionen und wird, wenn nicht anders angegeben, als "highlight.css" gespeichert.

Bei TeX und LaTeX enthält die Datei Makros, und wird per Default als "highlight.sty" gespeichert.

Name und Pfad des Stylesheets werden mit --style-outfile bestimmt. Wenn --outdir definiert ist, wird auch das Stylesheet im angegebenen Ausgabeverzeichnis gespeichert.

Mit --include-style fügt Highlight die Formatierungsangaben direkt in die Ausgabedokumente ein, statt einen Verweis auf externe Stylesheets zu setzen.

Der Verweis auf externe Dateien hat den Vorteil, die Formatierung an einer zentralen Stelle verwalten zu können, auf die die Ausgabedokumente verweisen.

Mit --style-infile kann eine Datei mit zusätzlichen Formatierungsangaben in die Ausgabedateien eingebunden werden, welche die vorgegebene highlight- Formatierung erweitert oder überschreibt.

Beispiel:

01 /* Inhalt von user.css (füge Rahmen und Line an der 
02    Zeilennummerierung hinzu) */
03 pre.hl {
04   border-width: 1px;
05   border-style:solid;
06   border-left-color: silver;
07   border-top-color: silver;
08   border-right-color: gray;
09   border-bottom-color: gray;
10 }
11 
12 .hl.lin {
13   border-right:1px solid #555555;
14   padding-left:0.5em;
15   padding-right:0.5em;
16   margin-right:1em;
17   text-decoration:none;
18 }

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

Terminal-Ausgabe

Da es nur wenige Farben zur ANSI-Ausgabe im Terminal gibt, existiert nur ein hartkodiertes Farbschema für --out-format=ansi. Daher sollte nach Möglichkeit --out-format=xterm256 verwendet werden, um eine Ausgabe in 256 Farben zu erhalten. Der 256 Farb-Modus wird z.B. von xterm, rxvt und Putty unterstützt.

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

Text-Ausgabe

Wird als Sprachdefinition txt angegeben, findet keine Syntaxhervorhebung statt.

Beispiel:

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

Beispiele:

Die folgenden Kommandos schreiben den Inhalt von hello.c nach 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

Neben hello.html wird highlight.css im aktuellen Verzeichnis erzeugt.

highlight --out-format=xhtml --batch-recursive '*.cpp' --outdir ~/html_code/

Dieses Kommando konvertiert alle *.cpp Dateien im aktuellen Verzeichnis und den Unterverzeichnissen in XHTML-Dateien, und speichert die Ausgabe in /home/you/html_code.

highlight -out-format=latex  * --outdir /home/you/latex_code/

Dieses Kommando konvertiert alle Dateien in LaTeX, und speichert sie in /home/you/latex_code/.

highlight -c stdout -s seashell --print-style

Dieses Kommando gibt nur die CSS-Informationen des angegebenen Stils (hier: Seashell) nach stdout aus.

GNU source-highlight Kompatibilität

Die Kommandozeilenschnittstelle überschneidet sich zu einem grossen Teil mit source-highlight (http://www.gnu.org/software/src-highlite/).
Diese highlight-Optionen haben dieselbe Bedeutung wie bei source-highlight:

 --input, --output, --help, --version, --out-format, --title, --data-dir,
 --verbose, --quiet, --ctags-file

Diese Optionen wurden hinzugefügt, um die Kompatibilität zu verbessern:

 --css, --doc, --failsafe, --line-number, --line-number-ref, --no-doc, --tab,
 --output-dir, --src-lang

Die obigen Optionen bilden eine gemeinsame Highlighter-Schnittstelle für Skripte, Plugins etc.

Fortgeschrittene Optionen

Exuberant Ctags Informationen hinzufügen

Die HTML-Ausgabe kann um beschreibende Tooltips mit ctags Daten erweitert werden:

ctags *.*
highlight --ctags-file *.cpp

Der Default-Parameter von ctags-file ist "tags", daher konnte er im obigen Beispiel weggelassen werden. Dieses Kommando fügt den Typ, den Namespace und den Pfad zur Definition des erkannten Tokens hinzu.

Beispiel:

"member | class:highlight::HtmlGenerator | htmlgenerator.h"

Parsen von Binärdaten vermeiden

Wenn highlight mit einer unbestimmten Menge von Eingabedaten aufgerufen wird, kann die Verarbeitung von binären Daten mit --validate-input verhindert werden. Dieser Schalter führt zu einem Vergleich der Datei-Header mit einer Liste von "Magic Numbers". Wenn ein Binär-Typ erkannt wird, bricht highlight die Verarbeitung mit einer Fehlermeldung ab. Mit --validate-input wird auch ein UTF-8 BOM in der Ausgabe unterdrückt.

Hervorbung von eingebettetem Code ohne öffnenden Delimiter

Wenn eine Datei mit eingebettetem Code ohne den einleitenden Delimiter beginnt, kann mit der --start-nested Option in diese Sprache gewechselt werden. Dies kann bei LuaTeX Dateien nötig sein:

highlight luatex.tex --latex --start-nested=inc_luatex

Die inc_luatex Definition ist eine Lua-Beschreibung mit TeX Kommentaren.

Tips und Tricks

Neue Konfigurationsskripte testen

Die Option --config-file ermöglicht es, neue Skripte vor der Installation zu testen. Die angegebene Datei muss eine lang- oder theme-Datei sein.

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

Sprachdefinitionen debuggen

Benutzen Sie --verbose um Lua- und Syntax-Daten anzuzeigen.

HTML Listentricks

Diese Beispiele gehen davon aus, dass HTML mit der Option--ordered-list als Liste ausgegeben wurde. Fügen Sie die CSS-Schnipsel mit style-infile in Ihre Ausgabe ein.

01 /* highlight odd lines */
02 ol li:nth-child(odd) {
03   background-color: #1f3030;
04 }
05 
06 /* highlight every 5th line*/
07 ol li:nth-child(5n) {
08   background-color: #1f3030;
09 }
10 
11 /* highlight every 10th line number*/
12 ol li:nth-child(10n) {
13   color: #ffff00;
14 }

UTF-8 BOM entfernen

Geben Sie --validate-input an, um das UTF-8 Byte Order Mark zu entfernen.

Konfiguration

Dateiformat

Die Konfigurationsdateien sind Lua Skripte. Folgende Syntax-Elemente genügen, um die Skripte anzupassen:

Wertzuweisung an Variablen:
name = value
(Variablen haben keinen Typ, nur Werte haben einen)

Strings:
string1="string-Literal mit Escape-Sequenzen: \n"
string2=[[Raw String ohne Escape-Sequenzen]]

Wenn ein raw String mit "[" beginnt oder mit "]" endet, muss die Klammer mit
Leerzeichen von den Begrenzern getrennt werden, um Syntaxfehler zu vermeiden.

Kommentare:
-- Einzeiliger Kommentar
--[[ Blockkommentar ]]

Arrays:
array = { first=1, second="2", 3, { 4,5 } }
Arrays können Variablen enthalten und verschachtelt werden.

Das vollständige Lua-Handbuch befindet sich hier: Lua Handbuch (en) .

Reguläre Ausdrücke

Siehe Reguläre Ausdrücke um die RE Syntax anzuzeigen.

Sprachdefinitionen

Eine Sprachdefinition beschreibt die Elemente einer Programmiersprache, die durch verschiedene Farben und Schrifttypen hervorgehoben werden. Die Datei muss in $HL_DIR/langDefs/ unter folgendem Namen gespeichert werden:

<übliche Erweiterung der Sourcecodedateien>.lang

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

Sollte es mehrere gebräuchliche Erweiterungen geben, werden diese in der Datei $HL_DIR/filetypes.conf einer Sprachdefinition zugeordnet.

Syntax-Elemente:

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

  Id:    Integer, ID der Schlüsselwortgruppe (Werte 1-4, die mehrfach verwendet
	werden können)
  List:  Liste, Auflistung von Schlüsselwörtern
  Regex: String, Regulärer Ausdruck
  Group: Integer, Capturing Group ID der Regex, bestimmt den Teil des gefundenen
	Ausdrucks, der als Schlüsselwort hervorgehoben werden soll (optional,
	wenn nicht gesetzt wird der Match mit der höchsten Group-ID zurück-
	gegeben (gezählt wird von links nach rechts))


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

  Block:     Boolean, true wenn der Kommentar ein Blockkommentar ist
  Nested:    Boolean, true wenn der Blockkommentar verschachtelt werden darf (optional)
  Delimiter: Liste, enthält Regex der öffnenden Begrenzer (Zeilenkommentar) oder
	    Regex des öffnenden und des schliessenden Begrenzers (Blockkommentar)


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

  Delimiter:      String, Regulärer Ausdruck der Begrenzer
  DelimiterPairs: Liste, enthält Ausdrücke der öffnenden und der schliessenden
		  Begrenzer wenn diese nicht gleich sind und optional ein Raw-
		  String Flag
  Escape:         String, Regulärer Ausdruck der Escapsesequenzen (optional)
  RawPrefix:      String, Definiert Raw String Prefix (optional)


PreProcessor = { Prefix, Continuation? }

  Prefix:        String, Regulärer Ausdruck der öffnenden Begrenzer
  Continuation:  String, Definiert Fortsetzungsindikator (optional)


NestedSections = {Lang, Delimiter= {} }

  Lang:      String, Name der eingebetteten Sprache
  Delimiter: Liste, Ausdrücke der öffnenden und der schliessenden Begrenzer


Description:       String, Beschreibung der Syntax

Digits:            String, Regulärer Ausdruck für Zahlenliterale (optional)

Identifiers:       String, Regulärer Ausdruck für Bezeichner (optional)

Operators:         String, Regulärer Ausdruck für Operatoren

EnableIndentation: Boolean, True wenn Syntax formatiert und eingerückt werden kann

IgnoreCase:        Boolean, True wenn Sprache nicht case-sesitive ist


Globale Variablen:

Die folgenden Variablen sind in einer Sprachbeschreibung verfügbar:

hl_lang_dir: Verzeichnis der Sprachdefinitionen (Parameter von dofile)

Identifiers: Default regex für Bezeichner
Digits:      Default regex für Zahlenliterale

Diese Integer-Variablen beschreiben die internen Zustände des highlight-Parsers:

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-Funktionen:

OnStateChange(oldState, newState, token)

  Hook Event: Wechsel des Parser-Zustandes
  Input:      Alter Zustand, geplanter neuer Zustand und das Token das zum
	      neuen Zustand führte
  Returns:    Korrekter Zustand mit dem fortgefahren wird

Beispiel:

01 Description="C and C++"
02 
03 Keywords={
04   {  Id=1,
05    List={"goto", "break", "return", "continue", "asm", "case", "default",
06          -- [..]
07         }
08   },
09   -- [..]
10 }
11 
12 Strings = {
13   Delimiter=[["|']],
14   RawPrefix="R",
15 }
16 
17 Comments = {
18    { Block=true,
19      Nested=false,
20      Delimiter = { [[\/\*]], [[\*\/]] }  },
21    { Block=false,
22      Delimiter = { [[//]] } }
23 }
24 
25 IgnoreCase=false
26 
27 PreProcessor = {
28   Prefix=[[#]],
29   Continuation="\\",
30 }
31 
32 Operators=[[\(|\)|\[|\]|\{|\}|\,|\;|\.|\:|\&|\<|\>|\!|\=|\/|\*|\%|\+|\-|\~]]
33 
34 EnableIndentation=true

Farbdefinitionen

Farbdefinitionen legen die Formatierung der Sprachelemente fest, die in den Sprachdefinitionen beschrieben wurden.

Die Dateien müssen mit der Endung .style in $HL_DIR/themes (siehe Abschnitt 1) gespeichert werden. Mit der --style (-s) Option wird das Farbschema angewandt.

Formatattribute:

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

Colour:    String, Farbe in Hex-Notation ("#rrggbb")
Bold:      Boolean, True wenn Font bold sein soll (optional)
Italic:    Boolean, True wenn Font kursiv sein soll (optional)
Underline: Boolean, True wenn Font unterstrichen sein soll (optional)


Theme-Elemente:

Description:   String, Theme-Beschreibung

Default        = Attributes (Farbe des nicht hervorgehobenen Texts)

Canvas         = Attributes (Hintergrundfarbe)

Number         = Attributes (Formatierung von Zahlen)

Escape         = Attributes (Formatierung von Escape-Sequenzen)

String         = Attributes (Formatierung von Strings)

PreProcessor   = Attributes (Formatierung von Präprozessor-Direktiven)

StringPreProc  = Attributes (Formatierung von Strings in
                             Präprozessor-Direktiven)

BlockComment   = Attributes (Formatierung von Blockkommentaren)

LineComment    = Attributes (Formatierung von Zeilenkommentaren)

LineNum        = Attributes (Formatierung von Zeilennummern)

Operator       = Attributes (Formatierung von Operatoren)

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

AttributesN: Liste, Formatierung von Schlüsselwoertgruppen. Es sollten
             mindestens vier Elemente angegeben werden, um mit der Anzahl
             von Schlüsselwortgruppen in den Sprachdefinitionen
             übereinzustimmen.

Beispiel:

01 Default        = { Colour="#000000" }
02 Canvas         = { Colour="#ffffff" }
03 Number         = { Colour="#000000" }
04 Escape         = { Colour="#bd8d8b" }
05 String         = { Colour="#bd8d8b" }
06 StringPreProc  = { Colour="#bd8d8b" }
07 BlockComment   = { Colour="#ac2020", Italic=true }
08 PreProcessor   = { Colour="#000000" }
09 LineNum        = { Colour="#555555" }
10 Operator       = { Colour="#000000" }
11 LineComment = BlockComment
12 
13 Keywords = {
14   { Colour= "#9c20ee", Bold=true },
15   { Colour= "#208920" },
16   { Colour= "#0000ff" },
17   { Colour= "#000000" },
18 }

Schlüsselwortgruppen

Sie können mehrere Schlüsselwort-Gruppen festlegen und jeder Gruppe eine eigene Formatierung zuweisen. Das ist nützlich wenn Sie z.B. Bibliotheksfunktionen, Makros oder Konstanten gesondert hervorheben möchten.

Eine Gruppe wird in zwei Schritten definiert:

 1. Beschreibung der Gruppe in der Sprachdefinition (Lang-Datei):

    Keywords = {
      -- fügen Sie die Beschreibung an:
      {Id=5, List = {"ERROR", "DEBUG", "WARN"} }
    }

 2. Festlegung des dazugehörigen Farbstils im Farb-Schema (Theme-Datei)

    Keywords= {
      --Stil als fünften Eintrag hinterlegen:
      { Colour= "#ff0000", Bold=true },
    }

Es wird empfohlen, eigene Keyword-Gruppen in Plugin-Skripten zu definieren, um keine Original-Dateien verändern zu müssen.

Plug-ins

Die --plug-in Option erwartet den Names eines Lua Skripts, das Elemente einer Sprachdefintion oder eines Themes überschreiben oder erweitern kann. Mit Hilfe dieser Plugins kann die Ausgabe angepasst werden, ohne installierte Konfigurations-Dateien ändern zu müssen.

Format:

-- function definitions, variables etc

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

Type:  String, ist eins von ["theme", "lang"]
Chunk: Name einer Lua-Funktion

Wenn type den Wert "theme" hat, wird die Funktion auf ein Farbschema angewandt, bei dem Wert "lang" bezieht sich die Funktion auf eine Sprachdefinition.

Die "Chunk"-Funktion erhält einen optionalen Parameter mit der Beschreibung des Farbschemas bzw. der Sprachdefinition ("Description"-Parameter). Die Funktionen werden nach dem Laden der Konfigurationsskripte ausgeführt, daher kann auf die Elemente dieser Skripte zugegriffen werden.

Beispiel:

01 -- function to update language definition with syslog levels
02 function syntaxUpdate(desc)
03   if desc=="C and C++" then
04     table.insert( Keywords,
05                   { Id=5, List={"LOG_EMERG", "LOG_CRIT", "LOG_ALERT",
06                     "LOG_ERR", "LOG_WARNING","LOG_NOTICE","LOG_INFO",
07                     "LOG_DEBUG"}
08                   } )
09   end
10 end
11 
12 -- function to update theme definition
13 function themeUpdate(desc)
14   if desc=="Kwrite Editor" then
15     Canvas={ Colour="#E0EAEE" }
16   end
17   table.insert(Keywords, {Colour= "#ff0000", Bold=true})
18 end
19 
20 Plugins={
21   { Type="theme", Chunk=themeUpdate },
22   { Type="lang", Chunk=syntaxUpdate },
23 }

Dateizuordnungen

In filetypes.conf werden alle Dateizuordnungen und Shebang-Definitionen eingetragen.

Format:

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

Lang:       String, Name der Sprachdefinition
Extensions: Liste, enthält alle Dateiendungen, die "Lang" zugeordnet werden
Shebang:    String, Regulärer Ausdruck der mit der ersten Zeile der Eingabe
            verglichen wird

Highlight integrieren

Beispielskripte

Im /examples Unterverzeichnis befinden sich Beispielskripte in PHP, Perl und Python, die highlight aufrufen und die Ausgabe als String auswerten. Diese Skripte können als Ausgangspunkt für neue Plug-ins genutzt werden.

SWIG Schnittstelle

Eine SWIG Interface-Datei befindet sich in /examples/swig. Installationshinweise finden Sie in README_SWIG, Programmierbeispiele in den vorhandenen Skripten.

Skripte und Plug-Ins für Drittsoftware

Im /examples/web_plugins Unterverzeichnis der highlight Installation befinden sich einige Plugins, die Highlight in Webanwendungen integrieren:

DokuWiki
MovableType
Wordpress
Serendipity

Sie finden weitere Anwendungsfälle im Internet:

Kompilieren und installieren

Vorkompilierte Pakete

Highlight ist in ISO C++ geschrieben. Es existieren folgende Pakete:

UNIX Kommandozeilen- und GUI-Anwendung
W32 Kommandozeilen- und GUI-Anwendungli>
Statische/dynamische Bibliothek

Auf der Website www.andre-simon.de sind Links auf vorkompilierte Pakete für weitere Betriebssysteme vorhanden (z.B. Debian, Arch Linux, Ubuntu, Darwin, FreeBSD). Auf der Website sind immer die aktuellsten Source-Pakete (upstream) verfügbar.

Kompilier-Abhängigkeiten

Highlight kompiliert zumindest mit gcc und suncc. Zum Kompilieren sind Boost Header-Pakete und Lua5.1 Development-Pakete nötig. Die optionale GUI benötigt die Qt4 Development-Pakete.
Das makefile enthält weitere Optionen.

Beispielpakete

Unter Packaging resources befinden sich Beispiele für das Paketieren unter Debian und Fedora.

Weitere Informationen befinden sich im Wiki.

English documentation