Documents/README.TextTables - brltty - Git at Google

 ~~~~~~~~~~~
 Text Tables
 ~~~~~~~~~~~

 .. include:: prologue.rst

 Description
 ===========

 Files with names of the form ``*.ttb`` are text tables, and with names of the
 form ``*.tti`` are text subtables. They are used by BRLTTY to translate the
 characters on the screen into their corresponding 8-dot computer braille
 representations (see |README.BrailleDots| for details).

 Text tables can usually be found in the ``/etc/brltty/Text/`` directory (see
 |README.Customize| for more details). See `Text Table List`_ for a list of
 BRLTTY's text tables.

 A text table consists of a sequence of directives, one per line, which define
 how each character is to be represented in 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 of any directive, 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.

 The precedence for determining the braille representation for a character is as
 follows:

 1) If the character is within the Unicode braille Row (U+2800 through U+28FF)
    then its low-order eight bits are used as follows:

    ===  ========  ===
    Hex  Binary    Dot
    ---  --------  ---
    01   00000001  1
    02   00000010  2
    04   00000100  3
    08   00001000  4
    10   00010000  5
    20   00100000  6
    40   01000000  7
    80   10000000  8
    ===  ========  ===

 2) If the character is within the Unicode private use row U+F000 through U+F0FF
    then its low-order byte is:

    A) interpreted as a single-byte character within the locAL character set
    B) translated to Unicode
    C) reprocessed

 3) An explicit representation (defined via `The Char Directive`_,
    `The Glyph Directive`_, or `The Byte Directive`_.

 4) An equivalent representation (defined via `The Alias Directive`_).

 5) The explicit representation of the Unicode base character.

 6) The explicit representation of the transliterated ASCII character.

 7) The explicit representation of the Unicode Replacement Character (U+FFFD).

 8) The explicit representation of a question mark (``?``).

 9) All eight braille dots.

 Directives
 ==========

 .. |character operand| replace::
    The character being defined.
    See `The String Operand`_ for details.

 .. |byte operand| replace::
    The character being defined.
    It may be specified in any of the ways supported by `The String Operand`_
    except that the Unicode-specific forms (``\u``, ``\U``, ``\<``) may not be used.

 .. |dots operand| replace::
    The braille representation for the character being defined.
    See `The Dots Operand`_ for details.

 .. |cell operand| replace::
    The braille representation for the character being tested.
    See `The Cell Operand`_ for details.

 The Char Directive
 ------------------

 .. parsed-literal:: char *character* *dots* # *comment*

 Use this directive to specify how a Unicode character is to be represented in
 braille. A character defined via this directive can also be entered from a
 braille keyboard. If several characters have the same braille representation
 then only one of them should be defined via this directive - the others should
 be defined via `The Glyph Directive`_ (which has the same syntax). If more than
 one character with the same braille representation is defined via this
 directive (which is allowed for backward compatibility) then the first one is
 used when entered from a braille keyboard.

 *character*
    |character operand|

 *dots*
    |dots operand|

 Examples::

    char a 1
    char b (12)
    char c ( 4  1   )
    char \\ 12567
    char \s 0
    char \x20 ()
    char \<LATIN_SMALL_LETTER_D> 145

 The Glyph Directive
 -------------------

 .. parsed-literal:: glyph *character* *dots* # *comment*

 Use this directive to specify how a Unicode character is to be represented in
 braille. A character defined via this directive is output-only - it can't
 be entered from a braille keyboard.

 *character*
    |character operand|

 *dots*
    |dots operand|

 See `The Char Directive`_ for examples.

 The Input Directive
 -------------------

 .. parsed-literal:: input *character* *dots* # *comment*

 Use this directive to specify how a Unicode character is to be entered from a
 braille keyboard. A character defined via this directive is input-only - its
 actual braille representation isn't defined.

 *character*
    |character operand|

 *dots*
    |dots operand|

 See `The Char Directive`_ for examples.

 The Alias Directive
 -------------------

 .. parsed-literal:: alias *from* *to* # *comment*

 Use this directive to define the *from* Unicode character such that it has the
 same braille representation as the *to* Unicode character. See
 `The String Operand`_ for details on how to specify both operands.

 The Byte Directive
 ------------------

 .. parsed-literal:: byte *byte* *dots* # *comment*

 Use this directive to specify how a character in the local character set is to
 be represented in braille. It has been retained for backward compatibility but
 should not be used. Unicode characters should be defined (via either
 `The Char Directive`_ or `The Glyph Directive`_) so that the text table remains
 valid regardless of what the local character set is.

 *byte*
    |byte operand|

 *dots*
    |dots operand|

 The IfGlyph Directive
 ---------------------

 .. parsed-literal:: ifGlyph *character* *directive*

 Use this directive to only process one or more directives if a character has a
 braille representation.

 *character*
    |character operand|

 *directive*
    |directive operand|

 Examples::

    ifGlyph C alias \u2103 C # degree Celsius

 The IfNotGlyph Directive
 ------------------------

 .. parsed-literal:: ifNotGlyph *character* *directive*

 Use this directive to only process one or more directives if a character
 doesn't have a braille representation.

 *character*
    |character operand|

 *directive*
    |directive operand|

 Examples::

    ifNotGlyph \s glyph \s 0

 The IfInput Directive
 ---------------------

 .. parsed-literal:: ifInput *cell* *directive*

 Use this directive to only process one or more directives if a character can be
 entered from a braille keyboard.

 *cell*
    |cell operand|

 *directive*
    |directive operand|

 The IfNotInput Directive
 ------------------------

 .. parsed-literal:: ifNotInput *cell* *directive*

 Use this directive to only process one or more directives if a character can't
 be entered from a braille keyboard.

 *cell*
    |cell operand|

 *directive*
    |directive operand|

 .. include:: nesting-directives.rst
 .. include:: variable-directives.rst
 .. include:: condition-directives.rst

 Operands
 ========

 .. include:: string-operand.rst

 The Dots Operand
 ----------------

 A *dots* operand is a sequence of one to eight dot numbers. If the dot numbers
 are enclosed within (parentheses) then they may be separated from one another
 by whitespace. 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`` is recognized
 when not enclosed within (parentheses), and means no dots - it may not be used
 in conjunction with any other dot number.

 The Cell Operand
 ----------------

 A *cell* operand is 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`` is recognized, and means no dots - it may not be used in
 conjunction with any other dot number.

 Text Table List
 ===============

 .. csv-table::
    :header-rows: 1
    :file: text-table.csv
	~~~~~~~~~~~
	Text Tables
	~~~~~~~~~~~

	.. include:: prologue.rst

	Description
	===========

	Files with names of the form ``*.ttb`` are text tables, and with names of the
	form ``*.tti`` are text subtables. They are used by BRLTTY to translate the
	characters on the screen into their corresponding 8-dot computer braille
	representations (see \|README.BrailleDots\| for details).

	Text tables can usually be found in the ``/etc/brltty/Text/`` directory (see
	\|README.Customize\| for more details). See `Text Table List`_ for a list of
	BRLTTY's text tables.

	A text table consists of a sequence of directives, one per line, which define
	how each character is to be represented in 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 of any directive, 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.

	The precedence for determining the braille representation for a character is as
	follows:

	1) If the character is within the Unicode braille Row (U+2800 through U+28FF)
	then its low-order eight bits are used as follows:

	=== ======== ===
	Hex Binary Dot
	--- -------- ---
	01 00000001 1
	02 00000010 2
	04 00000100 3
	08 00001000 4
	10 00010000 5
	20 00100000 6
	40 01000000 7
	80 10000000 8
	=== ======== ===

	2) If the character is within the Unicode private use row U+F000 through U+F0FF
	then its low-order byte is:

	A) interpreted as a single-byte character within the locAL character set
	B) translated to Unicode
	C) reprocessed

	3) An explicit representation (defined via `The Char Directive`_,
	`The Glyph Directive`_, or `The Byte Directive`_.

	4) An equivalent representation (defined via `The Alias Directive`_).

	5) The explicit representation of the Unicode base character.

	6) The explicit representation of the transliterated ASCII character.

	7) The explicit representation of the Unicode Replacement Character (U+FFFD).

	8) The explicit representation of a question mark (``?``).

	9) All eight braille dots.

	Directives
	==========

	.. \|character operand\| replace::
	The character being defined.
	See `The String Operand`_ for details.

	.. \|byte operand\| replace::
	The character being defined.
	It may be specified in any of the ways supported by `The String Operand`_
	except that the Unicode-specific forms (``\u``, ``\U``, ``\<``) may not be used.

	.. \|dots operand\| replace::
	The braille representation for the character being defined.
	See `The Dots Operand`_ for details.

	.. \|cell operand\| replace::
	The braille representation for the character being tested.
	See `The Cell Operand`_ for details.

	The Char Directive
	------------------

	.. parsed-literal:: char character dots # comment

	Use this directive to specify how a Unicode character is to be represented in
	braille. A character defined via this directive can also be entered from a
	braille keyboard. If several characters have the same braille representation
	then only one of them should be defined via this directive - the others should
	be defined via `The Glyph Directive`_ (which has the same syntax). If more than
	one character with the same braille representation is defined via this
	directive (which is allowed for backward compatibility) then the first one is
	used when entered from a braille keyboard.

	character
	\|character operand\|

	dots
	\|dots operand\|

	Examples::

	char a 1
	char b (12)
	char c ( 4 1 )
	char \\ 12567
	char \s 0
	char \x20 ()
	char \<LATIN_SMALL_LETTER_D> 145

	The Glyph Directive
	-------------------

	.. parsed-literal:: glyph character dots # comment

	Use this directive to specify how a Unicode character is to be represented in
	braille. A character defined via this directive is output-only - it can't
	be entered from a braille keyboard.

	character
	\|character operand\|

	dots
	\|dots operand\|

	See `The Char Directive`_ for examples.

	The Input Directive
	-------------------

	.. parsed-literal:: input character dots # comment

	Use this directive to specify how a Unicode character is to be entered from a
	braille keyboard. A character defined via this directive is input-only - its
	actual braille representation isn't defined.

	character
	\|character operand\|

	dots
	\|dots operand\|

	See `The Char Directive`_ for examples.

	The Alias Directive
	-------------------

	.. parsed-literal:: alias from to # comment

	Use this directive to define the from Unicode character such that it has the
	same braille representation as the to Unicode character. See
	`The String Operand`_ for details on how to specify both operands.

	The Byte Directive
	------------------

	.. parsed-literal:: byte byte dots # comment

	Use this directive to specify how a character in the local character set is to
	be represented in braille. It has been retained for backward compatibility but
	should not be used. Unicode characters should be defined (via either
	`The Char Directive`_ or `The Glyph Directive`_) so that the text table remains
	valid regardless of what the local character set is.

	byte
	\|byte operand\|

	dots
	\|dots operand\|

	The IfGlyph Directive
	---------------------

	.. parsed-literal:: ifGlyph character directive

	Use this directive to only process one or more directives if a character has a
	braille representation.

	character
	\|character operand\|

	directive
	\|directive operand\|

	Examples::

	ifGlyph C alias \u2103 C # degree Celsius

	The IfNotGlyph Directive
	------------------------

	.. parsed-literal:: ifNotGlyph character directive

	Use this directive to only process one or more directives if a character
	doesn't have a braille representation.

	character
	\|character operand\|

	directive
	\|directive operand\|

	Examples::

	ifNotGlyph \s glyph \s 0

	The IfInput Directive
	---------------------

	.. parsed-literal:: ifInput cell directive

	Use this directive to only process one or more directives if a character can be
	entered from a braille keyboard.

	cell
	\|cell operand\|

	directive
	\|directive operand\|

	The IfNotInput Directive
	------------------------

	.. parsed-literal:: ifNotInput cell directive

	Use this directive to only process one or more directives if a character can't
	be entered from a braille keyboard.

	cell
	\|cell operand\|

	directive
	\|directive operand\|

	.. include:: nesting-directives.rst
	.. include:: variable-directives.rst
	.. include:: condition-directives.rst

	Operands
	========

	.. include:: string-operand.rst

	The Dots Operand
	----------------

	A dots operand is a sequence of one to eight dot numbers. If the dot numbers
	are enclosed within (parentheses) then they may be separated from one another
	by whitespace. 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`` is recognized
	when not enclosed within (parentheses), and means no dots - it may not be used
	in conjunction with any other dot number.

	The Cell Operand
	----------------

	A cell operand is 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`` is recognized, and means no dots - it may not be used in
	conjunction with any other dot number.

	Text Table List
	===============

	.. csv-table::
	:header-rows: 1
	:file: text-table.csv