/usr/share/doc/brltty/English/BRLTTY-6.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
 <META NAME="GENERATOR" CONTENT="LinuxDoc-Tools">
 <TITLE>BRLTTY Reference Manual: Tables</TITLE>
 <LINK HREF="BRLTTY-7.html" REL=next>
 <LINK HREF="BRLTTY-5.html" REL=previous>
 <LINK HREF="BRLTTY.html#toc6" REL=contents>
</HEAD>
<BODY>
<A HREF="BRLTTY-7.html">Next</A>
<A HREF="BRLTTY-5.html">Previous</A>
<A HREF="BRLTTY.html#toc6">Contents</A>
<HR>
<H2><A NAME="tables"></A> <A NAME="s6">6.</A> <A HREF="BRLTTY.html#toc6">Tables</A></H2>



<H2><A NAME="table-text"></A> <A NAME="ss6.1">6.1</A> <A HREF="BRLTTY.html#toc6.1">Text Tables</A>
</H2>

<P>Files with names of the form <CODE>*.ttb</CODE> are text tables,
and with names of the form <CODE>*.tti</CODE> are text subtables.
They are used by BRLTTY to translate the characters on the screen
into their corresponding 8-dot computer braille representations.</P>
<P>BRLTTY is initially configured to use the
<A HREF="BRLTTY-14.html#nabcc">North American Braille Computer Code</A>
(NABCC) text table.
In addition to this default,
the following alternatives are provided:
<BR><CENTER>
<TABLE BORDER><TR><TD>
Name</TD><TD>Language</TD></TR><TR><TD>
auto</TD><TD>locale-based autoselection</TD></TR><TR><TD>
ar</TD><TD>Arabic (generic)</TD></TR><TR><TD>
as</TD><TD>Assamese</TD></TR><TR><TD>
awa</TD><TD>Awadhi</TD></TR><TR><TD>
bg</TD><TD>Bulgarian</TD></TR><TR><TD>
bh</TD><TD>Bihari</TD></TR><TR><TD>
bn</TD><TD>Bengali</TD></TR><TR><TD>
bo</TD><TD>Tibetan</TD></TR><TR><TD>
bra</TD><TD>Braj</TD></TR><TR><TD>
brf</TD><TD>Braille Ready Format</TD></TR><TR><TD>
</TD><TD>(for viewing .brf files within an editor or pager)</TD></TR><TR><TD>
cs</TD><TD>Czech</TD></TR><TR><TD>
cy</TD><TD>Welsh</TD></TR><TR><TD>
da</TD><TD>Danish</TD></TR><TR><TD>
da-1252</TD><TD>Danish (Svend Thougaard, 2002-11-18)</TD></TR><TR><TD>
da-lt</TD><TD>Danish (LogText)</TD></TR><TR><TD>
de</TD><TD>German</TD></TR><TR><TD>
dra</TD><TD>Dravidian</TD></TR><TR><TD>
el</TD><TD>Greek</TD></TR><TR><TD>
en</TD><TD>English</TD></TR><TR><TD>
en_CA</TD><TD>English (Canada)</TD></TR><TR><TD>
en_GB</TD><TD>English (United Kingdom)</TD></TR><TR><TD>
en_US</TD><TD>English (United States)</TD></TR><TR><TD>
en-nabcc</TD><TD>English (North American Braille Computer Code)</TD></TR><TR><TD>
eo</TD><TD>Esperanto</TD></TR><TR><TD>
es</TD><TD>Spanish</TD></TR><TR><TD>
et</TD><TD>Estonian</TD></TR><TR><TD>
fi</TD><TD>Finnish</TD></TR><TR><TD>
fr</TD><TD>French</TD></TR><TR><TD>
fr_CA</TD><TD>French (Canada)</TD></TR><TR><TD>
fr_FR</TD><TD>French (France)</TD></TR><TR><TD>
fr-2007</TD><TD>French (unified 2007)</TD></TR><TR><TD>
fr-cbifs</TD><TD>French (Code Braille Informatique Français Standard)</TD></TR><TR><TD>
fr-vs</TD><TD>French (VisioBraille)</TD></TR><TR><TD>
ga</TD><TD>Irish</TD></TR><TR><TD>
gd</TD><TD>Gaelic</TD></TR><TR><TD>
gon</TD><TD>Gondi</TD></TR><TR><TD>
gu</TD><TD>Gujarati</TD></TR><TR><TD>
he</TD><TD>Hebrew</TD></TR><TR><TD>
hi</TD><TD>Hindi</TD></TR><TR><TD>
hr</TD><TD>Croatian</TD></TR><TR><TD>
hu</TD><TD>Hungarian</TD></TR><TR><TD>
hy</TD><TD>Armenian</TD></TR><TR><TD>
is</TD><TD>Icelandic</TD></TR><TR><TD>
it</TD><TD>Italian</TD></TR><TR><TD>
kha</TD><TD>Khasi</TD></TR><TR><TD>
kn</TD><TD>Kannada</TD></TR><TR><TD>
kok</TD><TD>Konkani</TD></TR><TR><TD>
kru</TD><TD>Kurukh</TD></TR><TR><TD>
lt</TD><TD>Lituanian</TD></TR><TR><TD>
lv</TD><TD>Latvian</TD></TR><TR><TD>
mg</TD><TD>Malagasy</TD></TR><TR><TD>
mi</TD><TD>Maori</TD></TR><TR><TD>
ml</TD><TD>Malayalam</TD></TR><TR><TD>
mni</TD><TD>Manipuri</TD></TR><TR><TD>
mr</TD><TD>Marathi</TD></TR><TR><TD>
mt</TD><TD>Maltese</TD></TR><TR><TD>
mun</TD><TD>Munda</TD></TR><TR><TD>
mwr</TD><TD>Marwari</TD></TR><TR><TD>
ne</TD><TD>Nepali</TD></TR><TR><TD>
new</TD><TD>Newari</TD></TR><TR><TD>
nl</TD><TD>Dutch</TD></TR><TR><TD>
nl_BE</TD><TD>Dutch (Belgium)</TD></TR><TR><TD>
nl_NL</TD><TD>Dutch (Netherlands)</TD></TR><TR><TD>
no</TD><TD>Norwegian</TD></TR><TR><TD>
no-generic</TD><TD>Norwegian (with support for other languages)</TD></TR><TR><TD>
no-oub</TD><TD>Norwegian (Offentlig Utvalg for Blindeskrift)</TD></TR><TR><TD>
nwc</TD><TD>Newari (old)</TD></TR><TR><TD>
or</TD><TD>Oriya</TD></TR><TR><TD>
pa</TD><TD>Panjabi</TD></TR><TR><TD>
pi</TD><TD>Pali</TD></TR><TR><TD>
pl</TD><TD>Polish</TD></TR><TR><TD>
pt</TD><TD>Portuguese</TD></TR><TR><TD>
ro</TD><TD>Romanian</TD></TR><TR><TD>
ru</TD><TD>Russian</TD></TR><TR><TD>
sa</TD><TD>Sanskrit</TD></TR><TR><TD>
sat</TD><TD>Santali</TD></TR><TR><TD>
sd</TD><TD>Sindhi</TD></TR><TR><TD>
sk</TD><TD>Slovak</TD></TR><TR><TD>
sl</TD><TD>Slovenian</TD></TR><TR><TD>
sv</TD><TD>Swedish</TD></TR><TR><TD>
sv-1989</TD><TD>Swedish (1989 standard)</TD></TR><TR><TD>
sv-1996</TD><TD>Swedish (1996 standard)</TD></TR><TR><TD>
sw</TD><TD>Swahili</TD></TR><TR><TD>
ta</TD><TD>Tamil</TD></TR><TR><TD>
te</TD><TD>Telugu</TD></TR><TR><TD>
tr</TD><TD>Turkish</TD></TR><TR><TD>
vi</TD><TD>Vietnamese</TD></TR><TR><TD>
</TD></TR></TABLE>
</CENTER><BR>

See the 
<A HREF="BRLTTY-4.html#options-text-table">-t</A> command line option,
the 
<A HREF="BRLTTY-4.html#configure-text-table">text-table</A> configuration file directive,
and the 
<A HREF="BRLTTY-3.html#build-text-table">--with-text-table</A> build option
for details regarding how to use an alternate text table.</P>

<H3>Text Table Format</H3>

<P>A text table consists of a sequence of directives, one per line,
which define how each character is to be represented in braille.
<CODE>UTF-8</CODE> character encoding must be used.
White-space (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 white-space are ignored.
If the first non-white-space character of a line is "#"
then that line is a comment and is ignored.</P>

<H3>Text Table Directives</H3>

<P>The following directives are provided:
<DL>
<DT><B><CODE>char</CODE> <EM>character</EM> <EM>dots</EM> # <EM>comment</EM></B><DD>
<P>Use the <CODE>char</CODE> directive to specify
how a Unicode character is to be represented in braille.
Characters defined with 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 with the <CODE>char</CODE> directive -
the others should be defined with the <CODE>glyph</CODE> directive
(which has the same syntax).
If more than one character with the same braille representation
is defined with the <CODE>char</CODE> directive
(which is currently allowed for backward compatibility)
then the first one is selected.</P>
<P>
<DL>
<DT><B><EM>character</EM></B><DD>
<P>The Unicode character being defined.
It may be:
<UL>
<LI>Any single character other than a backslash or a white-space character.</LI>
<LI>A backslash-prefixed special character.
These are:
<DL>
<P>- </P>
<DT><B>\b</B><DD>
<P>The backspace character.
- </P>
<DT><B>\f</B><DD>
<P>The formfeed character.
- </P>
<DT><B>\n</B><DD>
<P>The newline character.
- </P>
<DT><B>\o###</B><DD>
<P>The three-digit octal representation of a character.
- </P>
<DT><B>\r</B><DD>
<P>The carriage return character.
- </P>
<DT><B>\s</B><DD>
<P>The space character.
- </P>
<DT><B>\t</B><DD>
<P>The horizontal tab character.
- </P>
<DT><B>\u####</B><DD>
<P>The four-digit hexadecimal representation of a character.
- </P>
<DT><B>\U########</B><DD>
<P>The eight-digit hexadecimal representation of a character.
- </P>
<DT><B>\v</B><DD>
<P>The vertical tab character.
- </P>
<DT><B>\x##</B><DD>
<P>The two-digit hexadecimal representation of a character.
- </P>
<DT><B>\X##</B><DD>
<P>... (the case of the X and of the digits isn't significant)
- </P>
<DT><B>\#</B><DD>
<P>A literal number sign.
- </P>
<DT><B>\&lt;name&gt;</B><DD>
<P>The Unicode name of a character (use _ for space).
- </P>
<DT><B>\\</B><DD>
<P>A literal backslash.</P>
</DL>
</LI>
</UL>
</P>
<DT><B><EM>dots</EM></B><DD>
<P>The braille representation of the Unicode character.
It is a sequence of one to eight dot numbers.
If the dot number sequence is enclosed within parentheses
then the dot numbers may be separated from one another by white-space.
A dot number is a digit within the range <CODE>1</CODE>-<CODE>8</CODE> as defined by the
<A HREF="BRLTTY-13.html#dots">Standard Braille Dot Numbering Convention</A>.
The special dot number <CODE>0</CODE> is recognized
when not enclosed within parentheses,
and means no dots;
it may not be used in conjunction with any other dot number.</P>
</DL>
</P>
<P>Examples:
<UL>
<LI><CODE>char a 1</CODE></LI>
<LI><CODE>char b (12)</CODE></LI>
<LI><CODE>char c ( 4  1   )</CODE></LI>
<LI><CODE>char \\ 12567</CODE></LI>
<LI><CODE>char \s 0</CODE></LI>
<LI><CODE>char \x20 ()</CODE></LI>
<LI><CODE>char \&lt;LATIN_SMALL_LETTER_D&gt; 145</CODE></LI>
</UL>
</P>
<DT><B><CODE>glyph</CODE> <EM>character</EM> <EM>dots</EM> # <EM>comment</EM></B><DD>
<P>Use the <CODE>glyph</CODE> directive to specify
how a Unicode character is to be represented in braille.
Characters defined with this directive are output-only. 
They cannot be entered from a braille keyboard.</P>
<P>See the <CODE>char</CODE> directive for syntax details and for examples.</P>
<DT><B><CODE>byte</CODE> <EM>byte</EM> <EM>dots</EM> # <EM>comment</EM></B><DD>
<P>Use the <CODE>byte</CODE> 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 the <CODE>char</CODE> directive)
so that the text table remains valid
regardless of what the local character set is.</P>
<P>
<DL>
<DT><B><EM>byte</EM></B><DD>
<P>The local character being defined.
It may be specified in the same ways
as the <EM>character</EM> operand of the <CODE>char</CODE> directive 
except that the Unicode-specific forms
(\u, \U, \&lt;)
may not be used.</P>
<DT><B><EM>dots</EM></B><DD>
<P>The braille representation of the local character.
It may be specified in the same ways
as the <EM>dots</EM> operand of the <CODE>char</CODE> directive.</P>
</DL>
</P>
<DT><B><CODE>include</CODE> <EM>file</EM> # <EM>comment</EM></B><DD>
<P>Use the <CODE>include</CODE> directive to include the content of a text subtable.
It is recursive, which means that
any text subtable can itself include yet another text subtable.
Care must be taken to ensure that an "include loop" is not created.</P>
<P>
<DL>
<DT><B><EM>file</EM></B><DD>
<P>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.</P>
</DL>
</P>
</DL>
</P>

<H2><A NAME="table-attributes"></A> <A NAME="ss6.2">6.2</A> <A HREF="BRLTTY.html#toc6.2">Attributes Tables</A>
</H2>

<P>Files with names of the form *.atb are attributes tables,
and with names of the form *.ati are attributes subtables.
They are used when BRLTTY
is displaying screen attributes rather than screen content
(see the 
<A HREF="BRLTTY-4.html#command-DISPMD">DISPMD</A> command).
Each of the eight braille dots represents
one of the eight <CODE>VGA</CODE> attribute bits.</P>
<P>The following attributes tables are provided:
<DL>
<DT><B>left_right</B><DD>
<P>The lefthand column represents the foreground colours:
<DL>
<DT><B>Dot 1</B><DD>
<P>Blue</P>
<DT><B>Dot 2</B><DD>
<P>Green</P>
<DT><B>Dot 3</B><DD>
<P>Red</P>
<DT><B>Dot 7</B><DD>
<P>Bright</P>
</DL>

The righthand column represents the background colours:
<DL>
<DT><B>Dot 4</B><DD>
<P>Blue</P>
<DT><B>Dot 5</B><DD>
<P>Green</P>
<DT><B>Dot 6</B><DD>
<P>Red</P>
<DT><B>Dot 8</B><DD>
<P>Blink</P>
</DL>

A dot is raised when its corresponding attribute bit is on.
This is the default attributes table
because it's the most intuitive.
One of its problems, though, is that it's difficult to discern
the difference between normal (white on black)
and reverse (black on white) video.</P>
<DT><B>invleft_right</B><DD>
<P>The lefthand column represents the foreground colours:
<DL>
<DT><B>Dot 1</B><DD>
<P>Blue</P>
<DT><B>Dot 2</B><DD>
<P>Green</P>
<DT><B>Dot 3</B><DD>
<P>Red</P>
<DT><B>Dot 7</B><DD>
<P>Bright</P>
</DL>

The righthand column represents the background colours:
<DL>
<DT><B>Dot 4</B><DD>
<P>Blue</P>
<DT><B>Dot 5</B><DD>
<P>Green</P>
<DT><B>Dot 6</B><DD>
<P>Red</P>
<DT><B>Dot 8</B><DD>
<P>Blink</P>
</DL>

A background bit being on triggers its corresponding dot,
whereas a foreground bit being off triggers its corresponding dot.
This unintuitive logic actually makes it easier
to read the most commonly used attribute combinations.</P>
<DT><B>upper_lower</B><DD>
<P>The upper square represents the foreground colours:
<DL>
<DT><B>Dot 1</B><DD>
<P>Red</P>
<DT><B>Dot 4</B><DD>
<P>Green</P>
<DT><B>Dot 2</B><DD>
<P>Blue</P>
<DT><B>Dot 5</B><DD>
<P>Bright</P>
</DL>

The lower square represents the background colours:
<DL>
<DT><B>Dot 3</B><DD>
<P>Red</P>
<DT><B>Dot 6</B><DD>
<P>Green</P>
<DT><B>Dot 7</B><DD>
<P>Blue</P>
<DT><B>Dot 8</B><DD>
<P>Blink</P>
</DL>

A dot is raised when its corresponding attribute bit is on.</P>
</DL>

See the 
<A HREF="BRLTTY-4.html#options-attributes-table">-a</A> command line option,
the 
<A HREF="BRLTTY-4.html#configure-attributes-table">attributes-table</A> configuration file directive,
and the 
<A HREF="BRLTTY-3.html#build-attributes-table">--with-attributes-table</A> build option
for details regarding how to use an alternate attributes table.</P>

<H3>Attributes Table Format</H3>

<P>An attributes table consists of a sequence of directives, one per line,
which define how combinations of <CODE>VGA</CODE> attributes
are to be represented in braille. 
<CODE>UTF-8</CODE> character encoding must be used.
White-space (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 white-space are ignored.
If the first non-white-space character of a line is "#"
then that line is a comment and is ignored.</P>

<H3>Attributes Table Directives</H3>

<P>The following directives are provided:
<DL>
<DT><B><CODE>dot</CODE> <EM>dot</EM> <EM>state</EM> # <EM>comment</EM></B><DD>
<P>Use the <CODE>dot</CODE> directive to specify
what a specific dot represents.</P>
<P>
<DL>
<DT><B><EM>dot</EM></B><DD>
<P>The dot being defined.
It is a single digit within the range <CODE>1</CODE>-<CODE>8</CODE> as defined by the
<A HREF="BRLTTY-13.html#dots">Standard Braille Dot Numbering Convention</A>.</P>
<DT><B><EM>state</EM></B><DD>
<P>What the dot represents.
It may be:
<DL>
<DT><B><CODE>=</CODE><EM>attribute</EM></B><DD>
<P>The dot is raised if the named attribute is on.</P>
<DT><B><CODE>~</CODE><EM>attribute</EM></B><DD>
<P>The dot is raised if the named attribute is off.</P>
</DL>
</P>
<P>The names of the attribute bits are:
<DL>
<DT><B>0X01</B><DD>
<P><CODE>fg-blue</CODE></P>
<DT><B>0X02</B><DD>
<P><CODE>fg-green</CODE></P>
<DT><B>0X04</B><DD>
<P><CODE>fg-red</CODE></P>
<DT><B>0X08</B><DD>
<P><CODE>fg-bright</CODE></P>
<DT><B>0X10</B><DD>
<P><CODE>bg-blue</CODE></P>
<DT><B>0X20</B><DD>
<P><CODE>bg-green</CODE></P>
<DT><B>0X40</B><DD>
<P><CODE>bg-red</CODE></P>
<DT><B>0X80</B><DD>
<P><CODE>blink</CODE></P>
</DL>
</P>
</DL>
</P>
<P>Examples:
<UL>
<LI><CODE>dot 1 =fg-red</CODE></LI>
<LI><CODE>dot 2 ~bg-blue</CODE></LI>
</UL>
</P>
<DT><B><CODE>include</CODE> <EM>file</EM> # <EM>comment</EM></B><DD>
<P>Use the <CODE>include</CODE> directive to include the content of an attributes subtable.
It is recursive, which means that
any attributes subtable can itself include yet another attributes subtable.
Care must be taken to ensure that an "include loop" is not created.</P>
<P>
<DL>
<DT><B><EM>file</EM></B><DD>
<P>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.</P>
</DL>
</P>
</DL>
</P>

<H2><A NAME="table-contraction"></A> <A NAME="ss6.3">6.3</A> <A HREF="BRLTTY.html#toc6.3">Contraction Tables</A>
</H2>

<P>Files with names of the form <CODE>*.ctb</CODE> are contraction tables,
and with names of the form <CODE>*.cti</CODE> are contraction subtables.
They are used by BRLTTY to translate character sequences on the screen
into their corresponding contracted braille representations.</P>
<P>BRLTTY presents contracted braille if:
<UL>
<LI>A contraction table has been selected.
See the 
<A HREF="BRLTTY-4.html#options-contraction-table">-c</A> command line option
and the 
<A HREF="BRLTTY-4.html#configure-contraction-table">contraction-table</A> configuration file directive
for details.</LI>
<LI>The 6-dot braille feature has been activated.
See the 
<A HREF="BRLTTY-4.html#command-SIXDOTS">SIXDOTS</A> command
and the 
<A HREF="BRLTTY-5.html#preference-text-style">Text Style</A> preference
for details.</LI>
</UL>

This feature isn't available if the
<A HREF="BRLTTY-3.html#build-contracted-braille">--disable-contracted-braille</A> build option was specified.</P>
<P>The following contraction tables are provided:
<BR><CENTER>
<TABLE BORDER><TR><TD>
Name</TD><TD>Language</TD></TR><TR><TD>
af</TD><TD>Afrikaans (contracted)</TD></TR><TR><TD>
am</TD><TD>Amharic (uncontracted)</TD></TR><TR><TD>
de-basis</TD><TD>German (uncontracted)</TD></TR><TR><TD>
de-kurzschrift</TD><TD>German (contracted - 1998 standard)</TD></TR><TR><TD>
de-vollschrift</TD><TD>German (basic contractions)</TD></TR><TR><TD>
en-ueb-g2</TD><TD>English (Unified English Braille, grade 2)</TD></TR><TR><TD>
en-us-g2</TD><TD>English (US, grade 2)</TD></TR><TR><TD>
es</TD><TD>Spanish (grade 2)</TD></TR><TR><TD>
fr-abrege</TD><TD>French (contracted)</TD></TR><TR><TD>
fr-integral</TD><TD>French (uncontracted)</TD></TR><TR><TD>
ha</TD><TD>Hausa (contracted)</TD></TR><TR><TD>
id</TD><TD>Indonesian (contracted)</TD></TR><TR><TD>
ja</TD><TD>Japanese (uncontracted)</TD></TR><TR><TD>
ko-g1</TD><TD>Korean (grade 1)</TD></TR><TR><TD>
ko-g2</TD><TD>Korean (grade 2)</TD></TR><TR><TD>
ko</TD><TD>Korean (uncontracted)</TD></TR><TR><TD>
mg</TD><TD>Malagasy (contracted)</TD></TR><TR><TD>
mun</TD><TD>Munda (contracted)</TD></TR><TR><TD>
nl</TD><TD>Dutch (contracted)</TD></TR><TR><TD>
ny</TD><TD>Chichewa (contracted)</TD></TR><TR><TD>
ipa</TD><TD>International Phonetic Alphabet</TD></TR><TR><TD>
pt</TD><TD>Portuguese (grade 2)</TD></TR><TR><TD>
si</TD><TD>Sinhalese (uncontracted)</TD></TR><TR><TD>
sw</TD><TD>Swahili (contracted)</TD></TR><TR><TD>
th</TD><TD>Thai (contracted)</TD></TR><TR><TD>
zh-tw</TD><TD>Chinese (Taiwan, uncontracted)</TD></TR><TR><TD>
zh-tw-ucb</TD><TD>Chinese (Taiwan, Unique Chinese Braille)</TD></TR><TR><TD>
zu</TD><TD>Zulu (contracted)</TD></TR><TR><TD>
</TD></TR></TABLE>
</CENTER><BR>

See the 
<A HREF="BRLTTY-4.html#options-contraction-table">-c</A> command line option,
and the 
<A HREF="BRLTTY-4.html#configure-contraction-table">contraction-table</A> configuration file directive
for details regarding how to use a contraction table.</P>

<H3>Contraction Table Format</H3>

<P>A contraction table consists of a sequence of entries, one per line,
which define how character sequences are to be represented in braille.
<CODE>UTF-8</CODE> character encoding must be used.
White-space (blanks, tabs) at the beginning of a line,
as well as before and/or after any operand,
is ignored.
Lines containing only white-space are ignored.
If the first non-white-space character of a line is "#"
then that line is a comment and is ignored.</P>
<P>The format of a contraction table entry is:
<BLOCKQUOTE><CODE>
<EM>directive</EM> <EM>operand</EM> ... [<EM>comment</EM>]
</CODE></BLOCKQUOTE>

Each directive has a specific number of operands.
Any text beyond the last operand of a directive is interpreted as a comment.
The order of the entries within a contraction table is, in general,
anything that is convenient for its maintainer(s).
An entry which defines an entity, e.g. <CODE>class</CODE>,
must precede all references to that entity.</P>
<P>Entries which match character sequences
are automatically rearranged from longest to shortest
so that longer matches are always preferred.
If more than one entry matches the same character sequence
then their original table ordering is maintained.
Thus, the same sequence may be translated differently under different circumstances.</P>

<H3>Contraction Table Operands</H3>

<P>
<DL>
<DT><B><EM>characters</EM></B><DD>
<P>The first operand of a character sequence matching directive
is the character sequence to be matched.
Each character within the sequence may be:
<UL>
<LI>Any single character other than a backslash or a white-space character.</LI>
<LI>A backslash-prefixed special character.
These are:
<DL>
<P>- </P>
<DT><B>\b</B><DD>
<P>The backspace character.
- </P>
<DT><B>\f</B><DD>
<P>The formfeed character.
- </P>
<DT><B>\n</B><DD>
<P>The newline character.
- </P>
<DT><B>\o###</B><DD>
<P>The three-digit octal representation of a character.
- </P>
<DT><B>\r</B><DD>
<P>The carriage return character.
- </P>
<DT><B>\s</B><DD>
<P>The space character.
- </P>
<DT><B>\t</B><DD>
<P>The horizontal tab character.
- </P>
<DT><B>\u####</B><DD>
<P>The four-digit hexadecimal representation of a character.
- </P>
<DT><B>\U########</B><DD>
<P>The eight-digit hexadecimal representation of a character.
- </P>
<DT><B>\v</B><DD>
<P>The vertical tab character.
- </P>
<DT><B>\x##</B><DD>
<P>The two-digit hexadecimal representation of a character.
- </P>
<DT><B>\X##</B><DD>
<P>... (the case of the X and of the digits isn't significant)
- </P>
<DT><B>\#</B><DD>
<P>A literal number sign.
- </P>
<DT><B>\&lt;name&gt;</B><DD>
<P>The Unicode name of a character (use _ for space).
- </P>
<DT><B>\\</B><DD>
<P>A literal backslash.</P>
</DL>
</LI>
</UL>
</P>
<DT><B><EM>representation</EM></B><DD>
<P>The second operand of those character sequence matching directives which have one
is the braille representation of the sequence.
Each braille cell is specified as a sequence of one to eight dot numbers.
A dot number is a digit within the range <CODE>1</CODE>-<CODE>8</CODE> as defined by the
<A HREF="BRLTTY-13.html#dots">Standard Braille Dot Numbering Convention</A>.
The special dot number <CODE>0</CODE>,
which may not be used in conjunction with any other dot number,
means no dots.</P>
</DL>
</P>

<H3><A NAME="contraction-opcodes"></A> Opcodes</H3>

<P>An opcode is a keyword which tells the translator how to interpret the operands.
The opcodes are grouped here by function.</P>

<H3><A NAME="contraction-opcodes-administration"></A> Table Administration</H3>

<P>These opcodes make it easier to write contraction tables.
They have no direct effect on the character translation.
<DL>
<DT><B><CODE>include</CODE> <EM>path</EM>
<A NAME="contraction-opcode-include"></A> </B><DD>
<P>Include the contents of another file.
Nesting can be to any depth.
Relative paths are anchored at the directory of the including file.</P>
<DT><B><CODE>locale</CODE> <EM>locale</EM>
<A NAME="contraction-opcode-locale"></A> </B><DD>
<P>Define the locale for character interpretation
(lowercase, uppercase, numeric, etc.).
The locale may be specified as:
<DL>
<DT><B><EM>language</EM>[<CODE>_</CODE><EM>country</EM>][<CODE>.</CODE><EM>charset</EM>][<CODE>@</CODE><EM>modifier</EM>]</B><DD>
<P>The <EM>language</EM> component is required and should be a two-letter <CODE>ISO-639</CODE> language code.
The <EM>country</EM> component is optional and should be a two-letter <CODE>ISO-3166</CODE> country code.
The <EM>charset</EM> component is optional and should be a character set name, e.g. <CODE>ISO-8859-1</CODE>.</P>
<DT><B>C</B><DD>
<P>7-bit ASCII.</P>
<DT><B>-</B><DD>
<P>No locale.</P>
</DL>

The last locale specification applies to the entire table.
If this opcode isn't used then the <CODE>C</CODE> locale is assumed.</P>
</DL>
</P>

<H3><A NAME="contraction-opcodes-symbols"></A> Special Symbol Definition</H3>

<P>These opcodes define special symbols which must be
inserted into the braille text in order to clarify it.
<DL>
<DT><B><CODE>capsign</CODE> <EM>dots</EM>
<A NAME="contraction-opcode-capsign"></A> </B><DD>
<P>The symbol which capitalizes a single letter.</P>
<DT><B><CODE>begcaps</CODE> <EM>dots</EM>
<A NAME="contraction-opcode-begcaps"></A> </B><DD>
<P>The symbol which begins a block of capital letters within a word.</P>
<DT><B><CODE>endcaps</CODE> <EM>dots</EM>
<A NAME="contraction-opcode-endcaps"></A> </B><DD>
<P>The symbol which ends a block of capital letters within a word.</P>
<DT><B><CODE>letsign</CODE> <EM>dots</EM>
<A NAME="contraction-opcode-letsign"></A> </B><DD>
<P>The symbol which marks a letter which isn't part of a word.</P>
<DT><B><CODE>numsign</CODE> <EM>dots</EM>
<A NAME="contraction-opcode-numsign"></A> </B><DD>
<P>The symbol which marks the beginning of a number.</P>
</DL>
</P>

<H3><A NAME="contraction-opcodes-translation"></A> Character Translation</H3>

<P>These opcodes define the braille representations for character sequences.
Each of them defines an entry within the contraction table.
These entries may be defined in any order except, as noted below,
when they define alternate representations for the same character sequence.</P>
<P>Each of these opcodes has
a <EM>characters</EM> operand (which must be specified as a <EM>string</EM>),
and a built-in condition governing its eligibility for use.
The text is processed strictly from left to right, character by character,
with the most eligible entry for each position being used.
If there's more than one eligible entry for a given position,
then the one with the longest character string is used.
If there's more than one eligible entry for the same character string,
then the one defined nearest to the beginning of the table is used
(this is the only order dependency).</P>
<P>Many of these opcodes have a <EM>dots</EM> operand
which defines the braille representation for its <EM>characters</EM> operand.
It may also be specified as an equals sign (<CODE>=</CODE>),
in which case it means one of two things.
If the entry is for a single character,
then it means that the currently selected computer braille representation
(see the 
<A HREF="BRLTTY-4.html#options-text-table">-t</A> command line option
and the 
<A HREF="BRLTTY-4.html#configure-text-table">text-table</A> configuration file directive)
for that character is to be used.
If it's for a multi-character sequence,
then the default representation for each character
(see 
<A HREF="#contraction-opcode-always">always</A>)
within the sequence is to be used.</P>
<P>Some special terms are used within the descriptions of these opcodes.
<DL>
<DT><B>word</B><DD>
<P>A maximal sequence of one or more consecutive letters.</P>
</DL>
</P>
<P>Now, finally, here are the opcode descriptions themselves:
<DL>
<DT><B><CODE>literal</CODE> <EM>characters</EM>
<A NAME="contraction-opcode-literal"></A> </B><DD>
<P>Translate the entire white-space-bounded containing character sequence into computer braille
(see the 
<A HREF="BRLTTY-4.html#options-text-table">-t</A> command line option
and the 
<A HREF="BRLTTY-4.html#configure-text-table">text-table</A> configuration file directive).</P>
<DT><B><CODE>replace</CODE> <EM>characters</EM> <EM>characters</EM>
<A NAME="contraction-opcode-replace"></A> </B><DD>
<P>Replace the first set of characters, no matter where they appear, with the second.
The replaced characters aren't reprocessed.</P>
<DT><B><CODE>always</CODE> <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-always"></A> </B><DD>
<P>Translate the characters no matter where they appear.
If there's only one character, then, in addition,
define the default representation for that character.</P>
<DT><B><CODE>repeatable</CODE> <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-repeatable"></A> </B><DD>
<P>Translate the characters no matter where they appear.
Ignore any consecutive repetitions of the same sequence.</P>
<DT><B><CODE>largesign</CODE> <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-largesign"></A> </B><DD>
<P>Translate the characters no matter where they appear.
Remove white-space between consecutive words matched by this opcode.</P>
<DT><B><CODE>lastlargesign</CODE> <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-lastlargesign"></A> </B><DD>
<P>Translate the characters no matter where they appear.
Remove preceding white-space if the previous word was matched by the
<A HREF="#contraction-opcode-largesign">largesign</A> opcode.</P>
<DT><B><CODE>word</CODE> <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-word"></A> </B><DD>
<P>Translate the characters if they're a word.</P>
<DT><B><CODE>joinword</CODE> <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-joinword"></A> </B><DD>
<P>Translate the characters if they're a word.
Remove the following white-space if the first character after it is a letter.</P>
<DT><B><CODE>lowword</CODE> <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-lowword"></A> </B><DD>
<P>Translate the characters if they're a white-space-bounded word.</P>
<DT><B><CODE>contraction</CODE> <EM>characters</EM>
<A NAME="contraction-opcode-contraction"></A> </B><DD>
<P>Prefix the characters with a letter sign
(see 
<A HREF="#contraction-opcode-letsign">letsign</A>)
if they're a word.</P>
<DT><B><CODE>sufword</CODE> <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-sufword"></A> </B><DD>
<P>Translate the characters if they're either a word or at the beginning of a word.</P>
<DT><B><CODE>prfword</CODE> <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-prfword"></A> </B><DD>
<P>Translate the characters if they're either a word or at the end of a word.</P>
<DT><B><CODE>begword</CODE> <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-begword"></A> </B><DD>
<P>Translate the characters if they're at the beginning of a word.</P>
<DT><B><CODE>begmidword</CODE> <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-begmidword"></A> </B><DD>
<P>Translate the characters if they're either at the beginning or in the middle of a word.</P>
<DT><B><CODE>midword</CODE> <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-midword"></A> </B><DD>
<P>Translate the characters if they're in the middle of a word.</P>
<DT><B><CODE>midendword</CODE> <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-midendword"></A> </B><DD>
<P>Translate the characters if they're either in the middle or at the end of a word.</P>
<DT><B><CODE>endword</CODE> <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-endword"></A> </B><DD>
<P>Translate the characters if they're at the end of a word.</P>
<DT><B><CODE>prepunc</CODE> <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-prepunc"></A> </B><DD>
<P>Translate the characters if they're part of punctuation at the beginning of a word.</P>
<DT><B><CODE>postpunc</CODE> <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-postpunc"></A> </B><DD>
<P>Translate the characters if they're part of punctuation at the end of a word.</P>
<DT><B><CODE>begnum</CODE> <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-begnum"></A> </B><DD>
<P>Translate the characters if they're at the beginning of a number.</P>
<DT><B><CODE>midnum</CODE> <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-midnum"></A> </B><DD>
<P>Translate the characters if they're in the middle of a number.</P>
<DT><B><CODE>endnum</CODE> <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-endnum"></A> </B><DD>
<P>Translate the characters if they're at the end of a number.</P>
</DL>
</P>

<H3><A NAME="contraction-opcodes-classes"></A> Character Classes</H3>

<P>These opcodes define and use character classes.
A character class associates a set of characters with a name.
The name then refers to any character within the class.
A character may belong to more than one class.</P>
<P>The following character classes are automatically predefined
based on the selected locale:
<DL>
<DT><B>digit</B><DD>
<P>Numeric characters.</P>
<DT><B>letter</B><DD>
<P>Both uppercase and lowercase alphabetic characters.
Some locales have additional letters which are neither uppercase nor lowercase.</P>
<DT><B>lowercase</B><DD>
<P>Lowercase alphabetic characters.</P>
<DT><B>punctuation</B><DD>
<P>Printable characters which are neither white-space nor alphanumeric.</P>
<DT><B>space</B><DD>
<P>White-space characters.
In the default locale these are:
space, horizontal tab, vertical tab, carriage return, new line, form feed.</P>
<DT><B>uppercase</B><DD>
<P>Uppercase alphabetic characters.</P>
</DL>
</P>
<P>The opcodes which define and use character classes are:
<DL>
<DT><B><CODE>class</CODE> <EM>name</EM> <EM>characters</EM>
<A NAME="contraction-opcode-class"></A> </B><DD>
<P>Define a new character class.
The <EM>characters</EM> operand must be specified as a <EM>string</EM>.
A character class may not be used until it's been defined.</P>
<DT><B><CODE>after</CODE> <EM>class</EM> <EM>opcode</EM> ...
<A NAME="contraction-opcode-after"></A> </B><DD>
<P>The specified opcode is further constrained in that
the matched character sequence must be immediately preceded by
a character belonging to the specified class.
If this opcode is used more than once on the same line
then the union of the characters in all the classes is used.</P>
<DT><B><CODE>before</CODE> <EM>class</EM> <EM>opcode</EM> ...
<A NAME="contraction-opcode-before"></A> </B><DD>
<P>The specified opcode is further constrained in that
the matched character sequence must be immediately followed by
a character belonging to the specified class.
If this opcode is used more than once on the same line
then the union of the characters in all the classes is used.</P>
</DL>
</P>

<H2><A NAME="table-key"></A> <A NAME="ss6.4">6.4</A> <A HREF="BRLTTY.html#toc6.4">Key Tables</A>
</H2>

<P>Files with names of the form <CODE>*.ktb</CODE> are key tables,
and with names of the form <CODE>*.kti</CODE> are key subtables.
They are used by BRLTTY to bind
braille display and keyboard key combinations
to BRLTTY commands.</P>
<P>The names of braille display key table files begin with <CODE>brl-</CODE><EM>xx</EM><CODE>-</CODE>",
where <EM>xx</EM> is the two-letter
<A HREF="BRLTTY-10.html#drivers">driver identification code</A>.
The rest of the name identifies the model(s)
for which the key table is used.</P>
<P>The names of keyboard key table files begin with <CODE>kbd-</CODE>.
The rest of the name describes the kind of keyboard
for which the key table has been designed.</P>
<P>The following keyboard key tables are provided:
<DL>
<DT><B>braille</B><DD>
<P>bindings for braille keyboards</P>
<DT><B>desktop</B><DD>
<P>bindings for full keyboards</P>
<DT><B>keypad</B><DD>
<P>bindings for keypad-based navigation</P>
<DT><B>laptop</B><DD>
<P>bindings for keyboards without a keypad</P>
<DT><B>sun_type6</B><DD>
<P>bindings for Sun Type 6 keyboards</P>
</DL>

See the 
<A HREF="BRLTTY-4.html#options-key-table">-k</A> command line option,
and the 
<A HREF="BRLTTY-4.html#configure-key-table">key-table</A> configuration file directive
for details regarding how to select a keyboard key table.</P>

<H3>Key Table Directives</H3>

<P>A key table consists of a sequence of directives, one per line,
which define how keys and key combinations are to be interpreted.
<CODE>UTF-8</CODE> character encoding must be used.
White-space (blanks, tabs) at the beginning of a line,
as well as before and/or after any operand,
is ignored.
Lines containing only white-space are ignored.
If the first non-white-space character of a line is a number (<CODE>#</CODE>) sign
then that line is a comment and is ignored.</P>
<P>The precedence for resolving each key press/release event is as follows:
<OL>
<LI>A hotkey press or release defined within the current context.
See the
<A HREF="#key-table-hotkey">hotkey</A>
directive for details.</LI>
<LI>A key combination defined within the current context.
See the
<A HREF="#key-table-bind">bind</A>
directive for details.</LI>
<LI>A braille keyboard command defined within the current context.
See the
<A HREF="#key-table-map">map</A>
and
<A HREF="#key-table-superimpose">superimpose</A>
directives for details.</LI>
<LI>A key combination defined within the default context.
See the
<A HREF="#key-table-bind">bind</A>
directive for details.</LI>
</OL>
</P>
<P>The following directives are provided:</P>

<H3><A NAME="key-table-assign"></A> The Assign Directive</H3>

<P>Create or update a variable associated with the current include level.
The variable is visible to the current and to lower include levels,
but not to higher include levels.</P>
<P><CODE>assign</CODE> <EM>variable</EM> [<EM>value</EM>]
<DL>
<DT><B><EM>variable</EM></B><DD>
<P>The name of the variable.
If the variable doesn't already exist at the current include level
then it is created.</P>
<DT><B><EM>value</EM></B><DD>
<P>The value which is to be assigned to the variable.
If it's not supplied then a zero-length (null) value is assigned.</P>
</DL>
</P>
<P>The escape sequence \{variable} is substituted
with the value of the variable named within the braces.
The variable must have been defined
at the current or at a higher include level.</P>
<P>Examples:
<UL>
<LI><CODE>assign nullValue</CODE></LI>
<LI><CODE>assign ReturnKey Key1</CODE></LI>
<LI><CODE>bind \{ReturnKey} RETURN</CODE></LI>
</UL>
</P>

<H3><A NAME="key-table-bind"></A> The Bind Directive</H3>

<P>Define which BRLTTY command is executed
when a particular combination of one or more keys is pressed.
The binding is defined within the current context.</P>
<P><CODE>bind</CODE> <EM>keys</EM> <EM>command</EM>
<DL>
<DT><B><EM>keys</EM></B><DD>
<P>The key combination which is to be bound.
It's a sequence of one or more key names
separated by plus (<CODE>+</CODE>) signs.
The final (or only) key name may be optionally prefixed
with an exclamation (<CODE>!</CODE>) point.
The keys may be pressed in any order, with the exception that
if the final key name is prefixed with an exclamation point
then it must be pressed last.
The exclamation point prefix means that
the command is executed as soon as that key is pressed.
If not used,
the command is executed as soon as any of the keys is released.</P>
<DT><B><EM>command</EM></B><DD>
<P>The name of a BRLTTY command.
One or more modifiers may be optionally appended to the command name
by using a plus (<CODE>+</CODE>) sign as the separator.
<UL>
<LI>For commands which enable/disable a feature:
<UL>
<LI>If the modifier <CODE>+on</CODE> is specified
then the feature is enabled.</LI>
<LI>If the modifier <CODE>+off</CODE> is specified
then the feature is disabled.</LI>
<LI>If neither <CODE>+on</CODE> nor <CODE>+off</CODE> is specified
then the state of the feature is toggled on/off.</LI>
</UL>
</LI>
<LI>For commands which move the braille window:
<UL>
<LI>If the modifier <CODE>+route</CODE> is specified
then, if necessary, the cursor is automatically routed
so that it's always visible on the braille display.</LI>
</UL>
</LI>
<LI>For commands which move the braille window to a specific line on the screen:
<UL>
<LI>If the modifier <CODE>+toleft</CODE> is specified
then the braille window is also moved
to the beginning of that line.</LI>
<LI>If the modifier <CODE>+scaled</CODE> is specified
then the set of keys bound to the command
is interpreted as though it were a scroll bar.
If it isn't,
then there's a one-to-one correspondence
between keys and lines.</LI>
</UL>
</LI>
<LI>For commands which require an offset:
<UL>
<LI>The modifier +<EM>offset</EM>,
where <EM>offset</EM> is a non-negative integer,
may be specified.
If it isn't supplied then <CODE>+0</CODE> is assumed.</LI>
</UL>
</LI>
</UL>
</P>
</DL>
</P>
<P>Examples:
<UL>
<LI><CODE>bind Key1 CSRTRK</CODE></LI>
<LI><CODE>bind Key1+Key2 CSRTRK+off</CODE></LI>
<LI><CODE>bind Key1+Key3 CSRTRK+on</CODE></LI>
<LI><CODE>bind Key4 TOP</CODE></LI>
<LI><CODE>bind Key5 TOP+route</CODE></LI>
<LI><CODE>bind VerticalSensor GOTOLINE+toleft+scaled</CODE></LI>
<LI><CODE>bind Key6 CONTEXT+1</CODE></LI>
</UL>
</P>

<H3><A NAME="key-table-context"></A> The Context Directive</H3>

<P>Define alternate ways to interpret certain key events and/or combinations.
A context contains definitions created by the
<A HREF="#key-table-bind">bind</A>, 
<A HREF="#key-table-hotkey">hotkey</A>,
<A HREF="#key-table-map">map</A>,
and
<A HREF="#key-table-superimpose">superimpose</A>
directives.</P>
<P><CODE>context</CODE> <EM>identifier</EM> [<EM>title</EM>]
<DL>
<DT><B><EM>identifier</EM></B><DD>
<P>Which context subsequent definitions are to be created within.
It may be:
<UL>
<LI>One of these special names:
<DL>
<DT><B>default</B><DD>
<P>The default context.
If a key combination hasn't been defined within the current context
then its definition within the default context is used.
This only applies to definitions created by
the 
<A HREF="#key-table-bind">bind</A> directive.</P>
<DT><B>menu</B><DD>
<P>This context is used when within BRLTTY's preferences menu.</P>
</DL>
</LI>
<LI>An integer within the range <CODE>0</CODE> through <CODE>252</CODE>.
Context <CODE>0</CODE> is an alternate way to refer to the default context.
Higher context numbers should be avoided because
the highest allowable number is subject to change without notice
if, for example, more named contexts are added.</LI>
</UL>
</P>
<DT><B><EM>title</EM></B><DD>
<P>A person-readable description of the context.
It may contain spaces,
and standard capitalization conventions should be used. 
This operand is optional.
If supplied when selecting a context which already has a title
then the two must match.
Named contexts already have internally-assigned titles.
Numeric contexts are initially created without titles.</P>
</DL>
</P>
<P>A context is created the first time it's selected.
It may be reselected any number of times thereafter.</P>
<P>All subsequent definitions until
either the next 
<A HREF="#key-table-context">context</A> directive
or the end of the current include level
are created within the selected context.
The initial context of the top-level key table is <CODE>default</CODE>.
The initial context of an included key subtable
is the context which was selected when it was included.
Context changes within included key subtables
don't affect the context of the including key table or subtable.</P>
<P>If a context has a title
(all named contexts
and those numeric contexts for which the <EM>title</EM> operand has been supplied)
then it is persistent.
When a key event causes a persistent context to be activated,
that context remains current until a subsequent key event
causes a different persistent context to be activated.</P>
<P>If a context doesn't have a title
(those numeric contexts for which the <EM>title</EM> operand hasn't been supplied)
then it is temporary.
When a key event causes a temporary context to be activated,
that context is only used to interpret the very next key event.</P>
<P>Examples:
<UL>
<LI><CODE>context menu</CODE></LI>
<LI><CODE>context 1 Braille Input</CODE></LI>
<LI><CODE>context 2</CODE></LI>
</UL>
</P>

<H3><A NAME="key-table-hide"></A> The Hide Directive</H3>

<P>Specify whether or not certain definitions (see the 
<A HREF="#key-table-bind">bind</A>,
<A HREF="#key-table-hotkey">hotkey</A>,
<A HREF="#key-table-map">map</A>,
and
<A HREF="#key-table-superimpose">superimpose</A>
directives) and notes (see the 
<A HREF="#key-table-note">note</A>
directive) are included within the key table's help text.</P>
<P><CODE>hide</CODE> <EM>state</EM>
<DL>
<DT><B><EM>state</EM></B><DD>
<P>One of these keywords:
<DL>
<DT><B>on</B><DD>
<P>They're excluded.</P>
<DT><B>off</B><DD>
<P>They're included.</P>
</DL>
</P>
</DL>
</P>
<P>The specified state applies to all subsequent definitions and notes
until either the next <CODE>hide</CODE> directive
or the end of the current include level.
The initial state of the top-level key table is <CODE>off</CODE>.
The initial state of an included key subtable
is the state which was selected when it was included. 
State changes within included key subtables
don't affect the state of the including key table or subtable.</P>
<P>Examples:
<UL>
<LI><CODE>hide on</CODE></LI>
</UL>
</P>

<H3><A NAME="key-table-hotkey"></A> The Hotkey Directive</H3>

<P>Bind the press and release events of a specific key
to two separate BRLTTY commands.
The bindings are defined within the current context.</P>
<P><CODE>hotkey</CODE> <EM>key</EM> <EM>press</EM> <EM>release</EM>
<DL>
<DT><B><EM>key</EM></B><DD>
<P>The name of the key which is to be bound.</P>
<DT><B><EM>press</EM></B><DD>
<P>The name of the BRLTTY command
which is to be executed whenever the key is pressed.</P>
<DT><B><EM>release</EM></B><DD>
<P>The name of the BRLTTY command
which is to be executed whenever the key is released.</P>
</DL>
</P>
<P>Modifiers may be appended to the command names.
See the <EM>command</EM> operand
of the 
<A HREF="#key-table-bind">bind</A> directive
for details.</P>
<P>Specify <CODE>NOOP</CODE> if no command is to be executed.
Specifying <CODE>NOOP</CODE> for both commands
effectively disables the key.</P>
<P>Examples:
<UL>
<LI><CODE>hotkey Key1 CSRVIS+off CSRVIS+on</CODE></LI>
<LI><CODE>hotkey Key2 NOOP NOOP</CODE></LI>
</UL>
</P>

<H3><A NAME="key-table-ifkey"></A> The IfKey Directive</H3>

<P>Conditionally process a key table directive
only if the device has a particular key.</P>
<P><CODE>ifkey</CODE> <EM>key</EM> <EM>directive</EM>
<DL>
<DT><B><EM>key</EM></B><DD>
<P>The name of the key whose availability is to be tested.</P>
<DT><B><EM>directive</EM></B><DD>
<P>The key table directive which is to be conditionally processed.</P>
</DL>
</P>
<P>Examples:
<UL>
<LI><CODE>ifkey Key1 ifkey Key2 bind Key1+Key2 HOME</CODE></LI>
</UL>
</P>

<H3><A NAME="key-table-include"></A> The Include Directive</H3>

<P>Process the directives within a key subtable.
It's recursive, which means that
any key subtable can itself include yet another key subtable.
Care must be taken to ensure that an "include loop" is not created.</P>
<P><CODE>include</CODE> <EM>file</EM>
<DL>
<DT><B><EM>file</EM></B><DD>
<P>The key subtable which is to be included.
It may be either a relative or an absolute path.
If relative, it's anchored at
the directory containing the including key table or subtable.</P>
</DL>
</P>
<P>Examples:
<UL>
<LI><CODE>include common.kti</CODE></LI>
<LI><CODE>include /path/to/my/keys.kti</CODE></LI>
</UL>
</P>

<H3><A NAME="key-table-map"></A> The Map Directive</H3>

<P>Map a key to a braille keyboard function.
The mapping is defined within the current context.</P>
<P><CODE>map</CODE> <EM>key</EM> <EM>function</EM>
<DL>
<DT><B><EM>key</EM></B><DD>
<P>The name of the key which is to be mapped.
More than one key may be mapped to the same braille keyboard function.</P>
<DT><B><EM>function</EM></B><DD>
<P>The name of the braille keyboard function.
It may be one of the following keywords:
<DL>
<DT><B>DOT1</B><DD>
<P>The upper-left standard braille dot.</P>
<DT><B>DOT2</B><DD>
<P>The middle-left standard braille dot.</P>
<DT><B>DOT3</B><DD>
<P>The lower-left standard braille dot.</P>
<DT><B>DOT4</B><DD>
<P>The upper-right standard braille dot.</P>
<DT><B>DOT5</B><DD>
<P>The middle-right standard braille dot.</P>
<DT><B>DOT6</B><DD>
<P>The lower-right standard braille dot.</P>
<DT><B>DOT7</B><DD>
<P>The lower-left computer braille dot.</P>
<DT><B>DOT8</B><DD>
<P>The lower-right computer braille dot.</P>
<DT><B>SPACE</B><DD>
<P>The space bar.</P>
<DT><B>SHIFT</B><DD>
<P>The shift key.</P>
<DT><B>UPPERCASE</B><DD>
<P>If a lowercase letter is being entered
then translate it to its uppercase equivalent.</P>
<DT><B>CONTROL</B><DD>
<P>The control key.</P>
<DT><B>META</B><DD>
<P>The left alt key.</P>
</DL>
</P>
</DL>
</P>
<P>If a key combination consists only of keys
which have been mapped to braille keyboard functions,
and if those functions when combined form a valid braille keyboard command,
then that command is executed as soon as any of the keys is released.
A valid braille keyboard command must include
either any combination of dot keys or the space bar (but not both).
If at least one dot key is included
then the braille keyboard functions specified by the
<A HREF="#key-table-superimpose">superimpose</A>
directives within the same context are also implicitly included.</P>
<P>Examples:
<UL>
<LI><CODE>map Key1 DOT1</CODE></LI>
</UL>
</P>

<H3><A NAME="key-table-note"></A> The Note Directive</H3>

<P>Add a person-readable explanation to the key table's help text.
Notes are commonly used, for example,
to describe the placement, sizes, and shapes of the keys on the device.</P>
<P><CODE>note</CODE> <EM>text</EM>
<DL>
<DT><B><EM>text</EM></B><DD>
<P>The explanation which is to be added.
It may contain spaces,
and should be grammatically correct.</P>
</DL>
</P>
<P>Each note specifies exactly one line of explanatory text.
Leading space is ignored so indentation cannot be specified.</P>
<P>There's no limit to the number of notes which may be specified.
All of them are gathered together
and presented in a single block
at the start of the key table's help text.</P>
<P>Examples:
<UL>
<LI><CODE>note Key1 is the round key at the far left on the front surface.</CODE></LI>
</UL>
</P>

<H3><A NAME="key-table-superimpose"></A> The Superimpose Directive</H3>

<P>Implicitly include a braille keyboard function whenever
a braille keyboard command consisting of at least one dot is executed.
The implicit inclusion is defined within the current context.
Any number of them may be specified.</P>
<P><CODE>superimpose</CODE> <EM>function</EM>
<DL>
<DT><B><EM>function</EM></B><DD>
<P>The name of the braille keyboard function.
See the <EM>function</EM> operand
of the 
<A HREF="#key-table-map">map</A> directive
for details.</P>
</DL>
</P>
<P>Examples:
<UL>
<LI><CODE>superimpose DOT7</CODE></LI>
</UL>
</P>

<H3><A NAME="key-table-title"></A> The Title Directive</H3>

<P>Provide a person-readable summary of the key table's purpose.</P>
<P><CODE>title</CODE> <EM>text</EM>
<DL>
<DT><B><EM>text</EM></B><DD>
<P>A one-line summary of what the key table is used for.
It may contain spaces,
and standard capitalization conventions should be used.</P>
</DL>
</P>
<P>The title of the key table may be specified only once.</P>
<P>Examples:
<UL>
<LI><CODE>title Bindings for Keypad-based Navigation</CODE></LI>
</UL>
</P>

<H3><A NAME="keyboard-properties"></A> Keyboard Properties</H3>

<P>The default is that all keyboards are monitored.
A subset of the keyboards may be selected by specifying one or more of the following properties
(see the 
<A HREF="BRLTTY-4.html#options-keyboard-properties">-K</A> command line option,
and the 
<A HREF="BRLTTY-4.html#configure-keyboard-properties">keyboard-properties</A> configuration file directive):
<DL>
<DT><B>type</B><DD>
<P>The bus type, specified as one of the following keywords:
<CODE>any</CODE>,
<CODE>ps2</CODE>,
<CODE>usb</CODE>,
<CODE>bluetooth</CODE>.</P>
<DT><B>vendor</B><DD>
<P>The vendor identifier, specified as a 16-bit unsigned integer.</P>
<DT><B>product</B><DD>
<P>The product identifier, specified as a 16-bit unsigned integer.</P>
</DL>
</P>
<P>The vendor and product identifiers may be specified in
decimal (no prefix),
octal (prefixed by <CODE>0</CODE>),
or hexadecimal (prefixed by <CODE>0x</CODE>).
Specifying <CODE>0</CODE> means match any value
(as if the property weren't specified).</P>

<HR>
<A HREF="BRLTTY-7.html">Next</A>
<A HREF="BRLTTY-5.html">Previous</A>
<A HREF="BRLTTY.html#toc6">Contents</A>
</BODY>
</HTML>
brltty 5.0-2ubuntu2 / usr / share / doc / brltty / English / BRLTTY-6.html
