In-/output

Apart from defining input and output files using -i and -o, it is possible to use IO redirection. If no input or output file name is defined by --input and --output options, highlight will use stdin and stdout for file processing.

If no input filename is defined by --input or given at the prompt, highlight is not able to determine the language type by means of the file extension. Only some scripting languages are determined by the shebang in the first input line. In this case you have to pass highlight the given langage with --syntax (this should be the file suffix of the source file in most cases).

Example: If you want to convert a Python file, highlight needs to load the py.lang language definition. The correct argument of --syntax would be "py". If you pass the filename directly to highlight, the program fetches the ".py" extension from the file name. 

highlight test.py                   # Option --syntax not needed
highlight < test.py --syntax py     # --syntax option necessary
cat test.py | highlight --syntax py

If there exist multiple suffixes (like C, cc, cpp, h with C++ - files), you assign them to the matching language definition in the file $HL_DIR/filetypes.conf.

Highlight enters the batch processing mode if the --batch-recursive (-B) option was given or if multiple input files were defined. In batch mode, highlight will save the generated files with the original filename, appending the extension of the chosen output type.

The -O option is useful with -B. Use --quiet to improve performance (recommended for usage in shell scripts).

HTML, TeX, LaTeX and SVG output

The HTML, TeX, LaTeX and SVG output formats allow to reference style definition files which contain the formatting information (stylesheets).

In HTML and SVG output, this file contains CSS definitions and is saved as 'highlight.css' by default.

In LaTeX and TeX, this file contains macro definitions, and is saved as 'highlight.sty' if not otherwise stated by the user.

Name and path of the stylesheet may be modified with --style-outfile. The --style-infile option defines another stylesheet to be included in the final style definition. This file may contain instructions to costumize the highlight output. If the --outdir option is given, all generated output, including stylesheets, are stored in this directory.

Use the --include-style switch to force highlight to save the style information embedded in the output documents without referencing a stylesheet.

The usage of referenced style definitions has the advantage to have all formatting information in a central place, which affects all referencing documents.

If you want to process LaTeX files in UTF-8 encoding, you may have to install the latex ucs package (see INSTALL).

Using the --style-infile option you can define a file to be included in the final formatting information of the document. You can enhance or redefine the default highlight style definitions without editing generated code. 

Example:

/* content of user.css (add document frame and a line to linenumbers) */
pre.hl {
  border-width: 1px;
  border-style:solid;
  border-left-color: silver;
  border-top-color: silver;
  border-right-color: gray;
  border-bottom-color: gray;
  padding: 0.5cm;
  margin: 2cm;
}
.hl.line {
  /* background-color:#EEEEEE;  color:#505050; */
  border-right:1px solid #555555;
  font-style:normal;
  font-weight:normal;
  padding:1px;
  text-decoration:none;
}

Usage: highlight -l --style-infile user.css main.cpp

Terminal output 
highlight --ansi  | less -R
highlight --xterm256  | less -R

displays coloured sourcecode in a terminal.

Since there are limited colours defined for ANSI terminal output, there exists only one hard coded colour theme with --ansi. You should therefore use --xterm256 to enable output in 256 colours. The 256 colour mode is supported by current releases of xterm, rxvt and Putty (among others).

Text output:

If the language definition is specified as "txt", no highlighting takes place. 

highlight -S txt -L README > readme.tex

Examples:

The following commands write the content of hello.c to hello.html: 

highlight -o hello.html -i hello.c
highlight -o hello.html hello.c
highlight -o hello.html --syntax c < hello.c
highlight --syntax c < hello.c > hello.html

Apart from hello.html, a file highlight.css is generated in the current working directory. 

highlight -X  --batch-recursive '*.cpp' --outdir /home/you/html_code/

This command converts all *.cpp files in the current directory and its sub- directories to xhtml files, and stores the output in /home/you/html_code. 

highlight -L  * --outdir /home/you/latex_code/

This command onverts all files to LaTeX, stored in /home/you/latex_code/.

back