Next Previous Contents

## 6. Tables

## 6.1 Text Tables

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.

BRLTTY is initially configured to use the North American Braille Computer Code (NABCC) text table. In addition to this default, the following alternatives are provided:

auto

  locale-based autoselection

ar

  Arabic (generic)

as

  Assamese

awa

  Awadhi

bg

  Bulgarian

bh

  Bihari

bn

  Bengali

bo

  Tibetan

bra

  Braj

brf

  for viewing `.brf` files within an editor or pager

cs

  Czech

cy

  Welsh

da

  Danish

de

  German

dra

  Dravidian

el

  Greek

en

  English

en_CA

  English (Canada)

en_UK

  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)

fr-cbifs

  French (Code Braille Informatique Français Standard)

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

  Mundari

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

  Norwegian (Offentlig Utvalg for Blindeskrift)

nwc

  Old Newari

or

  Oriya

pa

  Panjabi

pi

  Pali

pl

  Polish

pt

  Portuguese

ro

  Romanian

ru

  Russian

sa

  Sanskrit

sat

  Santali

sd

  Sindhi

sk

  Slovak

sv

  Swedish

sw

  Swahili

ta

  Tamil

te

  Telugu

tr

  Turkish

vi

  Vietnamese

See the -t command line option, the text-table configuration file directive, and the --with-text-table build option for details regarding how to use an alternate text table.

### Text Table Format

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

### Text Table Directives

The following directives are provided:

`char` character dots # comment

  Use the `char` directive to specify how a Unicode character is to be represented in braille.

  character

    The Unicode character being defined. It may be:

    - Any single character other than a backslash or a white-space character.
    - A backslash-prefixed special character. These are:

      -

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

      \#

        A literal number sign. -

      \<name>

        The Unicode name of a character (use _ for space). -

      \\

        A literal backslash.

  dots

    The braille representation of the Unicode character. 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. 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:

  - `char a 1`
  - `char b (12)`
  - `char c ( 4 1 )`
  - `char \\ 12567`
  - `char \s 0`
  - `char \x20 ()`
  - `char \<LATIN_SMALL_LETTER_D> 145`
`byte` byte dots # comment

  Use the `byte` 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 the `char` directive) so that the text table remains valid regardless of what the local character set is.

  byte

    The local character being defined. It may be specified in the same ways as the character operand of the `char` directive except that the Unicode-specific forms (\u, \U, \<) may not be used.

  dots

    The braille representation of the local character. It may be specified in the same ways as the dots operand of the `char` directive.

`include` file # comment

  Use the `include` directive to include the content of a text subtable. It is recursive, which means that any text subtable can itself include yet another text subtable. 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.

## 6.2 Attributes Tables

Files with names of the form *.atb are attributes tables, and with names of the form *.ati are attributes subtables. They are used when BRLTTY is displaying screen attributes rather than screen content (see the DISPMD command). Each of the eight braille dots represents one of the eight `VGA` attribute bits.

The following attributes tables are provided:

attributes

  The lefthand column represents the foreground colours:

  Dot 1

    Red

  Dot 2

    Green

  Dot 3

    Blue

  Dot 7

    Bright

  The righthand column represents the background colours:
  Dot 4

    Red

  Dot 5

    Green

  Dot 6

    Blue

  Dot 8

    Blink

  A dot is raised when its corresponding attribute bit is on. This is the default attributes table because it's the most intuitive. One of its problems, though, is that it's difficult to discern the difference between normal (white on black) and reverse (black on white) video.
attrib

  The lefthand column represents the foreground colours:

  Dot 1

    Red

  Dot 2

    Green

  Dot 3

    Blue

  Dot 7

    Bright

  The righthand column represents the background colours:
  Dot 4

    Red

  Dot 5

    Green

  Dot 6

    Blue

  Dot 8

    Blink

  A background bit being on triggers its corresponding dot, whereas a foreground bit being off triggers its corresponding dot. This unintuitive logic actually makes it easier to read the most commonly used attribute combinations.

See the -a command line option, the attributes-table configuration file directive, and the --with-attributes-table build option for details regarding how to use an alternate attributes table.

### Attributes Table Format

An attributes table consists of a sequence of directives, one per line, which define how combinations of `VGA` attributes are to be represented in braille. `UTF-8` character encoding must be used. 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.

### Attributes Table Directives

The following directives are provided:

`dot` dot state # comment

  Use the `dot` directive to specify what a specific dot represents.

  dot

    The dot being defined. It is a single digit within the range `1`-`8` as defined by the Standard Braille Dot Numbering Convention.

  state

    What the dot represents. It may be:

    `=`attribute

      The dot is raised if the named attribute is on.

    `~`attribute

      The dot is raised if the named attribute is off.

    The names of the attribute 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 =fg-red`
  - `dot 2 ~bg-blue`
`include` file # comment

  Use the `include` directive to include the content of an attributes subtable. It is recursive, which means that any attributes subtable can itself include yet another attributes subtable. 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.

## 6.3 Contraction Tables

Files with names of the form `*.ctb` are contraction tables, and with names of the form `*.cti` are contraction subtables. They are used by BRLTTY to translate character sequences on the screen into their corresponding contracted braille representations.

BRLTTY presents contracted braille if:

- A contraction table has been selected. See the -c command line option and the contraction-table configuration file directive for details.
- The 6-dot braille feature has been activated. See the SIXDOTS command and the Text Style preference for details.

This feature isn't available if the --disable-contracted-braille build option was specified.

The following contraction tables are provided:

af

  Afrikaans (contracted)

am

  Amharic (uncontracted)

de-basis

  German (uncontracted)

de-kurzschrift

  German (contracted - 1998 standard)

de-vollschrift

  German (basic contractions)

en-ueb-g2

  Unified English Braille (grade 2)

en-us-g2

  American English (grade 2)

es

  Spanish (grade 2)

fr-abrege

  French (contracted)

fr-integral

  French (uncontracted)

ha

  Hausa (contracted)

id

  Indonesian (contracted)

ja

  Japanese (uncontracted)

ko-g1

  Korean (grade 1)

ko-g2

  Korean (grade 2)

ko

  Korean (uncontracted)

mg

  Malagasy (contracted)

mun

  Munda (contracted)

nl

  Dutch (contracted)

ny

  Chichewa (contracted)

ipa

  International Phonetic Alphabet

pt

  Portuguese (grade 2)

si

  Sinhalese (uncontracted)

sw

  Swahili (contracted)

th

  Thai (contracted)

zh-tw

  Taiwanese Chinese (uncontracted)

zh-tw-ucb

  Taiwanese Chinese (Unique Chinese Braille)

zu

  Zulu (contracted)

See the -c command line option, and the contraction-table configuration file directive for details regarding how to use a contraction table.

### Contraction Table Format

A contraction table consists of a sequence of entries, one per line, which define how character sequences are to be represented in braille. `UTF-8` character encoding must be used. White-space (blanks, tabs) at the beginning of a line, as well as before and/or after any operand, 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 format of a contraction table entry is:

> `directive operand ... [comment]`

Each directive has a specific number of operands. Any text beyond the last operand of a directive is interpreted as a comment. The order of the entries within a contraction table is, in general, anything that is convenient for its maintainer(s). An entry which defines an entity, e.g. `class`, must precede all references to that entity.

Entries which match character sequences are automatically rearranged from longest to shortest so that longer matches are always preferred. If more than one entry matches the same character sequence then their original table ordering is maintained. Thus, the same sequence may be translated differently under different circumstances.

### Contraction Table Operands

characters

  The first operand of a character sequence matching directive is the character sequence to be matched. Each character within the sequence may be:

  - Any single character other than a backslash or a white-space character.
  - A backslash-prefixed special character. These are:

    -

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

    \#

      A literal number sign. -

    \<name>

      The Unicode name of a character (use _ for space). -

    \\

      A literal backslash.

representation

  The second operand of those character sequence matching directives which have one is the braille representation of the sequence. Each braille cell is specified as 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. The special dot number `0`, which may not be used in conjunction with any other dot number, means no dots.

### Opcodes

An opcode is a keyword which tells the translator how to interpret the operands. The opcodes are grouped here by function.

### Table Administration

These opcodes make it easier to write contraction tables. They have no direct effect on the character translation.

`include` path

  Include the contents of another file. Nesting can be to any depth. Relative paths are anchored at the directory of the including file.

`locale` locale

  Define the locale for character interpretation (lowercase, uppercase, numeric, etc.). The locale may be specified as:

  language[`_`country][`.`charset][`@`modifier]

    The language component is required and should be a two-letter `ISO-639` language code. The country component is optional and should be a two-letter `ISO-3166` country code. The charset component is optional and should be a character set name, e.g. `ISO-8859-1`.

  C

    7-bit ASCII.

  -

    No locale.

  The last locale specification applies to the entire table. If this opcode isn't used then the `C` locale is assumed.

### Special Symbol Definition

These opcodes define special symbols which must be inserted into the braille text in order to clarify it.

`capsign` dots

  The symbol which capitalizes a single letter.

`begcaps` dots

  The symbol which begins a block of capital letters within a word.

`endcaps` dots

  The symbol which ends a block of capital letters within a word.

`letsign` dots

  The symbol which marks a letter which isn't part of a word.

`numsign` dots

  The symbol which marks the beginning of a number.

### Character Translation

These opcodes define the braille representations for character sequences. Each of them defines an entry within the contraction table. These entries may be defined in any order except, as noted below, when they define alternate representations for the same character sequence.

Each of these opcodes has a characters operand (which must be specified as a string), and a built-in condition governing its eligibility for use. The text is processed strictly from left to right, character by character, with the most eligible entry for each position being used. If there's more than one eligible entry for a given position, then the one with the longest character string is used. If there's more than one eligible entry for the same character string, then the one defined nearest to the beginning of the table is used (this is the only order dependency).

Many of these opcodes have a dots operand which defines the braille representation for its characters operand. It may also be specified as an equals sign (`=`), in which case it means one of two things. If the entry is for a single character, then it means that the currently selected computer braille representation (see the -t command line option and the text-table configuration file directive) for that character is to be used. If it's for a multi-character sequence, then the default representation for each character (see always) within the sequence is to be used.

Some special terms are used within the descriptions of these opcodes.

word

  A maximal sequence of one or more consecutive letters.

Now, finally, here are the opcode descriptions themselves:

`literal` characters

  Translate the entire white-space-bounded containing character sequence into computer braille (see the -t command line option and the text-table configuration file directive).

`replace` characters characters

  Replace the first set of characters, no matter where they appear, with the second. The replaced characters aren't reprocessed.

`always` characters dots

  Translate the characters no matter where they appear. If there's only one character, then, in addition, define the default representation for that character.

`repeatable` characters dots

  Translate the characters no matter where they appear. Ignore any consecutive repetitions of the same sequence.

`largesign` characters dots

  Translate the characters no matter where they appear. Remove white-space between consecutive words matched by this opcode.

`lastlargesign` characters dots

  Translate the characters no matter where they appear. Remove preceding white-space if the previous word was matched by the largesign opcode.

`word` characters dots

  Translate the characters if they're a word.

`joinword` characters dots

  Translate the characters if they're a word. Remove the following white-space if the first character after it is a letter.

`lowword` characters dots

  Translate the characters if they're a white-space-bounded word.

`contraction` characters

  Prefix the characters with a letter sign (see letsign) if they're a word.

`sufword` characters dots

  Translate the characters if they're either a word or at the beginning of a word.

`prfword` characters dots

  Translate the characters if they're either a word or at the end of a word.

`begword` characters dots

  Translate the characters if they're at the beginning of a word.

`begmidword` characters dots

  Translate the characters if they're either at the beginning or in the middle of a word.

`midword` characters dots

  Translate the characters if they're in the middle of a word.

`midendword` characters dots

  Translate the characters if they're either in the middle or at the end of a word.

`endword` characters dots

  Translate the characters if they're at the end of a word.

`prepunc` characters dots

  Translate the characters if they're part of punctuation at the beginning of a word.

`postpunc` characters dots

  Translate the characters if they're part of punctuation at the end of a word.

`begnum` characters dots

  Translate the characters if they're at the beginning of a number.

`midnum` characters dots

  Translate the characters if they're in the middle of a number.

`endnum` characters dots

  Translate the characters if they're at the end of a number.

### Character Classes

These opcodes define and use character classes. A character class associates a set of characters with a name. The name then refers to any character within the class. A character may belong to more than one class.

The following character classes are automatically predefined basdd on the selected locale:

digit

  Numeric characters.

letter

  Both uppercase and lowercase alphabetic characters. Some locales have additional letters which are neither uppercase nor lowercase.

lowercase

  Lowercase alphabetic characters.

punctuation

  Printable characters which are neither white-space nor alphanumeric.

space

  White-space characters. In the default locale these are: space, horizontal tab, vertical tab, carriage return, new line, form feed.

uppercase

  Uppercase alphabetic characters.

The opcodes which define and use character classes are:

`class` name characters

  Define a new character class. The characters operand must be specified as a string. A character class may not be used until it's been defined.

`after` class opcode ...

  The specified opcode is further constrained in that the matched character sequence must be immediately preceded by a character belonging to the specified class. If this opcode is used more than once on the same line then the union of the characters in all the classes is used.

`before` class opcode ...

  The specified opcode is further constrained in that the matched character sequence must be immediately followed by a character belonging to the specified class. If this opcode is used more than once on the same line then the union of the characters in all the classes is used.

## 6.4 Key Tables

Files with names of the form `*.ktb` are key tables, and with names of the form `*.kti` are key subtables. They are used by BRLTTY to bind keyboard key combinations to BRLTTY commands.

The following key tables are provided:

desktop

  bindings for full keyboards

keypad

  bindings for keypad-based navigation

laptop

  bindings for keyboards without a keypad

See the -k command line option, and the key-table configuration file directive for details regarding how to use a key table.

### Key Table Format

A key table consists of a sequence of directives, one per line, which define what each key combination is to be bound to. `UTF-8` character encoding must be used. 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.

### Key Table Directives

The following directives are provided:

`bind` keys command # comment

  Use the `bind` directive to bind a key combination to a command.

  keys

    The key combination to be bound. It is a sequence of one or more key names (see the file `ktb_keynames.h` within the `Programs` subdirectory of BRLTTY's source tree) separated by plus (`+`) signs. The initial keys are known as modifiers and may be pressed in any order. The last key must be pressed while all the modifiers are being held.

  command

    The name of a BRLTTY command (see section Commands for details).

    For the commands listed in section Feature Activation:

    - If no modifier is appended then the state of the feature is toggled.
    - If the modifier `+on` is appended then the feature is turned on.
    - If the modifier `+off` is appended then the feature is turned off.

    For the commands listed in section Character Commands: The command acts on the character where the cursor is.

    For the commands listed in section Base Commands: The modifier `+`n, wehre n is a non-negative integer, may be appended. If this modifier isn't specified then `0` is assumed.

  Examples:

  - `bind CapsLock+Enter CsrTrk`
  - `bind CapsLock+O CsrTrk+off`
  - `bind CapsLock+P CsrTrk+on`
  - `bind KPInsert+1 GoToMark+1`
`include` file # comment

  Use the `include` directive to include the content of a key subtable. It is recursive, which means that any key subtable can itself include yet another key subtable. 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.

### Keyboard Properties

The default is that all keyboards are monitored. A subset of the keyboards may be selected by specifying one or more of the following properties (see the -K command line option, and the keyboard-properties configuration file directive):

type

  The bus type, specified as one of the following keywords: `any`, `ps2`, `usb`, `bluetooth`.

vendor

  The vendor identifier, specified as a 16-bit unsigned integer.

product

  The product identifier, specified as a 16-bit unsigned integer.

The vendor and product identifiers may be specified in decimal (no prefix), octal (prefixed by `0`), or hexadecimal (prefixed by `0x`). Specifying `0` means match any value (as if the property weren't specified).

Next Previous Contents