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