path: root/bad/speakup-docs.patch

---
 Documentation/speakup/DefaultKeyAssignments |   46 +++++++++
 Documentation/speakup/INSTALLATION          |  108 +++++++++++++++++++++
 Documentation/speakup/README                |   98 +++++++++++++++++++
 Documentation/speakup/keymap-tutorial       |  140 ++++++++++++++++++++++++++++
 4 files changed, 392 insertions(+)

--- /dev/null
+++ gregkh-2.6/Documentation/speakup/DefaultKeyAssignments
@@ -0,0 +1,46 @@
+This file is intended to give you an overview of the default keys used
+by speakup for it's review functions.  You may change them to be
+anything you want but that will take some familiarity with key
+mapping.
+
+We have remapped the insert or zero key on the keypad to act as a
+shift key.  Well, actually as an altgr key.  So in the following list
+InsKeyPad-period means hold down the insert key like a shift key and
+hit the keypad period.
+
+KeyPad-8		Say current Line
+InsKeyPad-8		say from top of screen to reading cursor.
+KeyPad-7		Say Previous Line (UP one line)
+KeyPad-9		Say Next Line (down one line)
+KeyPad-5		Say Current Word
+InsKeyPad-5		Spell Current Word
+KeyPad-4		Say Previous Word (left one word)
+InsKeyPad-4		say from left edge of line to reading cursor.
+KeyPad-6		Say Next Word (right one word)
+InsKeyPad-6		Say from reading cursor to right edge of line.
+KeyPad-2		Say Current Letter
+InsKeyPad-2		say current letter phonetically
+KeyPad-1		Say Previous Character (left one letter)
+KeyPad-3		Say Next Character (right one letter)
+KeyPad-plus		Say Entire Screen
+InsKeyPad-plus		Say from reading cursor line to bottom of screen.
+KeyPad-Minus		Park reading cursor (toggle)
+InsKeyPad-minus		Say character hex and decimal value.
+KeyPad-period		Say Position (current line, position and console)
+InsKeyPad-period	say colour attributes of current position.
+InsKeyPad-9		Move reading cursor to top of screen (insert pgup)
+InsKeyPad-3		Move reading cursor to bottom of screen (insert pgdn)
+InsKeyPad-7		Move reading cursor to left edge of screen (insert home)
+InsKeyPad-1		Move reading cursor to right edge of screen (insert end)
+ControlKeyPad-1		Move reading cursor to last character on current line.
+KeyPad-Enter		Shut Up (until another key is hit) and sync reading cursor
+InsKeyPad-Enter		Shut Up (until toggled back on).
+InsKeyPad-star n<x|y>	go to line (y) or column (x). Where 'n' is any
+		allowed value for the row or column for your current screen.
+KeyPad-/		Mark and Cut screen region.
+InsKeyPad-/		Paste screen region into any console.
+
+Hitting any key while speakup is outputting speech will quiet the
+synth until it has caught up with what is being printed on the
+console.
+
--- /dev/null
+++ gregkh-2.6/Documentation/speakup/INSTALLATION
@@ -0,0 +1,108 @@
+This document assumes you have had some experience with kernel
+compilation and installation.  If you have not, I recommend you get
+the kernel source and read the README and various documents in the
+linux/Documentation directory.  In particular the Changes file to make
+sure you have the appropriate utilities needed for installing a 2.2.xx
+or 2.4xx kernel.  It isn't as difficult as you might think.  The
+kernel README is intimidating the first time but once you get the
+steps down, it's really pretty easy.  Getting through the "make
+config" is the tedious bit.
+
+The first thing to do is to place a copy of the tarball in the /usr/src
+directory which is the directory the linux tree is located in as well.
+Next untar speakup by typing:
+
+tar zxf speakup-1.00.tar.gz
+cd speakup-1.00
+./install
+
+Note the dot-slash before the install.  This will copy the speakup
+directory to the kernel tree and apply the various patches and
+components to the appropriate kernel files.  Depending on how
+experienced you are with kernel compiling and hacking will determine
+whether you should bother looking at any failed patches.  If this
+happens, you should probably write to the speakup mailing list for
+help or myself.
+
+If all of the patch hunks apply successfully then just continue with
+the standard steps to compile the kernel with:
+
+make mrproper
+make config
+
+When you get to the section console speech output, answer 'y' to the
+CONFIG_SPEAKUP prompt.  You will be given a submenu with the list of
+synthesizers which are currently supported.  You can include as many
+synths in the kernel as you wish but remember each one takes up kernel
+space.  You can only choose one of the synths as the default or none,
+so just type dtlk or whatever is the correct string for the
+synthesizer you have.  You will also be asked if you wish to build-in
+a speakup key map.  If you do not say 'y' to this option you will need
+to load a speakup map at boot time with whichever mechanism your
+distribution uses for loading key maps.
+
+We have placed the speakup configuration options in make config just
+after the vga console choice.  For the DoubleTalk PC driver included
+by Jim Van Zandt.  I recommend you say no to that option.  I have not
+tried configuring them both in, but I wouldn't be at all surprised if
+it didn't work.
+
+If all goes well up to this point you can continue with the compiling
+process by doing:
+
+make dep >dep.file 2>&1 &
+make bzImage >cc.file 2>&1 &
+make modules >mod.file 2>&1 &
+
+I always redirect output to the files dep.file and cc.file so I can
+look over the compilation record to make sure there are no errors and
+warnings.
+
+Okay, you are ready to install the newly compiled kernel.  Make sure
+you make an linux.old entry in your lilo.conf file so you can recover
+if it blows up.  next as root run "make modules_install" to install
+whatever modules you compiled and move the bzImage from
+/usr/src/linux/arch/i386/boot to wherever your kernel lives.  Also
+move the System.map from /usr/src/linux to where your System.map
+lives.  On our systems we use debian so we create an vmlinuz-speakup
+and System.map-speakup in our /boot directory and set the symbolic
+links vmlinuz and System.map in the root (/) directory to point to the
+images.  Now type lilo to tell lilo to build the new booter file and
+install it.
+
+As of version 0.07, the keymap for speakup is automatically built in
+at compile time.  If you have other keymaps installed at boot time,
+you might want to consider removing them before you reboot the system.
+
+If everything has gone OK up until now, cross your fingers and type:
+
+shutdown -r now
+
+Your system should start talking to you as soon as it starts booting.
+It will talk and talk and ... well, you might want to hit the
+keypad-enter key to tell it to shut up.  You should also read the
+DefaultKeyAssignments file to learn the various review functions
+available.
+
+As of v-0.10 the speakup configuration options are in the
+/proc/speakup subtree.  The individual options should be fairly
+obvious by their names such as rate, volume, punc_level and so forth.
+You can manipulate them by cat'ing or echoing new values to them such
+as:
+
+echo 9 >/proc/speakup/rate
+
+You can see what the current values are by cat'ing those files to the console:
+
+cat /proc/speakup/rate
+
+I have probably managed to overlook a whole whack of things because
+this is the, enter version number here, draft.  Don't worry we'll get
+it right eventually.  If you like the package you really should get on
+the mailing list and start participating in it's development.
+
+  Kirk
+
+email: kirk@braille.uwo.ca
+phone: (519) 679-6845 (home)
+
--- /dev/null
+++ gregkh-2.6/Documentation/speakup/keymap-tutorial
@@ -0,0 +1,140 @@
+		       Speakup Keymap Tutorial
+
+This is meant to be a basic tutorial on how to change the Linux keymap
+file to assign speakup review functions to desired keys.  It is not
+intended to be a replacement for the loadkeys(8) or keymap(5) man
+pages.
+
+The basic lay-out of the keymap file is a series of lines with the
+following fields.  The keyword keycode indicates this is the start of
+a new key assignment.  It is then followed by a number which
+represents the actual key on the keyboard.  That number is followed by
+the equals '=' operator and finally a list of keywords representing
+key names such as keypad5.  Each line can have quite a few key
+functions on it.  They are interpreted by loadkeys in order and
+assigned to key shift states depending on the order they are
+encountered.  So for example, the first value after the equals is the
+keys unshifted state, while the second is the keys shifted state.  If
+you wish to learn the order they are interpreted in read the
+loadkeys(8) and keymap(5) man pages.
+
+You can have subsequent lines which are indented and start with
+another keyword for the various shifted states.  This way you can
+assign some of the states without having to specify them all in order
+up until you get to the one you want to assign.
+
+In speakup, we have assigned the insert key on the number pad to the
+altgr keyword.  This is not required; you could choose any other
+shifted state keyword.  We used altgr because it typically represents
+the right hand alt key.  In Linux each shift key is separate and
+independent, so the left shift and the right shift keys are not
+necessarily the same.  The altgr key is not really used for anything
+important, so we steel it.
+
+Here are the default key assignments for the number eight on the
+keypad:
+
+keycode  72 = KP_8
+	alt     keycode  72 = Ascii_8
+
+As you can see, the first line starts with keycode followed by 72
+which is the actual number assigned to the key when the keyboard port
+is read.  The KP_8 after the equal sign, is the symbolic representation
+of the function called when that key is hit.
+
+The second line is the same format except it starts with the keyword
+alt which is indented.  That means that the function at the end of
+that line Ascii_8 is applied to the alt-shifted eight key.
+
+Now here are the speakup assignments for that key:
+
+keycode  72 = 0x0d0a
+	altgr keycode 72 = 0x0d20
+#keycode  72 = KP_8
+	alt     keycode  72 = Ascii_8
+
+Notice that the only thing which has changed on the first line is the
+function called when the key is struck.  It is a hexadecimal number
+identifying the function called in a look up table.  It is not a
+symbolic representation yet because that means we need to change the
+loadkeys program to understand our symbolic names.  We will do this in
+the future but for now it is more expedient to just use the table
+indices.  You will find a table at the bottom of this document
+listing the review functions and their corresponding hex lookups.
+
+The 0x0d0a in the first line above is speakup's say line function.
+The second line ends with 0x0d20 which is speakup's read from top of
+screen to reading cursor line.
+
+The third line is the original key assignment commented out with a
+number-sign '#' at the beginning.  I do that so I can easily find the
+keys I want to affect by symbolic name.  Otherwise I would need to
+keep a look up table for all the keycodes.  I recommend you do this as
+well or you'll be very sorry at some point in the future.
+
+The forth line is just the standard key assignment for the left hand
+alt key.
+
+Now let's say we want to design a different keyboard layout.  I'll use
+an example for the JAWS style keypad because I've specifically been
+asked to help with that.  JAWS uses the eight on the keypad to move up
+a line or the speakup function to read previous line.  JAWS also uses
+the keypad_8 key in a shifted mode to read the current line.  I
+apologize if these are not quite right.  It has been a long time since
+I used JAWS.  So we would have the following two lines:
+
+keycode  72 = 0x0d0b
+	altgr keycode 72 = 0x0d0a
+
+The hex value 0x0d0b in the first line is speakup's SAY_PREVIOUS_LINE
+function.  The 0x0d0a in the second line is the same say_line function
+as we had earlier.  So when the number eight is hit on the keypad
+speakup will read the previous line and when the number eight is
+shifted with the insert key on the keypad it will read the current
+line.
+
+As you can tell, it is not really very difficult to reassign the keys
+to different review functions.
+
+Once you have carefully edited the keymap file, called default.map in
+the speakup distribution, you copy it into the /etc/kbd directory.
+Make sure you back up the original default.map from that directory
+first, if there is one.  Then you run loadkeys to load the new map
+into the kernel:
+
+loadkeys /etc/kbd/default.map
+
+If you wish to build your new keyboard lay-out into the kernel, after
+testing it, copy the default.map file into the drivers/char directory,
+with the name defkeymap.map, of your Linux source tree.  Then rm the
+defkeymap.c file and recompile the kernel.  Because there is no
+defkeymap.c `make' will rebuild it on the next compile.
+
+Here is a list of the available speakup review functions at this point
+in time.
+
+SAY_CHAR 0x0d04 /* say this character */
+SAY_PREV_CHAR 0x0d05 /* say character left of this char */
+SAY_NEXT_CHAR 0x0d06 /* say char right of this char */
+SAY_WORD 0x0d07 /* say this word under reading cursor */
+SAY_PREV_WORD 0x0d08
+SAY_NEXT_WORD 0x0d09
+SAY_LINE 0x0d0a /* say this line */
+SAY_PREV_LINE 0x0d0b /* say line above this line */
+SAY_NEXT_LINE 0x0d0c
+TOP_EDGE 0x0d0d /* move to top edge of screen */
+BOTTOM_EDGE 0x0d0e
+LEFT_EDGE 0x0d0f
+RIGHT_EDGE 0x0d10
+SAY_PHONETIC_CHAR 0x0d11 /* say this character phonetically */
+SPELL_WORD 0x0d12 /* spell this word letter by letter */
+SAY_SCREEN 0x0d14
+SAY_POSITION 0x0d1b
+SPEECH_OFF 0x0d1c
+SAY_ATTRIBUTES 0x0d1d
+SPEAKUP_PARKED 0x0d1e
+SAY_FROM_TOP 0x0d20
+SAY_TO_BOTTOM 0x0d21
+SAY_FROM_LEFT 0x0d22
+SAY_TO_RIGHT 0x0d23
+
--- /dev/null
+++ gregkh-2.6/Documentation/speakup/README
@@ -0,0 +1,98 @@
+Welcome to the speakup project for the Speakup speech package for Linux.
+
+Speakup is written by Kirk Reiser and Andy Berdan.  It is licensed
+under the GPL.  If you don't already know, the GPL stands for the GNU
+General Public License.  Which basically states that this code is free to
+copy, modify and distribute to anyone interested in playing with it.
+The one thing you may not do is turn any part of it into proprietary
+or commercial code without the permission of the author.  That's me.
+
+If you are interested in being involved with the development of speech
+output for Linux you can subscribe to the Speakup mailing list by
+sending a message to speakup-request@braille.uwo.ca with the line: subscribe.  You can also subscribe by going to the speakup web page and following the links at http://www.linux-speakup.org.
+
+We are at a very early stage in the development of this package.
+Hopefully changes will happen often and many.  The current files in
+this directory are:
+
+DefaultKeyAssignments		# speakup's default review keys
+INSTALLATION			#  for installing speakup from the tar ball.
+README				# this file
+keymap-tutorial			# a tutorial on how to layout the keyboard
+
+Read the INSTALLATION file to learn how to apply the patches and the
+default.map for the keyboard.  You should also read the Changes file.
+It really has any new things I've added since last time.
+
+There is no documentation in any of these files to instruct you what
+to do if something goes wrong with the patching or compilation.  If
+you would like that information you will need to subscribe to the
+mailing list and ask for help, or write me kirk@braille.uwo.ca for
+help.  I suggest the mailing list because I will probably tire quickly
+of answering the same questions over and over.  You could always
+decide to dig-in and take on the task, and write documentation to help
+others.
+
+There also is a speakup reflector for the Speak Freely package, which
+many of us hang out on and discuss all sorts of topics from speakup
+problems to ALSA driver installation and just about anything else
+you'd like to talk about.  The reflector is at lwl.braille.uwo.ca:4074
+with it's lwl page at lwl.braille.uwo.ca/speakup.html.  Come and join
+us, it's fun!
+
+Acknowledgements:
+
+I am really very new at kernel hacking and screen review package
+writing, so I have depended heavily on other folks kindness to help me
+a long.  No doubt I will continue to abuse them freely and others
+before this is a really good speech solution for Linux.  (Oh Well!,
+somebody's got to do it.)
+
+Theodore Ts'o.  He gave me a good discussion of unicode and UTF and
+the like.  He doesn't even remember writing me about it.
+
+Alan Cox.  He has answered many questions about scheduling and wait
+queues and timers along with code fragments and so on.  I just wish I
+understood it all totally.  He has also helped immensely in moving
+this package toward inclusion in the standard kernel tree. (Maybe next
+release!)
+
+Martin Mares.  He pointed me in the right direction to figuring out
+the colour attributes and other useful tidbits.
+
+Paul McDermott.  He really is the catalyst for me to actually get
+this all working.  Besides I like seeing him bounce around and get all
+excited every time I have something new working.
+
+John Covici, He was the first person to actually attempt writing
+another synthesizer driver for speakup.  It was the Speakout driver so
+it was also the first serial driver.
+
+Brian Borowski, he was the first person to actually write a speakup
+function other than Andy and I.
+
+Jim Danley, he has more or less become my main man in helping test
+code, add new features, bounce ideas off and generally become a good
+friend.
+
+Matt Campbell, he basically rewrote the drivers to be able to include
+all synths in the kernel at the same time.  The distribution
+maintainers appreciate him a lot as well.
+
+Gene Collins, he was very helpful debugging the current release prior
+to its public showing.  He has also worked hard educating others on
+the list and writing the ALSA mini howto.
+
+I would also like to really thank the folks that handle the
+distribution packages.  I and many other people would not find access
+to speakup nearly so convenient without their efforts.  They include
+Bill Acker, Tom Moore, Matt Campbell, Joe Norton and Joshua Lambert.
+
+There are probably many more I am forgetting right now.  I guess I'll
+just have to add you all later.
+
+
+Happy Hacking!
+
+  Kirk
+