Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
From:   Igor Matheus Andrade Torrente <igormtorrente@gmail.com>
To:     corbet@lwn.net, samuel.thibault@ens-lyon.org,
        jani.nikula@linux.intel.com, gene@collinsnet.net,
        w.d.hubbs@gmail.com, steve.holmes88@gmail.com
Cc:     Igor Matheus Andrade Torrente <igormtorrente@gmail.com>,
        speakup@linux-speakup.org, gregkh@linuxfoundation.org,
        rdunlap@infradead.org, grandmaster@al2klimov.de,
        chris@the-brannons.com, linux-doc@vger.kernel.org,
        linux-kernel@vger.kernel.org
Subject: [PATCH v3] docs: Convert the Speakup guide to rst
Date:   Thu,  3 Jun 2021 11:59:53 -0300
Message-Id: <20210603145953.10982-1-igormtorrente@gmail.com>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Precedence: bulk

Modify some parts of the text and add the necessary formatting to leverage
the rst features. Including links, code-blocks, bullet lists, etc.

Also, add a table of contents at the beginning and changes the license.

This change helps integrate this documentation to the rest of the rst
documentation.


Signed-off-by: Igor Matheus Andrade Torrente <igormtorrente@gmail.com>
---

v2: Rebase the patch to cover the commit cae2181b498fe

v3: Adds some Jani and Samuel's suggestion, and changes the licensing.

    And, therefore, this patch should only be accepted when we have
    all acks from the copyright owners.

    Current status:

    Gene Collins <gene@collinsnet.net> - Pending
    Samuel Thibault <samuel.thibault@ens-lyon.org> - ACK[1][2]
    Christopher Brannon <chris@the-brannons.com> - ACK[3]
    William Hubbs <w.d.hubbs@gmail.com> - Pending
    Steve Holmes <steve.holmes88@gmail.com> - Pending

    I will send a reply to this patch with all the files, so the Speakup
    community can evaluate the changes and compare them against the original
    and V2.

[1] https://www.spinics.net/lists/linux-doc/msg97635.html
[2] https://www.spinics.net/lists/linux-doc/msg97636.html
[3] https://www.spinics.net/lists/linux-doc/msg97655.html
---
 Documentation/admin-guide/index.rst    |    1 +
 Documentation/admin-guide/spkguide.rst | 1421 +++++++++++++++++++++
 Documentation/admin-guide/spkguide.txt | 1620 ------------------------
 3 files changed, 1422 insertions(+), 1620 deletions(-)
 create mode 100644 Documentation/admin-guide/spkguide.rst
 delete mode 100644 Documentation/admin-guide/spkguide.txt

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.rst b/Documentation/admin-guide/spkguide.rst
new file mode 100644
index 000000000000..ce4d42566e8e
--- /dev/null
+++ b/Documentation/admin-guide/spkguide.rst
@@ -0,0 +1,1421 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+========================
+The Speakup User's Guide
+========================
+
+| For Speakup 3.1.2 and Later
+| By Gene Collins
+| Updated by others
+| Last modified on Mon Jun 3 17:08:21 2021
+| Document version 1.3
+
+
+.. contents:: :local:
+
+
+Copyright
+=========
+
+:Authors:
+ Copyright (c) 2005  Gene Collins
+
+ Copyright (c) 2008  Samuel Thibault
+
+ Copyright (c) 2009, 2010  the Speakup Team
+
+
+Preface
+=======
+
+The purpose of this document is to familiarize users with the user
+interface to Speakup, a Linux Screen Reader.  If you need instructions
+for installing or obtaining Speakup, visit the web site at
+http://linux-speakup.org/.  Speakup is a set of patches to the standard
+Linux kernel source tree.  It can be built as a series of modules, or as
+a part of a monolithic kernel.  These details are beyond the scope of
+this manual, but the user may need to be aware of the module
+capabilities, depending on how your system administrator has installed
+Speakup.  If Speakup is built as a part of a monolithic kernel, and the
+user is using a hardware synthesizer, then Speakup will be able to
+provide speech access from the time the kernel is loaded, until the time
+the system is shutdown.  This means that if you have obtained Linux
+installation media for a distribution which includes Speakup as a part
+of its kernel, you will be able, as a blind person, to install Linux
+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
+is to boot your system, and Speakup should come up talking.  This
+assumes of course  that your synthesizer is a supported hardware
+synthesizer, and that it is either installed in or connected to your
+system, and is if necessary powered on.
+
+It is possible, however, that Speakup may have been compiled into the
+kernel with no default synthesizer.  It is even possible that your
+kernel has been compiled with support for some of the supported
+synthesizers and not others.  If you find that this is the case, and
+your synthesizer is supported but not available, complain to the person
+who compiled and installed your kernel.  Or better yet, go to the web
+site, and learn how to patch Speakup into your own kernel source, and
+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.::
+
+  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
+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 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)
+
+See the sections on loading modules and software synthesizers later in
+this manual for further details.  It should be noted here that the
+speakup.synth boot parameter will have no effect if Speakup has been
+compiled as modules.  In order for Speakup modules to be loaded during
+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
+talking as soon as the kernel is loaded.  In fact, it will talk a lot!
+It will speak all the boot up messages that the kernel prints on the
+screen during the boot process.  This is because Speakup is not a
+separate screen reader, but is actually built into the operating
+system.  Since almost all console applications must print text on the
+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.
+
+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
+to work.  If you toggle the numlock on, the keypad will produce numbers,
+which is exactly what you want for spreadsheets and such.  For the
+purposes of this guide, you should have the numlock turned off, which is
+its default state at bootup.
+
+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::
+
+  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
+in the bottom right corner of the keypad.  Speakup will shut up and stay
+that way, until you press another key.
+
+You can check to see if the boot process has completed by pressing the 8
+key on the keypad, which reads the current line.  This also has the
+effect of starting Speakup talking again, so you can press keypad enter
+to silence it again if the boot process has not completed.
+
+When the boot process is complete, you will arrive at a "login" prompt.
+At this point, you'll need to type in your user id and password, as
+provided by your system administrator.  You will hear Speakup speak the
+letters of your user id as you type it, but not the password.  This is
+because the password is not displayed on the screen for security
+reasons.  This has nothing to do with Speakup, it's a Linux security
+feature.
+
+Once you've logged in, you can run any Linux command or program which is
+allowed by your user id.  Normal users will not be able to run programs
+which require root privileges.
+
+When you are running a program or command, Speakup will automatically
+speak new text as it arrives on the screen.  You can at any time silence
+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
+
+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
+do under DOS or Windows, you hold it like a shift key, and press other
+keys in combination with it.  For example, repeatedly holding keypad
+insert, from now on called speakup, and keypad enter will toggle the
+speaking of new text on the screen on and off.  This is not the same as
+just pressing keypad enter by itself, which just silences the speech
+until you hit another key.  When you hit speakup plus keypad enter,
+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.
+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:
+
+"Leaving help."
+
+While you are in the Speakup help system, you can scroll up or down
+through the list of available commands using the cursor keys.  The list
+of commands is arranged in alphabetical order.  If you wish to jump to
+commands in a specific part of the alphabet, you may press the letter of
+the alphabet you wish to jump to.
+
+You can also just explore by typing keyboard keys.  Pressing keys will
+cause Speakup to speak the command associated with that key.  For
+example, if you press the keypad 8 key, you will hear:
+
+"Keypad 8 is line, say current."
+
+You'll notice that some commands do not have keys assigned to them.
+This is because they are very infrequently used commands, and are also
+accessible through the sys system.  We'll discuss the sys system later
+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
+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.
+
+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
+keypad functionality on and off can become a royal pain.  So, Speakup
+gives you a simple way to get at an alternative set of key mappings for
+your laptop.  These are also available by default on desktop systems,
+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.
+
+.. 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
+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
+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
+
+
+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::
+
+  ln -s /sys/accessibility/speakup /speakup
+
+to directly access speakup parameters from /speakup.
+You can see these entries by typing the command::
+
+  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
+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
+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
+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
+general idea of what such scripts can do.
+
+Suppose for example, that you wanted to control both the punctuation
+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:
+
+.. 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
+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.
+
+.. 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
+startup, and speakup will return to your preferred parameters every time
+the system is rebooted.
+
+Most of the Speakup sys parameters can be manipulated by a regular user
+on the system.  However, there are a few parameters that are dangerous
+enough that they should only be manipulated by the root user on your
+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::
+
+  -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::
+
+  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::
+
+  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.
+
+All the entries in the Speakup sys system are readable, some are
+writable by root only, and some are writable by everyone.  Unless you
+know what you are doing, you should probably leave the ones that are
+writable by root only alone.  Most of the names are self explanatory.
+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.
+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
+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
+a series of modules.   When compiled as modules, Speakup will only be
+able to speak some of the bootup messages if your system administrator
+has configured the system to load the modules at boo time. The modules
+can  be loaded after the file systems have been checked and mounted, or
+from an initrd.  There is a third possibility.  Speakup can be compiled
+with some components built into the kernel, and others as modules.  As
+we'll see in the next section, this is particularly useful when you are
+working with software synthesizers.
+
+If Speakup is completely compiled as modules, then you must use the
+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::
+
+  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::
+
+  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`.
+
+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
+
+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
+
+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
+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::
+
+  echo ltlk >/speakup/synth
+
+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
+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. Espeakup`_ and
+`8.2. Speech Dispatcher`_, respectively.
+
+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::
+
+  cd /dev
+  mknod softsynth c 10 26
+
+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::
+
+  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``
+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
+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
+
+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``.
+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
+
+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
+work with one of its supported software synthesizers.
+
+Two open source synthesizers you might use are Flite and Festival.  You
+might also choose to purchase the Software DecTalk from Fonix Sales Inc.
+If you run a google search for Fonix, you'll find their web site.
+
+You can obtain a copy of Speech Dispatcher from free(b)soft at
+http://www.freebsoft.org/.  Follow the installation instructions that
+come with Speech Dispatcher in order to install and configure Speech
+Dispatcher.  You can check out the web site for your Linux distribution
+in order to get a copy of either Flite or Festival.  Your Linux
+distribution may also have a precompiled Speech Dispatcher package.
+
+Once you've installed, configured, and tested Speech Dispatcher with your
+chosen software synthesizer, you still need one more piece of software
+in order to make things work.  You need a package called speechd-up.
+You get it from the free(b)soft web site mentioned above.  After you've
+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 soft >/speakup/synth
+
+Next run the speechd_up command like this::
+
+  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.
+
+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::
+
+  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.
+
+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::
+
+  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
+automatically speak characters as you move left and right with the
+cursor keys, and lines as you move up and down with the cursor keys.
+This is the traditional sort of cursor tracking.
+Recent versions of Speakup provide two additional ways to control the
+text that is spoken when the cursor is moved:
+"highlight tracking" and "read window."
+They are described later in this section.
+Sometimes, these modes get in your way, so you can disable cursor tracking
+altogether.
+
+You may select among the various forms of cursor tracking using the keypad
+asterisk key.
+Each time you press this key, a new mode is selected, and Speakup speaks
+the name of the new mode.  The names for the four possible states of cursor
+tracking are: "cursoring on", "highlight tracking", "read window",
+and "cursoring off."  The keypad asterisk key moves through the list of
+modes in a circular fashion.
+
+If highlight tracking is enabled, Speakup tracks highlighted text,
+rather than the cursor itself. When you move the cursor with the arrow keys,
+Speakup speaks the currently highlighted information.
+This is useful when moving through various menus and dialog boxes.
+If cursor tracking isn't helping you while navigating a menu,
+try highlight tracking.
+
+With the "read window" variety of cursor tracking, you can limit the text
+that Speakup speaks by specifying a window of interest on the screen.
+See section 15 for a description of the process of defining windows.
+When you move the cursor via the arrow keys, Speakup only speaks
+the contents of the window.  This is especially helpful when you are hearing
+superfluous speech.  Consider the following example.
+
+Suppose that you are at a shell prompt.  You use bash, and you want to
+explore your command history using the up and down arrow keys.  If you
+have enabled cursor tracking, you will hear two pieces of information.
+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
+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
+says "read window."  Move through your history using your arrow keys.
+You will notice that Speakup no longer speaks the redundant prompt.
+
+Some folks like to turn cursor tracking off while they are using the
+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
+program, and paste that captured text into a different place in the
+program, or into an entirely different program, which may even be
+running on a different console.
+
+For example, in this manual, we have made references to several web
+sites.  It would be nice if you could cut and paste these urls into your
+web browser.  Speakup does this quite nicely.  Suppose you wanted to
+past the following url into your browser:
+
+http://linux-speakup.org/
+
+Use the speakup review keys to position the reading cursor on the first
+character of the above url.  When the reading cursor is in position,
+press the keypad slash key once.  Speakup will say, "mark".  Next,
+position the reading cursor on the rightmost character of the above
+url. Press the keypad slash key once again to actually cut the text
+from the screen.  Speakup will say, "cut".  Although we call this
+cutting, Speakup does not actually delete the cut text from the screen.
+It makes a copy of the text in a special buffer for later pasting.
+
+Now that you have the url cut from the screen, you can paste it into
+your browser, or even paste the url on a command line as an argument to
+your browser.
+
+Suppose you want to start lynx and go to the Speakup site.
+
+You can switch to a different console with the alt left and right
+arrows, or you can switch to a specific console by typing alt and a
+function key.  These are not Speakup commands, just standard Linux
+console capabilities.
+
+Once you've changed to an appropriate console, and are at a shell prompt,
+type the word lynx, followed by a space.  Now press and hold the speakup
+key, while you type the keypad slash character.  The url will be pasted
+onto the command line, just as though you had typed it in.  Press the
+enter key to execute the command.
+
+The paste buffer will continue to hold the cut information, until a new
+mark and cut operation is carried out.  This means you can paste the cut
+information as many times as you like before doing another cut
+operation.
+
+You are not limited to cutting and pasting only one line on the screen.
+You can also cut and paste rectangular regions of the screen.  Just
+position the reading cursor at the top left corner of the text to be
+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
+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.
+
+You may, for example, wish to change how Speakup pronounces the z
+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::
+
+  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::
+
+  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
+want to be redirected into the sys system.
+
+The numbers 90 and 122 in the above echo commands are the ascii numeric
+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
+like in DOS, or at the Windows command prompt.
+
+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::
+
+  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
+Linux kernel source tree installed, and that it has been patched and
+configured with Speakup.  How you do this is beyond the scope of this
+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
+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
+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
+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::
+
+  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::
+
+  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::
+
+  /usr/src/linux-<version_number>/drivers/char/speakup/genmap newmap.map >/speakup/keymap
+
+
+.. 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.
+
+.. 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
+review keys, Speakup says, "left."
+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.
+
+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.
+
+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
+
+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
+
+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
+
+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,
+only French language is available beyond native Canadian English language.
+
+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::
+
+  tar xvjf speakup-<version>.tar.bz2
+
+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
+use. Type the number associated to your language (e.g. fr for French) then press
+Enter. Needed files are copied in the i18n directory.
+
+Note: the speakupconf must be installed on your system so that settings are saved.
+Otherwise, you will have an error: your language will be loaded but you will
+have to run the script again every time Speakup restarts.
+See section 16.1. for information about speakupconf.
+
+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::
+
+  speakup load
+
+Alternatively, you can add the above line to your file
+``~/.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
+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::
+
+  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
+screen that is constantly changing, such as a clock or status line.
+
+There is no way to save these window settings, and you can only have one
+window defined for each virtual console.  There is also no way to have
+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
+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
+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
+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
+root privileges.
+
+Speakupconf allows you to save and load your Speakup settings.  It works
+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.
+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
+
+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
+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``.
+
+Talkwith allows you to switch synthesizers on the fly.  It takes a synthesizer
+name as an argument.  For instance,
+talkwith dectlk
+causes Speakup to use the DecTalk Express.  If you wish to switch to a
+software synthesizer, you must also indicate which daemon you wish to
+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
+
+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
+
+causes espeakup to use the French voice.
+
+.. 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.
+
+
+
diff --git a/Documentation/admin-guide/spkguide.txt b/Documentation/admin-guide/spkguide.txt
deleted file mode 100644
index 977ab3f5a0a8..000000000000
--- a/Documentation/admin-guide/spkguide.txt
+++ /dev/null
@@ -1,1620 +0,0 @@
-
-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
-
-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
-any later version published by the Free Software Foundation; with no
-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".
-
-Preface
-
-The purpose of this document is to familiarize users with the user
-interface to Speakup, a Linux Screen Reader.  If you need instructions
-for installing or obtaining Speakup, visit the web site at
-http://linux-speakup.org/.  Speakup is a set of patches to the standard
-Linux kernel source tree.  It can be built as a series of modules, or as
-a part of a monolithic kernel.  These details are beyond the scope of
-this manual, but the user may need to be aware of the module
-capabilities, depending on how your system administrator has installed
-Speakup.  If Speakup is built as a part of a monolithic kernel, and the
-user is using a hardware synthesizer, then Speakup will be able to
-provide speech access from the time the kernel is loaded, until the time
-the system is shutdown.  This means that if you have obtained Linux
-installation media for a distribution which includes Speakup as a part
-of its kernel, you will be able, as a blind person, to install Linux
-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
-is to boot your system, and Speakup should come up talking.  This
-assumes of course  that your synthesizer is a supported hardware
-synthesizer, and that it is either installed in or connected to your
-system, and is if necessary powered on.
-
-It is possible, however, that Speakup may have been compiled into the
-kernel with no default synthesizer.  It is even possible that your
-kernel has been compiled with support for some of the supported
-synthesizers and not others.  If you find that this is the case, and
-your synthesizer is supported but not available, complain to the person
-who compiled and installed your kernel.  Or better yet, go to the web
-site, and learn how to patch Speakup into your own kernel source, and
-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.
-
-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
-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!
-
-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)
-
-See the sections on loading modules and software synthesizers later in
-this manual for further details.  It should be noted here that the
-speakup.synth boot parameter will have no effect if Speakup has been
-compiled as modules.  In order for Speakup modules to be loaded during
-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
-talking as soon as the kernel is loaded.  In fact, it will talk a lot!
-It will speak all the boot up messages that the kernel prints on the
-screen during the boot process.  This is because Speakup is not a
-separate screen reader, but is actually built into the operating
-system.  Since almost all console applications must print text on the
-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.
-
-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
-to work.  If you toggle the numlock on, the keypad will produce numbers,
-which is exactly what you want for spreadsheets and such.  For the
-purposes of this guide, you should have the numlock turned off, which is
-its default state at bootup.
-
-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:
-
-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
-in the bottom right corner of the keypad.  Speakup will shut up and stay
-that way, until you press another key.
-
-You can check to see if the boot process has completed by pressing the 8
-key on the keypad, which reads the current line.  This also has the
-effect of starting Speakup talking again, so you can press keypad enter
-to silence it again if the boot process has not completed.
-
-When the boot process is complete, you will arrive at a "login" prompt.
-At this point, you'll need to type in your user id and password, as
-provided by your system administrator.  You will hear Speakup speak the
-letters of your user id as you type it, but not the password.  This is
-because the password is not displayed on the screen for security
-reasons.  This has nothing to do with Speakup, it's a Linux security
-feature.
-
-Once you've logged in, you can run any Linux command or program which is
-allowed by your user id.  Normal users will not be able to run programs
-which require root privileges.
-
-When you are running a program or command, Speakup will automatically
-speak new text as it arrives on the screen.  You can at any time silence
-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
-
-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
-do under DOS or Windows, you hold it like a shift key, and press other
-keys in combination with it.  For example, repeatedly holding keypad
-insert, from now on called speakup, and keypad enter will toggle the
-speaking of new text on the screen on and off.  This is not the same as
-just pressing keypad enter by itself, which just silences the speech
-until you hit another key.  When you hit speakup plus keypad enter,
-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.
-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:
-
-"Leaving help."
-
-While you are in the Speakup help system, you can scroll up or down
-through the list of available commands using the cursor keys.  The list
-of commands is arranged in alphabetical order.  If you wish to jump to
-commands in a specific part of the alphabet, you may press the letter of
-the alphabet you wish to jump to.
-
-You can also just explore by typing keyboard keys.  Pressing keys will
-cause Speakup to speak the command associated with that key.  For
-example, if you press the keypad 8 key, you will hear:
-
-"Keypad 8 is line, say current."
-
-You'll notice that some commands do not have keys assigned to them.
-This is because they are very infrequently used commands, and are also
-accessible through the sys system.  We'll discuss the sys system later
-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
-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.
-
-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
-keypad functionality on and off can become a royal pain.  So, Speakup
-gives you a simple way to get at an alternative set of key mappings for
-your laptop.  These are also available by default on desktop systems,
-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.
-
-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
-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
-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
-
-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
-
-ln -s /sys/accessibility/speakup /speakup
-
-to directly access speakup parameters from /speakup.
-You can see these entries by typing the command:
-
-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
-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
-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
-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
-general idea of what such scripts can do.
-
-Suppose for example, that you wanted to control both the punctuation
-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.
-
-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
-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.
-
-The Speakup sys system also has another interesting use.  You can echo
-Speakup parameters into the sys system in a script during system
-startup, and speakup will return to your preferred parameters every time
-the system is rebooted.
-
-Most of the Speakup sys parameters can be manipulated by a regular user
-on the system.  However, there are a few parameters that are dangerous
-enough that they should only be manipulated by the root user on your
-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:
-
--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:
-
-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:
-
-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.
-
-All the entries in the Speakup sys system are readable, some are
-writable by root only, and some are writable by everyone.  Unless you
-know what you are doing, you should probably leave the ones that are
-writable by root only alone.  Most of the names are self explanatory.
-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.
-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
-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
-a series of modules.   When compiled as modules, Speakup will only be
-able to speak some of the bootup messages if your system administrator
-has configured the system to load the modules at boo time. The modules
-can  be loaded after the file systems have been checked and mounted, or
-from an initrd.  There is a third possibility.  Speakup can be compiled
-with some components built into the kernel, and others as modules.  As
-we'll see in the next section, this is particularly useful when you are
-working with software synthesizers.
-
-If Speakup is completely compiled as modules, then you must use the
-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:
-
-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:
-
-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.
-
-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
-
-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
-
-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
-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:
-
-echo ltlk >/speakup/synth
-
-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
-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.
-
-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:
-
-cd /dev
-mknod softsynth c 10 26
-
-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:
-
-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
-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
-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
-
-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.
-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
-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
-work with one of its supported software synthesizers.
-
-Two open source synthesizers you might use are Flite and Festival.  You
-might also choose to purchase the Software DecTalk from Fonix Sales Inc.
-If you run a google search for Fonix, you'll find their web site.
-
-You can obtain a copy of Speech Dispatcher from free(b)soft at
-http://www.freebsoft.org/.  Follow the installation instructions that
-come with Speech Dispatcher in order to install and configure Speech
-Dispatcher.  You can check out the web site for your Linux distribution
-in order to get a copy of either Flite or Festival.  Your Linux
-distribution may also have a precompiled Speech Dispatcher package.
-
-Once you've installed, configured, and tested Speech Dispatcher with your
-chosen software synthesizer, you still need one more piece of software
-in order to make things work.  You need a package called speechd-up.
-You get it from the free(b)soft web site mentioned above.  After you've
-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 soft >/speakup/synth
-
-Next run the speechd_up command like this:
-
-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.
-
-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:
-
-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.
-
-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:
-
-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
-automatically speak characters as you move left and right with the
-cursor keys, and lines as you move up and down with the cursor keys.
-This is the traditional sort of cursor tracking.
-Recent versions of Speakup provide two additional ways to control the
-text that is spoken when the cursor is moved:
-"highlight tracking" and "read window."
-They are described later in this section.
-Sometimes, these modes get in your way, so you can disable cursor tracking
-altogether.
-
-You may select among the various forms of cursor tracking using the keypad
-asterisk key.
-Each time you press this key, a new mode is selected, and Speakup speaks
-the name of the new mode.  The names for the four possible states of cursor
-tracking are: "cursoring on", "highlight tracking", "read window",
-and "cursoring off."  The keypad asterisk key moves through the list of
-modes in a circular fashion.
-
-If highlight tracking is enabled, Speakup tracks highlighted text,
-rather than the cursor itself. When you move the cursor with the arrow keys,
-Speakup speaks the currently highlighted information.
-This is useful when moving through various menus and dialog boxes.
-If cursor tracking isn't helping you while navigating a menu,
-try highlight tracking.
-
-With the "read window" variety of cursor tracking, you can limit the text
-that Speakup speaks by specifying a window of interest on the screen.
-See section 15 for a description of the process of defining windows.
-When you move the cursor via the arrow keys, Speakup only speaks
-the contents of the window.  This is especially helpful when you are hearing
-superfluous speech.  Consider the following example.
-
-Suppose that you are at a shell prompt.  You use bash, and you want to
-explore your command history using the up and down arrow keys.  If you
-have enabled cursor tracking, you will hear two pieces of information.
-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
-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
-says "read window."  Move through your history using your arrow keys.
-You will notice that Speakup no longer speaks the redundant prompt.
-
-Some folks like to turn cursor tracking off while they are using the
-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
-program, and paste that captured text into a different place in the
-program, or into an entirely different program, which may even be
-running on a different console.
-
-For example, in this manual, we have made references to several web
-sites.  It would be nice if you could cut and paste these urls into your
-web browser.  Speakup does this quite nicely.  Suppose you wanted to
-past the following url into your browser:
-
-http://linux-speakup.org/
-
-Use the speakup review keys to position the reading cursor on the first
-character of the above url.  When the reading cursor is in position,
-press the keypad slash key once.  Speakup will say, "mark".  Next,
-position the reading cursor on the rightmost character of the above
-url. Press the keypad slash key once again to actually cut the text
-from the screen.  Speakup will say, "cut".  Although we call this
-cutting, Speakup does not actually delete the cut text from the screen.
-It makes a copy of the text in a special buffer for later pasting.
-
-Now that you have the url cut from the screen, you can paste it into
-your browser, or even paste the url on a command line as an argument to
-your browser.
-
-Suppose you want to start lynx and go to the Speakup site.
-
-You can switch to a different console with the alt left and right
-arrows, or you can switch to a specific console by typing alt and a
-function key.  These are not Speakup commands, just standard Linux
-console capabilities.
-
-Once you've changed to an appropriate console, and are at a shell prompt,
-type the word lynx, followed by a space.  Now press and hold the speakup
-key, while you type the keypad slash character.  The url will be pasted
-onto the command line, just as though you had typed it in.  Press the
-enter key to execute the command.
-
-The paste buffer will continue to hold the cut information, until a new
-mark and cut operation is carried out.  This means you can paste the cut
-information as many times as you like before doing another cut
-operation.
-
-You are not limited to cutting and pasting only one line on the screen.
-You can also cut and paste rectangular regions of the screen.  Just
-position the reading cursor at the top left corner of the text to be
-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
-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.
-
-You may, for example, wish to change how Speakup pronounces the z
-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:
-
-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:
-
-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
-want to be redirected into the sys system.
-
-The numbers 90 and 122 in the above echo commands are the ascii numeric
-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
-like in DOS, or at the Windows command prompt.
-
-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:
-
-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
-Linux kernel source tree installed, and that it has been patched and
-configured with Speakup.  How you do this is beyond the scope of this
-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
-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
-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
-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:
-
-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:
-
-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:
-
-/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.
-
-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.
-
-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
-review keys, Speakup says, "left."
-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.
-
-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.
-
-* 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
-
-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
-
-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
-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
-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,
-only French language is available beyond native Canadian English language.
-
-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:
-
-tar xvjf speakup-<version>.tar.bz2
-
-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
-use. Type the number associated to your language (e.g. fr for French) then press
-Enter. Needed files are copied in the i18n directory.
-
-Note: the speakupconf must be installed on your system so that settings are saved.
-Otherwise, you will have an error: your language will be loaded but you will
-have to run the script again every time Speakup restarts.
-See section 16.1. for information about speakupconf.
-
-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:
-
-speakup load
-
-Alternatively, you can add the above line to your file
-~/.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
-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:
-
-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
-screen that is constantly changing, such as a clock or status line.
-
-There is no way to save these window settings, and you can only have one
-window defined for each virtual console.  There is also no way to have
-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
-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
-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
-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
-root privileges.
-
-Speakupconf allows you to save and load your Speakup settings.  It works
-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.
-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
-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
-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.
-
-Talkwith allows you to switch synthesizers on the fly.  It takes a synthesizer
-name as an argument.  For instance,
-talkwith dectlk
-causes Speakup to use the DecTalk Express.  If you wish to switch to a
-software synthesizer, you must also indicate which daemon you wish to
-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
-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
-causes espeakup to use the French voice.
-Note that 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.
-
-                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.
-
-
-0. PREAMBLE
-
-The purpose of this License is to make a manual, textbook, or other
-functional and useful document "free" in the sense of freedom: to
-assure everyone the effective freedom to copy and redistribute it,
-with or without modifying it, either commercially or noncommercially.
-Secondarily, this License preserves for the author and publisher a way
-to get credit for their work, while not being considered responsible
-for modifications made by others.
-
-This License is a kind of "copyleft", which means that derivative
-works of the document must themselves be free in the same sense.  It
-complements the GNU General Public License, which is a copyleft
-license designed for free software.
-
-We have designed this License in order to use it for manuals for free
-software, because free software needs free documentation: a free
-program should come with manuals providing the same freedoms that the
-software does.  But this License is not limited to software manuals;
-it can be used for any textual work, regardless of subject matter or
-whether it is published as a printed book.  We recommend this License
-principally for works whose purpose is instruction or reference.
-
-
-1. APPLICABILITY AND DEFINITIONS
-
-This License applies to any manual or other work, in any medium, that
-contains a notice placed by the copyright holder saying it can be
-distributed under the terms of this License.  Such a notice grants a
-world-wide, royalty-free license, unlimited in duration, to use that
-work under the conditions stated herein.  The "Document", below,
-refers to any such manual or work.  Any member of the public is a
-licensee, and is addressed as "you".  You accept the license if you
-copy, modify or distribute the work in a way requiring permission
-under copyright law.
-
-A "Modified Version" of the Document means any work containing the
-Document or a portion of it, either copied verbatim, or with
-modifications and/or translated into another language.
-
-A "Secondary Section" is a named appendix or a front-matter section of
-the Document that deals exclusively with the relationship of the
-publishers or authors of the Document to the Document's overall subject
-(or to related matters) and contains nothing that could fall directly
-within that overall subject.  (Thus, if the Document is in part a
-textbook of mathematics, a Secondary Section may not explain any
-mathematics.)  The relationship could be a matter of historical
-connection with the subject or with related matters, or of legal,
-commercial, philosophical, ethical or political position regarding
-them.
-
-The "Invariant Sections" are certain Secondary Sections whose titles
-are designated, as being those of Invariant Sections, in the notice
-that says that the Document is released under this License.  If a
-section does not fit the above definition of Secondary then it is not
-allowed to be designated as Invariant.  The Document may contain zero
-Invariant Sections.  If the Document does not identify any Invariant
-Sections then there are none.
-
-The "Cover Texts" are certain short passages of text that are listed,
-as Front-Cover Texts or Back-Cover Texts, in the notice that says that
-the Document is released under this License.  A Front-Cover Text may
-be at most 5 words, and a Back-Cover Text may be at most 25 words.
-
-A "Transparent" copy of the Document means a machine-readable copy,
-represented in a format whose specification is available to the
-general public, that is suitable for revising the document
-straightforwardly with generic text editors or (for images composed of
-pixels) generic paint programs or (for drawings) some widely available
-drawing editor, and that is suitable for input to text formatters or
-for automatic translation to a variety of formats suitable for input
-to text formatters.  A copy made in an otherwise Transparent file
-format whose markup, or absence of markup, has been arranged to thwart
-or discourage subsequent modification by readers is not Transparent.
-An image format is not Transparent if used for any substantial amount
-of text.  A copy that is not "Transparent" is called "Opaque".
-
-Examples of suitable formats for Transparent copies include plain
-ASCII without markup, Texinfo input format, LaTeX input format, SGML
-or XML using a publicly available DTD, and standard-conforming simple
-HTML, PostScript or PDF designed for human modification.  Examples of
-transparent image formats include PNG, XCF and JPG.  Opaque formats
-include proprietary formats that can be read and edited only by
-proprietary word processors, SGML or XML for which the DTD and/or
-processing tools are not generally available, and the
-machine-generated HTML, PostScript or PDF produced by some word
-processors for output purposes only.
-
-The "Title Page" means, for a printed book, the title page itself,
-plus such following pages as are needed to hold, legibly, the material
-this License requires to appear in the title page.  For works in
-formats which do not have any title page as such, "Title Page" means
-the text near the most prominent appearance of the work's title,
-preceding the beginning of the body of the text.
-
-A section "Entitled XYZ" means a named subunit of the Document whose
-title either is precisely XYZ or contains XYZ in parentheses following
-text that translates XYZ in another language.  (Here XYZ stands for a
-specific section name mentioned below, such as "Acknowledgements",
-"Dedications", "Endorsements", or "History".)  To "Preserve the Title"
-of such a section when you modify the Document means that it remains a
-section "Entitled XYZ" according to this definition.
-
-The Document may include Warranty Disclaimers next to the notice which
-states that this License applies to the Document.  These Warranty
-Disclaimers are considered to be included by reference in this
-License, but only as regards disclaiming warranties: any other
-implication that these Warranty Disclaimers may have is void and has
-no effect on the meaning of this License.
-
-
-2. VERBATIM COPYING
-
-You may copy and distribute the Document in any medium, either
-commercially or noncommercially, provided that this License, the
-copyright notices, and the license notice saying this License applies
-to the Document are reproduced in all copies, and that you add no other
-conditions whatsoever to those of this License.  You may not use
-technical measures to obstruct or control the reading or further
-copying of the copies you make or distribute.  However, you may accept
-compensation in exchange for copies.  If you distribute a large enough
-number of copies you must also follow the conditions in section 3.
-
-You may also lend copies, under the same conditions stated above, and
-you may publicly display copies.
-
-
-3. COPYING IN QUANTITY
-
-If you publish printed copies (or copies in media that commonly have
-printed covers) of the Document, numbering more than 100, and the
-Document's license notice requires Cover Texts, you must enclose the
-copies in covers that carry, clearly and legibly, all these Cover
-Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
-the back cover.  Both covers must also clearly and legibly identify
-you as the publisher of these copies.  The front cover must present
-the full title with all words of the title equally prominent and
-visible.  You may add other material on the covers in addition.
-Copying with changes limited to the covers, as long as they preserve
-the title of the Document and satisfy these conditions, can be treated
-as verbatim copying in other respects.
-
-If the required texts for either cover are too voluminous to fit
-legibly, you should put the first ones listed (as many as fit
-reasonably) on the actual cover, and continue the rest onto adjacent
-pages.
-
-If you publish or distribute Opaque copies of the Document numbering
-more than 100, you must either include a machine-readable Transparent
-copy along with each Opaque copy, or state in or with each Opaque copy
-a computer-network location from which the general network-using
-public has access to download using public-standard network protocols
-a complete Transparent copy of the Document, free of added material.
-If you use the latter option, you must take reasonably prudent steps,
-when you begin distribution of Opaque copies in quantity, to ensure
-that this Transparent copy will remain thus accessible at the stated
-location until at least one year after the last time you distribute an
-Opaque copy (directly or through your agents or retailers) of that
-edition to the public.
-
-It is requested, but not required, that you contact the authors of the
-Document well before redistributing any large number of copies, to give
-them a chance to provide you with an updated version of the Document.
-
-
-4. MODIFICATIONS
-
-You may copy and distribute a Modified Version of the Document under
-the conditions of sections 2 and 3 above, provided that you release
-the Modified Version under precisely this License, with the Modified
-Version filling the role of the Document, thus licensing distribution
-and modification of the Modified Version to whoever possesses a copy
-of it.  In addition, you must do these things in the Modified Version:
-
-A. Use in the Title Page (and on the covers, if any) a title distinct
-   from that of the Document, and from those of previous versions
-   (which should, if there were any, be listed in the History section
-   of the Document).  You may use the same title as a previous version
-   if the original publisher of that version gives permission.
-B. List on the Title Page, as authors, one or more persons or entities
-   responsible for authorship of the modifications in the Modified
-   Version, together with at least five of the principal authors of the
-   Document (all of its principal authors, if it has fewer than five),
-   unless they release you from this requirement.
-C. State on the Title page the name of the publisher of the
-   Modified Version, as the publisher.
-D. Preserve all the copyright notices of the Document.
-E. Add an appropriate copyright notice for your modifications
-   adjacent to the other copyright notices.
-F. Include, immediately after the copyright notices, a license notice
-   giving the public permission to use the Modified Version under the
-   terms of this License, in the form shown in the Addendum below.
-G. Preserve in that license notice the full lists of Invariant Sections
-   and required Cover Texts given in the Document's license notice.
-H. Include an unaltered copy of this License.
-I. Preserve the section Entitled "History", Preserve its Title, and add
-   to it an item stating at least the title, year, new authors, and
-   publisher of the Modified Version as given on the Title Page.  If
-   there is no section Entitled "History" in the Document, create one
-   stating the title, year, authors, and publisher of the Document as
-   given on its Title Page, then add an item describing the Modified
-   Version as stated in the previous sentence.
-J. Preserve the network location, if any, given in the Document for
-   public access to a Transparent copy of the Document, and likewise
-   the network locations given in the Document for previous versions
-   it was based on.  These may be placed in the "History" section.
-   You may omit a network location for a work that was published at
-   least four years before the Document itself, or if the original
-   publisher of the version it refers to gives permission.
-K. For any section Entitled "Acknowledgements" or "Dedications",
-   Preserve the Title of the section, and preserve in the section all
-   the substance and tone of each of the contributor acknowledgements
-   and/or dedications given therein.
-L. Preserve all the Invariant Sections of the Document,
-   unaltered in their text and in their titles.  Section numbers
-   or the equivalent are not considered part of the section titles.
-M. Delete any section Entitled "Endorsements".  Such a section
-   may not be included in the Modified Version.
-N. Do not retitle any existing section to be Entitled "Endorsements"
-   or to conflict in title with any Invariant Section.
-O. Preserve any Warranty Disclaimers.
-
-If the Modified Version includes new front-matter sections or
-appendices that qualify as Secondary Sections and contain no material
-copied from the Document, you may at your option designate some or all
-of these sections as invariant.  To do this, add their titles to the
-list of Invariant Sections in the Modified Version's license notice.
-These titles must be distinct from any other section titles.
-
-You may add a section Entitled "Endorsements", provided it contains
-nothing but endorsements of your Modified Version by various
-parties--for example, statements of peer review or that the text has
-been approved by an organization as the authoritative definition of a
-standard.
-
-You may add a passage of up to five words as a Front-Cover Text, and a
-passage of up to 25 words as a Back-Cover Text, to the end of the list
-of Cover Texts in the Modified Version.  Only one passage of
-Front-Cover Text and one of Back-Cover Text may be added by (or
-through arrangements made by) any one entity.  If the Document already
-includes a cover text for the same cover, previously added by you or
-by arrangement made by the same entity you are acting on behalf of,
-you may not add another; but you may replace the old one, on explicit
-permission from the previous publisher that added the old one.
-
-The author(s) and publisher(s) of the Document do not by this License
-give permission to use their names for publicity for or to assert or
-imply endorsement of any Modified Version.
-
-
-5. COMBINING DOCUMENTS
-
-You may combine the Document with other documents released under this
-License, under the terms defined in section 4 above for modified
-versions, provided that you include in the combination all of the
-Invariant Sections of all of the original documents, unmodified, and
-list them all as Invariant Sections of your combined work in its
-license notice, and that you preserve all their Warranty Disclaimers.
-
-The combined work need only contain one copy of this License, and
-multiple identical Invariant Sections may be replaced with a single
-copy.  If there are multiple Invariant Sections with the same name but
-different contents, make the title of each such section unique by
-adding at the end of it, in parentheses, the name of the original
-author or publisher of that section if known, or else a unique number.
-Make the same adjustment to the section titles in the list of
-Invariant Sections in the license notice of the combined work.
-
-In the combination, you must combine any sections Entitled "History"
-in the various original documents, forming one section Entitled
-"History"; likewise combine any sections Entitled "Acknowledgements",
-and any sections Entitled "Dedications".  You must delete all sections
-Entitled "Endorsements".
-
-
-6. COLLECTIONS OF DOCUMENTS
-
-You may make a collection consisting of the Document and other documents
-released under this License, and replace the individual copies of this
-License in the various documents with a single copy that is included in
-the collection, provided that you follow the rules of this License for
-verbatim copying of each of the documents in all other respects.
-
-You may extract a single document from such a collection, and distribute
-it individually under this License, provided you insert a copy of this
-License into the extracted document, and follow this License in all
-other respects regarding verbatim copying of that document.
-
-
-7. AGGREGATION WITH INDEPENDENT WORKS
-
-A compilation of the Document or its derivatives with other separate
-and independent documents or works, in or on a volume of a storage or
-distribution medium, is called an "aggregate" if the copyright
-resulting from the compilation is not used to limit the legal rights
-of the compilation's users beyond what the individual works permit.
-When the Document is included in an aggregate, this License does not
-apply to the other works in the aggregate which are not themselves
-derivative works of the Document.
-
-If the Cover Text requirement of section 3 is applicable to these
-copies of the Document, then if the Document is less than one half of
-the entire aggregate, the Document's Cover Texts may be placed on
-covers that bracket the Document within the aggregate, or the
-electronic equivalent of covers if the Document is in electronic form.
-Otherwise they must appear on printed covers that bracket the whole
-aggregate.
-
-
-8. TRANSLATION
-
-Translation is considered a kind of modification, so you may
-distribute translations of the Document under the terms of section 4.
-Replacing Invariant Sections with translations requires special
-permission from their copyright holders, but you may include
-translations of some or all Invariant Sections in addition to the
-original versions of these Invariant Sections.  You may include a
-translation of this License, and all the license notices in the
-Document, and any Warranty Disclaimers, provided that you also include
-the original English version of this License and the original versions
-of those notices and disclaimers.  In case of a disagreement between
-the translation and the original version of this License or a notice
-or disclaimer, the original version will prevail.
-
-If a section in the Document is Entitled "Acknowledgements",
-"Dedications", or "History", the requirement (section 4) to Preserve
-its Title (section 1) will typically require changing the actual
-title.
-
-
-9. TERMINATION
-
-You may not copy, modify, sublicense, or distribute the Document except
-as expressly provided for under this License.  Any other attempt to
-copy, modify, sublicense or distribute the Document is void, and will
-automatically terminate your rights under this License.  However,
-parties who have received copies, or rights, from you under this
-License will not have their licenses terminated so long as such
-parties remain in full compliance.
-
-
-10. FUTURE REVISIONS OF THIS LICENSE
-
-The Free Software Foundation may publish new, revised versions
-of the GNU Free Documentation License from time to time.  Such new
-versions will be similar in spirit to the present version, but may
-differ in detail to address new problems or concerns.  See
-https://www.gnu.org/copyleft/.
-
-Each version of the License is given a distinguishing version number.
-If the Document specifies that a particular numbered version of this
-License "or any later version" applies to it, you have the option of
-following the terms and conditions either of that specified version or
-of any later version that has been published (not as a draft) by the
-Free Software Foundation.  If the Document does not specify a version
-number of this License, you may choose any version ever published (not
-as a draft) by the Free Software Foundation.
-
-
-ADDENDUM: How to use this License for your documents
-
-To use this License in a document you have written, include a copy of
-the License in the document and put the following copyright and
-license notices just after the title page:
-
-    Copyright (c)  YEAR  YOUR NAME.
-    Permission is granted to copy, distribute and/or modify this document
-    under the terms of the GNU Free Documentation License, Version 1.2
-    or any later version published by the Free Software Foundation;
-    with no 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".
-
-If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
-replace the "with...Texts." line with this:
-
-    with the Invariant Sections being LIST THEIR TITLES, with the
-    Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
-
-If you have Invariant Sections without Cover Texts, or some other
-combination of the three, merge those two alternatives to suit the
-situation.
-
-If your document contains nontrivial examples of program code, we
-recommend releasing these examples in parallel under your choice of
-free software license, such as the GNU General Public License,
-to permit their use in free software.
-
-The End.
-- 
2.20.1