--- Documentation/speakup/DefaultKeyAssignments | 46 +++++++++ Documentation/speakup/INSTALLATION | 108 +++++++++++++++++++++ Documentation/speakup/README | 98 +++++++++++++++++++ Documentation/speakup/keymap-tutorial | 140 ++++++++++++++++++++++++++++ 4 files changed, 392 insertions(+) --- /dev/null 1970-01-01 00:00:00.000000000 +0000 +++ gregkh-2.6/Documentation/speakup/DefaultKeyAssignments 2005-07-05 15:30:57.000000000 -0700 @@ -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 1970-01-01 00:00:00.000000000 +0000 +++ gregkh-2.6/Documentation/speakup/INSTALLATION 2005-07-05 15:30:57.000000000 -0700 @@ -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 1970-01-01 00:00:00.000000000 +0000 +++ gregkh-2.6/Documentation/speakup/keymap-tutorial 2005-07-05 15:30:57.000000000 -0700 @@ -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 1970-01-01 00:00:00.000000000 +0000 +++ gregkh-2.6/Documentation/speakup/README 2005-07-05 15:30:57.000000000 -0700 @@ -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 +