SPEAKUP_DOCS.TXT

The Speakup Tutorial
By Saqib Shaikh <ss@saqibshaikh.com>

Introduction

In recent months there has been a vast growth in the popularity of the
Linux operating system. Speakup is a Linux screen reader, that is it is a
software program that enables blind computer users to use Linux by
receiving speech output.

This tutorial takes the new Speakup/Linux user through the basic things
that they need to know.

What Is Speakup?

As mentioned previously, Speakup is a screen reader for the Linux
operating system. One of the things which makes Speakup different from
more traditional screen readers is that it is patched into the kernel. To
explain what this means, Speakup is an integral part of the operating
system. This means that when you turn on your computer and Linux starts,
Speakup also starts, meaning you can hear all boot-up messages, and
resolve any problems related to the computer not reaching the login
prompt. In addition, when you shutdown your system you will receive speech
feedback right until the message "Power down" is given, indicating you
should turn off your computer.

Speakup is written by Kirk Reiser and Andy Berdan. It is distributed under
the terms of the GNU GPL. If you don't already know, GPL stands for
General Public License, and is a license agreement that basically states
that you are free to copy, modify and distribute Speakup, but may not turn
any part of it into proprietary or commercial code without the permission
of the author, Kirk Reiser.

Currently Speakup supports the following speech synthesisers. Each
synthesiser is given a keyword, which is how Speakup refers to that
synthesiser.

acntpc: Accent PC internal speech synthesiser.
acntsa: Accent SA external speech synthesiser.
apolo: Apollo II external speech synthesiser.
audptr: Audapter external speech synthesiser.
bns: Braille 'n Speak family of note-takers, including the Braille 'n
 Speak, Type 'n Speak, Braille Lite and Type Lite.
decext: External DEC-Talk (for the older DEC-Talk and Multi-Voice speech
 synthesisers).
dectlk: DEC-Talk Express external speech synthesiser.
dtlk: Doubletalk PC internal speech synthesiser.
ltlk: Doubletalk external or Litetalk speech synthesiser.
spkout: Speakout external speech synthesiser.
txprt: Transport external speech synthesiser.

Speakup Resources

The official Speakup home page is at http://linux-speakup.org, and the ftp
site at ftp://ftp.braille.uwo.ca/pub/linux/speakup.

Slackware Linux has recently become the first Linux distribution to
include Speakup.  You can find more information about Slackware at
http://www.slackware.com, or download it at
ftp://ftp.slackware.com/pub/slackware/slackware.

Bill Acker also has an FTP site devoted to Speakup and Red Hat Linux at
ftp://speakup.octothorp.org.

There is an ever-growing group of Speakup users on the internet. They are
all very friendly and willing to help each other with Speakup or Linux
problems. The main interaction between Speakup users is via the Speakup
mailing list. To subscribe, send a message to
<speakup-request@braille.uwo.ca>. In the body of the message write the
word "subscribe" (or "unsubscribe" to unsubscribe). Once you are
subscribed to the list, send a message to everyone else on the list by
emailing <speakup@braille.uwo.ca>.

Some users also hang out on the Speakup reflector. In order to use this
you should get and install a program called Speak Freely, which is
available for both Linux and Windows. To connect, point your sfmike at
lwl.braille.uwo.ca:4074.

Various people, Matthew Campbell in particular, have done talks about
Linux/Speakup on the ACB Radio Main Menu show. For more information, visit
http://www.acbradio.org.

Finally, you may contact Kirk directly at <kirk@braille.uwo.ca>. However,
please remember that if Kirk gets lots of emails all asking the same thing
he might get rather annoyed, so its always better to try the mailing list
first!

Speakup Screen Reading Keys

Using Speakup it is possible to use a special reading cursor to look
around the screen, without affecting the application's current operation.
All of Speakup's reading keys are, by default, bound to keys on the
numeric keypad. It is possible to change this default layout, but this
will require some knowledge of how Linux keymaps work. If you feel like
doing this then you should consult the document
ftp://ftp.braille.uwo.ca/pub/linux/speakup/keymap-tutorial.

Sometimes Speakup uses the 0, or insert key on the numeric keypad to
provide more functions. In these cases hold down the insert key and press
the other button. Note that although we call this the insert key, you
cannot use the other insert key which is positioned in a block of six
above the cursor keys.

The numbers 7, 8 and 9 on the numeric keypad read the previous, current
and next lines respectively. When moving up or down, the reading cursor
will be moved to that line. If you try pressing 7 when the reading cursor
is on the top line of the screen, or 9 when the reading cursor is on the
bottom line, then Speakup will respond "Top" or "Bottom" appropriately.

To move to, and read the previous/current/next word, use 4, 5 and 6
respectively. If you hear a beep, this means that you have past the end of
a line, and have moved to a different line. If you try to press 4 when you
are on the first word on the first line, or 6 when you are on the last
word of the last line, then Speakup will respond "Top" or "Bottom" as
before.

Use the 1, 2 and 3 to read by characters. As when reading words the
computer will beep when you move to a new line, and say "Top" or "Bottom"
when you are at the top/bottom of the screen.

To read from the top of the screen to the reading cursor use insert+8. Use
insert+4 to read from the beginning of the line to the reading cursor, and
insert+6 to read from the reading cursor to the end of the line.

Insert+5 will spell the current word. Insert+2 will say the current
character phonetically, using the millitary alphabet.

Use the plus (+) key to read the entire screen. Insert+plus reads from the
reading cursor to the bottom of the screen.

The minus key (-) toggles between having the reading cursor parked or
unparked. When the reading cursor is unparked, whenever the application
moves the cursor to a different position, the reading cursor will also
move. If parked, the reading cursor will always stay in its current
position unless you actually move it. This is often useful if you just
wish to monitor a particular part of the screen.

Insert+minus causes the decimal and hexadecimal value of the current
character to be read. Point (.) reads the current cursor position. This
includes the point on the current screen as well as which virtual console
is active. The minus key causes the color attributes of the current
position to be spoken.

To move the reading cursor to the top of the screen use insert+9, and use
insert+3 to move to the bottom of the screen. Insert+7 moves to the
beginning of the line, while insert+1 moves to the end of the line.

You can press any key to temporarily mute speech (the best way is to use
the control key). Pressing the enter key on the numeric keypad causes
Speakup to be silent until another key is pressed. Insert+enter causes
Speakup to stop talking until insert+enter is pressed again.

The slash key (/) will cause Speakup to go to the row/column that you
specify. The star key (*) toggles on cursor tracking. Cursor tracking is
currently only experimental.

Changing Speech Parameters

Speakup now uses the /proc file-system to change parameters. Use the command

echo value >/proc/speakup/parameter

Here, parameter includes such things as rate, pitch, volume, etc. To find
out the list of available parameters, type:

ls /proc/speakup

Value refers to the value you wish to set the parameter to. For example,
to set the rate of the sixth fastest value you would enter

echo 6 >/proc/speakup/rate

Installing Linux With Speech

Using Speakup it is now possible to install Linux with speech feedback.
For full details on installing Linux refer to one of the many good books
available, or the documentation that comes with your distribution of
Linux.

Finally, there is also another useful tool in the installer. This is
Parted.  It is a tool from which you can resize existing partitions.

Changing Your Keyboard Layout

One problem with Speakup is that in order to get the reading keys on the
numeric keypad to work, you must use the US keymap during a talking
installation of Linux. Later, you can change the keymap by using the
following procedure:

Firstly, download
ftp://ftp.braille.uwo.ca/pub/linux/speakup/speakupmap.map. This is a
keymap containing the Speakup key definitions.

Copy this file into the directory where your standard keymaps live. Copy
the US keymap into the file standard.map using a command like:

cp us.map standard.map

Then type:

diff -urN speakupmap.map standard.map >map.diff

Now, copy the keymap for your language to standard.map, for example:

cp uk.map standard.map

And finally type:

patch -p0 <map.diff

Now copy standard.map back to the original filename for your native
keymap, renaming it first. For example:

cp uk.map uk.map.old
mv standard.map uk.map

Load this keymap by typing:

loadkeys uk.map

Using Speakup On A Shared Machine

Previously, using Speakup on a computer that a sighted person also used
was a problem - you would probably need two different kernels. However,
you can now specify the default synthesiser to be "none", so that your
sighted colleague won't have any problems. Now, when you wish to use the
computer with speech, enter a command like the following at the boot
prompt:

linux speakup_synth=synthname speakup_ser=0

Where synthname refers to one of the synthesisers listed earlier, and
0 is the serial port the synth is connected to if it is not detected
automatically.

Installing Speakup From Scratch

If you want to install Speakup from scratch, then you will need to
recompile your kernel. The following is a rough list of things you should
do:

Get the latest kernel source from
ftp://ftp.kernel.org/pub/linux/kernel/vw.x/linux-w.x.y.z.tar.bz2. 
At the time of writing the latest kernel was 2.6.27.7.

Also get the Speakup source.  Probably it is best to get the CVS verision.
Unpack the kernel in /usr/src like this:

cd /usr/src
tar xjf linux-2.6.27.7.tar.bz2

Then make sure that the linux symlink points to it:

rm -f linux
ln -sf linux-2.6.27.7 linux

Run the speakup-checkout script in source/k in the Slackware tree to patch
speakup into your kernel.  Hit enter at the first prompt.  At the second,
enter the password for the CVS site.  This is:

please

You should probably start with Slackware's config file for the kernel.
Copy it from the Slackware tree (whereever you have it) into the kernel
sources in /usr/src:

cp kernels/speakup.s/config /usr/src/linux/.config

Now you can configure and compile the kernel by typing:

cd /usr/src/linux
make menuconfig  (select the options you want)
make

To copy the new kernel into place and reinstall LILO, use this:

rm -f /boot/vmlinuz /boot/System.map
cp arch/i386/boot/bzImage /boot/vmlinuz
cp System.map /boot/System.map
lilo

Please note that the above information is by no means sufficient to teach
someone to compile their kernel. There are many books/tutorials that cover
this topic in much more depth.

Using The CVS Version Of Speakup

[ Pardon the redundant nature of this section.  The previous one had recommended
using the speakup-1.00 release tarball, which probably will not work as well 
with the 2.6 kernel in Slackware -- Pat ]

CVS, which stands for Concurrent Versions System, is a tool that allows a
development version of a product to exist alongside the official release.
In terms of Speakup, the CVS version is newer than the stable release, but
is also likely to be less reliable as it hasn't been fully tested, and any
new piece of code added could potentially introduce more bugs. However,
using CVS means that you can try out new features and give feedback. If
you're a developer then you can work on the code as well.

Speakup comes with a script called "checkout" which contacts the CVS
server, downloads the program and applies all the patches. In order for
this to work you must have a clean copy of the Linux kernel source in
/usr/src/linux. The first time you run the checkout script you can run it
from anywhere, but after the first time you will want to run the script
from /usr/src/linux/drivers/char/speakup to do future updates.

If you haven't already got a copy of the checkout script you can download
it from ftp://ftp.braille.uwo.ca/pub/linux/speakup/checkout. After
downloading it you will need to make it executable. You can do this by
entering the command:

chmod 755 checkout

from the directory where the script is. To run the script type:

./checkout

You should be prompted with "No CVSROOT set hit return to select
anonymous". Just hit enter, and you will be asked for a password. All
anonymous passwords on the Speakup CVS server are the single word
"please". Kirk says that if you can't say please then you can't have what
you want! If everything went all right you should see multiple CVS
updating and patching messages.

Good luck in your Linux adventures. If you found this document useful and
have successfully installed Linux then please let me know. Equally, if you
don't like it then tell me also.

You may reach the author via email at ss@saqibshaikh.com. You may also
like to visit his home page at http://www.saqibshaikh.com.