Location of Highlighting Description Files

The highlighting description files that come with libt3highlight are stored in libt3highlight data directory. This is usually /usr/share/libt3highlightX or /usr/local/share/libt3highlightX (where X should be replaced by a number corresponding to the API version of the installed libt3highlight).

Furthermore, libt3highlight also searches the libt3highlight directory in the XDG DATA HOME directory (if the XDG_DATA_HOME environment variable is not set, this defaults to ~/.local/share/libt3highlight). This allows users to easily develop their own highlighting description files.

The Map File

To associate the correct syntax highlighting description file with a source file, libt3highlight uses a special map file named lang.map. This file must be located in the libt3highlight data directory. A per-user map file may also be stored in the libt3highlight directory of the XDG DATA HOME directory (which defaults to ~/.local/share/libt3highlight if the XDG_DATA_HOME environment variable is not set). This per-user map is read before the system-wide map, allowing a user to override the system-wide definitions.

The map file must include the format number (format = 1) and a list of %lang sections. Each %lang section must include a name and a lang-file. Optionally it may include a name-regex, that will be used to look up a language by name, and a file-regex, that will be used to look up a language for a given file name.

Below is an extract of the system-wide lang.map file distributed with libt3highlight:

format = 1

%lang {
  name = "C++"
  name-regex = "^(?i)(?:c\+\+|cpp)$"
  # We treat .h files as if they are C++ files, because many C++ header files
  # use the .h suffix. There is little harm in treating a C file as a C++ file.
  file-regex = "\.(?:cpp|C|cxx|cc|hpp|hxx|H|h)$"
  lang-file = "cpp.lang"
}
%lang {
  name = "C"
  name-regex = "^(?i)c$"
  file-regex = '\.[ch]$'
  lang-file = "c.lang"
}
%lang {
  name = "Shell"
  name-regex = "^(?i)(?:ba)?sh$"
  file-regex = "(?i)\.sh$"
  lang-file = "sh.lang"
}
%lang {
  name = "T3 Highlight Language Definition"
  name-regex = "^(?i)lang$"
  file-regex = "\.lang$"
  lang-file = "lang.lang"
}