<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<article>
	<articleinfo>
		<title>Installing Emacspeak HOWTO</title>
		
		<authorgroup>
		<author>
			<firstname>Jennifer</firstname>
			<surname>Jobst</surname>
			<affiliation>
				<address><email>jobst@us.ibm.com</email></address>
			</affiliation>
		</author>

		<author>
			<firstname>James</firstname>
			<surname>Van Zandt</surname>
			<affiliation>
				<address><email>jrv@vanzandt.mv.com</email></address>
			</affiliation>
		</author>
		</authorgroup>

		<abstract>
			<para>
			This document contains the installation
			instructions for the Emacspeak audio desktop
			application for Linux.
			</para>
		</abstract>
		<pubdate>December 4, 2001</pubdate>
		<revhistory>

			<revision>
				<revnumber>1.0</revnumber>
				<date>December 4, 2001</date>
				<authorinitials>JEJ</authorinitials>
				<revremark>First release</revremark>
			</revision>

			<revision>
				<revnumber>1.0 DRAFT</revnumber>
				<date>November 9, 2001</date>
				<authorinitials>JEJ</authorinitials>
				<revremark>DRAFT</revremark>
			</revision>

			<revision>
				<revnumber>Emacspeak HOWTO</revnumber>
				<date>1996-2001</date>
				<authorinitials>JVZ</authorinitials>
				<revremark>Previously, this document was
				known as the Emacspeak HOWTO, and was
				written and maintained by Mr. James
				Van Zandt.</revremark>
			</revision> 
				
		</revhistory>
	</articleinfo>

<sect1 id="legal-notice">
<title>Legal Notice</title>

	<para>
	This document is Copyright &copy; 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 <ulink url="http://www.gnu.org/license/fdl.txt"></ulink>.
	</para>
</sect1>

<sect1 id="introduction">
<title>Introduction</title>

	<para>	
	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.
	</para>
   
	<para>
	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. 
	</para>

	<para>
	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 <ulink url="http://emacspeak.sourceforge.net"></ulink>.
	</para>
</sect1>

<sect1 ID="documentation-conventions">
<title>Documentation Conventions</title>

	<para>
	As per the LDP Author Guide, this HOWTO uses the following
	documentation conventions:
	</para>	

	<simplelist type=horiz columns=2>
		
		<member>File Names:</member>
		<member><filename>file.extension</filename></member>

		<member>Commands to be typed:</member>
		<member><command>command</command></member>

		<member>Command prompt:</member>
		<member><prompt>></prompt> (unless otherwise specified)</member>

	</simplelist>
</sect1>

<sect1 ID="requirements">
<title>Requirements</title>

	<para>
	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.
	</para>

<sect2 ID="linux-distros">
<title>Linux Distributions</title>

	<para>
	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 at <ulink
	url="http://www.linuxdoc.org/HOWTO/INFO-SHEET.html"></ulink>.
	It provides an introduction to Linux,
	discusses some hardware requirements, and also has a section on
	how to obtain Linux.
	</para>

	<para>
	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 <ulink
	url="http://www.linuxdoc.org/HOWTO/Distributions-HOWTO/index.html"></ulink>,
	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:
	</para>
	
	<itemizedlist mark=bullet>
		<listitem>
			<para>
			Debian Linux - <ulink url="http://www.debian.org"></ulink>
			</para>
		</listitem>

		<listitem>
			<para>
			Mandrake Linux - <ulink url="http://www.linux_mandrake.com"></ulink>
			</para>
		</listitem>

		<listitem>
			<para>
			Red Hat Linux - <ulink url="http://www.redhat.com"></ulink>
			</para>
		</listitem>

		<listitem>
			<para>
			Slackware Linux - <ulink url="http://www.slackware.com"></ulink>
			</para>
		</listitem>

		<listitem>
			<para>
			SuSE Linux - <ulink url="http://www.suse.com"></ulink>
			</para>
		</listitem>

		<listitem>
			<para>
			TurboLinux - <ulink url="http://www.turbolinux.com"></ulink>
			</para>
		</listitem>
	</itemizedlist>

	<para>
	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 <ulink
	url="http://www.linuxdoc.org/HOWTO/Installation-HOWTO/overview.html"></ulink>,
	so you may want to refer there before making a decision as to
	which route to take.
	</para>

	<para>
	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 <xref linkend="appendixa">, 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 <ulink url="http://www.linux-speakup.org"></ulink> for
	instructions for this option.
	</para>
 
	<para>
	For assistance with installing Linux, Eric Raymond's Linux
	Installation HOWTO, at <ulink
	url="http://www.linuxdoc.org/HOWTO/Installation-HOWTO"></ulink>,
	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. 
	</para>
</sect2>

<sect2 ID="emacs">
<title>Emacs</title>

	<para>
	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. 
	</para>

	<para>
	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 <ulink
	url="http://www.gnu.org/software/emacs/emacs.html"></ulink>.
	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.
	</para>

	<para>
	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 <ulink
	url="http://www.linuxdoc.org/HOWTO/Emacs-Beginner-HOWTO.html"></ulink>.
	There is also an online manual available at <ulink
	url="http://www.gnu.org/manual/emacs/index.html"></ulink>.
	Alternatively, you can try the built-in Emacs tutorial. To
	start the tutorial, type <command>C-h t</command>.
	</para>
</sect2>

<sect2 id="applications">
<title>Background applications</title>

	<para>
	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.
	</para>

	<itemizedlist mark=bullet>
		<listitem>
			<para>
			<command>Tk, Tcl,</command> and <command>Tclx</command>: Check
			to make sure you have these applications.  If
			not, download and install the following
			rpms from <ulink
			url="http://www.rpmfind.net"></ulink>:
			<filename>tcl-8.3.2-7mdk</filename>,
			<filename>tk-8.3.2-7mdk</filename>, and
			<filename>tclx-8.3.2-7mdk</filename>.
			</para>
		</listitem>

		<listitem>
			<para>
			<command>Lesstif</command>: 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.
			</para>

			<para>
			Lesstif can be downloaded from
			either the Lesstif home page <ulink
			url="http://www.lesstif.org"></ulink> or Sourceforge
			<ulink
			url="http://sourceforge.net/projects/lesstif"></ulink>.
			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 (<filename>lesstif-mwm-0.92.32-1.i386.rpm</filename>,
			<filename>lesstif-clients-0.92.32-1.i386.rpm</filename>,
			and
			<filename>lesstif-devel-0.92.32-1.i386.rpm</filename>).
			If you choose to use the three individual
			files, be sure to
			use the <command>--nodeps</command> option when you unpack the
			RPMs to avoid dependancy errors.
			</para>
		</listitem>

		<listitem>
			<para>
			<command>sndconfig</command>: You will need to
			run this application from the command line to
			configure your sound card.  At the command
			prompt, type <command>sndconfig</command> and
			follow the instructions.
			</para>

			<para>
			If your sound card is not
			recognized by sndconfig, refer to <xref
			linkend=troubleshooting>, Troubleshooting, for
			more information.
			</para>
		</listitem>
		
		<listitem>
			<para>
			<command>stdiom</command>: 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.
			</para>

			<para>
			For information on auditory icons, refer to
			the Emacspeak User's Guide.
			</para>
		</listitem>
	</itemizedlist>
	
</sect2>

<sect2 ID="speech-synthesizers">
<title>Speech Synthesizers</title>

	<para>
	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.
	</para>

<sect3 ID="hardware-synths">
<title>Hardware synthesizers</title>

	<para>
	Emacspeak supports the following hardware synthesizers:
	</para>

	<itemizedlist mark=bullet>

		<listitem>
			<para> 
			Accent
			</para>
		</listitem>

		<listitem>
			<para> 
			Apollo
			</para>
		</listitem>

		<listitem>
			<para> 
			Braille Lite
			</para>
		</listitem>

		<listitem>
			<para> 
			Braille n' Speak
			</para>
		</listitem>	

		<listitem>
			<para> 
			DECtalk Express (the original Emacspeak synthesizer) or MultiVoice
			</para>
		</listitem>
	
		<listitem>
			<para> 
			DoubleTalk PC and AT 
			</para>
		</listitem>

		<listitem>
			<para> 
			Internal DECtalk PC and DECtalk PC2
			</para>
		</listitem>
	
		<listitem>
			<para> 
			LiteTalk
			</para>
		</listitem>
	
		<listitem>
			<para> 
			Type n' Speak
			</para>
		</listitem>

	</itemizedlist>
 
	<para>
	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.
	</para>

	<para>
	The Internal DECtalk PC and DECtalk PC2 require a kernel
	driver available from <ulink url=
	"ftp://leb.net/pub/blinux/dectalk_pc-0.95.tgz"></ulink>. Installation
	instructions are at <ulink url=
	"ftp://leb.net/pub/blinux/dectalk_pc-0.95.README"></ulink>.
	</para>

	<para>
	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 <ulink url="ftp://leb.net/pub/blinux/emacspeak/blinux.emacspeak-ss-1.7.tar.gz"></ulink>.
	A README file with installation instructions can be found at
	<ulink url="ftp://leb.net/pub/blinux/emacspeak/blinux/emacspeak-ss.README"></ulink>. 
	</para>
</sect3>

<sect3 ID="software-synths">
<title>Software synthesizers</title>

	<para>
	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.
	</para>

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

	<para>
	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
	<xref linkend="appendixb">, Appendix B.
	</para>

</sect3>
</sect2>
</sect1>

<sect1 ID="installing-emacspeak">
<title>Installing Emacspeak</title>

	<para>
	Assuming that you have all the items listed in <xref
	linkend="requirements">, Requirements, you are ready to install
	Emacspeak. The following steps provide the instructions to do so.
	</para>

	<orderedlist>

		<listitem>
			<para>
			Go to the Emacspeak site at <ulink
			url="http://emacspeak.sourceforge.net"></ulink>
			and, from the Support and Documentation
			section, select an Emacspeak file to
			download. If you select the binary file,
			<filename>emacspeak.tar.gz</filename>, 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
			(<filename>emacspeak-14.0-1.noarch.rpm</filename>).
			</para>
		</listitem>

		<listitem>
			<para>
			Download the file and place it in
			your home directory.
			</para>
		</listitem>

		<listitem>
			<para>
			Type <command>su root</command> and provide
			the root
			password if you are not already logged onto your
			machine as root.  You'll need root
			permissions to install Emacspeak.
			</para>
		</listitem>

		<listitem>
			<para>
			If you downloaded the rpm version of
			Emacspeak, unpack it using the command
			<command>rpm -i
			emacspeak-14.0-1.noarch.rpm</command>. If you
			downloaded the binary version, unzip and untar
			the file, then follow the installation
			directions in the README file in the resulting
			<filename>emacspeak-14.0</filename> directory.
			</para>
	
			<para>
			Once you have installed the rpm, you'll see a
			message saying that Emacspeak installed
			successfully, as well as some
			additional instructions. 
			</para>
		</listitem>

		<listitem>
			<para>
			If you are using Emacspeak v.14 or earlier and
			also using ViaVoice TTS as your
			synthesizer, change directories to the
			<filename>/usr/share/emacs/site-lisp/emacspeak/servers/linux-outloud</filename>
			directory and type the command
			<command>make</command>. 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.
			</para>
		</listitem>

		<listitem>
			<para>
			Using the <command>cd</command> command, change directories to the
			<filename>/etc</filename> directory and open
			your <filename>profile</filename> file with
			your favorite text editor
			(you must be root to edit the
			<filename>profile</filename>). Scroll to the
			bottom of the file, then add the following two lines:
			</para>
			
			<programlisting>
			export DTK_PROGRAM
			DTK_PROGRAM=<replaceable>name of your speech server</replaceable>
			</programlisting>

			<para>
			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.
			</para>

			<simplelist type=horiz columns=2>

				<member>ViaVoice TTS</member>
				<member>outloud</member>

				<member>DecTalk Xpress</member>
				<member>dtk-exp</member>

				<member>DecTalk MultiVoice</member>
				<member>dtk-mv</member>
			</simplelist>

			<para>
			Several additional synthesizers are supported,
			but they require add-on speech servers. Refer
			to the documentation for each specific speech
			server for more information.
			</para> 
		</listitem>

		<listitem>
			<para>
			Save your <filename>profile</filename> file
			and close it.
			</para>
		</listitem>
	</orderedlist>

	<para>
	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
	<command>emacspeak</command> at the prompt. Emacspeak should
	start talking immediately.
	</para>
</sect1>

<sect1 ID="troubleshooting">
<title>Frequently Asked Questions (FAQs)</title>

	<para>
	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 <ulink
	url="http://www.cs.vassar.edu/~priestdo/emacspeak/"></ulink>.
	You can find the answers to many additional questions there.
	</para>

	<variablelist>
		<varlistentry>
			<term><command>The volume on my system is very low -
			how can I increase it?</command></term>
				<listitem>
					<para>
					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
					<application>aumix</application>
					to increase your system's volume. 
					</para>

					<para>
					<application>Aumix</application>
					comes with many distributions
					of Linux, but if your distro
					doesn't have
					<application>aumix</application>,
					you can download it from
					<ulink
					url="http://prdownloads.sourceforge.net/aumix/aumix-2.7.tar.gz"></ulink>.
					The latest version is 2.7.
					</para>

					<para>
					To use
					<application>aumix</application>
					to increase your system's
					volume, type the command
					<command>aumix -v
					+100</command> or
					<command>aumix -w +100</command>.  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. 
					</para>

					<para>
					For more information on using
					<application>aumix</application>, type <command>aumix
					-h</command> at the command prompt.
					</para>
				</listitem>
		</varlistentry>

		<varlistentry>
			<term><command>sndconfig doesn't recognize my
			soundcard.  What should I do?</command></term>
				<listitem>
					<para>
					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 <ulink
					url="http://www.alsa-project.org"></ulink>,
					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 <ulink
					url="http://www.4front-tech.com/osshw.html"></ulink>.
					There used to be a free
					version, but apparently it is
					no longer available (if anyone
					knows differently, please let
					me know).
					</para>

					<note><title>Note</title>
						<para>
						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. 
						</para>
					</note>
				</listitem>
		</varlistentry>	
					

		<varlistentry>
			<term><command>When I try to install the ViaVoice RTK
			rpm file, I get
			the error "libXm.so.1 is missing."  What's wrong?</command></term>
				<listitem>
					<para>
					The file
					<filename>libXm.so.1</filename>
					is part of the
					<filename>lesstif</filename>
					distribution, and it is also a
					shared library. This error
					message indicates that either
					<filename>lesstif</filename>
					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
					<filename>libXm.so.1.0.17</filename>.
					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
					<filename>libXm.so.1</filename>,
					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
					<command>--nodeps</command>,
					which tells ViaVoice to ignore any
					missing dependencies. 
					</para>

					<note><title>Note</title>
					<para>
					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.
					</para>
					</note>
				</listitem>
		</varlistentry>

		<varlistentry>
			<term><command>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 <filename>eci.h?</filename></command></term>
				<listitem>
					<para>
					This error message appears
					when you install the ViaVoice
					RTK and SDK in the wrong
					order, or if the SDK is not installed.
					</para>

					<para>
					The file
					<filename>eci.h</filename>
					should be in the
					<filename>/usr/include</filename> directory.  If it is not
					there, re-install ViaVoice TTS
					RTK, then install ViaVoice TTS
					SDK. Check to make sure
					<filename>eci.h</filename> is
					in the <filename>/usr/include</filename> directory,
					then change directories to
					<filename>/usr/share/emacs/site-lisp/emacspeak/servers/linux-outloud</filename>,
					and type
					<command>make</command> at the
					command prompt. The ViaVoice TTS
					should now make successfully.
					</para>
				</listitem>
		</varlistentry>

		<varlistentry>	
			<term><command>When I start Emacspeak, I keep getting
			the error "process speaker not running."
			What's wrong?</command></term>
				<listitem>
					<para>
					If you are getting this error
					message, there are several
					possible causes. This section
					steps though finding and
					correcting this problem.
					</para>
					
					<para>
					The first step is to
					make sure that you have tcl
					correctly installed, as
					explained in the following instructions.
					</para>
		
					<orderedlist>
						<listitem>
							<para>
							First, make
							sure you are
							in the
							<filename>/usr/share/emacs/site-lisp/emacspeak/servers</filename>
							directory.
							</para>
						</listitem>

						<listitem>
							<para>
							At the command
							prompt, type
							<command>tcl
							<replaceable>name
							of speech server</replaceable></command>,
						 	The
							most common
							speech servers are
							<command>dtk-exp</command>
							and
							<command>outloud</command>.
							</para>
						</listitem>
					</orderedlist>

					<para>
					If you get an error such as
					<command>bash: tcl:: command
					not found</command>, 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.
					</para>

					<para>
					If everything is installed
					correctly, you should hear a
					voice saying "IBM
					ViaVoice. This is Emacspeak"
					or something similar. A
					<command>%</command> command
					prompt should also appear.
					At the prompt, type <command>q "this is
					a test."</command> Then press
					<command>Return</command> and
					type
					<command>d</command>. 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
					<command>exit</command> to
					quit tcl.
					</para>
					
					<para>
					You may also get an error like
					<command>stdiosynth executable
					not found</command> when you
					type <command>tcl
					<replaceable>name of speech server</replaceable></command>, and then get a
					command prompt. Testing has
					shown that this error can
					appear even when
					<application>stdiosynth</application>
					is correctly installed and
					Emacspeak is working. Even if
					you get this error message,
					you should still get the
					<command>%</command> command prompt,
					so you should be able to test
					the script.
					</para>

					<para>
					If the script test was unsuccessful,
					(if tcl was found and
					you got a <prompt>%</prompt>
					prompt but you did not hear any
					speech), the next step is to
					make sure that you have the
					correct lines in your
					<filename>profile</filename>
					file to let Emacspeak know
					where to find the
					speech server. To check this,
					follow these steps:
					</para>

					<orderedlist>
						<listitem>
							<para>
							Go to your
							<filename>/etc</filename>
							directory,
							then use you
							favorite text
							editor to open the
							file named
							<filename>profile</filename>.
							</para>
						</listitem>

						<listitem>
							<para>
							Make sure the
							following
							lines are in
							the file:
							</para>

							<programlisting>
							export DTK_PROGRAM
							DTK_PROGRAM=<replaceable>name
							of speech server</replaceable>
							</programlisting>

							<para>
							The most
							common speech
							servers, are
							<command>outloud</command>
							and
							<command>dtk-exp</command>.
							</para>
						</listitem>
					</orderedlist>
			
					<para>
					If these lines are not in your
					<filename>profile</filename>
					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 <varname>DTK_PORT</varname> is set
					correctly in your
					<filename>/etc/profile</filename> file.
					</para>

					<para>
					The variable <varname>DTK_PORT</varname>
					specifies which port your hardware
					sythesizer is plugged into on
					your computer. Under Linux, if
					your synthesizer is plugged
					into com1, you must set
					<varname>DTK_PORT</varname> to
					<filename>/dev/ttyS0</filename>,
					and if it is in com2, then
					<varname>DTK_PORT</varname> should be set to
					<filename>/dev/ttyS1</filename>.
					To set this variable, follow
					these steps:
					</para>

					<orderedlist>
						<listitem>
							<para>
							Open your
							<filename>profile</filename>
							file located
							in the
							<filename>/etc</filename>
							directory.
							</para>
						</listitem>

						<listitem>
							<para>
							Look for the
							variable
							<varname>DTK_PORT</varname>.  If
							this variable does not
							exist, scroll
							to the bottom
							of the
							<filename>profile</filename>
							file and add
							the following
							line:
							</para>

		<programlisting>
		export DTK_PORT=/dev/ttySX
		</programlisting>

							<para>
							In this line,
							the "X" should
							be replaced by
							the correct
							port number,
							as described
							above.
							</para>
						</listitem>
		
						<listitem>
							<para>
							When you are
							finished, save
							and close the
							<filename>profile</filename>
							file.
							</para>
						</listitem>
					</orderedlist>

					<para>
					Finally, retest tcl, and if
					it works, restart Emacspeak.
					Emacspeak should work correctly.
					</para>

					<para>
					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: 
					</para>
	
					<itemizedlist mark=bullet>
						<listitem>
							<para>
							Change the
							ownership of
							the serail
							device to the
							user running
							Emacspeak. To
							do this, type
							<command>chown
							<replaceable>username</replaceable>
							/dev/ttyS0</command>
							at the command
							prompt,
							then type
							<command>chmode
							u+rw
							/dev/ttyS0</command>.
							</para>
						</listitem>

						<listitem>
							<para>
							Add the user
							to the group
							associated
							with the
							serial
							device. On Red
							Hat systems
							this is
							usually the
							group
							<command>tty</command>.
							To do this,
							edit the
							<filename>/etc/group</filename>
							file and find
							the line
							starting with
							<command>tty:</command>.
							At the end of
							that line, add
							",<replaceable>username</replaceable>"
							where username
							is your
							username.
							</para>
						</listitem>

						<listitem>
							<para>
							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
							<command>chmod
							o+rw
							/dev/ttyS0</command>.
							</para>
						</listitem>
					</itemizedlist> 
				</listitem>
		</varlistentry>
	</variablelist>
</sect1>

<sect1 ID="additional-resources">
<title>Additional resources</title>

	<para>
	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:
	</para>

	<itemizedlist mark=bullet>
		<listitem>
			<para> 
			"A gentle introduction to Emacspeak," by Gary
			Lawrence Murphy, <ulink
			url="http://emacspeak-guide.sourceforge.net/tutorial.html/"></ulink>.
			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).
			</para>
		</listitem>

		<listitem>
			<para>
			"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 <command>C-h
			t</command>.  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.
			</para>
		</listitem>

		<listitem>
			<para>
			"Emacspeak Tutorial," by Nita Van Zandt,
			available at <ulink
			url="http://www.mv.com/ipusers/vanzandt/emacspeak-tutorial-1.0.tar.gz"></ulink>.
			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.
			</para>		
		</listitem>

		<listitem>
			<para>
			"The Emacs Beginner's HOWTO," by Jeremy
			D. Zawodny. It is available at <ulink
			url="http://www.linuxdoc.org/HOWTO/Emacs-Beginner-HOWTO.html"></ulink>
			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.
			</para>		
		</listitem>

		<listitem>
			<para>
			"Using Emacspeak HOWTO," by Jennifer Jobst,
			available at <ulink
			url="http://emacspeak.sourceforge.net"></ulink>. 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. 
			</para>
		</listitem>
	</itemizedlist>
</sect1>

<sect1 ID="appendixa">
<title>Appendix A: Installing Linux from a DOS machine</title>
	
	<para>
	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&trade; or DOS&trade;
	machine over a null-modem cable,
	please let me know the procedure you followed and I'll include
	it here.
	</para>

	<para>
	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 <ulink
	url="http://www.freedomscientific.com/fs_downloads/morejaws.asp"></ulink>),
	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.
	</para>

<sect2 id="appendix-a-requirements">
<title>Requirments</title>

	<para>
	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 <ulink
	url="http://www.vandyke.com/products/crt"></ulink>). 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. 
	</para>

</sect2>

<sect2 id="setup">
<title>Connecting the computers</title>

	<para>
	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
	<application>LapLink</application> will work fine.  The
	<application>LapLink</application> 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:
	</para>

	<itemizedlist>
		<listitem>
			<para>
			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.
			</para>
		</listitem>

		<listitem>
			<para>
			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.
			</para>
		</listitem>

		<listitem>
			<para>
			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).
			</para>
		</listitem>
	</itemizedlist>

	<para>
	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
	</para>
</sect2>

<sect2 id="installing">
<title>Installation</title>

	<para>
	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 <ulink
	url="http://www.vandyke.com/products/crt"></ulink>.
	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.
	</para>

	<para>
	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).
	</para>

	<para>
	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 <prompt>boot:</prompt> prompt, I typed in the
	command <command>linux text console=ttyS0</command>.  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. 
	</para>

	<para>
	Once you've typed in this string at the <prompt>boot:</prompt>
	prompt and hit <command>Return</command>, 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.
	</para>

</sect2>
</sect1>

<sect1 id="appendixb">
<title>Appendix B: Installing ViaVoice TTS</title>

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

<sect2 id="downloading-viavoice">
<title>Downloading ViaVoice</title>

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

	<orderedlist>
		<listitem>
			<para>
			Go to IBM's ViaVoice TTS website at <ulink
			url="http://www.redhat.com/services/techsupport/accessibility/s1-access-install.html"></ulink>.
			</para>
		</listitem>

		<listitem>			
			<para>
			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.
			</para>
		</listitem>
			
		<listitem>
			<para>
			Download the following files:
			</para>
	
			<itemizedlist mark=bullet>
				<listitem>
					<para>
					ViaVoice TTS SDK for Linux
					V5.1.  The filename is
					<filename>viavoice_tts_sdk_5.tar</filename>.
					</para>
				</listitem>

				<listitem>
					<para>
					ViaVoice TTS Run Time Kit for
					Linux V5.1. The filename is
					<filename>viavoice_tts_rtk_5.tar</filename>.
					</para>
				</listitem>
			</itemizedlist>
		</listitem>
	</orderedlist>
</sect2>

<sect2 id="installing-rtk">
<title>Installing ViaVoice RTK</title>

	<para>
	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.
	</para>
	
	<orderedlist>
		<listitem>
			<para>
			Type the <command>su
			root</command> command and provide the root
			password to log on to your system as root.
			</para>
		</listitem>
		
		<listitem>
			<para>
			Type the <command>cd</command> command to
			change to the directory that contains the files you just downloaded.
			</para>
		</listitem>

		<listitem>
			<para>
			Untar the RTK using the command <command>tar
			-xvf viavoice_tts_rtk_5.tar</command>. You
should now have two files in your directory, <filename>ttsrt_readme.txt</filename> and <filename>ViaVoice_TTS_rtk_5.1-1.2.i386.rpm</filename>. 
			</para>
		</listitem>

		<listitem>
			<para>
			Unpack the rpm using the command <command>rpm
			-i
ViaVoice_TTS_rtk_5.1-1.2.i386.rpm</command>. 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.
			</para>
		</listitem>

		<listitem>
			<para>
			Type the command <command>source
			/etc/profile</command> to finish installing the RTK.
			</para>
		</listitem>
	</orderedlist>
</sect2>

<sect2 id="installing-sdk">
<title>Installing ViaVoice SDK</title>

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

	<orderedlist>
		<listitem>
			<para>
			Change directories to the directory that contains the
			SDK file you downloaded.
			</para>
		</listitem>

		<listitem>
			<para>
			Untar the SDK file using the
			command <command>tar -xvf
			viavoice_tts_sdk_5.tar</command>. You should
			now have two files in your directory,
			<filename>ttssd.readme.txt</filename> and
			<filename>ViaVoice_TTS_sdk-5.1-1.2.i386.rpm</filename>.
			</para>
		</listitem>

		<listitem>
			<para>
			Unpack the rpm using the command <command>rpm
			-i --nodeps ViaVoice_TTS_sdk-5.1-1.2.i386.rpm</command>. 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.
			</para>
		</listitem>
	</orderedlist> 
</sect2>

<sect2 id="testing-install">
<title>Testing the installation</title>

	<para>
	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:
	</para>

	<orderedlist>
		<listitem>
			<para>
			Type the <command>cd</command> command to
			change to the
			<filename>/usr/lib/ViaVoiceTTS/samples/cmdlinespeak/</filename> directory.
			</para>
		</listitem>
	
		<listitem>
			<para>
			Type the command
			<command>./runcmdlinespeak</command> 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 <xref
			linkend="troubleshooting">, Troubleshooting,
			for information on how to increase your
			system volume. 
			</para>
		</listitem>
	</orderedlist>

	<para>
	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.
	</para>
</sect2>
</sect1>

<sect1 id="acknowledgments">
<title>Acknowledgments</title>

	<para>
	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.
	</para>

	<para>
	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."
	</para>

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

	<para>
	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.
	</para>
	
	<para>
	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.
	</para>

	<para>
	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.
	</para>

	<para>
	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!
	</para>
</sect1>
</article>