System Requirements
===================

The earliest release of Windows which is supported by BRLTTY is Windows 98.

In order to build BRLTTY from a supplied tarball, you need either Cygwin (see
[http://www.cygwin.com/]) or MinGW (see [http://mingw.sourceforge.net/]). In 
both cases, you also need the following additional packages:
*  gcc
*  make
*  w32api (version 3.6 or later)
*  yacc or bison

If you'd like to build BRLTTY from its source repository rather than from one
of the supplied tarballs then you'll also need these additional packages:
*  autoconf
*  tcl

In order to prepare the documentation (do make within the Documents/
subdirectory) you'll need these packages:
*  linuxdoc-tools
*  doxygen

If you are using MSYS for running configure and make, you should always use
Windows paths (like c:/brltty), not MSYS paths (like /c/brltty), because brltty
does _not_ understand MSYS paths.

------------------------------------------------------------------------------

Windows 98 and Me Limitation
============================

On Windows versions 2000, XP, 2003, and later, BRLTTY automatically accesses
the Windows terminal which you're currently using as you switch between them.
This isn't possible on earlier versions. One way to still achieve this
functionality, however, is to run one BRLTTY (which directly accesses your
braille display) on the root window and another one (which indirectly accesses
your braille display via BrlAPI) on each terminal. This scheme may sound
complicated, but it can be easily set up to run automatically.

The first (or root) BRLTTY should be run as part of Windows startup. It must be
given those options which are necessary to access your braille display, e.g.
-b, -d, and all other options you'd normally specify. It must also be given the
-Xroot=yes option, which attaches it to the root window. 

An additional BRLTTY should then be run for each new terminal. It should be
invoked like this:

   brltty -bba -N

The -bba option tells it to access the root BRLTTY via BrlAPI, and the -N
option tells it not to start a BrlAPI server of its own.

These BRLTTYs can be started automatically by, for example, adding this line to
your .bashrc script. Each of these BRLTTYs takes care of the terminal it's
running in, and connects, via BrlAPI, to the root BRLTTY in order to access
your braille display.

If you're not concerned with security, and would rather not fiddle with the
brlapi.key file, then add the -Aauth=none option to the command line which
invokes the root BRLTTY. You don't need to worry about unauthorized access over
the network since the default is that only locally running programs can connect
to BrlAPI.

------------------------------------------------------------------------------

USB Support
===========

USB devices are supported thanks to the libusb-win32 package. This means that,
_before_ compiling BRLTTY, you need to:

either
*  For Cygwin:
   1) Install the libusb-win32 package.
   2) Activate the kernel driver by running /usr/sbin/libusb-install. You must
      also do this each time you upgrade libusb-win32 in order to reactivate 
      the driver. You can verify that the driver has been activated by plugging
      in a USB device, running the testlibusb test program, and checking that 
      it finds your device.

or
1) Download the libusb-win32 installer. As of the time of this writing, you can
   get it from [http://libusb-win32.sourceforge.net/]. The file will be called
   something like "libusb-win32-filter-bin-<version>.exe", and should be
   available on [http://sourceforge.net/project/showfiles.php?group_id=78138].

2) Run the installer. Remember where you install the package, for example:

      C:\Program Files\LibUSB-Win32-<version>

3) Symlink the header and library files to your Cygwin/MinGW installation.
   *  For Cygwin, run:
      +  ln -s "/cygdrive/c/Program Files/LibUSB-Win32-<version>/include/usb.h" 
               /usr/include/
      +  ln -s "/cygdrive/c/Program Files/LibUSB-Win32-<version>/lib/gcc/libusb.a" 
               /usr/lib/

   *  For MinGW, run:
      +  ln -s "/c/Program Files/LibUSB-Win32-someversion/include/usb.h"
               /mingw/include/
      +  ln -s "/c/Program Files/LibUSB-Win32-someversion/lib/gcc/libusb.a"
               /mingw/lib/

Then you can configure, compile, install, and run BRLTTY as usual.

------------------------------------------------------------------------------

Configuring BRLTTY
==================

Some of BRLTTY's configure options are of particular interest to users of the 
Windows platform:

--enable-relocatable-install: The default is for BRLTTY to refer to its
components via absolute paths. On the Windows platform, however, the convention
is for a package to use relative paths so that it can be installed into an
arbitrary directory and so that it can be moved around thereafter as well. This
option builds BRLTTY such that relative paths are used.

------------------------------------------------------------------------------

Sticking to a console
=====================

It may be useful to have BRLTTY only review the console it is started in, i.e. 
for it not to follow the keyboard focus. To achieve this, set the FollowFocus 
parameter of the Windows screen driver to no. This can be done either on the 
command line (-XFollowFocus=no) or in brltty.conf (screen-parameter 
FollowFocus=no).

------------------------------------------------------------------------------

Sharing the Braille Display with Other Screen Readers
=====================================================

When you're not on a window which BRLTTY can handle its default action is to
retain control of the braille display and to present a brief message explaining
the problem. If you have another braille-capable screen reader and would like
it to take over instead then both BRLTTY and that other screen reader must be
instructed to share the braille display.

BRLTTY can be instructed to share the braille display via its --release-device
option; the short form of this option is -r. When this option is in effect
BRLTTY releases the braille display when you move onto a window which it cannot
handle and tries to regain control of the braille display when you move onto a
window which it can handle. Note that these actions take a noticeable amount of
time so you should only use this option if it's actually needed.

------------------------------------------------------------------------------

Sharing BRLTTY with JAWS
========================

A common case wherein a JAWS user might want BRLTTY to be in control of the
braille display is when using Cygwin.

There are two phases to configuring JAWS to run in the background while BRLTTY
controls the braille display. First, the window title must be established and
stable. Second, JAWS braille must be put to sleep.

What is a window title?
-----------------------

Every window in Windows has a title bar that contains the name of the
application which is running in it as well as some controls to do things like
move and resize it. BRLTTY does not show this title bar.

For a program window, JAWS uses the name of the program's executable as the
name of the configuration files to load when that program gains focus. For a
console application such as Cygwin, however, it uses the title of the window
instead. We must, therefore, tell JAWS within the window title that this is a
Cygwin window.

Setting the Window Title
------------------------

JAWS uses one of the words in the window title as the name of the configuration
files to load. This file set is what tells JAWS the specifics of how to handle
the application. It is, therefore, where JAWS must be instructed to put its
braille component to sleep.

At this writing, it appears that JAWS uses the following algorithm for choosing
which word in the title to use as the name of the file set:
1) If there are no slashes (/) or backslashes (\) in the title then JAWS uses 
   the first word. Thus, if the title is "Cygwin Bash Shell" then JAWS will 
   load the Cygwin configuration files.
2) If there is at least one slash (/) or backslash (\) in the title then JAWS 
   uses the last word. Thus, if the title is "$PWD - Cygwin" then JAWS will 
   similarly load the Cygwin configuration files.
Setting Cygwin's Window Title
-----------------------------

First, it is imperative that you replace, or at least modify, the default PS1
(primary shell prompt) setting. The default for this setting, as distributed by
Cygwin, places $PWD (the path to the current working directory) in the window
title, thus requiring you to have a separate JAWS configuration for every
directory on the system! One possible way to resolve this problem is to
uncomment the `settitle' function which can be found near the end of `.bashrc'.
This function allows you to place a string of your own choice in the title. You
can use this function, therefore, as follows:

   export PROMPT_COMMAND='settitle "$PWD - Cygwin"'
   export PS1='$ '

The first of these lines causes the window title to be set just before each
shell prompt. Since $PWD always contains at least one slash (/), the operative
word is `Cygwin' (the last word), and JAWS will load any Cygwin configuration
files that it finds. The second of these lines sets the primary shell prompt to
the customary dollar sign ($). More importantly, though, it replaces Cygwin's
default PS1 setting which contains escape sequences that overwrite the window
title with just $PWD thus not presenting any permanent text for JAWS to
recognize.

Putting JAWS Braille to Sleep
-----------------------------

Now that a stable window title has been established, JAWS braille can finally
be put to sleep. While in Cygwin and with BRLTTY not running, do the following:
1) Press Insert+F2 to bring up the Run JAWS Manager dialog.
2) Down-Arrow to Configuration Manager and press Enter. Verify that the title 
   on the top line contains "Cygwin.jcf".
3) Press Alt+S for Set Options.
4) Press B for Braille.
5) Press S for Braille Sleep Mode.
6) Verify that the box is checked (it should look like <x> instead of < >). 
   Press Space to toggle the setting if the x isn't there.
7) Press Enter to leave the menu.
8) Press Control+S to save the file.
9) Press Alt+F4 to exit the configuration manager.

Putting JAWS Speech to Sleep
----------------------------

If you want to use JAWS speech in Windows but not in Cygwin, you can do the
following:

1) Press Insert+F2 to bring up the Run JAWS Manager dialog.
2) Down-Arrow to Configuration Manager and press Enter. Verify that the title 
   on the top line contains "Cygwin.jcf".
3) Press Alt+S for Set Options.
4) Press A for Advanced.
5) You should be on an item labelled "Sleep Mode Enable" with an empty check
   box (< >). Press Space to check it (<x>). 
6) Press Enter to leave the menu.
7) Press Control+S to save the file.
8) Press Alt+F4 to exit the configuration manager.

Performance
-----------

You'll always be able to switch to Cygwin, and BRLTTY, if running, will take
control of the braille display automatically. Switching back to Windows and
JAWS may be a bit more problematic, though ... the degree of success seems to
depend on the type of braille display being used. Sometimes it works properly.
Sometimes, with a USB display, the cable must be unplugged/replugged to allow
JAWS to regain control. In extreme cases you may need to exit BRLTTY before
going to Windows.

------------------------------------------------------------------------------