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:

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. Characters defined with 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 with the char directive - the others should be defined with the glyph directive (which has the same syntax). If more than one character with the same braille representation is defined with the char directive (which is currently allowed for backward compatibility) then the first one is selected.

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

glyph character dots # comment

Use the glyph directive to specify how a Unicode character is to be represented in braille. Characters defined with this directive are output-only. They cannot be entered from a braille keyboard.

See the char directive for syntax details and for examples.

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:

left_right

The lefthand column represents the foreground colours:

Dot 1

Blue

Dot 2

Green

Dot 3

Red

Dot 7

Bright

The righthand column represents the background colours:

Dot 4

Blue

Dot 5

Green

Dot 6

Red

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.

invleft_right

The lefthand column represents the foreground colours:

Dot 1

Blue

Dot 2

Green

Dot 3

Red

Dot 7

Bright

The righthand column represents the background colours:

Dot 4

Blue

Dot 5

Green

Dot 6

Red

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.

upper_lower

The upper square represents the foreground colours:

Dot 1

Red

Dot 4

Green

Dot 2

Blue

Dot 5

Bright

The lower square represents the background colours:

Dot 3

Red

Dot 6

Green

Dot 7

Blue

Dot 8

Blink

A dot is raised when its corresponding attribute bit is on.

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.

The following contraction tables are provided:

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]

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 based 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 braille display and keyboard key combinations to BRLTTY commands.

The names of braille display key table files begin with brl-xx-", where xx is the two-letter driver identification code. The rest of the name identifies the model(s) for which the key table is used.

The names of keyboard table files begin with kbd-. The rest of the name describes the kind of keyboard for which the keyboard table has been designed.

The following keyboard tables are provided:

braille

bindings for braille keyboards

desktop

bindings for full keyboards

keypad

bindings for keypad-based navigation

laptop

bindings for keyboards without a keypad

sun_type6

bindings for Sun Type 6 keyboards

Key Table Directives

A key table consists of a sequence of directives, one per line, which define how keys and key combinations are to be interpreted. 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 a number (#) sign then that line is a comment and is ignored.

The precedence for resolving each key press/release event is as follows:

1. A hotkey press or release defined within the current context. See the hotkey directive for details.
2. A key combination defined within the current context. See the bind directive for details.
3. A braille keyboard command defined within the current context. See the map and superimpose directives for details.
4. A key combination defined within the default context. See the bind directive for details.

The following directives are provided:

The Assign Directive

Create or update a variable associated with the current include level. The variable is visible to the current and to lower include levels, but not to higher include levels.

assign variable [value]

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 which is to be assigned to the variable. If it's not supplied then a zero-length (null) value is assigned.

The escape sequence \{variable} is substituted with the value of the variable named within the braces. The variable must have been defined at the current or at a higher include level.

Examples:

• assign nullValue
• assign ReturnKey Key1
• bind \{ReturnKey} RETURN

The Bind Directive

Define which BRLTTY command is executed when a particular combination of one or more keys is pressed. The binding is defined within the current context.

bind keys command

keys

The key combination which is to be bound. It's a sequence of one or more key names separated by plus (+) signs. The final (or only) key name may be optionally prefixed with an exclamation (!) point. The keys may be pressed in any order, with the exception that if the final key name is prefixed with an exclamation point then it must be pressed last. The exclamation point prefix means that the command is executed as soon as that key is pressed. If not used, the command is executed as soon as any of the keys is released.

command

The name of a BRLTTY command. One or more modifiers may be optionally appended to the command name by using a plus (+) sign as the separator.

• For commands which enable/disable a feature:
  • If the modifier +on is specified then the feature is enabled.
  • If the modifier +off is specified then the feature is disabled.
  • If neither +on nor +off is specified then the state of the feature is toggled on/off.
• For commands which move the braille window:
  • If the modifier +route is specified then, if necessary, the cursor is automatically routed so that it's always visible on the braille display.
• For commands which move the braille window to a specific line on the screen:
  • If the modifier +toleft is specified then the braille window is also moved to the beginning of that line.
  • If the modifier +scaled is specified then the set of keys bound to the command is interpreted as though it were a scroll bar. If it isn't, then there's a one-to-one correspondence between keys and lines.
• For commands which require an offset:
  • The modifier +offset, where offset is a non-negative integer, may be specified. If it isn't supplied then +0 is assumed.

Examples:

• bind Key1 CSRTRK
• bind Key1+Key2 CSRTRK+off
• bind Key1+Key3 CSRTRK+on
• bind Key4 TOP
• bind Key5 TOP+route
• bind VerticalSensor GOTOLINE+toleft+scaled
• bind Key6 CONTEXT+1

The Context Directive

Define alternate ways to interpret certain key events and/or combinations. A context contains definitions created by the bind, hotkey, ignore, map, and superimpose directives.

context name [title]

name

Which context subsequent definitions are to be created within. These special contexts are predefined:

default

The default context. If a key combination hasn't been defined within the current context then its definition within the default context is used. This only applies to definitions created by the bind directive.

menu

This context is used when within BRLTTY's preferences menu.

title

A person-readable description of the context. It may contain spaces, and standard capitalization conventions should be used. This operand is optional. If supplied when selecting a context which already has a title then the two must match. Special contexts already have internally-assigned titles.

A context is created the first time it's selected. It may be reselected any number of times thereafter.

All subsequent definitions until either the next context directive or the end of the current include level are created within the selected context. The initial context of the top-level key table is default. The initial context of an included key subtable is the context which was selected when it was included. Context changes within included key subtables don't affect the context of the including key table or subtable.

If a context has a title then it is persistent. When a key event causes a persistent context to be activated, that context remains current until a subsequent key event causes a different persistent context to be activated.

If a context doesn't have a title then it is temporary. When a key event causes a temporary context to be activated, that context is only used to interpret the very next key event.

Examples:

• context menu
• context braille Braille Input
• context DESCCHAR

The Hide Directive

Specify whether or not certain definitions (see the bind, hotkey, map, and superimpose directives) and notes (see the note directive) are included within the key table's help text.

hide state

state

One of these keywords:

on

They're excluded.

off

They're included.

The specified state applies to all subsequent definitions and notes until either the next hide directive or the end of the current include level. The initial state of the top-level key table is off. The initial state of an included key subtable is the state which was selected when it was included. State changes within included key subtables don't affect the state of the including key table or subtable.

Examples:

• hide on

The Hotkey Directive

Bind the press and release events of a specific key to two separate BRLTTY commands. The bindings are defined within the current context.

hotkey key press release

key

The name of the key which is to be bound.

press

The name of the BRLTTY command which is to be executed whenever the key is pressed.

release

The name of the BRLTTY command which is to be executed whenever the key is released.

Modifiers may be appended to the command names. See the command operand of the bind directive for details.

Specify NOOP if no command is to be executed. Specifying NOOP for both commands effectively disables the key.

Examples:

• hotkey Key1 CSRVIS+off CSRVIS+on
• hotkey Key2 NOOP NOOP

The IfKey Directive

Conditionally process a key table directive only if the device has a particular key.

ifkey key directive

key

The name of the key whose availability is to be tested.

directive

The key table directive which is to be conditionally processed.

Examples:

• ifkey Key1 ifkey Key2 bind Key1+Key2 HOME

The Include Directive

Process the directives within a key subtable. It's 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.

include file

file

The key subtable which is to be included. It may be either a relative or an absolute path. If relative, it's anchored at the directory containing the including key table or subtable.

Examples:

• include common.kti
• include /path/to/my/keys.kti

The Ignore Directive

Ignore a specific key while within the current context.

ignore key

key

The name of the key which is to be ignored.

Examples:

• ignore Key1

The Map Directive

Map a key to a braille keyboard function. The mapping is defined within the current context.

map key function

key

The name of the key which is to be mapped. More than one key may be mapped to the same braille keyboard function.

function

The name of the braille keyboard function. It may be one of the following keywords:

DOT1

The upper-left standard braille dot.

DOT2

The middle-left standard braille dot.

DOT3

The lower-left standard braille dot.

DOT4

The upper-right standard braille dot.

DOT5

The middle-right standard braille dot.

DOT6

The lower-right standard braille dot.

DOT7

The lower-left computer braille dot.

DOT8

The lower-right computer braille dot.

SPACE

The space bar.

SHIFT

The shift key.

UPPER

If a lowercase letter is being entered then translate it to its uppercase equivalent.

CONTROL

The control key.

META

The left alt key.

If a key combination consists only of keys which have been mapped to braille keyboard functions, and if those functions when combined form a valid braille keyboard command, then that command is executed as soon as any of the keys is released. A valid braille keyboard command must include either any combination of dot keys or the space bar (but not both). If at least one dot key is included then the braille keyboard functions specified by the superimpose directives within the same context are also implicitly included.

Examples:

• map Key1 DOT1

The Note Directive

Add a person-readable explanation to the key table's help text. Notes are commonly used, for example, to describe the placement, sizes, and shapes of the keys on the device.

note text

text

The explanation which is to be added. It may contain spaces, and should be grammatically correct.

Each note specifies exactly one line of explanatory text. Leading space is ignored so indentation cannot be specified.

There's no limit to the number of notes which may be specified. All of them are gathered together and presented in a single block at the start of the key table's help text.

Examples:

• note Key1 is the round key at the far left on the front surface.

The Superimpose Directive

Implicitly include a braille keyboard function whenever a braille keyboard command consisting of at least one dot is executed. The implicit inclusion is defined within the current context. Any number of them may be specified.

superimpose function

function

The name of the braille keyboard function. See the function operand of the map directive for details.

Examples:

• superimpose DOT7

The Title Directive

Provide a person-readable summary of the key table's purpose.

title text

text

A one-line summary of what the key table is used for. It may contain spaces, and standard capitalization conventions should be used.

The title of the key table may be specified only once.

Examples:

• title Bindings for Keypad-based Navigation

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