BRLTTY: Translation Tables

Next Previous Contents

## 5. Translation Tables

BRLTTY uses two translation tables to govern the mapping from bytes to dot combinations.

## 5.1 Text Translation

The first, and most important, is the text translation table. BRLTTY is initially configured to use the North American Braille Computer Code (NABCC). In addition to this default text translation table, several alternatives are provided:

text.danish.tbl

  Danish

text.es.tbl

  Spanish

text.french.tbl

  French

text.german.tbl

  German

text.it.tbl

  Italian

text.no-h.tbl

  Norwegian and German

text.no-p.tbl

  Norwegian

text.pl-iso02.tbl

  Polish (iso-8859-2)

text.simple.tbl

  American English

text.sweden.tbl

  Swedish

text.swedish.tbl

  Swedish

text.uk.tbl

  United Kingdom English

text.us.tbl

  American English

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

## 5.2 Attributes Translation

The attributes translation table is 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 attribute bits. Two attributes translation tables are provided:

attributes.tbl

  The lefthand column represents the background colours:

  Dot 1

    Red

  Dot 2

    Green

  Dot 3

    Blue

  Dot 7

    Blink

  The righthand column represents the foreground colours:
  Dot 4

    Red

  Dot 5

    Green

  Dot 6

    Blue

  Dot 8

    Bright

  A dot is raised when its corresponding attribute bit is on. This is the default attributes translation 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.tbl

  The lefthand column represents the background colours:

  Dot 1

    Red

  Dot 2

    Green

  Dot 3

    Blue

  Dot 7

    Blink

  The righthand column represents the foreground colours:
  Dot 4

    Red

  Dot 5

    Green

  Dot 6

    Blue

  Dot 8

    Bright

  A foreground bit being on triggers its corresponding dot, whereas a background 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 translation table.

## 5.3 Table Format

A translation table is a 256-byte binary file. It's indexed with either a character or an attributes byte, and the byte at that position contains the corresponding dot combination. The mapping from bit to dot is as follows:

Bit 0

  Dot 1

Bit 1

  Dot 4

Bit 2

  Dot 2

Bit 3

  Dot 5

Bit 4

  Dot 3

Bit 5

  Dot 6

Bit 6

  Dot 7

Bit 7

  Dot 8

This particular mapping makes it easy and efficient for BRLTTY to vertically shift a dot pattern.

## 5.4 Table Utilities

These utilities reside within the `BrailleTables` subdirectory, and aren't built as part of the regular procedure. To build them, first ensure that BRLTTY has been configured (see section Build Options), and then run `make` within the `BrailleTables` subdirectory.

> `

>     cd BrailleTables
>     make

> `

### tbl2txt

This utility converts (uncompiles) a translation table into a text file for readability and/or modification.

> `tbl2txt -option ... table-file text-file`

table-file

  The translation table which is to be converted.

text-file

  The file into which the text representing the table content is to be written.

`-c`name `--code-page=`name

  The character set used to annotate each line of the text file.

The generated text file can, without modification, be recompiled back into a translation table with the txt2tbl utility. Each of its lines contains lots of interesting information.

If the `-c` option isn't specified, each line looks like this:

> `cc xx ddd (73214568)tt B+bbbb name`

If the `-c` option is specified, each line looks like this:

> `cc xx ddd (73214568)tt B+bbbb U+uuuu description`

cc

  The character itself. Unprintable characters are represented canonically. Control characters are flagged with a circumflex, e.g. Control-A (character 1) is `^A`. Meta control characters are flagged with a tilde, e.g. Meta-Control-A (character 129) is `~A`.

xx

  The hexadecimal value of the character.

ddd

  The decimal value of the character.

`(73214568)`

  The braille dot numbers. If a dot isn't to be raised, then its number is replaced with a blank. The English letter `y`, for example, would be `( 3 1456 )`. The dot numbers appear in the same order as on a standard braille keyboard so as to make it easier to visualize the braille character.

tt

  The hexadecimal value of the byte representing the dot combination which is in the translation table.

bbbb

  The hexadecimal value of the unicode number corresponding to the dot combination.

name

  The ASCII name of the character (only shown if the `-c` option isn't specified).

uuuu

  The hexadecimal value of the unicode number corresponding to the character (only shown if the `-c` option is specified).

description

  The formal unicode description for the character (only shown if the `-c` option is specified).

### txt2tbl

This utility compiles a translation table.

> `txt2tbl -option ... text-file table-file`

text-file

  The source file describing the table content.

table-file

  The file into which the translation table is to be written.

`-d` `--duplicates`

  Display a warning for each dot combination which has been used more than once.

`-m` `--missing`

  Display a warning for each dot combination which hasn't been used.

A line which assigns a dot combination to a character must contain that dot combination within parenthesis, e.g. `(12)`. The text file must contain exactly 256 such lines, each one, in order, defining the braille representation for its corresponding character. The dot numbers may be specified in any order, but each must only be specified once. It's valid to specify no number at all, e.g. `()` (for a space). Any number of spaces may occur any number of times anywhere between the parentheses. All characters before the left parenthesis and after the right parenthesis are ignored. All lines which don't contain a left parenthesis are ignored.

The algorithm for locating the dot numbers is actually a bit more complicated because a line may contain more than one left and/or right parenthesis (the tbl2txt utility does this). The first right parenthesis which is preceded by at least one left parenthesis is used. The nearest left parenthesis to the left of that right parenthesis is used. The line `)((12)`, for example, is valid.

### tbl2tbl

This utility converts a binary translation table from one dot mapping to another.

> `tbl2tbl input-mapping output-mapping`

input-mapping

  The dot mapping used within the source table.

output-mapping

  The dot mapping to be used within the table being generated.

The source table is read from standard input, and the converted table is written to standard output. The following dot mappings are supported:

standard

  BRLTTY's native mapping (described above).

tieman

  The mapping used by Tieman B.V..

  Bit 0

    Dot 1

  Bit 1

    Dot 2

  Bit 2

    Dot 3

  Bit 3

    Dot 7

  Bit 4

    Dot 8

  Bit 5

    Dot 6

  Bit 6

    Dot 5

  Bit 7

    Dot 4

alva

  The mapping used by Alva B.V. and Telesensory Systems Inc..

  Bit 0

    Dot 1

  Bit 1

    Dot 2

  Bit 2

    Dot 3

  Bit 3

    Dot 4

  Bit 4

    Dot 5

  Bit 5

    Dot 6

  Bit 6

    Dot 7

  Bit 7

    Dot 8

Next Previous Contents