Next Previous Contents

5. Contraction Tables

BRLTTY can display in-line contracted braille. It does this if:

The following contraction tables are provided:

compress.ctb

Remove excessive white-space.

en-us-g2.ctb

Grade 2 American English

5.1 File Format

Blank lines are ignored. Any leading and trailing white-space (any number of blanks and/or tabs) is ignored. Lines which begin with a number sign (#) are ignored, i.e. they're comments.

# This is a comment.
All other lines define table entries.

The general form of a table entry is an opcode followed by its operands. The opcode and its operands are separated from one another by white-space. Each opcode has a specific number of operands, and any text following its last operand is treated as a comment.

opcode operand ... comment

The opcode is a number which tells the translator how to interpret the operands. Opcode 0 can be used to assign a meaningful name to each needed opcode, e.g. opcode for 0 itself. If, for example, a table begins with:

0 0 opcode
then all the rest of the opcodes it needs can be defined like this:
opcode 1 include
This scheme, i.e. no built-in opcode names, was chosen in order to allow a table for some language's braille to be written solely in that language itself.

The following operand types are supported:

string

A sequence of characters other than white-space (which terminates the string) and backslashes (\). The following special representations are also supported:

\\

backslash

\f

form feed

\n

new line

\oooo

3-digit octal value

\r

carriage return

\s

blank (space)

\t

horizontal tab

\v

vertical tab

\xxx

2-digit hexadecimal value

number

An integer. It may be specified in any of the following ways:

decimal

A sequence of decimal digits (0-9), with the first digit being nonzero (1-9).

hexadecimal

A sequence of hexadecimal digits (0-9, and either a-f or A-F), preceded by either 0x or 0X.

octal

A sequence of octal digits (0-7), with the first digit being zero (0).

dots

A braille symbol. The braille dots must be specified via their standard numbers (see section Braille Dot Numbering Convention), and, for a multi-cell symbol, the cell specifications must be separated from one another by a dash (-). For example, the contraction for the English word lord (the letter l prefixed with dot 5) would be specified as 5-123. A space may be specified via the special dot number 0.

5.2 Opcode Summary by Number

First, here's a quick summary of all of the contraction table opcodes. For the details, see section Opcodes by Function.

0 opcode name

Name opcode.

1 path

Include file.

2 dots

Define capital sign.

3 dots

Define begin capitals sign.

4 dots

Define letter sign.

5 dots

Define number sign.

6 characters dots

Translate unconditionally.

7 characters dots

Translate unconditionally, remove repetitions.

8 characters dots

Translate if word.

9 characters dots

Translate if at beginning of word.

10 characters dots

Translate if in middle of word.

11 characters dots

Translate if at end of word.

12 characters dots

Translate if in middle or at end of word.

13 characters dots

Translate if in middle of number.

14 characters dots

Translate if white-space-bounded word.

15 characters dots

Translate unconditionally, join consecutive words of this type.

16 characters dots

Translate if word, join to next word.

17 characters

Translate whole white-space-bounded sequence unconditionally into computer braille.

18 characters

Prefix with letter sign if word.

19 characters

Ignore unconditionally.

20 characters dots

Translate if at end of number.

21 characters dots

Translate if at beginning of number.

22 characters dots

Translate if part of leading punctuation.

23 characters dots

Translate if part of trailing punctuation.

24 characters dots

Translate if word or at beginning of word.

25 dots

Define end capitals sign.

5.3 Opcodes by Function

Now for all of the details. The opcodes here are grouped by function rather than sorted by number. For a numerically sorted list, see section Opcode Summary by Number.

Table Administration

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

0 opcode name

Assign a name to an opcode. The name must be defined before it's used.

1 path

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

Special Symbol Definition

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

2 dots

The symbol which capitalizes a single letter.

3 dots

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

25 dots

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

4 dots

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

5 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 opcode 6) 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:

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

19 characters

Ignore the characters no matter where they appear.

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

7 characters dots

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

15 characters dots

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

8 characters dots

Translate the characters if they're a word.

16 characters dots

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

14 characters dots

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

18 characters

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

24 characters dots

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

9 characters dots

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

10 characters dots

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

12 characters dots

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

11 characters dots

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

22 characters dots

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

23 characters dots

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

21 characters dots

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

13 characters dots

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

20 characters dots

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


Next Previous Contents