[orca] Doc rewrite in progress: Flat review and Orca Find.

[Joanmarie Diggs <joanied src gnome org>]

commit 9da6292eddeaef884af25961b52a89e868a9c683
Author: Joanmarie Diggs <joanmarie diggs gmail com>
Date:   Wed Dec 15 16:28:19 2010 -0500

    Doc rewrite in progress: Flat review and Orca Find.

 help/C/commands_find.page        |    9 +---
 help/C/commands_flat_review.page |    7 ++-
 help/C/howto_flat_review.page    |   31 ++++++++++++++-
 help/C/howto_orca_find.page      |   79 +++++++++++++++++++++++++++++++++++++-
 4 files changed, 113 insertions(+), 13 deletions(-)
---
diff --git a/help/C/commands_find.page b/help/C/commands_find.page
index e288021..63cbe9d 100644
--- a/help/C/commands_find.page
+++ b/help/C/commands_find.page
@@ -18,12 +18,9 @@
   </info>
   <title>Orca Find Commands</title>
   <p>
-    Orca's Find feature allows you to search for elements displayed on the
-    screen. It is a Flat Review feature. Thus when there is a match, flat
-    review will be activated and moved to that location; focus within the
-    application will not be modified, nor will the caret be repositioned.
-    If you need to accomplish either, please see
-    <link xref="commands_mouse">Orca'a Mouse/Pointer-Related Commands</link>.
+    <app>Orca</app>'s <link xref="howto_orca_find">Find feature</link> allows
+    you to search the <link xref="howto_flat_review">Flat Review</link> context
+    for elements located within the current window.
   </p>
   <list>
     <item>
diff --git a/help/C/commands_flat_review.page b/help/C/commands_flat_review.page
index eb615be..2ee70d3 100644
--- a/help/C/commands_flat_review.page
+++ b/help/C/commands_flat_review.page
@@ -18,9 +18,10 @@
   </info>
   <title>Flat Review Commands</title>
   <p>
-    Orca's Flat Review commands are designed for spatially reviwing
-    elements displayed on the screen. They also provide a means for
-    reading the current line, word, and character.
+    Orca's <link xref="howto_flat_review">Flat Review</link> commands are
+    designed for spatially reviwing elements displayed on the screen. They
+    also provide a means for reading the current line, word, and character
+    when navigating in the text of a document.
   </p>
   <section id="line">
     <title>Commands for Reviewing by Line</title>
diff --git a/help/C/howto_flat_review.page b/help/C/howto_flat_review.page
index 3d4797d..fdde12f 100644
--- a/help/C/howto_flat_review.page
+++ b/help/C/howto_flat_review.page
@@ -12,8 +12,35 @@
       <p>Creative Commons Share Alike 3.0</p>
     </license>
   </info>
-  <title>Flat Review (WRITE ME)</title>
+  <title>Flat Review</title>
   <p>
-    Write me
+    <app>Orca</app>'s Flat Review feature allows you to spatially review the
+    contents, both text and widgets, of the active window. In this mode,
+    <app>Orca</app> treats the window as if it were a two-dimensional sheet of
+    text, eliminating any notion of widget hierarchy or other logical grouping
+    within the window.
+  </p>
+  <p>
+    The "flattened" contents, also known as the Flat Review context, can be
+    <link xref="commands_flat_review">navigated</link> by line, by word, by
+    character, and by object. In addition, you can perform a left-click or
+    right-click on the object being reviewed. Finally, you can use
+    <link xref="howto_orca_find">Orca Find</link>, a Flat-Review-based feature
+    to search the active window's contents.
+  </p>
+  <p>
+    Because the Flat Review context is a spatial representation of the active
+    window's contents, it is created when you first enter Flat Review and only
+    contains those objects which are visible. As a result, you will not be able
+    to use Flat Review to access items which are in the window but currently
+    off-screen. In addition, if the window's contents change of their own
+    accord, the Flat Review context will not automatically be updated. You can
+    cause a new context to be built by toggling Flat Review off and back on.
+  </p>
+  <p>
+    Finally, Flat Review by its nature is a mode that cannot be used at the same
+    time that <app>Orca</app> is tracking focus. Thus if you are in Flat Review
+    and then use the application's navigation commands to move the caret or to
+    give focus to another object, you will automatically leave Flat Review.
   </p>
 </page>
diff --git a/help/C/howto_orca_find.page b/help/C/howto_orca_find.page
index f924e05..eba8e2d 100644
--- a/help/C/howto_orca_find.page
+++ b/help/C/howto_orca_find.page
@@ -12,8 +12,83 @@
       <p>Creative Commons Share Alike 3.0</p>
     </license>
   </info>
-  <title>Orca Find (WRITE ME)</title>
+  <title>Orca Find</title>
   <p>
-    Write me
+    <app>Orca</app>'s Find feature is a
+    <link xref="howto_flat_review">Flat-Review</link>-based search designed to
+    help you quickly locate objects that are visible on-screen within the
+    current window.
+  </p>
+  <note style="tip">
+    <title>Activating Orca Find</title>
+      <p>
+        To open the Orca <gui>Find</gui> dialog, use the following command based
+        on your chosen <link xref="howto_keyboard_layout">keyboard layout</link>:
+      </p>
+      <list>
+        <item>
+          <p>Desktop:<keyseq><key>KP Delete</key></keyseq></p>
+        </item>
+        <item>
+          <p>Laptop:
+            <keyseq><key>Orca Modifier</key><key>Left Bracket</key></keyseq>
+          </p>
+        </item>
+      </list>
+      <p>
+        For a list of additional tasks you can perform, see the
+        <link xref="commands_find">Orca Find commands</link>
+      </p>
+  </note>
+  <p>
+    When you activate Orca Find, you will be placed in a dialog box where you
+    can specify the following items:
+  </p>
+  <list>
+    <item>
+      <p>The text to find</p>
+    </item>
+    <item>
+      <p>The location to start from, which can be:</p>
+      <list>
+        <item>
+          <p><gui>Current location</gui></p>
+        </item>
+        <item>
+          <p><gui>Top of window</gui></p>
+        </item>
+      </list>
+    </item>
+    <item>
+      <p><gui>Match case</gui></p>
+    </item>
+    <item>
+      <p><gui>Match entire word only</gui></p>
+    </item>
+    <item>
+      <p><gui>Search backwards</gui></p>
+    </item>
+    <item>
+      <p>
+        <gui>Wrap around</gui>, should there be no match from the starting point
+      </p>
+    </item>
+  </list>
+  <p>  
+    By default, the search will be case-insensitive and permit partial word
+    matches. And it will begin from your current location and search forward,
+    wrapping if needed.
+  </p>
+  <p>
+    Having performed a search, you can quickly search for the next or previous
+    match without having to return to the Orca Find dialog box.
+  </p>
+  <p>
+    Beause it is a <link xref="howto_flat_review">Flat Review</link> feature,
+    when there is a match, Flat Review will automatically be activated and the
+    matching item or text will become the current review item. Note that focus
+    within the application will not be modified, nor will the caret be
+    repositioned. If you need to accomplish either, please see
+    <link xref="commands_mouse">Orca's Mouse/Pointer-Related Commands</link>.
   </p>
 </page>