1 files changed, 331 insertions, 0 deletions
diff --git a/SPEAKUP_DOCS.TXT b/SPEAKUP_DOCS.TXT
new file mode 100644
index 000000000..78e339cba
--- /dev/null
+++ b/SPEAKUP_DOCS.TXT
@@ -0,0 +1,331 @@
+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.
+