<!doctype linuxdoc system>
<article>
<titlepag>
<title>BRLTTY Reference Manual
<subtitle>Access to the Console Screen for Blind Persons using Refreshable Braille Displays
<author>
<name>Nikhil Nair <tt><htmlurl url="mailto:nn201@cus.cam.ac.uk" name="<nn201@cus.cam.ac.uk>"></tt>
<and>
<name>Nicolas Pitre <tt><htmlurl url="mailto:nico@fluxnic.net" name="<nico@fluxnic.net>"></tt>
<and>
<name>Stéphane Doyon <tt><htmlurl url="mailto:s.doyon@videotron.ca" name="<s.doyon@videotron.ca>"></tt>
<and>
<name>Dave Mielke <tt><htmlurl url="mailto:dave@mielke.cc" name="<dave@mielke.cc>"></tt>
<date>Version 4.3, Oct 2011
<abstract>
Copyright © 1995-2011 by The BRLTTY Developers.
BRLTTY is free software,
and comes with ABSOLUTELY NO WARRANTY.
It is placed under the terms of version 2 or later of
<bf/The GNU General Public License/
as published by
<bf/The Free Software Foundation/.
</abstract>
</titlepag>
<toc>
<lof>
<lot>
<sect>Formalities<p>
<sect1>License<p>
This program is free software.
You may redistribute it and/or modify it under the terms of
<htmlurl url="http://www.gnu.org/licenses/licenses.html#GPL" name="The GNU General Public License">
as published by <htmlurl url="http://www.gnu.org/fsf/fsf.html" name="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 <tt/LICENSE-GPL/ in the top-level directory.
If not, write to the Free Software Foundation Inc.,
675 Mass Ave, Cambridge, MA 02139, USA.
<sect1>Disclaimer<p>
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 <bf/GNU General Public License/ for more details.
<sect1>Contact Information<label id="contact"><p>
BRLTTY represents the work of a team.
For up-to-date information, see BRLTTY's web page at
[<htmlurl url="http://mielke.cc/brltty/" name="http://mielke.cc/brltty/">].
As of this writing, the team includes:
<itemize>
<item>
Dave Mielke (maintainer, active)
<descrip>
<tag/Web/<htmlurl url="http://mielke.cc/" name="http://mielke.cc/">
<tag/E-Mail/<htmlurl url="mailto:dave@mielke.cc" name="<dave@mielke.cc>">
</descrip>
<item>
Samuel Thibault (active)
<descrip>
<tag/Web/<htmlurl url="http://dept-info.labri.fr/~thibault/" name="http://dept-info.labri.fr/~thibault/">
<tag/E-Mail/<htmlurl url="mailto:samuel.thibault@ens-lyon.org" name="<samuel.thibault@ens-lyon.org>">
</descrip>
<item>
Mario Lang (active)
<descrip>
<tag/Web/<htmlurl url="http://delysid.org/" name="http://delysid.org/">
<tag/E-Mail/<htmlurl url="mailto:mlang@delysid.org" name="<mlang@delysid.org>">
</descrip>
<item>
Nicolas Pitre
<descrip>
<tag/Web/<htmlurl url="http://www.cam.org/~nico/" name="http://www.cam.org/~nico/">
<tag/E-Mail/<htmlurl url="mailto:nico@fluxnic.net" name="<nico@fluxnic.net>">
</descrip>
<item>
Stéphane Doyon
<descrip>
<tag/Web/<htmlurl url="http://pages.infinit.net/sdoyon/" name="http://pages.infinit.net/sdoyon/">
<tag/E-Mail/<htmlurl url="mailto:s.doyon@videotron.ca" name="<s.doyon@videotron.ca>">
</descrip>
<item>
Nikhil Nair (author)
<descrip>
<tag/E-Mail/<htmlurl url="mailto:nn201@cus.cam.ac.uk" name="<nn201@cus.cam.ac.uk>">
</descrip>
</itemize>
Questions, comments, suggestions, criticisms, and contributions are all welcome.
Even though our e-mail addresses are listed above,
the best way to contact us is via BRLTTY's mailing list.
You can post to the list by sending e-mail to
<htmlurl url="mailto:BRLTTY@mielke.cc" name="<BRLTTY@mielke.cc>">.
If you aren't subscribed to the list
then your posts will be held for moderator approval.
To subscribe, unsubscribe, change settings, view archives, etc,
go to the list's information page at
<htmlurl url="http://mielke.cc/mailman/listinfo/brltty" name="http://mielke.cc/mailman/listinfo/brltty">.
<sect>Introduction<p>
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.
<sect1>Feature Summary<p>
BRLTTY provides the following capabilities:
<itemize>
<item>
Full implementation of the usual screen review facilities.
<item>
Choice between <tt/block/, <tt/underline/, or <tt/no/ cursor.
<item>
Optional <tt/underline/ to indicate specially highlighted text.
<item>
Optional use of <tt/blinking/ (rates individually settable) for
cursor, special highlighting underline, and/or capital letters.
<item>
Screen freezing for leisurely review.
<item>
Intelligent cursor routing, allowing easy fetching of cursor within
text editors, web browsers, etc.,
without moving ones hands from the braille display.
<item>
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.
<item>
Table driven in-line contracted braille (English and French provided).
<item>
Support for multiple braille codes.
<item>
Ability to identify an unknown character.
<item>
Ability to inspect character highlighting.
<item>
An on-line help facility for braille display commands.
<item>
A preferences menu.
<item>
Basic speech support.
<item>
Modular design allowing relatively easy addition of
drivers for other braille displays and speech synthesizers.
<item>
An Application Programming Interface.
</itemize>
<sect1>System Requirements<p>
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.
<descrip>
<tag/Linux/
This software has been tested on a variety of Linux systems:
<itemize>
<item>
Desktops, laptops, and some PDAs.
<item>
Processors from a 386SX20 to a Pentium.
<item>
A huge range of memory sizes.
<item>
Several distributions including Debian, Red Hat, Slackware, and SuSE.
<item>
Many kernels, including 1.2.13, 2.0, 2.2, and 2.4.
</itemize>
<tag/Solaris/
This software has been tested on the following Solaris systems:
<itemize>
<item>
The Sparc architecture (releases 7, 8, and 9).
<item>
The Intel architecture (release 9).
</itemize>
<tag/OpenBSD/
This software has been tested on the following OpenBSD systems:
<itemize>
<item>
The Intel architecture (release 3.4).
</itemize>
<tag/FreeBSD/
This software has been tested on the following FreeBSD systems:
<itemize>
<item>
The Intel architecture (release 5.1).
</itemize>
<tag/NetBSD/
This software has been tested on the following NetBSD systems:
<itemize>
<item>
The Intel architecture (release 1.6).
</itemize>
<tag/Windows/
This software has been tested on Windows 95, 98, and XP.
</descrip>
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 <tt>/dev/vcsa</> or <tt>/dev/vcsa0</>
(on systems with <tt/devfs/ it's called <tt>/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:
<itemize>
<item>
Allows BRLTTY to be started very early in the system boot sequence.
<item>
Enables the braille display to be fully operational during the login prompt.
<item>
Makes it much easier for a braille user to perform boot-time system administration tasks.
</itemize>
A patch for the <tt/screen/ program is provide
(see the <tt/Patches/ subdirectory).
It allows BRLTTY to access <tt/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 <tt/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 <tt/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 <ref id="displays" name="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 <ref id="contact" name="Contact Information">).
Finally, you need tools to build the executable from its source:
<tt/make/, <tt/C/ and <tt/C++/ compilers, <tt/yacc/, <tt/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.
<sect>The Build Procedure<p>
BRLTTY can be downloaded from its web site
(see section <ref id="contact" name="Contact Information"> for its location).
All releases are provided as compressed <ref id="tar" name="tar balls">.
Newer releases are also provided as <ref id="rpm" name="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.
<sect1>Installed File Hierarchy<label id="hierarchy"><p>
The build procedure should result in the installation of the following files:
<descrip>
<tag>/bin/</>
<descrip>
<tag>brltty</tag>
The BRLTTY program.
<tag><ref id="utility-brltty-install" name="brltty-install"></tag>
A utility for copying BRLTTY's
<ref id="hierarchy" name="installed file hierarchy">
from one location to another.
<tag><ref id="utility-brltty-config" name="brltty-config"></tag>
A utility which sets a number of environment variables to values
which reflect the current installation of BRLTTY.
</descrip>
<tag>/lib/</>
<descrip>
<tag/libbrlapi.a/
Static archive of the Application Programming Interface.
<tag/libbrlapi.so/
Dynamically loadable object for the Application Programming Interface.
</descrip>
<tag>/lib/brltty/</>
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 <ref id="build" name="Build Options">).
<descrip>
<tag/brltty-brl.lst/
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.
<tag>libbrlttyb<em/driver/.so.1</tag>
The dynamically loadable driver for a braille display,
where <em/driver/ is the two-letter <ref id="drivers" name="driver identification code">.
<tag/brltty-spk.lst/
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.
<tag>libbrlttys<em/driver/.so.1</tag>
The dynamically loadable driver for a speech synthesizer,
where <em/driver/ is the two-letter <ref id="drivers" name="driver identification code">.
</descrip>
<tag>/lib/brltty/rw/</>
Files created at run-time, e.g. needed but missing system resources.
<tag>/etc/</>
<descrip>
<tag/brltty.conf/
System defaults for BRLTTY.
<tag/brlapi.key/
The access key for BrlAPI.
</descrip>
<tag>/etc/brltty/</>
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 <ref id="build" name="Build Options">).
<descrip>
<tag/*.conf/
Driver-specific configuration data.
Their names look more or less like <tt/brltty-/<em/driver/<tt/.conf/,
where <em/driver/ is the two-letter <ref id="drivers" name="driver identification code">.
<tag/*.atb/
Attributes tables
(see section <ref id="table-attributes" name="Attributes Tables"> for details).
Their names look like <em/name/<tt/.atb/.
<tag/*.ati/
Include files for attributes tables.
<tag/*.ctb/
Contraction tables
(see section <ref id="table-contraction" name="Contraction Tables"> for details).
Their names look like <em/language/<tt/-/<em/country/<tt/-/<em/level/<tt/.ctb/.
<tag/*.cti/
Include files for contraction tables.
<tag/*.ktb/
Key tables
(see section <ref id="table-key" name="Key Tables"> for details).
Their names look like <em/name/<tt/.ktb/.
<tag/*.kti/
Include files for key tables.
<tag/*.ttb/
Text tables
(see section <ref id="table-text" name="Text Tables"> for details).
Their names look like <em/language/<tt/.ttb/.
<tag/*.tti/
Include files for text tables.
<tag/*.hlp/
Driver-specific help pages.
Their names look more or less like <tt/brltty-/<em/driver/<tt/.hlp/,
where <em/driver/ is the two-letter <ref id="drivers" name="driver identification code">.
</descrip>
<tag>/var/lib/BrlAPI/</>
Local sockets for connecting to the Application Programming Interface.
<tag>/include/</>
C header files for the Application Programming Interface.
Their names look like <tt/brlapi-/<em/function/<tt/.h/.
The main header is <tt/brlapi.h/.
<tag>/include/brltty/</>
C header files for accessing braille hardware.
Their names look like <tt/brldefs-/<em/driver/<tt/.h/
(where <em/driver/ is the two-letter <ref id="drivers" name="driver identification code">).
The headers <tt/brldefs.h/ and <tt/api.h/ are provided
for backward compatibility and shouldn't be used.
<tag>/man/</>
Man pages.
<descrip>
<tag>man1/<em/name/.1</tag>
Man pages for BRLTTY-related user commands.
<tag>man3/<em/name/.3</tag>
Man pages for Application Programming Interface library routines.
</descrip>
</descrip>
Some optional files which you should be aware of,
although they aren't part of the installed file hierarchy, are:
<descrip>
<tag>/etc/brltty.conf</tag>
The system defaults configuration file.
It's created by the system administrator.
See <ref id="configure" name="The Configuration File"> for details.
<tag>/etc/brltty-<em/driver/.prefs</tag>
The saved preferences settings file
(<em/driver/ is a two-letter <ref id="drivers" name="driver identification code">).
It's created by the <ref id="command-PREFSAVE" name="PREFSAVE"> command.
See <ref id="preferences" name="Preferences Settings"> for details.
</descrip>
<sect1>Installing from a TAR Ball<label id="tar"><p>
Here's what to do if you just want to install BRLTTY as quickly as possible,
trusting that all of our defaults are correct.
<enum>
<item>
Download the source.
It'll be a file named
<tt/brltty-/<em/release/<tt/.tar.gz/,
e.g. <tt/brltty-3.0.tar.gz/.
<item>
Unpack the source into its native hierarchical structure.
<tscreen>tar xzf brltty-<em/release/.tar.gz</tscreen>
This should create the directory <tt/brltty-/<em/release/.
<item>
Change to the source directory, configure, compile, and install BRLTTY.
<tscreen>
cd brltty-<em/release/
<newline>
./configure
<newline>
make install
</tscreen>
This should be done as <bf/root/.
</enum>
To uninstall BRLTTY, do:
<tscreen>
cd brltty-<em/release/
<newline>
make uninstall
</tscreen>
That's all there's to it.
Now, for those who really want to know what's going on, here are the details.
<sect2>Build Options<label id="build"><p>
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 <tt/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.
<tscreen>./configure</tscreen>
If, however, you have some special requirements,
or even if you're just adventurous,
you should find out what your choices are.
<tscreen>./configure --help</tscreen>
You should also check out the <tt/README/ file in the subdirectory
containing the driver for your braille display
for any additional display-specific instructions.
<sect3>System Defaults<label id="build-defaults"><p>
<descrip>
<tag><tt/--with-braille-driver=/<em/driver/<label id="build-braille-driver"></tag>
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 <ref id="drivers" name="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 (<tt/-/),
then that driver is excluded from the build.
Any of the following words can also be used as the operand of this option:
<descrip>
<tag/all/
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.
<tag/-all/
Only build those drivers which have been explicitly included via this option.
<tag/no/
Don't build any drivers at all.
This is equivalent to specifying <tt/--without-braille-driver/.
<tag/yes/
Build all of the drivers as dynamically loadable shared objects.
Don't link any of them into the binary.
This is equivalent to specifying <tt/--with-braille-driver/.
</descrip>
See the <ref id="configure-braille-driver" name="braille-driver"> configuration file directive
and the <ref id="options-braille-driver" name="-b"> command line option
for run-time selection.
<tag><tt/--with-braille-parameters=/[<em/driver/<tt/:/]<em/name/<tt/=/<em/value/<tt/,/...<label id="build-braille-parameters"></tag>
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 <ref id="drivers" name="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 <ref id="configure-braille-parameters" name="braille-parameters"> configuration file directive
and the <ref id="options-braille-parameters" name="-B"> command line option
for run-time selection.
<tag><tt/--with-braille-device=/<em/device/<tt/,/...<label id="build-braille-device"></tag>
Specify the default device to which the braille display is connected
(see section <ref id="operand-braille-device" name="Braille Device Specification">).
If this option isn't specified,
then <tt/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 <ref id="configure-braille-device" name="braille-device"> configuration file directive
and the <ref id="options-braille-device" name="-d"> command line option
for run-time selection.
<tag><tt/--with-libbraille=/<em/directory/<label id="build-libbraille"></tag>
Specify the installed location of the Libbraille package,
and build the Libbraille braille display driver
(see <ref id="restrictions-libbraille" name="Build Restrictions">).
Any of the following words can also be used as the operand of this option:
<descrip>
<tag/no/
Don't build the driver.
This is equivalent to specifying <tt/--without-libbraille/.
<tag/yes/
Build the driver if the package can be found in
<tt>/usr</>,
<tt>/usr/local</>,
<tt>/usr/local/Libbraille</>,
<tt>/usr/local/libbraille</>,
<tt>/opt/Libbraille</>,
or <tt>/opt/libbraille</>.
This is equivalent to specifying <tt/--with-libbraille/.
</descrip>
<tag><tt/--with-text-table=/<em/file/<label id="build-text-table"></tag>
Specify the built-in (fallback) text table
(see section <ref id="table-text" name="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 <tt/.ttb/ extension is optional.
If this option isn't specified,
then <tt/en-nabcc/,
a commonly (in North America) used 8-dot variant of the
<ref id="nabcc" name="North American Braille Computer Code">,
is assumed.
See the <ref id="configure-text-table" name="text-table"> configuration file directive
and the <ref id="options-text-table" name="-t"> command line option
for run-time selection.
This setting can be changed with the
<ref id="preference-text-table" name="Text Table"> preference.
<tag><tt/--with-attributes-table=/<em/file/<label id="build-attributes-table"></tag>
Specify the built-in (fallback) attributes table
(see section <ref id="table-attributes" name="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 <tt/.atb/ extension is optional.
If this option isn't specified,
then <tt/attributes/ is assumed.
Change it to <tt/attrib/ if you'd like it done the old way.
See the <ref id="configure-attributes-table" name="attributes-table"> configuration file directive
and the <ref id="options-attributes-table" name="-a"> command line option
for run-time selection.
This setting can be changed with the
<ref id="preference-attributes-table" name="Attributes Table"> preference.
<tag><tt/--with-speech-driver=/<em/driver/<label id="build-speech-driver"></tag>
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 <ref id="drivers" name="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 (<tt/-/),
then that driver is excluded from the build.
Any of the following words can also be used as the operand of this option:
<descrip>
<tag/all/
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.
<tag/-all/
Only build those drivers which have been explicitly included via this option.
<tag/no/
Don't build any drivers at all.
This is equivalent to specifying <tt/--without-speech-driver/.
<tag/yes/
Build all of the drivers as dynamically loadable shared objects.
Don't link any of them into the binary.
This is equivalent to specifying <tt/--with-speech-driver/.
</descrip>
See the <ref id="configure-speech-driver" name="speech-driver"> configuration file directive
and the <ref id="options-speech-driver" name="-s"> command line option
for run-time selection.
<tag><tt/--with-speech-parameters=/[<em/driver/<tt/:/]<em/name/<tt/=/<em/value/<tt/,/...<label id="build-speech-parameters"></tag>
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 <ref id="drivers" name="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 <ref id="configure-speech-parameters" name="speech-parameters"> configuration file directive
and the <ref id="options-speech-parameters" name="-S"> command line option
for run-time selection.
<tag><tt/--with-flite=/<em/directory/<label id="build-flite"></tag>
Specify the installed location of the FestivalLite text-to-speech package,
and build the FestivalLite speech synthesizer driver
(see <ref id="restrictions-flite" name="Build Restrictions">).
Any of the following words can also be used as the operand of this option:
<descrip>
<tag/no/
Don't build the driver.
This is equivalent to specifying <tt/--without-flite/.
<tag/yes/
Build the driver if the package can be found in
<tt>/usr</>,
<tt>/usr/local</>,
<tt>/usr/local/FestivalLite</>,
<tt>/usr/local/flite</>,
<tt>/opt/FestivalLite</>,
or <tt>/opt/flite</>.
This is equivalent to specifying <tt/--with-flite/.
</descrip>
<tag><tt/--with-flite-language=/<em/language/<label id="build-flite-language"></tag>
Specify the language which the FestivalLite text to speech engine is to use.
The default language is <tt/usenglish/.
<tag><tt/--with-flite-lexicon=/<em/lexicon/<label id="build-flite-lexicon"></tag>
Specify the lexicon which the FestivalLite text to speech engine is to use.
The default lexicon is <tt/cmulex/.
<tag><tt/--with-flite-voice=/<em/voice/<label id="build-flite-voice"></tag>
Specify the voice which the FestivalLite text to speech engine is to use.
The default voice is <tt/cmu_us_kal16/.
<tag><tt/--with-mikropuhe=/<em/directory/<label id="build-mikropuhe"></tag>
Specify the installed location of the Mikropuhe text-to-speech package,
and build the Mikropuhe speech synthesizer driver
(see <ref id="restrictions-mikropuhe" name="Build Restrictions">).
Any of the following words can also be used as the operand of this option:
<descrip>
<tag/no/
Don't build the driver.
This is equivalent to specifying <tt/--without-mikropuhe/.
<tag/yes/
Build the driver if the package can be found in
<tt>/usr</>,
<tt>/usr/local</>,
<tt>/usr/local/Mikropuhe</>,
<tt>/usr/local/mikropuhe</>,
<tt>/opt/Mikropuhe</>,
or <tt>/opt/mikropuhe</>.
This is equivalent to specifying <tt/--with-mikropuhe/.
</descrip>
<tag><tt/--with-speechd=/<em/directory/<label id="build-speechd"></tag>
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:
<descrip>
<tag/no/
Don't build the driver.
This is equivalent to specifying <tt/--without-speechd/.
<tag/yes/
Build the driver if the package can be found in
<tt>/usr</>,
<tt>/usr/local</>,
<tt>/usr/local/speech-dispatcher</>,
<tt>/usr/local/speechd</>,
<tt>/opt/speech-dispatcher</>,
or <tt>/opt/speechd</>.
This is equivalent to specifying <tt/--with-speechd/.
</descrip>
<tag><tt/--with-swift=/<em/directory/<label id="build-swift"></tag>
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:
<descrip>
<tag/no/
Don't build the driver.
This is equivalent to specifying <tt/--without-swift/.
<tag/yes/
Build the driver if the package can be found in
<tt>/usr</>,
<tt>/usr/local</>,
<tt>/usr/local/Swift</>,
<tt>/usr/local/swift</>,
<tt>/opt/Swift</>,
or <tt>/opt/swift</>.
This is equivalent to specifying <tt/--with-swift/.
</descrip>
<tag><tt/--with-theta=/<em/directory/<label id="build-theta"></tag>
Specify the installed location of the Theta text-to-speech package,
and build the Theta speech synthesizer driver
(see <ref id="restrictions-theta" name="Build Restrictions">).
Any of the following words can also be used as the operand of this option:
<descrip>
<tag/no/
Don't build the driver.
This is equivalent to specifying <tt/--without-theta/.
<tag/yes/
Build the driver if the package can be found in
<tt>/usr</>,
<tt>/usr/local</>,
<tt>/usr/local/Theta</>,
<tt>/usr/local/theta</>,
<tt>/opt/Theta</>,
or <tt>/opt/theta</>.
This is equivalent to specifying <tt/--with-theta/.
</descrip>
<tag><tt/--with-viavoice=/<em/directory/<label id="build-viavoice"></tag>
Specify the installed location of the ViaVoice text-to-speech package,
and build the ViaVoice speech synthesizer driver
(see <ref id="restrictions-viavoice" name="Build Restrictions">).
Any of the following words can also be used as the operand of this option:
<descrip>
<tag/no/
Don't build the driver.
This is equivalent to specifying <tt/--without-viavoice/.
<tag/yes/
Build the driver if the package can be found in
<tt>/usr</>,
<tt>/usr/local</>,
<tt>/usr/local/ViaVoice</>,
<tt>/usr/local/viavoice</>,
<tt>/opt/ViaVoice</>,
or <tt>/opt/viavoice</>.
This is equivalent to specifying <tt/--with-viavoice/.
</descrip>
<tag><tt/--with-screen-driver=/<em/driver/<label id="build-screen-driver"></tag>
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 <ref id="screen" name="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 (<tt/-/),
then that driver is excluded from the build.
Any of the following words can also be used as the operand of this option:
<descrip>
<tag/all/
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.
<tag/-all/
Only build those drivers which have been explicitly included via this option.
<tag/no/
Don't build any drivers at all.
This is equivalent to specifying <tt/--without-screen-driver/.
<tag/yes/
Build all of the drivers as dynamically loadable shared objects.
Don't link any of them into the binary.
This is equivalent to specifying <tt/--with-screen-driver/.
</descrip>
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 <tt/sc/ is selected.
See the <ref id="configure-screen-driver" name="screen-driver"> configuration file directive
and the <ref id="options-screen-driver" name="-x"> command line option
for run-time selection.
<tag><tt/--with-screen-parameters=/[<em/driver/<tt/:/]<em/name/<tt/=/<em/value/<tt/,/...<label id="build-screen-parameters"></tag>
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 <ref id="screen" name="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 <ref id="configure-screen-parameters" name="screen-parameters"> configuration file directive
and the <ref id="options-screen-parameters" name="-X"> command line option
for run-time selection.
<tag><tt/--with-usb-package=/<em/package/<tt/,/...<label id="build-usb-package"></tag>
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:
<enum>
<item>libusb
<item>libusb-1.0
</enum>
Any of the following words can also be used as the operand of this option:
<descrip>
<tag/no/
Don't support USB I/O.
This is equivalent to specifying <tt/--without-usb-package/.
<tag/yes/
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 <tt/--with-usb-package/.
</descrip>
<tag><tt/--with-bluetooth-package=/<em/package/<tt/,/...<label id="build-bluetooth-package"></tag>
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:
<enum>
<item>(no packages are currently supported)
</enum>
Any of the following words can also be used as the operand of this option:
<descrip>
<tag/no/
Don't support Bluetooth I/O.
This is equivalent to specifying <tt/--without-bluetooth-package/.
<tag/yes/
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 <tt/--with-bluetooth-package/.
</descrip>
</descrip>
<sect3>Directory Specification<label id="build-directoreis"><p>
<descrip>
<tag><tt/--with-execute-root=/<em/directory/<label id="build-execute-root"></tag>
Specify the directory at which the
<ref id="hierarchy" name="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 <ref id="multiple" name="Installing Multiple Versions">
for an example of how to do this).
<tag><tt/--with-install-root=/<em/directory/<label id="build-install-root"></tag>
Specify the directory beneath which the
<ref id="hierarchy" name="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 <ref id="build-execute-root" name="--with-execute-root"> build option)
is assumed.
This directory is only used by
<ref id="make-install" name="make install">
and <ref id="make-uninstall" name="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.
<tag><tt/--prefix=/<em/directory/<label id="build-portable-root"></tag>
Specify the directory within the
<ref id="hierarchy" name="installed file hierarchy">
where the default directories for the architecture-independent files
are to be rooted.
These directories include:
<itemize>
<item>the <ref id="build-writable-directory" name="writable directory">
<item>the <ref id="build-data-directory" name="data directory">
<item>the <ref id="build-configuration-directory" name="configuration directory">
<item>the <ref id="build-manpage-directory" name="manpage directory">
<item>the <ref id="build-include-directory" name="include directory">
</itemize>
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
<ref id="build-execute-root" name="--with-execute-root"> build option.
<tag><tt/--exec-prefix=/<em/directory/<label id="build-architecture-root"></tag>
Specify the directory within the
<ref id="hierarchy" name="installed file hierarchy">
where the default directories for the architecture-dependent files
are to be rooted.
These directories include:
<itemize>
<item>the <ref id="build-program-directory" name="program directory">
<item>the <ref id="build-library-directory" name="library directory">
<item>the <ref id="build-api-directory" name="API directory">
</itemize>
The absolute path should be supplied.
If this option isn't specified,
then the directory specified via the
<ref id="build-portable-root" name="--prefix">
build option is assumed.
This directory is rooted at the directory specified by the
<ref id="build-execute-root" name="--with-execute-root"> build option.
<tag><tt/--libdir=/<em/directory/<label id="build-api-directory"></tag>
Specify the directory within the
<ref id="hierarchy" name="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 <tt/--libdir/
(which defaults to <tt>/lib</> rooted at the directory specified by the
<ref id="build-architecture-root" name="--exec-prefix"> build option)
is assumed.
The directory is created if it doesn't exist.
<tag><tt/--sysconfdir=/<em/directory/<label id="build-configuration-directory"></tag>
Specify the directory within the
<ref id="hierarchy" name="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 <tt/--sysconfdir/
(which defaults to <tt>/etc</> rooted at the directory specified by the
<ref id="build-portable-root" name="--prefix"> build option)
is assumed.
The directory is created if it doesn't exist.
<tag><tt/--with-program-directory=/<em/directory/<label id="build-program-directory"></tag>
Specify the directory within the
<ref id="hierarchy" name="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 <tt/--bindir/
(which defaults to <tt>/bin</> rooted at the directory specified by the
<ref id="build-architecture-root" name="--exec-prefix"> build option)
is assumed.
The directory is created if it doesn't exist.
<tag><tt/--with-library-directory=/<em/directory/<label id="build-library-directory"></tag>
Specify the directory within the
<ref id="hierarchy" name="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 <tt/brltty/ subdirectory of the directory
specified via the standard configure option <tt/--libdir/
(which defaults to <tt>/lib</> rooted at the directory specified by the
<ref id="build-architecture-root" name="--exec-prefix"> build option)
is assumed.
The directory is created if it doesn't exist.
<tag><tt/--with-writable-directory=/<em/directory/<label id="build-writable-directory"></tag>
Specify the directory within the
<ref id="hierarchy" name="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:
<descrip>
<tag/no/
Don't define a writable directory.
This is equivalent to specifying <tt/--without-writable-directory/.
<tag/yes/
Use the default location.
This is equivalent to specifying <tt/--with-writable-directory/.
</descrip>
If this option isn't specified,
then the <tt>rw</> subdirectory of the directory specified via the
<ref id="build-library-directory" name="--with-library-directory"> build option
is assumed.
The directory is created if it doesn't exist.
<tag><tt/--with-data-directory=/<em/directory/<label id="build-data-directory"></tag>
Specify the directory within the
<ref id="hierarchy" name="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 <tt/brltty/ subdirectory of the directory
specified via the standard configure option <tt/--sysconfdir/
(which defaults to <tt>/etc</> rooted at the directory specified by the
<ref id="build-portable-root" name="--prefix"> build option)
is assumed.
The directory is created if it doesn't exist.
<tag><tt/--with-manpage-directory=/<em/directory/<label id="build-manpage-directory"></tag>
Specify the directory within the
<ref id="hierarchy" name="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 <tt/--mandir/
(which defaults to <tt>/man</> rooted at the directory specified by the
<ref id="build-portable-root" name="--prefix"> build option)
is assumed.
The directory is created if it doesn't exist.
<tag><tt/--with-include-directory=/<em/directory/<label id="build-include-directory"></tag>
Specify the directory within the
<ref id="hierarchy" name="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 <tt/brltty/ subdirectory of the directory
specified via the standard configure option <tt/--includedir/
(which defaults to <tt>/include</> rooted at the directory specified by the
<ref id="build-portable-root" name="--prefix"> build option)
is assumed.
The directory is created if it doesn't exist.
</descrip>
<sect3>Build Features<label id="build-features"><p>
These options are primarily useful when building BRLTTY for use on a boot disk.
<descrip>
<tag><tt/--enable-standalone-programs/<label id="build-standalone-programs"></tag>
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
<ref id="build-braille-driver" name="--with-braille-driver">,
<ref id="build-speech-driver" name="--with-speech-driver">,
and <ref id="build-screen-driver" name="--with-screen-driver">
build options) are compiled.
<tag><tt/--enable-relocatable-install/<label id="build-relocatable-install"></tag>
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.
<tag><tt/--disable-strippingl/<label id="build-strippingl"></tag>
Don't remove the symbol tables from executables and shared objects when installing them.
<tag><tt/--disable-learn-mode/<label id="build-learn-mode"></tag>
Reduce program size by excluding command learn mode
(see section <ref id="learn" name="Command Learn Mode">).
<tag><tt/--disable-contracted-braille/<label id="build-contracted-braille"></tag>
Reduce program size by excluding support for contracted braille
(see section <ref id="table-contraction" name="Contraction Tables">).
<tag><tt/--disable-speech-support/<label id="build-speech-support"></tag>
Reduce program size by excluding support for speech synthesizers.
<tag><tt/--disable-iconv/<label id="build-iconv"></tag>
Reduce program size by excluding support for
character set conversion.
<tag><tt/--disable-icu/<label id="build-icu"></tag>
Reduce program size by excluding support for
Unicode-based internationalization.
<tag><tt/--disable-x/<label id="build-x"></tag>
Reduce program size by excluding support for
X11.
<tag><tt/--disable-beeper-support/<label id="build-beeper-support"></tag>
Reduce program size by excluding support for
the console tone generator.
<tag><tt/--disable-pcm-support/<label id="build-pcm-support"></tag>
Reduce program size by excluding support for
the digital audio interface on the sound card.
<tag><tt/--enable-pcm-support=/<em/interface/</tag>
If a platform provides more than one digital audio interface
then the one which is to be used may be specified.
<table loc="h">
<tabular ca="lll">
Platform|Interface|Description@<hline>
Linux
|oss|Open Sound System@
|alsa|Advanced Linux Sound Architecture@
</tabular>
</table>
<tag><tt/--disable-midi-support/<label id="build-midi-support"></tag>
Reduce program size by excluding support for
the Musical Instrument Digital Interface of the sound card.
<tag><tt/--enable-midi-support=/<em/interface/</tag>
If a platform provides more than one Musical Instrument Digital Interface
then the one which is to be used may be specified.
<table loc="h">
<tabular ca="lll">
Platform|Interface|Description@<hline>
Linux
|oss|Open Sound System@
|alsa|Advanced Linux Sound Architecture@
</tabular>
</table>
<tag><tt/--disable-fm-support/<label id="build-fm-support"></tag>
Reduce program size by excluding support for
the FM synthesizer on an AdLib, OPL3, Sound Blaster, or equivalent sound card.
<tag><tt/--disable-pm-configfile/<label id="build-pm-configfile"></tag>
Reduce program size by excluding support for
the Papenmeier driver's configuration file.
<tag><tt/--disable-gpm/<label id="build-gpm"></tag>
Reduce program size by excluding
the interface to the <tt/gpm/ application
which allows BRLTTY to interact with the pointer (mouse) device
(see section <ref id="gpm" name="Pointer (Mouse) Support via GPM">).
<tag><tt/--disable-api/<label id="build-api"></tag>
Reduce program size by excluding
the Application Programming Interface.
<tag><tt/--with-api-parameters=/<em/name/<tt/=/<em/value/<tt/,/...<label id="build-api-parameters"></tag>
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 <bf/BrlAPI/ reference manual.
See the <ref id="configure-api-parameters" name="api-parameters"> configuration file directive
and the <ref id="options-api-parameters" name="-A"> command line option
for run-time selection.
<tag><tt/--disable-caml-bindings/<label id="build-caml-bindings"></tag>
Don't build the Caml bindings for the Application Programming Interface.
<tag><tt/--disable-java-bindings/<label id="build-java-bindings"></tag>
Don't build the Java bindings for the Application Programming Interface.
<tag><tt/--disable-lisp-bindings/<label id="build-lisp-bindings"></tag>
Don't build the Lisp bindings for the Application Programming Interface.
<tag><tt/--disable-python-bindings/<label id="build-python-bindings"></tag>
Don't build the Python bindings for the Application Programming Interface.
<tag><tt/--disable-tcl-bindings/<label id="build-tcl-bindings"></tag>
Don't build the Tcl bindings for the Application Programming Interface.
<tag><tt/--with-tcl-config=/<em/path/<label id="build-tcl-config"></tag>
Specify the location of the Tcl configuration script (<tt/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:
<descrip>
<tag/no/
Use other means to guess if Tcl is available, and, if so, where it has been installed.
This is equivalent to specifying <tt/--without-tcl-config/.
<tag/yes/
Search for the script in a few commonly used directories.
This is equivalent to specifying <tt/--with-tcl-config/.
</descrip>
</descrip>
<sect3>Miscellaneous Options<label id="build-miscellaneous"><p>
<descrip>
<tag><tt/--with-compiler-prefix=/<em/prefix/<label id="build-compiler-prefix"></tag>
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.
<tag><tt/--with-init-path=/<em/path/<label id="build-init-path"></tag>
Specify the path to the real <tt/init/ program for the system.
The absolute path should be supplied.
If this option is specified, then:
<enum>
<item>
The <tt/init/ program should be moved to a new location.
<item>
<tt/brltty/ should be moved to the <tt/init/ program's original location.
<item>
When the system runs <tt/init/ at startup,
<tt/brltty/ is actually run.
It puts itself into the background,
and runs the real <tt/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.
</enum>
If this option isn't specified, then this feature isn't activated.
This option is primarily intended for building a braillified installer image.
<tag><tt/--with-stderr-path=/<em/path/<label id="build-stderr-path"></tag>
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.
</descrip>
<sect2>Make File Targets<label id="make"><p>
Once BRLTTY has been configured,
the next steps are to compile and to install it.
These are done by applying the system's <tt/make/ command
to BRLTTY's main make file (<tt/Makefile/ in the top-level directory).
BRLTTY's make file supports most of the common application maintenance targets.
They include:
<descrip>
<tag/make/
A shortcut for <tt/make all/.
<tag>make all<label id="make-all"></tag>
Compile and link the BRLTTY executable, its drivers and their help pages,
its test programs, and a few other small utilities.
<tag>make install<label id="make-install"></tag>
Complete the compile and link phase
(see <ref id="make-all" name="make all">),
and then install the BRLTTY executable, its data files, drivers, and help pages,
in the correct places and with the correct permissions.
<tag>make uninstall<label id="make-uninstall"></tag>
Remove the BRLTTY executable, its data files, drivers, and help pages,
from the system.
<tag>make clean<label id="make-clean"></tag>
Ensure that the next compile and link
(see <ref id="make-all" name="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.
<tag>make distclean<label id="make-distclean"></tag>
In addition to removing the results of compiling and linking
(see <ref id="make-clean" name="make clean">):
<itemize>
<item>
Remove the results of BRLTTY configuration
(see <ref id="build" name="Build Options">).
This includes the removal of
<tt/config.mk/, <tt/config.h/,
<tt/config.cache/, <tt/config.status/, and <tt/config.log/.
<item>
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.
</itemize>
</descrip>
<sect1>Testing BRLTTY<p>
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:
<tscreen>brltty -b<em/driver/ -d<em/device/</tscreen>
For <em/driver/, specify the two-letter
<ref id="drivers" name="driver identification code">
corresponding to your braille display.
For <em/device/, 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 <ref id="configure-braille-driver" name="braille-driver">
and the <ref id="configure-braille-device" name="braille-device">
configuration file directives,
and/or compile your needs right into BRLTTY
via the <ref id="build-braille-driver" name="--with-braille-driver">
and the <ref id="build-braille-device" name="--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 <ref id="options-message-delay" name="-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 <ref id="utility-scrtest" name="scrtest">,
and the braille display driver can be tested with <ref id="utility-brltest" name="brltest">.
If you experience a problem which requires a lot of digging,
then you may wish to use the following <tt/brltty/ command line options:
<itemize>
<item>
<ref id="options-log-level" name="-ldebug">
to log lots of diagnostic messages.
<item>
<ref id="options-no-daemon" name="-n">
to keep BRLTTY in the foreground.
<item>
<ref id="options-standard-error" name="-e">
to direct diagnostic messages to standard error
rather than to the system log.
</itemize>
<sect1>Starting BRLTTY<p>
BRLTTY, when properly installed, is invoked with the single command <tt/brltty/.
A configuration file
(see section <ref id="configure" name="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 <ref id="options" name="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 <ref id="options-help" name="-h"> option
displays a summary of all the options.
The <ref id="options-version" name="-V"> option
displays the current version of the program, the API, and the selected drivers.
The <ref id="options-verify" name="-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:
<descrip>
<tag/Red Hat/
<tt>/etc/rc.d/rc.local</>
</descrip>
Starting BRLTTY from this script is a good approach (especially for new users).
Just add a set of lines like these:
<tscreen><verb>
if [ -x /bin/brltty -a -f /etc/brltty.conf ]
then
/bin/brltty
fi
</verb></tscreen>
This can usually be abbreviated to the somewhat less readable form:
<tscreen><verb>
[ -x /bin/brltty -a -f /etc/brltty.conf ] && /bin/brltty
</verb></tscreen>
Don't add these lines before the first line
(which usually looks like <tt>#!/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:
<descrip>
<tag>Debian</tag>
<tt>/etc/init.d/boot</> (for older releases)
<newline>
<tt>/etc/init.d/</> (for newer releases)
<newline>
A <tt/brltty/ package is provided
(see [<htmlurl url="http://packages.debian.org/brltty" name="http://packages.debian.org/brltty">])
as of release <tt/3.0/ (<tt/Woody/).
Since this package takes care of starting BRLTTY,
there's no need for user-supplied code to do so if it's installed.
If you need the daemon to run with some command-line options,
you can change the contents between quotes
on the directive <tt/ARGUMENTS/
in the <tt>/etc/default/brltty</> file.
<tag>RedHat</tag>
<tt>/etc/rc.d/rc.sysinit</>
<newline>
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 <tt/initlog/.
Look, probably right up near the top, for a set of lines like these:
<tscreen><verb>
# Rerun ourselves through initlog
if [ -z "$IN_INITLOG" ]; then
[ -f /sbin/initlog ] && exec /sbin/initlog $INITLOG_ARGS -r /etc/rc.sysinit
fi
</verb></tscreen>
Starting BRLTTY before this reinvocation
results in two BRLTTY processes 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.
<tag>Slackware</tag>
<tt>/etc/rc.d/rc.S</>
<tag>SuSE</tag>
<tt>/sbin/init.d/boot</>
</descrip>
An alternative is to start BRLTTY from <tt>/etc/inittab</>.
You have two choices if you choose this route.
<itemize>
<item>
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 <tt/:sysinit:/ line which is already in there.
<tscreen>brl::sysinit:/bin/brltty</tscreen>
<item>
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.
<tscreen>brl:12345:respawn:/bin/brltty -n</tscreen>
The <ref id="options-no-daemon" name="-n"> (<tt/--nodaemon/) option is very
important when running BRLTTY with <bf/init/'s <tt/respawn/ facility.
You'll end up with hundreds of BRLTTY processes all running at the same time
if you forget to specify it.
</itemize>
Check that the identifier (<tt/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 <tt/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 <ref id="command-RESTARTBRL" name="RESTARTBRL"> command).
Better yet, turn off the serial port probing.
Here's what we know so far about how to do this:
<descrip>
<tag/Red Hat/
The probing is done by a service named <tt/kudzu/.
Use the command <tscreen>chkconfig --list kudzu</tscreen> to see if it's been enabled.
Use the command <tscreen>chkconfig kudzu off</tscreen> to disable it.
Later releases allow you to let <tt/kudzu/ run
without probing the serial ports.
To do this, edit the file <tt>/etc/sysconfig/kudzu</>,
and set <tt/SAFE/ to <tt/yes/.
</descrip>
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 <ref id="build-execute-root" name="--with-execute-root">,
<ref id="build-program-directory" name="--bindir">,
<ref id="build-library-directory" name="--libdir">,
<ref id="build-writable-directory" name="--with-writable-directory">,
and <ref id="build-data-directory" name="--with-data-directory">
build options.
<sect1>Security Considerations<p>
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 <tt>/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.
<sect1>Build and Run-Time Restrictions<p>
<descrip>
<tag/Alert Tunes/<label id="restrictions-tunes">
Some platforms don't support all of the tune devices.
See the <ref id="preference-tune-device" name="Tune Device">
preference for details.
<tag/FestivalLite Speech Synthesizer Driver/<label id="restrictions-flite">
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 <ref id="build-theta" name="--with-theta"> build option)
cannot be simultaneously linked into the BRLTTY binary
(see the <ref id="build-speech-driver" name="--with-speech-driver"> build option)
because their run-time libraries contain conflicting symbols.
<tag/Libbraille Braille Display Driver/<label id="restrictions-libbraille">
The driver for the Libbraille package
is only built if that package has been installed.
<tag/Mikropuhe Speech Synthesizer Driver/<label id="restrictions-mikropuhe">
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 <ref id="build-standalone-programs" name="--enable-standalone-programs"> build option)
because a static archive isn't included with the package.
<tag/Theta Speech Synthesizer Driver/<label id="restrictions-theta">
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 <ref id="build-flite" name="--with-flite"> build option)
cannot be simultaneously linked into the BRLTTY binary
(see the <ref id="build-speech-driver" name="--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 <tt>$THETA_HOME/lib</> must be added
to the <tt/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.
<tag/ViaVoice Speech Synthesizer Driver/<label id="restrictions-viavoice">
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 <ref id="build-standalone-programs" name="--enable-standalone-programs"> build option)
because a static archive isn't included with the package.
<tag/VideoBraille Braille Display Driver/<label id="restrictions-videobraille">
The driver for the VideoBraille braille display is built on all systems,
but only works on Linux.
</descrip>
<sect1>Installing from an RPM File<label id="rpm"><p>
To install BRLTTY from an RPM (RedHat Package Manager) file, do the following:
<enum>
<item>
Download the binary package which corresponds to your hardware.
It'll be a file named
<tt/brltty-/<em/release/<tt/-/<em/version/<tt/./<em/architecture/<tt/.rpm/,
e.g. <tt/brltty-3.0-1.i386.rpm/.
<item>
Install the package.
<tscreen>rpm -Uvh brltty-<em/release/-<em/version/.<em/architecture/.rpm</tscreen>
This should be done as <bf/root/.
Strictly speaking, the <tt/-U/ (update) option is the only one which is necessary.
The <tt/-v/ (verbose) option displays the name of the package as it's being installed.
The <tt/-h/ (hashes) option displays a progress meter (using hash signs).
</enum>
For the brave,
we also provide the source RPM (<tt/.src.rpm/) file,
but that's beyond the scope of this document.
To uninstall BRLTTY, do:
<tscreen>rpm -e brltty</tscreen>
<sect1>Other Utilities<p>
Building BRLTTY also results in the building of
a few small helper and diagnostic utilities.
<sect2>brltty-config<label id="utility-brltty-config"><p>
This utility sets a number of environment variables to values
which reflect the current installation of BRLTTY
(see <ref id="build" name="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 <bf/Bourne Shell/ syntax.
<tscreen>. brltty-config</tscreen>
The following environment variables are set:
<descrip>
<tag/BRLTTY_VERSION/
The version number of the BRLTTY package.
<tag/BRLTTY_EXECUTE_ROOT/
Run-time root for the installed package.
Configured via the <ref id="build-execute-root" name="--with-execute-root"> build option.
<tag/BRLTTY_PROGRAM_DIRECTORY/
Directory for runnable programs (binaries, executables).
Configured via the <ref id="build-program-directory" name="--with-program-directory"> build option.
<tag/BRLTTY_LIBRARY_DIRECTORY/
Directory for drivers.
Configured via the <ref id="build-library-directory" name="--with-library-directory"> build option.
<tag/BRLTTY_WRITABLE_DIRECTORY/
Directory which can be written to.
Configured via the <ref id="build-writable-directory" name="--with-writable-directory"> build option.
<tag/BRLTTY_DATA_DIRECTORY/
Directory for tables and help pages.
Configured via the <ref id="build-data-directory" name="--with-data-directory"> build option.
<tag/BRLTTY_MANPAGE_DIRECTORY/
Directory for manual pages.
Configured via the <ref id="build-manpage-directory" name="--with-manpage-directory"> build option.
<tag/BRLTTY_INCLUDE_DIRECTORY/
Directory for BrlAPI's C header files.
Configured via the <ref id="build-include-directory" name="--with-include-directory"> build option.
<tag/BRLAPI_VERSION/
The version number of BrlAPI (BRLTTY's Application Programming Interface).
<tag/BRLAPI_RELEASE/
The full release number of BrlAPI.
<tag/BRLAPI_AUTH/
The name of BrlAPI's key file.
</descrip>
In addition, the following standard <bf/autoconf/ environment variables are also set:
<descrip>
<tag/prefix/
Subroot for architecture-independent files.
Configured via the <ref id="build-portable-root" name="--prefix"> build option.
<tag/exec_prefix/
Subroot for architecture-dependent files.
Configured via the <ref id="build-architecture-root" name="--exec-prefix"> build option.
<tag/bindir/
Default location for <ref id="build-program-directory" name="program directory">.
Configured via the <tt/--bindir/ build option.
<tag/libdir/
Directory for BrlAPI's static archive and dynamically loadable object.
Default anchor for <ref id="build-library-directory" name="library directory">.
Configured via the <ref id="build-api-directory" name="--libdir"> build option.
<tag/sysconfdir/
Directory for configuration files.
Default anchor for <ref id="build-data-directory" name="data directory">.
Configured via the <ref id="build-configuration-directory" name="--sysconfdir"> build option.
<tag/mandir/
Default location for <ref id="build-manpage-directory" name="manual pages directory">.
Configured via the <tt/--mandir/ build option.
<tag/includedir/
Default anchor for <ref id="build-include-directory" name="header files directory">.
Configured via the <tt/--includedir/ build option.
</descrip>
<sect2>brltty-install<label id="utility-brltty-install"><p>
This utility copies BRLTTY's
<ref id="hierarchy" name="installed file hierarchy">
from one location to another.
<tscreen>brltty-install <em/to/ [<em/from/]</tscreen>
<descrip>
<tag><em/to/</tag>
The location to which the
<ref id="hierarchy" name="installed file hierarchy">
is to be copied.
It must be an existing directory.
<tag><em/from/</tag>
The location from which the
<ref id="hierarchy" name="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.
</descrip>
This utility can be used, for example, to copy BRLTTY to a root disk.
If a root floppy is mounted as <tt>/mnt</>,
and BRLTTY is installed on the main system,
then typing <tscreen>brltty-install /mnt</tscreen>
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.
<sect2>brltest<label id="utility-brltest"><p>
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.
<tscreen>brltest -<em/option/ ... [<em/driver/ [<em/name/=<em/value/ ...]]</tscreen>
<descrip>
<tag><em/driver/</tag>
The driver for the braille display.
It must be a two-letter <ref id="drivers" name="driver identification code">.
If it's not specified, then the first driver configured via the
<ref id="build-braille-driver" name="--with-braille-driver"> build option
is assumed.
<tag><em/name/<tt/=/<em/value/</tag>
Set a braille display driver parameter.
For a description of the parameters accepted by a specific driver,
please see the documentation for that driver.
<tag><tt/-d/<em/device/ <tt/--device=/<em/device/</tag>
The absolute path for the device to which the braille display is connected.
If it's not specified, then the device configured via the
<ref id="build-braille-device" name="--with-braille-device"> build option
is assumed.
<tag><tt/-D/<em/directory/ <tt/--data-directory=/<em/directory/</tag>
The absolute path for the directory wherein the driver data files reside.
If it's not specified, then the directory configured via the
<ref id="build-data-directory" name="--with-data-directory"> build option
is assumed.
<tag><tt/-L/<em/directory/ <tt/--library-directory=/<em/directory/</tag>
The absolute path for the directory wherein the drivers reside.
If it's not specified, then the directory configured via the
<ref id="build-library-directory" name="--libdir"> build option
is assumed.
<tag><tt/-W/<em/directory/ <tt/--writable-directory=/<em/directory/</tag>
The absolute path for a directory which can be written to.
If it's not specified, then the directory configured via the
<ref id="build-writable-directory" name="--with-writable-directory"> build option
is assumed.
<tag><tt/-h/ <tt/--help/</tag>
Display a summary of the command line options, and then exit.
</descrip>
This utility uses BRLTTY's <ref id="learn" name="Command Learn Mode">.
The key press timeout
(after which this utility exits)
is <tt/10/ seconds.
The message hold time
(used for non-final segments of long messages)
is <tt/4/ seconds.
<sect2>spktest<label id="utility-spktest"><p>
This utility tests a speech synthesizer driver.
It may need to be run as root.
<tscreen>spktest -<em/option/ ... [<em/driver/ [<em/name/=<em/value/ ...]]</tscreen>
<descrip>
<tag><em/driver/</tag>
The driver for the speech synthesizer.
It must be a two-letter <ref id="drivers" name="driver identification code">.
If it's not specified, then the first driver configured via the
<ref id="build-speech-driver" name="--with-speech-driver"> build option
is assumed.
<tag><em/name/<tt/=/<em/value/</tag>
Set a speech synthesizer driver parameter.
For a description of the parameters accepted by a specific driver,
please see the documentation for that driver.
<tag><tt/-t/<em/string/ <tt/--text-string=/<em/string/</tag>
The text to be spoken.
If it's not specified, then standard input is read.
<tag><tt/-D/<em/directory/ <tt/--data-directory=/<em/directory/</tag>
The absolute path for the directory wherein the driver data files reside.
If it's not specified, then the directory configured via the
<ref id="build-data-directory" name="--with-data-directory"> build option
is assumed.
<tag><tt/-L/<em/directory/ <tt/--library-directory=/<em/directory/</tag>
The absolute path for the directory wherein the drivers reside.
If it's not specified, then the directory configured via the
<ref id="build-library-directory" name="--libdir"> build option
is assumed.
<tag><tt/-h/ <tt/--help/</tag>
Display a summary of the command line options, and then exit.
</descrip>
<sect2>scrtest<label id="utility-scrtest"><p>
This utility tests the screen driver.
It must be run as root.
<tscreen>scrtest -<em/option/ ... [<em/name/=<em/value/ ...]</tscreen>
<descrip>
<tag><em/name/<tt/=/<em/value/</tag>
Set a screen driver parameter.
For a description of the parameters accepted by a specific driver,
please see the documentation for that driver.
<tag><tt/-l/<em/column/ <tt/--left=/<em/column/</tag>
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.
<tag><tt/-c/<em/count/ <tt/--columns=/<em/count/</tag>
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.
<tag><tt/-t/<em/row/ <tt/--top=/<em/row/</tag>
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.
<tag><tt/-r/<em/count/ <tt/--rows=/<em/count/</tag>
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.
<tag><tt/-h/ <tt/--help/</tag>
Display a summary of the command line options, and then exit.
</descrip>
Notes:
<itemize>
<item>
If neither a starting column nor a region width is specified,
then the region is horizontally-centred and starts at column 5.
<item>
If neither a starting row nor a region height is specified,
then the region is vertically-centred and starts at row 5.
</itemize>
The following is written to standard output:
<enum>
<item>
A line detailing the dimensions of the screen.
<tscreen>Screen: <em/width/x<em/height/</tscreen>
<item>
A line detailing the position (zero-origin) of the cursor.
<tscreen>Cursor: [<em/column/,<em/row/]</tscreen>
<item>
A line detailing the size of the selected screen region,
and the position (zero-origin) of its top-left corner.
<tscreen>Region: <em/width/x<em/height/@[<em/column/,<em/row/]</tscreen>
<item>
The contents of the selected screen region.
Unprintable characters are written as blanks.
</enum>
<sect2>ttbtest<label id="utility-ttbtest"><p>
This utility tests a text table
(see section <ref id="table-text" name="Text Tables">).
<tscreen>ttbtest -<em/option/ ... <em/input-table/ <em/output-table/</tscreen>
<descrip>
<tag><em/input-table/</tag>
The file system path to the input text table.
If it's relative then it's anchored at the directory configured via the
<ref id="build-data-directory" name="--with-data-directory"> build option.
<tag><em/output-table/</tag>
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.
<tag><tt/-i/<em/format/ <tt/--input-format=/<em/format/</tag>
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.
<tag><tt/-o/<em/format/ <tt/--output-format=/<em/format/</tag>
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.
<tag><tt/-c/<em/charset/ <tt/--charset=/<em/charset/</tag>
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.
<tag><tt/-e/ <tt/--edit/</tag>
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.
<tag><tt/-h/ <tt/--help/</tag>
Display a summary of the command line options, and then exit.
</descrip>
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:
<descrip>
<tag/ttb/BRLTTY
<tag/sbl/SuSE Blinux
<tag/a2b/Gnopernicus
<tag/gnb/Gnome Braille
</descrip>
<sect2>ctbtest<label id="utility-ctbtest"><p>
This utility tests a contraction table
(see section <ref id="table-contraction" name="Contraction Tables">).
The text read from the input files (or standard input)
is rewritten to standard output as contracted braille.
<tscreen>ctbtest -<em/option/ ... <em/input-file/ ...</tscreen>
<descrip>
<tag><em/input-file/</tag>
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 <tt/-/ is interpreted to mean standard input.
If no files are specified then standard input is processed.
<tag><tt/-c/<em/file/ <tt/--contraction-table=/<em/file/</tag>
The file system path to the contraction table.
If it's relative then it's anchored at the directory configured via the
<ref id="build-data-directory" name="--with-data-directory"> build option.
The <tt/.ctb/ extension is optional.
If this option isn't supplied then <tt/en-us-g2/ is assumed.
<tag><tt/-t/<em/file/|<tt/auto/ <tt/--text-table=/<em/file/|<tt/auto/</tag>
Specify the text table
(see section <ref id="table-text" name="Text Tables"> for details).
If a relative path is supplied, then it's anchored at <tt>/etc/brltty</>
(see the <ref id="build-data-directory" name="--with-data-directory">
and the <ref id="build-execute-root" name="--with-execute-root">
build options for more details).
The <tt/.ttb/ extension is optional.
See the <ref id="configure-text-table" name="text-table">
configuration file directive for the default run-time setting.
This setting can be changed with the
<ref id="preference-text-table" name="Text Table"> preference.
<tag><tt/-w/<em/columns/ <tt/--output-width=/<em/columns/</tag>
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.
<tag><tt/-h/ <tt/--help/</tag>
Display a summary of the command line options, and then exit.
</descrip>
The text table is used:
<itemize>
<item>
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.
<item>
To define the braille representations of those characters
defined within the contraction table as <tt/=/
(see section <ref id="contraction-opcodes-translation" name="Character Translation">).
</itemize>
The <tt/brf.ttb/ text table is provided for use with this utility.
It defines the format used within <tt/.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.
<sect2>tunetest<label id="utility-tunetest"><p>
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.
<tscreen>tunetest -<em/option/ ... {<em/note/ <em/duration/} ...</tscreen>
<descrip>
<tag><em/note/</tag>
A standard <tt/MIDI/ note number.
It must be an integer from <tt/1/ through <tt/127/,
with <tt/60/ representing <tt/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 (<tt/1/) represents
the fifth <tt/C-Sharp/ below <tt/Middle C/,
and the highest value (<tt/127/) represents
the sixth <tt/G/ above <tt/Middle C/.
<tag><em/duration/</tag>
The duration of the note in milliseconds.
It must be an integer from <tt/1/ through <tt/255/.
<tag><tt/-d/<em/device/ <tt/--device=/<em/device/</tag>
The device on which to play the tune.
<descrip>
<tag/beeper/
The internal beeper (console tone generator).
<tag/pcm/
The digital audio interface on the sound card.
<tag/midi/
The Musical Instrument Digital Interface on the sound card.
<tag/fm/
The FM synthesizer on an
AdLib, OPL3, Sound Blaster, or equivalent sound card.
</descrip>
The device name may be abbreviated.
See the <ref id="preference-tune-device" name="Tune Device"> preference
for details regarding the default device and platform restrictions.
<tag><tt/-v/<em/loudness/ <tt/--volume=/<em/loudness/</tag>
Specify the output volume (loudness) as a percentage of the maximum.
The default output volume is <tt/50/.
<tag><tt/-p/<em/device/ <tt/--pcm-device=/<em/device/</tag>
Specify the device to use for digital audio
(see section <ref id="operand-pcm-device" name="PCM Device Specification">).
This option isn't available if the
<ref id="build-pcm-support" name="--disable-pcm-support"> build option was specified.
<tag><tt/-m/<em/device/ <tt/--midi-device=/<em/device/</tag>
Specify the device to use for the Musical Instrument Digital Interface
(see section <ref id="operand-midi-device" name="MIDI Device Specification">).
This option isn't available if the
<ref id="build-midi-support" name="--disable-midi-support"> build option was specified.
<tag><tt/-i/<em/instrument/ <tt/--instrument=/<em/instrument/</tag>
The instrument to use if the selected device is <tt/midi/.
For the complete list of instruments,
see the <ref id="midi" name="MIDI Instrument Table">.
The default instrument is an <tt/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 <tt/acoustic grand piano/, for example, may be specified as <tt/a-gra-pi/.
<tag><tt/-h/ <tt/--help/</tag>
Display a summary of the command line options, and then exit.
</descrip>
<sect>Using BRLTTY<p>
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 <tt/brltty/ at a shell prompt
(this must be done as root).
Check the
<ref id="options-braille-device" name="-d"> command line option,
the <ref id="configure-braille-device" name="braille-device"> configuration file directive,
and the <ref id="build-braille-device" name="--with-braille-device"> build option
for alternatives regarding how to tell BRLTTY which device your display is connected to.
Check the
<ref id="options-braille-driver" name="-b"> command line option,
the <ref id="configure-braille-driver" name="braille-driver"> configuration file directive,
and the <ref id="build-braille-driver" name="--with-braille-driver"> build option
for alternatives regarding how to tell BRLTTY which kind of braille display you have.
Check the
<ref id="options-braille-parameters" name="-B"> command line option,
and the <ref id="configure-braille-parameters" name="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 <ref id="options-message-delay" name="-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 <bf/cursor tracking/.
Just typing on the keyboard and reading the display, however, isn't enough.
Try entering a command which will cause an error, and pressing <bf/enter/.
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 <em/window/ 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.
<sect1>Commands<label id="commands"><p>
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 <ref id="command-HELP" name="HELP"> command.
Use the regular motion keys (as described below) to navigate the help page,
and press the <tt/help/ key again to quit.
<sect2>Vertical Motion<label id="vertical"><p>
See also
the <ref id="command-PRINDENT-NXINDENT" name="PRINDENT/NXINDENT">,
and the <ref id="command-PRDIFCHAR-NXDIFCHAR" name="PRDIFCHAR/NXDIFCHAR">
routing key commands.
<descrip>
<tag>LNUP/LNDN<label id="command-LNUP-LNDN"></tag>
Go up/down one line.
If identical line skipping has been activated
(see the <ref id="command-SKPIDLNS" name="SKPIDLNS"> command),
then these commands, rather than moving exactly one line,
are aliases for the <ref id="command-PRDIFLN-NXDIFLN" name="PRDIFLN/NXDIFLN"> commands.
<tag>WINUP/WINDN<label id="command-WINUP-WINDN"></tag>
Go up/down one window.
If the window is only 1 line high then move 5 lines.
<tag>PRDIFLN/NXDIFLN<label id="command-PRDIFLN-NXDIFLN"></tag>
Go up/down to the nearest line with different content.
If identical line skipping has been activated
(see the <ref id="command-SKPIDLNS" name="SKPIDLNS"> command),
then these commands, rather than skipping identical lines,
are aliases for the <ref id="command-LNUP-LNDN" name="LNUP/LNDN"> commands.
<tag>ATTRUP/ATTRDN<label id="command-ATTRUP-ATTRDN"></tag>
Go up/down to the nearest line with different attributes (character highlighting).
<tag>TOP/BOT<label id="command-TOP-BOT"></tag>
Go to the top/bottom line.
<tag>TOP_LEFT/BOT_LEFT<label id="command-TOP_LEFT-BOT_LEFT"></tag>
Go to the top-left/bottom-left corner.
<tag>PRPGRPH/NXPGRPH<label id="command-PRPGRPH-NXPGRPH"></tag>
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.
<tag>PRPROMPT/NXPROMPT<label id="command-PRPROMPT-NXPROMPT"></tag>
Go to the previous/next command prompt.
<tag>PRSEARCH/NXSEARCH<label id="command-PRSEARCH-NXSEARCH"></tag>
Search backward/forward for the nearest occurrence
of the character string within the cut buffer
(see <ref id="cut" name="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.
</descrip>
<sect2>Horizontal Motion<label id="horizontal"><p>
See also the <ref id="command-SETLEFT" name="SETLEFT"> routing key command.
<descrip>
<tag>CHRLT/CHRRT<label id="command-CHRLT-CHRRT"></tag>
Go left/right one character.
<tag>HWINLT/HWINRT<label id="command-HWINLT-HWINRT"></tag>
Go left/right half a window.
<tag>FWINLT/FWINRT<label id="command-FWINLT-FWINRT"></tag>
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 <ref id="command-SKPBLNKWINS" name="SKPBLNKWINS"> command),
further enhance their usefulness.
<tag>FWINLTSKIP/FWINRTSKIP<label id="command-FWINLTSKIP-FWINRTSKIP"></tag>
Go left/right to the nearest non-blank window.
<tag>LNBEG/LNEND<label id="command-LNBEG-LNEND"></tag>
Go to the beginning/end of the line.
</descrip>
<sect2>Implicit Motion<p>
See also the <ref id="command-GOTOMARK" name="GOTOMARK"> routing key command.
<descrip>
<tag>HOME<label id="command-HOME"></tag>
Go to where the cursor is.
<tag>BACK<label id="command-BACK"></tag>
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.
<tag>RETURN<label id="command-RETURN"></tag>
<itemize>
<item>
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 <ref id="command-BACK" name="BACK"> command).
<item>
If the cursor isn't within the braille window
then go to where the cursor is
(see the <ref id="command-HOME" name="HOME"> command).
</itemize>
</descrip>
<sect2>Feature Activation<label id="commands-features"><p>
Each of these commands has three forms:
<bf/activate/ (turn the feature on),
<bf/deactivate/ (turn the feature off),
and <bf/toggle/ (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 <bf/off/, and, when <bf/on/, affects BRLTTY's operation as a whole.
The initial setting of some of these features can be changed
via the <ref id="preferences-menu" name="preferences menu">.
<descrip>
<tag>FREEZE<label id="command-FREEZE"></tag>
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.
<tag>DISPMD<label id="command-DISPMD"></tag>
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 <ref id="options-text-table" name="-t"> command line option,
the <ref id="configure-text-table" name="text-table"> configuration file directive,
and the <ref id="build-text-table" name="--with-text-table"> build option).
When showing screen attributes, the attributes table is used
(see the <ref id="options-attributes-table" name="-a"> command line option,
the <ref id="configure-attributes-table" name="attributes-table"> configuration file directive,
and the <ref id="build-attributes-table" name="--with-attributes-table"> build option).
This feature only affects the current virtual terminal.
<tag>SIXDOTS<label id="command-SIXDOTS"></tag>
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 <ref id="options-contraction-table" name="-c"> command line option
and the <ref id="configure-contraction-table" name="contraction-table"> configuration file directive),
then it is used.
This setting can also be changed with the
<ref id="preference-text-style" name="Text Style"> preference.
<tag>SLIDEWIN<label id="command-SLIDEWIN"></tag>
If cursor tracking
(see the <ref id="command-CSRTRK" name="CSRTRK"> command)
is <bf/on/, 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 <bf/off/,
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
<ref id="preference-sliding-window" name="Sliding Window"> preference.
<tag>SKPIDLNS<label id="command-SKPIDLNS"></tag>
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 <ref id="command-LNUP-LNDN" name="LNUP/LNDN"> commands,
as well as the line wrapping feature of
the <ref id="command-FWINLT-FWINRT" name="FWINLT/FWINRT">
and <ref id="command-FWINLTSKIP-FWINRTSKIP" name="FWINLTSKIP/FWINRTSKIP"> commands.
This setting can also be changed with the
<ref id="preference-skip-identical-lines" name="Skip Identical Lines"> preference.
<tag>SKPBLNKWINS<label id="command-SKPBLNKWINS"></tag>
Skip past blank windows when reading either forward or backward.
This feature affects the <ref id="command-FWINLT-FWINRT" name="FWINLT/FWINRT"> commands.
This setting can also be changed with the
<ref id="preference-skip-blank-windows" name="Skip Blank Windows"> preference.
<tag>CSRVIS<label id="command-CSRVIS"></tag>
Show the cursor by superimposing a dot pattern
(see the <ref id="command-CSRSIZE" name="CSRSIZE"> command)
on top of the character where it is.
This feature is initially <bf/on/.
This setting can also be changed with the
<ref id="preference-show-cursor" name="Show Cursor"> preference.
<tag>CSRHIDE<label id="command-CSRHIDE"></tag>
Hide the cursor (see the <ref id="command-CSRVIS" name="CSRVIS"> command)
in order to accurately read the character beneath it.
This feature only affects the current virtual terminal.
<tag>CSRTRK<label id="command-CSRTRK"></tag>
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 <ref id="command-BACK" name="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 <bf/on/.
This feature only affects the current virtual terminal.
<tag>CSRSIZE<label id="command-CSRSIZE"></tag>
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
<ref id="preference-cursor-style" name="Cursor Style"> preference.
<tag>CSRBLINK<label id="command-CSRBLINK"></tag>
Blink (turn on and off according to a predefined interval)
the symbol representing the cursor
(see the <ref id="command-CSRVIS" name="CSRVIS"> command).
This setting can also be changed with the
<ref id="preference-blinking-cursor" name="Blinking Cursor"> preference.
<tag>ATTRVIS<label id="command-ATTRVIS"></tag>
Underline (with combinations of dots 7 and 8) highlighted characters.
<descrip>
<tag/no underline/
White on black (normal),
gray on black,
white on blue,
black on cyan.
<tag/dots 7 and 8/
Black on white (reverse video).
<tag/dot 8/
Everything else.
</descrip>
This setting can also be changed with the
<ref id="preference-show-attributes" name="Show Attributes"> preference.
<tag>ATTRBLINK<label id="command-ATTRBLINK"></tag>
Blink (turn on and off according to a predefined interval)
the attribute underline
(see the <ref id="command-ATTRVIS" name="ATTRVIS"> command).
This feature is initially <bf/on/.
This setting can also be changed with the
<ref id="preference-blinking-attributes" name="Blinking Attributes"> preference.
<tag>CAPBLINK<label id="command-CAPBLINK"></tag>
Blink (turn on and off according to a predefined interval)
capital (uppercase) letters.
This setting can also be changed with the
<ref id="preference-blinking-capitals" name="Blinking Capitals"> preference.
<tag>TUNES<label id="command-TUNES"></tag>
Play a short predefined tune (see <ref id="tunes" name="Alert Tunes">)
whenever a significant event occurs.
This feature is initially <bf/on/.
This setting can also be changed with the
<ref id="preference-alert-tunes" name="Alert Tunes"> preference.
<tag>AUTOREPEAT<label id="command-AUTOREPEAT"></tag>
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 <bf/on/.
This setting can also be changed with the
<ref id="preference-autorepeat" name="Autorepeat"> preference.
<tag>AUTOSPEAK<label id="command-AUTOSPEAK"></tag>
Automatically speak:
<itemize>
<item>the new line when the braille window is moved vertically.
<item>characters which are entered or deleted.
<item>the character to which the cursor is moved.
</itemize>
This feature is initially <bf/off/.
This setting can also be changed with the
<ref id="preference-autospeak" name="Autospeak"> preference.
</descrip>
<sect2>Mode Selection<p>
<descrip>
<tag>HELP<label id="command-HELP"></tag>
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 <ref id="vertical" name="vertical">
and <ref id="horizontal" name="horizontal"> motion commands
to navigate the help page.
Invoke the <tt/help/ command again to return to the screen.
<tag>INFO<label id="command-INFO"></tag>
Switch to the status display
(see section <ref id="status" name="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.
<tag>LEARN<label id="command-LEARN"></tag>
Switch to command learn mode
(see section <ref id="learn" name="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
<ref id="build-learn-mode" name="--disable-learn-mode"> build option was specified.
</descrip>
<sect2>Preference Maintenance<p>
<descrip>
<tag>PREFMENU<label id="command-PREFMENU"></tag>
Switch to the preferences menu
(see <ref id="preferences-menu" name="The Preferences Menu"> for full details).
Invoke this command again to return to normal operation.
<tag>PREFSAVE<label id="command-PREFSAVE"></tag>
Save the current preferences settings
(see <ref id="preferences" name="Preferences"> for full details).
<tag>PREFLOAD<label id="command-PREFLOAD"></tag>
Restore the most recently saved preferences settings
(see <ref id="preferences" name="Preferences"> for full details).
</descrip>
<sect2>Menu Navigation<label id="menu"><p>
<descrip>
<tag>MENU_FIRST_ITEM/MENU_LAST_ITEM<label id="command-MENU_FIRST_ITEM-MENU_LAST_ITEM"></tag>
Go to the first/last item in the menu.
<tag>MENU_PREV_ITEMMENU_NEXT_ITEM/<label id="command-MENU_PREV_ITEM-MENU_NEXT_ITEM"></tag>
Go to the previous/next item in the menu.
<tag>MENU_PREV_SETTING/MENU_NEXT_SETTING<label id="command-MENU_PREV_SETTING-MENU_NEXT_SETTING"></tag>
Decrement/increment the current menu item's setting.
</descrip>
<sect2>Speech Controls<label id="speech"><p>
<descrip>
<tag>SAY_LINE<label id="command-SAY_LINE"></tag>
Speak the current line.
The <ref id="preference-sayline-mode" name="Say-Line Mode"> preference
determines if pending speech is discarded first.
<tag>SAY_ABOVE<label id="command-SAY_ABOVE"></tag>
Speak the top portion of the screen (ending with the current line).
<tag>SAY_BELOW<label id="command-SAY_BELOW"></tag>
Speak the bottom portion of the screen (starting with the current line).
<tag>MUTE<label id="command-MUTE"></tag>
Stop speaking immediately.
<tag>SPKHOME<label id="command-SPKHOME"></tag>
Go to where the speech cursor is.
<tag>SAY_SLOWER/SAY_FASTER<label id="command-SAY_SLOWER-SAY_FASTER"></tag>
Decrease/increase the speech rate
(see also the <ref id="preference-speech-rate" name="Speech Rate"> preference).
This command is only available if a driver which supports it is being used.
<tag>SAY_SOFTER/SAY_LOUDER<label id="command-SAY_SOFTER-SAY_LOUDER"></tag>
Decrease/increase the speech volume
(see also the <ref id="preference-speech-volume" name="Speech Volume"> preference).
This command is only available if a driver which supports it is being used.
</descrip>
<sect2>Virtual Terminal Switching<p>
See also the <ref id="command-SWITCHVT" name="SWITCHVT"> routing key command.
<descrip>
<tag>SWITCHVT_PREV/SWITCHVT_NEXT<label id="command-SWITCHVT_PREV-SWITCHVT_NEXT"></tag>
Switch to the previous/next virtual terminal.
</descrip>
<sect2>Other Commands<p>
<descrip>
<tag>CSRJMP_VERT<label id="command-CSRJMP_VERT"></tag>
Route (bring) the cursor to anywhere on the top line of the braille window
(see <ref id="routing" name="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.
<tag>PASTE<label id="command-PASTE"></tag>
Insert the characters within the cut buffer at the current cursor location
(see <ref id="cut" name="Cut and Paste"> for full details).
<tag>RESTARTBRL<label id="command-RESTARTBRL"></tag>
Stop, and then restart the braille display driver.
<tag>RESTARTSPEECH<label id="command-RESTARTSPEECH"></tag>
Stop, and then restart the speech synthesizer driver.
</descrip>
<sect2>Character Commands<label id="commands-characters"><p>
<descrip>
<tag>ROUTE<label id="command-ROUTE"></tag>
Route (bring) the cursor to the character
associated with the routing key
(see <ref id="routing" name="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.
<tag>CUTBEGIN<label id="command-CUTBEGIN"></tag>
Anchor the start of the cut block at the character
associated with the routing key
(see <ref id="cut" name="Cut and Paste"> for full details).
This command clears the cut buffer.
<tag>CUTAPPEND<label id="command-CUTAPPEND"></tag>
Anchor the start of the cut block at the character
associated with the routing key
(see <ref id="cut" name="Cut and Paste"> for full details).
This command doesn't clear the cut buffer.
<tag>CUTRECT<label id="command-CUTRECT"></tag>
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 <ref id="cut" name="Cut and Paste"> for full details).
<tag>CUTLINE<label id="command-CUTLINE"></tag>
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 <ref id="cut" name="Cut and Paste"> for full details).
<tag>COPYCHARS<label id="command-COPYCHARS"></tag>
Copy the character block
anchored by the two routing keys
to the cut buffer
(see <ref id="cut" name="Cut and Paste"> for full details).
<tag>APNDCHARS<label id="command-APNDCHARS"></tag>
Append the character block
anchored by the two routing keys
to the cut buffer
(see <ref id="cut" name="Cut and Paste"> for full details).
<tag>PRINDENT/NXINDENT<label id="command-PRINDENT-NXINDENT"></tag>
Go up/down to the nearest line which isn't indented
more than the column associated with the routing key.
<tag>DESCCHAR<label id="command-DESCCHAR"></tag>
Momentarily (see the <ref id="options-message-delay" name="-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 (<tt/bright/ and <tt/blink/).
The message looks like this:
<tscreen>char 65 (0x41): white on black bright blink</tscreen>
<tag>SETLEFT<label id="command-SETLEFT"></tag>
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 <ref id="command-CHRLT-CHRRT" name="CHRLT/CHRRT">
and <ref id="command-HWINLT-HWINRT" name="HWINLT/HWINRT">
commands).
<tag>PRDIFCHAR/NXDIFCHAR<label id="command-PRDIFCHAR-NXDIFCHAR"></tag>
Go up/down to the nearest line which has a different character
in the column associated with the routing key.
</descrip>
<sect2>Base Commands<label id="commands-base"><p>
<descrip>
<tag>SWITCHVT<label id="command-SWITCHVT"></tag>
Switch to the virtual terminal whose number
(counting from 1) matches that of the routing key.
See also the <ref id="command-SWITCHVT_PREV-SWITCHVT_NEXT" name="SWITCHVT_PREV/SWITCHVT_NEXT"> virtual terminal switching commands.
<tag>SETMARK<label id="command-SETMARK"></tag>
Mark (remember) the current position of the braille window
in a register associated with the routing key.
See the <ref id="command-GOTOMARK" name="GOTOMARK"> command.
This feature only affects the current virtual terminal.
<tag>GOTOMARK<label id="command-GOTOMARK"></tag>
Move the braille window to the position formerly marked
(see the <ref id="command-SETMARK" name="SETMARK"> command)
with the same routing key.
This feature only affects the current virtual terminal.
</descrip>
<sect1>The Configuration File<label id="configure"><p>
System defaults for many settings may be established within a configuration file.
The default name for this file is <tt>/etc/brltty.conf</tt>,
although it may be overridden with the
<ref id="options-configuration-file" name="-f"> command line option.
It doesn't need to exist.
A template for it can be found within the <tt/DOCS/ subdirectory.
Blank lines are ignored.
A comment begin with a number sign (<tt/#/),
and continues to the end of the line.
The following directives are recognized:
<descrip>
<tag><tt/api-parameters/ <em/name/<tt/=/<em/value/<tt/,/...<label id="configure-api-parameters"></tag>
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 <bf/BrlAPI/ reference manual.
See the <ref id="build-api-parameters" name="--with-api-parameters">
build option for the defaults established during the build procedure.
This directive can be overridden with the
<ref id="options-api-parameters" name="-A"> command line option.
<tag><tt/attributes-table/ <em/file/<label id="configure-attributes-table"></tag>
Specify the attributes table
(see section <ref id="table-attributes" name="Attributes Tables"> for details).
If a relative path is supplied, then it's anchored at <tt>/etc/brltty</>
(see the <ref id="build-data-directory" name="--with-data-directory">
and the <ref id="build-execute-root" name="--with-execute-root">
build options for more details).
The <tt/.atb/ extension is optional.
The default is to use the built-in table
(see the <ref id="build-attributes-table" name="--with-attributes-table"> build option).
This directive can be overridden with the
<ref id="options-attributes-table" name="-a"> command line option.
<tag><tt/braille-device/ <em/device/<tt/,/...<label id="configure-braille-device"></tag>
Specify the device to which the braille display is connected
(see section <ref id="operand-braille-device" name="Braille Device Specification">).
See the <ref id="build-braille-device" name="--with-braille-device">
build option for the default established during the build procedure.
This directive can be overridden with the
<ref id="options-braille-device" name="-d"> command line option.
<tag><tt/braille-driver/ <em/driver/<tt/,/...|<tt/auto/<label id="configure-braille-driver"></tag>
Specify the braille display driver
(see section <ref id="operand-driver" name="Driver Specification">).
The default is to perform autodetection.
This directive can be overridden with the
<ref id="options-braille-driver" name="-b"> command line option.
<tag><tt/braille-parameters/ [<em/driver/<tt/:/]<em/name/<tt/=/<em/value/<tt/,/...<label id="configure-braille-parameters"></tag>
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 <ref id="drivers" name="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 <ref id="build-braille-parameters" name="--with-braille-parameters">
build option for the defaults established during the build procedure.
This directive can be overridden with the
<ref id="options-braille-parameters" name="-B"> command line option.
<tag><tt/contraction-table/ <em/file/<label id="configure-contraction-table"></tag>
Specify the contraction table
(see section <ref id="table-contraction" name="Contraction Tables"> for details).
If a relative path is supplied, then it's anchored at <tt>/etc/brltty</>
(see the <ref id="build-data-directory" name="--with-data-directory">
and the <ref id="build-execute-root" name="--with-execute-root">
build options for more details).
The <tt/.ctb/ extension is optional.
The contraction table is used when the 6-dot braille feature is activated
(see the <ref id="command-SIXDOTS" name="SIXDOTS"> command
and the <ref id="preference-text-style" name="Text Style"> preference).
The default is to display uncontracted 6-dot braille.
This directive can be overridden with the
<ref id="options-contraction-table" name="-c"> command line option.
It isn't available if the
<ref id="build-contracted-braille" name="--disable-contracted-braille"> build option was specified.
<tag><tt/key-table/ <em/file/|<tt/auto/<label id="configure-key-table"></tag>
Specify the key table
(see section <ref id="table-key" name="Key Tables"> for details).
If a relative path is supplied, then it's anchored at <tt>/etc/brltty</>
(see the <ref id="build-data-directory" name="--with-data-directory">
and the <ref id="build-execute-root" name="--with-execute-root">
build options for more details).
The <tt/.ktb/ extension is optional.
The default is not to use a key table.
This directive can be overridden with the
<ref id="options-key-table" name="-k"> command line option.
<tag><tt/keyboard-properties/ <em/name/<tt/=/<em/value/<tt/,/...<label id="configure-keyboard-properties"></tag>
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 <ref id="keyboard-properties" name="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
<ref id="options-keyboard-properties" name="-K"> command line option.
<tag><tt/midi-device/ <em/device/<label id="configure-midi-device"></tag>
Specify the device to use for the Musical Instrument Digital Interface
(see section <ref id="operand-midi-device" name="MIDI Device Specification">).
This directive can be overridden with the
<ref id="options-midi-device" name="-m"> command line option.
It isn't available if the
<ref id="build-midi-support" name="--disable-midi-support"> build option was specified.
<tag><tt/pcm-device/ <em/device/<label id="configure-pcm-device"></tag>
Specify the device to use for digital audio
(see section <ref id="operand-pcm-device" name="PCM Device Specification">).
This directive can be overridden with the
<ref id="options-pcm-device" name="-p"> command line option.
It isn't available if the
<ref id="build-pcm-support" name="--disable-pcm-support"> build option was specified.
<tag><tt/preferences-file/ <em/file/<label id="configure-preferences-file"></tag>
Specify the location of the file which is to be used
for the saving and loading of user preferences.
If a relative path is supplied, then it's anchored at <tt>/var/lib/brltty</>.
The default is to use <tt/brltty.prefs/.
This directive can be overridden with the
<ref id="options-preferences-file" name="-F"> command line option.
<tag><tt/release-device/ <em/boolean/<label id="configure-release-device"></tag>
Whether or not to release the device to which the braille display is connected
when the current screen or window can't be read.
<descrip>
<tag/on/Release the device.
<tag/off/Don't release the device.
</descrip>
The default setting is <tt/on/ on Windows platforms
and <tt/off/ on all other platforms.
This directive can be overridden with the
<ref id="options-release-device" name="-r"> command line option.
<tag><tt/screen-driver/ <em/driver/<label id="configure-screen-driver"></tag>
Specify the screen driver
(see section <ref id="screen" name="Supported Screen Drivers">).
See the <ref id="build-screen-driver" name="--with-screen-driver">
build option for the default established during the build procedure.
This directive can be overridden with the
<ref id="options-screen-driver" name="-x"> command line option.
<tag><tt/screen-parameters/ [<em/driver/<tt/:/]<em/name/<tt/=/<em/value/<tt/,/...<label id="configure-screen-parameters"></tag>
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 <ref id="screen" name="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 <ref id="build-screen-parameters" name="--with-screen-parameters">
build option for the defaults established during the build procedure.
This directive can be overridden with the
<ref id="options-screen-parameters" name="-X"> command line option.
<tag><tt/speech-driver/ <em/driver/<tt/,/...|<tt/auto/<label id="configure-speech-driver"></tag>
Specify the speech synthesizer driver
(see section <ref id="operand-driver" name="Driver Specification">).
The default is to perform autodetection.
This directive can be overridden with the
<ref id="options-speech-driver" name="-s"> command line option.
It isn't available if the
<ref id="build-speech-support" name="--disable-speech-support"> build option was specified.
<tag><tt/speech-input/ <em/name/<label id="configure-speech-input"></tag>
Specify the name of the file system object
(FIFO, named pipe, named socket, etc)
which can be used by other applications
for text-to-speech conversion via BRLTTY's speech driver.
This directive can be overridden with the
<ref id="options-speech-input" name="-i"> command line option.
It isn't available if the
<ref id="build-speech-support" name="--disable-speech-support"> build option was specified.
<tag><tt/speech-parameters/ [<em/driver/<tt/:/]<em/name/<tt/=/<em/value/<tt/,/...<label id="configure-speech-parameters"></tag>
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 <ref id="drivers" name="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 <ref id="build-speech-parameters" name="--with-speech-parameters">
build option for the defaults established during the build procedure.
This directive can be overridden with the
<ref id="options-speech-parameters" name="-S"> command line option.
<tag><tt/text-table/ <em/file/|<tt/auto/<label id="configure-text-table"></tag>
Specify the text table
(see section <ref id="table-text" name="Text Tables"> for details).
If a relative path is supplied, then it's anchored at <tt>/etc/brltty</>
(see the <ref id="build-data-directory" name="--with-data-directory">
and the <ref id="build-execute-root" name="--with-execute-root">
build options for more details).
The <tt/.ttb/ extension is optional.
The default is to perform locale-based autoselection,
with fallback to the built-in table
(see the <ref id="build-text-table" name="--with-text-table"> build option).
This directive can be overridden with the
<ref id="options-text-table" name="-t"> command line option.
</descrip>
<sect1>Command Line Options<label id="options"><p>
Many settings can be explicitly specified when invoking BRLTTY.
The <tt/brltty/ command accepts the following options:
<descrip>
<tag><tt/-a/<em/file/ <tt/--attributes-table=/<em/file/<label id="options-attributes-table"></tag>
Specify the attributes table
(see section <ref id="table-attributes" name="Attributes Tables"> for details).
If a relative path is supplied, then it's anchored at <tt>/etc/brltty</>
(see the <ref id="build-data-directory" name="--with-data-directory">
and the <ref id="build-execute-root" name="--with-execute-root">
build options for more details).
The <tt/.atb/ extension is optional.
See the <ref id="configure-attributes-table" name="attributes-table">
configuration file directive for the default run-time setting.
This setting can be changed with the
<ref id="preference-attributes-table" name="Attributes Table"> preference.
<tag><tt/-b/<em/driver/<tt/,/...|<tt/auto/ <tt/--braille-driver=/<em/driver/<tt/,/...|<tt/auto/<label id="options-braille-driver"></tag>
Specify the braille display driver
(see section <ref id="operand-driver" name="Driver Specification">).
See the <ref id="configure-braille-driver" name="braille-driver">
configuration file directive for the default run-time setting.
<tag><tt/-c/<em/file/ <tt/--contraction-table=/<em/file/<label id="options-contraction-table"></tag>
Specify the contraction table
(see section <ref id="table-contraction" name="Contraction Tables"> for details).
If a relative path is supplied, then it's anchored at <tt>/etc/brltty</>
(see the <ref id="build-data-directory" name="--with-data-directory">
and the <ref id="build-execute-root" name="--with-execute-root">
build options for more details).
The <tt/.ctb/ extension is optional.
The contraction table is used when the 6-dot braille feature is activated
(see the <ref id="command-SIXDOTS" name="SIXDOTS"> command
and the <ref id="preference-text-style" name="Text Style"> preference).
See the <ref id="configure-contraction-table" name="contraction-table">
configureation file directive for the default run-time setting.
This setting can be changed with the
<ref id="preference-contraction-table" name="Contraction Table"> preference.
This option isn't available if the
<ref id="build-contracted-braille" name="--disable-contracted-braille"> build option was specified.
<tag><tt/-d/<em/device/<tt/,/... <tt/--braille-device=/<em/device/<tt/,/...<label id="options-braille-device"></tag>
Specify the device to which the braille display is connected
(see section <ref id="operand-braille-device" name="Braille Device Specification">).
See the <ref id="configure-braille-device" name="braille-device">
configuration file directive for the default run-time setting.
<tag><tt/-e/ <tt/--standard-error/<label id="options-standard-error"></tag>
Write diagnostic messages to standard error.
The default is to record them via <tt/syslog/.
<tag><tt/-f/<em/file/ <tt/--configuration-file=/<em/file/<label id="options-configuration-file"></tag>
Specify the location of the <ref id="configure" name="configuration file">
which is to be used for the establishing of default run-time settings.
<tag><tt/-h/ <tt/--help/<label id="options-help"></tag>
Display a summary of the command line options accepted by BRLTTY,
and then exit.
<tag><tt/-i/<em/name/ <tt/--speech-input=/<em/name/<label id="options-speech-input"></tag>
Specify the name of the file system object
(FIFO, named pipe, named socket, etc)
which can be used by other applications
for text-to-speech conversion via BRLTTY's speech driver.
If not specified, the file system object is not created.
See the <ref id="configure-speech-input" name="speech-input">
configuration file directive for the default run-time setting.
This option isn't available if the
<ref id="build-speech-support" name="--disable-speech-support"> build option was specified.
<tag><tt/-k/<em/file/ <tt/--key-table=/<em/file/<label id="options-key-table"></tag>
Specify the key table
(see section <ref id="table-key" name="Key Tables"> for details).
If a relative path is supplied, then it's anchored at <tt>/etc/brltty</>
(see the <ref id="build-data-directory" name="--with-data-directory">
and the <ref id="build-execute-root" name="--with-execute-root">
build options for more details).
The <tt/.ktb/ extension is optional.
See the <ref id="configure-key-table" name="key-table">
configureation file directive for the default run-time setting.
This setting can be changed with the
<ref id="preference-key-table" name="Key Table"> preference.
<tag><tt/-l/<em/level/ <tt/--log-level=/<em/level/<label id="options-log-level"></tag>
Specify the severity threshold for diagnostic message generation.
The following levels are recognized.
<descrip>
<tag/0/emergency
<tag/1/alert
<tag/2/critical
<tag/3/error
<tag/4/warning
<tag/5/notice
<tag/6/information
<tag/7/debug
</descrip>
Either the number or the name may be supplied,
and the name may be abbreviated.
If not specified,
then <tt/information/ is assumed
(see the <ref id="options-quiet" name="-q"> option for more details).
<tag><tt/-m/<em/device/ <tt/--midi-device=/<em/device/<label id="options-midi-device"></tag>
Specify the device to use for the Musical Instrument Digital Interface
(see section <ref id="operand-midi-device" name="MIDI Device Specification">).
See the <ref id="configure-midi-device" name="midi-device">
configuration file directive for the default run-time setting.
This option isn't available if the
<ref id="build-midi-support" name="--disable-midi-support"> build option was specified.
<tag><tt/-n/ <tt/--no-daemon/<label id="options-no-daemon"></tag>
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.
<tag><tt/-p/<em/device/ <tt/--pcm-device=/<em/device/<label id="options-pcm-device"></tag>
Specify the device to use for digital audio
(see section <ref id="operand-pcm-device" name="PCM Device Specification">).
See the <ref id="configure-pcm-device" name="pcm-device">
configuration file directive for the default run-time setting.
This option isn't available if the
<ref id="build-pcm-support" name="--disable-pcm-support"> build option was specified.
<tag><tt/-q/ <tt/--quiet/<label id="options-quiet"></tag>
Log less information.
This option changes the default log level
(see the <ref id="options-log-level" name="-l"> option)
to <tt/notice/ if
either the <ref id="options-verify" name="-v">
or the <ref id="options-version" name="-V">
option is specified, and to <tt/warning/ otherwise.
<tag><tt/-r/ <tt/--release-device/<label id="options-release-device"></tag>
Release the device to which the braille display is connected
when the current screen or window can't be read.
See the <ref id="configure-release-device" name="release-device">
configuration file directive for the default run-time setting.
<tag><tt/-s/<em/driver/<tt/,/...|<tt/auto/ <tt/--speech-driver=/<em/driver/<tt/,/...|<tt/auto/<label id="options-speech-driver"></tag>
Specify the speech synthesizer driver
(see section <ref id="operand-driver" name="Driver Specification">).
See the <ref id="configure-speech-driver" name="speech-driver">
configuration file directive for the default run-time setting.
This option isn't available if the
<ref id="build-speech-support" name="--disable-speech-support"> build option was specified.
<tag><tt/-t/<em/file/ <tt/--text-table=/<em/file/<label id="options-text-table"></tag>
Specify the text table
(see section <ref id="table-text" name="Text Tables"> for details).
If a relative path is supplied, then it's anchored at <tt>/etc/brltty</>
(see the <ref id="build-data-directory" name="--with-data-directory">
and the <ref id="build-execute-root" name="--with-execute-root">
build options for more details).
The <tt/.ttb/ extension is optional.
See the <ref id="configure-text-table" name="text-table">
configureation file directive for the default run-time setting.
This setting can be changed with the
<ref id="preference-text-table" name="Text Table"> preference.
<tag><tt/-v/ <tt/--verify/<label id="options-verify"></tag>
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 <ref id="options-quiet" name="-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 <ref id="options-braille-driver" name="-b"> command line option)
and/or more than one braille device
(see the <ref id="options-braille-device" name="-d"> command line option)
has been specified then braille display autodetection is performed.
If more than one speech driver
(see the <ref id="options-speech-driver" name="-s"> command line option)
has been specified then speech synthesizer autodetection is performed.
<tag><tt/-x/<em/driver/ <tt/--screen-driver=/<em/driver/<label id="options-screen-driver"></tag>
Specify the screen driver
(see section <ref id="screen" name="Supported Screen Drivers">).
See the <ref id="configure-screen-driver" name="screen-driver">
configuration file directive for the default run-time setting.
<tag><tt/-A/<em/name/<tt/=/<em/value/<tt/,/... <tt/--api-parameters=/<em/name/<tt/=/<em/value/<tt/,/...<label id="options-api-parameters"></tag>
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 <bf/BrlAPI/ reference manual.
See the <ref id="configure-api-parameters" name="api-parameters">
configuration file directive for the default run-time settings.
<tag><tt/-B/[<em/driver/<tt/:/]<em/name/<tt/=/<em/value/<tt/,/... <tt/--braille-parameters=/[<em/driver/<tt/:/]<em/name/<tt/=/<em/value/<tt/,/...<label id="options-braille-parameters"></tag>
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 <ref id="drivers" name="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 <ref id="configure-braille-parameters" name="braille-parameters">
configuration file directive for the default run-time settings.
<tag><tt/-E/ <tt/--environment-variables/<label id="options-environment-variables"></tag>
Recognize environment variables when determining
the default settings for unspecified command line options
(see section <ref id="options" name="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:
<itemize>
<item>All letters are in upper case.
<item>Underscores (<tt/_/) are used instead of minus signs (<tt/-/).
<item>The prefix <tt/BRLTTY_/ is added.
</itemize>
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:
<descrip>
<tag><tt/BRLTTY_API_PARAMETERS/</tag>
Parameters for the Application Programming Interface
(see the <ref id="options-api-parameters" name="-A"> command line option).
<tag><tt/BRLTTY_ATTRIBUTES_TABLE/</tag>
The attributes table
(see the <ref id="options-attributes-table" name="-a"> command line option).
<tag><tt/BRLTTY_BRAILLE_DEVICE/</tag>
The braille display device
(see the <ref id="options-braille-device" name="-d"> command line option).
<tag><tt/BRLTTY_BRAILLE_DRIVER/</tag>
The braille display driver
(see the <ref id="options-braille-driver" name="-b"> command line option).
<tag><tt/BRLTTY_BRAILLE_PARAMETERS/</tag>
Parameters for the braille display driver
(see the <ref id="options-braille-parameters" name="-B"> command line option).
<tag><tt/BRLTTY_CONFIGURATION_FILE/</tag>
The configuration file
(see the <ref id="options-configuration-file" name="-f"> command line option).
<tag><tt/BRLTTY_CONTRACTION_TABLE/</tag>
The contraction table
(see the <ref id="options-contraction-table" name="-c"> command line option).
<tag><tt/BRLTTY_KEY_TABLE/</tag>
The key table
(see the <ref id="options-key-table" name="-k"> command line option).
<tag><tt/BRLTTY_KEYBOARD_PROPERTIES/</tag>
The keyboard properties
(see the <ref id="options-keyboard-properties" name="-K"> command line option).
<tag><tt/BRLTTY_MIDI_DEVICE/</tag>
The Musical Instrument Digital Interface device
(see the <ref id="options-midi-device" name="-m"> command line option).
<tag><tt/BRLTTY_PCM_DEVICE/</tag>
The digital audio device
(see the <ref id="options-pcm-device" name="-p"> command line option).
<tag><tt/BRLTTY_PREFERENCES_FILE/</tag>
The location of the file which is to be used
for the saving and loading of user preferences
(see the <ref id="options-preferences-file" name="-F"> command line option).
<tag><tt/BRLTTY_RELEASE_DEVICE/</tag>
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 <ref id="options-release-device" name="-r"> command line option).
<tag><tt/BRLTTY_SCREEN_PARAMETERS/</tag>
Parameters for the screen driver
(see the <ref id="options-screen-parameters" name="-X"> command line option).
<tag><tt/BRLTTY_SPEECH_DRIVER/</tag>
The speech synthesizer driver
(see the <ref id="options-speech-driver" name="-s"> command line option).
<tag><tt/BRLTTY_SPEECH_INPUT/</tag>
The name of the file system object
which can be used by other applications
for text-to-speech conversion via BRLTTY's speech driver
(see the <ref id="options-speech-input" name="-i"> command line option).
<tag><tt/BRLTTY_SPEECH_PARAMETERS/</tag>
Parameters for the speech synthesizer driver
(see the <ref id="options-speech-parameters" name="-S"> command line option).
<tag><tt/BRLTTY_TEXT_TABLE/</tag>
The text table
(see the <ref id="options-text-table" name="-t"> command line option).
</descrip>
<tag><tt/-F/<em/file/ <tt/--preferences-file=/<em/file/<label id="options-preferences-file"></tag>
Specify the location of the file which is to be used
for the saving and loading of user preferences.
If a relative path is supplied, then it's anchored at <tt>/var/lib/brltty</>.
See the <ref id="configure-preferences-file" name="preferences-file">
configuration file directive for the default run-time setting.
<tag><tt/-I/ <tt/--install-service/<label id="options-install-service"></tag>
Install BRLTTY as the BrlAPI service.
This means that:
<itemize>
<item>BRLTTY will be automatically started when the system is booted.
<item>Applications can know that a BrlAPI server is running.
</itemize>
This option is only supported on the Windows platform.
<tag><tt/-K/<em/name/<tt/=/<em/value/<tt/,/... <tt/--keyboard-properties=/<em/name/<tt/=/<em/value/<tt/,/...<label id="options-keyboard-properties"></tag>
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 <ref id="keyboard-properties" name="Keyboard Properties">
for a list of the properties which may be specified.
See the <ref id="configure-keyboard-properties" name="keyboard-properties">
configuration file directive for the default run-time settings.
<tag><tt/-M/<em/csecs/ <tt/--message-delay=/<em/csecs/<label id="options-message-delay"></tag>
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 <tt/400/ (4 seconds) is assumed.
<tag><tt/-N/ <tt/--no-api/<label id="options-no-api"></tag>
Disable the application programming interface.
<tag><tt/-P/<em/file/ <tt/--pid-file=/<em/file/<label id="options-pid-file"></tag>
Specify the file wherein BRLTTY is to write its process identifier (pid).
If not specified, BRLTTY doesn't write its process identifier anywhere.
<tag><tt/-R/ <tt/--remove-service/<label id="options-remove-service"></tag>
Remove the BrlAPI service.
This means that:
<itemize>
<item>BRLTTY will not be automatically started when the system is booted.
<item>Applications can know that no BrlAPI server is running.
</itemize>
This option is only supported on the Windows platform.
<tag><tt/-S/[<em/driver/<tt/:/]<em/name/<tt/=/<em/value/<tt/,/... <tt/--speech-parameters=/[<em/driver/<tt/:/]<em/name/<tt/=/<em/value/<tt/,/...<label id="options-speech-parameters"></tag>
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 <ref id="drivers" name="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 <ref id="configure-speech-parameters" name="speech-parameters">
configuration file directive for the default run-time settings.
<tag><tt/-U/<em/csecs/ <tt/--update-interval=/<em/csecs/<label id="options-update-interval"></tag>
Specify the interval (in hundredths of a second)
at which the braille window is updated with new screen content.
If not specified, then <tt/4/ (40 milliseconds) is assumed.
<tag><tt/-V/ <tt/--version/<label id="options-version"></tag>
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 <ref id="options-quiet" name="-q"> option isn't specified,
then also display copyright information.
<tag><tt/-X/[<em/driver/<tt/:/]<em/name/<tt/=/<em/value/<tt/,/... <tt/--screen-parameters=/[<em/driver/<tt/:/]<em/name/<tt/=/<em/value/<tt/,/...<label id="options-screen-parameters"></tag>
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 <ref id="screen" name="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 <ref id="configure-screen-parameters" name="screen-parameters">
configuration file directive for the default run-time settings.
</descrip>
<sect>Feature Descriptions<p>
<sect1>Cursor Routing<label id="routing"><p>
When moving the braille window around the screen
while examining the text, say, in an editor,
you often need to bring the cursor
to a specific character within the braille window.
You'll probably find this to be a rather difficult task for a number of reasons.
One is that you may not know where the cursor is,
and that you may lose your place while trying to find it.
Another is that the cursor may move unrpedictably as the arrow keys are pressed
(some editors, for example, don't allow the cursor to be
more to the right than the end of the line it's on).
Cursor routing provides just such a capability
by knowing where the cursor is,
by simulating the same arrow-key presses which you'd have to enter manually,
and by monitoring the progress of the cursor as it moves.
Some braille displays have a button, known as a routing key, above each cell.
These keys use the <ref id="command-ROUTE" name="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 <tt/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 <tt/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,
<ref id="command-CSRJMP_VERT" name="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 <tt/lynx/)
wherein horizontal cursor motion must never be attempted.
<sect1>Cut and Paste<label id="cut"><p>
This feature enables you to grab some text which is already on the screen
and re-enter it at the current cursor position.
Using it saves time and avoids errors
when a long and/or complicated piece of text needs to be copied,
and even when the same short and simple piece of text needs to be copied many times.
It's particularly useful for things like
long file names,
complicated command lines,
E-mail addresses,
and URLs. Cutting and pasting text involves three simple steps:
<enum>
<item>
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:
<itemize>
<item>
invoke the <ref id="command-CUTBEGIN" name="CUTBEGIN"> command
to start a new cut buffer
<item>
invoke the <ref id="command-CUTAPPEND" name="CUTAPPEND"> command
to append to the existing cut buffer
</itemize>
by pressing the key(s) associated with it
and then pressing the routing key associated with the character.
<item>
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
<itemize>
<item>
invoke the <ref id="command-CUTRECT" name="CUTRECT"> command
to cut a rectangular area
<item>
invoke the <ref id="command-CUTLINE" name="CUTLINE"> command
to cut a linear area
</itemize>
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.
<item>
Insert (paste) the text where it's needed.
Place the cursor over the character where the text is to be pasted,
and invoke the <ref id="command-PASTE" name="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 <tt/vi/'s command mode),
then you'd better be aware of what the characters in the cut buffer will do.
</enum>
The cut buffer is also used by
the <ref id="command-PRSEARCH-NXSEARCH" name="PRSEARCH/NXSEARCH"> commands.
<sect1>Pointer (Mouse) Support via GPM<label id="gpm"><p>
If BRLTTY is configured with the <ref id="build-gpm" name="--enable-gpm"> build option
on a system where the <tt/gpm/ application has been installed,
then it'll interact with the pointer (mouse).
Moving the pointer drags the braille window
(see the <ref id="preference-window-follows-pointer" name="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.
<tt/gpm/ uses reverse video to show where the pointer is.
Underlining of highlighted characters
(see the <ref id="command-ATTRVIS" name="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 <tt/gpm/'s cut-and-paste capability.
Although you should read <tt/gpm/'s own documentation,
here are some notes on how it works.
<itemize>
<item>
Copy the current character to the cut buffer
by single-clicking the left button.
<item>
Copy the current word (space-delimited) to the cut buffer
by double-clicking the left button.
<item>
Copy the current line to the cut buffer
by tripple-clicking the left button.
<item>
Copy a linear region to the cut buffer as follows:
<enum>
<item>
Place the pointer on the first character of the region.
<item>
Press (and hold) the left button.
<item>
Move the pointer to the last character of the region
(all currently selected characters are highlighted).
<item>
Release the left button.
</enum>
<item>
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.
<item>
Append to the cut buffer
by using the right button of a three-button mouse.
</itemize>
<sect1>Alert Tunes<label id="tunes"><p>
BRLTTY alerts you to the occurrence of significant events
by playing short predefined tunes.
This feature can be activated and deactivated with
either the <ref id="command-TUNES" name="TUNES"> command
or the <ref id="preference-alert-tunes" name="Alert Tunes"> preference.
The tunes are played via the internal beeper by default,
but other alternatives can be selected
with the <ref id="preference-tune-device" name="Tune Device"> preference.
Each significant event is associated, from highest to lowest priority,
with one or more of the following:
<descrip>
<tag/a tune/
If a tune has been associated with the event,
if the <ref id="preference-alert-tunes" name="Alert Tunes"> preference
(see also the <ref id="command-TUNES" name="TUNES"> command)
is active,
and if the selected tune device
(see the <ref id="preference-tune-device" name="Tune Device"> preference)
can be opened,
then the tune is played.
<tag/a dot pattern/
If a dot pattern has been associated with the event,
and if the <ref id="preference-alert-dots" name="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.
<tag/a message/
If a message has been associated with the event,
and if the <ref id="preference-alert-messages" name="Alert Messages"> preference is active,
then it is displayed for a few seconds
(see the <ref id="options-message-delay" name="-M"> command line option).
</descrip>
These events include:
<itemize>
<item>
When the braille display driver starts or stops.
<item>
When a lengthy command completes.
<item>
When a command cannot be executed.
<item>
When a mark is set.
<item>
When the start or end of the cut block is set.
<item>
When a feature is activated or deactivated.
<item>
When cursor tracking is turned on or off.
<item>
When the screen image is frozen or unfrozen.
<item>
When the braille window wraps
either down to the beginning of the next line
or up to the end of the previous line.
<item>
When identical lines are skipped.
<item>
When a requested motion cannot be performed.
<item>
When cursor routing starts, finishes, or fails.
</itemize>
<sect1>Preferences Settings<label id="preferences"><p>
When BRLTTY starts, it loads a file which contains your preferences settings.
The file doesn't need to exist,
and is created the first time the settings are saved
with the <ref id="command-PREFSAVE" name="PREFSAVE"> command.
The most recently saved settings can be restored at any time
with the <ref id="command-PREFLOAD" name="PREFLOAD"> command.
The name for this file is <tt>/etc/brltty-</tt><em/driver/<tt/.prefs/.
where <em/driver/ is the two-letter <ref id="drivers" name="driver identification code">.
<sect2>The Preferences Menu<label id="preferences-menu"><p>
The preferences settings are saved as binary data
which, therefore, can't be edited by hand.
BRLTTY, however, has a simple menu from which you can easily change them.
The meny is activated by the <ref id="command-PREFMENU" name="PREFMENU"> command.
The braille display briefly
(see the <ref id="options-message-delay" name="-M"> command line option)
shows the menu title,
and then presents the current item and its current setting.
<Sect3>Navigating the Menu<p>
See <ref id="menu" name="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.
<descrip>
<tag><tt/TOP//<tt/BOT/, <tt/TOP_LEFT//<tt/BOT_LEFT/, <tt/PAGE_UP//<tt/PAGE_DOWN/</tag>
Go to the first/last item in the menu
(same as <ref id="command-MENU_FIRST_ITEM-MENU_LAST_ITEM" name="MENU_FIRST_ITEM/MENU_LAST_ITEM">).
<tag><tt/LNUP//<tt/LNDN/, <tt/PRDIFLN//<tt/NXDIFLN/, <tt/CURSOR_UP//<tt/CURSOR_DOWN/</tag>
Go to the previous/next item in the menu
(same as <ref id="command-MENU_PREV_ITEM-MENU_NEXT_ITEM" name="MENU_PREV_ITEM/MENU_NEXT_ITEM">).
<tag><tt/WINUP//<tt/WINDN/, <tt/CHRLT//<tt/CHRRT/, <tt/CURSOR_LEFT//<tt/CURSOR_RIGHT/, <tt/BACK//<tt/HOME/</tag>
Decrement/increment the current menu item's setting
(same as <ref id="command-MENU_PREV_SETTING-MENU_NEXT_SETTING" name="MENU_PREV_SETTING/MENU_NEXT_SETTING">).
</descrip>
Notes:
<itemize>
<item>
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.
<item>
Use the <tt/PREFLOAD/ command to undo all of the changes
which were made since entering the menu.
<item>
Use the <tt/PREFMENU/ command (again) to leave the new settings in effect,
exit the menu, and resume normal operation.
If the <sq/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.
</itemize>
<sect3>The Menu Items<p>
<descrip>
<tag>Save on Exit<label id="preference-save-on-exit"></tag>
When exiting the preferences menu:
<descrip>
<tag/No/
Don't automatically save the preferences settings.
<tag/Yes/
Automatically save the preferences settings.
</descrip>
The initial setting is <tt/No/.
<tag>Text Style<label id="preference-text-style"></tag>
When displaying screen content
(see the <ref id="command-DISPMD" name="DISPMD"> command),
show characters:
<descrip>
<tag/8-dot/
With all eight dots.
<tag/6-dot/
With only dots 1 through 6.
If a contraction table has been selected
(see the <ref id="options-contraction-table" name="-c"> command line option
and the <ref id="configure-contraction-table" name="contraction-table"> configuration file directive),
then it is used.
</descrip>
This setting can also be changed with the
<ref id="command-SIXDOTS" name="SIXDOTS"> command.
<tag>Skip Identical Lines<label id="preference-skip-identical-lines"></tag>
When moving either up or down exactly one line with
the <ref id="command-LNUP-LNDN" name="LNUP/LNDN"> commands,
as well as the line wrapping feature of
the <ref id="command-FWINLT-FWINRT" name="FWINLT/FWINRT">
and <ref id="command-FWINLTSKIP-FWINRTSKIP" name="FWINLTSKIP/FWINRTSKIP"> commands:
<descrip>
<tag/No/
Don't skip past lines which have the same content as the current line.
<tag/Yes/
Skip past lines which have the same content as the current line.
</descrip>
This setting can also be changed with the
<ref id="command-SKPIDLNS" name="SKPIDLNS"> command.
<tag>Skip Blank Windows<label id="preference-skip-blank-windows"></tag>
When moving either left or right with
the <ref id="command-FWINLT-FWINRT" name="FWINLT/FWINRT"> commands:
<descrip>
<tag/No/
Don't skip past blank windows.
<tag/Yes/
Skip past blank windows.
</descrip>
This setting can also be changed with the
<ref id="command-SKPBLNKWINS" name="SKPBLNKWINS"> command.
<tag>Which Blank Windows<label id="preference-which-blank-windows"></tag>
If blank windows are to be skipped:
<descrip>
<tag/All/
Skip all of them.
<tag/End of Line/
Only skip those which are at the end (on the right side) of a line.
<tag/Rest of Line/
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.
</descrip>
<tag>Sliding Window<label id="preference-sliding-window"></tag>
If the cursor is being tracked
(see the <ref id="command-CSRTRK" name="CSRTRK"> command),
and the cursor moves too close to (or beyond)
either end of the braille window:
<descrip>
<tag/No/
Horizontally reposition the window such that its left end
is a multiple of its width from the left edge of the screen.
<tag/Yes/
Horizontally reposition the window such that the cursor,
while remaining on that side of the window, is nearer the centre.
</descrip>
This setting can also be changed with the
<ref id="command-SLIDEWIN" name="SLIDEWIN"> command.
<tag>Eager Sliding Window<label id="preference-eager-sliding-window"></tag>
If the braille window is to slide:
<descrip>
<tag/No/
Reposition it whenever the cursor moves beyond either end.
<tag/Yes/
Reposition it whenever the cursor moves too close to either end.
</descrip>
The initial setting is <tt/No/.
<tag>Window Overlap<label id="preference-window-overlap"></tag>
When moving either left or right with
the <ref id="command-FWINLT-FWINRT" name="FWINLT/FWINRT"> commands,
this setting specifies how many characters
horizontally adjacent braille windows should overlap each other by.
The initial setting is <tt/0/.
<tag>Autorepeat<label id="preference-autorepeat"></tag>
While the key (combination) for a command remains pressed:
<descrip>
<tag/No/
Don't automatically repeat the command.
<tag/Yes/
Automatically repeat the command at a regular interval after an initial delay.
</descrip>
The following commands are eligible for autorepeating:
<itemize>
<item>
The <ref id="command-LNUP-LNDN" name="LNUP/LNDN"> commands.
<item>
The <ref id="command-PRDIFLN-NXDIFLN" name="PRDIFLN/NXDIFLN"> commands.
<item>
The <ref id="command-CHRLT-CHRRT" name="CHRLT/CHRRT"> commands.
<item>
Braille window panning operations
(see the <ref id="preference-autorepeat-panning" name="Autorepeat Panning"> preference).
<item>
The Page-Up and Page-Down operations.
<item>
The Cursor-Up and Cursor-Down operations.
<item>
The Cursor-Left and Cursor-Right operations.
<item>
The Backspace and Delete operations.
<item>
Character entry.
</itemize>
Only some drivers support this functionality,
the primary limitation 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
<ref id="command-AUTOREPEAT" name="AUTOREPEAT"> command.
The initial setting is <tt/Yes/.
<tag>Autorepeat Panning<label id="preference-autorepeat-panning"></tag>
When the <ref id="preference-autorepeat" name="Autorepeat"> preference is enabled:
<descrip>
<tag/No/
Don't autorepeat braille window panning operations.
<tag/Yes/
Autorepeat braille window panning operations.
</descrip>
This preference affects the <ref id="command-FWINLT-FWINRT" name="FWINLT/FWINRT"> commands.
The initial setting is <tt/No/.
<tag>Autorepeat Delay<label id="preference-autorepeat-delay"></tag>
When a character is to be autorepeated,
this setting specifies the amount of time
(see the note on <ref id="time-settings" name="time settings"> below)
which must pass before autorepeating begins.
The initial setting is <tt/50/.
<tag>Autorepeat Interval<label id="preference-autorepeat-interval"></tag>
When a character is being autorepeated,
this setting specifies the amount of time
(see the note on <ref id="time-settings" name="time settings"> below)
between each reexecution.
The initial setting is <tt/10/.
<tag>Show Cursor<label id="preference-show-cursor"></tag>
When displaying screen content
(see the <ref id="command-DISPMD" name="DISPMD"> command):
<descrip>
<tag/No/
Don't show the cursor.
<tag/Yes/
Show the cursor.
</descrip>
This setting can also be changed with the
<ref id="command-CSRVIS" name="CSRVIS"> command.
The initial setting is <tt/Yes/.
<tag>Cursor Style<label id="preference-cursor-style"></tag>
When showing the cursor, represent it:
<descrip>
<tag/Underline/
With dots 7 and 8.
<tag/Block/
With all eight dots.
</descrip>
This setting can also be changed with the
<ref id="command-CSRSIZE" name="CSRSIZE"> command.
<tag>Blinking Cursor<label id="preference-blinking-cursor"></tag>
When the cursor is to be shown:
<descrip>
<tag/No/
Leave it visible all the time.
<tag/Yes/
Make it alternately visible and invisible
according to a predefined interval.
</descrip>
This setting can also be changed with the
<ref id="command-CSRBLINK" name="CSRBLINK"> command.
<tag>Cursor Visible Time<label id="preference-cursor-visible-time"></tag>
When the cursor is to be blinked, this setting specifies the length of time
(see the note on <ref id="time-settings" name="time settings"> below)
during each cycle that it is to be visible.
The initial setting is <tt/40/.
<tag>Cursor Invisible Time<label id="preference-cursor-invisible-time"></tag>
When the cursor is to be blinked, this setting specifies the length of time
(see the note on <ref id="time-settings" name="time settings"> below)
during each cycle that it is to be invisible.
The initial setting is <tt/40/.
<tag>Show Attributes<label id="preference-show-attributes"></tag>
When displaying screen content
(see the <ref id="command-DISPMD" name="DISPMD"> command):
<descrip>
<tag/No/
Don't underline highlighted characters.
<tag/Yes/
Underline highlighted characters.
</descrip>
This setting can also be changed with the
<ref id="command-ATTRVIS" name="ATTRVIS"> command.
<tag>Blinking Attributes<label id="preference-blinking-attributes"></tag>
When highlighted characters are to be underlined:
<descrip>
<tag/No/
Leave the indicator visible all the time.
<tag/Yes/
Make the indicator alternately visible and invisible
according to a predefined interval.
</descrip>
This setting can also be changed with the
<ref id="command-ATTRBLINK" name="ATTRBLINK"> command.
<tag>Attributes Visible Time<label id="preference-attributes-visible-time"></tag>
When the highlighted character underline is to be blinked,
this setting specifies the length of time
(see the note on <ref id="time-settings" name="time settings"> below)
during each cycle that it is to be visible.
The initial setting is <tt/20/.
<tag>Attributes Invisible Time<label id="preference-attributes-invisible-time"></tag>
When the highlighted character underline is to be blinked,
this setting specifies the length of time
(see the note on <ref id="time-settings" name="time settings"> below)
during each cycle that it is to be invisible.
The initial setting is <tt/60/.
<tag>Blinking Capitals<label id="preference-blinking-capitals"></tag>
When displaying screen content
(see the <ref id="command-DISPMD" name="DISPMD"> command):
<descrip>
<tag/No/
Leave capital letters visible all the time.
<tag/Yes/
Make capital letters alternately visible and invisible
according to a predefined interval.
</descrip>
This setting can also be changed with the
<ref id="command-CAPBLINK" name="CAPBLINK"> command.
<tag>Capitals Visible Time<label id="preference-capitals-visible-time"></tag>
When capital letters are to be blinked,
this setting specifies the length of time
(see the note on <ref id="time-settings" name="time settings"> below)
during each cycle that they're to be visible.
The initial setting is <tt/60/.
<tag>Capitals Invisible Time<label id="preference-capitals-invisible-time"></tag>
When capital letters are to be blinked,
this setting specifies the length of time
(see the note on <ref id="time-settings" name="time settings"> below)
during each cycle that they're to be invisible.
The initial setting is <tt/20/.
<tag>Braille Firmness<label id="preference-braille-firmness"></tag>
Adjust the firmness (or stiffness) of the braille dots.
It can be set to:
<itemize>
<item>Maximum
<item>High
<item>Medium
<item>Low
<item>Minimum
</itemize>
This preference is only available if a driver which supports it is being used.
The initial setting is <tt/Medium/.
<tag>Braille Sensitivity<label id="preference-braille-sensitivity"></tag>
Adjust the sensitivity of the braille dots to touch.
It can be set to:
<itemize>
<item>Maximum
<item>High
<item>Medium
<item>Low
<item>Minimum
</itemize>
This preference is only available if a driver which supports it is being used.
The initial setting is <tt/Medium/.
<tag>Window Follows Pointer<label id="preference-window-follows-pointer"></tag>
When moving the pointer device (mouse):
<descrip>
<tag/No/
Don't drag the braille window.
<tag/Yes/
Drag the braille window.
</descrip>
This preference is only presented if the
<ref id="build-gpm" name="--enable-gpm"> build option was specified.
<tag>Highlight Window<label id="preference-highlight-window"></tag>
When moving the braille window:
<descrip>
<tag/No/
Don't highlight the new screen area.
<tag/Yes/
Highlight the new screen area.
</descrip>
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 <ref id="preference-window-follows-pointer" name="Window Follows Pointer"> preference),
causes the area of the screen corresponding to
the new location of the braille window to be highlighted.
If the <ref id="preference-show-attributes" name="Show Attributes"> preference is enabled
then only the character corresponding to the upper-left corner of the braille window is highlighted.
<tag>Alert Tunes<label id="preference-alert-tunes"></tag>
Whenever a significant event with an associated tune occurs
(see <ref id="tunes" name="Alert Tunes">):
<descrip>
<tag/No/
Don't play the tune.
<tag/Yes/
Play the tune.
</descrip>
This setting can also be changed with the
<ref id="command-TUNES" name="TUNES"> command.
The initial setting is <tt/Yes/.
<tag>Tune Device<label id="preference-tune-device"></tag>
Play alert tunes via:
<descrip>
<tag/Beeper/
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
<ref id="build-beeper-support" name="--disable-beeper-support"> build option was specified.
<tag/PCM/
The digital audio interface on the sound card.
This setting is supported
on Linux (via <tt>/dev/dsp</>),
on Solaris (via <tt>/dev/audio</>),
on OpenBSD (via <tt>/dev/audio0</>),
on FreeBSD (via <tt>/dev/dsp</>),
and on NetBSD (via <tt>/dev/audio0</>).
It doesn't work when this device is already being used
by another application.
This device isn't available if the
<ref id="build-pcm-support" name="--disable-pcm-support"> build option was specified.
<tag/MIDI/
The Musical Instrument Digital Interface on the sound card
This setting is supported
on Linux (via <tt>/dev/sequencer</>).
It doesn't work when this device is already being used
by another application.
This device isn't available if the
<ref id="build-midi-support" name="--disable-midi-support"> build option was specified.
<tag/FM/
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
<ref id="build-fm-support" name="--disable-fm-support"> build option was specified.
</descrip>
The initial setting is <tt/Beeper/ on those platforms which support it,
and <tt/PCM/ on those platforms which don't.
<tag>PCM Volume<label id="preference-pcm-volume"></tag>
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 <tt/70/.
<tag>MIDI Volume<label id="preference-midi-volume"></tag>
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 <tt/70/.
<tag>MIDI Instrument<label id="preference-midi-instrument"></tag>
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 <ref id="midi" name="MIDI Instrument Table">).
The initial setting is <tt/Acoustic Grand Piano/.
<tag>FM Volume<label id="preference-fm-volume"></tag>
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 <tt/70/.
<tag>Alert Dots<label id="preference-alert-dots"></tag>
Whenever a significant event with an associated dot pattern occurs
(see <ref id="tunes" name="Alert Tunes">):
<descrip>
<tag/No/
Don't display the dot pattern.
<tag/Yes/
Briefly display the dot pattern.
</descrip>
If alert tunes are to be played
(see the <ref id="command-TUNES" name="TUNES"> command
and the <ref id="preference-alert-tunes" name="Alert Tunes"> preference),
if a tune has been associated with the event,
and if the selected tune device can be opened,
then, regardless of the setting of this preference, the dot pattern isn't displayed.
<tag>Alert Messages<label id="preference-alert-messages"></tag>
Whenever a significant event with an associated message occurs
(see <ref id="tunes" name="Alert Tunes">):
<descrip>
<tag/No/
Don't display the message.
<tag/Yes/
Display the message.
</descrip>
If alert tunes are to be played
(see the <ref id="command-TUNES" name="TUNES"> command
and the <ref id="preference-alert-tunes" name="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 <ref id="preference-alert-dots" name="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.
<tag>Say-Line Mode<label id="preference-sayline-mode"></tag>
When using the <ref id="command-SAY_LINE" name="SAY_LINE"> command:
<descrip>
<tag/Immediate/
Discard pending speech.
<tag/Enqueue/
Don't discard pending speech.
</descrip>
The initial setting is <tt/Immediate/.
<tag>Autospeak<label id="preference-autospeak"></tag>
<descrip>
<tag/No/
Only speak when explicitly requested to do so.
<tag/Yes/
Automatically speak:
<itemize>
<item>the new line when the braille window is moved vertically.
<item>characters which are entered or deleted.
<item>the character to which the cursor is moved.
</itemize>
</descrip>
This setting can also be changed with the
<ref id="command-AUTOSPEAK" name="AUTOSPEAK"> command.
The initial setting is <tt/No/.
<tag>Speech Rate<label id="preference-speech-rate"></tag>
Adjust the speech rate
(<tt/0/ is the slowest, <tt/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 <ref id="command-SAY_SLOWER-SAY_FASTER" name="SAY_SLOWER/SAY_FASTER"> commands.
The initial setting is <tt/10/.
<tag>Speech Volume<label id="preference-speech-volume"></tag>
Adjust the speech volume
(<tt/0/ is the softest, <tt/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 <ref id="command-SAY_SOFTER-SAY_LOUDER" name="SAY_SOFTER/SAY_LOUDER"> commands.
The initial setting is <tt/10/.
<tag>Speech Pitch<label id="preference-speech-pitch"></tag>
Adjust the speech pitch
(<tt/0/ is the lowest, <tt/20/ is the highest).
This preference is only available if a driver which supports it is being used.
The initial setting is <tt/10/.
<tag>Speech Punctuation<label id="preference-speech-punctuation"></tag>
Adjust the amount of punctuation which is spoken.
It can be set to:
<itemize>
<item>None
<item>Some
<item>All
</itemize>
This preference is only available if a driver which supports it is being used.
The initial setting is <tt/Some/.
<tag>Status Style<label id="preference-status-style"></tag>
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.
<descrip>
<tag/None/
Don't use the status cells.
This setting is always safe, but it's also quite useless.
<tag/Alva/
The status cells contain:
<descrip>
<tag/1/
The location of the cursor (see below).
<tag/2/
The location of the top-left corner of the braille window (see below).
<tag/3/
A letter indicating BRLTTY's state.
In order of precedence:
<descrip>
<tag/a/
Screen attributes are being shown
(see the <ref id="command-DISPMD" name="DISPMD"> command).
<tag/f/
The screen image is frozen
(see the <ref id="command-FREEZE" name="FREEZE"> command).
<tag/f/
The cursor is being tracked
(see the <ref id="command-CSRTRK" name="CSRTRK"> command).
<tag><em/blank/</tag>
Nothing special.
</descrip>
</descrip>
The locations of the cursor and the braille window
are presented in an interesting way.
Dots 1 through 6 represent the line number with a letter
from <tt/a/ (for 1) through <tt/y/ (for 25).
Dots 7 and 8 (the extra two at the bottom)
represent the horizontal braille window number as follows:
<descrip>
<tag/No Dots/The first (leftmost) window.
<tag/Dot 7/The second window.
<tag/Dot 8/The third window.
<tag/Dots 7 and 8/The fourth window.
</descrip>
In both cases, the indicators wrap:
line 26 is represented by the letter <tt/a/, and the fifth horizontal
braille window is represented by no dots at the bottom.
<tag/Tieman/
The status cells contain:
<descrip>
<tag/1-2/
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).
<tag/3-4/
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).
<tag/5/
Each dot indicates if a feature is turned on as follows:
<descrip>
<tag/Dot 1/
The screen image is frozen
(see the <ref id="command-FREEZE" name="FREEZE"> command).
<tag/Dot 2/
Screen attributes are being displayed
(see the <ref id="command-DISPMD" name="DISPMD"> command).
<tag/Dot 3/
Alert tunes are being played
(see the <ref id="command-TUNES" name="TUNES"> command).
<tag/Dot 4/
The cursor is being shown
(see the <ref id="command-CSRVIS" name="CSRVIS"> command).
<tag/Dot 5/
The cursor is a solid block
(see the <ref id="command-CSRSIZE" name="CSRSIZE"> command).
<tag/Dot 6/
The cursor is blinking
(see the <ref id="command-CSRBLINK" name="CSRBLINK"> command).
<tag/Dot 7/
The cursor is being tracked
(see the <ref id="command-CSRTRK" name="CSRTRK"> command).
<tag/Dot 8/
The braille window will slide
(see the <ref id="command-SLIDEWIN" name="SLIDEWIN"> command).
</descrip>
</descrip>
<tag/PowerBraille 80/
The status cells contain:
<descrip>
<tag/1/
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.
</descrip>
<tag/Generic/
This setting passes a lot of information to the braille driver,
and the driver itself decides how to present it.
<tag/MDV/
The status cells contain:
<descrip>
<tag/1-2/
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.
</descrip>
<tag/Voyager/
The status cells contain:
<descrip>
<tag/1/
The row (counting from 1) corresponding to
the top of the braille window (see below).
<tag/2/
The row (counting from 1) whereon the cursor is (see below).
<tag/3/
If the screen is frozen
(see the <ref id="command-FREEZE" name="FREEZE"> command),
then the letter <tt/F/.
If it isn't, then
the column (counting from 1) wherein the cursor is (see below).
</descrip>
Row and column numbers are shown as two digits within a single cell.
The tens digit is shown in the top half of the cell,
and the units digit is shown in the bottom half of the cell.
</descrip>
The initial setting is braille display driver dependent.
<tag>Text Table<label id="preference-text-table"></tag>
Select the text table.
See section <ref id="table-text" name="Text Tables"> for details.
See the <ref id="options-text-table" name="-t"> command line option for the initial setting.
This preference isn't saved.
<tag>Attributes Table<label id="preference-attributes-table"></tag>
Select the attributes table.
See section <ref id="table-attributes" name="Attributes Tables"> for details.
See the <ref id="options-attributes-table" name="-a"> command line option for the initial setting.
This preference isn't saved.
<tag>Contraction Table<label id="preference-contraction-table"></tag>
Select the contraction table.
See section <ref id="table-contraction" name="Contraction Tables"> for details.
See the <ref id="options-contraction-table" name="-c"> command line option for the initial setting.
This preference isn't saved.
<tag>Key Table<label id="preference-key-table"></tag>
Select the key table.
See section <ref id="table-key" name="Key Tables"> for details.
See the <ref id="options-key-table" name="-k"> command line option for the initial setting.
This preference isn't saved.
</descrip>
Notes:
<itemize>
<item><label id="time-settings">
All time settings are in hundredths of a second.
They are multiples of the braille window update interval
(see the <ref id="options-update-interval" name="-U"> command line option)
within the range 1 through 100.
</itemize>
<sect1>The Status Display<label id="status"><p>
The status display is a summary of BRLTTY's current state
which fits completely within the braille window.
Some braille displays have a set of status cells
which are used to permanently display some of this information as well
(see the documentation for your display's driver).
The data presented by this display isn't static, and may change at any time
in response to screen updates and/or BRLTTY commands.
Use the <ref id="command-INFO" name="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.
<sect2>Displays with 21 Cells or More<p>
Short pneumonics have been used, even though they're rather cryptic,
in order to show the precise column layout.
<tscreen><em/wx/:<em/wy/ <em/cx/:<em/cy/ <em/vt/ <em/tcmfdu/</tscreen>
<descrip>
<tag><em/wx/<tt/:/<em/wy/</tag>
The column and row (counting from 1) on the screen corresponding
to the top-left corner of the braille window.
<tag><em/cx/<tt/:/<em/cy/</tag>
The column and row (counting from 1) on the screen corresponding
to the position of the cursor.
<tag><em/vt/</tag>
The number (counting from 1) of the current virtual terminal.
<tag><em/t/</tag>
The state of the cursor tracking feature
(see the <ref id="command-CSRTRK" name="CSRTRK"> command).
<descrip>
<tag>blank</tag>Cursor tracking is off.
<tag><tt/t/</tag>Cursor tracking is on.
</descrip>
<tag><em/c/</tag>
The state of the cursor visibility features
(see the <ref id="command-CSRVIS" name="CSRVIS">
and <ref id="command-CSRBLINK" name="CSRBLINK"> commands).
<descrip>
<tag>blank</tag>The cursor isn't visible, and won't blink when made visible.
<tag><tt/b/</tag>The cursor isn't visible, and will blink when made visible.
<tag><tt/v/</tag>The cursor is visible, and isn't blinking.
<tag><tt/B/</tag>The cursor is visible, and is blinking.
</descrip>
<tag><em/m/</tag>
The current display mode
(see the <ref id="command-DISPMD" name="DISPMD"> command).
<descrip>
<tag><tt/t/</tag>Screen content (text) is being displayed.
<tag><tt/a/</tag>Screen highlighting (attributes) is being displayed.
</descrip>
<tag><em/f/</tag>
The state of the frozen screen feature
(see the <ref id="command-FREEZE" name="FREEZE"> command).
<descrip>
<tag>blank</tag>The screen isn't frozen.
<tag><tt/f/</tag>The screen is frozen.
</descrip>
<tag><em/d/</tag>
The number of braille dots being used to display each character
(see the <ref id="command-SIXDOTS" name="SIXDOTS"> command).
<descrip>
<tag><tt/8/</tag>All eight dots are being used.
<tag><tt/6/</tag>Only dots 1 through 6 are being used.
</descrip>
<tag><em/u/</tag>
The state of the uppercase (capital letter) display features
(see the <ref id="command-CAPBLINK" name="CAPBLINK"> command).
<descrip>
<tag>blank</tag>Uppercase letters don't blink.
<tag><tt/B/</tag>Uppercase letters blink.
</descrip>
</descrip>
<sect2>Displays with 20 Cells or Less<p>
Short pneumonics have been used, even though they're rather cryptic,
in order to show the precise column layout.
<tscreen><em/xx/<em/yy/<em/s/ <em/vt/ <em/tcmfdu/</tscreen>
<descrip>
<tag><em/xx/</tag>
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).
<tag><em/yy/</tag>
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).
<tag><em/s/</tag>
The settings of some of BRLTTY's features.
A feature is turned on if its corresponding dot is raised.
<descrip>
<tag/Dot 1/
Frozen screen image
(see the <ref id="command-FREEZE" name="FREEZE"> command).
<tag/Dot 2/
Display attributes
(see the <ref id="command-DISPMD" name="DISPMD"> command).
<tag/Dot 3/
Alert tunes
(see the <ref id="command-TUNES" name="TUNES"> command).
<tag/Dot 4/
Visible cursor
(see the <ref id="command-CSRVIS" name="CSRVIS"> command).
<tag/Dot 5/
Block cursor
(see the <ref id="command-CSRSIZE" name="CSRSIZE"> command).
<tag/Dot 6/
Blinking cursor
(see the <ref id="command-CSRBLINK" name="CSRBLINK"> command).
<tag/Dot 7/
Cursor tracking
(see the <ref id="command-CSRTRK" name="CSRTRK"> command).
<tag/Dot 8/
Sliding window
(see the <ref id="command-SLIDEWIN" name="SLIDEWIN"> command).
</descrip>
<tag><em/vt/</tag>
The number (counting from 1) of the current virtual terminal.
<tag><em/t/</tag>
The state of the cursor tracking feature
(see the <ref id="command-CSRTRK" name="CSRTRK"> command).
<descrip>
<tag>blank</tag>Cursor tracking is off.
<tag><tt/t/</tag>Cursor tracking is on.
</descrip>
<tag><em/c/</tag>
The state of the cursor visibility features
(see the <ref id="command-CSRVIS" name="CSRVIS">
and <ref id="command-CSRBLINK" name="CSRBLINK"> commands).
<descrip>
<tag>blank</tag>The cursor isn't visible, and won't blink when made visible.
<tag><tt/b/</tag>The cursor isn't visible, and will blink when made visible.
<tag><tt/v/</tag>The cursor is visible, and isn't blinking.
<tag><tt/B/</tag>The cursor is visible, and is blinking.
</descrip>
<tag><em/m/</tag>
The current display mode
(see the <ref id="command-DISPMD" name="DISPMD"> command).
<descrip>
<tag><tt/t/</tag>Screen content (text) is being displayed.
<tag><tt/a/</tag>Screen highlighting (attributes) is being displayed.
</descrip>
<tag><em/f/</tag>
The state of the frozen screen feature
(see the <ref id="command-FREEZE" name="FREEZE"> command).
<descrip>
<tag>blank</tag>The screen isn't frozen.
<tag><tt/f/</tag>The screen is frozen.
</descrip>
<tag><em/d/</tag>
The number of braille dots being used to display each character
(see the <ref id="command-SIXDOTS" name="SIXDOTS"> command).
<descrip>
<tag><tt/8/</tag>All eight dots are being used.
<tag><tt/6/</tag>Only dots 1 through 6 are being used.
</descrip>
<tag><em/u/</tag>
The state of the uppercase (capital letter) display features
(see the <ref id="command-CAPBLINK" name="CAPBLINK"> command).
<descrip>
<tag>blank</tag>Uppercase letters don't blink.
<tag><tt/B/</tag>Uppercase letters blink.
</descrip>
</descrip>
<sect1>Command Learn Mode<label id="learn"><p>
Command learn mode is an interactive way to learn
what the keys on the braille display do.
It can be accessed
either by the <ref id="command-LEARN" name="LEARN"> command
or via the <ref id="utility-brltest" name="brltest"> utility.
This feature isn't available if the
<ref id="build-learn-mode" name="--disable-learn-mode"> build option was specified.
When this mode is entered,
the message <tt/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 <ref id="command-LEARN" name="LEARN"> command is pressed.
It exits automatically, and the message <tt/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 <ref id="options-message-delay" name="-M"> command line option)
or until any key on the display is pressed.
<sect>Tables<label id="tables"><p>
<sect1>Text Tables<label id="table-text"><p>
Files with names of the form <tt/*.ttb/ are text tables,
and with names of the form <tt/*.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
<ref id="nabcc" name="North American Braille Computer Code">
(NABCC) text table.
In addition to this default,
the following alternatives are provided:
<descrip>
<tag/auto/locale-based autoselection
<tag/ar/Arabic (generic)
<tag/as/Assamese
<tag/awa/Awadhi
<tag/bg/Bulgarian
<tag/bh/Bihari
<tag/bn/Bengali
<tag/bo/Tibetan
<tag/bra/Braj
<tag/brf/for viewing <tt/.brf/ files within an editor or pager
<tag/cs/Czech
<tag/cy/Welsh
<tag/da/Danish
<tag/de/German
<tag/dra/Dravidian
<tag/el/Greek
<tag/en/English
<tag/en_CA/English (Canada)
<tag/en_GB/English (United Kingdom)
<tag/en_US/English (United States)
<tag/en-nabcc/English (North American Braille Computer Code)
<tag/eo/Esperanto
<tag/es/Spanish
<tag/et/Estonian
<tag/fi/Finnish
<tag/fr/French
<tag/fr_CA/French (Canada)
<tag/fr_FR/French (France)
<tag/fr-2007/French (unified)
<tag/fr-cbifs/French (Code Braille Informatique Français Standard)
<tag/ga/Irish
<tag/gd/Gaelic
<tag/gon/Gondi
<tag/gu/Gujarati
<tag/he/Hebrew
<tag/hi/Hindi
<tag/hr/Croatian
<tag/hu/Hungarian
<tag/hy/Armenian
<tag/is/Icelandic
<tag/it/Italian
<tag/kha/Khasi
<tag/kn/Kannada
<tag/kok/Konkani
<tag/kru/Kurukh
<tag/lt/Lituanian
<tag/lv/Latvian
<tag/mg/Malagasy
<tag/mi/Maori
<tag/ml/Malayalam
<tag/mni/Manipuri
<tag/mr/Marathi
<tag/mt/Maltese
<tag/mun/Mundari
<tag/mwr/Marwari
<tag/ne/Nepali
<tag/new/Newari
<tag/nl/Dutch
<tag/nl_BE/Dutch (Belgium)
<tag/nl_NL/Dutch (Netherlands)
<tag/no/Norwegian
<tag/no-generic/Norwegian (with support for other languages)
<tag/no-oub/Norwegian (Offentlig Utvalg for Blindeskrift)
<tag/nwc/Old Newari
<tag/or/Oriya
<tag/pa/Panjabi
<tag/pi/Pali
<tag/pl/Polish
<tag/pt/Portuguese
<tag/ro/Romanian
<tag/ru/Russian
<tag/sa/Sanskrit
<tag/sat/Santali
<tag/sd/Sindhi
<tag/sk/Slovak
<tag/sv/Swedish
<tag/sw/Swahili
<tag/ta/Tamil
<tag/te/Telugu
<tag/tr/Turkish
<tag/vi/Vietnamese
</descrip>
See the <ref id="options-text-table" name="-t"> command line option,
the <ref id="configure-text-table" name="text-table"> configuration file directive,
and the <ref id="build-text-table" name="--with-text-table"> build option
for details regarding how to use an alternate text table.
<sect2>Text Table Format<p>
A text table consists of a sequence of directives, one per line,
which define how each character is to be represented in braille.
<tt/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.
<sect2>Text Table Directives<p>
The following directives are provided:
<descrip>
<tag><tt/char/ <em/character/ <em/dots/ # <em/comment/</tag>
Use the <tt/char/ directive to specify
how a Unicode character is to be represented in braille.
Characters defined with this directive
can also be entered from a braille keyboard.
If several characters have the same braille representation
then only one of them should be defined with the <tt/char/ directive -
the others should be defined with teh <tt/glyph/ directive
(which has the same syntax).
If more than one character with the same braille representation
is defined with the <tt/char/ directive
(which is currently allowed for backward compatibility)
then the first one is selected.
<descrip>
<tag><em/character/</tag>
The Unicode character being defined.
It may be:
<itemize>
<item>
Any single character other than a backslash or a white-space character.
<item>
A backslash-prefixed special character.
These are:
<descrip>
- <tag/\b/The backspace character.
- <tag/\f/The formfeed character.
- <tag/\n/The newline character.
- <tag/\o###/The three-digit octal representation of a character.
- <tag/\r/The carriage return character.
- <tag/\s/The space character.
- <tag/\t/The horizontal tab character.
- <tag/\u####/The four-digit hexadecimal representation of a character.
- <tag/\U########/The eight-digit hexadecimal representation of a character.
- <tag/\v/The vertical tab character.
- <tag/\x##/The two-digit hexadecimal representation of a character.
- <tag/\X##/... (the case of the X and of the digits isn't significant)
- <tag/\#/A literal number sign.
- <tag/\<name>/The Unicode name of a character (use _ for space).
- <tag/\\/A literal backslash.
</descrip>
</itemize>
<tag><em/dots/</tag>
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 <tt/1/-<tt/8/ as defined by the
<ref id="dots" name="Standard Braille Dot Numbering Convention">.
The special dot number <tt/0/ is recognized
when not enclosed within parentheses,
and means no dots;
it may not be used in conjunction with any other dot number.
</descrip>
Examples:
<itemize>
<item><tt/char a 1/
<item><tt/char b (12)/
<item><tt/char c ( 4 1 )/
<item><tt/char \\ 12567/
<item><tt/char \s 0/
<item><tt/char \x20 ()/
<item><tt/char \<LATIN_SMALL_LETTER_D> 145/
</itemize>
<tag><tt/glyph/ <em/character/ <em/dots/ # <em/comment/</tag>
Use the <tt/glyph/ directive to specify
how a Unicode character is to be represented in braille.
Characters defined with this directive are output-only.
They cannot be entered from a braille keyboard.
See the <tt/char/ directive for syntax details and for examples.
<tag><tt/byte/ <em/byte/ <em/dots/ # <em/comment/</tag>
Use the <tt/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 <tt/char/ directive)
so that the text table remains valid
regardless of what the local character set is.
<descrip>
<tag><em/byte/</tag>
The local character being defined.
It may be specified in the same ways
as the <em/character/ operand of the <tt/char/ directive
except that the Unicode-specific forms
(\u, \U, \<)
may not be used.
<tag><em/dots/</tag>
The braille representation of the local character.
It may be specified in the same ways
as the <em/dots/ operand of the <tt/char/ directive.
</descrip>
<tag><tt/include/ <em/file/ # <em/comment/</tag>
Use the <tt/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.
<descrip>
<tag><em/file/</tag>
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.
</descrip>
</descrip>
<sect1>Attributes Tables<label id="table-attributes"><p>
Files with names of the form *.atb are attributes tables,
and with names of the form *.ati are attributes subtables.
They are used when BRLTTY
is displaying screen attributes rather than screen content
(see the <ref id="command-DISPMD" name="DISPMD"> command).
Each of the eight braille dots represents
one of the eight <tt/VGA/ attribute bits.
The following attributes tables are provided:
<descrip>
<tag/attributes/
The lefthand column represents the foreground colours:
<descrip>
<tag/Dot 1/Red
<tag/Dot 2/Green
<tag/Dot 3/Blue
<tag/Dot 7/Bright
</descrip>
The righthand column represents the background colours:
<descrip>
<tag/Dot 4/Red
<tag/Dot 5/Green
<tag/Dot 6/Blue
<tag/Dot 8/Blink
</descrip>
A dot is raised when its corresponding attribute bit is on.
This is the default attributes table
because it's the most intuitive.
One of its problems, though, is that it's difficult to discern
the difference between normal (white on black)
and reverse (black on white) video.
<tag/attrib/
The lefthand column represents the foreground colours:
<descrip>
<tag/Dot 1/Red
<tag/Dot 2/Green
<tag/Dot 3/Blue
<tag/Dot 7/Bright
</descrip>
The righthand column represents the background colours:
<descrip>
<tag/Dot 4/Red
<tag/Dot 5/Green
<tag/Dot 6/Blue
<tag/Dot 8/Blink
</descrip>
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.
</descrip>
See the <ref id="options-attributes-table" name="-a"> command line option,
the <ref id="configure-attributes-table" name="attributes-table"> configuration file directive,
and the <ref id="build-attributes-table" name="--with-attributes-table"> build option
for details regarding how to use an alternate attributes table.
<sect2>Attributes Table Format<p>
An attributes table consists of a sequence of directives, one per line,
which define how combinations of <tt/VGA/ attributes
are to be represented in braille.
<tt/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.
<sect2>Attributes Table Directives<p>
The following directives are provided:
<descrip>
<tag><tt/dot/ <em/dot/ <em/state/ # <em/comment/</tag>
Use the <tt/dot/ directive to specify
what a specific dot represents.
<descrip>
<tag><em/dot/</tag>
The dot being defined.
It is a single digit within the range <tt/1/-<tt/8/ as defined by the
<ref id="dots" name="Standard Braille Dot Numbering Convention">.
<tag><em/state/</tag>
What the dot represents.
It may be:
<descrip>
<tag><tt/=/<em/attribute/</tag>The dot is raised if the named attribute is on.
<tag><tt/˜/<em/attribute/</tag>The dot is raised if the named attribute is off.
</descrip>
The names of the attribute bits are:
<descrip>
<tag/0X01/<tt/fg-blue/
<tag/0X02/<tt/fg-green/
<tag/0X04/<tt/fg-red/
<tag/0X08/<tt/fg-bright/
<tag/0X10/<tt/bg-blue/
<tag/0X20/<tt/bg-green/
<tag/0X40/<tt/bg-red/
<tag/0X80/<tt/blink/
</descrip>
</descrip>
Examples:
<itemize>
<item><tt/dot 1 =fg-red/
<item><tt/dot 2 ˜bg-blue/
</itemize>
<tag><tt/include/ <em/file/ # <em/comment/</tag>
Use the <tt/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.
<descrip>
<tag><em/file/</tag>
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.
</descrip>
</descrip>
<sect1>Contraction Tables<label id="table-contraction"><p>
Files with names of the form <tt/*.ctb/ are contraction tables,
and with names of the form <tt/*.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:
<itemize>
<item>
A contraction table has been selected.
See the <ref id="options-contraction-table" name="-c"> command line option
and the <ref id="configure-contraction-table" name="contraction-table"> configuration file directive
for details.
<item>
The 6-dot braille feature has been activated.
See the <ref id="command-SIXDOTS" name="SIXDOTS"> command
and the <ref id="preference-text-style" name="Text Style"> preference
for details.
</itemize>
This feature isn't available if the
<ref id="build-contracted-braille" name="--disable-contracted-braille"> build option was specified.
The following contraction tables are provided:
<descrip>
<tag/af/Afrikaans (contracted)
<tag/am/Amharic (uncontracted)
<tag/de-basis/German (uncontracted)
<tag/de-kurzschrift/German (contracted - 1998 standard)
<tag/de-vollschrift/German (basic contractions)
<tag/en-ueb-g2/Unified English Braille (grade 2)
<tag/en-us-g2/American English (grade 2)
<tag/es/Spanish (grade 2)
<tag/fr-abrege/French (contracted)
<tag/fr-integral/French (uncontracted)
<tag/ha/Hausa (contracted)
<tag/id/Indonesian (contracted)
<tag/ja/Japanese (uncontracted)
<tag/ko-g1/Korean (grade 1)
<tag/ko-g2/Korean (grade 2)
<tag/ko/Korean (uncontracted)
<tag/mg/Malagasy (contracted)
<tag/mun/Munda (contracted)
<tag/nl/Dutch (contracted)
<tag/ny/Chichewa (contracted)
<tag/ipa/International Phonetic Alphabet
<tag/pt/Portuguese (grade 2)
<tag/si/Sinhalese (uncontracted)
<tag/sw/Swahili (contracted)
<tag/th/Thai (contracted)
<tag/zh-tw/Taiwanese Chinese (uncontracted)
<tag/zh-tw-ucb/Taiwanese Chinese (Unique Chinese Braille)
<tag/zu/Zulu (contracted)
</descrip>
See the <ref id="options-contraction-table" name="-c"> command line option,
and the <ref id="configure-contraction-table" name="contraction-table"> configuration file directive
for details regarding how to use a contraction table.
<sect2>Contraction Table Format<p>
A contraction table consists of a sequence of entries, one per line,
which define how character sequences are to be represented in braille.
<tt/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:
<tscreen><em/directive/ <em/operand/ ... [<em/comment/]</tscreen>
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. <tt/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.
<sect2>Contraction Table Operands<p>
<descrip>
<tag><em/characters/</tag>
The first operand of a character sequence matching directive
is the character sequence to be matched.
Each character within the sequence may be:
<itemize>
<item>
Any single character other than a backslash or a white-space character.
<item>
A backslash-prefixed special character.
These are:
<descrip>
- <tag/\b/The backspace character.
- <tag/\f/The formfeed character.
- <tag/\n/The newline character.
- <tag/\o###/The three-digit octal representation of a character.
- <tag/\r/The carriage return character.
- <tag/\s/The space character.
- <tag/\t/The horizontal tab character.
- <tag/\u####/The four-digit hexadecimal representation of a character.
- <tag/\U########/The eight-digit hexadecimal representation of a character.
- <tag/\v/The vertical tab character.
- <tag/\x##/The two-digit hexadecimal representation of a character.
- <tag/\X##/... (the case of the X and of the digits isn't significant)
- <tag/\#/A literal number sign.
- <tag/\<name>/The Unicode name of a character (use _ for space).
- <tag/\\/A literal backslash.
</descrip>
</itemize>
<tag><em/representation/</tag>
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 <tt/1/-<tt/8/ as defined by the
<ref id="dots" name="Standard Braille Dot Numbering Convention">.
The special dot number <tt/0/,
which may not be used in conjunction with any other dot number,
means no dots.
</descrip>
<sect2>Opcodes<label id="contraction-opcodes"><p>
An opcode is a keyword which tells the translator how to interpret the operands.
The opcodes are grouped here by function.
<sect3>Table Administration<label id="contraction-opcodes-administration"><p>
These opcodes make it easier to write contraction tables.
They have no direct effect on the character translation.
<descrip>
<tag><tt/include/ <em/path/<label id="contraction-opcode-include"></tag>
Include the contents of another file.
Nesting can be to any depth.
Relative paths are anchored at the directory of the including file.
<tag><tt/locale/ <em/locale/<label id="contraction-opcode-locale"></tag>
Define the locale for character interpretation
(lowercase, uppercase, numeric, etc.).
The locale may be specified as:
<descrip>
<tag><em/language/[<tt/_/<em/country/][<tt/./<em/charset/][<tt/@/<em/modifier/]</tag>
The <em/language/ component is required and should be a two-letter <tt/ISO-639/ language code.
The <em/country/ component is optional and should be a two-letter <tt/ISO-3166/ country code.
The <em/charset/ component is optional and should be a character set name, e.g. <tt/ISO-8859-1/.
<tag/C/
7-bit ASCII.
<tag/-/
No locale.
</descrip>
The last locale specification applies to the entire table.
If this opcode isn't used then the <tt/C/ locale is assumed.
</descrip>
<sect3>Special Symbol Definition<label id="contraction-opcodes-symbols"><p>
These opcodes define special symbols which must be
inserted into the braille text in order to clarify it.
<descrip>
<tag><tt/capsign/ <em/dots/<label id="contraction-opcode-capsign"></tag>
The symbol which capitalizes a single letter.
<tag><tt/begcaps/ <em/dots/<label id="contraction-opcode-begcaps"></tag>
The symbol which begins a block of capital letters within a word.
<tag><tt/endcaps/ <em/dots/<label id="contraction-opcode-endcaps"></tag>
The symbol which ends a block of capital letters within a word.
<tag><tt/letsign/ <em/dots/<label id="contraction-opcode-letsign"></tag>
The symbol which marks a letter which isn't part of a word.
<tag><tt/numsign/ <em/dots/<label id="contraction-opcode-numsign"></tag>
The symbol which marks the beginning of a number.
</descrip>
<sect3>Character Translation<label id="contraction-opcodes-translation"><p>
These opcodes define the braille representations for character sequences.
Each of them defines an entry within the contraction table.
These entries may be defined in any order except, as noted below,
when they define alternate representations for the same character sequence.
Each of these opcodes has
a <em/characters/ operand (which must be specified as a <em/string/),
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 <em/dots/ operand
which defines the braille representation for its <em/characters/ operand.
It may also be specified as an equals sign (<tt/=/),
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 <ref id="options-text-table" name="-t"> command line option
and the <ref id="configure-text-table" name="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 <ref id="contraction-opcode-always" name="always">)
within the sequence is to be used.
Some special terms are used within the descriptions of these opcodes.
<descrip>
<tag/word/
A maximal sequence of one or more consecutive letters.
</descrip>
Now, finally, here are the opcode descriptions themselves:
<descrip>
<tag><tt/literal/ <em/characters/<label id="contraction-opcode-literal"></tag>
Translate the entire white-space-bounded containing character sequence into computer braille
(see the <ref id="options-text-table" name="-t"> command line option
and the <ref id="configure-text-table" name="text-table"> configuration file directive).
<tag><tt/replace/ <em/characters/ <em/characters/<label id="contraction-opcode-replace"></tag>
Replace the first set of characters, no matter where they appear, with the second.
The replaced characters aren't reprocessed.
<tag><tt/always/ <em/characters/ <em/dots/<label id="contraction-opcode-always"></tag>
Translate the characters no matter where they appear.
If there's only one character, then, in addition,
define the default representation for that character.
<tag><tt/repeatable/ <em/characters/ <em/dots/<label id="contraction-opcode-repeatable"></tag>
Translate the characters no matter where they appear.
Ignore any consecutive repetitions of the same sequence.
<tag><tt/largesign/ <em/characters/ <em/dots/<label id="contraction-opcode-largesign"></tag>
Translate the characters no matter where they appear.
Remove white-space between consecutive words matched by this opcode.
<tag><tt/lastlargesign/ <em/characters/ <em/dots/<label id="contraction-opcode-lastlargesign"></tag>
Translate the characters no matter where they appear.
Remove preceding white-space if the previous word was matched by the
<ref id="contraction-opcode-largesign" name="largesign"> opcode.
<tag><tt/word/ <em/characters/ <em/dots/<label id="contraction-opcode-word"></tag>
Translate the characters if they're a word.
<tag><tt/joinword/ <em/characters/ <em/dots/<label id="contraction-opcode-joinword"></tag>
Translate the characters if they're a word.
Remove the following white-space if the first character after it is a letter.
<tag><tt/lowword/ <em/characters/ <em/dots/<label id="contraction-opcode-lowword"></tag>
Translate the characters if they're a white-space-bounded word.
<tag><tt/contraction/ <em/characters/<label id="contraction-opcode-contraction"></tag>
Prefix the characters with a letter sign
(see <ref id="contraction-opcode-letsign" name="letsign">)
if they're a word.
<tag><tt/sufword/ <em/characters/ <em/dots/<label id="contraction-opcode-sufword"></tag>
Translate the characters if they're either a word or at the beginning of a word.
<tag><tt/prfword/ <em/characters/ <em/dots/<label id="contraction-opcode-prfword"></tag>
Translate the characters if they're either a word or at the end of a word.
<tag><tt/begword/ <em/characters/ <em/dots/<label id="contraction-opcode-begword"></tag>
Translate the characters if they're at the beginning of a word.
<tag><tt/begmidword/ <em/characters/ <em/dots/<label id="contraction-opcode-begmidword"></tag>
Translate the characters if they're either at the beginning or in the middle of a word.
<tag><tt/midword/ <em/characters/ <em/dots/<label id="contraction-opcode-midword"></tag>
Translate the characters if they're in the middle of a word.
<tag><tt/midendword/ <em/characters/ <em/dots/<label id="contraction-opcode-midendword"></tag>
Translate the characters if they're either in the middle or at the end of a word.
<tag><tt/endword/ <em/characters/ <em/dots/<label id="contraction-opcode-endword"></tag>
Translate the characters if they're at the end of a word.
<tag><tt/prepunc/ <em/characters/ <em/dots/<label id="contraction-opcode-prepunc"></tag>
Translate the characters if they're part of punctuation at the beginning of a word.
<tag><tt/postpunc/ <em/characters/ <em/dots/<label id="contraction-opcode-postpunc"></tag>
Translate the characters if they're part of punctuation at the end of a word.
<tag><tt/begnum/ <em/characters/ <em/dots/<label id="contraction-opcode-begnum"></tag>
Translate the characters if they're at the beginning of a number.
<tag><tt/midnum/ <em/characters/ <em/dots/<label id="contraction-opcode-midnum"></tag>
Translate the characters if they're in the middle of a number.
<tag><tt/endnum/ <em/characters/ <em/dots/<label id="contraction-opcode-endnum"></tag>
Translate the characters if they're at the end of a number.
</descrip>
<sect3>Character Classes<label id="contraction-opcodes-classes"><p>
These opcodes define and use character classes.
A character class associates a set of characters with a name.
The name then refers to any character within the class.
A character may belong to more than one class.
The following character classes are automatically predefined
basdd on the selected locale:
<descrip>
<tag/digit/
Numeric characters.
<tag/letter/
Both uppercase and lowercase alphabetic characters.
Some locales have additional letters which are neither uppercase nor lowercase.
<tag/lowercase/
Lowercase alphabetic characters.
<tag/punctuation/
Printable characters which are neither white-space nor alphanumeric.
<tag/space/
White-space characters.
In the default locale these are:
space, horizontal tab, vertical tab, carriage return, new line, form feed.
<tag/uppercase/
Uppercase alphabetic characters.
</descrip>
The opcodes which define and use character classes are:
<descrip>
<tag><tt/class/ <em/name/ <em/characters/<label id="contraction-opcode-class"></tag>
Define a new character class.
The <em/characters/ operand must be specified as a <em/string/.
A character class may not be used until it's been defined.
<tag><tt/after/ <em/class/ <em/opcode/ ...<label id="contraction-opcode-after"></tag>
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.
<tag><tt/before/ <em/class/ <em/opcode/ ...<label id="contraction-opcode-before"></tag>
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.
</descrip>
<sect1>Key Tables<label id="table-key"><p>
Files with names of the form <tt/*.ktb/ are key tables,
and with names of the form <tt/*.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 <tt/brl-/<em/xx/<tt/-/",
where <em/xx/ is the two-letter
<ref id="drivers" name="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 <tt/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:
<descrip>
<tag/kbd-desktop/bindings for full keyboards
<tag/kbd-keypad/bindings for keypad-based navigation
<tag/kbd-laptop/bindings for keyboards without a keypad
</descrip>
See the <ref id="options-key-table" name="-k"> command line option,
and the <ref id="configure-key-table" name="key-table"> configuration file directive
for details regarding how to select a keyboard key table.
<sect2>Key Table Directives<p>
A key table consists of a sequence of directives, one per line,
which define how keys and key combinations are to be interpreted.
<tt/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 (<tt/#/) sign
then that line is a comment and is ignored.
The precedence for resolving each key press/release event is as follows:
<enum>
<item>
A hotkey press or release defined within the current context.
See the
<ref id="key-table-hotkey" name="hotkey">
directive for details.
<item>
A key combination defined within the current context.
See the
<ref id="key-table-bind" name="bind">
directive for details.
<item>
A braille keyboard command defined within the current context.
See the
<ref id="key-table-map" name="map">
and
<ref id="key-table-superimpose" name="superimpose">
directives for details.
<item>
A key combination defined within the default context.
See the
<ref id="key-table-bind" name="bind">
directive for details.
</enum>
The following directives are provided:
<sect3>The Assign Directive<label id="key-table-assign"><p>
Create or update a variable associated with the current include level.
The variable is visible to the current and to lower include levels,
but not to higher include levels.
<tt/assign/ <em/variable/ [<em/value/]
<descrip>
<tag><em/variable/</tag>
The name of the variable.
If the variable doesn't already exist at the current include level
then it is created.
<tag><em/value/</tag>
The value which is to be assigned to the variable.
If it's not supplied then a zero-length (null) value is assigned.
</descrip>
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:
<itemize>
<item><tt/assign nullValue/
<item><tt/assign ReturnKey Key1/
<item><tt/bind \{ReturnKey} RETURN/
</itemize>
<sect3>The Bind Directive<label id="key-table-bind"><p>
Define which BRLTTY command is executed
when a particular combination of one or more keys is pressed.
The binding is defined within the current context.
<tt/bind/ <em/keys/ <em/command/
<descrip>
<tag><em/keys/</tag>
The key combination which is to be bound.
It's a sequence of one or more key names
separated by plus (<tt/+/) signs.
The final (or only) key name may be optionally prefixed
with an exclamation (<tt/!/) 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.
<tag><em/command/</tag>
The name of a BRLTTY command.
One or more modifiers may be optionally appended to the command name
by using a plus (<tt/+/) sign as the separator.
<itemize>
<item>
For commands which enable/disable a feature:
<itemize>
<item>
If the modifier <tt/+on/ is specified
then the feature is enabled.
<item>
If the modifier <tt/+off/ is specified
then the feature is disabled.
<item>
If neither <tt/+on/ nor <tt/+off/ is specified
then the state of the feature is toggled on/off.
</itemize>
<item>
For commands which move the braille window:
<itemize>
<item>
If the modifier <tt/+route/ is specified
then, if necessary, the cursor is automatically routed
so that it's always visible on the braille display.
</itemize>
<item>
For commands which move the braille window to a specific line on the screen:
<itemize>
<item>
If the modifier <tt/+toleft/ is specified
then the braille window is also moved
to the beginning of that line.
<item>
If the modifier <tt/+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.
</itemize>
<item>
For commands which require an offset:
<itemize>
<item>
The modifier +<em/offset/,
where <em/offset/ is a non-negative integer,
may be specified.
If it isn't supplied then <tt/+0/ is assumed.
</itemize>
</itemize>
</descrip>
Examples:
<itemize>
<item><tt/bind Key1 CSRTRK/
<item><tt/bind Key1+Key2 CSRTRK+off/
<item><tt/bind Key1+Key3 CSRTRK+on/
<item><tt/bind Key4 TOP/
<item><tt/bind Key5 TOP+route/
<item><tt/bind VerticalSensor GOTOLINE+toleft+scaled/
<item><tt/bind Key6 CONTEXT+1/
</itemize>
<sect3>The Context Directive<label id="key-table-context"><p>
Define alternate ways to interpret certain key events and/or combinations.
A context contains definitions created by the
<ref id="key-table-bind" name="bind">,
<ref id="key-table-hotkey" name="hotkey">,
<ref id="key-table-map" name="map">,
and
<ref id="key-table-superimpose" name="superimpose">
directives.
<tt/context/ <em/identifier/ [<em/title/]
<descrip>
<tag><em/identifier/</tag>
Which context subsequent definitions are to be created within.
It may be:
<itemize>
<item>
One of these special names:
<descrip>
<tag/default/
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 <ref id="key-table-bind" name="bind"> directive.
<tag/menu/
This context is used when within BRLTTY's preferences menu.
</descrip>
<item>
An integer within the range <tt/0/ through <tt/252/.
Context <tt/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.
</itemize>
<tag><em/title/</tag>
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.
</descrip>
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 <ref id="key-table-context" name="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 <tt/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 <em/title/ 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 <em/title/ 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:
<itemize>
<item><tt/context menu/
<item><tt/context 1 Braille Input/
<item><tt/context 2/
</itemize>
<sect3>The Hide Directive<label id="key-table-hide"><p>
Specify whether or not certain definitions (see the
<ref id="key-table-bind" name="bind">,
<ref id="key-table-hotkey" name="hotkey">,
<ref id="key-table-map" name="map">,
and
<ref id="key-table-superimpose" name="superimpose">
directives) and notes (see the
<ref id="key-table-note" name="note">
directive) are included within the key table's help text.
<tt/hide/ <em/state/
<descrip>
<tag><em/state/</tag>
One of these keywords:
<descrip>
<tag/on/They're excluded.
<tag/off/They're included.
</descrip>
</descrip>
The specified state applies to all subsequent definitions and notes
until either the next <tt/hide/ directive
or the end of the current include level.
The initial state of the top-level key table is <tt/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:
<itemize>
<item><tt/hide on/
</itemize>
<sect3>The Hotkey Directive<label id="key-table-hotkey"><p>
Bind the press and release events of a specific key
to two separate BRLTTY commands.
The bindings are defined within the current context.
<tt/hotkey/ <em/key/ <em/press/ <em/release/
<descrip>
<tag><em/key/</tag>
The name of the key which is to be bound.
<tag><em/press/</tag>
The name of the BRLTTY command
which is to be executed whenever the key is pressed.
<tag><em/release/</tag>
The name of the BRLTTY command
which is to be executed whenever the key is released.
</descrip>
Modifiers may be appended to the command names.
See the <em/command/ operand
of the <ref id="key-table-bind" name="bind"> directive
for details.
Specify <tt/NOOP/ if no command is to be executed.
Specifying <tt/NOOP/ for both commands
effectively disables the key.
Examples:
<itemize>
<item><tt/hotkey Key1 CSRVIS+off CSRVIS+on/
<item><tt/hotkey Key2 NOOP NOOP/
</itemize>
<sect3>The IfKey Directive<label id="key-table-ifkey"><p>
Conditionally process a key table directive
only if the device has a particular key.
<tt/ifkey/ <em/key/ <em/directive/
<descrip>
<tag><em/key/</tag>
The name of the key whose availability is to be tested.
<tag><em/directive/</tag>
The key table directive which is to be conditionally processed.
</descrip>
Examples:
<itemize>
<item><tt/ifkey Key1 ifkey Key2 bind Key1+Key2 HOME/
</itemize>
<sect3>The Include Directive<label id="key-table-include"><p>
Process the directives within a key subtable.
It's recursive, which means that
any key subtable can itself include yet another key subtable.
Care must be taken to ensure that an "include loop" is not created.
<tt/include/ <em/file/
<descrip>
<tag><em/file/</tag>
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.
</descrip>
Examples:
<itemize>
<item><tt/include common.kti/
<item><tt>include /path/to/my/keys.kti</tt>
</itemize>
<sect3>The Map Directive<label id="key-table-map"><p>
Map a key to a braille keyboard function.
The mapping is defined within the current context.
<tt/map/ <em/key/ <em/function/
<descrip>
<tag><em/key/</tag>
The name of the key which is to be mapped.
More than one key may be mapped to the same braille keyboard function.
<tag><em/function/</tag>
The name of the braille keyboard function.
It may be one of the following keywords:
<descrip>
<tag/DOT1/The upper-left standard braille dot.
<tag/DOT2/The middle-left standard braille dot.
<tag/DOT3/The lower-left standard braille dot.
<tag/DOT4/The upper-right standard braille dot.
<tag/DOT5/The middle-right standard braille dot.
<tag/DOT6/The lower-right standard braille dot.
<tag/DOT7/The lower-left computer braille dot.
<tag/DOT8/The lower-right computer braille dot.
<tag/SPACE/The space bar.
<tag/SHIFT/The shift key.
<tag/UPPERCASE/
If a lowercase letter is being entered
then translate it to its uppercase equivalent.
<tag/CONTROL/The control key.
<tag/META/The left alt key.
</descrip>
</descrip>
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
<ref id="key-table-superimpose" name="superimpose">
directives within the same context are also implicitly included.
Examples:
<itemize>
<item><tt/map Key1 DOT1/
</itemize>
<sect3>The Note Directive<label id="key-table-note"><p>
Add a person-readable explanation to the key table's help text.
Notes are commonly used, for example,
to describe the placement, sizes, and shapes of the keys on the device.
<tt/note/ <em/text/
<descrip>
<tag><em/text/</tag>
The explanation which is to be added.
It may contain spaces,
and should be grammatically correct.
</descrip>
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:
<itemize>
<item><tt/note Key1 is the round key at the far left on the front surface./
</itemize>
<sect3>The Superimpose Directive<label id="key-table-superimpose"><p>
Implicitly include a braille keyboard function whenever
a braille keyboard command consisting of at least one dot is executed.
The implicit inclusion is defined within the current context.
Any number of them may be specified.
<tt/superimpose/ <em/function/
<descrip>
<tag><em/function/</tag>
The name of the braille keyboard function.
See the <em/function/ operand
of the <ref id="key-table-map" name="map"> directive
for details.
</descrip>
Examples:
<itemize>
<item><tt/superimpose DOT7/
</itemize>
<sect3>The Title Directive<label id="key-table-title"><p>
Provide a person-readable summary of the key table's purpose.
<tt/title/ <em/text/
<descrip>
<tag><em/text/</tag>
A one-line summary of what the key table is used for.
It may contain spaces,
and standard capitalization conventions should be used.
</descrip>
The title of the key table may be specified only once.
Examples:
<itemize>
<item><tt/title Bindings for Keypad-based Navigation/
</itemize>
<sect2>Keyboard Properties<label id="keyboard-properties"><p>
The default is that all keyboards are monitored.
A subset of the keyboards may be selected by specifying one or more of the following properties
(see the <ref id="options-keyboard-properties" name="-K"> command line option,
and the <ref id="configure-keyboard-properties" name="keyboard-properties"> configuration file directive):
<descrip>
<tag/type/
The bus type, specified as one of the following keywords:
<tt/any/,
<tt/ps2/,
<tt/usb/,
<tt/bluetooth/.
<tag/vendor/
The vendor identifier, specified as a 16-bit unsigned integer.
<tag/product/
The product identifier, specified as a 16-bit unsigned integer.
</descrip>
The vendor and product identifiers may be specified in
decimal (no prefix),
octal (prefixed by <tt/0/),
or hexadecimal (prefixed by <tt/0x/).
Specifying <tt/0/ means match any value
(as if the property weren't specified).
<sect>Advanced Topics<p>
<sect1>Installing Multiple Versions<label id="multiple"><p>
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 <ref id="build-execute-root" name="--with-execute-root"> build option allows you
to install the complete <ref id="hierarchy" name="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:
<tscreen><verb>
./configure --with-execute-root=/brltty-3.1
make install
</verb></tscreen>
You can then run it like this:
<tscreen>/brltty-3.1/bin/brltty</tscreen>
When version 3.2 is released, just install it in a different location
and run the new executable from there.
<tscreen><verb>
./configure --with-execute-root=/brltty-3.2
make install
/brltty-3.2/bin/brltty
</verb></tscreen>
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.
<tscreen>ln -s /brltty-3.1/bin/brltty /bin/brltty</tscreen>
When it's time to switch to the newer version, just repoint the symbolc link.
<tscreen>ln -s /brltty-3.2/bin/brltty /bin/brltty</tscreen>
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.
<tscreen><verb>
ln -s /brltty/bin/brltty /bin/brltty
ln -s /brltty/etc/brltty /etc/brltty
ln -s /brltty/lib/brltty /lib/brltty
</verb></tscreen>
Then all you need to do is to point <tt>/brltty</> to the desired version.
<tscreen>ln -s /brltty-3.1 /brltty</tscreen>
<sect1>Installation/Rescue Root Disks for Linux<p>
BRLTTY can run as a stand-alone executable.
Everything it needs to know can be explicitly configured at build-time
(see <ref id="build" name="Build Options">).
If the data directory
(see the <ref id="build-data-directory" name="--with-data-directory">
and <ref id="build-execute-root" name="--with-execute-root"> build options)
doesn't exist, then BRLTTY looks in <tt>/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 <tt>/etc/brltty</>) by hand, it's important
to set its permissions so that only root can create files within it.
<tscreen>chmod 755 /etc/brltty</tscreen>
The screen content inspection device (usually <tt>/dev/vcsa</>) is required.
It should already exist unless your Linux distribution is quite old.
If necessary, you can create it with:
<tscreen><verb>
mknod /dev/vcsa c 7 128
chmod 660 /dev/vcsa
chown root.tty /dev/vcsa
</verb></tscreen>
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
<ref id="build-standalone-programs" name="--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 <ref id="build-features" name="Build Features">).
The executable is stripped during the <ref id="make-install" name="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.
<tscreen>strip brltty</tscreen>
<sect1>Future Enhancements<p>
Apart from fixing bugs and supporting more types of braille displays,
we hope, time permitting, to work on the following:
<descrip>
<tag/Better Attribute Handling/
<itemize>
<item>Attribute tracking.
<item>Mixed text and attribute mode.
</itemize>
<tag/Scroll Tracking/
Locking the braille window to one line as it scrolls on the screen.
<tag/Better Speech Support/
<itemize>
<item>Mixed braille and speech for faster reading of text.
<item>Better speech navigation.
<item>More speech synthesizers.
</itemize>
<tag/Screen Subregions/
Ignore cursor motion outside the region,
and set soft navigational boundaries at the edges of the region.
</descrip>
See the file <tt/TODO/ for a more complete list.
<sect1>Known Bugs<p>
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.
<appendix>
<sect>Supported Braille Displays<label id="displays"><p>
BRLTTY supports the following braille displays:
<table loc="h">
<tabular ca="ll">
Name|Models@<hline>
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@
BrailComm
|III@
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@
|Active Braille@
|Braille Wave@
|Easy Braille@
|Braille Star 40/80@
|Bookworm@
|Braillino@
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@
|Part232 (serial adapter)@
|BraillePen/EasyLink@
XWindow
|X11@
|Windows@
</tabular>
</table>
<sect>Supported Speech Synthesizers<label id="synthesizers"><p>
BRLTTY supports the following speech synthesizers:
<table loc="h">
<tabular ca="ll">
Name|Models@<hline>
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@
</tabular>
</table>
<sect>Driver Identification Codes<label id="drivers"><p>
<table loc="h">
<tabular ca="ll">
Code|Name@<hline>
al|Alva@
at|Albatross@
ba|BrlAPI@
bc|BrailComm@
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@
</tabular>
</table>
<sect>Supported Screen Drivers<label id="screen"><p>
BRLTTY supports the following screen drivers:
<descrip>
<tag/as/
AT-SPI
<tag/hd/
This driver provides direct access to the Hurd console screen.
It's only selectable, and is the default, on Hurd systems.
<tag/lx/
This driver provides direct access to the Linux console screen.
It's only selectable, and is the default, on Linux systems.
<tag/sc/
This driver provides access to the <tt/screen/ program.
It's selectable on all systems,
and is the default if no native screen driver is available.
The patch for <tt/screen/ which we provide
(see the <tt/Patches/ subdirectory)
must be applied.
Use of this driver,
due to the fact that <tt/screen/ must be concurrently running,
makes BRLTTY effectively useful only after the user has logged in.
<tag/wn/
This driver provides direct access to the Windows console screen.
It's only selectable, and is the default, on Windows/Cygwin systems.
</descrip>
<sect>Operand Syntax<p>
<sect1>Driver Specificationn<label id="operand-driver"><p>
A braille display or speech synthesizer driver must be specified
via its two-letter <ref id="drivers" name="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 <tt/auto/ is specified then autodetection is performed
using only those drivers which are known to be reliable for this purpose.
<sect1>Braille Device Specificationn<label id="operand-braille-device"><p>
The general form of a braille device specification
(see the <ref id="options-braille-device" name="-d"> command line option,
the <ref id="configure-braille-device" name="braille-device"> configuration file directive,
and the <ref id="build-braille-device" name="--with-braille-device"> build option)
is <tt/qualifier:/<em/data/.
For backward compatibility with earlier releases,
if the qualifier is omitted then <tt/serial:/ is assumed.
The following device types are supported:
<descrip>
<tag/Bluetooth/
For a bluetooth device, specify <tt/bluetooth:/<em/address/
(<tt/bt:/ and <tt/bluez:/ may also be used).
The address must be six two-digit hexadecimal numbers separated by colons,
e.g. <tt/01:23:45:67:89:AB/.
<tag/Serial/
For a serial device, specify <tt/serial:/<em>/path/to/device</>.
The <tt/serial:/ qualifier is optional (for backward compatibility).
If a relative path is given then it's anchored at <tt>/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:
<itemize>
<item><tt>serial:/dev/ttyS0</>
<item><tt>serial:ttyS0</>
<item><tt>/dev/ttyS0</>
<item><tt>ttyS0</>
</itemize>
<tag/USB/
For a USB device, specify <tt/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. <tt/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.
</descrip>
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. <tt>usb:,serial:/dev/ttyS0</tt>,
since the former tends to autodetect more reliably than the latter.
<sect1>PCM Device Specificationn<label id="operand-pcm-device"><p>
In most cases the PCM device is
the full path to an appropriate system device.
Exceptions are:
<descrip>
<tag/ALSA/
The name of and arguments for the physical or logical device,
i.e. <em/name/[<tt/:/<em/argument/<tt/,/...].
</descrip>
The default PCM device is:
<table loc="h">
<tabular ca="ll">
Platform|Device@<hline>
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@
</tabular>
</table>
<sect1>MIDI Device Specificationn<label id="operand-midi-device"><p>
In most cases the MIDI device is
the full path to an appropriate system device.
Exceptions are:
<descrip>
<tag/ALSA/
The client and port separated by a colon,
i.e. <em/client/<tt/:/<em/port/.
Each may be specified
either as a number
or as a case-sensitive substring of its name.
</descrip>
The default MIDI device is:
<table loc="h">
<tabular ca="ll">
Platform|Device@<hline>
Linux/ALSA|the first available MIDI output port@
Linux/OSS|/dev/sequencer@
</tabular>
</table>
<sect>Standard Braille Dot Numbering Convention<label id="dots"><p>
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:
<descrip>
<tag/1/Top-left (row 1, column 1).
<tag/2/Middle-left (row 2, column 1).
<tag/3/Bottom-left (row 3, column 1).
<tag/4/Top-right (row 1, column 2).
<tag/5/Middle-right (row 2, column 2).
<tag/6/Bottom-right (row 3, column 2).
</descrip>
Computer braille has introduced a fourth row at the bottom.
<descrip>
<tag/7/Below-left (row 4, column 1).
<tag/8/Below-right (row 4, column 2).
</descrip>
Perhaps a picture will make this numbering convention easier to understand.
<tscreen><verb>
1 o o 4
2 o o 5
3 o o 6
7 o o 8
</verb></tscreen>
<sect>North American Braille Computer Code<label id="nabcc"><p>
<tscreen><verb>
Num Hex Dots Description
+-----------------------------------------------------------------+
| 0 00 [7 4 8] NUL (null) |
| 1 01 [7 1 8] SOH (start of header) |
| 2 02 [7 21 8] STX (start of text) |
| 3 03 [7 14 8] ETX (end of text) |
| 4 04 [7 145 8] EOT (end of transmission) |
| 5 05 [7 1 5 8] ENQ (enquiry) |
| 6 06 [7 214 8] ACK (acknowledge) |
| 7 07 [7 2145 8] BEL (bell) |
| 8 08 [7 21 5 8] BS (back space) |
| 9 09 [7 2 4 8] HT (horizontal tab) |
| 10 0A [7 2 45 8] LF (line feed) |
| 11 0B [73 1 8] VT (vertical tab) |
| 12 0C [7321 8] FF (form feed) |
| 13 0D [73 14 8] CR (carriage return) |
| 14 0E [73 145 8] SO (shift out) |
| 15 0F [73 1 5 8] SI (shift in) |
| 16 10 [73214 8] DLE (data link escape) |
| 17 11 [732145 8] DC1 (direct control 1) |
| 18 12 [7321 5 8] DC2 (direct control 2) |
| 19 13 [732 4 8] DC3 (direct control 3) |
| 20 14 [732 45 8] DC4 (direct control 4) |
| 21 15 [73 1 68] NAK (negative acknowledge) |
| 22 16 [7321 68] SYN (synchronize) |
| 23 17 [7 2 4568] ETB (end of text block) |
| 24 18 [73 14 68] CAN (cancel) |
| 25 19 [73 14568] EM (end of medium) |
| 26 1A [73 1 568] SUB (substitute) |
| 27 1B [7 2 4 68] ESC (escape) |
| 28 1C [7 21 568] FS (file separator) |
| 29 1D [7 214568] GS (group separator) |
| 30 1E [7 45 8] RS (record separator) |
| 31 1F [7 4568] US (unit separator) |
| 32 20 [ ] space |
| 33 21 [ 32 4 6 ] exclamation point |
| 34 22 [ 5 ] quotation mark |
| 35 23 [ 3 456 ] number sign |
| 36 24 [ 214 6 ] dollar sign |
| 37 25 [ 14 6 ] percent sign |
| 38 26 [ 3214 6 ] ampersand |
| 39 27 [ 3 ] acute accent |
| 40 28 [ 321 56 ] left parenthesis |
| 4 291 [ 32 456 ) right parenthesis |
| 42 2A [ 1 6 ] asterisk |
| 43 2B [ 3 4 6 ] plus sign |
| 44 2C [ 6 ] comma |
| 45 2D [ 3 6 ] minus sign |
| 46 2E [ 4 6 ] period |
| 47 2F [ 3 4 ] forward slash |
| 48 30 [ 3 56 ] zero |
| 49 31 [ 2 ] one |
| 50 32 [ 32 ] two |
| 51 33 [ 2 5 ] three |
| 52 34 [ 2 56 ] four |
| 53 35 [ 2 6 ] five |
| 54 36 [ 32 5 ] six |
| 55 37 [ 32 56 ] seven |
| 56 38 [ 32 6 ] eight |
| 57 39 [ 3 5 ] nine |
| 58 3A [ 1 56 ] colon |
| 59 3B [ 56 ] semicolon |
| 60 3C [ 21 6 ] less-than sign |
| 61 3D [ 321456 ] equals sign |
| 62 3E [ 3 45 ] greater-than sign |
| 63 3F [ 1456 ] question mark |
| 64 40 [7 4 ] commercial at |
| 65 41 [7 1 ] capital a |
| 66 42 [7 21 ] capital b |
| 67 43 [7 14 ] capital c |
| 68 44 [7 145 ] capital d |
| 69 45 [7 1 5 ] capital e |
| 70 46 [7 214 ] capital f |
| 71 47 [7 2145 ] capital g |
| 72 48 [7 21 5 ] capital h |
| 73 49 [7 2 4 ] capital i |
| 74 4A [7 2 45 ] capital j |
| 75 4B [73 1 ] capital k |
| 76 4C [7321 ] capital l |
| 77 4D [73 14 ] capital m |
| 78 4E [73 145 ] capital n |
| 79 4F [73 1 5 ] capital o |
| 80 50 [73214 ] capital p |
| 81 51 [732145 ] capital q |
| 82 52 [7321 5 ] capital r |
| 83 53 [732 4 ] capital s |
| 84 54 [732 45 ] capital t |
| 85 55 [73 1 6 ] capital u |
| 86 56 [7321 6 ] capital v |
| 87 57 [7 2 456 ] capital w |
| 88 58 [73 14 6 ] capital x |
| 89 59 [73 1456 ] capital y |
| 90 5A [73 1 56 ] capital z |
| 91 5B [7 2 4 6 ] left bracket |
| 92 5C [7 21 56 ] backward slash |
| 93 5D [7 21456 ] right bracket |
| 94 5E [7 45 ] circumflex accent |
| 95 5F [ 456 ] underscore |
| 96 60 [ 4 ] grave accent |
| 97 61 [ 1 ] small a |
| 98 62 [ 21 ] small b |
| 99 63 [ 14 ] small c |
| 100 64 [ 145 ] small d |
| 101 65 [ 1 5 ] small e |
| 102 66 [ 214 ] small f |
| 103 67 [ 2145 ] small g |
| 104 68 [ 21 5 ] small h |
| 105 69 [ 2 4 ] small i |
| 106 6A [ 2 45 ] small j |
| 107 6B [ 3 1 ] small k |
| 108 6C [ 321 ] small l |
| 109 6D [ 3 14 ] small m |
| 110 6E [ 3 145 ] small n |
| 111 6F [ 3 1 5 ] small o |
| 112 70 [ 3214 ] small p |
| 113 71 [ 32145 ] small q |
| 114 72 [ 321 5 ] small r |
| 115 73 [ 32 4 ] small s |
| 116 74 [ 32 45 ] small t |
| 117 75 [ 3 1 6 ] small u |
| 118 76 [ 321 6 ] small v |
| 119 77 [ 2 456 ] small w |
| 120 78 [ 3 14 6 ] small x |
| 121 79 [ 3 1456 ] small y |
| 122 7A [ 3 1 56 ] small z |
| 123 7B [ 2 4 6 ] left brace |
| 124 7C [ 21 56 ] vertical bar |
| 125 7D [ 21456 ] right brace |
| 126 7E [ 45 ] tilde accent |
| 127 7F [7 456 ] DEL (delete) |
| 128 80 [ 4 8] <control> |
| 129 81 [ 1 8] <control> |
| 130 82 [ 21 8] BPH (break permitted here) |
| 131 83 [ 14 8] NBH (no break here) |
| 132 84 [ 145 8] <control> |
| 133 85 [ 1 5 8] NL (next line) |
| 134 86 [ 214 8] SSA (start of selected area) |
| 135 87 [ 2145 8] ESA (end of selected area) |
| 136 88 [ 21 5 8] CTS (character tabulation set) |
| 137 89 [ 2 4 8] CTJ (character tabulation justification) |
| 138 8A [ 2 45 8] LTS (line tabulation set) |
| 139 8B [ 3 1 8] PLD (partial line down) |
| 140 8C [ 321 8] PLU (partial line up) |
| 141 8D [ 3 14 8] RLF (reverse line feed) |
| 142 8E [ 3 145 8] SS2 (single shift two) |
| 143 8F [ 3 1 5 8] SS3 (single shift three) |
| 144 90 [ 3214 8] DCS (device control string) |
| 145 91 [ 32145 8] PU1 (private use one) |
| 146 92 [ 321 5 8] PU2 (private use two) |
| 147 93 [ 32 4 8] STS (set transmit state) |
| 148 94 [ 32 45 8] CC (cancel character) |
| 149 95 [ 3 1 68] MW (message waiting) |
| 150 96 [ 321 68] SGA (start of guarded area) |
| 151 97 [ 2 4568] EGA (end of guarded area) |
| 152 98 [ 3 14 68] SS (start of string) |
| 153 99 [ 3 14568] <control> |
| 154 9A [ 3 1 568] SCI (single character introducer) |
| 155 9B [ 2 4 68] CSI (control sequence introducer) |
| 156 9C [ 21 568] ST (string terminator) |
| 157 9D [ 214568] OSC (operating system command) |
| 158 9E [ 45 8] PM (privacy message) |
| 159 9F [ 4568] APC (application program command) |
| 160 A0 [7 8] no-break space |
| 161 A1 [732 4 6 ] inverted exclamation mark |
| 162 A2 [7 214 6 ] cent sign |
| 163 A3 [73 456 ] pound sign |
| 164 A4 [7 14 6 ] currency sign |
| 165 A5 [73214 6 ] yen sign |
| 166 A6 [7 1 56 ] broken bar |
| 167 A7 [73 5 ] section sign |
| 168 A8 [7 5 ] diaeresis |
| 169 A9 [732 56 ] copyright sign |
| 170 AA [ 8] feminine ordinal indicator |
| 171 AB [7 21 6 ] left-pointing double angle quotation mark |
| 172 AC [7 2 56 ] not sign |
| 173 AD [73 6 ] soft hyphen |
| 174 AE [732 6 ] registered sign |
| 175 AF [7 2 6 ] macron |
| 176 B0 [73 56 ] degree sign |
| 177 B1 [73 4 6 ] plus-minus sign |
| 178 B2 [732 ] superscript two |
| 179 B3 [7 2 5 ] superscript three |
| 180 B4 [73 ] acute accent |
| 181 B5 [7 56 ] micro sign |
| 182 B6 [732 5 ] pilcrow sign |
| 183 B7 [7 4 6 ] middle dot |
| 184 B8 [7 6 ] cedilla |
| 185 B9 [7 2 ] superscript one |
| 186 BA [7 ] masculine ordinal indicator |
| 187 BB [73 45 ] right-pointing double angle quotation mark |
| 188 BC [7321 56 ] vulgar fraction one quarter |
| 189 BD [7321456 ] vulgar fraction one half |
| 190 BE [732 456 ] vulgar fraction three quarters |
| 191 BF [7 1456 ] inverted question mark |
| 192 C0 [732 5 8] capital a grave |
| 193 C1 [7 1 68] capital a acute |
| 194 C2 [7 2 8] capital a circumflex |
| 195 C3 [7 5 8] capital a tilde |
| 196 C4 [73214 68] capital a diaeresis |
| 197 C5 [73 45 8] capital a ring above |
| 198 C6 [73 8] capital ae |
| 199 C7 [73 4 68] capital c cedilla |
| 200 C8 [732 568] capital e grave |
| 201 C9 [7 21 68] capital e acute |
| 202 CA [732 8] capital e circumflex |
| 203 CB [73214568] capital e diaeresis |
| 204 CC [732 68] capital i grave |
| 205 CD [7 14 68] capital i acute |
| 206 CE [7 2 5 8] capital i circumflex |
| 207 CF [7321 568] capital i diaeresis |
| 208 D0 [7 68] capital eth |
| 209 D1 [7 4 68] capital n tilde |
| 210 D2 [73 5 8] capital o grave |
| 211 D3 [7 14568] capital o acute |
| 212 D4 [7 2 568] capital o circumflex |
| 213 D5 [7 568] capital o tilde |
| 214 D6 [732 4 68] capital o diaeresis |
| 215 D7 [7 1 6 ] multiplication sign |
| 216 D8 [73 4 8] capital o stroke |
| 217 D9 [73 568] capital u grave |
| 218 DA [7 1 568] capital u acute |
| 219 DB [7 2 68] capital u circumflex |
| 220 DC [732 4568] capital u diaeresis |
| 221 DD [7 214 68] capital y acute |
| 222 DE [73 68] capital thorn |
| 223 DF [73 4568] small sharp s |
| 224 E0 [ 32 5 8] small a grave |
| 225 E1 [ 1 68] small a acute |
| 226 E2 [ 2 8] small a circumflex |
| 227 E3 [ 5 8] small a tilde |
| 228 E4 [ 3214 68] small a diaeresis |
| 229 E5 [ 3 45 8] small a ring above |
| 230 E6 [ 3 8] small ae |
| 231 E7 [ 3 4 68] small c cedilla |
| 232 E8 [ 32 568] small e grave |
| 233 E9 [ 21 68] small e acute |
| 234 EA [ 32 8] small e circumflex |
| 235 EB [ 3214568] small e diaeresis |
| 236 EC [ 32 68] small i grave |
| 237 ED [ 14 68] small i acute |
| 238 EE [ 2 5 8] small i circumflex |
| 239 EF [ 321 568] small i diaeresis |
| 240 F0 [ 68] small eth |
| 241 F1 [ 4 68] small n tilde |
| 242 F2 [ 3 5 8] small o grave |
| 243 F3 [ 14568] small o acute |
| 244 F4 [ 2 568] small o circumflex |
| 245 F5 [ 568] small o tilde |
| 246 F6 [ 32 4 68] small o diaeresis |
| 247 F7 [73 4 ] division sign |
| 248 F8 [ 3 4 8] small o stroke |
| 249 F9 [ 3 568] small u grave |
| 250 FA [ 1 568] small u acute |
| 251 FB [ 2 68] small u circumflex |
| 252 FC [ 32 4568] small u diaeresis |
| 253 FD [ 214 68] small y acute |
| 254 FE [ 3 68] small thorn |
| 255 FF [ 3 4568] small y diaeresis |
+-----------------------------------------------------------------+
</verb></tscreen>
<sect>MIDI Instrument Table<label id="midi"><p>
<table loc="h">
<tabular ca="lrl">
<hline>Piano
|0|Acoustic Grand Piano@
|1|Bright Acoustic Piano@
|2|Electric Grand Piano@
|3|Honkytonk Piano@
|4|Electric Piano 1@
|5|Electric Piano 2@
|6|Harpsichord@
|7|Clavi@
<hline>Chromatic Percussion
|8|Celesta@
|9|Glockenspiel@
|10|Music Box@
|11|Vibraphone@
|12|Marimba@
|13|Xylophone@
|14|Tubular Bells@
|15|Dulcimer@
<hline>Organ
|16|Drawbar Organ@
|17|Percussive Organ@
|18|Rock Organ@
|19|Church Organ@
|20|Reed Organ@
|21|Accordion@
|22|Harmonica@
|23|Tango Accordion@
<hline>Guitar
|24|Nylon Acoustic Guitar@
|25|Steel Acoustic Guitar@
|26|Jazz Electric Guitar@
|27|Clean Electric Guitar@
|28|Muted Electric Guitar@
|29|Overdriven Guitar@
|30|Distortion Guitar@
|31|Guitar Harmonics@
<hline>Bass
|32|Acoustic Bass@
|33|Finger Electric Bass@
|34|Pick Electric Bass@
|35|Fretless Bass@
|36|Slap Bass 1@
|37|Slap Bass 2@
|38|Synth Bass 1@
|39|Synth Bass 2@
<hline>Strings
|40|Violin@
|41|Viola@
|42|Cello@
|43|Contrabass@
|44|Tremolo Strings@
|45|Pizzicato Strings@
|46|Orchestral Harp@
|47|Timpani@
<hline>Ensemble
|48|String Ensemble 1@
|49|String Ensemble 2@
|50|Synth Strings 1@
|51|Synth Strings 2@
|52|Choir Aahs@
|53|Voice Oohs@
|54|Synth Voice@
|55|Orchestra Hit@
<hline>Brass
|56|Trumpet@
|57|Trombone@
|58|Tuba@
|59|Muted Trumpet@
|60|French Horn@
|61|Brass Section@
|62|Synth Brass 1@
|63|Synth Brass 2@
<hline>Reed
|64|Soprano Saxophone@
|65|Alto Saxophone@
|66|Tenor Saxophone@
|67|Baritone Saxophone@
|68|Oboe@
|69|English Horn@
|70|Bassoon@
|71|Clarinet@
<hline>Pipe
|72|Piccolo@
|73|Flute@
|74|Recorder@
|75|Pan Flute@
|76|Blown Bottle@
|77|Shakuhachi@
|78|Whistle@
|79|Ocarina@
<hline>Synth Lead
|80|Lead 1 (square)@
|81|Lead 2 (sawtooth)@
|82|Lead 3 (calliope)@
|83|Lead 4 (chiff)@
|84|Lead 5 (charang)@
|85|Lead 6 (voice)@
|86|Lead 7 (fifths)@
|87|Lead 8 (bass + lead)@
<hline>Synth Pad
|88|Pad 1 (new age)@
|89|Pad 2 (warm)@
|90|Pad 3 (polysynth)@
|91|Pad 4 (choir)@
|92|Pad 5 (bowed)@
|93|Pad 6 (metallic)@
|94|Pad 7 (halo)@
|95|Pad 8 (sweep)@
<hline>Synth FM
|96|FX 1 (rain)@
|97|FX 2 (soundtrack)@
|98|FX 3 (crystal)@
|99|FX 4 (atmosphere)@
|100|FX 5 (brightness)@
|101|FX 6 (goblins)@
|102|FX 7 (echoes)@
|103|FX 8 (science-fiction)@
<hline>Ethnic
|104|Sitar@
|105|Banjo@
|106|Shamisen@
|107|Koto@
|108|Kalimba@
|109|Bag Pipe@
|110|Fiddle@
|111|Shanai@
<hline>Percussive
|112|Tinkle Bell@
|113|Agogo@
|114|Steel Drum@
|115|Wooden Block@
|116|Taiko Drum@
|117|Melodic Tom@
|118|Synth Drum@
|119|Reverse Cymbal@
<hline>Sound Effects
|120|Guitar Fret Noise@
|121|Breath Noise@
|122|Seashore@
|123|Bird Tweet@
|124|Telephone Ring@
|125|Helicopter@
|126|Applause@
|127|Gunshot@
</tabular>
</table>
</article>
