[orca] Doc rewrite in progress: Added a Live Regions page

[Joanmarie Diggs <joanied src gnome org>]

commit bbfbf520f791ef47e04d611176d6aa913327983a
Author: Joanmarie Diggs <joanmarie diggs gmail com>
Date:   Thu Dec 16 20:38:20 2010 -0500

    Doc rewrite in progress: Added a Live Regions page

 help/C/commands_live_regions.page |    2 +-
 help/C/howto_live_regions.page    |   60 +++++++++++++++++++++++++++
 help/C/howto_reading_web.page     |   82 +++++++++++++++++++++++++++++++++++--
 help/C/howto_tables.page          |    4 +-
 help/Makefile.am                  |    1 +
 5 files changed, 142 insertions(+), 7 deletions(-)
---
diff --git a/help/C/commands_live_regions.page b/help/C/commands_live_regions.page
index 89ae977..23d08d2 100644
--- a/help/C/commands_live_regions.page
+++ b/help/C/commands_live_regions.page
@@ -2,7 +2,7 @@
   <info>
     <link type="next" xref="commands_chat" />
     <link type="guide" xref="commands#accessing_dynamic_information" />
-    <link type="seealso" xref="howto_reading_web"  />
+    <link type="seealso" xref="howto_live_regions"  />
     <title type="sort">1. Live Region</title>
     <title type="link">Live Regions</title>
     <desc>
diff --git a/help/C/howto_live_regions.page b/help/C/howto_live_regions.page
new file mode 100644
index 0000000..4b0409f
--- /dev/null
+++ b/help/C/howto_live_regions.page
@@ -0,0 +1,60 @@
+<page xmlns="http://projectmallard.org/1.0/"; type="topic" id="howto_live_regions">
+  <info>
+    <link type="guide" xref="index#reading"/>
+    <link type="next" xref="howto_whereami" />
+    <title type="sort">6. Live Regions</title>
+    <desc>
+      Interacting with dynamic web content
+    </desc>
+    <credit type="author">
+      <name>Joanmarie Diggs</name>
+      <email>joanied gnome org</email>
+    </credit>
+    <license>
+      <p>Creative Commons Share Alike 3.0</p>
+    </license>
+  </info>
+  <title>Live Regions</title>
+  <p>
+    A live region is a dynamically-updated portion of a web page, such as a
+    table of sports statistics, a list of current stock prices, a log from
+    a chat, or an alert displayed by the page you are reading. While live
+    regions appear quite frequently, fully accessible web pages with live
+    regions are encountered less often. This problem is actively being
+    addressed by a number of organizations.
+  </p>
+  <section>
+    <title>Live Region Politeness Levels</title>
+    <p>
+      Live regions have an associated "politeness" level which is set by the
+      author as a means to convey the importance of the information and to
+      suggest when users should be informed by their assistive technology of
+      updates made within that region. Live regions can be "off", "polite", or
+      "aggressive" to the point of being "rude."
+    </p>
+  </section>
+  <section>
+    <title><app>Orca</app>'s Support for Live Regions</title>
+    <p>
+      Because you might not agree with the politeness level specified by the
+      author whose page you are viewing, <app>Orca</app> provides a number of
+      <link xref="commands_live_regions">live region commands</link> which
+      allow you to modify the level of any or all of the regions on a page.
+      In addition, you can:
+    </p>
+    <list>
+      <item>
+        <p>Turn live region support on or off</p>
+      </item>
+      <item>
+        <p>Jump to the next and previous live region spatially</p>
+      </item>
+      <item>
+        <p>Jump to the last live region which presented information</p>
+      </item>
+      <item>
+        <p>Review the last nine live region messages which were presented</p>
+    </item>
+    </list>
+  </section>
+</page>
diff --git a/help/C/howto_reading_web.page b/help/C/howto_reading_web.page
index 03b6660..5b5dbdc 100644
--- a/help/C/howto_reading_web.page
+++ b/help/C/howto_reading_web.page
@@ -14,8 +14,82 @@
       <p>Creative Commons Share Alike 3.0</p>
     </license>
   </info>
-  <title>Web Pages (WRITE ME)</title>
-  <p>
-    Write me
-  </p>
+  <title>Web Pages (FINISH ME)</title>
+  <section id="caret_navigation">
+    <title>Caret Navigation</title>
+    <p>
+      Write me
+    </p>
+    </section>
+      <section id="structural_navigation">
+    <title>Structural Navigation</title>
+    <p>
+      Write me
+    </p>
+    </section>
+    <section id="live_regions">
+      <title>Live Regions</title>
+      <p>
+        Live regions are parts of a web page that the web page author expects to
+        change dynamically. Examples of live regions include:
+      </p>
+      <list>
+        <item>
+          <p>tables displaying sports statistics or stock prices</p>
+        </item>
+        <item>
+          <p>logs from a browser-based chat tool</p>
+        </item>
+        <item>
+          <p>notifications or alerts that pop up on the page you are reading</p>
+        </item>
+      </list>
+      <p>
+        Many such sites exist; however, providing fully accessible web pages which
+        utilize live regions has been more of a challenge. These challenges are
+        being addressed by the W3C and the developers of Gecko and WebKitGtk.
+      </p>
+      <note style="tip">
+        <title>Live Region Politeness Levels</title>
+        <p>
+          The "politeness level" associated with a live region is not an Orca
+          concept, but rather an ARIA one. While the <link href="http://www.w3.org/TR/wai-aria/states_and_properties#aria-live";>W3C</link>
+          and <link href="https://developer.mozilla.org/en/AJAX/WAI_ARIA_Live_Regions#aria-live.3dPOLITENESS_SETTING";>Mozilla</link>
+          definitions differ slightly, the consensus is that live regions can be
+          completely off, polite, or aggressive to the point of being rude.
+        </p>
+        <p>
+          How polite a live region is -- or is not -- is initially determined by
+          the creator of that live region based on its nature. Because you might
+          not agree with the level specified by the author whose page you are
+          viewing, <app>Orca</app> provides commands with allow you to modify
+          the level for any or all of the live regions on any page.
+        </p>
+      </note>
+      <p>
+        In addition to being able to adjust the politeness level of live regions,
+        you can:
+      </p>
+      <list>
+        <item>
+          <p>Turn live region support on or off</p>
+        </item>
+        <item>
+          <p>Jump to the next and previous live region spatially</p>
+        </item>
+        <item>
+          <p>Jump to the last live region which presented information</p>
+        </item>
+        <item>
+          <p>Jump to the last live region which presented information</p>
+        </item>
+        <item>
+          <p>Review the last nine live region messages which were presented</p>
+        </item>
+      </list>
+      <p>
+        The keybindings for performing all of the above tasks can be found in
+        <link xref="commands_live_regions">Live Region Commands</link>.
+      </p>
+    </section>
 </page>
diff --git a/help/C/howto_tables.page b/help/C/howto_tables.page
index 037ef8a..5541414 100644
--- a/help/C/howto_tables.page
+++ b/help/C/howto_tables.page
@@ -1,8 +1,8 @@
 <page xmlns="http://projectmallard.org/1.0/"; type="topic" id="howto_tables">
   <info>
     <link type="guide" xref="index#reading"/>
-    <link type="next" xref="howto_whereami" />
-    <title type="sort">A5 Tables</title>
+    <link type="next" xref="howto_live_regions" />
+    <title type="sort">5. Tables</title>
     <desc>
       Accessing document tables efficiently
     </desc>
diff --git a/help/Makefile.am b/help/Makefile.am
index e5e079a..9c1dc3f 100644
--- a/help/Makefile.am
+++ b/help/Makefile.am
@@ -28,6 +28,7 @@ DOC_PAGES = \
 	howto_key_bindings.page \
 	howto_keyboard_layout.page \
 	howto_learn_modes.page \
+	howto_live_regions.page \
 	howto_mouse_review.page \
 	howto_notifications.page \
 	howto_orca_find.page \