Colorer console tools documentation

# Colorer Library console tools

Colorer library provides useful program, located at `colorer/bin/colorer.exe` (`colorer/bin/colorer` in unix systems), which allows you to use common features of the library. These are include:

- Listing and test loading of all available languages.
- Regular Expressions tests.
- Generating HTML markup of highlighted source files.
- Viewing highlighted files in console window (win32 only).

## Listing Languages

To list all available types of syntax rules, run `colorer -l` command. This will print into standard output all supported computer languages and file types. If you want to test full colorer's database and load all types, run `colorer -ll`. This will take little more time to load and test HRC database. All errors, warnings and other messages you'll found in log file, specified in `catalog.xml` file.

## Generating highlighted HTML sources

You can use Colorer to format you source files into HTML markup. This is useful when publishing sources on your web-site, or making documentation, based on source files. You can find generated examples of some sources on start page in section Highlighting. Also you can check Online HTML Generator on colorer.sf.net site.

To generate highlighted source of file `filename`, you have to run `colorer -h filename`. This will print generated HTML file into standard output. If you want to write this HTML into some file, you can specify this file with `-o` option. Also you can specify input and output character encodings (`-ei ENCNAME` and `-eo ENCNAME`) to read and write data. So, running `colorer -h -ei UTF-8 -eo UTF-16BE -o NAME.HTML yoursource.cpp` will cause to generate highlighted html of `yoursource.cpp` file with name `NAME.HTML`, using UTF-8 as input encoding and UTF-16BE as encoding of result file.

You can specify special "doclinks" file with external help references to any tokens in your generated HTML. Use `-ls"filename"` to activate this feature. You can find sample doclink files in `colorer/bin/doclinks` directory.

## Viewing file in a console window

To run internal colorer viewer you can run `colorer -v filename`. This should work only on win32 systems. Console viewer uses unicode versions of Win32 API, so it can view files with different character sets. In w9x systems colorer additionally uses output encoding parameter because they don't support unicode console output. Viewer supports standard navigation keys, but has minimal functionality.

## Additional options

Colorer provides a set of different command line options, you can check all of them running `colorer` without any parameters.

### Token generator

This option is similar with HTML generation more, except that generated HTML file defines all tokens not with colors, but with abstract css classes, which has name, equals to the name of appropriate token (Region). To use colorer in this more, you have to run `colorer -ht filename`

### Type detection

By default, colorer tries automatically detect filetype. You can redefine used language with `-t` parameter. Use `-t name`, and colorer will use language `name` to highlight requiried file.

### Specifing catalog path

You can specify custom path to `catalog.xml` file. This file contains references to all other library resources. By default, colorer tries to search this file in a set of predefined locations.

### Highlighting styles selection

You can change color style, used to highlight source files. Colorer makes this through the HRD files set. You can change default used coloring style with `-i` option. Text viewer and HTML generator has different sets of HRD styles, you can find available style names in `catalog.xml` file. For example, specify `-i black` to activate black styled scheme of colors.

### Customizing HTML output

There is a numerous options available, controlling HTML output. These are:

- `-db` Disable BOM insertion in start of output files when one of Unicode encodings is used.
- `-dc` Disable informational header output in start of each HTML file.
- `-ds` Disable HTML special symbols substitutions with entities.
- `-dh` Disable HTML header and footer output (only tokenized text).

### Simple file forwarding

Last useful option of colorer tool is `-f` processing mode. With this command colorer simply forwards input file into the output one with optional encoding convertion.