Highlight

*** Since Github is now part of Mordor Corp, the highlight Git repo *** *** moved to https://gitlab.com/saalen/highlight ***

---

--- HIGHLIGHT MANUAL ------- Version 3.43 ------------------ April 2018 ---

OSI Certified Open Source Software

Deutsche Anleitung: README_DE

CONTENT

1. OVERVIEW 1.1 INTENDED PURPOSE 1.2 FEATURE LIST 1.3 SUPPORTED PROGRAMMING AND MARKUP LANGUAGES

2. USAGE AND OPTIONS 2.1 QUICK INTRODUCTION 2.2 CLI OPTIONS 2.3 GUI OPTIONS 2.4 INPUT AND OUTPUT 2.5 GNU SOURCE-HIGHLIGHT COMPATIBILITY 2.6 ADVANCED OPTIONS 2.7 ENVIRONMENT VARIABLES

3. CONFIGURATION 3.1 FILE FORMAT 3.2 LANGUAGE DEFINITIONS 3.3 REGULAR EXPRESSIONS 3.4 THEME DEFINITIONS 3.5 KEYWORD GROUPS 3.6 PLUG-INS 3.7 FILE MAPPING 3.8 CONFIG FILE SEARCH

4. EMBEDDING HIGHLIGHT 4.1 SAMPLE SCRIPTS 4.2 PANDOC 4.3 SWIG 4.4 TCL 4.5 THIRD PARTY SCRIPTS AND PLUG-INS

5. BUILDING AND INSTALLING 5.1 PRECOMPILED PACKAGES 5.2 BUILDING DEPENDENCIES

6. DEVELOPER CONTACT

7. OVERVIEW

---

Highlight converts sourcecode to HTML, XHTML, RTF, ODT, LaTeX, TeX, SVG, BBCode, Pango markup and terminal escape sequences with coloured syntax highlighting. Language definitions and colour themes are customizable.

1.1 INTENDED PURPOSE

Highlight was designed to offer a flexible but easy to use syntax highlighter for several output formats. No syntax or colouring information is hardcoded, instead all relevant data is stored in configuration scripts. These Lua scripts may be altered and enhanced with plug-in scripts.

1.2 FEATURE LIST

• highlighting of keywords, types, strings, numbers, escape sequences, comments, operators and preprocessor directives
• coloured output in HTML, XHTML 1.1, RTF, TeX, LaTeX, SVG, BBCode, Pango Markup and terminal escape sequences
• supports referenced stylesheet files for HTML, LaTeX, TeX or SVG output
• configuration files are Lua scripts
• supports plug-in scripts to tweak language definitions and themes
• syntax elements are defined as regular expressions or plain string lists
• customizable keyword groups
• recognition of nested languages within a file
• reformatting and indentation of C, C++, C# and Java source code
• wrapping of long lines
• configurable output of line numbers

1.3 SUPPORTED PROGRAMMING AND MARKUP LANGUAGES

Please see README_LANGLIST for the current set of supported languages. You may also run "highlight --list-scripts=langs" to get a list and associated file extensions.

2. USAGE AND OPTIONS

---

2.1 QUICK INTRODUCTION

The following examples show how to produce a highlighted C++ file, using main.cpp as input file:

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

  You will find the HTML file and highlight.css in the working directory. If you use IO redirection (2nd example), you must define the programming language with --syntax.

• Generate HTML with embedded CSS definitions and line numbers: highlight -i main.cpp -o main.cpp.html --include-style --line-numbers

• Generate HTML with inline CSS definitions: highlight -i main.cpp -o main.cpp.html --inline-css

• Generate LaTeX using "horstmann" source formatting style and "neon" colour theme: highlight -O latex -i main.cpp -o main.cpp.tex --reformat horstmann --style neon

  The following output formats may be defined with --out-format:

  html: HTML5 (default) 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

• Customize font settings: highlight --syntax ada --font-size 12 --font "'Courier New',monospace" highlight --syntax ada --out-format=latex --font-size tiny --font sffamily

• Define an output directory: highlight -d some/target/dir/ *.cpp *.h

See "highlight --help" or "man highlight" for more details.

2.2 CLI OPTIONS

The command line version of highlight offers the following options:

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)

La