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.


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

Gnopernicus uses BrlAPI (a general-purpose braille-enabling application
programming interface).

After installation, but *before* launching the new BRLTTY, please check that a
BrlAPI authorization key has been defined. If the file /etc/brlapi.key either
doesn't exist or is empty then you need to generate a key. The easiest way to
do this is:

    echo some-string >/etc/brlapi.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 authorization 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
    ...


Compiling Gnopernicus
=====================

Gnopernicus must be linked against the libbrlapi.so which comes with the
currently running BRLTTY. Whenever the version of this shared object changes
(only the first two digits matter, e.g. libbrlapi.so.0.2.0 upgraded to
libbrlapi.so.3.0.0 but not libbrlapi.so.0.3.0 upgraded to libbrlapi.so.0.3.1),
you must rebuild (compile and link) Gnopernicus so as to make it use the
correct interface.

If the build fails then one thing you should try is replacing the Gnopernicus
source file braille/libbrl/ttybrl.c with the one provided by BRLTTY in
Patches/ttybrl.c.


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

You need to ensure that the braille-related accessibility features of Gnome are
set correctly, i.e. that Accessibility is enabled, that Braille Support is
enabled, and that the Braille Device is set to "BRLTTY". Gnopernicus, at start
time, automatically checks these settings, and, for each feature which isn't
enabled, displays a dialogue which asks the user if it should be. Since a blind
user can't see these dialogues, and, therefore, may experience what he believes
to be an unexpected hang when starting Gnopernicus, other means have been
provided so that he can ensure that they're correct ahead of time. They may be
preconfigured via Gnopernicus command-line options, via the generic Gnome
command-line configuration tool, or, if sighted assistance is available, from
the Gnome desktop. All of these methods, in that order, are described below.


Gnopernicus Command-line Options
--------------------------------

As of Gnopernicus 0.7, the following command-line options are supported. 

   -b  --enable-braille           Enable the Braille service.
   -B  --disable-braille          Disable the Braille service.
   -s  --enable-speech            Enable the Speech service.
   -S  --disable-speech           Disable the Speech service.
   -m  --enable-magnifier         Enable the Magnifier service.
   -M  --disable-magnifier        Disable the Magnifier service.
   -o  --enable-braille-monitor   Enable the on-screen Braille Monitor.
   -O  --disable-braille-monitor  Disable the on-screen Braille Monitor.
   -e  --braille-device=<type>    The braille device type (should be BRLTTY).
   -p  --braille-port=ttyS<n>     The serial port (not relevant for BRLTTY).

To get Gnopernicus to operate your braille display via BRLTTY, the minimum set 
of options you must specify is:

   -b -e BRLTTY

These options make permanent changes to the Gnome Accessibility settings so you
only need to specify them when you invoke Gnopernicus for the first time.
Specifying them on every invocation isn't wrong, but you should be aware that
this approach will undo any subsequent changes to the settings made via the
Gnome Desktop.


The Generic Gnome Command-line Configuration Tool
-------------------------------------------------

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".

You can check the current setting of any key with: 

   gconftool-2 --get <key> 

You can change the setting of any key with:

   gconftool-2 --type <type> --set <key> <value>

To check if Assistive Technology Support (Accessibility) is enabled, for
example, do:

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

If it's disabled (set to false) and you'd like to permanently enable it, set it
to true as follows:

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

There's also a way to temporarily (for a single session) enable Accessibility.  
This is done by setting the environment variable GNOME_ACCESSIBILITY to 1.

    sh: GNOME_ACCESSIBILITY=1; export GNOME_ACCESSIBILITY
   ksh: export GNOME_ACCESSIBILITY=1
   csh: setenv GNOME_ACCESSIBILITY 1

The relevant gconf keys are:

[turn Accessibility on (as just described above)]
   gconftool-2 --type bool --set /desktop/gnome/interface/accessibility true

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

[set Braille Device to BRLTTY's BrlAPI]
   gconftool-2 --type string --set /apps/gnopernicus/braille/device BRLTTY

[set Braille Translation Table to your preferred language]
   gconftool-2 --type string --set /apps/gnopernicus/braille/translation_table
      English: en_US (American)
       German: de
      Spanish: es
      Swedish: sv

[turn the on-screen Braille Monitor (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


Configuration via the Gnome Desktop
-----------------------------------

To enable Assistive Technologies Support (Accessibility), do: Alt-F1 ->
"Desktop Preferences" -> "Accessibility" -> "Assistive Technology Support"

If "Enable Assistive Technologies" isn't checked, then check it, log out, and
log back in again.

If the main Gnopernicus window isn't visible, do: Alt-F1 -> "Accessibility" -> 
"Screen Reader"

From the main Gnopernicus window, select: "Startup Mode"

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

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

From the main Gnopernicus window again, select: "Preferences" -> "Braille"

Select "Braille Device", set it to "BRLTTY's BrlAPI", and click "OK" to apply
the change.

Select "Translation Table", set it to your preferred language, and click "OK"  
to apply the change.

Make any other changes which more accurately tailor Gnopernicus's braille
support to your own personal needs, then "Close" the "Braille Preferences"
window, and, finally, "Close" the "Preferences" window.

Braille should start working as soon as all needed configuration changes have
been made.


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 /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 Mappings
============

This driver assumes that Gnopernicus key bindings remain at their default
settings. Changing Gnopernicus's key bindings may interfere with the user's
ability to accurately and/or predictably control window navigation when using
BRLTTY.


Original Mappings
-----------------

The original way in which BRLTTY commands were mapped to Gnopernicus functions
wasn't very practical. It's still documented here, though, in case the version
of Gnopernicus which you're running is still using it. It is as follows:

   BRLTTY          Gnopern   Functional
   Command         Binding   Description
   --------------  --------  -----------
   BRL_CMD_LNUP    DK00      Go to parent object
   BRL_CMD_HOME    DK01      Go to object with focus
   BRL_CMD_LNDN    DK02      Go to child object
   BRL_CMD_FWINLT  DK03      Go to previous object
   BRL_CMD_FWINRT  DK05      Go to next object
   BRL_CMD_CHRLT   L09K01    Move left one character
   BRL_CMD_CHRRT   L09K03    Move right one character
   BRL_CMD_HWINLT  L09K04    Move left one display-width
   BRL_CMD_HWINRT  L09K06    Move right one display-width
   BRL_BLK_ROUTE   HMSnn     Route (bring) cursor to character


Current Mappings
----------------

The current way in which BRLTTY commands are mapped to Gnopernicus functions is
listed below. If the version of Gnopernicus which you're running isn't yet
using it then copy the file ttybrl.c from the Patches/ subdirectory of BRLTTY's
source tree to the braille/libbrl/ subdirectory of Gnopernicus's source tree,
and then rebuild Gnopernicus.

   BRLTTY              Gnopern  Functional
   Command             Binding  Description
   --------------      -------  -----------
   BRL_CMD_TOP_LEFT    L00K07   Go to title
   BRL_CMD_BOT_LEFT    L00K03   Go to status bar
   BRL_CMD_TOP         L00K09   Go to menu
   BRL_CMD_BOT         L00K01   Go to tool bar
   BRL_CMD_HOME        L00K12   Go to object with focus
   BRL_CMD_PRPROMPT    L00K08   Go to parent object
   BRL_CMD_NXPROMPT    L00K02   Go to child object
   BRL_CMD_PRPGRPH     L00K15   Go to first object
   BRL_CMD_NXPGRPH     L00K14   Go to last object
   BRL_CMD_LNUP        L00K04   Go to previous object
   BRL_CMD_LNDN        L00K06   Go to next object
   BRL_CMD_FREEZE      L00K10   Toggle focus-tracking/flat-review mode
   BRL_CMD_FWINLT      L09K04   Move one display-width left
   BRL_CMD_FWINRT      L09K06   Move one display-width right
   BRL_CMD_CHRLT       L09K01   Move one character left
   BRL_CMD_CHRRT       L09K03   Move one character right
   BRL_CMD_SAY_SOFTER  L08K01   Decrease speech volume
   BRL_CMD_SAY_LOUDER  L08K03   Increase speech volume
   BRL_CMD_SAY_SLOWER  L08K04   Decrease speech rate
   BRL_CMD_SAY_FASTER  L08K06   Increase speech rate
   BRL_BLK_ROUTE       HMSnn    Route (bring) cursor to character


Getting the Routing Keys to Work
--------------------------------

The routing keys won't work until their action has been configured. To
configure them, do the following:

Go to Gnopernicus's "Preferences" dialog (option 2 in its main menu).

Choose "Braille Preferences" (option 2 in the Preferences dialog).

Choose "Braille key mapping" (option 5 in the Braille Preferences dialog).

You will now be on the "Position Sensors" page tab. Press the radio button
which says "Position sensors move caret" (which should be the fifth radio
button).

Select "Apply" followed by "OK" to close the dialog.

You will be back in the Braille Preferences dialog. Click its "Close" button to
close it. 

You will be back in the main Preferences dialog. Click its "Close" button to 
close it.

Be aware that your routing keys will only work in those contexts which actually
have a caret.
