<page xmlns="http://projectmallard.org/1.0/" type="topic" id="preferences_speech">
  <info>
    <link type="guide" xref="preferences#orca" />
    <link type="next" xref="preferences_braille" />
    <title type="sort">2. Speech</title>
    <title type="link">Speech</title>
    <desc>
      Configuring the voice and what gets spoken
    </desc>
    <credit type="author">
      <name>Joanmarie Diggs</name>
      <email>joanied@gnome.org</email>
    </credit>
    <license>
      <p>Creative Commons Share Alike 3.0</p>
    </license>
  </info>
  <title>Speech Preferences</title>
  <section id="enable_speech">
    <title>Enable speech</title>
    <media type="image" mime="image/png" src="figures/preferences_enable_speech.png"/>
    <p>
      The <gui>Enable speech</gui> check box controls whether or not
      <app>Orca</app> will make use of a speech synthesizer.
      Braille-only users will likely want to uncheck this checkbox.
    </p>
  </section>
  <section id="tts_options">
    <title>Text-To-Speech Options</title>
    <media type="image" mime="image/png" src="figures/preferences_tts_options.png"/>
    <section>
      <title>Speech system</title>
      <p>
        This combo box allows you to select your preferred speech system from
        those you have installed. Examples include Speech Dispatcher and GNOME
        Speech.
      </p>
    </section>
    <section>
      <title>Speech synthesizer</title>
      <p>
        This combo box allows you to select the speech synthesizer to be used
        with your chosen Speech system.
      </p>
    </section>
    <section>
      <title>Voice settings</title>
      <p>
        This combo box makes it possible for you to use different voices so that
        you can better distinguish uppercase and linked text from other text,
        and on-screen text from text added by <app>Orca</app>.
      </p>
      <note style="tip">
        <title>Configuring Multiple Voices</title>
        <p>
          For each voice you wish to configure, first select the
          voice in the <gui>Voice settings</gui> combo box. Then
          configure the person, rate, pitch, and volume to be used
          for that voice.
        </p>
      </note>
    </section>
    <section>
      <title>Person</title>
      <p>
        This combo box allows you to choose which "person" or "speaker" should
        be used with the selected voice. For instance, you might wish to have
        David speak by default, but have hyperlinks spoken by Alice. Note that
        what you find in the <gui>Person</gui> combo box will depend on which
        speech synthesizers you have installed.
      </p>
    </section>
    <section>
      <title>Rate, Pitch, and Volume</title>
      <media type="image" mime="image/png" src="figures/preferences_rate_pitch_volume.png"/>
      <p>
        These three left-right sliders allow you to further customize the sound
        of the person you have just selected.
      </p>
    </section>
  </section>
  <section id="punctuation_level">
    <title>Punctuation Level</title>
    <media type="image" mime="image/png" src="figures/preferences_punctuation_level.png"/>
    <p>
      The <gui>Punctuation Level</gui> radio button group is used to
      adjust the amount of punctuation spoken by the synthesizer. The
      available levels are <gui>None</gui>, <gui>Some</gui>, <gui>Most</gui>,
      and <gui>All</gui>.
    </p>
    <section>
      <title>None</title>
      <p>
        Choosing a punctuation level of <gui>None</gui> would, as you expect,
        cause no punctuation to be spoken. Note, however, that special symbols
        such as subscripted and superscripted numbers, unicode fractions, and
        bullets are still spoken at this level, even though some might consider
        these types of symbols punctuation.
      </p>
    </section>
    <section>
      <title>Some</title>
      <p>
        Choosing a punctuation level of <gui>Some</gui> causes all of the
        previously-mentioned symbols to be spoken. In addition, <app>Orca</app>
        will speak known mathematical symbols, currency symbols, and "^", "@",
        "/", "&amp;", "#".
      </p>
    </section>
    <section>
      <title>Most</title>
      <p>
          Choosing a punctuation level of <gui>Most</gui> causes all of the
        previous-mentioned symbols to be spoken. In addition, <app>Orca</app>
        will speak all other known punctuation symbols <em>other than</em> "!",
        "'", ",", ".", "?".
      </p>
    </section>
    <section>
      <title>All</title>
      <p>
        Choosing a punctuation level of <gui>All</gui>, as expected, causes
        <app>Orca</app> to speak all known punctuation symbols.
      </p>
    </section>
    <p>
      Default value: <gui>Most</gui>
    </p>
  </section>
  <section id="verbosity">
    <title>Verbosity</title>
    <media type="image" mime="image/png" src="figures/preferences_speech_verbosity.png"/>
    <p>
      The <gui>Verbosity</gui> setting determines the amount of information
      that will be spoken in various situations. For example, if it is set
      to verbose, and you arrow into a word that is misspelled, <app>Orca</app>
      will announce that the word is misspelled. When the level is set to brief,
      this announcement will not be made.
    </p>
    <p>
      Default value: <gui>Verbose</gui>
    </p>
  </section>
  <section id="table_rows">
    <title>Table Rows</title>
    <media type="image" mime="image/png" src="figures/preferences_table_rows.png"/>
    <p>
      The <gui>Table Rows</gui> radio button group determines what gets
      spoken when navigating amongst rows in a table. The available
      options are <gui>speak row</gui> and <gui>speak cell</gui>.
    </p>
    <p>
      Consider the process of examining the list of messages in your Inbox.
      In order to have <app>Orca</app> announce the sender, subject, date,
      and presence of attachments you would need <gui>speak row</gui>. On
      the other hand, when navigating amongst rows in a spreadsheet, hearing
      the full row may not be desired. In that case, <gui>speak cell</gui>
      should instead be chosen.
    </p>
      <p>
        Default value: <gui>Speak row</gui>
      </p>
  </section>
  <section id="progress_bar_updates">
    <title>Progress Bar Updates</title>
    <media type="image" mime="image/png" src="figures/preferences_progress_bar_updates.png"/>
    <section>
      <title>Enabled</title>
      <p>
        If the <gui>Enabled</gui> checkbox is checked <app>Orca</app> will
        periodically present the status of progress bars.
      </p>
      <p>
        Default value: checked
      </p>
    </section>
    <section>
      <title>Frequency (secs)</title>
      <p>
        This spin button determines how often the announcement is made.
      </p>
      <p>
        Default value: 10
      </p>
    </section>
    <section>
      <title>Restrict to</title>
      <p>
         This combo box allows you to control which progress bars should be
         presented, assuming the presentation of progress bar updates has been
         enabled. The choices are <gui>All</gui>, <gui>Application</gui>, and
         <gui>Window</gui>.
      </p>
      <p>
        Choosing <gui>All</gui> will result in <app>Orca</app> presenting
        updates for all progress bars, regardless of where the progress bars
        are located.
      </p>
      <p>
        Choosing <gui>Application</gui> will result in <app>Orca</app>
        presenting updates from progress bars in the active application, even
        if they are not in the active window.
      </p>
      <p>
         Choosing <gui>Window</gui> will result in <app>Orca</app> only
         presenting updates for progress bars in the active window.
      </p>
      <p>
        Default value: <gui>Application</gui>
      </p>
    </section>
  </section>
  <section id="only_speak_displayed_text">
    <title>Only speak displayed text</title>
    <media type="image" mime="image/png" src="figures/preferences_only_speak_displayed_text.png"/>
    <p>
      Checking this checkbox causes <app>Orca</app> to only speak actual
      text displayed on screen. This option is intended primarily for low
      vision users and users with a visual learning disability.
    </p>
  </section>
  <section id="multicase_strings">
    <title>Speak multicase strings as words</title>
    <media type="image" mime="image/png" src="figures/preferences_speak_multicase_strings_as_words.png"/>
    <p>
      In some texts, and especially when working with code, one often comes
      across a "word" consisting of several words with alternating case, such
      as "MultiCaseString." Speech synthesizers do not always pronounce such
      multicase strings correctly. Checking the <gui>Speak multicase strings
      as words</gui> checkbox will cause <app>Orca</app> to break a word like
      "MultiCaseString" into separate words ("Multi," "Case," and "String")
      prior to passing it along to the speech synthesizer.
    </p>
  </section>
  <section id="pauses">
    <media type="image" mime="image/png" src="figures/preferences_break_speech_into_chunks.png"/>
    <title>Break speech into chunks between pauses</title>
    <p>
      Depending on the enabled speech settings, <app>Orca</app> may have quite
      a bit to say about a particular object such as its name, its role, its
      state, its mnemonic, its tutorial message, and so on. Checking the
      <gui>Break speech into chunks between pauses</gui> checkbox will cause
      <app>Orca</app> to insert brief pauses in between each of these pieces
      of information.
    </p>
  </section>
  <section id="say_all_by">
    <media type="image" mime="image/png" src="figures/preferences_say_all_by.png"/>
    <title>Say All By</title>
    <p>
      The <gui>Say All By</gui> combo box allows you to specify whether
      <app>Orca</app> speaks a sentence at a time or a line at a time when
      doing a "Say All" of a document.
    </p>
  </section>
  <section id="system_voice_items">
    <title>System Information</title>
    <media type="image" mime="image/png" src="figures/preferences_system_voice_options.png"/>
    <p>
      The following items control the presentation of a variety of
      supplemental, "system" information about the item with focus.
      Because the associated text does not appear on screen, this
      information is presented in <app>Orca</app>'s System voice.
    </p>
    <note style="note">
      <title>Configuration of System Information</title>
      <p>
        The follow items will not be available for configuration if
        the <gui>Only speak displayed text</gui> checkbox is checked.
      </p>
      </note>
      <section id="speak_blank_lines">
        <title>Speak blank lines</title>
        <p>
          If the <gui>Speak blank lines</gui> checkbox is checked,
          <app>Orca</app> will say "blank" each time you arrow to a blank
          line. If it is unchecked, <app>Orca</app> will say nothing when
          you move to a blank line.
        </p>
      </section>
      <section id="indentation_and_justification">
        <title>Speak indentation and justification</title>
        <p>
          When working with code or editing other documents it is often
          desirable to be aware of justification and indentation. Checking
          the <gui>Speak indentation and justification</gui> checkbox will
          cause <app>Orca</app> to announce this information.
        </p>
      </section>
      <section id="mnemonics">
       <title>Speak object mnemonics</title>
        <p>
          If the <gui>Speak object mnemonics</gui> checkbox is checked,
          <app>Orca</app> will announce the mnemonic associated with the
          object with focus (such as <keyseq><key>Alt</key><key>O</key>
          </keyseq> for an <gui>OK</gui> button).
        </p>
      </section>
    <section id="child_position">
      <title>Speak child position</title>
      <p>
        Checking the <gui>Speak child position</gui> checkbox will cause
        <app>Orca</app> to announce the position of the focused item in
        menus, lists, and trees (e.g. "9 of 16").
      </p>
    </section>
    <section id="speak_tutorial_messages">
      <title>Speak tutorial messages</title>
      <p>
        If the <gui>Speak tutorial messages</gui> checkbox is checked, as
        you move amongst objects in an interface, <app>Orca</app> will
        provide additional information, such as how to interact with the
        currently-focused object.
      </p>
    </section>
  </section>
</page>
