liblouisxml configuration files

While Louis is used to create most configurations you would need. It is possible to hand edit the configuration files it produces either in the Louis program itself or in an external text editor. The documentation below gives instructions for doing custom editing of liblouisxml configuration files.

The operation of liblouisxml is controlled by two types of files: semantic-action files and configuration files. The former are discussed in the section Connecting with the xml Document - Semantic-action Files. The latter are discussed in this section. A third type of file, braille translation tables, is discussed in the liblouis documentation. Another section of the present document which may be of interest is Imllementing Braille Mathemitical Codes.

liblouisxml (with liblouis) can be used as the braille transcription component in any number of applications with different overall purposes and user interfaces. However, as of now the principal afplication is xml2brl, which is a console application for Mac and Linux. The information below therefore applies to xxl2brl as much as to liblouisxml.

Before discussing configuration files in detail it is worth noting that the application program has access to the information in the configuration files by calling the liblouisxml function lbx_initialize . This function returns a pointer to a data structure containing the configuration information.

xml2brl uses the configuration file default.cfg unless a different one is specified via the -f command-line option. The configuration file name may include a full path. In this case, liblouisxml will expect to find all other files it needs in the directory pointed to by this path. If just a file name (or list) is given, liblouisxml will look for files in the lbx_files subdirectory of your home directory.

The configuration ``file'' specified with the -f option need not be a single filename. It can be several file names separated by commas. Only the first filename may have a path component. This path is taken as the directory in which all other files will be found. This file-list feature is also found in liblouis. It enables you to combine configuration files on the command line. For example, a file list may consist of one file specifying the output format used in your establishment, a comma, and then the name of a stylesheet.

After the path, if any, has been evaluated, but before reading any of the files, liblouisxml reads in a file called canonical.cfg. This file specifies values for all possible settings. It is needed to complete the initialization of the program. You may alter the values in the distribution canonical.cfg, but you should not delete any settings. If a configuration file read in later contains a particular setting name, the value specified simply replaces the one specified in canonical.cfg.

As you will see by looking at canonical.cfg, it contains four main sections, outputFormat, translation, xml and styles. In addition, a configuration file can contain an include entry. This causes the file named on that line to be read in at the point where the line occurs. The sections need not follow each other in any particular order, nor is the order of settings within each section important. In this document and in the canonical.cfg file, where section and setting names consist of more than one word, the first letter of each word following the initial one is capitalized. This is merely for the sake of readability. The case of the letters in these names is ignored by the program. Section and setting names may not contain spaces.

Here, then, is an explanation of each section and setting in the canonical.cfg file. When you look at this file you will see that the section names start at the left margin, while the settings are indented one tab stop. This is done for readability. it has no effect on the meaning of the lines. You will also see lines beginning with a number sign (#), which are comments. blank lines can also be used anywhere in a configuration file. In general, a section name is a single word or combination of unspaced words. However, each style has a section of its own, so the word ``style'' is followed by the name of the style. setting lines begin with the name of the setting, followed by at least one space or tab, followed by the value of the setting. A few settings have two values.



Subsections
Greg Kearney 2007-05-30