Highlight Dokumentation

Highlight Handbuch

Inhalt

Übersicht
1. Sinn und Zweck
2. Features
Gebrauch und Optionen
Konfiguration

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

Features

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
Unterstützt 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)

Gebrauch und Optionen

Schnelle Einführung

Folgende Beispiele zeigen, wie man die farbige HTML-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

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

  Folgende Ausgabeformate können mit --out-format bestimmt werden:

  html:      HTML5 (Standard)
  xhtml:     XHTML 1.1
  tex:       Plain TeX
  latex:     LaTeX
  rtf:       RTF
  odt:       OpenDocument Text (Flat XML)
  svg:       SVG
  bbcode:    BBCode
  pango:     Pango markup
  ansi:      Terminal 16 color escape codes
  xterm256:  Terminal 256 color escape codes
  truecolor: Terminal 16m color escape codes

- 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
     --config-file=<file>       set path to a lang or theme file
 -d, --outdir=<directory>       name of output directory
 -h, --help[=topic]             print this help or a topic description
                                  <topic> = [syntax, theme, plugin, config, test, lsp]
 -i, --input=<file>             name of single input file
 -o, --output=<file>            name of single output file
 -P, --progress                 print progress bar in batch mode
 -q, --quiet                    suppress progress info in batch mode
 -S, --syntax=<type|path>       specify type of source code or syntax file path
     --syntax-by-name=<name>    specify type of source code by given name
                                  will not read a file of this name, useful for stdin
     --syntax-supported         test if the given syntax can be loaded
 -v, --verbose                  print debug info; repeat to show more information
     --force[=syntax]           generate output if input syntax is unknown
     --list-scripts=<type>      list installed scripts
                                  <type> = [langs, themes, plugins]
     --list-cat=<categories>    filter the scripts by the given categories
                                  (example: --list-cat='source;script')
     --max-size=<size>          set maximum input file size
                                  (examples: 512M, 1G; default: 256M)
     --plug-in=<script>         execute Lua plug-in script; repeat option to
                                  execute multiple plug-ins
     --plug-in-param=<value>    set plug-in input parameter
     --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~')
     --stdout                   output to stdout (batch mode, --print-style)
     --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, odt, rtf,
                                  ansi, xterm256, truecolor, bbcode, pango, svg]
 -c, --style-outfile=<file>     name of style file or print to stdout, if
                                  'stdout' is given as file argument
 -e, --style-infile=<file>      to be included in style-outfile (deprecated)
                                  use a plug-in file instead
 -f, --fragment                 omit document header and footer
 -F, --reformat=<style>         reformats and indents output in given style
                                  <style> = [allman, gnu, google, horstmann,
                                  java, kr, linux, lisp, mozilla, otbs, pico,
                                  vtk, ratliff, stroustrup, webkit, whitesmith]
 -I, --include-style            include style definition in output file
 -J, --line-length=<num>        line length before wrapping (see -V, -W)
 -j, --line-number-length=<num> line number width incl. left padding (default: 5)
     --line-range=<start-end>   output only lines from number <start> to <end>
 -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|path>       set colour style (theme) or theme file path
 -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 set to NONE
 -V, --wrap-simple              wrap lines after 80 (default) characters w/o
                                  indenting function parameters and statements
 -W, --wrap                     wrap lines after 80 (default) characters
     --wrap-no-numbers          omit line numbers of wrapped lines
                                  (assumes -l)
 -z, --zeroes                   pad line numbers with 0's
     --isolate                  output each syntax token separately (verbose output)
     --keep-injections          output plug-in injections in spite of -f
     --kw-case=<case>           change case of case insensitive keywords
                                  <case> =  [upper, lower, capitalize]
     --no-trailing-nl[=mode]    omit trailing newline. If mode is empty-file, omit
                                  only for empty input
     --no-version-info          omit version info comment


(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=<name>        set CSS class name prefix;
                                  omit class name if set to NONE
     --inline-css               output CSS within each tag (verbose output)
     --enclose-pre              enclose fragmented output with pre tag
                                  (assumes -f)


LaTeX output options:

 -b, --babel                    disable Babel package shorthands
 -r, --replace-quotes           replace double quotes by \dq{}
     --beamer                   adapt output for the Beamer package
     --pretty-symbols           improve appearance of brackets and other symbols


RTF output options:

     --page-color               include page color attributes
 -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)


Terminal escape output options (xterm256 or truecolor):

     --canvas[=width]           set background colour padding (default: 80)


Language Server options:

     --ls-profile=<server>      read LSP configuration from lsp.conf
     --ls-delay=<ms>            set server initialization delay
     --ls-exec=<bin>            set server executable name
     --ls-option=<option>       set server CLI option (can be repeated)
     --ls-hover                 execute hover requests (HTML output only)
     --ls-semantic              retrieve semantic token types (requires LSP 3.16)
     --ls-syntax=<lang>         set syntax which is understood by the server
     --ls-syntax-error          retrieve syntax error information
                                  (assumes --ls-hover or --ls-semantic)
     --ls-workspace=<dir>       set workspace directory to init. the server


If no in- or output files are specified, stdin and stdout will be used.
Reading from stdin can also be triggered using the '-' option.
Default output format: xterm256 or truecolor if appropriate, HTML otherwise.
Style definitions are stored in highlight.css (HTML, XHTML, SVG) or
highlight.sty (LaTeX, TeX) if neither -c nor -I is given.
Reformatting code (-F) will only work with C, C++, C# and Java input files.
LSP features require absolute input paths and disable reformatting (-F)
Wrapping lines with -V or -W will cause faulty highlighting of long single
line comments and directives. Using line-range might interfere with multi
line syntax elements. Use with caution.

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

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.

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 oder --out-format=truecolor verwendet werden, um eine Ausgabe im angegebenen Farbschema zu erhalten.

highlight --out-format=ansi <inputfile> | less -R
highlight --out-format=xterm256 -srdark <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:

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

Parsen von Binärdaten vermeiden

Wird highlight mit unbekannten Eingabedaten aufgerufen, verhindert --validate-input die Verarbeitung von binären Daten. 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.

Hervorhebung 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

→ Mehr Infos hierzu im Wiki

Sprachdefinitionen debuggen

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

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

Weitere Informationen finden sich im Lua Handbuch (en) .

Reguläre Ausdrücke

Siehe Reguläre Ausdrücke.

Sprachdefinitionen

Eine Sprachdefinition beschreibt die Elemente einer Programmiersprache, die durch verschiedene Farben und Schrifttypen hervorgehoben werden. Die Datei muss in 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 filetypes.conf einer Sprachdefinition zugeordnet.

Syntax-Elemente:

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

  Id:          Integer, ID der Schluesselwortgruppe (mehrfach verwendbar)
               Default-Themes unterstuetzen 4  Gruppen, Base16-Themes 6.
  List:        Liste, Auflistung von Schluesselwoertern
  Regex:       String, Regulaerer Ausdruck
  Group:       Integer, Capturing Group ID der Regex, bestimmt den Teil des
               gefundenen Ausdrucks, der als Schluesselwort hervorgehoben werden
               soll (optional, wenn nicht gesetzt wird der Match mit der
               hoechsten Group-ID zurueckgegeben (Zaehlung von links nach rechts))
  Priority:    Integer, wenn nicht Null werden keine weiteren Ausdruecke
               ausgewertet wenn diese Regex einen Treffer liefert
  Constraints: Tabelle, bestehend aus:
               Line: Integer, begrenzt Suche auf die Zeilennummer,
               Filename: String, begrenzt Suche auf den DAteinamen

Regulaere Ausdruecke werden in ihrer Reihenfolge innerhalb von Keywords ausgewertet.
Sollte ein Ausdruck nicht funktionieren, koennte ein vorher definierter Ausdruck
ebenfalls matchen und einen Konflikt ausloesen.

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, enthaelt Regex der oeffnenden Begrenzer (Zeilenkommentar) oder
             Regex des oeffnenden und des schliessenden Begrenzers (Blockkommentar)


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

  Delimiter:         String, Regulaerer Ausdruck der Begrenzer
  DelimiterPairs:    Liste, enthaelt Ausdruecke der oeffnenden und der schliessenden
                     Begrenzer wenn diese nicht gleich sind und optional ein Raw-
                     String Flag
  Escape:            String, Regulaerer Ausdruck fuer Escapsesequenzen (optional)
  Interpolation:     String, Regulaerer Ausdruck fuer Interpolation (optional)
  RawPrefix:         String, definiert Raw String Prefix (optional)
  AssertEqualLength: Boolean, True wenn die Begrenzer gleich lang sein muessen


PreProcessor = { Prefix, Continuation? }

  Prefix:        String, Regulaerer Ausdruck der oeffnenden Begrenzer
  Continuation:  String, Definiert Fortsetzungsindikator (optional)


NestedSections = {Lang, Delimiter= {} }

  Lang:      String, Name der eingebetteten Sprache
  Delimiter: Liste, Ausdruecke der oeffnenden und der schliessenden Begrenzer


KeywordFormatHints={ { Id, Bold?, Italic?, Underline? } }
  Id:         Integer, Id der Schluesselwortgruppe deren Attribute geaendert werden
  Bold:       Boolean, font weight property
  Italic:     Boolean, font style property
  Underline:  Boolean, font decoration property

Diese Angaben werden bei gemischten Syntaxtypen im Batch-Modus ohne --include-style
nicht in allen Faellen uebernommen.

Description:       String, Beschreibung der Syntax

Categories:        Table, Liste von Kategorien (config, source, script, etc)

Digits:            String, Regulaerer Ausdruck fuer Zahlenliterale (optional)

Identifiers:       String, Regulaerer Ausdruck fuer Bezeichner (optional)

Operators:         String, Regulaerer Ausdruck fuer Operatoren

EnableIndentation: Boolean, True wenn Syntax formatiert und eingerueckt werden kann

IgnoreCase:        Boolean, True wenn Sprache nicht case-sensitive 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
HL_REJECT

Die Funktion OnStateChange:

Dieser Hook wird bei Zustandsuebergaengen des Parsers aufgerufen (z.B. beim
Wechsel von HL_STANDARD zu HL_KEYWORD wenn ein Schluesselwort erkannt wurde).
Mit dieser Funktion kann der neue Zustand angepasst werden, oder es koennen
Syntax-Elemente wie Keyword-Listen erweitert werden.

OnStateChange(oldState, newState, token, kwGroupID, lineno, column)

  Hook Event: Zustandswechsel des Parsers
  Parameters: oldState:  bisheriger Zustand
              newState:  geplanter neuer Zustand
              token:     das Token welches den Wechsel ausgeloest hat
              kwGroupID: Wenn newState = HL_KEYWORD, enthaelt dieser Parameter
                         die Gruppen-ID
              lineno:    Zeilennummer (seit 3.50)
              column:    Zeilenspalte (seit 3.50)
  Returns:    den korrekten Zustand zum fortfahren ODER HL_REJECT

HL_REJECT wird dann zurueckgegeben, wenn das Token und der erkannte Zustand
verworfen werden sollen; das erste Zeichzen von Token wird dann ausgegeben und
als "oldState" hervorgehoben.

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

→ Mehr Infos hierzu im Wiki

Farbdefinitionen

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

Die Dateien müssen mit der Endung .theme in themes/ 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
Categories     = Table, Liste von Kategorien (dark, light, etc)
Default        = Attributes (Farbe des nicht hervorgehobenen Texts)
Canvas         = Attributes (Hintergrundfarbe)
Number         = Attributes (Zahlen)
Escape         = Attributes (Escape-Sequenzen)
String         = Attributes (Strings)
Interpolation  = Attributes (Interpolationen)
PreProcessor   = Attributes (Praeprozessor-Direktiven)
StringPreProc  = Attributes (Strings in Praeprozessor-Direktiven)
BlockComment   = Attributes (Blockkommentare)
LineComment    = Attributes (Zeilenkommentare)
LineNum        = Attributes (Zeilennummern)
Operator       = Attributes (Operatoren)
Hover          = Attributes (LSP Hover Elemente)
Error          = Attributes (LSP Syntaxfehler)
ErrorMessage   = Attributes (LSP Fehlerbeschreibungen)

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

AttributesN: Liste, Formatierung von Schlüsselwoertgruppen.

SemanticAttributesN: An array consisting of:
                     `Type`: Token Identifier of the LS protocol (V 3.16)
                     `Style`: formatting of the token

Beispiel:

 1 
 2 Description = "vim zmrok"
 3 
 4 Categories = {"dark", "vim"}
 5 
 6 Default = { Colour="#F8F8F8" }
 7 Canvas = { Colour="#141414" }
 8 Number = { Colour="#FACE43" }
 9 Escape = { Colour="#ffa500" }
10 String = { Colour="#D9FF77" }
11 BlockComment = { Colour="#8a8a8a" }
12 PreProcessor = { Colour="#8b864e" }
13 LineNum = { Colour="#777777" }
14 StringPreProc = String
15 LineComment   = BlockComment
16 Operator      = { Colour="#888888" }
17 Interpolation = { Colour="#D084CE" }
18 
19 Keywords = {
20   { Colour="#A56A30" , Bold=true},
21   { Colour="#C7CA87" },
22   { Colour="#30a630" },
23   { Colour="#3b84cc" },
24   { Colour= "#d484aa" },
25   { Colour= "#ae84d4" },
26 }
27 
28 -- new LSP based elements:
29 
30 SemanticTokenTypes  = {
31   { Type = 'keyword', Style = Keywords[1] },
32   { Type = 'type', Style = Keywords[2] },
33   { Type = 'function', Style = Keywords[4] },
34   { Type = 'method', Style = Keywords[4] },
35   { Type = 'class', Style =  Keywords[1] },
36   { Type = 'struct', Style = Keywords[2] },
37   { Type = 'parameter', Style = Keywords[6] },
38   { Type = 'variable', Style = Keywords[5] },
39   { Type = 'number', Style = Number },
40   { Type = 'regexp', Style = String },
41   { Type = 'operator', Style = Operator },
42 }

→ Mehr Infos hierzu im Wiki

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 },
    }

Plug-ins

Die --plug-in Option erwartet den Names eines Lua Skripts, das Elemente einer Sprachdefintion oder eines Themes überschreibt oder erweitert. Mit Hilfe dieser Plugins kann die Ausgabe angepasst werden, ohne installierte Konfigurations-Dateien ändern zu müssen.
Siehe Plug-Ins zur Beschreibung von Dateiformat und Beispielen.

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

Dateisuche

Konfigurationsskripte werden in folgenden Verzeichnissen gesucht:

1. ~/.highlight/
2. Wert der Umgebungsvariablen HIGHLIGHT_DATADIR
3. benutzerdefiniertes Verz., definiert mit --data-dir
4. /usr/share/highlight/
5. /etc/highlight/ (wegen filetypes.conf)
6. aktuelles Arbeitsverzeichnis (Fallback)

Es wird erwartet, dass folgende Unterverzeichnisse die entsprechenden Skripte enthalten:

-langDefs: *.lang
-themes: *.theme
-plugins: *.lua

Eine eigene filetypes.conf kann direkt in in ~/.highlight/ gespeichert werden.

→ Mehr Infos hierzu im Wiki