<!doctype linuxdoc system>
<article>

<titlepag>
  <title>BRLTTY
    <subtitle>Access to the Linux/Unix Console for Blind Persons using Refreshable Braille Displays
  <author>
    <name>Nikhil Nair <tt><htmlurl url="mailto:nn201@cus.cam.ac.uk" name="&lt;nn201@cus.cam.ac.uk&gt;"></tt>
  <and>
    <name>Nicolas Pitre <tt><htmlurl url="mailto:nico@cam.org" name="&lt;nico@cam.org&gt;"></tt>
  <and>
    <name>Stéphane Doyon <tt><htmlurl url="mailto:s.doyon@videotron.ca" name="&lt;s.doyon@videotron.ca&gt;"></tt>
  <and>
    <name>Dave Mielke <tt><htmlurl url="mailto:dave@mielke.cc" name="&lt;dave@mielke.cc&gt;"></tt>
  <date>Version 3.3.1, September 2003
  <abstract>
    Copyright &copy; 1995-2003 by The BRLTTY Team - All Rights Reserved.
    This is free software, placed under the terms of
    <bf/The GNU General Public License/.
    BRLTTY comes with ABSOLUTELY NO WARRANTY.
  </abstract>
</titlepag>
<toc>
<lof>
<lot>

<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 grade 2 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 and Solaris.
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.
      <item>
        A DEC Alpha
        (only tested once under Red Hat Alpha Linux on a noname board kindly lent
        to the Cambridge University Computer Laboratory by DEC in Reading, England).
    </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>
</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.

In order for BRLTTY to successfully communicate with the refreshable braille display,
the correct driver (serial, parallel, USB) must be configured into the kernel.
If the driver requires special options, then they must be supplied.
If it's built into the kernel, then its options must be:
<descrip>
  <tag/Linux/
    <itemize>
      <item>
        Set during the kernel configuration procedure.
      <item>
        Supplied at the LILO boot prompt.
      <item>
        Specified on an <tt/append/ directive in <tt>/etc/lilo.conf</>.
    </itemize>
</descrip>
If the driver is a module, then its options must be:
<descrip>
  <tag/Linux/
    <itemize>
      <item>
        Supplied as options to the <tt/modprobe/ (or <tt/insmod/) command.
      <item>
        Specified on an <tt/options/ directive in <tt>/etc/modules.conf</>
        (called <tt>/etc/conf.modules</> by some older distributions).
    </itemize>
</descrip>

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.
    </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/*.ctb/
        Contraction tables
        (see section <ref id="contraction" name="Contracted Braille"> for details).
        Their names look like <em/language/<tt/-/<em/country/<tt/-/<em/level/<tt/.ctb/.
      <tag/*.cti/
        Include files for contraction 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">.
      <tag/*.tbl/
        Translation tables
        (see section <ref id="translation" name="Translation Tables"> for details).
        Their names look like <tt/text./<em/language/<tt/.tbl/.
        Tables designed for use with character sets other than <tt/iso-8859-1/
        have names which indicate this fact.
        There are also a couple of special tables which map
        character highlighting attributes to braille dots:
        <tt/attrib.tbl/ does it the original way,
        and <tt/attributes.tbl/ does it the current way.
    </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>
</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 default braille display driver.
    Either a two-letter <ref id="drivers" name="driver identification code">
    or the proper name (full or abbreviated) of the driver
    may be used.
    If this option is specified, then the named driver
    is statically linked into the BRLTTY binary.
    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-device=/<em/device/<label id="build-braille-device"></tag>
    Specify the default device to which the braille display is connected.
    If a relative path is supplied, then it's anchored at <tt>/dev</>.
    If this option isn't specified,
    then an operating system appropriate path
    for the primary serial port is assumed.
    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-text-table=/<em/file/<label id="build-text-table"></tag>
    Specify the default text translation table
    (see section <ref id="translation" name="Translation 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="--sysconfdir">
    and the <ref id="build-execute-root" name="--with-execute-root">
    build options for more details).
    If this option isn't specified,
    then 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 default attributes translation table
    (see section <ref id="translation" name="Translation 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="--sysconfdir">
    and the <ref id="build-execute-root" name="--with-execute-root">
    build options for more details).
    If this option isn't specified,
    then <tt/attributes.tbl/ is assumed.
    Change it to <tt/attrib.tbl/ 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 default speech synthesizer driver.
    Either a two-letter <ref id="drivers" name="driver identification code">
    or the proper name (full or abbreviated) of the driver
    may be used.
    If this option is specified, then the named driver
    is statically linked into the BRLTTY binary.
    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-screen-driver=/<em/driver/<label id="build-screen-driver"></tag>
    Specify the screen driver.
    It may be one of the following:
    <descrip>
      <tag/linux/
        This driver provides direct access to the Linux console screen.
        It's only selectable, and is the default, on Linux systems.
      <tag/shm/
        This driver provides access to the <tt/screen/ program.
        It's selectable on all systems,
        and is the default on most.
        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.
    </descrip>
    If this option isn't specified,
    then an operating system appropriate selection is made.
    If a specific driver for the current operating system is available,
    then it's used.
    If not, then <tt/shm/ is used.
</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-data-directory" name="data 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">
    </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/--bindir=/<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 <tt>/bin</>, rooted at the directory specified by the
    <ref id="build-architecture-root" name="--exec-prefix">
    build option, is assumed.
  <tag><tt/--libdir=/<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 <tt>/lib</>, rooted at the directory specified by the
    <ref id="build-architecture-root" name="--exec-prefix">
    build option, is assumed.
    The files themselves are installed within this directory's <tt/brltty/ subdirectory
    (which is created if necessary).
  <tag><tt/--sysconfdir=/<em/directory/<label id="build-data-directory"></tag>
    Specify the directory within the
    <ref id="hierarchy" name="installed file hierarchy">
    where the configuration files, tables, help pages,
    and other architecture-dependent files are to be installed.
    The absolute path should be supplied.
    If this option isn't specified,
    then <tt>/etc</>, rooted at the directory specified by the
    <ref id="build-portable-root" name="--prefix">
    build option, is assumed.
    The files themselves are installed within this directory's <tt/brltty/ subdirectory
    (which is created if necessary).
</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">
    and the <ref id="build-speech-driver" name="--with-speech-driver">
    build options) are compiled.
  <tag><tt/--disable-tainted-components/<label id="build-tainted-components"></tag>
    Exclude those components which have a build-time dependency
    beyond what a standard system is expected to provide.
    These include:
    <itemize>
      <item>The <bf/ViaVoice/ speech driver.
    </itemize>
  <tag><tt/--disable-preferences-menu/<label id="build-preferences-menu"></tag>
    Reduce program size by excluding the preferences menu
    (see section <ref id="preferences-menu" name="The Preferences Menu">).
  <tag><tt/--disable-table-selection/<label id="build-table-selection"></tag>
    Reduce program size by excluding
    the table selection entries from the preferences menu
    (see the <ref id="preference-text-table" name="Text Table">,
    <ref id="preference-attributes-table" name="Attributes Table">,
    and <ref id="preference-contraction-table" name="Contraction Table"> preferences).
  <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="contraction" name="Contracted Braille">).
  <tag><tt/--disable-speech-support/<label id="build-speech-support"></tag>
    Reduce program size by excluding support for speech synthesizers.
  <tag><tt/--disable-beeper-tunes/<label id="build-beeper-tunes"></tag>
    Reduce program size by excluding support for the playing of alert tunes
    (see section <ref id="tunes" name="Alert Tunes">)
    via the internal beeper (console tone generator).
  <tag><tt/--disable-pcm-tunes/<label id="build-pcm-tunes"></tag>
    Reduce program size by excluding support for the playing of alert tunes
    (see section <ref id="tunes" name="Alert Tunes">)
    via the digital audio interface on the sound card.
  <tag><tt/--disable-midi-tunes/<label id="build-midi-tunes"></tag>
    Reduce program size by excluding support for the playing of alert tunes
    (see section <ref id="tunes" name="Alert Tunes">)
    via the Musical Instrument Digital Interface on the sound card.
  <tag><tt/--disable-fm-tunes/<label id="build-fm-tunes"></tag>
    Reduce program size by excluding support for the playing of alert tunes
    (see section <ref id="tunes" name="Alert Tunes">)
    via 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/--enable-gpm/<label id="build-gpm"></tag>
    Include an interface to the <tt/gpm/ application
    so that, on systems which support it,
    BRLTTY will interact with the pointer (mouse) device
    (see section <ref id="gpm" name="Pointer (Mouse) Support via GPM">).
  <tag><tt/--enable-api/<label id="build-api"></tag>
    Include the application programming interface
    (see section <ref id="api" name="The Application Programming Interface">).
</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.
</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 translation 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 and the selected drivers.

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>&num;!/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/rcS</> (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.
  <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 experience problems if an application tries to use
the kernel's sound subsystem before it has been initialized.
If your system is one of them, then
you may need to disable the automatic starting of the speech synthesizer driver
with the <ref id="options-no-speech" name="-N"> option.

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-data-directory" name="--sysconfdir">,
and <ref id="build-library-directory" name="--libdir">
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&amp;paste, beeps,
and all that, you can run BRLTTY without root priviledge.

<sect1>Build and Run-Time Restrictions<p>
<descrip>
  <tag/Alert 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/ViaVoice Driver/
    The driver for the ViaVoice software speech synthesizer
    is only built if that package has been installed.
  <tag/VideoBraille Driver/
    The driver for the VideoBraille braille display is built on all systems,
    but only works on Linux.
  <tag/Voyager Driver/
    The driver for the Voyager braille display is only built
    on the Linux operating system.
</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-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/ &lsqb;<em/from/&rsqb;</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>txt2hlp<p>
This is a helper utility which is used during the build procedure
to prepare the help pages for the drivers.
<tscreen>txt2hlp <em/output-file/ <em/input-file/ ...</tscreen>
<descrip>
  <tag><em/output-file/</tag>
    The file which is to contain all of the compiled help pages.
    The pages are numbered, starting from zero,
    in the same order as the input files are specified.
  <tag><em/input-file/</tag>
    At least one input file must be specified.
    Each is the source for a single help page,
    and should contain plain text.
</descrip>

<sect2>tbl2hex<p>
This is a helper utility which is used during the build procedure
to prepare the default text and attributes translation tables.
<tscreen>tbl2hex</tscreen>
The translation table is read from standard input,
and a set of hexadecimal constants
suitable for inclusion within a C array initializer
is written to standard output.

<sect2>brltest<label id="utility-brltest"><p>
This utility tests the braille display driver,
and also provides an interactive way to learn
what the keys on the braille display do.
It must 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 may be
    either a two-letter <ref id="drivers" name="driver identification code">
    or the absolute path to a dynamically loadable shared object.
    If it's not specified, then the 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/-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 device 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>

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>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: &lsqb;<em/column/,<em/row/&rsqb;</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/@&lsqb;<em/column/,<em/row/&rsqb;</tscreen>
  <item>
    The contents of the selected screen region.
    Unprintable characters are written as blanks.
</enum>

<sect2>tunetest<label id="utility-tunetest"><p>
This utility tests the alert tunes facility,
and also provides an easy way to compose new tunes.
<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/-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<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-NXINDENT" name="NXINDENT">
and the <ref id="command-PRINDENT" name="PRINDENT"> routing key commands.
<descrip>
  <tag>LNUP<label id="command-LNUP"></tag>
    Go up one line.
    If identical line skipping has been activated
    (see the <ref id="command-SKPIDLNS" name="SKPIDLNS"> command),
    then this command, rather than moving exactly one line,
    is an alias for the <ref id="command-PRDIFLN" name="PRDIFLN"> command.
  <tag>LNDN<label id="command-LNDN"></tag>
    Go down one line.
    If identical line skipping has been activated
    (see the <ref id="command-SKPIDLNS" name="SKPIDLNS"> command),
    then this command, rather than moving exactly one line,
    is an alias for the <ref id="command-NXDIFLN" name="NXDIFLN"> command.
  <tag>WINUP<label id="command-WINUP"></tag>
    Go up several lines.
  <tag>WINDN<label id="command-WINDN"></tag>
    Go down several lines.
  <tag>PRDIFLN<label id="command-PRDIFLN"></tag>
    Go up to the nearest previous line
    with different content.
    If identical line skipping has been activated
    (see the <ref id="command-SKPIDLNS" name="SKPIDLNS"> command),
    then this command, rather than skipping identical lines,
    is an alias for the <ref id="command-LNUP" name="LNUP"> command.
  <tag>NXDIFLN<label id="command-NXDIFLN"></tag>
    Go down to the nearest next line
    with different content.
    If identical line skipping has been activated
    (see the <ref id="command-SKPIDLNS" name="SKPIDLNS"> command),
    then this command, rather than skipping identical lines,
    is an alias for the <ref id="command-LNDN" name="LNDN"> command.
  <tag>ATTRUP<label id="command-ATTRUP"></tag>
    Go up to the nearest previous line
    with different character highlighting (attributes).
  <tag>ATTRDN<label id="command-ATTRDN"></tag>
    Go down to the nearest next line
    with different character highlighting (attributes).
  <tag>TOP<label id="command-TOP"></tag>
    Go up to the top line.
  <tag>BOT<label id="command-BOT"></tag>
    Go down to the bottom line.
  <tag>TOP_LEFT<label id="command-TOP_LEFT"></tag>
    Go to the top-left corner.
  <tag>BOT_LEFT<label id="command-BOT_LEFT"></tag>
    Go to the bottom-left corner.
  <tag>PRPGRPH<label id="command-PRPGRPH"></tag>
    Go up to the last line of the previous paragraph
    (the first non-blank line beyond the nearest previous blank line).
    The current line is included when searching for the inter-paragraph space.
  <tag>NXPGRPH<label id="command-NXPGRPH"></tag>
    Go down to the first line of the next paragraph
    (the first non-blank line beyond the nearest next blank line).
    The current line is included when searching for the inter-paragraph space.
  <tag>PRPROMPT<label id="command-PRPROMPT"></tag>
    Go up to the previous command prompt.
  <tag>NXPROMPT<label id="command-NXPROMPT"></tag>
    Go down to the next command prompt.
  <tag>PRSEARCH<label id="command-PRSEARCH"></tag>
    Search backward for the nearest occurrence
    of the character string within the cut buffer
    (see <ref id="cut" name="Cut and Paste">).
    The search starts at the character immediately to the left of the braille window,
    proceeds from right to left,
    and, at the beginning of a line, wraps to the end of the previous line.
    The search isn't case sensitive.
  <tag>NXSEARCH<label id="command-NXSEARCH"></tag>
    Search forward for the nearest occurrence
    of the character string within the cut buffer
    (see <ref id="cut" name="Cut and Paste">).
    The search starts at the character immediately to the right of the braille window,
    proceeds from left to right,
    and, at the end of a line, wraps to the beginning of the next line.
    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<label id="command-CHRLT"></tag>
    Go left one character.
  <tag>CHRRT<label id="command-CHRRT"></tag>
    Go right one character.
  <tag>HWINLT<label id="command-HWINLT"></tag>
    Go left half a window.
  <tag>HWINRT<label id="command-HWINRT"></tag>
    Go right half a window.
  <tag>FWINLT<label id="command-FWINLT"></tag>
    Go left one window.
    This command is particularly useful when reading backward
    because it automatically wraps up to the end of the previous line
    when invoked at the beginning of the current line.
    Other features like its ability to skip blank windows
    (see the <ref id="command-SKPBLNKWINS" name="SKPBLNKWINS"> command)
    further enhance its usefulness for this purpose.
  <tag>FWINRT<label id="command-FWINRT"></tag>
    Go right one window.
    This command is particularly useful when reading forward
    because it automatically wraps down to the beginning of the next line
    when invoked at the end of the current line.
    Other features like its ability to skip blank windows
    (see the <ref id="command-SKPBLNKWINS" name="SKPBLNKWINS"> command)
    further enhance its usefulness for this purpose.
  <tag>FWINLTSKIP<label id="command-FWINLTSKIP"></tag>
    Go left to the nearest previous non-blank window.
  <tag>FWINRTSKIP<label id="command-FWINRTSKIP"></tag>
    Go right to the nearest next non-blank window.
  <tag>LNBEG<label id="command-LNBEG"></tag>
    Go to the beginning (left) of the line.
  <tag>LNEND<label id="command-LNEND"></tag>
    Go to the end (right) 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.
</descrip>

<sect2>Feature Activation<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 translation 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 translation 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 passed lines which have the same content as the current line.
    This feature affects the <ref id="command-LNUP" name="LNUP">
    and <ref id="command-LNDN" name="LNDN"> commands,
    as well as the line wrapping feature of
    the <ref id="command-FWINLT" name="FWINLT">,
    <ref id="command-FWINRT" name="FWINRT">,
    <ref id="command-FWINLTSKIP" name="FWINLTSKIP">,
    and <ref id="command-FWINRTSKIP" name="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 passed blank windows when reading either forward or backward.
    This feature affects the <ref id="command-FWINLT" name="FWINLT">
    and <ref id="command-FWINRT" name="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.
</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.
    This command isn't available if the
    <ref id="build-preferences-menu" name="--disable-preferences-menu"> build option was specified.
  <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<label id="command-MENU_FIRST_ITEM"></tag>
    Go to the first item in the menu.
  <tag>MENU_LAST_ITEM<label id="command-MENU_LAST_ITEM"></tag>
    Go to the last item in the menu.
  <tag>MENU_PREV_ITEM<label id="command-MENU_PREV_ITEM"></tag>
    Go to the previous item in the menu.
  <tag>MENU_NEXT_ITEM<label id="command-MENU_NEXT_ITEM"></tag>
    Go to the next item in the menu.
  <tag>MENU_PREV_SETTING<label id="command-MENU_PREV_SETTING"></tag>
    Decrement the current menu item's setting.
  <tag>MENU_NEXT_SETTING<label id="command-MENU_NEXT_SETTING"></tag>
    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.
</descrip>

<sect2>Virtual Terminal Switching<p>
See also the <ref id="command-SWITCHVT" name="SWITCHVT"> routing key command.
<descrip>
  <tag>SWITCHVT_PREV<label id="command-SWITCHVT_PREV"></tag>
    Switch to the previous virtual terminal
    (the one whose number is one less than the current one).
  <tag>SWITCHVT_NEXT<label id="command-SWITCHVT_NEXT"></tag>
    Switch to the next virtual terminal
    (the one whose number is one greater than the current one).
</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>Routing Keys<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>SWITCHVT<label id="command-SWITCHVT"></tag>
    Switch to the virtual terminal whose number
    (counting from 1) matches that of the routing key.
  <tag>PRINDENT<label id="command-PRINDENT"></tag>
    Go up to the nearest previous line which isn't indented
    more than the column associated with the routing key.
  <tag>NXINDENT<label id="command-NXINDENT"></tag>
    Go down to the nearest next 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" name="CHRLT">,
    <ref id="command-CHRRT" name="CHRRT">,
    <ref id="command-HWINLT" name="HWINLT">,
    and <ref id="command-HWINRT" name="HWINRT"> 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/&num;/),
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 section <ref id="api" name="The Application Programming Interface">.
    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 translation table
    (see section <ref id="translation" name="Translation 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="--sysconfdir">
    and the <ref id="build-execute-root" name="--with-execute-root">
    build options for more details).
    See the <ref id="build-attributes-table" name="--with-attributes-table">
    build option for the default established during the build procedure.
    This directive can be overridden with the
    <ref id="options-attributes-table" name="-a"> command line option.
  <tag><tt/braille-driver/ <em/driver/<label id="configure-braille-driver"></tag>
    Specify the braille display driver.
    Either a two-letter <ref id="drivers" name="driver identification code">
    or the full path to a dynamically loadable shared object
    may be supplied.
    See the <ref id="build-braille-driver" name="--with-braille-driver">
    build option for the default established during the build procedure.
    This directive can be overridden with the
    <ref id="options-braille-driver" name="-b"> command line option.
  <tag><tt/braille-device/ <em/device/<label id="configure-braille-device"></tag>
    Specify the device to which the braille display is connected.
    The full path must be supplied.
    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-parameters/ <em/name/<tt/=/<em/value/<tt/,/...<label id="configure-braille-parameters"></tag>
    Specify parameters for the braille display driver.
    If the same parameter is specified more than once,
    then its rightmost assignment is used.
    For a description of the parameters accepted by a specific driver,
    please see the documentation for that driver.
    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="contraction" name="Contracted Braille"> for details).
    If a relative path is supplied, then it's anchored at <tt>/etc/brltty</>
    (see the <ref id="build-data-directory" name="--sysconfdir">
    and the <ref id="build-execute-root" name="--with-execute-root">
    build options for more details).
    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/preferences-file/ <em/file/<label id="configure-preferences-file"></tag>
    Specify the location of the preferences file.
    If it's not specified, then <tt>/etc/brltty-</tt><em/driver/<tt/.prefs/ is assumed,
    where <em/driver/ is a two-letter <ref id="drivers" name="driver identification code">.
    The preferences file doesn't need to exist.
    This directive can be overridden with the
    <ref id="options-preferences-file" name="-p"> command line option.
  <tag><tt/screen-parameters/ <em/name/<tt/=/<em/value/<tt/,/...<label id="configure-screen-parameters"></tag>
    Specify parameters for the screen driver.
    If the same parameter is specified more than once,
    then its rightmost assignment is used.
    For a description of the parameters accepted by a specific driver,
    please see the documentation for that driver.
    This directive can be overridden with the
    <ref id="options-screen-parameters" name="-X"> command line option.
  <tag><tt/speech-driver/ <em/driver/<label id="configure-speech-driver"></tag>
    Specify the speech synthesizer driver.
    Either a two-letter <ref id="drivers" name="driver identification code">
    or the full path to a dynamically loadable shared object
    may be supplied.
    See the <ref id="build-speech-driver" name="--with-speech-driver">
    build option for the default established during the build procedure.
    This directive can be overridden with the
    <ref id="options-speech-driver" name="-s"> command line option.
  <tag><tt/speech-parameters/ <em/name/<tt/=/<em/value/<tt/,/...<label id="configure-speech-parameters"></tag>
    Specify parameters for the speech synthesizer driver.
    If the same parameter is specified more than once,
    then its rightmost assignment is used.
    For a description of the parameters accepted by a specific driver,
    please see the documentation for that driver.
    This directive can be overridden with the
    <ref id="options-speech-parameters" name="-S"> command line option.
  <tag><tt/text-table/ <em/file/<label id="configure-text-table"></tag>
    Specify the text translation table
    (see section <ref id="translation" name="Translation 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="--sysconfdir">
    and the <ref id="build-execute-root" name="--with-execute-root">
    build options for more details).
    See the <ref id="build-text-table" name="--with-text-table">
    build option for the default established during the build procedure.
    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 translation table
    (see section <ref id="translation" name="Translation 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="--sysconfdir">
    and the <ref id="build-execute-root" name="--with-execute-root">
    build options for more details).
    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/--braille-driver=/<em/driver/<label id="options-braille-driver"></tag>
    Specify the braille display driver.
    Either a two-letter <ref id="drivers" name="driver identification code">
    or the full path to a dynamically loadable shared object
    may be supplied.
    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="contraction" name="Contracted Braille"> for details).
    If a relative path is supplied, then it's anchored at <tt>/etc/brltty</>
    (see the <ref id="build-data-directory" name="--sysconfdir">
    and the <ref id="build-execute-root" name="--with-execute-root">
    build options for more details).
    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/--braille-device=/<em/device/<label id="options-braille-device"></tag>
    Specify the device to which the braille display is connected.
    The full path must be supplied.
    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/-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/-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/file/ <tt/--preferences-file=/<em/file/<label id="options-preferences-file"></tag>
    Specify the location of the preferences file.
    The preferences file doesn't need to exist.
    See the <ref id="configure-preferences-file" name="preferences-file">
    configuration file directive for the default run-time setting.
  <tag><tt/-q/ <tt/--quiet/<label id="options-quiet"></tag>
    Log less information.
    This option changes the log level
    (see the <ref id="options-log-level" name="-l"> option)
    to <tt/notice/.
  <tag><tt/-s/<em/driver/ <tt/--speech-driver=/<em/driver/<label id="options-speech-driver"></tag>
    Specify the speech synthesizer driver.
    Either a two-letter <ref id="drivers" name="driver identification code">
    or the full path to a dynamically loadable shared object
    may be supplied.
    See the <ref id="configure-speech-driver" name="speech-driver">
    configuration file directive for the default run-time setting.
  <tag><tt/-t/<em/file/ <tt/--text-table=/<em/file/<label id="options-text-table"></tag>
    Specify the text translation table
    (see section <ref id="translation" name="Translation 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="--sysconfdir">
    and the <ref id="build-execute-root" name="--with-execute-root">
    build options for more details).
    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/--version/<label id="options-version"></tag>
    Display the current version of BRLTTY,
    identify the selected drivers,
    and then exit.
    If the <ref id="options-quiet" name="-q"> option isn't specified, then
    copyright information,
    and the parameter settings for each of the selected drivers
    are also displayed,
    and the working directory, the preferences file,
    the text and attributes translation tables,
    and the braille display device and help file are identified.
  <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 section <ref id="api" name="The Application Programming Interface">.
    See the <ref id="configure-api-parameters" name="api-parameters">
    configuration file directive for the default run-time setting.
  <tag><tt/-B/<em/name/<tt/=/<em/value/<tt/,/... <tt/--braille-parameters=/<em/name/<tt/=/<em/value/<tt/,/...<label id="options-braille-parameters"></tag>
    Specify parameters for the braille display driver.
    If the same parameter is specified more than once,
    then its rightmost assignment is used.
    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 setting.
  <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 translation 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_PREFERENCES_FILE/</tag>
        The preferences file
        (see the <ref id="options-preferences-file" name="-p"> 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_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 translation table
        (see the <ref id="options-text-table" name="-a"> command line option).
    </descrip>
  <tag><tt/-M/<em/csecs/ <tt/--message-delay=/<em/csecs/<label id="options-message-delay"></tag>
    Specify the message hold time (in hundredths of a second).
    If not specified, then <tt/400/ (4 seconds) is assumed.
    This is the amount of time that BRLTTY keeps its own
    internally generated messages on the braille display.
  <tag><tt/-N/ <tt/--no-speech/<label id="options-no-speech"></tag>
    Don't automatically start the speech synthesizer driver.
    This option is unfortunately necessary on some systems when BRLTTY is
    started before the sound subsystem within the kernel has been initialized.
  <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/<em/csecs/ <tt/--refresh-interval=/<em/csecs/<label id="options-refresh-interval"></tag>
    Specify the braille window refresh internal (in hundredths of a second).
    If not specified, then <tt/4/ (40 milliseconds) is assumed.
  <tag><tt/-S/<em/name/<tt/=/<em/value/<tt/,/... <tt/--speech-parameters=/<em/name/<tt/=/<em/value/<tt/,/...<label id="options-speech-parameters"></tag>
    Specify parameters for the speech synthesizer driver.
    If the same parameter is specified more than once,
    then its rightmost assignment is used.
    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 setting.
  <tag><tt/-X/<em/name/<tt/=/<em/value/<tt/,/... <tt/--screen-parameters=/<em/name/<tt/=/<em/value/<tt/,/...<label id="options-screen-parameters"></tag>
    Specify parameters for the screen driver.
    If the same parameter is specified more than once,
    then its rightmost assignment is used.
    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 setting.
</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" name="PRSEARCH">
and <ref id="command-NXSEARCH" name="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 braille window moves the pointer
(see the <ref id="preference-pointer-follows-window" name="Pointer Follows Window"> preference).
Any motion of the braille window (manual, cursor tracking, etc.),
other than when it moves in response to pointer motion,
moves the pointer to the character on the screen
which corresponds to the upper-left corner of the braille window.
This enables a sighted observer to see where the braille window is,
and, therefore, to know what the braille user is reading.
It also keeps the pointer within the braille window
so that it can be found easily,
and so that the pointer device can always be readily used
as another way to move the braille window.

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 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 identical lines are skipped.
   <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 a requested motion cannot be performed.
   <item>
     When a command cannot be executed.
   <item>
     When a lengthy command completes.
</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 default name for this file is <tt>/etc/brltty.conf</tt>.
A system default for its name can be established with
the <ref id="configure-preferences-file" name="preferences-file"> configuration file directive.
Its name can be explicitly set at run-time with
the <ref id="options-preferences-file" name="-p"> command line option.

<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.
This feature isn't available if the
<ref id="build-preferences-menu" name="--disable-preferences-menu"> build option was specified.

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/TOP_LEFT/</tag>
    Go to the first item in the menu
    (same as <ref id="command-MENU_FIRST_ITEM" name="MENU_FIRST_ITEM">).
  <tag><tt/BOT/, <tt/BOT_LEFT/</tag>
    Go to the last item in the menu
    (same as <ref id="command-MENU_LAST_ITEM" name="MENU_LAST_ITEM">).
  <tag><tt/LNUP/, <tt/CURSOR_UP/</tag>
    Go to the previous item in the menu
    (same as <ref id="command-MENU_PREV_ITEM" name="MENU_PREV_ITEM">).
  <tag><tt/LNDN/, <tt/CURSOR_DOWN/</tag>
    Go to the next item in the menu
    (same as <ref id="command-MENU_NEXT_ITEM" name="MENU_NEXT_ITEM">).
  <tag><tt/WINUP/, <tt/CHRLT/, <tt/CURSOR_LEFT/</tag>
    Decrement the current menu item's setting
    (same as <ref id="command-MENU_PREV_SETTING" name="MENU_PREV_SETTING">).
  <tag><tt/WINDN/, <tt/CHRRT/, <tt/CURSOR_RIGHT/, <tt/HOME/, <tt/RETURN/</tag>
    Increment the current menu item's setting
    (same as <ref id="command-MENU_NEXT_SETTING" name="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 each routing key represents an integer (starting from 0),
    and a selection which is out of range is silently brought into range.
    If the item has named settings,
    then the routing keys correspond ordinally with the settings.
  <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>Meta Mode<label id="preference-meta-mode"></tag>
    Enter a meta character by:
    <descrip>
      <tag/Escape Prefix/
        Prefixing it with an <tt/escape/ byte.
      <tag/High-order Bit/
        Setting its high-order bit.
    </descrip>
    Use the <tt/setmetamode/ command to find out how your system has been configured.
    The initial setting is <tt/Escape Prefix/.
  <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" name="LNUP">
    and <ref id="command-LNDN" name="LNDN"> commands,
    as well as the line wrapping feature of
    the <ref id="command-FWINLT" name="FWINLT">,
    <ref id="command-FWINRT" name="FWINRT">,
    <ref id="command-FWINLTSKIP" name="FWINLTSKIP">,
    and <ref id="command-FWINRTSKIP" name="FWINRTSKIP"> commands:
    <descrip>
      <tag/No/
        Don't skip passed lines which have the same content as the current line.
      <tag/Yes/
        Skip passed 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" name="FWINLT">
    and <ref id="command-FWINRT" name="FWINRT"> commands:
    <descrip>
      <tag/No/
        Don't skip passed blank windows.
      <tag/Yes/
        Skip passed 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/off/.
  <tag>Window Overlap<label id="preference-window-overlap"></tag>
    When moving either left or right with
    the <ref id="command-FWINLT" name="FWINLT">
    and <ref id="command-FWINRT" name="FWINRT"> commands,
    this setting specifies how many characters
    horizontally adjacent braille windows should overlap each other by.
    The initial setting is <tt/0/.
  <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.
  <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 Period<label id="preference-cursor-visible-period"></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/10/.
  <tag>Cursor Invisible Period<label id="preference-cursor-invisible-period"></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/10/.
  <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 Period<label id="preference-attributes-visible-period"></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/4/.
  <tag>Attributes Invisible Period<label id="preference-attributes-invisible-period"></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/12/.
  <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 Period<label id="preference-capitals-visible-period"></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/4/.
  <tag>Capitals Invisible Period<label id="preference-capitals-invisible-period"></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/2/.
  <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>Pointer Follows Window<label id="preference-pointer-follows-window"></tag>
    When moving the braille window:
    <descrip>
      <tag/No/
        Don't move the pointer (mouse).
      <tag/Yes/
        Move the pointer (mouse) to the character on the screen
        corresponding to the top-left corner of the braille window.
    </descrip>
    This preference is only presented if the
    <ref id="build-gpm" name="--enable-gpm"> build option was specified.
  <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.
  <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.
        It's always safe to use,
        although it may be somewhat soft.
        This device isn't available if the
        <ref id="build-beeper-tunes" name="--disable-beeper-tunes"> build option was specified.
      <tag/PCM/
        The digital audio interface on the sound card.
        This setting is supported on Linux (via <tt>/dev/dsp</>),
        and on Solaris (via <tt>/dev/audio</>).
        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-tunes" name="--disable-pcm-tunes"> 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-tunes" name="--disable-midi-tunes"> 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-tunes" name="--disable-fm-tunes"> 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>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>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>
  <tag>Autospeak<label id="preference-autospeak"></tag>
    <descrip>
      <tag/No/
        Only speak when explicitly requested to do so
        (see section <ref id="speech" name="Speech Controls">).
      <tag/Yes/
        This setting is experimental.
    </descrip>
  <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 zero) of the cursor
            (shown in the top half of the cells)
            and the top-left corner of the braille window
            (shown in the bottom half of the cells).
          <tag/3-4/
            The rows (counting from zero) of the cursor
            (shown in the top half of the cells)
            and the top-left corner of the braille window
            (shown in the bottom half of the cells).
          <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 0) corresponding to
            the top of the braille window (see below).
          <tag/2/
            The row (counting from 0) 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 0) 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>
    It's initial setting is braille display driver dependent.
  <tag>Text Table<label id="preference-text-table"></tag>
    Select the text translation table.
    See section <ref id="translation-text" name="Text Translation"> for details.
    See the <ref id="options-text-table" name="-t"> command line option for the initial setting.
    This preference isn't saved.
    It isn't presented if the
    <ref id="build-table-selection" name="--disable-table-selection"> build option was specified.
  <tag>Attributesw Table<label id="preference-attributes-table"></tag>
    Select the attributes translation table.
    See section <ref id="translation-attributes" name="Attributes Translation"> for details.
    See the <ref id="options-attributes-table" name="-a"> command line option for the initial setting.
    This preference isn't saved.
    It isn't presented if the
    <ref id="build-table-selection" name="--disable-table-selection"> build option was specified.
  <tag>Contraction Table<label id="preference-contraction-table"></tag>
    Select the contraction table.
    See section <ref id="contraction" name="Contracted Braille"> for details.
    See the <ref id="options-contraction-table" name="-c"> command line option for the initial setting.
    This preference isn't saved.
    It isn't presented if the
    <ref id="build-table-selection" name="--disable-table-selection"> build option was specified.
</descrip>

Notes:
<itemize>
  <item><label id="time-settings">
    All time settings are in braille window refresh intervals
    (see the <ref id="options-refresh-interval" name="-M"> command line option).
    They are integers within the range 1 through 16.
</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 0) 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 0) 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 0) on the screen corresponding
    to the position of the cursor (shown in the top half of the cells)
    and to the top-left corner of the braille window (shown in the bottom half of the cells).
  <tag><em/yy/</tag>
    The rows (counting from 0) on the screen corresponding
    to the position of the cursor (shown in the top half of the cells)
    and to the top-left corner of the braille window (shown in the bottom half of the cells).
  <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.

<sect1>Contracted Braille<label id="contraction"><p>
BRLTTY can display in-line contracted braille.
It does this 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/big5.ctb/Chinese big5.
  <tag/compress.ctb/Remove excessive white-space.
  <tag/en-us-g2.ctb/Grade 2 American English.
</descrip>

<sect2>File Format<p>
Blank lines are ignored.
Any leading and trailing white-space (any number of blanks and/or tabs) is ignored.
Lines which begin with a number sign (<tt/&num;/) are ignored,
i.e. they're comments.
<tscreen>&num; This is a comment.</tscreen>
All other lines define table entries.

The general form of a table entry is an opcode followed by its operands.
The opcode and its operands are separated from one another by white-space.
Each opcode has a specific number of operands,
and any text following its last operand is treated as a comment.
<tscreen><em/opcode/ <em/operand/ ... <em/comment/</tscreen>

The opcode is a number which tells the translator how to interpret the operands.
Opcode <tt/0/ can be used to assign a meaningful name to each needed opcode,
e.g. <tt/opcode/ for <tt/0/ itself.
If, for example, a table begins with:
<tscreen>0 0 opcode</tscreen>
then all the rest of the opcodes it needs can be defined like this:
<tscreen>opcode 1 include</tscreen>
This scheme, i.e. no built-in opcode names, was chosen in order to allow
a table for some language's braille to be written solely in that language itself.

The following operand types are supported:
<descrip>
  <tag/string/
    A sequence of characters other than
    white-space (which terminates the string)
    and backslashes (<tt/&bsol;/).
    The following special representations are also supported:
    <descrip>
      <tag><tt/&bsol;&bsol;/</tag>backslash
      <tag><tt/&bsol;f/</tag>form feed
      <tag><tt/&bsol;n/</tag>new line
      <tag><tt/&bsol;o/<em/ooo/</tag>3-digit octal value
      <tag><tt/&bsol;r/</tag>carriage return
      <tag><tt/&bsol;s/</tag>blank (space)
      <tag><tt/&bsol;t/</tag>horizontal tab
      <tag><tt/&bsol;v/</tag>vertical tab
      <tag><tt/&bsol;x/<em/xx/</tag>2-digit hexadecimal value
    </descrip>
  <tag/number/
    An integer.
    It may be specified in any of the following ways:
    <descrip>
      <tag/decimal/
        A sequence of decimal digits (<tt/0/-<tt/9/),
        with the first digit being nonzero (<tt/1/-<tt/9/).
      <tag/hexadecimal/
        A sequence of hexadecimal digits (<tt/0/-<tt/9/, and either <tt/a/-<tt/f/ or <tt/A/-<tt/F/),
        preceded by either <tt/0x/ or <tt/0X/.
      <tag/octal/
        A sequence of octal digits (<tt/0/-<tt/7/),
        with the first digit being zero (<tt/0/).
    </descrip>
  <tag/dots/
    A braille symbol.
    The braille dots must be specified via their standard numbers
    (see section <ref id="dots" name="Braille Dot Numbering Convention">),
    and, for a multi-cell symbol, the cell specifications
    must be separated from one another by a dash (<tt/-/).
    For example, the contraction for the English word <tt/lord/
    (the letter <tt/l/ prefixed with dot 5)
    would be specified as <tt/5-123/.
    A space may be specified via the special dot number <tt/0/.
</descrip>

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

<sect2>Opcodes by Function<label id="contraction-opcode-function"><p>
Now for all of the details.
The opcodes here are grouped by function rather than sorted by number.
For a numerically sorted list, see section
<ref id="contraction-opcode-number" name="Opcode Summary by Number">.

<sect3>Table Administration<p>
These opcodes make it easier to write contraction tables.
They have no direct effect on the character translation.
<descrip>
  <tag>0 <em/opcode/ <em/name/<label id="contraction-opcode-0"></tag>
    Assign a name to an opcode.
    The name must be defined before it's used.
  <tag>1 <em/path/<label id="contraction-opcode-1"></tag>
    Include the contents of another file.
    Nesting can be to any depth.
    Relative paths are anchored at the directory of the including file.
</descrip>

<sect3>Special Symbol Definition<p>
These opcodes define special symbols which must be
inserted into the braille text in order to clarify it.
<descrip>
  <tag>2 <em/dots/<label id="contraction-opcode-2"></tag>
    The symbol which capitalizes a single letter.
  <tag>3 <em/dots/<label id="contraction-opcode-3"></tag>
    The symbol which begins a block of capital letters within a word.
  <tag>25 <em/dots/<label id="contraction-opcode-25"></tag>
    The symbol which ends a block of capital letters within a word.
  <tag>4 <em/dots/<label id="contraction-opcode-4"></tag>
    The symbol which marks a letter which isn't part of a word.
  <tag>5 <em/dots/<label id="contraction-opcode-5"></tag>
    The symbol which marks the beginning of a number.
</descrip>

<sect3>Character 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-6" name="opcode 6">)
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>17 <em/characters/<label id="contraction-opcode-17"></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>19 <em/characters/ <em/characters/<label id="contraction-opcode-19"></tag>
    Replace the first set of characters, no matter where they appear, with the second.
    The replaced characters aren't reprocessed.
  <tag>6 <em/characters/ <em/dots/<label id="contraction-opcode-6"></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>7 <em/characters/ <em/dots/<label id="contraction-opcode-7"></tag>
    Translate the characters no matter where they appear.
    Ignore any consecutive repetitions of the same sequence.
  <tag>15 <em/characters/ <em/dots/<label id="contraction-opcode-15"></tag>
    Translate the characters no matter where they appear.
    Remove white-space between consecutive words matched by this opcode.
  <tag>8 <em/characters/ <em/dots/<label id="contraction-opcode-8"></tag>
    Translate the characters if they're a word.
  <tag>16 <em/characters/ <em/dots/<label id="contraction-opcode-16"></tag>
    Translate the characters if they're a word.
    Remove the following white-space if the first character after it is a letter.
  <tag>14 <em/characters/ <em/dots/<label id="contraction-opcode-14"></tag>
    Translate the characters if they're a white-space-bounded word.
  <tag>18 <em/characters/<label id="contraction-opcode-18"></tag>
    Prefix the characters with a letter sign
    (see <ref id="contraction-opcode-4" name="opcode 4">)
    if they're a word.
  <tag>24 <em/characters/ <em/dots/<label id="contraction-opcode-24"></tag>
    Translate the characters if they're either a word or at the beginning of a word.
  <tag>9 <em/characters/ <em/dots/<label id="contraction-opcode-9"></tag>
    Translate the characters if they're at the beginning of a word.
  <tag>10 <em/characters/ <em/dots/<label id="contraction-opcode-10"></tag>
    Translate the characters if they're in the middle of a word.
  <tag>12 <em/characters/ <em/dots/<label id="contraction-opcode-12"></tag>
    Translate the characters if they're either in the middle or at the end of a word.
  <tag>11 <em/characters/ <em/dots/<label id="contraction-opcode-11"></tag>
    Translate the characters if they're at the end of a word.
  <tag>22 <em/characters/ <em/dots/<label id="contraction-opcode-22"></tag>
    Translate the characters if they're part of punctuation at the beginning of a word.
  <tag>23 <em/characters/ <em/dots/<label id="contraction-opcode-23"></tag>
    Translate the characters if they're part of punctuation at the end of a word.
  <tag>21 <em/characters/ <em/dots/<label id="contraction-opcode-21"></tag>
    Translate the characters if they're at the beginning of a number.
  <tag>13 <em/characters/ <em/dots/<label id="contraction-opcode-13"></tag>
    Translate the characters if they're in the middle of a number.
  <tag>20 <em/characters/ <em/dots/<label id="contraction-opcode-20"></tag>
    Translate the characters if they're at the end of a number.
</descrip>

<sect>Translation Tables<label id="translation"><p>
BRLTTY uses two <bf/translation tables/ to govern
the mapping from bytes to dot combinations.

<sect1>Text Translation<label id="translation-text"><p>
The first, and most important, is the text translation table.
BRLTTY is initially configured to use the
<ref id="nabcc" name="North American Braille Computer Code"> (NABCC).
In addition to this default text translation table,
several alternatives are provided:
<descrip>
  <tag/text.danish.tbl/Danish
  <tag/text.es.tbl/Spanish
  <tag/text.french.tbl/French
  <tag/text.german.tbl/German
  <tag/text.it.tbl/Italian
  <tag/text.no-h.tbl/Norwegian and German
  <tag/text.no-p.tbl/Norwegian
  <tag/text.pl-iso02.tbl/Polish (iso-8859-2)
  <tag/text.simple.tbl/American English
  <tag/text.sweden.tbl/Swedish
  <tag/text.swedish.tbl/Swedish
  <tag/text.uk.tbl/United Kingdom English
  <tag/text.us.tbl/American English
</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 translation table.

<sect1>Attributes Translation<label id="translation-attributes"><p>
The attributes translation table is 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 attribute bits.
Two attributes translation tables are provided:
<descrip>
  <tag/attributes.tbl/
    The lefthand column represents the background colours:
    <descrip>
      <tag/Dot 1/Red
      <tag/Dot 2/Green
      <tag/Dot 3/Blue
      <tag/Dot 7/Blink
    </descrip>
    The righthand column represents the foreground colours:
    <descrip>
      <tag/Dot 4/Red
      <tag/Dot 5/Green
      <tag/Dot 6/Blue
      <tag/Dot 8/Bright
    </descrip>
    A dot is raised when its corresponding attribute bit is on.
    This is the default attributes translation 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.tbl/
    The lefthand column represents the background colours:
    <descrip>
      <tag/Dot 1/Red
      <tag/Dot 2/Green
      <tag/Dot 3/Blue
      <tag/Dot 7/Blink
    </descrip>
    The righthand column represents the foreground colours:
    <descrip>
      <tag/Dot 4/Red
      <tag/Dot 5/Green
      <tag/Dot 6/Blue
      <tag/Dot 8/Bright
    </descrip>
    A foreground bit being on triggers its corresponding dot,
    whereas a background 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 translation table.

<sect1>Table Format<p>
A translation table is a 256-byte binary file.
It's indexed with either a character or an attributes byte,
and the byte at that position contains the corresponding dot combination.
The mapping from bit to dot is as follows:
<descrip>
  <tag/Bit 0/Dot 1
  <tag/Bit 1/Dot 4
  <tag/Bit 2/Dot 2
  <tag/Bit 3/Dot 5
  <tag/Bit 4/Dot 3
  <tag/Bit 5/Dot 6
  <tag/Bit 6/Dot 7
  <tag/Bit 7/Dot 8
</descrip>
This particular mapping makes it easy and efficient for BRLTTY
to vertically shift a dot pattern.

<sect1>Table Utilities<p>
These utilities reside within the <tt/BrailleTables/ subdirectory,
and aren't built as part of the regular procedure.
To build them,
first ensure that BRLTTY has been configured
(see section <ref id="build" name="Build Options">),
and then run <tt/make/ within the <tt/BrailleTables/ subdirectory.
<tscreen><verb>
cd BrailleTables
make
</verb></tscreen>

<sect2>tbl2txt<label id="utility-tbl2txt"><p>
This utility converts (uncompiles) a translation table into a text file
for readability and/or modification.
<tscreen>tbl2txt -<em/option/ ... <em/table-file/ <em/text-file/</tscreen>
<descrip>
  <tag><em/table-file/</tag>
    The translation table which is to be converted.
  <tag><em/text-file/</tag>
    The file into which the text representing the table content is to be written.
  <tag><tt/-c/<em/name/ <tt/--code-page=/<em/name/</tag>
    The character set used to annotate each line of the text file.
</descrip>

The generated text file can, without modification, be recompiled back into a
translation table with the <ref id="utility-txt2tbl" name="txt2tbl"> utility.
Each of its lines contains lots of interesting information.

If the <tt/-c/ option isn't specified, each line looks like this:
<tscreen><em/cc/ <em/xx/ <em/ddd/ (73214568)<em/tt/ B+<em/bbbb/ <em/name/</tscreen>
If the <tt/-c/ option is specified, each line looks like this:
<tscreen><em/cc/ <em/xx/ <em/ddd/ (73214568)<em/tt/ B+<em/bbbb/ U+<em/uuuu/ <em/description/</tscreen>
<descrip>
  <tag><em/cc/</tag>
    The character itself.
    Unprintable characters are represented canonically.
    Control characters are flagged with a circumflex,
    e.g. Control-A (character 1) is <tt/&circ;A/. 
    Meta control characters are flagged with a tilde,
    e.g. Meta-Control-A (character 129) is <tt/&tilde;A/. 
  <tag><em/xx/</tag>
    The hexadecimal value of the character.
  <tag><em/ddd/</tag>
    The decimal value of the character.
  <tag><tt/(73214568)/</tag>
    The braille dot numbers.
    If a dot isn't to be raised,
    then its number is replaced with a blank.
    The English letter <tt/y/, for example, would be
    <tt/(&nbsp;3&nbsp;1456&nbsp;)/.
    The dot numbers appear in the same order
    as on a standard braille keyboard
    so as to make it easier to visualize the braille character.
  <tag><em/tt/</tag>
    The hexadecimal value of the byte representing the dot combination
    which is in the translation table.
  <tag><em/bbbb/</tag>
    The hexadecimal value of the unicode number
    corresponding to the dot combination.
  <tag><em/name/</tag>
    The ASCII name of the character
    (only shown if the <tt/-c/ option isn't specified).
  <tag><em/uuuu/</tag>
    The hexadecimal value of the unicode number
    corresponding to the character
    (only shown if the <tt/-c/ option is specified).
  <tag><em/description/</tag>
    The formal unicode description for the character
    (only shown if the <tt/-c/ option is specified).
</descrip>

<sect2>txt2tbl<label id="utility-txt2tbl"><p>
This utility compiles a translation table.
<tscreen>txt2tbl -<em/option/ ... <em/text-file/ <em/table-file/</tscreen>
<descrip>
  <tag><em/text-file/</tag>
    The source file describing the table content.
  <tag><em/table-file/</tag>
    The file into which the translation table is to be written.
  <tag><tt/-d/ <tt/--duplicates/</tag>
    Display a warning for each dot combination which has been used more than once.
  <tag><tt/-m/ <tt/--missing/</tag>
    Display a warning for each dot combination which hasn't been used.
</descrip>

A line which assigns a dot combination to a character
must contain that dot combination within parenthesis, e.g. <tt/(12)/.
The text file must contain exactly 256 such lines, each one, in order,
defining the braille representation for its corresponding character.
The dot numbers may be specified in any order,
but each must only be specified once.
It's valid to specify no number at all, e.g. <tt/()/ (for a space).
Any number of spaces may occur any number of times anywhere between the parentheses.
All characters before the left parenthesis and after the right parenthesis are ignored.
All lines which don't contain a left parenthesis are ignored.

The algorithm for locating the dot numbers is actually a bit more complicated
because a line may contain more than one left and/or right parenthesis
(the <ref id="utility-tbl2txt" name="tbl2txt"> utility does this).
The first right parenthesis which is preceded by at least one left parenthesis is used.
The nearest left parenthesis to the left of that right parenthesis is used.
The line <tt/)((12)/, for example, is valid.

<sect2>tbl2tbl<label id="utility-tbl2tbl"><p>
This utility converts a binary translation table from one dot mapping to another.
<tscreen>tbl2tbl <em/input-mapping/ <em/output-mapping/</tscreen>
<descrip>
  <tag><em/input-mapping/</tag>
    The dot mapping used within the source table.
  <tag><em/output-mapping/</tag>
    The dot mapping to be used within the table being generated.
</descrip>
The source table is read from standard input,
and the converted table is written to standard output.
The following dot mappings are supported:
<descrip>
  <tag/standard/
    BRLTTY's native mapping (described above).
  <tag/tieman/
    The mapping used by <htmlurl url="http://www.braillevoyager.nl/uk/index.html" name="Tieman B.V.">.
    <descrip>
      <tag/Bit 0/Dot 1
      <tag/Bit 1/Dot 2
      <tag/Bit 2/Dot 3
      <tag/Bit 3/Dot 7
      <tag/Bit 4/Dot 8
      <tag/Bit 5/Dot 6
      <tag/Bit 6/Dot 5
      <tag/Bit 7/Dot 4
    </descrip>
  <tag/alva/
    The mapping used by <htmlurl url="http://www.alva-bv.nl/alvacorp/alva_corp_home.html" name="Alva B.V.">
    and <htmlurl url="http://www.telesensory.com" name="Telesensory Systems Inc.">.
    <descrip>
      <tag/Bit 0/Dot 1
      <tag/Bit 1/Dot 2
      <tag/Bit 2/Dot 3
      <tag/Bit 3/Dot 4
      <tag/Bit 4/Dot 5
      <tag/Bit 5/Dot 6
      <tag/Bit 6/Dot 7
      <tag/Bit 7/Dot 8
    </descrip>
</descrip>

<sect>The Application Programming Interface<label id="api"><p>
This section hasn't been written yet.

<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="--sysconfdir">
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/Socket Interface/
    A mechanism allowing screen readers and X display interpreters
    to easily make full use of all braille dsplays supported by BRLTTY.
  <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.

<sect>Appendices<p>

<sect1>Supported Braille Displays<label id="displays"><p>
BRLTTY supports the following braille displays:
<itemize>
  <item>
    <htmlurl url="http://www.alva-bv.nl/alvacorp/alva_corp_home.html" name="Alva B.V.">:
    ABT3xx,
    Delphi (serial and parallel ports),
    Satellite
  <item>
    <htmlurl url="http://www.baum.de/English/homeeng1.htm" name="Baum">:
    Vario/RBT 40/80 (emulation 1/2)
  <item>
    <htmlurl url="http://www.blazie.com/pages/main.html" name="Blazie Engineering">:
    BrailleLite 18/40/M40
  <item>
    <htmlurl url="http://www.eurobraille.fr/Indexuk.htm" name="EuroBraille">:
    AzerBraille,
    Clio,
    Iris,
    NoteBraille,
    Scriba
  <item>
    <htmlurl url="http://www.handialog.com/indexuk.htm" name="Handialog">:
    VisioBraille 2040
  <item>
    <htmlurl url="http://www.handytech.com/" name="Handy Tech Elektronik GmbH">:
    Bookworm,
    Braille Star 40/80,
    Braille Wave,
    Modular 20/40/80
  <item>
    <htmlurl url="http://cidat.once.es/" name="La O.N.C.E.">:
    EcoBraille 20/40/80
  <item>
    <htmlurl url="http://www.cavazza.it/cnt/schede/scheda-mb408l-eng.html" name="MDV">:
    MB208/MB408L/MB408S (protocol 5)
  <item>
    <htmlurl url="http://www.papenmeier.de/" name="Papenmeier">:
    Tiny,
    Compact,
    Compact 486,
    2D Lite,
    2D Screen Soft,
    EL 2D-40,
    EL 2D-66,
    EL 2D-80,
    EL 40,
    EL 80,
    Elba 20,
    Elba 32,
    IB 80 CR Soft
  <item>
    <htmlurl url="http://www.pulsedata.co.nz/" name="Pulse Data International">:
    BrailleNote 18/32
  <item>
    <htmlurl url="http://www.telesensory.com/" name="Telesensory Systems Inc.">:
    Navigator 20/40/80 (latest firmware version only),
    PowerBraille 40/65/80
  <item>
    Tactilog:
    LogText
  <item>
    <htmlurl url="http://www.braillevoyager.nl/uk/index.html" name="Tieman B.V.">:
    CombiBraille 25/45/85,
    MiniBraille 20,
    MultiBraille MB125CR/MB145CR/MB185CR,
    Voyager 44/70 (USB)
  <item>
    <htmlurl url="http://www.tinlecco.it/tiflosoft" name="Tiflosoft">:
    VideoBraille 40
</itemize>

<sect1>Supported Speech Synthesizers<label id="synthesizers"><p>
BRLTTY supports the following speech synthesizers:
<itemize>
  <item>
    <htmlurl url="http://www.alva-bv.nl/alvacorp/alva_corp_home.html" name="Alva B.V.">:
    Delphi
  <item>
    <htmlurl url="http://www.blazie.com/pages/main.html" name="Blazie Engineering">:
    BrailleLite
  <item>
    <htmlurl url="http://www.elan.fr/" name="Elan Informatique">:
    Televox
  <item>
    <htmlurl url="http://www.ibm.com/" name="International Business Machines (IBM)">:
    <htmlurl url="http://www.ibm.com/software/speech/dev/ttssdk_linux.html" name="ViaVoice">
  <item>
    <htmlurl url="http://www.braillevoyager.nl/uk/index.html" name="Tieman B.V.">:
    CombiBraille
  <item>
    <htmlurl url="http://www.ed.ac.uk/" name="The University of Edinburgh">
    (<htmlurl url="http://www.cstr.ed.ac.uk/" name="Centre for Speech Technology Research">):
    <htmlurl url="http://www.cstr.ed.ac.uk/projects/festival/" name="Festival">
</itemize>

<sect1>Driver Identification Codes<label id="drivers"><p>
<descrip>
  <tag/al/Alva
  <tag/bl/BrailleLite
  <tag/bn/BrailleNote
  <tag/cb/CombiBraille
  <tag/ec/EcoBraille
  <tag/es/ExternalSpeech
  <tag/eu/EuroBraille
  <tag/fv/Festival
  <tag/gs/GenericSay
  <tag/ht/HandyTech
  <tag/lt/LogText
  <tag/mb/MultiBraille
  <tag/md/MDV
  <tag/mn/MiniBraille
  <tag/no/no driver
  <tag/pm/Papenmeier
  <tag/ts/Telesensory Systems Inc.
  <tag/tv/Televox
  <tag/va/Vario/RBT (emulation 1)
  <tag/vd/VideoBraille
  <tag/vh/Vario/RBT (emulation 2)
  <tag/vo/Voyager
  <tag/vs/VisioBraille
  <tag/vv/ViaVoice
</descrip>

<sect1>Braille Dot Numbering Convention<label id="dots"><p>
A standard braille cell consists of six dots
arranged in two columns and three rows.
Computer braille has introduced a fourth row at the bottom.
Each dot can be specifically identified by its number as follows:
<descrip>
  <tag/1/Row 1 (top) left.
  <tag/2/Row 2 left.
  <tag/3/Row 3 left.
  <tag/4/Row 1 (top) right.
  <tag/5/Row 2 right.
  <tag/6/Row 3 right.
  <tag/7/Row 4 (bottom) left.
  <tag/8/Row 4 (bottom) right.
</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>

<sect1>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>

<sect1>MIDI Instrument Table<label id="midi"><p>
<descrip>
  <tag/Piano/
    Acoustic Grand Piano
    <newline>
    Bright Acoustic Piano
    <newline>
    Electric Grand Piano
    <newline>
    Honkytonk Piano
    <newline>
    Electric Piano 1
    <newline>
    Electric Piano 2
    <newline>
    Harpsichord
    <newline>
    Clavi
  <tag/Chromatic Percussion/
    Celesta
    <newline>
    Glockenspiel
    <newline>
    Music Box
    <newline>
    Vibraphone
    <newline>
    Marimba
    <newline>
    Xylophone
    <newline>
    Tubular Bells
    <newline>
    Dulcimer
  <tag/Organ/
    Drawbar Organ
    <newline>
    Percussive Organ
    <newline>
    Rock Organ
    <newline>
    Church Organ
    <newline>
    Reed Organ
    <newline>
    Accordion
    <newline>
    Harmonica
    <newline>
    Tango Accordion
  <tag/Guitar/
    Nylon Acoustic Guitar
    <newline>
    Steel Acoustic Guitar
    <newline>
    Jazz Electric Guitar
    <newline>
    Clean Electric Guitar
    <newline>
    Muted Electric Guitar
    <newline>
    Overdriven Guitar
    <newline>
    Distortion Guitar
    <newline>
    Guitar Harmonics
  <tag/Bass/
    Acoustic Bass
    <newline>
    Finger Electric Bass
    <newline>
    Pick Electric Bass
    <newline>
    Fretless Bass
    <newline>
    Slap Bass 1
    <newline>
    Slap Bass 2
    <newline>
    Synth Bass 1
    <newline>
    Synth Bass 2
  <tag/Strings/
    Violin
    <newline>
    Viola
    <newline>
    Cello
    <newline>
    Contrabass
    <newline>
    Tremolo Strings
    <newline>
    Pizzicato Strings
    <newline>
    Orchestral Harp
    <newline>
    Timpani
  <tag/Ensemble/
    String Ensemble 1
    <newline>
    String Ensemble 2
    <newline>
    Synth Strings 1
    <newline>
    Synth Strings 2
    <newline>
    Choir Aahs
    <newline>
    Voice Oohs
    <newline>
    Synth Voice
    <newline>
    Orchestra Hit
  <tag/Brass/
    Trumpet
    <newline>
    Trombone
    <newline>
    Tuba
    <newline>
    Muted Trumpet
    <newline>
    French Horn
    <newline>
    Brass Section
    <newline>
    Synth Brass 1
    <newline>
    Synth Brass 2
  <tag/Reed/
    Soprano Saxophone
    <newline>
    Alto Saxophone
    <newline>
    Tenor Saxophone
    <newline>
    Baritone Saxophone
    <newline>
    Oboe
    <newline>
    English Horn
    <newline>
    Bassoon
    <newline>
    Clarinet
  <tag/Pipe/
    Piccolo
    <newline>
    Flute
    <newline>
    Recorder
    <newline>
    Pan Flute
    <newline>
    Blown Bottle
    <newline>
    Shakuhachi
    <newline>
    Whistle
    <newline>
    Ocarina
  <tag/Synth Lead/
    Lead 1 (square)
    <newline>
    Lead 2 (sawtooth)
    <newline>
    Lead 3 (calliope)
    <newline>
    Lead 4 (chiff)
    <newline>
    Lead 5 (charang)
    <newline>
    Lead 6 (voice)
    <newline>
    Lead 7 (fifths)
    <newline>
    Lead 8 (bass + lead)
  <tag/Synth Pad/
    Pad 1 (new age)
    <newline>
    Pad 2 (warm)
    <newline>
    Pad 3 (polysynth)
    <newline>
    Pad 4 (choir)
    <newline>
    Pad 5 (bowed)
    <newline>
    Pad 6 (metallic)
    <newline>
    Pad 7 (halo)
    <newline>
    Pad 8 (sweep)
  <tag/Synth FM/
    FX 1 (rain)
    <newline>
    FX 2 (soundtrack)
    <newline>
    FX 3 (crystal)
    <newline>
    FX 4 (atmosphere)
    <newline>
    FX 5 (brightness)
    <newline>
    FX 6 (goblins)
    <newline>
    FX 7 (echoes)
    <newline>
    FX 8 (science-fiction)
  <tag/Ethnic/
    Sitar
    <newline>
    Banjo
    <newline>
    Shamisen
    <newline>
    Koto
    <newline>
    Kalimba
    <newline>
    Bag Pipe
    <newline>
    Fiddle
    <newline>
    Shanai
  <tag/Percussive/
    Tinkle Bell
    <newline>
    Agogo
    <newline>
    Steel Drum
    <newline>
    Wooden Block
    <newline>
    Taiko Drum
    <newline>
    Melodic Tom
    <newline>
    Synth Drum
    <newline>
    Reverse Cymbal
  <tag/Sound Effects/
    Guitar Fret Noise
    <newline>
    Breath Noise
    <newline>
    Seashore
    <newline>
    Bird Tweet
    <newline>
    Telephone Ring
    <newline>
    Helicopter
    <newline>
    Applause
    <newline>
    Gunshot
</descrip>

<sect>Epilogue<p>

<sect1>Contact Information<label id="contact"><p>
For up-to-date information, see our web page at
[<htmlurl url="http://mielke.cc/brltty/" name="http://mielke.cc/brltty/">].

BRLTTY represents the work of a team, which includes:
<itemize>
  <item>
    <htmlurl url="http://mielke.cc/" name="Dave Mielke">
    <tt><htmlurl url="mailto:dave@mielke.cc" name="&lt;dave@mielke.cc&gt;"></tt>
    (current maintainer, active developer)
  <item>
    <htmlurl url="http://www.cam.org/~nico/" name="Nicolas Pitre">
    <tt><htmlurl url="mailto:nico@cam.org" name="&lt;nico@cam.org&gt;"></tt>
    (active developer)
  <item>
    <htmlurl url="http://pages.infinit.net/sdoyon/" name="Stéphane Doyon">
    <tt><htmlurl url="mailto:s.doyon@videotron.ca" name="&lt;s.doyon@videotron.ca&gt;"></tt>
    (active developer)
  <item>
    Nikhil Nair 
    <tt><htmlurl url="mailto:nn201@cus.cam.ac.uk" name="&lt;nn201@cus.cam.ac.uk&gt;"></tt>
    (original author, no longer active)
</itemize>

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

<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/COPYING/ 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.

</article>
