William Hubbs | c6e3fd2 | 2010-10-07 13:20:02 -0500 | [diff] [blame] | 1 | |
| 2 | The Speakup User's Guide |
| 3 | For Speakup 3.1.2 and Later |
| 4 | By Gene Collins |
| 5 | Updated by others |
| 6 | Last modified on Mon Sep 27 14:26:31 2010 |
| 7 | Document version 1.3 |
| 8 | |
| 9 | Copyright (c) 2005 Gene Collins |
| 10 | Copyright (c) 2008 Samuel Thibault |
| 11 | Copyright (c) 2009, 2010 the Speakup Team |
| 12 | |
| 13 | Permission is granted to copy, distribute and/or modify this document |
| 14 | under the terms of the GNU Free Documentation License, Version 1.2 or |
| 15 | any later version published by the Free Software Foundation; with no |
| 16 | Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A |
| 17 | copy of the license is included in the section entitled "GNU Free |
| 18 | Documentation License". |
| 19 | |
| 20 | Preface |
| 21 | |
| 22 | The purpose of this document is to familiarize users with the user |
| 23 | interface to Speakup, a Linux Screen Reader. If you need instructions |
| 24 | for installing or obtaining Speakup, visit the web site at |
| 25 | http://linux-speakup.org/. Speakup is a set of patches to the standard |
| 26 | Linux kernel source tree. It can be built as a series of modules, or as |
| 27 | a part of a monolithic kernel. These details are beyond the scope of |
| 28 | this manual, but the user may need to be aware of the module |
| 29 | capabilities, depending on how your system administrator has installed |
| 30 | Speakup. If Speakup is built as a part of a monolithic kernel, and the |
| 31 | user is using a hardware synthesizer, then Speakup will be able to |
| 32 | provide speech access from the time the kernel is loaded, until the time |
| 33 | the system is shutdown. This means that if you have obtained Linux |
| 34 | installation media for a distribution which includes Speakup as a part |
| 35 | of its kernel, you will be able, as a blind person, to install Linux |
| 36 | with speech access unaided by a sighted person. Again, these details |
| 37 | are beyond the scope of this manual, but the user should be aware of |
| 38 | them. See the web site mentioned above for further details. |
| 39 | |
| 40 | 1. Starting Speakup |
| 41 | |
| 42 | If your system administrator has installed Speakup to work with your |
| 43 | specific synthesizer by default, then all you need to do to use Speakup |
| 44 | is to boot your system, and Speakup should come up talking. This |
| 45 | assumes of course that your synthesizer is a supported hardware |
| 46 | synthesizer, and that it is either installed in or connected to your |
| 47 | system, and is if necessary powered on. |
| 48 | |
| 49 | It is possible, however, that Speakup may have been compiled into the |
| 50 | kernel with no default synthesizer. It is even possible that your |
| 51 | kernel has been compiled with support for some of the supported |
| 52 | synthesizers and not others. If you find that this is the case, and |
| 53 | your synthesizer is supported but not available, complain to the person |
| 54 | who compiled and installed your kernel. Or better yet, go to the web |
| 55 | site, and learn how to patch Speakup into your own kernel source, and |
| 56 | build and install your own kernel. |
| 57 | |
| 58 | If your kernel has been compiled with Speakup, and has no default |
| 59 | synthesizer set, or you would like to use a different synthesizer than |
| 60 | the default one, then you may issue the following command at the boot |
| 61 | prompt of your boot loader. |
| 62 | |
| 63 | linux speakup.synth=ltlk |
| 64 | |
| 65 | This command would tell Speakup to look for and use a LiteTalk or |
| 66 | DoubleTalk LT at boot up. You may replace the ltlk synthesizer keyword |
| 67 | with the keyword for whatever synthesizer you wish to use. The |
| 68 | speakup.synth parameter will accept the following keywords, provided |
| 69 | that support for the related synthesizers has been built into the |
| 70 | kernel. |
| 71 | |
| 72 | acntsa -- Accent SA |
| 73 | acntpc -- Accent PC |
| 74 | apollo -- Apollo |
| 75 | audptr -- Audapter |
| 76 | bns -- Braille 'n Speak |
| 77 | dectlk -- DecTalk Express (old and new, db9 serial only) |
| 78 | decext -- DecTalk (old) External |
| 79 | dtlk -- DoubleTalk PC |
| 80 | keypc -- Keynote Gold PC |
| 81 | ltlk -- DoubleTalk LT, LiteTalk, or external Tripletalk (db9 serial only) |
| 82 | spkout -- Speak Out |
| 83 | txprt -- Transport |
| 84 | dummy -- Plain text terminal |
| 85 | |
| 86 | Note: Speakup does * NOT * support usb connections! Speakup also does * |
| 87 | NOT * support the internal Tripletalk! |
| 88 | |
| 89 | Speakup does support two other synthesizers, but because they work in |
| 90 | conjunction with other software, they must be loaded as modules after |
Aybuke Ozdemir | f6bb9e3 | 2014-09-25 02:14:51 +0300 | [diff] [blame^] | 91 | their related software is loaded, and so are not available at boot up. |
William Hubbs | c6e3fd2 | 2010-10-07 13:20:02 -0500 | [diff] [blame] | 92 | These are as follows: |
| 93 | |
| 94 | decpc -- DecTalk PC (not available at boot up) |
| 95 | soft -- One of several software synthesizers (not available at boot up) |
| 96 | |
| 97 | See the sections on loading modules and software synthesizers later in |
| 98 | this manual for further details. It should be noted here that the |
| 99 | speakup.synth boot parameter will have no effect if Speakup has been |
| 100 | compiled as modules. In order for Speakup modules to be loaded during |
| 101 | the boot process, such action must be configured by your system |
| 102 | administrator. This will mean that you will hear some, but not all, of |
| 103 | the bootup messages. |
| 104 | |
| 105 | 2. Basic operation |
| 106 | |
| 107 | Once you have booted the system, and if necessary, have supplied the |
| 108 | proper bootup parameter for your synthesizer, Speakup will begin |
Aybuke Ozdemir | f6bb9e3 | 2014-09-25 02:14:51 +0300 | [diff] [blame^] | 109 | talking as soon as the kernel is loaded. In fact, it will talk a lot! |
William Hubbs | c6e3fd2 | 2010-10-07 13:20:02 -0500 | [diff] [blame] | 110 | It will speak all the boot up messages that the kernel prints on the |
| 111 | screen during the boot process. This is because Speakup is not a |
| 112 | separate screen reader, but is actually built into the operating |
| 113 | system. Since almost all console applications must print text on the |
| 114 | screen using the kernel, and must get their keyboard input through the |
| 115 | kernel, they are automatically handled properly by Speakup. There are a |
| 116 | few exceptions, but we'll come to those later. |
| 117 | |
Aybuke Ozdemir | f6bb9e3 | 2014-09-25 02:14:51 +0300 | [diff] [blame^] | 118 | Note: In this guide I will refer to the numeric keypad as the keypad. |
William Hubbs | c6e3fd2 | 2010-10-07 13:20:02 -0500 | [diff] [blame] | 119 | This is done because the speakupmap.map file referred to later in this |
| 120 | manual uses the term keypad instead of numeric keypad. Also I'm lazy |
| 121 | and would rather only type one word. So keypad it is. Got it? Good. |
| 122 | |
| 123 | Most of the Speakup review keys are located on the keypad at the far |
| 124 | right of the keyboard. The numlock key should be off, in order for these |
| 125 | to work. If you toggle the numlock on, the keypad will produce numbers, |
| 126 | which is exactly what you want for spreadsheets and such. For the |
| 127 | purposes of this guide, you should have the numlock turned off, which is |
| 128 | its default state at bootup. |
| 129 | |
| 130 | You probably won't want to listen to all the bootup messages every time |
| 131 | you start your system, though it's a good idea to listen to them at |
| 132 | least once, just so you'll know what kind of information is available to |
| 133 | you during the boot process. You can always review these messages after |
| 134 | bootup with the command: |
| 135 | |
| 136 | dmesg | more |
| 137 | |
| 138 | In order to speed the boot process, and to silence the speaking of the |
| 139 | bootup messages, just press the keypad enter key. This key is located |
| 140 | in the bottom right corner of the keypad. Speakup will shut up and stay |
| 141 | that way, until you press another key. |
| 142 | |
| 143 | You can check to see if the boot process has completed by pressing the 8 |
| 144 | key on the keypad, which reads the current line. This also has the |
| 145 | effect of starting Speakup talking again, so you can press keypad enter |
Aybuke Ozdemir | f6bb9e3 | 2014-09-25 02:14:51 +0300 | [diff] [blame^] | 146 | to silence it again if the boot process has not completed. |
William Hubbs | c6e3fd2 | 2010-10-07 13:20:02 -0500 | [diff] [blame] | 147 | |
| 148 | When the boot process is complete, you will arrive at a "login" prompt. |
| 149 | At this point, you'll need to type in your user id and password, as |
| 150 | provided by your system administrator. You will hear Speakup speak the |
| 151 | letters of your user id as you type it, but not the password. This is |
| 152 | because the password is not displayed on the screen for security |
| 153 | reasons. This has nothing to do with Speakup, it's a Linux security |
| 154 | feature. |
| 155 | |
| 156 | Once you've logged in, you can run any Linux command or program which is |
| 157 | allowed by your user id. Normal users will not be able to run programs |
| 158 | which require root privileges. |
| 159 | |
| 160 | When you are running a program or command, Speakup will automatically |
| 161 | speak new text as it arrives on the screen. You can at any time silence |
Aybuke Ozdemir | f6bb9e3 | 2014-09-25 02:14:51 +0300 | [diff] [blame^] | 162 | the speech with keypad enter, or use any of the Speakup review keys. |
William Hubbs | c6e3fd2 | 2010-10-07 13:20:02 -0500 | [diff] [blame] | 163 | |
| 164 | Here are some basic Speakup review keys, and a short description of what |
| 165 | they do. |
| 166 | |
| 167 | keypad 1 -- read previous character |
| 168 | keypad 2 -- read current character (pressing keypad 2 twice rapidly will speak |
| 169 | the current character phonetically) |
| 170 | keypad 3 -- read next character |
| 171 | keypad 4 -- read previous word |
| 172 | keypad 5 -- read current word (press twice rapidly to spell the current word) |
| 173 | keypad 6 -- read next word |
| 174 | keypad 7 -- read previous line |
| 175 | keypad 8 -- read current line (press twice rapidly to hear how much the |
| 176 | text on the current line is indented) |
| 177 | keypad 9 -- read next line |
| 178 | keypad period -- speak current cursor position and announce current |
| 179 | virtual console |
| 180 | |
| 181 | It's also worth noting that the insert key on the keypad is mapped |
| 182 | as the speakup key. Instead of pressing and releasing this key, as you |
| 183 | do under DOS or Windows, you hold it like a shift key, and press other |
| 184 | keys in combination with it. For example, repeatedly holding keypad |
| 185 | insert, from now on called speakup, and keypad enter will toggle the |
| 186 | speaking of new text on the screen on and off. This is not the same as |
| 187 | just pressing keypad enter by itself, which just silences the speech |
| 188 | until you hit another key. When you hit speakup plus keypad enter, |
| 189 | Speakup will say, "You turned me off.", or "Hey, that's better." When |
| 190 | Speakup is turned off, no new text on the screen will be spoken. You |
| 191 | can still use the reading controls to review the screen however. |
| 192 | |
| 193 | 3. Using the Speakup Help System |
| 194 | |
| 195 | In order to enter the Speakup help system, press and hold the speakup |
| 196 | key (remember that this is the keypad insert key), and press the f1 key. |
| 197 | You will hear the message: |
| 198 | |
| 199 | "Press space to leave help, cursor up or down to scroll, or a letter to |
| 200 | go to commands in list." |
| 201 | |
| 202 | When you press the spacebar to leave the help system, you will hear: |
| 203 | |
| 204 | "Leaving help." |
| 205 | |
| 206 | While you are in the Speakup help system, you can scroll up or down |
| 207 | through the list of available commands using the cursor keys. The list |
| 208 | of commands is arranged in alphabetical order. If you wish to jump to |
| 209 | commands in a specific part of the alphabet, you may press the letter of |
| 210 | the alphabet you wish to jump to. |
| 211 | |
| 212 | You can also just explore by typing keyboard keys. Pressing keys will |
| 213 | cause Speakup to speak the command associated with that key. For |
| 214 | example, if you press the keypad 8 key, you will hear: |
| 215 | |
| 216 | "Keypad 8 is line, say current." |
| 217 | |
Aybuke Ozdemir | f6bb9e3 | 2014-09-25 02:14:51 +0300 | [diff] [blame^] | 218 | You'll notice that some commands do not have keys assigned to them. |
William Hubbs | c6e3fd2 | 2010-10-07 13:20:02 -0500 | [diff] [blame] | 219 | This is because they are very infrequently used commands, and are also |
| 220 | accessible through the sys system. We'll discuss the sys system later |
| 221 | in this manual. |
| 222 | |
Aybuke Ozdemir | f6bb9e3 | 2014-09-25 02:14:51 +0300 | [diff] [blame^] | 223 | You'll also notice that some commands have two keys assigned to them. |
William Hubbs | c6e3fd2 | 2010-10-07 13:20:02 -0500 | [diff] [blame] | 224 | This is because Speakup has a built in set of alternative key bindings |
| 225 | for laptop users. The alternate speakup key is the caps lock key. You |
| 226 | can press and hold the caps lock key, while pressing an alternate |
| 227 | speakup command key to activate the command. On most laptops, the |
| 228 | numeric keypad is defined as the keys in the j k l area of the keyboard. |
| 229 | |
| 230 | There is usually a function key which turns this keypad function on and |
| 231 | off, and some other key which controls the numlock state. Toggling the |
| 232 | keypad functionality on and off can become a royal pain. So, Speakup |
| 233 | gives you a simple way to get at an alternative set of key mappings for |
| 234 | your laptop. These are also available by default on desktop systems, |
| 235 | because Speakup does not know whether it is running on a desktop or |
| 236 | laptop. So you may choose which set of Speakup keys to use. Some |
| 237 | system administrators may have chosen to compile Speakup for a desktop |
| 238 | system without this set of alternate key bindings, but these details are |
| 239 | beyond the scope of this manual. To use the caps lock for its normal |
| 240 | purpose, hold the shift key while toggling the caps lock on and off. We |
| 241 | should note here, that holding the caps lock key and pressing the z key |
| 242 | will toggle the alternate j k l keypad on and off. |
| 243 | |
| 244 | 4. Keys and Their Assigned Commands |
| 245 | |
| 246 | In this section, we'll go through a list of all the speakup keys and |
| 247 | commands. You can also get a list of commands and assigned keys from |
| 248 | the help system. |
| 249 | |
| 250 | The following list was taken from the speakupmap.map file. Key |
| 251 | assignments are on the left of the equal sign, and the associated |
| 252 | Speakup commands are on the right. The designation "spk" means to press |
| 253 | and hold the speakup key, a.k.a. keypad insert, a.k.a. caps lock, while |
| 254 | pressing the other specified key. |
| 255 | |
| 256 | spk key_f9 = punc_level_dec |
| 257 | spk key_f10 = punc_level_inc |
| 258 | spk key_f11 = reading_punc_dec |
| 259 | spk key_f12 = reading_punc_inc |
| 260 | spk key_1 = vol_dec |
| 261 | spk key_2 = vol_inc |
| 262 | spk key_3 = pitch_dec |
| 263 | spk key_4 = pitch_inc |
| 264 | spk key_5 = rate_dec |
| 265 | spk key_6 = rate_inc |
| 266 | key_kpasterisk = toggle_cursoring |
| 267 | spk key_kpasterisk = speakup_goto |
| 268 | spk key_f1 = speakup_help |
| 269 | spk key_f2 = set_win |
| 270 | spk key_f3 = clear_win |
| 271 | spk key_f4 = enable_win |
| 272 | spk key_f5 = edit_some |
| 273 | spk key_f6 = edit_most |
| 274 | spk key_f7 = edit_delim |
| 275 | spk key_f8 = edit_repeat |
| 276 | shift spk key_f9 = edit_exnum |
| 277 | key_kp7 = say_prev_line |
| 278 | spk key_kp7 = left_edge |
| 279 | key_kp8 = say_line |
| 280 | double key_kp8 = say_line_indent |
| 281 | spk key_kp8 = say_from_top |
| 282 | key_kp9 = say_next_line |
| 283 | spk key_kp9 = top_edge |
| 284 | key_kpminus = speakup_parked |
| 285 | spk key_kpminus = say_char_num |
| 286 | key_kp4 = say_prev_word |
| 287 | spk key_kp4 = say_from_left |
| 288 | key_kp5 = say_word |
| 289 | double key_kp5 = spell_word |
| 290 | spk key_kp5 = spell_phonetic |
| 291 | key_kp6 = say_next_word |
| 292 | spk key_kp6 = say_to_right |
| 293 | key_kpplus = say_screen |
| 294 | spk key_kpplus = say_win |
Aybuke Ozdemir | f6bb9e3 | 2014-09-25 02:14:51 +0300 | [diff] [blame^] | 295 | key_kp1 = say_prev_char |
William Hubbs | c6e3fd2 | 2010-10-07 13:20:02 -0500 | [diff] [blame] | 296 | spk key_kp1 = right_edge |
| 297 | key_kp2 = say_char |
| 298 | spk key_kp2 = say_to_bottom |
| 299 | double key_kp2 = say_phonetic_char |
Aybuke Ozdemir | f6bb9e3 | 2014-09-25 02:14:51 +0300 | [diff] [blame^] | 300 | key_kp3 = say_next_char |
William Hubbs | c6e3fd2 | 2010-10-07 13:20:02 -0500 | [diff] [blame] | 301 | spk key_kp3 = bottom_edge |
| 302 | key_kp0 = spk_key |
| 303 | key_kpdot = say_position |
| 304 | spk key_kpdot = say_attributes |
| 305 | key_kpenter = speakup_quiet |
| 306 | spk key_kpenter = speakup_off |
| 307 | key_sysrq = speech_kill |
| 308 | key_kpslash = speakup_cut |
| 309 | spk key_kpslash = speakup_paste |
| 310 | spk key_pageup = say_first_char |
| 311 | spk key_pagedown = say_last_char |
| 312 | key_capslock = spk_key |
| 313 | spk key_z = spk_lock |
| 314 | key_leftmeta = spk_key |
| 315 | ctrl spk key_0 = speakup_goto |
| 316 | spk key_u = say_prev_line |
| 317 | spk key_i = say_line |
| 318 | double spk key_i = say_line_indent |
| 319 | spk key_o = say_next_line |
| 320 | spk key_minus = speakup_parked |
| 321 | shift spk key_minus = say_char_num |
| 322 | spk key_j = say_prev_word |
| 323 | spk key_k = say_word |
| 324 | double spk key_k = spell_word |
| 325 | spk key_l = say_next_word |
| 326 | spk key_m = say_prev_char |
| 327 | spk key_comma = say_char |
| 328 | double spk key_comma = say_phonetic_char |
| 329 | spk key_dot = say_next_char |
| 330 | spk key_n = say_position |
| 331 | ctrl spk key_m = left_edge |
| 332 | ctrl spk key_y = top_edge |
| 333 | ctrl spk key_dot = right_edge |
| 334 | ctrl spk key_p = bottom_edge |
| 335 | spk key_apostrophe = say_screen |
| 336 | spk key_h = say_from_left |
| 337 | spk key_y = say_from_top |
| 338 | spk key_semicolon = say_to_right |
| 339 | spk key_p = say_to_bottom |
| 340 | spk key_slash = say_attributes |
| 341 | spk key_enter = speakup_quiet |
| 342 | ctrl spk key_enter = speakup_off |
| 343 | spk key_9 = speakup_cut |
| 344 | spk key_8 = speakup_paste |
| 345 | shift spk key_m = say_first_char |
| 346 | ctrl spk key_semicolon = say_last_char |
| 347 | |
| 348 | 5. The Speakup Sys System |
| 349 | |
| 350 | The Speakup screen reader also creates a speakup subdirectory as a part |
| 351 | of the sys system. |
| 352 | |
| 353 | As a convenience, run as root |
| 354 | |
| 355 | ln -s /sys/accessibility/speakup /speakup |
| 356 | |
Aybuke Ozdemir | f6bb9e3 | 2014-09-25 02:14:51 +0300 | [diff] [blame^] | 357 | to directly access speakup parameters from /speakup. |
William Hubbs | c6e3fd2 | 2010-10-07 13:20:02 -0500 | [diff] [blame] | 358 | You can see these entries by typing the command: |
| 359 | |
| 360 | ls -1 /speakup/* |
| 361 | |
| 362 | If you issue the above ls command, you will get back something like |
| 363 | this: |
| 364 | |
| 365 | /speakup/attrib_bleep |
| 366 | /speakup/bell_pos |
| 367 | /speakup/bleep_time |
| 368 | /speakup/bleeps |
| 369 | /speakup/cursor_time |
| 370 | /speakup/delimiters |
| 371 | /speakup/ex_num |
| 372 | /speakup/key_echo |
| 373 | /speakup/keymap |
| 374 | /speakup/no_interrupt |
| 375 | /speakup/punc_all |
| 376 | /speakup/punc_level |
| 377 | /speakup/punc_most |
| 378 | /speakup/punc_some |
| 379 | /speakup/reading_punc |
| 380 | /speakup/repeats |
| 381 | /speakup/say_control |
| 382 | /speakup/say_word_ctl |
| 383 | /speakup/silent |
| 384 | /speakup/spell_delay |
| 385 | /speakup/synth |
| 386 | /speakup/synth_direct |
| 387 | /speakup/version |
| 388 | |
| 389 | /speakup/i18n: |
| 390 | announcements |
| 391 | characters |
| 392 | chartab |
| 393 | colors |
| 394 | ctl_keys |
| 395 | formatted |
| 396 | function_names |
| 397 | key_names |
| 398 | states |
| 399 | |
| 400 | /speakup/soft: |
| 401 | caps_start |
| 402 | caps_stop |
| 403 | delay_time |
| 404 | direct |
| 405 | freq |
| 406 | full_time |
| 407 | jiffy_delta |
| 408 | pitch |
| 409 | punct |
| 410 | rate |
| 411 | tone |
| 412 | trigger_time |
| 413 | voice |
| 414 | vol |
| 415 | |
| 416 | Notice the two subdirectories of /speakup: /speakup/i18n and |
| 417 | /speakup/soft. |
| 418 | The i18n subdirectory is described in a later section. |
| 419 | The files under /speakup/soft represent settings that are specific to the |
| 420 | driver for the software synthesizer. If you use the LiteTalk, your |
| 421 | synthesizer-specific settings would be found in /speakup/ltlk. In other words, |
| 422 | a subdirectory named /speakup/KWD is created to hold parameters specific |
| 423 | to the device whose keyword is KWD. |
| 424 | These parameters include volume, rate, pitch, and others. |
| 425 | |
| 426 | In addition to using the Speakup hot keys to change such things as |
| 427 | volume, pitch, and rate, you can also echo values to the appropriate |
| 428 | entry in the /speakup directory. This is very useful, since it |
| 429 | lets you control Speakup parameters from within a script. How you |
| 430 | would write such scripts is somewhat beyond the scope of this manual, |
| 431 | but I will include a couple of simple examples here to give you a |
| 432 | general idea of what such scripts can do. |
| 433 | |
| 434 | Suppose for example, that you wanted to control both the punctuation |
| 435 | level and the reading punctuation level at the same time. For |
| 436 | simplicity, we'll call them punc0, punc1, punc2, and punc3. The scripts |
| 437 | might look something like this: |
| 438 | |
| 439 | #!/bin/bash |
| 440 | # punc0 |
| 441 | # set punc and reading punc levels to 0 |
| 442 | echo 0 >/speakup/punc_level |
| 443 | echo 0 >/speakup/reading_punc |
| 444 | echo Punctuation level set to 0. |
| 445 | |
| 446 | #!/bin/bash |
| 447 | # punc1 |
| 448 | # set punc and reading punc levels to 1 |
| 449 | echo 1 >/speakup/punc_level |
| 450 | echo 1 >/speakup/reading_punc |
| 451 | echo Punctuation level set to 1. |
| 452 | |
| 453 | #!/bin/bash |
| 454 | # punc2 |
| 455 | # set punc and reading punc levels to 2 |
| 456 | echo 2 >/speakup/punc_level |
| 457 | echo 2 >/speakup/reading_punc |
| 458 | echo Punctuation level set to 2. |
| 459 | |
| 460 | #!/bin/bash |
| 461 | # punc3 |
| 462 | # set punc and reading punc levels to 3 |
| 463 | echo 3 >/speakup/punc_level |
| 464 | echo 3 >/speakup/reading_punc |
| 465 | echo Punctuation level set to 3. |
| 466 | |
| 467 | If you were to store these four small scripts in a directory in your |
| 468 | path, perhaps /usr/local/bin, and set the permissions to 755 with the |
| 469 | chmod command, then you could change the default reading punc and |
| 470 | punctuation levels at the same time by issuing just one command. For |
| 471 | example, if you were to execute the punc3 command at your shell prompt, |
| 472 | then the reading punc and punc level would both get set to 3. |
| 473 | |
| 474 | I should note that the above scripts were written to work with bash, but |
| 475 | regardless of which shell you use, you should be able to do something |
| 476 | similar. |
| 477 | |
| 478 | The Speakup sys system also has another interesting use. You can echo |
| 479 | Speakup parameters into the sys system in a script during system |
| 480 | startup, and speakup will return to your preferred parameters every time |
| 481 | the system is rebooted. |
| 482 | |
| 483 | Most of the Speakup sys parameters can be manipulated by a regular user |
| 484 | on the system. However, there are a few parameters that are dangerous |
| 485 | enough that they should only be manipulated by the root user on your |
| 486 | system. There are even some parameters that are read only, and cannot |
| 487 | be written to at all. For example, the version entry in the Speakup |
| 488 | sys system is read only. This is because there is no reason for a user |
| 489 | to tamper with the version number which is reported by Speakup. Doing |
| 490 | an ls -l on /speakup/version will return this: |
| 491 | |
| 492 | -r--r--r-- 1 root root 0 Mar 21 13:46 /speakup/version |
| 493 | |
| 494 | As you can see, the version entry in the Speakup sys system is read |
| 495 | only, is owned by root, and belongs to the root group. Doing a cat of |
| 496 | /speakup/version will display the Speakup version number, like |
| 497 | this: |
| 498 | |
| 499 | cat /speakup/version |
Aybuke Ozdemir | f6bb9e3 | 2014-09-25 02:14:51 +0300 | [diff] [blame^] | 500 | Speakup v-2.00 CVS: Thu Oct 21 10:38:21 EDT 2004 |
William Hubbs | c6e3fd2 | 2010-10-07 13:20:02 -0500 | [diff] [blame] | 501 | synth dtlk version 1.1 |
| 502 | |
| 503 | The display shows the Speakup version number, along with the version |
| 504 | number of the driver for the current synthesizer. |
| 505 | |
| 506 | Looking at entries in the Speakup sys system can be useful in many |
| 507 | ways. For example, you might wish to know what level your volume is set |
| 508 | at. You could type: |
| 509 | |
| 510 | cat /speakup/KWD/vol |
| 511 | # Replace KWD with the keyword for your synthesizer, E.G., ltlk for LiteTalk. |
| 512 | 5 |
| 513 | |
| 514 | The number five which comes back is the level at which the synthesizer |
| 515 | volume is set at. |
| 516 | |
| 517 | All the entries in the Speakup sys system are readable, some are |
| 518 | writable by root only, and some are writable by everyone. Unless you |
| 519 | know what you are doing, you should probably leave the ones that are |
Aybuke Ozdemir | f6bb9e3 | 2014-09-25 02:14:51 +0300 | [diff] [blame^] | 520 | writable by root only alone. Most of the names are self explanatory. |
William Hubbs | c6e3fd2 | 2010-10-07 13:20:02 -0500 | [diff] [blame] | 521 | Vol for controlling volume, pitch for pitch, rate for controlling speaking |
| 522 | rate, etc. If you find one you aren't sure about, you can post a query |
| 523 | on the Speakup list. |
| 524 | |
| 525 | 6. Changing Synthesizers |
| 526 | |
| 527 | It is possible to change to a different synthesizer while speakup is |
| 528 | running. In other words, it is not necessary to reboot the system |
| 529 | in order to use a different synthesizer. You can simply echo the |
Aybuke Ozdemir | f6bb9e3 | 2014-09-25 02:14:51 +0300 | [diff] [blame^] | 530 | synthesizer keyword to the /speakup/synth sys entry. |
William Hubbs | c6e3fd2 | 2010-10-07 13:20:02 -0500 | [diff] [blame] | 531 | Depending on your situation, you may wish to echo none to the synth |
| 532 | sys entry, to disable speech while one synthesizer is disconnected and |
| 533 | a second one is connected in its place. Then echo the keyword for the |
| 534 | new synthesizer into the synth sys entry in order to start speech |
| 535 | with the newly connected synthesizer. See the list of synthesizer |
| 536 | keywords in section 1 to find the keyword which matches your synth. |
| 537 | |
| 538 | 7. Loading modules |
| 539 | |
| 540 | As mentioned earlier, Speakup can either be completely compiled into the |
| 541 | kernel, with the exception of the help module, or it can be compiled as |
| 542 | a series of modules. When compiled as modules, Speakup will only be |
| 543 | able to speak some of the bootup messages if your system administrator |
| 544 | has configured the system to load the modules at boo time. The modules |
| 545 | can be loaded after the file systems have been checked and mounted, or |
| 546 | from an initrd. There is a third possibility. Speakup can be compiled |
| 547 | with some components built into the kernel, and others as modules. As |
| 548 | we'll see in the next section, this is particularly useful when you are |
| 549 | working with software synthesizers. |
| 550 | |
| 551 | If Speakup is completely compiled as modules, then you must use the |
| 552 | modprobe command to load Speakup. You do this by loading the module for |
| 553 | the synthesizer driver you wish to use. The driver modules are all |
| 554 | named speakup_<keyword>, where <keyword> is the keyword for the |
| 555 | synthesizer you want. So, in order to load the driver for the DecTalk |
| 556 | Express, you would type the following command: |
| 557 | |
| 558 | modprobe speakup_dectlk |
| 559 | |
| 560 | Issuing this command would load the DecTalk Express driver and all other |
| 561 | related Speakup modules necessary to get Speakup up and running. |
| 562 | |
| 563 | To completely unload Speakup, again presuming that it is entirely built |
| 564 | as modules, you would give the command: |
| 565 | |
| 566 | modprobe -r speakup_dectlk |
| 567 | |
| 568 | The above command assumes you were running a DecTalk Express. If you |
| 569 | were using a different synth, then you would substitute its keyword in |
| 570 | place of dectlk. |
| 571 | |
| 572 | If you have multiple drivers loaded, you need to unload all of them, in |
| 573 | order to completely unload Speakup. |
| 574 | For example, if you have loaded both the dectlk and ltlk drivers, use the |
| 575 | command: |
| 576 | modprobe -r speakup_dectlk speakup_ltlk |
| 577 | |
| 578 | You cannot unload the driver for software synthesizers when a user-space |
| 579 | daemon is using /dev/softsynth. First, kill the daemon. Next, remove |
| 580 | the driver with the command: |
| 581 | modprobe -r speakup_soft |
| 582 | |
| 583 | Now, suppose we have a situation where the main Speakup component |
| 584 | is built into the kernel, and some or all of the drivers are built as |
| 585 | modules. Since the main part of Speakup is compiled into the kernel, a |
| 586 | partial Speakup sys system has been created which we can take advantage |
| 587 | of by simply echoing the synthesizer keyword into the |
| 588 | /speakup/synth sys entry. This will cause the kernel to |
| 589 | automatically load the appropriate driver module, and start Speakup |
| 590 | talking. To switch to another synth, just echo a new keyword to the |
| 591 | synth sys entry. For example, to load the DoubleTalk LT driver, |
| 592 | you would type: |
| 593 | |
| 594 | echo ltlk >/speakup/synth |
| 595 | |
| 596 | You can use the modprobe -r command to unload driver modules, regardless |
| 597 | of whether the main part of Speakup has been built into the kernel or |
| 598 | not. |
| 599 | |
| 600 | 8. Using Software Synthesizers |
| 601 | |
| 602 | Using a software synthesizer requires that some other software be |
| 603 | installed and running on your system. For this reason, software |
| 604 | synthesizers are not available for use at bootup, or during a system |
| 605 | installation process. |
| 606 | There are two freely-available solutions for software speech: Espeakup and |
| 607 | Speech Dispatcher. |
| 608 | These are described in subsections 8.1 and 8.2, respectively. |
| 609 | |
| 610 | During the rest of this section, we assume that speakup_soft is either |
| 611 | built in to your kernel, or loaded as a module. |
| 612 | |
| 613 | If your system does not have udev installed , before you can use a |
| 614 | software synthesizer, you must have created the /dev/softsynth device. |
| 615 | If you have not already done so, issue the following commands as root: |
| 616 | |
| 617 | cd /dev |
| 618 | mknod softsynth c 10 26 |
| 619 | |
| 620 | While we are at it, we might just as well create the /dev/synth device, |
| 621 | which can be used to let user space programs send information to your |
| 622 | synthesizer. To create /dev/synth, change to the /dev directory, and |
| 623 | issue the following command as root: |
| 624 | |
| 625 | mknod synth c 10 25 |
| 626 | |
| 627 | of both. |
| 628 | |
| 629 | 8.1. Espeakup |
| 630 | |
| 631 | Espeakup is a connector between Speakup and the eSpeak software synthesizer. |
| 632 | Espeakup may already be available as a package for your distribution |
| 633 | of Linux. If it is not packaged, you need to install it manually. |
| 634 | You can find it in the contrib/ subdirectory of the Speakup sources. |
Aybuke Ozdemir | f6bb9e3 | 2014-09-25 02:14:51 +0300 | [diff] [blame^] | 635 | The filename is espeakup-$VERSION.tar.bz2, where $VERSION |
William Hubbs | c6e3fd2 | 2010-10-07 13:20:02 -0500 | [diff] [blame] | 636 | depends on the current release of Espeakup. The Speakup 3.1.2 source |
| 637 | ships with version 0.71 of Espeakup. |
| 638 | The README file included with the Espeakup sources describes the process |
| 639 | of manual installation. |
| 640 | |
| 641 | Assuming that Espeakup is installed, either by the user or by the distributor, |
| 642 | follow these steps to use it. |
| 643 | |
| 644 | Tell Speakup to use the "soft driver: |
| 645 | echo soft > /speakup/synth |
| 646 | |
| 647 | Finally, start the espeakup program. There are two ways to do it. |
| 648 | Both require root privileges. |
| 649 | |
| 650 | If Espeakup was installed as a package for your Linux distribution, |
| 651 | you probably have a distribution-specific script that controls the operation |
| 652 | of the daemon. Look for a file named espeakup under /etc/init.d or |
| 653 | /etc/rc.d. Execute the following command with root privileges: |
| 654 | /etc/init.d/espeakup start |
| 655 | Replace init.d with rc.d, if your distribution uses scripts located under |
| 656 | /etc/rc.d. |
| 657 | Your distribution will also have a procedure for starting daemons at |
| 658 | boot-time, so it is possible to have software speech as soon as user-space |
| 659 | daemons are started by the bootup scripts. |
| 660 | These procedures are not described in this document. |
| 661 | |
| 662 | If you built Espeakup manually, the "make install" step placed the binary |
Aybuke Ozdemir | f6bb9e3 | 2014-09-25 02:14:51 +0300 | [diff] [blame^] | 663 | under /usr/bin. |
William Hubbs | c6e3fd2 | 2010-10-07 13:20:02 -0500 | [diff] [blame] | 664 | Run the following command as root: |
| 665 | /usr/bin/espeakup |
| 666 | Espeakup should start speaking. |
| 667 | |
| 668 | 8.2. Speech Dispatcher |
| 669 | |
| 670 | For this option, you must have a package called |
| 671 | Speech Dispatcher running on your system, and it must be configured to |
| 672 | work with one of its supported software synthesizers. |
| 673 | |
| 674 | Two open source synthesizers you might use are Flite and Festival. You |
| 675 | might also choose to purchase the Software DecTalk from Fonix Sales Inc. |
| 676 | If you run a google search for Fonix, you'll find their web site. |
| 677 | |
| 678 | You can obtain a copy of Speech Dispatcher from free(b)soft at |
| 679 | http://www.freebsoft.org/. Follow the installation instructions that |
| 680 | come with Speech Dispatcher in order to install and configure Speech |
| 681 | Dispatcher. You can check out the web site for your Linux distribution |
| 682 | in order to get a copy of either Flite or Festival. Your Linux |
| 683 | distribution may also have a precompiled Speech Dispatcher package. |
| 684 | |
| 685 | Once you've installed, configured, and tested Speech Dispatcher with your |
| 686 | chosen software synthesizer, you still need one more piece of software |
Aybuke Ozdemir | f6bb9e3 | 2014-09-25 02:14:51 +0300 | [diff] [blame^] | 687 | in order to make things work. You need a package called speechd-up. |
William Hubbs | c6e3fd2 | 2010-10-07 13:20:02 -0500 | [diff] [blame] | 688 | You get it from the free(b)soft web site mentioned above. After you've |
| 689 | compiled and installed speechd-up, you are almost ready to begin using |
| 690 | your software synthesizer. |
| 691 | |
| 692 | Now you can begin using your software synthesizer. In order to do so, |
| 693 | echo the soft keyword to the synth sys entry like this: |
| 694 | |
| 695 | echo soft >/speakup/synth |
| 696 | |
| 697 | Next run the speechd_up command like this: |
| 698 | |
| 699 | speechd_up & |
| 700 | |
| 701 | Your synth should now start talking, and you should be able to adjust |
| 702 | the pitch, rate, etc. |
| 703 | |
| 704 | 9. Using The DecTalk PC Card |
| 705 | |
| 706 | The DecTalk PC card is an ISA card that is inserted into one of the ISA |
| 707 | slots in your computer. It requires that the DecTalk PC software be |
| 708 | installed on your computer, and that the software be loaded onto the |
| 709 | Dectalk PC card before it can be used. |
| 710 | |
| 711 | You can get the dec_pc.tgz file from the linux-speakup.org site. The |
| 712 | dec_pc.tgz file is in the ~ftp/pub/linux/speakup directory. |
| 713 | |
| 714 | After you have downloaded the dec_pc.tgz file, untar it in your home |
| 715 | directory, and read the Readme file in the newly created dec_pc |
| 716 | directory. |
| 717 | |
| 718 | The easiest way to get the software working is to copy the entire dec_pc |
| 719 | directory into /user/local/lib. To do this, su to root in your home |
| 720 | directory, and issue the command: |
| 721 | |
| 722 | cp dec_pc /usr/local/lib |
| 723 | |
| 724 | You will need to copy the dtload command from the dec_pc directory to a |
| 725 | directory in your path. Either /usr/bin or /usr/local/bin is a good |
| 726 | choice. |
| 727 | |
| 728 | You can now run the dtload command in order to load the DecTalk PC |
| 729 | software onto the card. After you have done this, echo the decpc |
| 730 | keyword to the synth entry in the sys system like this: |
| 731 | |
| 732 | echo decpc >/speakup/synth |
| 733 | |
| 734 | Your DecTalk PC should start talking, and then you can adjust the pitch, |
| 735 | rate, volume, voice, etc. The voice entry in the Speakup sys system |
| 736 | will accept a number from 0 through 7 for the DecTalk PC synthesizer, |
| 737 | which will give you access to some of the DecTalk voices. |
| 738 | |
| 739 | 10. Using Cursor Tracking |
| 740 | |
| 741 | In Speakup version 2.0 and later, cursor tracking is turned on by |
| 742 | default. This means that when you are using an editor, Speakup will |
| 743 | automatically speak characters as you move left and right with the |
| 744 | cursor keys, and lines as you move up and down with the cursor keys. |
| 745 | This is the traditional sort of cursor tracking. |
| 746 | Recent versions of Speakup provide two additional ways to control the |
| 747 | text that is spoken when the cursor is moved: |
| 748 | "highlight tracking" and "read window." |
| 749 | They are described later in this section. |
| 750 | Sometimes, these modes get in your way, so you can disable cursor tracking |
| 751 | altogether. |
| 752 | |
| 753 | You may select among the various forms of cursor tracking using the keypad |
| 754 | asterisk key. |
| 755 | Each time you press this key, a new mode is selected, and Speakup speaks |
| 756 | the name of the new mode. The names for the four possible states of cursor |
| 757 | tracking are: "cursoring on", "highlight tracking", "read window", |
| 758 | and "cursoring off." The keypad asterisk key moves through the list of |
| 759 | modes in a circular fashion. |
| 760 | |
| 761 | If highlight tracking is enabled, Speakup tracks highlighted text, |
| 762 | rather than the cursor itself. When you move the cursor with the arrow keys, |
| 763 | Speakup speaks the currently highlighted information. |
| 764 | This is useful when moving through various menus and dialog boxes. |
| 765 | If cursor tracking isn't helping you while navigating a menu, |
| 766 | try highlight tracking. |
| 767 | |
| 768 | With the "read window" variety of cursor tracking, you can limit the text |
| 769 | that Speakup speaks by specifying a window of interest on the screen. |
| 770 | See section 15 for a description of the process of defining windows. |
| 771 | When you move the cursor via the arrow keys, Speakup only speaks |
| 772 | the contents of the window. This is especially helpful when you are hearing |
| 773 | superfluous speech. Consider the following example. |
| 774 | |
| 775 | Suppose that you are at a shell prompt. You use bash, and you want to |
| 776 | explore your command history using the up and down arrow keys. If you |
| 777 | have enabled cursor tracking, you will hear two pieces of information. |
| 778 | Speakup speaks both your shell prompt and the current entry from the |
| 779 | command history. You may not want to hear the prompt repeated |
| 780 | each time you move, so you can silence it by specifying a window. Find |
| 781 | the last line of text on the screen. Clear the current window by pressing |
| 782 | the key combination speakup f3. Use the review cursor to find the first |
| 783 | character that follows your shell prompt. Press speakup + f2 twice, to |
| 784 | define a one-line window. The boundaries of the window are the |
| 785 | character following the shell prompt and the end of the line. Now, cycle |
| 786 | through the cursor tracking modes using keypad asterisk, until Speakup |
| 787 | says "read window." Move through your history using your arrow keys. |
| 788 | You will notice that Speakup no longer speaks the redundant prompt. |
| 789 | |
| 790 | Some folks like to turn cursor tracking off while they are using the |
| 791 | lynx web browser. You definitely want to turn cursor tracking off when |
| 792 | you are using the alsamixer application. Otherwise, you won't be able |
| 793 | to hear your mixer settings while you are using the arrow keys. |
| 794 | |
| 795 | 11. Cut and Paste |
| 796 | |
| 797 | One of Speakup's more useful features is the ability to cut and paste |
| 798 | text on the screen. This means that you can capture information from a |
| 799 | program, and paste that captured text into a different place in the |
| 800 | program, or into an entirely different program, which may even be |
| 801 | running on a different console. |
| 802 | |
| 803 | For example, in this manual, we have made references to several web |
| 804 | sites. It would be nice if you could cut and paste these urls into your |
| 805 | web browser. Speakup does this quite nicely. Suppose you wanted to |
| 806 | past the following url into your browser: |
| 807 | |
| 808 | http://linux-speakup.org/ |
| 809 | |
| 810 | Use the speakup review keys to position the reading cursor on the first |
| 811 | character of the above url. When the reading cursor is in position, |
| 812 | press the keypad slash key once. Speakup will say, "mark". Next, |
| 813 | position the reading cursor on the rightmost character of the above |
| 814 | url. Press the keypad slash key once again to actually cut the text |
| 815 | from the screen. Speakup will say, "cut". Although we call this |
Aybuke Ozdemir | f6bb9e3 | 2014-09-25 02:14:51 +0300 | [diff] [blame^] | 816 | cutting, Speakup does not actually delete the cut text from the screen. |
William Hubbs | c6e3fd2 | 2010-10-07 13:20:02 -0500 | [diff] [blame] | 817 | It makes a copy of the text in a special buffer for later pasting. |
| 818 | |
| 819 | Now that you have the url cut from the screen, you can paste it into |
| 820 | your browser, or even paste the url on a command line as an argument to |
| 821 | your browser. |
| 822 | |
| 823 | Suppose you want to start lynx and go to the Speakup site. |
| 824 | |
| 825 | You can switch to a different console with the alt left and right |
| 826 | arrows, or you can switch to a specific console by typing alt and a |
| 827 | function key. These are not Speakup commands, just standard Linux |
| 828 | console capabilities. |
| 829 | |
| 830 | Once you've changed to an appropriate console, and are at a shell prompt, |
| 831 | type the word lynx, followed by a space. Now press and hold the speakup |
| 832 | key, while you type the keypad slash character. The url will be pasted |
| 833 | onto the command line, just as though you had typed it in. Press the |
| 834 | enter key to execute the command. |
| 835 | |
| 836 | The paste buffer will continue to hold the cut information, until a new |
| 837 | mark and cut operation is carried out. This means you can paste the cut |
| 838 | information as many times as you like before doing another cut |
| 839 | operation. |
| 840 | |
| 841 | You are not limited to cutting and pasting only one line on the screen. |
| 842 | You can also cut and paste rectangular regions of the screen. Just |
| 843 | position the reading cursor at the top left corner of the text to be |
| 844 | cut, mark it with the keypad slash key, then position the reading cursor |
| 845 | at the bottom right corner of the region to be cut, and cut it with the |
| 846 | keypad slash key. |
| 847 | |
| 848 | 12. Changing the Pronunciation of Characters |
| 849 | |
| 850 | Through the /speakup/i18n/characters sys entry, Speakup gives you the |
| 851 | ability to change how Speakup pronounces a given character. You could, |
| 852 | for example, change how some punctuation characters are spoken. You can |
| 853 | even change how Speakup will pronounce certain letters. |
| 854 | |
| 855 | You may, for example, wish to change how Speakup pronounces the z |
| 856 | character. The author of Speakup, Kirk Reiser, is Canadian, and thus |
| 857 | believes that the z should be pronounced zed. If you are an American, |
| 858 | you might wish to use the zee pronunciation instead of zed. You can |
| 859 | change the pronunciation of both the upper and lower case z with the |
| 860 | following two commands: |
| 861 | |
| 862 | echo 90 zee >/speakup/characters |
| 863 | echo 122 zee >/speakup/characters |
| 864 | |
| 865 | Let's examine the parts of the two previous commands. They are issued |
| 866 | at the shell prompt, and could be placed in a startup script. |
| 867 | |
| 868 | The word echo tells the shell that you want to have it display the |
| 869 | string of characters that follow the word echo. If you were to just |
| 870 | type: |
| 871 | |
| 872 | echo hello. |
| 873 | |
| 874 | You would get the word hello printed on your screen as soon as you |
| 875 | pressed the enter key. In this case, we are echoing strings that we |
| 876 | want to be redirected into the sys system. |
| 877 | |
| 878 | The numbers 90 and 122 in the above echo commands are the ascii numeric |
| 879 | values for the upper and lower case z, the characters we wish to change. |
| 880 | |
| 881 | The string zee is the pronunciation that we want Speakup to use for the |
| 882 | upper and lower case z. |
| 883 | |
| 884 | The > symbol redirects the output of the echo command to a file, just |
| 885 | like in DOS, or at the Windows command prompt. |
| 886 | |
| 887 | And finally, /speakup/i18n/characters is the file entry in the sys system |
| 888 | where we want the output to be directed. Speakup looks at the numeric |
| 889 | value of the character we want to change, and inserts the pronunciation |
| 890 | string into an internal table. |
| 891 | |
| 892 | You can look at the whole table with the following command: |
| 893 | |
| 894 | cat /speakup/i18n/characters |
| 895 | |
| 896 | Speakup will then print out the entire character pronunciation table. I |
| 897 | won't display it here, but leave you to look at it at your convenience. |
| 898 | |
| 899 | 13. Mapping Keys |
| 900 | |
| 901 | Speakup has the capability of allowing you to assign or "map" keys to |
| 902 | internal Speakup commands. This section necessarily assumes you have a |
| 903 | Linux kernel source tree installed, and that it has been patched and |
| 904 | configured with Speakup. How you do this is beyond the scope of this |
| 905 | manual. For this information, visit the Speakup web site at |
| 906 | http://linux-speakup.org/. The reason you'll need the kernel source |
| 907 | tree patched with Speakup is that the genmap utility you'll need for |
| 908 | processing keymaps is in the |
| 909 | /usr/src/linux-<version_number>/drivers/char/speakup directory. The |
| 910 | <version_number> in the above directory path is the version number of |
| 911 | the Linux source tree you are working with. |
| 912 | |
| 913 | So ok, you've gone off and gotten your kernel source tree, and patched |
| 914 | and configured it. Now you can start manipulating keymaps. |
| 915 | |
| 916 | You can either use the |
| 917 | /usr/src/linux-<version_number>/drivers/char/speakup/speakupmap.map file |
| 918 | included with the Speakup source, or you can cut and paste the copy in |
| 919 | section 4 into a separate file. If you use the one in the Speakup |
| 920 | source tree, make sure you make a backup of it before you start making |
| 921 | changes. You have been warned! |
| 922 | |
| 923 | Suppose that you want to swap the key assignments for the Speakup |
| 924 | say_last_char and the Speakup say_first_char commands. The |
| 925 | speakupmap.map lists the key mappings for these two commands as follows: |
| 926 | |
| 927 | spk key_pageup = say_first_char |
| 928 | spk key_pagedown = say_last_char |
| 929 | |
| 930 | You can edit your copy of the speakupmap.map file and swap the command |
| 931 | names on the right side of the = (equals) sign. You did make a backup, |
| 932 | right? The new keymap lines would look like this: |
| 933 | |
| 934 | spk key_pageup = say_last_char |
| 935 | spk key_pagedown = say_first_char |
| 936 | |
| 937 | After you edit your copy of the speakupmap.map file, save it under a new |
| 938 | file name, perhaps newmap.map. Then exit your editor and return to the |
| 939 | shell prompt. |
| 940 | |
| 941 | You are now ready to load your keymap with your swapped key assignments. |
| 942 | Assuming that you saved your new keymap as the file newmap.map, you |
| 943 | would load your keymap into the sys system like this: |
| 944 | |
| 945 | /usr/src/linux-<version_number>/drivers/char/speakup/genmap newmap.map |
| 946 | >/speakup/keymap |
| 947 | |
| 948 | Remember to substitute your kernel version number for the |
| 949 | <version_number> in the above command. Also note that although the |
| 950 | above command wrapped onto two lines in this document, you should type |
| 951 | it all on one line. |
| 952 | |
| 953 | Your say first and say last characters should now be swapped. Pressing |
| 954 | speakup pagedown should read you the first non-whitespace character on |
| 955 | the line your reading cursor is in, and pressing speakup pageup should |
| 956 | read you the last character on the line your reading cursor is in. |
| 957 | |
| 958 | You should note that these new mappings will only stay in effect until |
| 959 | you reboot, or until you load another keymap. |
| 960 | |
| 961 | One final warning. If you try to load a partial map, you will quickly |
| 962 | find that all the mappings you didn't include in your file got deleted |
Aybuke Ozdemir | f6bb9e3 | 2014-09-25 02:14:51 +0300 | [diff] [blame^] | 963 | from the working map. Be extremely careful, and always make a backup! |
William Hubbs | c6e3fd2 | 2010-10-07 13:20:02 -0500 | [diff] [blame] | 964 | You have been warned! |
| 965 | |
| 966 | 14. Internationalizing Speakup |
| 967 | |
| 968 | Speakup indicates various conditions to the user by speaking messages. |
| 969 | For instance, when you move to the left edge of the screen with the |
| 970 | review keys, Speakup says, "left." |
| 971 | Prior to version 3.1.0 of Speakup, all of these messages were in English, |
| 972 | and they could not be changed. If you used a non-English synthesizer, |
| 973 | you still heard English messages, such as "left" and "cursoring on." |
| 974 | In version 3.1.0 or higher, one may load translations for the various |
| 975 | messages via the /sys filesystem. |
| 976 | |
| 977 | The directory /speakup/i18n contains several collections of messages. |
| 978 | Each group of messages is stored in its own file. |
| 979 | The following section lists all of these files, along with a brief description |
| 980 | of each. |
| 981 | |
| 982 | 14.1. Files Under the i18n Subdirectory |
| 983 | |
| 984 | * announcements: |
| 985 | This file contains various general announcements, most of which cannot |
| 986 | be categorized. You will find messages such as "You killed Speakup", |
| 987 | "I'm alive", "leaving help", "parked", "unparked", and others. |
| 988 | You will also find the names of the screen edges and cursor tracking modes |
| 989 | here. |
| 990 | |
| 991 | * characters: |
| 992 | See section 12 for a description of this file. |
| 993 | |
| 994 | * chartab: |
| 995 | See section 12. Unlike the rest of the files in the i18n subdirectory, |
| 996 | this one does not contain messages to be spoken. |
| 997 | |
| 998 | * colors: |
| 999 | When you use the "say attributes" function, Speakup says the name of the |
| 1000 | foreground and background colors. These names come from the i18n/colors |
| 1001 | file. |
| 1002 | |
| 1003 | * ctl_keys: |
| 1004 | Here, you will find names of control keys. These are used with Speakup's |
| 1005 | say_control feature. |
| 1006 | |
| 1007 | * formatted: |
| 1008 | This group of messages contains embedded formatting codes, to specify |
| 1009 | the type and width of displayed data. If you change these, you must |
| 1010 | preserve all of the formatting codes, and they must appear in the order |
| 1011 | used by the default messages. |
| 1012 | |
| 1013 | * function_names: |
| 1014 | Here, you will find a list of names for Speakup functions. These are used |
| 1015 | by the help system. For example, suppose that you have activated help mode, |
| 1016 | and you pressed keypad 3. Speakup says: |
| 1017 | "keypad 3 is character, say next." |
| 1018 | The message "character, say next" names a Speakup function, and it |
| 1019 | comes from this function_names file. |
| 1020 | |
| 1021 | * key_names: |
| 1022 | Again, key_names is used by Speakup's help system. In the previous |
| 1023 | example, Speakup said that you pressed "keypad 3." |
| 1024 | This name came from the key_names file. |
| 1025 | |
| 1026 | * states: |
| 1027 | This file contains names for key states. |
| 1028 | Again, these are part of the help system. For instance, if you had pressed |
| 1029 | speakup + keypad 3, you would hear: |
| 1030 | "speakup keypad 3 is go to bottom edge." |
| 1031 | The speakup key is depressed, so the name of the key state is speakup. |
| 1032 | This part of the message comes from the states collection. |
| 1033 | |
| 1034 | 14.2. Loading Your Own Messages |
| 1035 | |
| 1036 | The files under the i18n subdirectory all follow the same format. |
| 1037 | They consist of lines, with one message per line. |
| 1038 | Each message is represented by a number, followed by the text of the message. |
| 1039 | The number is the position of the message in the given collection. |
| 1040 | For example, if you view the file /speakup/i18n/colors, you will see the |
| 1041 | following list: |
| 1042 | |
| 1043 | 0 black |
| 1044 | 1 blue |
| 1045 | 2 green |
| 1046 | 3 cyan |
| 1047 | 4 red |
| 1048 | 5 magenta |
| 1049 | 6 yellow |
| 1050 | 7 white |
| 1051 | 8 grey |
| 1052 | |
| 1053 | You can change one message, or you can change a whole group. |
| 1054 | To load a whole collection of messages from a new source, simply use |
| 1055 | the cp command: |
| 1056 | cp ~/my_colors /speakup/i18n/colors |
| 1057 | You can change an individual message with the echo command, |
| 1058 | as shown in the following example. |
| 1059 | |
| 1060 | The Spanish name for the color blue is azul. |
| 1061 | Looking at the colors file, we see that the name "blue" is at position 1 |
| 1062 | within the colors group. Let's change blue to azul: |
| 1063 | echo '1 azul' > /speakup/i18n/colors |
| 1064 | The next time that Speakup says message 1 from the colors group, it will |
| 1065 | say "azul", rather than "blue." |
| 1066 | |
| 1067 | In the future, translations into various languages will be made available, |
| 1068 | and most users will just load the files necessary for their language. |
| 1069 | |
| 1070 | 14.3. No Support for Non-Western-European Languages |
| 1071 | |
| 1072 | As of the current release, Speakup only supports Western European languages. |
| 1073 | Support for the extended characters used by languages outside of the Western |
| 1074 | European family of languages is a work in progress. |
| 1075 | |
| 1076 | 15. Using Speakup's Windowing Capability |
| 1077 | |
| 1078 | Speakup has the capability of defining and manipulating windows on the |
| 1079 | screen. Speakup uses the term "Window", to mean a user defined area of |
| 1080 | the screen. The key strokes for defining and manipulating Speakup |
| 1081 | windows are as follows: |
| 1082 | |
| 1083 | speakup + f2 -- Set the bounds of the window. |
| 1084 | Speakup + f3 -- clear the current window definition. |
| 1085 | speakup + f4 -- Toggle window silence on and off. |
| 1086 | speakup + keypad plus -- Say the currently defined window. |
| 1087 | |
| 1088 | These capabilities are useful for tracking a certain part of the screen |
| 1089 | without rereading the whole screen, or for silencing a part of the |
| 1090 | screen that is constantly changing, such as a clock or status line. |
| 1091 | |
| 1092 | There is no way to save these window settings, and you can only have one |
| 1093 | window defined for each virtual console. There is also no way to have |
Lucas De Marchi | 25985ed | 2011-03-30 22:57:33 -0300 | [diff] [blame] | 1094 | windows automatically defined for specific applications. |
William Hubbs | c6e3fd2 | 2010-10-07 13:20:02 -0500 | [diff] [blame] | 1095 | |
| 1096 | In order to define a window, use the review keys to move your reading |
| 1097 | cursor to the beginning of the area you want to define. Then press |
| 1098 | speakup + f2. Speakup will tell you that the window starts at the |
| 1099 | indicated row and column position. Then move the reading cursor to the |
| 1100 | end of the area to be defined as a window, and press speakup + f2 again. |
| 1101 | If there is more than one line in the window, Speakup will tell you |
| 1102 | that the window ends at the indicated row and column position. If there |
| 1103 | is only one line in the window, then Speakup will tell you that the |
| 1104 | window is the specified line on the screen. If you are only defining a |
| 1105 | one line window, you can just press speakup + f2 twice after placing the |
| 1106 | reading cursor on the line you want to define as a window. It is not |
| 1107 | necessary to position the reading cursor at the end of the line in order |
| 1108 | to define the whole line as a window. |
| 1109 | |
| 1110 | 16. Tools for Controlling Speakup |
| 1111 | |
| 1112 | The speakup distribution includes extra tools (in the tools directory) |
| 1113 | which were written to make speakup easier to use. This section will |
| 1114 | briefly describe the use of these tools. |
| 1115 | |
| 1116 | 16.1. Speakupconf |
| 1117 | |
| 1118 | speakupconf began life as a contribution from Steve Holmes, a member of |
| 1119 | the speakup community. We would like to thank him for his work on the |
| 1120 | early versions of this project. |
| 1121 | |
| 1122 | This script may be installed as part of your linux distribution, but if |
| 1123 | it isn't, the recommended places to put it are /usr/local/bin or |
| 1124 | /usr/bin. This script can be run by any user, so it does not require |
| 1125 | root privileges. |
| 1126 | |
| 1127 | Speakupconf allows you to save and load your Speakup settings. It works |
| 1128 | by reading and writing the /sys files described above. |
| 1129 | |
| 1130 | The directory that speakupconf uses to store your settings depends on |
| 1131 | whether it is run from the root account. If you execute speakupconf as |
| 1132 | root, it uses the directory /etc/speakup. Otherwise, it uses the directory |
| 1133 | ~/.speakup, where ~ is your home directory. |
| 1134 | Anyone who needs to use Speakup from your console can load his own custom |
| 1135 | settings with this script. |
| 1136 | |
| 1137 | speakupconf takes one required argument: load or save. |
| 1138 | Use the command |
| 1139 | speakupconf save |
| 1140 | to save your Speakup settings, and |
| 1141 | speakupconf load |
| 1142 | to load them into Speakup. |
| 1143 | A second argument may be specified to use an alternate directory to |
| 1144 | load or save the speakup parameters. |
| 1145 | |
| 1146 | 16.2. Talkwith |
| 1147 | |
| 1148 | Charles Hallenbeck, another member of the speakup community, wrote the |
| 1149 | initial versions of this script, and we would also like to thank him for |
| 1150 | his work on it. |
| 1151 | |
| 1152 | This script needs root privileges to run, so if it is not installed as |
| 1153 | part of your linux distribution, the recommended places to install it |
| 1154 | are /usr/local/sbin or /usr/sbin. |
| 1155 | |
| 1156 | Talkwith allows you to switch synthesizers on the fly. It takes a synthesizer |
| 1157 | name as an argument. For instance, |
| 1158 | talkwith dectlk |
| 1159 | causes Speakup to use the DecTalk Express. If you wish to switch to a |
| 1160 | software synthesizer, you must also indicate which daemon you wish to |
| 1161 | use. There are two possible choices: |
| 1162 | spd and espeakup. spd is an abbreviation for speechd-up. |
| 1163 | If you wish to use espeakup for software synthesis, give the command |
| 1164 | talkwith soft espeakup |
| 1165 | To use speechd-up, type: |
| 1166 | talkwith soft spd |
| 1167 | Any arguments that follow the name of the daemon are passed to the daemon |
| 1168 | when it is invoked. For instance: |
| 1169 | talkwith espeakup --default-voice=fr |
| 1170 | causes espeakup to use the French voice. |
| 1171 | Note that talkwith must always be executed with root privileges. |
| 1172 | |
| 1173 | Talkwith does not attempt to load your settings after the new |
| 1174 | synthesizer is activated. You can use speakupconf to load your settings |
| 1175 | if desired. |
| 1176 | |
| 1177 | GNU Free Documentation License |
| 1178 | Version 1.2, November 2002 |
| 1179 | |
| 1180 | |
| 1181 | Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. |
| 1182 | 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
| 1183 | Everyone is permitted to copy and distribute verbatim copies |
| 1184 | of this license document, but changing it is not allowed. |
| 1185 | |
| 1186 | |
| 1187 | 0. PREAMBLE |
| 1188 | |
| 1189 | The purpose of this License is to make a manual, textbook, or other |
| 1190 | functional and useful document "free" in the sense of freedom: to |
| 1191 | assure everyone the effective freedom to copy and redistribute it, |
| 1192 | with or without modifying it, either commercially or noncommercially. |
| 1193 | Secondarily, this License preserves for the author and publisher a way |
| 1194 | to get credit for their work, while not being considered responsible |
| 1195 | for modifications made by others. |
| 1196 | |
| 1197 | This License is a kind of "copyleft", which means that derivative |
| 1198 | works of the document must themselves be free in the same sense. It |
| 1199 | complements the GNU General Public License, which is a copyleft |
| 1200 | license designed for free software. |
| 1201 | |
| 1202 | We have designed this License in order to use it for manuals for free |
| 1203 | software, because free software needs free documentation: a free |
| 1204 | program should come with manuals providing the same freedoms that the |
| 1205 | software does. But this License is not limited to software manuals; |
| 1206 | it can be used for any textual work, regardless of subject matter or |
| 1207 | whether it is published as a printed book. We recommend this License |
| 1208 | principally for works whose purpose is instruction or reference. |
| 1209 | |
| 1210 | |
| 1211 | 1. APPLICABILITY AND DEFINITIONS |
| 1212 | |
| 1213 | This License applies to any manual or other work, in any medium, that |
| 1214 | contains a notice placed by the copyright holder saying it can be |
| 1215 | distributed under the terms of this License. Such a notice grants a |
| 1216 | world-wide, royalty-free license, unlimited in duration, to use that |
| 1217 | work under the conditions stated herein. The "Document", below, |
| 1218 | refers to any such manual or work. Any member of the public is a |
| 1219 | licensee, and is addressed as "you". You accept the license if you |
| 1220 | copy, modify or distribute the work in a way requiring permission |
| 1221 | under copyright law. |
| 1222 | |
| 1223 | A "Modified Version" of the Document means any work containing the |
| 1224 | Document or a portion of it, either copied verbatim, or with |
| 1225 | modifications and/or translated into another language. |
| 1226 | |
| 1227 | A "Secondary Section" is a named appendix or a front-matter section of |
| 1228 | the Document that deals exclusively with the relationship of the |
| 1229 | publishers or authors of the Document to the Document's overall subject |
| 1230 | (or to related matters) and contains nothing that could fall directly |
| 1231 | within that overall subject. (Thus, if the Document is in part a |
| 1232 | textbook of mathematics, a Secondary Section may not explain any |
| 1233 | mathematics.) The relationship could be a matter of historical |
| 1234 | connection with the subject or with related matters, or of legal, |
| 1235 | commercial, philosophical, ethical or political position regarding |
| 1236 | them. |
| 1237 | |
| 1238 | The "Invariant Sections" are certain Secondary Sections whose titles |
| 1239 | are designated, as being those of Invariant Sections, in the notice |
| 1240 | that says that the Document is released under this License. If a |
| 1241 | section does not fit the above definition of Secondary then it is not |
| 1242 | allowed to be designated as Invariant. The Document may contain zero |
| 1243 | Invariant Sections. If the Document does not identify any Invariant |
| 1244 | Sections then there are none. |
| 1245 | |
| 1246 | The "Cover Texts" are certain short passages of text that are listed, |
| 1247 | as Front-Cover Texts or Back-Cover Texts, in the notice that says that |
| 1248 | the Document is released under this License. A Front-Cover Text may |
| 1249 | be at most 5 words, and a Back-Cover Text may be at most 25 words. |
| 1250 | |
| 1251 | A "Transparent" copy of the Document means a machine-readable copy, |
| 1252 | represented in a format whose specification is available to the |
| 1253 | general public, that is suitable for revising the document |
| 1254 | straightforwardly with generic text editors or (for images composed of |
| 1255 | pixels) generic paint programs or (for drawings) some widely available |
| 1256 | drawing editor, and that is suitable for input to text formatters or |
| 1257 | for automatic translation to a variety of formats suitable for input |
| 1258 | to text formatters. A copy made in an otherwise Transparent file |
| 1259 | format whose markup, or absence of markup, has been arranged to thwart |
| 1260 | or discourage subsequent modification by readers is not Transparent. |
| 1261 | An image format is not Transparent if used for any substantial amount |
| 1262 | of text. A copy that is not "Transparent" is called "Opaque". |
| 1263 | |
| 1264 | Examples of suitable formats for Transparent copies include plain |
| 1265 | ASCII without markup, Texinfo input format, LaTeX input format, SGML |
| 1266 | or XML using a publicly available DTD, and standard-conforming simple |
| 1267 | HTML, PostScript or PDF designed for human modification. Examples of |
| 1268 | transparent image formats include PNG, XCF and JPG. Opaque formats |
| 1269 | include proprietary formats that can be read and edited only by |
| 1270 | proprietary word processors, SGML or XML for which the DTD and/or |
| 1271 | processing tools are not generally available, and the |
| 1272 | machine-generated HTML, PostScript or PDF produced by some word |
| 1273 | processors for output purposes only. |
| 1274 | |
| 1275 | The "Title Page" means, for a printed book, the title page itself, |
| 1276 | plus such following pages as are needed to hold, legibly, the material |
| 1277 | this License requires to appear in the title page. For works in |
| 1278 | formats which do not have any title page as such, "Title Page" means |
| 1279 | the text near the most prominent appearance of the work's title, |
| 1280 | preceding the beginning of the body of the text. |
| 1281 | |
| 1282 | A section "Entitled XYZ" means a named subunit of the Document whose |
| 1283 | title either is precisely XYZ or contains XYZ in parentheses following |
| 1284 | text that translates XYZ in another language. (Here XYZ stands for a |
| 1285 | specific section name mentioned below, such as "Acknowledgements", |
| 1286 | "Dedications", "Endorsements", or "History".) To "Preserve the Title" |
| 1287 | of such a section when you modify the Document means that it remains a |
| 1288 | section "Entitled XYZ" according to this definition. |
| 1289 | |
| 1290 | The Document may include Warranty Disclaimers next to the notice which |
| 1291 | states that this License applies to the Document. These Warranty |
| 1292 | Disclaimers are considered to be included by reference in this |
| 1293 | License, but only as regards disclaiming warranties: any other |
| 1294 | implication that these Warranty Disclaimers may have is void and has |
| 1295 | no effect on the meaning of this License. |
| 1296 | |
| 1297 | |
| 1298 | 2. VERBATIM COPYING |
| 1299 | |
| 1300 | You may copy and distribute the Document in any medium, either |
| 1301 | commercially or noncommercially, provided that this License, the |
| 1302 | copyright notices, and the license notice saying this License applies |
| 1303 | to the Document are reproduced in all copies, and that you add no other |
| 1304 | conditions whatsoever to those of this License. You may not use |
| 1305 | technical measures to obstruct or control the reading or further |
| 1306 | copying of the copies you make or distribute. However, you may accept |
| 1307 | compensation in exchange for copies. If you distribute a large enough |
| 1308 | number of copies you must also follow the conditions in section 3. |
| 1309 | |
| 1310 | You may also lend copies, under the same conditions stated above, and |
| 1311 | you may publicly display copies. |
| 1312 | |
| 1313 | |
| 1314 | 3. COPYING IN QUANTITY |
| 1315 | |
| 1316 | If you publish printed copies (or copies in media that commonly have |
| 1317 | printed covers) of the Document, numbering more than 100, and the |
| 1318 | Document's license notice requires Cover Texts, you must enclose the |
| 1319 | copies in covers that carry, clearly and legibly, all these Cover |
| 1320 | Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on |
| 1321 | the back cover. Both covers must also clearly and legibly identify |
| 1322 | you as the publisher of these copies. The front cover must present |
| 1323 | the full title with all words of the title equally prominent and |
| 1324 | visible. You may add other material on the covers in addition. |
| 1325 | Copying with changes limited to the covers, as long as they preserve |
| 1326 | the title of the Document and satisfy these conditions, can be treated |
| 1327 | as verbatim copying in other respects. |
| 1328 | |
| 1329 | If the required texts for either cover are too voluminous to fit |
| 1330 | legibly, you should put the first ones listed (as many as fit |
| 1331 | reasonably) on the actual cover, and continue the rest onto adjacent |
| 1332 | pages. |
| 1333 | |
| 1334 | If you publish or distribute Opaque copies of the Document numbering |
| 1335 | more than 100, you must either include a machine-readable Transparent |
| 1336 | copy along with each Opaque copy, or state in or with each Opaque copy |
| 1337 | a computer-network location from which the general network-using |
| 1338 | public has access to download using public-standard network protocols |
| 1339 | a complete Transparent copy of the Document, free of added material. |
| 1340 | If you use the latter option, you must take reasonably prudent steps, |
| 1341 | when you begin distribution of Opaque copies in quantity, to ensure |
| 1342 | that this Transparent copy will remain thus accessible at the stated |
| 1343 | location until at least one year after the last time you distribute an |
| 1344 | Opaque copy (directly or through your agents or retailers) of that |
| 1345 | edition to the public. |
| 1346 | |
| 1347 | It is requested, but not required, that you contact the authors of the |
| 1348 | Document well before redistributing any large number of copies, to give |
| 1349 | them a chance to provide you with an updated version of the Document. |
| 1350 | |
| 1351 | |
| 1352 | 4. MODIFICATIONS |
| 1353 | |
| 1354 | You may copy and distribute a Modified Version of the Document under |
| 1355 | the conditions of sections 2 and 3 above, provided that you release |
| 1356 | the Modified Version under precisely this License, with the Modified |
| 1357 | Version filling the role of the Document, thus licensing distribution |
| 1358 | and modification of the Modified Version to whoever possesses a copy |
| 1359 | of it. In addition, you must do these things in the Modified Version: |
| 1360 | |
| 1361 | A. Use in the Title Page (and on the covers, if any) a title distinct |
| 1362 | from that of the Document, and from those of previous versions |
| 1363 | (which should, if there were any, be listed in the History section |
| 1364 | of the Document). You may use the same title as a previous version |
| 1365 | if the original publisher of that version gives permission. |
| 1366 | B. List on the Title Page, as authors, one or more persons or entities |
| 1367 | responsible for authorship of the modifications in the Modified |
| 1368 | Version, together with at least five of the principal authors of the |
| 1369 | Document (all of its principal authors, if it has fewer than five), |
| 1370 | unless they release you from this requirement. |
| 1371 | C. State on the Title page the name of the publisher of the |
| 1372 | Modified Version, as the publisher. |
| 1373 | D. Preserve all the copyright notices of the Document. |
| 1374 | E. Add an appropriate copyright notice for your modifications |
| 1375 | adjacent to the other copyright notices. |
| 1376 | F. Include, immediately after the copyright notices, a license notice |
| 1377 | giving the public permission to use the Modified Version under the |
| 1378 | terms of this License, in the form shown in the Addendum below. |
| 1379 | G. Preserve in that license notice the full lists of Invariant Sections |
| 1380 | and required Cover Texts given in the Document's license notice. |
| 1381 | H. Include an unaltered copy of this License. |
| 1382 | I. Preserve the section Entitled "History", Preserve its Title, and add |
| 1383 | to it an item stating at least the title, year, new authors, and |
| 1384 | publisher of the Modified Version as given on the Title Page. If |
| 1385 | there is no section Entitled "History" in the Document, create one |
| 1386 | stating the title, year, authors, and publisher of the Document as |
| 1387 | given on its Title Page, then add an item describing the Modified |
| 1388 | Version as stated in the previous sentence. |
| 1389 | J. Preserve the network location, if any, given in the Document for |
| 1390 | public access to a Transparent copy of the Document, and likewise |
| 1391 | the network locations given in the Document for previous versions |
| 1392 | it was based on. These may be placed in the "History" section. |
| 1393 | You may omit a network location for a work that was published at |
| 1394 | least four years before the Document itself, or if the original |
| 1395 | publisher of the version it refers to gives permission. |
| 1396 | K. For any section Entitled "Acknowledgements" or "Dedications", |
| 1397 | Preserve the Title of the section, and preserve in the section all |
| 1398 | the substance and tone of each of the contributor acknowledgements |
| 1399 | and/or dedications given therein. |
| 1400 | L. Preserve all the Invariant Sections of the Document, |
| 1401 | unaltered in their text and in their titles. Section numbers |
| 1402 | or the equivalent are not considered part of the section titles. |
| 1403 | M. Delete any section Entitled "Endorsements". Such a section |
| 1404 | may not be included in the Modified Version. |
| 1405 | N. Do not retitle any existing section to be Entitled "Endorsements" |
| 1406 | or to conflict in title with any Invariant Section. |
| 1407 | O. Preserve any Warranty Disclaimers. |
| 1408 | |
| 1409 | If the Modified Version includes new front-matter sections or |
| 1410 | appendices that qualify as Secondary Sections and contain no material |
| 1411 | copied from the Document, you may at your option designate some or all |
| 1412 | of these sections as invariant. To do this, add their titles to the |
| 1413 | list of Invariant Sections in the Modified Version's license notice. |
| 1414 | These titles must be distinct from any other section titles. |
| 1415 | |
| 1416 | You may add a section Entitled "Endorsements", provided it contains |
| 1417 | nothing but endorsements of your Modified Version by various |
| 1418 | parties--for example, statements of peer review or that the text has |
| 1419 | been approved by an organization as the authoritative definition of a |
| 1420 | standard. |
| 1421 | |
| 1422 | You may add a passage of up to five words as a Front-Cover Text, and a |
| 1423 | passage of up to 25 words as a Back-Cover Text, to the end of the list |
| 1424 | of Cover Texts in the Modified Version. Only one passage of |
| 1425 | Front-Cover Text and one of Back-Cover Text may be added by (or |
| 1426 | through arrangements made by) any one entity. If the Document already |
| 1427 | includes a cover text for the same cover, previously added by you or |
| 1428 | by arrangement made by the same entity you are acting on behalf of, |
| 1429 | you may not add another; but you may replace the old one, on explicit |
| 1430 | permission from the previous publisher that added the old one. |
| 1431 | |
| 1432 | The author(s) and publisher(s) of the Document do not by this License |
| 1433 | give permission to use their names for publicity for or to assert or |
| 1434 | imply endorsement of any Modified Version. |
| 1435 | |
| 1436 | |
| 1437 | 5. COMBINING DOCUMENTS |
| 1438 | |
| 1439 | You may combine the Document with other documents released under this |
| 1440 | License, under the terms defined in section 4 above for modified |
| 1441 | versions, provided that you include in the combination all of the |
| 1442 | Invariant Sections of all of the original documents, unmodified, and |
| 1443 | list them all as Invariant Sections of your combined work in its |
| 1444 | license notice, and that you preserve all their Warranty Disclaimers. |
| 1445 | |
| 1446 | The combined work need only contain one copy of this License, and |
| 1447 | multiple identical Invariant Sections may be replaced with a single |
| 1448 | copy. If there are multiple Invariant Sections with the same name but |
| 1449 | different contents, make the title of each such section unique by |
| 1450 | adding at the end of it, in parentheses, the name of the original |
| 1451 | author or publisher of that section if known, or else a unique number. |
| 1452 | Make the same adjustment to the section titles in the list of |
| 1453 | Invariant Sections in the license notice of the combined work. |
| 1454 | |
| 1455 | In the combination, you must combine any sections Entitled "History" |
| 1456 | in the various original documents, forming one section Entitled |
| 1457 | "History"; likewise combine any sections Entitled "Acknowledgements", |
| 1458 | and any sections Entitled "Dedications". You must delete all sections |
| 1459 | Entitled "Endorsements". |
| 1460 | |
| 1461 | |
| 1462 | 6. COLLECTIONS OF DOCUMENTS |
| 1463 | |
| 1464 | You may make a collection consisting of the Document and other documents |
| 1465 | released under this License, and replace the individual copies of this |
| 1466 | License in the various documents with a single copy that is included in |
| 1467 | the collection, provided that you follow the rules of this License for |
| 1468 | verbatim copying of each of the documents in all other respects. |
| 1469 | |
| 1470 | You may extract a single document from such a collection, and distribute |
| 1471 | it individually under this License, provided you insert a copy of this |
| 1472 | License into the extracted document, and follow this License in all |
| 1473 | other respects regarding verbatim copying of that document. |
| 1474 | |
| 1475 | |
| 1476 | 7. AGGREGATION WITH INDEPENDENT WORKS |
| 1477 | |
| 1478 | A compilation of the Document or its derivatives with other separate |
| 1479 | and independent documents or works, in or on a volume of a storage or |
| 1480 | distribution medium, is called an "aggregate" if the copyright |
| 1481 | resulting from the compilation is not used to limit the legal rights |
| 1482 | of the compilation's users beyond what the individual works permit. |
| 1483 | When the Document is included in an aggregate, this License does not |
| 1484 | apply to the other works in the aggregate which are not themselves |
| 1485 | derivative works of the Document. |
| 1486 | |
| 1487 | If the Cover Text requirement of section 3 is applicable to these |
| 1488 | copies of the Document, then if the Document is less than one half of |
| 1489 | the entire aggregate, the Document's Cover Texts may be placed on |
| 1490 | covers that bracket the Document within the aggregate, or the |
| 1491 | electronic equivalent of covers if the Document is in electronic form. |
| 1492 | Otherwise they must appear on printed covers that bracket the whole |
| 1493 | aggregate. |
| 1494 | |
| 1495 | |
| 1496 | 8. TRANSLATION |
| 1497 | |
| 1498 | Translation is considered a kind of modification, so you may |
| 1499 | distribute translations of the Document under the terms of section 4. |
| 1500 | Replacing Invariant Sections with translations requires special |
| 1501 | permission from their copyright holders, but you may include |
| 1502 | translations of some or all Invariant Sections in addition to the |
| 1503 | original versions of these Invariant Sections. You may include a |
| 1504 | translation of this License, and all the license notices in the |
| 1505 | Document, and any Warranty Disclaimers, provided that you also include |
| 1506 | the original English version of this License and the original versions |
| 1507 | of those notices and disclaimers. In case of a disagreement between |
| 1508 | the translation and the original version of this License or a notice |
| 1509 | or disclaimer, the original version will prevail. |
| 1510 | |
| 1511 | If a section in the Document is Entitled "Acknowledgements", |
| 1512 | "Dedications", or "History", the requirement (section 4) to Preserve |
| 1513 | its Title (section 1) will typically require changing the actual |
| 1514 | title. |
| 1515 | |
| 1516 | |
| 1517 | 9. TERMINATION |
| 1518 | |
| 1519 | You may not copy, modify, sublicense, or distribute the Document except |
| 1520 | as expressly provided for under this License. Any other attempt to |
| 1521 | copy, modify, sublicense or distribute the Document is void, and will |
| 1522 | automatically terminate your rights under this License. However, |
| 1523 | parties who have received copies, or rights, from you under this |
| 1524 | License will not have their licenses terminated so long as such |
| 1525 | parties remain in full compliance. |
| 1526 | |
| 1527 | |
| 1528 | 10. FUTURE REVISIONS OF THIS LICENSE |
| 1529 | |
| 1530 | The Free Software Foundation may publish new, revised versions |
| 1531 | of the GNU Free Documentation License from time to time. Such new |
| 1532 | versions will be similar in spirit to the present version, but may |
| 1533 | differ in detail to address new problems or concerns. See |
| 1534 | http://www.gnu.org/copyleft/. |
| 1535 | |
| 1536 | Each version of the License is given a distinguishing version number. |
| 1537 | If the Document specifies that a particular numbered version of this |
| 1538 | License "or any later version" applies to it, you have the option of |
| 1539 | following the terms and conditions either of that specified version or |
| 1540 | of any later version that has been published (not as a draft) by the |
| 1541 | Free Software Foundation. If the Document does not specify a version |
| 1542 | number of this License, you may choose any version ever published (not |
| 1543 | as a draft) by the Free Software Foundation. |
| 1544 | |
| 1545 | |
| 1546 | ADDENDUM: How to use this License for your documents |
| 1547 | |
| 1548 | To use this License in a document you have written, include a copy of |
| 1549 | the License in the document and put the following copyright and |
| 1550 | license notices just after the title page: |
| 1551 | |
| 1552 | Copyright (c) YEAR YOUR NAME. |
| 1553 | Permission is granted to copy, distribute and/or modify this document |
| 1554 | under the terms of the GNU Free Documentation License, Version 1.2 |
| 1555 | or any later version published by the Free Software Foundation; |
| 1556 | with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. |
| 1557 | A copy of the license is included in the section entitled "GNU |
| 1558 | Free Documentation License". |
| 1559 | |
| 1560 | If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, |
| 1561 | replace the "with...Texts." line with this: |
| 1562 | |
| 1563 | with the Invariant Sections being LIST THEIR TITLES, with the |
| 1564 | Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. |
| 1565 | |
| 1566 | If you have Invariant Sections without Cover Texts, or some other |
| 1567 | combination of the three, merge those two alternatives to suit the |
| 1568 | situation. |
| 1569 | |
| 1570 | If your document contains nontrivial examples of program code, we |
| 1571 | recommend releasing these examples in parallel under your choice of |
| 1572 | free software license, such as the GNU General Public License, |
| 1573 | to permit their use in free software. |
| 1574 | |
| 1575 | The End. |