------------------------------------------------------------------------------- --- HIGHLIGHT HANDBUCH ----- Version 3.41 --------------- November 2017 --- ------------------------------------------------------------------------------- OSI Certified Open Source Software English manual: README INHALT ------------------------------------------------------------------------------- 1. UEBERSICHT 1.1 SINN UND ZWECK 1.2 FUNKTIONSLISTE 1.3 UNTERSTUETZTE PROGRAMMIER- UND AUSZEICHNUNGSSPRACHEN 2. GEBRAUCH UND OPTIONEN 2.1 SCHNELLE EINFUEHRUNG 2.2 CLI OPTIONEN 2.3 GUI OPTIONEN 2.4 EIN- UND AUSGABE 2.5 GNU SOURCE-HIGHLIGHT KOMPATIBILITAET 2.6 FORTGESCHRITTENE OPTIONEN 2.7 UMGEBUNGSVARIABLEN 3. KONFIGURATION 3.1 DATEIFORMAT 3.2 SPRACHDEFINITIONEN 3.3 REGULAERE AUSDRUECKE 3.4 FARBDEFINITIONEN 3.5 SCHLUESSELWORTGRUPPEN 3.6 PLUG-INS 3.7 DATEIZUORDNUNGEN 3.8 PFADE DER KONFIG-DATEIEN 4. HIGHLIGHT INTEGRIEREN 4.1 BEISPIELSKRIPTE 4.2 PANDOC 4.3 SWIG 4.4 TCL 4.5 SKRIPTE UND PLUG-INS FUER DRITTSOFTWARE 5. KOMPILIEREN UND INSTALLIEREN 5.1 VORKOMPILIERTE PAKETE 5.2 KOMPILIER-ABHAENGIGKEITEN 6. ENTWICKLERKONTAKT 1. UEBERSICHT ------------------------------------------------------------------------------- Highlight konvertiert Sourcecode in XHTML, HTML, RTF, ODT, TeX, LaTeX, SVG, BBCode, Pango Markup und Terminal Escape-Sequenzen mit farbiger Syntaxhervorhebung. Sprachdefinitionen und Farbstile sind konfigurierbar. 1.1 SINN UND ZWECK ------------------------------------------------------------------------------- Highlight wurde mit dem Ziel entworfen, einen flexiblen und einfach zu bedienenden Syntaxhighlighter fuer mehrere Ausgabeformate anzubieten. Statt hartkodierter Sprachbeschreibungen und Farbschemata sind alle wichtigen Informationen in Konfigurationsskripten enthalten. Diese Lua-Skripte koennen mit Plug-Ins angepasst und erweitert werden. 1.2 FUNKTIONSLISTE ------------------------------------------------------------------------------- * Hervorhebung von Schluesselwoertern, Typbezeichnern, Strings, Zahlen, Escapesequenzen, Operatoren, Praeprozessor-Direktiven und Kommentaren * Farbige Ausgabe in HTML, XHTML, RTF, TeX, LaTeX, SVG, BBCode, Pango Markup und Terminal-Escapesequenzen * Speichern von Stylesheets wahlweise in separater Datei oder innerhalb der Ausgabedatei (HTML, LaTeX, TeX, SVG) * Alle Konfigurationsdateien sind Lua-Skripte * Unterstuetzt Plug-In Skripte zur Anpassung von Sprachdefinitionen und Themes * Syntax-Elemente werden als regelaere Ausdruecke oder als Stringlisten beschrieben * Erweiterbare Schluesselwort-Gruppen * Erkennung mehrerer Sprachen innerhalb einer Datei * Neuformatierung und Einrueckung von C, C++, C# und Java Code * Umbrechen von langen Zeilen * Anpassbare Ausgabe von Zeilennummern 1.3 UNTERSTUETZTE PROGRAMMIER- UND AUSZEICHNUNGSSPRACHEN ------------------------------------------------------------------------------- Die Liste aller unterstuetzten Sprachen befindet sich in README_LANGLIST. Das Kommando "highlight --list-scripts=langs" zeigt ebenfalls eine Liste aller Sprachen und den verknuepften Dateiendungen. 2. GEBRAUCH UND OPTIONEN ------------------------------------------------------------------------------- 2.1 SCHNELLE EINFUEHRUNG ------------------------------------------------------------------------------- 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 (siehe 2. Beispiel), 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.tex --reformat horstmann --style neon Folgende Ausgabeformate koennen 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 Schriftgroesse anpassen: highlight --syntax ada --font-size 12 --font "'Courier New',monospace" highlight --syntax ada --out-format=latex --font-size tiny --font sffamily - Ausgabeverzeichnis definieren: highlight -d some/target/dir/ *.cpp *.h 2.2 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 print this help -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 supress progress info in batch mode -S, --syntax=<type> specify type of source code -v, --verbose print debug info --force generate output if input syntax is unknown --list-scripts=<type> list installed scripts <type> = [langs, themes, plugins] --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~') --start-nested=<lang> define nested language which starts input without opening delimiter --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, banner, gnu, horstmann, java, kr, linux, mozilla, otbs, vtk, stroustrup, whitesmith, google, pico, lisp] -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) -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 (theme) -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 --delim-cr set CR as end-of-line delimiter (MacOS 9) --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 omit trailing newline --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) 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 2.3 GUI OPTIONEN ------------------------------------------------------------------------------- Die graphische Oberflaeche bietet eine Teilmenge der CLI-Funktionen. Sie enthaelt eine dynamische Vorschau der sichtbaren Ausgabe. Auf der Projekt-Webseite finden Sie Screenshots und Screencasts. Wird highlight-gui mit der Option --portable gestartet, speichert es die Einstellungen im Programmverzeichnis (anstatt zB. die Registry zu benutzen). 2.4 EIN- UND AUSGABE ------------------------------------------------------------------------------- Wenn kein Dateiname mit --input bzw. --output angegeben wird, benutzt highlight stdin bzw. stdout fuer 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 fuer die Programmiersprache uebliche Dateierweiterung). Beispiel: Wenn Sie eine Python-Datei konvertieren wollen, muss highlight die Sprachdefinition py.lang einlesen. Das korrekte Argument fuer --syntax ist also "py". highlight test.py # Option --syntax nicht noetig highlight < test.py --syntax py # --syntax muss angegeben werden cat test.py | highlight --syntax py Sollte es mehrere Dateierweiterungen fuer 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 uebergeben 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, zusaetzlich wird die Dateierweiterung des gewaehlten Ausgabeformats angehangen. Sollte es in den Eingabeverzeichnissen Dateien mit identischem Namen geben, so werden diese Ausgabedateien mit ihrem Quellverzeichnis als Praefix ausgegeben. Die --outdir Option ist im Batch Modus besonders nuetzlich. In Skripten sollte --quiet angegeben werden, um die Geschwindigkeit der Verarbeitung zu erhoehen. HTML, TeX, LaTeX und SVG Ausgabe: -------------------------------- Die HTML, TeX, LaTeX und SVG-Formate erlauben die Einbindung von Stylesheets, welche die Formatierungsinformationen enthalten. Bei der HTML- und SVG-Ausgabe enthaelt diese Datei CSS-Definitionen und wird, wenn nicht anders angegeben, als "highlight.css" gespeichert. Bei TeX und LaTeX enthaelt 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 fuegt 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 koennen, auf die alle Ausgabedokumente verweisen. Mit --style-infile kann eine Datei mit zusaetzlichen Formatierungsangaben in die Ausgabedateien eingebunden werden, welche die vorgegebene highlight- Formatierung erweitert oder ueberschreibt. Hinweis: Ein Plug-In Skript ist die bessere Methode das Styling anzupassen. Terminal-Ausgabe: -------------------- Da es nur wenige Farben zur ANSI-Ausgabe im Terminal gibt, existiert nur ein hartkodiertes Farbschema fuer --out-format=ansi. Daher sollte nach Moeglichkeit --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 unterstuetzt. Neuere Terminal-Emulatoren unterstuetzen auch 16 Millionen Farben, dies wird mit --out-format=truecolors aktiviert. 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. 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. 2.5 GNU SOURCE-HIGHLIGHT KOMPATIBILITAET ------------------------------------------------------------------------------- Die Kommandozeilenschnittstelle ueberschneidet 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 Diese Optionen wurden hinzugefuegt, um die Kompatibilitaet 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 fuer Skripte, Plugins etc. 2.6 FORTGESCHRITTENE OPTIONEN ------------------------------------------------------------------------------- Parsen von Binaerdaten vermeiden -------------------------------- Wird highlight mit unbekannten Eingabedaten aufgerufen, verhindert --validate-input die Verarbeitung von binaeren Daten. Dieser Schalter fuehrt zu einem Vergleich der Datei-Header mit einer Liste von "Magic Numbers". Wenn ein Binaer-Typ erkannt wird, bricht highlight die Verarbeitung mit einer Fehlermeldung ab. Mit --validate-input wird zusaetzlich der UTF-8 BOM in der Ausgabe unterdrueckt. Hervorhebung von eingebettetem Code ohne oeffnenden Delimiter ------------------------------------------------------------- Wenn eine Datei mit eingebettetem Code ohne einen fuer diese Syntax ueblichen einleitenden Delimiter beginnt, kann mit der --start-nested Option in diese Sprache gewechselt werden. Dies kann bei LuaTeX Dateien noetig sein: highlight luatex.tex --latex --start-nested=inc_luatex Die inc_luatex Definition ist eine Lua-Beschreibung mit TeX Kommentaren. Neue Konfigurationsskripte testen: ---------------------------------- Die Option --config-file ermoeglicht es, neue Skripte vor der Installation zu testen. Die 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. UTF8 BOM entfernen: ------------------- Geben Sie --validate-input an, um das UTF8 Byte Order Mark (Startsequenz) zu entfernen. Ausgabe in stdout erzwingen --------------------------- Mit --stdout wird die Ausgabe auch im Batch-Modus nach stdout ausgegeben. Portable GUI (Windows build) ---------------------------- Starten Sie highlight-gui.exe mit der --portable Option, damit die Konfiguration in Textdateien und nicht in der Registry gespeichert wird. 2.7 UMGEBUNGSVARIABLEN ------------------------------------------------------------------------------- Die Kommandozeilenversion beruecksichtigt folgende Variablen: HIGHLIGHT_DATADIR: setzt den Pfad zum Konfigurationsverzeichnis HIGHLIGHT_OPTIONS: kann Kommandozeilenoptionen enthalten, aber keine Pfade zu Eingabedateien 3. KONFIGURATION ------------------------------------------------------------------------------- 3.1 DATEIFORMAT ------------------------------------------------------------------------------- Die Konfigurationsdateien sind Lua Skripte. Deutsche Einfuehrung in die Syntax: http://www.fh-wedel.de/~si/seminare/ws09/Ausarbeitung/09.lua/lua1.htm Das vollstaendige Lua-Handbuch befindet sich hier: http://www.lua.org/manual/5.1/manual.html Folgende Syntax-Elemente genuegen, 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. Highlight entfernt diese Leerzeichen beim Einlesen. Ist der String ein regulaerer Ausdruck mit einem Ausdruck wie [[:space:]], muss der Stringbegrenzer mit einem "Fueller" verwendet werden: [=[ regex string ]=] Kommentare: -- Einzeiliger Kommentar --[[ Blockkommentar ]] Arrays: array = { first=1, second="2", 3, { 4,5 } } Arrays koennen Variablen enthalten und geschachtelt sein. 3.2 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: <uebliche Erweiterung der Sourcecodedateien>.lang Beispiele: PHP -> php.lang, Java -> java.lang Sollte es mehrere gebrauechliche Erweiterungen geben, werden diese in der Datei filetypes.conf einer Sprachdefinition zugeordnet. Syntax-Elemente: Keywords = { Id, List|Regex, Group? } Id: Integer, ID der Schluesselwortgruppe (Werte 1-4, die mehrfach verwendet werden koennen) 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 zurueck- gegeben (gezaehlt 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, 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 Description: String, Beschreibung der Syntax 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 verfuegbar: HL_LANG_DIR: Verzeichnis der Sprachdefinitionen (Parameter der Lua dofile-Funktion) Identifiers: Default regex fuer Bezeichner Digits: Default regex fuer Zahlenliterale Diese Integer-Variablen beschreiben die internen Zustaende 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_INTERPOLATION 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_INTERPOLATION_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) 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 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. Beispiele: function OnStateChange(oldState, newState, token) if token=="]]" and oldState==HL_STRING and newState==HL_BLOCK_COMMENT_END then return HL_STRING_END end return newState end Diese Funktion loest ein Parsing-Problem in Lua, weil der Begrenzer "]]" Kommentare und Strings abschliessen kann. function OnStateChange(oldState, newState, token) if token=="'" and oldState==HL_NUMBER and newState==HL_STRING then return HL_NUMBER end return newState end Dieser Hook ermoeglicht das korrekte Parsen von C++14 Zahl-Literalen. Weitere Funktionen sind in README_PLUGINS beschrieben. Beispiel: --------- Description="C and C++" Keywords={ { Id=1, List={"goto", "break", "return", "continue", "asm", "case", "default", -- [..] } }, -- [..] } Strings = { Delimiter=[["|']], RawPrefix="R", } Comments = { { Block=true, Nested=false, Delimiter = { [[\/\*]], [[\*\/]] } }, { Block=false, Delimiter = { [[//]] } } } IgnoreCase=false PreProcessor = { Prefix=[[#]], Continuation="\\", } Operators=[[\(|\)|\[|\]|\{|\}|\,|\;|\.|\:|\&|\<|\>|\!|\=|\/|\*|\%|\+|\-|\~]] EnableIndentation=true 3.3 REGULAERE AUSDRUECKE ------------------------------------------------------------------------------- Die Datei README_REGEX beschreibt alle unterstuetzten Ausdruecke. 3.4 FARBDEFINITIONEN ------------------------------------------------------------------------------- Farbdefinitionen legen die Formatierung der Sprachelemente fest, die in den Sprachdefinitionen beschrieben wurden. Die Dateien muessen 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 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) Interpolation = Attributes (Formatierung von Interpolationen) PreProcessor = Attributes (Formatierung von Praeprozessor-Direktiven) StringPreProc = Attributes (Formatierung von Strings in Praeprozessor-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 Schluesselwoertgruppen. Es sollten mindestens vier Elemente angegeben werden, um mit der Anzahl von Schluesselwortgruppen in den Sprachdefinitionen uebereinzustimmen. Beispiel: Default = { Colour="#000000" } Canvas = { Colour="#ffffff" } Number = { Colour="#000000" } Escape = { Colour="#bd8d8b" } String = { Colour="#bd8d8b" } StringPreProc = { Colour="#bd8d8b" } BlockComment = { Colour="#ac2020", Italic=true } PreProcessor = { Colour="#000000" } LineNum = { Colour="#555555" } Operator = { Colour="#000000" } LineComment = BlockComment Keywords = { { Colour= "#9c20ee", Bold=true }, { Colour= "#208920" }, { Colour= "#0000ff" }, { Colour= "#000000" }, } 3.5 SCHLUESSELWORTGRUPPEN ------------------------------------------------------------------------------- Sie koennen eigene Schluesselwort-Gruppen festlegen und jeder Gruppe eine eigene Formatierung zuweisen. Das ist nuetzlich wenn Sie z.B. Bibliotheksfunktionen, Makros oder Konstanten gesondert hervorheben moechten. Eine Gruppe wird in zwei Schritten definiert: 1. Beschreibung der Gruppe in der Sprachdefinition: Keywords = { -- fuegen Sie die Beschreibung an: {Id=5, List = {"ERROR", "DEBUG", "WARN"} } } 2. Festlegung des dazugehoerigen Farbstils im Farb-Schema: Keywords= { --Stil als fuenften Eintrag hinterlegen: { Colour= "#ff0000", Bold=true }, } Es wird empfohlen, eigene Keyword-Gruppen in Plugin-Skripten zu definieren, um keine Original-Dateien zu veraendern. Weitere Infos finden sich im cpp_qt.lua Beispiel-Plugin sowie in README_PLUGINS. 3.6 PLUG-INS ------------------------------------------------------------------------------- Die --plug-in Option erwartet den Pfad eines Lua Skripts, das Elemente einer Sprachdefinition oder eines Themes ueberschreibt oder erweitert. Mit Hilfe dieser Plugins kann die Ausgabe angepasst werden, ohne installierte Konfigurations-Dateien zu aendern. Man kann mehrere Plugins anwenden, indem die --plug-in Option wiederholt angegeben wird. Siehe README_PLUGINS um mehr darueber zu erfahren. 3.7 DATEIZUORDNUNGEN ------------------------------------------------------------------------------- In filetypes.conf werden Dateizuordnungen und Shebang-Definitionen eingetragen. Eine Konfiguration ist nur dann zwingend notwendig, wenn es mehrere Dateiendungen fuer eine Syntax gibt oder eine Endung nicht eindeutig zugewiesen werden kann. Ansonsten wird die Syntax geladen, deren Name mit der Dateiendung der Eingabedatei uebereinstimmt. Format: FileMapping={ { Lang, Filenames|Extensions|Shebang }, } Lang: String, Name der Sprachdefinition Filenames: Liste, enthaelt alle Dateinamen, die "Lang" zugeordnet werden Extensions: Liste, enthaelt alle Dateiendungen, die "Lang" zugeordnet werden Shebang: String, Regulaerer Ausdruck der mit der ersten Zeile der Eingabe verglichen wird Verhalten der Software bei mehrdeutigen Endungen: - CLI: die erste eingetragene Verknuepfung wird angewandt - GUI: eine Syntax-Auswahl wird angezeigt Tragen Sie neue Dateiendungen auch in gui_files/ext/fileopenfilter.conf ein, damit diese im GUI-Dateiauswahldialog als Filter angezeigt werden. 3.8 PFADE DER KONFIG-DATEIEN ------------------------------------------------------------------------------- Konfigurationsskripte werden in folgenden Verzeichnissen gesucht: 1. ~/.highlight/ 2. Wert der Umgebungsvariablen HIGHLIGHT_DATADIR 3. benutzerdefiniertes Verz., definiert mit --data-dir (deprecated) 4. /usr/share/highlight/ 5. /etc/highlight/ (wegen filetypes.conf) 6. aktuelles Arbeitsverzeicnnis (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. Diese Suchreihenfolge vereinfacht die Erweiterung und Anpassung bestehender Skripte, ohne vorinstallierte Dateien umkopieren zu muessen. 4. HIGHLIGHT EINBETTEN ------------------------------------------------------------------------------- 4.1 BEISPIELSKRIPTE ------------------------------------------------------------------------------- Im extras/ Unterverzeichnis befinden sich Beispielskripte in PHP, Perl und Python, die highlight aufrufen und die Ausgabe als String auswerten. Diese Skripte koennen als Ausgangspunkt fuer neue Erweiterungen genutzt werden. 4.2 PANDOC ------------------------------------------------------------------------------- PP Makros und eine Anleitung dazu liegen in extras/pandoc. 4.3 SWIG ------------------------------------------------------------------------------- Eine SWIG Interface-Datei befindet sich in extras/swig. Installationshinweise stehen in README_SWIG, Beispiele sind in Perl, PHP und Python vorhanden. 4.4 TCL ------------------------------------------------------------------------------- Eine TCL-Erweiterung befindet sich in /extras/tcl. Installationshinweise stehen in README_TCL. 4.5 SKRIPTE UND PLUG-INS FUER DRITTSOFTWARE ------------------------------------------------------------------------------- Im extras/web_plugins Unterverzeichnis befinden sich einige Plugins, die Highlight in Webanwendungen integrieren: -DokuWiki -MovableType -Wordpress -Serendipity Andere Anwendungen von highlight sind auf andre-simon.de aufgelistet. Diese Seite verweist auf unterschiedliche Projekte die highlight integrieren, z.B. Webgit, Evolution, Inkscape, Ranger, ...). 5. KOMPILIEREN UND INSTALLIEREN ------------------------------------------------------------------------------- 5.1 VORKOMPILIERTE PAKETE ------------------------------------------------------------------------------- Highlight ist in ISO C++ geschrieben. Es existieren folgende Pakete: - UNIX Kommandozeilen- und GUI-Anwendung - Windows Kommandozeilen- und GUI-Anwendung - Statische/dynamische Bibliothek Auf der Website www.andre-simon.de sind Links auf vorkompilierte Pakete fuer weitere Betriebssysteme vorhanden (z.B. Debian, Arch Linux, Ubuntu, Darwin, FreeBSD). Auf der Website sind immer die aktuellsten Source-Pakete (upstream) verfuegbar. Source tarball Windows und MacOS executables http://www.andre-simon.de Arch Linux http://www.archlinux.org/packages/community/i686/highlight/ Debian GNU/Linux https://packages.debian.org/search?keywords=highlight Fedora http://koji.fedoraproject.org/koji/packageinfo?packageID=2044 FreeBSD http://www.freshports.org/textproc/highlight/ Gentoo Portage https://packages.gentoo.org/packages/app-text/highlight Mac OS X http://braumeister.org/formula/highlight Slackware http://sotirov-bg.net/slackpack/search.cgi?q=highlight SuSE http://packman.links2linux.de/package/highlight Ubuntu http://packages.ubuntu.com/oneiric/allpackages Windows Chocolatey https://chocolatey.org/packages/highlight In INSTALL befinden sich weitere Informationen zu Paketinhalt und Installation. 5.2 KOMPILIER-ABHAENGIGKEITEN ------------------------------------------------------------------------------- Highlight kompiliert zumindest mit gcc und clang. Zum Kompilieren sind Boost Header-Pakete und Lua5.x/LuaJit Development-Pakete noetig. Die optionale GUI benoetigt Qt5 Development-Pakete. Im Makefile finden Sie weitere Informationen. 6. ENTWICKLERKONTAKT ------------------------------------------------------------------------------- Andre Simon andre.simon1@gmx.de http://www.andre-simon.de sf.net Projekt mit SVN Repository, Download Mirror, Bugtracker, Foren: http://sourceforge.net/projects/syntaxhighlight/ Github Projekt mit Git Repository, Bugtracker: https://github.com/andre-simon/highlight
Generated by dwww version 1.15 on Wed Jun 26 02:57:13 CEST 2024.