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>
52 set type of source code, necessary if input file suffix is miss‐
53 ing
54 --syntax-by-name=<name>
56 specify type of source code by given name. Will not read a file
57 of this name, useful for stdin and to determine the syntax of
58 the file before piping its content to highlight. This option
59 overrides --syntax.
60 -v, --verbose
62 print debug info to stderr
63 -q, --quiet
65 suppress progress info in batch mode
66 --force[=syntax]
68 generate output if input syntax is unknown. The fallback syntax
69 may be set here, Plain Text is default.
70 --list-scripts=<type>
72 list installed scripts <type> = [langs, themes, plugins]
73 --list-cat=<categories>
75 filter the scripts by the given categories (example: --list-
76 cat='source;script')
77 --max-size=<size>
79 set maximum input file size (examples: 512M, 1G; default: 256M)
80 --plug-in=<script>
82 execute Lua plug-in script; repeat option to apply multiple
83 plug-ins
84 --plug-in-param
86 set plug-in input parameter. This might be an input file name
87 (ie. 'tags').
88 --print-config
90 print path configuration
91 --print-style
93 print stylesheet only (see --style-outfile)
94 --skip=<list>
96 ignore listed unknown file types (example: --skip='bak;c~;h~')
97 --start-nested=<lang>
99 define nested language which starts input without opening delim‐
100 iter
101 --stdout
103 output to stdout (batch mode, --print-style)
104 --validate-input
106 test if input is a valid text file
107 --version
109 print version and copyright info
110
113 -O, --out-format=<format>
114 output file in given format <format>=[html, xhtml, latex, tex,
115 rtf, odt, ansi, xterm256, truecolor, bbcode, pango, svg]
116 -c, --style-outfile=<file>
118 name of style definition file
119 -T, --doc-title
121 document title
122 -e, --style-infile=<file>
124 name of file to be included in style-outfile
125 -f, --fragment
127 omit header and footer of the output document (see --keep-injec‐
128 tions)
129 -F, --reformat=<style>
131 reformat output in given style. <style>=[allman, gnu, google,
132 horstmann, java, kr, linux, lisp, mozilla, otbs, pico, vtk,
133 ratliff, stroustrup, webkit, whitesmith, user]
134 The user style does not apply a predefined scheme. Use --refor‐
136 mat-option to define reformatting behaviour.
137 --reformat-option=<opt>
139 apply an astyle cmd line option (assumes -F). Can be repeated to
140 override settings of the chosen indentation scheme.
141 -I, --include-style
143 include style definition in output
144 -J, --line-length=<num>
146 line length before wrapping (see -V, -W)
147 -j, --line-number-length=<num>
149 line number length incl. left padding. Default length: 5
150 -k, --font=<font>
152 set font (specific to output format)
153 -K, --font-size=<num?>
155 set font size (specific to output format)
156 -l, --line-numbers
158 print line numbers in output file
159 -m, --line-number-start=<cnt>
161 start line numbering with cnt (assumes -l)
162 --line-range=<start-end>
164 output only lines from number <start> to <end>
165 -s, --style=<style name>
167 set highlighting style (theme). See --base16.
168 -t --replace-tabs=<num>
170 replace tabs by num spaces
171 -u, --encoding=<enc>
173 set output encoding which matches input file encoding; omit
174 encoding information if set to "NONE"
175 -V, --wrap-simple
177 wrap lines after 80 (default) characters without indenting func‐
178 tion parameters and statements.
179 -W, --wrap
181 wrap lines after 80 (default) characters (use with caution).
182 -z, --zeroes
184 fill leading space of line numbers with zeroes
185 --base16[=theme]
187 use a theme of the Base16 collection. Use a classic theme other‐
188 wise.
189 --delim-cr
191 set CR as end-of-line delimiter (MacOS 9)
192 --isolate
194 output each syntax token in separate tags (verbose output)
195 --keep-injections
197 output plug-in header and footer injections in spite of -f
198 --kw-case=<upper|lower|capitalize>
200 output all keywords in given case if language is not case sensi‐
201 tive
202 --no-trailing-nl
204 omit trailing newline
205 --no-version-info
207 omit version info comment
208 --wrap-no-numbers
210 omit line numbers of wrapped lines (assumes -l)
211
214 -a, --anchors
215 attach anchors to line numbers (HTML only)
216 -y, --anchor-prefix=<str>
218 set anchor name prefix
219 -N, --anchor-filename
221 use input file name as anchor name
222 -C, --print-index
224 print index file with links to all output files
225 -n, --ordered-list
227 print lines as ordered list items
228 --class-name=<str>
230 set CSS class name prefix; omit class name if set to "NONE"
231 --inline-css
233 output CSS within each tag (verbose output)
234 --enclose-pre
236 enclose fragmented output with pre tag (assumes -f)
237
240 -b, --babel
241 disable Babel package shorthands
242 -r, --replace-quotes
244 replace double quotes by \dq
245 --beamer
247 adapt output for the Beamer package
248 --pretty-symbols
250 improve appearance of brackets and other symbols
251
254 --page-color
255 include page color attributes
256 -x, --page-size=<size>
258 set page size, <size>=[a3, a4, a5, b4, b5, b6, letter]
259 --char-styles
261 include character stylesheets
262
265 --height=<h>
266 set image height (units allowed)
267 --width=<w>
269 set image size (see --height)
270
273 --canvas[=width]
274 set background colour padding (default: 80)
275
278 --doc create stand alone document
279 --no-doc
281 cancel the --doc option
282 --css=filename
284 the external style sheet filename
285 --src-lang=STRING
287 source language
288 -t, --tab=INT
290 specify tab length
291 -n, --line-number[=0]
293 number all output lines, optional padding
294 --line-number-ref[=p]
296 number all output lines and generate an anchor, made of the
297 specified prefix
298 p + the line number (default='line')
299 --output-dir=path
301 output directory
302 --failsafe
304 if no language definition is found for the input, it is simply
305 copied to the output
306
309 Highlight recognizes these variables:
310 HIGHLIGHT_DATADIR
312 sets the path to highlight's configuration scripts
313 HIGHLIGHT_OPTIONS
315 may contain command line options, but no input file paths.
316
319 If no in- or output files are specified, stdin and stdout will be used
320 for in- or output. Since version 3.44, reading from stdin can also be
321 triggered by the '-' option.
322 Default output format: xterm256 or truecolor if appropriate, HTML oth‐
324 erwise.
325 Style definitions are stored in highlight.css (HTML, XHTML, SVG) or
327 highlight.sty (LaTeX, TeX) if neither -c nor -I is given. For CSS, def‐
328 initions are stored in the output document header with -I, if -f is
329 also given there will be no style definitions.
330 Reformatting code (-F) will only work with C, C++, C# and Java input
332 files.
333
335 Wrapping lines with -V or -W will cause faulty highlighting of long
336 single line comments and directives. Using line-range might interfere
337 with multi line syntax elements. Use with caution.
338
340 The configuration files are stored in /usr/share/highlight/. Language
341 definitions, themes and plugins are located in subdirectories.
342 Documentation files are stored in /usr/share/doc/highlight/ , configu‐
344 ration files in /etc/highlight/.
345 See README how to install own scripts in the home directory.
347
349 Single file conversion:
350 highlight -o hello.html -i hello.c
352 highlight -o hello.html hello.c
354 highlight -o hello.html -S c < hello.c
356 highlight -S c < hello.c > hello.html
358 Note that a file highlight.css is created in the current directory.
360 Batch file processing:
362 highlight --out-format=xhtml -B '*.cpp' -d /home/you/html_code/
364 converts all *.cpp files in the current directory and its subdirecto‐
366 ries to xhtml files, and stores the output in /home/you/html_code.
367 highlight --out-format=latex * -d /home/you/latex_code/
369 converts all files to LaTeX, stored in /home/you/latex_code/.
371 Use --quiet to improve performance of batch file processing (recom‐
373 mended for usage in shell scripts).
374 Use highlight --out-format=xterm256 <yourfile> | less -R to display a
376 source file in a terminal.
377 Run highlight --list-scripts=langs to see all supported syntax types.
379
382 Andre Simon <as@andre-simon.de>
383
385 README file and highlight webpage at http://www.andre-simon.de/.
386Andre Simon 2019-07-27 highlight(1)