Documents/README.ContractionTables

~~~~~~~~~~~~~~~~~~
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
`<https://github.com/unicode-org/cldr>`_.

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-rows: 1
   :file: contraction-table.csv