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