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="<nn201@cus.cam.ac.uk>"></tt> <and> <name>Nicolas Pitre <tt><htmlurl url="mailto:nico@cam.org" name="<nico@cam.org>"></tt> <and> <name>Stéphane Doyon <tt><htmlurl url="mailto:s.doyon@videotron.ca" name="<s.doyon@videotron.ca>"></tt> <and> <name>Dave Mielke <tt><htmlurl url="mailto:dave@mielke.cc" name="<dave@mielke.cc>"></tt> <date>Version 3.2, February 2003 <abstract> Copyright © 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. </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-install-brltty" name="install-brltty"></tag> A <ref id="utility-install-brltty" name="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/*.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 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 isn't specified, then all of the braille display drivers are built as dynamically loadable shared objects, and the needed one can be selected at run-time. If it is specified, then only that driver is compiled, and 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 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 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 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 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 isn't specified, then all of the speech synthesizer drivers are built as dynamically loadable shared objects, and the needed one can be selected at run-time. If it is specified, then only that driver is compiled, and 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. <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">). </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 ] then /bin/brltty fi </verb></tscreen> This can usually be abbreviated to the somewhat less readable form: <tscreen><verb> [ -x /bin/brltty ] && /bin/brltty </verb></tscreen> Don't add these lines before the first line (which usually looks like <tt>#!/bin/sh</>). If the braille display is to be used by a system administrator, then it should probably be started as early as possible during the boot sequence (like before the file systems are checked) so that the display is usable in the event that something goes wrong during these checks and the system drops into single user mode. Again, exactly where it's best to do this is distribution-dependent. Here are the places we know about so far: <descrip> <tag>Debian</tag> <tt>/etc/init.d/boot</> for older releases, and <tt>/etc/init.d/rcS</> for newer releases. <tag>RedHat</tag> <tt>/etc/rc.d/rc.sysinit</> Beware that later releases, in order to support a more user-oriented system initialization procedure, have this script reinvoke itself such that it's under the control of <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&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>install-brltty<label id="utility-install-brltty"><p> This utility copies BRLTTY's <ref id="hierarchy" name="installed file hierarchy"> from one location to another. <tscreen>install-brltty <em/to/ [<em/from/]</tscreen> <descrip> <tag><em/to/</tag> The location to which the <ref id="hierarchy" name="installed file hierarchy"> is to be copied. It must be an existing directory. <tag><em/from/</tag> The location from which the <ref id="hierarchy" name="installed file hierarchy"> is to be taken. If it's specified, then it must be an existing directory. If it's not specified, then the location used for the build is assumed. </descrip> This utility can be used, for example, to copy BRLTTY to a root disk. If a root floppy is mounted as <tt>/mnt</>, and BRLTTY is installed on the main system, then typing <tscreen>install-brltty /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/-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: [<em/column/,<em/row/]</tscreen> <item> A line detailing the size of the selected screen region, and the position (zero-origin) of its top-left corner. <tscreen>Region: <em/width/x<em/height/@[<em/column/,<em/row/]</tscreen> <item> The contents of the selected screen region. Unprintable characters are written as blanks. </enum> <sect2>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<p> <descrip> <tag>SAY<label id="command-SAY"></tag> Speak the current line. <tag>SAYALL<label id="command-SAYALL"></tag> Speak the rest 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/#/), and continues to the end of the line. The following directives are recognized: <descrip> <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/-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_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, 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>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/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/#/) are ignored, i.e. they're comments. <tscreen># 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/\/). The following special representations are also supported: <descrip> <tag><tt/\\/</tag>backslash <tag><tt/\f/</tag>form feed <tag><tt/\n/</tag>new line <tag><tt/\o/<em/ooo/</tag>3-digit octal value <tag><tt/\r/</tag>carriage return <tag><tt/\s/</tag>blank (space) <tag><tt/\t/</tag>horizontal tab <tag><tt/\v/</tag>vertical tab <tag><tt/\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/</tag> Ignore unconditionally. <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/<label id="contraction-opcode-19"></tag> Ignore the characters no matter where they appear. <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/ˆA/. Meta control characters are flagged with a tilde, e.g. Meta-Control-A (character 129) is <tt/˜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/( 3 1456 )/. 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>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 <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="<dave@mielke.cc>"></tt> (current maintainer, active developer) <item> <htmlurl url="http://www.cam.org/~nico/" name="Nicolas Pitre"> <tt><htmlurl url="mailto:nico@cam.org" name="<nico@cam.org>"></tt> (active developer) <item> <htmlurl url="http://pages.infinit.net/sdoyon/" name="Stéphane Doyon"> <tt><htmlurl url="mailto:s.doyon@videotron.ca" name="<s.doyon@videotron.ca>"></tt> (active developer) <item> Nikhil Nair <tt><htmlurl url="mailto:nn201@cus.cam.ac.uk" name="<nn201@cus.cam.ac.uk>"></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>