Introduction
============

As of version 0.3.4 (released in July of 2003), Gnopernicus contains a braille
driver for BRLTTY. This means that you can now use Gnopernicus with any braille
display that is supported by BRLTTY. Although support is far from complete,
basic braille displaying, as well as key transmission, work fine.


Building BRLTTY
===============

Gnopernicus uses BrlAPI (BRLTTY's application programming interface).  When
building BRLTTY, therefore, configure it with --enable-api in order to enable
the compilation and installation of libbrlapi and its header files.

    ./configure --enable-api
    make
    make install

After installation, but *before* launching the new BRLTTY, you need to generate
an authentication key for its API. The easiest way to do this is:

    echo some-string >/etc/bbrlapi.key

Easiest, of course and as usual, doesn't necessarily mean best. It's much
better for this kind of data to be unpredictable. If, therefore, a random data
source is available then it should be used.

If you have the mcookie command then you can do:

    mcookie >/etc/brlapi.key

If you have the dd command and the /dev/random device then you can do:

    dd if=/dev/random of=/etc/brlapi.key bs=32 count=1

If there's the slightest possibility that even just one untrustworthy user can
access your system then you should seriously consider ensuring that the fiLe
containing the authentication key for BrlAPI can only be accessed by those
users who actually need to use the braille display. If there's only one braille
user then it's easy.  Just make him the owner of the file and ensure that noone
else can access it.

    chown whoever /etc/brlapi.key
    chmod 600 /etc/brlapi.key

If there's more than one braille user then it's a little more complicated.  
Create a new group with a meaningful name (like, say, brlapi), make the file
readable to that group but not to anyone else, and ensure that each braille
user is a member of that group.

    groupadd brlapi
    chgrp brlapi /etc/brlapi.key
    chmod 640 /etc/brlapi.key
    usermod -G brlapi user1
    usermod -G brlapi user2
    ...


Configuring Gnopernicus
=======================

You need to activate Braille Support, and to change the Braille Device Type to
"BRLTTY". This configuration can be done not only via the display but also via
the command line. Both of these methods are described here.


When the focus is inside the Gnopernicus window, select

    1 General Settings

In this menu, check the checkbox with the label "Braille". This activates
braille support, and makes the "Braille Settings" window available.

Now click OK to apply the change and close the window.

In the main Gnopernicus window again, select

    2 Input/Output Settings -> 2 Braille Settings -> 1 Braille Device

In this dialog box, ensure that "BRLTTY" is the selected braille device.

After applying your changes, "Close" the "Braille Settings" and "Input/Output
Settings" windows.

Braille should start working as soon as any needed configuration changes are
made.


There's a command-line interface to the Gnome configuration system (gconf)
called "gconftool-2". You can get verbose help for it with "gconftool-2 --help"
or something shorter with "gconftool-2 --usage".

The first step is to ensure that the accessibility features of Gnome are
enabled. Gnopernicus, at start time, automatically detects if accessibility
isn't enabled, and, if so, displays a dialog which asks the user if it should
be enabled. Since a blind user can't see this dialog, here's how to ensure that
the setting is correct ahead of time.

Check the current setting by inspecting the relevant gconf key:

    gconftool-2 --get /apps/desktop/gnome/interface/accessibility

If it's false, set it to true as follows (all one line):

    gconftool-2 --type bool
                --set /apps/desktop/gnome/interface/accessibility true

Gnopernicus uses gconf to store its settings, so you can manually turn braille
on (and turn speech off if you like). The relevant gconf keys are:

[turn braille on]
    gconftool-2 --type bool --set /apps/gnopernicus/srcore/br_active true

[set braille device to brltty]
    gconftool-2 --type string --set /apps/gnopernicus/braille/device BRLTTY

[turn braille monitor display (for sighted users) off]
    gconftool-2 --type bool --set /apps/gnopernicus/srcore/bm_active false

[turn speech off]
    gconftool-2 --type bool --set /apps/gnopernicus/srcore/sp_active false

You can run "gconftool-2 --get ...." with any key (you don't need the "--type"
parameter for the "get" function) to verify that that gconf key is set
correctly.


Starting Gnome
==============

Here's a sample .xinitrc file for starting Gnome under the Garnome
distribution. The accessibility key is set in the file to ensure that it is
true. The environment variable GTK_MODULES seems to be necessary to make
everything accessible. The .xinitrc file must be placed in your home directory
and is used when you type "startx" to start the X-server.

 ------------------------------------------------------------------------------
 #!/bin/sh

 # Define environment variables.
 GARNOME=$HOME/garnome
 PATH=$GARNOME/bin:$PATH
 LD_LIBRARY_PATH=$GARNOME/lib:$LD_LIBRARY_PATH
 PYTHONPATH=$GARNOME/lib/python2.2/site-packages
 PKG_CONFIG_PATH=$GARNOME/lib/pkgconfig:/usr/lib/pkgconfig
 GDK_USE_XFT=1
 GTK_MODULES=gail:atk-bridge
 export PATH LD_LIBRARY_PATH PYTHONPATH PKG_CONFIG_PATH GDK_USE_XFT GTK_MODULES

 # Configure Gnome.
 gconftool-2 --type bool --set /apps/desktop/gnome/interface/accessibility true

 # Tell Gnopernicus which virtual terminal is being used by the X display.
 # This is a bit complicated so cut-and-paste (rather than retype) it.
 CONTROLVT="$(grep "using VT number" "/var/log/XFree86.$(echo "$DISPLAY" | sed -e "s/^.*::*\([0-9]*\).*$/\1/").log" | sed -e "s/^.*using VT number \([0-9]*\).*$/\1/")"
 export CONTROLVT

 # Start the Gnome session.
 exec $GARNOME/bin/gnome-session
 ------------------------------------------------------------------------------


Starting Gnopernicus
====================

Gnopernicus is started from a file in your home directory which Gnome reads
when it starts up. While Gnome provides a GUI for adding startup programs,
there's no proper command-line or script way to do so yet. You can, however,
manually edit the session file as follows:

1) Create the directory "~/.gnome2" if it doesn't exist yet.
2) Create the file "~/.gnome2/session-manual" if it doesn't exist yet.
3) Contents of the "session-manual" file (without the indentation):

   <blank line>
   [Default]
   num_clients=1
   0,RestartStyleHint=3
   0,Priority=60
   0,RestartCommand=gnopernicus


Key Bindings
============

This driver assumes that Gnopernicus key bindings remain at their default
settings. BRLTTY commands are mapped to Gnopernicus key bindings as follows:

   BRLTTY       Gnopernicus
   Command      Binding      Description
   ----------   -----------  -----------
   CMD_LNUP     DK00         Go To Parent
   CMD_HOME     DK01         Go To Focus
   CMD_LNDN     DK02         Go To Child
   CMD_FWINLT   DK03         Go To Previous
                DK04         Repeat Last
   CMD_FWINRT   DK05         Go To Next
                DK01DK02     Do Default Action
   CR_ROUTE     HMSnn        Route Cursor


What's Left
===========

We need some way to figure out the tty on which the X server is currently
running. Some investigation didn't really show any way to get this information
via the X protocol. We'll probably need to add a BrlAPI-specific configuration
entry which at least lets the user set this. The downside would be that this
would make it very hard to use Gnopernicus for more than one X server
concurrently.

Any input on these issues would be highly appreciated.


