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). In addition to this default text table, several 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_BE

Dutch (Belgium)

nl_NL

Dutch (Netherlands)

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:

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 dots # 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:

include file dots # 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:

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)

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:

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.


Next Previous Contents