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, BB‐
15 Code, 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 <topic> = [syntax, theme,
37 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 --syntax-supported
63 test if the given syntax can be loaded and print the result
64 (assumes -S or --syntax-by-name)
65 -v, --verbose
67 print debug info to stderr; repeat to show more information
68 -q, --quiet
70 suppress progress info in batch mode
71 --force[=syntax]
73 generate output if input syntax is unknown. The fallback syntax
74 may be set here, Plain Text is default.
75 --list-scripts=<type>
77 list installed scripts <type> = [langs, themes, plugins]
78 --list-cat=<categories>
80 filter the scripts by the given categories (example: --list-
81 cat='source;script')
82 --max-size=<size>
84 set maximum input file size (examples: 512M, 1G; default: 256M)
85 --plug-in=<script>
87 execute Lua plug-in script; repeat option to apply multiple
88 plug-ins
89 --plug-in-param
91 set plug-in input parameter. This might be an input file name
92 (ie. 'tags').
93 --print-config
95 print path configuration
96 --print-style
98 print stylesheet only (see --style-outfile)
99 --skip=<list>
101 ignore listed unknown file types (example: --skip='bak;c~;h~')
102 --stdout
104 output to stdout (batch mode, --print-style)
105 --validate-input
107 test if input is a valid text file
108 --service-mode
110 run in service mode, not stopping until signaled
111 --version
113 print version and copyright info
114
117 -O, --out-format=<format>
118 output file in given format <format>=[html, xhtml, latex, tex,
119 rtf, odt, ansi, xterm256, truecolor, bbcode, pango, svg]
120 -c, --style-outfile=<file>
122 name of style definition file
123 -T, --doc-title
125 document title
126 -e, --style-infile=<file>
128 name of file to be included in style-outfile
129 -f, --fragment
131 omit header and footer of the output document (see --keep-injec‐
132 tions)
133 -F, --reformat=<style>
135 reformat output in given style. <style>=[allman, gnu, google,
136 horstmann, java, kr, linux, lisp, mozilla, otbs, pico, vtk,
137 ratliff, stroustrup, webkit, whitesmith]
138 -I, --include-style
140 include style definition in output
141 -J, --line-length=<num>
143 line length before wrapping (see -V, -W)
144 -j, --line-number-length=<num>
146 line number length incl. left padding. Default length: 5
147 -k, --font=<font>
149 set font (specific to output format)
150 -K, --font-size=<num?>
152 set font size (specific to output format)
153 -l, --line-numbers
155 print line numbers in output file
156 -m, --line-number-start=<cnt>
158 start line numbering with cnt (assumes -l)
159 --line-range=<start-end>
161 output only lines from number <start> to <end>
162 -s, --style=<style name|path>
164 set highlighting style (theme). Add 'base16/' prefix to use a
165 Base16 theme. The theme may also be defined as path of the theme
166 file.
167 -t --replace-tabs=<num>
169 replace tabs by num spaces
170 -u, --encoding=<enc>
172 set output encoding which matches input file encoding; omit en‐
173 coding information if set to "NONE"
174 -V, --wrap-simple
176 wrap lines after 80 (default) characters without indenting func‐
177 tion parameters and statements.
178 -W, --wrap
180 wrap lines after 80 (default) characters (use with caution).
181 -z, --zeroes
183 fill leading space of line numbers with zeroes
184 --isolate
186 output each syntax token in separate tags (verbose output)
187 --keep-injections
189 output plug-in header and footer injections in spite of -f
190 --kw-case=<upper|lower|capitalize>
192 output all keywords in given case if language is not case sensi‐
193 tive
194 --no-trailing-nl[=mode]
196 omit trailing newline. If mode is "empty-file", omit only for
197 empty input
198 --no-version-info
200 omit version info comment
201 --wrap-no-numbers
203 omit line numbers of wrapped lines (assumes -l)
204
207 -a, --anchors
208 attach anchors to line numbers (HTML only)
209 -y, --anchor-prefix=<str>
211 set anchor name prefix
212 -N, --anchor-filename
214 use input file name as anchor name
215 -C, --print-index
217 print index file with links to all output files
218 -n, --ordered-list
220 print lines as ordered list items
221 --class-name=<str>
223 set CSS class name prefix; omit class name if set to "NONE"
224 --inline-css
226 output CSS within each tag (verbose output)
227 --enclose-pre
229 enclose fragmented output with pre tag (assumes -f)
230
233 -b, --babel
234 disable Babel package shorthands
235 -r, --replace-quotes
237 replace double quotes by \dq
238 --beamer
240 adapt output for the Beamer package
241 --pretty-symbols
243 improve appearance of brackets and other symbols
244
247 --page-color
248 include page color attributes
249 -x, --page-size=<size>
251 set page size, <size>=[a3, a4, a5, b4, b5, b6, letter]
252 --char-styles
254 include character stylesheets
255
258 --height=<h>
259 set image height (units allowed)
260 --width=<w>
262 set image size (see --height)
263
266 --canvas[=width]
267 set background colour padding (default: 80)
268
271 --ls-profile=<server>
272 load LSP configuration from lsp.conf
273 --ls-delay=<ms>
275 set server initialization delay in milliseconds
276 --ls-exec=<bin>
278 set server executable name
279 --ls-option=<option>
281 set server CLI option (can be repeated)
282 --ls-hover
284 execute hover requests (HTML output only)
285 --ls-semantic
287 query server for semantic token types (requires LSP 3.16)
288 --ls-syntax=<lang>
290 set syntax which is understood by the server
291 --ls-syntax-error
293 retrieve syntax error information (assumes --ls-hover or --ls-
294 semantic)
295 --ls-workspace=<dir>
297 set workspace directory to initialize the server
298 --ls-legacy
300 do not require a server capabilities response
301
304 Highlight recognizes these variables:
305 HIGHLIGHT_DATADIR
307 sets the path to highlight's configuration scripts
308 HIGHLIGHT_OPTIONS
310 may contain command line options, but no input file paths.
311
314 If no in- or output files are specified, stdin and stdout will be used
315 for in- or output. Reading from stdin can also be triggered by the '-'
316 option.
317 Default output format: xterm256 or truecolor if appropriate, HTML oth‐
319 erwise.
320 Style definitions are stored in highlight.css (HTML, XHTML, SVG) or
322 highlight.sty (LaTeX, TeX) if neither -c nor -I is given. For CSS, def‐
323 initions are stored in the output document header with -I, if -f is
324 also given there will be no style definitions.
325 Reformatting code (-F) will only work with C, C++, C# and Java input
327 files.
328 LSP features require absolute input paths and disable reformatting
330 (-F).
331
334 Wrapping lines with -V or -W will cause faulty highlighting of long
335 single line comments and directives. Using line-range might interfere
336 with multi line syntax elements. Use with caution.
337
339 The configuration files are stored in /usr/share/highlight/. Language
340 definitions, themes and plugins are located in subdirectories.
341 Documentation files are stored in /usr/share/doc/highlight/, configura‐
343 tion files in /etc/highlight/.
344 See README how to install own scripts in the home directory.
346
348 Single file conversion:
349 highlight -o hello.html -i hello.c
351 highlight -o hello.html hello.c
353 highlight -o hello.html -S c < hello.c
355 highlight -S c < hello.c > hello.html
357 Note that a file highlight.css is created in the current directory.
359 Batch file processing:
361 highlight --out-format=xhtml -B '*.cpp' -d /home/you/html_code/
363 converts all *.cpp files in the current directory and its subdirecto‐
365 ries to xhtml files, and stores the output in /home/you/html_code.
366 highlight --out-format=latex * -d /home/you/latex_code/
368 converts all files to LaTeX, stored in /home/you/latex_code/.
370 Use --quiet to improve performance of batch file processing (recom‐
372 mended for usage in shell scripts).
373 Use highlight --out-format=xterm256 <yourfile> | less -R to display a
375 source file in a terminal.
376 Run highlight --list-scripts=langs to see all supported syntax types.
378
381 Andre Simon <as@andre-simon.de>
382
384 README files and http://www.andre-simon.de/.
385Andre Simon 2023-05-11 highlight(1)