# Text Tables

Contents

- Description
- Directives
  - The Char Directive
  - The Glyph Directive
  - The Alias Directive
  - The Byte Directive
  - The IfGlyph Directive
  - The IfNotGlyph Directive
  - The IfCell Directive
  - The IfNotCell Directive
  - The Include Directive
  - The Assign Directive
  - The AssignDefault Directive
  - The IfVar Directive
  - The IfNotVar Directive
  - The BeginVariables Directive
  - The EndVariables Directive
  - The ListVariables Directive
  - The EndIf Directive
  - The Else Directive
- Operands
  - The String Operand
  - The Dots Operand
  - The Cell Operand
- Text Table List

## 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 Braille Dots for details).

Text tables can usually be found in the `/etc/brltty/Text/` directory (see Local Customization 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:

   1. interpreted as a single-byte character within the locAL character set
   2. translated to Unicode
   3. 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

### The Char Directive

    char character dots # comment

Use this directive to specify how a Unicode character is to be represented in braille. Characters 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
  The character being defined. See The String Operand for details.
dots
  The braille representation for the character being defined. See The Dots Operand for details.

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 this directive to specify how a Unicode character is to be represented in braille. Characters defined via this directive are output-only - they cannot be entered from a braille keyboard.

character
  The character being defined. See The String Operand for details.
dots
  The braille representation for the character being defined. See The Dots Operand for details.

See The Char Directive for examples.

### The Alias Directive

    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

    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
  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
  The braille representation for the character being defined. See The Dots Operand for details.

### The IfGlyph Directive

    ifGlyph character directive

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

character
  The character being defined. See The String Operand for details.
directive
  The directive that is to be conditionally processed. It may contain spaces. This operand is optional. If it isn't supplied then this directive applies to all subsequent lines until The EndIf Directive or The Else Directive that is at the same conditional nesting level.

Examples:

    ifGlyph C alias \u2103 C # degree Celsius

### The IfNotGlyph Directive

    ifNotGlyph character directive

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

character
  The character being defined. See The String Operand for details.
directive
  The directive that is to be conditionally processed. It may contain spaces. This operand is optional. If it isn't supplied then this directive applies to all subsequent lines until The EndIf Directive or The Else Directive that is at the same conditional nesting level.

Examples:

    ifNotGlyph \s glyph \s 0

### The IfCell Directive

    ifCell cell directive

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

cell
  The braille representation for the character being tested. See The Cell Operand for details.
directive
  The directive that is to be conditionally processed. It may contain spaces. This operand is optional. If it isn't supplied then this directive applies to all subsequent lines until The EndIf Directive or The Else Directive that is at the same conditional nesting level.

### The IfNotCell Directive

    ifNotCell cell directive

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

cell
  The braille representation for the character being tested. See The Cell Operand for details.
directive
  The directive that is to be conditionally processed. It may contain spaces. This operand is optional. If it isn't supplied then this directive applies to all subsequent lines until The EndIf Directive or The Else Directive that is at the same conditional nesting level.

### The Include Directive

    include file # comment

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

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

### The Assign Directive

    assign variable value

Use this directive to create or update a variable associated with the current nesting level (see The BeginVariables Directive) of the current include level (see The Include Directive). The variable is visible to the current and to lower include levels, but not to higher include levels.

variable
  The name of the variable. If the variable doesn't already exist at the current include level then it is created.
value
  The value that is to be assigned to the variable. If it's not supplied then a zero-length (null) value is assigned.

Examples:

    assign nullValue
    assign shortValue word
    assign longValue a\svalue\swith\sspaces
    assign IndirectValue \{variableName}

### The AssignDefault Directive

    assignDefault variable value

Use this directive to assign a default value to a variable associated with the current nesting level (see The BeginVariables Directive) of the current include level (see The Include Directive). It's functionally equivalent to:

    ifNotVar variable assign variable value

See The Assign Directive and The IfNotVar Directive for more details.

variable
  The name of the variable. If the variable doesn't already exist at the current include level then it is created. If it does already exist then it is not modified.
value
  The value that is to be assigned to the variable if it doesn't already exist. If it's not supplied then a zero-length (null) value is assigned.

Examples:

    assignDefault format plain\stext

### The IfVar Directive

    ifVar variable directive

Use this directive to only process one or more directives if a variable exists.

variable
  The name of the variable whose existence is to be tested.
directive
  The directive that is to be conditionally processed. It may contain spaces. This operand is optional. If it isn't supplied then this directive applies to all subsequent lines until The EndIf Directive or The Else Directive that is at the same conditional nesting level.

Examples:

    ifVar var1 ifVar var2 assign concatenation \{var1}\{var2}

### The IfNotVar Directive

    ifNotVar variable directive

Use this directive to only process one or more directives if a variable doesn't exist.

variable
  The name of the variable whose existence is to be tested.
directive
  The directive that is to be conditionally processed. It may contain spaces. This operand is optional. If it isn't supplied then this directive applies to all subsequent lines until The EndIf Directive or The Else Directive that is at the same conditional nesting level.

Examples:

    ifNotVar var1 assign var1 default\svalue

### The BeginVariables Directive

    beginVariables

Use this directive to open a new variable nesting level. The Assign Directive) will define variables at this new nesting level, and will hide variables with the same names in any previous nesting level. These variables will remain defined until The EndVariables Directive that is at the same variable nesting level.

Examples:

    assign x 1
    # \{x} evaluates to 1
    beginVariables
    # \{x} still evaluates to 1
    assign x 2
    # \{x} now evaluates to 2
    endVariables
    # \{x} evaluates to 1 again

### The EndVariables Directive

    endVariables

Use this directive to close the current variable nesting level. See The BeginVariables Directive for details.

### The ListVariables Directive

    listVariables

Use this directive to list all of the currently defiined variables. It can be helpful when debugging.

### The EndIf Directive

    endIf

Use this directive to terminate the current conditional nesting level.

Examples:

    ifVar x
       These lines will be processed if a variable named x exists.
    endIf

### The Else Directive

    else

Use this directive to negate the test associated with the current conditional nesting level.

Examples:

    assign x some\svalue
    ifVar x
       These lines will be processed.
    else
       These lines won't be processed.
    endIf

## Operands

### The String Operand

A string operand may be specified as a non-whitespace sequence of:

- Any single character other than a backslash (\\) or a white-space character.

- A backslash-prefixed special character. These are:

  Sequence | Meaning
  `\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)
  `\<name>` | The Unicode name of a character (use _ for space).
  `\{variable}` | The value of a variable.
  `\\` | A literal backslash.
  `\#` | A literal number sign.

### 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 Braille Dots 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 Braille Dots 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

name | description
--- | ---
auto | locale-based autoselection
ar | Arabic (generic)
as | Assamese
awa | Awadhi
bg | Bulgarian
bh | Bihari
bn | Bengali
bo | Tibetan
bra | Braj
brf | Braille Ready Format (for viewing .brf files within an editor or pager)
cs | Czech
cy | Welsh
da | Danish
da-1252 | Danish (Svend Thougaard, 2002–11–18)
da-lt | Danish (LogText)
de | German
dra | Dravidian
el | Greek
en | English
en_CA | English (Canada)
en_GB | English (United Kingdom)
en_US | English (United States)
en-nabcc | English (North American Braille Computer Code)
eo | Esperanto
es | Spanish
et | Estonian
fi | Finnish
fr | French
fr_CA | French (Canada)
fr_FR | French (France)
fr-2007 | French (unified 2007)
fr-cbifs | French (Code Braille Informatique Français Standard)
fr-vs | French (VisioBraille)
ga | Irish
gd | Gaelic
gon | Gondi
gu | Gujarati
he | Hebrew
hi | Hindi
hr | Croatian
hu | Hungarian
hy | Armenian
is | Icelandic
it | Italian
kha | Khasi
kn | Kannada
kok | Konkani
kru | Kurukh
lt | Lituanian
lv | Latvian
mg | Malagasy
mi | Maori
ml | Malayalam
mni | Manipuri
mr | Marathi
mt | Maltese
mun | Munda
mwr | Marwari
ne | Nepali
new | Newari
nl | Dutch
nl_BE | Dutch (Belgium)
nl_NL | Dutch (Netherlands)
no | Norwegian
no-generic | Norwegian (with support for other languages)
no-oup | Norwegian (Offentlig utvalg for punktskrift)
nwc | Newari (old)
or | Oriya
pa | Panjabi
pi | Pali
pl | Polish
pt | Portuguese
ro | Romanian
ru | Russian
se | Sami (Northern)
sa | Sanskrit
sat | Santali
sd | Sindhi
sk | Slovak
sl | Slovenian
sv | Swedish
sv-1989 | Swedish (1989 standard)
sv-1996 | Swedish (1996 standard)
sw | Swahili
ta | Tamil
te | Telugu
tr | Turkish
uk | Ukrainian
vi | Vietnamese