GNOME.org
 

[orca] Continued work on bug 631123 - Orca documentation needs to be updated, converted to Mallard, augment

commit 99a8d77ce3c68a0c511a78f5fe1e71f0de025d39
Author: Joanmarie Diggs <joanmarie diggs gmail com>
Date:   Sat Dec 18 19:57:04 2010 -0500

    Continued work on bug 631123 - Orca documentation needs to be updated, converted to Mallard, augmented, and moved to the Orca module
    
    * Added a "Quick Reference" section to the top so that the main
      page is less verbose and more table-of-contents like.
    * Addressed the bulk of AlanC's comments (#6 of the bug)

 help/C/commands.page                  |   17 +---------
 help/C/commands_mouse.page            |   17 +++++++++--
 help/C/commands_reading.page          |   18 +++++++++--
 help/C/howto_keyboard_layout.page     |    4 +-
 help/C/howto_text_setup.page          |    2 +-
 help/C/index.page                     |   12 ++-----
 help/C/preferences.page               |   53 ++++++++++++--------------------
 help/C/preferences_key_bindings.page  |   12 +++++--
 help/C/preferences_pronunciation.page |    4 +-
 9 files changed, 67 insertions(+), 72 deletions(-)
---
diff --git a/help/C/commands.page b/help/C/commands.page
index 889ec01..5b1b81c 100644
--- a/help/C/commands.page
+++ b/help/C/commands.page
@@ -1,8 +1,9 @@
 <page xmlns="http://projectmallard.org/1.0/"; type="guide" id="commands">
   <info>
     <link type="next" xref="commands_controlling_orca" />
-    <link type="seealso" xref="index" />
+    <link type="guide" xref="index#quick_reference" />
     <title type="sort">4. <app>Orca</app>'s Commands</title>
+    <title type="link">Commands</title>
     <credit type="author">
       <name>Joanmarie Diggs</name>
       <email>joanied gnome org</email>
@@ -10,22 +11,8 @@
     <license>
       <p>Creative Commons Share Alike 3.0</p>
     </license>
-    <desc>
-      Much of <app>Orca</app>'s functionality consists of commands which
-      enable you to navigate more efficiently and obtain information about
-      the elements displayed on the screen. The guides are designed for those
-      who are already familiar with how to use a screen reader and just need
-      to know what commands are available in <app>Orca</app>.
-    </desc>
   </info>
   <title><app>Orca</app>'s Commands</title>
-  <p>
-    Much of <app>Orca</app>'s functionality consists of commands which enable
-    you to navigate more efficiently and obtain information about the elements
-    displayed on the screen. The guides are designed for those who are already
-    familiar with how to use a screen reader and just need to know what commands
-    are available in <app>Orca</app>.
-  </p>
   <section id="getting_started"  style="2column">
     <title>Getting Started</title>
   </section>
diff --git a/help/C/commands_mouse.page b/help/C/commands_mouse.page
index 3d66b09..bbeafbf 100644
--- a/help/C/commands_mouse.page
+++ b/help/C/commands_mouse.page
@@ -19,12 +19,23 @@
   </info>
   <title>Mouse/Pointer-Related Commands</title>
   <p>
-    The following commands can be used to manipulate the mouse pointer
-    and read the contents under it. All of the commands are "bound"
-    to keystrokes with one exception: Toggling Mouse Review Mode.
+    <app>Orca</app> provides several commands which can be used to manipulate
+    the mouse pointer and read the contents under it. All of the commands are
+    "bound" to keystrokes with one exception: Toggling Mouse Review Mode.
     Please see <link xref="howto_key_bindings">Modifying Keybindings</link>
     for information on how to bind this command to a keystroke.
   </p>
+  <note style="tip">
+    <p>
+      In the list that follows, you will see several references to "KP". All
+      "KP" keys are located on the numeric keypad. You will also notice that
+      there are different keystrokes depending upon whether you are using a
+      desktop or a laptop -- or more accurately, whether you are using
+      <app>Orca</app>'s Desktop keyboard layout or its Laptop keyboard layout.
+      For additional information, please see the
+      <link xref="howto_keyboard_layout">Keyboard Layout</link> topic.
+    </p>
+  </note>
   <list>
     <item>
       <p>Left-click on current item:</p>
diff --git a/help/C/commands_reading.page b/help/C/commands_reading.page
index e6e9c83..ee37eb0 100644
--- a/help/C/commands_reading.page
+++ b/help/C/commands_reading.page
@@ -25,15 +25,27 @@
     will present your new location. As a result, you are likely already familiar with
     how to read a document using <app>Orca</app>. However, if you would like to review
     GNOME's caret navigation commands, please see 
-    "<link href="http://library.gnome.org/users/gnome-access-guide/unstable/keynav-52.html";>Caret 
+    "<link href="http://library.gnome.org/users/gnome-access-guide/stable/keynav-52.html";>Caret 
     Navigation Mode</link>" in the
-    <link href="http://library.gnome.org/users/gnome-access-guide/unstable";>GNOME 
+    <link href="http://library.gnome.org/users/gnome-access-guide/stable";>GNOME 
     Desktop Accessibility Guide</link>.
   </p>
   <p>
     In addition to the caret navigation commands which are part of GNOME,
-    you can use the following <app>Orca</app> commands to read a document:
+    <app>Orca</app> provides a number of commands which you can use to read a
+    document.
   </p>
+  <note style="tip">
+    <p>
+      In the lists that follow, you will see several references to "KP". All
+      "KP" keys are located on the numeric keypad. You will also notice that
+      there are different keystrokes depending upon whether you are using a
+      desktop or a laptop -- or more accurately, whether you are using
+      <app>Orca</app>'s Desktop keyboard layout or its Laptop keyboard layout.
+      For additional information, please see the
+      <link xref="howto_keyboard_layout">Keyboard Layout</link> topic.
+    </p>
+  </note>
   <section id="flat_review">
     <title>Reading Your Current Location</title>
     <p>
diff --git a/help/C/howto_keyboard_layout.page b/help/C/howto_keyboard_layout.page
index 57303e9..1a57320 100644
--- a/help/C/howto_keyboard_layout.page
+++ b/help/C/howto_keyboard_layout.page
@@ -14,8 +14,8 @@
   </info>
   <title>Keyboard Layout</title>
   <p>
-    Orca has two keyboard layouts: Desktop and Laptop. The layout you choose
-    impacts which key is used as the Orca Modifier.
+    Orca has two keyboard layouts: Desktop (i.e. with a numeric keypad) and
+    Laptop. The layout you choose impacts which key is used as the Orca Modifier.
   </p>
   <list>
     <item>
diff --git a/help/C/howto_text_setup.page b/help/C/howto_text_setup.page
index 4c717e3..3d46083 100644
--- a/help/C/howto_text_setup.page
+++ b/help/C/howto_text_setup.page
@@ -23,7 +23,7 @@
       <p>
         Open a <gui>Run</gui> dialog. For most distros, this can be accomplished
         by pressing <keyseq><key>Alt</key><key>F2</key></keyseq>. Alternatively,
-        you can use a terminal window.
+        you can use a terminal window or the system text console.
       </p>
     </item>
     <item>
diff --git a/help/C/index.page b/help/C/index.page
index ff353d7..8858db6 100644
--- a/help/C/index.page
+++ b/help/C/index.page
@@ -22,15 +22,9 @@
      of the accessibility features in GNOME, including keyboard navigation and
      accessible login.
   </p>
-  <p>
-     If you are new to screen readers or are unfamiliar with <app>Orca</app>,
-     the guides which follow should get you started with performing common
-     tasks using <app>Orca</app>. If, on the other hand, you are already
-     familiar with how to use a screen reader and just need to know what options
-     and tools <app>Orca</app> provides, you may prefer to read the guides
-     covering <link xref="preferences"><app>Orca</app>'s Preferences dialogs
-     </link> and <link xref="commands"><app>Orca</app>'s commands</link>.
-  </p>
+  <section id="quick_reference" style="2column">
+    <title>Quick Reference</title>
+  </section>
   <section id="getting_started" style="2column">
     <title>Getting Started</title>
   </section>
diff --git a/help/C/preferences.page b/help/C/preferences.page
index 13c25bf..479c016 100644
--- a/help/C/preferences.page
+++ b/help/C/preferences.page
@@ -1,7 +1,8 @@
 <page xmlns="http://projectmallard.org/1.0/"; type="guide" id="preferences">
   <info>
     <link type="next" xref="preferences_general" />
-    <link type="seealso" xref="index" />
+    <link type="guide" xref="index#quick_reference" />
+    <title type="link">Preferences</title>
     <credit type="author">
       <name>Joanmarie Diggs</name>
       <email>joanied gnome org</email>
@@ -9,40 +10,8 @@
     <license>
       <p>Creative Commons Share Alike 3.0</p>
     </license>
-    <desc>
-      <app>Orca</app>'s preferences dialogs allow you to customize the
-      behavior and features of <app>Orca</app>, including speech, braille,
-      magnification, and keyboard layout. These customizations can be set
-      globally or be limited to a particular application. These guides will
-      familiarize you with all of the customizations which you can make.
-    </desc>
   </info>
   <title><app>Orca</app>'s Preferences Dialogs</title>
-  <p>
-    <app>Orca</app>'s preferences dialogs allow you to customize the behavior
-    and features of <app>Orca</app>, including speech, braille, magnification,
-    and keyboard layout. These customizations can be set globally or be limited
-    to a particular application. These guides will familiarize you with all of
-    the customizations which you can make.
-  </p>
-  <note style="tip">
-    <title>Keyboard Shortcuts for Getting Into the Preferences Dialogs</title>
-    <list>
-      <item>
-        <p>
-          <keyseq><key>Orca Modifier</key><key>Space</key></keyseq>:
-          <app>Orca</app>'s Preferences
-        </p>
-      </item>
-      <item>
-        <p>
-          <keyseq><key>Ctrl</key><key>Orca Modifier</key><key>Space</key>
-          </keyseq>: <app>Orca</app>'s Preferences for the current
-          application
-        </p>
-      </item>
-    </list>
-  </note>
   <section id="orca" style="2column">
     <title>Orca Preferences</title>
     <p>
@@ -51,6 +20,24 @@
       General Preferences, you will find the following available in both the
       <app>Orca</app> Preferences dialog and <app>Orca</app>'s
       application-specific preferences dialogs.</p>
+    <note style="tip">
+      <title>Keyboard Shortcuts for Getting Into the Preferences Dialogs</title>
+      <list>
+        <item>
+          <p>
+            <keyseq><key>Orca Modifier</key><key>Space</key></keyseq>:
+            <app>Orca</app>'s Preferences
+          </p>
+        </item>
+        <item>
+          <p>
+            <keyseq><key>Ctrl</key><key>Orca Modifier</key><key>Space</key>
+            </keyseq>: <app>Orca</app>'s Preferences for the current
+            application
+          </p>
+        </item>
+      </list>
+    </note>
   </section>
   <section id="application" style="2column">
     <title>Application-Unique Preferences</title>
diff --git a/help/C/preferences_key_bindings.page b/help/C/preferences_key_bindings.page
index 389222e..24fec73 100644
--- a/help/C/preferences_key_bindings.page
+++ b/help/C/preferences_key_bindings.page
@@ -25,10 +25,14 @@
       key or keys will serve as the Orca Modifier. The available options are:
     </p>
     <list>
-      <item><p>Insert, KP_Insert</p></item>
-      <item><p>KP_Insert</p></item>
-      <item><p>Insert</p></item>
-      <item><p>Caps_Lock</p></item>
+      <item>
+        <p>
+          <gui>KP_Insert</gui> (the same key as the <key>0</key> on the
+          numeric keypad)
+      </p></item>
+      <item><p><gui>Insert</gui></p></item>
+      <item><p><gui>Insert, KP_Insert</gui></p></item>
+      <item><p><gui>Caps_Lock</gui></p></item>
     </list>
   </section>
   <section id="key_bindings_table">
diff --git a/help/C/preferences_pronunciation.page b/help/C/preferences_pronunciation.page
index b5c2143..ff88e5e 100644
--- a/help/C/preferences_pronunciation.page
+++ b/help/C/preferences_pronunciation.page
@@ -20,8 +20,8 @@
   <p id="introduction">
     Sometimes your speech synthesizer just doesn't say the right thing
     for a given string. You might prefer to hear "laughing out loud"
-    rather than "LOL." Or there may be a name or a technical term which
-    the synthesizer mispronounces.
+    rather than "LOL," or "accessibility" rather than "a11y". Or there
+    may be a name or a technical term which the synthesizer mispronounces.
   </p>
   <p>
      The <gui>Pronunciation</gui> page of the <app>Orca</app> preferences
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]