Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdeaccessibility@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 2834 insertions, 0 deletions

diff --git a/doc/kttsd/index.docbook b/doc/kttsd/index.docbook
new file mode 100644
index 0000000..a533d52
--- /dev/null
+++ b/doc/kttsd/index.docbook
@@ -0,0 +1,2834 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+  <!ENTITY ktts "<application>KTTS</application>">
+  <!ENTITY kappname "&ktts;">
+  <!ENTITY package "kdeaccessibility">
+  <!ENTITY mbrola "<application>MBROLA</application>">
+  <!ENTITY % imageobjectco.module "INCLUDE">
+  <!ENTITY % addindex "IGNORE">
+  <!ENTITY % English "INCLUDE">
+]>
+<!-- Note to translators: KTTSD is meant to be built under KDE
+     versions 3.2 and later.  Please avoid entities that won't
+     be defined under those KDE versions.  Thanks.
+-->
+
+<!-- kdoctemplate v0.9 January 10 2003
+     Changes to comments to clarify entity usage January 10 2003
+     Minor update to "Credits and Licenses" section on August 24, 2000
+     Removed "Revision history" section on 22 January 2001
+     Changed to Installation/Help menu entities 18 October 2001
+     Other minor cleanup and changes 18 October 2001 
+     FPI change and minor changes November 2002 -->
+
+<!--
+This template was designed by: David Rugge davidrugge@mindspring.com
+with lots of help from: Eric Bischoff ebisch@cybercable.tm.fr
+and Frederik Fouvry fouvry@sfs.nphil.uni-tuebingen.de
+of the KDE DocBook team.
+
+You may freely use this template for writing any sort of KDE documentation.
+If you have any changes or improvements, please let us know.
+
+Remember:
+- in XML, the case of the <tags> and attributes is relevant ;
+- also, quote all attributes.
+
+Please don't forget to remove all these comments in your final documentation,
+thanks ;-).
+-->
+
+<!-- ................................................................ -->
+
+<!-- The language must NOT be changed here. -->
+<!-- If you are writing original documentation in a language other -->
+<!-- than English, change the language above ONLY, not here -->
+<book lang="&language;">
+
+<!-- This header contains all of the meta-information for the document such
+as Authors, publish date, the abstract, and Keywords -->
+
+<bookinfo>
+<title>The &ktts; Handbook</title>
+
+<authorgroup>
+<author>
+<!-- This is just put in as an example.  For real documentation, please 
+     define a general entity in entities/contributor.entities, e.g.
+<!ENTITY George.N.Ugnacious "<personname><firstname>George</firstname><othername>N.</othername><surname>Ugnacious</surname></personname>">
+<!ENTITY George.N.Ugnacious.mail "<email>gnu@kde.org</email>">
+and use `&George.N.Ugnacious; &George.N.Ugnacious.mail;' in the author element.
+ -->
+<personname>
+<firstname>Gary</firstname>
+<othername>R.</othername>
+<surname>Cramblitt</surname>
+</personname>
+<email>garycramblitt@comcast.net</email>
+</author>
+
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+
+</authorgroup>
+
+<copyright>
+<year>2004-2005</year>
+<holder>Gary R. Cramblitt</holder>
+</copyright>
+<!-- Translators: put here the copyright notice of the translation -->
+<!-- Put here the FDL notice.  Read the explanation in fdl-notice.docbook 
+     and in the FDL itself on how to use it. -->
+<legalnotice>&FDLNotice;</legalnotice>
+
+<!-- Date and version information of the documentation
+Don't forget to include this last date and this last revision number, we
+need them for translation coordination !
+Please respect the format of the date (YYYY-MM-DD) and of the version
+(V.MM.LL), it could be used by automation scripts.
+Do NOT change these in the translation. -->
+
+<date>2005-07-31</date>
+<releaseinfo>1.05.00</releaseinfo>
+
+<!-- Abstract about this handbook -->
+
+<abstract>
+<para>
+&ktts; - the &kde; Text-to-Speech system - is
+a plugin based service that
+allows any &kde; (or non-&kde;) application to speak using the &DCOP; interface.
+</para>
+
+<para>&ktts; intends to be the implementation for the &kde; Text-to-Speech API.</para>
+
+</abstract>
+
+<!-- This is a set of Keywords for indexing by search engines.
+Please at least include KDE, the KDE package it is in, the name
+ of your application, and a few relevant keywords. -->
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>accessibility</keyword>
+<keyword>kdeaccessibility</keyword>
+<keyword>TTS</keyword>
+<keyword>Text-to-Speech</keyword>
+<keyword>KTTSD</keyword>
+<keyword>kttsmgr</keyword>
+<keyword>festival</keyword>
+<keyword>flite</keyword>
+<keyword>hadifix</keyword>
+<keyword>MBROLA</keyword>
+<keyword>freetts</keyword>
+<keyword>epos</keyword>
+<keyword>SSML</keyword>
+</keywordset>
+
+</bookinfo>
+
+<!-- The contents of the documentation begin here.  Label
+each chapter so with the id attribute. This is necessary for two reasons: it
+allows you to easily reference the chapter from other chapters of your
+document, and if there is no ID, the name of the generated HTML files will vary
+from time to time making it hard to manage for maintainers and for the CVS
+system. Any chapter labelled (OPTIONAL) may be left out at the author's
+discretion. Other chapters should not be left out in order to maintain a
+consistent documentation style across all KDE apps. -->
+
+<!-- ====================================================================== -->
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<!-- The introduction chapter contains a brief introduction for the
+application that explains what it does and where to report
+problems. Basically a long version of the abstract.  Don't include a
+revision history. (see installation appendix comment) -->
+
+<para>&ktts; is a subsysem within &kde; for producing
+Text-to-Speech (TTS).  It provides a common API for &kde; programmers to give
+TTS capabilities to their applications.  It provides some
+nice capabilities for end users as well.</para>
+
+<para>User features:</para>
+
+<itemizedlist>
+<listitem><para>Speak contents of a text file.</para></listitem>
+<listitem><para>Speak &kde; notification events (KNotify).</para></listitem>
+<listitem><para>Speak all or part of the text of a web page in &konqueror;.</para></listitem>
+<listitem><para>Speak all or part of the text in &kate; text editor,
+including instances where &kate; is embedded in another &kde; application.</para></listitem>
+<listitem><para>Long text is parsed into sentences.  User may backup by sentence
+or paragraph, replay, pause, and stop playing.</para></listitem>
+<listitem><para>Audio output via &arts;, ALSA, GStreamer (version 0.8.7 or later), or aKode.</para></listitem>
+<listitem><para>User-configurable filters for substituting misspoken words, choosing
+speech synthesizers, and transforming XHMTL/&XML; documents.</para></listitem>
+</itemizedlist>
+
+<para>Programmer features:</para>
+
+<itemizedlist>
+<listitem><para>Priority system for screen reader outputs, warnings and messages, while still playing regular texts.</para></listitem>
+<listitem><para>Plugin-based architecture for support of a wide variety of speech synthesis engines and drivers.</para></listitem>
+<listitem><para>Permit generation of speech from the command line (or via shell scripts) using the &kde; &DCOP; utilities.</para></listitem>
+<listitem><para>Provide a lightweight and easily usable interface for applications to generate speech output.</para></listitem>
+<listitem><para>Applications need not be concerned about contention over the speech device.</para></listitem>
+<listitem><para>FUTURE: Provide support for speech markup languages, such as VoiceXML, Sable, &Java; Speech Markup Language (JSML), and Speech Markup Meta-language (SMML).</para></listitem>
+<listitem><para>FUTURE: Provide limited support for embedded speech markers.</para></listitem>
+<listitem><para>Asynchronous to prevent system blocking.</para></listitem>
+</itemizedlist>
+
+<para>&ktts; actually consists of several programs:
+<variablelist>
+
+<varlistentry>
+<term><command>kttsd</command></term>
+<listitem><para>the &kde; Text-to-Speech Daemon, which is a non-&GUI;
+application that provides TTS services to applications via &DCOP;.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term><command>kttsmgr</command></term>
+<listitem><para>a &GUI; application for configuring and controlling
+kttsd.  kttsmgr sits in the system tray.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term><command>libkhtmlkttsdplugin</command></term>
+<listitem><para>A plugin for the &konqueror; web browser that permits you
+to speak all or a portion of the text on a web page.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term><command>ktexteditor_kttsd</command></term>
+<listitem><para>A plugin for the &kate; text editor that permits you to speak
+all or a portion of a text file.
+</para></listitem></varlistentry>
+
+</variablelist>
+</para>
+
+<!-- ...................................................................... -->
+
+<sect1 id="support">
+<title>Support</title>
+<para>
+In addition to the &kde; Bugzilla database (
+<ulink url="http://bugs.kde.org/">http://bugs.kde.org/</ulink>
+), discussions for &ktts;
+currently take place in the kde-accessibility mailing list.  Subscribe at
+<ulink url="https://mail.kde.org/mailman/listinfo/kde-accessibility">
+https://mail.kde.org/mailman/listinfo/kde-accessibility</ulink>.  Developers
+also hang out in IRC (irc.kde.org, channel #kde-accessibility).
+</para>
+</sect1>
+
+</chapter>
+
+<!-- ====================================================================== -->
+
+<chapter id="using-kapp">
+<title>Using &ktts;</title>
+
+<para>
+<warning><para>Before you can use &ktts;, you must install at least one speech
+synthesis engine and make sure it is working.  See <xref linkend="installation" />.
+</para></warning></para>
+
+<!-- ...................................................................... -->
+
+
+<sect1 id="starting-kttsmgr">
+<title>Starting <command>kttsmgr</command></title>
+
+<para>
+To start the &ktts; system, type the following command in a &konsole;
+</para>
+
+<para><userinput>kttsmgr</userinput></para>
+
+<para>or click on kttsmgr in the &kde; Menu.</para>
+
+<para>If this is the first time running <command>kttsmgr</command>, or
+if you have not yet configured any talkers, the <guilabel>Talkers</guilabel>
+screen appears.  See <xref linkend="configure-plugin" />.
+If you have already configured at least one talker, the <guilabel>General</guilabel>
+screen appears.  See <xref linkend="general" />.</para>
+
+</sect1>
+
+<!-- ...................................................................... -->
+
+
+<sect1 id="configure-plugin">
+<title>Configuring Synthesis Plugins (Talkers)</title>
+
+<para>Most text-to-speech (TTS) synthesizers offer multiple languages and voices
+and may offer multiple speaking genders, volumes, and rates.  You may configure more than
+one instance of a synthesizer.  Each combination of language, synthesizer, voice,
+gender, volume, and rate is called a talker.  You must configure at least one talker
+before you can start &ktts; and begin speaking text.</para>
+
+<note><para>Multiple talkers for the same synthesizer is similar to multiple print
+queues for a single physical printer.</para></note>
+
+<para>When applications send text to &ktts;, they may specify the
+attributes of the preferred talker to do the synthesis.  For example,
+an application may request an English language female talker.  If you have
+configured a talker with both the English language and female gender, that
+talker will be used, otherwise the closest matching talker will be automatically
+picked.  To learn more about how &ktts; picks talkers, see
+<xref linkend="filters" />.</para>
+
+<para>When you click the <guilabel>Talkers</guilabel> tab in <command>kttsmgr</command>,
+the <guilabel>Talkers</guilabel> screen appears.  This screen also automatically
+appears if you start <command>kttsmgr</command> and you have not yet configured
+any talkers.</para>
+
+<para>
+<screenshot>
+<screeninfo>The &kde; Text-to-Speech Manager (Talkers tab).</screeninfo>
+	<mediaobjectco>
+		<imageobjectco>
+			<areaspec units="calspair">
+				<area id="pt-talker-1" coords="1 1"/>
+				<area id="pt-talker-2" coords="1 1"/>
+				<area id="pt-talker-3" coords="1 1"/>
+				<area id="pt-talker-4" coords="1 1"/>
+				<area id="pt-talker-5" coords="1 1"/>
+				<area id="pt-talker-6" coords="1 1"/>
+			</areaspec>
+			<imageobject>
+				<imagedata fileref="talkers.png" format="PNG"/>
+			</imageobject>
+		</imageobjectco>
+		<textobject>
+			<phrase>The &kde; Text-to-Speech Manager (Talkers tab)</phrase>
+		</textobject>
+	</mediaobjectco>
+</screenshot>
+</para>
+
+<para>
+<calloutlist>
+<callout arearefs="pt-talker-1"><para>Click to add a new talker.</para></callout>
+<callout arearefs="pt-talker-2"><para>All the configured <guilabel>Talkers</guilabel> are listed here.  Highest priority <guilabel>Talkers</guilabel> are listed at the top.  The top-most talker will be used to do the speaking when an application does not specify a talker.</para></callout>
+<callout arearefs="pt-talker-3"><para>Click on a talker in the list to highlight it and click this button to remove it.</para></callout>
+<callout arearefs="pt-talker-4"><para>Click on a talker in the list to highlight it and click this button to display the synthesis plugin's configuration dialog.  See below.</para></callout>
+<callout arearefs="pt-talker-5"><para>Click on a talker in the list to highlight it and click this button to move it down one row in the list.  The lower a talker appears in the list, the lower its priority.</para></callout>
+<callout arearefs="pt-talker-6"><para>Click one of these buttons to apply the changes you have made to the running &ktts; system.</para></callout>
+</calloutlist>
+</para>
+
+<para>When you click the <guibutton>Add</guibutton> button, the <guilabel>Add Talker</guilabel> screen appears.</para>
+
+<para>
+	<screenshot>
+		<screeninfo>Add Talker screen.</screeninfo>
+		<mediaobjectco>
+			<imageobjectco>
+				<areaspec units="calspair">
+					<area id="pt-addtalker-1" coords="1 1"/>
+					<area id="pt-addtalker-2" coords="1 1"/>
+					<area id="pt-addtalker-3" coords="1 1"/>
+				</areaspec>
+				<imageobject>
+					<imagedata fileref="addtalker.png" format="PNG"/>
+				</imageobject>
+			</imageobjectco>
+			<textobject>
+				<phrase>Add Talker screen</phrase>
+			</textobject>
+		</mediaobjectco>
+	</screenshot>
+</para>
+
+<para>
+<calloutlist>
+<callout arearefs="pt-addtalker-1"><para>You can select a speech synthesis
+plugin by either <guilabel>Synthesizer</guilabel> name, or by the <guilabel>Language</guilabel> the synthesizer can speak.
+Check the radio button next to the corresponding box.  When the
+<guilabel>Language</guilabel> radio button is checked, the
+<guilabel>Language</guilabel> box displays all the languages supported by
+all available synthesizers, and the <guilabel>Synthesizer</guilabel> box
+displays only those synthesizers that support the chosen language.
+When the <guilabel>Synthesizer</guilabel> radio button is checked,
+the <guilabel>Synthesizer</guilabel> box displays all available
+synthesizers, and the <guilabel>Language</guilabel> box displays
+only the languages supported by the chosen synthesizer.</para></callout>
+<callout arearefs="pt-addtalker-2"><para>Choose the language and
+synthesizer plugin here.</para></callout>
+<callout arearefs="pt-addtalker-3"><para>When you click here,
+most synthesizer plugins will automatically configure themselves,
+choosing a default setup.  A new talker
+will appear in the list in the <guilabel>Talkers</guilabel> screen.
+Click the <guibutton>Edit</guibutton> button to display or edit the talker's 
+configuration.</para></callout>
+</calloutlist>
+</para>
+
+<para>When you click the <guibutton>Add</guibutton> button on the
+<guilabel>Talkers</guilabel> tab and add a talker that cannot
+automatically configure itself, or click the
+<guibutton>Edit</guibutton> button,
+the <guilabel>Talker Configuration</guilabel> screen appears.
+Each speech synthesis plugin has a different
+<guilabel>Talker Configuration</guilabel> screen.  The following is an example for
+configuring the Festival Interactive plugin.  For specifics for each
+kind of plugin, see <xref linkend="configuration" />.</para>
+
+<para>
+<screenshot>
+<screeninfo>Talker Configuration</screeninfo>
+	<mediaobjectco>
+		<imageobjectco>
+			<areaspec units="calspair">
+				<area id="pt-prop-1" coords="1 1"/>
+				<area id="pt-prop-2" coords="1 1"/>
+				<area id="pt-prop-3" coords="1 1"/>
+				<area id="pt-prop-4" coords="1 1"/>
+				<area id="pt-prop-5" coords="1 1"/>
+				<area id="pt-prop-6" coords="1 1"/>
+				<area id="pt-prop-7" coords="1 1"/>
+			</areaspec>
+			<imageobject>
+				<imagedata fileref="festivalintconf.png" format="PNG"/>
+			</imageobject>
+		</imageobjectco>
+		<textobject>
+			<phrase>Talker Configuration</phrase>
+		</textobject>
+	</mediaobjectco>
+</screenshot>
+</para>
+
+<para>
+<calloutlist>
+<callout arearefs="pt-prop-1"><para>Specify the path to the Festival executable program.
+If Festival is in your PATH environment variable, just enter
+<userinput><replaceable>festival</replaceable></userinput>.</para></callout>
+<callout arearefs="pt-prop-2"><para>Click to scan for available voices.</para></callout>
+<callout arearefs="pt-prop-3"><para>Select a voice.</para></callout>
+<callout arearefs="pt-prop-4"><para>Select a character encoding for text sent to Festival.
+For voices that are known to &ktts;, this setting will be picked for you automatically.  In general, western languages use ISO 8859-1.  Eastern European languages such
+as Czech or Slovak use ISO 8859-2.</para></callout>
+<callout arearefs="pt-prop-5"><para>Click to test.  You should hear a test sentence spoken.</para></callout>
+<callout arearefs="pt-prop-6"><para>Use these controls to set the volume, talking speed, and
+pitch (tone) of the synthesized speech.  If any of these are disabled (grayed), the chosen
+voice does not support changing them.</para></callout>
+<callout arearefs="pt-prop-7"><para>Some voices, such as the MultiSyn voices, are so large
+that they require several seconds to load.  Checking this box will cause them to be loaded
+when KTTSD is started, thereby saving time (at the expense of using more memory)
+before the first sentence is synthesized.</para></callout>
+</calloutlist>
+</para>
+
+<para>Click the <guibutton>OK</guibutton> button to save the talker configuration settings.</para>
+
+<warning><para>
+Be sure to click the <guibutton>Apply</guibutton> button, otherwise your
+changes will not take effect in the running &ktts; system.
+</para></warning>
+
+<para>Assuming the test worked, you are almost ready to begin using &ktts;.
+Now go back to the <guilabel>General</guilabel> tab and check the
+<guilabel>Enable Text-to-Speech System (KTTSD)</guilabel> box.  This
+will start the &kde; TTS Daemon.  See <xref linkend="general" />.
+You may now begin using &ktts; to
+speak text.  Click the <guilabel>Jobs</guilabel> tab to create and manage text jobs.
+See <xref linkend="jobmgr" />.
+</para>
+
+</sect1>
+
+<!-- ...................................................................... -->
+
+
+<sect1 id="general">
+<title>Starting KTTSD and Setting General Options</title>
+
+<para>Once you have configured at least one talker,
+you can start the &kde; Text-to-Speech System.  Click on the
+<guilabel>General</guilabel> tab.  The <guilabel>General</guilabel>
+screen appears.  You can also set some general options on this screen.
+</para>
+
+<para>
+	<screenshot>
+		<screeninfo>The &kde; Text-to-Speech Manager (General tab).</screeninfo>
+		<mediaobjectco>
+			<imageobjectco>
+				<areaspec units="calspair">
+					<area id="pt-gen-1" coords="1 1"/>
+					<area id="pt-gen-2" coords="1 1"/>
+					<area id="pt-gen-3" coords="1 1"/>
+					<area id="pt-gen-4" coords="1 1"/>
+                    <area id="pt-gen-5" coords="1 1"/>
+                    <area id="pt-gen-6" coords="1 1"/>
+				</areaspec>
+				<imageobject>
+					<imagedata fileref="general.png" format="PNG"/>
+				</imageobject>
+			</imageobjectco>
+			<textobject>
+				<phrase>The &kde; Text-to-Speech Manager (General tab)</phrase>
+			</textobject>
+		</mediaobjectco>
+	</screenshot>
+</para>
+
+<para>
+<calloutlist>
+<callout arearefs="pt-gen-1"><para>Check this box to activate the &ktts; system.
+This starts the &kde; TTS Daemon (KTTSD).  If KTTSD starts successfully,
+the <guilabel>Jobs</guilabel> tab will appear.
+Once KTTSD has been started, you can begin creating and speaking text jobs.
+See <xref linkend="jobmgr" />.  Unchecking will stop KTTSD and deactivate the &kde; TTS system.
+<note><para>If this box is disabled, you have not yet configured any talkers
+(or you forgot to click the <guibutton>Apply</guibutton> button).
+See <xref linkend="configure-plugin"/>.</para></note>
+</para></callout>
+<callout arearefs="pt-gen-2"><para>When this box is checked, an icon appears
+in the system tray whenever <command>kttsmgr</command> is running.  In this
+mode, clicking <guibutton>OK</guibutton> or <guibutton>Cancel</guibutton> does
+not cause <command>kttsmgr</command> to exit.  Instead, the screen
+disappears but <command>kttsmgr</command> continues running in the system
+tray.  Click the icon to restore the screen.  To quit <command>kttsmgr</command>,
+right-click on the icon in the system tray and choose <guilabel>Quit</guilabel>.
+When unchecked, an icon does not appear in the system tray.  Clicking <guibutton>OK</guibutton>
+or <guibutton>Cancel</guibutton> quits <command>kttsmgr</command>.
+<note><para>When <command>kttsmgr</command> exits, 
+&ktts; keeps running if the <guilabel>Enable Text-to-Speech System (KTTSD)</guilabel> box is checked.</para></note>
+<note><para>This option does not take effect until the next time
+<command>kttsmgr</command> is started.</para></note>
+<note><para>This option has no effect when <command>kttsmgr</command> is
+running in the &kcontrol;.</para></note>
+</para></callout>
+<callout arearefs="pt-gen-3"><para>When this box is checked, the <command>kttsmgr</command> screen appears when you start <command>kttsmgr</command>.  If unchecked, the
+<command>kttsmgr</command> icon appears in the system tray when
+<command>kttsmgr</command> is started, but the screen does not appear.
+Click the icon in the system tray to make the screen appear.</para></callout>
+<callout arearefs="pt-gen-4"><para>When this box is checked, and <command>kttsmgr</command> is 
+not already running, it will appear in the system tray whenever KTTSD is speaking.
+This gives you an opportunity to stop or otherwise manage the speaking.</para></callout>
+<callout arearefs="pt-gen-5"><para>When this box is checked, and <command>kttsmgr</command>
+automatically appears in the system tray whenever speaking, it will also disappear
+automatically when speaking has finished.</para></callout>
+<callout arearefs="pt-gen-6"><para>Be sure to click here to save your settings.</para></callout>
+</calloutlist>
+</para>
+
+</sect1>
+
+<!-- ...................................................................... -->
+
+
+<sect1 id="jobmgr">
+<title>Managing Text Jobs</title>
+
+<para>When you click the <guilabel>Jobs</guilabel> tab in <command>kttsmgr</command>,
+the <guilabel>Jobs</guilabel> screen appears.</para>
+
+<para>
+<screenshot>
+<screeninfo>The &kde; Text-to-Speech Manager (Jobs tab).</screeninfo>
+	<mediaobjectco>
+		<imageobjectco>
+			<areaspec units="calspair">
+				<area id="pt-jobmgr-1" coords="1 1"/>
+				<area id="pt-jobmgr-2" coords="1 1"/>
+				<area id="pt-jobmgr-3" coords="1 1"/>
+				<area id="pt-jobmgr-4" coords="1 1"/>
+				<area id="pt-jobmgr-5" coords="1 1"/>
+				<area id="pt-jobmgr-6" coords="1 1"/>
+				<area id="pt-jobmgr-7" coords="1 1"/>
+			</areaspec>
+			<imageobject>
+				<imagedata fileref="jobs.png" format="PNG"/>
+			</imageobject>
+		</imageobjectco>
+		<textobject>
+			<phrase>The &kde; Text-to-Speech Manager (Jobs tab)</phrase>
+		</textobject>
+	</mediaobjectco>
+</screenshot>
+</para>
+
+<para>
+<calloutlist>
+<callout arearefs="pt-jobmgr-1"><para>All of the text jobs currently in the queue
+are listed here, together with the application that queued the job,
+the current job state, number of sentences in the job,
+and current sentence number.  The <guilabel>Talker ID</guilabel> corresponds to the
+<guilabel>ID</guilabel> column on the <guilabel>Talkers</guilabel> screen.
+</para></callout>
+<callout arearefs="pt-jobmgr-2"><para>The buttons in this row permit you to start,
+delete, and pause text jobs.  Select a job in the list above, then click
+one of these buttons.</para></callout>
+<callout arearefs="pt-jobmgr-3"><para>The buttons in this row permit
+you to advance or rewind by sentence within the job selected in the list
+above.  (Not all jobs have multiple parts.)</para></callout>
+<callout arearefs="pt-jobmgr-4"><para>The buttons in this row permit
+you to speak the text currently in the &kde; clipboard, or open a text file
+for speaking.  You can also refresh the list of text jobs or
+change the talker for a job.  See <xref linkend="selecttalker" />.</para></callout>
+<callout arearefs="pt-jobmgr-5"><para>The currently-speaking sentence
+appears here.</para></callout>
+<callout arearefs="pt-jobmgr-6"><para>When you click <guibutton>OK</guibutton>,
+all changes to settings on other screens are applied (if any) and
+<command>kttsmgr</command> minimizes to the system tray.  Click on the icon
+in the system tray to restore the screen.</para></callout>
+<callout arearefs="pt-jobmgr-7"><para>Drag this divider to resize
+the jobs listing and <guilabel>Current sentence</guilabel> panels.</para></callout>
+</calloutlist>
+</para>
+
+<note><para>The <guilabel>Jobs</guilabel> tab only appears when KTTSD is running.  If you do not see the <guilabel>Jobs</guilabel> tab, click on the
+<guilabel>General</guilabel> tab and check the
+<guilabel>Enable Text-to-Speech (KTTSD)</guilabel> box.</para>
+</note>
+
+<note><para>If you do not have the &arts; audio subsystem installed, but you
+do have ALSA, GStreamer, or aKode installed, click the <guilabel>Audio</guilabel> tab.
+See <xref linkend="audio" />.</para></note>
+
+<note><para>Only Text jobs are listed and controlled on this screen.
+Screen Reader Output, Warnings, and Messages are not displayed.  For more information
+about &ktts; message types, see <xref linkend="filters" />.</para></note>
+
+</sect1>
+
+<!-- ...................................................................... -->
+
+<sect1 id="audio">
+<title>Audio Settings</title>
+
+<para>When you click the <guilabel>Audio</guilabel> tab in <command>kttsmgr</command>,
+the <guilabel>Audio</guilabel> screen appears.</para>
+
+<para>
+    <screenshot>
+        <screeninfo>The &kde; Text-to-Speech Manager (Audio tab).</screeninfo>
+        <mediaobjectco>
+            <imageobjectco>
+                <areaspec units="calspair">
+                    <area id="pt-audio-1" coords="1 1"/>
+                    <area id="pt-audio-2" coords="1 1"/>
+                    <area id="pt-audio-3" coords="1 1"/>
+                    <area id="pt-audio-4" coords="1 1"/>
+                    <area id="pt-audio-5" coords="1 1"/>
+                </areaspec>
+                <imageobject>
+                    <imagedata fileref="audio.png" format="PNG"/>
+                </imageobject>
+            </imageobjectco>
+            <textobject>
+                <phrase>The &kde; Text-to-Speech Manager (Audio tab)</phrase>
+            </textobject>
+        </mediaobjectco>
+    </screenshot>
+</para>
+
+<para>
+<calloutlist>
+<callout arearefs="pt-audio-1"><para>Select the method of audio output here.
+If a component is is grayed, either &ktts; was compiled
+without that support for that audio plugin, or &ktts; was unable to load the
+necessary libraries.
+</para></callout>
+<callout arearefs="pt-audio-2"><para>If GStreamer or aKode is selected for audio output,
+choose the audio sink method here.  If no sinks are listed, you need
+to install at least one.  If ALSA is selected, choose the PCM device here.  See <xref linkend="requirements" />.
+</para></callout>
+<callout arearefs="pt-audio-3"><para>Adjust the speed of talking here.
+50% is approximately twice as slow as normal while 200% is approximately
+twice as fast.  You must have the <command>sox</command> utility installed for this setting
+to work.
+</para></callout>
+<callout arearefs="pt-audio-4"><para>When this box is checked, &ktts; will 
+copy temporary audio files (.wav files) into the indicated folder.  Choose
+any folder on your hard drive you like, but you must have write access to it.
+This can be useful for creating audio files of speech for other purposes.
+The files will have names of the form <filename>kttsd-J-SS</filename> where
+<filename>J</filename> is the job number and <filename>SS</filename> is the sentence number.
+Existing files with the same name will be deleted.
+<emphasis>Do not forget to uncheck this box, otherwise your hard drive will fill up!</emphasis>
+</para></callout>
+<callout arearefs="pt-audio-5"><para>Be sure to click <guibutton>Apply</guibutton>
+to apply the new settings to the running &ktts; system.
+</para></callout>
+</calloutlist>
+</para>
+
+<note><para>There are two ways to adjust the speed of speech in &ktts;.
+Many of the <guilabel>Talkers</guilabel> have a <guilabel>Speed</guilabel>
+setting in their configuration dialogs, which you can display by clicking
+<guibutton>Edit</guibutton> on the <guilabel>Talkers</guilabel> screen.  This
+<guilabel>Speed</guilabel> setting on the <guilabel>Audio</guilabel> screen
+is in addition to the talker speed setting and generally can be used
+even if the talker does not support a speed setting.  For this speed setting
+to work, you must have the <command>sox</command>
+utility installed on your system (Debian users: 
+<command>apt-get install sox</command>).  Also, this speed setting is ignored
+when speaking text containing SSML.  (See <xref linkend="ssml" />)</para></note>
+
+<note><para>The list of ALSA devices includes all the ALSA PCM devices and
+plugins configured in your system.  Many of the choices will not work.
+You must experiment to find a device that works for you.  If in doubt,
+choose <guilabel>default</guilabel>.</para></note>
+
+</sect1>
+
+<!-- ...................................................................... -->
+
+<sect1 id="interruption">
+<title>Text Interruption Settings</title>
+
+<para>When you click the <guilabel>Interruption</guilabel> tab in <command>kttsmgr</command>,
+the <guilabel>Interruption</guilabel> screen appears.</para>
+
+<para>
+<screenshot>
+<screeninfo>The &kde; Text-to-Speech Manager (Interruption tab).</screeninfo>
+	<mediaobjectco>
+		<imageobjectco>
+			<areaspec units="calspair">
+				<area id="pt-interruption-1" coords="1 1"/>
+				<area id="pt-interruption-2" coords="1 1"/>
+				<area id="pt-interruption-3" coords="1 1"/>
+				<area id="pt-interruption-4" coords="1 1"/>
+			</areaspec>
+			<imageobject>
+				<imagedata fileref="interruption.png" format="PNG"/>
+			</imageobject>
+		</imageobjectco>
+		<textobject>
+			<phrase>The &kde; Text-to-Speech Manager (Interruption tab)</phrase>
+		</textobject>
+	</mediaobjectco>
+</screenshot>
+</para>
+
+<para>This screen permits you to specify special actions to be taken whenever
+a text job is interrupted by another, higher priority, message.  There are
+four kinds of speech jobs that &ktts; handles:
+<itemizedlist>
+<listitem><para>Regular text.</para></listitem>
+<listitem><para>Messages.</para></listitem>
+<listitem><para>Warnings.</para></listitem>
+<listitem><para>Screen Reader Output.</para></listitem>
+</itemizedlist>
+</para>
+
+<para>Screen Reader Output has the highest priority.  It is reserved for use
+by Screen Reader applications.  Screen Reader Output preempts all other
+messages, causing those jobs to pause.  Once the Screen Reader Output has
+been spoken, the preempted jobs will automatically resume.
+</para>
+
+<para>Warnings are the next highest priority.  It is reserved for high-priority
+messages, such as "CPU is over-heating."  A Warning will preempt Messages
+and regular text, causing those jobs to pause.  Once the Warning has been
+spoken, the preempted jobs will automatically resume.</para>
+
+<para>Messages are the next highest priority.  A Message will preempt regular
+text jobs.  &kmouth; is an example of an application that uses Messages.
+For example, while reading out long text from a web page,
+&kmouth; can be used to greet someone who walks into the room.</para>
+
+<para>All four kinds of jobs are queues, except for Screen Reader Output.
+If a Screen Reader Output is sent from an application while
+&ktts; is speaking another Screen Reader Output, the speaking message 
+is stopped and discarded.</para>
+
+<para>When a text job is interrupted by a Message, Warning, or Screen Reader Output,
+&ktts; will add the audio outputs on this screen to the stream.</para>
+
+<para>
+<calloutlist>
+<callout arearefs="pt-interruption-1"><para>This message is spoken whenever a regular text job is interrupted.</para></callout>
+<callout arearefs="pt-interruption-2"><para>This audio file is sounded whenever a regular text job is interrupted.  If both a <guilabel>Pre-sound</guilabel>
+and a <guilabel>Pre-message</guilabel> are specified, the 
+<guilabel>Pre-sound</guilabel> is sounded before the <guilabel>Pre-message</guilabel>.</para></callout>
+<callout arearefs="pt-interruption-3"><para>This message is spoken whenever an
+interrupted text job resumes.</para></callout>
+<callout arearefs="pt-interruption-4"><para>This audio file is sounded whenever an
+interrupted text job resumes.  It is sounded last.</para></callout>
+</calloutlist>
+</para>
+
+<note><para>The settings on this screen apply only to regular text jobs.
+Messages, Warnings, and Screen Reader Outputs have no special actions when
+they are preempted by a higher-priority message.</para></note>
+
+</sect1>
+
+<!-- ...................................................................... -->
+
+
+<sect1 id="web">
+<title>Speaking Text from Web Pages</title>
+
+<para>While running the &kde; &konqueror; web browser, you can speak the text
+of the web page displayed.  First ensure that &ktts; is running.
+Highlight the text you want spoken and choose
+<menuchoice>
+  <guisubmenu>Tools</guisubmenu>
+  <guisubmenu>Speak Text</guisubmenu>
+</menuchoice> on the main menu.
+<action>After a moment, the highlighted text should begin speaking.</action>
+</para>
+
+<tip><para>It is almost always a good idea to highlight the text on the
+web page you want spoken.  You can skip this step, but you will
+hear a lot of &HTML; headers and other invisible tags spoken.</para></tip>
+
+</sect1>
+
+<!-- ...................................................................... -->
+
+
+<sect1 id="kate">
+<title>Speaking Text from &kate; Text Editor</title>
+
+<para>While running the &kde; Advanced Text Editor (&kate;), you can speak the text
+displayed.  First ensure that &ktts; is running.
+Highlight the text you want spoken and choose
+<menuchoice>
+  <guisubmenu>Tools</guisubmenu>
+  <guisubmenu>Speak Text</guisubmenu>
+</menuchoice> on the main menu.
+<action>After a moment, the highlighted text should begin speaking.</action>
+</para>
+
+<tip><para>You do not have to first highlight text.  In this case, the entire
+file will be spoken.</para></tip>
+
+<tip><para>This also works when &kate; is running embedded in another application,
+such as &konqueror; or &quanta;.</para></tip>
+
+</sect1>
+
+<!-- ...................................................................... -->
+
+<sect1 id="knotify">
+<title>Speaking Notifications (KNotify)</title>
+
+<para>KNotify is the notification subsystem within &kde;, which alerts you
+to events you configure within the &kde; system.  You can configure
+&ktts; to speak text notifications.</para>
+
+<para>For example, &konversation;, a &kde; IRC application, permits you
+to configure a wide variety of notifications.  For instance, you can tell
+&konversation; to notify you whenever a message appears in an IRC channel
+with your nickname in it.  Together with &ktts; you can
+have &kde; speak the text of the IRC message to you.</para>
+
+<para>In general, if a &kde; application supports KNotify, a
+<guilabel>Notifications</guilabel> menu item will appear under the
+application's <guilabel>Settings</guilabel> menu.  The specifics for configuring
+each application with KNotify vary from application to application.</para>
+
+<para>To enable &ktts; to speak KNotify text notifications,
+start <command>kttsmgr</command> and click the <guilabel>Notifications</guilabel> tab.
+The <guilabel>Notifications</guilabel> screen appears.</para>
+
+<para>
+<screenshot>
+<screeninfo>The &kde; Text-to-Speech Manager (Notifications tab).</screeninfo>
+	<mediaobjectco>
+		<imageobjectco>
+			<areaspec units="calspair">
+				<area id="pt-notify-1" coords="1 1"/>
+				<area id="pt-notify-2" coords="1 1"/>
+				<area id="pt-notify-3" coords="1 1"/>
+				<area id="pt-notify-4" coords="1 1"/>
+				<area id="pt-notify-5" coords="1 1"/>
+				<area id="pt-notify-6" coords="1 1"/>
+				<area id="pt-notify-7" coords="1 1"/>
+				<area id="pt-notify-8" coords="1 1"/>
+				<area id="pt-notify-9" coords="1 1"/>
+				<area id="pt-notify-10" coords="1 1"/>
+			</areaspec>
+			<imageobject>
+				<imagedata fileref="notifications.png" format="PNG"/>
+			</imageobject>
+		</imageobjectco>
+		<textobject>
+			<phrase>The &kde; Text-to-Speech Manager (Notification tab)</phrase>
+		</textobject>
+	</mediaobjectco>
+</screenshot>
+</para>
+
+<para>
+<calloutlist>
+<callout arearefs="pt-notify-1"><para>Check this box to enable speaking of
+&kde; notifications.  If unchecked, everything else on this screen is disabled
+and &ktts; does not speak any notifications.</para></callout>
+<callout arearefs="pt-notify-2"><para>When checked, any application
+that sends an event with a sound will not be spoken by &ktts;.</para></callout>
+<callout arearefs="pt-notify-3"><para>Use these buttons to add or delete
+application events from the list below.  When you click
+the <guibutton>Add</guibutton> button, a screen appears in which
+you select the application and event you want to add to the list.
+</para></callout>
+<callout arearefs="pt-notify-4"><para>This event will speak the message
+&konversation; sends when someone mentions your nickname in an Internet Relay Chat message.
+</para></callout>
+<callout arearefs="pt-notify-5"><para>For all other events coming from
+&konversation;, no action will be taken in &ktts;.</para></callout>
+<callout arearefs="pt-notify-6"><para>For all events not otherwise
+specified in the list, no action will be taken in &ktts;.</para></callout>
+<callout arearefs="pt-notify-7"><para>Use this box to specify what
+&ktts; should do when it receives an event.  Your choices are:</para>
+<para>
+<variablelist>
+<varlistentry>
+<term>Speak event name</term>
+<listitem><para>Speaks the name of the event; what you see listed in the
+event list on this screen.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>Speak the notification message</term>
+<listitem><para>Speaks the message as it is sent from the application.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>Do not speak the notification</term>
+<listitem><para>Does not speak this event at all.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>Speak custom text</term>
+<listitem><para>Speaks the text you enter in the box to the right.</para></listitem>
+</varlistentry>
+</variablelist>
+</para>
+</callout>
+<callout arearefs="pt-notify-8"><para>If the action is
+<guilabel>Speak custom text</guilabel>, enter the text of the message
+you would like spoken here.  Within the message, you may use the following
+substitution strings:</para>
+<para>
+<variablelist>
+<varlistentry>
+<term>%e</term>
+<listitem><para>The name of the event</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>%a</term>
+<listitem><para>The name of the application that sent the event</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>%m</term>
+<listitem><para>The message the application sent</para></listitem>
+</varlistentry>
+</variablelist>
+</para>
+</callout>
+<callout arearefs="pt-notify-9"><para>Test the message by clicking here.</para></callout>
+<callout arearefs="pt-notify-10"><para>You may specify the attributes of the
+desired talker to speak the notification message here.
+<command><userinput>default</userinput></command>
+will use the topmost talker listed in the <guilabel>Talkers</guilabel>
+screen.  See <xref linkend="selecttalker" />.
+</para></callout>
+</calloutlist>
+</para>
+
+<para>Notice there are three levels of events.  If an action for a specific event
+of a specific application is specified, that action is taken.  Otherwise, if
+an action for all other events of a specific application is specified, that
+action is taken.  Otherwise, the action specified for all other events
+under <guilabel>Default (all other events)</guilabel> is taken.</para>
+
+<para>The event <guilabel>all notifications</guilabel>
+for application <guilabel>Default (all other events)</guilabel>
+may not be deleted from the list.  For the default all other events,
+you may specify the kind of notifications that are spoken, as follows:</para>
+
+<variablelist>
+<varlistentry>
+<term>none</term>
+<listitem><para>None will be spoken.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>notification dialogs</term>
+<listitem><para>Notifications that display a dialog on your screen, that you must then
+dismiss, will be spoken.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>passive popups</term>
+<listitem><para>Notifications that display a passive dialog on your screen,
+that automatically disappear after a moment, will be spoken.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>notification dialogs and passive popups</term>
+<listitem><para>Notifications that display on screen, passively or not,
+will be spoken.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>all notifications</term>
+<listitem><para>All notifications, regardless of whether they produce
+a display on screen, will be spoken.</para></listitem>
+</varlistentry>
+</variablelist>
+
+<tip><para>String Replacer filters are a good way to clean up messages
+sent from applications if they are mispronounced or misspoken in 
+&ktts;.  The <filename>kmail.xml</filename> file, which
+comes with &ktts;, is a good example.  It removes <command>br</command>,
+and <command>b</command> tags from the &kmail; notification messages and also removes the
+phrase <command>/local/inbox/</command>, since this
+may be safely assumed in most cases.  See <xref linkend="stringreplacer" />.
+</para></tip>
+
+<para>Use the <guibutton>Save</guibutton> button to save your
+notification settings to a file.  Use the <guibutton>Load</guibutton>
+button to load saved settings from a file.  The loaded events are merged
+with existing events in the list.  If you want to start with
+an empty event list, click the <guibutton>Clear</guibutton>
+button first.  All events except for <guilabel>all notifications</guilabel>
+will be erased.</para>
+
+<note><para>Be sure to click <guibutton>Apply</guibutton>
+or <guibutton>OK</guibutton> to save your settings.</para></note>
+
+</sect1>
+
+<!-- ...................................................................... -->
+
+<sect1 id="ssml">
+<title>SSML</title>
+
+<para>The Speech Synthesis Markup Language (SSML) is a W3C standard
+for marking up text for speech output.  It provides tags for controlling
+voices, rate of speech, volume, gender, and pitch (tone).  It also
+provides tags for controlling how words are spoken, for instance
+spelling out abbreviations.  SSML is part of the VoiceXML specification,
+which is also a W3C standard.</para>
+
+<para>At this time, &ktts; provides limited and very basic support for
+SSML.  It currently has the following restrictions.</para>
+
+<itemizedlist>
+<listitem><para>Works only with the Festival Interactive and Hadifix Talkers.</para></listitem>
+<listitem><para>You must install the <command>rab_diphone</command>
+(British male) voice, as this is the default voice Festival uses when speaking
+SSML.</para></listitem>
+<listitem><para>The <guilabel>Speed</guilabel> setting on the <guilabel>Audio</guilabel>
+screen is ignored when speaking text containing SSML.</para></listitem>
+<listitem><para>If the <guilabel>Speed</guilabel> or <guilabel>Pitch</guilabel>
+settings in the Festival configuration dialog are not set to 100%, it
+will usually cause the SSML text to be spoken in a monotone.</para></listitem>
+</itemizedlist>
+
+<para>The following sample text can be used to experiment with SSML.</para>
+
+<programlisting><![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE speak PUBLIC "-//W3C//DTD SYNTHESIS 1.0//EN"
+    "http://www.w3.org/TR/speech-synthesis/synthesis.dtd">
+
+<speak version="1.0" xml:lang="en-US">
+    <prosody pitch="low">
+        Who's been sleeping in my bed?
+    </prosody>
+    said papa bear.
+    <prosody pitch="medium">
+        Who's been sleeping in my bed?
+    </prosody>
+    said momma bear.
+    <prosody pitch="high">
+        Who's been sleeping in my bed?
+    </prosody>
+    said baby bear.
+</speak>
+]]></programlisting>
+
+<para>More robust support for SSML is planned for the next version of
+&ktts;.
+</para>
+
+</sect1>
+
+<!-- ...................................................................... -->
+
+<sect1 id="filters">
+<title>Filters (Advanced)</title>
+
+<para>Filters are an advanced feature of &ktts;.  For the
+basic operation of &ktts;, they are not needed.</para>
+
+<para>Filters are used to pre-process text before it is sent to the
+speech synthesis engine.  They are useful for enhancing speech,
+substituting for misspoken words or abbreviations, choosing the
+appropriate language and talker to do the speaking, or working around 
+certain limitations of speech synthesizers and their voices.</para>
+
+<!-- ...................................................................... -->
+
+<sect2 id="msg-types">
+<title>Types of &ktts; Messages</title>
+
+<para>To understand how to use filters, it is
+helpful to first understand how text is processed by &ktts;.
+Text spoken by &ktts; is of four possible types.</para>
+
+<para>
+<itemizedlist>
+<listitem><para>Screen Reader Output.</para></listitem>
+<listitem><para>Warnings.</para></listitem>
+<listitem><para>Messages</para></listitem>
+<listitem><para>Text Jobs</para></listitem>
+</itemizedlist>
+</para>
+
+<para>The type is determined by the application that sends the text
+to &ktts;.</para>
+
+<para>Screen Reader Output has the highest priority.  It is reserved for use
+by Screen Reader applications.  Screen Reader Output preempts all other
+messages, causing those jobs to pause.  Once the Screen Reader Output has
+been spoken, the preempted messages will automatically resume.
+</para>
+
+<para>Warnings are the next highest priority.  It is reserved for high-priority
+messages, such as "CPU is over-heating."  A Warning will preempt Messages
+and regular text, causing those jobs to pause.  Once the Warning has been
+spoken, the preempted messages will automatically resume.</para>
+
+<para>Messages are the next highest priority.  A Message will preempt regular
+text jobs.  &kmouth; is an example of an application that uses Messages.
+For example, while reading out long text from a web page,
+&kmouth; can be used to greet someone who walks into the room.
+&kde; Notifications are also Messages  (see <xref linkend="knotify" />).</para>
+
+<para>The rest are ordinary Text Jobs.  Any job you initiate from the
+<guilabel>Jobs</guilabel> tab is a Text Job.  KSayit is an example
+of an application that uses Text Jobs.  Text Jobs are intended for
+longer speech output that is not urgent.</para>
+
+<para>All four kinds of jobs are queues, except for Screen Reader Output.
+If a Screen Reader Output is sent from an application while
+&ktts; is speaking another Screen Reader Output, the speaking message 
+is stopped and discarded.</para>
+
+</sect2>
+
+<!-- ...................................................................... -->
+
+<sect2 id="filter-types">
+<title>Types of Filters</title>
+
+<para>The first thing you must know about filters is that they are
+never applied to Screen Reader Output.  They are applied to
+Warnings, Messages, and Text jobs, and also &kde; notifications (KNotify).</para>
+
+<para>There are two kinds of filters --
+ordinary filters and Sentence Boundary Detector (SBD) filters.
+SBDs break text up into individual sentences.  This allows
+&ktts; to begin speaking faster because it need only
+synthesize the first sentence; not the entire Text Job.
+It also permits you to advance or rewind by sentence in the
+<guilabel>Jobs</guilabel> tab, or to stop or pause Text Jobs when
+the speech synthesizer does not directly support stopping of speech.
+</para>
+
+<para>Ordinary filters process the text and pass it on to the
+next filter.  There are currently three kinds of ordinary filters.
+</para>
+
+<para>
+<itemizedlist>
+<listitem><para>String Replacers.</para></listitem>
+<listitem><para>&XML; Transformers</para></listitem>
+<listitem><para>Talker Choosers.</para></listitem>
+</itemizedlist>
+</para>
+
+<note><para>Filters are implemented using a plugin architecture.
+In the future, there may be additional kinds of filters.</para></note>
+
+<para>String Replacer filters substitute pieces of text with
+other text.  The replaced pieces are matched either as words or
+as regular expressions.  &ktts; comes with pre-defined
+String Replacer filters for speaking abbreviations, speaking
+chat emoticons, such as ":-)", or reformatting notification
+messages from &konversation; or &kmail; into a more understandable
+form.
+</para>
+
+<para>&XML; Transformers use an &XML; Style Language - Transforms (XSLT)
+file to convert &XML; of one format to another format.
+&ktts; comes with a couple of XSLT files for converting
+&XHTML; into SSML.
+</para>
+
+<para>Talker Choosers permit you redirect jobs to a talker 
+based on the contents of the text, or upon the application that sent it
+to &ktts;.  For example, if you have configured a female talker
+in the <guilabel>Talkers</guilabel> tab, you can direct text coming from
+KSayIt to that talker.  See <xref linkend="configure-plugin" />.
+</para>
+
+<para>Each of these kinds of filters has configurable rules for when
+the filter should apply itself to the text to be spoken.  If the
+filter determines that it should not apply itself, the text
+is passed on to the next filter unaltered.</para>
+
+<para>When a Text Job, Message, Warning, or &kde; Notification message is sent to &ktts;,
+it passes through each of the enabled filters you have configured in the
+screen below.  The order is from top to bottom.  After passing through
+each of the ordinary filters listed in the top portion of the screen, Text Jobs
+are passed to the <guilabel>Sentence Boundary Detector</guilabel> (SBD) filters.
+(&kde; Notifications, Warnings, and Messages never pass through SBD filters.)
+Unlike ordinary filters, the first SBD filter that makes changes to the text
+stops any further filtering.
+</para>
+
+</sect2>
+
+<!-- ...................................................................... -->
+
+<sect2 id="configure-filters">
+<title>Configuring Filters</title>
+
+<para>To use filters, click the <guilabel>Filters</guilabel> tab in <command>kttsmgr</command>.</para>
+
+<para>
+    <screenshot>
+        <screeninfo>The &kde; Text-to-Speech Manager (Filters tab).</screeninfo>
+        <mediaobjectco>
+            <imageobjectco>
+                <areaspec units="calspair">
+                    <area id="pt-filters-1" coords="1 1"/>
+                    <area id="pt-filters-2" coords="1 1"/>
+                    <area id="pt-filters-3" coords="1 1"/>
+                    <area id="pt-filters-4" coords="1 1"/>
+                    <area id="pt-filters-5" coords="1 1"/>
+                    <area id="pt-filters-6" coords="1 1"/>
+                    <area id="pt-filters-7" coords="1 1"/>
+                    <area id="pt-filters-8" coords="1 1"/>
+                </areaspec>
+                <imageobject>
+                    <imagedata fileref="filters.png" format="PNG"/>
+                </imageobject>
+            </imageobjectco>
+            <textobject>
+                <phrase>The &kde; Text-to-Speech Manager (Filters tab)</phrase>
+            </textobject>
+        </mediaobjectco>
+    </screenshot>
+</para>
+
+<para>
+<calloutlist>
+<callout arearefs="pt-filters-1"><para>This is the list of configured ordinary filters.
+If unchecked, the filter is inactive and will be bypassed.
+Filters are applied in the order specified here, top to bottom.</para></callout>
+<callout arearefs="pt-filters-2"><para>Click here to add a new filter.  You will
+be prompted for the kind of filter to add.  After choosing the kind,
+see the configuration dialogs below.</para></callout>
+<callout arearefs="pt-filters-3"><para>Click here to remove a filter.</para></callout>
+<callout arearefs="pt-filters-4"><para>Click here to change the configuration
+of a filter.  See the configuration dialogs below.</para></callout>
+<callout arearefs="pt-filters-5"><para>Click these buttons to move a filter
+up or down in the list.</para></callout>
+<callout arearefs="pt-filters-6"><para>These are the Sentence Boundary Detector
+filters.  When you first start &ktts;, the Standard Sentence Boundary Detector
+is automatically configured for you.  You can change this filter's configuration,
+or add additional Sentence Boundary Detectors, but we advise beginners not
+to change them.</para></callout>
+<callout arearefs="pt-filters-7"><para>This drop-down button permits you
+to add, remove, edit, or change the order of Sentence Boundary Detector filters.</para></callout>
+<callout arearefs="pt-filters-8"><para>Be sure to click here, otherwise your
+settings will not take effect.</para></callout>
+</calloutlist>
+</para>
+
+</sect2>
+
+<!-- ...................................................................... -->
+
+<sect2 id="stringreplacer">
+<title>Configuring String Replacer Filters</title>
+
+<para>You configure String Replacer filters by supplying
+a list of words or regular expressions to be matched.
+When the matched words or regular expressions are found in the
+text, each is replaced by a substitute string you supply.
+Matching is case insensitive.</para>
+
+<para>
+    <screenshot>
+        <screeninfo>String Replacer</screeninfo>
+        <mediaobjectco>
+            <imageobjectco>
+                <areaspec units="calspair">
+                    <area id="pt-stringreplacer-1" coords="1 1"/>
+                    <area id="pt-stringreplacer-2" coords="1 1"/>
+                    <area id="pt-stringreplacer-3" coords="1 1"/>
+                    <area id="pt-stringreplacer-4" coords="1 1"/>
+                    <area id="pt-stringreplacer-5" coords="1 1"/>
+                    <area id="pt-stringreplacer-6" coords="1 1"/>
+                    <area id="pt-stringreplacer-7" coords="1 1"/>
+                    <area id="pt-stringreplacer-8" coords="1 1"/>
+                    <area id="pt-stringreplacer-9" coords="1 1"/>
+                </areaspec>
+                <imageobject>
+                    <imagedata fileref="stringreplacer.png" format="PNG"/>
+                </imageobject>
+            </imageobjectco>
+            <textobject>
+                <phrase>String Replacer</phrase>
+            </textobject>
+        </mediaobjectco>
+    </screenshot>
+</para>
+
+<para>
+<calloutlist>
+<callout arearefs="pt-stringreplacer-1"><para>Enter a name for your filter.  Use any
+name you like that distinquishes it from all other filters.</para></callout>
+<callout arearefs="pt-stringreplacer-2"><para>This is the list of words
+and regular expressions.  The filter searches for matches on each string in
+the <guilabel>Match</guilabel> column, replacing the matched string
+with the string in the <guilabel>Replace With</guilabel> column.  The list
+is processed in the order displayed, top to bottom.</para></callout>
+<callout arearefs="pt-stringreplacer-3"><para>Click here to add another word or
+regular expression to the list.</para></callout>
+<callout arearefs="pt-stringreplacer-4"><para>Click here to move the currently
+highlighted word or regular expression up or down in the list.</para></callout>
+<callout arearefs="pt-stringreplacer-5"><para>Click to change an existing word
+or regular expression in the list.</para></callout>
+<callout arearefs="pt-stringreplacer-6"><para>Click to remove the currently
+highlighted word or regular expression from the list.</para></callout>
+<callout arearefs="pt-stringreplacer-7"><para>Use these buttons to load
+a list of words or regular expression from a file, save the current list to
+a file, or clear the entire list.  When loading from a file, the items in the
+file are appended to the existing list.</para></callout>
+<callout arearefs="pt-stringreplacer-8"><para>If not blank, the filter will
+apply itself only if the job's talker language matches
+the language you enter here.  Click the button to display a list of languages.
+You may select more than one language by pressing
+<keycap>&Ctrl;</keycap> while clicking.</para></callout>
+<callout arearefs="pt-stringreplacer-9"><para>If not blank, the filter will
+apply itself only if the text came from one of the applications listed.
+You may enter more than one application separated by commas.
+Example: <command><userinput>konversation,kmail</userinput></command></para>
+<tip><para>You can discover the <guilabel>Application ID</guilabel>
+of running programs using the <command>&kdcop;</command> program.
+You should leave the &DCOP; numbers out.  For example, if &kdcop; shows
+an Application ID of <command>kopete-3432</command>, you would just
+enter <command><userinput>kopete</userinput></command>.</para></tip></callout>
+</calloutlist>
+</para>
+
+<para>The String Replacer filter will only apply itself to the text
+if all non-blank conditions are met in the 
+<guilabel>Apply This Filter When</guilabel> box.
+if all the boxes are blank, the filter will apply to all text.</para>
+
+<para>All matching is case insensitive.</para>
+
+<para>When matching words, the String Replacer filter internally uses a
+regular expression of the form <command>\s<userinput>word</userinput>\s</command>.
+In other words, the word must have word boundaries (spaces) on either side of it.</para>
+
+<para>A discussion on how to write regular expressions is outside the scope
+of this handbook.  If you have the &kde; Regular Expression editor installed,
+there is a button available on the <guilabel>Add</guilabel> or
+<guilabel>Edit</guilabel> screens that will assist you at
+constructing regular expressions.  The &kde; Regular Expression Editor is part
+of the <command>kdeutils</command> package.</para>
+
+<para>&ktts; comes with a few word list files, including a list
+of emoticons, such as ":-)", some abbreviations typically used in IRC or
+instant messaging applications, and a list of other abbreviations.
+There is also a list of special characters which the current version
+of the Polish Festival voice cannot handle.
+If you develop useful word lists of your own, use the <guibutton>Save</guibutton>
+button to save them to a file and send them to the
+&ktts; team for inclusion in the next version.</para>
+
+</sect2>
+
+<!-- ...................................................................... -->
+
+<sect2 id="xmltransformer">
+<title>Configuring &XML; Transformer Filters</title>
+
+<para>The &XML; Transformer filter uses XSLT files to transform &XML; from
+one format to another.  XSLT, the &XML; Style Language - Transforms, is a W3C
+standard language for performing such transformations.
+It can only be used on well-formed &XML;.  You must have the
+<command>xsltproc</command> utility installed.</para>
+
+<para>
+    <screenshot>
+        <screeninfo>&XML; Transformer</screeninfo>
+        <mediaobjectco>
+            <imageobjectco>
+                <areaspec units="calspair">
+                    <area id="pt-xmltransformer-1" coords="1 1"/>
+                    <area id="pt-xmltransformer-2" coords="1 1"/>
+                    <area id="pt-xmltransformer-3" coords="1 1"/>
+                    <area id="pt-xmltransformer-4" coords="1 1"/>
+                    <area id="pt-xmltransformer-5" coords="1 1"/>
+                </areaspec>
+                <imageobject>
+                    <imagedata fileref="xmltransformer.png" format="PNG"/>
+                </imageobject>
+            </imageobjectco>
+            <textobject>
+                <phrase>&XML; Transformer</phrase>
+            </textobject>
+        </mediaobjectco>
+    </screenshot>
+</para>
+
+<para>
+<calloutlist>
+<callout arearefs="pt-xmltransformer-1"><para>Enter a name for your filter.  Use any
+name you like that distinquishes it from all other filters.</para></callout>
+<callout arearefs="pt-xmltransformer-2"><para>Enter the full path
+to an existing XSLT file, which will perform the transformation.</para></callout>
+<callout arearefs="pt-xmltransformer-3"><para>Specify the path to the
+<command>xsltproc</command> utility.  If xsltproc is in your environment
+PATH, simply enter <command><userinput>xsltproc</userinput></command>.</para></callout>
+<callout arearefs="pt-xmltransformer-4"><para>If not blank, the filter
+will apply itself only if the &XML; has the specified root element
+or a <command><![CDATA[<!DOCTYPE]]></command> specification
+beginning with the entered string. This distinquishes one
+form of &XML; from another.  For example,
+<command><userinput>html</userinput></command> in the
+<guilabel>DOCTYPE</guilabel> box will match
+<command><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">]]></command>.
+</para></callout>
+<callout arearefs="pt-xmltransformer-5"><para>If not blank, the filter will
+apply itself only if the text came from one of the applications listed.
+You may enter more than one application separated by commas.
+Example: <command><userinput>konversation,kmail</userinput></command></para>
+<tip><para>You can discover the <guilabel>Application ID</guilabel>
+of running programs using the <command>&kdcop;</command> program.
+You should leave the &DCOP; numbers out.  For example, if &kdcop; shows
+an Application ID of <command>kopete-3432</command>, you would just
+enter <command><userinput>kopete</userinput></command>.</para></tip></callout>
+</calloutlist>
+</para>
+
+<para>The &XML; Transformer filter will only apply itself to the text
+if the specified root element or DOCTYPE are met and if the 
+application ID is met in the 
+<guilabel>Apply This Filter When</guilabel> box.  If an item in this
+box is blank, the test is not performed, so if all the
+boxes are blank, the filter will apply itself to all text.  However,
+you should fill in at least one box, since many text jobs will not be in
+&XML; format.</para>
+
+</sect2>
+
+<!-- ...................................................................... -->
+
+<sect2 id="talkerchooser">
+<title>Configuring Talker Chooser Filters</title>
+
+<para>Talker Chooser filters are used to direct the text to a desired
+talker configured in the <guilabel>Talker</guilabel> tab, or to any
+talker having specified attributes.  For example,
+you can specify that text coming from <command>kmail</command>
+should be spoken using a talker configured with a female voice.
+See <xref linkend="configure-plugin" />.</para>
+
+<para>Just before &ktts; begins sending text to each of the
+filters, it picks a talker to speak the text.  The talker chosen is
+based on the talker attributes specified by the application that sent
+the text to &ktts; and the attributes of the talkers that
+you have configured on the <guilabel>Talkers</guilabel> tab.
+The Talker Chooser filter permits you to override the
+chosen talker.
+</para>
+
+<para>
+    <screenshot>
+        <screeninfo>Talker Chooser</screeninfo>
+        <mediaobjectco>
+            <imageobjectco>
+                <areaspec units="calspair">
+                    <area id="pt-talkerchooser-1" coords="1 1"/>
+                    <area id="pt-talkerchooser-2" coords="1 1"/>
+                    <area id="pt-talkerchooser-3" coords="1 1"/>
+                    <area id="pt-talkerchooser-4" coords="1 1"/>
+                    <area id="pt-talkerchooser-5" coords="1 1"/>
+                </areaspec>
+                <imageobject>
+                    <imagedata fileref="talkerchooser.png" format="PNG"/>
+                </imageobject>
+            </imageobjectco>
+            <textobject>
+                <phrase>Talker Chooser</phrase>
+            </textobject>
+        </mediaobjectco>
+    </screenshot>
+</para>
+
+<para>
+<calloutlist>
+<callout arearefs="pt-talkerchooser-1"><para>Enter a name for your filter.  Use any
+name you like that distinquishes it from all other filters.</para></callout>
+<callout arearefs="pt-talkerchooser-2"><para>If not blank, the filter will apply
+itself only if the text contains the entered regular expression.  If it is installed,
+click the browse button to launch the &kde; Regular Expression Editor to assist you at entering
+the regular expression.</para>
+<tip><para>For better performance, try to "anchor" the regular expression to the
+start of the string.  In other words, start your regular expression with
+<command><userinput><![CDATA[^]]></userinput></command>.</para></tip></callout>
+<callout arearefs="pt-talkerchooser-3"><para>If not blank, the filter will
+apply itself only if the text came from one of the applications listed.
+You may enter more than one application separated by commas.
+Example: <command><userinput>konversation,kmail</userinput></command></para>
+<tip><para>You can discover the <guilabel>Application ID</guilabel>
+of running programs using the <command>&kdcop;</command> program.
+You should leave the &DCOP; numbers out.  For example, if &kdcop; shows
+an Application ID of <command>kopete-3432</command>, you would just
+enter <command><userinput>kopete</userinput></command>.</para></tip></callout>
+<callout arearefs="pt-talkerchooser-4"><para>Specify the attributes of the
+talker you prefer to speak the text here.  If the text meets the filter
+conditions above, a talker will be chosen that most closely matches
+the attributes you specify here.  Click the button at the right to
+display the <guilabel>Select Talker</guilabel> screen.
+See <xref linkend="selecttalker" />.</para></callout>
+<callout arearefs="pt-talkerchooser-5"><para>Use these buttons
+to save your Talker Chooser settings, load settings from a saved file,
+or clear all the settings.</para></callout>
+</calloutlist>
+</para>
+
+<para>The Talker Chooser filter will only apply itself to the text
+if all non-blank conditions are met in the 
+<guilabel>Apply This Filter When</guilabel> box.  You must fill in
+at least one of the boxes.</para>
+
+<para>The easiest way to learn how to configure Talker Choosers is
+to experiment.  Disable the Talker Chooser and submit some text.
+In the <guilabel>Jobs</guilabel> tab, note the talker that
+&ktts; chooses.  Click the <guibutton>Change Talker</guibutton>
+button, enter some attributes, and try again to see how the choice is affected.
+Of course, you must have more than one talker configured for
+the Talker Chooser to do anything.</para>
+
+</sect2>
+
+<!-- ...................................................................... -->
+
+<sect2 id="sbd">
+<title>Configuring Sentence Boundary Detector Filters</title>
+
+<para>Sentence Boundary Detector (SBD) filters break text up into individual sentences.
+This is important because it</para>
+
+<itemizedlist>
+<listitem><para>allows &ktts; to begin speaking faster
+because it need only synthesize the first sentence, rather than the entire
+block of text, which might be very long, and</para></listitem>
+<listitem><para>allows you to rewind and advance by sentences in the
+<guilabel>Jobs</guilabel> tab, and</para></listitem>
+<listitem><para>allows you to pause or stop Text Jobs in the
+<guilabel>Jobs</guilabel> tab even if the speech synthesizer is not
+capable of being stopped.</para></listitem>
+</itemizedlist>
+
+<para>For these reasons, the Standard Sentence Boundary Detector filter
+is automatically configured the first time you run <command>kttsmgr</command>
+and cannot be disabled (although you can remove it).  We advise you
+not to modify this filter unless you know what you are doing.</para>
+
+<para>You can, however, add additional SBD filters to solve certain
+problems.  For example, as of February 2005, the Polish Festival voice
+has the annoying attribute of speaking sentence punctuation.  It will
+speak the periods at the end of each sentence, for instance.  You cannot solve this problem
+by creating a String Replacer filter to remove the sentence punctuation,
+because doing so will prevent the Standard SBD from recognizing any
+sentences.  Instead, you can create a modified version of the
+Standard SBD that recognizes sentences while simultaneously removing
+the sentence punctuation.  To do this, add an SBD filter and use the
+<guibutton>Load</guibutton> button to load the <filename>polish_festival_sbdrc</filename>
+file that comes with &ktts;.</para>
+
+<para>SBD filters work by matching an end-of-sentence regular expression
+and inserting Tab (decimal 8) characters at the sentence boundaries.
+(All Tab characters are automatically stripped from text before filtering begins.)
+Note that the Standard SBD preserves the sentence punctuation.
+</para>
+
+<para>SBD filters are never applied to &kde; Notification messages (knotify),
+Warnings, Messages, or Screen Reader Outputs.</para>
+
+<para>If you accidentally remove the Standard Sentence Boundary Detectory filter,
+you can get it back by loading the <filename>standard_sbdrc</filename> file,
+which comes with &ktts;.</para>
+
+</sect2>
+
+</sect1>
+
+<!-- ...................................................................... -->
+
+<sect1 id="selecttalker">
+<title>Selecting Talkers (Advanced)</title>
+
+<para>You can configure
+any number of talkers in the <guilabel>Talkers</guilabel> tab.
+See <xref linkend="configure-plugin" />.  When applications send text
+to &ktts;, they may specify the attributes of a desired
+talker to speak the text.  &ktts; will pick the closest
+matching talker from among the talkers you have configured to satisfy
+the application's request.  For example, an application might request
+the text be spoken by an English female voice.  If you have configured
+a talker with English language and female gender, that talker will be used.
+If you have configured all English male talkers, one of those talkers
+will be used.  If an application specifies no attributes,
+the default (topmost) talker listed in the <guilabel>Talkers</guilabel>
+tab is used.</para>
+
+<para>When applications specify the attributes of the desired talker,
+they may indicate that certain attributes are "preferred" over other
+attributes.  For example, an application may specify that it wishes
+that a female loud voice speak the text, and that the loud attribute is
+"preferred" over the female attribute.  If you had a female soft talker
+and a male loud talker configured, &ktts; will choose the male
+loud talker to do the speaking.  Since language is a critical parameter
+in making speech understandable, it is always a "preferred" attribute.</para>
+
+<para>Using the <guilabel>Select Talker</guilabel> screen, you may
+override application talker settings.  The screen is displayed</para>
+
+<itemizedlist>
+<listitem><para>when you click the <guibutton>Change Talker</guibutton>
+button on the <guilabel>Jobs</guilabel> tab, or</para></listitem>
+<listitem><para>when you click the <guilabel>Talker</guilabel> button
+on the <guilabel>Filter Configuration</guilabel> dialog for
+a Talker Chooser filter, or</para></listitem>
+<listitem><para>when you click the <guilabel>Talker</guilabel> button
+on the <guilabel>Notifications</guilabel> tab.</para></listitem>
+</itemizedlist>
+
+<para>
+    <screenshot>
+        <screeninfo>Select Talker</screeninfo>
+        <mediaobjectco>
+            <imageobjectco>
+                <areaspec units="calspair">
+                    <area id="pt-selecttalker-1" coords="1 1"/>
+                    <area id="pt-selecttalker-2" coords="1 1"/>
+                    <area id="pt-selecttalker-3" coords="1 1"/>
+                    <area id="pt-selecttalker-4" coords="1 1"/>
+                    <area id="pt-selecttalker-5" coords="1 1"/>
+                </areaspec>
+                <imageobject>
+                    <imagedata fileref="selecttalker.png" format="PNG"/>
+                </imageobject>
+            </imageobjectco>
+            <textobject>
+                <phrase>Select Talker</phrase>
+            </textobject>
+        </mediaobjectco>
+    </screenshot>
+</para>
+
+<para>The screen offers three methods to specify desired talker
+attributes:</para>
+
+<itemizedlist>
+<listitem><para>Use the default talker (topmost in the
+<guilabel>Talkers</guilabel> tab).  In other words, no talker attributes
+are specified.</para></listitem>
+<listitem><para>Use the closest matching talker having one or more specified attributes.</para></listitem>
+<listitem><para>Use the closest matching talker having all the attributes
+of a configured talker.  If you don't delete or modify the talker's settings,
+&ktts; will pick that specific talker.  If you delete or modify the
+talker's settings, then &ktts; will pick the closest matching talker
+having the talker's original attributes.</para></listitem>
+</itemizedlist>
+
+<para>
+<calloutlist>
+<callout arearefs="pt-selecttalker-1"><para>Choose the method for entering
+the desired talker attributes by clicking one of these radio buttons.</para></callout>
+<callout arearefs="pt-selecttalker-2"><para>Choose the attributes of the desired
+talker here.  Leave an attribute blank if you do not care about that attribute.</para></callout>
+<callout arearefs="pt-selecttalker-3"><para>Check this box if you wish the
+attribute to be "preferred" over other attributes.  You may check more than one
+box.</para></callout>
+<callout arearefs="pt-selecttalker-4"><para>Since language is a critical factor
+in making speech understandable, it is always a preferred attribute.  It is rare
+that you will use this attribute.  The only time you might specify the language
+attribute is when you know a specific application sends text in a language
+different from your desktop.</para></callout>
+<callout arearefs="pt-selecttalker-5"><para>This is a list of the talkers
+you currently have configured in &ktts;.  By choosing one of these,
+in effect, you are specifying all the attributes of that talker.  If that
+talker is still configured when text is sent, you'll get an exact match and that
+talker will be chosen.  However, if you later delete the talker, or modify
+its settings, it might not be the chosen talker anymore.  The talker
+most closely matching the original attributes will be chosen.</para></callout>
+</calloutlist>
+</para>
+
+<para>The <guilabel>Language</guilabel> attribute is special because
+text will probably be unintelligible if spoken by a talker that
+speaks a language different from the text.  Therefore, language
+is automatically a "preferred" attribute. If you specify a language,
+it will override the chosen language, but if you leave it blank,
+the existing language setting will be used.  If the application that sent the
+text to &ktts; did not specify a language, &ktts; assigns
+the language of the topmost talker you have configured in the
+<guilabel>Talkers</guilabel> tab.  In other words, the topmost
+talker is assumed to speak the language of your desktop.</para>
+
+<tip><para>To clear all the attributes in the
+<guilabel>Use closest matching Talker having</guilabel> section,
+first click the <guilabel>Use default Talker</guilabel> radio button,
+then click the <guilabel>Use closest matching Talker having</guilabel>
+radio button.</para></tip>
+
+</sect1>
+
+</chapter>
+
+<!-- ====================================================================== -->
+
+<chapter id="commands">
+<title>Command Reference</title>
+
+<!-- (OPTIONAL, BUT RECOMMENDED) This chapter should list all of the
+application windows and their menubar and toolbar commands for easy reference.
+Also include any keys that have a special function but have no equivalent in the
+menus or toolbars. This may not be necessary for small apps or apps with no tool
+or menu bars. -->
+
+<para>TODO</para>
+
+</chapter>
+
+<!--
+
+<sect1 id="kapp-mainwindow">
+<title>The main &ktts; window</title>
+
+<sect2>
+<title>The File Menu</title>
+<para>
+<variablelist>
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>New</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Creates a new document</action></para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Save</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Saves the document</action></para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Quit</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Quits</action> &ktts;</para></listitem>
+</varlistentry>
+</variablelist>
+</para>
+
+</sect2>
+
+-->
+
+<!-- ====================================================================== -->
+
+<chapter id="developers">
+<title>Developer's Guide to &ktts;</title>
+
+<para>&ktts; has two Application Programmer Interfaces (APIs):
+</para>
+
+<itemizedlist>
+<listitem><para>The &kde; Text-to-Speech API, which is used by application
+programmers to give their applications TTS capabilities.  Applications
+communicate with KTTSD via &DCOP;.</para></listitem>
+<listitem><para>The KTTSD Plugin API, which is used to add speech
+synthesis plugins to KTTSD so that &ktts; will work with
+a new speech synthesis engine.</para></listitem>
+</itemizedlist>
+
+<para>The following section gives a short description of the &kde; Text-to-Speech API
+&DCOP; Interface.
+Full documentation for both APIs is available online at the
+<ulink url="http://accessibility.kde.org/developer/kttsd/">
+&kde; Accessibility</ulink> web site (http://accessibility.kde.org).
+</para>
+
+
+<!-- ...................................................................... -->
+
+
+<sect1 id="dcop-interface">
+<title>The &ktts; &DCOP; Interface</title>
+
+<para>Applications communicate requests for Text-to-Speech services via the
+&kde; &DCOP; interface to program <command>kttsd</command> object <command>KSpeech</command>.
+</para>
+
+<para>Enter the following commands in a &konsole;.</para>
+
+<para>If KTTSD is not already running</para>
+
+<para><userinput>kttsd</userinput></para>
+
+<para>To queue a text job to be spoken</para>
+
+<para><userinput>dcop kttsd KSpeech setText "<replaceable>text</replaceable>"  "<replaceable>talker</replaceable>"</userinput></para>
+
+<para>where <userinput><replaceable>text</replaceable></userinput> is the text to be spoken, and <userinput><replaceable>talker</replaceable></userinput> is a language code
+such as <userinput><replaceable>en</replaceable></userinput>, <userinput><replaceable>cy</replaceable></userinput>, &etc;  This command does
+not speak the text; instead it queues a text job for speaking.</para>
+
+<para>Example.</para>
+
+<para><userinput>dcop kttsd KSpeech setText "This is a test." "en"</userinput></para>
+
+<para>To speak the last queued text job</para>
+
+<para><userinput>dcop kttsd KSpeech startText <replaceable>0</replaceable></userinput></para>
+
+<para>In this case, <userinput>0</userinput> refers to the last text job queued.  
+You may also specify a specific job number.  (If no job number is given, a <userinput>0</userinput> is required.)</para>
+
+<para>To stop the currently speaking text job</para>
+
+<para><userinput>dcop kttsd KSpeech stopText 0</userinput></para>
+
+<para>Depending upon the speech plugin used, speaking may not immediately stop.</para>
+
+<para>There are many more commands that can be sent.  To see a list of possible
+commands,</para>
+
+<para><userinput>dcop kttsd KSpeech</userinput></para>
+
+<para>or read the 
+<ulink url="http://accessibility.kde.org/developer/kttsd/">
+&kde; Text-to-Speech API</ulink> online.</para>
+
+</sect1>
+
+</chapter>
+
+<!-- ====================================================================== -->
+
+<chapter id="faq">
+<title>Questions and Answers</title>
+
+<!-- (OPTIONAL but recommended) This chapter should include all of the silly
+(and not-so-silly) newbie questions that fill up your mailbox. This chapter
+should be reserved for BRIEF questions and answers! If one question uses more
+than a page or so then it should probably be part of the
+"Using this Application" chapter instead. You should use links to
+cross-reference questions to the parts of your documentation that answer them.
+This is also a great place to provide pointers to other FAQ's if your users
+must do some complicated configuration on other programs in order for your
+application work. -->
+
+&reporting.bugs;
+&updating.documentation;
+
+<qandaset id="faqlist">
+<qandaentry>
+<question>
+<para><command>kttsmgr</command> immediately crashes when I start it.  I
+compiled with debug support and I don't even get a backtrace.</para>
+</question>
+<answer>
+<para>GStreamer has crashed taking &ktts; down with it.  You most
+likely need to "register" GStreamer.  For GStreamer 0.8x, the command is
+<command>gst-register-0.8</command>.  If this doesn't solve the problem,
+you may have an incompatible version of GStreamer installed.  You could
+try upgrading or uninstalling GStreamer.</para>
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>ALSA audio output is not working if I am playing music in another
+application at the same time.  When I pause a text job, &ktts;
+freezes.  I notice "unable to open PCM" in the &konsole; output.</para>
+</question>
+<answer>
+<para>You have the ALSA device contention problem, which prevents opening
+more than one PCM device at one time.  See the ALSA website (dmix) for
+possible solutions. <ulink url="www.alsa-project.org">www.alsa-project.org</ulink>
+</para>
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>I need to start over.  How do I get &ktts; completely terminated?</para>
+</question>
+<answer>
+<para>Enter the following commands in a &konsole;:
+<programlisting>
+killall kttsd
+killall kttsmgr
+</programlisting>
+</para>
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>How can I see debugging output from <command>kttsd</command>?</para>
+</question>
+<answer>
+<para>Open two &konsole; windows.  First start <command>kttsd</command> in one
+window, then start <command>kttsmgr</command> in the second.</para>
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>I have an additional Festival voice I downloaded from the Internet.
+I installed it, and I can use it in Festival, but it does not show up in <command>kttsmgr</command>.</para>
+</question>
+<answer>
+<para>Edit file <command>$KDEHOME/share/apps/kttsd/festivalint/voices</command> to
+add the new voice.  The other entries can be used as a guide.  If you
+successfully add a voice, please send a patch to the developers along
+with the &URL; from which you obtained the voice file.</para>
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>None of the supported speech synthesizers support the language I need.
+Where can I get a synth for my language?</para>
+</question>
+<answer>
+<para>Google(tm) is your friend.  This 
+<ulink url="http://tcts.fpms.ac.be/synthesis/mbrola/mbrtts.html">link</ulink>
+might also help.  If you find a free synthesis engine that supports your
+desired language, and want to add support for it to &ktts;, please
+contact the development team.  Open source engines are especially welcome.
+If you know of a commercial synth, perhaps you can pursuade the vendor
+to donate a free copy to the &ktts; development team.
+In the meantime, you may be able to get
+the synth working using the <guilabel>Command</guilabel> plugin.
+See <xref linkend="using-with-command" />.</para>
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>&ktts; is speaking too slow.  How can I speed it up?</para>
+</question>
+<answer>
+<para>There is a <guilabel>Speed</guilabel> setting on the <guilabel>Audio</guilabel>
+tab.  For this to work, you must have the <command>sox</command> utility
+installed and available in the PATH.  Some synthesis plugins, such as
+Festival Interactive also provide a <guilabel>Speed</guilabel>
+setting in the talker configuration dialog.  Depending upon the
+voice used, it may or may not be enabled.</para>
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>OK, that works for some things, but web pages are still spoken too slow.</para>
+</question>
+<answer>
+<para>The speed settings are ignored when &ktts; is speaking
+&HTML;.  (This is because the &HTML; is converted into SSML, which has its own
+"rate" tags.)  Either disable the &HTML; &XML; Transformer filter
+(see <xref linkend="filters"/>), or if you are brave, edit the .xsl file
+in the &HTML; to SSML Transformer filter and increase the default talking rate.</para>
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>I cannot get web pages to speak in a female voice.  I have female Festival talker
+configured, but &ktts; always speaks web pages in a male voice.</para>
+</question>
+<answer>
+<para>As of Festival 1.95 beta, the SABLE GENDER tag doesn't seem to be working.
+To keep Festival from producing errors, the SSML to SABLE .xsl file strips the
+gender tags out.  The same applies to voice tags as well.</para>
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>I have the &HTML; &XML; Transformer filter configured, but web pages are not spoken at
+all using the Festival plugin.</para>
+</question>
+<answer>
+<para>Due to a bug in Festival 1.95 beta, you must install the
+<command>rab_diphone</command> (British male) voice for SABLE to work at all, even
+if you are not using that voice to speak the web pages.  Also,
+make sure the <command>xsltproc</command> utility is installed and in the PATH.</para>
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>Certain characters or punctuation seem to be producing errors in the synthesizer,
+making it skip entire sentences, or pronounce gibberish.  What can I do?</para>
+</question>
+<answer>
+<para>First, make sure the <guilabel>Character encoding</guilabel> option in the
+talker's configuration dialog is properly set for the language.  If certain words
+or characters are causing problems, a String Replacer filter might help.
+If certain sentence punctuation characters are confusing the synth, you'll need to
+configure a Sentence Boundary Detector filter.  See <xref linkend="filters" />.</para>
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>I added a String Replacer filter of my own and now &ktts;
+will not allow me to rewind or advance by sentence.  On the <guilabel>Jobs</guilabel>
+tab, it claims each job has only one sentence.  What did I do wrong?</para>
+</question>
+<answer>
+<para>You must not filter out sentence punctuation characters (period, question mark,
+exclamation mark, colon, and semicolon).
+For these characters, use a Sentence Boundary Detector filter instead.</para>
+</answer>
+</qandaentry>
+</qandaset>
+</chapter>
+
+<!-- ====================================================================== -->
+
+<chapter id="credits">
+
+<!-- Include credits for the programmers, documentation writers, and
+contributors here. The license for your software should then be included below
+the credits with a reference to the appropriate license file included in the KDE
+distribution. -->
+
+<title>Credits and License</title>
+
+<para>
+&ktts;
+</para>
+<para>
+Program Copyright &copy; 2002 Jos&#233; Pablo Ezequiel "Pupeno" Fern&#225;ndez <email>pupeno@kde.org</email> 
+</para>
+<para>
+Current Maintainer: Gary Cramblitt <email>garycramblitt@comcast.net</email>
+</para>
+<para>
+Contributors:
+<itemizedlist>
+<listitem><para>Olaf Schmidt <email>ojschmidt@kde.org</email></para>
+</listitem>
+<listitem><para>Gunnar Schmi Dt <email>gunnar@schmi-dt.de</email></para>
+</listitem>
+<listitem><para>Paul Giannaros <email>ceruleanblaze@gmail.com</email></para>
+</listitem>
+</itemizedlist>
+</para>
+
+<para>
+Documentation Copyright &copy; 2004 Gary R. Cramblitt <email>garycramblitt@comcast.net</email>
+</para>
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+&underFDL;               <!-- FDL: do not remove -->
+
+<!-- Determine which license your application is licensed under, 
+     and delete all the remaining licenses below:
+
+     (NOTE:  All documentation are licensed under the FDL, 
+     regardless of what license the application uses) -->
+
+&underGPL;        	 <!-- GPL License -->
+
+<note><para>Speech synthesis engines used by &ktts; have their own
+licenses.  See each engine's documentation or website for details.
+Some voices also have their own licensing.</para></note>
+
+</chapter>
+
+<!-- ====================================================================== -->
+
+<appendix id="installation">
+<title>Installation</title>
+
+<!-- ...................................................................... -->
+
+
+<sect1 id="getting-kapp">
+<title>How to obtain &ktts;</title>
+
+<!-- This first entity contains boiler plate for applications that are
+part of KDE CVS.  You should remove it if you are releasing your
+application --> 
+
+<para>
+&install.intro.documentation;
+</para>
+
+<para>(FUTURE) Debian Install Command: <command>apt-get install kdeaccessibility</command></para>
+
+<note>
+<para>You will find links to source and binary packages
+on the <ulink url="http://accessibility.kde.org/developer/kttsd/">
+&kde; Accessibility</ulink> web site (http://accessibility.kde.org).</para>
+
+<para>If you have access to the &kde; code repository, you can download &ktts;
+by checking out the <command>kdeaccessibility</command> module.  &ktts;
+will be found in the <command>kttsd</command> folder.  You can also
+download tarballs of the kdeaccessibility source code from
+<ulink url="ftp://ftp.kde.org/pub/kde/">
+ftp://ftp.kde.org/pub/kde/</ulink></para>
+</note>
+
+</sect1>
+
+<!-- ...................................................................... -->
+
+
+<sect1 id="requirements">
+<title>Requirements</title>
+
+<para>Mandatory requirements:</para>
+
+<para>
+<itemizedlist>
+<listitem><para>&kde; version 3.2 or later.</para></listitem>
+<listitem><para>A speech synthesis engine.  The following engines
+and spoken languages are currently supported.</para>
+
+<para>
+<informaltable id="synth-engines">
+<tgroup cols="2">
+<tbody>
+
+<row>
+<entry>Festival</entry>
+<entry>American English, British, Spanish, German, Finnish, Czech, Polish, Russian,
+Italian, French Canadian, Kiswahili, Zulu, and Ibibio</entry>
+</row>
+
+<row>
+<entry>Festival Lite (flite)</entry>
+<entry>English</entry>
+</row>
+
+<row>
+<entry>Hadifix (&mbrola; and txt2pho)</entry>
+<entry>German, Hungarian</entry>
+</row>
+
+<row>
+<entry>Epos</entry>
+<entry>Czech, Slovak</entry>
+</row>
+
+<row>
+<entry>FreeTTS</entry>
+<entry>English</entry>
+</row>
+
+</tbody>
+</tgroup>
+</informaltable>
+</para>
+
+<para>It also works with any synthesis engine that can be run from a command in
+a &konsole;.</para>
+
+<note><para>
+The languages listed above may not be comprehensive or up-to-date.
+Check the specifications for each engine for a complete list of supported
+languages.  Also check the
+<ulink url="http://accessibility.kde.org/developer/kttsd/index.php">
+&ktts;</ulink> website for additional
+information that might not have made it into this handbook.
+</para></note>
+
+<note>
+<para>&ktts; uses a flexible plugin architecture for
+speech synthesis engines.  If you
+want to enhance &ktts; to support another engine, contact the
+development team.
+</para>
+</note>
+
+<para>
+See <xref linkend="configuration" /> for specific instructions for each
+of these engines.
+</para>
+
+</listitem>
+
+<listitem>
+<para>At least one of the following audio subsystems:
+
+<itemizedlist>
+<listitem><para>&kde; &arts; Soundsystem.  &arts; is usually installed with &kde;.</para></listitem>
+<listitem><para>ALSA (Advanced &Linux; Sound Architecture).  ALSA is installed with
+most &Linux; systems.  (<ulink url="www.alsa-project.org">www.alsa-project.org</ulink>)</para></listitem>
+<listitem><para>GStreamer version 0.8.7 or greater.  <emphasis>Note</emphasis>:
+Be sure to register your GStreamer plugins by running the <command>gst-register</command> 
+command prior to using GStreamer in &ktts;.  
+(<ulink url="http://gstreamer.freedesktop.org">
+http://gstreamer.freedesktop.org</ulink>)</para></listitem>
+<listitem><para>aKode library.  aKode is a decoder library that is part of &kde;.
+</para></listitem>
+</itemizedlist>
+
+<note><para>The &kde; project plans to drop &arts; starting in version 4.</para></note>
+
+<note><para>Some users experience device contention with ALSA.  If your system
+has this problem, you will not be able to simultaneously play music while speaking.
+&ktts; will also freeze if you pause a text job and then
+start another.  See the ALSA website (dmix) for possible solutions.</para></note>
+
+<note><para>As of July 2005, aKode does not support a true pause capability.
+When you pause a text job in &ktts; it will finish speaking the
+current sentence.</para></note>
+
+</para>
+</listitem>
+
+</itemizedlist>
+</para>
+
+<para>Optional components:</para>
+
+<para>
+<itemizedlist>
+
+<listitem>
+<para>The <command>sox</command> audio utility is needed for
+adjusting overall speech speed, but not required.  Debian users can install
+sox with the command <command>apt-get install sox</command>.
+Sox is included on most &Linux; distribution CDs.</para>
+</listitem>
+
+<listitem>
+<para>The <command>xsltproc</command> utility is needed for
+SSML support and for the &XML; Transformer filter, but not required.  Debian users can install
+xsltproc with the command <command>apt-get install xsltproc</command>.</para>
+</listitem>
+
+</itemizedlist>
+</para>
+
+</sect1>
+
+<!-- ...................................................................... -->
+
+
+<sect1 id="compilation">
+<title>Compilation and Installation</title>
+
+<!-- This entity contains the boilerplate text for standard -->
+<!-- compilation instructions.  If your application requires any -->
+<!-- special handling, remove it, and replace with your own text. -->
+
+<!-- &install.compile.documentation; -->
+
+<para>In order to compile &ktts;, you must have a
+recent (&kde; 3.4 or greater) copy of the &kde; development files,
+including kdelibs and arts.</para>
+
+<para>If you downloaded &ktts; as a tarball, log in
+as a normal user and untar the tarball to a suitable folder, 
+change to that folder, and enter the following commands.</para>
+
+<programlisting>
+./configure
+make
+</programlisting>
+
+<para>The following <command>configure</command> options are available:</para>
+
+<para>
+<informaltable id="configure-audio-options">
+<tgroup cols="3">
+<tbody>
+
+<row>
+<entry><emphasis>Default Option</emphasis></entry>
+<entry><emphasis>Description</emphasis></entry>
+<entry><emphasis>Alternate</emphasis></entry>
+</row>
+<row>
+<entry>--with-arts</entry>
+<entry>Builds the arts audio plugin.</entry>
+<entry>--without-arts</entry>
+</row>
+<row>
+<entry>--with-alsa=check</entry>
+<entry>Builds the ALSA audio plugin.</entry>
+<entry>--with-alsa=no</entry>
+</row>
+<row>
+<entry>--with-gstreamer=no</entry>
+<entry>Does not build the GStreamer audio plugin.</entry>
+<entry>--with-gstreamer=check</entry>
+</row>
+<row>
+<entry>--with-akode=no</entry>
+<entry>Does not build the aKode audio plugin.</entry>
+<entry>--with-akode=check</entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+</para>
+
+<note><para>
+In &kde; 4, the &arts; plugin will likely be removed or at least not built by default.
+</para></note>
+
+<para>The following speech synthesizer plugins are all built by default.
+Some of them are runtime only dependent upon non-free software.
+(Non-free according to Debian Policy). The "Configure Option to
+not build" column shows the configure command to not build the plugin:</para>
+
+<para>
+<informaltable id="configure-synth-options">
+<tgroup cols="3">
+<tbody>
+
+<row>
+<entry><emphasis>Synth</emphasis></entry>
+<entry><emphasis>License</emphasis></entry>
+<entry><emphasis>Configure Option to not build</emphasis></entry>
+</row>
+<row><entry>Festival</entry><entry>free</entry><entry>--disable-kttsd-festivalint</entry></row>
+<row><entry>Festival Lite</entry><entry>free</entry><entry>--disable-kttsd-flite</entry></row>
+<row><entry>Epos</entry><entry>free</entry><entry>--disable-kttsd-epos</entry></row>
+<row><entry>Command</entry><entry>free</entry><entry>--disable-kttsd-command</entry></row>
+<row><entry>Hadifix</entry><entry>non-free</entry><entry>--disable-kttsd-hadifix</entry></row>
+<row><entry>FreeTTS</entry><entry>non-free</entry><entry>--disable-kttsd-freetts</entry></row>
+</tbody></tgroup></informaltable></para>
+
+<para>By default, the commands above will install &ktts; to
+<filename>/opt/kde3</filename>.  If this folder is not in your
+$<envar>KDEDIRS</envar> path, you may need to add a
+<userinput>--prefix=<replaceable>target</replaceable></userinput> option.
+For example,</para>
+
+<programlisting>
+./configure --prefix=/usr/local
+make
+</programlisting>
+
+<note><para>On Debian systems, <filename><replaceable>/usr/local</replaceable></filename>
+is the usual place to install applications compiled from source code.
+</para></note>
+
+<para>Login as root and install the compiled &ktts;
+using the following commands.</para>
+
+<programlisting>
+su
+make install
+</programlisting>
+
+<para>If you downloaded the &ktts; source from the
+<filename>kdeaccessibility</filename> code repository module, or downloaded the nightly
+tarball, use the following commands to compile and install.
+</para>
+
+<programlisting>
+cd kdeaccessibility
+echo kttsd>inst-apps
+make -f Makefile.cvs
+./configure
+cd kttsd
+make
+su
+make install
+</programlisting>
+
+</sect1>
+
+<!-- ...................................................................... -->
+
+
+<sect1 id="configuration">
+<title>Configuration</title>
+
+<para>Make sure your speech synthesis engine is working before using
+&ktts;.  Follow the instructions that came with the engine.</para>
+
+<tip>
+<para>In some cases, you may need to grant write access to the audio device.</para>
+<para><userinput>chmod a+rw <replaceable>/dev/dsp*</replaceable></userinput></para>
+</tip>
+
+<!-- ...................................................................... -->
+
+
+<sect2 id="using-with-festival">
+<title>Using with Festival (Interactive)</title>
+
+<para>Festival is one of the best free and open source TTS
+engines available.  Voice quality is generally good and there are quite
+a few languages and voices supported.
+For many voices, you can control the volume, 
+speed of the generated speech, and pitch (tone) from &ktts;.</para>
+
+<para>Synthesizer Name: <guilabel>Festival Interactive</guilabel></para>
+
+<para>&URL;: <ulink url="http://www.cstr.ed.ac.uk/projects/festival/">
+http://www.cstr.ed.ac.uk/projects/festival/</ulink>
+</para>
+
+<para>Debian Install Command: <userinput>apt-get install festival</userinput></para>
+
+<para>
+You will need to install at least one language.  Follow the instructions
+that come with Festival.  If you will be speaking web pages,
+you must install the <command>rab_diphone</command> (British Male)
+voice.
+</para>
+
+<para>Additional English festival voices are available from</para>
+
+<para><ulink url="http://hts.ics.nitech.ac.jp/">http://hts.ics.nitech.ac.jp/</ulink>.
+</para>
+
+<para>Additional Spanish, English, and German voices are available from</para>
+
+<para><ulink url="http://cslu.cse.ogi.edu/tts/download/">
+http://cslu.cse.ogi.edu/tts/download/</ulink></para>
+
+<para>You must compile an additional module
+for these voices, therefore, you must have the Festival source code.
+The German voices have limited distribution.
+</para>
+
+<para>A Finnish male voice is available from </para>
+
+<para><ulink url="http://www.ling.helsinki.fi/suopuhe/download/">
+http://www.ling.helsinki.fi/suopuhe/download/</ulink>.
+</para>
+
+<para>A Polish male voice is available from </para>
+
+<para><ulink url="http://www.artegence.com/download/voicexml/speech/festival_polish_voice.tgz">
+http://www.artegence.com/download/voicexml/speech/festival_polish_voice.tgz</ulink>.
+</para>
+
+<para>A Russian male voice is available from </para>
+
+<para><ulink url="http://nshmyrev.narod.ru/festival/festival.html">
+http://nshmyrev.narod.ru/festival/festival.html
+</ulink></para>
+
+<para>You must have Festival 1.95 beta or later to use this voice.  The voice
+is still in early development.  Untar to
+<filename>festival/lib/voices/russian/</filename>.  When you configure the Russian
+talker, the voice code is <userinput>msu_ru_nsh_diphone</userinput>.  Be sure to
+select an 8-bit cryllic encoding, such as <userinput>KOI8-R</userinput>.</para>
+
+<para>Italian voices for Festival 1.95 beta are available at</para>
+
+<para><ulink url="http://www.csrf.pd.cnr.it/TTS/It-FESTIVAL-download.htm">
+http://www.csrf.pd.cnr.it/TTS/It-FESTIVAL-download.htm</ulink>.</para>
+
+<para>If you get CRC errors when you unzip, try downloading again.</para>
+
+<para>Kiswahili, Zulu, and Ibibio voices for Festival 1.95 beta are available at</para>
+
+<para><ulink url="http://www.llsti.org/">http://www.llsti.org/</ulink>.</para>
+
+<para>Unfortunately, the Hindi voice also available there will not work with
+&ktts;.</para>
+
+<para>Commercial voices, including a French Canadian voice,
+can be purchased from Cepstral, LLC at</para>
+
+<para><ulink url="http://www.cepstral.com/">http://www.cepstral.com/</ulink></para>
+
+<para>The FAQ on their Support page has information about using their voices
+in Festival.</para>
+
+<para>Festival is typically included with &Linux; distributions.  Check your
+distro CDs to see if it is included.</para>
+
+<note>
+<para>When using the Polish, Hungarian, or Czech languages, be sure the <guilabel>Encoding</guilabel>
+option is set to <userinput>ISO 8859-2</userinput>.
+</para>
+<para>When using the Russian voice, be sure the <guilabel>Encoding</guilabel>
+option is set to an 8-bit cryllic encoding, such as <userinput>KOI8-R</userinput>.
+</para>
+</note>
+
+<!-- ...................................................................... -->
+
+
+<sect3 id="festival-with-mbrola">
+<title>Using Festival with &mbrola;</title>
+
+<para>Festival can be used in combination with the &mbrola; synthesizer.
+In this mode, Festival does the lexical analysis and &mbrola; produces the
+audio.  The &mbrola; binary and &mbrola; voice files can be downloaded from</para>
+
+<para><ulink url="http://festvox.org/mbrola/">http://festvox.org/mbrola/</ulink>.</para>
+
+<para>Follow the instructions in the <filename>readme.txt</filename> that comes with
+the download.</para>
+
+<para>Note that &mbrola; is not a complete Text-to-Speech system.  &mbrola; synthesizes
+speech from diphone files.  You must have additional software that can produce
+the diphones.  When combined with Festival, Festival produces the diphones needed
+by &mbrola;.  <command>txt2pho</command> can also be used to produce diphones
+from German text.  See <xref linkend="using-with-hadifix"/> for more information.</para>
+
+<para>There are three methods of combining Festival with &mbrola;.</para>
+
+<para>
+<itemizedlist>
+<listitem><para><link linkend="mbrola-wrappers">&mbrola; Wrappers</link>.
+At the time of writing this Handbook,
+this method is limited to English voices.</para></listitem>
+<listitem><para><link linkend="ims-german-festival">IMS German Festival</link>.</para></listitem>
+<listitem><para><link linkend="festival-czech">Festival-Czech</link>.</para></listitem>
+</itemizedlist>
+</para>
+
+<!-- ...................................................................... -->
+
+<sect4 id="mbrola-wrappers">
+<title>Using Festival with &mbrola; Wrappers</title>
+
+<para>In this method, additional
+wrapper code is added to Festival to enable speech synthesis using
+&mbrola; voice files.  Note that the &mbrola; voice files are <emphasis>not</emphasis>
+installed in the &mbrola; folder tree.  Instead, they are installed
+in the <filename>festival/lib/</filename> folder tree.  For instructions, see</para>
+
+<para><ulink url="http://www.cstr.ed.ac.uk/projects/festival/mbrola.html">
+http://www.cstr.ed.ac.uk/projects/festival/mbrola.html</ulink></para>
+
+</sect4>
+
+<!-- ...................................................................... -->
+
+<sect4 id="ims-german-festival">
+<title>Using IMS German Festival</title>
+
+<para>IMS German Festival is a modified version of Festival that uses German &mbrola;
+voices.  It works with either Festival version 1.4.1 or Festival 2.0 (1.95beta).
+First install Festival and &mbrola;, if you have not already done so.
+Next, download IMS German Festival, from</para>
+
+<para>
+<ulink url="http://www.ims.uni-stuttgart.de/phonetik/synthesis/festival_opensource.html">
+http://www.ims.uni-stuttgart.de/phonetik/synthesis/festival_opensource.html</ulink>.</para>
+
+<para>Follow the instructions in the <filename>README</filename> that comes with the
+download.  (Note, if using in combination with Festival 2.0, it is <emphasis>not</emphasis>
+necessary to apply the <filename>fixes</filename> tarball, but you must still
+rebuild festival.)  Finally, add the following
+lines to the <filename>festival/lib/siteinit.scm</filename> file.</para>
+
+<para>
+<programlisting>
+(voice-location "german_de1_os" "/usr/local/mbrola/de1"
+  "German Female, IMS Festival de1")
+(voice-location "german_de2_os" "/usr/local/mbrola/de2"
+  "German Male, IMS Festival de2")
+(voice-location "german_de3_os" "/usr/local/mbrola/de3"
+  "German Female, IMS Festival de3")
+</programlisting>
+</para>
+
+<para>just above the line that reads</para>
+
+<para>
+<programlisting>
+(provide 'siteinit)
+</programlisting>
+</para>
+
+<para>On some systems, the file you edit is <filename>/etc/festival.scm</filename>.  
+Only add the lines that correspond to the German voices you have installed.
+Substitute the correct path for 
+<userinput><replaceable>/usr/local/mbrola/</replaceable></userinput>.
+Also note that (at the time of this writing) 
+IMS German Festival does not work with the de4, de5, or de6 German voices.</para>
+
+</sect4>
+
+<!-- ...................................................................... -->
+
+<sect4 id="festival-czech">
+<title>Using Festival-Czech</title>
+
+<para>This method uses some special code to enable speech synthesis
+using Festival with an &mbrola; Czech voice.  To install, first download and 
+install Festival and &mbrola;, and make sure both are working.  Next, download
+Festival-Czech from</para>
+
+<para><ulink url="http://www.freebsoft.org/festival-czech">
+http://www.freebsoft.org/festival-czech</ulink></para>
+
+<note><para>In the following procedures substitute the correct folder
+paths as needed.</para></note>
+
+<para>Untar the download to a suitable folder and make
+the lexicon.  The Festival executable must be in your <envar>PATH</envar>.
+</para>
+
+<para>
+<programlisting>
+cd /usr/local
+tar xvfz festival-czech.tar.gz
+cd festival-czech
+make
+</programlisting>
+</para>
+
+<para>Download the <filename>cz2</filename> voice file from the &mbrola;
+website, and unzip it in the &mbrola; folder.</para>
+
+<para>
+<programlisting>
+cd /usr/local/mbrola
+mkdir cz2
+cd cz2
+unzip cz2-001009.zip
+</programlisting>
+</para>
+
+<para>Add the following lines to the <filename>festival/lib/siteinit.scm</filename> file.</para>
+
+<para>
+<programlisting>
+(set! czech-lexicon-file "/usr/local/festival-czech/czech-lexicon.out")
+(set! load-path (cons "/usr/local/festival-czech" load-path))
+(require 'czech)
+(set! czech-mbrola_database "/usr/local/mbrola/cz2/cz2")
+(set! mbrola_progname "/usr/local/mbrola/mbrola")
+(voice-location "czech_mbrola_cz2" "/usr/local/mbrola/cz2"
+    "Czech Male, MBROLA")
+(require 'czech-mbrola)
+</programlisting>
+</para>
+
+<para>just above the line that reads</para>
+
+<para>
+<programlisting>
+(provide 'siteinit)
+</programlisting>
+</para>
+
+<para>On some systems, the file you edit is <filename>/etc/festival.scm</filename>.</para>
+
+</sect4>
+
+</sect3>
+
+</sect2>
+
+<!-- ...................................................................... -->
+
+<sect2 id="using-with-flite">
+<title>Using with Festival Lite (flite)</title>
+
+<para>Festival Lite is a free open source engine that currently supports
+a limited number of voices and languages.  It is light weight, but
+sacrifices voice quality somewhat.
+You cannot control the pitch, volume, or speed of this engine
+from &ktts;.</para>
+
+<para>Synthesizer Name: <guilabel>Festival Lite (flite)</guilabel></para>
+
+<para>&URL;: <ulink url="http://www.speech.cs.cmu.edu/flite/index.html">
+http://www.speech.cs.cmu.edu/flite/index.html</ulink>
+</para>
+
+<para>Debian Install Command: <userinput>apt-get install flite</userinput></para>
+
+<para>flite is typically included with &Linux; distributions.  Check your
+distro CDs to see if it is included.</para>
+
+<para>Build and install flite following the instructions in the
+<filename>README</filename> that comes with it.</para>
+
+</sect2>
+
+<!-- ...................................................................... -->
+
+
+<sect2 id="using-with-hadifix">
+<title>Using with Hadifix (&mbrola; and txt2pho)</title>
+
+<para>Hadifix is a two-stage synthesis engine based on diphones.
+The <command>txt2pho</command> utility converts text into diphones
+and the &mbrola; engine synthesizes the diphones to sound.
+Voice quality is good, but language support is currently somewhat limited.
+You can control the voice, pitch, speed, and volume from <application>kttsmgr</application>.
+</para>
+
+<para>Synthesizer Name: <guilabel>Hadifix</guilabel></para>
+
+<para>&URL;: see below</para>
+
+<para>Debian Install Command: none</para>
+
+<para>If you do not already have Hadifix installed, do this:</para>
+
+<procedure>
+<step><para>Download &mbrola; binary from
+<ulink url="http://festvox.org/mbrola/">http://festvox.org/mbrola/</ulink>.</para></step>
+<step><para>Install &mbrola; to <filename>/usr/local/mbrola</filename> folder.</para></step>
+<step><para>Download at least one german language file from the &mbrola; site.
+Unzip to the <filename>/usr/local/mbrola</filename> folder.</para></step>
+<step><para>Download txt2pho from</para>
+<para>
+<ulink url="http://www.ikp.uni-bonn.de/dt/forsch/phonetik/hadifix/HADIFIXforMBROLA.html">
+http://www.ikp.uni-bonn.de/dt/forsch/phonetik/hadifix/HADIFIXforMBROLA.html</ulink>.</para>
+</step>
+<step><para>Unzip txt2pho to <filename>/usr/local/txt2pho</filename>.</para></step>
+<step><para>Edit <command>txt2phorc</command> file, putting correct data paths in.</para></step>
+<step><para>Either copy <command>txt2phorc</command> to <filename>~/.txt2phorc</filename> or to <filename>/etc/txt2pho</filename>.
+Note that you drop the "rc" in file name.</para></step>
+<step><para>In <application>kttsmgr</application>, choose the German language 
+(<guilabel>de</guilabel>), and add <guilabel>Hadifix</guilabel>.</para></step>
+<step><para>On the <guilabel>Configure Talker</guilabel> screen,
+configure a voice and the paths to &mbrola; and txt2pho.</para></step>
+<step><para>Click the <guibutton>Test</guibutton> button to test.</para></step>
+</procedure>
+
+<para>A Hungarian implementation for &mbrola; and txt2pho is available at</para>
+
+<para>
+<ulink url="http://tkltrans.sourceforge.net/">http://tkltrans.sourceforge.net/</ulink>.
+</para>
+
+</sect2>
+
+<!-- ...................................................................... -->
+
+
+<sect2 id="using-with-epos">
+    <title>Using with Epos</title>
+
+<para>Epos is a free Czeck and Slovak open source engine.
+It is light weight, but sacrifices voice quality somewhat.
+You cannot control the volume of this engine
+from &ktts;.</para>
+
+<para>Synthesizer Name: <guilabel>Epos TTS Synthesis System</guilabel></para>
+
+<para>&URL;: <ulink url="http://epos.ure.cas.cz/">
+http://epos.ure.cas.cz/</ulink>
+</para>
+
+<para>Debian Install Command: <userinput>apt-get install epos</userinput></para>
+
+<para>Start <application>kttsmgr</application>.  On the <guilabel>Talkers</guilabel> tab,
+click the <guibutton>Add</guibutton> button.  Choose Czeck or Slovak
+language and <guilabel>Epos TTS Synthesis System</guilabel>.
+If the epos server executable and client are not
+in your <envar>PATH</envar>, specify the paths to these executables
+in the <guilabel>Configure Talker</guilabel> screen.  The options boxes
+permit you to pass additional options to the server and client.  In a 
+&konsole;, type <userinput>epos -h</userinput> 
+or <userinput>say -h</userinput> for information.</para>
+
+</sect2>
+
+<!-- ...................................................................... -->
+
+
+<sect2 id="using-with-freetts">
+    <title>Using with FreeTTS</title>
+
+<para>FreeTTS is a free open source speech engine written in &Java;, which means
+that you must have the &Java; Virtual Machine software installed on your
+system to use it.  It currently has limited voice and language support.
+You cannot control the pitch, volume, or speed of this engine
+from &ktts;.</para>
+
+<para>Synthesizer Name: <guilabel>FreeTTS</guilabel></para>
+
+<para>&URL;: <ulink url="http://sourceforge.net/projects/freetts/">
+http://sourceforge.net/projects/freetts/</ulink>
+</para>
+
+<para>Debian Install Command: none</para>
+
+</sect2>
+
+<!-- ...................................................................... -->
+
+
+<sect2 id="using-with-command">
+    <title>Using the Command Plugin</title>
+
+<para>The command plugin permits you to use &ktts; with any
+speech synthesis engine that can be run as a command in a 
+&konsole;.</para>
+
+<para>Synthesizer Name: <guilabel>Command</guilabel></para>
+
+<para>&URL;: none</para>
+
+<para>Debian Install Command: none</para>
+
+<para>Ideally, you should use a command that synthesizes to a temporary audio
+(wav) file, rather than send the speech directly to the audio device.</para>
+
+<para>If the speech synthesis engine requires text to be encoded
+differently from your desktop encoding setting, you must use the
+<command>%f</command> parameter to pass the text to the engine.
+&ktts; will encode the text in the setting you specify when
+it writes the text to the temporary file.  If you attempt to pass text
+on the command line using the <command>%t</command> parameter,
+it will be encoded using your desktop locale setting.
+You can also use the <guilabel>Send the data as standard input</guilabel>
+option to solve this problem, if the engine accepts input from StdIn.
+For example, here is a sample command to send polish text to Festival using
+ISO 8859-2 encoding and removing unspeakable punctuation characters.</para>
+
+<para><command>cat %f | tr '(){}[]"' ' ' | festival --tts --language polish</command>
+</para>
+
+</sect2>
+
+<!-- ====================================================================== -->
+
+</sect1>
+
+</appendix>
+
+&documentation.index;
+</book>
+
+<!--
+Local Variables:
+mode: xml
+sgml-minimize-attributes:nil
+sgml-general-insert-case:lower
+sgml-indent-step:0
+sgml-indent-data:nil
+End:
+
+vim:tabstop=2:shiftwidth=2:expandtab 
+-->