# Contraction Tables

Contents

- Description
- Contraction Directives
  - The Literal Directive
  - The Always Directive
  - The Repeatable Directive
  - The LargeSign Directive
  - The LastLargeSign Directive
  - The Word Directive
  - The JoinWord Directive
  - The LowWord Directive
  - The Contraction Directive
  - The SufWord Directive
  - The PrfWord Directive
  - The BegWord Directive
  - The BegMidWord Directive
  - The MidWord Directive
  - The MidEndWord Directive
  - The EndWord Directive
  - The PrePunc Directive
  - The PostPunc Directive
  - The BegNum Directive
  - The MidNum Directive
  - The EndNum Directive
- Character Classes
  - The Class Directive
  - The After Directive
  - The Before Directive
- Indicator Specification
  - The CapSign Directive
  - The BegCaps Directive
  - The EndCaps Directive
  - The LetSign Directive
  - The NumSign Directive
- Special Directives
  - The Replace Directive
  - The Emoji Directive
- Standard Directives
  - The Include Directive
- Operands
  - The String Operand
  - The Representation Operand
- Contraction Table List

## 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.
  `\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-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)