Sophie: brltty-4.2-3.fc14 x86

brltty-4.2-3.fc14.x86_64.rpm

BRLTTY Reference Manual
Access to the Console Screen for Blind Persons using
Refreshable Braille Displays
Nikhil Nair <nn201@cus.cam.ac.uk>

Nicolas Pitre <nico@fluxnic.net>

Stéphane Doyon <s.doyon@videotron.ca>

Dave Mielke <dave@mielke.cc>

Version 4.2, May 2010

Copyright © 1995-2010 by The BRLTTY Developers. BRLTTY is free soft-
ware, and comes with ABSOLUTELY NO WARRANTY. It is placed under the
terms of version 2 or later of TThhee GGNNUU GGeenneerraall PPuubblliicc LLiicceennssee as pub-
lished by TThhee FFrreeee SSooffttwwaarree FFoouunnddaattiioonn.

______________________________________________________________________

Table of Contents

1. Formalities
1.1 License
1.2 Disclaimer
1.3 Contact Information

2. Introduction
2.1 Feature Summary
2.2 System Requirements

3. The Build Procedure
3.1 Installed File Hierarchy
3.2 Installing from a TAR Ball
3.2.1 Build Options
3.2.1.1 System Defaults
3.2.1.2 Directory Specification
3.2.1.3 Build Features
3.2.1.4 Miscellaneous Options
3.2.2 Make File Targets
3.3 Testing BRLTTY
3.4 Starting BRLTTY
3.5 Security Considerations
3.6 Build and Run-Time Restrictions
3.7 Installing from an RPM File
3.8 Other Utilities
3.8.1 brltty-config
3.8.2 brltty-install
3.8.3 brltest
3.8.4 spktest
3.8.5 scrtest
3.8.6 ttbtest
3.8.7 ctbtest
3.8.8 tunetest

4. Using BRLTTY
4.1 Commands
4.1.1 Vertical Motion
4.1.2 Horizontal Motion
4.1.3 Implicit Motion
4.1.4 Feature Activation
4.1.5 Mode Selection
4.1.6 Preference Maintenance
4.1.7 Menu Navigation
4.1.8 Speech Controls
4.1.9 Virtual Terminal Switching
4.1.10 Other Commands
4.1.11 Character Commands
4.1.12 Base Commands
4.2 The Configuration File
4.3 Command Line Options

5. Feature Descriptions
5.1 Cursor Routing
5.2 Cut and Paste
5.3 Pointer (Mouse) Support via GPM
5.4 Alert Tunes
5.5 Preferences Settings
5.5.1 The Preferences Menu
5.5.1.1 Navigating the Menu
5.5.1.2 The Menu Items
5.6 The Status Display
5.6.1 Displays with 21 Cells or More
5.6.2 Displays with 20 Cells or Less
5.7 Command Learn Mode

6. Tables
6.1 Text Tables
6.1.1 Text Table Format
6.1.2 Text Table Directives
6.2 Attributes Tables
6.2.1 Attributes Table Format
6.2.2 Attributes Table Directives
6.3 Contraction Tables
6.3.1 Contraction Table Format
6.3.2 Contraction Table Operands
6.3.3 Opcodes
6.3.3.1 Table Administration
6.3.3.2 Special Symbol Definition
6.3.3.3 Character Translation
6.3.3.4 Character Classes
6.4 Key Tables
6.4.1 Key Table Directives
6.4.1.1 The Assign Directive
6.4.1.2 The Bind Directive
6.4.1.3 The Context Directive
6.4.1.4 The Hide Directive
6.4.1.5 The Hotkey Directive
6.4.1.6 The IfKey Directive
6.4.1.7 The Include Directive
6.4.1.8 The Map Directive
6.4.1.9 The Note Directive
6.4.1.10 The Superimpose Directive
6.4.1.11 The Title Directive
6.4.2 Keyboard Properties

7. Advanced Topics
7.1 Installing Multiple Versions
7.2 Installation/Rescue Root Disks for Linux
7.3 Future Enhancements
7.4 Known Bugs

A. Supported Braille Displays
B. Supported Speech Synthesizers
C. Driver Identification Codes
D. Supported Screen Drivers
E. Operand Syntax
E.1 Driver Specificationn
E.2 Braille Device Specificationn
E.3 PCM Device Specificationn
E.4 MIDI Device Specificationn

F. Standard Braille Dot Numbering Convention
G. North American Braille Computer Code
H. MIDI Instrument Table

______________________________________________________________________

11.. FFoorrmmaalliittiieess

11..11.. LLiicceennssee

This program is free software. You may redistribute it and/or modify
it under the terms of The GNU General Public License as published by
The Free Software Foundation. Version 2 (or any later version) of the
license may be used.

You should have received a copy of the license along with this
program. It should be in the file LICENSE-GPL in the top-level
directory. If not, write to the Free Software Foundation Inc., 675
Mass Ave, Cambridge, MA 02139, USA.

11..22.. DDiissccllaaiimmeerr

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY - not even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GGNNUU
GGeenneerraall PPuubblliicc LLiicceennssee for more details.

11..33.. CCoonnttaacctt IInnffoorrmmaattiioonn

BRLTTY represents the work of a team. For up-to-date information, see
BRLTTY's web page at [http://mielke.cc/brltty/]. As of this writing,
the team includes:

· Dave Mielke <dave@mielke.cc> (current maintainer, active developer)

· Nicolas Pitre <nico@fluxnic.net> (active developer)

· Stéphane Doyon <s.doyon@videotron.ca> (active developer)

· Nikhil Nair <nn201@cus.cam.ac.uk> (original author, no longer
active)

Comments, suggestions, criticisms, and contributions are all welcome.
We'll try to respond promptly to all (sensible) mail, but give no
guarantee. In general, we recommend that you send e-mail messages to
all active developers. If you have a question about a particular type
of display supported by BRLTTY, you may wish to contact the author of
its driver (see the README file in its subdirectory for details).

22.. IInnttrroodduuccttiioonn

BRLTTY gives a braille user access to the text consoles of a
Linux/Unix system. It runs as a background process (daemon) which
operates a refreshable braille display, and can be started very early
in the system boot sequence. It enables a braille user, therefore, to
easily independently handle aspects of system administration such as
single user mode entry, file system recovery, and boot problem
analysis. It even greatly eases such routine tasks as logging in.

BRLTTY reproduces a rectangular portion of the screen (referred to
within this document as `the window') as braille text on the display.
Controls on the display can be used to move the window around on the
screen, to enable and disable various viewing options, and to perform
special functions.

22..11.. FFeeaattuurree SSuummmmaarryy

BRLTTY provides the following capabilities:

· Full implementation of the usual screen review facilities.

· Choice between block, underline, or no cursor.

· Optional underline to indicate specially highlighted text.

· Optional use of blinking (rates individually settable) for cursor,
special highlighting underline, and/or capital letters.

· Screen freezing for leisurely review.

· Intelligent cursor routing, allowing easy fetching of cursor within
text editors, web browsers, etc., without moving ones hands from
the braille display.

· A cut-and-paste function (linear or rectangular) which is
particularly useful for copying long file names, copying text
between virtual terminals, entering complicated commands, etc.

· Table driven in-line contracted braille (English and French
provided).

· Support for multiple braille codes.

· Ability to identify an unknown character.

· Ability to inspect character highlighting.

· An on-line help facility for braille display commands.

· A preferences menu.

· Basic speech support.

· Modular design allowing relatively easy addition of drivers for
other braille displays and speech synthesizers.

· An Application Programming Interface.

22..22.. SSyysstteemm RReeqquuiirreemmeennttss

To date, BRLTTY runs under Linux, Solaris, OpenBSD, FreeBSD, NetBSD,
and Windows. While ports to other Unix-like operating systems aren't
currently planned, we do welcome any interest in such projects.

LLiinnuuxx
This software has been tested on a variety of Linux systems:

· Desktops, laptops, and some PDAs.

· Processors from a 386SX20 to a Pentium.

· A huge range of memory sizes.

· Several distributions including Debian, Red Hat, Slackware,
and SuSE.

· Many kernels, including 1.2.13, 2.0, 2.2, and 2.4.

SSoollaarriiss
This software has been tested on the following Solaris systems:

· The Sparc architecture (releases 7, 8, and 9).

· The Intel architecture (release 9).

OOppeennBBSSDD
This software has been tested on the following OpenBSD systems:

· The Intel architecture (release 3.4).

FFrreeeeBBSSDD
This software has been tested on the following FreeBSD systems:

· The Intel architecture (release 5.1).

NNeettBBSSDD
This software has been tested on the following NetBSD systems:

· The Intel architecture (release 1.6).

WWiinnddoowwss
This software has been tested on Windows 95, 98, and XP.

On Linux, BRLTTY can inspect the content of the screen completely
independently of any logged in user. It does this by using a special
device which provides easy access to the contents of the current
virtual console. This device was introduced in version 1.1.92 of the
Linux kernel, and is normally called either /dev/vcsa or /dev/vcsa0
(on systems with devfs it's called /dev/vcc/a). For this reason,
Linux kernel 1.1.92 or later is required if BRLTTY is to be used in
this way. This capability:

· Allows BRLTTY to be started very early in the system boot sequence.

· Enables the braille display to be fully operational during the
login prompt.

· Makes it much easier for a braille user to perform boot-time system
administration tasks.

A patch for the screen program is provide (see the Patches
subdirectory). It allows BRLTTY to access screen's screen image via
shared memory, and, therefore, allows BRLTTY to be used quite
effectively on platforms which don't have their own screen content
inspection facility. The main weakness of the screen approach is that
BRLTTY can't be started until the user has logged in.

BRLTTY only works with text-based consoles and applications. It can
be used with curses-based applications, but not with any application
which either uses special VGA features or requires a graphics console
(like the X Window system).

You must also, of course, possess a supported refreshable braille
display (see section ``Supported Braille Displays'' for the complete
list). We hope that additional displays will be supported in the
future, so, if you have any vaguely technical programming information
for a device which you'd like to see supported, then please let us
know (see section ``Contact Information'').

Finally, you need tools to build the executable from its source: make,
C and C++ compilers, yacc, awk, etc. The development tools provided
with standard Unix distributions should suffice. If you have
problems, then contact us and we'll compile a binary for you.

33.. TThhee BBuuiilldd PPrroocceedduurree

BRLTTY can be downloaded from its web site (see section ``Contact
Information'' for its location). All releases are provided as
compressed ``tar balls''. Newer releases are also provided as ``RPM''
(RedHat Package Manager) files.

That tidbit of information has probably peaked your curiosity, and now
you just can't wait to get started. It's a good idea, though, to
first become familiar with the files which will ultimately be
installed.

33..11.. IInnssttaalllleedd FFiillee HHiieerraarrcchhyy

The build procedure should result in the installation of the following
files:

//bbiinn//

bbrrllttttyy
The BRLTTY program.

````bbrrllttttyy--iinnssttaallll''''
A utility for copying BRLTTY's ``installed file hierarchy''
from one location to another.

````bbrrllttttyy--ccoonnffiigg''''
A utility which sets a number of environment variables to
values which reflect the current installation of BRLTTY.

//lliibb//

lliibbbbrrllaappii..aa
Static archive of the Application Programming Interface.

lliibbbbrrllaappii..ssoo
Dynamically loadable object for the Application Programming
Interface.

//lliibb//bbrrllttttyy//
Your installation of BRLTTY may not have all of the following
types of files. They're only created as needed based on the
build options you select (see ``Build Options'').

bbrrllttttyy--bbrrll..llsstt
A list of the braille display drivers which have been built
as dynamically loadable shared objects, and, therefore, which
can be selected at run-time. Each line consists of the two-
letter identification code for a driver, a tab character, and
a description of the braille display which that driver is
for.

lliibbbbrrllttttyybb_d_r_i_v_e_r..ssoo..11
The dynamically loadable driver for a braille display, where
_d_r_i_v_e_r is the two-letter ``driver identification code''.

bbrrllttttyy--ssppkk..llsstt
A list of the speech synthesizer drivers which have been
built as dynamically loadable shared objects, and, therefore,
which can be selected at run-time. Each line consists of the
two-letter identification code for a driver, a tab character,
and a description of the speech synthesizer which that driver
is for.

lliibbbbrrllttttyyss_d_r_i_v_e_r..ssoo..11
The dynamically loadable driver for a speech synthesizer,
where _d_r_i_v_e_r is the two-letter ``driver identification
code''.

//lliibb//bbrrllttttyy//rrww//
Files created at run-time, e.g. needed but missing system
resources.

//eettcc//

bbrrllttttyy..ccoonnff
System defaults for BRLTTY.

bbrrllaappii..kkeeyy
The access key for BrlAPI.

//eettcc//bbrrllttttyy//
Your installation of BRLTTY may not have all of the following
types of files. They're only created as needed based on the
build options you select (see ``Build Options'').

**..ccoonnff
Driver-specific configuration data. Their names look more or
less like brltty-_d_r_i_v_e_r.conf, where _d_r_i_v_e_r is the two-letter
``driver identification code''.

**..aattbb
Attributes tables (see section ``Attributes Tables'' for
details). Their names look like _n_a_m_e.atb.

**..aattii
Include files for attributes tables.

**..ccttbb
Contraction tables (see section ``Contraction Tables'' for
details). Their names look like _l_a_n_g_u_a_g_e-_c_o_u_n_t_r_y-_l_e_v_e_l.ctb.

**..ccttii
Include files for contraction tables.

**..kkttbb
Key tables (see section ``Key Tables'' for details). Their
names look like _n_a_m_e.ktb.

**..kkttii
Include files for key tables.

**..ttttbb
Text tables (see section ``Text Tables'' for details). Their
names look like _l_a_n_g_u_a_g_e.ttb.

**..ttttii
Include files for text tables.

**..hhllpp
Driver-specific help pages. Their names look more or less
like brltty-_d_r_i_v_e_r.hlp, where _d_r_i_v_e_r is the two-letter
``driver identification code''.

//vvaarr//lliibb//BBrrllAAPPII//
Local sockets for connecting to the Application Programming
Interface.

//iinncclluuddee//
C header files for the Application Programming Interface. Their
names look like brlapi-_f_u_n_c_t_i_o_n.h. The main header is brlapi.h.

//iinncclluuddee//bbrrllttttyy//
C header files for accessing braille hardware. Their names look
like brldefs-_d_r_i_v_e_r.h (where _d_r_i_v_e_r is the two-letter ``driver
identification code''). The headers brldefs.h and api.h are
provided for backward compatibility and shouldn't be used.

//mmaann//
Man pages.

mmaann11//_n_a_m_e..11
Man pages for BRLTTY-related user commands.

mmaann33//_n_a_m_e..33
Man pages for Application Programming Interface library
routines.

Some optional files which you should be aware of, although they aren't
part of the installed file hierarchy, are:

//eettcc//bbrrllttttyy..ccoonnff
The system defaults configuration file. It's created by the
system administrator. See ``The Configuration File'' for
details.

//eettcc//bbrrllttttyy--_d_r_i_v_e_r..pprreeffss
The saved preferences settings file (_d_r_i_v_e_r is a two-letter
``driver identification code''). It's created by the
``PREFSAVE'' command. See ``Preferences Settings'' for details.

33..22.. IInnssttaalllliinngg ffrroomm aa TTAARR BBaallll

Here's what to do if you just want to install BRLTTY as quickly as
possible, trusting that all of our defaults are correct.

1. Download the source. It'll be a file named brltty-_r_e_l_e_a_s_e.tar.gz,
e.g. brltty-3.0.tar.gz.

2. Unpack the source into its native hierarchical structure.

tar xzf brltty-_r_e_l_e_a_s_e.tar.gz

This should create the directory brltty-_r_e_l_e_a_s_e.

3. Change to the source directory, configure, compile, and install
BRLTTY.

cd brltty-_r_e_l_e_a_s_e
./configure
make install

This should be done as rroooott.

To uninstall BRLTTY, do:

cd brltty-_r_e_l_e_a_s_e
make uninstall

That's all there's to it. Now, for those who really want to know
what's going on, here are the details.

33..22..11.. BBuuiilldd OOppttiioonnss

The first step in building BRLTTY is to configure it for your system
and/or for your personal needs. This is done by running the configure
script in BRLTTY's top-level directory. We've tried to make the
defaults fit the most common case, so, assuming that you're not
attempting to do anything out of the ordinary, you may not need to do
anything more complicated than invoke this script without specifying
any options at all.

./configure

If, however, you have some special requirements, or even if you're
just adventurous, you should find out what your choices are.

./configure --help

You should also check out the README file in the subdirectory contain-
ing the driver for your braille display for any additional display-
specific instructions.

33..22..11..11.. SSyysstteemm DDeeffaauullttss

--with-braille-driver=_d_r_i_v_e_r
Specify the braille display drivers which are to be linked into
the BRLTTY binary. Those drivers which aren't listed via this
option are built as dynamically loadable shared objects and can
still be selected at run-time. Each driver must be identified
either by its two-letter ``driver identification code'' or by
its proper name (full or abbreviated). The driver identifiers
must be separated from one another by a single comma. If a
driver identifier is prefixed by a minus sign (-), then that
driver is excluded from the build. Any of the following words
can also be used as the operand of this option:

aallll
Link all of the drivers into the binary. Don't build any of
them as dynamically loadable shared objects. This word may
also be specified as the final element of a driver list.
This is how to specify the dfault driver when all the drivers
are to be linked in.

--aallll
Only build those drivers which have been explicitly included
via this option.

nnoo Don't build any drivers at all. This is equivalent to
specifying --without-braille-driver.

yyeess
Build all of the drivers as dynamically loadable shared
objects. Don't link any of them into the binary. This is
equivalent to specifying --with-braille-driver.

See the ``braille-driver'' configuration file directive and the
``-b'' command line option for run-time selection.

--with-braille-parameters=[_d_r_i_v_e_r:]_n_a_m_e=_v_a_l_u_e,...
Specify the default parameter settings for the braille display
drivers. If the same parameter is specified more than once,
then its rightmost assignment is used. If a parameter name is
qualified by a driver (see section ``Driver Identification
Codes'') then that setting only applies to that driver; if it
isn't then it applies to all drivers. For a description of the
parameters accepted by a specific driver, please see the
documentation for that driver. See the ``braille-parameters''
configuration file directive and the ``-B'' command line option
for run-time selection.

--with-braille-device=_d_e_v_i_c_e,...
Specify the default device to which the braille display is
connected (see section ``Braille Device Specification''). If
this option isn't specified, then usb: is assumed if USB support
is available, and an operating system appropriate path for the
primary (first) serial port (device) is assumed if not. See the
``braille-device'' configuration file directive and the ``-d''
command line option for run-time selection.

--with-libbraille=_d_i_r_e_c_t_o_r_y
Specify the installed location of the Libbraille package, and
build the Libbraille braille display driver (see ``Build
Restrictions''). Any of the following words can also be used as
the operand of this option:

nnoo Don't build the driver. This is equivalent to specifying
--without-libbraille.
yyeess
Build the driver if the package can be found in /usr,
/usr/local, /usr/local/Libbraille, /usr/local/libbraille,
/opt/Libbraille, or /opt/libbraille. This is equivalent to
specifying --with-libbraille.

--with-text-table=_f_i_l_e
Specify the built-in (fallback) text table (see section ``Text
Tables'' for details). The specified table is linked into the
BRLTTY binary, and is used either if locale-based autoselection
fails or if the requested table can't be loaded. The absolute
path to a table outside the source tree may be specified. The
.ttb extension is optional. If this option isn't specified,
then en-nabcc, a commonly (in North America) used 8-dot variant
of the ``North American Braille Computer Code'', is assumed.
See the ``text-table'' configuration file directive and the
``-t'' command line option for run-time selection. This setting
can be changed with the ``Text Table'' preference.

--with-attributes-table=_f_i_l_e
Specify the built-in (fallback) attributes table (see section
``Attributes Translation'' for details). The specified table is
linked into the BRLTTY binary, and is used if the requested
table can't be loaded. The absolute path to a table outside the
source tree may be specified. The .atb extension is optional.
If this option isn't specified, then attributes is assumed.
Change it to attrib if you'd like it done the old way. See the
``attributes-table'' configuration file directive and the ``-a''
command line option for run-time selection. This setting can be
changed with the ``Attributes Table'' preference.

--with-speech-driver=_d_r_i_v_e_r
Specify the speech synthesizer drivers which are to be linked
into the BRLTTY binary. Those drivers which aren't listed via
this option are built as dynamically loadable shared objects and
can still be selected at run-time. Each driver must be
identified either by its two-letter ``driver identification
code'' or by its proper name (full or abbreviated). The driver
identifiers must be separated from one another by a single
comma. If a driver identifier is prefixed by a minus sign (-),
then that driver is excluded from the build. Any of the
following words can also be used as the operand of this option:

--aallll
Only build those drivers which have been explicitly included
via this option.

nnoo Don't build any drivers at all. This is equivalent to
specifying --without-speech-driver.

yyeess
Build all of the drivers as dynamically loadable shared
objects. Don't link any of them into the binary. This is
equivalent to specifying --with-speech-driver.

See the ``speech-driver'' configuration file directive and the
``-s'' command line option for run-time selection.

--with-speech-parameters=[_d_r_i_v_e_r:]_n_a_m_e=_v_a_l_u_e,...
Specify the default parameter settings for the speech
synthesizer drivers. If the same parameter is specified more
than once, then its rightmost assignment is used. If a
parameter name is qualified by a driver (see section ``Driver
Identification Codes'') then that setting only applies to that
driver; if it isn't then it applies to all drivers. For a
description of the parameters accepted by a specific driver,
please see the documentation for that driver. See the ``speech-
parameters'' configuration file directive and the ``-S'' command
line option for run-time selection.

--with-flite=_d_i_r_e_c_t_o_r_y
Specify the installed location of the FestivalLite text-to-
speech package, and build the FestivalLite speech synthesizer
driver (see ``Build Restrictions''). Any of the following words
can also be used as the operand of this option:

nnoo Don't build the driver. This is equivalent to specifying
--without-flite.

yyeess
Build the driver if the package can be found in /usr,
/usr/local, /usr/local/FestivalLite, /usr/local/flite,
/opt/FestivalLite, or /opt/flite. This is equivalent to
specifying --with-flite.

--with-flite-language=_l_a_n_g_u_a_g_e
Specify the language which the FestivalLite text to speech
engine is to use. The default language is usenglish.

--with-flite-lexicon=_l_e_x_i_c_o_n
Specify the lexicon which the FestivalLite text to speech engine
is to use. The default lexicon is cmulex.

--with-flite-voice=_v_o_i_c_e
Specify the voice which the FestivalLite text to speech engine
is to use. The default voice is cmu_us_kal16.

--with-mikropuhe=_d_i_r_e_c_t_o_r_y
Specify the installed location of the Mikropuhe text-to-speech
package, and build the Mikropuhe speech synthesizer driver (see
``Build Restrictions''). Any of the following words can also be
used as the operand of this option:

nnoo Don't build the driver. This is equivalent to specifying
--without-mikropuhe.

yyeess
Build the driver if the package can be found in /usr,
/usr/local, /usr/local/Mikropuhe, /usr/local/mikropuhe,
/opt/Mikropuhe, or /opt/mikropuhe. This is equivalent to
specifying --with-mikropuhe.

--with-speechd=_d_i_r_e_c_t_o_r_y
Specify the installed location of the speech-dispatcher text-to-
speech package, and build the speech-dispatcher speech
synthesizer driver. Any of the following words can also be used
as the operand of this option:

nnoo Don't build the driver. This is equivalent to specifying
--without-speechd.

yyeess
Build the driver if the package can be found in /usr,
/usr/local, /usr/local/speech-dispatcher, /usr/local/speechd,
/opt/speech-dispatcher, or /opt/speechd. This is equivalent
to specifying --with-speechd.

--with-swift=_d_i_r_e_c_t_o_r_y
Specify the installed location of the Swift text-to-speech
package, and build the Swift speech synthesizer driver. Any of
the following words can also be used as the operand of this
option:

nnoo Don't build the driver. This is equivalent to specifying
--without-swift.

yyeess
Build the driver if the package can be found in /usr,
/usr/local, /usr/local/Swift, /usr/local/swift, /opt/Swift,
or /opt/swift. This is equivalent to specifying --with-
swift.

--with-theta=_d_i_r_e_c_t_o_r_y
Specify the installed location of the Theta text-to-speech
package, and build the Theta speech synthesizer driver (see
``Build Restrictions''). Any of the following words can also be
used as the operand of this option:

nnoo Don't build the driver. This is equivalent to specifying
--without-theta.

yyeess
Build the driver if the package can be found in /usr,
/usr/local, /usr/local/Theta, /usr/local/theta, /opt/Theta,
or /opt/theta. This is equivalent to specifying --with-
theta.

--with-viavoice=_d_i_r_e_c_t_o_r_y
Specify the installed location of the ViaVoice text-to-speech
package, and build the ViaVoice speech synthesizer driver (see
``Build Restrictions''). Any of the following words can also be
used as the operand of this option:

nnoo Don't build the driver. This is equivalent to specifying
--without-viavoice.

yyeess
Build the driver if the package can be found in /usr,
/usr/local, /usr/local/ViaVoice, /usr/local/viavoice,
/opt/ViaVoice, or /opt/viavoice. This is equivalent to
specifying --with-viavoice.

--with-screen-driver=_d_r_i_v_e_r
Specify the screen drivers which are to be linked into the
BRLTTY binary. Those drivers which aren't listed via this
option are built as dynamically loadable shared objects and can
still be selected at run-time. Each driver must be identified
either by its two-letter driver identification code (see section
``Supported Screen Drivers'') or by its proper name (full or
abbreviated). The driver identifiers must be separated from one
another by a single comma. If a driver identifier is prefixed
by a minus sign (-), then that driver is excluded from the
build. Any of the following words can also be used as the
operand of this option:

--aallll
Only build those drivers which have been explicitly included
via this option.

nnoo Don't build any drivers at all. This is equivalent to
specifying --without-screen-driver.

yyeess
Build all of the drivers as dynamically loadable shared
objects. Don't link any of them into the binary. This is
equivalent to specifying --with-screen-driver.

The first non-excluded driver becomes the default driver. If
this option isn't specified, or if no drivdr is specifically
included, then an operating system appropriate default is
selected. If a native driver for the current operating system
is available, then that driver is selected; if not, then sc is
selected. See the ``screen-driver'' configuration file direc-
tive and the ``-x'' command line option for run-time selection.

--with-screen-parameters=[_d_r_i_v_e_r:]_n_a_m_e=_v_a_l_u_e,...
Specify the default parameter settings for the screen drivers.
If the same parameter is specified more than once, then its
rightmost assignment is used. If a parameter name is qualified
by a driver (see section ``Supported Screen Drivers'') then that
setting only applies to that driver; if it isn't then it applies
to all drivers. For a description of the parameters accepted by
a specific driver, please see the documentation for that driver.
See the ``screen-parameters'' configuration file directive and
the ``-X'' command line option for run-time selection.

--with-usb-package=_p_a_c_k_a_g_e,...
Specify the package which is to be used for USB I/O. The
package names must be separated from one another by a single
comma, and are processed from left to right. The first one
which is installed on the system is selected. The following
packages are supported:

1. libusb

2. libusb-1.0

Any of the following words can also be used as the operand of
this option:

nnoo Don't support USB I/O. This is equivalent to specifying
--without-usb-package.

yyeess
Use native support for USB I/O. If native support isn't
available for the current platform then use the first
available supported package (as per the order specified
above). This is equivalent to specifying --with-usb-package.

--with-bluetooth-package=_p_a_c_k_a_g_e,...
Specify the package which is to be used for Bluetooth I/O. The
package names must be separated from one another by a single
comma, and are processed from left to right. The first one
which is installed on the system is selected. The following
packages are supported:

1. (no packages are currently supported)

Any of the following words can also be used as the operand of
this option:

nnoo Don't support Bluetooth I/O. This is equivalent to
specifying --without-bluetooth-package.

yyeess
Use native support for Bluetooth I/O. If native support
isn't available for the current platform then use the first
available supported package (as per the order specified
above). This is equivalent to specifying --with-bluetooth-
package.

33..22..11..22.. DDiirreeccttoorryy SSppeecciiffiiccaattiioonn

--with-execute-root=_d_i_r_e_c_t_o_r_y
Specify the directory at which the ``installed file hierarchy''
is to be rooted at run-time. The absolute path should be
supplied. If this option isn't specified, then the system's
root directory is assumed. Use this option if you need to
install BRLTTY's run-time files in a non-standard location. You
need to use this feature, for example, if you'd like to have
more than one version of BRLTTY installed at the same time (see
section ``Installing Multiple Versions'' for an example of how
to do this).

--with-install-root=_d_i_r_e_c_t_o_r_y
Specify the directory beneath which the ``installed file
hierarchy'' is to be installed. The absolute path should be
supplied. If this option isn't specified, then the run-time
package root (see the ``--with-execute-root'' build option) is
assumed. This directory is only used by ``make install'' and
``make uninstall''. Use this option if you need to install
BRLTTY in a different location than the one from which it'll
ultimately be executed. You need to use this feature, for
example, if you're building BRLTTY on one system for use on
another.

--prefix=_d_i_r_e_c_t_o_r_y
Specify the directory within the ``installed file hierarchy''
where the default directories for the architecture-independent
files are to be rooted. These directories include:

· the ``writable directory''

· the ``data directory''

· the ``configuration directory''

· the ``manpage directory''

· the ``include directory''

The absolute path should be supplied. If this option isn't
specified, then the system's root directory is assumed. This
directory is rooted at the directory specified by the ``--with-
execute-root'' build option.

--exec-prefix=_d_i_r_e_c_t_o_r_y
Specify the directory within the ``installed file hierarchy''
where the default directories for the architecture-dependent
files are to be rooted. These directories include:

· the ``program directory''

· the ``library directory''

· the ``API directory''

The absolute path should be supplied. If this option isn't
specified, then the directory specified via the ``--prefix''
build option is assumed. This directory is rooted at the direc-
tory specified by the ``--with-execute-root'' build option.

--libdir=_d_i_r_e_c_t_o_r_y
Specify the directory within the ``installed file hierarchy''
where the static archive and the dynamically loadable object for
the Application Programming Interface are to be installed. The
absolute path should be supplied. If this option isn't
specified, then the directory specified via the standard
configure option --libdir (which defaults to /lib rooted at the
directory specified by the ``--exec-prefix'' build option) is
assumed. The directory is created if it doesn't exist.

--sysconfdir=_d_i_r_e_c_t_o_r_y
Specify the directory within the ``installed file hierarchy''
where the configuration files are to be installed. The absolute
path should be supplied. If this option isn't specified, then
the directory specified via the standard configure option
--sysconfdir (which defaults to /etc rooted at the directory
specified by the ``--prefix'' build option) is assumed. The
directory is created if it doesn't exist.

--with-program-directory=_d_i_r_e_c_t_o_r_y
Specify the directory within the ``installed file hierarchy''
where the runnable programs (binaries, executables) are to be
installed. The absolute path should be supplied. If this
option isn't specified, then the directory specified via the
standard configure option --bindir (which defaults to /bin
rooted at the directory specified by the ``--exec-prefix'' build
option) is assumed. The directory is created if it doesn't
exist.

--with-library-directory=_d_i_r_e_c_t_o_r_y
Specify the directory within the ``installed file hierarchy''
where the drivers and other architecture-dependent files are to
be installed. The absolute path should be supplied. If this
option isn't specified, then the brltty subdirectory of the
directory specified via the standard configure option --libdir
(which defaults to /lib rooted at the directory specified by the
``--exec-prefix'' build option) is assumed. The directory is
created if it doesn't exist.

--with-writable-directory=_d_i_r_e_c_t_o_r_y
Specify the directory within the ``installed file hierarchy''
which may be written to. The absolute path should be supplied.
Any of the following words can also be used as the operand of
this option:

nnoo Don't define a writable directory. This is equivalent to
specifying --without-writable-directory.

yyeess
Use the default location. This is equivalent to specifying
--with-writable-directory.

If this option isn't specified, then the rw subdirectory of the
directory specified via the ``--with-library-directory'' build
option is assumed. The directory is created if it doesn't
exist.

--with-data-directory=_d_i_r_e_c_t_o_r_y
Specify the directory within the ``installed file hierarchy''
where the tables, help pages, and other architecture-independent
files are to be installed. The absolute path should be
supplied. If this option isn't specified, then the brltty
subdirectory of the directory specified via the standard
configure option --sysconfdir (which defaults to /etc rooted at
the directory specified by the ``--prefix'' build option) is
assumed. The directory is created if it doesn't exist.

--with-manpage-directory=_d_i_r_e_c_t_o_r_y
Specify the directory within the ``installed file hierarchy''
where the man pages are to be installed. The absolute path
should be supplied. If this option isn't specified, then the
directory specified via the standard configure option --mandir
(which defaults to /man rooted at the directory specified by the
``--prefix'' build option) is assumed. The directory is created
if it doesn't exist.

--with-include-directory=_d_i_r_e_c_t_o_r_y
Specify the directory within the ``installed file hierarchy''
where the C header files for the Application Programming
Interface are to be installed. The absolute path should be
supplied. If this option isn't specified, then the brltty
subdirectory of the directory specified via the standard
configure option --includedir (which defaults to /include rooted
at the directory specified by the ``--prefix'' build option) is
assumed. The directory is created if it doesn't exist.

33..22..11..33.. BBuuiilldd FFeeaattuurreess

These options are primarily useful when building BRLTTY for use on a
boot disk.

--enable-standalone-programs
Create statically linked, rather than dynamically linked,
programs. This option removes all dependencies on shared
objects at run-time. Only the default drivers (see the
``--with-braille-driver'', ``--with-speech-driver'', and
``--with-screen-driver'' build options) are compiled.

--enable-relocatable-install
If this feature is enabled then all internal paths are
recalculated to be relative to the program directory. If it's
disabled then all internal paths are absolute. This feature
allows the entire installed file hierarchy to be copied or
moved, in tact, from one place to another, and is primarily
intended for use on Windows platforms.

--disable-strippingl
Don't remove the symbol tables from executables and shared
objects when installing them.

--disable-learn-mode
Reduce program size by excluding command learn mode (see section
``Command Learn Mode'').

--disable-contracted-braille
Reduce program size by excluding support for contracted braille
(see section ``Contraction Tables'').

--disable-speech-support
Reduce program size by excluding support for speech
synthesizers.

--disable-iconv
Reduce program size by excluding support for character set
conversion.

--disable-icu
Reduce program size by excluding support for Unicode-based
internationalization.

--disable-x
Reduce program size by excluding support for X11.

--disable-beeper-support
Reduce program size by excluding support for the console tone
generator.

--disable-pcm-support
Reduce program size by excluding support for the digital audio
interface on the sound card.

--enable-pcm-support=_i_n_t_e_r_f_a_c_e
If a platform provides more than one digital audio interface
then the one which is to be used may be specified.

Platform Interface Description
_______________________________________________________________
Linux oss Open Sound System
alsa Advanced Linux Sound Architecture

--disable-midi-support
Reduce program size by excluding support for the Musical
Instrument Digital Interface of the sound card.

--enable-midi-support=_i_n_t_e_r_f_a_c_e
If a platform provides more than one Musical Instrument Digital
Interface then the one which is to be used may be specified.

Platform Interface Description
_______________________________________________________________
Linux oss Open Sound System
alsa Advanced Linux Sound Architecture

--disable-fm-support
Reduce program size by excluding support for the FM synthesizer
on an AdLib, OPL3, Sound Blaster, or equivalent sound card.

--disable-pm-configfile
Reduce program size by excluding support for the Papenmeier
driver's configuration file.

--disable-gpm
Reduce program size by excluding the interface to the gpm
application which allows BRLTTY to interact with the pointer
(mouse) device (see section ``Pointer (Mouse) Support via
GPM'').

--disable-api
Reduce program size by excluding the Application Programming
Interface.

--with-api-parameters=_n_a_m_e=_v_a_l_u_e,...
Specify the default parameter settings for the Application
Programming Interface. If the same parameter is specified more
than once, then its rightmost assignment is used. For a
description of the parameters accepted by the interface, please
see the BBrrllAAPPII reference manual. See the ``api-parameters''
configuration file directive and the ``-A'' command line option
for run-time selection.

--disable-caml-bindings
Don't build the Caml bindings for the Application Programming
Interface.

--disable-java-bindings
Don't build the Java bindings for the Application Programming
Interface.

--disable-lisp-bindings
Don't build the Lisp bindings for the Application Programming
Interface.

--disable-python-bindings
Don't build the Python bindings for the Application Programming
Interface.

--disable-tcl-bindings
Don't build the Tcl bindings for the Application Programming
Interface.

--with-tcl-config=_p_a_t_h
Specify the location of the Tcl configuration script
(tclConfig.sh). Either the path to the script itself or to the
directory containing it may be supplied. Any of the following
words can also be used as the operand of this option:

nnoo Use other means to guess if Tcl is available, and, if so,
where it has been installed. This is equivalent to
specifying --without-tcl-config.

yyeess
Search for the script in a few commonly used directories.
This is equivalent to specifying --with-tcl-config.

33..22..11..44.. MMiisscceellllaanneeoouuss OOppttiioonnss

--with-compiler-prefix=_p_r_e_f_i_x
Specify the prefix (path and beginning of program name) for the
suite of compile and link tools which are to be used. You may
need to use this option if, for example, you're cross-compiling
for a different architecture.

--with-init-path=_p_a_t_h
Specify the path to the real init program for the system. The
absolute path should be supplied. If this option is specified,
then:

1. The init program should be moved to a new location.

2. brltty should be moved to the init program's original
location.

3. When the system runs init at startup, brltty is actually run.
It puts itself into the background, and runs the real init in
the foreground. This is one (somewhat sneaky) way to have
braille right at the outset. It's especially useful for some
install/rescue disks.

If this option isn't specified, then this feature isn't acti-
vated. This option is primarily intended for building a brail-
lified installer image.
--with-stderr-path=_p_a_t_h
Specify the path to the file or device where standard erorr
output is to be written. The absolute path should be supplied.
If this option isn't specified, then this feature isn't
activated. This option is primarily intended for building a
braillified installer image.

33..22..22.. MMaakkee FFiillee TTaarrggeettss

Once BRLTTY has been configured, the next steps are to compile and to
install it. These are done by applying the system's make command to
BRLTTY's main make file (Makefile in the top-level directory).
BRLTTY's make file supports most of the common application maintenance
targets. They include:

mmaakkee
A shortcut for make all.

mmaakkee aallll
Compile and link the BRLTTY executable, its drivers and their
help pages, its test programs, and a few other small utilities.

mmaakkee iinnssttaallll
Complete the compile and link phase (see ``make all''), and then
install the BRLTTY executable, its data files, drivers, and help
pages, in the correct places and with the correct permissions.

mmaakkee uunniinnssttaallll
Remove the BRLTTY executable, its data files, drivers, and help
pages, from the system.

mmaakkee cclleeaann
Ensure that the next compile and link (see ``make all'') will be
done from scratch by removing the results of compiling, linking,
and testing from the source directory structure. This includes
the removal of object files, executables, dynamically loadable
shared objects, driver lists, help pages, temporary header
files, and core files.

mmaakkee ddiissttcclleeaann
In addition to removing the results of compiling and linking
(see ``make clean''):

· Remove the results of BRLTTY configuration (see ``Build
Options''). This includes the removal of config.mk,
config.h, config.cache, config.status, and config.log.

· Remove other files from the source directory structure which
tend to accumulate over time but which don't belong there.
This includes the removal of editor backup files, test case
results, rejected patch hunks, and copies of original source
files.

33..33.. TTeessttiinngg BBRRLLTTTTYY

After compiling, linking, and installing BRLTTY, it's a good idea to
give it a quick test before activating it permanently. To do so,
invoke it with the command:

brltty -b_d_r_i_v_e_r -d_d_e_v_i_c_e

For _d_r_i_v_e_r, specify the two-letter ``driver identification code'' cor-
responding to your braille display. For _d_e_v_i_c_e, specify the full path
for the device to which your braille display is connected.

If you don't want to explicitly identify the driver and device each
time you start BRLTTY, then you can take two approaches. You can
establish system defaults via the ``braille-driver'' and the
``braille-device'' configuration file directives, and/or compile your
needs right into BRLTTY via the ``--with-braille-driver'' and the
``--with-braille-device'' build options.

If all is well, BRLTTY's version identification message should appear
on the braille display for a few seconds (see the ``-M'' command line
option). After it goes away (which you can hasten by pressing any key
on the display), the area of the screen where the cursor is should
appear. This means that you should expect to see your shell's command
prompt. Then, as you enter your next command, each character should
appear on the display as it's typed on the keyboard.

If this is your experience, then leave BRLTTY running, and enjoy it.
If this isn't your experience, then it may be necessary to test each
driver separately in order to isolate the source of the probledm. The
screen driver can be tested with ``scrtest'', and the braille display
driver can be tested with ``brltest''.

If you experience a problem which requires a lot of digging, then you
may wish to use the following brltty command line options:

· ``-ldebug'' to log lots of diagnostic messages.

· ``-n'' to keep BRLTTY in the foreground.

· ``-e'' to direct diagnostic messages to standard error rather than
to the system log.

33..44.. SSttaarrttiinngg BBRRLLTTTTYY

BRLTTY, when properly installed, is invoked with the single command
brltty. A configuration file (see section ``The Configuration File''
for details) can be created in order to establish system defaults for
such things as the location of the preferences file, the braille
display driver to be used, the device to which the braille display is
connected, and the text table to be used. Many options (see section
``Command Line Options'' for details) allow explicit run-time
specification of such things as the location of the configuration
file, any defaults established within the configuration file, and some
characteristics which have reasonable defaults but which those who
think they know what they're doing may wish to play with. The ``-h''
option displays a summary of all the options. The ``-V'' option
displays the current version of the program, the API, and the selected
drivers. The ``-v'' option displays the values of the options after
all sources have been considered.

It's probably best to have the system automatically start BRLTTY as
part of the boot sequence so that the braille display is already up
and running when the login prompt appears. Most (probably all)
distributions provide a script wherein user-supplied applications can
be safely started near the end of the boot sequence. The name of this
script is distribution-dependent. Here are the ones we know about so
far:

RReedd HHaatt
/etc/rc.d/rc.local

Starting BRLTTY from this script is a good approach (especially for
new users). Just add a set of lines like these:

if [ -x /bin/brltty -a -f /etc/brltty.conf ]
then
/bin/brltty
fi

This can usually be abbreviated to the somewhat less readable form:

[ -x /bin/brltty -a -f /etc/brltty.conf ] && /bin/brltty

Don't add these lines before the first line (which usually looks like
#!/bin/sh).

If the braille display is to be used by a system administrator, then
it should probably be started as early as possible during the boot
sequence (like before the file systems are checked) so that the
display is usable in the event that something goes wrong during these
checks and the system drops into single user mode. Again, exactly
where it's best to do this is distribution-dependent. Here are the
places we know about so far:

DDeebbiiaann
/etc/init.d/boot (for older releases)
/etc/init.d/rcS (for newer releases)
A brltty package is provided (see
[http://packages.debian.org/brltty]) as of release 3.0 (Woody).
Since this package takes care of starting BRLTTY, there's no
need for user-supplied code to do so if it's installed.

RReeddHHaatt
/etc/rc.d/rc.sysinit
Beware that later releases, in order to support a more user-
oriented system initialization procedure, have this script
reinvoke itself such that it's under the control of initlog.
Look, probably right up near the top, for a set of lines like
these:

# Rerun ourselves through initlog
if [ -z "$IN_INITLOG" ]; then
[ -f /sbin/initlog ] && exec /sbin/initlog $INITLOG_ARGS -r /etc/rc.sysinit
fi

Starting BRLTTY before this reinvocation results in two BRLTTY pro-
cesses running at the same time, and that'll give you no end of
problems. If your version of this script has this feature, then
make sure you start BRLTTY after the lines which implement it.

SSllaacckkwwaarree
/etc/rc.d/rc.S

SSuuSSEE
/sbin/init.d/boot

An alternative is to start BRLTTY from /etc/inittab. You have two
choices if you choose this route.
· If you want it to be started really early but don't need it to be
automatially restarted if it dies, then add a line like this before
the first :sysinit: line which is already in there.

brl::sysinit:/bin/brltty

· If you don't mind it being started later but do want it to be
automatially restarted if it dies, then add a line like this
anywhere within the file.

brl:12345:respawn:/bin/brltty -n

The ``-n'' (--nodaemon) option is very important when running BRLTTY
with iinniitt's respawn facility. You'll end up with hundreds of BRLTTY
processes all running at the same time if you forget to specify it.

Check that the identifier (bt in these examples) isn't already being
used by another entry, and, if it is, choose a different one which
isn't.

Note that a command like kill -TERM is sufficient to stop BRLTTY in
its tracks. If it dies during entry into single user mode, for
example, it may well be due to a problem of this nature.

Some systems, as part of the boot sequence, probe the serial ports
(usually in order to automatically find the mouse and deduce its
type). If your braille display is using a serial port, this kind of
probing may be enough to get it confused. If this happens to you,
then try restarting the braille driver (see the ``RESTARTBRL''
command). Better yet, turn off the serial port probing. Here's what
we know so far about how to do this:

RReedd HHaatt
The probing is done by a service named kudzu. Use the command

chkconfig --list kudzu

to see if it's been enabled. Use the command

chkconfig kudzu off

to disable it. Later releases allow you to let kudzu run without
probing the serial ports. To do this, edit the file /etc/syscon-
fig/kudzu, and set SAFE to yes.

If you want to start BRLTTY before any file systems are mounted, then
ensure that all of its components are installed within the root file
system. See the ``--with-execute-root'', ``--bindir'', ``--libdir'',
``--with-writable-directory'', and ``--with-data-directory'' build
options.

33..55.. SSeeccuurriittyy CCoonnssiiddeerraattiioonnss

BRLTTY needs to run with root privileges because it needs read and
write access for the port to which the braille display is connected,
read access to /dev/vcsa or equivalent (to query the screen dimensions
and the cursor position, and to review the current screen content and
highlighting), and read and write access to the system console (for
arrow key entry during cursor routing, for input character insertion
during paste, for special key simulation using keys on the braille
display, for retrieving output character translation and screen font
mapping tables, and for activation of the internal beeper). Access to
the needed devices can, of course, be granted to a non-root user by
changing the file permissions associated with the devices. Merely
having access to the console, however, isn't enough because activating
the internal beeper and simulating key strokes still require root
privilege. So, if you're willing to give up cursor routing,
cut&paste, beeps, and all that, you can run BRLTTY without root
priviledge.

33..66.. BBuuiilldd aanndd RRuunn--TTiimmee RReessttrriiccttiioonnss

AAlleerrtt TTuunneess

Some platforms don't support all of the tune devices. See the
``Tune Device'' preference for details.

FFeessttiivvaallLLiittee SSppeeeecchh SSyynntthheessiizzeerr DDrriivveerr

The driver for the FestivalLite text to speech engine is only
built if that package has been installed.

This driver and the driver for the Theta text to speech engine
(see the ``--with-theta'' build option) cannot be simultaneously
linked into the BRLTTY binary (see the ``--with-speech-driver''
build option) because their run-time libraries contain
conflicting symbols.

LLiibbbbrraaiillllee BBrraaiillllee DDiissppllaayy DDrriivveerr

The driver for the Libbraille package is only built if that
package has been installed.

MMiikkrrooppuuhhee SSppeeeecchh SSyynntthheessiizzeerr DDrriivveerr

The driver for the Mikropuhe text to speech engine is only built
if that package has been installed.

This driver cannot be included if the BRLTTY binary is
statically linked (see the ``--enable-standalone-programs''
build option) because a static archive isn't included with the
package.

TThheettaa SSppeeeecchh SSyynntthheessiizzeerr DDrriivveerr

The driver for the Theta text to speech engine is only built if
that package has been installed.

This driver and the driver for the FestivalLite text to speech
engine (see the ``--with-flite'' build option) cannot be
simultaneously linked into the BRLTTY binary (see the ``--with-
speech-driver'' build option) because their run-time libraries
contain conflicting symbols.

If this driver is built as a dynamically loadable shared object
then $THETA_HOME/lib must be added to the LD_LIBRARY_PATH
environment variable before BRLTTY is invoked because the shared
objects within the package don't contain run-time search paths
for their dependencies.

VViiaaVVooiiccee SSppeeeecchh SSyynntthheessiizzeerr DDrriivveerr

The driver for the ViaVoice text to speech engine is only built
if that package has been installed.

This driver cannot be included if the BRLTTY binary is
statically linked (see the ``--enable-standalone-programs''
build option) because a static archive isn't included with the
package.
VViiddeeooBBrraaiillllee BBrraaiillllee DDiissppllaayy DDrriivveerr

The driver for the VideoBraille braille display is built on all
systems, but only works on Linux.

33..77.. IInnssttaalllliinngg ffrroomm aann RRPPMM FFiillee

To install BRLTTY from an RPM (RedHat Package Manager) file, do the
following:

1. Download the binary package which corresponds to your hardware.
It'll be a file named brltty-_r_e_l_e_a_s_e-_v_e_r_s_i_o_n._a_r_c_h_i_t_e_c_t_u_r_e.rpm, e.g.
brltty-3.0-1.i386.rpm.

2. Install the package.

rpm -Uvh brltty-_r_e_l_e_a_s_e-_v_e_r_s_i_o_n._a_r_c_h_i_t_e_c_t_u_r_e.rpm

This should be done as rroooott. Strictly speaking, the -U (update)
option is the only one which is necessary. The -v (verbose) option
displays the name of the package as it's being installed. The -h
(hashes) option displays a progress meter (using hash signs).

For the brave, we also provide the source RPM (.src.rpm) file, but
that's beyond the scope of this document.

To uninstall BRLTTY, do:

rpm -e brltty

33..88.. OOtthheerr UUttiilliittiieess

Building BRLTTY also results in the building of a few small helper and
diagnostic utilities.

33..88..11.. bbrrllttttyy--ccoonnffiigg

This utility sets a number of environment variables to values which
reflect the current installation of BRLTTY (see ``Build Options'').
It should be executed within an existing shell environment, i.e. not
as a command in its own right, and can only be used by scripts which
support BBoouurrnnee SShheellll syntax.

. brltty-config

The following environment variables are set:

BBRRLLTTTTYY__VVEERRSSIIOONN
The version number of the BRLTTY package.

BBRRLLTTTTYY__EEXXEECCUUTTEE__RROOOOTT
Run-time root for the installed package. Configured via the
``--with-execute-root'' build option.

BBRRLLTTTTYY__PPRROOGGRRAAMM__DDIIRREECCTTOORRYY
Directory for runnable programs (binaries, executables).
Configured via the ``--with-program-directory'' build option.

BBRRLLTTTTYY__LLIIBBRRAARRYY__DDIIRREECCTTOORRYY
Directory for drivers. Configured via the ``--with-library-
directory'' build option.

BBRRLLTTTTYY__WWRRIITTAABBLLEE__DDIIRREECCTTOORRYY
Directory which can be written to. Configured via the ``--with-
writable-directory'' build option.

BBRRLLTTTTYY__DDAATTAA__DDIIRREECCTTOORRYY
Directory for tables and help pages. Configured via the
``--with-data-directory'' build option.

BBRRLLTTTTYY__MMAANNPPAAGGEE__DDIIRREECCTTOORRYY
Directory for manual pages. Configured via the ``--with-
manpage-directory'' build option.

BBRRLLTTTTYY__IINNCCLLUUDDEE__DDIIRREECCTTOORRYY
Directory for BrlAPI's C header files. Configured via the
``--with-include-directory'' build option.

BBRRLLAAPPII__VVEERRSSIIOONN
The version number of BrlAPI (BRLTTY's Application Programming
Interface).

BBRRLLAAPPII__RREELLEEAASSEE
The full release number of BrlAPI.

BBRRLLAAPPII__AAUUTTHH
The name of BrlAPI's key file.

In addition, the following standard aauuttooccoonnff environment variables are
also set:

pprreeffiixx
Subroot for architecture-independent files. Configured via the
``--prefix'' build option.

eexxeecc__pprreeffiixx
Subroot for architecture-dependent files. Configured via the
``--exec-prefix'' build option.

bbiinnddiirr
Default location for ``program directory''. Configured via the
--bindir build option.

lliibbddiirr
Directory for BrlAPI's static archive and dynamically loadable
object. Default anchor for ``library directory''. Configured
via the ``--libdir'' build option.

ssyyssccoonnffddiirr
Directory for configuration files. Default anchor for ``data
directory''. Configured via the ``--sysconfdir'' build option.

mmaannddiirr
Default location for ``manual pages directory''. Configured via
the --mandir build option.

iinncclluuddeeddiirr
Default anchor for ``header files directory''. Configured via
the --includedir build option.

33..88..22.. bbrrllttttyy--iinnssttaallll

This utility copies BRLTTY's ``installed file hierarchy'' from one
location to another.

brltty-install _t_o [_f_r_o_m]

_t_o The location to which the ``installed file hierarchy'' is to be
copied. It must be an existing directory.

_f_r_o_m
The location from which the ``installed file hierarchy'' is to
be taken. If it's specified, then it must be an existing
directory. If it's not specified, then the location used for
the build is assumed.

This utility can be used, for example, to copy BRLTTY to a root disk.
If a root floppy is mounted as /mnt, and BRLTTY is installed on the
main system, then typing

brltty-install /mnt

copies BRLTTY, along with all of its data and library files, to the
root floppy.

Some problems have been experienced when copying BRLTTY between
systems with different versions of the shared C library. This is
worth investigating if you have difficulties.

33..88..33.. bbrrlltteesstt

This utility tests a braille display driver, and also provides an
interactive way to learn what the keys on the braille display do. It
should be run as root.

brltest -_o_p_t_i_o_n ... [_d_r_i_v_e_r [_n_a_m_e=_v_a_l_u_e ...]]

_d_r_i_v_e_r
The driver for the braille display. It must be a two-letter
``driver identification code''. If it's not specified, then the
first driver configured via the ``--with-braille-driver'' build
option is assumed.

_n_a_m_e=_v_a_l_u_e
Set a braille display driver parameter. For a description of
the parameters accepted by a specific driver, please see the
documentation for that driver.

-d_d_e_v_i_c_e --device=_d_e_v_i_c_e
The absolute path for the device to which the braille display is
connected. If it's not specified, then the device configured
via the ``--with-braille-device'' build option is assumed.

-D_d_i_r_e_c_t_o_r_y --data-directory=_d_i_r_e_c_t_o_r_y
The absolute path for the directory wherein the driver data
files reside. If it's not specified, then the directory
configured via the ``--with-data-directory'' build option is
assumed.

-L_d_i_r_e_c_t_o_r_y --library-directory=_d_i_r_e_c_t_o_r_y
The absolute path for the directory wherein the drivers reside.
If it's not specified, then the directory configured via the
``--libdir'' build option is assumed.

-W_d_i_r_e_c_t_o_r_y --writable-directory=_d_i_r_e_c_t_o_r_y
The absolute path for a directory which can be written to. If
it's not specified, then the directory configured via the
``--with-writable-directory'' build option is assumed.

-h --help
Display a summary of the command line options, and then exit.

This utility uses BRLTTY's ``Command Learn Mode''. The key press
timeout (after which this utility exits) is 10 seconds. The message
hold time (used for non-final segments of long messages) is 4 seconds.

33..88..44.. ssppkktteesstt

This utility tests a speech synthesizer driver. It may need to be run
as root.

spktest -_o_p_t_i_o_n ... [_d_r_i_v_e_r [_n_a_m_e=_v_a_l_u_e ...]]

_d_r_i_v_e_r
The driver for the speech synthesizer. It must be a two-letter
``driver identification code''. If it's not specified, then the
first driver configured via the ``--with-speech-driver'' build
option is assumed.

_n_a_m_e=_v_a_l_u_e
Set a speech synthesizer driver parameter. For a description of
the parameters accepted by a specific driver, please see the
documentation for that driver.

-t_s_t_r_i_n_g --text-string=_s_t_r_i_n_g
The text to be spoken. If it's not specified, then standard
input is read.

-h --help
Display a summary of the command line options, and then exit.

33..88..55.. ssccrrtteesstt

This utility tests the screen driver. It must be run as root.

scrtest -_o_p_t_i_o_n ... [_n_a_m_e=_v_a_l_u_e ...]

_n_a_m_e=_v_a_l_u_e
Set a screen driver parameter. For a description of the
parameters accepted by a specific driver, please see the
documentation for that driver.

-l_c_o_l_u_m_n --left=_c_o_l_u_m_n
Specify the starting (left) column (zero-origin) of the region.
If this value isn't supplied, then a default value, based on the
specified width, is selected such that the region is
horizontally centred.

-c_c_o_u_n_t --columns=_c_o_u_n_t
Specify the width of the region (in columns). If this value
isn't supplied, then a default value, based on the specified
starting column, is selected such that the region is
horizontally centred.

-t_r_o_w --top=_r_o_w
Specify the starting (top) row (zero-origin) of the region. If
this value isn't supplied, then a default value, based on the
specified height, is selected such that the region is vertically
centred.

-r_c_o_u_n_t --rows=_c_o_u_n_t
Specify the height of the region (in rows). If this value isn't
supplied, then a default value, based on the specified starting
row, is selected such that the region is vertically centred.

-h --help
Display a summary of the command line options, and then exit.

Notes:

· If neither a starting column nor a region width is specified, then
the region is horizontally-centred and starts at column 5.

· If neither a starting row nor a region height is specified, then
the region is vertically-centred and starts at row 5.

The following is written to standard output:

1. A line detailing the dimensions of the screen.

Screen: _w_i_d_t_hx_h_e_i_g_h_t

2. A line detailing the position (zero-origin) of the cursor.

Cursor: [_c_o_l_u_m_n,_r_o_w]

3. A line detailing the size of the selected screen region, and the
position (zero-origin) of its top-left corner.

Region: _w_i_d_t_hx_h_e_i_g_h_t@[_c_o_l_u_m_n,_r_o_w]

4. The contents of the selected screen region. Unprintable characters
are written as blanks.

33..88..66.. ttttbbtteesstt

This utility tests a text table (see section ``Text Tables'').

ttbtest -_o_p_t_i_o_n ... _i_n_p_u_t_-_t_a_b_l_e _o_u_t_p_u_t_-_t_a_b_l_e

_i_n_p_u_t_-_t_a_b_l_e
The file system path to the input text table. If it's relative
then it's anchored at the directory configured via the ``--with-
data-directory'' build option.

_o_u_t_p_u_t_-_t_a_b_l_e
The file system path to the output text table. If it's relative
then it's anchored at the current working directory. If this
parameter isn't supplied then no output table is written.

-i_f_o_r_m_a_t --input-format=_f_o_r_m_a_t
Specify the format of the input table. If this option isn't
supplied then the format of the input table is deduced from the
extension of the input table's file name.

-o_f_o_r_m_a_t --output-format=_f_o_r_m_a_t
Specify the format of the output table. If this option isn't
supplied then the format of the output table is deduced from the
extension of the output table's file name.

-c_c_h_a_r_s_e_t --charset=_c_h_a_r_s_e_t
Specify the name of the 8-bit character set to use when
interpreting the tables. If this option isn't supplied then the
host's character set is used.

-e --edit
Invoke the text table editor. If the output table is specified
then changes are written to it. If not then the input table is
rewritten.

-h --help
Display a summary of the command line options, and then exit.

If no special action is requested then the output table is optional.
If it is not specified then the input table is checked. If it is
specified then the input table is converted.

The following table formats are supported:

ttttbb
BRLTTY

ssbbll
SuSE Blinux

aa22bb
Gnopernicus

ggnnbb
Gnome Braille

33..88..77.. ccttbbtteesstt

This utility tests a contraction table (see section ``Contraction
Tables''). The text read from the input files (or standard input) is
rewritten to standard output as contracted braille.

ctbtest -_o_p_t_i_o_n ... _i_n_p_u_t_-_f_i_l_e ...

_i_n_p_u_t_-_f_i_l_e
The list of files to be processed. Any number of files may be
specified. They're processed from left to right. The special
file name - is interpreted to mean standard input. If no files
are specified then standard input is processed.

-c_f_i_l_e --contraction-table=_f_i_l_e
The file system path to the contraction table. If it's relative
then it's anchored at the directory configured via the ``--with-
data-directory'' build option. The .ctb extension is optional.
If this option isn't supplied then en-us-g2 is assumed.

-t_f_i_l_e|auto --text-table=_f_i_l_e|auto
Specify the text table (see section ``Text Tables'' for
details). If a relative path is supplied, then it's anchored at
/etc/brltty (see the ``--with-data-directory'' and the ``--with-
execute-root'' build options for more details). The .ttb
extension is optional. See the ``text-table'' configuration
file directive for the default run-time setting. This setting
can be changed with the ``Text Table'' preference.

-w_c_o_l_u_m_n_s --output-width=_c_o_l_u_m_n_s
The maximum length of an output line. Each contracted input
line is wrapped into as many output lines as necessary. If this
option isn't specified then there's no limit, and there's a one-
to-one correspondance between input and output lines.

-h --help
Display a summary of the command line options, and then exit.

The text table is used:

· To define the output character set so that the contracted braille
will be displayed correctly. The same table as will be used by
BRLTTY when the output is read should be specified.

· To define the braille representations of those characters defined
within the contraction table as = (see section ``Character
Translation'').

The brf.ttb text table is provided for use with this utility. It
defines the format used within .brf files. This is also the preferred
format used by most braille printers and within electronically
distributed braille documents. This table effectively allows this
utility to be used as a text to braille translator.

33..88..88.. ttuunneetteesstt

This utility tests the alert tunes facility, and also provides an easy
way to compose new tunes. It may need to be run as root.

tunetest -_o_p_t_i_o_n ... {_n_o_t_e _d_u_r_a_t_i_o_n} ...

_n_o_t_e
A standard MIDI note number. It must be an integer from 1
through 127, with 60 representing Middle C. Each value
represents a standard chromatic semi-tone, with the next lower
and higher values representing, respectively, the next lower and
higher notes. The lowest value (1) represents the fifth C-Sharp
below Middle C, and the highest value (127) represents the sixth
G above Middle C.

_d_u_r_a_t_i_o_n
The duration of the note in milliseconds. It must be an integer
from 1 through 255.

-d_d_e_v_i_c_e --device=_d_e_v_i_c_e
The device on which to play the tune.

bbeeeeppeerr
The internal beeper (console tone generator).

ppccmm
The digital audio interface on the sound card.

mmiiddii
The Musical Instrument Digital Interface on the sound card.

ffmm The FM synthesizer on an AdLib, OPL3, Sound Blaster, or
equivalent sound card.

The device name may be abbreviated. See the ``Tune Device''
preference for details regarding the default device and platform
restrictions.

-v_l_o_u_d_n_e_s_s --volume=_l_o_u_d_n_e_s_s
Specify the output volume (loudness) as a percentage of the
maximum. The default output volume is 50.

-p_d_e_v_i_c_e --pcm-device=_d_e_v_i_c_e
Specify the device to use for digital audio (see section ``PCM
Device Specification''). This option isn't available if the
``--disable-pcm-support'' build option was specified.

-m_d_e_v_i_c_e --midi-device=_d_e_v_i_c_e
Specify the device to use for the Musical Instrument Digital
Interface (see section ``MIDI Device Specification''). This
option isn't available if the ``--disable-midi-support'' build
option was specified.

-i_i_n_s_t_r_u_m_e_n_t --instrument=_i_n_s_t_r_u_m_e_n_t
The instrument to use if the selected device is midi. For the
complete list of instruments, see the ``MIDI Instrument Table''.
The default instrument is an acoustic grand piano. The words
comprising the instrument name must be separated from one
another by a single minus sign rather than by spaces, and any of
the words may be abbreviated. An acoustic grand piano, for
example, may be specified as a-gra-pi.

-h --help
Display a summary of the command line options, and then exit.

44.. UUssiinngg BBRRLLTTTTYY

Before starting BRLTTY, you need to set up your braille display. In
most cases this is done simply by connecting it to an available serial
port, and then turning it on. After your display has been set up, run
BRLTTY simply by typing the command brltty at a shell prompt (this
must be done as root). Check the ``-d'' command line option, the
``braille-device'' configuration file directive, and the ``--with-
braille-device'' build option for alternatives regarding how to tell
BRLTTY which device your display is connected to. Check the ``-b''
command line option, the ``braille-driver'' configuration file
directive, and the ``--with-braille-driver'' build option for
alternatives regarding how to tell BRLTTY which kind of braille
display you have. Check the ``-B'' command line option, and the
``braille-parameters'' configuration file directive for alternatives
regarding how to pass parameters to the driver for your braille
display.

A message giving the program name (BRLTTY) and its version number will
appear briefly (see the ``-M'' command line option) on the braille
display. The display will then show a small area of the screen
including the cursor. By default, the cursor is represented as dots 7
and 8 superimposed on the character it is on.

Any screen activity will be reflected on the braille display. The
display will also follow the progress of the cursor on the screen.
This feature is known as ccuurrssoorr ttrraacckkiinngg.

Just typing on the keyboard and reading the display, however, isn't
enough. Try entering a command which will cause an error, and
pressing eenntteerr. The error appears on the screen, but, unless you have
a multi-line display, the chances are that it isn't visible on the
braille display. All you see thereon is another shell prompt. What's
needed, then, is some way to move the braille _w_i_n_d_o_w around the
screen. The keys on the braille display itself can be used to send
commands to BRLTTY which, in addition to a lot of other things, can
also do exactly that.

44..11.. CCoommmmaannddss

Unfortunately, the various braille displays don't offer a standard set
of controls. Some have the six standard dot keys, some have eight,
and others have none. Some have thumb keys, but there's no standard
number of them. Some have a button above each braille cell. Some
have rocker switches. Some have an easy-to-reach bar which works much
like a joystick. Most have varying combinations of the above.
Because the nature and layout of each display is so different, please
refer to the documentation for your particular display in order to
find out exactly what its keys do.

BRLTTY commands are referred to by name within this manual. If you
forget which key(s) on your braille display to use for a paticular
command, then refer to its driver's help page. The main key you
should immediately commit to memory, therefore, is the one for the
``HELP'' command. Use the regular motion keys (as described below) to
navigate the help page, and press the help key again to quit.

44..11..11.. VVeerrttiiccaall MMoottiioonn

See also the ``PRINDENT/NXINDENT'', and the ``PRDIFCHAR/NXDIFCHAR''
routing key commands.

LLNNUUPP//LLNNDDNN
Go up/down one line. If identical line skipping has been
activated (see the ``SKPIDLNS'' command), then these commands,
rather than moving exactly one line, are aliases for the
``PRDIFLN/NXDIFLN'' commands.

WWIINNUUPP//WWIINNDDNN
Go up/down one window. If the window is only 1 line high then
move 5 lines.

PPRRDDIIFFLLNN//NNXXDDIIFFLLNN
Go up/down to the nearest line with different content. If
identical line skipping has been activated (see the ``SKPIDLNS''
command), then these commands, rather than skipping identical
lines, are aliases for the ``LNUP/LNDN'' commands.

AATTTTRRUUPP//AATTTTRRDDNN
Go up/down to the nearest line with different attributes
(character highlighting).

TTOOPP//BBOOTT
Go to the top/bottom line.

TTOOPP__LLEEFFTT//BBOOTT__LLEEFFTT
Go to the top-left/bottom-left corner.

PPRRPPGGRRPPHH//NNXXPPGGRRPPHH
Go to the nearest line of the previous/next paragraph (the first
non-blank line beyond the nearest blank line). The current line
is included when searching for the inter-paragraph space.

PPRRPPRROOMMPPTT//NNXXPPRROOMMPPTT
Go to the previous/next command prompt.

PPRRSSEEAARRCCHH//NNXXSSEEAARRCCHH
Search backward/forward for the nearest occurrence of the
character string within the cut buffer (see ``Cut and Paste'')
which isn't within the braille window. The search proceeds to
the left/right, starting at the character immediately to the
left/right of the window, and wrapping at the edge of the
screen. The search isn't case sensitive.

44..11..22.. HHoorriizzoonnttaall MMoottiioonn

See also the ``SETLEFT'' routing key command.

CCHHRRLLTT//CCHHRRRRTT
Go left/right one character.

HHWWIINNLLTT//HHWWIINNRRTT
Go left/right half a window.

FFWWIINNLLTT//FFWWIINNRRTT
Go left/right one window. These commands are particularly
useful because they automatically wrap when they reach the edge
of the screen. Other features, like their ability to skip blank
windows (see the ``SKPBLNKWINS'' command), further enhance their
usefulness.

FFWWIINNLLTTSSKKIIPP//FFWWIINNRRTTSSKKIIPP
Go left/right to the nearest non-blank window.

LLNNBBEEGG//LLNNEENNDD
Go to the beginning/end of the line.

44..11..33.. IImmpplliicciitt MMoottiioonn

See also the ``GOTOMARK'' routing key command.

HHOOMMEE
Go to where the cursor is.

BBAACCKK
Go back to where the most recent motion command put the braille
window. This is an easy way to get right back to where you were
reading after an unexpected event (like cursor tracking) moves
the braille window at an inopportune moment.

RREETTUURRNN

· If the most recent motion of the braille window was
automatic, e.g. as a result of cursor tracking, then go back
to where the most recent motion command put it (see the
``BACK'' command).

· If the cursor isn't within the braille window then go to
where the cursor is (see the ``HOME'' command).

44..11..44.. FFeeaattuurree AAccttiivvaattiioonn

Each of these commands has three forms: aaccttiivvaattee (turn the feature
on), ddeeaaccttiivvaattee (turn the feature off), and ttooggggllee (if it's off then
turn it on, and if it's on then turn it off). Unless specifically
noted, each of these features is initially ooffff, and, when oonn, affects
BRLTTY's operation as a whole. The initial setting of some of these
features can be changed via the ``preferences menu''.

FFRREEEEZZEE
Freeze the screen image. BRLTTY makes a copy of the screen
(content and attributes) as of the moment when the screen image
is frozen, and then ignores all updating of the screen until
it's unfrozen. This feature makes it easy, for example, to
sample the output of an application which writes too much too
quickly.

DDIISSPPMMDD
Show the highlighting (the attributes) of each character within
the braille window, rather than the characters themselves (the
content). This feature is useful, for example, when you need to
locate a highlighted item. When showing screen content, the
text table is used (see the ``-t'' command line option, the
``text-table'' configuration file directive, and the ``--with-
text-table'' build option). When showing screen attributes, the
attributes table is used (see the ``-a'' command line option,
the ``attributes-table'' configuration file directive, and the
``--with-attributes-table'' build option). This feature only
affects the current virtual terminal.

SSIIXXDDOOTTSS
Show characters using 6-dot, rather than 8-dot, braille. Dots 7
and 8 are still used by other features like cursor
representation and highlighted character underlining. If a
contraction table has been selected (see the ``-c'' command line
option and the ``contraction-table'' configuration file
directive), then it is used. This setting can also be changed
with the ``Text Style'' preference.

SSLLIIDDEEWWIINN
If cursor tracking (see the ``CSRTRK'' command) is oonn, then,
whenever the cursor moves too close to (or beyond) either end of
the braille window, horizontally reposition the window such that
the cursor, while remaining on that side, is nearer the centre.
If this feature is ooffff, then the braille window is always
positioned such that its left end is a multiple of its width
from the left edge of the screen. This setting can also be
changed with the ``Sliding Window'' preference.

SSKKPPIIDDLLNNSS
Rather than explicitly moving exactly one line either up or
down, skip past lines which have the same content as the current
line. This feature affects the ``LNUP/LNDN'' commands, as well
as the line wrapping feature of the ``FWINLT/FWINRT'' and
``FWINLTSKIP/FWINRTSKIP'' commands. This setting can also be
changed with the ``Skip Identical Lines'' preference.

SSKKPPBBLLNNKKWWIINNSS
Skip past blank windows when reading either forward or backward.
This feature affects the ``FWINLT/FWINRT'' commands. This
setting can also be changed with the ``Skip Blank Windows''
preference.

CCSSRRVVIISS
Show the cursor by superimposing a dot pattern (see the
``CSRSIZE'' command) on top of the character where it is. This
feature is initially oonn. This setting can also be changed with
the ``Show Cursor'' preference.

CCSSRRHHIIDDEE
Hide the cursor (see the ``CSRVIS'' command) in order to
accurately read the character beneath it. This feature only
affects the current virtual terminal.

CCSSRRTTRRKK
Track (follow) the cursor. If the cursor moves to a location
which isn't within the braille window, then automatically move
the braille window to the cursor's new location. You'll usually
want this feature turned on since it minimizes the effects of
screen scrolling, and since, during input, the region wherein
you're currently typing is always visible. If this feature
causes the braille window to jump at an inopportune moment, then
use the ``BACK'' command to get back to where you were reading.
You may need to turn this feature off when using an application
which continually updates the screen while maintaining a fixed
data layout. This feature is initially oonn. This feature only
affects the current virtual terminal.

CCSSRRSSIIZZEE
Represent the cursor with all eight dots (a solid block), rather
than with just dots 7 and 8 (an underline). This setting can
also be changed with the ``Cursor Style'' preference.

CCSSRRBBLLIINNKK
Blink (turn on and off according to a predefined interval) the
symbol representing the cursor (see the ``CSRVIS'' command).
This setting can also be changed with the ``Blinking Cursor''
preference.

AATTTTRRVVIISS
Underline (with combinations of dots 7 and 8) highlighted
characters.

nnoo uunnddeerrlliinnee
White on black (normal), gray on black, white on blue, black
on cyan.

ddoottss 77 aanndd 88
Black on white (reverse video).

ddoott 88
Everything else.

This setting can also be changed with the ``Show Attributes''
preference.

AATTTTRRBBLLIINNKK
Blink (turn on and off according to a predefined interval) the
attribute underline (see the ``ATTRVIS'' command). This feature
is initially oonn. This setting can also be changed with the
``Blinking Attributes'' preference.

CCAAPPBBLLIINNKK
Blink (turn on and off according to a predefined interval)
capital (uppercase) letters. This setting can also be changed
with the ``Blinking Capitals'' preference.

TTUUNNEESS
Play a short predefined tune (see ``Alert Tunes'') whenever a
significant event occurs. This feature is initially oonn. This
setting can also be changed with the ``Alert Tunes'' preference.

AAUUTTOORREEPPEEAATT
Automatically repeat a command at a regular interval after an
initial delay while its key (combination) remains pressed. Only
some drivers support this functionality, the primary limitation
being that many braille displays don't signal key presses and
key releases as distinctly separate events. This feature is
initially oonn. This setting can also be changed with the
``Autorepeat'' preference.

AAUUTTOOSSPPEEAAKK
Automatically speak:

· the new line when the braille window is moved vertically.

· characters which are entered or deleted.

· the character to which the cursor is moved.

This feature is initially ooffff. This setting can also be changed
with the ``Autospeak'' preference.

44..11..55.. MMooddee SSeelleeccttiioonn

HHEELLPP
Switch to the braille display driver's help page. This is where
you can find an on-line summary of things like what your braille
display's keys do, and how to interpret its status cells. Use
the regular ``vertical'' and ``horizontal'' motion commands to
navigate the help page. Invoke the help command again to return
to the screen.

IINNFFOO
Switch to the status display (see section ``The Status Display''
for full details). It presents a summary including the position
of the cursor, the position of the braille window, and the
states of a number of BRLTTY's features. Invoke this command
again to return to the screen.

LLEEAARRNN
Switch to command learn mode (see section ``Command Learn Mode''
for full details). This is how you can interactively learn what
your braille display's keys do. Invoke this command again to
return to the screen. This command isn't available if the
``--disable-learn-mode'' build option was specified.

44..11..66.. PPrreeffeerreennccee MMaaiinntteennaannccee

PPRREEFFMMEENNUU
Switch to the preferences menu (see ``The Preferences Menu'' for
full details). Invoke this command again to return to normal
operation.

PPRREEFFSSAAVVEE
Save the current preferences settings (see ``Preferences'' for
full details).

PPRREEFFLLOOAADD
Restore the most recently saved preferences settings (see
``Preferences'' for full details).

44..11..77.. MMeennuu NNaavviiggaattiioonn

MMEENNUU__FFIIRRSSTT__IITTEEMM//MMEENNUU__LLAASSTT__IITTEEMM
Go to the first/last item in the menu.

MMEENNUU__PPRREEVV__IITTEEMMMMEENNUU__NNEEXXTT__IITTEEMM//
Go to the previous/next item in the menu.

MMEENNUU__PPRREEVV__SSEETTTTIINNGG//MMEENNUU__NNEEXXTT__SSEETTTTIINNGG
Decrement/increment the current menu item's setting.

44..11..88.. SSppeeeecchh CCoonnttrroollss

SSAAYY__LLIINNEE
Speak the current line. The ``Say-Line Mode'' preference
determines if pending speech is discarded first.
SSAAYY__AABBOOVVEE
Speak the top portion of the screen (ending with the current
line).

SSAAYY__BBEELLOOWW
Speak the bottom portion of the screen (starting with the
current line).

MMUUTTEE
Stop speaking immediately.

SSPPKKHHOOMMEE
Go to where the speech cursor is.

SSAAYY__SSLLOOWWEERR//SSAAYY__FFAASSTTEERR
Decrease/increase the speech rate (see also the ``Speech Rate''
preference). This command is only available if a driver which
supports it is being used.

SSAAYY__SSOOFFTTEERR//SSAAYY__LLOOUUDDEERR
Decrease/increase the speech volume (see also the ``Speech
Volume'' preference). This command is only available if a
driver which supports it is being used.

44..11..99.. VViirrttuuaall TTeerrmmiinnaall SSwwiittcchhiinngg

See also the ``SWITCHVT'' routing key command.

SSWWIITTCCHHVVTT__PPRREEVV//SSWWIITTCCHHVVTT__NNEEXXTT
Switch to the previous/next virtual terminal.

44..11..1100.. OOtthheerr CCoommmmaannddss

CCSSRRJJMMPP__VVEERRTT
Route (bring) the cursor to anywhere on the top line of the
braille window (see ``Cursor Routing'' for full details). The
cursor is moved by simulating vertical arrow-key presses. This
command doesn't always work because some applications either
move the cursor somewhat unpredictably or use the arrow keys for
purposes other than cursor motion. It's somewhat safer than the
other cursor routing commands, though, because it makes no
attempt to simulate the left- and right-arrows.

PPAASSTTEE
Insert the characters within the cut buffer at the current
cursor location (see ``Cut and Paste'' for full details).

RREESSTTAARRTTBBRRLL
Stop, and then restart the braille display driver.

RREESSTTAARRTTSSPPEEEECCHH
Stop, and then restart the speech synthesizer driver.

44..11..1111.. CChhaarraacctteerr CCoommmmaannddss

RROOUUTTEE
Route (bring) the cursor to the character associated with the
routing key (see ``Cursor Routing'' for full details). The
cursor is moved by simulating arrow-key presses. This command
doesn't always work because some applications either move the
cursor somewhat unpredictably or use the arrow keys for purposes
other than cursor motion.

CCUUTTBBEEGGIINN
Anchor the start of the cut block at the character associated
with the routing key (see ``Cut and Paste'' for full details).
This command clears the cut buffer.

CCUUTTAAPPPPEENNDD
Anchor the start of the cut block at the character associated
with the routing key (see ``Cut and Paste'' for full details).
This command doesn't clear the cut buffer.

CCUUTTRREECCTT
Anchor the end of the cut block at the character associated with
the routing key, and append the rectangular region to the cut
buffer (see ``Cut and Paste'' for full details).

CCUUTTLLIINNEE
Anchor the end of the cut block at the character associated with
the routing key, and append the linear region to the cut buffer
(see ``Cut and Paste'' for full details).

CCOOPPYYCCHHAARRSS
Copy the character block anchored by the two routing keys to the
cut buffer (see ``Cut and Paste'' for full details).

AAPPNNDDCCHHAARRSS
Append the character block anchored by the two routing keys to
the cut buffer (see ``Cut and Paste'' for full details).

PPRRIINNDDEENNTT//NNXXIINNDDEENNTT
Go up/down to the nearest line which isn't indented more than
the column associated with the routing key.

DDEESSCCCCHHAARR
Momentarily (see the ``-M'' command line option) display a
message describing the character associated with the routing
key. It reveals the decimal and hexadecimal values of the
character, the foreground and background colours, and, when
present, special attributes (bright and blink). The message
looks like this:

char 65 (0x41): white on black bright blink

SSEETTLLEEFFTT
Horizontally reposition the braille window so that its left edge
is at the column associated with the routing key. This feature
makes it very easy to put the window exactly where it's needed,
and, therefore, for displays which have routing keys, almost
eliminates the need for a lot of elementary window motion (like
the ``CHRLT/CHRRT'' and ``HWINLT/HWINRT'' commands).

PPRRDDIIFFCCHHAARR//NNXXDDIIFFCCHHAARR
Go up/down to the nearest line which has a different character
in the column associated with the routing key.

44..11..1122.. BBaassee CCoommmmaannddss

SSWWIITTCCHHVVTT
Switch to the virtual terminal whose number (counting from 1)
matches that of the routing key. See also the
``SWITCHVT_PREV/SWITCHVT_NEXT'' virtual terminal switching
commands.

SSEETTMMAARRKK
Mark (remember) the current position of the braille window in a
register associated with the routing key. See the ``GOTOMARK''
command. This feature only affects the current virtual
terminal.

GGOOTTOOMMAARRKK
Move the braille window to the position formerly marked (see the
``SETMARK'' command) with the same routing key. This feature
only affects the current virtual terminal.

44..22.. TThhee CCoonnffiigguurraattiioonn FFiillee

System defaults for many settings may be established within a
configuration file. The default name for this file is
/etc/brltty.conf, although it may be overridden with the ``-f''
command line option. It doesn't need to exist. A template for it can
be found within the DOCS subdirectory.

Blank lines are ignored. A comment begin with a number sign (#), and
continues to the end of the line. The following directives are
recognized:

api-parameters _n_a_m_e=_v_a_l_u_e,...
Specify parameters for the Application Programming Interrface.
If the same parameter is specified more than once, then its
rightmost assignment is used. For a description of the
parameters accepted by the interface, please see the BBrrllAAPPII
reference manual. See the ``--with-api-parameters'' build
option for the defaults established during the build procedure.
This directive can be overridden with the ``-A'' command line
option.

attributes-table _f_i_l_e
Specify the attributes table (see section ``Attributes Tables''
for details). If a relative path is supplied, then it's
anchored at /etc/brltty (see the ``--with-data-directory'' and
the ``--with-execute-root'' build options for more details).
The .atb extension is optional. The default is to use the
built-in table (see the ``--with-attributes-table'' build
option). This directive can be overridden with the ``-a''
command line option.

braille-device _d_e_v_i_c_e,...
Specify the device to which the braille display is connected
(see section ``Braille Device Specification''). See the
``--with-braille-device'' build option for the default
established during the build procedure. This directive can be
overridden with the ``-d'' command line option.

braille-driver _d_r_i_v_e_r,...|auto
Specify the braille display driver (see section ``Driver
Specification''). The default is to perform autodetection.
This directive can be overridden with the ``-b'' command line
option.

braille-parameters [_d_r_i_v_e_r:]_n_a_m_e=_v_a_l_u_e,...
Specify parameters for the braille display drivers. If the same
parameter is specified more than once, then its rightmost
assignment is used. If a parameter name is qualified by a
driver (see section ``Driver Identification Codes'') then that
setting only applies to that driver; if it isn't then it applies
to all drivers. For a description of the parameters accepted by
a specific driver, please see the documentation for that driver.
See the ``--with-braille-parameters'' build option for the
defaults established during the build procedure. This directive
can be overridden with the ``-B'' command line option.

contraction-table _f_i_l_e
Specify the contraction table (see section ``Contraction
Tables'' for details). If a relative path is supplied, then
it's anchored at /etc/brltty (see the ``--with-data-directory''
and the ``--with-execute-root'' build options for more details).
The .ctb extension is optional. The contraction table is used
when the 6-dot braille feature is activated (see the ``SIXDOTS''
command and the ``Text Style'' preference). The default is to
display uncontracted 6-dot braille. This directive can be
overridden with the ``-c'' command line option. It isn't
available if the ``--disable-contracted-braille'' build option
was specified.

key-table _f_i_l_e|auto
Specify the key table (see section ``Key Tables'' for details).
If a relative path is supplied, then it's anchored at
/etc/brltty (see the ``--with-data-directory'' and the ``--with-
execute-root'' build options for more details). The .ktb
extension is optional. The default is not to use a key table.
This directive can be overridden with the ``-k'' command line
option.

keyboard-properties _n_a_m_e=_v_a_l_u_e,...
Specify the properties of the keyboard(s) to be monitored. If
the same property is specified more than once, then its
rightmost assignment is used. See section ``Keyboard
Properties'' for a list of the properties which may be
specified. The default is to monitor all keyboards. This
directive can be overridden with the ``-K'' command line option.

midi-device _d_e_v_i_c_e
Specify the device to use for the Musical Instrument Digital
Interface (see section ``MIDI Device Specification''). This
directive can be overridden with the ``-m'' command line option.
It isn't available if the ``--disable-midi-support'' build
option was specified.

pcm-device _d_e_v_i_c_e
Specify the device to use for digital audio (see section ``PCM
Device Specification''). This directive can be overridden with
the ``-p'' command line option. It isn't available if the
``--disable-pcm-support'' build option was specified.

release-device _b_o_o_l_e_a_n
Whether or not to release the device to which the braille
display is connected when the current screen or window can't be
read.

oonn Release the device.

ooffff
Don't release the device.

The default setting is on on Windows platforms and off on all
other platforms. This directive can be overridden with the
``-r'' command line option.

screen-driver _d_r_i_v_e_r
Specify the screen driver (see section ``Supported Screen
Drivers''). See the ``--with-screen-driver'' build option for
the default established during the build procedure. This
directive can be overridden with the ``-x'' command line option.

screen-parameters [_d_r_i_v_e_r:]_n_a_m_e=_v_a_l_u_e,...
Specify parameters for the screen drivers. If the same
parameter is specified more than once, then its rightmost
assignment is used. If a parameter name is qualified by a
driver (see section ``Supported Screen Drivers'') then that
setting only applies to that driver; if it isn't then it applies
to all drivers. For a description of the parameters accepted by
a specific driver, please see the documentation for that driver.
See the ``--with-screen-parameters'' build option for the
defaults established during the build procedure. This directive
can be overridden with the ``-X'' command line option.

speech-driver _d_r_i_v_e_r,...|auto
Specify the speech synthesizer driver (see section ``Driver
Specification''). The default is to perform autodetection.
This directive can be overridden with the ``-s'' command line
option. It isn't available if the ``--disable-speech-support''
build option was specified.

speech-fifo _f_i_l_e
Specify the FIFO (a special file which works like a pipe) which
is to be used by other applications that wish to gain access to
BRLTTY's speech driver. This directive can be overridden with
the ``-F'' command line option. It isn't available if the
``--disable-speech-support'' build option was specified.

speech-parameters [_d_r_i_v_e_r:]_n_a_m_e=_v_a_l_u_e,...
Specify parameters for the speech synthesizer drivers. If the
same parameter is specified more than once, then its rightmost
assignment is used. If a parameter name is qualified by a
driver (see section ``Driver Identification Codes'') then that
setting only applies to that driver; if it isn't then it applies
to all drivers. For a description of the parameters accepted by
a specific driver, please see the documentation for that driver.
See the ``--with-speech-parameters'' build option for the
defaults established during the build procedure. This directive
can be overridden with the ``-S'' command line option.

text-table _f_i_l_e|auto
Specify the text table (see section ``Text Tables'' for
details). If a relative path is supplied, then it's anchored at
/etc/brltty (see the ``--with-data-directory'' and the ``--with-
execute-root'' build options for more details). The .ttb
extension is optional. The default is to perform locale-based
autoselection, with fallback to the built-in table (see the
``--with-text-table'' build option). This directive can be
overridden with the ``-t'' command line option.

44..33.. CCoommmmaanndd LLiinnee OOppttiioonnss

Many settings can be explicitly specified when invoking BRLTTY. The
brltty command accepts the following options:

-a_f_i_l_e --attributes-table=_f_i_l_e
Specify the attributes table (see section ``Attributes Tables''
for details). If a relative path is supplied, then it's
anchored at /etc/brltty (see the ``--with-data-directory'' and
the ``--with-execute-root'' build options for more details).
The .atb extension is optional. See the ``attributes-table''
configuration file directive for the default run-time setting.
This setting can be changed with the ``Attributes Table''
preference.

-b_d_r_i_v_e_r,...|auto --braille-driver=_d_r_i_v_e_r,...|auto
Specify the braille display driver (see section ``Driver
Specification''). See the ``braille-driver'' configuration file
directive for the default run-time setting.

-c_f_i_l_e --contraction-table=_f_i_l_e
Specify the contraction table (see section ``Contraction
Tables'' for details). If a relative path is supplied, then
it's anchored at /etc/brltty (see the ``--with-data-directory''
and the ``--with-execute-root'' build options for more details).
The .ctb extension is optional. The contraction table is used
when the 6-dot braille feature is activated (see the ``SIXDOTS''
command and the ``Text Style'' preference). See the
``contraction-table'' configureation file directive for the
default run-time setting. This setting can be changed with the
``Contraction Table'' preference. This option isn't available
if the ``--disable-contracted-braille'' build option was
specified.

-d_d_e_v_i_c_e,... --braille-device=_d_e_v_i_c_e,...
Specify the device to which the braille display is connected
(see section ``Braille Device Specification''). See the
``braille-device'' configuration file directive for the default
run-time setting.

-e --standard-error
Write diagnostic messages to standard error. The default is to
record them via syslog.

-f_f_i_l_e --configuration-file=_f_i_l_e
Specify the location of the ``configuration file'' which is to
be used for the establishing of default run-time settings.

-h --help
Display a summary of the command line options accepted by
BRLTTY, and then exit.

-k_f_i_l_e --key-table=_f_i_l_e
Specify the key table (see section ``Key Tables'' for details).
If a relative path is supplied, then it's anchored at
/etc/brltty (see the ``--with-data-directory'' and the ``--with-
execute-root'' build options for more details). The .ktb
extension is optional. See the ``key-table'' configureation
file directive for the default run-time setting. This setting
can be changed with the ``Key Table'' preference.

-l_l_e_v_e_l --log-level=_l_e_v_e_l
Specify the severity threshold for diagnostic message
generation. The following levels are recognized.

00 emergency

11 alert

22 critical

33 error

44 warning

55 notice

66 information

77 debug

Either the number or the name may be supplied, and the name may
be abbreviated. If not specified, then information is assumed
(see the ``-q'' option for more details).

-m_d_e_v_i_c_e --midi-device=_d_e_v_i_c_e
Specify the device to use for the Musical Instrument Digital
Interface (see section ``MIDI Device Specification''). See the
``midi-device'' configuration file directive for the default
run-time setting. This option isn't available if the
``--disable-midi-support'' build option was specified.

-n --no-daemon
Specify that BRLTTY is to remain in the foreground. If not
specified, then BRLTTY becomes a background process (daemon)
after initializing itself but before starting any of the
selected drivers.

-p_d_e_v_i_c_e --pcm-device=_d_e_v_i_c_e
Specify the device to use for digital audio (see section ``PCM
Device Specification''). See the ``pcm-device'' configuration
file directive for the default run-time setting. This option
isn't available if the ``--disable-pcm-support'' build option
was specified.

-q --quiet
Log less information. This option changes the default log level
(see the ``-l'' option) to notice if either the ``-v'' or the
``-V'' option is specified, and to warning otherwise.

-r --release-device
Release the device to which the braille display is connected
when the current screen or window can't be read. See the
``release-device'' configuration file directive for the default
run-time setting.

-s_d_r_i_v_e_r,...|auto --speech-driver=_d_r_i_v_e_r,...|auto
Specify the speech synthesizer driver (see section ``Driver
Specification''). See the ``speech-driver'' configuration file
directive for the default run-time setting. This option isn't
available if the ``--disable-speech-support'' build option was
specified.

-t_f_i_l_e --text-table=_f_i_l_e
Specify the text table (see section ``Text Tables'' for
details). If a relative path is supplied, then it's anchored at
/etc/brltty (see the ``--with-data-directory'' and the ``--with-
execute-root'' build options for more details). The .ttb
extension is optional. See the ``text-table'' configureation
file directive for the default run-time setting. This setting
can be changed with the ``Text Table'' preference.

-v --verify
Display the current versions of BRLTTY itself, of the server
side of its application programming interface, and of the
selected braille and speech drivers, and then exit. If the
``-q'' option isn't specified, then also display the values of
the options after all sources have been considered. If more
than one braille driver (see the ``-b'' command line option)
and/or more than one braille device (see the ``-d'' command line
option) has been specified then braille display autodetection is
performed. If more than one speech driver (see the ``-s''
command line option) has been specified then speech synthesizer
autodetection is performed.

-x_d_r_i_v_e_r --screen-driver=_d_r_i_v_e_r
Specify the screen driver (see section ``Supported Screen
Drivers''). See the ``screen-driver'' configuration file
directive for the default run-time setting.

-A_n_a_m_e=_v_a_l_u_e,... --api-parameters=_n_a_m_e=_v_a_l_u_e,...
Specify parameters for the Application Programming Interface.
If the same parameter is specified more than once, then its
rightmost assignment is used. For a description of the
parameters accepted by the interface, please see the BBrrllAAPPII
reference manual. See the ``api-parameters'' configuration file
directive for the default run-time settings.

-B[_d_r_i_v_e_r:]_n_a_m_e=_v_a_l_u_e,... --braille-parame-
ters=[_d_r_i_v_e_r:]_n_a_m_e=_v_a_l_u_e,...
Specify parameters for the braille display drivers. If the same
parameter is specified more than once, then its rightmost
assignment is used. If a parameter name is qualified by a
driver (see section ``Driver Identification Codes'') then that
setting only applies to that driver; if it isn't then it applies
to all drivers. For a description of the parameters accepted by
a specific driver, please see the documentation for that driver.
See the ``braille-parameters'' configuration file directive for
the default run-time settings.

-E --environment-variables
Recognize environment variables when determining the default
settings for unspecified command line options (see section
``Command Line Options''). If this option is specified, and if
the environment variable associated with an unspecified option
is defined, then the value of that environment variable is used.
The names of these environment variables are based on the long
names of the options they correspond to:

· All letters are in upper case.

· Underscores (_) are used instead of minus signs (-).

· The prefix BRLTTY_ is added.

This option is particularly useful on the Linux operating system
as it allows default settings to be passed to BRLTTY via boot
parameters. The following environment variables are supported:

BRLTTY_API_PARAMETERS
Parameters for the Application Programming Interface (see the
``-A'' command line option).

BRLTTY_ATTRIBUTES_TABLE
The attributes table (see the ``-a'' command line option).

BRLTTY_BRAILLE_DEVICE
The braille display device (see the ``-d'' command line
option).

BRLTTY_BRAILLE_DRIVER
The braille display driver (see the ``-b'' command line
option).

BRLTTY_BRAILLE_PARAMETERS
Parameters for the braille display driver (see the ``-B''
command line option).

BRLTTY_CONFIGURATION_FILE
The configuration file (see the ``-f'' command line option).

BRLTTY_CONTRACTION_TABLE
The contraction table (see the ``-c'' command line option).

BRLTTY_KEY_TABLE
The key table (see the ``-k'' command line option).
BRLTTY_KEYBOARD_PROPERTIES
The keyboard properties (see the ``-K'' command line option).

BRLTTY_MIDI_DEVICE
The Musical Instrument Digital Interface device (see the
``-m'' command line option).

BRLTTY_PCM_DEVICE
The digital audio device (see the ``-p'' command line
option).

BRLTTY_RELEASE_DEVICE
Whether or not to release the device to which the braille
display is connected when the current screen or window can't
be read (see the ``-r'' command line option).

BRLTTY_SCREEN_PARAMETERS
Parameters for the screen driver (see the ``-X'' command line
option).

BRLTTY_SPEECH_DRIVER
The speech synthesizer driver (see the ``-s'' command line
option).

BRLTTY_SPEECH_FIFO
The speech pass-through FIFO (see the ``-F'' command line
option).

BRLTTY_SPEECH_PARAMETERS
Parameters for the speech synthesizer driver (see the ``-S''
command line option).

BRLTTY_TEXT_TABLE
The text table (see the ``-t'' command line option).

-F_f_i_l_e --speech-fifo=_f_i_l_e
Specify the FIFO (a special file which works like a pipe) which
is to be used by other applications that wish to gain access to
BRLTTY's speech driver. If not specified, no FIFO is created.
See the ``speech-fifo'' configuration file directive for the
default run-time setting. This option isn't available if the
``--disable-speech-support'' build option was specified.

-I --install-service
Install BRLTTY as the BrlAPI service. This means that:

· BRLTTY will be automatically started when the system is
booted.

· Applications can know that a BrlAPI server is running.

This option is only supported on the Windows platform.

-K_n_a_m_e=_v_a_l_u_e,... --keyboard-properties=_n_a_m_e=_v_a_l_u_e,...
Specify the properties of the keyboard(s) to be monitored. If
the same property is specified more than once, then its
rightmost assignment is used. See section ``Keyboard
Properties'' for a list of the properties which may be
specified. See the ``keyboard-properties'' configuration file
directive for the default run-time settings.

-M_c_s_e_c_s --message-delay=_c_s_e_c_s
Specify the amount of time (in hundredths of a second) that
BRLTTY keeps its own internally generated messages on the
braille display. If not specified, then 400 (4 seconds) is
assumed.
-N --no-api
Disable the application programming interface.

-P_f_i_l_e --pid-file=_f_i_l_e
Specify the file wherein BRLTTY is to write its process
identifier (pid). If not specified, BRLTTY doesn't write its
process identifier anywhere.

-R --remove-service
Remove the BrlAPI service. This means that:

· BRLTTY will not be automatically started when the system is
booted.

· Applications can know that no BrlAPI server is running.

This option is only supported on the Windows platform.

-S[_d_r_i_v_e_r:]_n_a_m_e=_v_a_l_u_e,... --speech-parame-
ters=[_d_r_i_v_e_r:]_n_a_m_e=_v_a_l_u_e,...
Specify parameters for the speech synthesizer drivers. If the
same parameter is specified more than once, then its rightmost
assignment is used. If a parameter name is qualified by a
driver (see section ``Driver Identification Codes'') then that
setting only applies to that driver; if it isn't then it applies
to all drivers. For a description of the parameters accepted by
a specific driver, please see the documentation for that driver.
See the ``speech-parameters'' configuration file directive for
the default run-time settings.

-U_c_s_e_c_s --update-interval=_c_s_e_c_s
Specify the interval (in hundredths of a second) at which the
braille window is updated with new screen content. If not
specified, then 4 (40 milliseconds) is assumed.

-V --version
Display the current versions of BRLTTY itself, of the server
side of its application programming interface, and of those
drivers which have been linked into its binary, and then exit.
If the ``-q'' option isn't specified, then also display
copyright information.

-X[_d_r_i_v_e_r:]_n_a_m_e=_v_a_l_u_e,... --screen-parame-
ters=[_d_r_i_v_e_r:]_n_a_m_e=_v_a_l_u_e,...
Specify parameters for the screen drivers. If the same
parameter is specified more than once, then its rightmost
assignment is used. If a parameter name is qualified by a
driver (see section ``Supported Screen Drivers'') then that
setting only applies to that driver; if it isn't then it applies
to all drivers. For a description of the parameters accepted by
a specific driver, please see the documentation for that driver.
See the ``screen-parameters'' configuration file directive for
the default run-time settings.

55.. FFeeaattuurree DDeessccrriippttiioonnss

55..11.. CCuurrssoorr RRoouuttiinngg

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.

Some braille displays have a button, known as a routing key, above
each cell. These keys use the ``ROUTE'' command to route the cursor
right to the desired location.

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 vi), 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 lynx) 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).

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.

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.

A safer but less powerful cursor routing command, ``CSRJMP_VERT'',
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 lynx) wherein horizontal cursor motion must
never be attempted.

55..22.. CCuutt aanndd PPaassttee

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:

1. 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:

· invoke the ``CUTBEGIN'' command to start a new cut buffer

· invoke the ``CUTAPPEND'' command to append to the existing cut
buffer

by pressing the key(s) associated with it and then pressing the
routing key associated with the character.

2. 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

· invoke the ``CUTRECT'' command to cut a rectangular area

· invoke the ``CUTLINE'' command to cut a linear area

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.

3. Insert (paste) the text where it's needed. Place the cursor over
the character where the text is to be pasted, and invoke the
``PASTE'' 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 vi's command mode), then you'd better be aware
of what the characters in the cut buffer will do.

The cut buffer is also used by the ``PRSEARCH/NXSEARCH'' commands.

55..33.. PPooiinntteerr ((MMoouussee)) SSuuppppoorrtt vviiaa GGPPMM

If BRLTTY is configured with the ``--enable-gpm'' build option on a
system where the gpm application has been installed, then it'll
interact with the pointer (mouse).

Moving the pointer drags the braille window (see the ``Window Follows
Pointer'' 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.

gpm uses reverse video to show where the pointer is. Underlining of
highlighted characters (see the ``ATTRVIS'' command for details)
should be turned on, therefore, when the braille user wishes to use
the pointer.

This feature also gives the braille user access to gpm's cut-and-paste
capability. Although you should read gpm's own documentation, here
are some notes on how it works.

· Copy the current character to the cut buffer by single-clicking the
left button.

· Copy the current word (space-delimited) to the cut buffer by
double-clicking the left button.
· Copy the current line to the cut buffer by tripple-clicking the
left button.

· Copy a linear region to the cut buffer as follows:

1. Place the pointer on the first character of the region.

2. Press (and hold) the left button.

3. Move the pointer to the last character of the region (all
currently selected characters are highlighted).

4. Release the left button.

· 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.

· Append to the cut buffer by using the right button of a three-
button mouse.

55..44.. AAlleerrtt TTuunneess

BRLTTY alerts you to the occurrence of significant events by playing
short predefined tunes. This feature can be activated and deactivated
with either the ``TUNES'' command or the ``Alert Tunes'' preference.
The tunes are played via the internal beeper by default, but other
alternatives can be selected with the ``Tune Device'' preference.

Each significant event is associated, from highest to lowest priority,
with one or more of the following:

aa ttuunnee
If a tune has been associated with the event, if the ``Alert
Tunes'' preference (see also the ``TUNES'' command) is active,
and if the selected tune device (see the ``Tune Device''
preference) can be opened, then the tune is played.

aa ddoott ppaatttteerrnn
If a dot pattern has been associated with the event, and if the
``Alert Dots'' 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.

aa mmeessssaaggee
If a message has been associated with the event, and if the
``Alert Messages'' preference is active, then it is displayed
for a few seconds (see the ``-M'' command line option).

These events include:

· When the braille display driver starts or stops.

· When a lengthy command completes.

· When a command cannot be executed.

· When a mark is set.

· When the start or end of the cut block is set.

· When a feature is activated or deactivated.

· When cursor tracking is turned on or off.

· When the screen image is frozen or unfrozen.

· When the braille window wraps either down to the beginning of the
next line or up to the end of the previous line.

· When identical lines are skipped.

· When a requested motion cannot be performed.

· When cursor routing starts, finishes, or fails.

55..55.. PPrreeffeerreenncceess SSeettttiinnggss

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 ``PREFSAVE'' command. The most
recently saved settings can be restored at any time with the
``PREFLOAD'' command.

The name for this file is /etc/brltty-_d_r_i_v_e_r.prefs. where _d_r_i_v_e_r is
the two-letter ``driver identification code''.

55..55..11.. TThhee PPrreeffeerreenncceess MMeennuu

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.

The meny is activated by the ``PREFMENU'' command. The braille
display briefly (see the ``-M'' command line option) shows the menu
title, and then presents the current item and its current setting.

55..55..11..11.. NNaavviiggaattiinngg tthhee MMeennuu

See ``Menu Navigation Commands'' 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.

TOP/BOT, TOP_LEFT/BOT_LEFT, PAGE_UP/PAGE_DOWN
Go to the first/last item in the menu (same as
``MENU_FIRST_ITEM/MENU_LAST_ITEM'').

LNUP/LNDN, PRDIFLN/NXDIFLN, CURSOR_UP/CURSOR_DOWN
Go to the previous/next item in the menu (same as
``MENU_PREV_ITEM/MENU_NEXT_ITEM'').

WINUP/WINDN, CHRLT/CHRRT, CURSOR_LEFT/CURSOR_RIGHT, BACK/HOME
Decrement/increment the current menu item's setting (same as
``MENU_PREV_SETTING/MENU_NEXT_SETTING'').

Notes:

· The routing keys can also be used to select a setting for the
current item. If the item has numeric settings, then the entire
row of routing keys acts as a scroll bar which covers the full
range of valid values. If the item has named settings, then the
routing keys correspond ordinally with the settings.

· Use the PREFLOAD command to undo all of the changes which were made
since entering the menu.

· Use the PREFMENU 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.

55..55..11..22.. TThhee MMeennuu IItteemmss

SSaavvee oonn EExxiitt
When exiting the preferences menu:

NNoo Don't automatically save the preferences settings.

YYeess
Automatically save the preferences settings.

The initial setting is No.

TTeexxtt SSttyyllee
When displaying screen content (see the ``DISPMD'' command),
show characters:

88--ddoott
With all eight dots.

66--ddoott
With only dots 1 through 6. If a contraction table has been
selected (see the ``-c'' command line option and the
``contraction-table'' configuration file directive), then it
is used.

This setting can also be changed with the ``SIXDOTS'' command.

SSkkiipp IIddeennttiiccaall LLiinneess
When moving either up or down exactly one line with the
``LNUP/LNDN'' commands, as well as the line wrapping feature of
the ``FWINLT/FWINRT'' and ``FWINLTSKIP/FWINRTSKIP'' commands:

NNoo Don't skip past lines which have the same content as the
current line.

YYeess
Skip past lines which have the same content as the current
line.

This setting can also be changed with the ``SKPIDLNS'' command.

SSkkiipp BBllaannkk WWiinnddoowwss
When moving either left or right with the ``FWINLT/FWINRT''
commands:

NNoo Don't skip past blank windows.

YYeess
Skip past blank windows.

This setting can also be changed with the ``SKPBLNKWINS'' com-
mand.

WWhhiicchh BBllaannkk WWiinnddoowwss
If blank windows are to be skipped:

AAllll
Skip all of them.

EEnndd ooff LLiinnee
Only skip those which are at the end (on the right side) of a
line.

RReesstt ooff LLiinnee
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.

SSlliiddiinngg WWiinnddooww
If the cursor is being tracked (see the ``CSRTRK'' command), and
the cursor moves too close to (or beyond) either end of the
braille window:

NNoo Horizontally reposition the window such that its left end is
a multiple of its width from the left edge of the screen.

YYeess
Horizontally reposition the window such that the cursor,
while remaining on that side of the window, is nearer the
centre.

This setting can also be changed with the ``SLIDEWIN'' command.

EEaaggeerr SSlliiddiinngg WWiinnddooww
If the braille window is to slide:

NNoo Reposition it whenever the cursor moves beyond either end.

YYeess
Reposition it whenever the cursor moves too close to either
end.

The initial setting is No.

WWiinnddooww OOvveerrllaapp
When moving either left or right with the ``FWINLT/FWINRT''
commands, this setting specifies how many characters
horizontally adjacent braille windows should overlap each other
by. The initial setting is 0.

AAuuttoorreeppeeaatt
While the key (combination) for a command remains pressed:

NNoo Don't automatically repeat the command.

YYeess
Automatically repeat the command at a regular interval after
an initial delay.

The following commands are eligible for autorepeating:

· The ``LNUP/LNDN'' commands.

· The ``PRDIFLN/NXDIFLN'' commands.

· The ``CHRLT/CHRRT'' commands.

· Braille window panning operations (see the ``Autorepeat
Panning'' preference).

· The Page-Up and Page-Down operations.

· The Cursor-Up and Cursor-Down operations.

· The Cursor-Left and Cursor-Right operations.

· The Backspace and Delete operations.

· Character entry.

Only some drivers support this functionality, the primary limi-
tation being that many braille displays don't signal both key
presses and key releases as distinctly separate events. This
setting can also be changed with the ``AUTOREPEAT'' command.
The initial setting is Yes.

AAuuttoorreeppeeaatt PPaannnniinngg
When the ``Autorepeat'' preference is enabled:

NNoo Don't autorepeat braille window panning operations.

YYeess
Autorepeat braille window panning operations.

This preference affects the ``FWINLT/FWINRT'' commands. The
initial setting is No.

AAuuttoorreeppeeaatt DDeellaayy
When a character is to be autorepeated, this setting specifies
the amount of time (see the note on ``time settings'' below)
which must pass before autorepeating begins. The initial
setting is 50.

AAuuttoorreeppeeaatt IInntteerrvvaall
When a character is being autorepeated, this setting specifies
the amount of time (see the note on ``time settings'' below)
between each reexecution. The initial setting is 10.

SShhooww CCuurrssoorr
When displaying screen content (see the ``DISPMD'' command):

NNoo Don't show the cursor.

YYeess
Show the cursor.

This setting can also be changed with the ``CSRVIS'' command.
The initial setting is Yes.

CCuurrssoorr SSttyyllee
When showing the cursor, represent it:

UUnnddeerrlliinnee
With dots 7 and 8.

BBlloocckk
With all eight dots.

This setting can also be changed with the ``CSRSIZE'' command.

BBlliinnkkiinngg CCuurrssoorr
When the cursor is to be shown:

NNoo Leave it visible all the time.

YYeess
Make it alternately visible and invisible according to a
predefined interval.

This setting can also be changed with the ``CSRBLINK'' command.

CCuurrssoorr VViissiibbllee TTiimmee
When the cursor is to be blinked, this setting specifies the
length of time (see the note on ``time settings'' below) during
each cycle that it is to be visible. The initial setting is 40.

CCuurrssoorr IInnvviissiibbllee TTiimmee
When the cursor is to be blinked, this setting specifies the
length of time (see the note on ``time settings'' below) during
each cycle that it is to be invisible. The initial setting is
40.

SShhooww AAttttrriibbuutteess
When displaying screen content (see the ``DISPMD'' command):

NNoo Don't underline highlighted characters.

YYeess
Underline highlighted characters.

This setting can also be changed with the ``ATTRVIS'' command.

BBlliinnkkiinngg AAttttrriibbuutteess
When highlighted characters are to be underlined:

NNoo Leave the indicator visible all the time.

YYeess
Make the indicator alternately visible and invisible
according to a predefined interval.

This setting can also be changed with the ``ATTRBLINK'' command.

AAttttrriibbuutteess VViissiibbllee TTiimmee
When the highlighted character underline is to be blinked, this
setting specifies the length of time (see the note on ``time
settings'' below) during each cycle that it is to be visible.
The initial setting is 20.

AAttttrriibbuutteess IInnvviissiibbllee TTiimmee
When the highlighted character underline is to be blinked, this
setting specifies the length of time (see the note on ``time
settings'' below) during each cycle that it is to be invisible.
The initial setting is 60.

BBlliinnkkiinngg CCaappiittaallss
When displaying screen content (see the ``DISPMD'' command):

NNoo Leave capital letters visible all the time.

YYeess
Make capital letters alternately visible and invisible
according to a predefined interval.

This setting can also be changed with the ``CAPBLINK'' command.

CCaappiittaallss VViissiibbllee TTiimmee
When capital letters are to be blinked, this setting specifies
the length of time (see the note on ``time settings'' below)
during each cycle that they're to be visible. The initial
setting is 60.

CCaappiittaallss IInnvviissiibbllee TTiimmee
When capital letters are to be blinked, this setting specifies
the length of time (see the note on ``time settings'' below)
during each cycle that they're to be invisible. The initial
setting is 20.

BBrraaiillllee FFiirrmmnneessss
Adjust the firmness (or stiffness) of the braille dots. It can
be set to:

· Maximum

· High

· Medium

· Low

· Minimum

This preference is only available if a driver which supports it
is being used. The initial setting is Medium.

BBrraaiillllee SSeennssiittiivviittyy
Adjust the sensitivity of the braille dots to touch. It can be
set to:

· Maximum

· High

· Medium

· Low

· Minimum

This preference is only available if a driver which supports it
is being used. The initial setting is Medium.

WWiinnddooww FFoolllloowwss PPooiinntteerr
When moving the pointer device (mouse):

NNoo Don't drag the braille window.

YYeess
Drag the braille window.

This preference is only presented if the ``--enable-gpm'' build
option was specified.

HHiigghhlliigghhtt WWiinnddooww
When moving the braille window:

NNoo Don't highlight the new screen area.

YYeess
Highlight the new screen area.

This feature enables a sighted observer to see where the braille
window is, and, therefore, to know what the braille user is
reading. Any motion of the braille window (manual, cursor
tracking, etc.), other than when it moves in response to pointer
(mouse) motion (see the ``Window Follows Pointer'' preference),
causes the area of the screen corresponding to the new location
of the braille window to be highlighted. If the ``Show
Attributes'' preference is enabled then only the character cor-
responding to the upper-left corner of the braille window is
highlighted.

AAlleerrtt TTuunneess
Whenever a significant event with an associated tune occurs (see
``Alert Tunes''):

NNoo Don't play the tune.

YYeess
Play the tune.

This setting can also be changed with the ``TUNES'' command.
The initial setting is Yes.

TTuunnee DDeevviiccee
Play alert tunes via:

BBeeeeppeerr
The internal beeper (console tone generator). This setting
is supported on Linux, on OpenBSD, on FreeBSD, and on NetBSD.
It's always safe to use, although it may be somewhat soft.
This device isn't available if the ``--disable-beeper-
support'' build option was specified.

PPCCMM
The digital audio interface on the sound card. This setting
is supported on Linux (via /dev/dsp), on Solaris (via
/dev/audio), on OpenBSD (via /dev/audio0), on FreeBSD (via
/dev/dsp), and on NetBSD (via /dev/audio0). It doesn't work
when this device is already being used by another
application. This device isn't available if the ``--disable-
pcm-support'' build option was specified.

MMIIDDII
The Musical Instrument Digital Interface on the sound card
This setting is supported on Linux (via /dev/sequencer). It
doesn't work when this device is already being used by
another application. This device isn't available if the
``--disable-midi-support'' build option was specified.

FFMM 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 ``--disable-fm-support'' build option was
specified.

The initial setting is Beeper on those platforms which support
it, and PCM on those platforms which don't.

PPCCMM VVoolluummee
If the digital audio interface of the sound card is being used
to play the alert tunes, this setting specifies the loudness (as
a percentage of the maximum) at which they are to be played.
The initial setting is 70.

MMIIDDII VVoolluummee
If the Musical Instrument Digital Interface (MIDI) of the sound
card is being used to play the alert tunes, this setting
specifies the loudness (as a percentage of the maximum) at which
they are to be played. The initial setting is 70.

MMIIDDII IInnssttrruummeenntt
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 ``MIDI
Instrument Table''). The initial setting is Acoustic Grand
Piano.

FFMM VVoolluummee
If the FM synthesizer of the sound card is being used to play
the alert tunes, this setting specifies the loudness (as a
percentage of the maximum) at which they are to be played. The
initial setting is 70.

AAlleerrtt DDoottss
Whenever a significant event with an associated dot pattern
occurs (see ``Alert Tunes''):

NNoo Don't display the dot pattern.

YYeess
Briefly display the dot pattern.

AAlleerrtt MMeessssaaggeess
Whenever a significant event with an associated message occurs
(see ``Alert Tunes''):

NNoo Don't display the message.

YYeess
Display the message.

If alert tunes are to be played (see the ``TUNES'' command and
the ``Alert Tunes'' 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 ``Alert
Dots'' 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.

SSaayy--LLiinnee MMooddee
When using the ``SAY_LINE'' command:

IImmmmeeddiiaattee
Discard pending speech.

EEnnqquueeuuee
Don't discard pending speech.

The initial setting is Immediate.

AAuuttoossppeeaakk

NNoo Only speak when explicitly requested to do so.

YYeess
Automatically speak:

· the new line when the braille window is moved vertically.

· characters which are entered or deleted.

· the character to which the cursor is moved.

This setting can also be changed with the ``AUTOSPEAK'' command.
The initial setting is No.

SSppeeeecchh RRaattee
Adjust the speech rate (0 is the slowest, 20 is the fastest).
This preference is only available if a driver which supports it
is being used. This setting can also be changed with the
``SAY_SLOWER/SAY_FASTER'' commands. The initial setting is 10.

SSppeeeecchh VVoolluummee
Adjust the speech volume (0 is the softest, 20 is the loudest).
This preference is only available if a driver which supports it
is being used. This setting can also be changed with the
``SAY_SOFTER/SAY_LOUDER'' commands. The initial setting is 10.

SSppeeeecchh PPiittcchh
Adjust the speech pitch (0 is the lowest, 20 is the highest).
This preference is only available if a driver which supports it
is being used. The initial setting is 10.

SSppeeeecchh PPuunnccttuuaattiioonn
Adjust the amount of punctuation which is spoken. It can be set
to:

· All

· Some

· All

This preference is only available if a driver which supports it
is being used. The initial setting is Some.

SSttaattuuss SSttyyllee
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.

NNoonnee
Don't use the status cells. This setting is always safe, but
it's also quite useless.

AAllvvaa
The status cells contain:

11 The location of the cursor (see below).

22 The location of the top-left corner of the braille window
(see below).

33 A letter indicating BRLTTY's state. In order of
precedence:

aa Screen attributes are being shown (see the ``DISPMD''
command).

ff The screen image is frozen (see the ``FREEZE''
command).

ff The cursor is being tracked (see the ``CSRTRK''
command).

_b_l_a_n_k
Nothing special.

The locations of the cursor and the braille window are pre-
sented in an interesting way. Dots 1 through 6 represent the
line number with a letter from a (for 1) through y (for 25).
Dots 7 and 8 (the extra two at the bottom) represent the hor-
izontal braille window number as follows:

NNoo DDoottss
The first (leftmost) window.

DDoott 77
The second window.

DDoott 88
The third window.

DDoottss 77 aanndd 88
The fourth window.

In both cases, the indicators wrap: line 26 is represented by
the letter a, and the fifth horizontal braille window is rep-
resented by no dots at the bottom.

TTiieemmaann
The status cells contain:

11--22
The columns (counting from 1) 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).

33--44
The rows (counting from 1) 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).

55 Each dot indicates if a feature is turned on as follows:

DDoott 11
The screen image is frozen (see the ``FREEZE''
command).

DDoott 22
Screen attributes are being displayed (see the
``DISPMD'' command).

DDoott 33
Alert tunes are being played (see the ``TUNES''
command).

DDoott 44
The cursor is being shown (see the ``CSRVIS'' command).

DDoott 55
The cursor is a solid block (see the ``CSRSIZE''
command).

DDoott 66
The cursor is blinking (see the ``CSRBLINK'' command).

DDoott 77
The cursor is being tracked (see the ``CSRTRK''
command).

DDoott 88
The braille window will slide (see the ``SLIDEWIN''
command).

PPoowweerrBBrraaiillllee 8800
The status cells contain:
11 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.

GGeenneerriicc
This setting passes a lot of information to the braille
driver, and the driver itself decides how to present it.

MMDDVV
The status cells contain:

11--22
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.

VVooyyaaggeerr
The status cells contain:

11 The row (counting from 1) corresponding to the top of the
braille window (see below).

22 The row (counting from 1) whereon the cursor is (see
below).

33 If the screen is frozen (see the ``FREEZE'' command), then
the letter F. If it isn't, then the column (counting from
1) wherein the cursor is (see below).

Row and column numbers are shown as two digits within a sin-
gle 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.

The initial setting is braille display driver dependent.

TTeexxtt TTaabbllee
Select the text table. See section ``Text Tables'' for details.
See the ``-t'' command line option for the initial setting.
This preference isn't saved.

AAttttrriibbuutteess TTaabbllee
Select the attributes table. See section ``Attributes Tables''
for details. See the ``-a'' command line option for the initial
setting. This preference isn't saved.

CCoonnttrraaccttiioonn TTaabbllee
Select the contraction table. See section ``Contraction
Tables'' for details. See the ``-c'' command line option for
the initial setting. This preference isn't saved.

KKeeyy TTaabbllee
Select the key table. See section ``Key Tables'' for details.
See the ``-k'' command line option for the initial setting.
This preference isn't saved.

Notes:

· All time settings are in hundredths of a second. They are
multiples of the braille window update interval (see the ``-U''
command line option) within the range 1 through 100.

55..66.. TThhee SSttaattuuss DDiissppllaayy

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.

Use the ``INFO'' 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.

55..66..11.. DDiissppllaayyss wwiitthh 2211 CCeellllss oorr MMoorree

Short pneumonics have been used, even though they're rather cryptic,
in order to show the precise column layout.

_w_x:_w_y _c_x:_c_y _v_t _t_c_m_f_d_u

_w_x:_w_y
The column and row (counting from 1) on the screen corresponding
to the top-left corner of the braille window.

_c_x:_c_y
The column and row (counting from 1) on the screen corresponding
to the position of the cursor.

_v_t The number (counting from 1) of the current virtual terminal.

_t The state of the cursor tracking feature (see the ``CSRTRK''
command).

bbllaannkk
Cursor tracking is off.

t Cursor tracking is on.

_c The state of the cursor visibility features (see the ``CSRVIS''
and ``CSRBLINK'' commands).

bbllaannkk
The cursor isn't visible, and won't blink when made visible.

b The cursor isn't visible, and will blink when made visible.

v The cursor is visible, and isn't blinking.

B The cursor is visible, and is blinking.

_m The current display mode (see the ``DISPMD'' command).

t Screen content (text) is being displayed.

a Screen highlighting (attributes) is being displayed.

_f The state of the frozen screen feature (see the ``FREEZE''
command).

bbllaannkk
The screen isn't frozen.

f The screen is frozen.

_d The number of braille dots being used to display each character
(see the ``SIXDOTS'' command).

8 All eight dots are being used.

6 Only dots 1 through 6 are being used.

_u The state of the uppercase (capital letter) display features
(see the ``CAPBLINK'' command).

bbllaannkk
Uppercase letters don't blink.

B Uppercase letters blink.

55..66..22.. DDiissppllaayyss wwiitthh 2200 CCeellllss oorr LLeessss

Short pneumonics have been used, even though they're rather cryptic,
in order to show the precise column layout.

_x_x_y_y_s _v_t _t_c_m_f_d_u

_x_x The columns (counting from 1) 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).

_y_y The rows (counting from 1) 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).

_s The settings of some of BRLTTY's features. A feature is turned
on if its corresponding dot is raised.

DDoott 11
Frozen screen image (see the ``FREEZE'' command).

DDoott 22
Display attributes (see the ``DISPMD'' command).

DDoott 33
Alert tunes (see the ``TUNES'' command).

DDoott 44
Visible cursor (see the ``CSRVIS'' command).

DDoott 55
Block cursor (see the ``CSRSIZE'' command).

DDoott 66
Blinking cursor (see the ``CSRBLINK'' command).

DDoott 77
Cursor tracking (see the ``CSRTRK'' command).

DDoott 88
Sliding window (see the ``SLIDEWIN'' command).

_v_t The number (counting from 1) of the current virtual terminal.

_t The state of the cursor tracking feature (see the ``CSRTRK''
command).

bbllaannkk
Cursor tracking is off.

t Cursor tracking is on.

_c The state of the cursor visibility features (see the ``CSRVIS''
and ``CSRBLINK'' commands).

bbllaannkk
The cursor isn't visible, and won't blink when made visible.

b The cursor isn't visible, and will blink when made visible.

v The cursor is visible, and isn't blinking.

B The cursor is visible, and is blinking.

_m The current display mode (see the ``DISPMD'' command).

t Screen content (text) is being displayed.

a Screen highlighting (attributes) is being displayed.

_f The state of the frozen screen feature (see the ``FREEZE''
command).

bbllaannkk
The screen isn't frozen.

f The screen is frozen.

_d The number of braille dots being used to display each character
(see the ``SIXDOTS'' command).

8 All eight dots are being used.

6 Only dots 1 through 6 are being used.

_u The state of the uppercase (capital letter) display features
(see the ``CAPBLINK'' command).

bbllaannkk
Uppercase letters don't blink.

B Uppercase letters blink.

55..77.. CCoommmmaanndd LLeeaarrnn MMooddee

Command learn mode is an interactive way to learn what the keys on the
braille display do. It can be accessed either by the ``LEARN''
command or via the ``brltest'' utility. This feature isn't available
if the ``--disable-learn-mode'' build option was specified.

When this mode is entered, the message command learn mode 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 ``LEARN'' command is pressed. It exits automatically, and the
message done 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.

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 ``-M'' command line option)
or until any key on the display is pressed.

66.. TTaabblleess

66..11.. TTeexxtt TTaabblleess

Files with names of the form *.ttb are text tables, and with names of
the form *.tti are text subtables. They are used by BRLTTY to
translate the characters on the screen into their corresponding 8-dot
computer braille representations.

BRLTTY is initially configured to use the ``North American Braille
Computer Code'' (NABCC) text table. In addition to this default, the
following alternatives are provided:

aauuttoo
locale-based autoselection

aarr Arabic (generic)

aass Assamese

aawwaa
Awadhi

bbgg Bulgarian

bbhh Bihari

bbnn Bengali

bboo Tibetan

bbrraa
Braj

bbrrff
for viewing .brf files within an editor or pager

ccss Czech

ccyy Welsh

ddaa Danish

ddee German

ddrraa
Dravidian

eell Greek

eenn English

eenn__CCAA
English (Canada)

eenn__UUKK
English (United Kingdom)

eenn__UUSS
English (United States)

eenn--nnaabbcccc
English (North American Braille Computer Code)

eeoo Esperanto

eess Spanish

eett Estonian

ffii Finnish

ffrr French

ffrr__CCAA
French (Canada)

ffrr__FFRR
French (France)

ffrr--22000077
French (unified)

ffrr--ccbbiiffss
French (Code Braille Informatique Français Standard)

ggaa Irish

ggdd Gaelic

ggoonn
Gondi

gguu Gujarati

hhee Hebrew

hhii Hindi

hhrr Croatian

hhuu Hungarian

hhyy Armenian

iiss Icelandic

iitt Italian

kkhhaa
Khasi

kknn Kannada

kkookk
Konkani

kkrruu
Kurukh

lltt Lituanian

llvv Latvian

mmgg Malagasy

mmii Maori

mmll Malayalam

mmnnii
Manipuri

mmrr Marathi

mmtt Maltese

mmuunn
Mundari

mmwwrr
Marwari

nnee Nepali

nneeww
Newari

nnll Dutch

nnll__BBEE
Dutch (Belgium)

nnll__NNLL
Dutch (Netherlands)

nnoo Norwegian

nnoo--ggeenneerriicc
Norwegian (with support for other languages)

nnoo--oouubb
Norwegian (Offentlig Utvalg for Blindeskrift)

nnwwcc
Old Newari

oorr Oriya

ppaa Panjabi

ppii Pali

ppll Polish

pptt Portuguese

rroo Romanian

rruu Russian

ssaa Sanskrit

ssaatt
Santali

ssdd Sindhi

sskk Slovak

ssvv Swedish

ssww Swahili

ttaa Tamil

ttee Telugu

ttrr Turkish

vvii Vietnamese

See the ``-t'' command line option, the ``text-table'' configuration
file directive, and the ``--with-text-table'' build option for details
regarding how to use an alternate text table.

66..11..11.. TTeexxtt TTaabbllee FFoorrmmaatt

A text table consists of a sequence of directives, one per line, which
define how each character is to be represented in braille. UTF-8
character encoding must be used. 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.

66..11..22.. TTeexxtt TTaabbllee DDiirreeccttiivveess

The following directives are provided:

char _c_h_a_r_a_c_t_e_r _d_o_t_s # _c_o_m_m_e_n_t
Use the char directive to specify how a Unicode character is to
be represented in braille.

_c_h_a_r_a_c_t_e_r
The Unicode character being defined. It may be:

· Any single character other than a backslash or a white-
space character.

· A backslash-prefixed special character. These are:

\\bb The backspace character. -

\\ff The formfeed character. -

\\nn The newline character. -

\\oo######
The three-digit octal representation of a character. -

\\rr The carriage return character. -

\\ss The space character. -

\\tt The horizontal tab character. -

\\uu########
The four-digit hexadecimal representation of a
character. -

\\UU################
The eight-digit hexadecimal representation of a
character. -

\\vv The vertical tab character. -

\\xx####
The two-digit hexadecimal representation of a
character. -

\\XX####
... (the case of the X and of the digits isn't
significant) -

\\## A literal number sign. -

\\<<nnaammee>>
The Unicode name of a character (use _ for space). -

\\\\ A literal backslash.

_d_o_t_s
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 1-8 as defined by the
``Standard Braille Dot Numbering Convention''. The special
dot number 0 is recognized when not enclosed within
parentheses, and means no dots; it may not be used in
conjunction with any other dot number.

Examples:

· char a 1

· char b (12)

· char c ( 4 1 )

· char \\ 12567

· char \s 0

· char \x20 ()

· char \<LATIN_SMALL_LETTER_D> 145

byte _b_y_t_e _d_o_t_s # _c_o_m_m_e_n_t
Use the byte 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 char directive) so
that the text table remains valid regardless of what the local
character set is.

_b_y_t_e
The local character being defined. It may be specified in
the same ways as the _c_h_a_r_a_c_t_e_r operand of the char directive
except that the Unicode-specific forms (\u, \U, \<) may not
be used.

_d_o_t_s
The braille representation of the local character. It may be
specified in the same ways as the _d_o_t_s operand of the char
directive.

include _f_i_l_e # _c_o_m_m_e_n_t
Use the include 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.

_f_i_l_e
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.

66..22.. AAttttrriibbuutteess TTaabblleess

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 ``DISPMD'' command). Each of the eight braille dots represents
one of the eight VGA attribute bits.

The following attributes tables are provided:

aattttrriibbuutteess
The lefthand column represents the foreground colours:

DDoott 11
Red

DDoott 22
Green

DDoott 33
Blue

DDoott 77
Bright

The righthand column represents the background colours:

DDoott 44
Red

DDoott 55
Green

DDoott 66
Blue

DDoott 88
Blink

A dot is raised when its corresponding attribute bit is on.
This is the default attributes table because it's the most intu-
itive. 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.

aattttrriibb
The lefthand column represents the foreground colours:

DDoott 11
Red

DDoott 22
Green

DDoott 33
Blue
DDoott 77
Bright

The righthand column represents the background colours:

DDoott 44
Red

DDoott 55
Green

DDoott 66
Blue

DDoott 88
Blink

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.

See the ``-a'' command line option, the ``attributes-table'' configu-
ration file directive, and the ``--with-attributes-table'' build
option for details regarding how to use an alternate attributes table.

66..22..11.. AAttttrriibbuutteess TTaabbllee FFoorrmmaatt

An attributes table consists of a sequence of directives, one per
line, which define how combinations of VGA attributes are to be
represented in braille. UTF-8 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.

66..22..22.. AAttttrriibbuutteess TTaabbllee DDiirreeccttiivveess

The following directives are provided:

dot _d_o_t _s_t_a_t_e # _c_o_m_m_e_n_t
Use the dot directive to specify what a specific dot represents.

_d_o_t
The dot being defined. It is a single digit within the range
1-8 as defined by the ``Standard Braille Dot Numbering
Convention''.

_s_t_a_t_e
What the dot represents. It may be:

=_a_t_t_r_i_b_u_t_e
The dot is raised if the named attribute is on.

~_a_t_t_r_i_b_u_t_e
The dot is raised if the named attribute is off.

The names of the attribute bits are:

00XX0011
fg-blue

00XX0022
fg-green

00XX0044
fg-red

00XX0088
fg-bright

00XX1100
bg-blue

00XX2200
bg-green

00XX4400
bg-red

00XX8800
blink

Examples:

· dot 1 =fg-red

· dot 2 ~bg-blue

include _f_i_l_e # _c_o_m_m_e_n_t
Use the include 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.

_f_i_l_e
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.

66..33.. CCoonnttrraaccttiioonn TTaabblleess

Files with names of the form *.ctb are contraction tables, and with
names of the form *.cti are contraction subtables. They are used by
BRLTTY to translate character sequences on the screen into their
corresponding contracted braille representations.

BRLTTY presents contracted braille if:

· A contraction table has been selected. See the ``-c'' command line
option and the ``contraction-table'' configuration file directive
for details.

· The 6-dot braille feature has been activated. See the ``SIXDOTS''
command and the ``Text Style'' preference for details.

This feature isn't available if the ``--disable-contracted-
braille'' build option was specified.

The following contraction tables are provided:

aaff Afrikaans (contracted)

aamm Amharic (uncontracted)

ddee--bbaassiiss
German (uncontracted)

ddee--kkuurrzzsscchhrriifftt
German (contracted - 1998 standard)

ddee--vvoollllsscchhrriifftt
German (basic contractions)

eenn--uueebb--gg22
Unified English Braille (grade 2)

eenn--uuss--gg22
American English (grade 2)

eess Spanish (grade 2)

ffrr--aabbrreeggee
French (contracted)

ffrr--iinntteeggrraall
French (uncontracted)

hhaa Hausa (contracted)

iidd Indonesian (contracted)

jjaa Japanese (uncontracted)

kkoo--gg11
Korean (grade 1)

kkoo--gg22
Korean (grade 2)

kkoo Korean (uncontracted)

mmgg Malagasy (contracted)

mmuunn
Munda (contracted)

nnll Dutch (contracted)

nnyy Chichewa (contracted)

iippaa
International Phonetic Alphabet

pptt Portuguese (grade 2)

ssii Sinhalese (uncontracted)

ssww Swahili (contracted)

tthh Thai (contracted)

zzhh--ttww
Taiwanese Chinese (uncontracted)

zzhh--ttww--uuccbb
Taiwanese Chinese (Unique Chinese Braille)

zzuu Zulu (contracted)

See the ``-c'' command line option, and the ``contraction-table'' con-
figuration file directive for details regarding how to use a contrac-
tion table.

66..33..11.. CCoonnttrraaccttiioonn TTaabbllee FFoorrmmaatt

A contraction table consists of a sequence of entries, one per line,
which define how character sequences are to be represented in braille.
UTF-8 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.

The format of a contraction table entry is:

_d_i_r_e_c_t_i_v_e _o_p_e_r_a_n_d ... [_c_o_m_m_e_n_t]

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. class, must precede all references to that entity.

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.

66..33..22.. CCoonnttrraaccttiioonn TTaabbllee OOppeerraannddss

_c_h_a_r_a_c_t_e_r_s
The first operand of a character sequence matching directive is
the character sequence to be matched. Each character within the
sequence may be:

· Any single character other than a backslash or a white-space
character.

· A backslash-prefixed special character. These are:

\\bb The backspace character. -

\\ff The formfeed character. -

\\nn The newline character. -

\\oo######
The three-digit octal representation of a character. -

\\rr The carriage return character. -

\\ss The space character. -

\\tt The horizontal tab character. -

\\uu########
The four-digit hexadecimal representation of a character.
-

\\UU################
The eight-digit hexadecimal representation of a character.
-

\\vv The vertical tab character. -

\\xx####
The two-digit hexadecimal representation of a character.
-

\\XX####
... (the case of the X and of the digits isn't
significant) -

\\## A literal number sign. -

\\<<nnaammee>>
The Unicode name of a character (use _ for space). -

\\\\ A literal backslash.

_r_e_p_r_e_s_e_n_t_a_t_i_o_n
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
1-8 as defined by the ``Standard Braille Dot Numbering
Convention''. The special dot number 0, which may not be used
in conjunction with any other dot number, means no dots.

66..33..33.. OOppccooddeess

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

66..33..33..11.. TTaabbllee AAddmmiinniissttrraattiioonn

These opcodes make it easier to write contraction tables. They have
no direct effect on the character translation.

include _p_a_t_h
Include the contents of another file. Nesting can be to any
depth. Relative paths are anchored at the directory of the
including file.

locale _l_o_c_a_l_e
Define the locale for character interpretation (lowercase,
uppercase, numeric, etc.). The locale may be specified as:

_l_a_n_g_u_a_g_e[[__c_o_u_n_t_r_y][._c_h_a_r_s_e_t][@_m_o_d_i_f_i_e_r]
The _l_a_n_g_u_a_g_e component is required and should be a two-letter
ISO-639 language code. The _c_o_u_n_t_r_y component is optional and
should be a two-letter ISO-3166 country code. The _c_h_a_r_s_e_t
component is optional and should be a character set name,
e.g. ISO-8859-1.

CC 7-bit ASCII.

-- No locale.

The last locale specification applies to the entire table. If
this opcode isn't used then the C locale is assumed.

66..33..33..22.. SSppeecciiaall SSyymmbbooll DDeeffiinniittiioonn

These opcodes define special symbols which must be inserted into the
braille text in order to clarify it.

capsign _d_o_t_s
The symbol which capitalizes a single letter.
begcaps _d_o_t_s
The symbol which begins a block of capital letters within a
word.

endcaps _d_o_t_s
The symbol which ends a block of capital letters within a word.

letsign _d_o_t_s
The symbol which marks a letter which isn't part of a word.

numsign _d_o_t_s
The symbol which marks the beginning of a number.

66..33..33..33.. CChhaarraacctteerr TTrraannssllaattiioonn

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.

Each of these opcodes has a _c_h_a_r_a_c_t_e_r_s operand (which must be
specified as a _s_t_r_i_n_g), 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).

Many of these opcodes have a _d_o_t_s operand which defines the braille
representation for its _c_h_a_r_a_c_t_e_r_s operand. It may also be specified
as an equals sign (=), 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 ``-t'' command line
option and the ``text-table'' 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 ``always'') within
the sequence is to be used.

Some special terms are used within the descriptions of these opcodes.

wwoorrdd
A maximal sequence of one or more consecutive letters.

Now, finally, here are the opcode descriptions themselves:

literal _c_h_a_r_a_c_t_e_r_s
Translate the entire white-space-bounded containing character
sequence into computer braille (see the ``-t'' command line
option and the ``text-table'' configuration file directive).

replace _c_h_a_r_a_c_t_e_r_s _c_h_a_r_a_c_t_e_r_s
Replace the first set of characters, no matter where they
appear, with the second. The replaced characters aren't
reprocessed.

always _c_h_a_r_a_c_t_e_r_s _d_o_t_s
Translate the characters no matter where they appear. If
there's only one character, then, in addition, define the
default representation for that character.

repeatable _c_h_a_r_a_c_t_e_r_s _d_o_t_s
Translate the characters no matter where they appear. Ignore
any consecutive repetitions of the same sequence.
largesign _c_h_a_r_a_c_t_e_r_s _d_o_t_s
Translate the characters no matter where they appear. Remove
white-space between consecutive words matched by this opcode.

lastlargesign _c_h_a_r_a_c_t_e_r_s _d_o_t_s
Translate the characters no matter where they appear. Remove
preceding white-space if the previous word was matched by the
``largesign'' opcode.

word _c_h_a_r_a_c_t_e_r_s _d_o_t_s
Translate the characters if they're a word.

joinword _c_h_a_r_a_c_t_e_r_s _d_o_t_s
Translate the characters if they're a word. Remove the
following white-space if the first character after it is a
letter.

lowword _c_h_a_r_a_c_t_e_r_s _d_o_t_s
Translate the characters if they're a white-space-bounded word.

contraction _c_h_a_r_a_c_t_e_r_s
Prefix the characters with a letter sign (see ``letsign'') if
they're a word.

sufword _c_h_a_r_a_c_t_e_r_s _d_o_t_s
Translate the characters if they're either a word or at the
beginning of a word.

prfword _c_h_a_r_a_c_t_e_r_s _d_o_t_s
Translate the characters if they're either a word or at the end
of a word.

begword _c_h_a_r_a_c_t_e_r_s _d_o_t_s
Translate the characters if they're at the beginning of a word.

begmidword _c_h_a_r_a_c_t_e_r_s _d_o_t_s
Translate the characters if they're either at the beginning or
in the middle of a word.

midword _c_h_a_r_a_c_t_e_r_s _d_o_t_s
Translate the characters if they're in the middle of a word.

midendword _c_h_a_r_a_c_t_e_r_s _d_o_t_s
Translate the characters if they're either in the middle or at
the end of a word.

endword _c_h_a_r_a_c_t_e_r_s _d_o_t_s
Translate the characters if they're at the end of a word.

prepunc _c_h_a_r_a_c_t_e_r_s _d_o_t_s
Translate the characters if they're part of punctuation at the
beginning of a word.

postpunc _c_h_a_r_a_c_t_e_r_s _d_o_t_s
Translate the characters if they're part of punctuation at the
end of a word.

begnum _c_h_a_r_a_c_t_e_r_s _d_o_t_s
Translate the characters if they're at the beginning of a
number.

midnum _c_h_a_r_a_c_t_e_r_s _d_o_t_s
Translate the characters if they're in the middle of a number.

endnum _c_h_a_r_a_c_t_e_r_s _d_o_t_s
Translate the characters if they're at the end of a number.
66..33..33..44.. CChhaarraacctteerr CCllaasssseess

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.

The following character classes are automatically predefined basdd on
the selected locale:

ddiiggiitt
Numeric characters.

lleetttteerr
Both uppercase and lowercase alphabetic characters. Some
locales have additional letters which are neither uppercase nor
lowercase.

lloowweerrccaassee
Lowercase alphabetic characters.

ppuunnccttuuaattiioonn
Printable characters which are neither white-space nor
alphanumeric.

ssppaaccee
White-space characters. In the default locale these are: space,
horizontal tab, vertical tab, carriage return, new line, form
feed.

uuppppeerrccaassee
Uppercase alphabetic characters.

The opcodes which define and use character classes are:

class _n_a_m_e _c_h_a_r_a_c_t_e_r_s
Define a new character class. The _c_h_a_r_a_c_t_e_r_s operand must be
specified as a _s_t_r_i_n_g. A character class may not be used until
it's been defined.

after _c_l_a_s_s _o_p_c_o_d_e ...
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.

before _c_l_a_s_s _o_p_c_o_d_e ...
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.

66..44.. KKeeyy TTaabblleess

Files with names of the form *.ktb are key tables, and with names of
the form *.kti are key subtables. They are used by BRLTTY to bind
braille display and keyboard key combinations to BRLTTY commands.

The names of braille display key table files begin with brl-_x_x-",
where _x_x is the two-letter ``driver identification code''. The rest
of the name identifies the model(s) for which the key table is used.

The names of keyboard key table files begin with kbd-. The rest of
the name describes the kind of keyboard for which the key table has
been designed.

The following keyboard key tables are provided:

kkbbdd--ddeesskkttoopp
bindings for full keyboards

kkbbdd--kkeeyyppaadd
bindings for keypad-based navigation

kkbbdd--llaappttoopp
bindings for keyboards without a keypad

See the ``-k'' command line option, and the ``key-table'' configura-
tion file directive for details regarding how to select a keyboard key
table.

66..44..11.. KKeeyy TTaabbllee DDiirreeccttiivveess

A key table consists of a sequence of directives, one per line, which
define how keys and key combinations are to be interpreted. UTF-8
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 (#) sign then that
line is a comment and is ignored.

The precedence for resolving each key press/release event is as
follows:

1. A hotkey press or release defined within the current context. See
the ``hotkey'' directive for details.

2. A key combination defined within the current context. See the
``bind'' directive for details.

3. A braille keyboard command defined within the current context. See
the ``map'' and ``superimpose'' directives for details.

4. A key combination defined within the default context. See the
``bind'' directive for details.

The following directives are provided:

66..44..11..11.. TThhee AAssssiiggnn DDiirreeccttiivvee

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.

assign _v_a_r_i_a_b_l_e [_v_a_l_u_e]

_v_a_r_i_a_b_l_e
The name of the variable. If the variable doesn't already exist
at the current include level then it is created.

_v_a_l_u_e
The value which is to be assigned to the variable. If it's not
supplied then a zero-length (null) value is assigned.

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.

Examples:

· assign nullValue

· assign ReturnKey Key1

· bind \{ReturnKey} RETURN

66..44..11..22.. TThhee BBiinndd DDiirreeccttiivvee

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.

bind _k_e_y_s _c_o_m_m_a_n_d

_k_e_y_s
The key combination which is to be bound. It's a sequence of
one or more key names separated by plus (+) signs. The final
(or only) key name may be optionally prefixed with an
exclamation (!) 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.

_c_o_m_m_a_n_d
The name of a BRLTTY command. One or more modifiers may be
optionally appended to the command name by using a plus (+) sign
as the separator.

· For commands which enable/disable a feature:

· If the modifier +on is specified then the feature is
enabled.

· If the modifier +off is specified then the feature is
disabled.

· If neither +on nor +off is specified then the state of the
feature is toggled on/off.

· For commands which move the braille window:

· If the modifier +route is specified then, if necessary,
the cursor is automatically routed so that it's always
visible on the braille display.

· For commands which move the braille window to a specific line
on the screen:

· If the modifier +toleft is specified then the braille
window is also moved to the beginning of that line.

· If the modifier +scaled 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.

· For commands which require an offset:

· The modifier +_o_f_f_s_e_t, where _o_f_f_s_e_t is a non-negative
integer, may be specified. If it isn't supplied then +0
is assumed.

Examples:

· bind Key1 CSRTRK

· bind Key1+Key2 CSRTRK+off

· bind Key1+Key3 CSRTRK+on

· bind Key4 TOP

· bind Key5 TOP+route

· bind VerticalSensor GOTOLINE+toleft+scaled

· bind Key6 CONTEXT+1

66..44..11..33.. TThhee CCoonntteexxtt DDiirreeccttiivvee

Define alternate ways to interpret certain key events and/or
combinations. A context contains definitions created by the ``bind'',
``hotkey'', ``map'', and ``superimpose'' directives.

context _i_d_e_n_t_i_f_i_e_r [_t_i_t_l_e]

_i_d_e_n_t_i_f_i_e_r
Which context subsequent definitions are to be created within.
It may be:

· One of these special names:

ddeeffaauulltt
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 ``bind'' directive.

mmeennuu
This context is used when within BRLTTY's preferences
menu.

· An integer within the range 0 through 252. Context 0 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.

_t_i_t_l_e
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.

A context is created the first time it's selected. It may be
reselected any number of times thereafter.

All subsequent definitions until either the next ``context'' 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
default. 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.

If a context has a title (all named contexts and those numeric
contexts for which the _t_i_t_l_e operand has been supplied) then it is
persisten. 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.

If a context doesn't have a title (those numeric contexts for which
the _t_i_t_l_e 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.

Examples:

· context menu

· context 1 Braille Input

· context 2

66..44..11..44.. TThhee HHiiddee DDiirreeccttiivvee

Specify whether or not certain definitions (see the ``bind'',
``hotkey'', ``map'', and ``superimpose'' directives) and notes (see
the ``note'' directive) are included within the key table's help text.

hide _s_t_a_t_e

_s_t_a_t_e
One of these keywords:

oonn They're excluded.

ooffff
They're included.

The specified state applies to all subsequent definitions and notes
until either the next hide directive or the end of the current include
level. The initial state of the top-level key table is off. 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.

Examples:

· hide on

66..44..11..55.. TThhee HHoottkkeeyy DDiirreeccttiivvee

Bind the press and release events of a specific key to two separate
BRLTTY commands. The bindings are defined within the current context.

hotkey _k_e_y _p_r_e_s_s _r_e_l_e_a_s_e

_k_e_y
The name of the key which is to be bound.

_p_r_e_s_s
The name of the BRLTTY command which is to be executed whenever
the key is pressed.

_r_e_l_e_a_s_e
The name of the BRLTTY command which is to be executed whenever
the key is released.

Modifiers may be appended to the command names. See the _c_o_m_m_a_n_d
operand of the ``bind'' directive for details.

Specify NOOP if no command is to be executed. Specifying NOOP for
both commands effectively disables the key.

Examples:

· hotkey Key1 CSRVIS+off CSRVIS+on

· hotkey Key2 NOOP NOOP

66..44..11..66.. TThhee IIffKKeeyy DDiirreeccttiivvee

Conditionally process a key table directive only if the device has a
particular key.

ifkey _k_e_y _d_i_r_e_c_t_i_v_e

_k_e_y
The name of the key whose availability is to be tested.

_d_i_r_e_c_t_i_v_e
The key table directive which is to be conditionally processed.

Examples:

· ifkey Key1 ifkey Key2 bind Key1+Key2 HOME

66..44..11..77.. TThhee IInncclluuddee DDiirreeccttiivvee

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.

include _f_i_l_e

_f_i_l_e
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.

Examples:

· include common.kti

· include /path/to/my/keys.kti

66..44..11..88.. TThhee MMaapp DDiirreeccttiivvee

Map a key to a braille keyboard function. The mapping is defined
within the current context.

map _k_e_y _f_u_n_c_t_i_o_n

_k_e_y
The name of the key which is to be mapped. More than one key
may be mapped to the same braille keyboard function.

_f_u_n_c_t_i_o_n
The name of the braille keyboard function. It may be one of the
following keywords:

DDOOTT11
The upper-left standard braille dot.

DDOOTT22
The middle-left standard braille dot.
DDOOTT33
The lower-left standard braille dot.

DDOOTT44
The upper-right standard braille dot.

DDOOTT55
The middle-right standard braille dot.

DDOOTT66
The lower-right standard braille dot.

DDOOTT77
The lower-left computer braille dot.

DDOOTT88
The lower-right computer braille dot.

SSPPAACCEE
The space bar.

SSHHIIFFTT
The shift key.

UUPPPPEERRCCAASSEE
If a lowercase letter is being entered then translate it to
its uppercase equivalent.

CCOONNTTRROOLL
The control key.

MMEETTAA
The left alt key.

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 ``superimpose'' directives within
the same context are also implicitly included.

Examples:

· map Key1 DOT1

66..44..11..99.. TThhee NNoottee DDiirreeccttiivvee

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.

note _t_e_x_t

_t_e_x_t
The explanation which is to be added. It may contain spaces,
and should be grammatically correct.

Each note specifies exactly one line of explanatory text. Leading
space is ignored so indentation cannot be specified.

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.

Examples:

· note Key1 is the round key at the far left on the front surface.

66..44..11..1100.. TThhee SSuuppeerriimmppoossee DDiirreeccttiivvee

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.

superimpose _f_u_n_c_t_i_o_n

_f_u_n_c_t_i_o_n
The name of the braille keyboard function. See the _f_u_n_c_t_i_o_n
operand of the ``map'' directive for details.

Examples:

· superimpose DOT7

66..44..11..1111.. TThhee TTiittllee DDiirreeccttiivvee

Provide a person-readable summary of the key table's purpose.

title _t_e_x_t

_t_e_x_t
A one-line summary of what the key table is used for. It may
contain spaces, and standard capitalization conventions should
be used.

The title of the key table may be specified only once.

Examples:

· title Bindings for Keypad-based Navigation

66..44..22.. KKeeyybbooaarrdd PPrrooppeerrttiieess

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 ``-K'' command line option, and the ``keyboard-
properties'' configuration file directive):

ttyyppee
The bus type, specified as one of the following keywords: any,
ps2, usb, bluetooth.

vveennddoorr
The vendor identifier, specified as a 16-bit unsigned integer.

pprroodduucctt
The product identifier, specified as a 16-bit unsigned integer.

The vendor and product identifiers may be specified in decimal (no
prefix), octal (prefixed by 0), or hexadecimal (prefixed by 0x).
Specifying 0 means match any value (as if the property weren't
specified).

77.. AAddvvaanncceedd TTooppiiccss

77..11.. IInnssttaalllliinngg MMuullttiippllee VVeerrssiioonnss

It's easy to have more than one version of BRLTTY installed on the
same system at the same time. This capability allows you to test a
new version before removing the old one.

The ``--with-execute-root'' build option allows you to install the
complete ``installed file hierarchy'' anywhere you want such that it's
entirely self-contained. Remembering that it's best to keep all of
BRLTTY's components within the root file system, you can build it like
this:

./configure --with-execute-root=/brltty-3.1
make install

You can then run it like this:

/brltty-3.1/bin/brltty

When version 3.2 is released, just install it in a different location
and run the new executable from there.

./configure --with-execute-root=/brltty-3.2
make install
/brltty-3.2/bin/brltty

So far, this paradigm is somewhat awkward for at least two reasons.
One is that these long path names are too hard to type, and the other
is that you don't want to fiddle with your system's boot sequence each
time you want to switch to a different version of BRLTTY. These
problems are easily solved by adding a symbolic link for the
executable.

ln -s /brltty-3.1/bin/brltty /bin/brltty

When it's time to switch to the newer version, just repoint the sym-
bolc link.

ln -s /brltty-3.2/bin/brltty /bin/brltty

If you'd like to get really fancy, then introduce another level of
indirection in order to make all of BRLTTY's files for any given
version look like they're in all of the standard places. First,
create a symbolic link through a common repointable location from each
of BRLTTY's standard locations.

ln -s /brltty/bin/brltty /bin/brltty
ln -s /brltty/etc/brltty /etc/brltty
ln -s /brltty/lib/brltty /lib/brltty

Then all you need to do is to point /brltty to the desired version.

ln -s /brltty-3.1 /brltty

77..22.. IInnssttaallllaattiioonn//RReessccuuee RRoooott DDiisskkss ffoorr LLiinnuuxx

BRLTTY can run as a stand-alone executable. Everything it needs to
know can be explicitly configured at build-time (see ``Build
Options''). If the data directory (see the ``--with-data-directory''
and ``--with-execute-root'' build options) doesn't exist, then BRLTTY
looks in /etc for the files it needs. Even if any of these files
don't exist at all, BRLTTY still works!

If, for some reason, you ever create the data directory (usually
/etc/brltty) by hand, it's important to set its permissions so that
only root can create files within it.

chmod 755 /etc/brltty

The screen content inspection device (usually /dev/vcsa) is required.
It should already exist unless your Linux distribution is quite old.
If necessary, you can create it with:

mknod /dev/vcsa c 7 128
chmod 660 /dev/vcsa
chown root.tty /dev/vcsa

One problem often encountered when trying to use BRLTTY in an
uncertain environment like a root disk or an incomplete system is that
it might not find the shared libraries (or parts thereof) which it
needs. Root disks often use subset and/or outdated versions of the
libraries which may be inadequate. The solution is to configure
BRLTTY with the ``--enable-standalone-programs'' build option. This
removes all dependencies on shared libraries, but, unfortunately, also
creates a larger executable. There are a number of build options
which can be used to selectively remove unneeded features from BRLTTY
in order to somewhat mitigate this problem (see section ``Build
Features'').

The executable is stripped during the ``make install''. This
significantly reduces its size by removing its symbol table. You'll
get a much smaller executable, therefore, if you complete the full
build procedure, and then copy it from its installed location. If,
however, you copy it from the build directory, it'll be way too big.
Don't forget to strip it.

strip brltty

77..33.. FFuuttuurree EEnnhhaanncceemmeennttss

Apart from fixing bugs and supporting more types of braille displays,
we hope, time permitting, to work on the following:

BBeetttteerr AAttttrriibbuuttee HHaannddlliinngg

· Attribute tracking.

· Mixed text and attribute mode.

SSccrroollll TTrraacckkiinngg
Locking the braille window to one line as it scrolls on the
screen.

BBeetttteerr SSppeeeecchh SSuuppppoorrtt

· Mixed braille and speech for faster reading of text.

· Better speech navigation.

· More speech synthesizers.

SSccrreeeenn SSuubbrreeggiioonnss
Ignore cursor motion outside the region, and set soft
navigational boundaries at the edges of the region.

See the file TODO for a more complete list.

77..44.. KKnnoowwnn BBuuggss

At the time of writing (December 2001), the following problems are
known:

Cursor routing is implemented as a looping sub-process which runs at
reduced priority to avoid using too much cpu time. Different system
loads require different settings of its parameters. The defaults work
very well in a typical Unix editor on a fairly lightly loaded system,
but very poorly in some other situations, e.g. over a slow serial link
to a remote host.

AA.. SSuuppppoorrtteedd BBrraaiillllee DDiissppllaayyss

BRLTTY supports the following braille displays:

BB.. SSuuppppoorrtteedd SSppeeeecchh SSyynntthheessiizzeerrss

BRLTTY supports the following speech synthesizers:

Name Models
_____________________________________________________________
Alva Delphi (4nn)
BrailleLite
CombiBraille
eSpeak text to speech engine
ExternalSpeech runs /usr/local/bin/externalspeech
Festival text to speech engine
FestivalLite text to speech engine
GenericSay pipes to /usr/local/bin/say
Mikropuhe text to speech engine
Swift text to speech engine
Theta text to speech engine
ViaVoice text to speech engine

CC.. DDrriivveerr IIddeennttiiffiiccaattiioonn CCooddeess

DD.. SSuuppppoorrtteedd SSccrreeeenn DDrriivveerrss

BRLTTY supports the following screen drivers:

aass AT-SPI

hhdd This driver provides direct access to the Hurd console screen.
It's only selectable, and is the default, on Hurd systems.

llxx This driver provides direct access to the Linux console screen.
It's only selectable, and is the default, on Linux systems.

Name Models
_____________________________________________________________
Albatross 46/80
Alva ABT (3nn)
Delphi (4nn)
Satellite (5nn)
Braille System 40
Braille Controller 640/680
Baum Inka
Vario/RBT
SuperVario/Brailliant
PocketVario
VarioPro
EcoVario
VarioConnect/BrailleConnect
Refreshabraille
BrailleLite 18/40/M20/M40
BrailleNote 18/32
BrlAPI
CombiBraille 25/45/85
EcoBraille 20/40/80
EuroBraille AzerBraille
Clio
Iris
NoteBraille
Scriba
Esys 12/40
FreedomScientific Focus 1 44/70/84
Focus 2 40/80
Focus Blue 40
PAC Mate 20/40
HandyTech Modular 20/40/80
Modular Evolution 64/88
Braille Wave 40
Easy Braille
Braille Star 40/80
Bookworm
Braillino 20
HIMS Braille Sense
SyncBraille
Libbraille
LogText 32
MDV MB208/MB408L/MB408S (protocol 5)
Metec BD-40
MiniBraille 20
MultiBraille MB125CR/MB145CR/MB185CR
Papenmeier Compact 486
Compact/Tiny
IB 80 CR Soft
2D Lite (plus)
2D Screen Soft
EL 80
EL 2D 40/66/80
EL 40/66/70/80 S
EL 2D 80 S
EL 40 P
EL 80 II
Elba 20/32
Trio 40/Elba20/Elba32
Pegasus 20/27/40/80
Seika 40
TSI Navigator 20/40/80
PowerBraille 40/65/80
TTY terminfo
VideoBraille 40
Virtual TCP/Unix, client/server
VisioBraille 20/40
Voyager 44/70
XWindow X11
Windows

Code Name
____________________________________________________
al Alva
at Albatross
ba BrlAPI
bl BrailleLite
bm Baum (Native, HT, PB1, PB2)
bn BrailleNote
cb CombiBraille
ec EcoBraille
es eSpeak
eu EuroBraille
fl FestivalLite
fs FreedomScientific
fv Festival
gs GenericSay
hm HIMS
ht HandyTech
il IrisLinux
lb Libbraille
lt LogText
mb MultiBraille
md MDV
mn MiniBraille
mp Mikropuhe
mt Metec
no no driver
pg Pegasus
pm Papenmeier
sd SpeechDispatcher
sk Seika
sw Swift
th Theta
ts Telesensory Systems Inc.
tt TTY
vd VideoBraille
vo Voyager
vr Virtual
vs VisioBraille
vv ViaVoice
xs ExternalSpeech
xw XWindow

sscc This driver provides access to the screen program. It's
selectable on all systems, and is the default if no native
screen driver is available. The patch for screen which we
provide (see the Patches subdirectory) must be applied. Use of
this driver, due to the fact that screen must be concurrently
running, makes BRLTTY effectively useful only after the user has
logged in.

wwnn This driver provides direct access to the Windows console
screen. It's only selectable, and is the default, on
Windows/Cygwin systems.

EE.. OOppeerraanndd SSyynnttaaxx

EE..11.. DDrriivveerr SSppeecciiffiiccaattiioonnnn

A braille display or speech synthesizer driver must be specified via
its two-letter ``driver identification code''.

A comma-delimited list of drivers may be specified. If this is done
then autodetection is performed using each listed driver in sequence.
You may need to experiment in order to determine the most reliable
order since some drivers autodetect better than others.

If the single word auto is specified then autodetection is performed
using only those drivers which are known to be reliable for this
purpose.

EE..22.. BBrraaiillllee DDeevviiccee SSppeecciiffiiccaattiioonnnn

The general form of a braille device specification (see the ``-d''
command line option, the ``braille-device'' configuration file
directive, and the ``--with-braille-device'' build option) is
qualifier:_d_a_t_a. For backward compatibility with earlier releases, if
the qualifier is omitted then serial: is assumed.

The following device types are supported:

BBlluueettooootthh
For a bluetooth device, specify bluetooth:_a_d_d_r_e_s_s (bt: and
bluez: may also be used). The address must be six two-digit
hexadecimal numbers separated by colons, e.g. 01:23:45:67:89:AB.

SSeerriiaall
For a serial device, specify serial:_/_p_a_t_h_/_t_o_/_d_e_v_i_c_e. The
serial: qualifier is optional (for backward compatibility). If
a relative path is given then it's anchored at /dev (the usual
location where devices are defined on a Unix-like system). The
following device specifications all refer to the first serial
device on Linux:

· serial:/dev/ttyS0

· serial:ttyS0

· /dev/ttyS0

· ttyS0

UUSSBB
For a USB device, specify usb:. BRLTTY will search for the
first USB device which matches the braille display driver being
used. If this is inadequate, e.g. if you have more than one USB
braille display which requires the same driver, then you can
refine the device specification by appending the serial number
of the display to it, e.g. usb:12345. N.B.: The "identification
by serial number" feature doesn't work for some models because
some manufacturers either don't set the USB serial number
descriptor at all or do set it but not to a unique value.

A comma-delimited list of braille devices may be specified. If this
is done then autodetection is performed on each listed device in
sequence. This feature is particularly useful if you have a braille
display with more than one interrface, e.g. both a serial and a USB
port. In this case it's usually better to list the USB port first,
e.g. usb:,serial:/dev/ttyS0, since the former tends to autodetect more
reliably than the latter.

EE..33.. PPCCMM DDeevviiccee SSppeecciiffiiccaattiioonnnn

In most cases the PCM device is the full path to an appropriate system
device. Exceptions are:

AALLSSAA
The name of and arguments for the physical or logical device,
i.e. _n_a_m_e[:_a_r_g_u_m_e_n_t,...].

The default PCM device is:

Platform Device
_______________________________________________________
FreeBSD /dev/dsp
Linux/ALSA hw:0,0
Linux/OSS /dev/dsp
NetBSD /dev/audio
OpenBSD /dev/audio
Qnx preferred PCM output device
Solaris /dev/audio

EE..44.. MMIIDDII DDeevviiccee SSppeecciiffiiccaattiioonnnn

In most cases the MIDI device is the full path to an appropriate
system device. Exceptions are:

AALLSSAA
The client and port separated by a colon, i.e. _c_l_i_e_n_t:_p_o_r_t.
Each may be specified either as a number or as a case-sensitive
substring of its name.

The default MIDI device is:

Platform Device
____________________________________________________________
Linux/ALSA the first available MIDI output port
Linux/OSS /dev/sequencer

FF.. SSttaannddaarrdd BBrraaiillllee DDoott NNuummbbeerriinngg CCoonnvveennttiioonn

A standard braille cell consists of six dots arranged in three rows
and two columns. Each dot can be specifically identified by its
number as follows:

11 Top-left (row 1, column 1).

22 Middle-left (row 2, column 1).

33 Bottom-left (row 3, column 1).

44 Top-right (row 1, column 2).

55 Middle-right (row 2, column 2).

66 Bottom-right (row 3, column 2).

Computer braille has introduced a fourth row at the bottom.

77 Below-left (row 4, column 1).

88 Below-right (row 4, column 2).

Perhaps a picture will make this numbering convention easier to
understand.
1 o o 4
2 o o 5
3 o o 6
7 o o 8

GG.. NNoorrtthh AAmmeerriiccaann BBrraaiillllee CCoommppuutteerr CCooddee

HH.. MMIIDDII IInnssttrruummeenntt TTaabbllee