Introduction

The t3highlight program uses style definition files to define what the generated output should look like. This allows t3highlight to output syntax highlighted source code for a variety of purposes. This page describes the syntax of the style definition files.

Overall Structure

A complete style definition file for t3highlight consists of:

a file format specifier, which must have the value 1,
the optional boolean key expand-escapes,
an optional list of string replacements,
an optional list of document definitions,
a list of style start and end strings.

The style definitions are read using libt3config, which defines the lexical structure and basic syntax. The syntax of libt3config is fairly self-explanitory, but the following note from the libt3config documentation is useful to repeat here:

: Strings are text enclosed in either " or '. Strings may not include newline characters. To include the delimiting character in the string, repeat the character twice (i.e. 'foo''bar' encodes the string foo'bar). Multiple strings may be concatenated by using a plus sign (+). To split a string accross multiple lines, use string concatenation using the plus sign, where a plus sign must appear before the newline after each substring.

Further documentation about the libt3config format can be found in the libt3config documentation.

Example

Below is a section from the html style, which shows the different parts of a style definition file. For brevity, some parts have been shortened or omitted.

format = 1
expand-escapes = yes

%translate { search = "&" ; replace = "&amp;" }
%translate { search = "<" ; replace = "&lt;" }
%translate { search = ">" ; replace = "&gt;" }

documents {
  # The actual html style also includes a "standalone" document type. This has
  # been omitted for brevity.
  separate-css {
    description = "HTML 4.01 strict with style sheet reference (use css tag)"
    header = '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">\n<html><head>\n' +
      '<meta http-equiv="Content-Type" content="text/html; charset=%{charset}">' +
      '<!--Generated by t3highlight-->\n' +
      '<link href="%{css}" rel="stylesheet" type="text/css">' +
      '<title>%{name}</title></head>\n<body><pre>\n'
    footer = '</pre></body></html>\n'
  }
  raw {
    description = "HTML without header, for embedding"
    header = "<!--Generated by t3highlight-->\n<pre>"
    footer = "</pre>"
  }
}

styles {
  normal {
    start = ""
    end = ""
  }
  keyword {
    start = '<span class="hl-keyword">'
    end = '</span>'
  }
  string {
    start = '<span class="hl-string">'
    end = '</span>'
  }
  string-escape {
    start = '<span class="hl-string-escape">'
    end = '</span>'
  }
  comment {
    start = '<span class="hl-comment">'
    end = '</span>'
  }
  # More styles follow. These have been omitted for brevity. In a complete style
  # definition file, start and end strings should be included for all possible
  # style names.
}

The only required parts in the style definition are the format version and the styles sections. The expand-escapes setting causes backslash-escapes in the strings to be expanded. All the standard escapes are supported.

The translate definitions are textual replacements, which are made to the input just before writing the output. In the html example above, the characters &, < and > are replaced with their HTML character names to make sure the output is valid HTML.

The optional document section allows one to define headers and footers for the output. Multiple such headers and footers may be given, to define different but related document types. The first of these document definitions is automatically chosen as the default. Note the occurence of %{text} tags in the first header. These will be replaced in the output. The tags %{name} and %{charset} are set by default to the name of the file and the character-set, but may be overriden from the command line. All other tags must be set from the command line, or they will be removed from the output. To include a literal % in the output, use %%.

Each style definition must include only a start and an end key. These are the strings that will be inserted before and after each section of output with the named style.