Installing Emacspeak HOWTO

Jennifer Jobst

James Van Zandt

jrv@vanzandt.mv.com
Revision History                                                             
Revision 1.1                    July 23, 2002           Revised by: SDS      
Updated the maintainer of this document to Sharon Snider, corrected links,   
and converted to XML.                                                        
Revision 1.0                    December 4, 2001        Revised by: JEJ      
First release                                                                
Revision 1.0 DRAFT              November 9, 2001        Revised by: JEJ      
DRAFT                                                                        
Revision Emacspeak HOWTO        1996-2001               Revised by: JVZ      
Previously, this document was known as the Emacspeak HOWTO, and was written  
and maintained by Mr. James Van Zandt.                                       


This document contains the installation instructions for the Emacspeak audio
desktop application for Linux.

Please send any comments, or contributions via e-mail to [mailto:
snidersd@us.ibm.com] Sharon Snider. This document will be updated regularly
with new contributions and suggestions.

-----------------------------------------------------------------------------
Table of Contents
1. Legal Notice
2. Introduction
3. Documentation Conventions
4. Requirements
    4.1. Linux Distributions
    4.2. Emacs
    4.3. Background applications
    4.4. Speech Synthesizers
   
   
5. Installing Emacspeak
6. Frequently Asked Questions (FAQs)
7. Additional resources
8. Appendix A: Installing Linux from a DOS machine
    8.1. Requirments
    8.2. Connecting the computers
    8.3. Installation
   
   
9. Appendix B: Installing ViaVoice TTS
    9.1. Downloading ViaVoice
    9.2. Installing ViaVoice RTK
    9.3. Installing ViaVoice SDK
    9.4. Testing the installation
   
   
10. Acknowledgments

1. Legal Notice

This document is Copyright © 2001 IBM. Permission is granted to copy,
distribute and/or modify this document under the terms of the GNU Free
Documentation License, Version 1.1 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 can be found at [http://www.gnu.org/
license/fdl.txt] http://www.gnu.org/license/fdl.txt.
-----------------------------------------------------------------------------

2. Introduction

Emacspeak is a Linux application that allows users to get synthesized speech
output inside the Emacs desktop environment. Because Emacspeak is actually
integrated into the Emacs environment (instead of just running "on top" of an
environment like most screen readers), Emacspeak provides much more
context-specific information than its commercial screen reader counterparts.
In this sense, Emacspeak is not a "screen reader," but rather a subsystem of
Emacs that produces speech output.

Although Emacspeak only works inside Emacs, there are a large number of both
built-in and add-on applications for Emacs that do everything from keeping
track of your appointments to playing CDs to coding HTML. In addition, Emacs
has a special command shell mode that can be used to run any command-line
application.

This HOWTO focuses on installing Emacspeak on your Linux system. It does not
discuss how to actually use Emacs or Emacspeak - for information on usage,
refer to the Emacspeak User's Guide, available at [http://www.tldp.org/
guides.html#espk] http://www.tldp.org/guides.html#espk.
-----------------------------------------------------------------------------

3. Documentation Conventions

As per the LDP Author Guide, this HOWTO uses the following documentation
conventions:

File Names:           file.extension                 
Commands to be typed: command                        
Command prompt:       > (unless otherwise specified) 

-----------------------------------------------------------------------------
4. Requirements

There are a number of things you must have before you install Emacspeak,
including Linux, a Linux-compatible sound card, Emacs, and a hardware or
software speech synthesizer. You should read this section carefully before
installing Emacspeak, because Emacspeak will not function correctly if any of
the requirements are missing.
-----------------------------------------------------------------------------

4.1. Linux Distributions

This HOWTO assumes that you have already installed Linux on your system. If
not, you may wish to refer to the "Linux Information Sheet" by Michael K.
Johnson a [http://www.linuxdoc.org/HOWTO/INFO-SHEET.html] http://
www.linuxdoc.org/HOWTO/INFO-SHEET.html. It provides an introduction to Linux,
discusses some hardware requirements, and also has a section on how to obtain
Linux.

There are a number of different Linux distributions (distros) that you can
choose from. All of the distros are based upon the same basic Linux code, or
kernel, but each distro has a different installation process, features, and
support options. Martin Wheeler's "Distributions HOWTO," at [http://
www.linuxdoc.org/HOWTO/Distributions-HOWTO/index.html] http://
www.linuxdoc.org/HOWTO/Distributions-HOWTO/index.html, discusses the pros and
cons of a number of Linux distros. You can also find information about each
distribution on their respective web sites. Those distros known to support
Emacspeak are listed below with their URLs:

  * Debian Linux - [http://www.debian.org] http://www.debian.org
   
  * Mandrake Linux - [http://www.mandrakelinux.com/en/] http://
    www.mandrakelinux.com/en/
   
  * Red Hat Linux - [http://www.redhat.com] http://www.redhat.com
   
  * Slackware Linux - [http://www.slackware.com] http://www.slackware.com
   
  * SuSE Linux - [http://www.suse.com] http://www.suse.com
   
  * TurboLinux - [http://www.turbolinux.com] http://www.turbolinux.com
   

All of the distributions listed above can be downloaded free of charge from
their respective web sites. However, the downloads are quite large, so you'll
need a fast Internet connection. You will also need access to a CD burner, to
burn your own CDs from the images you download. Depending on the
distribution, you may also have to download and make a boot floppy. Once you
have burned the CDs and created the boot floppy, you can install Linux.
Alternatively, you can purchase the disks at your local computer store for
between $30 and $80 US. Both of these options are discussed at length in the
Linux Installation HOWTO at [http://www.linuxdoc.org/HOWTO/Installation-HOWTO
/overview.html] http://www.linuxdoc.org/HOWTO/Installation-HOWTO/
overview.html, so you may want to refer there before making a decision as to
which route to take.

Most methods of installation require sighted assistance. However, if you
prefer to install Linux yourself, there are two options. The first is to
install Linux from a DOS machine running JAWS. This option requires two
machines, a null modem cable, JAWS for DOS, and a hardware speech
synthesizer. More information on this option can be found in, Appendix A. The
second option is installing one of the distributions that includes a Speakup
kernel patch. This option requires a Speakup-enabled distro and a hardware
synthesizer. Speakup is a screen reader that is patched into the kernel, so
it starts talking at boot and will speak during the entire installation.
Currently, Speakup is supported on Debian, Red Hat 7.1, and Slackware. The
Speakup option also requires you to download the CD images and make your own
CDs. Refer to the Speakup home page at [http://www.linux-speakup.org] http://
www.linux-speakup.org for instructions for this option.

For assistance with installing Linux, Eric Raymond's Linux Installation
HOWTO, at [http://www.linuxdoc.org/HOWTO/Installation-HOWTO] http://
www.linuxdoc.org/HOWTO/Installation-HOWTO, is highly recommended reading. In
the HOWTO, Eric discusses hardware requirements, choosing a distro, and
installing your distro of choice. If Eric's HOWTO does not provide enough
installation-specific information, you can refer to the documentation
specific to your distribution, available at the URLs given in the distro
list.
-----------------------------------------------------------------------------

4.2. Emacs

Because Emacspeak is an Emacs subsystem, you must have Emacs installed for
Emacspeak to work. Most distributions include Emacs by default, so it should
be installed on your system when you install Linux.

If you do not have Emacs on your system or you want to check on the latest
version of Emacs, refer to the Emacs homepage at [http://www.gnu.org/software
/emacs/emacs.html] http://www.gnu.org/software/emacs/emacs.html. If you
install Emacs on your own or choose to upgrade, be sure to install all of
Emacs, including both the X and non-X versions (even if you do not plan to
use X). Some Emacs applications depend on packages included in the X version,
even if you use those applications in the non-X version of Emacs.

If you would like to learn more about Emacs and how to use it, an excellent
place to start is the Emacs Beginner's HOWTO, by Jeremy D. Zawondy. It's
available at [http://www.linuxdoc.org/HOWTO/Emacs-Beginner-HOWTO.html] http:/
/www.linuxdoc.org/HOWTO/Emacs-Beginner-HOWTO.html. There is also an online
manual available at [http://www.gnu.org/manual/emacs/index.html] http://
www.gnu.org/manual/emacs/index.html. Alternatively, you can try the built-in
Emacs tutorial. To start the tutorial, type C-h t.
-----------------------------------------------------------------------------

4.3. Background applications

Emacspeak depends on a number of applications. Because each Linux
distribution comes with different applications, you may find that your distro
does not quite have everything that Emacspeak needs to run properly.
Therefore, before you install anything else, it is important to make sure you
have all the necessary applications, as listed below.

  * Tk, Tcl, and Tclx: Check to make sure you have these applications. If
    not, download and install the following rpms from [http://
    www.rpmfind.net] http://www.rpmfind.net: tcl-8.3.2-7mdk, tk-8.3.2-7mdk,
    and tclx-8.3.2-7mdk.
   
  * Lesstif: If you want to run the Graphical User Interface (GUI) versions
    of the ViaVoice sample programs, you'll need these packages. For
    Emacspeak, the Lesstif packages are only useful if you're running
    Xwindows, or if you want to use the GUI tools.
   
    Lesstif can be downloaded from either the Lesstif home page [http://
    www.lesstif.org] http://www.lesstif.org or Sourceforge [http://
    sourceforge.net/projects/lesstif] http://sourceforge.net/projects/
    lesstif. Currently, the latest release of Lesstif is version 0.93.14;
    however, Marty Moore recommends using the 0.92.32 version. You can either
    download the gzipped tarball that contains all the necessary files or
    download the three individual packages (lesstif-mwm-0.92.32-1.i386.rpm,
    lesstif-clients-0.92.32-1.i386.rpm, and
    lesstif-devel-0.92.32-1.i386.rpm). If you choose to use the three
    individual files, be sure to use the --nodeps option when you unpack the
    RPMs to avoid dependancy errors.
   
  * sndconfig: You will need to run this application from the command line to
    configure your sound card. At the command prompt, type sndconfig and
    follow the instructions.
   
    If your sound card is not recognized by sndconfig, refer to, 
    Troubleshooting, for more information.
   
  * stdiom: This package is only necessary if you are using ViaVoice as your
    synthesizer, or if you want to use auditory icons, and your sound card is
    not a multi-channel card.
   
    For information on auditory icons, refer to the [http://www.tldp.org/
    guides.html#espk] Emacspeak User's Guide.
   

-----------------------------------------------------------------------------
4.4. Speech Synthesizers

 To produce speech output, you need two things: something to parse the
information on the screen (Emacspeak), and something to produce the sounds
you hear as output (a speech synthesizer). Emacspeak can use either a
hardware or software synthesizer to produce sound output. Software
synthesizers have the benefit of being either free or very inexpensive.
Hardware synthesizers can run from $150 to $1600 or more, but they are
typically easier to install than software synthesizers.
-----------------------------------------------------------------------------

4.4.1. Hardware synthesizers

Emacspeak supports the following hardware synthesizers:

  * Accent
   
  * Apollo
   
  * Braille Lite
   
  * Braille n' Speak
   
  * DECtalk Express (the original Emacspeak synthesizer) or MultiVoice
   
  * DoubleTalk PC and AT
   
  * Internal DECtalk PC and DECtalk PC2
   
  * LiteTalk
   
  * Type n' Speak
   

Support for the DECtalk Express and MultiVoice synthesizers is built into
Emacspeak. If you have a synthesizer other than a DECtalk Express, you may
require additional drivers or "speech servers" to get Emacspeak to work with
your synthesizer.

The Internal DECtalk PC and DECtalk PC2 require a kernel driver available
from [ftp://leb.net/pub/blinux/dectalk_pc-0.95.tgz] ftp://leb.net/pub/blinux/
dectalk_pc-0.95.tgz. Installation instructions are at [ftp://leb.net/pub/
blinux/dectalk_pc-0.95.README] ftp://leb.net/pub/blinux/
dectalk_pc-0.95.README.

The DoubleTalk PC and AT, Braille n' Speak, Type n' Speak, Braille Lite,
Apollo, and Accent synthesizers all require an additional speech server that
can be downloaded from [http://leb.net/pub/blinux/emacspeak/blinux/
emacspeak-ss-1.7-1.i386.rpm] http://leb.net/pub/blinux/emacspeak/blinux/
emacspeak-ss-1.7-1.i386.rpm. A README file with installation instructions can
be found at [ftp://leb.net/pub/blinux/emacspeak/blinux/emacspeak-ss.README]
ftp://leb.net/pub/blinux/emacspeak/blinux/emacspeak-ss.README.
-----------------------------------------------------------------------------

4.4.2. Software synthesizers

If you choose to use a software synthesizer, you must make sure your sound
card is Linux compatible. In addition, if you want to perform any tasks that
require a multi-channel sound card, such as playing auditory cues when you
open or close an Emacs buffer, you must make sure that your sound card is
multi-channel capable.

There is a complete list of Linux-compatible sound cards available at [http:/
/www.alsa-project.org] http://www.alsa-project.org. In addition, you can
usually find information on your distribution's web site about which sound
cards are supported with each distro.

Once you have ensured that your sound card is Linux compatible, you can
install a software synthesizer. Currently the only one that works with
Emacspeak is IBM's ViaVoice Text-to-Speech (TTS), formerly called ViaVoice
Outloud. Many Emacspeak users use this software synthesizer, because it is
free of charge. Instructions for installing ViaVoice can be found in, 
Appendix B.
-----------------------------------------------------------------------------

5. Installing Emacspeak

Assuming that you have all the items listed in, Requirements, you are ready
to install Emacspeak. The following steps provide the instructions to do so.

 1. Go to the Emacspeak site at [http://emacspeak.sourceforge.net] http://
    emacspeak.sourceforge.net and, from the Support and Documentation
    section, select an Emacspeak file to download. If you select the binary
    file, emacspeak.tar.gz, you will need to configure and make Emacspeak. If
    you have some experience with Linux, or if you're using a distribution
    that does not support RPMs, you should download this option. If your
    distro supports RPMs, you can download the ready-to-install version of
    Emacspeak (emacspeak-14.0-1.noarch.rpm).
   
 2. Download the file and place it in your home directory.
   
 3. Type su root and provide the root password if you are not already logged
    onto your machine as root. You'll need root permissions to install
    Emacspeak.
   
 4. If you downloaded the rpm version of Emacspeak, unpack it using the
    command rpm -i emacspeak-14.0-1.noarch.rpm. If you downloaded the binary
    version, unzip and untar the file, then follow the installation
    directions in the README file in the resulting emacspeak-14.0 directory.
   
    Once you have installed the rpm, you'll see a message saying that
    Emacspeak installed successfully, as well as some additional
    instructions.
   
 5. If you are using Emacspeak v.14 or earlier and also using ViaVoice TTS as
    your synthesizer, change directories to the /usr/share/emacs/site-lisp/
    emacspeak/servers/linux-outloud directory and type the command make. This
    command compiles the ViaVoice TTS server. If you are not using ViaVoice,
    or if you have Emacspeak v.15 or later, you do not need to complete this
    step.
   
 6. Using the cd command, change directories to the /etc directory and open
    your profile file with your favorite text editor (you must be root to
    edit the profile). Scroll to the bottom of the file, then add the
    following two lines:
    export DTK_PROGRAM DTK_PROGRAM=name of your speech server                
   
    The value of DTK_PROGRAM must be the name of your speech server. A list
    of standard Emacspeak-supported speech synthesizers and the names of
    their respective speech servers is below.
   
    ViaVoice TTS        Outloud
    DecTalk Xpress      dtk-exp
    DecTalk MultiVoice  dtk-mv 
   
    Several additional synthesizers are supported, but they require add-on
    speech servers. Refer to the documentation for each specific speech
    server for more information.
   
 7. Save your profile file and close it.
   

Now, you should have installed and configured everything required to run
Emacspeak. To use Emacspeak, log on to your system as someone other than root
(you should never run Emacspeak as root), and type emacspeak at the prompt.
Emacspeak should start talking immediately.
-----------------------------------------------------------------------------

6. Frequently Asked Questions (FAQs)

This sections covers some of the more common problems encountered when
installing Emacspeak. If there is a topic that is not covered here, you
should review the Emacspeak mailing list archives at [http://
www.cs.vassar.edu/~priestdo/emacspeak/] http://www.cs.vassar.edu/~priestdo/
emacspeak/. You can find the answers to many additional questions there.

The volume on my system is very low - how can I increase it?
    The easiest way to turn up system volume is with a set of speakers.
    However, sometimes speakers aren't feasible (for example, with a laptop),
    or even with speakers, the volume is still not loud enough. In this case,
    you can use the application aumix to increase your system's volume.
   
    Aumix comes with many distributions of Linux, but if your distro doesn't
    have aumix, you can download it from [http://prdownloads.sourceforge.net/
    aumix/aumix-2.7.tar.gz] http://prdownloads.sourceforge.net/aumix/
    aumix-2.7.tar.gz. The latest version is 2.7.
   
    To use aumix to increase your system's volume, type the command aumix -v
    +100 or aumix -w +100. The numerical value is the percentage volume, so
    in this case 100 means 100%. You may want to try different settings to
    find the most comfortable one for you.
   
    For more information on using aumix, type aumix -h at the command prompt.
   
sndconfig doesn't recognize my soundcard. What should I do?
    If sndconfig doesn't recognize your soundcard, you should see if you can
    download a driver for your card. The Advanced Linux Sound Architecture
    (ALSA) Web site, located at [http://www.alsa-project.org] http://
    www.alsa-project.org, lists many sound cards, along with their drivers
    (if available). Another alternative is the Open Sound System (OSS) for
    Linux. OSS is a commercial implementation of the Linux kernel drivers,
    and a list of supported cards can be found at [http://www.4front-tech.com
    /osshw.html] http://www.4front-tech.com/osshw.html. There used to be a
    free version, but apparently it is no longer available (if anyone knows
    differently, please let me know).
   
    Note Note                                                                
         Some users have reported compatibility problems with ViaVoice and   
         ALSA drivers. I have been unable to determine the exact problem or  
         solution from various mailing archives, so if anyone can provide    
         more information on this issue, please let me know.                 
   
When I try to install the ViaVoice RTK rpm file, I get the error "libXm.so.1
    is missing." What's wrong?
    The file libXm.so.1 is part of the lesstif distribution, and it is also a
    shared library. This error message indicates that either lesstif is not
    installed, or that the system is unable to locate the file. Often shared
    libraries are referenced by a symbolic link to the real shared library
    file, which may be named something like libXm.so.1.0.17. When the name of
    the symbolic link to the shared library and the name of the real shared
    library file differ, the system may not be able to find the shared
    library, even if it exists. If another program depends on a shared
    library that cannot be found, an error message like the one above
    results. In the case of libXm.so.1, lesstif is only needed for graphical
    demonstration programs. Thus, if you do not plan to use the graphical
    mode, it is safe to install the ViaVoice RTK rpm using the option 
    --nodeps, which tells ViaVoice to ignore any missing dependencies.
   
    Note Note                                                                
         Note that this is only a workaround, not a "fix," and that it only  
         works for ViaVoice Text-to-speech (TTS). This solution may not work 
         if you use any of the ViaVoice voice recognition software.          
   
When I compile the ViaVoice TTS server for Emacspeak, I get an error
    "tcleci.cpp:43:17: eci.h: No such file or directory." Where is eci.h?
    This error message appears when you install the ViaVoice RTK and SDK in
    the wrong order, or if the SDK is not installed.
   
    The file eci.h should be in the /usr/include directory. If it is not
    there, re-install ViaVoice TTS, RTK, then install ViaVoice TTS SDK. Check
    to make sure eci.h is in the /usr/include directory, then change
    directories to /usr/share/emacs/site-lisp/emacspeak/servers/
    linux-outloud, and type make at the command prompt. The ViaVoice TTS
    should now make successfully.
   
When I start Emacspeak, I keep getting the error "process speaker not
    running." What's wrong?
    If you are getting this error message, there are several possible causes.
    This section steps though finding and correcting this problem.
   
    The first step is to make sure that you have tcl correctly installed, as
    explained in the following instructions.
   
     1. First, make sure you are in the /usr/share/emacs/site-lisp/emacspeak/
        servers directory.
       
     2. At the command prompt, type tcl name of speech server. The most
        common speech servers are dtk-exp and outloud.
       
   
    If you get an error such as bash: tcl:: command not found, it means that
    tcl/tclx is not correctly installed on your system. You must get the
    latest version of either tcl or tclx and install it before Emacspeak will
    work.
   
    If everything is installed correctly, you should hear a voice saying "IBM
    ViaVoice. This is Emacspeak" or something similar. A % command prompt
    should also appear. At the prompt, type q "this is a test." Then press 
    Return and type d. This command runs the speech, so you should hear "this
    is a test" spoken. If you hear this, the server script is running
    properly. You can type exit to quit tcl.
   
    You may also get an error like stdiosynth executable not found when you
    type tclname of speech server, and then get a command prompt. Testing has
    shown that this error can appear even when stdiosynth is correctly
    installed and Emacspeak is working. Even if you get this error message,
    you should still get the % command prompt, so you should be able to test
    the script.
   
    If the script test was unsuccessful, (if tcl was found and you got a %
    prompt but you did not hear any speech), the next step is to make sure
    that you have the correct lines in your profile file to let Emacspeak
    know where to find the speech server. To check this, follow these steps:
   
     1. Go to your /etc directory, then use you favorite text editor to open
        the file namedprofile.
       
     2. Make sure the following lines are in the file:
         export DTK_PROGRAM DTK_PROGRAM=name of speech server                
       
        The most common speech servers, are outloud and dtk-exp.
       
   
    If these lines are not in your profile file, add them and then re-test
    tcl. If you are using ViaVoice TTS as your synthesizer, Emacspeak should
    work correctly at this point. If you are using a hardware synthesizer and
    you still do not get any sound, check to make sure that the environment
    variable DTK_PORT is set correctly in your /etc/profile file.
   
    The variable DTK_PORT specifies which port your hardware synthesizer is
    plugged into on your computer. Under Linux, if your synthesizer is
    plugged into com1, you must set DTK_PORT to/dev/ttyS0, and if it is in
    com2, then DTK_PORT should be set to /dev/ttyS1. To set this variable,
    follow these steps:
   
     1. Open your profile file located in the /etc directory.
       
     2. Look for the variable DTK_PORT. If this variable does not exist,
        scroll to the bottom of the profile and add the following line:
        export DTK_PORT=/dev/ttySX                                           
       
        In this line, the "X" should be replaced by the correct port number,
        as described above.
       
     3. When you are finished, save and close the profile file.
       
   
    Finally, retest tcl, and if it works, restart Emacspeak. Emacspeak should
    work correctly.
   
    If you have a hardware synthesizer and are still not getting any speech,
    you probably do not have the necessary permissions to use the serial port
    for your synthesizer. There are a number of solutions to this problem,
    and the best solution depends on your operating environment. For example,
    if you are in a multi-user environment, controlling the access
    permissions to the serial device may be a concern. The options are as
    follows:
   
      + Change the ownership of the serail device to the user running
        Emacspeak. To do this, type chown username /dev/ttyS0 at the command
        prompt then type chmode u+rw dev/ttyS0.
       
      + Add the user to the group associated with the serial device. On Red
        Hat systems this is usually the grouptty. To do this edit the /etc/
        group file and find the line starting with tty:. At the end of that
        line, add ",username" where username is your username.
       
      + Give read/write access to the serial device for all users. This is
        the least secure solution, but if you are the only user on the
        system, it will not matter. To give read/write access, make sure you
        are the root user and at the command prompt type chmod o+rw /dev/
        ttyS0.
       
   

-----------------------------------------------------------------------------
7. Additional resources

Once Emacspeak has been successfully installed, you should become familiar
with the Emacspeak commands and the many applications you can run with Emacs.
Although this HOWTO does not cover this information, there are a number of
excellent tutorials that are available for new users of both Emacs and
Emacspeak. The following list provides a starting point:

  * "A gentle introduction to Emacspeak," by Gary Lawrence Murphy, [http://
    emacspeak-guide.sourceforge.net/tutorial.html/] http://
    emacspeak-guide.sourceforge.net/tutorial.html/. Gary provides a
    lighthearted but thorough introduction to Emacs and Emacspeak, focusing
    on users who are not familiar with either application. This introduction
    is recommend as a starting point, even before you do the Emacs tutorial
    (see next item).
   
  * "The (Official) Emacs Tutorial," by the Free Software Foundation. I call
    this the "official" tutorial because it is included with Emacs. To access
    this tutorial, start Emacspeak, then type C-h t. This tutorial discusses
    the basic Emacs commands, including navigation using Emacs as a text
    editor, and a bit about how Emacs works "under the hood." For new users
    this tutorial is strongly recommended, and even those users who are
    familiar with Emacs might find something new.
   
  * "Emacspeak Tutorial," by Nita Van Zandt, available at [http://www.mv.com/
    ipusers/vanzandt/emacspeak-tutorial-1.0.tar.gz] http://www.mv.com/ipusers
    /vanzandt/emacspeak-tutorial-1.0.tar.gz. This tutorial helps new
    Emacspeak users get up and running and includes plenty of examples and
    step-by-step instructions. Once you have a grasp of Emacs, this tutorial
    is a must.
   
  * "The Emacs Beginner's HOWTO," by Jeremy D. Zawodny. It is available at
    [http://www.linuxdoc.org/HOWTO/Emacs-Beginner-HOWTO.html] http://
    www.linuxdoc.org/HOWTO/Emacs-Beginner-HOWTO.html and discusses many of
    the topics discussed in the Emacs tutorial. However, it also includes
    overviews of some of the more popular Emacs packages, including VM, Gnus,
    BBDB, and AucTeX.
   
  * "Using Emacspeak HOWTO," by Jennifer Jobst, available at [http://
    emacspeak.sourceforge.net] http://emacspeak.sourceforge.net. This HOWTO
    is a task-based guide on getting the most out of Emacs and Emacspeak.
    From browsing the Internet to coding to playing games, this HOWTO tells
    you where to get the best Emacs applications for each task and how to use
    them.
   

-----------------------------------------------------------------------------
8. Appendix A: Installing Linux from a DOS machine

In the original Emacspeak HOWTO, James Van Zandt provided instructions on how
to install Linux from a DOS machine using a null-modem cable. As with the
other instructions in this HOWTO, I tried, unfortunately without success, to
duplicate this procedure. However, I have provided the information gathered
during testing in the following section. If you successfully install Linux
from a Windows?? or DOS?? machine over a null-modem cable, please let me know
the procedure you followed and I'll include it here.

Please note that the original instructions for installing Linux over a null
modem cable were written for a DOS machine. I first attempted to reproduce
these instructions with my Windows 2000 machine (from the DOS prompt) and Red
Hat 7.1. Although I successfully downloaded and installed JAWS for DOS
(available from Freedom Scientific at [http://www.freedomscientific.com/
fs_downloads/morejaws.asp] http://www.freedomscientific.com/fs_downloads/
morejaws.asp), I was unable to get a DOS VT100 terminal emulator installed. I
tried using TELIX, which was popular several years ago, but when I tried to
install TELIX version 3.51, I got a runtime error. Since I was unable to find
any other DOS terminal emulators, I decided to try using a Windows
screenreader and terminal emulator instead. This section documents the
procedure I tried with the Windows machine.
-----------------------------------------------------------------------------

8.1. Requirments

For this process, you will need a machine with a working speech synthesizer
and a terminal emulator program. For my test, I used a Windows 2000 machine
and tried both Narrarator (which comes with Windows 2000) and JAWS for
Windows v.3.5. For the terminal emulator, I used tried both Hyperterminal
(which comes with Windows) and CRT (which can be downloaded from [http://
www.vandyke.com/products/crt] http://www.vandyke.com/products/crt). You will
also need a second machine (on which to install Linux), a null modem cable,
and a copy of your preferred Linux distribution on either floppy disk or
CD-ROM.
-----------------------------------------------------------------------------

8.2. Connecting the computers

To connect the two computers, you need a "null modem" cable. A "null modem"
cable is a serial cable that connects ground to ground and transmits on each
end to receive on the other. The cable that comes with the DOS application
LapLink will work fine. The LapLink cable is particularly handy because it
has both a 9 pin and a 25 pin connector on each end. Alternatively, you may
be able to find a null modem cable at your local computer store, or you can
have one made. If you choose to have one made, here are the required
connections:

  * For two 9 pin connectors, connect pin 2 (receive data) to pin 3, pin 3
    (transmit data) to pin 2, and pin 5 (signal ground) to pin 5.
   
  * For two 25 pin connectors, connect pin 2 (receive data) to pin 3, pin 3
    (transmit data) to pin 2, and pin 7 (signal ground) to pin 7.
   
  * For a 9 pin connector (first) to a 25 pin connector (second), connect pin
    2 (receive data) to pin 2 (transmit data), pin 3 (transmit data) to pin 3
    (receive data), and pin 5 (signal ground) to pin 7 (signal ground).
   

Once you have your null modem cable, you'll need to connect the two machines
while both of them are off. It's easiest to use COM1 on both machines. Once
you've got them connected, you're ready to start them up, as discussed in the
next section
-----------------------------------------------------------------------------

8.3. Installation

Once your machines are connected via the null modem cable, boot the DOS/
Windows machine, then start the terminal emulation program. For my test, I
tried both Hyperterminal (which comes with Windows 2000) and CRT (which can
be downloaded from [http://www.vandyke.com/products/crt] http://
www.vandyke.com/products/crt. For some reason, the arrow keys did not work in
HyperTerminal, making navigation within the HyperTerminal window impossible.
However, the arrow keys (as well as Tab and Return) do work in CRT, so I
recommend using CRT as your terminal emulator.

Set the terminal emulator for 9600 baud, no parity, eight data bits, 1 stop
bit. If "Flow control" is an option, select Hardware. Also be sure to set
your terminal emulation mode to VT100. Start the terminal emulator connection
(you won't get any data at this point, as your Linux machine should still be
off).

Once you've set up the terminal emulator on your DOS/Windows machine, insert
the "boot" floppy or CD into your Linux machine and boot the machine. With
Red Hat, at the boot: prompt, I typed in the command linux text console=ttyS0
. Note that the "s" in "ttyS0" is capitalized, and that's a "zero" at the end
of the string, not a capital letter "o." Other distributions may require
other strings, so if you know the syntax required for distros other than Red
Hat, please let me know and I will include that information here.

Once you've typed in this string at the boot: prompt and hit Return, you
should get output in your terminal emulator program on your DOS/Windows
machine. Unfortunately, at this point I discovered that neither JAWS for
Windows nor Narrarator produces speech output in either the HyperTerminal or
CRT terminal windows. This ultimately stymied my attempts to install Linux
over a null modem cable.
-----------------------------------------------------------------------------

9. Appendix B: Installing ViaVoice TTS

This section steps through the installation of ViaVoice TTS, which can be
used as a software synthesizer with Emacspeak.
-----------------------------------------------------------------------------

9.1. Downloading ViaVoice

First, you must download the ViaVoice Software Development Kit (SDK) and the
Run Time Kit (RTK), as described in the following steps.

 1. Go to IBM's ViaVoice TTS website a [http://www-4.ibm.com/software/speech/
    dev/ttssdk_linux.html] http://www-4.ibm.com/software/speech/dev/
    ttssdk_linux.html.
   
 2. Scroll down to the Downloads section, and click on the Downloads link.
    You will be asked to provide a username and password before you download
    anything.
   
 3. Download the following files:
   
      + ViaVoice TTS SDK for Linux V5.1. The filename is
        viavoice_tts_sdk_5.tar.
       
      + ViaVoice TTS Run Time Kit for Linux V5.1. The filename is
        viavoice_tts_rtk_5.tar.
       
   

-----------------------------------------------------------------------------
9.2. Installing ViaVoice RTK

Now that you have downloaded the ViaVoice files, you can install them. You
must install the RTK first, as it contains libraries required by the SDK.

 1. Type the su root command and provide the root password to log on to your
    system as root.
   
 2. Type the cd command to change to the directory that contains the files
    you just downloaded.
   
 3. Untar the RTK using the command tar -xvf viavoice_tts_rtk_5.tar. You
    should now have two files in your directory, ttsrt_readme.txt and
    ViaVoice_TTS_rtk_5.1-1.2.i386.rpm.
   
 4. Unpack the rpm using the command rpm -i ViaVoice_TTS_rtk_5.1-1.2.i386.rpm
    . You will be given a license agreement to read. You can press the
    spacebar to scroll through the document. When you've read the document,
    you'll be returned to the command prompt.
   
 5. Type the command source /etc/profile to finish installing the RTK.
   

-----------------------------------------------------------------------------
9.3. Installing ViaVoice SDK

Now that you have installed the RTK, you can install the SDK as well using
the following steps:

 1. Change directories to the directory that contains the SDK file you
    downloaded.
   
 2. Untar the SDK file using the command tar -xvf viavoice_tts_sdk_5.tar. You
    should now have two files in your directory, ttssd.readme.txt and
    ViaVoice_TTS_sdk-5.1-1.2.i386.rpm.
   
 3. Unpack the rpm using the command rpm-i --nodeps
    ViaVoice_TTS_sdk-5.1-1.2.i386.rpm. You will be given a license agreement
    to read. You can press the spacebar to scroll through the agreement. When
    you've read the document, you'll be returned to the command prompt.
   

-----------------------------------------------------------------------------
9.4. Testing the installation

Now that you have installed both the ViaVoice RTK and SDK, you must test to
make sure that they are working correctly. You can perform two tests using
the following steps:

 1. Type the cd command to change to the /usr/lib/ViaVoiceTTS/samples/
    cmdlinespeak/ directory.
   
 2. Type the command ./runcmdlinespeak at the prompt. You should hear your
    computer say "Hello, welcome to ViaVoice Outloud for Linux." Normal
    system volume is often very low, so you may not be able to hear it very
    well. Refer to, Troubleshooting, for information on how to increase your
    system volume.
   

If for some reason your test was not successful, refer to the installation
notes provided with both the RTK (ttsrt.readme.txt) and the SDK
(ttssd.readme.txt) for debugging information.
-----------------------------------------------------------------------------

10. Acknowledgments

As with any effort for the Linux project, there are a number of people who
contributed to this HOWTO in a roundabout way. Without their help, this
document would not exist.

Mr. James Van Zandt, the original author of the Emacspeak HOWTO. He
graciously allowed me maintainership of the original HOWTO, which has been
reworked into this document, "The Emacspeak Installation HOWTO."

Dr. T.V. Raman, who always answered my Emacspeak questions, no matter how
odd.

Marty Moore, who provided a list of instructions for installing Emacspeak and
ViaVoice under Mandrake. Many of Marty's instructions were used to make this
document more complete.

Tim Cross also deserves recognition, as he clarified several points in
Marty's instructions, and some of Tim's comments are also used in this
document. Tim also provided excellent explanations for the libXm.so.1 error
message, as well as the "process speaker not running" error message.

All the folks on the Emacspeak and blinux mailing lists who contributed
suggestions, answered my questions, and gently showed me the errors in my
ways.

Throughout this document, I have tried to give credit to other authors when
referring to their work. If I missed a citation, please let me know and I
will be sure to correct it. If you did the work, you certainly deserve the
credit!
