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