Commit | Line | Data |
---|---|---|
c6e3fd22 WH |
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 | |
f6bb9e39 | 91 | their related software is loaded, and so are not available at boot up. |
c6e3fd22 WH |
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 | |
f6bb9e39 | 109 | talking as soon as the kernel is loaded. In fact, it will talk a lot! |
c6e3fd22 WH |
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 | ||
f6bb9e39 | 118 | Note: In this guide I will refer to the numeric keypad as the keypad. |
c6e3fd22 WH |
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 | |
f6bb9e39 | 146 | to silence it again if the boot process has not completed. |
c6e3fd22 WH |
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 | |
f6bb9e39 | 162 | the speech with keypad enter, or use any of the Speakup review keys. |
c6e3fd22 WH |
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 | ||
f6bb9e39 | 218 | You'll notice that some commands do not have keys assigned to them. |
c6e3fd22 WH |
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 | ||
f6bb9e39 | 223 | You'll also notice that some commands have two keys assigned to them. |
c6e3fd22 WH |
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 | |
f6bb9e39 | 295 | key_kp1 = say_prev_char |
c6e3fd22 WH |
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 | |
f6bb9e39 | 300 | key_kp3 = say_next_char |
c6e3fd22 WH |
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 | |
f96a15c7 | 347 | spk key_r = read_all_doc |
c6e3fd22 WH |
348 | |
349 | 5. The Speakup Sys System | |
350 | ||
351 | The Speakup screen reader also creates a speakup subdirectory as a part | |
352 | of the sys system. | |
353 | ||
354 | As a convenience, run as root | |
355 | ||
356 | ln -s /sys/accessibility/speakup /speakup | |
357 | ||
f6bb9e39 | 358 | to directly access speakup parameters from /speakup. |
c6e3fd22 WH |
359 | You can see these entries by typing the command: |
360 | ||
361 | ls -1 /speakup/* | |
362 | ||
363 | If you issue the above ls command, you will get back something like | |
364 | this: | |
365 | ||
366 | /speakup/attrib_bleep | |
367 | /speakup/bell_pos | |
368 | /speakup/bleep_time | |
369 | /speakup/bleeps | |
370 | /speakup/cursor_time | |
371 | /speakup/delimiters | |
372 | /speakup/ex_num | |
373 | /speakup/key_echo | |
374 | /speakup/keymap | |
375 | /speakup/no_interrupt | |
376 | /speakup/punc_all | |
377 | /speakup/punc_level | |
378 | /speakup/punc_most | |
379 | /speakup/punc_some | |
380 | /speakup/reading_punc | |
381 | /speakup/repeats | |
382 | /speakup/say_control | |
383 | /speakup/say_word_ctl | |
384 | /speakup/silent | |
385 | /speakup/spell_delay | |
386 | /speakup/synth | |
387 | /speakup/synth_direct | |
388 | /speakup/version | |
389 | ||
390 | /speakup/i18n: | |
391 | announcements | |
392 | characters | |
393 | chartab | |
394 | colors | |
395 | ctl_keys | |
396 | formatted | |
397 | function_names | |
398 | key_names | |
399 | states | |
400 | ||
401 | /speakup/soft: | |
402 | caps_start | |
403 | caps_stop | |
404 | delay_time | |
405 | direct | |
406 | freq | |
407 | full_time | |
408 | jiffy_delta | |
409 | pitch | |
d97a9d7a | 410 | inflection |
c6e3fd22 WH |
411 | punct |
412 | rate | |
413 | tone | |
414 | trigger_time | |
415 | voice | |
416 | vol | |
417 | ||
418 | Notice the two subdirectories of /speakup: /speakup/i18n and | |
419 | /speakup/soft. | |
420 | The i18n subdirectory is described in a later section. | |
421 | The files under /speakup/soft represent settings that are specific to the | |
422 | driver for the software synthesizer. If you use the LiteTalk, your | |
423 | synthesizer-specific settings would be found in /speakup/ltlk. In other words, | |
424 | a subdirectory named /speakup/KWD is created to hold parameters specific | |
425 | to the device whose keyword is KWD. | |
426 | These parameters include volume, rate, pitch, and others. | |
427 | ||
428 | In addition to using the Speakup hot keys to change such things as | |
429 | volume, pitch, and rate, you can also echo values to the appropriate | |
430 | entry in the /speakup directory. This is very useful, since it | |
431 | lets you control Speakup parameters from within a script. How you | |
432 | would write such scripts is somewhat beyond the scope of this manual, | |
433 | but I will include a couple of simple examples here to give you a | |
434 | general idea of what such scripts can do. | |
435 | ||
436 | Suppose for example, that you wanted to control both the punctuation | |
437 | level and the reading punctuation level at the same time. For | |
438 | simplicity, we'll call them punc0, punc1, punc2, and punc3. The scripts | |
439 | might look something like this: | |
440 | ||
441 | #!/bin/bash | |
442 | # punc0 | |
443 | # set punc and reading punc levels to 0 | |
444 | echo 0 >/speakup/punc_level | |
445 | echo 0 >/speakup/reading_punc | |
446 | echo Punctuation level set to 0. | |
447 | ||
448 | #!/bin/bash | |
449 | # punc1 | |
450 | # set punc and reading punc levels to 1 | |
451 | echo 1 >/speakup/punc_level | |
452 | echo 1 >/speakup/reading_punc | |
453 | echo Punctuation level set to 1. | |
454 | ||
455 | #!/bin/bash | |
456 | # punc2 | |
457 | # set punc and reading punc levels to 2 | |
458 | echo 2 >/speakup/punc_level | |
459 | echo 2 >/speakup/reading_punc | |
460 | echo Punctuation level set to 2. | |
461 | ||
462 | #!/bin/bash | |
463 | # punc3 | |
464 | # set punc and reading punc levels to 3 | |
465 | echo 3 >/speakup/punc_level | |
466 | echo 3 >/speakup/reading_punc | |
467 | echo Punctuation level set to 3. | |
468 | ||
469 | If you were to store these four small scripts in a directory in your | |
470 | path, perhaps /usr/local/bin, and set the permissions to 755 with the | |
471 | chmod command, then you could change the default reading punc and | |
472 | punctuation levels at the same time by issuing just one command. For | |
473 | example, if you were to execute the punc3 command at your shell prompt, | |
474 | then the reading punc and punc level would both get set to 3. | |
475 | ||
476 | I should note that the above scripts were written to work with bash, but | |
477 | regardless of which shell you use, you should be able to do something | |
478 | similar. | |
479 | ||
480 | The Speakup sys system also has another interesting use. You can echo | |
481 | Speakup parameters into the sys system in a script during system | |
482 | startup, and speakup will return to your preferred parameters every time | |
483 | the system is rebooted. | |
484 | ||
485 | Most of the Speakup sys parameters can be manipulated by a regular user | |
486 | on the system. However, there are a few parameters that are dangerous | |
487 | enough that they should only be manipulated by the root user on your | |
488 | system. There are even some parameters that are read only, and cannot | |
489 | be written to at all. For example, the version entry in the Speakup | |
490 | sys system is read only. This is because there is no reason for a user | |
491 | to tamper with the version number which is reported by Speakup. Doing | |
492 | an ls -l on /speakup/version will return this: | |
493 | ||
494 | -r--r--r-- 1 root root 0 Mar 21 13:46 /speakup/version | |
495 | ||
496 | As you can see, the version entry in the Speakup sys system is read | |
497 | only, is owned by root, and belongs to the root group. Doing a cat of | |
498 | /speakup/version will display the Speakup version number, like | |
499 | this: | |
500 | ||
501 | cat /speakup/version | |
f6bb9e39 | 502 | Speakup v-2.00 CVS: Thu Oct 21 10:38:21 EDT 2004 |
c6e3fd22 WH |
503 | synth dtlk version 1.1 |
504 | ||
505 | The display shows the Speakup version number, along with the version | |
506 | number of the driver for the current synthesizer. | |
507 | ||
508 | Looking at entries in the Speakup sys system can be useful in many | |
509 | ways. For example, you might wish to know what level your volume is set | |
510 | at. You could type: | |
511 | ||
512 | cat /speakup/KWD/vol | |
513 | # Replace KWD with the keyword for your synthesizer, E.G., ltlk for LiteTalk. | |
514 | 5 | |
515 | ||
516 | The number five which comes back is the level at which the synthesizer | |
517 | volume is set at. | |
518 | ||
519 | All the entries in the Speakup sys system are readable, some are | |
520 | writable by root only, and some are writable by everyone. Unless you | |
521 | know what you are doing, you should probably leave the ones that are | |
f6bb9e39 | 522 | writable by root only alone. Most of the names are self explanatory. |
d97a9d7a ST |
523 | Vol for controlling volume, pitch for pitch, inflection for pitch range, rate |
524 | for controlling speaking rate, etc. If you find one you aren't sure about, you | |
525 | can post a query on the Speakup list. | |
c6e3fd22 WH |
526 | |
527 | 6. Changing Synthesizers | |
528 | ||
529 | It is possible to change to a different synthesizer while speakup is | |
530 | running. In other words, it is not necessary to reboot the system | |
531 | in order to use a different synthesizer. You can simply echo the | |
f6bb9e39 | 532 | synthesizer keyword to the /speakup/synth sys entry. |
c6e3fd22 WH |
533 | Depending on your situation, you may wish to echo none to the synth |
534 | sys entry, to disable speech while one synthesizer is disconnected and | |
535 | a second one is connected in its place. Then echo the keyword for the | |
536 | new synthesizer into the synth sys entry in order to start speech | |
537 | with the newly connected synthesizer. See the list of synthesizer | |
538 | keywords in section 1 to find the keyword which matches your synth. | |
539 | ||
540 | 7. Loading modules | |
541 | ||
542 | As mentioned earlier, Speakup can either be completely compiled into the | |
543 | kernel, with the exception of the help module, or it can be compiled as | |
544 | a series of modules. When compiled as modules, Speakup will only be | |
545 | able to speak some of the bootup messages if your system administrator | |
d64fbe9f | 546 | has configured the system to load the modules at boot time. The modules |
c6e3fd22 WH |
547 | can be loaded after the file systems have been checked and mounted, or |
548 | from an initrd. There is a third possibility. Speakup can be compiled | |
549 | with some components built into the kernel, and others as modules. As | |
550 | we'll see in the next section, this is particularly useful when you are | |
551 | working with software synthesizers. | |
552 | ||
553 | If Speakup is completely compiled as modules, then you must use the | |
554 | modprobe command to load Speakup. You do this by loading the module for | |
555 | the synthesizer driver you wish to use. The driver modules are all | |
556 | named speakup_<keyword>, where <keyword> is the keyword for the | |
557 | synthesizer you want. So, in order to load the driver for the DecTalk | |
558 | Express, you would type the following command: | |
559 | ||
560 | modprobe speakup_dectlk | |
561 | ||
562 | Issuing this command would load the DecTalk Express driver and all other | |
563 | related Speakup modules necessary to get Speakup up and running. | |
564 | ||
565 | To completely unload Speakup, again presuming that it is entirely built | |
566 | as modules, you would give the command: | |
567 | ||
568 | modprobe -r speakup_dectlk | |
569 | ||
570 | The above command assumes you were running a DecTalk Express. If you | |
571 | were using a different synth, then you would substitute its keyword in | |
572 | place of dectlk. | |
573 | ||
574 | If you have multiple drivers loaded, you need to unload all of them, in | |
575 | order to completely unload Speakup. | |
576 | For example, if you have loaded both the dectlk and ltlk drivers, use the | |
577 | command: | |
578 | modprobe -r speakup_dectlk speakup_ltlk | |
579 | ||
580 | You cannot unload the driver for software synthesizers when a user-space | |
581 | daemon is using /dev/softsynth. First, kill the daemon. Next, remove | |
582 | the driver with the command: | |
583 | modprobe -r speakup_soft | |
584 | ||
585 | Now, suppose we have a situation where the main Speakup component | |
586 | is built into the kernel, and some or all of the drivers are built as | |
587 | modules. Since the main part of Speakup is compiled into the kernel, a | |
588 | partial Speakup sys system has been created which we can take advantage | |
589 | of by simply echoing the synthesizer keyword into the | |
590 | /speakup/synth sys entry. This will cause the kernel to | |
591 | automatically load the appropriate driver module, and start Speakup | |
592 | talking. To switch to another synth, just echo a new keyword to the | |
593 | synth sys entry. For example, to load the DoubleTalk LT driver, | |
594 | you would type: | |
595 | ||
596 | echo ltlk >/speakup/synth | |
597 | ||
598 | You can use the modprobe -r command to unload driver modules, regardless | |
599 | of whether the main part of Speakup has been built into the kernel or | |
600 | not. | |
601 | ||
602 | 8. Using Software Synthesizers | |
603 | ||
604 | Using a software synthesizer requires that some other software be | |
605 | installed and running on your system. For this reason, software | |
606 | synthesizers are not available for use at bootup, or during a system | |
607 | installation process. | |
608 | There are two freely-available solutions for software speech: Espeakup and | |
609 | Speech Dispatcher. | |
610 | These are described in subsections 8.1 and 8.2, respectively. | |
611 | ||
612 | During the rest of this section, we assume that speakup_soft is either | |
613 | built in to your kernel, or loaded as a module. | |
614 | ||
615 | If your system does not have udev installed , before you can use a | |
616 | software synthesizer, you must have created the /dev/softsynth device. | |
617 | If you have not already done so, issue the following commands as root: | |
618 | ||
619 | cd /dev | |
620 | mknod softsynth c 10 26 | |
621 | ||
622 | While we are at it, we might just as well create the /dev/synth device, | |
623 | which can be used to let user space programs send information to your | |
624 | synthesizer. To create /dev/synth, change to the /dev directory, and | |
625 | issue the following command as root: | |
626 | ||
627 | mknod synth c 10 25 | |
628 | ||
629 | of both. | |
630 | ||
631 | 8.1. Espeakup | |
632 | ||
633 | Espeakup is a connector between Speakup and the eSpeak software synthesizer. | |
634 | Espeakup may already be available as a package for your distribution | |
635 | of Linux. If it is not packaged, you need to install it manually. | |
636 | You can find it in the contrib/ subdirectory of the Speakup sources. | |
f6bb9e39 | 637 | The filename is espeakup-$VERSION.tar.bz2, where $VERSION |
c6e3fd22 WH |
638 | depends on the current release of Espeakup. The Speakup 3.1.2 source |
639 | ships with version 0.71 of Espeakup. | |
640 | The README file included with the Espeakup sources describes the process | |
641 | of manual installation. | |
642 | ||
643 | Assuming that Espeakup is installed, either by the user or by the distributor, | |
644 | follow these steps to use it. | |
645 | ||
646 | Tell Speakup to use the "soft driver: | |
647 | echo soft > /speakup/synth | |
648 | ||
649 | Finally, start the espeakup program. There are two ways to do it. | |
650 | Both require root privileges. | |
651 | ||
652 | If Espeakup was installed as a package for your Linux distribution, | |
653 | you probably have a distribution-specific script that controls the operation | |
654 | of the daemon. Look for a file named espeakup under /etc/init.d or | |
655 | /etc/rc.d. Execute the following command with root privileges: | |
656 | /etc/init.d/espeakup start | |
657 | Replace init.d with rc.d, if your distribution uses scripts located under | |
658 | /etc/rc.d. | |
659 | Your distribution will also have a procedure for starting daemons at | |
660 | boot-time, so it is possible to have software speech as soon as user-space | |
661 | daemons are started by the bootup scripts. | |
662 | These procedures are not described in this document. | |
663 | ||
664 | If you built Espeakup manually, the "make install" step placed the binary | |
f6bb9e39 | 665 | under /usr/bin. |
c6e3fd22 WH |
666 | Run the following command as root: |
667 | /usr/bin/espeakup | |
668 | Espeakup should start speaking. | |
669 | ||
670 | 8.2. Speech Dispatcher | |
671 | ||
672 | For this option, you must have a package called | |
673 | Speech Dispatcher running on your system, and it must be configured to | |
674 | work with one of its supported software synthesizers. | |
675 | ||
676 | Two open source synthesizers you might use are Flite and Festival. You | |
677 | might also choose to purchase the Software DecTalk from Fonix Sales Inc. | |
678 | If you run a google search for Fonix, you'll find their web site. | |
679 | ||
680 | You can obtain a copy of Speech Dispatcher from free(b)soft at | |
681 | http://www.freebsoft.org/. Follow the installation instructions that | |
682 | come with Speech Dispatcher in order to install and configure Speech | |
683 | Dispatcher. You can check out the web site for your Linux distribution | |
684 | in order to get a copy of either Flite or Festival. Your Linux | |
685 | distribution may also have a precompiled Speech Dispatcher package. | |
686 | ||
687 | Once you've installed, configured, and tested Speech Dispatcher with your | |
688 | chosen software synthesizer, you still need one more piece of software | |
f6bb9e39 | 689 | in order to make things work. You need a package called speechd-up. |
c6e3fd22 WH |
690 | You get it from the free(b)soft web site mentioned above. After you've |
691 | compiled and installed speechd-up, you are almost ready to begin using | |
692 | your software synthesizer. | |
693 | ||
694 | Now you can begin using your software synthesizer. In order to do so, | |
695 | echo the soft keyword to the synth sys entry like this: | |
696 | ||
697 | echo soft >/speakup/synth | |
698 | ||
699 | Next run the speechd_up command like this: | |
700 | ||
701 | speechd_up & | |
702 | ||
703 | Your synth should now start talking, and you should be able to adjust | |
704 | the pitch, rate, etc. | |
705 | ||
706 | 9. Using The DecTalk PC Card | |
707 | ||
708 | The DecTalk PC card is an ISA card that is inserted into one of the ISA | |
709 | slots in your computer. It requires that the DecTalk PC software be | |
710 | installed on your computer, and that the software be loaded onto the | |
711 | Dectalk PC card before it can be used. | |
712 | ||
713 | You can get the dec_pc.tgz file from the linux-speakup.org site. The | |
714 | dec_pc.tgz file is in the ~ftp/pub/linux/speakup directory. | |
715 | ||
716 | After you have downloaded the dec_pc.tgz file, untar it in your home | |
717 | directory, and read the Readme file in the newly created dec_pc | |
718 | directory. | |
719 | ||
720 | The easiest way to get the software working is to copy the entire dec_pc | |
721 | directory into /user/local/lib. To do this, su to root in your home | |
722 | directory, and issue the command: | |
723 | ||
724 | cp dec_pc /usr/local/lib | |
725 | ||
726 | You will need to copy the dtload command from the dec_pc directory to a | |
727 | directory in your path. Either /usr/bin or /usr/local/bin is a good | |
728 | choice. | |
729 | ||
730 | You can now run the dtload command in order to load the DecTalk PC | |
731 | software onto the card. After you have done this, echo the decpc | |
732 | keyword to the synth entry in the sys system like this: | |
733 | ||
734 | echo decpc >/speakup/synth | |
735 | ||
736 | Your DecTalk PC should start talking, and then you can adjust the pitch, | |
737 | rate, volume, voice, etc. The voice entry in the Speakup sys system | |
738 | will accept a number from 0 through 7 for the DecTalk PC synthesizer, | |
739 | which will give you access to some of the DecTalk voices. | |
740 | ||
741 | 10. Using Cursor Tracking | |
742 | ||
743 | In Speakup version 2.0 and later, cursor tracking is turned on by | |
744 | default. This means that when you are using an editor, Speakup will | |
745 | automatically speak characters as you move left and right with the | |
746 | cursor keys, and lines as you move up and down with the cursor keys. | |
747 | This is the traditional sort of cursor tracking. | |
748 | Recent versions of Speakup provide two additional ways to control the | |
749 | text that is spoken when the cursor is moved: | |
750 | "highlight tracking" and "read window." | |
751 | They are described later in this section. | |
752 | Sometimes, these modes get in your way, so you can disable cursor tracking | |
753 | altogether. | |
754 | ||
755 | You may select among the various forms of cursor tracking using the keypad | |
756 | asterisk key. | |
757 | Each time you press this key, a new mode is selected, and Speakup speaks | |
758 | the name of the new mode. The names for the four possible states of cursor | |
759 | tracking are: "cursoring on", "highlight tracking", "read window", | |
760 | and "cursoring off." The keypad asterisk key moves through the list of | |
761 | modes in a circular fashion. | |
762 | ||
763 | If highlight tracking is enabled, Speakup tracks highlighted text, | |
764 | rather than the cursor itself. When you move the cursor with the arrow keys, | |
765 | Speakup speaks the currently highlighted information. | |
766 | This is useful when moving through various menus and dialog boxes. | |
767 | If cursor tracking isn't helping you while navigating a menu, | |
768 | try highlight tracking. | |
769 | ||
770 | With the "read window" variety of cursor tracking, you can limit the text | |
771 | that Speakup speaks by specifying a window of interest on the screen. | |
772 | See section 15 for a description of the process of defining windows. | |
773 | When you move the cursor via the arrow keys, Speakup only speaks | |
774 | the contents of the window. This is especially helpful when you are hearing | |
775 | superfluous speech. Consider the following example. | |
776 | ||
777 | Suppose that you are at a shell prompt. You use bash, and you want to | |
778 | explore your command history using the up and down arrow keys. If you | |
779 | have enabled cursor tracking, you will hear two pieces of information. | |
780 | Speakup speaks both your shell prompt and the current entry from the | |
781 | command history. You may not want to hear the prompt repeated | |
782 | each time you move, so you can silence it by specifying a window. Find | |
783 | the last line of text on the screen. Clear the current window by pressing | |
784 | the key combination speakup f3. Use the review cursor to find the first | |
785 | character that follows your shell prompt. Press speakup + f2 twice, to | |
786 | define a one-line window. The boundaries of the window are the | |
787 | character following the shell prompt and the end of the line. Now, cycle | |
788 | through the cursor tracking modes using keypad asterisk, until Speakup | |
789 | says "read window." Move through your history using your arrow keys. | |
790 | You will notice that Speakup no longer speaks the redundant prompt. | |
791 | ||
792 | Some folks like to turn cursor tracking off while they are using the | |
793 | lynx web browser. You definitely want to turn cursor tracking off when | |
794 | you are using the alsamixer application. Otherwise, you won't be able | |
795 | to hear your mixer settings while you are using the arrow keys. | |
796 | ||
797 | 11. Cut and Paste | |
798 | ||
799 | One of Speakup's more useful features is the ability to cut and paste | |
800 | text on the screen. This means that you can capture information from a | |
801 | program, and paste that captured text into a different place in the | |
802 | program, or into an entirely different program, which may even be | |
803 | running on a different console. | |
804 | ||
805 | For example, in this manual, we have made references to several web | |
806 | sites. It would be nice if you could cut and paste these urls into your | |
807 | web browser. Speakup does this quite nicely. Suppose you wanted to | |
808 | past the following url into your browser: | |
809 | ||
810 | http://linux-speakup.org/ | |
811 | ||
812 | Use the speakup review keys to position the reading cursor on the first | |
813 | character of the above url. When the reading cursor is in position, | |
814 | press the keypad slash key once. Speakup will say, "mark". Next, | |
815 | position the reading cursor on the rightmost character of the above | |
816 | url. Press the keypad slash key once again to actually cut the text | |
817 | from the screen. Speakup will say, "cut". Although we call this | |
f6bb9e39 | 818 | cutting, Speakup does not actually delete the cut text from the screen. |
c6e3fd22 WH |
819 | It makes a copy of the text in a special buffer for later pasting. |
820 | ||
821 | Now that you have the url cut from the screen, you can paste it into | |
822 | your browser, or even paste the url on a command line as an argument to | |
823 | your browser. | |
824 | ||
825 | Suppose you want to start lynx and go to the Speakup site. | |
826 | ||
827 | You can switch to a different console with the alt left and right | |
828 | arrows, or you can switch to a specific console by typing alt and a | |
829 | function key. These are not Speakup commands, just standard Linux | |
830 | console capabilities. | |
831 | ||
832 | Once you've changed to an appropriate console, and are at a shell prompt, | |
833 | type the word lynx, followed by a space. Now press and hold the speakup | |
834 | key, while you type the keypad slash character. The url will be pasted | |
835 | onto the command line, just as though you had typed it in. Press the | |
836 | enter key to execute the command. | |
837 | ||
838 | The paste buffer will continue to hold the cut information, until a new | |
839 | mark and cut operation is carried out. This means you can paste the cut | |
840 | information as many times as you like before doing another cut | |
841 | operation. | |
842 | ||
843 | You are not limited to cutting and pasting only one line on the screen. | |
844 | You can also cut and paste rectangular regions of the screen. Just | |
845 | position the reading cursor at the top left corner of the text to be | |
846 | cut, mark it with the keypad slash key, then position the reading cursor | |
847 | at the bottom right corner of the region to be cut, and cut it with the | |
848 | keypad slash key. | |
849 | ||
850 | 12. Changing the Pronunciation of Characters | |
851 | ||
852 | Through the /speakup/i18n/characters sys entry, Speakup gives you the | |
853 | ability to change how Speakup pronounces a given character. You could, | |
854 | for example, change how some punctuation characters are spoken. You can | |
855 | even change how Speakup will pronounce certain letters. | |
856 | ||
857 | You may, for example, wish to change how Speakup pronounces the z | |
858 | character. The author of Speakup, Kirk Reiser, is Canadian, and thus | |
859 | believes that the z should be pronounced zed. If you are an American, | |
860 | you might wish to use the zee pronunciation instead of zed. You can | |
861 | change the pronunciation of both the upper and lower case z with the | |
862 | following two commands: | |
863 | ||
864 | echo 90 zee >/speakup/characters | |
865 | echo 122 zee >/speakup/characters | |
866 | ||
867 | Let's examine the parts of the two previous commands. They are issued | |
868 | at the shell prompt, and could be placed in a startup script. | |
869 | ||
870 | The word echo tells the shell that you want to have it display the | |
871 | string of characters that follow the word echo. If you were to just | |
872 | type: | |
873 | ||
874 | echo hello. | |
875 | ||
876 | You would get the word hello printed on your screen as soon as you | |
877 | pressed the enter key. In this case, we are echoing strings that we | |
878 | want to be redirected into the sys system. | |
879 | ||
880 | The numbers 90 and 122 in the above echo commands are the ascii numeric | |
881 | values for the upper and lower case z, the characters we wish to change. | |
882 | ||
883 | The string zee is the pronunciation that we want Speakup to use for the | |
884 | upper and lower case z. | |
885 | ||
886 | The > symbol redirects the output of the echo command to a file, just | |
887 | like in DOS, or at the Windows command prompt. | |
888 | ||
889 | And finally, /speakup/i18n/characters is the file entry in the sys system | |
890 | where we want the output to be directed. Speakup looks at the numeric | |
891 | value of the character we want to change, and inserts the pronunciation | |
892 | string into an internal table. | |
893 | ||
894 | You can look at the whole table with the following command: | |
895 | ||
896 | cat /speakup/i18n/characters | |
897 | ||
898 | Speakup will then print out the entire character pronunciation table. I | |
899 | won't display it here, but leave you to look at it at your convenience. | |
900 | ||
901 | 13. Mapping Keys | |
902 | ||
903 | Speakup has the capability of allowing you to assign or "map" keys to | |
904 | internal Speakup commands. This section necessarily assumes you have a | |
905 | Linux kernel source tree installed, and that it has been patched and | |
906 | configured with Speakup. How you do this is beyond the scope of this | |
907 | manual. For this information, visit the Speakup web site at | |
908 | http://linux-speakup.org/. The reason you'll need the kernel source | |
909 | tree patched with Speakup is that the genmap utility you'll need for | |
910 | processing keymaps is in the | |
911 | /usr/src/linux-<version_number>/drivers/char/speakup directory. The | |
912 | <version_number> in the above directory path is the version number of | |
913 | the Linux source tree you are working with. | |
914 | ||
915 | So ok, you've gone off and gotten your kernel source tree, and patched | |
916 | and configured it. Now you can start manipulating keymaps. | |
917 | ||
918 | You can either use the | |
919 | /usr/src/linux-<version_number>/drivers/char/speakup/speakupmap.map file | |
920 | included with the Speakup source, or you can cut and paste the copy in | |
921 | section 4 into a separate file. If you use the one in the Speakup | |
922 | source tree, make sure you make a backup of it before you start making | |
923 | changes. You have been warned! | |
924 | ||
925 | Suppose that you want to swap the key assignments for the Speakup | |
926 | say_last_char and the Speakup say_first_char commands. The | |
927 | speakupmap.map lists the key mappings for these two commands as follows: | |
928 | ||
929 | spk key_pageup = say_first_char | |
930 | spk key_pagedown = say_last_char | |
931 | ||
932 | You can edit your copy of the speakupmap.map file and swap the command | |
933 | names on the right side of the = (equals) sign. You did make a backup, | |
934 | right? The new keymap lines would look like this: | |
935 | ||
936 | spk key_pageup = say_last_char | |
937 | spk key_pagedown = say_first_char | |
938 | ||
939 | After you edit your copy of the speakupmap.map file, save it under a new | |
940 | file name, perhaps newmap.map. Then exit your editor and return to the | |
941 | shell prompt. | |
942 | ||
943 | You are now ready to load your keymap with your swapped key assignments. | |
944 | Assuming that you saved your new keymap as the file newmap.map, you | |
945 | would load your keymap into the sys system like this: | |
946 | ||
947 | /usr/src/linux-<version_number>/drivers/char/speakup/genmap newmap.map | |
948 | >/speakup/keymap | |
949 | ||
950 | Remember to substitute your kernel version number for the | |
951 | <version_number> in the above command. Also note that although the | |
952 | above command wrapped onto two lines in this document, you should type | |
953 | it all on one line. | |
954 | ||
955 | Your say first and say last characters should now be swapped. Pressing | |
956 | speakup pagedown should read you the first non-whitespace character on | |
957 | the line your reading cursor is in, and pressing speakup pageup should | |
958 | read you the last character on the line your reading cursor is in. | |
959 | ||
960 | You should note that these new mappings will only stay in effect until | |
961 | you reboot, or until you load another keymap. | |
962 | ||
963 | One final warning. If you try to load a partial map, you will quickly | |
964 | find that all the mappings you didn't include in your file got deleted | |
f6bb9e39 | 965 | from the working map. Be extremely careful, and always make a backup! |
c6e3fd22 WH |
966 | You have been warned! |
967 | ||
968 | 14. Internationalizing Speakup | |
969 | ||
970 | Speakup indicates various conditions to the user by speaking messages. | |
971 | For instance, when you move to the left edge of the screen with the | |
972 | review keys, Speakup says, "left." | |
973 | Prior to version 3.1.0 of Speakup, all of these messages were in English, | |
974 | and they could not be changed. If you used a non-English synthesizer, | |
975 | you still heard English messages, such as "left" and "cursoring on." | |
976 | In version 3.1.0 or higher, one may load translations for the various | |
977 | messages via the /sys filesystem. | |
978 | ||
979 | The directory /speakup/i18n contains several collections of messages. | |
980 | Each group of messages is stored in its own file. | |
981 | The following section lists all of these files, along with a brief description | |
982 | of each. | |
983 | ||
984 | 14.1. Files Under the i18n Subdirectory | |
985 | ||
986 | * announcements: | |
987 | This file contains various general announcements, most of which cannot | |
988 | be categorized. You will find messages such as "You killed Speakup", | |
989 | "I'm alive", "leaving help", "parked", "unparked", and others. | |
990 | You will also find the names of the screen edges and cursor tracking modes | |
991 | here. | |
992 | ||
993 | * characters: | |
994 | See section 12 for a description of this file. | |
995 | ||
996 | * chartab: | |
997 | See section 12. Unlike the rest of the files in the i18n subdirectory, | |
998 | this one does not contain messages to be spoken. | |
999 | ||
1000 | * colors: | |
1001 | When you use the "say attributes" function, Speakup says the name of the | |
1002 | foreground and background colors. These names come from the i18n/colors | |
1003 | file. | |
1004 | ||
1005 | * ctl_keys: | |
1006 | Here, you will find names of control keys. These are used with Speakup's | |
1007 | say_control feature. | |
1008 | ||
1009 | * formatted: | |
1010 | This group of messages contains embedded formatting codes, to specify | |
1011 | the type and width of displayed data. If you change these, you must | |
1012 | preserve all of the formatting codes, and they must appear in the order | |
1013 | used by the default messages. | |
1014 | ||
1015 | * function_names: | |
1016 | Here, you will find a list of names for Speakup functions. These are used | |
1017 | by the help system. For example, suppose that you have activated help mode, | |
1018 | and you pressed keypad 3. Speakup says: | |
1019 | "keypad 3 is character, say next." | |
1020 | The message "character, say next" names a Speakup function, and it | |
1021 | comes from this function_names file. | |
1022 | ||
1023 | * key_names: | |
1024 | Again, key_names is used by Speakup's help system. In the previous | |
1025 | example, Speakup said that you pressed "keypad 3." | |
1026 | This name came from the key_names file. | |
1027 | ||
1028 | * states: | |
1029 | This file contains names for key states. | |
1030 | Again, these are part of the help system. For instance, if you had pressed | |
1031 | speakup + keypad 3, you would hear: | |
1032 | "speakup keypad 3 is go to bottom edge." | |
1033 | The speakup key is depressed, so the name of the key state is speakup. | |
1034 | This part of the message comes from the states collection. | |
1035 | ||
cae2181b ST |
1036 | 14.2. Changing language |
1037 | ||
1038 | 14.2.1. Loading Your Own Messages | |
c6e3fd22 WH |
1039 | |
1040 | The files under the i18n subdirectory all follow the same format. | |
1041 | They consist of lines, with one message per line. | |
1042 | Each message is represented by a number, followed by the text of the message. | |
1043 | The number is the position of the message in the given collection. | |
1044 | For example, if you view the file /speakup/i18n/colors, you will see the | |
1045 | following list: | |
1046 | ||
1047 | 0 black | |
1048 | 1 blue | |
1049 | 2 green | |
1050 | 3 cyan | |
1051 | 4 red | |
1052 | 5 magenta | |
1053 | 6 yellow | |
1054 | 7 white | |
1055 | 8 grey | |
1056 | ||
1057 | You can change one message, or you can change a whole group. | |
1058 | To load a whole collection of messages from a new source, simply use | |
1059 | the cp command: | |
1060 | cp ~/my_colors /speakup/i18n/colors | |
1061 | You can change an individual message with the echo command, | |
1062 | as shown in the following example. | |
1063 | ||
1064 | The Spanish name for the color blue is azul. | |
1065 | Looking at the colors file, we see that the name "blue" is at position 1 | |
1066 | within the colors group. Let's change blue to azul: | |
1067 | echo '1 azul' > /speakup/i18n/colors | |
1068 | The next time that Speakup says message 1 from the colors group, it will | |
1069 | say "azul", rather than "blue." | |
1070 | ||
cae2181b ST |
1071 | 14.2.2. Choose a language |
1072 | ||
c6e3fd22 | 1073 | In the future, translations into various languages will be made available, |
cae2181b ST |
1074 | and most users will just load the files necessary for their language. So far, |
1075 | only French language is available beyond native Canadian English language. | |
1076 | ||
1077 | French is only available after you are logged in. | |
1078 | ||
1079 | Canadian English is the default language. To toggle another language, | |
1080 | download the source of Speakup and untar it in your home directory. The | |
1081 | following command should let you do this: | |
1082 | ||
1083 | tar xvjf speakup-<version>.tar.bz2 | |
1084 | ||
1085 | where <version> is the version number of the application. | |
1086 | ||
1087 | Next, change to the newly created directory, then into the tools/ directory, and | |
1088 | run the script speakup_setlocale. You are asked the language that you want to | |
1089 | use. Type the number associated to your language (e.g. fr for French) then press | |
1090 | Enter. Needed files are copied in the i18n directory. | |
1091 | ||
1092 | Note: the speakupconf must be installed on your system so that settings are saved. | |
1093 | Otherwise, you will have an error: your language will be loaded but you will | |
1094 | have to run the script again every time Speakup restarts. | |
1095 | See section 16.1. for information about speakupconf. | |
1096 | ||
1097 | You will have to repeat these steps for any change of locale, i.e. if you wish | |
1098 | change the speakup's language or charset (iso-8859-15 ou UTF-8). | |
1099 | ||
1100 | If you wish store the settings, note that at your next login, you will need to | |
1101 | do: | |
1102 | ||
1103 | speakup load | |
1104 | ||
1105 | Alternatively, you can add the above line to your file | |
1106 | ~/.bashrc or ~/.bash_profile. | |
1107 | ||
1108 | If your system administrator ran himself the script, all the users will be able | |
1109 | to change from English to the language choosed by root and do directly | |
1110 | speakupconf load (or add this to the ~/.bashrc or | |
1111 | ~/.bash_profile file). If there are several languages to handle, the | |
1112 | administrator (or every user) will have to run the first steps until speakupconf | |
1113 | save, choosing the appropriate language, in every user's home directory. Every | |
1114 | user will then be able to do speakupconf load, Speakup will load his own settings. | |
c6e3fd22 WH |
1115 | |
1116 | 14.3. No Support for Non-Western-European Languages | |
1117 | ||
1118 | As of the current release, Speakup only supports Western European languages. | |
1119 | Support for the extended characters used by languages outside of the Western | |
1120 | European family of languages is a work in progress. | |
1121 | ||
1122 | 15. Using Speakup's Windowing Capability | |
1123 | ||
1124 | Speakup has the capability of defining and manipulating windows on the | |
1125 | screen. Speakup uses the term "Window", to mean a user defined area of | |
1126 | the screen. The key strokes for defining and manipulating Speakup | |
1127 | windows are as follows: | |
1128 | ||
1129 | speakup + f2 -- Set the bounds of the window. | |
1130 | Speakup + f3 -- clear the current window definition. | |
1131 | speakup + f4 -- Toggle window silence on and off. | |
1132 | speakup + keypad plus -- Say the currently defined window. | |
1133 | ||
1134 | These capabilities are useful for tracking a certain part of the screen | |
1135 | without rereading the whole screen, or for silencing a part of the | |
1136 | screen that is constantly changing, such as a clock or status line. | |
1137 | ||
1138 | There is no way to save these window settings, and you can only have one | |
1139 | window defined for each virtual console. There is also no way to have | |
25985edc | 1140 | windows automatically defined for specific applications. |
c6e3fd22 WH |
1141 | |
1142 | In order to define a window, use the review keys to move your reading | |
1143 | cursor to the beginning of the area you want to define. Then press | |
1144 | speakup + f2. Speakup will tell you that the window starts at the | |
1145 | indicated row and column position. Then move the reading cursor to the | |
1146 | end of the area to be defined as a window, and press speakup + f2 again. | |
1147 | If there is more than one line in the window, Speakup will tell you | |
1148 | that the window ends at the indicated row and column position. If there | |
1149 | is only one line in the window, then Speakup will tell you that the | |
1150 | window is the specified line on the screen. If you are only defining a | |
1151 | one line window, you can just press speakup + f2 twice after placing the | |
1152 | reading cursor on the line you want to define as a window. It is not | |
1153 | necessary to position the reading cursor at the end of the line in order | |
1154 | to define the whole line as a window. | |
1155 | ||
1156 | 16. Tools for Controlling Speakup | |
1157 | ||
1158 | The speakup distribution includes extra tools (in the tools directory) | |
1159 | which were written to make speakup easier to use. This section will | |
1160 | briefly describe the use of these tools. | |
1161 | ||
1162 | 16.1. Speakupconf | |
1163 | ||
1164 | speakupconf began life as a contribution from Steve Holmes, a member of | |
1165 | the speakup community. We would like to thank him for his work on the | |
1166 | early versions of this project. | |
1167 | ||
1168 | This script may be installed as part of your linux distribution, but if | |
1169 | it isn't, the recommended places to put it are /usr/local/bin or | |
1170 | /usr/bin. This script can be run by any user, so it does not require | |
1171 | root privileges. | |
1172 | ||
1173 | Speakupconf allows you to save and load your Speakup settings. It works | |
1174 | by reading and writing the /sys files described above. | |
1175 | ||
1176 | The directory that speakupconf uses to store your settings depends on | |
1177 | whether it is run from the root account. If you execute speakupconf as | |
1178 | root, it uses the directory /etc/speakup. Otherwise, it uses the directory | |
1179 | ~/.speakup, where ~ is your home directory. | |
1180 | Anyone who needs to use Speakup from your console can load his own custom | |
1181 | settings with this script. | |
1182 | ||
1183 | speakupconf takes one required argument: load or save. | |
1184 | Use the command | |
1185 | speakupconf save | |
1186 | to save your Speakup settings, and | |
1187 | speakupconf load | |
1188 | to load them into Speakup. | |
1189 | A second argument may be specified to use an alternate directory to | |
1190 | load or save the speakup parameters. | |
1191 | ||
1192 | 16.2. Talkwith | |
1193 | ||
1194 | Charles Hallenbeck, another member of the speakup community, wrote the | |
1195 | initial versions of this script, and we would also like to thank him for | |
1196 | his work on it. | |
1197 | ||
1198 | This script needs root privileges to run, so if it is not installed as | |
1199 | part of your linux distribution, the recommended places to install it | |
1200 | are /usr/local/sbin or /usr/sbin. | |
1201 | ||
1202 | Talkwith allows you to switch synthesizers on the fly. It takes a synthesizer | |
1203 | name as an argument. For instance, | |
1204 | talkwith dectlk | |
1205 | causes Speakup to use the DecTalk Express. If you wish to switch to a | |
1206 | software synthesizer, you must also indicate which daemon you wish to | |
1207 | use. There are two possible choices: | |
1208 | spd and espeakup. spd is an abbreviation for speechd-up. | |
1209 | If you wish to use espeakup for software synthesis, give the command | |
1210 | talkwith soft espeakup | |
1211 | To use speechd-up, type: | |
1212 | talkwith soft spd | |
1213 | Any arguments that follow the name of the daemon are passed to the daemon | |
1214 | when it is invoked. For instance: | |
1215 | talkwith espeakup --default-voice=fr | |
1216 | causes espeakup to use the French voice. | |
1217 | Note that talkwith must always be executed with root privileges. | |
1218 | ||
1219 | Talkwith does not attempt to load your settings after the new | |
1220 | synthesizer is activated. You can use speakupconf to load your settings | |
1221 | if desired. | |
1222 | ||
1223 | GNU Free Documentation License | |
1224 | Version 1.2, November 2002 | |
1225 | ||
1226 | ||
1227 | Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. | |
c6e3fd22 WH |
1228 | Everyone is permitted to copy and distribute verbatim copies |
1229 | of this license document, but changing it is not allowed. | |
1230 | ||
1231 | ||
1232 | 0. PREAMBLE | |
1233 | ||
1234 | The purpose of this License is to make a manual, textbook, or other | |
1235 | functional and useful document "free" in the sense of freedom: to | |
1236 | assure everyone the effective freedom to copy and redistribute it, | |
1237 | with or without modifying it, either commercially or noncommercially. | |
1238 | Secondarily, this License preserves for the author and publisher a way | |
1239 | to get credit for their work, while not being considered responsible | |
1240 | for modifications made by others. | |
1241 | ||
1242 | This License is a kind of "copyleft", which means that derivative | |
1243 | works of the document must themselves be free in the same sense. It | |
1244 | complements the GNU General Public License, which is a copyleft | |
1245 | license designed for free software. | |
1246 | ||
1247 | We have designed this License in order to use it for manuals for free | |
1248 | software, because free software needs free documentation: a free | |
1249 | program should come with manuals providing the same freedoms that the | |
1250 | software does. But this License is not limited to software manuals; | |
1251 | it can be used for any textual work, regardless of subject matter or | |
1252 | whether it is published as a printed book. We recommend this License | |
1253 | principally for works whose purpose is instruction or reference. | |
1254 | ||
1255 | ||
1256 | 1. APPLICABILITY AND DEFINITIONS | |
1257 | ||
1258 | This License applies to any manual or other work, in any medium, that | |
1259 | contains a notice placed by the copyright holder saying it can be | |
1260 | distributed under the terms of this License. Such a notice grants a | |
1261 | world-wide, royalty-free license, unlimited in duration, to use that | |
1262 | work under the conditions stated herein. The "Document", below, | |
1263 | refers to any such manual or work. Any member of the public is a | |
1264 | licensee, and is addressed as "you". You accept the license if you | |
1265 | copy, modify or distribute the work in a way requiring permission | |
1266 | under copyright law. | |
1267 | ||
1268 | A "Modified Version" of the Document means any work containing the | |
1269 | Document or a portion of it, either copied verbatim, or with | |
1270 | modifications and/or translated into another language. | |
1271 | ||
1272 | A "Secondary Section" is a named appendix or a front-matter section of | |
1273 | the Document that deals exclusively with the relationship of the | |
1274 | publishers or authors of the Document to the Document's overall subject | |
1275 | (or to related matters) and contains nothing that could fall directly | |
1276 | within that overall subject. (Thus, if the Document is in part a | |
1277 | textbook of mathematics, a Secondary Section may not explain any | |
1278 | mathematics.) The relationship could be a matter of historical | |
1279 | connection with the subject or with related matters, or of legal, | |
1280 | commercial, philosophical, ethical or political position regarding | |
1281 | them. | |
1282 | ||
1283 | The "Invariant Sections" are certain Secondary Sections whose titles | |
1284 | are designated, as being those of Invariant Sections, in the notice | |
1285 | that says that the Document is released under this License. If a | |
1286 | section does not fit the above definition of Secondary then it is not | |
1287 | allowed to be designated as Invariant. The Document may contain zero | |
1288 | Invariant Sections. If the Document does not identify any Invariant | |
1289 | Sections then there are none. | |
1290 | ||
1291 | The "Cover Texts" are certain short passages of text that are listed, | |
1292 | as Front-Cover Texts or Back-Cover Texts, in the notice that says that | |
1293 | the Document is released under this License. A Front-Cover Text may | |
1294 | be at most 5 words, and a Back-Cover Text may be at most 25 words. | |
1295 | ||
1296 | A "Transparent" copy of the Document means a machine-readable copy, | |
1297 | represented in a format whose specification is available to the | |
1298 | general public, that is suitable for revising the document | |
1299 | straightforwardly with generic text editors or (for images composed of | |
1300 | pixels) generic paint programs or (for drawings) some widely available | |
1301 | drawing editor, and that is suitable for input to text formatters or | |
1302 | for automatic translation to a variety of formats suitable for input | |
1303 | to text formatters. A copy made in an otherwise Transparent file | |
1304 | format whose markup, or absence of markup, has been arranged to thwart | |
1305 | or discourage subsequent modification by readers is not Transparent. | |
1306 | An image format is not Transparent if used for any substantial amount | |
1307 | of text. A copy that is not "Transparent" is called "Opaque". | |
1308 | ||
1309 | Examples of suitable formats for Transparent copies include plain | |
1310 | ASCII without markup, Texinfo input format, LaTeX input format, SGML | |
1311 | or XML using a publicly available DTD, and standard-conforming simple | |
1312 | HTML, PostScript or PDF designed for human modification. Examples of | |
1313 | transparent image formats include PNG, XCF and JPG. Opaque formats | |
1314 | include proprietary formats that can be read and edited only by | |
1315 | proprietary word processors, SGML or XML for which the DTD and/or | |
1316 | processing tools are not generally available, and the | |
1317 | machine-generated HTML, PostScript or PDF produced by some word | |
1318 | processors for output purposes only. | |
1319 | ||
1320 | The "Title Page" means, for a printed book, the title page itself, | |
1321 | plus such following pages as are needed to hold, legibly, the material | |
1322 | this License requires to appear in the title page. For works in | |
1323 | formats which do not have any title page as such, "Title Page" means | |
1324 | the text near the most prominent appearance of the work's title, | |
1325 | preceding the beginning of the body of the text. | |
1326 | ||
1327 | A section "Entitled XYZ" means a named subunit of the Document whose | |
1328 | title either is precisely XYZ or contains XYZ in parentheses following | |
1329 | text that translates XYZ in another language. (Here XYZ stands for a | |
1330 | specific section name mentioned below, such as "Acknowledgements", | |
1331 | "Dedications", "Endorsements", or "History".) To "Preserve the Title" | |
1332 | of such a section when you modify the Document means that it remains a | |
1333 | section "Entitled XYZ" according to this definition. | |
1334 | ||
1335 | The Document may include Warranty Disclaimers next to the notice which | |
1336 | states that this License applies to the Document. These Warranty | |
1337 | Disclaimers are considered to be included by reference in this | |
1338 | License, but only as regards disclaiming warranties: any other | |
1339 | implication that these Warranty Disclaimers may have is void and has | |
1340 | no effect on the meaning of this License. | |
1341 | ||
1342 | ||
1343 | 2. VERBATIM COPYING | |
1344 | ||
1345 | You may copy and distribute the Document in any medium, either | |
1346 | commercially or noncommercially, provided that this License, the | |
1347 | copyright notices, and the license notice saying this License applies | |
1348 | to the Document are reproduced in all copies, and that you add no other | |
1349 | conditions whatsoever to those of this License. You may not use | |
1350 | technical measures to obstruct or control the reading or further | |
1351 | copying of the copies you make or distribute. However, you may accept | |
1352 | compensation in exchange for copies. If you distribute a large enough | |
1353 | number of copies you must also follow the conditions in section 3. | |
1354 | ||
1355 | You may also lend copies, under the same conditions stated above, and | |
1356 | you may publicly display copies. | |
1357 | ||
1358 | ||
1359 | 3. COPYING IN QUANTITY | |
1360 | ||
1361 | If you publish printed copies (or copies in media that commonly have | |
1362 | printed covers) of the Document, numbering more than 100, and the | |
1363 | Document's license notice requires Cover Texts, you must enclose the | |
1364 | copies in covers that carry, clearly and legibly, all these Cover | |
1365 | Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on | |
1366 | the back cover. Both covers must also clearly and legibly identify | |
1367 | you as the publisher of these copies. The front cover must present | |
1368 | the full title with all words of the title equally prominent and | |
1369 | visible. You may add other material on the covers in addition. | |
1370 | Copying with changes limited to the covers, as long as they preserve | |
1371 | the title of the Document and satisfy these conditions, can be treated | |
1372 | as verbatim copying in other respects. | |
1373 | ||
1374 | If the required texts for either cover are too voluminous to fit | |
1375 | legibly, you should put the first ones listed (as many as fit | |
1376 | reasonably) on the actual cover, and continue the rest onto adjacent | |
1377 | pages. | |
1378 | ||
1379 | If you publish or distribute Opaque copies of the Document numbering | |
1380 | more than 100, you must either include a machine-readable Transparent | |
1381 | copy along with each Opaque copy, or state in or with each Opaque copy | |
1382 | a computer-network location from which the general network-using | |
1383 | public has access to download using public-standard network protocols | |
1384 | a complete Transparent copy of the Document, free of added material. | |
1385 | If you use the latter option, you must take reasonably prudent steps, | |
1386 | when you begin distribution of Opaque copies in quantity, to ensure | |
1387 | that this Transparent copy will remain thus accessible at the stated | |
1388 | location until at least one year after the last time you distribute an | |
1389 | Opaque copy (directly or through your agents or retailers) of that | |
1390 | edition to the public. | |
1391 | ||
1392 | It is requested, but not required, that you contact the authors of the | |
1393 | Document well before redistributing any large number of copies, to give | |
1394 | them a chance to provide you with an updated version of the Document. | |
1395 | ||
1396 | ||
1397 | 4. MODIFICATIONS | |
1398 | ||
1399 | You may copy and distribute a Modified Version of the Document under | |
1400 | the conditions of sections 2 and 3 above, provided that you release | |
1401 | the Modified Version under precisely this License, with the Modified | |
1402 | Version filling the role of the Document, thus licensing distribution | |
1403 | and modification of the Modified Version to whoever possesses a copy | |
1404 | of it. In addition, you must do these things in the Modified Version: | |
1405 | ||
1406 | A. Use in the Title Page (and on the covers, if any) a title distinct | |
1407 | from that of the Document, and from those of previous versions | |
1408 | (which should, if there were any, be listed in the History section | |
1409 | of the Document). You may use the same title as a previous version | |
1410 | if the original publisher of that version gives permission. | |
1411 | B. List on the Title Page, as authors, one or more persons or entities | |
1412 | responsible for authorship of the modifications in the Modified | |
1413 | Version, together with at least five of the principal authors of the | |
1414 | Document (all of its principal authors, if it has fewer than five), | |
1415 | unless they release you from this requirement. | |
1416 | C. State on the Title page the name of the publisher of the | |
1417 | Modified Version, as the publisher. | |
1418 | D. Preserve all the copyright notices of the Document. | |
1419 | E. Add an appropriate copyright notice for your modifications | |
1420 | adjacent to the other copyright notices. | |
1421 | F. Include, immediately after the copyright notices, a license notice | |
1422 | giving the public permission to use the Modified Version under the | |
1423 | terms of this License, in the form shown in the Addendum below. | |
1424 | G. Preserve in that license notice the full lists of Invariant Sections | |
1425 | and required Cover Texts given in the Document's license notice. | |
1426 | H. Include an unaltered copy of this License. | |
1427 | I. Preserve the section Entitled "History", Preserve its Title, and add | |
1428 | to it an item stating at least the title, year, new authors, and | |
1429 | publisher of the Modified Version as given on the Title Page. If | |
1430 | there is no section Entitled "History" in the Document, create one | |
1431 | stating the title, year, authors, and publisher of the Document as | |
1432 | given on its Title Page, then add an item describing the Modified | |
1433 | Version as stated in the previous sentence. | |
1434 | J. Preserve the network location, if any, given in the Document for | |
1435 | public access to a Transparent copy of the Document, and likewise | |
1436 | the network locations given in the Document for previous versions | |
1437 | it was based on. These may be placed in the "History" section. | |
1438 | You may omit a network location for a work that was published at | |
1439 | least four years before the Document itself, or if the original | |
1440 | publisher of the version it refers to gives permission. | |
1441 | K. For any section Entitled "Acknowledgements" or "Dedications", | |
1442 | Preserve the Title of the section, and preserve in the section all | |
1443 | the substance and tone of each of the contributor acknowledgements | |
1444 | and/or dedications given therein. | |
1445 | L. Preserve all the Invariant Sections of the Document, | |
1446 | unaltered in their text and in their titles. Section numbers | |
1447 | or the equivalent are not considered part of the section titles. | |
1448 | M. Delete any section Entitled "Endorsements". Such a section | |
1449 | may not be included in the Modified Version. | |
1450 | N. Do not retitle any existing section to be Entitled "Endorsements" | |
1451 | or to conflict in title with any Invariant Section. | |
1452 | O. Preserve any Warranty Disclaimers. | |
1453 | ||
1454 | If the Modified Version includes new front-matter sections or | |
1455 | appendices that qualify as Secondary Sections and contain no material | |
1456 | copied from the Document, you may at your option designate some or all | |
1457 | of these sections as invariant. To do this, add their titles to the | |
1458 | list of Invariant Sections in the Modified Version's license notice. | |
1459 | These titles must be distinct from any other section titles. | |
1460 | ||
1461 | You may add a section Entitled "Endorsements", provided it contains | |
1462 | nothing but endorsements of your Modified Version by various | |
1463 | parties--for example, statements of peer review or that the text has | |
1464 | been approved by an organization as the authoritative definition of a | |
1465 | standard. | |
1466 | ||
1467 | You may add a passage of up to five words as a Front-Cover Text, and a | |
1468 | passage of up to 25 words as a Back-Cover Text, to the end of the list | |
1469 | of Cover Texts in the Modified Version. Only one passage of | |
1470 | Front-Cover Text and one of Back-Cover Text may be added by (or | |
1471 | through arrangements made by) any one entity. If the Document already | |
1472 | includes a cover text for the same cover, previously added by you or | |
1473 | by arrangement made by the same entity you are acting on behalf of, | |
1474 | you may not add another; but you may replace the old one, on explicit | |
1475 | permission from the previous publisher that added the old one. | |
1476 | ||
1477 | The author(s) and publisher(s) of the Document do not by this License | |
1478 | give permission to use their names for publicity for or to assert or | |
1479 | imply endorsement of any Modified Version. | |
1480 | ||
1481 | ||
1482 | 5. COMBINING DOCUMENTS | |
1483 | ||
1484 | You may combine the Document with other documents released under this | |
1485 | License, under the terms defined in section 4 above for modified | |
1486 | versions, provided that you include in the combination all of the | |
1487 | Invariant Sections of all of the original documents, unmodified, and | |
1488 | list them all as Invariant Sections of your combined work in its | |
1489 | license notice, and that you preserve all their Warranty Disclaimers. | |
1490 | ||
1491 | The combined work need only contain one copy of this License, and | |
1492 | multiple identical Invariant Sections may be replaced with a single | |
1493 | copy. If there are multiple Invariant Sections with the same name but | |
1494 | different contents, make the title of each such section unique by | |
1495 | adding at the end of it, in parentheses, the name of the original | |
1496 | author or publisher of that section if known, or else a unique number. | |
1497 | Make the same adjustment to the section titles in the list of | |
1498 | Invariant Sections in the license notice of the combined work. | |
1499 | ||
1500 | In the combination, you must combine any sections Entitled "History" | |
1501 | in the various original documents, forming one section Entitled | |
1502 | "History"; likewise combine any sections Entitled "Acknowledgements", | |
1503 | and any sections Entitled "Dedications". You must delete all sections | |
1504 | Entitled "Endorsements". | |
1505 | ||
1506 | ||
1507 | 6. COLLECTIONS OF DOCUMENTS | |
1508 | ||
1509 | You may make a collection consisting of the Document and other documents | |
1510 | released under this License, and replace the individual copies of this | |
1511 | License in the various documents with a single copy that is included in | |
1512 | the collection, provided that you follow the rules of this License for | |
1513 | verbatim copying of each of the documents in all other respects. | |
1514 | ||
1515 | You may extract a single document from such a collection, and distribute | |
1516 | it individually under this License, provided you insert a copy of this | |
1517 | License into the extracted document, and follow this License in all | |
1518 | other respects regarding verbatim copying of that document. | |
1519 | ||
1520 | ||
1521 | 7. AGGREGATION WITH INDEPENDENT WORKS | |
1522 | ||
1523 | A compilation of the Document or its derivatives with other separate | |
1524 | and independent documents or works, in or on a volume of a storage or | |
1525 | distribution medium, is called an "aggregate" if the copyright | |
1526 | resulting from the compilation is not used to limit the legal rights | |
1527 | of the compilation's users beyond what the individual works permit. | |
1528 | When the Document is included in an aggregate, this License does not | |
1529 | apply to the other works in the aggregate which are not themselves | |
1530 | derivative works of the Document. | |
1531 | ||
1532 | If the Cover Text requirement of section 3 is applicable to these | |
1533 | copies of the Document, then if the Document is less than one half of | |
1534 | the entire aggregate, the Document's Cover Texts may be placed on | |
1535 | covers that bracket the Document within the aggregate, or the | |
1536 | electronic equivalent of covers if the Document is in electronic form. | |
1537 | Otherwise they must appear on printed covers that bracket the whole | |
1538 | aggregate. | |
1539 | ||
1540 | ||
1541 | 8. TRANSLATION | |
1542 | ||
1543 | Translation is considered a kind of modification, so you may | |
1544 | distribute translations of the Document under the terms of section 4. | |
1545 | Replacing Invariant Sections with translations requires special | |
1546 | permission from their copyright holders, but you may include | |
1547 | translations of some or all Invariant Sections in addition to the | |
1548 | original versions of these Invariant Sections. You may include a | |
1549 | translation of this License, and all the license notices in the | |
1550 | Document, and any Warranty Disclaimers, provided that you also include | |
1551 | the original English version of this License and the original versions | |
1552 | of those notices and disclaimers. In case of a disagreement between | |
1553 | the translation and the original version of this License or a notice | |
1554 | or disclaimer, the original version will prevail. | |
1555 | ||
1556 | If a section in the Document is Entitled "Acknowledgements", | |
1557 | "Dedications", or "History", the requirement (section 4) to Preserve | |
1558 | its Title (section 1) will typically require changing the actual | |
1559 | title. | |
1560 | ||
1561 | ||
1562 | 9. TERMINATION | |
1563 | ||
1564 | You may not copy, modify, sublicense, or distribute the Document except | |
1565 | as expressly provided for under this License. Any other attempt to | |
1566 | copy, modify, sublicense or distribute the Document is void, and will | |
1567 | automatically terminate your rights under this License. However, | |
1568 | parties who have received copies, or rights, from you under this | |
1569 | License will not have their licenses terminated so long as such | |
1570 | parties remain in full compliance. | |
1571 | ||
1572 | ||
1573 | 10. FUTURE REVISIONS OF THIS LICENSE | |
1574 | ||
1575 | The Free Software Foundation may publish new, revised versions | |
1576 | of the GNU Free Documentation License from time to time. Such new | |
1577 | versions will be similar in spirit to the present version, but may | |
1578 | differ in detail to address new problems or concerns. See | |
5723a0dd | 1579 | https://www.gnu.org/copyleft/. |
c6e3fd22 WH |
1580 | |
1581 | Each version of the License is given a distinguishing version number. | |
1582 | If the Document specifies that a particular numbered version of this | |
1583 | License "or any later version" applies to it, you have the option of | |
1584 | following the terms and conditions either of that specified version or | |
1585 | of any later version that has been published (not as a draft) by the | |
1586 | Free Software Foundation. If the Document does not specify a version | |
1587 | number of this License, you may choose any version ever published (not | |
1588 | as a draft) by the Free Software Foundation. | |
1589 | ||
1590 | ||
1591 | ADDENDUM: How to use this License for your documents | |
1592 | ||
1593 | To use this License in a document you have written, include a copy of | |
1594 | the License in the document and put the following copyright and | |
1595 | license notices just after the title page: | |
1596 | ||
1597 | Copyright (c) YEAR YOUR NAME. | |
1598 | Permission is granted to copy, distribute and/or modify this document | |
1599 | under the terms of the GNU Free Documentation License, Version 1.2 | |
1600 | or any later version published by the Free Software Foundation; | |
1601 | with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. | |
1602 | A copy of the license is included in the section entitled "GNU | |
1603 | Free Documentation License". | |
1604 | ||
1605 | If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, | |
1606 | replace the "with...Texts." line with this: | |
1607 | ||
1608 | with the Invariant Sections being LIST THEIR TITLES, with the | |
1609 | Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. | |
1610 | ||
1611 | If you have Invariant Sections without Cover Texts, or some other | |
1612 | combination of the three, merge those two alternatives to suit the | |
1613 | situation. | |
1614 | ||
1615 | If your document contains nontrivial examples of program code, we | |
1616 | recommend releasing these examples in parallel under your choice of | |
1617 | free software license, such as the GNU General Public License, | |
1618 | to permit their use in free software. | |
1619 | ||
1620 | The End. |