Modify some parts of the text and add the necessary formatting to leverage
the rst features. Including links, code-blocks, bullet lists, etc.
Also, adds a table of contents at the beginning and a section to the
license.
This change helps integrate this documentation to the rest of the rst
documentation.
Signed-off-by: Igor Matheus Andrade Torrente <[email protected]>
---
V2: Rebase the patch to cover the commit cae2181b498fe
---
Documentation/admin-guide/index.rst | 1 +
.../{spkguide.txt => spkguide.rst} | 1026 +++++++++--------
2 files changed, 574 insertions(+), 453 deletions(-)
rename Documentation/admin-guide/{spkguide.txt => spkguide.rst} (75%)
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 423116c4e787..c45121777ecf 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -112,6 +112,7 @@ configure specific aspects of kernel behavior to your liking.
ras
rtc
serial-console
+ spkguide
svga
syscall-user-dispatch
sysrq
diff --git a/Documentation/admin-guide/spkguide.txt b/Documentation/admin-guide/spkguide.rst
similarity index 75%
rename from Documentation/admin-guide/spkguide.txt
rename to Documentation/admin-guide/spkguide.rst
index 977ab3f5a0a8..e254af41a8e9 100644
--- a/Documentation/admin-guide/spkguide.txt
+++ b/Documentation/admin-guide/spkguide.rst
@@ -1,14 +1,20 @@
-
+========================
The Speakup User's Guide
-For Speakup 3.1.2 and Later
-By Gene Collins
-Updated by others
-Last modified on Mon Sep 27 14:26:31 2010
-Document version 1.3
+========================
+
+| For Speakup 3.1.2 and Later
+| By Gene Collins
+| Updated by others
+| Last modified on Mon Jan 21 17:08:21 2021
+| Document version 1.3
+
-Copyright (c) 2005 Gene Collins
-Copyright (c) 2008 Samuel Thibault
-Copyright (c) 2009, 2010 the Speakup Team
+Copyright and License
+=====================
+
+| Copyright (c) 2005 Gene Collins
+| Copyright (c) 2008 Samuel Thibault
+| Copyright (c) 2009, 2010 the Speakup Team
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
@@ -17,7 +23,40 @@ Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
copy of the license is included in the section entitled "GNU Free
Documentation License".
+
+Contents
+========
+
+* `Preface`_.
+
+* `1. Starting Speakup`_
+* `2. Basic operation`_
+* `3. Using the Speakup Help System`_
+* `4. Keys and Their Assigned Commands`_
+* `5. The Speakup Sys System`_
+* `6. Changing Synthesizers`_
+* `7. Loading modules`_
+* `8. Using Software Synthesizers`_
+ - `8.1. Espeakup`_
+ - `8.2. Speech Dispatcher`_
+* `9. Using The DecTalk PC Card`_
+* `10. Using Cursor Tracking`_
+* `11. Cut and Paste`_
+* `12. Changing the Pronunciation of Characters`_
+* `13. Mapping Keys`_
+* `14. Internationalizing Speakup`_
+ - `14.1. Files Under the i18n Subdirectory`_.
+ - `14.2.1. Loading Your Own Messages`_.
+ - `14.2.2. Choose a language`_.
+ - `14.3. No Support for Non-Western-European Languages`_.
+* `15. Using Speakup's Windowing Capability`_
+* `16. Tools for Controlling Speakup`_
+ - `16.1. Speakupconf`_.
+ - `16.2. Talkwith`_
+
+
Preface
+=======
The purpose of this document is to familiarize users with the user
interface to Speakup, a Linux Screen Reader. If you need instructions
@@ -37,7 +76,9 @@ with speech access unaided by a sighted person. Again, these details
are beyond the scope of this manual, but the user should be aware of
them. See the web site mentioned above for further details.
+
1. Starting Speakup
+====================
If your system administrator has installed Speakup to work with your
specific synthesizer by default, then all you need to do to use Speakup
@@ -58,41 +99,43 @@ build and install your own kernel.
If your kernel has been compiled with Speakup, and has no default
synthesizer set, or you would like to use a different synthesizer than
the default one, then you may issue the following command at the boot
-prompt of your boot loader.
+prompt of your boot loader.::
-linux speakup.synth=ltlk
+ linux speakup.synth=ltlk
This command would tell Speakup to look for and use a LiteTalk or
DoubleTalk LT at boot up. You may replace the ltlk synthesizer keyword
with the keyword for whatever synthesizer you wish to use. The
-speakup.synth parameter will accept the following keywords, provided
+``speakup.synth`` parameter will accept the following keywords, provided
that support for the related synthesizers has been built into the
kernel.
-acntsa -- Accent SA
-acntpc -- Accent PC
-apollo -- Apollo
-audptr -- Audapter
-bns -- Braille 'n Speak
-dectlk -- DecTalk Express (old and new, db9 serial only)
-decext -- DecTalk (old) External
-dtlk -- DoubleTalk PC
-keypc -- Keynote Gold PC
-ltlk -- DoubleTalk LT, LiteTalk, or external Tripletalk (db9 serial only)
-spkout -- Speak Out
-txprt -- Transport
-dummy -- Plain text terminal
-
-Note: Speakup does * NOT * support usb connections! Speakup also does *
-NOT * support the internal Tripletalk!
+| acntsa -- Accent SA
+| acntpc -- Accent PC
+| apollo -- Apollo
+| audptr -- Audapter
+| bns -- Braille 'n Speak
+| dectlk -- DecTalk Express (old and new, db9 serial only)
+| decext -- DecTalk (old) External
+| dtlk -- DoubleTalk PC
+| keypc -- Keynote Gold PC
+| ltlk -- DoubleTalk LT, LiteTalk, or external Tripletalk (db9 serial only)
+| spkout -- Speak Out
+| txprt -- Transport
+| dummy -- Plain text terminal
+
+.. note::
+
+ | Speakup does **NOT** support usb connections!
+ | Speakup also does **NOT** support the internal Tripletalk!
Speakup does support two other synthesizers, but because they work in
conjunction with other software, they must be loaded as modules after
their related software is loaded, and so are not available at boot up.
These are as follows:
-decpc -- DecTalk PC (not available at boot up)
-soft -- One of several software synthesizers (not available at boot up)
+| decpc -- DecTalk PC (not available at boot up)
+| soft -- One of several software synthesizers (not available at boot up)
See the sections on loading modules and software synthesizers later in
this manual for further details. It should be noted here that the
@@ -102,7 +145,9 @@ the boot process, such action must be configured by your system
administrator. This will mean that you will hear some, but not all, of
the bootup messages.
+
2. Basic operation
+===================
Once you have booted the system, and if necessary, have supplied the
proper bootup parameter for your synthesizer, Speakup will begin
@@ -115,10 +160,12 @@ screen using the kernel, and must get their keyboard input through the
kernel, they are automatically handled properly by Speakup. There are a
few exceptions, but we'll come to those later.
-Note: In this guide I will refer to the numeric keypad as the keypad.
-This is done because the speakupmap.map file referred to later in this
-manual uses the term keypad instead of numeric keypad. Also I'm lazy
-and would rather only type one word. So keypad it is. Got it? Good.
+.. note::
+
+ In this guide I will refer to the numeric keypad as the keypad.
+ This is done because the speakupmap.map file referred to later in this
+ manual uses the term keypad instead of numeric keypad. Also I'm lazy
+ and would rather only type one word. So keypad it is. Got it? Good.
Most of the Speakup review keys are located on the keypad at the far
right of the keyboard. The numlock key should be off, in order for these
@@ -131,9 +178,9 @@ You probably won't want to listen to all the bootup messages every time
you start your system, though it's a good idea to listen to them at
least once, just so you'll know what kind of information is available to
you during the boot process. You can always review these messages after
-bootup with the command:
+bootup with the command::
-dmesg | more
+ dmesg | more
In order to speed the boot process, and to silence the speaking of the
bootup messages, just press the keypad enter key. This key is located
@@ -164,19 +211,19 @@ the speech with keypad enter, or use any of the Speakup review keys.
Here are some basic Speakup review keys, and a short description of what
they do.
-keypad 1 -- read previous character
-keypad 2 -- read current character (pressing keypad 2 twice rapidly will speak
- the current character phonetically)
-keypad 3 -- read next character
-keypad 4 -- read previous word
-keypad 5 -- read current word (press twice rapidly to spell the current word)
-keypad 6 -- read next word
-keypad 7 -- read previous line
-keypad 8 -- read current line (press twice rapidly to hear how much the
- text on the current line is indented)
-keypad 9 -- read next line
-keypad period -- speak current cursor position and announce current
- virtual console
+| keypad 1 -- read previous character
+| keypad 2 -- read current character (pressing keypad 2 twice rapidly will speak
+ the current character phonetically)
+| keypad 3 -- read next character
+| keypad 4 -- read previous word
+| keypad 5 -- read current word (press twice rapidly to spell the current word)
+| keypad 6 -- read next word
+| keypad 7 -- read previous line
+| keypad 8 -- read current line (press twice rapidly to hear how much the
+ text on the current line is indented)
+| keypad 9 -- read next line
+| keypad period -- speak current cursor position and announce current
+ virtual console
It's also worth noting that the insert key on the keypad is mapped
as the speakup key. Instead of pressing and releasing this key, as you
@@ -190,16 +237,18 @@ Speakup will say, "You turned me off.", or "Hey, that's better." When
Speakup is turned off, no new text on the screen will be spoken. You
can still use the reading controls to review the screen however.
+
3. Using the Speakup Help System
+=================================
In order to enter the Speakup help system, press and hold the speakup
-key (remember that this is the keypad insert key), and press the f1 key.
+key (remember that this is the keypad insert key), and press the `f1` key.
You will hear the message:
"Press space to leave help, cursor up or down to scroll, or a letter to
go to commands in list."
-When you press the spacebar to leave the help system, you will hear:
+When you press the `spacebar` to leave the help system, you will hear:
"Leaving help."
@@ -222,10 +271,10 @@ in this manual.
You'll also notice that some commands have two keys assigned to them.
This is because Speakup has a built in set of alternative key bindings
-for laptop users. The alternate speakup key is the caps lock key. You
-can press and hold the caps lock key, while pressing an alternate
+for laptop users. The alternate speakup key is the `caps lock` key. You
+can press and hold the `caps lock` key, while pressing an alternate
speakup command key to activate the command. On most laptops, the
-numeric keypad is defined as the keys in the j k l area of the keyboard.
+numeric keypad is defined as the keys in the `j k l` area of the keyboard.
There is usually a function key which turns this keypad function on and
off, and some other key which controls the numlock state. Toggling the
@@ -236,198 +285,205 @@ because Speakup does not know whether it is running on a desktop or
laptop. So you may choose which set of Speakup keys to use. Some
system administrators may have chosen to compile Speakup for a desktop
system without this set of alternate key bindings, but these details are
-beyond the scope of this manual. To use the caps lock for its normal
-purpose, hold the shift key while toggling the caps lock on and off. We
-should note here, that holding the caps lock key and pressing the z key
-will toggle the alternate j k l keypad on and off.
+beyond the scope of this manual. To use the `caps lock` for its normal
+purpose, hold the shift key while toggling the `caps lock` on and off.
+
+.. note::
+
+ Holding the `caps lock` key and pressing the `z` key will toggle the
+ alternate `j k l` keypad on and off.
+
4. Keys and Their Assigned Commands
+====================================
In this section, we'll go through a list of all the speakup keys and
commands. You can also get a list of commands and assigned keys from
the help system.
-The following list was taken from the speakupmap.map file. Key
+The following list was taken from the ``speakupmap.map`` file. Key
assignments are on the left of the equal sign, and the associated
Speakup commands are on the right. The designation "spk" means to press
-and hold the speakup key, a.k.a. keypad insert, a.k.a. caps lock, while
+and hold the speakup key, a.k.a. keypad insert, a.k.a. `caps lock`, while
pressing the other specified key.
-spk key_f9 = punc_level_dec
-spk key_f10 = punc_level_inc
-spk key_f11 = reading_punc_dec
-spk key_f12 = reading_punc_inc
-spk key_1 = vol_dec
-spk key_2 = vol_inc
-spk key_3 = pitch_dec
-spk key_4 = pitch_inc
-spk key_5 = rate_dec
-spk key_6 = rate_inc
-key_kpasterisk = toggle_cursoring
-spk key_kpasterisk = speakup_goto
-spk key_f1 = speakup_help
-spk key_f2 = set_win
-spk key_f3 = clear_win
-spk key_f4 = enable_win
-spk key_f5 = edit_some
-spk key_f6 = edit_most
-spk key_f7 = edit_delim
-spk key_f8 = edit_repeat
-shift spk key_f9 = edit_exnum
- key_kp7 = say_prev_line
-spk key_kp7 = left_edge
- key_kp8 = say_line
-double key_kp8 = say_line_indent
-spk key_kp8 = say_from_top
- key_kp9 = say_next_line
-spk key_kp9 = top_edge
- key_kpminus = speakup_parked
-spk key_kpminus = say_char_num
- key_kp4 = say_prev_word
-spk key_kp4 = say_from_left
- key_kp5 = say_word
-double key_kp5 = spell_word
-spk key_kp5 = spell_phonetic
- key_kp6 = say_next_word
-spk key_kp6 = say_to_right
- key_kpplus = say_screen
-spk key_kpplus = say_win
- key_kp1 = say_prev_char
-spk key_kp1 = right_edge
- key_kp2 = say_char
-spk key_kp2 = say_to_bottom
-double key_kp2 = say_phonetic_char
- key_kp3 = say_next_char
-spk key_kp3 = bottom_edge
- key_kp0 = spk_key
- key_kpdot = say_position
-spk key_kpdot = say_attributes
-key_kpenter = speakup_quiet
-spk key_kpenter = speakup_off
-key_sysrq = speech_kill
- key_kpslash = speakup_cut
-spk key_kpslash = speakup_paste
-spk key_pageup = say_first_char
-spk key_pagedown = say_last_char
-key_capslock = spk_key
- spk key_z = spk_lock
-key_leftmeta = spk_key
-ctrl spk key_0 = speakup_goto
-spk key_u = say_prev_line
-spk key_i = say_line
-double spk key_i = say_line_indent
-spk key_o = say_next_line
-spk key_minus = speakup_parked
-shift spk key_minus = say_char_num
-spk key_j = say_prev_word
-spk key_k = say_word
-double spk key_k = spell_word
-spk key_l = say_next_word
-spk key_m = say_prev_char
-spk key_comma = say_char
-double spk key_comma = say_phonetic_char
-spk key_dot = say_next_char
-spk key_n = say_position
- ctrl spk key_m = left_edge
- ctrl spk key_y = top_edge
- ctrl spk key_dot = right_edge
-ctrl spk key_p = bottom_edge
-spk key_apostrophe = say_screen
-spk key_h = say_from_left
-spk key_y = say_from_top
-spk key_semicolon = say_to_right
-spk key_p = say_to_bottom
-spk key_slash = say_attributes
- spk key_enter = speakup_quiet
- ctrl spk key_enter = speakup_off
- spk key_9 = speakup_cut
-spk key_8 = speakup_paste
-shift spk key_m = say_first_char
- ctrl spk key_semicolon = say_last_char
-spk key_r = read_all_doc
+| spk key_f9 = punc_level_dec
+| spk key_f10 = punc_level_inc
+| spk key_f11 = reading_punc_dec
+| spk key_f12 = reading_punc_inc
+| spk key_1 = vol_dec
+| spk key_2 = vol_inc
+| spk key_3 = pitch_dec
+| spk key_4 = pitch_inc
+| spk key_5 = rate_dec
+| spk key_6 = rate_inc
+| key_kpasterisk = toggle_cursoring
+| spk key_kpasterisk = speakup_goto
+| spk key_f1 = speakup_help
+| spk key_f2 = set_win
+| spk key_f3 = clear_win
+| spk key_f4 = enable_win
+| spk key_f5 = edit_some
+| spk key_f6 = edit_most
+| spk key_f7 = edit_delim
+| spk key_f8 = edit_repeat
+| shift spk key_f9 = edit_exnum
+| key_kp7 = say_prev_line
+| spk key_kp7 = left_edge
+| key_kp8 = say_line
+| double key_kp8 = say_line_indent
+| spk key_kp8 = say_from_top
+| key_kp9 = say_next_line
+| spk key_kp9 = top_edge
+| key_kpminus = speakup_parked
+| spk key_kpminus = say_char_num
+| key_kp4 = say_prev_word
+| spk key_kp4 = say_from_left
+| key_kp5 = say_word
+| double key_kp5 = spell_word
+| spk key_kp5 = spell_phonetic
+| key_kp6 = say_next_word
+| spk key_kp6 = say_to_right
+| key_kpplus = say_screen
+| spk key_kpplus = say_win
+| key_kp1 = say_prev_char
+| spk key_kp1 = right_edge
+| key_kp2 = say_char
+| spk key_kp2 = say_to_bottom
+| double key_kp2 = say_phonetic_char
+| key_kp3 = say_next_char
+| spk key_kp3 = bottom_edge
+| key_kp0 = spk_key
+| key_kpdot = say_position
+| spk key_kpdot = say_attributes
+| key_kpenter = speakup_quiet
+| spk key_kpenter = speakup_off
+| key_sysrq = speech_kill
+| key_kpslash = speakup_cut
+| spk key_kpslash = speakup_paste
+| spk key_pageup = say_first_char
+| spk key_pagedown = say_last_char
+| key_capslock = spk_key
+| spk key_z = spk_lock
+| key_leftmeta = spk_key
+| ctrl spk key_0 = speakup_goto
+| spk key_u = say_prev_line
+| spk key_i = say_line
+| double spk key_i = say_line_indent
+| spk key_o = say_next_line
+| spk key_minus = speakup_parked
+| shift spk key_minus = say_char_num
+| spk key_j = say_prev_word
+| spk key_k = say_word
+| double spk key_k = spell_word
+| spk key_l = say_next_word
+| spk key_m = say_prev_char
+| spk key_comma = say_char
+| double spk key_comma = say_phonetic_char
+| spk key_dot = say_next_char
+| spk key_n = say_position
+| ctrl spk key_m = left_edge
+| ctrl spk key_y = top_edge
+| ctrl spk key_dot = right_edge
+| ctrl spk key_p = bottom_edge
+| spk key_apostrophe = say_screen
+| spk key_h = say_from_left
+| spk key_y = say_from_top
+| spk key_semicolon = say_to_right
+| spk key_p = say_to_bottom
+| spk key_slash = say_attributes
+| spk key_enter = speakup_quiet
+| ctrl spk key_enter = speakup_off
+| spk key_9 = speakup_cut
+| spk key_8 = speakup_paste
+| shift spk key_m = say_first_char
+| ctrl spk key_semicolon = say_last_char
+| spk key_r = read_all_doc
+
5. The Speakup Sys System
+==========================
The Speakup screen reader also creates a speakup subdirectory as a part
of the sys system.
-As a convenience, run as root
+As a convenience, run as root::
-ln -s /sys/accessibility/speakup /speakup
+ ln -s /sys/accessibility/speakup /speakup
to directly access speakup parameters from /speakup.
-You can see these entries by typing the command:
+You can see these entries by typing the command::
-ls -1 /speakup/*
+ ls -1 /speakup/*
If you issue the above ls command, you will get back something like
-this:
-
-/speakup/attrib_bleep
-/speakup/bell_pos
-/speakup/bleep_time
-/speakup/bleeps
-/speakup/cursor_time
-/speakup/delimiters
-/speakup/ex_num
-/speakup/key_echo
-/speakup/keymap
-/speakup/no_interrupt
-/speakup/punc_all
-/speakup/punc_level
-/speakup/punc_most
-/speakup/punc_some
-/speakup/reading_punc
-/speakup/repeats
-/speakup/say_control
-/speakup/say_word_ctl
-/speakup/silent
-/speakup/spell_delay
-/speakup/synth
-/speakup/synth_direct
-/speakup/version
-
-/speakup/i18n:
-announcements
-characters
-chartab
-colors
-ctl_keys
-formatted
-function_names
-key_names
-states
-
-/speakup/soft:
-caps_start
-caps_stop
-delay_time
-direct
-freq
-full_time
-jiffy_delta
-pitch
-inflection
-punct
-rate
-tone
-trigger_time
-voice
-vol
-
-Notice the two subdirectories of /speakup: /speakup/i18n and
-/speakup/soft.
-The i18n subdirectory is described in a later section.
-The files under /speakup/soft represent settings that are specific to the
+this::
+
+ /speakup/attrib_bleep
+ /speakup/bell_pos
+ /speakup/bleep_time
+ /speakup/bleeps
+ /speakup/cursor_time
+ /speakup/delimiters
+ /speakup/ex_num
+ /speakup/key_echo
+ /speakup/keymap
+ /speakup/no_interrupt
+ /speakup/punc_all
+ /speakup/punc_level
+ /speakup/punc_most
+ /speakup/punc_some
+ /speakup/reading_punc
+ /speakup/repeats
+ /speakup/say_control
+ /speakup/say_word_ctl
+ /speakup/silent
+ /speakup/spell_delay
+ /speakup/synth
+ /speakup/synth_direct
+ /speakup/version
+
+ /speakup/i18n:
+ announcements
+ characters
+ chartab
+ colors
+ ctl_keys
+ formatted
+ function_names
+ key_names
+ states
+
+ /speakup/soft:
+ caps_start
+ caps_stop
+ delay_time
+ direct
+ freq
+ full_time
+ jiffy_delta
+ pitch
+ inflection
+ punct
+ rate
+ tone
+ trigger_time
+ voice
+ vol
+
+Notice the two subdirectories of ``/speakup``: ``/speakup/i18n`` and
+``/speakup/soft``.
+The `i18n` subdirectory is described in a later section.
+The files under ``/speakup/soft`` represent settings that are specific to the
driver for the software synthesizer. If you use the LiteTalk, your
-synthesizer-specific settings would be found in /speakup/ltlk. In other words,
-a subdirectory named /speakup/KWD is created to hold parameters specific
+synthesizer-specific settings would be found in ``/speakup/ltlk``. In other words,
+a subdirectory named ``/speakup/KWD`` is created to hold parameters specific
to the device whose keyword is KWD.
These parameters include volume, rate, pitch, and others.
In addition to using the Speakup hot keys to change such things as
volume, pitch, and rate, you can also echo values to the appropriate
-entry in the /speakup directory. This is very useful, since it
+entry in the ``/speakup`` directory. This is very useful, since it
lets you control Speakup parameters from within a script. How you
would write such scripts is somewhat beyond the scope of this manual,
but I will include a couple of simple examples here to give you a
@@ -438,44 +494,48 @@ level and the reading punctuation level at the same time. For
simplicity, we'll call them punc0, punc1, punc2, and punc3. The scripts
might look something like this:
-#!/bin/bash
-# punc0
-# set punc and reading punc levels to 0
-echo 0 >/speakup/punc_level
-echo 0 >/speakup/reading_punc
-echo Punctuation level set to 0.
-
-#!/bin/bash
-# punc1
-# set punc and reading punc levels to 1
-echo 1 >/speakup/punc_level
-echo 1 >/speakup/reading_punc
-echo Punctuation level set to 1.
-
-#!/bin/bash
-# punc2
-# set punc and reading punc levels to 2
-echo 2 >/speakup/punc_level
-echo 2 >/speakup/reading_punc
-echo Punctuation level set to 2.
-
-#!/bin/bash
-# punc3
-# set punc and reading punc levels to 3
-echo 3 >/speakup/punc_level
-echo 3 >/speakup/reading_punc
-echo Punctuation level set to 3.
+.. code-block:: shell
+
+ #!/bin/bash
+ # punc0
+ # set punc and reading punc levels to 0
+ echo 0 >/speakup/punc_level
+ echo 0 >/speakup/reading_punc
+ echo Punctuation level set to 0.
+
+ #!/bin/bash
+ # punc1
+ # set punc and reading punc levels to 1
+ echo 1 >/speakup/punc_level
+ echo 1 >/speakup/reading_punc
+ echo Punctuation level set to 1.
+
+ #!/bin/bash
+ # punc2
+ # set punc and reading punc levels to 2
+ echo 2 >/speakup/punc_level
+ echo 2 >/speakup/reading_punc
+ echo Punctuation level set to 2.
+
+ #!/bin/bash
+ # punc3
+ # set punc and reading punc levels to 3
+ echo 3 >/speakup/punc_level
+ echo 3 >/speakup/reading_punc
+ echo Punctuation level set to 3.
If you were to store these four small scripts in a directory in your
-path, perhaps /usr/local/bin, and set the permissions to 755 with the
-chmod command, then you could change the default reading punc and
+path, perhaps ``/usr/local/bin``, and set the permissions to 755 with the
+``chmod`` command, then you could change the default reading punc and
punctuation levels at the same time by issuing just one command. For
example, if you were to execute the punc3 command at your shell prompt,
then the reading punc and punc level would both get set to 3.
-I should note that the above scripts were written to work with bash, but
-regardless of which shell you use, you should be able to do something
-similar.
+.. note::
+
+ The above scripts were written to work with bash, but
+ regardless of which shell you use, you should be able to do something
+ similar.
The Speakup sys system also has another interesting use. You can echo
Speakup parameters into the sys system in a script during system
@@ -489,29 +549,29 @@ system. There are even some parameters that are read only, and cannot
be written to at all. For example, the version entry in the Speakup
sys system is read only. This is because there is no reason for a user
to tamper with the version number which is reported by Speakup. Doing
-an ls -l on /speakup/version will return this:
+an ``ls -l`` on ``/speakup/version`` will return this::
--r--r--r-- 1 root root 0 Mar 21 13:46 /speakup/version
+ -r--r--r-- 1 root root 0 Mar 21 13:46 /speakup/version
As you can see, the version entry in the Speakup sys system is read
only, is owned by root, and belongs to the root group. Doing a cat of
-/speakup/version will display the Speakup version number, like
-this:
+``/speakup/version`` will display the Speakup version number, like
+this::
-cat /speakup/version
-Speakup v-2.00 CVS: Thu Oct 21 10:38:21 EDT 2004
-synth dtlk version 1.1
+ cat /speakup/version
+ Speakup v-2.00 CVS: Thu Oct 21 10:38:21 EDT 2004
+ synth dtlk version 1.1
The display shows the Speakup version number, along with the version
number of the driver for the current synthesizer.
Looking at entries in the Speakup sys system can be useful in many
ways. For example, you might wish to know what level your volume is set
-at. You could type:
+at. You could type::
-cat /speakup/KWD/vol
-# Replace KWD with the keyword for your synthesizer, E.G., ltlk for LiteTalk.
-5
+ cat /speakup/KWD/vol
+ # Replace KWD with the keyword for your synthesizer, E.G., ltlk for LiteTalk.
+ 5
The number five which comes back is the level at which the synthesizer
volume is set at.
@@ -524,12 +584,14 @@ Vol for controlling volume, pitch for pitch, inflection for pitch range, rate
for controlling speaking rate, etc. If you find one you aren't sure about, you
can post a query on the Speakup list.
+
6. Changing Synthesizers
+=========================
It is possible to change to a different synthesizer while speakup is
running. In other words, it is not necessary to reboot the system
in order to use a different synthesizer. You can simply echo the
-synthesizer keyword to the /speakup/synth sys entry.
+synthesizer keyword to the ``/speakup/synth`` sys entry.
Depending on your situation, you may wish to echo none to the synth
sys entry, to disable speech while one synthesizer is disconnected and
a second one is connected in its place. Then echo the keyword for the
@@ -537,7 +599,9 @@ new synthesizer into the synth sys entry in order to start speech
with the newly connected synthesizer. See the list of synthesizer
keywords in section 1 to find the keyword which matches your synth.
+
7. Loading modules
+===================
As mentioned earlier, Speakup can either be completely compiled into the
kernel, with the exception of the help module, or it can be compiled as
@@ -555,51 +619,55 @@ modprobe command to load Speakup. You do this by loading the module for
the synthesizer driver you wish to use. The driver modules are all
named speakup_<keyword>, where <keyword> is the keyword for the
synthesizer you want. So, in order to load the driver for the DecTalk
-Express, you would type the following command:
+Express, you would type the following command::
-modprobe speakup_dectlk
+ modprobe speakup_dectlk
Issuing this command would load the DecTalk Express driver and all other
related Speakup modules necessary to get Speakup up and running.
To completely unload Speakup, again presuming that it is entirely built
-as modules, you would give the command:
+as modules, you would give the command::
-modprobe -r speakup_dectlk
+ modprobe -r speakup_dectlk
The above command assumes you were running a DecTalk Express. If you
were using a different synth, then you would substitute its keyword in
-place of dectlk.
+place of `dectlk`.
If you have multiple drivers loaded, you need to unload all of them, in
order to completely unload Speakup.
For example, if you have loaded both the dectlk and ltlk drivers, use the
-command:
-modprobe -r speakup_dectlk speakup_ltlk
+command::
+
+ modprobe -r speakup_dectlk speakup_ltlk
You cannot unload the driver for software synthesizers when a user-space
-daemon is using /dev/softsynth. First, kill the daemon. Next, remove
-the driver with the command:
-modprobe -r speakup_soft
+daemon is using ``/dev/softsynth``. First, kill the daemon. Next, remove
+the driver with the command::
+
+ modprobe -r speakup_soft
Now, suppose we have a situation where the main Speakup component
is built into the kernel, and some or all of the drivers are built as
modules. Since the main part of Speakup is compiled into the kernel, a
partial Speakup sys system has been created which we can take advantage
of by simply echoing the synthesizer keyword into the
-/speakup/synth sys entry. This will cause the kernel to
+``/speakup/synth`` sys entry. This will cause the kernel to
automatically load the appropriate driver module, and start Speakup
talking. To switch to another synth, just echo a new keyword to the
synth sys entry. For example, to load the DoubleTalk LT driver,
-you would type:
+you would type::
-echo ltlk >/speakup/synth
+ echo ltlk >/speakup/synth
-You can use the modprobe -r command to unload driver modules, regardless
+You can use the ``modprobe -r`` command to unload driver modules, regardless
of whether the main part of Speakup has been built into the kernel or
not.
+
8. Using Software Synthesizers
+===============================
Using a software synthesizer requires that some other software be
installed and running on your system. For this reason, software
@@ -607,34 +675,36 @@ synthesizers are not available for use at bootup, or during a system
installation process.
There are two freely-available solutions for software speech: Espeakup and
Speech Dispatcher.
-These are described in subsections 8.1 and 8.2, respectively.
+These are described in subsections `8.1. Espeakup`_ and
+`8.2. Speech Dispatcher`_, respectively.
-During the rest of this section, we assume that speakup_soft is either
+During the rest of this section, we assume that `speakup_soft` is either
built in to your kernel, or loaded as a module.
If your system does not have udev installed , before you can use a
-software synthesizer, you must have created the /dev/softsynth device.
-If you have not already done so, issue the following commands as root:
+software synthesizer, you must have created the ``/dev/softsynth`` device.
+If you have not already done so, issue the following commands as root::
-cd /dev
-mknod softsynth c 10 26
+ cd /dev
+ mknod softsynth c 10 26
-While we are at it, we might just as well create the /dev/synth device,
+While we are at it, we might just as well create the ``/dev/synth`` device,
which can be used to let user space programs send information to your
-synthesizer. To create /dev/synth, change to the /dev directory, and
-issue the following command as root:
+synthesizer. To create ``/dev/synth``, change to the ``/dev`` directory, and
+issue the following command as root::
-mknod synth c 10 25
+ mknod synth c 10 25
of both.
8.1. Espeakup
+-------------
Espeakup is a connector between Speakup and the eSpeak software synthesizer.
Espeakup may already be available as a package for your distribution
of Linux. If it is not packaged, you need to install it manually.
-You can find it in the contrib/ subdirectory of the Speakup sources.
-The filename is espeakup-$VERSION.tar.bz2, where $VERSION
+You can find it in the ``contrib/`` subdirectory of the Speakup sources.
+The filename is ``espeakup-$VERSION.tar.bz2``, where ``$VERSION``
depends on the current release of Espeakup. The Speakup 3.1.2 source
ships with version 0.71 of Espeakup.
The README file included with the Espeakup sources describes the process
@@ -643,31 +713,37 @@ of manual installation.
Assuming that Espeakup is installed, either by the user or by the distributor,
follow these steps to use it.
-Tell Speakup to use the "soft driver:
-echo soft > /speakup/synth
+Tell Speakup to use the "soft driver::
+
+ echo soft > /speakup/synth
Finally, start the espeakup program. There are two ways to do it.
Both require root privileges.
If Espeakup was installed as a package for your Linux distribution,
you probably have a distribution-specific script that controls the operation
-of the daemon. Look for a file named espeakup under /etc/init.d or
-/etc/rc.d. Execute the following command with root privileges:
-/etc/init.d/espeakup start
-Replace init.d with rc.d, if your distribution uses scripts located under
-/etc/rc.d.
+of the daemon. Look for a file named espeakup under ``/etc/init.d`` or
+``/etc/rc.d``. Execute the following command with root privileges::
+
+ /etc/init.d/espeakup start
+
+Replace ``init.d`` with ``rc.d``, if your distribution uses scripts located
+under ``/etc/rc.d``.
Your distribution will also have a procedure for starting daemons at
boot-time, so it is possible to have software speech as soon as user-space
daemons are started by the bootup scripts.
These procedures are not described in this document.
-If you built Espeakup manually, the "make install" step placed the binary
-under /usr/bin.
-Run the following command as root:
-/usr/bin/espeakup
+If you built Espeakup manually, the ``make install`` step placed the binary
+under ``/usr/bin``.
+Run the following command as root::
+
+ /usr/bin/espeakup
+
Espeakup should start speaking.
8.2. Speech Dispatcher
+----------------------
For this option, you must have a package called
Speech Dispatcher running on your system, and it must be configured to
@@ -692,53 +768,57 @@ compiled and installed speechd-up, you are almost ready to begin using
your software synthesizer.
Now you can begin using your software synthesizer. In order to do so,
-echo the soft keyword to the synth sys entry like this:
+echo the soft keyword to the synth sys entry like this::
-echo soft >/speakup/synth
+ echo soft >/speakup/synth
-Next run the speechd_up command like this:
+Next run the speechd_up command like this::
-speechd_up &
+ speechd_up &
Your synth should now start talking, and you should be able to adjust
the pitch, rate, etc.
+
9. Using The DecTalk PC Card
+=============================
The DecTalk PC card is an ISA card that is inserted into one of the ISA
slots in your computer. It requires that the DecTalk PC software be
installed on your computer, and that the software be loaded onto the
Dectalk PC card before it can be used.
-You can get the dec_pc.tgz file from the linux-speakup.org site. The
-dec_pc.tgz file is in the ~ftp/pub/linux/speakup directory.
+You can get the ``dec_pc.tgz`` file from the linux-speakup.org site. The
+``dec_pc.tgz`` file is in the ``~ftp/pub/linux/speakup`` directory.
-After you have downloaded the dec_pc.tgz file, untar it in your home
-directory, and read the Readme file in the newly created dec_pc
+After you have downloaded the ``dec_pc.tgz`` file, untar it in your home
+directory, and read the Readme file in the newly created ``dec_pc``
directory.
-The easiest way to get the software working is to copy the entire dec_pc
-directory into /user/local/lib. To do this, su to root in your home
-directory, and issue the command:
+The easiest way to get the software working is to copy the entire ``dec_pc``
+directory into ``/user/local/lib``. To do this, su to root in your home
+directory, and issue the command::
-cp dec_pc /usr/local/lib
+ cp dec_pc /usr/local/lib
You will need to copy the dtload command from the dec_pc directory to a
-directory in your path. Either /usr/bin or /usr/local/bin is a good
-choice.
+directory in your path. Either ``/usr/bin`` or ``/usr/local/bin`` is a
+good choice.
You can now run the dtload command in order to load the DecTalk PC
-software onto the card. After you have done this, echo the decpc
-keyword to the synth entry in the sys system like this:
+software onto the card. After you have done this, ``echo`` the decpc
+keyword to the synth entry in the sys system like this::
-echo decpc >/speakup/synth
+ echo decpc >/speakup/synth
Your DecTalk PC should start talking, and then you can adjust the pitch,
rate, volume, voice, etc. The voice entry in the Speakup sys system
will accept a number from 0 through 7 for the DecTalk PC synthesizer,
which will give you access to some of the DecTalk voices.
+
10. Using Cursor Tracking
+==========================
In Speakup version 2.0 and later, cursor tracking is turned on by
default. This means that when you are using an editor, Speakup will
@@ -781,8 +861,8 @@ Speakup speaks both your shell prompt and the current entry from the
command history. You may not want to hear the prompt repeated
each time you move, so you can silence it by specifying a window. Find
the last line of text on the screen. Clear the current window by pressing
-the key combination speakup f3. Use the review cursor to find the first
-character that follows your shell prompt. Press speakup + f2 twice, to
+the key combination speakup `f3`. Use the review cursor to find the first
+character that follows your shell prompt. Press speakup + `f2` twice, to
define a one-line window. The boundaries of the window are the
character following the shell prompt and the end of the line. Now, cycle
through the cursor tracking modes using keypad asterisk, until Speakup
@@ -794,7 +874,9 @@ lynx web browser. You definitely want to turn cursor tracking off when
you are using the alsamixer application. Otherwise, you won't be able
to hear your mixer settings while you are using the arrow keys.
+
11. Cut and Paste
+==================
One of Speakup's more useful features is the ability to cut and paste
text on the screen. This means that you can capture information from a
@@ -847,9 +929,11 @@ cut, mark it with the keypad slash key, then position the reading cursor
at the bottom right corner of the region to be cut, and cut it with the
keypad slash key.
+
12. Changing the Pronunciation of Characters
+=============================================
-Through the /speakup/i18n/characters sys entry, Speakup gives you the
+Through the ``/speakup/i18n/characters`` sys entry, Speakup gives you the
ability to change how Speakup pronounces a given character. You could,
for example, change how some punctuation characters are spoken. You can
even change how Speakup will pronounce certain letters.
@@ -859,19 +943,19 @@ character. The author of Speakup, Kirk Reiser, is Canadian, and thus
believes that the z should be pronounced zed. If you are an American,
you might wish to use the zee pronunciation instead of zed. You can
change the pronunciation of both the upper and lower case z with the
-following two commands:
+following two commands::
-echo 90 zee >/speakup/characters
-echo 122 zee >/speakup/characters
+ echo 90 zee >/speakup/characters
+ echo 122 zee >/speakup/characters
Let's examine the parts of the two previous commands. They are issued
at the shell prompt, and could be placed in a startup script.
The word echo tells the shell that you want to have it display the
string of characters that follow the word echo. If you were to just
-type:
+type::
-echo hello.
+ echo hello.
You would get the word hello printed on your screen as soon as you
pressed the enter key. In this case, we are echoing strings that we
@@ -883,22 +967,24 @@ values for the upper and lower case z, the characters we wish to change.
The string zee is the pronunciation that we want Speakup to use for the
upper and lower case z.
-The > symbol redirects the output of the echo command to a file, just
+The ``>`` symbol redirects the output of the echo command to a file, just
like in DOS, or at the Windows command prompt.
-And finally, /speakup/i18n/characters is the file entry in the sys system
+And finally, ``/speakup/i18n/characters`` is the file entry in the sys system
where we want the output to be directed. Speakup looks at the numeric
value of the character we want to change, and inserts the pronunciation
string into an internal table.
-You can look at the whole table with the following command:
+You can look at the whole table with the following command::
-cat /speakup/i18n/characters
+ cat /speakup/i18n/characters
Speakup will then print out the entire character pronunciation table. I
won't display it here, but leave you to look at it at your convenience.
+
13. Mapping Keys
+=================
Speakup has the capability of allowing you to assign or "map" keys to
internal Speakup commands. This section necessarily assumes you have a
@@ -908,15 +994,15 @@ manual. For this information, visit the Speakup web site at
http://linux-speakup.org/. The reason you'll need the kernel source
tree patched with Speakup is that the genmap utility you'll need for
processing keymaps is in the
-/usr/src/linux-<version_number>/drivers/char/speakup directory. The
-<version_number> in the above directory path is the version number of
+``/usr/src/linux-<version_number>/drivers/char/speakup`` directory. The
+``<version_number>`` in the above directory path is the version number of
the Linux source tree you are working with.
So ok, you've gone off and gotten your kernel source tree, and patched
and configured it. Now you can start manipulating keymaps.
You can either use the
-/usr/src/linux-<version_number>/drivers/char/speakup/speakupmap.map file
+``/usr/src/linux-<version_number>/drivers/char/speakup/speakupmap.map`` file
included with the Speakup source, or you can cut and paste the copy in
section 4 into a separate file. If you use the one in the Speakup
source tree, make sure you make a backup of it before you start making
@@ -924,48 +1010,52 @@ changes. You have been warned!
Suppose that you want to swap the key assignments for the Speakup
say_last_char and the Speakup say_first_char commands. The
-speakupmap.map lists the key mappings for these two commands as follows:
+speakupmap.map lists the key mappings for these two commands as follows::
-spk key_pageup = say_first_char
-spk key_pagedown = say_last_char
+ spk key_pageup = say_first_char
+ spk key_pagedown = say_last_char
You can edit your copy of the speakupmap.map file and swap the command
-names on the right side of the = (equals) sign. You did make a backup,
-right? The new keymap lines would look like this:
+names on the right side of the ``=`` (equals) sign. You did make a backup,
+right? The new keymap lines would look like this::
-spk key_pageup = say_last_char
-spk key_pagedown = say_first_char
+ spk key_pageup = say_last_char
+ spk key_pagedown = say_first_char
After you edit your copy of the speakupmap.map file, save it under a new
file name, perhaps newmap.map. Then exit your editor and return to the
shell prompt.
You are now ready to load your keymap with your swapped key assignments.
- Assuming that you saved your new keymap as the file newmap.map, you
-would load your keymap into the sys system like this:
+Assuming that you saved your new keymap as the file newmap.map, you
+would load your keymap into the sys system like this::
-/usr/src/linux-<version_number>/drivers/char/speakup/genmap newmap.map
->/speakup/keymap
+ /usr/src/linux-<version_number>/drivers/char/speakup/genmap newmap.map >/speakup/keymap
-Remember to substitute your kernel version number for the
-<version_number> in the above command. Also note that although the
-above command wrapped onto two lines in this document, you should type
-it all on one line.
+
+.. note::
+
+ Remember to substitute your kernel version number for the
+ ``<version_number>`` in the above command.
Your say first and say last characters should now be swapped. Pressing
speakup pagedown should read you the first non-whitespace character on
the line your reading cursor is in, and pressing speakup pageup should
read you the last character on the line your reading cursor is in.
-You should note that these new mappings will only stay in effect until
-you reboot, or until you load another keymap.
+.. note::
+
+ These new mappings will only stay in effect until you reboot,
+ or until you load another keymap.
One final warning. If you try to load a partial map, you will quickly
find that all the mappings you didn't include in your file got deleted
from the working map. Be extremely careful, and always make a backup!
You have been warned!
+
14. Internationalizing Speakup
+===============================
Speakup indicates various conditions to the user by speaking messages.
For instance, when you move to the left edge of the screen with the
@@ -974,101 +1064,108 @@ Prior to version 3.1.0 of Speakup, all of these messages were in English,
and they could not be changed. If you used a non-English synthesizer,
you still heard English messages, such as "left" and "cursoring on."
In version 3.1.0 or higher, one may load translations for the various
-messages via the /sys filesystem.
+messages via the ``/sys`` filesystem.
-The directory /speakup/i18n contains several collections of messages.
+The directory ``/speakup/i18n`` contains several collections of messages.
Each group of messages is stored in its own file.
The following section lists all of these files, along with a brief description
of each.
14.1. Files Under the i18n Subdirectory
+----------------------------------------
+
+announcements
+ This file contains various general announcements, most of which cannot
+ be categorized. You will find messages such as "You killed Speakup",
+ "I'm alive", "leaving help", "parked", "unparked", and others.
+ You will also find the names of the screen edges and cursor tracking modes
+ here.
-* announcements:
-This file contains various general announcements, most of which cannot
-be categorized. You will find messages such as "You killed Speakup",
-"I'm alive", "leaving help", "parked", "unparked", and others.
-You will also find the names of the screen edges and cursor tracking modes
-here.
-
-* characters:
-See section 12 for a description of this file.
-
-* chartab:
-See section 12. Unlike the rest of the files in the i18n subdirectory,
-this one does not contain messages to be spoken.
-
-* colors:
-When you use the "say attributes" function, Speakup says the name of the
-foreground and background colors. These names come from the i18n/colors
-file.
-
-* ctl_keys:
-Here, you will find names of control keys. These are used with Speakup's
-say_control feature.
-
-* formatted:
-This group of messages contains embedded formatting codes, to specify
-the type and width of displayed data. If you change these, you must
-preserve all of the formatting codes, and they must appear in the order
-used by the default messages.
-
-* function_names:
-Here, you will find a list of names for Speakup functions. These are used
-by the help system. For example, suppose that you have activated help mode,
-and you pressed keypad 3. Speakup says:
-"keypad 3 is character, say next."
-The message "character, say next" names a Speakup function, and it
-comes from this function_names file.
-
-* key_names:
-Again, key_names is used by Speakup's help system. In the previous
-example, Speakup said that you pressed "keypad 3."
-This name came from the key_names file.
-
-* states:
-This file contains names for key states.
-Again, these are part of the help system. For instance, if you had pressed
-speakup + keypad 3, you would hear:
-"speakup keypad 3 is go to bottom edge."
-The speakup key is depressed, so the name of the key state is speakup.
-This part of the message comes from the states collection.
-
-14.2. Changing language
-
-14.2.1. Loading Your Own Messages
+characters
+ See `12. Changing the Pronunciation of Characters`_ for a description
+ of this file.
+
+chartab
+ See `12. Changing the Pronunciation of Characters`_. Unlike the rest
+ of the files in the i18n subdirectory, this one does not contain messages
+ to be spoken.
+
+colors
+ When you use the "say attributes" function, Speakup says the name of the
+ foreground and background colors. These names come from the i18n/colors
+ file.
+
+ctl_keys
+ Here, you will find names of control keys. These are used with Speakup's
+ say_control feature.
+
+formatted
+ This group of messages contains embedded formatting codes, to specify
+ the type and width of displayed data. If you change these, you must
+ preserve all of the formatting codes, and they must appear in the order
+ used by the default messages.
+
+function_names
+ Here, you will find a list of names for Speakup functions. These are used
+ by the help system. For example, suppose that you have activated help mode,
+ and you pressed keypad 3. Speakup says:
+ "keypad 3 is character, say next."
+ The message "character, say next" names a Speakup function, and it
+ comes from this function_names file.
+
+key_names
+ Again, key_names is used by Speakup's help system. In the previous
+ example, Speakup said that you pressed "keypad 3."
+ This name came from the key_names file.
+
+states
+ This file contains names for key states.
+ Again, these are part of the help system. For instance, if you had pressed
+ speakup + keypad 3, you would hear:
+ "speakup keypad 3 is go to bottom edge."
+ The speakup key is depressed, so the name of the key state is speakup.
+ This part of the message comes from the states collection.
+
+14.2.1. Loading Your Own Messages
+----------------------------------
The files under the i18n subdirectory all follow the same format.
They consist of lines, with one message per line.
Each message is represented by a number, followed by the text of the message.
The number is the position of the message in the given collection.
-For example, if you view the file /speakup/i18n/colors, you will see the
-following list:
-
-0 black
-1 blue
-2 green
-3 cyan
-4 red
-5 magenta
-6 yellow
-7 white
-8 grey
+For example, if you view the file ``/speakup/i18n/colors``, you will see the
+following list::
+
+ 0 - black
+ 1 - blue
+ 2 - green
+ 3 - cyan
+ 4 - red
+ 5 - magenta
+ 6 - yellow
+ 7 - white
+ 8 - grey
You can change one message, or you can change a whole group.
To load a whole collection of messages from a new source, simply use
-the cp command:
-cp ~/my_colors /speakup/i18n/colors
+the cp command::
+
+ cp ~/my_colors /speakup/i18n/colors
+
You can change an individual message with the echo command,
as shown in the following example.
The Spanish name for the color blue is azul.
Looking at the colors file, we see that the name "blue" is at position 1
-within the colors group. Let's change blue to azul:
-echo '1 azul' > /speakup/i18n/colors
+within the colors group. Let's change blue to azul::
+
+ echo '1 azul' > /speakup/i18n/colors
+
The next time that Speakup says message 1 from the colors group, it will
say "azul", rather than "blue."
14.2.2. Choose a language
+-------------------------
In the future, translations into various languages will be made available,
and most users will just load the files necessary for their language. So far,
@@ -1078,11 +1175,11 @@ French is only available after you are logged in.
Canadian English is the default language. To toggle another language,
download the source of Speakup and untar it in your home directory. The
-following command should let you do this:
+following command should let you do this::
-tar xvjf speakup-<version>.tar.bz2
+ tar xvjf speakup-<version>.tar.bz2
-where <version> is the version number of the application.
+where ``<version>`` is the version number of the application.
Next, change to the newly created directory, then into the tools/ directory, and
run the script speakup_setlocale. You are asked the language that you want to
@@ -1098,38 +1195,41 @@ You will have to repeat these steps for any change of locale, i.e. if you wish
change the speakup's language or charset (iso-8859-15 ou UTF-8).
If you wish store the settings, note that at your next login, you will need to
-do:
+do::
-speakup load
+ speakup load
Alternatively, you can add the above line to your file
-~/.bashrc or ~/.bash_profile.
+``~/.bashrc`` or ``~/.bash_profile``.
If your system administrator ran himself the script, all the users will be able
to change from English to the language choosed by root and do directly
-speakupconf load (or add this to the ~/.bashrc or
-~/.bash_profile file). If there are several languages to handle, the
+speakupconf load (or add this to the ``~/.bashrc`` or
+``~/.bash_profile`` file). If there are several languages to handle, the
administrator (or every user) will have to run the first steps until speakupconf
save, choosing the appropriate language, in every user's home directory. Every
user will then be able to do speakupconf load, Speakup will load his own settings.
14.3. No Support for Non-Western-European Languages
+----------------------------------------------------
As of the current release, Speakup only supports Western European languages.
Support for the extended characters used by languages outside of the Western
European family of languages is a work in progress.
+
15. Using Speakup's Windowing Capability
+=========================================
Speakup has the capability of defining and manipulating windows on the
screen. Speakup uses the term "Window", to mean a user defined area of
the screen. The key strokes for defining and manipulating Speakup
-windows are as follows:
+windows are as follows::
-speakup + f2 -- Set the bounds of the window.
-Speakup + f3 -- clear the current window definition.
-speakup + f4 -- Toggle window silence on and off.
-speakup + keypad plus -- Say the currently defined window.
+ speakup + f2 -- Set the bounds of the window.
+ Speakup + f3 -- clear the current window definition.
+ speakup + f4 -- Toggle window silence on and off.
+ speakup + keypad plus -- Say the currently defined window.
These capabilities are useful for tracking a certain part of the screen
without rereading the whole screen, or for silencing a part of the
@@ -1141,55 +1241,64 @@ windows automatically defined for specific applications.
In order to define a window, use the review keys to move your reading
cursor to the beginning of the area you want to define. Then press
-speakup + f2. Speakup will tell you that the window starts at the
+speakup + `f2`. Speakup will tell you that the window starts at the
indicated row and column position. Then move the reading cursor to the
-end of the area to be defined as a window, and press speakup + f2 again.
- If there is more than one line in the window, Speakup will tell you
+end of the area to be defined as a window, and press speakup + `f2` again.
+If there is more than one line in the window, Speakup will tell you
that the window ends at the indicated row and column position. If there
is only one line in the window, then Speakup will tell you that the
window is the specified line on the screen. If you are only defining a
-one line window, you can just press speakup + f2 twice after placing the
+one line window, you can just press speakup + `f2` twice after placing the
reading cursor on the line you want to define as a window. It is not
necessary to position the reading cursor at the end of the line in order
to define the whole line as a window.
+
16. Tools for Controlling Speakup
+==================================
The speakup distribution includes extra tools (in the tools directory)
which were written to make speakup easier to use. This section will
briefly describe the use of these tools.
16.1. Speakupconf
+------------------
speakupconf began life as a contribution from Steve Holmes, a member of
the speakup community. We would like to thank him for his work on the
early versions of this project.
This script may be installed as part of your linux distribution, but if
-it isn't, the recommended places to put it are /usr/local/bin or
-/usr/bin. This script can be run by any user, so it does not require
+it isn't, the recommended places to put it are ``/usr/local/bin`` or
+``/usr/bin``. This script can be run by any user, so it does not require
root privileges.
Speakupconf allows you to save and load your Speakup settings. It works
-by reading and writing the /sys files described above.
+by reading and writing the ``/sys`` files described above.
The directory that speakupconf uses to store your settings depends on
whether it is run from the root account. If you execute speakupconf as
-root, it uses the directory /etc/speakup. Otherwise, it uses the directory
-~/.speakup, where ~ is your home directory.
+root, it uses the directory ``/etc/speakup``. Otherwise, it uses the directory
+``~/.speakup``, where ``~`` is your home directory.
Anyone who needs to use Speakup from your console can load his own custom
settings with this script.
speakupconf takes one required argument: load or save.
-Use the command
-speakupconf save
-to save your Speakup settings, and
-speakupconf load
+Use the command::
+
+ speakupconf save
+
+to save your Speakup settings, and::
+
+ speakupconf load
+
to load them into Speakup.
+
A second argument may be specified to use an alternate directory to
load or save the speakup parameters.
16.2. Talkwith
+---------------
Charles Hallenbeck, another member of the speakup community, wrote the
initial versions of this script, and we would also like to thank him for
@@ -1197,7 +1306,7 @@ his work on it.
This script needs root privileges to run, so if it is not installed as
part of your linux distribution, the recommended places to install it
-are /usr/local/sbin or /usr/sbin.
+are ``/usr/local/sbin`` or ``/usr/sbin``.
Talkwith allows you to switch synthesizers on the fly. It takes a synthesizer
name as an argument. For instance,
@@ -1208,25 +1317,36 @@ use. There are two possible choices:
spd and espeakup. spd is an abbreviation for speechd-up.
If you wish to use espeakup for software synthesis, give the command
talkwith soft espeakup
-To use speechd-up, type:
-talkwith soft spd
+To use speechd-up, type::
+
+ talkwith soft spd
+
Any arguments that follow the name of the daemon are passed to the daemon
-when it is invoked. For instance:
-talkwith espeakup --default-voice=fr
+when it is invoked. For instance::
+
+ talkwith espeakup --default-voice=fr
+
causes espeakup to use the French voice.
-Note that talkwith must always be executed with root privileges.
+
+.. note::
+
+ Talkwith must always be executed with root privileges.
Talkwith does not attempt to load your settings after the new
synthesizer is activated. You can use speakupconf to load your settings
if desired.
+
+Document License
+================
+
GNU Free Documentation License
Version 1.2, November 2002
- Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
+Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
0. PREAMBLE
--
2.20.1
Hello,
Adding the speakup list in the loop.
Igor Matheus Andrade Torrente wrote:
> Modify some parts of the text and add the necessary formatting to leverage
> the rst features. Including links, code-blocks, bullet lists, etc.
>
> Also, adds a table of contents at the beginning and a section to the
> license.
>
> This change helps integrate this documentation to the rest of the rst
> documentation.
Mmm, I'm unsure how the result is readable with the speakup screen
reader itself. I have attached the result, could people on the speakup
mailing list check how well it goes? If it significantly degrades
readability, we'll have to reject the move to rst formatting, since in
the end it's people who use the speakup screen reader who need to be
able to read this document.
Samuel
Hi Samuel: While I've never heard of that file extention, I sampled that file,
heard nothing unusual, probably reading in Alpine.
Chime
Hello,
On 01/06/2021 00:07, Samuel Thibault wrote:
> Mmm, I'm unsure how the result is readable with the speakup screen
> reader itself. I have attached the result, could people on the speakup
> mailing list check how well it goes? If it significantly degrades
> readability, we'll have to reject the move to rst formatting, since in
> the end it's people who use the speakup screen reader who need to be
> able to read this document.
>
> Samuel
Can we not have two versions? I don't have Sphinx installed (used to format
https://www.kernel.org/doc/html/latest/index.html) but converted
speakup.rst to
html5 using rst2html5.py and indeed the output is way better looking and
easier
to navigate than the txt version.
And anyway can we just provide a link to the web page that will be built
from the rst file? I think it should be accessible in graphical web
browsers as
in console ones (I tried using links, lynx and w3m).
As an aside the document still states:
Speakup does NOT support usb connections!
Is it still true? PS I widely prefer the asciidoc/asciidoctor format
than rst,
but the choice has been done for the Linux Kernel documentation, I know...
Didier
On Tue, Jun 01, 2021 at 12:07:54AM +0200, Samuel Thibault wrote:
> Mmm, I'm unsure how the result is readable with the speakup screen
> reader itself. I have attached the result, could people on the speakup
> mailing list check how well it goes? If it significantly degrades
> readability, we'll have to reject the move to rst formatting, since in
> the end it's people who use the speakup screen reader who need to be
> able to read this document.
It sounds OK to me with punctuation level set to 1, and using software
synthesis through espeakup. The formatting could be a problem if
someone is using a higher punctuation level, or a braille
display. Could a txtdocs option be implemented as a documentation
target for kernel builds, which would produce plain text files? That I
think would provide the best of both worlds where the guide could be
maintained as RST, but could be output in plain text like the format
the guide exists in now.
Another concern is that if the speakup guide is maintained in RST,
that could dissuade others from keeping it updated who don't already
know RST.
Greg
--
web site: http://www.gregn.net
gpg public key: http://www.gregn.net/pubkey.asc
skype: gregn1
(authorization required, add me to your contacts list first)
If we haven't been in touch before, e-mail me before adding me to your contacts.
--
Free domains: http://www.eu.org/ or mail [email protected]
On 01/06/2021 01:15, Gregory Nowak wrote:
> Another concern is that if the speakup guide is maintained in RST,
> that could dissuade others from keeping it updated who don't already
> know RST.
I only we could find someone to keep it updated...
01.06.2021 01:07, Samuel Thibault пишет:
> Hello,
>
> Adding the speakup list in the loop.
>
> Igor Matheus Andrade Torrente wrote:
>> Modify some parts of the text and add the necessary formatting to leverage
>> the rst features. Including links, code-blocks, bullet lists, etc.
>>
>> Also, adds a table of contents at the beginning and a section to the
>> license.
>>
>> This change helps integrate this documentation to the rest of the rst
>> documentation.
> Mmm, I'm unsure how the result is readable with the speakup screen
> reader itself. I have attached the result, could people on the speakup
> mailing list check how well it goes? If it significantly degrades
> readability, we'll have to reject the move to rst formatting, since in
> the end it's people who use the speakup screen reader who need to be
> able to read this document.
>
I think this is a great change. to be honest - I myself thought to do it
a few months ago.
As for readability, rst is a rather minimalistic format, so it is
convenient to perceive it even in a raw format, and the advantages of
using it, in my opinion, outweigh all the non-conveniences that I do not
observe.
> Samuel
Alexander
On 01/06/2021 01:15, Gregory Nowak wrote:
> Another concern is that if the speakup guide is maintained in RST,
Didier Spaier wrote:
> If only we could find someone to keep it updated...
The usual story between "everybody", "someone", and "nobody"...
Samuel
Didier Spaier <[email protected]> writes:
>> Mmm, I'm unsure how the result is readable with the speakup screen
>> reader itself. I have attached the result, could people on the speakup
>> mailing list check how well it goes? If it significantly degrades
>> readability, we'll have to reject the move to rst formatting, since in
>> the end it's people who use the speakup screen reader who need to be
>> able to read this document.
>> Samuel
>
> Can we not have two versions? I don't have Sphinx installed (used to format
> https://www.kernel.org/doc/html/latest/index.html) but converted
> speakup.rst to
> html5 using rst2html5.py and indeed the output is way better looking
> and easier
> to navigate than the txt version.
RST is ok with Speakup et al, both in source form and when converted to HTML
and rendered in a console browser.
> Is it still true? PS I widely prefer the asciidoc/asciidoctor format
> than rst,
> but the choice has been done for the Linux Kernel documentation, I know...
I knew you were a man of impeccably good taste, Didier, and this
confirms it. From a technical standpoint, asciidoc is meant as a
readable plain-text representation of docbook, so it is easily
convertable to the formats supported by docbook. But the kernel has
settled on RST. Speakup docs should use whatever the rest of the kernel
docs are using, and I see no compelling reason why they cannot.
--
Chris Brannon
Founder: Blind and Low Vision Unix Users Group (https://blvuug.org/).
Personal website: (https://the-brannons.com/)
Chat: IRC: teiresias on libera.chat and OFTC, XMPP: [email protected]
I read through much of the speakup users guide in rst and it seems
completely accessible reading the file in email with the mutt email client,
speakup and a doubletalk PC synth. No guarantees I may well have missed
things.
Thanks for the usefull work.
tom Fowle WA6IVG
On Mon, 31 May 2021, Igor Matheus Andrade Torrente <[email protected]> wrote:
> Modify some parts of the text and add the necessary formatting to leverage
> the rst features. Including links, code-blocks, bullet lists, etc.
>
> Also, adds a table of contents at the beginning and a section to the
> license.
>
> This change helps integrate this documentation to the rest of the rst
> documentation.
>
> Signed-off-by: Igor Matheus Andrade Torrente <[email protected]>
> ---
>
> V2: Rebase the patch to cover the commit cae2181b498fe
>
> ---
> Documentation/admin-guide/index.rst | 1 +
> .../{spkguide.txt => spkguide.rst} | 1026 +++++++++--------
> 2 files changed, 574 insertions(+), 453 deletions(-)
> rename Documentation/admin-guide/{spkguide.txt => spkguide.rst} (75%)
>
> diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
> index 423116c4e787..c45121777ecf 100644
> --- a/Documentation/admin-guide/index.rst
> +++ b/Documentation/admin-guide/index.rst
> @@ -112,6 +112,7 @@ configure specific aspects of kernel behavior to your liking.
> ras
> rtc
> serial-console
> + spkguide
> svga
> syscall-user-dispatch
> sysrq
> diff --git a/Documentation/admin-guide/spkguide.txt b/Documentation/admin-guide/spkguide.rst
> similarity index 75%
> rename from Documentation/admin-guide/spkguide.txt
> rename to Documentation/admin-guide/spkguide.rst
> index 977ab3f5a0a8..e254af41a8e9 100644
> --- a/Documentation/admin-guide/spkguide.txt
> +++ b/Documentation/admin-guide/spkguide.rst
> @@ -1,14 +1,20 @@
> -
> +========================
> The Speakup User's Guide
> -For Speakup 3.1.2 and Later
> -By Gene Collins
> -Updated by others
> -Last modified on Mon Sep 27 14:26:31 2010
> -Document version 1.3
> +========================
> +
> +| For Speakup 3.1.2 and Later
> +| By Gene Collins
> +| Updated by others
> +| Last modified on Mon Jan 21 17:08:21 2021
> +| Document version 1.3
> +
>
> -Copyright (c) 2005 Gene Collins
> -Copyright (c) 2008 Samuel Thibault
> -Copyright (c) 2009, 2010 the Speakup Team
> +Copyright and License
> +=====================
> +
> +| Copyright (c) 2005 Gene Collins
> +| Copyright (c) 2008 Samuel Thibault
> +| Copyright (c) 2009, 2010 the Speakup Team
Use a field list?
https://docutils.sourceforge.io/docs/user/rst/quickref.html#field-lists
>
> Permission is granted to copy, distribute and/or modify this document
> under the terms of the GNU Free Documentation License, Version 1.2 or
> @@ -17,7 +23,40 @@ Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
> copy of the license is included in the section entitled "GNU Free
> Documentation License".
>
> +
> +Contents
> +========
> +
> +* `Preface`_.
> +
> +* `1. Starting Speakup`_
> +* `2. Basic operation`_
> +* `3. Using the Speakup Help System`_
> +* `4. Keys and Their Assigned Commands`_
> +* `5. The Speakup Sys System`_
> +* `6. Changing Synthesizers`_
> +* `7. Loading modules`_
> +* `8. Using Software Synthesizers`_
> + - `8.1. Espeakup`_
> + - `8.2. Speech Dispatcher`_
> +* `9. Using The DecTalk PC Card`_
> +* `10. Using Cursor Tracking`_
> +* `11. Cut and Paste`_
> +* `12. Changing the Pronunciation of Characters`_
> +* `13. Mapping Keys`_
> +* `14. Internationalizing Speakup`_
> + - `14.1. Files Under the i18n Subdirectory`_.
> + - `14.2.1. Loading Your Own Messages`_.
> + - `14.2.2. Choose a language`_.
> + - `14.3. No Support for Non-Western-European Languages`_.
> +* `15. Using Speakup's Windowing Capability`_
> +* `16. Tools for Controlling Speakup`_
> + - `16.1. Speakupconf`_.
> + - `16.2. Talkwith`_
There's a directive for this:
.. contents::
The document didn't use to have a manually updated contents, why add one
now that you can have it automated?
https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents
> +
> +
> Preface
> +=======
>
> The purpose of this document is to familiarize users with the user
> interface to Speakup, a Linux Screen Reader. If you need instructions
> @@ -37,7 +76,9 @@ with speech access unaided by a sighted person. Again, these details
> are beyond the scope of this manual, but the user should be aware of
> them. See the web site mentioned above for further details.
>
> +
Unnecessary extra blank line, but okay.
> 1. Starting Speakup
I'd drop the numbers and let Sphinx take care of this.
> +====================
>
> If your system administrator has installed Speakup to work with your
> specific synthesizer by default, then all you need to do to use Speakup
> @@ -58,41 +99,43 @@ build and install your own kernel.
> If your kernel has been compiled with Speakup, and has no default
> synthesizer set, or you would like to use a different synthesizer than
> the default one, then you may issue the following command at the boot
> -prompt of your boot loader.
> +prompt of your boot loader.::
>
> -linux speakup.synth=ltlk
> + linux speakup.synth=ltlk
>
> This command would tell Speakup to look for and use a LiteTalk or
> DoubleTalk LT at boot up. You may replace the ltlk synthesizer keyword
> with the keyword for whatever synthesizer you wish to use. The
> -speakup.synth parameter will accept the following keywords, provided
> +``speakup.synth`` parameter will accept the following keywords, provided
> that support for the related synthesizers has been built into the
> kernel.
>
> -acntsa -- Accent SA
> -acntpc -- Accent PC
> -apollo -- Apollo
> -audptr -- Audapter
> -bns -- Braille 'n Speak
> -dectlk -- DecTalk Express (old and new, db9 serial only)
> -decext -- DecTalk (old) External
> -dtlk -- DoubleTalk PC
> -keypc -- Keynote Gold PC
> -ltlk -- DoubleTalk LT, LiteTalk, or external Tripletalk (db9 serial only)
> -spkout -- Speak Out
> -txprt -- Transport
> -dummy -- Plain text terminal
> -
> -Note: Speakup does * NOT * support usb connections! Speakup also does *
> -NOT * support the internal Tripletalk!
> +| acntsa -- Accent SA
> +| acntpc -- Accent PC
> +| apollo -- Apollo
> +| audptr -- Audapter
> +| bns -- Braille 'n Speak
> +| dectlk -- DecTalk Express (old and new, db9 serial only)
> +| decext -- DecTalk (old) External
> +| dtlk -- DoubleTalk PC
> +| keypc -- Keynote Gold PC
> +| ltlk -- DoubleTalk LT, LiteTalk, or external Tripletalk (db9 serial only)
> +| spkout -- Speak Out
> +| txprt -- Transport
> +| dummy -- Plain text terminal
Looks like a definition list?
https://docutils.sourceforge.io/docs/user/rst/quickref.html#definition-lists
> +
> +.. note::
> +
> + | Speakup does **NOT** support usb connections!
> + | Speakup also does **NOT** support the internal Tripletalk!
Why the pipes "|"?
>
> Speakup does support two other synthesizers, but because they work in
> conjunction with other software, they must be loaded as modules after
> their related software is loaded, and so are not available at boot up.
> These are as follows:
>
> -decpc -- DecTalk PC (not available at boot up)
> -soft -- One of several software synthesizers (not available at boot up)
> +| decpc -- DecTalk PC (not available at boot up)
> +| soft -- One of several software synthesizers (not available at boot up)
>
> See the sections on loading modules and software synthesizers later in
> this manual for further details. It should be noted here that the
> @@ -102,7 +145,9 @@ the boot process, such action must be configured by your system
> administrator. This will mean that you will hear some, but not all, of
> the bootup messages.
>
> +
> 2. Basic operation
> +===================
>
> Once you have booted the system, and if necessary, have supplied the
> proper bootup parameter for your synthesizer, Speakup will begin
> @@ -115,10 +160,12 @@ screen using the kernel, and must get their keyboard input through the
> kernel, they are automatically handled properly by Speakup. There are a
> few exceptions, but we'll come to those later.
>
> -Note: In this guide I will refer to the numeric keypad as the keypad.
> -This is done because the speakupmap.map file referred to later in this
> -manual uses the term keypad instead of numeric keypad. Also I'm lazy
> -and would rather only type one word. So keypad it is. Got it? Good.
> +.. note::
> +
> + In this guide I will refer to the numeric keypad as the keypad.
> + This is done because the speakupmap.map file referred to later in this
> + manual uses the term keypad instead of numeric keypad. Also I'm lazy
> + and would rather only type one word. So keypad it is. Got it? Good.
>
> Most of the Speakup review keys are located on the keypad at the far
> right of the keyboard. The numlock key should be off, in order for these
> @@ -131,9 +178,9 @@ You probably won't want to listen to all the bootup messages every time
> you start your system, though it's a good idea to listen to them at
> least once, just so you'll know what kind of information is available to
> you during the boot process. You can always review these messages after
> -bootup with the command:
> +bootup with the command::
>
> -dmesg | more
> + dmesg | more
>
> In order to speed the boot process, and to silence the speaking of the
> bootup messages, just press the keypad enter key. This key is located
> @@ -164,19 +211,19 @@ the speech with keypad enter, or use any of the Speakup review keys.
> Here are some basic Speakup review keys, and a short description of what
> they do.
>
> -keypad 1 -- read previous character
> -keypad 2 -- read current character (pressing keypad 2 twice rapidly will speak
> - the current character phonetically)
> -keypad 3 -- read next character
> -keypad 4 -- read previous word
> -keypad 5 -- read current word (press twice rapidly to spell the current word)
> -keypad 6 -- read next word
> -keypad 7 -- read previous line
> -keypad 8 -- read current line (press twice rapidly to hear how much the
> - text on the current line is indented)
> -keypad 9 -- read next line
> -keypad period -- speak current cursor position and announce current
> - virtual console
> +| keypad 1 -- read previous character
> +| keypad 2 -- read current character (pressing keypad 2 twice rapidly will speak
> + the current character phonetically)
> +| keypad 3 -- read next character
> +| keypad 4 -- read previous word
> +| keypad 5 -- read current word (press twice rapidly to spell the current word)
> +| keypad 6 -- read next word
> +| keypad 7 -- read previous line
> +| keypad 8 -- read current line (press twice rapidly to hear how much the
> + text on the current line is indented)
> +| keypad 9 -- read next line
> +| keypad period -- speak current cursor position and announce current
> + virtual console
Definition list?
Ditto for all the similar cases.
>
> It's also worth noting that the insert key on the keypad is mapped
> as the speakup key. Instead of pressing and releasing this key, as you
> @@ -190,16 +237,18 @@ Speakup will say, "You turned me off.", or "Hey, that's better." When
> Speakup is turned off, no new text on the screen will be spoken. You
> can still use the reading controls to review the screen however.
>
[snip]
> +
> +Document License
> +================
> +
Using SPDX might be nice.
> GNU Free Documentation License
> Version 1.2, November 2002
>
>
> - Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
> - Everyone is permitted to copy and distribute verbatim copies
> - of this license document, but changing it is not allowed.
> +Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
> +Everyone is permitted to copy and distribute verbatim copies
> +of this license document, but changing it is not allowed.
>
>
> 0. PREAMBLE
--
Jani Nikula, Intel Open Source Graphics Center
Hi Jani Nikula,
On 6/1/21 8:28 AM, Jani Nikula wrote:
> On Mon, 31 May 2021, Igor Matheus Andrade Torrente <[email protected]> wrote:
>> Modify some parts of the text and add the necessary formatting to leverage
>> the rst features. Including links, code-blocks, bullet lists, etc.
>>
>> Also, adds a table of contents at the beginning and a section to the
>> license.
>>
>> This change helps integrate this documentation to the rest of the rst
>> documentation.
>>
>> Signed-off-by: Igor Matheus Andrade Torrente <[email protected]>
>> ---
>>
>> V2: Rebase the patch to cover the commit cae2181b498fe
>>
>> ---
>> Documentation/admin-guide/index.rst | 1 +
>> .../{spkguide.txt => spkguide.rst} | 1026 +++++++++--------
>> 2 files changed, 574 insertions(+), 453 deletions(-)
>> rename Documentation/admin-guide/{spkguide.txt => spkguide.rst} (75%)
>>
>> diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
>> index 423116c4e787..c45121777ecf 100644
>> --- a/Documentation/admin-guide/index.rst
>> +++ b/Documentation/admin-guide/index.rst
>> @@ -112,6 +112,7 @@ configure specific aspects of kernel behavior to your liking.
>> ras
>> rtc
>> serial-console
>> + spkguide
>> svga
>> syscall-user-dispatch
>> sysrq
>> diff --git a/Documentation/admin-guide/spkguide.txt b/Documentation/admin-guide/spkguide.rst
>> similarity index 75%
>> rename from Documentation/admin-guide/spkguide.txt
>> rename to Documentation/admin-guide/spkguide.rst
>> index 977ab3f5a0a8..e254af41a8e9 100644
>> --- a/Documentation/admin-guide/spkguide.txt
>> +++ b/Documentation/admin-guide/spkguide.rst
>> @@ -1,14 +1,20 @@
>> -
>> +========================
>> The Speakup User's Guide
>> -For Speakup 3.1.2 and Later
>> -By Gene Collins
>> -Updated by others
>> -Last modified on Mon Sep 27 14:26:31 2010
>> -Document version 1.3
>> +========================
>> +
>> +| For Speakup 3.1.2 and Later
>> +| By Gene Collins
>> +| Updated by others
>> +| Last modified on Mon Jan 21 17:08:21 2021
>> +| Document version 1.3
>> +
>>
>> -Copyright (c) 2005 Gene Collins
>> -Copyright (c) 2008 Samuel Thibault
>> -Copyright (c) 2009, 2010 the Speakup Team
>> +Copyright and License
>> +=====================
>> +
>> +| Copyright (c) 2005 Gene Collins
>> +| Copyright (c) 2008 Samuel Thibault
>> +| Copyright (c) 2009, 2010 the Speakup Team
>
> Use a field list?
>
> https://docutils.sourceforge.io/docs/user/rst/quickref.html#field-lists
That what I was looking for when converting this text, thanks!
>
>>
>> Permission is granted to copy, distribute and/or modify this document
>> under the terms of the GNU Free Documentation License, Version 1.2 or
>> @@ -17,7 +23,40 @@ Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
>> copy of the license is included in the section entitled "GNU Free
>> Documentation License".
>>
>> +
>> +Contents
>> +========
>> +
>> +* `Preface`_.
>> +
>> +* `1. Starting Speakup`_
>> +* `2. Basic operation`_
>> +* `3. Using the Speakup Help System`_
>> +* `4. Keys and Their Assigned Commands`_
>> +* `5. The Speakup Sys System`_
>> +* `6. Changing Synthesizers`_
>> +* `7. Loading modules`_
>> +* `8. Using Software Synthesizers`_
>> + - `8.1. Espeakup`_
>> + - `8.2. Speech Dispatcher`_
>> +* `9. Using The DecTalk PC Card`_
>> +* `10. Using Cursor Tracking`_
>> +* `11. Cut and Paste`_
>> +* `12. Changing the Pronunciation of Characters`_
>> +* `13. Mapping Keys`_
>> +* `14. Internationalizing Speakup`_
>> + - `14.1. Files Under the i18n Subdirectory`_.
>> + - `14.2.1. Loading Your Own Messages`_.
>> + - `14.2.2. Choose a language`_.
>> + - `14.3. No Support for Non-Western-European Languages`_.
>> +* `15. Using Speakup's Windowing Capability`_
>> +* `16. Tools for Controlling Speakup`_
>> + - `16.1. Speakupconf`_.
>> + - `16.2. Talkwith`_
>
> There's a directive for this:
>
> .. contents::
>
> The document didn't use to have a manually updated contents, why add one
> now that you can have it automated?
>
> https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents
Thanks, I will change it!
>
>> +
>> +
>> Preface
>> +=======
>>
>> The purpose of this document is to familiarize users with the user
>> interface to Speakup, a Linux Screen Reader. If you need instructions
>> @@ -37,7 +76,9 @@ with speech access unaided by a sighted person. Again, these details
>> are beyond the scope of this manual, but the user should be aware of
>> them. See the web site mentioned above for further details.
>>
>> +
>
> Unnecessary extra blank line, but okay.
For me these blank lines makes the rst more readable in the text editor
like vim.
>
>> 1. Starting Speakup
>
> I'd drop the numbers and let Sphinx take care of this.
>
>> +====================
>>
>> If your system administrator has installed Speakup to work with your
>> specific synthesizer by default, then all you need to do to use Speakup
>> @@ -58,41 +99,43 @@ build and install your own kernel.
>> If your kernel has been compiled with Speakup, and has no default
>> synthesizer set, or you would like to use a different synthesizer than
>> the default one, then you may issue the following command at the boot
>> -prompt of your boot loader.
>> +prompt of your boot loader.::
>>
>> -linux speakup.synth=ltlk
>> + linux speakup.synth=ltlk
>>
>> This command would tell Speakup to look for and use a LiteTalk or
>> DoubleTalk LT at boot up. You may replace the ltlk synthesizer keyword
>> with the keyword for whatever synthesizer you wish to use. The
>> -speakup.synth parameter will accept the following keywords, provided
>> +``speakup.synth`` parameter will accept the following keywords, provided
>> that support for the related synthesizers has been built into the
>> kernel.
>>
>> -acntsa -- Accent SA
>> -acntpc -- Accent PC
>> -apollo -- Apollo
>> -audptr -- Audapter
>> -bns -- Braille 'n Speak
>> -dectlk -- DecTalk Express (old and new, db9 serial only)
>> -decext -- DecTalk (old) External
>> -dtlk -- DoubleTalk PC
>> -keypc -- Keynote Gold PC
>> -ltlk -- DoubleTalk LT, LiteTalk, or external Tripletalk (db9 serial only)
>> -spkout -- Speak Out
>> -txprt -- Transport
>> -dummy -- Plain text terminal
>> -
>> -Note: Speakup does * NOT * support usb connections! Speakup also does *
>> -NOT * support the internal Tripletalk!
>> +| acntsa -- Accent SA
>> +| acntpc -- Accent PC
>> +| apollo -- Apollo
>> +| audptr -- Audapter
>> +| bns -- Braille 'n Speak
>> +| dectlk -- DecTalk Express (old and new, db9 serial only)
>> +| decext -- DecTalk (old) External
>> +| dtlk -- DoubleTalk PC
>> +| keypc -- Keynote Gold PC
>> +| ltlk -- DoubleTalk LT, LiteTalk, or external Tripletalk (db9 serial only)
>> +| spkout -- Speak Out
>> +| txprt -- Transport
>> +| dummy -- Plain text terminal
>
> Looks like a definition list?
>
> https://docutils.sourceforge.io/docs/user/rst/quickref.html#definition-lists
If the '|' is replaced by definition-list, I'll have to skip a line to
each item so the sphinx doesn't concatenate them into a single line.
Like this:
keywords
acntsa -- Accent SA
acntpc -- Accent PC
apollo -- Apollo
[...]
There's a way to do that without these blank lines?
For me, it doesn't look very good, but I think the tradeoff worth it
improves readability to speakup users. If it is the case.
>
>> +
>> +.. note::
>> +
>> + | Speakup does **NOT** support usb connections!
>> + | Speakup also does **NOT** support the internal Tripletalk!
>
> Why the pipes "|"?
This is the way I found to separate these sentences into two different
lines. I'm gladly accepting a better solution for this :)
>
>>
>> Speakup does support two other synthesizers, but because they work in
>> conjunction with other software, they must be loaded as modules after
>> their related software is loaded, and so are not available at boot up.
>> These are as follows:
>>
>> -decpc -- DecTalk PC (not available at boot up)
>> -soft -- One of several software synthesizers (not available at boot up)
>> +| decpc -- DecTalk PC (not available at boot up)
>> +| soft -- One of several software synthesizers (not available at boot up)
>>
>> See the sections on loading modules and software synthesizers later in
>> this manual for further details. It should be noted here that the
>> @@ -102,7 +145,9 @@ the boot process, such action must be configured by your system
>> administrator. This will mean that you will hear some, but not all, of
>> the bootup messages.
>>
>> +
>> 2. Basic operation
>> +===================
>>
>> Once you have booted the system, and if necessary, have supplied the
>> proper bootup parameter for your synthesizer, Speakup will begin
>> @@ -115,10 +160,12 @@ screen using the kernel, and must get their keyboard input through the
>> kernel, they are automatically handled properly by Speakup. There are a
>> few exceptions, but we'll come to those later.
>>
>> -Note: In this guide I will refer to the numeric keypad as the keypad.
>> -This is done because the speakupmap.map file referred to later in this
>> -manual uses the term keypad instead of numeric keypad. Also I'm lazy
>> -and would rather only type one word. So keypad it is. Got it? Good.
>> +.. note::
>> +
>> + In this guide I will refer to the numeric keypad as the keypad.
>> + This is done because the speakupmap.map file referred to later in this
>> + manual uses the term keypad instead of numeric keypad. Also I'm lazy
>> + and would rather only type one word. So keypad it is. Got it? Good.
>>
>> Most of the Speakup review keys are located on the keypad at the far
>> right of the keyboard. The numlock key should be off, in order for these
>> @@ -131,9 +178,9 @@ You probably won't want to listen to all the bootup messages every time
>> you start your system, though it's a good idea to listen to them at
>> least once, just so you'll know what kind of information is available to
>> you during the boot process. You can always review these messages after
>> -bootup with the command:
>> +bootup with the command::
>>
>> -dmesg | more
>> + dmesg | more
>>
>> In order to speed the boot process, and to silence the speaking of the
>> bootup messages, just press the keypad enter key. This key is located
>> @@ -164,19 +211,19 @@ the speech with keypad enter, or use any of the Speakup review keys.
>> Here are some basic Speakup review keys, and a short description of what
>> they do.
>>
>> -keypad 1 -- read previous character
>> -keypad 2 -- read current character (pressing keypad 2 twice rapidly will speak
>> - the current character phonetically)
>> -keypad 3 -- read next character
>> -keypad 4 -- read previous word
>> -keypad 5 -- read current word (press twice rapidly to spell the current word)
>> -keypad 6 -- read next word
>> -keypad 7 -- read previous line
>> -keypad 8 -- read current line (press twice rapidly to hear how much the
>> - text on the current line is indented)
>> -keypad 9 -- read next line
>> -keypad period -- speak current cursor position and announce current
>> - virtual console
>> +| keypad 1 -- read previous character
>> +| keypad 2 -- read current character (pressing keypad 2 twice rapidly will speak
>> + the current character phonetically)
>> +| keypad 3 -- read next character
>> +| keypad 4 -- read previous word
>> +| keypad 5 -- read current word (press twice rapidly to spell the current word)
>> +| keypad 6 -- read next word
>> +| keypad 7 -- read previous line
>> +| keypad 8 -- read current line (press twice rapidly to hear how much the
>> + text on the current line is indented)
>> +| keypad 9 -- read next line
>> +| keypad period -- speak current cursor position and announce current
>> + virtual console
>
> Definition list?
>
> Ditto for all the similar cases.
>
>>
>> It's also worth noting that the insert key on the keypad is mapped
>> as the speakup key. Instead of pressing and releasing this key, as you
>> @@ -190,16 +237,18 @@ Speakup will say, "You turned me off.", or "Hey, that's better." When
>> Speakup is turned off, no new text on the screen will be spoken. You
>> can still use the reading controls to review the screen however.
>>
>
> [snip]
>
>> +
>> +Document License
>> +================
>> +
>
> Using SPDX might be nice.
I was just trying to respect the original text as much as possible, but
I don't mind change it if everybody agrees with it.
>
>> GNU Free Documentation License
>> Version 1.2, November 2002
>>
>>
>> - Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
>> - Everyone is permitted to copy and distribute verbatim copies
>> - of this license document, but changing it is not allowed.
>> +Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
>> +Everyone is permitted to copy and distribute verbatim copies
>> +of this license document, but changing it is not allowed.
>>
>>
>> 0. PREAMBLE
>
Hi Samuel,
On 5/31/21 7:07 PM, Samuel Thibault wrote:
> Hello,
>
> Adding the speakup list in the loop.
>
> Igor Matheus Andrade Torrente wrote:
>> Modify some parts of the text and add the necessary formatting to leverage
>> the rst features. Including links, code-blocks, bullet lists, etc.
>>
>> Also, adds a table of contents at the beginning and a section to the
>> license.
>>
>> This change helps integrate this documentation to the rest of the rst
>> documentation.
>
> Mmm, I'm unsure how the result is readable with the speakup screen
> reader itself. I have attached the result, could people on the speakup
> mailing list check how well it goes? If it significantly degrades
> readability, we'll have to reject the move to rst formatting, since in
> the end it's people who use the speakup screen reader who need to be
> able to read this document.
I was reading all the emails sent in this thread, but I'm not sure how I
should proceed. Do think should I continue to improve the patch with the
Jani Nikula suggestions? Or abandon it? Or keep both versions?
>
> Samuel
>
Thanks,
---
Igor M. A. Torrente
On Tue, 01 Jun 2021, Igor Torrente <[email protected]> wrote:
> Hi Jani Nikula,
>
> On 6/1/21 8:28 AM, Jani Nikula wrote:
>> On Mon, 31 May 2021, Igor Matheus Andrade Torrente <[email protected]> wrote:
>>> -acntsa -- Accent SA
>>> -acntpc -- Accent PC
>>> -apollo -- Apollo
>>> -audptr -- Audapter
>>> -bns -- Braille 'n Speak
>>> -dectlk -- DecTalk Express (old and new, db9 serial only)
>>> -decext -- DecTalk (old) External
>>> -dtlk -- DoubleTalk PC
>>> -keypc -- Keynote Gold PC
>>> -ltlk -- DoubleTalk LT, LiteTalk, or external Tripletalk (db9 serial only)
>>> -spkout -- Speak Out
>>> -txprt -- Transport
>>> -dummy -- Plain text terminal
>>> -
>>> -Note: Speakup does * NOT * support usb connections! Speakup also does *
>>> -NOT * support the internal Tripletalk!
>>> +| acntsa -- Accent SA
>>> +| acntpc -- Accent PC
>>> +| apollo -- Apollo
>>> +| audptr -- Audapter
>>> +| bns -- Braille 'n Speak
>>> +| dectlk -- DecTalk Express (old and new, db9 serial only)
>>> +| decext -- DecTalk (old) External
>>> +| dtlk -- DoubleTalk PC
>>> +| keypc -- Keynote Gold PC
>>> +| ltlk -- DoubleTalk LT, LiteTalk, or external Tripletalk (db9 serial only)
>>> +| spkout -- Speak Out
>>> +| txprt -- Transport
>>> +| dummy -- Plain text terminal
>>
>> Looks like a definition list?
>>
>> https://docutils.sourceforge.io/docs/user/rst/quickref.html#definition-lists
>
> If the '|' is replaced by definition-list, I'll have to skip a line to
> each item so the sphinx doesn't concatenate them into a single line.
> Like this:
>
> keywords
> acntsa -- Accent SA
>
> acntpc -- Accent PC
>
> apollo -- Apollo
> [...]
>
>
> There's a way to do that without these blank lines?
>
> For me, it doesn't look very good, but I think the tradeoff worth it
> improves readability to speakup users. If it is the case.
I was thinking:
acntsa
Accent SA
acntpc
Accent PC
apollo
Apollo
[...]
Simply by looking at what the data appears to be, and trying to match
that with the semantically appropriate rst construct. Maybe you think
that's too verbose or takes too much vertical space or isn't grep
friendly - and it's fine. I'm just making suggestions.
Another, more condensed alternative is to use tables, but that can
become annoying to maintain if you don't get the column widths right
from the start.
https://docutils.sourceforge.io/docs/user/rst/quickref.html#tables
>>> +
>>> +.. note::
>>> +
>>> + | Speakup does **NOT** support usb connections!
>>> + | Speakup also does **NOT** support the internal Tripletalk!
>>
>> Why the pipes "|"?
>
> This is the way I found to separate these sentences into two different
> lines. I'm gladly accepting a better solution for this :)
Maybe just like this?
.. note::
Speakup does **NOT** support usb connections!
Speakup also does **NOT** support the internal Tripletalk!
Again, I'm not insisting on any of these changes, I'm just suggesting
things you might find helpful!
BR,
Jani.
--
Jani Nikula, Intel Open Source Graphics Center
Igor Matheus Andrade Torrente <[email protected]> writes:
> Modify some parts of the text and add the necessary formatting to leverage
> the rst features. Including links, code-blocks, bullet lists, etc.
>
> Also, adds a table of contents at the beginning and a section to the
> license.
>
> This change helps integrate this documentation to the rest of the rst
> documentation.
>
> Signed-off-by: Igor Matheus Andrade Torrente <[email protected]>
Thanks for doing this work - I'm definitely in favor of it, and if the
RST format works for the intended readers, we want it.
Do please follow through on Jani's comments.
I am concerned about one thing, though: the licensing of this document
is not GPL-compatible, which means we can't build it into the rest of
the docs. It looks like it entered Documentation/ from staging, through
Greg's [added to CC] tree. Greg, were you aware of this licensing when
you added this document?
What are the chances that we can get the authors to agree on a change to
a GPL-compatible license for this file?
Thanks,
jon
Hello,
Igor Torrente, le mar. 01 juin 2021 12:39:01 -0300, a ecrit:
> I was reading all the emails sent in this thread, but I'm not sure how I
> should proceed. Do think should I continue to improve the patch with the
> Jani Nikula suggestions? Or abandon it? Or keep both versions?
It seems that people are fine with the switch to the .rst format, and
it'll indeed allow much better distribution of its content, so please
continue improving the patch with the suggestions from Jani, you have an
Acked-by: Samuel Thibault <[email protected]>
and the review will probably come from Jani, who seems to actually know
a bit about the rst syntax :)
Samuel
Jonathan Corbet, le mar. 01 juin 2021 12:53:01 -0600, a ecrit:
> I am concerned about one thing, though: the licensing of this document
> is not GPL-compatible, which means we can't build it into the rest of
> the docs.
? I see various GFDL-1.1-no-invariants-or-later documentation in
userspace-api/media notably, do they have such build restriction? What
is actually posing problem in the GFDL licence?
> What are the chances that we can get the authors to agree on a change to
> a GPL-compatible license for this file?
I don't know about Collins' opinion on this, Cc-ing him with the latest
mail my archives know for him (which dates 2008...)
The copyright "the Speakup Team" is a more complex thing to look for.
Samuel
Samuel Thibault, le mer. 02 juin 2021 00:37:43 +0200, a ecrit:
> - The initial import of the file (bddef0d280cd) wears only the Gene
> Collins copyright notice.
> - Christopher Brannon (now in Cc) made various changes and added the
> "the Speakup Team" copyright notice.
I'm here fixing the mail for Chris and Gene with an up-to-date email
address, I also bounced them my previous mail.
Samuel
Samuel Thibault, le mer. 02 juin 2021 00:44:52 +0200, a ecrit:
> Samuel Thibault, le mer. 02 juin 2021 00:37:43 +0200, a ecrit:
> > - The initial import of the file (bddef0d280cd) wears only the Gene
> > Collins copyright notice.
> > - Christopher Brannon (now in Cc) made various changes and added the
> > "the Speakup Team" copyright notice.
>
> I'm here fixing the mail for Chris and Gene with an up-to-date email
> address, I also bounced them my previous mail.
Err, sorry, Chris' wasn't actually fixed, now fixed.
Samuel
Samuel Thibault wrote:
> > - The initial import of the file (bddef0d280cd) wears only the Gene
> > Collins copyright notice.
>
> I'm here fixing the mail for Chris and Gene with an up-to-date email
> address, I also bounced them my previous mail.
Mmm, no, [email protected] is not working either. Does anybody on the
speakup mailing list know an up-to-date mail address for Gene?
Samuel
Hi Samuel,
On 6/1/21 6:55 PM, Samuel Thibault wrote:
> Hello,
>
> Igor Torrente, le mar. 01 juin 2021 12:39:01 -0300, a ecrit:
>> I was reading all the emails sent in this thread, but I'm not sure how I
>> should proceed. Do think should I continue to improve the patch with the
>> Jani Nikula suggestions? Or abandon it? Or keep both versions?
>
> It seems that people are fine with the switch to the .rst format, and
> it'll indeed allow much better distribution of its content, so please
> continue improving the patch with the suggestions from Jani, you have an
>
> Acked-by: Samuel Thibault <[email protected]>
>
> and the review will probably come from Jani, who seems to actually know
> a bit about the rst syntax :)
OK, I will keep improving it.
>
> Samuel
>
Thanks,
---
Igor M. A. Torrente
Hi Samuel,
On 6/1/21 6:57 PM, Samuel Thibault wrote:
> Igor Torrente, le mar. 01 juin 2021 12:11:26 -0300, a ecrit:
>>>> +| acntsa -- Accent SA
>>>> +| acntpc -- Accent PC
>>>> +| apollo -- Apollo
>>>> +| audptr -- Audapter
>>>> +| bns -- Braille 'n Speak
>>>> +| dectlk -- DecTalk Express (old and new, db9 serial only)
>>>> +| decext -- DecTalk (old) External
>>>> +| dtlk -- DoubleTalk PC
>>>> +| keypc -- Keynote Gold PC
>>>> +| ltlk -- DoubleTalk LT, LiteTalk, or external Tripletalk (db9 serial only)
>>>> +| spkout -- Speak Out
>>>> +| txprt -- Transport
>>>> +| dummy -- Plain text terminal
>>>
>>> Looks like a definition list?
>>>
>>> https://docutils.sourceforge.io/docs/user/rst/quickref.html#definition-lists
>>
>> If the '|' is replaced by definition-list, I'll have to skip a line to each
>> item so the sphinx doesn't concatenate them into a single line. Like this:
>>
>> keywords
>> acntsa -- Accent SA
>>
>> acntpc -- Accent PC
>>
>> apollo -- Apollo
>> [...]
>>
>>
>> There's a way to do that without these blank lines?
>
> The blank line isn't really a problem.
>
>>>> +Document License
>>>> +================
>>>> +
>>>
>>> Using SPDX might be nice.
>>
>> I was just trying to respect the original text as much as possible, but I
>> don't mind change it if everybody agrees with it.
>
> SPDX should be fine.
I have two questions about it.
1 - Should I only make this change when we have the 'acks' from all the
previous contributors? Or can I change it to the v3?
2 - Is '.. SPDX-License-Identifier: GPL-2.0' at the beginning is enough?
>
> Samuel
>
Thanks,
---
Igor M. A. Torrente
Igor Torrente, le mar. 01 juin 2021 12:11:26 -0300, a ecrit:
> > > +| acntsa -- Accent SA
> > > +| acntpc -- Accent PC
> > > +| apollo -- Apollo
> > > +| audptr -- Audapter
> > > +| bns -- Braille 'n Speak
> > > +| dectlk -- DecTalk Express (old and new, db9 serial only)
> > > +| decext -- DecTalk (old) External
> > > +| dtlk -- DoubleTalk PC
> > > +| keypc -- Keynote Gold PC
> > > +| ltlk -- DoubleTalk LT, LiteTalk, or external Tripletalk (db9 serial only)
> > > +| spkout -- Speak Out
> > > +| txprt -- Transport
> > > +| dummy -- Plain text terminal
> >
> > Looks like a definition list?
> >
> > https://docutils.sourceforge.io/docs/user/rst/quickref.html#definition-lists
>
> If the '|' is replaced by definition-list, I'll have to skip a line to each
> item so the sphinx doesn't concatenate them into a single line. Like this:
>
> keywords
> acntsa -- Accent SA
>
> acntpc -- Accent PC
>
> apollo -- Apollo
> [...]
>
>
> There's a way to do that without these blank lines?
The blank line isn't really a problem.
> > > +Document License
> > > +================
> > > +
> >
> > Using SPDX might be nice.
>
> I was just trying to respect the original text as much as possible, but I
> don't mind change it if everybody agrees with it.
SPDX should be fine.
Samuel
Jani Nikula, le mar. 01 juin 2021 18:51:49 +0300, a ecrit:
> On Tue, 01 Jun 2021, Igor Torrente <[email protected]> wrote:
> > There's a way to do that without these blank lines?
> >
> > For me, it doesn't look very good, but I think the tradeoff worth it
> > improves readability to speakup users. If it is the case.
>
> I was thinking:
>
> acntsa
> Accent SA
>
> acntpc
> Accent PC
>
> apollo
> Apollo
Having the two pieces on separate lines makes it a bit more tedious to
read on Braille displays, it's better to keep them single-line.
> >>> +
> >>> +.. note::
> >>> +
> >>> + | Speakup does **NOT** support usb connections!
> >>> + | Speakup also does **NOT** support the internal Tripletalk!
> >>
> >> Why the pipes "|"?
> >
> > This is the way I found to separate these sentences into two different
> > lines. I'm gladly accepting a better solution for this :)
>
> Maybe just like this?
>
> .. note::
>
> Speakup does **NOT** support usb connections!
>
> Speakup also does **NOT** support the internal Tripletalk!
That will be fine (though the first statement is actually outdated)
Samuel
Samuel Thibault <[email protected]> writes:
> Jonathan Corbet, le mar. 01 juin 2021 12:53:01 -0600, a ecrit:
>> I am concerned about one thing, though: the licensing of this document
>> is not GPL-compatible, which means we can't build it into the rest of
>> the docs.
>
> ? I see various GFDL-1.1-no-invariants-or-later documentation in
> userspace-api/media notably, do they have such build restriction? What
> is actually posing problem in the GFDL licence?
Those media docs are separate from the rest of the kernel
documentation. Other than that, all FDL in Documentation/ was
dual-licensed, last time I checked.
The problem is that the kernel docs, when built, include a great deal of
code and text taken directly from the kernel source. The built docs are
thus a derived product of the kernel and the result needs to carry a
GPL-compatible license. I've spent some time talking with lawyers about
this, and they have confirmed that view of things.
This document should not have entered Documentation/ with that license;
had I known this was happening at the time, I would have raised a fuss.
As a standalone .txt file there is probably no legal problem, but that
changes as soon as you bring it into RST TOC tree.
>> What are the chances that we can get the authors to agree on a change to
>> a GPL-compatible license for this file?
>
> I don't know about Collins' opinion on this, Cc-ing him with the latest
> mail my archives know for him (which dates 2008...)
>
> The copyright "the Speakup Team" is a more complex thing to look for.
Do you have a history of contributors to the file in its previous home?
I'm sorry to be obnoxious; I *really* want to see this document converted
and in with the rest. But the licensing is something that we need to
get right.
Thanks,
jon
Jonathan Corbet, le mar. 01 juin 2021 16:18:46 -0600, a ecrit:
> The problem is that the kernel docs, when built, include a great deal of
> code and text taken directly from the kernel source. The built docs are
> thus a derived product of the kernel and the result needs to carry a
> GPL-compatible license.
Ah...
> I've spent some time talking with lawyers about
> this, and they have confirmed that view of things.
Yes, sure.
> As a standalone .txt file there is probably no legal problem, but that
> changes as soon as you bring it into RST TOC tree.
Yes.
> >> What are the chances that we can get the authors to agree on a change to
> >> a GPL-compatible license for this file?
> >
> > I don't know about Collins' opinion on this, Cc-ing him with the latest
> > mail my archives know for him (which dates 2008...)
> >
> > The copyright "the Speakup Team" is a more complex thing to look for.
>
> Do you have a history of contributors to the file in its previous home?
Checking more closely, it seems we have it. The detail is in
[email protected]:linux-speakup/speakup.git in ./doc/spkguide.txt, but that
seems relatively simple:
- The initial import of the file (bddef0d280cd) wears only the Gene
Collins copyright notice.
- I made some changes and added my copyright notice.
- Christopher Brannon (now in Cc) made various changes and added the
"the Speakup Team" copyright notice.
- William Hubbs (now in Cc) made some changes.
- Steve Holmes (now in Cc) added one sentence.
So we'd need Gene's, Christopher's, William's, and Steve's ack on adding
the GPL alternative to the GFDL-1.2 licence.
Samuel
Samuel Thibault <[email protected]> writes:
> So we'd need Gene's, Christopher's, William's, and Steve's ack on adding
> the GPL alternative to the GFDL-1.2 licence.
That would be great.
One other thing that crosses my mind...we'll need to remove the GFDL
license text as well. That's already technically a violation to have
within a GFDL-licensed document, since it cannot be distributed under
the terms of that license. We have the GFDL text already in
LICENSES/deprecated/GFDL-1.2 if you want to refer to it (but the SPDX
tag is sufficient for that as well).
Thanks,
jon
Um, make that [email protected]. I need new fingers obviously.
Gene's current address is [email protected]
Kirk
On Wed, 2 Jun 2021, Samuel Thibault wrote:
> Samuel Thibault wrote:
>>> - The initial import of the file (bddef0d280cd) wears only the Gene
>>> Collins copyright notice.
>>
>> I'm here fixing the mail for Chris and Gene with an up-to-date email
>> address, I also bounced them my previous mail.
>
> Mmm, no, [email protected] is not working either. Does anybody on the
> speakup mailing list know an up-to-date mail address for Gene?
>
> Samuel
>
Samuel Thibault <[email protected]> writes:
> So we'd need Gene's, Christopher's, William's, and Steve's ack on adding
> the GPL alternative to the GFDL-1.2 licence.
You have my ack. Do whatever is needful. I wish I didn't have to care about
this stuff.
--
Chris Brannon
Founder: Blind and Low Vision Unix Users Group (https://blvuug.org/).
Personal website: (https://the-brannons.com/)
Chat: IRC: teiresias on libera.chat and OFTC, XMPP: [email protected]
Hello,
Chris Brannon, le mar. 01 juin 2021 19:54:30 -0700, a ecrit:
> Samuel Thibault <[email protected]> writes:
>
> > So we'd need Gene's, Christopher's, William's, and Steve's ack on adding
> > the GPL alternative to the GFDL-1.2 licence.
>
> You have my ack. Do whatever is needful. I wish I didn't have to care about
> this stuff.
Thanks! Linux will stay GPL forever anyway so that will do for
long-term.
Samuel
Jonathan Corbet, le mar. 01 juin 2021 16:47:05 -0600, a ecrit:
> Samuel Thibault <[email protected]> writes:
>
> > So we'd need Gene's, Christopher's, William's, and Steve's ack on adding
> > the GPL alternative to the GFDL-1.2 licence.
>
> That would be great.
>
> One other thing that crosses my mind...we'll need to remove the GFDL
> license text as well.
Yes, sure the SPDX tag will be enough.
Samuel
On Tue, 01 Jun 2021, Igor Torrente <[email protected]> wrote:
> Hi Samuel,
>
> On 6/1/21 6:55 PM, Samuel Thibault wrote:
>> Hello,
>>
>> Igor Torrente, le mar. 01 juin 2021 12:39:01 -0300, a ecrit:
>>> I was reading all the emails sent in this thread, but I'm not sure how I
>>> should proceed. Do think should I continue to improve the patch with the
>>> Jani Nikula suggestions? Or abandon it? Or keep both versions?
>>
>> It seems that people are fine with the switch to the .rst format, and
>> it'll indeed allow much better distribution of its content, so please
>> continue improving the patch with the suggestions from Jani, you have an
>>
>> Acked-by: Samuel Thibault <[email protected]>
>>
>> and the review will probably come from Jani, who seems to actually know
>> a bit about the rst syntax :)
>
> OK, I will keep improving it.
Heh, I just made suggestions on things that I thought could be done
better, but please see for yourself how it renders and how it actually
works with Braille displays. That should have priority over anything I
suggest.
BR,
Jani.
--
Jani Nikula, Intel Open Source Graphics Center
Hi Jani,
On 6/2/21 9:27 AM, Jani Nikula wrote:
> On Tue, 01 Jun 2021, Igor Torrente <[email protected]> wrote:
>> Hi Samuel,
>>
>> On 6/1/21 6:55 PM, Samuel Thibault wrote:
>>> Hello,
>>>
>>> Igor Torrente, le mar. 01 juin 2021 12:39:01 -0300, a ecrit:
>>>> I was reading all the emails sent in this thread, but I'm not sure how I
>>>> should proceed. Do think should I continue to improve the patch with the
>>>> Jani Nikula suggestions? Or abandon it? Or keep both versions?
>>>
>>> It seems that people are fine with the switch to the .rst format, and
>>> it'll indeed allow much better distribution of its content, so please
>>> continue improving the patch with the suggestions from Jani, you have an
>>>
>>> Acked-by: Samuel Thibault <[email protected]>
>>>
>>> and the review will probably come from Jani, who seems to actually know
>>> a bit about the rst syntax :)
>>
>> OK, I will keep improving it.
>
> Heh, I just made suggestions on things that I thought could be done
> better, but please see for yourself how it renders and how it actually
> works with Braille displays. That should have priority over anything I
> suggest.
I understand and agree. But I don't have a braille display to test the
change, so I will need the help of the community anyway.
And if anything gets worse I can revert the changes in the next patch
version based on the feedback.
>
> BR,
> Jani.
>
>
Thanks,
---
Igor M. A. Torrente
On Tue, Jun 01, 2021 at 04:18:46PM -0600, Jonathan Corbet wrote:
> Samuel Thibault <[email protected]> writes:
>
> > Jonathan Corbet, le mar. 01 juin 2021 12:53:01 -0600, a ecrit:
> >> I am concerned about one thing, though: the licensing of this document
> >> is not GPL-compatible, which means we can't build it into the rest of
> >> the docs.
> >
> > ? I see various GFDL-1.1-no-invariants-or-later documentation in
> > userspace-api/media notably, do they have such build restriction? What
> > is actually posing problem in the GFDL licence?
>
> Those media docs are separate from the rest of the kernel
> documentation. Other than that, all FDL in Documentation/ was
> dual-licensed, last time I checked.
>
> The problem is that the kernel docs, when built, include a great deal of
> code and text taken directly from the kernel source. The built docs are
> thus a derived product of the kernel and the result needs to carry a
> GPL-compatible license. I've spent some time talking with lawyers about
> this, and they have confirmed that view of things.
>
> This document should not have entered Documentation/ with that license;
> had I known this was happening at the time, I would have raised a fuss.
> As a standalone .txt file there is probably no legal problem, but that
> changes as soon as you bring it into RST TOC tree.
Sorry about this, I totally missed this issue when moving the code out
of staging.
greg k-h