~~~~~~~~~~~
Text Tables
~~~~~~~~~~~

.. include:: prologue.rst

Description
===========

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 (see |README.BrailleDots| for details).

Text tables can usually be found in the ``/etc/brltty/Text/`` directory (see
|README.Customize| for more details). See `Text Table List`_ for a list of
BRLTTY's text tables.

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. Whitespace (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 whitespace are ignored. If the first non-whitespace character of a line 
is ``#`` then that line is a comment and is ignored.

The precedence for determining the braille representation for a character is as
follows:

1) If the character is within the Unicode braille Row (U+2800 through U+28FF)
   then its low-order eight bits are used as follows:

   ===  ========  ===
   Hex  Binary    Dot
   ---  --------  ---
   01   00000001  1
   02   00000010  2
   04   00000100  3
   08   00001000  4
   10   00010000  5
   20   00100000  6
   40   01000000  7
   80   10000000  8
   ===  ========  ===

2) If the character is within the Unicode private use row U+F000 through U+F0FF
   then its low-order byte is:

   A) interpreted as a single-byte character within the locAL character set
   B) translated to Unicode
   C) reprocessed

3) An explicit representation (defined via `The Char Directive`_,
   `The Glyph Directive`_, or `The Byte Directive`_.

4) An equivalent representation (defined via `The Alias Directive`_).

5) The explicit representation of the Unicode base character.

6) The explicit representation of the transliterated ASCII character.

7) The explicit representation of the Unicode Replacement Character (U+FFFD).

8) The explicit representation of a question mark (``?``).

9) All eight braille dots.

Directives
==========

.. |character operand| replace::
   The character being defined.
   See `The String Operand`_ for details.

.. |byte operand| replace::
   The character being defined.
   It may be specified in any of the ways supported by `The String Operand`_
   except that the Unicode-specific forms (``\u``, ``\U``, ``\<``) may not be used.

.. |dots operand| replace::
   The braille representation for the character being defined.
   See `The Dots Operand`_ for details.

.. |cell operand| replace::
   The braille representation for the character being tested.
   See `The Cell Operand`_ for details.

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

.. parsed-literal:: char *character* *dots* # *comment*

Use this directive to specify how a Unicode character is to be represented in
braille. A character defined via 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 via this directive - the others should
be defined via `The Glyph Directive`_ (which has the same syntax). If more than
one character with the same braille representation is defined via this
directive (which is allowed for backward compatibility) then the first one is
used when entered from a braille keyboard.

*character*
   |character operand|

*dots*
   |dots operand|

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
-------------------

.. parsed-literal:: glyph *character* *dots* # *comment*

Use this directive to specify how a Unicode character is to be represented in
braille. A character defined via this directive is output-only - it can't
be entered from a braille keyboard.

*character*
   |character operand|

*dots*
   |dots operand|

See `The Char Directive`_ for examples.

The Input Directive
-------------------

.. parsed-literal:: input *character* *dots* # *comment*

Use this directive to specify how a Unicode character is to be entered from a
braille keyboard. A character defined via this directive is input-only - its
actual braille representation isn't defined.

*character*
   |character operand|

*dots*
   |dots operand|

See `The Char Directive`_ for examples.

The Alias Directive
-------------------

.. parsed-literal:: alias *from* *to* # *comment*

Use this directive to define the *from* Unicode character such that it has the
same braille representation as the *to* Unicode character. See
`The String Operand`_ for details on how to specify both operands.

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

.. parsed-literal:: byte *byte* *dots* # *comment*

Use this 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 either
`The Char Directive`_ or `The Glyph Directive`_) so that the text table remains
valid regardless of what the local character set is.

*byte*
   |byte operand|

*dots*
   |dots operand|

The IfGlyph Directive
---------------------

.. parsed-literal:: ifGlyph *character* *directive*

Use this directive to only process one or more directives if a character has a
braille representation.

*character*
   |character operand|

*directive*
   |directive operand|

Examples::

   ifGlyph C alias \u2103 C # degree Celsius

The IfNotGlyph Directive
------------------------

.. parsed-literal:: ifNotGlyph *character* *directive*

Use this directive to only process one or more directives if a character
doesn't have a braille representation.

*character*
   |character operand|

*directive*
   |directive operand|

Examples::

   ifNotGlyph \s glyph \s 0

The IfInput Directive
---------------------

.. parsed-literal:: ifInput *cell* *directive*

Use this directive to only process one or more directives if a character can be
entered from a braille keyboard.

*cell*
   |cell operand|

*directive*
   |directive operand|

The IfNotInput Directive
------------------------

.. parsed-literal:: ifNotInput *cell* *directive*

Use this directive to only process one or more directives if a character can't
be entered from a braille keyboard.

*cell*
   |cell operand|

*directive*
   |directive operand|

.. include:: nesting-directives.rst
.. include:: variable-directives.rst
.. include:: condition-directives.rst

Operands
========

.. include:: string-operand.rst

The Dots Operand
----------------

A *dots* operand is a sequence of one to eight dot numbers. If the dot numbers
are enclosed within (parentheses) then they may be separated from one another
by whitespace. A dot number is a digit within the range ``1``-``8``
as defined by the standard braille dot numbering convention (see
|README.BrailleDots| for details). 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.

The Cell Operand
----------------

A *cell* operand is a sequence of one to eight dot numbers. A dot number is
a digit within the range ``1``-``8`` as defined by the standard braille dot
numbering convention (see |README.BrailleDots| for details). The special dot
number ``0`` is recognized, and means no dots - it may not be used in
conjunction with any other dot number.

Text Table List
===============

.. csv-table::
   :header-rows: 1
   :file: text-table.csv