~~~~~~~~~~~~~~~~~~ Contraction Tables ~~~~~~~~~~~~~~~~~~ .. include:: prologue.rst 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 |README.Customize| 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: .. parsed-literal:: *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 --------------------- .. parsed-literal:: literal *characters* Translate the entire whitespace-bounded text containing the character sequence into computer braille. The Always Directive -------------------- .. parsed-literal:: 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 ------------------------ .. parsed-literal:: repeatable *characters* *representation* Unconditionally translate the characters no matter where they appear. Ignore any consecutive repetitions of the same sequence. The LargeSign Directive ----------------------- .. parsed-literal:: largeSign *characters* *representation* Unconditionally translate the characters no matter where they appear. Remove whitespace between consecutive words matched by this directive. The LastLargeSign Directive --------------------------- .. parsed-literal:: 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 ------------------ .. parsed-literal:: word *characters* *representation* Translate the characters if they're a word. The JoinWord Directive ---------------------- .. parsed-literal:: 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 --------------------- .. parsed-literal:: lowWord *characters* *representation* Translate the characters if they're a whitespace-bounded word. The Contraction Directive ------------------------- .. parsed-literal:: contraction *characters* Prefix the characters with a letter sign (see `The LetSign Directive`_) if they're a word. The SufWord Directive --------------------- .. parsed-literal:: sufWord *characters* *representation* Translate the characters if they're either a word or at the beginning of a word. The PrfWord Directive --------------------- .. parsed-literal:: prfWord *characters* *representation* Translate the characters if they're either a word or at the end of a word. The BegWord Directive --------------------- .. parsed-literal:: begWord *characters* *representation* Translate the characters if they're at the beginning of a word. The BegMidWord Directive ------------------------ .. parsed-literal:: begMidWord *characters* *representation* Translate the characters if they're either at the beginning or in the middle of a word. The MidWord Directive --------------------- .. parsed-literal:: midWord *characters* *representation* Translate the characters if they're in the middle of a word. The MidEndWord Directive ------------------------ .. parsed-literal:: midEndWord *characters* *representation* Translate the characters if they're either in the middle or at the end of a word. The EndWord Directive --------------------- .. parsed-literal:: endWord *characters* *representation* Translate the characters if they're at the end of a word. The PrePunc Directive --------------------- .. parsed-literal:: prePunc *characters* *representation* Translate the characters if they're part of punctuation at the beginning of a word. The PostPunc Directive ---------------------- .. parsed-literal:: postPunc *characters* *representation* Translate the characters if they're part of punctuation at the end of a word. The BegNum Directive -------------------- .. parsed-literal:: begNum *characters* *representation* Translate the characters if they're at the beginning of a number. The MidNum Directive -------------------- .. parsed-literal:: midNum *characters* *representation* Translate the characters if they're in the middle of a number. The EndNum Directive -------------------- .. parsed-literal:: endNum *characters* *representation* Translate the characters if they're at the end of a number. Character Classes ================= The Class Directive ------------------- .. parsed-literal:: class *name* *characters* Define a new character class. A character class may not be used until it has been defined. The After Directive ------------------- .. parsed-literal:: 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 -------------------- .. parsed-literal:: 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 --------------------- .. parsed-literal:: capSign *representation* Define the symbol which capitalizes a single letter. The BegCaps Directive --------------------- .. parsed-literal:: begCaps *representation* Define the symbol which begins a block of capital letters within a word. The EndCaps Directive --------------------- .. parsed-literal:: endCaps *representation* Define the symbol which ends a block of capital letters within a word. The LetSign Directive --------------------- .. parsed-literal:: letSign *representation* Define the symbol which marks a letter which isn't part of a word. The NumSign Directive --------------------- .. parsed-literal:: numSign *representation* Define the symbol which marks the beginning of a number. Special Directives ================== The Replace Directive --------------------- .. parsed-literal:: replace *characters* *characters* Translate the first character sequence into the second character sequence. The replacement characters are then recontracted. The Emoji Directive ------------------- .. parsed-literal:: 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 ``_. Standard Directives =================== .. include:: nesting-directives.rst Operands ======== .. include:: string-operand.rst 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 |README.BrailleDots| 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 ====================== .. csv-table:: :header: "Name", "Description" :file: contraction-table.csv