Text Tables
-----------

Files with names of the form *.ttb are text tables, and with names of the form 
*.tti are text subtables. They are used by BRLTTY to translate the characters 
on the screen into their corresponding 8-dot computer braille representations.

A text table consists of a sequence of directives, one per line, which define 
how each character is to be represented in braille. UTF-8 character encoding 
must be used. White-space (blanks, tabs) at the beginning of a line, as well as 
before and/or after any operand of any directive, is ignored. Lines containing 
only white-space are ignored. If the first non-white-space character of a line 
is "#" then that line is a comment and is ignored.

===============================================================================

The Char Directive
------------------

   char <character> <dots> # <comment>

Use the "char" directive to specify how a Unicode character is to be 
represented in braille. Characters defined with this directive can also be
entered from a braille keyboard. If several characters have the same braille
representation then only one of them should be defined with the "char"
directive - the others should be defined with teh "glyph" directive (which has
the same syntax). If more than one character with the same braille
representation is defined with the "char" directive (which is currently allowed
for backward compatibility) then the first one is selected.

The <character> operand specifies the Unicode character being defined. It may
be:
*  Any single character other than a backslash or a white-space character.
*  A backslash-prefixed special character. These are:
   -  \b          The backspace character.
   -  \f          The formfeed character.
   -  \n          The newline character.
   -  \o###       The three-digit octal representation of a character.
   -  \r          The carriage return character.
   -  \s          The space character.
   -  \t          The horizontal tab character.
   -  \u####      The four-digit hexadecimal representation of a character.
   -  \U########  The eight-digit hexadecimal representation of a character.
   -  \v          The vertical tab character.
   -  \x##        The two-digit hexadecimal representation of a character.
   -  \X##        ... (the case of the X and of the digits isn't significant)
   -  \#          A literal number sign.
   -  \<name>     The Unicode name of a character (use _ for space).
   -  \\          A literal backslash.

The <dots> operand specifies the braille representation of the Unicode 
character. It is a sequence of one to eight dot numbers. If the dot number 
sequence is enclosed within parentheses then the dot numbers may be separated 
from one another by white-space. A dot number is a digit within the range 1-8 
as defined by the standard braille dot numbering convention (see README-DOTS). 
The special dot number 0 is recognized when not enclosed within parentheses, 
and means no dots; it may not be used in conjunction with any other dot number.

Examples:

   char a 1
   char b (12)
   char c ( 4  1   )
   char \\ 12567
   char \s 0
   char \x20 ()
   char \<LATIN_SMALL_LETTER_D> 145

===============================================================================

The Glyph Directive
-------------------

   glyph <character> <dots> # <comment>

Use the "glyph" directive to specify how a Unicode character is to be 
represented in braille. Characters defined with this directive are output-only. 
They cannot be entered from a braille keyboard.

See the "char" directive for syntax details and for examples.

===============================================================================

The Byte Directive
------------------

   byte <byte> <dots> # <comment>

Use the "byte" directive to specify how a character in the local character set 
is to be represented in braille. It has been retained for backward 
compatibility but should not be used. Unicode characters should be defined (via 
the "char" directive) so that the text table remains valid regardless of what 
the local character set is.

The <byte> operand specifies the local character being defined. It may be 
specified in the same ways as the <character> operand of the "char" directive 
except that the Unicode-specific forms (\u, \U, \<) may not be used.

The <dots> operand specifies the braille representation of the local character. 
It may be specified in the same ways as the <dots> operand of the "char" 
directive.

===============================================================================

The Include Directive
---------------------

   include <file> # <comment>

Use the "include" directive to include the content of a text subtable. It is 
recursive, which means that any text subtable can itself include yet another 
text subtable. Care must be taken to ensure that an "include loop" is not
created.

The <file> operand specifies the file to be included. It may be either a 
relative or an absolute path. If relative, it is anchored at the directory 
containing the including file.

===============================================================================

