Contraction Tables

Contents

Description

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.

Contraction tables can usually be found in the /etc/brltty/Contraction/ directory (see Local Customization for more details). SEe Contraction Table list for a list of BRLTTY's contraction tables.

A contraction table consists of a sequence of directives, one per line, that define how character sequences are to be represented in contracted braille. UTF-8 character encoding must be used. Whitespace (blanks, tabs) at the beginning of a line, as well as before and/or after any operand, is ignored. Lines containing only whitespace are ignored. If the first non-whitespace character of a line is # then that line is a comment and is ignored.

Contraction Directives

The format of a contraction directive 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. This commenting capability is often used to list some of the words that make the directive necessary.

The order of the directives within a contraction table is, in general, anything that is convenient for its maintainer(s). A directive that defines an entity, e.g. The Class Directive, must precede all references to that entity.

Directives that match character sequences are automatically rearranged such that longer sequences are matched first. If more than one directive matches the same character sequence then their original table ordering is maintained.

Whenever a character needs to be written, its representation as defined via The Always Directive is used. In principle, this means that every character within the representation operand of every contraction directive should be explicitly defined via The Always Directive. If a character's representation hasn't been defined then the Unicode Replacement Character (U+FFFD) is used - if it's representation hasn't been defined then all eight dots are used.

The Literal Directive

literal characters

Translate the entire whitespace-bounded text containing the character sequence into computer braille.

The Always Directive

always characters representation

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

The Repeatable Directive

repeatable characters representation

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

The LargeSign Directive

largeSign characters representation

Unconditionally translate the characters no matter where they appear. Remove whitespace between consecutive words matched by this directive.

The LastLargeSign Directive

lastLargeSign characters representation

Unconditionally translate the characters no matter where they appear. Remove preceding whitespace if the previous word was matched by The LargeSign Directive.

The Word Directive

word characters representation

Translate the characters if they're a word.

The JoinWord Directive

joinWord characters representation

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

The LowWord Directive

lowWord characters representation

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

The Contraction Directive

contraction characters

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

The SufWord Directive

sufWord characters representation

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

The PrfWord Directive

prfWord characters representation

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

The BegWord Directive

begWord characters representation

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

The BegMidWord Directive

begMidWord characters representation

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

The MidWord Directive

midWord characters representation

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

The MidEndWord Directive

midEndWord characters representation

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

The EndWord Directive

endWord characters representation

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

The PrePunc Directive

prePunc characters representation

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

The PostPunc Directive

postPunc characters representation

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

The BegNum Directive

begNum characters representation

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

The MidNum Directive

midNum characters representation

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

The EndNum Directive

endNum characters representation

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

Character Classes

The Class Directive

class name characters

Define a new character class. A character class may not be used until it has been defined.

The After Directive

after class directive

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

The Before Directive

before class directive

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

Indicator Specification

The CapSign Directive

capSign representation

Define the symbol which capitalizes a single letter.

The BegCaps Directive

begCaps representation

Define the symbol which begins a block of capital letters within a word.

The EndCaps Directive

endCaps representation

Define the symbol which ends a block of capital letters within a word.

The LetSign Directive

letSign representation

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

The NumSign Directive

numSign representation

Define the symbol which marks the beginning of a number.

Special Directives

The Replace Directive

replace characters characters

Translate the first character sequence into the second character sequence. The replacement characters are then recontracted.

The Emoji Directive

emoji language

Translate an emoji character sequence into its description in the specified language. The language operand is an ISO 639 two-letter language code.

This directive only works if at least ICU version 57 is installed.

This directive relies on data provided by the CLDR package. CLDR stands for the Common Locale Data Repository project. Knoqwn names for this package include:

  • cldr-emoji-annotation
  • unicode-cldr

At the time of this writing, this project is maintained at https://github.com/unicode-org/cldr.

Standard Directives

The Include Directive

include file # comment

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

Operands

The String Operand

A string operand may be specified as a non-whitespace sequence of:

  • Any single character other than a backslash (\\) or a white-space character.

  • A backslash-prefixed special character. These are:

    Sequence Meaning
    \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.
    \R The Unicode replacement 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)
    \<name> The Unicode name of a character (use _ for space).
    \{variable} The value of a variable.
    \\ A literal backslash.
    \# A literal number sign.

The Representation Operand

The contracted braille representation of a character sequence. Braille cells are separated from one another by a minus (-) sign. 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 (see Braille Dots for details). The special dot number 0 means no dots, and may not be used in conjunction with any other dot numbers.

The equals (=) sign , when used all by itself, means that the characters operand of the contraction directive is to be written without any translation.

Contraction Table List

name description
auto locale-based autoselection
af Afrikaans (contracted)
am Amharic (uncontracted)
de German
de-g0 German (uncontracted)
de-g1 German (basic contractions)
de-g2 German (contracted)
de-1998 German (contracted - 1998 standard)
de-2015 German (contracted - 2015 standard)
en English
en_US English (United States)
en-ueb-g1 English (Unified, uncontracted)
en-ueb-g2 English (Unified, contracted)
en-us-g2 English (United States, contracted)
es Spanish (contracted)
fr French
fr-g1 French (uncontracted)
fr-g2 French (contracted)
ha Hausa (contracted)
id Indonesian (contracted)
ipa International Phonetic Alphabet
ja Japanese (uncontracted)
ko Korean
ko-g0 Korean (uncontracted)
ko-g1 Korean (partially contracted)
ko-g2 Korean (contracted)
lt Lithuanian (uncontracted)
mg Malagasy (contracted)
mun Munda (contracted)
nl Dutch (contracted)
ny Chichewa (contracted)
pt Portuguese (contracted)
ru Russian (contracted)
si Sinhalese (uncontracted)
sw Swahili (contracted)
th Thai (contracted)
zh_TW Chinese (Taiwan, uncontracted)
zu Zulu (contracted)