1highlight(1) user documentation highlight(1)
2
6 Highlight - a universal sourcecode to formatted text converter
7
10 highlight [OPTIONS]... [FILES]...
11
14 Highlight converts sourcecode to HTML, XHTML, RTF, ODT, LaTeX, TeX,
15 BBCode, Pango markup, SVG, XTERM or ANSI escape sequences. There are
16 several colour themes available. Highlight recognizes keywords, num‐
17 bers, strings, comments, symbols and preprocessor directives. It sup‐
18 ports about 180 programming languages, which are defined in Lua
19 scripts.
20 It's easily possible to enhance highlight's database of programming
23 languages and colour themes. See the README file for details.
24
26 -B, --batch-recursive=<wildcard>
27 convert all files matching the wildcard (uses recursive search)
28 -D, --data-dir=<path>
30 set path to highlight data directory
31 --config-file=<file>
33 set path to a lang or theme file
34 -h, --help[=topic]
36 print this help or a topic description
37 <topic> = [syntax, theme, plugin, config]
38 -i, --input=<file>
40 name of input file
41 -o, --output=<file>
43 name of output file
44 -d, --outdir=<output directory>
46 name of output directory
47 -P, --progress
49 print progress bar in batch mode
50 -S, --syntax=<type|path>
52 set type of source code, necessary if input file suffix is miss‐
53 ing. The syntax may also be defined as path of the language
54 file.
55 --syntax-by-name=<name>
57 specify type of source code by given name. Will not read a file
58 of this name, useful for stdin and to determine the syntax of
59 the file before piping its content to highlight. This option
60 overrides --syntax.
61 -v, --verbose
63 print debug info to stderr
64 -q, --quiet
66 suppress progress info in batch mode
67 --force[=syntax]
69 generate output if input syntax is unknown. The fallback syntax
70 may be set here, Plain Text is default.
71 --list-scripts=<type>
73 list installed scripts <type> = [langs, themes, plugins]
74 --list-cat=<categories>
76 filter the scripts by the given categories (example: --list-
77 cat='source;script')
78 --max-size=<size>
80 set maximum input file size (examples: 512M, 1G; default: 256M)
81 --plug-in=<script>
83 execute Lua plug-in script; repeat option to apply multiple
84 plug-ins
85 --plug-in-param
87 set plug-in input parameter. This might be an input file name
88 (ie. 'tags').
89 --print-config
91 print path configuration
92 --print-style
94 print stylesheet only (see --style-outfile)
95 --skip=<list>
97 ignore listed unknown file types (example: --skip='bak;c~;h~')
98 --start-nested=<lang>
100 define nested language which starts input without opening delim‐
101 iter
102 --stdout
104 output to stdout (batch mode, --print-style)
105 --validate-input
107 test if input is a valid text file
108 --version
110 print version and copyright info
111
114 -O, --out-format=<format>
115 output file in given format <format>=[html, xhtml, latex, tex,
116 rtf, odt, ansi, xterm256, truecolor, bbcode, pango, svg]
117 -c, --style-outfile=<file>
119 name of style definition file
120 -T, --doc-title
122 document title
123 -e, --style-infile=<file>
125 name of file to be included in style-outfile
126 -f, --fragment
128 omit header and footer of the output document (see --keep-injec‐
129 tions)
130 -F, --reformat=<style>
132 reformat output in given style. <style>=[allman, gnu, google,
133 horstmann, java, kr, linux, lisp, mozilla, otbs, pico, vtk,
134 ratliff, stroustrup, webkit, whitesmith, user]
135 The user style does not apply a predefined scheme. Use --refor‐
137 mat-option to define reformatting behaviour.
138 --reformat-option=<opt>
140 apply an astyle cmd line option (assumes -F). Can be repeated to
141 override settings of the chosen indentation scheme.
142 -I, --include-style
144 include style definition in output
145 -J, --line-length=<num>
147 line length before wrapping (see -V, -W)
148 -j, --line-number-length=<num>
150 line number length incl. left padding. Default length: 5
151 -k, --font=<font>
153 set font (specific to output format)
154 -K, --font-size=<num?>
156 set font size (specific to output format)
157 -l, --line-numbers
159 print line numbers in output file
160 -m, --line-number-start=<cnt>
162 start line numbering with cnt (assumes -l)
163 --line-range=<start-end>
165 output only lines from number <start> to <end>
166 -s, --style=<style name|path>
168 set highlighting style (theme). Add 'base16/' prefix to use a
169 Base16 theme. The theme may also be defined as path of the theme
170 file.
171 -t --replace-tabs=<num>
173 replace tabs by num spaces
174 -u, --encoding=<enc>
176 set output encoding which matches input file encoding; omit
177 encoding information if set to "NONE"
178 -V, --wrap-simple
180 wrap lines after 80 (default) characters without indenting func‐
181 tion parameters and statements.
182 -W, --wrap
184 wrap lines after 80 (default) characters (use with caution).
185 -z, --zeroes
187 fill leading space of line numbers with zeroes
188 --base16[=theme]
190 use a theme of the Base16 collection. Use a classic theme other‐
191 wise.
192 --delim-cr
194 set CR as end-of-line delimiter (MacOS 9)
195 --isolate
197 output each syntax token in separate tags (verbose output)
198 --keep-injections
200 output plug-in header and footer injections in spite of -f
201 --kw-case=<upper|lower|capitalize>
203 output all keywords in given case if language is not case sensi‐
204 tive
205 --no-trailing-nl[=mode]
207 omit trailing newline. If mode is "empty-file", omit only for
208 empty input
209 --no-version-info
211 omit version info comment
212 --wrap-no-numbers
214 omit line numbers of wrapped lines (assumes -l)
215
218 -a, --anchors
219 attach anchors to line numbers (HTML only)
220 -y, --anchor-prefix=<str>
222 set anchor name prefix
223 -N, --anchor-filename
225 use input file name as anchor name
226 -C, --print-index
228 print index file with links to all output files
229 -n, --ordered-list
231 print lines as ordered list items
232 --class-name=<str>
234 set CSS class name prefix; omit class name if set to "NONE"
235 --inline-css
237 output CSS within each tag (verbose output)
238 --enclose-pre
240 enclose fragmented output with pre tag (assumes -f)
241
244 -b, --babel
245 disable Babel package shorthands
246 -r, --replace-quotes
248 replace double quotes by \dq
249 --beamer
251 adapt output for the Beamer package
252 --pretty-symbols
254 improve appearance of brackets and other symbols
255
258 --page-color
259 include page color attributes
260 -x, --page-size=<size>
262 set page size, <size>=[a3, a4, a5, b4, b5, b6, letter]
263 --char-styles
265 include character stylesheets
266
269 --height=<h>
270 set image height (units allowed)
271 --width=<w>
273 set image size (see --height)
274
277 --canvas[=width]
278 set background colour padding (default: 80)
279
282 --doc create stand alone document
283 --no-doc
285 cancel the --doc option
286 --css=filename
288 the external style sheet filename
289 --src-lang=STRING
291 source language
292 -t, --tab=INT
294 specify tab length
295 -n, --line-number[=0]
297 number all output lines, optional padding
298 --line-number-ref[=p]
300 number all output lines and generate an anchor, made of the
301 specified prefix
302 p + the line number (default='line')
303 --output-dir=path
305 output directory
306 --failsafe
308 if no language definition is found for the input, it is simply
309 copied to the output
310
313 Highlight recognizes these variables:
314 HIGHLIGHT_DATADIR
316 sets the path to highlight's configuration scripts
317 HIGHLIGHT_OPTIONS
319 may contain command line options, but no input file paths.
320
323 If no in- or output files are specified, stdin and stdout will be used
324 for in- or output. Since version 3.44, reading from stdin can also be
325 triggered by the '-' option.
326 Default output format: xterm256 or truecolor if appropriate, HTML oth‐
328 erwise.
329 Style definitions are stored in highlight.css (HTML, XHTML, SVG) or
331 highlight.sty (LaTeX, TeX) if neither -c nor -I is given. For CSS, def‐
332 initions are stored in the output document header with -I, if -f is
333 also given there will be no style definitions.
334 Reformatting code (-F) will only work with C, C++, C# and Java input
336 files.
337
339 Wrapping lines with -V or -W will cause faulty highlighting of long
340 single line comments and directives. Using line-range might interfere
341 with multi line syntax elements. Use with caution.
342
344 The configuration files are stored in /usr/share/highlight/. Language
345 definitions, themes and plugins are located in subdirectories.
346 Documentation files are stored in /usr/share/doc/highlight/ , configu‐
348 ration files in /etc/highlight/.
349 See README how to install own scripts in the home directory.
351
353 Single file conversion:
354 highlight -o hello.html -i hello.c
356 highlight -o hello.html hello.c
358 highlight -o hello.html -S c < hello.c
360 highlight -S c < hello.c > hello.html
362 Note that a file highlight.css is created in the current directory.
364 Batch file processing:
366 highlight --out-format=xhtml -B '*.cpp' -d /home/you/html_code/
368 converts all *.cpp files in the current directory and its subdirecto‐
370 ries to xhtml files, and stores the output in /home/you/html_code.
371 highlight --out-format=latex * -d /home/you/latex_code/
373 converts all files to LaTeX, stored in /home/you/latex_code/.
375 Use --quiet to improve performance of batch file processing (recom‐
377 mended for usage in shell scripts).
378 Use highlight --out-format=xterm256 <yourfile> | less -R to display a
380 source file in a terminal.
381 Run highlight --list-scripts=langs to see all supported syntax types.
383
386 Andre Simon <as@andre-simon.de>
387
389 README file and highlight webpage at http://www.andre-simon.de/.
390Andre Simon 2020-01-18 highlight(1)