[orca] Update internals docs. Did not touch script writing guide yet.

[William Walker <wwalker src gnome org>]

commit 5cdbe63b789a0aa5019a5f25ba28f60fbd977f17
Author: Willie Walker <william walker sun com>
Date:   Sun Apr 19 01:20:15 2009 -0400

    Update internals docs.  Did not touch script writing guide yet.
---
 docs/doc-set/architecture.png  |  Bin 0 -> 703147 bytes
 docs/doc-set/architecture.sgml |  540 +++++++++++++++++++------------------
 docs/doc-set/blurb.sgml        |   30 ++-
 docs/doc-set/diagrams.odg      |  Bin 138112 -> 139196 bytes
 docs/doc-set/internals.html    |  587 +++++++++++++++++++++-------------------
 docs/doc-set/internals.sgml    |  106 ++++---
 docs/doc-set/legal.sgml        |    4 +-
 7 files changed, 663 insertions(+), 604 deletions(-)

diff --git a/docs/doc-set/architecture.png b/docs/doc-set/architecture.png
new file mode 100644
index 0000000..4b74443
Binary files /dev/null and b/docs/doc-set/architecture.png differ
diff --git a/docs/doc-set/architecture.sgml b/docs/doc-set/architecture.sgml
index 8ddfbc4..ef46793 100644
--- a/docs/doc-set/architecture.sgml
+++ b/docs/doc-set/architecture.sgml
@@ -1,4 +1,4 @@
-<!-- Copyright 2005-2008, Sun Microsystems, Inc. -->
+<!-- Copyright 2005-2009, Sun Microsystems, Inc. -->
 
   <!--
   ************************************************************************
@@ -9,56 +9,59 @@
   -->
 
   <chapter id="architecture"><title>Architecture</title>
-
     <para>The Orca architecture has been driven primarily by the Orca
-      User Experience Design.  There are two primary operating modes
-      of Orca: a focus tracking mode and a flat review mode.</para>
-
-    <para>The focus tracking mode generally relies upon applications
-      to provide reasonable keyboard navigation techniques to allow
-      the user to operate the application without requiring the mouse.
-      As the user uses traditional keyboard navigation techniques to
-      move from component to component in the application (e.g.,
-      pressing the Tab key to move from pushbutton to text area to
-      toggle button, etc.), Orca will present this to the user via
-      braille, speech, magnification, or a combination thereof.  In
-      the cases where more complex navigation is needed, such as
-      structural navigation of complex text documents, Orca also
-      provides a facility to define keyboard and braille input events
-      that it can intercept and handle appropriately.</para>
+    User Experience Design.  There are two primary operating modes
+    of Orca: a focus tracking mode and a flat review mode.</para>
+
+    <para>The focus tracking mode is the preferred mode of operation.
+    It generally relies upon applications to provide reasonable
+    keyboard navigation techniques to allow the user to operate the
+    application without requiring the mouse.  As the user uses
+    traditional keyboard navigation techniques to move from component
+    to component in the application (e.g., pressing the Tab key to
+    move from pushbutton to text area to toggle button, etc.), Orca
+    will present this to the user via braille, speech, magnification,
+    or a combination thereof.  In the cases where more complex
+    navigation is needed, such as structural navigation of complex
+    text documents, Orca also provides a facility to define keyboard
+    and braille input events that it can intercept and handle
+    appropriately.</para>
 
     <para>The flat review mode provides the user with the ability to
-      spatially navigate a window, giving them the ability to explore
-      as well as discover and interact with components in the window.
-      Orca provides a default set of keybindings for flat review, and
-      these keybindings can be easily redefined by the user.</para>
-
-    <para>The various modes of Orca are handled by "scripts," which
-      are Python modules that can provide a custom interpretation of
-      an application's interaction model.  It is not intended that 
-      there will be a unique script for every application.  Instead,
-      it is expected that there will be a general purpose script that
-      covers a large number of applications.  In the event that more
-      compelling or custom behavior is desired for an application,
-      however, one can use a custom script for the application.
-      Furthermore, scripts can subclass other scripts, allowing
-      them to be quite simple.</para>
+    spatially navigate a window, giving them the ability to explore as
+    well as discover and interact with components in the window. This
+    mode is not a preferred mode, but is instead intended to allow a
+    user to interact with ill-behaved applications.  Orca provides a
+    default set of keybindings for flat review, and these keybindings
+    can be easily redefined by the user.</para>
+
+    <para>The focus tracking mode of Orca is handled by "scripts,"
+    which are Python modules that can provide a custom interpretation
+    of an application's interaction model.  It is not intended that
+    there will be a unique script for every application.  Instead, it
+    is expected that there will be a general purpose "default" script
+    that covers a large number of applications.  In the event that
+    more compelling or custom behavior is desired for an application,
+    however, one can use a custom script for the application.
+    Furthermore, scripts can subclass other scripts, allowing them to
+    be quite simple. In practice, all the custom scripts extend the
+    "default" script.</para>
 
     <para>As illustrated in the high level Orca architecture diagram,
-      the main components of Orca are as follows: desktop applications
-      that support the AT-SPI, the AT-SPI registry and infrastructure,
-      Orca itself, Orca Scripts, and system services (e.g., speech,
-      braille, magnification).</para>
+    the main components of Orca are as follows: desktop applications
+    that support the AT-SPI, the AT-SPI registry and infrastructure,
+    Orca itself, Orca Scripts, and system services (e.g., speech,
+    braille, magnification).</para>
 
     <figure>
       <title>High Level Orca Architecture. The main components of Orca
-        are as follows: desktop  applications that support the AT-SPI,
-        the  AT-SPI  registry and  infrastructure,  Orca itself,  Orca
-        Scripts, and  system services.  The  key communication between
-        the components is depicted.</title>
+      are as follows: desktop applications that support the AT-SPI,
+      the AT-SPI registry and infrastructure, Orca itself, Orca
+      Scripts, and system services.  The key communication between the
+      components is depicted.</title>
       <mediaobject>
         <imageobject>
-          <imagedata fileref="architecture.jpg" format="JPEG"/>
+          <imagedata fileref="architecture.png" format="PNG"/>
         </imageobject>
         <textobject>
           <phrase>High Level Orca Architecture</phrase>
@@ -67,34 +70,39 @@
     </figure>
 
     <para>The following sections describe the architecture in more
-      detail.</para>
+    detail.</para>
 
     <section id="archdesktop"><title>Desktop and AT-SPI</title>
-
       <para>Orca's sole view of any application on the desktop is via
-        the AT-SPI <citation><xref linkend="at-spi"
-        endterm="at-spi.abbrev"/></citation>.  The AT-SPI is an
-        IDL/CORBA/Bonobo-based technology <citation><xref linkend="bonobo"
-        endterm="bonobo.abbrev"/></citation> that provides a common
-        interface for the desktop and its applications to expose their
-        GUI component hierarchy to assistive technologies such as
-        Orca.  AT-SPI support is provided by toolkits such as GNOME's
-        GTK+ toolkit (via gail <citation><xref linkend="gail"
-        endterm="gail.abbrev"/></citation>), the Java platform (via
-        the Java access bridge), and the custom
-        toolkits used by applications such as Mozilla and Open
-        Office.  Future support includes the Qt toolkit of KDE.</para>
+      the AT-SPI <citation><xref linkend="at-spi"
+      endterm="at-spi.abbrev"/></citation>.  The AT-SPI is an
+      IDL/CORBA/Bonobo-based
+      technology <citation><xref linkend="bonobo"
+      endterm="bonobo.abbrev"/></citation> that provides a common
+      interface for the desktop and its applications to expose their
+      GUI component hierarchy to assistive technologies such as Orca.
+      &note; the AT-SPI infrastructure is being migrated to D-Bus for
+      GNOME 3.0.  This migration should have little impact on the
+      architecture or code of Orca.  In other words, do you worry
+      'bout a thing.</para>
+
+      <para>AT-SPI support is provided by toolkits such as GNOME's
+      GTK+ toolkit (via GAIL <citation><xref linkend="gail"
+      endterm="gail.abbrev"/></citation>), the Java platform (via the
+      Java access bridge), and the custom toolkits used by
+      applications such as Mozilla and Open Office.  Future support
+      includes the Qt toolkit of KDE.</para>
 
       <para>Assistive Technologies interact with the AT-SPI via two
-        primary means: the AT-SPI registry and accessible objects.
-        The AT-SPI registry permits assistive technologies to discover
-        existing applications on the desktop and to register for event
-        notification for AT-SPI events (e.g., window creation, focus
-        changes, object state changes, etc.) and device events (e.g.,
-        keyboard input events).  Accessible objects provide the
-        assistive technology with information about the application,
-        and tend to mirror the actual GUI component hierarchy.
-        Accessible objects can be obtained in three ways: </para>
+      primary means: the AT-SPI registry and accessible objects.  The
+      AT-SPI registry permits assistive technologies to discover
+      existing applications on the desktop and to register for event
+      notification for AT-SPI events (e.g., window creation, focus
+      changes, object state changes, etc.) and device events (e.g.,
+      keyboard input events).  Accessible objects provide the
+      assistive technology with information about the application, and
+      tend to mirror the actual GUI component hierarchy.  Accessible
+      objects can be obtained in three ways: </para>
 
       <orderedlist numeration="arabic">
         <listitem>
@@ -110,256 +118,252 @@
         </listitem>
       </orderedlist>
 
-      <para>Orca's interaction with the AT-SPI is managed through
-        Orca's <literal>atspi.py</literal> module.  The
-        <literal>atspi.py</literal> module communicates directly with
-        the AT-SPI via the AT-SPI IDL interfaces and also provides a
-        number of classes that help with AT-SPI interaction:
-        <literal>Registry</literal>, <literal>Accessible</literal>,
-        and <literal>Event</literal>.  The full documentation for
-        each of these classes is available in the pydoc for Orca
-	while the following paragraphs provide a brief overview.</para>
-
-      <para>The <literal>Registry</literal> class provides a singleton
-        class instance to access to the AT-SPI
-        registry.  It provides convenience methods for registering
-        AT-SPI event listeners and device event listeners, and also
-        provides the mechanism for starting and stopping event
-        delivery from the AT-SPI registry.</para>
-
-      <para>The <literal>Accessible</literal> class provides a wrapper
-        for communicating with CORBA objects that implement the AT-SPI
-        Accessible and Application interfaces. Using Python's ability
-        to add new properties to a class instance at run time, Orca
-        can also annotate Accessible class instances with additional
-        information.  The main purpose of an Accessible is to provide
-        a local cache for accessible objects, preventing the need for
-        numerous round trip calls to the AT-SPI registry and
-        application for information.</para>
-
-      <para>The <literal>Event</literal> class provides a wrapper for
-        converting AT-SPI events into Python <literal>Event</literal>
-        instances.  The main purpose is to convert the AT-SPI
-        accessible source of the event into a Python
-        <literal>Accessible</literal> instance and to also provide an
-        <literal>Event</literal> instance that can be annotated by
-        scripts (the actual AT-SPI event delivered by the registry is 
-	read-only).</para>
+      <para>Orca's interaction with the AT-SPI is managed through the
+      <literal>pyatspi.py</literal> module that is part of AT-SPI.  The
+      <literal>pyatspi.py</literal> module communicates directly with
+      the AT-SPI number of classes that help with AT-SPI interaction.
+      The best ways to learn AT-SPI are as follows:
+
+      <orderedlist numeration="arabic">
+        <listitem>
+          <para>Read the AT-SPI interface documentation.</para>
+        </listitem>
+        <listitem>
+          <para>Run the <literal>accerciser</literal> application to
+          examine the accessibility information of desktop
+          applications.  This includes analyzing the accessible
+          hierarchy as well as watching events that are issued as
+          you interact with desktop applcations.</para>
+        </listitem>
+        <listitem>
+          <para>Enable the debug mode of Orca as described on the
+          <ulink url="http://live.gnome.org/Orca/Debugging";>Orca
+          WIKI</ulink>.  Run Orca and interact with an
+          application. Then, quit Orca and analyze the debug
+          log.</para>
+        </listitem>
+      </orderedlist>
+      </para>
 
       <para>As illustrated in the high level Orca architecture
-        diagram, the <literal>atspi</literal> module has been used to
-        register event and device listeners with the AT-SPI registry.
-        Each exemplary desktop application (Firefox, NetBeans, GAIM,
-        StarOffice) emits AT-SPI events to the AT-SPI registry which
-        then delivers them to the <literal>atspi</literal> module.
-        The <literal>atspi</literal> module then calls all appropriate
-        listeners for the events it receives from the AT-SPI
-        registry.</para>
+      diagram, the <literal>pyatspi</literal> module has been used to
+      register event and device listeners with the AT-SPI registry.
+      Each exemplary desktop application (Firefox, Evolution, Pidgin,
+      and OpenOffice) emits AT-SPI events to the AT-SPI registry which
+      then delivers them to the <literal>pyatspi</literal> module.
+      The <literal>pyatspi</literal> module then calls all appropriate
+      listeners for the events it receives from the AT-SPI
+      registry.</para>
 
       <para>In this case, the <literal>orca</literal> module receives
-        keyboard events, which it interprets and also sends on to the
-        <literal>focus_tracking_presenter</literal> module.  Of more
-        interest, however, is that the
-        <literal>focus_tracking_presenter</literal> module receives
-        AT-SPI events which it then passes on the script for the
-        application associated with the event.  If there is no script,
-        the <literal>focus_tracking_presenter</literal> will create an
-        instance of the default script.  See the &scriptguidelink; for
-        more information.</para>
-
-      <para>The <literal>atspi</literal> module also registers its
-        own set of event listeners that it uses to keep its local
-        cache of accessible objects up to date.</para>
+      keyboard events, which it interprets and also sends on to the
+      <literal>focus_tracking_presenter</literal> module (not depicted
+      in the illustration).  Of more
+      interest, however, is that the
+      <literal>focus_tracking_presenter</literal> module receives
+      AT-SPI events which it then passes on the script for the
+      application associated with the event.  If there is no script,
+      the <literal>focus_tracking_presenter</literal> will create an
+      instance of the default script.  See the &scriptguidelink; for
+      more information.</para>
 
       <para>&detail; Because processing AT-SPI object events can be
-        time consuming, and because the notification of AT-SPI object
-        events is relatively "bursty," the
-        <literal>focus_tracking_presenter</literal> maintains a queue
-        of AT-SPI object and input device events. It adds the events
-        to this queue when it receives them and processes the events
-        on the GLib idle handling thread.  This permits Orca to
-        survive a relatively long burst of events and also allows it
-        to handle the events on a thread that is compatible with
-        GLib.</para>
-
+      time consuming, and because the notification of AT-SPI object
+      events is relatively "bursty," the
+      <literal>focus_tracking_presenter</literal> maintains a queue of
+      AT-SPI object and input device events. It adds the events to
+      this queue when it receives them and processes the events on the
+      GLib idle handling thread.  This permits Orca to survive a
+      relatively long burst of events and also allows it to handle the
+      events on a thread that is compatible with GLib.</para>
     </section>
 
     <section id="archorca"><title>Orca Module</title>
-
       <para>The <literal>orca</literal> module is the "main entry
-        point" of Orca.  It initializes the components that Orca uses
-        (atspi, speech, braille, mag) and loads the user's settings.
-        It also is the first to receive all keyboard and braille input
-        events and delves them out to other Orca components
-        appropriately.</para>
+      point" of Orca.  It initializes the components that Orca uses
+      (pyatspi, speech, braille, mag) and loads the user's settings.
+      It also is the first to receive all keyboard and braille input
+      events and delves them out to other Orca components
+      appropriately.</para>
 
       <para>The <literal>orca</literal> module maintains the current
-        known "locus of focus" in the <literal>locusOfFocus</literal>
-        field of the <literal>orca_state</literal> module.  The
-        <literal>locusOfFocus</literal> is intended to represent the
-        current object that the user is working with.  In simple
-        terms, it is the object that is highlighted or has the dotted
-        line drawn around it.  Be advised that the notion of "focus"
-        differs from toolkit to toolkit.  For example, the object with
-        toolkit focus may actually be the parent of the object that is
-        highlighted.  The <literal>locusOfFocus</literal> is an an
-        attempt to neutralize these differences across toolkits: the
-        locus of focus is the individual object that is highlighted,
-        has the caret, etc.</para>
-
-      <para>Orca scripts set the locus of focus to inform Orca when
-        the locus of focus has changed.  In addition, in the event
-        that there was a visual appearance change to the object that
-        has the locus of focus, the <literal>orca</literal> module
-        provides a <literal>visualAppearanceChanged</literal> that
-        scripts can use to inform Orca of this event.</para>
+      known "locus of focus" in the <literal>locusOfFocus</literal>
+      field of the <literal>orca_state</literal> module.  The
+      <literal>orca_state.locusOfFocus</literal> field is intended to
+      represent the current object that the user is working with.  In
+      simple terms, it is the object that is highlighted or has the
+      dotted line drawn around it.  Be advised that the notion of
+      "focus" differs from toolkit to toolkit.  For example, the
+      object with toolkit focus may actually be the parent of the
+      object that is highlighted.  As such,
+      the <literal>orca_status.locusOfFocus</literal> field is an an
+      attempt to neutralize these differences across toolkits: the
+      locus of focus is the individual object that is highlighted, has
+      the caret, etc.</para>
+
+      <para>Orca scripts
+      set <literal>orca_state.locusOfFocus</literal> to inform Orca
+      when the locus of focus has changed.  In addition, in the event
+      that there was a visual appearance change to the object that has
+      the locus of focus, the <literal>orca</literal> module provides
+      a <literal>visualAppearanceChanged</literal> that scripts can
+      use to inform Orca of this event.</para>
 
       <para>&note; The <literal>orca_state.locusOfFocus</literal>
-        field is intended to be set only via the
-        <literal>setLocusOfFocus</literal> method of the
-        <literal>orca</literal> module. Because the
-        <literal>setLocusOfFocus</literal> method performs bookkeeping
-        and other tasks, the
-        <literal>orca_state.locusOfFocus</literal> field should never
-        be set directly.</para>
+      field is intended to be set only via the
+      <literal>setLocusOfFocus</literal> method of the
+      <literal>orca</literal> module. Because the
+      <literal>orca.setLocusOfFocus</literal> method performs bookkeeping
+      and other tasks, the
+      <literal>orca_state.locusOfFocus</literal> field should never be
+      set directly.</para>
 
       <section id="archsettings"><title>settings</title> 
-
-        <para>The <emphasis role="bold">settings</emphasis> module
-          (not depicted in the high level Orca architecture diagram)
-          holds preferences set by the user during configuration.
-          These settings include the following: use of speech and/or
-          braille, voice styles, key echo, text echo, and command
-          echo.</para>
+        <para>The <literal>settings</literal> module (not depicted in
+        the high level Orca architecture diagram) holds preferences
+        set by the user during configuration.  These settings include
+        the following: use of speech, braille, and/or magnification,
+        voice styles, key echo, text echo, etc.</para>
 
         <para>Any Orca module can check the value of a setting by
-          examining the field directly in the
-          <literal>settings</literal> module.  In addition, the
-          <literal>orca</literal> module will import the
-          <literal>user-settings</literal> module from the
-          <literal>~/.orca directory</literal>, if it exists (it
-	  is created as part of the configuration process that
-	  is run the first time Orca is used or when the user
-	  presses Insert+Space to invoke the configuration GUI).</para>
+        examining the field directly in the
+        <literal>settings</literal> module.  In addition, the
+        <literal>orca</literal> module will import the
+        <literal>user-settings</literal> module from the
+        <literal>~/.orca directory</literal>, if it exists.
+        The <literal>user-settings</literal> module is
+	created as part of the configuration process that is run the
+	first time Orca is used or when the user presses 
+	<literal>Insert+Space</literal> to invoke the configuration
+	GUI.</para>
 
 	<para>The <literal>user-settings</literal> module is a Python
-          script, allowing it to contain functions, class definitions,
-          etc.  The primary job of the
-          <literal>user-settings</literal> is to directly set the
-          values of fields in the <literal>settings</literal>
-          module.</para>
+        script, allowing it to contain functions, class definitions,
+        etc.  The primary job of the
+        <literal>user-settings</literal>, however, is to directly set
+        the values of fields in the <literal>settings</literal>
+        module.</para>
 
         <para>&detail; the <literal>init</literal> method of the
-          <literal>orca</literal> module obtains settings.  As a
-          result, the <literal>user-settings</literal> module is
-          imported very early in the Orca life cycle.</para>
-
+        <literal>orca</literal> module obtains settings.  As a
+        result, the <literal>user-settings</literal> module is
+        imported very early in the Orca life cycle.</para>
       </section>
     </section>
 
     <section id="script"><title>Orca Scripts</title>
-
-      <para>Internally, the <literal>orca</literal> module keeps track
-        of list of <literal>PresentationManager</literal> instances
-        (see the pydoc for
-        <literal>presentation_manager.py</literal>). The
-        <literal>FocusTrackingPresenter</literal> (see
-        <literal>focus_tracking_presenter</literal>) is of the most
-        interest, as it is the <literal>PresentationManager</literal>
-        that manages scripts.</para>
+      <para>The <literal>orca</literal> module creates a single
+      instance of a <literal>FocusTrackingPresenter</literal> (defined
+      in the
+      <literal>focus_tracking_presenter</literal> module), which manages
+      all the scripts for Orca.</para>
 
       <para>Details on the <literal>FocusTrackingPresenter</literal>
-        and Orca scripts can be found in the
-        &scriptguidelink;.</para>
-
+      and Orca scripts can be found in the &scriptguidelink;.</para>
     </section>
 
     <section id="archsystemservices"><title>System Services</title>
-
       <para> Orca relies on existing system services to provide
-        support for speech synthesis, braille, and screen
-        magnification.  To interact with these services, Orca provides
-        the modules described in the following sections.
-      </para>
+      support for speech synthesis, braille, and screen magnification.
+      To interact with these services, Orca provides the modules
+      described in the following sections.</para>
 
       <section id="archspeech"><title>speech</title>
-
-        <para>The <emphasis role="bold">speech</emphasis> module
-          provides Orca's Python interface to system speech services.
-          Each speech service is generated by a "speech server
-          factory."  There are currently two such factories: one for
-          <citation><xref linkend="gnome-speech"
-          endterm="gnome-speech.abbrev"/></citation> (see
-          <literal>gnomespeechfactory.py</literal> and one for
-          <citation><xref linkend="emacspeak"
-          endterm="emacspeak.abbrev"/></citation> (see
-          <literal>espeechfactory.py</literal>), though it is expected
-          that support for other factories can be added in the
-          future.</para>
+        <para>All speaking operations should be done by calling
+        methods in the <literal>speech</literal> module.
+        The <literal>speech</literal> module provides Orca's Python
+        interface to system speech services.  Each speech service is
+        generated by a "speech server factory."  There are currently
+        three such factories: one for
+        <citation><xref linkend="gnome-speech"
+        endterm="gnome-speech.abbrev"/></citation> (see the
+        <literal>gnomespeechfactory</literal> module), one for
+        <citation><xref linkend="emacspeak"
+        endterm="emacspeak.abbrev"/></citation> (see the
+        <literal>espeechfactory</literal> module), and one for
+        SpeechDispatcher (see
+        the <literal>speechdispatcherfactory</literal> module).
+        Currently, the only officially supported factory is the one
+        provided by the <literal>gnomespeechfactory</literal>
+        module.</para>
           
         <para>Each speech factory offers up a list of
-          <literal>SpeechServer</literal>s, where each
-          <literal>SpeechServer</literal> is typically an interface to
-          a particular speech engine.  For example, the
-          <literal>espeechfactory</literal> will offer up a
-          <literal>SpeechServer</literal> that talks to the Fonix
-          DECtalk engine and a <literal>SpeechServer</literal> that
-          talks to the IBMTTS engine.  Likewise, the
-          <literal>gnomespeechfactory</literal> will offer up a
-          <literal>SpeechServer</literal> that uses the
-          <literal>gnome-speech</literal> interface to talk to the
-          Festival Speech Synthesis System, a separate
-          <literal>SpeechServer</literal> that also uses the
-          <literal>gnome-speech</literal> interface to talk to the
-          Fonix DECtalk engine, and so on.</para>
-
-        <para>Each <literal>SpeechServer</literal> instance then provides
-          a set of methods for actually speaking.  Each of the methods
-          accepts an <literal>ACSS</literal> instance, which represents
-          an aural cascading style sheet (<citation><xref linkend="acss"
-          endterm="acss.abbrev"/></citation>) that defines the voice
-          and voice parameter settings to use.</para>
+        <literal>SpeechServer</literal>s, where each
+        <literal>SpeechServer</literal> is typically an interface to
+        a particular speech engine.  For example, the
+        <literal>espeechfactory</literal> will offer up a
+        <literal>SpeechServer</literal> that talks to the Fonix
+        DECtalk engine and a <literal>SpeechServer</literal> that
+        talks to the IBMTTS engine.  Likewise, the
+        <literal>gnomespeechfactory</literal> will offer up a
+        <literal>SpeechServer</literal> that uses the
+        <literal>gnome-speech</literal> interface to talk to the
+        eSpeak synthesis engine, a separate
+        <literal>SpeechServer</literal> that also uses the
+        <literal>gnome-speech</literal> interface to talk to the Fonix
+        DECtalk engine, and so on.</para>
+
+        <para>Each <literal>SpeechServer</literal> instance provides a
+        set of methods for actually speaking. Many of the methods
+        accepts an <literal>ACSS</literal> instance, which represents
+        an aural cascading style sheet (<citation><xref linkend="acss"
+        endterm="acss.abbrev"/></citation>) that defines the voice and
+        voice parameter settings to use.</para>
 
         <para>As part of the <literal>orca-setup</literal> process,
-          the user selects a particular speech factory,
-          <literal>SpeechServer</literal>, and voice to use as their
-          default voice.  When Orca starts, the
-          <literal>speech</literal> module looks for these settings
-          and connects to the appropriate speech factory and
-          <literal>SpeechServer</literal>.  In the event the a
-          connection cannot be made, the <literal>speech</literal>
-          module attempts to find a working synthesis engine to use by
-          examining its list of speech factories.  The
-          <literal>speech</literal> module then provides simple
-          methods that delegate to the <literal>SpeechServer</literal>
-          instance.  This model allows scripts to use their own
-          <literal>SpeechServer</literal> instances if they wish, but
-          scripts typically just rely upon the user's default
-          preferences.</para>
+        the user selects a particular speech factory,
+        <literal>SpeechServer</literal>, and voice to use as their
+        default voice.  When Orca starts, the
+        <literal>speech</literal> module looks for these settings
+        and connects to the appropriate speech factory and
+        <literal>SpeechServer</literal>.  In the event the a
+        connection cannot be made, the <literal>speech</literal>
+        module attempts to find a working synthesis engine to use by
+        examining its list of speech factories.  The
+        <literal>speech</literal> module then provides simple methods
+        that delegate to the <literal>SpeechServer</literal> instance.
+        Although this model allows scripts to use their own
+        <literal>SpeechServer</literal> instances if they wish,
+        scripts typically just rely upon the user's default
+        preferences.</para>
+
+        <para>&note; Each Orca script has a
+        single <literal>speechgenerator.SpeechGenerator</literal>
+        instance to help generate text to be sent to
+        the <literal>speech</literal> module.  More information on
+        speech generators can be found in the
+        &scriptguidelink;.</para>
       </section>
 
       <section id="archbraille"><title>braille</title>
-        <para> The <emphasis role="bold">braille</emphasis> module
-          provides Orca's Python interface to the system's BrlTTY
-          <citation><xref linkend="brltty"
-          endterm="brltty.abbrev"/></citation> daemon.  The BrlTTY
-          daemon, in turn, provides the interface to braille devices
-          for both displaying braille and receiving input from the
-          user.</para>
+        <para> The <literal>braille</literal> module provides Orca's
+        Python interface to the system's BrlTTY
+        <citation><xref linkend="brltty"
+        endterm="brltty.abbrev"/></citation> daemon.  The BrlTTY
+        daemon, in turn, provides the interface to braille devices
+        for both displaying braille and receiving input from the
+        user.</para>
+        <para>&note; As with speech, each Orca script has a
+        single <literal>braillegenerator.BrailleGenerator</literal>
+        instance to help generate text to be sent to
+        the <literal>braille</literal> module.  More information on
+        braille generators can be found in the
+        &scriptguidelink;.</para>
         <para>&todo; flesh this section out more.</para>
       </section>
 
       <section id="archmag"><title>mag</title>
-        <para> The <emphasis role="bold">mag</emphasis> module
-          provides Orca's Python interface to the system's gnome-mag
-          <citation><xref linkend="gnome-mag"
-          endterm="gnome-mag.abbrev"/></citation> CORBA service(s).
-          The magnification component provides methods that permit
-          Orca discover screen magnification services and set their
-          desktop region of interest.</para>
+        <para> The <literal>mag</literal> module
+        provides Orca's Python interface to the system's gnome-mag
+        <citation><xref linkend="gnome-mag"
+        endterm="gnome-mag.abbrev"/></citation> CORBA service(s).  The
+        magnification component provides methods that permit Orca
+        discover screen magnification services and set their desktop
+        region of interest.  The script is responsible for
+        calling <literal>mag.magnifyAccessible</literal> with the
+        appropriate parameters to set the magnifier's region of
+        interest.</para>
         <para>&todo; flesh this section out more.</para>
       </section>
-
     </section>
-
   </chapter>
diff --git a/docs/doc-set/blurb.sgml b/docs/doc-set/blurb.sgml
index c3dba39..73c9fae 100644
--- a/docs/doc-set/blurb.sgml
+++ b/docs/doc-set/blurb.sgml
@@ -1,13 +1,21 @@
-<!-- Copyright 2005-2008, Sun Microsystems, Inc. -->
+<!-- Copyright 2005-2009, Sun Microsystems, Inc. -->
 
-<para>Orca is a flexible, extensible, and powerful assistive
-  technology that provides end-user access to applications and
-  toolkits that support the AT-SPI (e.g., the GNOME desktop).  With
-  early input from and continued engagement with its end users, Orca 
-  has been designed and implemented by the Sun Microsystems, Inc.,
-  Accessibility Program Office.</para>
+<para>Orca is a free, open source, flexible, and extensible screen
+reader that provides access to the graphical desktop via
+user-customizable combinations of speech, braille, and/or
+magnification.  Under development by the Sun Microsystems, Inc.,
+Accessibility Program Office since 2004, Orca has been created with
+early input from and continued engagement with its end users.</para>
 
-<para>&note; Orca is currently a work in progress.  As a result, this
-  and other books in the Orca Documentation Series are under
-  continuous modification and are also in various states of
-  completeness.</para>
+<para>Orca works with applications and toolkits that support the
+assistive technology service provider interface (AT-SPI), which is the
+primary assistive technology infrastructure for the Solaris and Linux
+operating environments.  Applications and toolkits supporting the
+AT-SPI include the GNOME GTK+ toolkit, the Java platform's Swing
+toolkit, OpenOffice, and Mozilla.  AT-SPI support for WebKit and the
+KDE Qt toolkit is currently being pursued.</para>
+
+<para>See also http://live.gnome.org/Orca for detailed English and
+Spanish information on Orca, including how to run Orca, how to
+communicate with the Orca user community, and where to log bugs and
+feature requests.</para>
diff --git a/docs/doc-set/diagrams.odg b/docs/doc-set/diagrams.odg
index fb158e5..6a7713d 100644
Binary files a/docs/doc-set/diagrams.odg and b/docs/doc-set/diagrams.odg differ
diff --git a/docs/doc-set/internals.html b/docs/doc-set/internals.html
index 7f308d8..a0cf8a3 100644
--- a/docs/doc-set/internals.html
+++ b/docs/doc-set/internals.html
@@ -1,264 +1,295 @@
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Orca Technical Reference</title><meta name="generator" content="DocBook XSL Stylesheets V1.69.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="id2488862"></a>Orca Technical Reference</h1></div><div><div class="legalnotice"><a name="id2489718"></a><p>Copyright 2005-2008, Sun Microsystems, Inc.</p></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="preface"><a href="#archforward">Foreword</a></span></dt><dt><span class="chapter"><a href="#prereq">1. Prerequisites</a></span></dt><dd><dl><dt><span class="section"><a href="#prereqgnome">GNOME 2.22 or better</a></span></dt><dt><span class="section"><a href="#prereqpython">Python v2.4 or better</a></span></dt><dt><span class="section"><a href="#prereqbrltty">BrlTTY v3.7
 .2 or better</a></span></dt><dt><span class="section"><a href="#prereqkeyboardnav">Keyboard Navigation</a></span></dt></dl></dd><dt><span class="chapter"><a href="#architecture">2. Architecture</a></span></dt><dd><dl><dt><span class="section"><a href="#archdesktop">Desktop and AT-SPI</a></span></dt><dt><span class="section"><a href="#archorca">Orca Module</a></span></dt><dd><dl><dt><span class="section"><a href="#archsettings">settings</a></span></dt></dl></dd><dt><span class="section"><a href="#script">Orca Scripts</a></span></dt><dt><span class="section"><a href="#archsystemservices">System Services</a></span></dt><dd><dl><dt><span class="section"><a href="#archspeech">speech</a></span></dt><dt><span class="section"><a href="#archbraille">braille</a></span></dt><dt><span class="section"><a href="#archmag">mag</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#scriptguide">3. Introduction to Scripting</a></span></dt><dd><dl><dt><span class="section"><a h
 ref="#sgcontract">Script Contract</a></span></dt><dt><span class="section"><a href="#sglifecycle">Script Life Cycle</a></span></dt></dl></dd><dt><span class="chapter"><a href="#customization">4. Customized Behavior</a></span></dt><dd><dl><dt><span class="section"><a href="#sgeventlisteners">Defining Event Listeners</a></span></dt><dt><span class="section"><a href="#sginputeventhandlers">Input Event Handlers</a></span></dt><dt><span class="section"><a href="#sgkeybindings">Defining Keyboard Bindings</a></span></dt><dt><span class="section"><a href="#sgbraillebindings">Defining Braille Bindings</a></span></dt></dl></dd><dt><span class="chapter"><a href="#sgutilities">5. Script Utilities</a></span></dt><dd><dl><dt><span class="section"><a href="#debug">Debug Utilities</a></span></dt><dt><span class="section"><a href="#sgtts">Speech Synthesis</a></span></dt><dd><dl><dt><span class="section"><a href="#sgspeechpy"><code class="literal">speech.py</code></a></span></dt><dt><span cla
 ss="section"><a href="#sgsgpy"><code class="literal">speechgenerator.py</code></a></span></dt></dl></dd><dt><span class="section"><a href="#sgbrailleoutput">Braille Output</a></span></dt><dd><dl><dt><span class="section"><a href="#sgbraillepy"><code class="literal">braille.py</code></a></span></dt><dt><span class="section"><a href="#sgbgpy"><code class="literal">braillegenerator.py</code></a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#i18n">6. Internationalization (I18N) Support</a></span></dt><dt><span class="bibliography"><a href="#archbibliography">Bibliography</a></span></dt></dl></div><div class="list-of-figures"><p><b>List of Figures</b></p><dl><dt>2.1. <a href="#id2489635">High Level Orca Architecture. The main components of Orca
-        are as follows: desktop  applications that support the AT-SPI,
-        the  AT-SPI  registry and  infrastructure,  Orca itself,  Orca
-        Scripts, and  system services.  The  key communication between
-        the components is depicted.</a></dt><dt>4.1. <a href="#id2493464">Orca Script Diagram</a></dt></dl></div><div class="preface" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="archforward"></a>Foreword</h2></div></div></div><p>Orca is a flexible, extensible, and powerful assistive
-  technology that provides end-user access to applications and
-  toolkits that support the AT-SPI (e.g., the GNOME desktop).  With
-  early input from and continued engagement with its end users, Orca 
-  has been designed and implemented by the Sun Microsystems, Inc.,
-  Accessibility Program Office.</p><p><span class="emphasis"><em>NOTE:</em></span> Orca is currently a work in progress.  As a result, this
-  and other books in the Orca Documentation Series are under
-  continuous modification and are also in various states of
-  completeness.</p><p>This book covers the overall architecture of Orca, including
-      a portion on writing custom scripts. The bulk of the user
-      information and user experience design can be found on the Orca
-      WIKI at http://live.gnome.org/Orca.</p></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="prereq"></a>Chapter 1. Prerequisites</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#prereqgnome">GNOME 2.22 or better</a></span></dt><dt><span class="section"><a href="#prereqpython">Python v2.4 or better</a></span></dt><dt><span class="section"><a href="#prereqbrltty">BrlTTY v3.7.2 or better</a></span></dt><dt><span class="section"><a href="#prereqkeyboardnav">Keyboard Navigation</a></span></dt></dl></div><p>To help narrow the scope of the Orca development activity,
-      Orca uses existing software where available.  For example, as
-      mentioned in the requirements, Orca is a screen reader that
-      needs to be able to interact with speech synthesis, braille,
-      and screen magnification services, but it need not be the
-      provider of such services.  Given this, Orca has the following
-      dependencies:</p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="prereqgnome"></a>GNOME 2.22 or better</h2></div></div></div><p>The GNOME 2.22 desktop contains a number of bug fixes and
-        enhancements to the accessibility infrastructure.  These are
-        needed for Orca to run properly.  GNOME 2.22 also packages a
-        variety of other dependencies of Orca, including gnome-speech,
-        gnome-mag, pyatspi, etc.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="prereqpython"></a>Python v2.4 or better</h2></div></div></div><p>Orca is written in the Python programming language and
-        depends upon features found in Python versions 2.4 and
-        greater.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="prereqbrltty"></a>BrlTTY v3.7.2 or better</h2></div></div></div><p>BrlTTY [<span class="citation"><a href="#brltty">BRLTTY</a></span>] provides access to a
-        variety of Braille displays, and consists of a library and a
-        daemon to provide programmatic interaction with the
-        display.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="prereqkeyboardnav"></a>Keyboard Navigation</h2></div></div></div><p>As much as possible, Orca relies upon the keyboard
-        navigation methods built in to the native platform.  For
-        example, it is expected that the native platform will provide
-        access via traditional methods such as the "tab" key, keyboard
-        mnemonics, and keyboard accelerators.</p></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="architecture"></a>Chapter 2. Architecture</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#archdesktop">Desktop and AT-SPI</a></span></dt><dt><span class="section"><a href="#archorca">Orca Module</a></span></dt><dd><dl><dt><span class="section"><a href="#archsettings">settings</a></span></dt></dl></dd><dt><span class="section"><a href="#script">Orca Scripts</a></span></dt><dt><span class="section"><a href="#archsystemservices">System Services</a></span></dt><dd><dl><dt><span class="section"><a href="#archspeech">speech</a></span></dt><dt><span class="section"><a href="#archbraille">braille</a></span></dt><dt><span class="section"><a href="#archmag">mag</a></span></dt></dl></dd></dl></div><p>The Orca architecture has been driven primarily by the Orca
-      User Experience Design.  There are two primary operating modes
-      of Orca: a focus tracking mode and a flat review mode.</p><p>The focus tracking mode generally relies upon applications
-      to provide reasonable keyboard navigation techniques to allow
-      the user to operate the application without requiring the mouse.
-      As the user uses traditional keyboard navigation techniques to
-      move from component to component in the application (e.g.,
-      pressing the Tab key to move from pushbutton to text area to
-      toggle button, etc.), Orca will present this to the user via
-      braille, speech, magnification, or a combination thereof.  In
-      the cases where more complex navigation is needed, such as
-      structural navigation of complex text documents, Orca also
-      provides a facility to define keyboard and braille input events
-      that it can intercept and handle appropriately.</p><p>The flat review mode provides the user with the ability to
-      spatially navigate a window, giving them the ability to explore
-      as well as discover and interact with components in the window.
-      Orca provides a default set of keybindings for flat review, and
-      these keybindings can be easily redefined by the user.</p><p>The various modes of Orca are handled by "scripts," which
-      are Python modules that can provide a custom interpretation of
-      an application's interaction model.  It is not intended that 
-      there will be a unique script for every application.  Instead,
-      it is expected that there will be a general purpose script that
-      covers a large number of applications.  In the event that more
-      compelling or custom behavior is desired for an application,
-      however, one can use a custom script for the application.
-      Furthermore, scripts can subclass other scripts, allowing
-      them to be quite simple.</p><p>As illustrated in the high level Orca architecture diagram,
-      the main components of Orca are as follows: desktop applications
-      that support the AT-SPI, the AT-SPI registry and infrastructure,
-      Orca itself, Orca Scripts, and system services (e.g., speech,
-      braille, magnification).</p><div class="figure"><a name="id2489635"></a><p class="title"><b>Figure 2.1. High Level Orca Architecture. The main components of Orca
-        are as follows: desktop  applications that support the AT-SPI,
-        the  AT-SPI  registry and  infrastructure,  Orca itself,  Orca
-        Scripts, and  system services.  The  key communication between
-        the components is depicted.</b></p><div class="mediaobject"><img src="architecture.jpg" alt="High Level Orca Architecture"></div></div><p>The following sections describe the architecture in more
-      detail.</p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="archdesktop"></a>Desktop and AT-SPI</h2></div></div></div><p>Orca's sole view of any application on the desktop is via
-        the AT-SPI [<span class="citation"><a href="#at-spi">AT-SPI</a></span>].  The AT-SPI is an
-        IDL/CORBA/Bonobo-based technology [<span class="citation"><a href="#bonobo">Bonobo</a></span>] that provides a common
-        interface for the desktop and its applications to expose their
-        GUI component hierarchy to assistive technologies such as
-        Orca.  AT-SPI support is provided by toolkits such as GNOME's
-        GTK+ toolkit (via gail [<span class="citation"><a href="#gail">GAIL</a></span>]), the Java platform (via
-        the Java access bridge), and the custom
-        toolkits used by applications such as Mozilla and Open
-        Office.  Future support includes the Qt toolkit of KDE.</p><p>Assistive Technologies interact with the AT-SPI via two
-        primary means: the AT-SPI registry and accessible objects.
-        The AT-SPI registry permits assistive technologies to discover
-        existing applications on the desktop and to register for event
-        notification for AT-SPI events (e.g., window creation, focus
-        changes, object state changes, etc.) and device events (e.g.,
-        keyboard input events).  Accessible objects provide the
-        assistive technology with information about the application,
-        and tend to mirror the actual GUI component hierarchy.
-        Accessible objects can be obtained in three ways: </p><div class="orderedlist"><ol type="1"><li><p>From the AT-SPI registry via queries on the desktop</p></li><li><p>From an AT-SPI event</p></li><li><p>From another Accessible via parent/child relationships
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Orca Technical Reference</title><meta name="generator" content="DocBook XSL Stylesheets V1.69.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="id2488862"></a>Orca Technical Reference</h1></div><div><div class="legalnotice"><a name="id2489718"></a><p>Copyright 2005-2009, Sun Microsystems, Inc.</p></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="preface"><a href="#archforward">Foreword</a></span></dt><dt><span class="chapter"><a href="#prereq">1. Prerequisites</a></span></dt><dd><dl><dt><span class="section"><a href="#prereqgnome">GNOME</a></span></dt><dt><span class="section"><a href="#prereqpython">Python v2.4 or better</a></span></dt><dt><span class="section"><a href="#prereqbrltty">BrlTTY v3.7.2 or better</a
 ></span></dt><dt><span class="section"><a href="#prereqkeyboardnav">Keyboard Navigation</a></span></dt></dl></dd><dt><span class="chapter"><a href="#architecture">2. Architecture</a></span></dt><dd><dl><dt><span class="section"><a href="#archdesktop">Desktop and AT-SPI</a></span></dt><dt><span class="section"><a href="#archorca">Orca Module</a></span></dt><dd><dl><dt><span class="section"><a href="#archsettings">settings</a></span></dt></dl></dd><dt><span class="section"><a href="#script">Orca Scripts</a></span></dt><dt><span class="section"><a href="#archsystemservices">System Services</a></span></dt><dd><dl><dt><span class="section"><a href="#archspeech">speech</a></span></dt><dt><span class="section"><a href="#archbraille">braille</a></span></dt><dt><span class="section"><a href="#archmag">mag</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#scriptguide">3. Introduction to Scripting</a></span></dt><dd><dl><dt><span class="section"><a href="#sgcontrac
 t">Script Contract</a></span></dt><dt><span class="section"><a href="#sglifecycle">Script Life Cycle</a></span></dt></dl></dd><dt><span class="chapter"><a href="#customization">4. Customized Behavior</a></span></dt><dd><dl><dt><span class="section"><a href="#sgeventlisteners">Defining Event Listeners</a></span></dt><dt><span class="section"><a href="#sginputeventhandlers">Input Event Handlers</a></span></dt><dt><span class="section"><a href="#sgkeybindings">Defining Keyboard Bindings</a></span></dt><dt><span class="section"><a href="#sgbraillebindings">Defining Braille Bindings</a></span></dt></dl></dd><dt><span class="chapter"><a href="#sgutilities">5. Script Utilities</a></span></dt><dd><dl><dt><span class="section"><a href="#debug">Debug Utilities</a></span></dt><dt><span class="section"><a href="#sgtts">Speech Synthesis</a></span></dt><dd><dl><dt><span class="section"><a href="#sgspeechpy"><code class="literal">speech.py</code></a></span></dt><dt><span class="section"><a
  href="#sgsgpy"><code class="literal">speechgenerator.py</code></a></span></dt></dl></dd><dt><span class="section"><a href="#sgbrailleoutput">Braille Output</a></span></dt><dd><dl><dt><span class="section"><a href="#sgbraillepy"><code class="literal">braille.py</code></a></span></dt><dt><span class="section"><a href="#sgbgpy"><code class="literal">braillegenerator.py</code></a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#i18n">6. Internationalization (I18N) Support</a></span></dt><dt><span class="bibliography"><a href="#archbibliography">Bibliography</a></span></dt></dl></div><div class="list-of-figures"><p><b>List of Figures</b></p><dl><dt>2.1. <a href="#id2489678">High Level Orca Architecture. The main components of Orca
+      are as follows: desktop applications that support the AT-SPI,
+      the AT-SPI registry and infrastructure, Orca itself, Orca
+      Scripts, and system services.  The key communication between the
+      components is depicted.</a></dt><dt>4.1. <a href="#id2493370">Orca Script Diagram</a></dt></dl></div><div class="preface" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="archforward"></a>Foreword</h2></div></div></div><p>Orca is a free, open source, flexible, and extensible screen
+reader that provides access to the graphical desktop via
+user-customizable combinations of speech, braille, and/or
+magnification.  Under development by the Sun Microsystems, Inc.,
+Accessibility Program Office since 2004, Orca has been created with
+early input from and continued engagement with its end users.</p><p>Orca works with applications and toolkits that support the
+assistive technology service provider interface (AT-SPI), which is the
+primary assistive technology infrastructure for the Solaris and Linux
+operating environments.  Applications and toolkits supporting the
+AT-SPI include the GNOME GTK+ toolkit, the Java platform's Swing
+toolkit, OpenOffice, and Mozilla.  AT-SPI support for WebKit and the
+KDE Qt toolkit is currently being pursued.</p><p>See also http://live.gnome.org/Orca for detailed English and
+Spanish information on Orca, including how to run Orca, how to
+communicate with the Orca user community, and where to log bugs and
+feature requests.</p><p>This book covers the overall architecture of Orca, including
+    a portion on writing custom scripts. The bulk of the end user
+    information and user experience design can be found on the 
+    <a href="http://live.gnome.org/Orca"; target="_top">Orca WIKI</a>.</p></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="prereq"></a>Chapter 1. Prerequisites</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#prereqgnome">GNOME</a></span></dt><dt><span class="section"><a href="#prereqpython">Python v2.4 or better</a></span></dt><dt><span class="section"><a href="#prereqbrltty">BrlTTY v3.7.2 or better</a></span></dt><dt><span class="section"><a href="#prereqkeyboardnav">Keyboard Navigation</a></span></dt></dl></div><p>Orca is a screen reader that needs to be able to interact
+    with speech synthesis, braille, and screen magnification services,
+    but it need not be the provider of such services. To help narrow
+    the scope of the Orca development activity, Orca uses existing
+    software where available.  As such, Orca has the following
+    dependencies.</p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="prereqgnome"></a>GNOME</h2></div></div></div><p>Orca is part of the GNOME project and ships with each
+      release of GNOME.  Because Orca uses a number of GNOME
+      components, such as AT-SPI, ATK, GAIL, gnome-speech, gnome-mag,
+      and GTK+, Orca is only supported on the release of GNOME with
+      which it was released.  For example, Orca v2.22.0 was released
+      with GNOME 2.22.0 and is only supported on GNOME 2.22.0.  To
+      determine the version of Orca you are using, run the following
+      command:
+</p><pre class="programlisting">
+orca --version
+</pre><p>
+      To determine the version of GNOME you are using, run the
+      following command:
+</p><pre class="programlisting">
+gnome-about --version
+</pre><p>
+      </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="prereqpython"></a>Python v2.4 or better</h2></div></div></div><p>Orca is written in the Python programming language and
+      depends upon features found in Python versions 2.4 and
+      greater. To determine the version of Python you are using, run
+      the following command:
+</p><pre class="programlisting">
+python -V
+</pre><p>
+      </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="prereqbrltty"></a>BrlTTY v3.7.2 or better</h2></div></div></div><p>BrlTTY [<span class="citation"><a href="#brltty">BRLTTY</a></span>] provides access to a
+      variety of Braille displays, and consists of a library and a
+      daemon to provide programmatic interaction with the
+      display.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="prereqkeyboardnav"></a>Keyboard Navigation</h2></div></div></div><p>As much as possible, Orca relies upon the keyboard
+      navigation methods built in to the native platform.  For
+      example, it is expected that the native platform will provide
+      access via traditional methods such as the "tab" key, keyboard
+      mnemonics, and keyboard accelerators.</p></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="architecture"></a>Chapter 2. Architecture</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#archdesktop">Desktop and AT-SPI</a></span></dt><dt><span class="section"><a href="#archorca">Orca Module</a></span></dt><dd><dl><dt><span class="section"><a href="#archsettings">settings</a></span></dt></dl></dd><dt><span class="section"><a href="#script">Orca Scripts</a></span></dt><dt><span class="section"><a href="#archsystemservices">System Services</a></span></dt><dd><dl><dt><span class="section"><a href="#archspeech">speech</a></span></dt><dt><span class="section"><a href="#archbraille">braille</a></span></dt><dt><span class="section"><a href="#archmag">mag</a></span></dt></dl></dd></dl></div><p>The Orca architecture has been driven primarily by the Orca
+    User Experience Design.  There are two primary operating modes
+    of Orca: a focus tracking mode and a flat review mode.</p><p>The focus tracking mode is the preferred mode of operation.
+    It generally relies upon applications to provide reasonable
+    keyboard navigation techniques to allow the user to operate the
+    application without requiring the mouse.  As the user uses
+    traditional keyboard navigation techniques to move from component
+    to component in the application (e.g., pressing the Tab key to
+    move from pushbutton to text area to toggle button, etc.), Orca
+    will present this to the user via braille, speech, magnification,
+    or a combination thereof.  In the cases where more complex
+    navigation is needed, such as structural navigation of complex
+    text documents, Orca also provides a facility to define keyboard
+    and braille input events that it can intercept and handle
+    appropriately.</p><p>The flat review mode provides the user with the ability to
+    spatially navigate a window, giving them the ability to explore as
+    well as discover and interact with components in the window. This
+    mode is not a preferred mode, but is instead intended to allow a
+    user to interact with ill-behaved applications.  Orca provides a
+    default set of keybindings for flat review, and these keybindings
+    can be easily redefined by the user.</p><p>The focus tracking mode of Orca is handled by "scripts,"
+    which are Python modules that can provide a custom interpretation
+    of an application's interaction model.  It is not intended that
+    there will be a unique script for every application.  Instead, it
+    is expected that there will be a general purpose "default" script
+    that covers a large number of applications.  In the event that
+    more compelling or custom behavior is desired for an application,
+    however, one can use a custom script for the application.
+    Furthermore, scripts can subclass other scripts, allowing them to
+    be quite simple. In practice, all the custom scripts extend the
+    "default" script.</p><p>As illustrated in the high level Orca architecture diagram,
+    the main components of Orca are as follows: desktop applications
+    that support the AT-SPI, the AT-SPI registry and infrastructure,
+    Orca itself, Orca Scripts, and system services (e.g., speech,
+    braille, magnification).</p><div class="figure"><a name="id2489678"></a><p class="title"><b>Figure 2.1. High Level Orca Architecture. The main components of Orca
+      are as follows: desktop applications that support the AT-SPI,
+      the AT-SPI registry and infrastructure, Orca itself, Orca
+      Scripts, and system services.  The key communication between the
+      components is depicted.</b></p><div class="mediaobject"><img src="architecture.png" alt="High Level Orca Architecture"></div></div><p>The following sections describe the architecture in more
+    detail.</p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="archdesktop"></a>Desktop and AT-SPI</h2></div></div></div><p>Orca's sole view of any application on the desktop is via
+      the AT-SPI [<span class="citation"><a href="#at-spi">AT-SPI</a></span>].  The AT-SPI is an
+      IDL/CORBA/Bonobo-based
+      technology [<span class="citation"><a href="#bonobo">Bonobo</a></span>] that provides a common
+      interface for the desktop and its applications to expose their
+      GUI component hierarchy to assistive technologies such as Orca.
+      <span class="emphasis"><em>NOTE:</em></span> the AT-SPI infrastructure is being migrated to D-Bus for
+      GNOME 3.0.  This migration should have little impact on the
+      architecture or code of Orca.  In other words, do you worry
+      'bout a thing.</p><p>AT-SPI support is provided by toolkits such as GNOME's
+      GTK+ toolkit (via GAIL [<span class="citation"><a href="#gail">GAIL</a></span>]), the Java platform (via the
+      Java access bridge), and the custom toolkits used by
+      applications such as Mozilla and Open Office.  Future support
+      includes the Qt toolkit of KDE.</p><p>Assistive Technologies interact with the AT-SPI via two
+      primary means: the AT-SPI registry and accessible objects.  The
+      AT-SPI registry permits assistive technologies to discover
+      existing applications on the desktop and to register for event
+      notification for AT-SPI events (e.g., window creation, focus
+      changes, object state changes, etc.) and device events (e.g.,
+      keyboard input events).  Accessible objects provide the
+      assistive technology with information about the application, and
+      tend to mirror the actual GUI component hierarchy.  Accessible
+      objects can be obtained in three ways: </p><div class="orderedlist"><ol type="1"><li><p>From the AT-SPI registry via queries on the desktop</p></li><li><p>From an AT-SPI event</p></li><li><p>From another Accessible via parent/child relationships
             and other relationships such as "label for" and 
-	    "labeled by".</p></li></ol></div><p>Orca's interaction with the AT-SPI is managed through
-        Orca's <code class="literal">atspi.py</code> module.  The
-        <code class="literal">atspi.py</code> module communicates directly with
-        the AT-SPI via the AT-SPI IDL interfaces and also provides a
-        number of classes that help with AT-SPI interaction:
-        <code class="literal">Registry</code>, <code class="literal">Accessible</code>,
-        and <code class="literal">Event</code>.  The full documentation for
-        each of these classes is available in the pydoc for Orca
-	while the following paragraphs provide a brief overview.</p><p>The <code class="literal">Registry</code> class provides a singleton
-        class instance to access to the AT-SPI
-        registry.  It provides convenience methods for registering
-        AT-SPI event listeners and device event listeners, and also
-        provides the mechanism for starting and stopping event
-        delivery from the AT-SPI registry.</p><p>The <code class="literal">Accessible</code> class provides a wrapper
-        for communicating with CORBA objects that implement the AT-SPI
-        Accessible and Application interfaces. Using Python's ability
-        to add new properties to a class instance at run time, Orca
-        can also annotate Accessible class instances with additional
-        information.  The main purpose of an Accessible is to provide
-        a local cache for accessible objects, preventing the need for
-        numerous round trip calls to the AT-SPI registry and
-        application for information.</p><p>The <code class="literal">Event</code> class provides a wrapper for
-        converting AT-SPI events into Python <code class="literal">Event</code>
-        instances.  The main purpose is to convert the AT-SPI
-        accessible source of the event into a Python
-        <code class="literal">Accessible</code> instance and to also provide an
-        <code class="literal">Event</code> instance that can be annotated by
-        scripts (the actual AT-SPI event delivered by the registry is 
-	read-only).</p><p>As illustrated in the high level Orca architecture
-        diagram, the <code class="literal">atspi</code> module has been used to
-        register event and device listeners with the AT-SPI registry.
-        Each exemplary desktop application (Firefox, NetBeans, GAIM,
-        StarOffice) emits AT-SPI events to the AT-SPI registry which
-        then delivers them to the <code class="literal">atspi</code> module.
-        The <code class="literal">atspi</code> module then calls all appropriate
-        listeners for the events it receives from the AT-SPI
-        registry.</p><p>In this case, the <code class="literal">orca</code> module receives
-        keyboard events, which it interprets and also sends on to the
-        <code class="literal">focus_tracking_presenter</code> module.  Of more
-        interest, however, is that the
-        <code class="literal">focus_tracking_presenter</code> module receives
-        AT-SPI events which it then passes on the script for the
-        application associated with the event.  If there is no script,
-        the <code class="literal">focus_tracking_presenter</code> will create an
-        instance of the default script.  See the <a href="#scriptguide" title="Chapter 3. Introduction to Scripting">Orca Script Writing Guide</a> for
-        more information.</p><p>The <code class="literal">atspi</code> module also registers its
-        own set of event listeners that it uses to keep its local
-        cache of accessible objects up to date.</p><p><span class="emphasis"><em>IMPLEMENTATION DETAIL:</em></span> Because processing AT-SPI object events can be
-        time consuming, and because the notification of AT-SPI object
-        events is relatively "bursty," the
-        <code class="literal">focus_tracking_presenter</code> maintains a queue
-        of AT-SPI object and input device events. It adds the events
-        to this queue when it receives them and processes the events
-        on the GLib idle handling thread.  This permits Orca to
-        survive a relatively long burst of events and also allows it
-        to handle the events on a thread that is compatible with
-        GLib.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="archorca"></a>Orca Module</h2></div></div></div><p>The <code class="literal">orca</code> module is the "main entry
-        point" of Orca.  It initializes the components that Orca uses
-        (atspi, speech, braille, mag) and loads the user's settings.
-        It also is the first to receive all keyboard and braille input
-        events and delves them out to other Orca components
-        appropriately.</p><p>The <code class="literal">orca</code> module maintains the current
-        known "locus of focus" in the <code class="literal">locusOfFocus</code>
-        field of the <code class="literal">orca_state</code> module.  The
-        <code class="literal">locusOfFocus</code> is intended to represent the
-        current object that the user is working with.  In simple
-        terms, it is the object that is highlighted or has the dotted
-        line drawn around it.  Be advised that the notion of "focus"
-        differs from toolkit to toolkit.  For example, the object with
-        toolkit focus may actually be the parent of the object that is
-        highlighted.  The <code class="literal">locusOfFocus</code> is an an
-        attempt to neutralize these differences across toolkits: the
-        locus of focus is the individual object that is highlighted,
-        has the caret, etc.</p><p>Orca scripts set the locus of focus to inform Orca when
-        the locus of focus has changed.  In addition, in the event
-        that there was a visual appearance change to the object that
-        has the locus of focus, the <code class="literal">orca</code> module
-        provides a <code class="literal">visualAppearanceChanged</code> that
-        scripts can use to inform Orca of this event.</p><p><span class="emphasis"><em>NOTE:</em></span> The <code class="literal">orca_state.locusOfFocus</code>
-        field is intended to be set only via the
-        <code class="literal">setLocusOfFocus</code> method of the
-        <code class="literal">orca</code> module. Because the
-        <code class="literal">setLocusOfFocus</code> method performs bookkeeping
-        and other tasks, the
-        <code class="literal">orca_state.locusOfFocus</code> field should never
-        be set directly.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="archsettings"></a>settings</h3></div></div></div><p>The <span class="bold"><strong>settings</strong></span> module
-          (not depicted in the high level Orca architecture diagram)
-          holds preferences set by the user during configuration.
-          These settings include the following: use of speech and/or
-          braille, voice styles, key echo, text echo, and command
-          echo.</p><p>Any Orca module can check the value of a setting by
-          examining the field directly in the
-          <code class="literal">settings</code> module.  In addition, the
-          <code class="literal">orca</code> module will import the
-          <code class="literal">user-settings</code> module from the
-          <code class="literal">~/.orca directory</code>, if it exists (it
-	  is created as part of the configuration process that
-	  is run the first time Orca is used or when the user
-	  presses Insert+Space to invoke the configuration GUI).</p><p>The <code class="literal">user-settings</code> module is a Python
-          script, allowing it to contain functions, class definitions,
-          etc.  The primary job of the
-          <code class="literal">user-settings</code> is to directly set the
-          values of fields in the <code class="literal">settings</code>
-          module.</p><p><span class="emphasis"><em>IMPLEMENTATION DETAIL:</em></span> the <code class="literal">init</code> method of the
-          <code class="literal">orca</code> module obtains settings.  As a
-          result, the <code class="literal">user-settings</code> module is
-          imported very early in the Orca life cycle.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="script"></a>Orca Scripts</h2></div></div></div><p>Internally, the <code class="literal">orca</code> module keeps track
-        of list of <code class="literal">PresentationManager</code> instances
-        (see the pydoc for
-        <code class="literal">presentation_manager.py</code>). The
-        <code class="literal">FocusTrackingPresenter</code> (see
-        <code class="literal">focus_tracking_presenter</code>) is of the most
-        interest, as it is the <code class="literal">PresentationManager</code>
-        that manages scripts.</p><p>Details on the <code class="literal">FocusTrackingPresenter</code>
-        and Orca scripts can be found in the
-        <a href="#scriptguide" title="Chapter 3. Introduction to Scripting">Orca Script Writing Guide</a>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="archsystemservices"></a>System Services</h2></div></div></div><p> Orca relies on existing system services to provide
-        support for speech synthesis, braille, and screen
-        magnification.  To interact with these services, Orca provides
-        the modules described in the following sections.
-      </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="archspeech"></a>speech</h3></div></div></div><p>The <span class="bold"><strong>speech</strong></span> module
-          provides Orca's Python interface to system speech services.
-          Each speech service is generated by a "speech server
-          factory."  There are currently two such factories: one for
-          [<span class="citation"><a href="#gnome-speech">gnome-speech</a></span>] (see
-          <code class="literal">gnomespeechfactory.py</code> and one for
-          [<span class="citation"><a href="#emacspeak">Emacspeak</a></span>] (see
-          <code class="literal">espeechfactory.py</code>), though it is expected
-          that support for other factories can be added in the
-          future.</p><p>Each speech factory offers up a list of
-          <code class="literal">SpeechServer</code>s, where each
-          <code class="literal">SpeechServer</code> is typically an interface to
-          a particular speech engine.  For example, the
-          <code class="literal">espeechfactory</code> will offer up a
-          <code class="literal">SpeechServer</code> that talks to the Fonix
-          DECtalk engine and a <code class="literal">SpeechServer</code> that
-          talks to the IBMTTS engine.  Likewise, the
-          <code class="literal">gnomespeechfactory</code> will offer up a
-          <code class="literal">SpeechServer</code> that uses the
-          <code class="literal">gnome-speech</code> interface to talk to the
-          Festival Speech Synthesis System, a separate
-          <code class="literal">SpeechServer</code> that also uses the
-          <code class="literal">gnome-speech</code> interface to talk to the
-          Fonix DECtalk engine, and so on.</p><p>Each <code class="literal">SpeechServer</code> instance then provides
-          a set of methods for actually speaking.  Each of the methods
-          accepts an <code class="literal">ACSS</code> instance, which represents
-          an aural cascading style sheet ([<span class="citation"><a href="#acss">ACSS</a></span>]) that defines the voice
-          and voice parameter settings to use.</p><p>As part of the <code class="literal">orca-setup</code> process,
-          the user selects a particular speech factory,
-          <code class="literal">SpeechServer</code>, and voice to use as their
-          default voice.  When Orca starts, the
-          <code class="literal">speech</code> module looks for these settings
-          and connects to the appropriate speech factory and
-          <code class="literal">SpeechServer</code>.  In the event the a
-          connection cannot be made, the <code class="literal">speech</code>
-          module attempts to find a working synthesis engine to use by
-          examining its list of speech factories.  The
-          <code class="literal">speech</code> module then provides simple
-          methods that delegate to the <code class="literal">SpeechServer</code>
-          instance.  This model allows scripts to use their own
-          <code class="literal">SpeechServer</code> instances if they wish, but
-          scripts typically just rely upon the user's default
-          preferences.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="archbraille"></a>braille</h3></div></div></div><p> The <span class="bold"><strong>braille</strong></span> module
-          provides Orca's Python interface to the system's BrlTTY
-          [<span class="citation"><a href="#brltty">BRLTTY</a></span>] daemon.  The BrlTTY
-          daemon, in turn, provides the interface to braille devices
-          for both displaying braille and receiving input from the
-          user.</p><p><span class="emphasis"><em>TODO:</em></span> flesh this section out more.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="archmag"></a>mag</h3></div></div></div><p> The <span class="bold"><strong>mag</strong></span> module
-          provides Orca's Python interface to the system's gnome-mag
-          [<span class="citation"><a href="#gnome-mag">gnome-mag</a></span>] CORBA service(s).
-          The magnification component provides methods that permit
-          Orca discover screen magnification services and set their
-          desktop region of interest.</p><p><span class="emphasis"><em>TODO:</em></span> flesh this section out more.</p></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="scriptguide"></a>Chapter 3. Introduction to Scripting</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#sgcontract">Script Contract</a></span></dt><dt><span class="section"><a href="#sglifecycle">Script Life Cycle</a></span></dt></dl></div><p>In this section, you will learn more about the Orca
+	    "labeled by".</p></li></ol></div><p>Orca's interaction with the AT-SPI is managed through the
+      <code class="literal">pyatspi.py</code> module that is part of AT-SPI.  The
+      <code class="literal">pyatspi.py</code> module communicates directly with
+      the AT-SPI number of classes that help with AT-SPI interaction.
+      The best ways to learn AT-SPI are as follows:
+
+      </p><div class="orderedlist"><ol type="1"><li><p>Read the AT-SPI interface documentation.</p></li><li><p>Run the <code class="literal">accerciser</code> application to
+          examine the accessibility information of desktop
+          applications.  This includes analyzing the accessible
+          hierarchy as well as watching events that are issued as
+          you interact with desktop applcations.</p></li><li><p>Enable the debug mode of Orca as described on the
+          <a href="http://live.gnome.org/Orca/Debugging"; target="_top">Orca
+          WIKI</a>.  Run Orca and interact with an
+          application. Then, quit Orca and analyze the debug
+          log.</p></li></ol></div><p>
+      </p><p>As illustrated in the high level Orca architecture
+      diagram, the <code class="literal">pyatspi</code> module has been used to
+      register event and device listeners with the AT-SPI registry.
+      Each exemplary desktop application (Firefox, Evolution, Pidgin,
+      and OpenOffice) emits AT-SPI events to the AT-SPI registry which
+      then delivers them to the <code class="literal">pyatspi</code> module.
+      The <code class="literal">pyatspi</code> module then calls all appropriate
+      listeners for the events it receives from the AT-SPI
+      registry.</p><p>In this case, the <code class="literal">orca</code> module receives
+      keyboard events, which it interprets and also sends on to the
+      <code class="literal">focus_tracking_presenter</code> module (not depicted
+      in the illustration).  Of more
+      interest, however, is that the
+      <code class="literal">focus_tracking_presenter</code> module receives
+      AT-SPI events which it then passes on the script for the
+      application associated with the event.  If there is no script,
+      the <code class="literal">focus_tracking_presenter</code> will create an
+      instance of the default script.  See the <a href="#scriptguide" title="Chapter 3. Introduction to Scripting">Orca Script Writing Guide</a> for
+      more information.</p><p><span class="emphasis"><em>IMPLEMENTATION DETAIL:</em></span> Because processing AT-SPI object events can be
+      time consuming, and because the notification of AT-SPI object
+      events is relatively "bursty," the
+      <code class="literal">focus_tracking_presenter</code> maintains a queue of
+      AT-SPI object and input device events. It adds the events to
+      this queue when it receives them and processes the events on the
+      GLib idle handling thread.  This permits Orca to survive a
+      relatively long burst of events and also allows it to handle the
+      events on a thread that is compatible with GLib.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="archorca"></a>Orca Module</h2></div></div></div><p>The <code class="literal">orca</code> module is the "main entry
+      point" of Orca.  It initializes the components that Orca uses
+      (pyatspi, speech, braille, mag) and loads the user's settings.
+      It also is the first to receive all keyboard and braille input
+      events and delves them out to other Orca components
+      appropriately.</p><p>The <code class="literal">orca</code> module maintains the current
+      known "locus of focus" in the <code class="literal">locusOfFocus</code>
+      field of the <code class="literal">orca_state</code> module.  The
+      <code class="literal">orca_state.locusOfFocus</code> field is intended to
+      represent the current object that the user is working with.  In
+      simple terms, it is the object that is highlighted or has the
+      dotted line drawn around it.  Be advised that the notion of
+      "focus" differs from toolkit to toolkit.  For example, the
+      object with toolkit focus may actually be the parent of the
+      object that is highlighted.  As such,
+      the <code class="literal">orca_status.locusOfFocus</code> field is an an
+      attempt to neutralize these differences across toolkits: the
+      locus of focus is the individual object that is highlighted, has
+      the caret, etc.</p><p>Orca scripts
+      set <code class="literal">orca_state.locusOfFocus</code> to inform Orca
+      when the locus of focus has changed.  In addition, in the event
+      that there was a visual appearance change to the object that has
+      the locus of focus, the <code class="literal">orca</code> module provides
+      a <code class="literal">visualAppearanceChanged</code> that scripts can
+      use to inform Orca of this event.</p><p><span class="emphasis"><em>NOTE:</em></span> The <code class="literal">orca_state.locusOfFocus</code>
+      field is intended to be set only via the
+      <code class="literal">setLocusOfFocus</code> method of the
+      <code class="literal">orca</code> module. Because the
+      <code class="literal">orca.setLocusOfFocus</code> method performs bookkeeping
+      and other tasks, the
+      <code class="literal">orca_state.locusOfFocus</code> field should never be
+      set directly.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="archsettings"></a>settings</h3></div></div></div><p>The <code class="literal">settings</code> module (not depicted in
+        the high level Orca architecture diagram) holds preferences
+        set by the user during configuration.  These settings include
+        the following: use of speech, braille, and/or magnification,
+        voice styles, key echo, text echo, etc.</p><p>Any Orca module can check the value of a setting by
+        examining the field directly in the
+        <code class="literal">settings</code> module.  In addition, the
+        <code class="literal">orca</code> module will import the
+        <code class="literal">user-settings</code> module from the
+        <code class="literal">~/.orca directory</code>, if it exists.
+        The <code class="literal">user-settings</code> module is
+	created as part of the configuration process that is run the
+	first time Orca is used or when the user presses 
+	<code class="literal">Insert+Space</code> to invoke the configuration
+	GUI.</p><p>The <code class="literal">user-settings</code> module is a Python
+        script, allowing it to contain functions, class definitions,
+        etc.  The primary job of the
+        <code class="literal">user-settings</code>, however, is to directly set
+        the values of fields in the <code class="literal">settings</code>
+        module.</p><p><span class="emphasis"><em>IMPLEMENTATION DETAIL:</em></span> the <code class="literal">init</code> method of the
+        <code class="literal">orca</code> module obtains settings.  As a
+        result, the <code class="literal">user-settings</code> module is
+        imported very early in the Orca life cycle.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="script"></a>Orca Scripts</h2></div></div></div><p>The <code class="literal">orca</code> module creates a single
+      instance of a <code class="literal">FocusTrackingPresenter</code> (defined
+      in the
+      <code class="literal">focus_tracking_presenter</code> module), which manages
+      all the scripts for Orca.</p><p>Details on the <code class="literal">FocusTrackingPresenter</code>
+      and Orca scripts can be found in the <a href="#scriptguide" title="Chapter 3. Introduction to Scripting">Orca Script Writing Guide</a>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="archsystemservices"></a>System Services</h2></div></div></div><p> Orca relies on existing system services to provide
+      support for speech synthesis, braille, and screen magnification.
+      To interact with these services, Orca provides the modules
+      described in the following sections.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="archspeech"></a>speech</h3></div></div></div><p>All speaking operations should be done by calling
+        methods in the <code class="literal">speech</code> module.
+        The <code class="literal">speech</code> module provides Orca's Python
+        interface to system speech services.  Each speech service is
+        generated by a "speech server factory."  There are currently
+        three such factories: one for
+        [<span class="citation"><a href="#gnome-speech">gnome-speech</a></span>] (see the
+        <code class="literal">gnomespeechfactory</code> module), one for
+        [<span class="citation"><a href="#emacspeak">Emacspeak</a></span>] (see the
+        <code class="literal">espeechfactory</code> module), and one for
+        SpeechDispatcher (see
+        the <code class="literal">speechdispatcherfactory</code> module).
+        Currently, the only officially supported factory is the one
+        provided by the <code class="literal">gnomespeechfactory</code>
+        module.</p><p>Each speech factory offers up a list of
+        <code class="literal">SpeechServer</code>s, where each
+        <code class="literal">SpeechServer</code> is typically an interface to
+        a particular speech engine.  For example, the
+        <code class="literal">espeechfactory</code> will offer up a
+        <code class="literal">SpeechServer</code> that talks to the Fonix
+        DECtalk engine and a <code class="literal">SpeechServer</code> that
+        talks to the IBMTTS engine.  Likewise, the
+        <code class="literal">gnomespeechfactory</code> will offer up a
+        <code class="literal">SpeechServer</code> that uses the
+        <code class="literal">gnome-speech</code> interface to talk to the
+        eSpeak synthesis engine, a separate
+        <code class="literal">SpeechServer</code> that also uses the
+        <code class="literal">gnome-speech</code> interface to talk to the Fonix
+        DECtalk engine, and so on.</p><p>Each <code class="literal">SpeechServer</code> instance provides a
+        set of methods for actually speaking. Many of the methods
+        accepts an <code class="literal">ACSS</code> instance, which represents
+        an aural cascading style sheet ([<span class="citation"><a href="#acss">ACSS</a></span>]) that defines the voice and
+        voice parameter settings to use.</p><p>As part of the <code class="literal">orca-setup</code> process,
+        the user selects a particular speech factory,
+        <code class="literal">SpeechServer</code>, and voice to use as their
+        default voice.  When Orca starts, the
+        <code class="literal">speech</code> module looks for these settings
+        and connects to the appropriate speech factory and
+        <code class="literal">SpeechServer</code>.  In the event the a
+        connection cannot be made, the <code class="literal">speech</code>
+        module attempts to find a working synthesis engine to use by
+        examining its list of speech factories.  The
+        <code class="literal">speech</code> module then provides simple methods
+        that delegate to the <code class="literal">SpeechServer</code> instance.
+        Although this model allows scripts to use their own
+        <code class="literal">SpeechServer</code> instances if they wish,
+        scripts typically just rely upon the user's default
+        preferences.</p><p><span class="emphasis"><em>NOTE:</em></span> Each Orca script has a
+        single <code class="literal">speechgenerator.SpeechGenerator</code>
+        instance to help generate text to be sent to
+        the <code class="literal">speech</code> module.  More information on
+        speech generators can be found in the
+        <a href="#scriptguide" title="Chapter 3. Introduction to Scripting">Orca Script Writing Guide</a>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="archbraille"></a>braille</h3></div></div></div><p> The <code class="literal">braille</code> module provides Orca's
+        Python interface to the system's BrlTTY
+        [<span class="citation"><a href="#brltty">BRLTTY</a></span>] daemon.  The BrlTTY
+        daemon, in turn, provides the interface to braille devices
+        for both displaying braille and receiving input from the
+        user.</p><p><span class="emphasis"><em>NOTE:</em></span> As with speech, each Orca script has a
+        single <code class="literal">braillegenerator.BrailleGenerator</code>
+        instance to help generate text to be sent to
+        the <code class="literal">braille</code> module.  More information on
+        braille generators can be found in the
+        <a href="#scriptguide" title="Chapter 3. Introduction to Scripting">Orca Script Writing Guide</a>.</p><p><span class="emphasis"><em>TODO:</em></span> flesh this section out more.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="archmag"></a>mag</h3></div></div></div><p> The <code class="literal">mag</code> module
+        provides Orca's Python interface to the system's gnome-mag
+        [<span class="citation"><a href="#gnome-mag">gnome-mag</a></span>] CORBA service(s).  The
+        magnification component provides methods that permit Orca
+        discover screen magnification services and set their desktop
+        region of interest.  The script is responsible for
+        calling <code class="literal">mag.magnifyAccessible</code> with the
+        appropriate parameters to set the magnifier's region of
+        interest.</p><p><span class="emphasis"><em>TODO:</em></span> flesh this section out more.</p></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="scriptguide"></a>Chapter 3. Introduction to Scripting</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#sgcontract">Script Contract</a></span></dt><dt><span class="section"><a href="#sglifecycle">Script Life Cycle</a></span></dt></dl></div><p>In this section, you will learn more about the Orca
       architecture as well as how to create your own custom scripts
       for Orca.</p><p>The goal of scripting is to provide Orca with the capability
       of providing a natural feeling and compelling user experience
@@ -438,7 +469,7 @@
       here only for historical purposes.</p><p>The customized behavior of a script is set up in its
       constructor.  In its constructor, each script is expected to
       extend/override several fields as illustrated in the following
-      diagram and describe below:</p><div class="figure"><a name="id2493464"></a><p class="title"><b>Figure 4.1. Orca Script Diagram</b></p><div class="mediaobject"><img src="script.jpg" alt="Orca Script Diagram"></div></div><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">listeners</code>: a dictionary where the
+      diagram and describe below:</p><div class="figure"><a name="id2493370"></a><p class="title"><b>Figure 4.1. Orca Script Diagram</b></p><div class="mediaobject"><img src="script.jpg" alt="Orca Script Diagram"></div></div><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">listeners</code>: a dictionary where the
           keys are strings that match AT-SPI event types (e.g.,
           <code class="literal">focus:</code>,
           <code class="literal">object:text-caret-moved</code>, etc.), and the
@@ -804,23 +835,23 @@ if settings.brailleVerbosityLevel == settings.VERBOSITY_LEVEL_VERBOSE:
     regions.append(braille.Region(
                    " " + rolenames.getBrailleForRoleName(obj)))
         </pre></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="i18n"></a>Chapter 6. Internationalization (I18N) Support</h2></div></div></div><p>All human-consumable text obtained from AT-SPI calls is
-      expected to be in a localized form.  As such, Orca does not
-      do any extra localization processing when working with text
-      obtained via the AT-SPI.</p><p>For text generated by Orca itself, Orca handles
-      internationalization and localization using the [<span class="citation"><a href="#gettext">gettext</a></span>] support
-      of Python.  The gettext support of Python is similar to the GNU
-      gettext module.  Each human consumable string of Orca is US
-      English text wrapped in a call to gettext.gettext.  The call to
-      gettext.gettext will either return a localized string or default
-      to the US English text. Orca depends upon an active and thriving
-      community of open source translators to provide the
-      localizations.</p><p>The synthesis of localized speech is to be provided by the
-      underlying gnome-speech engine.  That is, Orca merely passes
-      localized text to the speech engine, which is responsible for
-      the correct interpretation and pronunciation.</p><p>The generation of localized braille is to be determined.
-      <span class="emphasis"><em>TODO:</em></span> BrlTTY currently does not support this at the moment, but
-      it is expected that the BrlTTY developers will add this in the
-      future.</p></div><div class="bibliography"><div class="titlepage"><div><div><h2 class="title"><a name="archbibliography"></a>Bibliography</h2></div></div></div><div class="biblioentry"><a name="at-spi"></a><p>[<span class="abbrev"><a name="at-spi.abbrev"></a>AT-SPI</span>] <span class="authorgroup"><span class="firstname">Bill</span> <span class="surname">Haneman</span>, <span class="firstname">Marc</span> <span class="surname">Mulcahy</span>, and <span class="firstname">Michael</span> <span class="surname">Meeks</span>. </span><span class="title"><i><a href="http://directory.fsf.org/accessibility/at-spi.html"; target="_top">
+    expected to be in a localized form.  As such, Orca does not do any
+    extra localization processing when working with text obtained via
+    the AT-SPI.</p><p>For text generated by Orca itself, Orca handles
+    internationalization and localization using
+    the [<span class="citation"><a href="#gettext">gettext</a></span>] support of Python.  The
+    gettext support of Python is similar to the GNU gettext module.
+    Each human consumable string of Orca is US English text wrapped in
+    a call to gettext.gettext.  The call to gettext.gettext will
+    either return a localized string or default to the US English
+    text. Orca depends upon an active and thriving community of open
+    source translators to provide the localizations.</p><p>The synthesis of localized speech is to be provided by the
+    underlying gnome-speech engine.  That is, Orca merely passes
+    localized text to the speech engine, which is responsible for the
+    correct interpretation and pronunciation.</p><p>The generation of localized braille is to be determined.
+    <span class="emphasis"><em>TODO:</em></span> BrlTTY currently does not support this at the moment, but
+    it is expected that the BrlTTY developers will add this in the
+    future.</p></div><div class="bibliography"><div class="titlepage"><div><div><h2 class="title"><a name="archbibliography"></a>Bibliography</h2></div></div></div><div class="biblioentry"><a name="at-spi"></a><p>[<span class="abbrev"><a name="at-spi.abbrev"></a>AT-SPI</span>] <span class="authorgroup"><span class="firstname">Bill</span> <span class="surname">Haneman</span>, <span class="firstname">Marc</span> <span class="surname">Mulcahy</span>, and <span class="firstname">Michael</span> <span class="surname">Meeks</span>. </span><span class="title"><i><a href="http://directory.fsf.org/accessibility/at-spi.html"; target="_top">
         AT-SPI</a>
     </i>. </span></p></div><div class="biblioentry"><a name="acss"></a><p>[<span class="abbrev"><a name="acss.abbrev"></a>ACSS</span>] <span class="authorgroup"><span class="firstname">T.V.</span> <span class="surname">Raman</span>. </span><span class="title"><i><a href="http://www.w3.org/TR/1998/REC-CSS2-19980512/aural.html"; target="_top">Aural Style Sheets</a>
     </i>. </span></p></div><div class="biblioentry"><a name="bonobo"></a><p>[<span class="abbrev"><a name="bonobo.abbrev"></a>Bonobo</span>] <span class="author"><span class="firstname">George</span> <span class="surname">Lebl</span>. </span><span class="title"><i><a href="http://lidn.sourceforge.net/articles/gnomenclatureintrotobonobo/"; target="_top">
diff --git a/docs/doc-set/internals.sgml b/docs/doc-set/internals.sgml
index bf9e895..25198b3 100644
--- a/docs/doc-set/internals.sgml
+++ b/docs/doc-set/internals.sgml
@@ -1,4 +1,4 @@
-<!-- Copyright 2005-2008, Sun Microsystems, Inc. -->
+<!-- Copyright 2005-2009, Sun Microsystems, Inc. -->
 
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.0//EN" "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd";
 [
@@ -34,9 +34,9 @@
   <preface id="archforward"><title>Foreword</title>
     &blurb;
     <para>This book covers the overall architecture of Orca, including
-      a portion on writing custom scripts. The bulk of the user
-      information and user experience design can be found on the Orca
-      WIKI at http://live.gnome.org/Orca.</para>
+    a portion on writing custom scripts. The bulk of the end user
+    information and user experience design can be found on the 
+    <ulink url="http://live.gnome.org/Orca";>Orca WIKI</ulink>.</para>
   </preface>
 
   <!--
@@ -48,42 +48,58 @@
   -->
 
   <chapter id="prereq"><title>Prerequisites</title>
-    <para>To help narrow the scope of the Orca development activity,
-      Orca uses existing software where available.  For example, as
-      mentioned in the requirements, Orca is a screen reader that
-      needs to be able to interact with speech synthesis, braille,
-      and screen magnification services, but it need not be the
-      provider of such services.  Given this, Orca has the following
-      dependencies:</para>
-
-    <section id="prereqgnome"><title>GNOME 2.22 or better</title> 
-      <para>The GNOME 2.22 desktop contains a number of bug fixes and
-        enhancements to the accessibility infrastructure.  These are
-        needed for Orca to run properly.  GNOME 2.22 also packages a
-        variety of other dependencies of Orca, including gnome-speech,
-        gnome-mag, pyatspi, etc.</para>
+    <para>Orca is a screen reader that needs to be able to interact
+    with speech synthesis, braille, and screen magnification services,
+    but it need not be the provider of such services. To help narrow
+    the scope of the Orca development activity, Orca uses existing
+    software where available.  As such, Orca has the following
+    dependencies.</para>
+
+    <section id="prereqgnome"><title>GNOME</title> 
+      <para>Orca is part of the GNOME project and ships with each
+      release of GNOME.  Because Orca uses a number of GNOME
+      components, such as AT-SPI, ATK, GAIL, gnome-speech, gnome-mag,
+      and GTK+, Orca is only supported on the release of GNOME with
+      which it was released.  For example, Orca v2.22.0 was released
+      with GNOME 2.22.0 and is only supported on GNOME 2.22.0.  To
+      determine the version of Orca you are using, run the following
+      command:
+<programlisting>
+orca --version
+</programlisting>
+      To determine the version of GNOME you are using, run the
+      following command:
+<programlisting>
+gnome-about --version
+</programlisting>
+      </para>
     </section>
 
     <section id="prereqpython"><title>Python v2.4 or better</title> 
       <para>Orca is written in the Python programming language and
-        depends upon features found in Python versions 2.4 and
-        greater.</para>
+      depends upon features found in Python versions 2.4 and
+      greater. To determine the version of Python you are using, run
+      the following command:
+<programlisting>
+python -V
+</programlisting>
+      </para>
     </section>
 
     <section id="prereqbrltty"><title>BrlTTY v3.7.2 or better</title>
       <para>BrlTTY <citation><xref linkend="brltty"
-        endterm="brltty.abbrev"/></citation> provides access to a
-        variety of Braille displays, and consists of a library and a
-        daemon to provide programmatic interaction with the
-        display.</para>
+      endterm="brltty.abbrev"/></citation> provides access to a
+      variety of Braille displays, and consists of a library and a
+      daemon to provide programmatic interaction with the
+      display.</para>
     </section>
 
     <section id="prereqkeyboardnav"><title>Keyboard Navigation</title>
       <para>As much as possible, Orca relies upon the keyboard
-        navigation methods built in to the native platform.  For
-        example, it is expected that the native platform will provide
-        access via traditional methods such as the "tab" key, keyboard
-        mnemonics, and keyboard accelerators.</para>
+      navigation methods built in to the native platform.  For
+      example, it is expected that the native platform will provide
+      access via traditional methods such as the "tab" key, keyboard
+      mnemonics, and keyboard accelerators.</para>
     </section>
   </chapter>
 
@@ -100,27 +116,27 @@
 
   <chapter id="i18n"><title>Internationalization (I18N) Support</title>
     <para>All human-consumable text obtained from AT-SPI calls is
-      expected to be in a localized form.  As such, Orca does not
-      do any extra localization processing when working with text
-      obtained via the AT-SPI.</para>
+    expected to be in a localized form.  As such, Orca does not do any
+    extra localization processing when working with text obtained via
+    the AT-SPI.</para>
     <para>For text generated by Orca itself, Orca handles
-      internationalization and localization using the <citation><xref
-      linkend="gettext" endterm="gettext.abbrev"/></citation> support
-      of Python.  The gettext support of Python is similar to the GNU
-      gettext module.  Each human consumable string of Orca is US
-      English text wrapped in a call to gettext.gettext.  The call to
-      gettext.gettext will either return a localized string or default
-      to the US English text. Orca depends upon an active and thriving
-      community of open source translators to provide the
-      localizations.</para>
+    internationalization and localization using
+    the <citation><xref linkend="gettext"
+    endterm="gettext.abbrev"/></citation> support of Python.  The
+    gettext support of Python is similar to the GNU gettext module.
+    Each human consumable string of Orca is US English text wrapped in
+    a call to gettext.gettext.  The call to gettext.gettext will
+    either return a localized string or default to the US English
+    text. Orca depends upon an active and thriving community of open
+    source translators to provide the localizations.</para>
     <para>The synthesis of localized speech is to be provided by the
-      underlying gnome-speech engine.  That is, Orca merely passes
-      localized text to the speech engine, which is responsible for
-      the correct interpretation and pronunciation.</para>
+    underlying gnome-speech engine.  That is, Orca merely passes
+    localized text to the speech engine, which is responsible for the
+    correct interpretation and pronunciation.</para>
     <para>The generation of localized braille is to be determined.
-      &todo; BrlTTY currently does not support this at the moment, but
-      it is expected that the BrlTTY developers will add this in the
-      future.</para>
+    &todo; BrlTTY currently does not support this at the moment, but
+    it is expected that the BrlTTY developers will add this in the
+    future.</para>
   </chapter>
 
   <!--
diff --git a/docs/doc-set/legal.sgml b/docs/doc-set/legal.sgml
index 49a9e76..45d0bda 100644
--- a/docs/doc-set/legal.sgml
+++ b/docs/doc-set/legal.sgml
@@ -1,5 +1,5 @@
-<!-- Copyright 2005-2008, Sun Microsystems, Inc. -->
+<!-- Copyright 2005-2009, Sun Microsystems, Inc. -->
 
 <legalnotice>
-   <para>Copyright 2005-2008, Sun Microsystems, Inc.</para>
+  <para>Copyright 2005-2009, Sun Microsystems, Inc.</para>
 </legalnotice>