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, 1122 insertions, 0 deletions

diff --git a/doc/kmouth/index.docbook b/doc/kmouth/index.docbook
new file mode 100644
index 0000000..3cfcf10
--- /dev/null
+++ b/doc/kmouth/index.docbook
@@ -0,0 +1,1122 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+  <!ENTITY kmouth '<application>KMouth</application>'>
+  <!ENTITY kappname "&kmouth;">
+  <!ENTITY package "kdeaccessibility">
+  <!ENTITY % addindex "IGNORE">
+  <!ENTITY % English "INCLUDE"><!-- change language only here -->
+]>
+
+<book lang="&language;">
+<bookinfo>
+  <title>The &kmouth; Handbook</title>
+
+  <authorgroup>
+    <author>
+      <firstname>Gunnar</firstname>
+      <surname>Schmi Dt</surname>
+      <affiliation>
+        <address><email>gunnar@schmi-dt.de</email></address>
+      </affiliation>
+    </author>
+  <!-- TRANS:ROLES_OF_TRANSLATORS -->
+  </authorgroup>
+
+
+  <copyright>
+    <year>2002</year><year>2003</year>
+    <holder>Gunnar Schmi Dt</holder>
+  </copyright>
+  <!-- Translators: put here the copyright notice of the translation -->
+  <legalnotice>&FDLNotice;</legalnotice>
+
+
+  <date>2006-05-20</date>
+  <releaseinfo>1.1.1</releaseinfo>
+
+  <abstract>
+    <para>
+      &kmouth; is an application that enables persons that cannot speak to let their
+      computers speak.
+    </para>
+  </abstract>
+
+  <keywordset>
+    <keyword>KDE</keyword>
+    <keyword>kdeutils</keyword>
+    <keyword>KMouth</keyword>
+    <keyword>text-to-speech conversion</keyword>
+    <keyword>mutual persons</keyword>
+  </keywordset>
+</bookinfo>
+
+<chapter id="introduction">
+  <title>Introduction</title>
+
+  <para>
+    &kmouth; is a program that enables persons that cannot speak to let their
+    computers speak. It includes a history of spoken sentences from which the
+    user can select sentences to be re-spoken.
+  </para>
+  <para>
+    Note that &kmouth; does not include speech synthesizer. Instead it requires
+    a speech synthesizer installed in the system.
+  </para>
+  <para>
+    Please report any problems and feature requests to the author of &kmouth;.
+  </para>
+</chapter>
+
+<chapter id="using-kmouth">
+  <title>Using &kmouth;</title>
+  <sect1 id="Wizard">
+    <title>The first start</title>
+    <para>
+      During the first start of &kmouth;, a wizard is displayed into which you
+      can enter some basic configuration.
+    </para>
+    <para>
+      <screenshot>
+        <screeninfo>The wizard</screeninfo>
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="kmouthwizard.png" format="PNG"/>
+          </imageobject>
+          <imageobject>
+            <imagedata fileref="kmouthwizard.eps" format="EPS"/>
+          </imageobject>
+          <textobject>
+            <phrase>The wizard</phrase>
+          </textobject>
+        </mediaobject>
+      </screenshot>
+    </para>
+    <para>
+      With the first page of the wizard (the left screen shot) you specify
+      the command that shall later be used for the text-to-speech conversion.
+      For more details look into the <link linkend="tts-config">description
+      of the configuration dialog.</link>
+    </para>
+    <para>
+      With the second page you select which standard phrase books you need.
+      From the phrase books you later can select often used phrases so that
+      you do not need to type them in. Of course &kmouth; also has an edit
+      dialog for the case that you later want to edit your phrase books.
+    </para>
+    <para>
+      With the third page (the right screen shot) you define the dictionary
+      for a word completion. &kmouth; will parse the &kde; documentation of
+      the chosen language in order to detect the frequentness of individual
+      words. Optionally you can compare the word list to an OpenOffice.org
+      dictionary in order to only add correctly spelled words to the word
+      completion.
+    </para>
+  </sect1>
+  <sect1 id="main-window">
+    <title>The Main Window</title>
+    <para>
+      The main window of &kmouth; is fairly simple. It consists basically of an
+      edit field into which you type your sentences (the lower white field in
+      the screen shot) and a history of spoken sentences (the upper white field
+      in the screen shot).
+    </para>
+    <para>
+      <screenshot>
+        <screeninfo>The main window of &kmouth;</screeninfo>
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="kmouthmain.png" format="PNG"/>
+          </imageobject>
+          <imageobject>
+            <imagedata fileref="kmouthmain.eps" format="EPS"/>
+          </imageobject>
+          <textobject>
+            <phrase>Screen shot</phrase>
+          </textobject>
+        </mediaobject>
+      </screenshot>
+    </para>
+    <para>
+      Assuming that you have correctly <link linkend="config-dialog">configured
+      &kmouth;</link> you can use the edit field for entering sentences you
+      want to hear. Once a sentence got spoken it will be appended to the
+      history. From the history you can select sentences to be re-spoken.
+    </para>
+    <para>
+      From the phrase books (located in the line below the tool bar) you can
+      select often used phrases.
+    </para>
+  </sect1>
+  <sect1 id="config-dialog">
+    <title>The Configuration Dialog</title>
+    <para>
+      By using the menu entry
+      <menuchoice>
+        <guimenu>Settings</guimenu><guimenuitem>Configure &kmouth;...</guimenuitem>
+      </menuchoice>
+      you open the configuration dialog of &kmouth;. This dialog consists of
+      the pages <guilabel>General Options</guilabel> with the two tabs <guilabel>Text-to-Speech</guilabel> 
+      and <guilabel>Preferences</guilabel>, the page <guilabel>Word Completion</guilabel> and
+       the page <guilabel>KTTSD Speech Service</guilabel> 
+    </para>
+    <sect2 id="tts-config">
+      <title>The <guilabel>Text-to-Speech</guilabel> tab</title>
+      <para>
+        <screenshot>
+          <screeninfo>The <guilabel>Text-to-Speech</guilabel> tab</screeninfo>
+          <mediaobject>
+            <imageobject>
+              <imagedata fileref="kmouthctts.png" format="PNG"/>
+            </imageobject>
+            <imageobject>
+              <imagedata fileref="kmouthctts.eps" format="EPS"/>
+            </imageobject>
+            <textobject>
+              <phrase>Screen shot</phrase>
+            </textobject>
+          </mediaobject>
+        </screenshot>
+      </para>
+      <para>
+        Into the edit field of the <guilabel>Text-to-Speech</guilabel> tab you enter the command
+        for calling the speech synthesizer. With the combo box below the edit
+        field you specify the character encoding that is used for passing the
+        text to the speech synthesizer.
+      </para>
+      <para>
+        &kmouth; knows two ways of passing the text: If the command expects the
+        text as standard input you select the check box.
+      </para>
+      <para>
+        The other way is to pass the text as a parameter:
+        Before calling the command &kmouth; replaces certain placeholders with
+        actual content:
+        <informaltable frame="topbot">
+         <tgroup cols="2">
+          <thead>
+          <row><entry>Placeholder</entry><entry>Replaced with</entry></row>
+          </thead>
+            <tbody>
+              <row><entry><token>%t</token></entry>
+                   <entry>The actual text that should be spoken</entry>
+              </row>
+              <row><entry><token>%f</token></entry>
+                   <entry>The name of a temporary file that contains the text
+                          that should be spoken</entry>
+              </row>
+              <row><entry><token>%l</token></entry>
+                   <entry>The language code associated with the current word completion
+                          dictionary</entry>
+              </row>
+              <row><entry><token>%%</token></entry><entry>A percent sign</entry></row>
+           </tbody>
+          </tgroup>
+        </informaltable>
+      </para>
+      <para>
+        Off course the command for speaking texts is dependent on which speech
+        synthesizer you use. Please look into the documentation of your speech
+        synthesizer for the command for speaking texts. You can find examples
+        for the command in the <link linkend="tts">appendix</link>.
+      </para>
+      <para>
+        By selecting <guilabel>Use KTTSD speech service if possible</guilabel> you tell &kmouth;
+        first to try to send the text to the KTTSD speech service. If this succeeds the
+        other configuration entries on this tab are ignored. The KTTSD speech
+        service is a &kde; daemon which gives &kde; applications a standardized
+        interface for speech synthesis and is currently developed in <acronym>SVN</acronym>. It
+        is safe to select this option even if KTTSD is not installed.
+      </para>
+    </sect2>
+    <sect2 id="preferences">
+      <title>The <guilabel>Preferences</guilabel> tab</title>
+      <para>
+        <screenshot>
+          <screeninfo>The <guilabel>Preferences</guilabel> tab</screeninfo>
+          <mediaobject>
+            <imageobject>
+              <imagedata fileref="kmouthcpref.png" format="PNG"/>
+            </imageobject>
+            <imageobject>
+              <imagedata fileref="kmouthcpref.eps" format="EPS"/>
+            </imageobject>
+            <textobject>
+              <phrase>Screen shot</phrase>
+            </textobject>
+          </mediaobject>
+        </screenshot>
+      </para>
+      <para>
+        The <guilabel>Preferences</guilabel> tab contains options that alter the behavior of
+        &kmouth; in certain situations.
+      </para>
+      <para>
+        With the first combo box, <guilabel>Selection of phrases in the phrase book:</guilabel>,
+        you specify which action is triggered by typing the shortcut of a
+        phrase or by selecting a phrase in the <guimenu>Phrase Book</guimenu>
+        menu or in the phrase book bar.
+      </para>
+      <para>
+        By selecting <guilabel>Speak Immediately</guilabel> the
+        selected phrase gets immediately spoken and is entered into
+        the history. If you select <guilabel>Insert Into Edit
+        Field</guilabel> the selected phrase is just inserted into the
+        edit field. 
+      </para>
+      <para>
+        With the second combo box, <guilabel>Closing the phrase book
+        edit window:</guilabel>, you specify whether the phrase book
+        gets saved if you just close the phrase book edit window.
+      </para>
+      <para>
+        By selecting <guilabel>Save Phrase Book</guilabel> the phrase
+        book gets saved. If you select <guilabel>Discard
+        changes</guilabel> the changes are discarded and the phrase 
+        book is not saved. If you select <guilabel>Ask Whether to
+        Save</guilabel> &kmouth; will ask you whether it shall save
+        the phrase book.
+      </para>
+    </sect2>
+    <sect2 id="completion-config">
+      <title>The <guilabel>Word Completion</guilabel> page</title>
+      <para>
+        <screenshot>
+          <screeninfo>The <guilabel>Word Completion</guilabel> page</screeninfo>
+          <mediaobject>
+            <imageobject>
+              <imagedata fileref="kmouthcwcp.png" format="PNG"/>
+            </imageobject>
+            <imageobject>
+              <imagedata fileref="kmouthcwcp.eps" format="EPS"/>
+            </imageobject>
+            <textobject>
+              <phrase>Screen shot</phrase>
+            </textobject>
+          </mediaobject>
+        </screenshot>
+      </para>
+      <para>
+        The <guilabel>Word Completion</guilabel> page contains a list
+        of dictionaries used for the word completion. (&kmouth; will
+        display a combo box next to the edit field in the main window
+        if this list contains more than one dictionary. You can use this
+        combo box in order to select the dictionary that actually gets
+        used for the word completion.)
+      </para>
+      <para>
+        With the buttons on the right side of the page you can add and
+        delete dictionaries, change the order of the dictionaries or export
+        dictionaries to a file. With the edit field and the combo box below
+        the list you can change the name and the language associated with
+        the dictionary.
+      </para>
+      <para>
+        When you add a new dictionary you may choose between several sources:
+      </para>
+      <itemizedlist>
+        <listitem>
+          <para>Create a new dictionary from the &kde; documentation</para>
+          <para>
+            If you use this source &kmouth; will ask you for the intended
+            language and afterwards parse the &kde; documentation. The
+            frequentness of the individual words is detect by simply counting
+            the occurrences of each word. Optionally you can compare the word
+            list to an OpenOffice.org dictionary in order to only add correctly
+            spelled words to the new dictionary.
+          </para>
+        </listitem>
+        <listitem>
+          <para>Create a new dictionary from a file</para>
+          <para>
+            If you use this source &kmouth; will ask you for the intended
+            file. You may either select an &XML; file, a standard text file or
+            a file containing a word completion dictionary created by either
+            &kmouth; or GOK (the GNOME On-screen Keyboard). If you select a
+            standard text file or an &XML; file the frequentness of the individual
+            words is detected by simply counting the occurrences of each word.
+            Optionally you can compare the word list to an OpenOffice.org
+            dictionary in order to only add correctly spelled words to the new
+            dictionary.
+          </para>
+        </listitem>
+        <listitem>
+          <para>Create a new dictionary from a folder</para>
+          <para>
+            If you use this source &kmouth; will ask you for the intended folder.
+            &kmouth; will open all files in that folder and its subdirectories.
+            Each file is either loaded as a completion dictionary, as an &XML; file
+            or as a standard text file. In the latter two cases the occurrences of
+            each individual word in the file is counted. Optionally you can compare
+            the word list to an OpenOffice.org dictionary in order to only add
+            correctly spelled words to the new dictionary.
+          </para>
+        </listitem>
+        <listitem>
+          <para>Merge dictionaries</para>
+          <para>
+            You can use this option in order to merge the available dictionaries.
+            &kmouth; will ask you which dictionaries should be merged and how the
+            individual dictionaries should be weighted.
+          </para>
+        </listitem>
+        <listitem>
+          <para>Create an empty word list</para>
+          <para>
+            You can use this option in order to create a blank dictionary without
+            any entries. As &kmouth; automatically adds newly typed words to the
+            dictionaries it will learn your vocabulary with the time.
+          </para>
+        </listitem>
+      </itemizedlist>
+    </sect2>
+    <sect2 id="kttsd-speech-service-config">
+      <title>The <guilabel>KTTSD Speech Service</guilabel> page</title>
+      <para>The configuration of the &kde; Speech Service is described in detail in the 
+        <ulink url="help:kttsd">KTTS Handbook</ulink>.</para>
+    </sect2>
+  </sect1>
+  <sect1 id="phrasebook-editor">
+    <title>The Phrase Book Edit Window</title>
+    <para>
+      By using the menu entry
+      <menuchoice>
+        <guimenu>Phrase Books</guimenu><guimenuitem>Edit...</guimenuitem>
+      </menuchoice>
+      you open the phrase book edit window.
+    </para>
+    <para>
+      <screenshot>
+        <screeninfo>The phrase book edit window</screeninfo>
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="kmouthedit.png" format="PNG"/>
+          </imageobject>
+          <imageobject>
+            <imagedata fileref="kmouthedit.eps" format="EPS"/>
+          </imageobject>
+          <textobject>
+            <phrase>Screens hot</phrase>
+          </textobject>
+        </mediaobject>
+      </screenshot>
+    </para>
+    <para>
+      The main area of the phrase book edit window is divided into two parts.
+      Within the upper part the phrase books are displayed in some tree
+      structure.
+    </para>
+    <para>
+      Within the lower part you may modify a selected item. If you have
+      selected a phrase you can modify the contents of the phrase as well
+      as its shortcut. If you have selected a phrase book you can only
+      change its name.
+    </para>
+    <para>
+      Actions like adding new phrases and phrase books and deleting selected
+      phrases and phrase books can be done by selecting them in either the
+      menu bar, the toolbar or a pop up menu.
+    </para>
+    <para>
+      You can change the order of the phrase books and phrases by dragging
+      them to their new places or by using the arrow keys while the
+      &Alt; key is pressed.
+    </para>
+  </sect1>
+
+</chapter>
+
+<chapter id="commands">
+  <title>Command Reference</title>
+
+  <sect1 id="main-commands">
+    <title>Commands Within The Main Window</title>
+    <sect2 id="file-menu">
+      <title>The <guimenu>File</guimenu> Menu</title>
+        <variablelist>
+          <varlistentry>
+            <term><menuchoice>
+              <shortcut>
+                <keycombo>&Ctrl;<keycap>O</keycap></keycombo>
+              </shortcut>
+              <guimenu>File</guimenu>
+              <guimenuitem>Open as History...</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>Opens a text file into as history of spoken sentences.</action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <shortcut>
+                <keycombo>&Ctrl;<keycap>S</keycap></keycombo>
+              </shortcut>
+              <guimenu>File</guimenu>
+              <guimenuitem>Save History As...</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>Saves the history into a text file.</action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <shortcut>
+                <keycombo>&Ctrl;<keycap>P</keycap></keycombo>
+              </shortcut>
+              <guimenu>File</guimenu>
+              <guimenuitem>Print History...</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>Prints the history.</action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <shortcut>
+                <keycombo>&Ctrl;<keycap>Q</keycap></keycombo>
+              </shortcut>
+              <guimenu>File</guimenu>
+              <guimenuitem>Quit</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>Quits &kmouth;</action></para></listitem>
+          </varlistentry>
+        </variablelist>
+    </sect2>
+
+    <sect2 id="edit-menu">
+      <title>The <guimenu>Edit</guimenu> Menu</title>
+        <variablelist>
+          <varlistentry>
+            <term><menuchoice>
+              <shortcut>
+                <keycombo>&Ctrl;<keycap>X</keycap></keycombo>
+              </shortcut>
+              <guimenu>Edit</guimenu>
+              <guimenuitem>Cut</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>
+              Cuts the selected section and puts it to the clipboard. If there
+              is some text selected in the edit field it is placed it on the
+              clipboard. Otherwise the selected sentences in the history (if
+              any) are placed on the clipboard.
+            </action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <shortcut>
+                <keycombo>&Ctrl;<keycap>C</keycap></keycombo>
+              </shortcut>
+              <guimenu>Edit</guimenu>
+              <guimenuitem>Copy</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>
+              Copies the selected section to the clipboard. If there is some
+              text selected in the edit field it is copied to the clipboard.
+              Otherwise the selected sentences in the history (if any) are
+              copied to the clipboard.
+            </action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <shortcut>
+                <keycombo>&Ctrl;<keycap>V</keycap></keycombo>
+              </shortcut>
+              <guimenu>Edit</guimenu>
+              <guimenuitem>Paste</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>
+              Pastes the clipboard contents at the current cursor position into
+              the edit field.
+            </action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <guimenu>Edit</guimenu>
+              <guimenuitem>Speak</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>
+              Speaks the currently active sentence(s). If there is some text in
+              the edit field it is spoken. Otherwise the selected sentences in
+              the history (if any) are spoken.
+            </action></para></listitem>
+          </varlistentry>
+        </variablelist>
+    </sect2>
+
+    <sect2 id="phrasebooks-menu">
+      <title>The <guimenu>Phrase Books</guimenu> Menu</title>
+        <variablelist>
+          <varlistentry>
+            <term><menuchoice>
+              <guimenu>Phrase Books</guimenu>
+              <guimenuitem>Edit...</guimenuitem>
+            </menuchoice></term>
+            <listitem><para>
+              Opens the <link linkend="phrasebook-editor">phrase book edit window</link>.
+            </para></listitem>
+          </varlistentry>
+        </variablelist>
+    </sect2>
+
+    <sect2 id="settings-menu">
+      <title>The <guimenu>Settings</guimenu> Menu</title>
+        <variablelist>
+          <varlistentry>
+            <term><menuchoice>
+              <shortcut> 
+                <keycombo>&Ctrl;<keycap>M</keycap></keycombo> 
+              </shortcut> 
+               <guimenu>Settings</guimenu>
+              <guimenuitem>Show Menubar</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>
+                When checked, this displays the menubar. When unchecked the
+                menubar is hidden.
+            </action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <guimenu>Settings</guimenu>
+              <guimenuitem>Show Toolbar</guimenuitem>
+            </menuchoice></term>
+            <listitem><para>
+              <action>
+                When checked, this displays a movable toolbar containing
+                buttons used to initiate frequently used commands. The toolbar
+                is most commonly located at the top of the editor just under
+                the menu. When unchecked the toolbar is hidden.
+              </action>
+              Clicking on the striated grip and dragging allows the user to move
+              the bar.
+            </para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <guimenu>Settings</guimenu>
+              <guimenuitem>Show Statusbar</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>
+              When checked, this displays a small bar at the bottom of the
+              main window containing information about the status of
+              &kmouth;. When unchecked the status bar is hidden.
+            </action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <guimenu>Settings</guimenu>
+              <guimenuitem>Show Phrasebook Bar</guimenuitem>
+            </menuchoice></term>
+            <listitem><para>
+              <action>
+                When checked, this displays a movable phrasebook bar containing
+                buttons for the phrasebook entries. The phrasebook bar
+                is most commonly located at the top of the editor just under
+                the toolbar. When unchecked the phrasebook bar is hidden.
+              </action>
+              Clicking on the striated grip and dragging allows the user to move
+              the bar.
+            </para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <guimenu>Settings</guimenu>
+              <guimenuitem>Configure KMouth...</guimenuitem>
+            </menuchoice></term>
+            <listitem><para>
+              Opens the <link linkend="config-dialog">configuration dialog for
+              the speech synthesizer</link> and other &kmouth; settings.
+            </para></listitem>
+          </varlistentry>
+        </variablelist>
+    </sect2>
+
+    <sect2 id="help-menu">
+      <title>The <guimenu>Help</guimenu> Menu</title>
+      &help.menu.documentation;
+    </sect2>
+
+    <sect2 id="popup-menu">
+      <title>The pop up menu of history entries</title>
+        <variablelist>
+          <varlistentry>
+            <term><menuchoice>
+              <guimenuitem>Speak</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>
+              The selected sentences are spoken.
+            </action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <guimenuitem>Delete</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>
+              The selected sentences are removed from the history.
+            </action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <guimenuitem>Cut</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>
+              The selected sentences are deleted and placed on the clipboard.
+            </action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <guimenuitem>Copy</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>
+              The selected sentences are copied to the clipboard.
+            </action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <guimenuitem>Select All Entries</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>
+              All history entries are selected.
+            </action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <guimenuitem>Deselect All Entries</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>
+              All history entries are deselected.
+            </action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <shortcut><keycombo>&Ctrl;<keycap>O</keycap></keycombo></shortcut> 
+              <guimenuitem>Open as History...</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>
+              Opens a text file into as history of spoken sentences.
+            </action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+<shortcut><keycombo>&Ctrl;<keycap>S</keycap></keycombo></shortcut> 
+              <guimenuitem>Save History As...</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>
+              Saves the history into a text file.
+            </action></para></listitem>
+          </varlistentry>
+        </variablelist>
+    </sect2>
+  </sect1>
+
+  <sect1 id="pb-editor-commands">
+    <title>Commands within the phrase book edit window</title>
+    <sect2 id="pbe-file-menu">
+      <title>The <guimenu>File</guimenu> Menu</title>
+        <variablelist>
+          <varlistentry>
+            <term><menuchoice>
+              <guimenu>File</guimenu>
+              <guimenuitem>New Phrase</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>Adds a new phrase.</action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <guimenu>File</guimenu>
+              <guimenuitem>New Phrase Book</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>Adds a new phrase book.</action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <shortcut>
+                <keycombo>&Ctrl;<keycap>S</keycap></keycombo>
+              </shortcut>
+              <guimenu>File</guimenu>
+              <guimenuitem>Save</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>Saves the phrase book.</action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <guimenu>File</guimenu>
+              <guimenuitem>Import...</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>Imports a file and adds its contents to the phrase book</action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <guimenu>File</guimenu>
+              <guimenuitem>Import Standard Phrase Book</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>Imports a standard phrase book and adds its contents to the phrase book</action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <guimenu>File</guimenu>
+              <guimenuitem>Export...</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>Exports the currently selected phrase(s) or phrase book(s) to a file</action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <shortcut>
+                <keycombo>&Ctrl;<keycap>P</keycap></keycombo>
+              </shortcut>
+              <guimenu>File</guimenu>
+              <guimenuitem>Print...</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>Prints the currently selected phrase(s) or phrase book(s)</action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <shortcut>
+                <keycombo>&Ctrl;<keycap>W</keycap></keycombo>
+              </shortcut>
+              <guimenu>File</guimenu>
+              <guimenuitem>Close</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>Closes the window</action></para></listitem>
+          </varlistentry>
+        </variablelist>
+    </sect2>
+
+    <sect2 id="pbe-edit-menu">
+      <title>The <guimenu>Edit</guimenu> Menu</title>
+        <variablelist>
+          <varlistentry>
+            <term><menuchoice>
+              <shortcut>
+                <keycombo>&Ctrl;<keycap>X</keycap></keycombo>
+              </shortcut>
+              <guimenu>Edit</guimenu>
+              <guimenuitem>Cut</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>
+              Cuts the selected items and puts it to the clipboard.
+            </action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <shortcut>
+                <keycombo>&Ctrl;<keycap>C</keycap></keycombo>
+              </shortcut>
+              <guimenu>Edit</guimenu>
+              <guimenuitem>Copy</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>
+              Copies the selected items to the clipboard.
+            </action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <shortcut>
+                <keycombo>&Ctrl;<keycap>V</keycap></keycombo>
+              </shortcut>
+              <guimenu>Edit</guimenu>
+              <guimenuitem>Paste</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>
+              Pastes the clipboard contents into the phrase book.
+            </action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <guimenu>Edit</guimenu>
+              <guimenuitem>Delete</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>
+              Deletes the selected items.
+            </action></para></listitem>
+          </varlistentry>
+        </variablelist>
+    </sect2>
+
+    <sect2 id="pbe-help-menu">
+      <title>The <guimenu>Help</guimenu> Menu</title>
+      &help.menu.documentation;
+    </sect2>
+
+    <sect2 id="pbe-popup-menu">
+      <title>The Pop up Menu</title>
+        <variablelist>
+          <varlistentry>
+            <term><menuchoice>
+              <guimenuitem>New Phrase</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>Adds a new phrase.</action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <guimenuitem>New Phrase Book</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>Adds a new phrase book.</action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <guimenuitem>Import...</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>Imports a file and adds its contents to the phrase book</action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <guimenuitem>Import Standard Phrase Book</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>Imports a standard phrase book and adds its contents to the phrase book</action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <guimenuitem>Export...</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>Exports the currently selected phrase(s) or phrase book(s) to a file</action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <shortcut> 
+                <keycombo>&Ctrl;<keycap>X</keycap></keycombo> 
+              </shortcut> 
+               <guimenuitem>Cut</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>
+              Cuts the selected items and puts it to the clipboard.
+            </action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <shortcut> 
+                <keycombo>&Ctrl;<keycap>C</keycap></keycombo> 
+              </shortcut> 
+              <guimenuitem>Copy</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>
+              Copies the selected items to the clipboard.
+            </action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <shortcut> 
+                <keycombo>&Ctrl;<keycap>V</keycap></keycombo> 
+              </shortcut> 
+              <guimenuitem>Paste</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>
+              Pastes the clipboard contents at this position into the phrase book.
+            </action></para></listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><menuchoice>
+              <guimenuitem>Delete</guimenuitem>
+            </menuchoice></term>
+            <listitem><para><action>
+              Deletes the selected items.
+            </action></para></listitem>
+          </varlistentry>
+        </variablelist>
+    </sect2>
+  </sect1>
+
+</chapter>
+
+<chapter id="faq">
+  <title>Questions and Answers</title>
+
+  &reporting.bugs;
+  &updating.documentation;
+
+  <qandaset id="faqlist">
+    <qandaentry>
+      <question>
+        <para>I do not hear anything.</para>
+      </question>
+      <answer>
+        <para>
+          Most likely you did not configure correctly (or not at all?) the
+          text-to-speech command. Use
+          <menuchoice>
+            <guimenu>Settings</guimenu><guimenuitem>Configure &kmouth;...</guimenuitem>
+          </menuchoice>, open the page <guilabel>General Options</guilabel>
+          and enter the command for speaking texts on the tab <guilabel>Text-to-Speech</guilabel>.
+          (See section about the <link linkend="tts-config">configuration
+          dialog for the speech synthesizer</link> for more details.)
+        </para>
+      </answer>
+    </qandaentry>
+  </qandaset>
+</chapter>
+
+<chapter id="credits">
+  <title>Credits and License</title>
+
+  <para>
+    &kappname;
+  </para>
+  <para>
+    Program copyright 2002-2004 Gunnar Schmi Dt<email>gunnar@schmi-dt.de</email>
+  </para>
+  <para>
+    Documentation copyright 2002-2004 Gunnar Schmi Dt <email>gunnar@schmi-dt.de</email>
+  </para>
+
+  <!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+  &underFDL;
+  &underGPL;
+</chapter>
+
+<appendix id="tts">
+  <title>Examples for the text-to-speech configuration</title>
+  <qandaset id="ttslist">
+    <qandaentry>
+      <question>
+        <para>Festival</para>
+      </question>
+      <answer>
+        <para>
+          Festival is a text-to-speech system written from the University of
+          Edinburgh. It currently supports English, Spanish and Welsh speech.
+          Its license allows to use and distribute Festival free of charge
+          without restrictions.
+        </para>
+        <para>
+          In order to create the command line example for the text-to-speech
+          configuration we assume that Festival is installed in the directory
+          <filename class="directory">/usr/local/festival/</filename>. The
+          command for speaking texts then is as follows:
+        </para>
+        <para>
+          <screen><userinput><command>/usr/local/festival/bin/festival</command> <option>--tts</option></userinput></screen>
+        </para>
+        <para>
+          The option <guilabel>Send the data as standard input</guilabel> must
+          be enabled.
+        </para>
+      </answer>
+    </qandaentry>
+    <qandaentry>
+      <question>
+        <para>FreeTTS</para>
+      </question>
+      <answer>
+        <para>
+          FreeTTS is a speech synthesizer written entirely in the &Java;™
+          programming language. It currently only has support for English
+          pronounciation. Its license allows to use and distribute FreeTTS
+          free of charge without restrictions.
+        </para>
+        <para>
+          In order to create the command line example for the text-to-speech
+          configuration we assume that FreeTTS is installed in the directory
+          <filename class="directory">/usr/local/freetts/</filename>. The
+          command for speaking texts then one of the following three examples:
+        </para>
+        <para>
+          <screen><userinput><command>java</command> <option>-jar /usr/local/freetts/lib/freetts.jar</option> <option>-text %t</option></userinput></screen>
+        </para>
+        <para>
+          <screen><userinput><command>java</command> <option>-jar /usr/local/freetts/lib/freetts.jar</option> <option>-file %f</option></userinput></screen>
+        </para>
+        <para>
+          <screen><userinput><command>java</command> <option>-jar /usr/local/freetts/lib/freetts.jar</option></userinput></screen>
+        </para>
+        <para>
+          For the third example the option <guilabel>Send the data as standard
+          input</guilabel> must be enabled. (This one is the preferred example
+          for the use with FreeTTS.)
+        </para>
+      </answer>
+    </qandaentry>
+    <qandaentry>
+      <question>
+        <para>MBROLA</para>
+      </question>
+      <answer>
+        <para>
+          MBROLA is a speech synthesizer for a large number of languages. It
+          converts a list of phonemes to a wave file, so you need some other
+          tool to convert the text into a list of phonemes. The license of
+          MBROLA allows to use and MBROLA free of charge for non-commercial,
+          non-military applications.
+        </para>
+        <para>
+          For our example we will use Hadifax in order to convert German texts
+          into a list of phonemes suitable for MBROLA. We will assume that
+          Hadifax and MBROLA are installed to
+          <filename class="directory">/usr/local/hadifax/</filename> and
+          <filename class="directory">/usr/local/mbrola/</filename>.
+        </para>
+        <para>
+          Unfortunately Hadifax tends to swallow the last character of the text,
+          so we may want to add an additional character to the text. The complete
+          command is therefore more complex than the previous examples:
+        </para>
+        <para>
+          <screen><userinput>(<command>cat</command> <option>-</option>; <command>echo</command> <option>&quot; &quot;</option>) | <command>/usr/local/hadifax/txt2pho</command> <option>-f</option>
+          | <command>/usr/local/mbrola/mbrola</command> <option>-e</option>
+          <option>/usr/local/mbrola/de1/de1 - /tmp/tmp.wav</option>;
+          <command>artsplay</command> <option>/tmp/tmp.wav</option>; <command>rm</command> <option>/tmp/tmp.wav</option></userinput></screen>
+        </para>
+        <para>
+          All parts of this command need to be written into one line. The option
+          <guilabel>Send the data as standard input</guilabel> must be enabled.
+        </para>
+      </answer>
+    </qandaentry>
+    <qandaentry>
+      <question>
+        <para>The &kde; Text-to-Speech Daemon</para>
+      </question>
+      <answer>
+        <para>
+          The &kde; Text-to-Speech Daemon (KTTSD) is a &kde; wide text-to-speech service
+          which gives &kde; applications a standardized interface for speech synthesis
+          and is currently developed in <acronym>SVN</acronym>. It uses plug-ins in
+          order to support various text-to-speech systems.
+        </para>
+        <para>
+          As the configuration of the speech synthesizer is done in KTTSD the only
+          &kmouth;-specific option you need to activate is <guilabel>Use KTTSD speech
+          service if possible</guilabel>.
+        </para>
+        <para>
+          Of course you need to configure KTTSD. You may do this with the configuration
+          page <guilabel>KTTSD Speech Service</guilabel> that is added to the configuration
+          dialog of &kmouth; if KTTSD is installed.
+        </para>
+      </answer>
+    </qandaentry>
+  </qandaset>
+</appendix>
+
+<appendix id="installation">
+  <title>Installation</title>
+
+  <sect1 id="getting-kmouth">
+    <title>How to obtain &kmouth;</title>
+
+  &install.intro.documentation;
+
+  </sect1>
+
+  <sect1 id="requirements">
+    <title>Requirements</title>
+
+    <para>
+      In order to successfully use &kmouth;, you need a speech synthesizer
+      (and of course &kde; 3.x). &kmouth; uses about 15 MB of memory to
+      run (plus the amount of memory needed by your speech synthesizer),
+      but this may vary depending on your platform and configuration.
+    </para>
+  </sect1>
+
+
+  <sect1 id="compilation">
+  <title>Compilation and Installation</title>
+
+  &install.compile.documentation;
+
+  </sect1>
+</appendix>
+
+</book>
+<!--
+Local Variables:
+mode: sgml
+sgml-minimize-attributes:nil
+sgml-general-insert-case:lower
+sgml-indent-step:0
+sgml-indent-data:nil
+End:
+-->