Translation Tables
------------------

Files within this directory with names of the form text.*.tbl are text
translation tables. They are used by BRLTTY to translate the characters on the
screen into their corresponding braille representations.

Files within this directory with names of the form attr*.tbl are attributes
translation tables. They are used by BRLTTY to translate the VGA highlighting
attributes of the characters on the screen into corresponding combinations of
braille dots.

A translation table consists of a sequence of directives, one per line, which
define how each possible byte value is to be represented in braille. 
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 Byte Directive
------------------

   byte <byte> <dots> # <comment>

Use the "byte" directive to specify how a byte (character) is to be represented
in braille. See the text translation tables for examples of its use. Since this
is by far the most commonly used directive, the "byte" keyword itself is
optional.

The <byte> operand specifies the byte being defined. It may be:
*  Any single character other than a backslash or a white-space character.
*  A backslash-prefixed special character. These are:
   -  \\    A literal backslash.
   -  \#    A literal number sign.
   -  \x##  The two-digit hexadecimal representation of any character.
   -  \X##  ... (the case of the X and of the digits isn't significant)

The <dots> operand specifies the braille representation of the byte. 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 below). 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:

   byte a 1
   b 12
   c (14)
   d ( 1  4   5    )
   \\ 12567
   \x20 0

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

The Dot Directive
-----------------

   dot <dot> <state> # <comment>

Use the "dot" directive to specify how the undefined bytes are to be
represented in braille. See the attributes translation tables for examples of
its use. The default is that all dots are on.

The <dot> operand specifies the dot being defined. It is a single digit within
the range 1-8 as defined by the standard braille dot numbering convention (see
below).

The <state> operand specifies when the dot is raised. It may be:
*  on    The dot is raised.
*  off   The dot isn't raised.
*  =bit  The dot is raised if the named bit is on (set to 1).
*  ~bit  The dot is raised if the named bit is off (set to 0).

The names of the bits are:
*  0X01  fg-blue
*  0X02  fg-green
*  0X04  fg-red
*  0X08  fg-bright
*  0X10  bg-blue
*  0X20  bg-green
*  0X40  bg-red
*  0X80  blink

Examples:

   dot 1 on
   dot 2 off
   dot 3 =fg-red
   dot 4 ~bg-blue

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

Standard Braille Dot Numbering Convention
-----------------------------------------

A standard braille cell consists of six dots arranged in three rows and two
columns. Each dot can be specifically identified by its number as follows:

   Dot  Position     Row  Col
    1   top-left      1    1
    2   middle-left   2    1
    3   bottom-left   3    1
    4   top-right     1    2
    5   middle-right  2    2
    6   bottom-right  3    2

Computer braille has introduced a fourth row at the bottom.

   Dot  Position     Row  Col
    7   below-left    4    1
    8   below-right   4    2

Perhaps a picture will make this numbering convention easier to understand.

   1 o o 4
   2 o o 5
   3 o o 6
   7 o o 8

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