File: Manual-4.html

package info (click to toggle)
brltty 3.4.1-4
links: PTS
area: main
in suites: sarge
size: 6,268 kB
ctags: 4,537
sloc: ansic: 54,295; sh: 3,470; makefile: 793; tcl: 398; yacc: 300; awk: 57; python: 29
file content (1403 lines) | stat: -rw-r--r-- 62,034 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
 <META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.20">
 <TITLE>BRLTTY: Feature Descriptions</TITLE>
 <LINK HREF="Manual-5.html" REL=next>
 <LINK HREF="Manual-3.html" REL=previous>
 <LINK HREF="Manual.html#toc4" REL=contents>
</HEAD>
<BODY>
<A HREF="Manual-5.html">Next</A>
<A HREF="Manual-3.html">Previous</A>
<A HREF="Manual.html#toc4">Contents</A>
<HR>
<H2><A NAME="s4">4.</A> <A HREF="Manual.html#toc4">Feature Descriptions</A></H2>



<H2><A NAME="routing"></A> <A NAME="ss4.1">4.1</A> <A HREF="Manual.html#toc4.1">Cursor Routing</A>
</H2>

<P>When moving the braille window around the screen
while examining the text, say, in an editor,
you often need to bring the cursor
to a specific character within the braille window.
You'll probably find this to be a rather difficult task for a number of reasons.
One is that you may not know where the cursor is,
and that you may lose your place while trying to find it.
Another is that the cursor may move unrpedictably as the arrow keys are pressed
(some editors, for example, don't allow the cursor to be
more to the right than the end of the line it's on).
Cursor routing provides just such a capability
by knowing where the cursor is,
by simulating the same arrow-key presses which you'd have to enter manually,
and by monitoring the progress of the cursor as it moves.</P>
<P>Some braille displays have a button, known as a routing key, above each cell.
These keys use the 
<A HREF="Manual-3.html#command-ROUTE">ROUTE</A> command
to route the cursor right to the desired location.</P>
<P>Cursor routing, while very convenient and effective,
is, strictly speaking, not completely reliable.
One reason for this is that its current implementation assumes
VT100 cursor key escape sequences.
Another is that some applications do non-standard things
in response to detecting that a cursor key has been pressed.
A minor problem found within some editors (like <CODE>vi</CODE>),
as already mentioned above,
is that they throw in some unpredictable horizontal motion
when vertical motion is requested
because they don't allow the cursor to be to the right of the end of a line.
A major problem found within some web browsers (like <CODE>lynx</CODE>)
is that the up- and down-arrow keys are used to move among the links
(which may skip lines and/or move the cursor horizontally,
but which rarely just moves the cursor one line in the desired direction),
and that the left- and right-arrow keys are used to select links
(which has absolutely nothing to do with any form of cursor motion whatsoever,
and which even totally changes the screen content).</P>
<P>Cursor routing may not work very well on a heavily loaded system,
and definitely doesn't work very well when working on a remote system over a slow link.
This is so because of all of the checks which must be made along the way
in order to deal with unpredictable cursor motion
and in order to ensure that any mistake has at least a fighting chance to be undone.
Even  though BRLTTY tries to be fairly clever,
it must still essentially wait to see what happens after each simulated arrow-key press.</P>
<P>Once a cursor routing request has been made,
BRLTTY keeps trying to route the cursor to the desired location until
a timeout expires before the cursor reaches that location,
the cursor seems to be moving in the wrong direction,
or you switch to a different virtual terminal.
An attempt is first made to use virtical motion
to bring the cursor to the right line,
and, only if that succeeds, an attempt is then made
to use horizontal motion to bring the cursor to the right column.
If another request is made while one is still in progress,
then the first one is aborted and the second one is initiated.</P>
<P>A safer but less powerful cursor routing command,
<A HREF="Manual-3.html#command-CSRJMP_VERT">CSRJMP_VERT</A>,
uses just vertical motion to bring the cursor
to anywhere on the top line of the braille window.
It's especially useful in conjunction with applications (like <CODE>lynx</CODE>)
wherein horizontal cursor motion must never be attempted.</P>

<H2><A NAME="cut"></A> <A NAME="ss4.2">4.2</A> <A HREF="Manual.html#toc4.2">Cut and Paste</A>
</H2>

<P>This feature enables you to grab some text which is already on the screen 
and re-enter it at the current cursor position.
Using it saves time and avoids errors
when a long and/or complicated piece of text needs to be copied,
and even when the same short and simple piece of text needs to be copied many times.
It's particularly useful for things like
long file names,
complicated command lines,
E-mail addresses,
and URLs. Cutting and pasting text involves three simple steps:
<OL>
<LI>Mark either the top-left corner of the rectangular area
or the beginning of the linear area
on the screen which is to be grabbed (cut).
If your display has routing keys,
then move the braille window so that
the first character to be cut appears anywhere within it, and then:
<UL>
<LI>invoke the 
<A HREF="Manual-3.html#command-CUTBEGIN">CUTBEGIN</A> command
to start a new cut buffer</LI>
<LI>invoke the 
<A HREF="Manual-3.html#command-CUTAPPEND">CUTAPPEND</A> command
to append to the existing cut buffer</LI>
</UL>

by pressing the key(s) associated with it
and then pressing the routing key associated with the character.</LI>
<LI>Mark either the bottom-right corner of the rectangular area
or the end of the linear area
on the screen which is to be grabbed (cut).
If your display has routing keys,
then move the braille window so that
the last character to be cut appears anywhere within it, and then
<UL>
<LI>invoke the 
<A HREF="Manual-3.html#command-CUTRECT">CUTRECT</A> command
to cut a rectangular area</LI>
<LI>invoke the 
<A HREF="Manual-3.html#command-CUTLINE">CUTLINE</A> command
to cut a linear area</LI>
</UL>

by pressing the key(s) associated with it
and then pressing the routing key associated with the character.
Marking the end of the cut area
appends the selected screen content to the cut buffer.
Excess white-space is removed from the end of each line in the cut buffer
so that unwanted trailing spaces won't be pasted back in.
Control characters are replaced with blanks.</LI>
<LI>Insert (paste) the text where it's needed.
Place the cursor over the character where the text is to be pasted,
and invoke the 
<A HREF="Manual-3.html#command-PASTE">PASTE</A> command.
You can paste the same text any number of times without recutting it.
This description assumes that you're already in some sort of input mode.
If you paste when you're in some other kind of mode
(like <CODE>vi</CODE>'s command mode),
then you'd better be aware of what the characters in the cut buffer will do.</LI>
</OL>
</P>
<P>The cut buffer is also used by
the 
<A HREF="Manual-3.html#command-PRSEARCH">PRSEARCH</A>
and 
<A HREF="Manual-3.html#command-NXSEARCH">NXSEARCH</A> commands.</P>

<H2><A NAME="gpm"></A> <A NAME="ss4.3">4.3</A> <A HREF="Manual.html#toc4.3">Pointer (Mouse) Support via GPM</A>
</H2>

<P>If BRLTTY is configured with the 
<A HREF="Manual-2.html#build-gpm">--enable-gpm</A> build option
on a system where the <CODE>gpm</CODE> application has been installed,
then it'll interact with the pointer (mouse).</P>
<P>Moving the braille window moves the pointer
(see the 
<A HREF="#preference-pointer-follows-window">Pointer Follows Window</A> preference).
Any motion of the braille window (manual, cursor tracking, etc.),
other than when it moves in response to pointer motion,
moves the pointer to the character on the screen
which corresponds to the upper-left corner of the braille window.
This enables a sighted observer to see where the braille window is,
and, therefore, to know what the braille user is reading.
It also keeps the pointer within the braille window
so that it can be found easily,
and so that the pointer device can always be readily used
as another way to move the braille window.</P>
<P>Moving the pointer drags the braille window
(see the 
<A HREF="#preference-window-follows-pointer">Window Follows Pointer</A> preference).
Whenever the pointer is moved beyond the edge of the braille window,
the braille window is dragged along (one character at a time).
This gives the braille user another two-dimensional way
to inspect the screen content
or to quickly move the braille window to a desired location.
It also gives a sighted observer an easy way to move the braille window
to something he'd like the braille user to read.</P>
<P><CODE>gpm</CODE> uses reverse video to show where the pointer is.
Underlining of highlighted characters
(see the 
<A HREF="Manual-3.html#command-ATTRVIS">ATTRVIS</A> command for details)
should be turned on, therefore, when the braille user wishes to use the pointer.</P>
<P>This feature also gives the braille user access to <CODE>gpm</CODE>'s cut-and-paste capability.
Although you should read <CODE>gpm</CODE>'s own documentation,
here are some notes on how it works.
<UL>
<LI>Copy the current character to the cut buffer
by single-clicking the left button.</LI>
<LI>Copy the current word (space-delimited) to the cut buffer
by double-clicking the left button.</LI>
<LI>Copy the current line to the cut buffer
by tripple-clicking the left button.</LI>
<LI>Copy a linear region to the cut buffer as follows:
<OL>
<LI>Place the pointer on the first character of the region.</LI>
<LI>Press (and hold) the left button.</LI>
<LI>Move the pointer to the last character of the region
(all currently selected characters are highlighted).</LI>
<LI>Release the left button.</LI>
</OL>
</LI>
<LI>Paste (input) the current contents of the cut buffer
by clicking the middle button of a three-button mouse
or by clicking the right button of a two-button mouse.</LI>
<LI>Append to the cut buffer
by using the right button of a three-button mouse.</LI>
</UL>
</P>

<H2><A NAME="tunes"></A> <A NAME="ss4.4">4.4</A> <A HREF="Manual.html#toc4.4">Alert Tunes</A>
</H2>

<P>BRLTTY alerts you to the occurrence of significant events
by playing short predefined tunes.
This feature can be activated and deactivated with
either the 
<A HREF="Manual-3.html#command-TUNES">TUNES</A> command
or the 
<A HREF="#preference-alert-tunes">Alert Tunes</A> preference.
The tunes are played via the internal beeper by default,
but other alternatives can be selected
with the 
<A HREF="#preference-tune-device">Tune Device</A> preference.</P>
<P>Each significant event is associated, from highest to lowest priority,
with one or more of the following:
<DL>
<DT><B>a tune</B><DD><P>If a tune has been associated with the event,
if the 
<A HREF="#preference-alert-tunes">Alert Tunes</A> preference
(see also the 
<A HREF="Manual-3.html#command-TUNES">TUNES</A> command)
is active,
and if the selected tune device
(see the 
<A HREF="#preference-tune-device">Tune Device</A> preference)
can be opened,
then the tune is played.</P>
<DT><B>a dot pattern</B><DD><P>If a dot pattern has been associated with the event,
and if the 
<A HREF="#preference-alert-dots">Alert Dots</A> preference is active,
then the dot pattern is briefly displayed on every braille cell.
Some braille displays don't respond quickly enough
for this mechanism to work effectively.</P>
<DT><B>a message</B><DD><P>If a message has been associated with the event,
and if the 
<A HREF="#preference-alert-messages">Alert Messages</A> preference is active,
then it is displayed for a few seconds
(see the 
<A HREF="Manual-3.html#options-message-delay">-M</A> command line option).</P>
</DL>
</P>
<P>These events include:
<UL>
<LI>When the braille display driver starts or stops.</LI>
<LI>When the start or end of the cut block is set.</LI>
<LI>When a feature is activated or deactivated.</LI>
<LI>When cursor tracking is turned on or off.</LI>
<LI>When the screen image is frozen or unfrozen.</LI>
<LI>When identical lines are skipped.</LI>
<LI>When the braille window wraps
either down to the beginning of the next line
or up to the end of the previous line.</LI>
<LI>When a requested motion cannot be performed.</LI>
<LI>When a command cannot be executed.</LI>
<LI>When a lengthy command completes.</LI>
</UL>
</P>

<H2><A NAME="preferences"></A> <A NAME="ss4.5">4.5</A> <A HREF="Manual.html#toc4.5">Preferences Settings</A>
</H2>

<P>When BRLTTY starts, it loads a file which contains your preferences settings.
The file doesn't need to exist,
and is created the first time the settings are saved
with the 
<A HREF="Manual-3.html#command-PREFSAVE">PREFSAVE</A> command.
The most recently saved settings can be restored at any time
with the 
<A HREF="Manual-3.html#command-PREFLOAD">PREFLOAD</A> command.</P>
<P>The default name for this file is <CODE>/etc/brltty.conf</CODE>.
A system default for its name can be established with
the 
<A HREF="Manual-3.html#configure-preferences-file">preferences-file</A> configuration file directive.
Its name can be explicitly set at run-time with
the 
<A HREF="Manual-3.html#options-preferences-file">-p</A> command line option.</P>

<H3><A NAME="preferences-menu"></A> The Preferences Menu</H3>

<P>The preferences settings are saved as binary data
which, therefore, can't be edited by hand.
BRLTTY, however, has a simple menu from which you can easily change them.
This feature isn't available if the
<A HREF="Manual-2.html#build-preferences-menu">--disable-preferences-menu</A> build option was specified.</P>
<P>The meny is activated by the 
<A HREF="Manual-3.html#command-PREFMENU">PREFMENU</A> command.
The braille display briefly
(see the 
<A HREF="Manual-3.html#options-message-delay">-M</A> command line option)
shows the menu title,
and then presents the current item and its current setting.</P>

<H3>Navigating the Menu</H3>

<P>See 
<A HREF="Manual-3.html#menu">Menu Navigation Commands</A> for the full list of
commands which enable you to select items and change settings within the menu.
For backward compatibility with old drivers, the window motion commands,
which have modified meanings in this context, can also be used.
<DL>
<DT><B><CODE>TOP</CODE>, <CODE>TOP_LEFT</CODE></B><DD><P>Go to the first item in the menu
(same as 
<A HREF="Manual-3.html#command-MENU_FIRST_ITEM">MENU_FIRST_ITEM</A>).</P>
<DT><B><CODE>BOT</CODE>, <CODE>BOT_LEFT</CODE></B><DD><P>Go to the last item in the menu
(same as 
<A HREF="Manual-3.html#command-MENU_LAST_ITEM">MENU_LAST_ITEM</A>).</P>
<DT><B><CODE>LNUP</CODE>, <CODE>CURSOR_UP</CODE></B><DD><P>Go to the previous item in the menu
(same as 
<A HREF="Manual-3.html#command-MENU_PREV_ITEM">MENU_PREV_ITEM</A>).</P>
<DT><B><CODE>LNDN</CODE>, <CODE>CURSOR_DOWN</CODE></B><DD><P>Go to the next item in the menu
(same as 
<A HREF="Manual-3.html#command-MENU_NEXT_ITEM">MENU_NEXT_ITEM</A>).</P>
<DT><B><CODE>WINUP</CODE>, <CODE>CHRLT</CODE>, <CODE>CURSOR_LEFT</CODE></B><DD><P>Decrement the current menu item's setting
(same as 
<A HREF="Manual-3.html#command-MENU_PREV_SETTING">MENU_PREV_SETTING</A>).</P>
<DT><B><CODE>WINDN</CODE>, <CODE>CHRRT</CODE>, <CODE>CURSOR_RIGHT</CODE>, <CODE>HOME</CODE>, <CODE>RETURN</CODE></B><DD><P>Increment the current menu item's setting
(same as 
<A HREF="Manual-3.html#command-MENU_NEXT_SETTING">MENU_NEXT_SETTING</A>).</P>
</DL>
</P>
<P>Notes:
<UL>
<LI>The routing keys can also be used to select a setting for the current item.
If the item has numeric settings,
then each routing key represents an integer (starting from 0),
and a selection which is out of range is silently brought into range.
If the item has named settings,
then the routing keys correspond ordinally with the settings.</LI>
<LI>Use the <CODE>PREFLOAD</CODE> command to undo all of the changes
which were made since entering the menu.</LI>
<LI>Use the <CODE>PREFMENU</CODE> command (again) to leave the new settings in effect,
exit the menu, and resume normal operation.
If the "Save Settings on Exit" item is set, then, in addition,
the new settings are written to the preferences settings file.
Any command not recognized by the menu system also does these same things.</LI>
</UL>
</P>

<H3>The Menu Items</H3>

<P>
<DL>
<DT><B>Save on Exit
<A NAME="preference-save-on-exit"></A> </B><DD><P>When exiting the preferences menu:
<DL>
<DT><B>No</B><DD><P>Don't automatically save the preferences settings.</P>
<DT><B>Yes</B><DD><P>Automatically save the preferences settings.</P>
</DL>

The initial setting is <CODE>No</CODE>.</P>
<DT><B>Text Style
<A NAME="preference-text-style"></A> </B><DD><P>When displaying screen content
(see the 
<A HREF="Manual-3.html#command-DISPMD">DISPMD</A> command),
show characters:
<DL>
<DT><B>8-dot</B><DD><P>With all eight dots.</P>
<DT><B>6-dot</B><DD><P>With only dots 1 through 6.
If a contraction table has been selected
(see the 
<A HREF="Manual-3.html#options-contraction-table">-c</A> command line option
and the 
<A HREF="Manual-3.html#configure-contraction-table">contraction-table</A> configuration file directive),
then it is used.</P>
</DL>

This setting can also be changed with the
<A HREF="Manual-3.html#command-SIXDOTS">SIXDOTS</A> command.</P>
<DT><B>Meta Mode
<A NAME="preference-meta-mode"></A> </B><DD><P>Enter a meta character by:
<DL>
<DT><B>Escape Prefix</B><DD><P>Prefixing it with an <CODE>escape</CODE> byte.</P>
<DT><B>High-order Bit</B><DD><P>Setting its high-order bit.</P>
</DL>

Use the <CODE>setmetamode</CODE> command to find out how your system has been configured.
The initial setting is <CODE>Escape Prefix</CODE>.</P>
<DT><B>Skip Identical Lines
<A NAME="preference-skip-identical-lines"></A> </B><DD><P>When moving either up or down exactly one line with
the 
<A HREF="Manual-3.html#command-LNUP">LNUP</A>
and 
<A HREF="Manual-3.html#command-LNDN">LNDN</A> commands,
as well as the line wrapping feature of
the 
<A HREF="Manual-3.html#command-FWINLT">FWINLT</A>,
<A HREF="Manual-3.html#command-FWINRT">FWINRT</A>,
<A HREF="Manual-3.html#command-FWINLTSKIP">FWINLTSKIP</A>,
and 
<A HREF="Manual-3.html#command-FWINRTSKIP">FWINRTSKIP</A> commands:
<DL>
<DT><B>No</B><DD><P>Don't skip passed lines which have the same content as the current line.</P>
<DT><B>Yes</B><DD><P>Skip passed lines which have the same content as the current line.</P>
</DL>

This setting can also be changed with the
<A HREF="Manual-3.html#command-SKPIDLNS">SKPIDLNS</A> command.</P>
<DT><B>Skip Blank Windows
<A NAME="preference-skip-blank-windows"></A> </B><DD><P>When moving either left or right with
the 
<A HREF="Manual-3.html#command-FWINLT">FWINLT</A>
and 
<A HREF="Manual-3.html#command-FWINRT">FWINRT</A> commands:
<DL>
<DT><B>No</B><DD><P>Don't skip passed blank windows.</P>
<DT><B>Yes</B><DD><P>Skip passed blank windows.</P>
</DL>

This setting can also be changed with the
<A HREF="Manual-3.html#command-SKPBLNKWINS">SKPBLNKWINS</A> command.</P>
<DT><B>Which Blank Windows
<A NAME="preference-which-blank-windows"></A> </B><DD><P>If blank windows are to be skipped:
<DL>
<DT><B>All</B><DD><P>Skip all of them.</P>
<DT><B>End of Line</B><DD><P>Only skip those which are at the end (on the right side) of a line.</P>
<DT><B>Rest of Line</B><DD><P>Only skip those which are
at the end (on the right side) of a line when reading forward,
and at the beginning (on the left side) of a line when reading backward.</P>
</DL>
</P>
<DT><B>Sliding Window
<A NAME="preference-sliding-window"></A> </B><DD><P>If the cursor is being tracked
(see the 
<A HREF="Manual-3.html#command-CSRTRK">CSRTRK</A> command),
and the cursor moves too close to (or beyond)
either end of the braille window:
<DL>
<DT><B>No</B><DD><P>Horizontally reposition the window such that its left end
is a multiple of its width from the left edge of the screen.</P>
<DT><B>Yes</B><DD><P>Horizontally reposition the window such that the cursor,
while remaining on that side of the window, is nearer the centre.</P>
</DL>

This setting can also be changed with the
<A HREF="Manual-3.html#command-SLIDEWIN">SLIDEWIN</A> command.</P>
<DT><B>Eager Sliding Window
<A NAME="preference-eager-sliding-window"></A> </B><DD><P>If the braille window is to slide:
<DL>
<DT><B>No</B><DD><P>Reposition it whenever the cursor moves beyond either end.</P>
<DT><B>Yes</B><DD><P>Reposition it whenever the cursor moves too close to either end.</P>
</DL>

The initial setting is <CODE>off</CODE>.</P>
<DT><B>Window Overlap
<A NAME="preference-window-overlap"></A> </B><DD><P>When moving either left or right with
the 
<A HREF="Manual-3.html#command-FWINLT">FWINLT</A>
and 
<A HREF="Manual-3.html#command-FWINRT">FWINRT</A> commands,
this setting specifies how many characters
horizontally adjacent braille windows should overlap each other by.
The initial setting is <CODE>0</CODE>.</P>
<DT><B>Show Cursor
<A NAME="preference-show-cursor"></A> </B><DD><P>When displaying screen content
(see the 
<A HREF="Manual-3.html#command-DISPMD">DISPMD</A> command):
<DL>
<DT><B>No</B><DD><P>Don't show the cursor.</P>
<DT><B>Yes</B><DD><P>Show the cursor.</P>
</DL>

This setting can also be changed with the
<A HREF="Manual-3.html#command-CSRVIS">CSRVIS</A> command.</P>
<DT><B>Cursor Style
<A NAME="preference-cursor-style"></A> </B><DD><P>When showing the cursor, represent it:
<DL>
<DT><B>Underline</B><DD><P>With dots 7 and 8.</P>
<DT><B>Block</B><DD><P>With all eight dots.</P>
</DL>

This setting can also be changed with the
<A HREF="Manual-3.html#command-CSRSIZE">CSRSIZE</A> command.</P>
<DT><B>Blinking Cursor
<A NAME="preference-blinking-cursor"></A> </B><DD><P>When the cursor is to be shown:
<DL>
<DT><B>No</B><DD><P>Leave it visible all the time.</P>
<DT><B>Yes</B><DD><P>Make it alternately visible and invisible
according to a predefined interval.</P>
</DL>

This setting can also be changed with the
<A HREF="Manual-3.html#command-CSRBLINK">CSRBLINK</A> command.</P>
<DT><B>Cursor Visible Period
<A NAME="preference-cursor-visible-period"></A> </B><DD><P>When the cursor is to be blinked, this setting specifies the length of time
(see the note on 
<A HREF="#time-settings">time settings</A> below)
during each cycle that it is to be visible.
The initial setting is <CODE>10</CODE>.</P>
<DT><B>Cursor Invisible Period
<A NAME="preference-cursor-invisible-period"></A> </B><DD><P>When the cursor is to be blinked, this setting specifies the length of time
(see the note on 
<A HREF="#time-settings">time settings</A> below)
during each cycle that it is to be invisible.
The initial setting is <CODE>10</CODE>.</P>
<DT><B>Show Attributes
<A NAME="preference-show-attributes"></A> </B><DD><P>When displaying screen content
(see the 
<A HREF="Manual-3.html#command-DISPMD">DISPMD</A> command):
<DL>
<DT><B>No</B><DD><P>Don't underline highlighted characters.</P>
<DT><B>Yes</B><DD><P>Underline highlighted characters.</P>
</DL>

This setting can also be changed with the
<A HREF="Manual-3.html#command-ATTRVIS">ATTRVIS</A> command.</P>
<DT><B>Blinking Attributes
<A NAME="preference-blinking-attributes"></A> </B><DD><P>When highlighted characters are to be underlined:
<DL>
<DT><B>No</B><DD><P>Leave the indicator visible all the time.</P>
<DT><B>Yes</B><DD><P>Make the indicator alternately visible and invisible
according to a predefined interval.</P>
</DL>

This setting can also be changed with the
<A HREF="Manual-3.html#command-ATTRBLINK">ATTRBLINK</A> command.</P>
<DT><B>Attributes Visible Period
<A NAME="preference-attributes-visible-period"></A> </B><DD><P>When the highlighted character underline is to be blinked,
this setting specifies the length of time
(see the note on 
<A HREF="#time-settings">time settings</A> below)
during each cycle that it is to be visible.
The initial setting is <CODE>4</CODE>.</P>
<DT><B>Attributes Invisible Period
<A NAME="preference-attributes-invisible-period"></A> </B><DD><P>When the highlighted character underline is to be blinked,
this setting specifies the length of time
(see the note on 
<A HREF="#time-settings">time settings</A> below)
during each cycle that it is to be invisible.
The initial setting is <CODE>12</CODE>.</P>
<DT><B>Blinking Capitals
<A NAME="preference-blinking-capitals"></A> </B><DD><P>When displaying screen content
(see the 
<A HREF="Manual-3.html#command-DISPMD">DISPMD</A> command):
<DL>
<DT><B>No</B><DD><P>Leave capital letters visible all the time.</P>
<DT><B>Yes</B><DD><P>Make capital letters alternately visible and invisible
according to a predefined interval.</P>
</DL>

This setting can also be changed with the
<A HREF="Manual-3.html#command-CAPBLINK">CAPBLINK</A> command.</P>
<DT><B>Capitals Visible Period
<A NAME="preference-capitals-visible-period"></A> </B><DD><P>When capital letters are to be blinked,
this setting specifies the length of time
(see the note on 
<A HREF="#time-settings">time settings</A> below)
during each cycle that they're to be visible.
The initial setting is <CODE>4</CODE>.</P>
<DT><B>Capitals Invisible Period
<A NAME="preference-capitals-invisible-period"></A> </B><DD><P>When capital letters are to be blinked,
this setting specifies the length of time
(see the note on 
<A HREF="#time-settings">time settings</A> below)
during each cycle that they're to be invisible.
The initial setting is <CODE>2</CODE>.</P>
<DT><B>Window Follows Pointer
<A NAME="preference-window-follows-pointer"></A> </B><DD><P>When moving the pointer device (mouse):
<DL>
<DT><B>No</B><DD><P>Don't drag the braille window.</P>
<DT><B>Yes</B><DD><P>Drag the braille window.</P>
</DL>

This preference is only presented if the
<A HREF="Manual-2.html#build-gpm">--enable-gpm</A> build option was specified.</P>
<DT><B>Pointer Follows Window
<A NAME="preference-pointer-follows-window"></A> </B><DD><P>When moving the braille window:
<DL>
<DT><B>No</B><DD><P>Don't move the pointer (mouse).</P>
<DT><B>Yes</B><DD><P>Move the pointer (mouse) to the character on the screen
corresponding to the top-left corner of the braille window.</P>
</DL>

This preference is only presented if the
<A HREF="Manual-2.html#build-gpm">--enable-gpm</A> build option was specified.</P>
<DT><B>Alert Tunes
<A NAME="preference-alert-tunes"></A> </B><DD><P>Whenever a significant event with an associated tune occurs
(see 
<A HREF="#tunes">Alert Tunes</A>):
<DL>
<DT><B>No</B><DD><P>Don't play the tune.</P>
<DT><B>Yes</B><DD><P>Play the tune.</P>
</DL>

This setting can also be changed with the
<A HREF="Manual-3.html#command-TUNES">TUNES</A> command.</P>
<DT><B>Tune Device
<A NAME="preference-tune-device"></A> </B><DD><P>Play alert tunes via:
<DL>
<DT><B>Beeper</B><DD><P>The internal beeper (console tone generator).
This setting is supported on Linux,
and on OpenBSD.
It's always safe to use,
although it may be somewhat soft.
This device isn't available if the
<A HREF="Manual-2.html#build-beeper-tunes">--disable-beeper-tunes</A> build option was specified.</P>
<DT><B>PCM</B><DD><P>The digital audio interface on the sound card.
This setting is supported on Linux (via <CODE>/dev/dsp</CODE>),
on OpenBSD (via <CODE>/dev/audio0</CODE>),
and on Solaris (via <CODE>/dev/audio</CODE>).
It doesn't work when this device is already being used
by another application.
This device isn't available if the
<A HREF="Manual-2.html#build-pcm-tunes">--disable-pcm-tunes</A> build option was specified.</P>
<DT><B>MIDI</B><DD><P>The Musical Instrument Digital Interface on the sound card
This setting is supported on Linux (via <CODE>/dev/sequencer</CODE>).
It doesn't work when this device is already being used
by another application.
This device isn't available if the
<A HREF="Manual-2.html#build-midi-tunes">--disable-midi-tunes</A> build option was specified.</P>
<DT><B>FM</B><DD><P>The FM synthesizer on an
AdLib, OPL3, Sound Blaster, or equivalent sound card.
This setting is supported on Linux.
It works even if the FM synthesizer
is already being used by another application.
The results are unpredictable, and potentially not very good,
if it's used with a sound card which doesn't support this feature.
This device isn't available if the
<A HREF="Manual-2.html#build-fm-tunes">--disable-fm-tunes</A> build option was specified.</P>
</DL>

The initial setting is <CODE>beeper</CODE> on those platforms which support it,
and <CODE>PCM</CODE> on those platforms which don't.</P>
<DT><B>MIDI Instrument
<A NAME="preference-midi-instrument"></A> </B><DD><P>If the Musical Instrument Digital Interface (MIDI) of the sound card
is being used to play the alert tunes,
this setting specifies which instrument is to be used
(see the 
<A HREF="Manual-8.html#midi">MIDI Instrument Table</A>).
The initial setting is <CODE>Acoustic Grand Piano</CODE>.</P>
<DT><B>Alert Dots
<A NAME="preference-alert-dots"></A> </B><DD><P>Whenever a significant event with an associated dot pattern occurs
(see 
<A HREF="#tunes">Alert Tunes</A>):
<DL>
<DT><B>No</B><DD><P>Don't display the dot pattern.</P>
<DT><B>Yes</B><DD><P>Briefly display the dot pattern.</P>
</DL>

If alert tunes are to be played
(see the 
<A HREF="Manual-3.html#command-TUNES">TUNES</A> command
and the 
<A HREF="#preference-alert-tunes">Alert Tunes</A> preference),
if a tune has been associated with the event,
and if the selected tune device can be opened,
then, regardless of the setting of this preference, the dot pattern isn't displayed.</P>
<DT><B>Alert Messages
<A NAME="preference-alert-messages"></A> </B><DD><P>Whenever a significant event with an associated message occurs
(see 
<A HREF="#tunes">Alert Tunes</A>):
<DL>
<DT><B>No</B><DD><P>Don't display the message.</P>
<DT><B>Yes</B><DD><P>Display the message.</P>
</DL>

If alert tunes are to be played
(see the 
<A HREF="Manual-3.html#command-TUNES">TUNES</A> command
and the 
<A HREF="#preference-alert-tunes">Alert Tunes</A> preference),
if a tune has been associated with the event,
and if the selected tune device can be opened,
or if alert dot patterns are to be displayed
(see the 
<A HREF="#preference-alert-dots">Alert Dots</A> preference)
and if a dot pattern has been associated with the event,
then, regardless of the setting of this preference, the message isn't displayed.</P>
<DT><B>Say-Line Mode
<A NAME="preference-sayline-mode"></A> </B><DD><P>When using the 
<A HREF="Manual-3.html#command-SAY_LINE">SAY_LINE</A> command:
<DL>
<DT><B>Immediate</B><DD><P>Discard pending speech.</P>
<DT><B>Enqueue</B><DD><P>Don't discard pending speech.</P>
</DL>
</P>
<DT><B>Autospeak
<A NAME="preference-autospeak"></A> </B><DD><P>
<DL>
<DT><B>No</B><DD><P>Only speak when explicitly requested to do so
(see section 
<A HREF="Manual-3.html#speech">Speech Controls</A>).</P>
<DT><B>Yes</B><DD><P>This setting is experimental.</P>
</DL>
</P>
<DT><B>Status Style
<A NAME="preference-status-style"></A> </B><DD><P>This setting specifies the way that the status cells are to be used.
You shuldn't normally need to play with it.
It enables BRLTTY's developers to test status cell configurations
for braille displays which they don't actually have.
<DL>
<DT><B>None</B><DD><P>Don't use the status cells.
This setting is always safe, but it's also quite useless.</P>
<DT><B>Alva</B><DD><P>The status cells contain:
<DL>
<DT><B>1</B><DD><P>The location of the cursor (see below).</P>
<DT><B>2</B><DD><P>The location of the top-left corner of the braille window (see below).</P>
<DT><B>3</B><DD><P>A letter indicating BRLTTY's state.
In order of precedence:
<DL>
<DT><B>a</B><DD><P>Screen attributes are being shown
(see the 
<A HREF="Manual-3.html#command-DISPMD">DISPMD</A> command).</P>
<DT><B>f</B><DD><P>The screen image is frozen
(see the 
<A HREF="Manual-3.html#command-FREEZE">FREEZE</A> command).</P>
<DT><B>f</B><DD><P>The cursor is being tracked
(see the 
<A HREF="Manual-3.html#command-CSRTRK">CSRTRK</A> command).</P>
<DT><B><EM>blank</EM></B><DD><P>Nothing special.</P>
</DL>
</P>
</DL>

The locations of the cursor and the braille window
are presented in an interesting way.
Dots 1 through 6 represent the line number with a letter
from <CODE>a</CODE> (for 1) through <CODE>y</CODE> (for 25).
Dots 7 and 8 (the extra two at the bottom)
represent the horizontal braille window number as follows:
<DL>
<DT><B>No Dots</B><DD><P>The first (leftmost) window.</P>
<DT><B>Dot 7</B><DD><P>The second window.</P>
<DT><B>Dot 8</B><DD><P>The third window.</P>
<DT><B>Dots 7 and 8</B><DD><P>The fourth window.</P>
</DL>

In both cases, the indicators wrap:
line 26 is represented by the letter <CODE>a</CODE>, and the fifth horizontal
braille window is represented by no dots at the bottom.</P>
<DT><B>Tieman</B><DD><P>The status cells contain:
<DL>
<DT><B>1-2</B><DD><P>The columns (counting from zero) of the cursor
(shown in the top half of the cells)
and the top-left corner of the braille window
(shown in the bottom half of the cells).</P>
<DT><B>3-4</B><DD><P>The rows (counting from zero) of the cursor
(shown in the top half of the cells)
and the top-left corner of the braille window
(shown in the bottom half of the cells).</P>
<DT><B>5</B><DD><P>Each dot indicates if a feature is turned on as follows:
<DL>
<DT><B>Dot 1</B><DD><P>The screen image is frozen
(see the 
<A HREF="Manual-3.html#command-FREEZE">FREEZE</A> command).</P>
<DT><B>Dot 2</B><DD><P>Screen attributes are being displayed
(see the 
<A HREF="Manual-3.html#command-DISPMD">DISPMD</A> command).</P>
<DT><B>Dot 3</B><DD><P>Alert tunes are being played
(see the 
<A HREF="Manual-3.html#command-TUNES">TUNES</A> command).</P>
<DT><B>Dot 4</B><DD><P>The cursor is being shown
(see the 
<A HREF="Manual-3.html#command-CSRVIS">CSRVIS</A> command).</P>
<DT><B>Dot 5</B><DD><P>The cursor is a solid block
(see the 
<A HREF="Manual-3.html#command-CSRSIZE">CSRSIZE</A> command).</P>
<DT><B>Dot 6</B><DD><P>The cursor is blinking
(see the 
<A HREF="Manual-3.html#command-CSRBLINK">CSRBLINK</A> command).</P>
<DT><B>Dot 7</B><DD><P>The cursor is being tracked
(see the 
<A HREF="Manual-3.html#command-CSRTRK">CSRTRK</A> command).</P>
<DT><B>Dot 8</B><DD><P>The braille window will slide
(see the 
<A HREF="Manual-3.html#command-SLIDEWIN">SLIDEWIN</A> command).</P>
</DL>
</P>
</DL>
</P>
<DT><B>PowerBraille 80</B><DD><P>The status cells contain:
<DL>
<DT><B>1</B><DD><P>The row (counting from 1) corresponding
to the top of the braille window.
The tens digit is shown in the top half of the cell,
and the units digit is shown in the bottom half of the cell.</P>
</DL>
</P>
<DT><B>Generic</B><DD><P>This setting passes a lot of information to the braille driver,
and the driver itself decides how to present it.</P>
<DT><B>MDV</B><DD><P>The status cells contain:
<DL>
<DT><B>1-2</B><DD><P>The location of the top-left corner of the braille window.
The row (counting from 1) is shown in the top half of the cells,
and the column (counting from 1) is shown in the bottom half of the cells.</P>
</DL>
</P>
<DT><B>Voyager</B><DD><P>The status cells contain:
<DL>
<DT><B>1</B><DD><P>The row (counting from 0) corresponding to
the top of the braille window (see below).</P>
<DT><B>2</B><DD><P>The row (counting from 0) whereon the cursor is (see below).</P>
<DT><B>3</B><DD><P>If the screen is frozen
(see the 
<A HREF="Manual-3.html#command-FREEZE">FREEZE</A> command),
then the letter <CODE>F</CODE>.
If it isn't, then
the column (counting from 0) wherein the cursor is (see below).</P>
</DL>

Row and column numbers are shown as two digits within a single cell.
The tens digit is shown in the top half of the cell,
and the units digit is shown in the bottom half of the cell.</P>
</DL>

It's initial setting is braille display driver dependent.</P>
<DT><B>Text Table
<A NAME="preference-text-table"></A> </B><DD><P>Select the text translation table.
See section 
<A HREF="Manual-5.html#translation-text">Text Translation</A> for details.
See the 
<A HREF="Manual-3.html#options-text-table">-t</A> command line option for the initial setting.
This preference isn't saved.
It isn't presented if the
<A HREF="Manual-2.html#build-table-selection">--disable-table-selection</A> build option was specified.</P>
<DT><B>Attributesw Table
<A NAME="preference-attributes-table"></A> </B><DD><P>Select the attributes translation table.
See section 
<A HREF="Manual-5.html#translation-attributes">Attributes Translation</A> for details.
See the 
<A HREF="Manual-3.html#options-attributes-table">-a</A> command line option for the initial setting.
This preference isn't saved.
It isn't presented if the
<A HREF="Manual-2.html#build-table-selection">--disable-table-selection</A> build option was specified.</P>
<DT><B>Contraction Table
<A NAME="preference-contraction-table"></A> </B><DD><P>Select the contraction table.
See section 
<A HREF="#contraction">Contracted Braille</A> for details.
See the 
<A HREF="Manual-3.html#options-contraction-table">-c</A> command line option for the initial setting.
This preference isn't saved.
It isn't presented if the
<A HREF="Manual-2.html#build-table-selection">--disable-table-selection</A> build option was specified.</P>
</DL>
</P>
<P>Notes:
<UL>
<LI>
<A NAME="time-settings"></A> 
All time settings are in braille window refresh intervals
(see the 
<A HREF="Manual-3.html#options-refresh-interval">-M</A> command line option).
They are integers within the range 1 through 16.</LI>
</UL>
</P>

<H2><A NAME="status"></A> <A NAME="ss4.6">4.6</A> <A HREF="Manual.html#toc4.6">The Status Display</A>
</H2>

<P>The status display is a summary of BRLTTY's current state
which fits completely within the braille window.
Some braille displays have a set of status cells
which are used to permanently display some of this information as well
(see the documentation for your display's driver).
The data presented by this display isn't static, and may change at any time
in response to screen updates and/or BRLTTY commands.</P>
<P>Use the 
<A HREF="Manual-3.html#command-INFO">INFO</A> command
to switch to the status display,
and use it again to return to the screen.
The layout of the information contained therein
is dependent on the size of the braille window.</P>

<H3>Displays with 21 Cells or More</H3>

<P>Short pneumonics have been used, even though they're rather cryptic,
in order to show the precise column layout.
<BLOCKQUOTE><CODE>
<EM>wx</EM>:<EM>wy</EM> <EM>cx</EM>:<EM>cy</EM> <EM>vt</EM> <EM>tcmfdu</EM>
</CODE></BLOCKQUOTE>

<DL>
<DT><B><EM>wx</EM><CODE>:</CODE><EM>wy</EM></B><DD><P>The column and row (counting from 0) on the screen corresponding
to the top-left corner of the braille window.</P>
<DT><B><EM>cx</EM><CODE>:</CODE><EM>cy</EM></B><DD><P>The column and row (counting from 0) on the screen corresponding
to the position of the cursor.</P>
<DT><B><EM>vt</EM></B><DD><P>The number (counting from 1) of the current virtual terminal.</P>
<DT><B><EM>t</EM></B><DD><P>The state of the cursor tracking feature
(see the 
<A HREF="Manual-3.html#command-CSRTRK">CSRTRK</A> command).
<DL>
<DT><B>blank</B><DD><P>Cursor tracking is off.</P>
<DT><B><CODE>t</CODE></B><DD><P>Cursor tracking is on.</P>
</DL>
</P>
<DT><B><EM>c</EM></B><DD><P>The state of the cursor visibility features
(see the 
<A HREF="Manual-3.html#command-CSRVIS">CSRVIS</A>
and 
<A HREF="Manual-3.html#command-CSRBLINK">CSRBLINK</A> commands).
<DL>
<DT><B>blank</B><DD><P>The cursor isn't visible, and won't blink when made visible.</P>
<DT><B><CODE>b</CODE></B><DD><P>The cursor isn't visible, and will blink when made visible.</P>
<DT><B><CODE>v</CODE></B><DD><P>The cursor is visible, and isn't blinking.</P>
<DT><B><CODE>B</CODE></B><DD><P>The cursor is visible, and is blinking.</P>
</DL>
</P>
<DT><B><EM>m</EM></B><DD><P>The current display mode
(see the 
<A HREF="Manual-3.html#command-DISPMD">DISPMD</A> command).
<DL>
<DT><B><CODE>t</CODE></B><DD><P>Screen content (text) is being displayed.</P>
<DT><B><CODE>a</CODE></B><DD><P>Screen highlighting (attributes) is being displayed.</P>
</DL>
</P>
<DT><B><EM>f</EM></B><DD><P>The state of the frozen screen feature
(see the 
<A HREF="Manual-3.html#command-FREEZE">FREEZE</A> command).
<DL>
<DT><B>blank</B><DD><P>The screen isn't frozen.</P>
<DT><B><CODE>f</CODE></B><DD><P>The screen is frozen.</P>
</DL>
</P>
<DT><B><EM>d</EM></B><DD><P>The number of braille dots being used to display each character
(see the 
<A HREF="Manual-3.html#command-SIXDOTS">SIXDOTS</A> command).
<DL>
<DT><B><CODE>8</CODE></B><DD><P>All eight dots are being used.</P>
<DT><B><CODE>6</CODE></B><DD><P>Only dots 1 through 6 are being used.</P>
</DL>
</P>
<DT><B><EM>u</EM></B><DD><P>The state of the uppercase (capital letter) display features
(see the 
<A HREF="Manual-3.html#command-CAPBLINK">CAPBLINK</A> command).
<DL>
<DT><B>blank</B><DD><P>Uppercase letters don't blink.</P>
<DT><B><CODE>B</CODE></B><DD><P>Uppercase letters blink.</P>
</DL>
</P>
</DL>
</P>

<H3>Displays with 20 Cells or Less</H3>

<P>Short pneumonics have been used, even though they're rather cryptic,
in order to show the precise column layout.
<BLOCKQUOTE><CODE>
<EM>xx</EM><EM>yy</EM><EM>s</EM> <EM>vt</EM> <EM>tcmfdu</EM>
</CODE></BLOCKQUOTE>

<DL>
<DT><B><EM>xx</EM></B><DD><P>The columns (counting from 0) on the screen corresponding
to the position of the cursor (shown in the top half of the cells)
and to the top-left corner of the braille window (shown in the bottom half of the cells).</P>
<DT><B><EM>yy</EM></B><DD><P>The rows (counting from 0) on the screen corresponding
to the position of the cursor (shown in the top half of the cells)
and to the top-left corner of the braille window (shown in the bottom half of the cells).</P>
<DT><B><EM>s</EM></B><DD><P>The settings of some of BRLTTY's features.
A feature is turned on if its corresponding dot is raised.
<DL>
<DT><B>Dot 1</B><DD><P>Frozen screen image
(see the 
<A HREF="Manual-3.html#command-FREEZE">FREEZE</A> command).</P>
<DT><B>Dot 2</B><DD><P>Display attributes
(see the 
<A HREF="Manual-3.html#command-DISPMD">DISPMD</A> command).</P>
<DT><B>Dot 3</B><DD><P>Alert tunes
(see the 
<A HREF="Manual-3.html#command-TUNES">TUNES</A> command).</P>
<DT><B>Dot 4</B><DD><P>Visible cursor
(see the 
<A HREF="Manual-3.html#command-CSRVIS">CSRVIS</A> command).</P>
<DT><B>Dot 5</B><DD><P>Block cursor
(see the 
<A HREF="Manual-3.html#command-CSRSIZE">CSRSIZE</A> command).</P>
<DT><B>Dot 6</B><DD><P>Blinking cursor
(see the 
<A HREF="Manual-3.html#command-CSRBLINK">CSRBLINK</A> command).</P>
<DT><B>Dot 7</B><DD><P>Cursor tracking
(see the 
<A HREF="Manual-3.html#command-CSRTRK">CSRTRK</A> command).</P>
<DT><B>Dot 8</B><DD><P>Sliding window
(see the 
<A HREF="Manual-3.html#command-SLIDEWIN">SLIDEWIN</A> command).</P>
</DL>
</P>
<DT><B><EM>vt</EM></B><DD><P>The number (counting from 1) of the current virtual terminal.</P>
<DT><B><EM>t</EM></B><DD><P>The state of the cursor tracking feature
(see the 
<A HREF="Manual-3.html#command-CSRTRK">CSRTRK</A> command).
<DL>
<DT><B>blank</B><DD><P>Cursor tracking is off.</P>
<DT><B><CODE>t</CODE></B><DD><P>Cursor tracking is on.</P>
</DL>
</P>
<DT><B><EM>c</EM></B><DD><P>The state of the cursor visibility features
(see the 
<A HREF="Manual-3.html#command-CSRVIS">CSRVIS</A>
and 
<A HREF="Manual-3.html#command-CSRBLINK">CSRBLINK</A> commands).
<DL>
<DT><B>blank</B><DD><P>The cursor isn't visible, and won't blink when made visible.</P>
<DT><B><CODE>b</CODE></B><DD><P>The cursor isn't visible, and will blink when made visible.</P>
<DT><B><CODE>v</CODE></B><DD><P>The cursor is visible, and isn't blinking.</P>
<DT><B><CODE>B</CODE></B><DD><P>The cursor is visible, and is blinking.</P>
</DL>
</P>
<DT><B><EM>m</EM></B><DD><P>The current display mode
(see the 
<A HREF="Manual-3.html#command-DISPMD">DISPMD</A> command).
<DL>
<DT><B><CODE>t</CODE></B><DD><P>Screen content (text) is being displayed.</P>
<DT><B><CODE>a</CODE></B><DD><P>Screen highlighting (attributes) is being displayed.</P>
</DL>
</P>
<DT><B><EM>f</EM></B><DD><P>The state of the frozen screen feature
(see the 
<A HREF="Manual-3.html#command-FREEZE">FREEZE</A> command).
<DL>
<DT><B>blank</B><DD><P>The screen isn't frozen.</P>
<DT><B><CODE>f</CODE></B><DD><P>The screen is frozen.</P>
</DL>
</P>
<DT><B><EM>d</EM></B><DD><P>The number of braille dots being used to display each character
(see the 
<A HREF="Manual-3.html#command-SIXDOTS">SIXDOTS</A> command).
<DL>
<DT><B><CODE>8</CODE></B><DD><P>All eight dots are being used.</P>
<DT><B><CODE>6</CODE></B><DD><P>Only dots 1 through 6 are being used.</P>
</DL>
</P>
<DT><B><EM>u</EM></B><DD><P>The state of the uppercase (capital letter) display features
(see the 
<A HREF="Manual-3.html#command-CAPBLINK">CAPBLINK</A> command).
<DL>
<DT><B>blank</B><DD><P>Uppercase letters don't blink.</P>
<DT><B><CODE>B</CODE></B><DD><P>Uppercase letters blink.</P>
</DL>
</P>
</DL>
</P>

<H2><A NAME="learn"></A> <A NAME="ss4.7">4.7</A> <A HREF="Manual.html#toc4.7">Command Learn Mode</A>
</H2>

<P>Command learn mode is an interactive way to learn
what the keys on the braille display do.
It can be accessed
either by the 
<A HREF="Manual-3.html#command-LEARN">LEARN</A> command
or via the 
<A HREF="Manual-2.html#utility-brltest">brltest</A> utility.
This feature isn't available if the
<A HREF="Manual-2.html#build-learn-mode">--disable-learn-mode</A> build option was specified.</P>
<P>When this mode is entered,
the message <CODE>command learn mode</CODE> is written to the braille display.
Then, as each key (or key combination) on the display is pressed,
a short message describing its BRLTTY function is written.
This mode exits immediately if the key (or key combination)
for the 
<A HREF="Manual-3.html#command-LEARN">LEARN</A> command is pressed.
It exits automatically, and the message <CODE>done</CODE> is written,
if ten seconds elapse without any key on the display being pressed.
Note that some displays don't signal the driver
and/or some drivers don't signal BRLTTY
until all the keys are released.</P>
<P>If a message is longer than the braille display is wide,
then it's displayed in segments.
The length of each segment but the last is one less than the display's width,
with the rightmost character on the display being set to a minus sign.
Each such segment remains on the display
either for a few seconds
(see the 
<A HREF="Manual-3.html#options-message-delay">-M</A> command line option)
or until any key on the display is pressed.</P>

<H2><A NAME="contraction"></A> <A NAME="ss4.8">4.8</A> <A HREF="Manual.html#toc4.8">Contracted Braille</A>
</H2>

<P>BRLTTY can display in-line contracted braille.
It does this if:
<UL>
<LI>A contraction table has been selected.
See the 
<A HREF="Manual-3.html#options-contraction-table">-c</A> command line option
and the 
<A HREF="Manual-3.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="Manual-3.html#command-SIXDOTS">SIXDOTS</A> command
and the 
<A HREF="#preference-text-style">Text Style</A> preference
for details.</LI>
</UL>

This feature isn't available if the
<A HREF="Manual-2.html#build-contracted-braille">--disable-contracted-braille</A> build option was specified.</P>
<P>The following contraction tables are provided:
<DL>
<DT><B>big5.ctb</B><DD><P>Chinese big5.</P>
<DT><B>big5</B><DD><P>Chinese</P>
<DT><B>compress</B><DD><P>Remove excessive white-space.</P>
<DT><B>en-us-g2</B><DD><P>Grade 2 American English.</P>
</DL>
</P>

<H3>File Format</H3>

<P>Blank lines are ignored.
Any leading and trailing white-space (any number of blanks and/or tabs) is ignored.
Lines which begin with a number sign (<CODE>#</CODE>) are ignored,
i.e. they're comments.
<BLOCKQUOTE><CODE>
# This is a comment.
</CODE></BLOCKQUOTE>

All other lines define table entries.</P>
<P>The general form of a table entry is an opcode followed by its operands.
The opcode and its operands are separated from one another by white-space.
Each opcode has a specific number of operands,
and any text following its last operand is treated as a comment.
<BLOCKQUOTE><CODE>
<EM>opcode</EM> <EM>operand</EM> ... <EM>comment</EM>
</CODE></BLOCKQUOTE>
</P>
<P>The opcode is a number which tells the translator how to interpret the operands.
Opcode <CODE>0</CODE> can be used to assign a meaningful name to each needed opcode,
e.g. <CODE>opcode</CODE> for <CODE>0</CODE> itself.
If, for example, a table begins with:
<BLOCKQUOTE><CODE>
0 0 opcode
</CODE></BLOCKQUOTE>

then all the rest of the opcodes it needs can be defined like this:
<BLOCKQUOTE><CODE>
opcode 1 include
</CODE></BLOCKQUOTE>

This scheme, i.e. no built-in opcode names, was chosen in order to allow
a table for some language's braille to be written solely in that language itself.</P>
<P>The following operand types are supported:
<DL>
<DT><B>string</B><DD><P>A sequence of characters other than
white-space (which terminates the string)
and backslashes (<CODE>\</CODE>).
The following special representations are also supported:
<DL>
<DT><B><CODE>\\</CODE></B><DD><P>backslash</P>
<DT><B><CODE>\f</CODE></B><DD><P>form feed</P>
<DT><B><CODE>\n</CODE></B><DD><P>new line</P>
<DT><B><CODE>\o</CODE><EM>ooo</EM></B><DD><P>3-digit octal value</P>
<DT><B><CODE>\r</CODE></B><DD><P>carriage return</P>
<DT><B><CODE>\s</CODE></B><DD><P>blank (space)</P>
<DT><B><CODE>\t</CODE></B><DD><P>horizontal tab</P>
<DT><B><CODE>\v</CODE></B><DD><P>vertical tab</P>
<DT><B><CODE>\x</CODE><EM>xx</EM></B><DD><P>2-digit hexadecimal value</P>
</DL>
</P>
<DT><B>number</B><DD><P>An integer.
It may be specified in any of the following ways:
<DL>
<DT><B>decimal</B><DD><P>A sequence of decimal digits (<CODE>0</CODE>-<CODE>9</CODE>),
with the first digit being nonzero (<CODE>1</CODE>-<CODE>9</CODE>).</P>
<DT><B>hexadecimal</B><DD><P>A sequence of hexadecimal digits (<CODE>0</CODE>-<CODE>9</CODE>, and either <CODE>a</CODE>-<CODE>f</CODE> or <CODE>A</CODE>-<CODE>F</CODE>),
preceded by either <CODE>0x</CODE> or <CODE>0X</CODE>.</P>
<DT><B>octal</B><DD><P>A sequence of octal digits (<CODE>0</CODE>-<CODE>7</CODE>),
with the first digit being zero (<CODE>0</CODE>).</P>
</DL>
</P>
<DT><B>dots</B><DD><P>A braille symbol.
The braille dots must be specified via their standard numbers
(see section 
<A HREF="Manual-8.html#dots">Braille Dot Numbering Convention</A>),
and, for a multi-cell symbol, the cell specifications
must be separated from one another by a dash (<CODE>-</CODE>).
For example, the contraction for the English word <CODE>lord</CODE>
(the letter <CODE>l</CODE> prefixed with dot 5)
would be specified as <CODE>5-123</CODE>.
A space may be specified via the special dot number <CODE>0</CODE>.</P>
</DL>
</P>

<H3><A NAME="contraction-opcode-number"></A> Opcode Summary by Number</H3>

<P>First, here's a quick summary of all of the contraction table opcodes.
For the details, see section
<A HREF="#contraction-opcode-function">Opcodes by Function</A>.
<DL>
<DT><B>
<A HREF="#contraction-opcode-0">0</A> <EM>opcode</EM> <EM>name</EM></B><DD><P>Name opcode.</P>
<DT><B>
<A HREF="#contraction-opcode-1">1</A> <EM>path</EM></B><DD><P>Include file.</P>
<DT><B>
<A HREF="#contraction-opcode-2">2</A> <EM>dots</EM></B><DD><P>Define capital sign.</P>
<DT><B>
<A HREF="#contraction-opcode-3">3</A> <EM>dots</EM></B><DD><P>Define begin capitals sign.</P>
<DT><B>
<A HREF="#contraction-opcode-4">4</A> <EM>dots</EM></B><DD><P>Define letter sign.</P>
<DT><B>
<A HREF="#contraction-opcode-5">5</A> <EM>dots</EM></B><DD><P>Define number sign.</P>
<DT><B>
<A HREF="#contraction-opcode-6">6</A> <EM>characters</EM> <EM>dots</EM></B><DD><P>Translate unconditionally.</P>
<DT><B>
<A HREF="#contraction-opcode-7">7</A> <EM>characters</EM> <EM>dots</EM></B><DD><P>Translate unconditionally, remove repetitions.</P>
<DT><B>
<A HREF="#contraction-opcode-8">8</A> <EM>characters</EM> <EM>dots</EM></B><DD><P>Translate if word.</P>
<DT><B>
<A HREF="#contraction-opcode-9">9</A> <EM>characters</EM> <EM>dots</EM></B><DD><P>Translate if at beginning of word.</P>
<DT><B>
<A HREF="#contraction-opcode-10">10</A> <EM>characters</EM> <EM>dots</EM></B><DD><P>Translate if in middle of word.</P>
<DT><B>
<A HREF="#contraction-opcode-11">11</A> <EM>characters</EM> <EM>dots</EM></B><DD><P>Translate if at end of word.</P>
<DT><B>
<A HREF="#contraction-opcode-12">12</A> <EM>characters</EM> <EM>dots</EM></B><DD><P>Translate if in middle or at end of word.</P>
<DT><B>
<A HREF="#contraction-opcode-13">13</A> <EM>characters</EM> <EM>dots</EM></B><DD><P>Translate if in middle of number.</P>
<DT><B>
<A HREF="#contraction-opcode-14">14</A> <EM>characters</EM> <EM>dots</EM></B><DD><P>Translate if white-space-bounded word.</P>
<DT><B>
<A HREF="#contraction-opcode-15">15</A> <EM>characters</EM> <EM>dots</EM></B><DD><P>Translate unconditionally, join consecutive words of this type.</P>
<DT><B>
<A HREF="#contraction-opcode-16">16</A> <EM>characters</EM> <EM>dots</EM></B><DD><P>Translate if word, join to next word.</P>
<DT><B>
<A HREF="#contraction-opcode-17">17</A> <EM>characters</EM></B><DD><P>Translate whole white-space-bounded sequence unconditionally into computer braille.</P>
<DT><B>
<A HREF="#contraction-opcode-18">18</A> <EM>characters</EM></B><DD><P>Prefix with letter sign if word.</P>
<DT><B>
<A HREF="#contraction-opcode-19">19</A> <EM>characters</EM> <EM>characters</EM></B><DD><P>Replace the first set of characters with the second.</P>
<DT><B>
<A HREF="#contraction-opcode-20">20</A> <EM>characters</EM> <EM>dots</EM></B><DD><P>Translate if at end of number.</P>
<DT><B>
<A HREF="#contraction-opcode-21">21</A> <EM>characters</EM> <EM>dots</EM></B><DD><P>Translate if at beginning of number.</P>
<DT><B>
<A HREF="#contraction-opcode-22">22</A> <EM>characters</EM> <EM>dots</EM></B><DD><P>Translate if part of leading punctuation.</P>
<DT><B>
<A HREF="#contraction-opcode-23">23</A> <EM>characters</EM> <EM>dots</EM></B><DD><P>Translate if part of trailing punctuation.</P>
<DT><B>
<A HREF="#contraction-opcode-24">24</A> <EM>characters</EM> <EM>dots</EM></B><DD><P>Translate if word or at beginning of word.</P>
<DT><B>
<A HREF="#contraction-opcode-25">25</A> <EM>dots</EM></B><DD><P>Define end capitals sign.</P>
<DT><B>
<A HREF="#contraction-opcode-26">26</A> <EM>locale</EM></B><DD><P>Define locale.</P>
</DL>
</P>

<H3><A NAME="contraction-opcode-function"></A> Opcodes by Function</H3>

<P>Now for all of the details.
The opcodes here are grouped by function rather than sorted by number.
For a numerically sorted list, see section
<A HREF="#contraction-opcode-number">Opcode Summary by Number</A>.</P>

<H3>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>0 <EM>opcode</EM> <EM>name</EM>
<A NAME="contraction-opcode-0"></A> </B><DD><P>Assign a name to an opcode.
The name must be defined before it's used.</P>
<DT><B>1 <EM>path</EM>
<A NAME="contraction-opcode-1"></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>26 <EM>locale</EM>
<A NAME="contraction-opcode-26"></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>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>2 <EM>dots</EM>
<A NAME="contraction-opcode-2"></A> </B><DD><P>The symbol which capitalizes a single letter.</P>
<DT><B>3 <EM>dots</EM>
<A NAME="contraction-opcode-3"></A> </B><DD><P>The symbol which begins a block of capital letters within a word.</P>
<DT><B>25 <EM>dots</EM>
<A NAME="contraction-opcode-25"></A> </B><DD><P>The symbol which ends a block of capital letters within a word.</P>
<DT><B>4 <EM>dots</EM>
<A NAME="contraction-opcode-4"></A> </B><DD><P>The symbol which marks a letter which isn't part of a word.</P>
<DT><B>5 <EM>dots</EM>
<A NAME="contraction-opcode-5"></A> </B><DD><P>The symbol which marks the beginning of a number.</P>
</DL>
</P>

<H3>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="Manual-3.html#options-text-table">-t</A> command line option
and the 
<A HREF="Manual-3.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-6">opcode 6</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>17 <EM>characters</EM>
<A NAME="contraction-opcode-17"></A> </B><DD><P>Translate the entire white-space-bounded containing character sequence into computer braille
(see the 
<A HREF="Manual-3.html#options-text-table">-t</A> command line option
and the 
<A HREF="Manual-3.html#configure-text-table">text-table</A> configuration file directive).</P>
<DT><B>19 <EM>characters</EM> <EM>characters</EM>
<A NAME="contraction-opcode-19"></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>6 <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-6"></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>7 <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-7"></A> </B><DD><P>Translate the characters no matter where they appear.
Ignore any consecutive repetitions of the same sequence.</P>
<DT><B>15 <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-15"></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>8 <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-8"></A> </B><DD><P>Translate the characters if they're a word.</P>
<DT><B>16 <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-16"></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>14 <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-14"></A> </B><DD><P>Translate the characters if they're a white-space-bounded word.</P>
<DT><B>18 <EM>characters</EM>
<A NAME="contraction-opcode-18"></A> </B><DD><P>Prefix the characters with a letter sign
(see 
<A HREF="#contraction-opcode-4">opcode 4</A>)
if they're a word.</P>
<DT><B>24 <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-24"></A> </B><DD><P>Translate the characters if they're either a word or at the beginning of a word.</P>
<DT><B>9 <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-9"></A> </B><DD><P>Translate the characters if they're at the beginning of a word.</P>
<DT><B>10 <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-10"></A> </B><DD><P>Translate the characters if they're in the middle of a word.</P>
<DT><B>12 <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-12"></A> </B><DD><P>Translate the characters if they're either in the middle or at the end of a word.</P>
<DT><B>11 <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-11"></A> </B><DD><P>Translate the characters if they're at the end of a word.</P>
<DT><B>22 <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-22"></A> </B><DD><P>Translate the characters if they're part of punctuation at the beginning of a word.</P>
<DT><B>23 <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-23"></A> </B><DD><P>Translate the characters if they're part of punctuation at the end of a word.</P>
<DT><B>21 <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-21"></A> </B><DD><P>Translate the characters if they're at the beginning of a number.</P>
<DT><B>13 <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-13"></A> </B><DD><P>Translate the characters if they're in the middle of a number.</P>
<DT><B>20 <EM>characters</EM> <EM>dots</EM>
<A NAME="contraction-opcode-20"></A> </B><DD><P>Translate the characters if they're at the end of a number.</P>
</DL>
</P>

<HR>
<A HREF="Manual-5.html">Next</A>
<A HREF="Manual-3.html">Previous</A>
<A HREF="Manual.html#toc4">Contents</A>
</BODY>
</HTML>