<page xmlns="http://projectmallard.org/1.0/" type="topic" id="howto_text_setup">
  <info>
    <desc>
      A feature which allows you to perform basic configuration of <app>Orca</app> even
      if the graphical desktop is not running.
    </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>Using Text Setup</title>
  <p>
    Orca has a text setup feature which allows you to perform basic configuration
    of <app>Orca</app> even if the graphical desktop is not running.
  </p>
  <steps>
    <title>Launching <app>Orca</app>'s Text-Only Guided Setup</title>
    <item>
      <p>
        Open a <gui>Run</gui> dialog. For most distros, this can be accomplished
        by pressing <keyseq><key>Alt</key><key>F2</key></keyseq>. Alternatively,
        you can use a terminal window or the system text console.
      </p>
    </item>
    <item>
      <p>
        Type <cmd>orca --text-setup</cmd> or <cmd>orca -t</cmd> and press
       <key>Return</key>.
      </p>
    </item>
  </steps>
  <p>You will be asked a few questions:</p>
  <steps>
    <item>
      <p>Select desired speech system</p>
      <p>
        The choices that follow will depend on which speech systems you have
        installed on your system. Type the number associated with your desired
        speech system and press <key>Return</key>.
      </p>
    </item>
    <item>
      <p>Select desired speech server</p>
      <p>
        The choices that follow will depend on which speech synthesizers you have
        installed on your system. Type the number associated with your desired
        speech server and press <key>Return</key>.
      </p>
    </item>
    <item>
      <p>Select desired voice</p>
      <p>
        The "voices" correspond with the languages available. In the case of
        speech-dispatcher, there are approximately 60 languages and dialects
        supported with more being added regularly. Type in the number of your
       language choice (e.g., <cmd>7</cmd> for American English) and press
       <key>Return</key>. You do not need to wait for the entire list to be
       spoken. In addition, <app>Orca</app> attempts to make your default
       language the first choice, so in many cases you can simply type
       <cmd>1</cmd> and press <key>Return</key> without having to listen to
       the full list of voices.</p>
    </item>
    <item>
      <p>Enable echo by word?</p>
      <p>
        This option causes <app>Orca</app> to speak words as you finish typing
        them. Type <cmd>y</cmd> or <cmd>n</cmd> and press <key>Return</key>.
      </p>
    </item>
    <item>
      <p>Enable key echo?</p>
      <p>
        This option causes <app>Orca</app> to speak all keys as they are pressed.
        Type <cmd>y</cmd> or <cmd>n</cmd> and press <key>Return</key>.
      </p>
      <p>
        If you indicate that you would like key echo enabled, setup will then
        ask you about the types of key echo you can enable or disable. For each
        one, type <cmd>y</cmd> to enable it or <cmd>n</cmd> to disable it and
        press <key>Return</key>. The types are:
      </p>
      <list>
        <item>
          <p>alphanumeric and punctuation keys</p>
          <p>
            This option controls whether or not keys like <key>a</key>,
            <key>b</key>, <key>c</key>, <key>;</key>, <key>?</key>, and so on
            should be spoken when pressed.
          </p>
        </item>
        <item>
          <p>modifier keys</p>
          <p>
            This option controls whether or not <key>Shift</key>, <key>Ctrl</key>,
            <key>Alt</key> and <key>Meta</key> should be spoken when pressed.
          </p>
        </item>
        <item>
          <p>locking keys</p>
          <p>
            This option controls whether or not <key>Caps Lock</key>, <key>Scroll
            Lock</key>, and <key>Num Lock</key> should be spoken when pressed.
          </p>
        </item>
        <item>
          <p>function keys</p>
          <p>
            This option controls whether or not <key>F1</key> through <key>F12</key>
            should be spoken when pressed.
          </p>
        </item>
        <item>
          <p>action keys</p>
          <p>
            This option controls whether or not <key>BackSpace</key>,
            <key>Delete</key>, <key>Return</key>, <key>Escape</key>,
            <key>Tab</key>, <key>Page Up</key>, <key>Page Down</key>,
            <key>Home</key>, and <key>End</key> should be spoken when
            pressed.
          </p>
        </item>
      </list>
    </item>
    <item>
      <p>Select desired keyboard layout.</p>
      <p>
        Orca has two keyboard layouts: Desktop and Laptop. The layout you
        choose impacts which key is used as the Orca Modifier.
      </p>
      <list>
        <item>
          <p>
            If you are using the Laptop layout, the default Orca Modifier will
            be <key>CapsLock</key>
          </p>
        </item>
        <item>
          <p>
            If you are using the Desktop layout, the Orca Modifier will be both
           <key>Insert</key> and <key>KeyPad Insert</key>, the latter being the
           same key as <key>KeyPad 0</key>.
          </p>
        </item>
      </list>
      <p>
        The layout also determines the keystrokes associated with a number of
        <app>Orca</app>'s commands, especially in the areas of Flat Review,
        Where Am I, and Say All.
      </p>
      <p>
        Type <cmd>1</cmd> for Desktop layout or <cmd>2</cmd> for Laptop layout
        and press <key>Return</key>.
      </p>
    </item>
    <item>
      <p>Enable Braille</p>
      <p>
        This functionality assumes a BrlTTY-compatible device is available.
        Type <cmd>y</cmd> or <cmd>n</cmd> and press <key>Return</key>. Note
        that you can usually just enter <cmd>y</cmd> here; <app>Orca</app> will
        recover gracefully and function even if it cannot find BrlTTY.
      </p>
    </item>
    <item>
      <p>Enable Braille Monitor</p>
      <p>
        Orca's Braille Monitor is an on-screen braille representation. This is
        mostly for sighted developers who need to verify BrlTTY output, but may
        also be useful in other situations, such as visually diagnosing or verifying
        braille output. Type <cmd>y</cmd> or <cmd>n</cmd> and press <key>Return</key>.
      </p>
    </item>
    <item>
      <p>Automatically start <app>Orca</app> when you log in</p>
      <p>
        Type <cmd>y</cmd> if you want <app>Orca</app> automatically launched for you
        or <cmd>n</cmd> if you do not, and press <key>Return</key>.
      </p>
    </item>
  </steps>
  <p>
    That's it. <app>Orca</app> is now ready for use. If accessibility was not
    yet enabled, <app>Orca</app> does so now and asks you to logout and back
    in for the services to start. Type <cmd>y</cmd> and press <key>Return</key>
    to restart your login session. If, on the other hand, accessibility was
    already enabled, you will simply be prompted to press <key>Return</key>
    after which <app>Orca</app> will be launched for you.
  </p>
</page>
