[gedit] significant reworkings of the search and replace help topics ... all done to satisfy the needs of pb

[Jim Campbell <jcampbell src gnome org>]

commit fb5dc303325c857f4a0a45ceda4e07d733eaea0a
Author: Jim Campbell <jwcampbell gmail com>
Date:   Tue Mar 15 19:04:18 2011 -0500

    significant reworkings of the search and replace help topics ... all done to satisfy the needs of pbor and nacho.

 help/C/gedit-replace.page |   62 ++++++++------------------------------------
 help/C/gedit-search.page  |   37 ++++++++++++++++++++++++++
 2 files changed, 49 insertions(+), 50 deletions(-)
---
diff --git a/help/C/gedit-replace.page b/help/C/gedit-replace.page
index ecf4f01..4b85449 100644
--- a/help/C/gedit-replace.page
+++ b/help/C/gedit-replace.page
@@ -18,38 +18,20 @@
     </credit>
   </info>
 
-  <title>Find and replace text</title>
-  <p><app>gedit</app> includes features that help you find and replace text in your files. Using these features, you can search for text, highlight all occurrences of that text in the current document, and then (optionally) replace that text with other text.</p>
+  <title>Replace text</title>
 
-  <section>
-    <title>Find text</title>
-    <p>The Find tool can help you find where specific sequences of characters appear in your file.</p>
-    <steps>
-      <title>Finding text</title>
-      <item><p>Open the <gui style="menu">Find</gui> menu by clicking <guiseq><gui>Search</gui><gui>Find</gui></guiseq> or pressing <keyseq><key>Ctrl</key><key>F</key></keyseq>.</p></item>
-      <item><p>Type the text you wish to search for in the 'Search for' field. Note that <app>gedit</app> keeps a short history of searched-for items to the right of the 'Search for' field.</p></item>
-      <item><p>Click <gui>Find</gui> or press <keyseq><key>Alt</key><key>F</key></keyseq>.</p></item>
-    </steps>
-    <p>All occurrences of the text you searched for will be highlighted in the currently open file. <app>gedit</app> will scroll the file to display the currently selected text.</p>
-
-    <note>
-      <p>The text that you've searched for will remain highlighted by gedit, even after you've completed your search.  To remove the highlight, click <guiseq><gui>Search</gui><gui>Clear Highlight</gui></guiseq>, or just press <keyseq><key>Shift</key><key>Ctrl</key><key>K</key></keyseq>.</p>
-    </note>
+    <p>Editing text can be time consuming. To save time, <app>gedit</app> includes a <app>Replace</app> function that helps you to find and replace portions of text.</p>
 
-  </section>
-
-  <section>
-    <title>Replace text</title>
-    <p>Finding text is useful, but what if you also want to replace some of the text that you find with new text? That's what the Replace tool is for.</p>
     <steps>
+      <title>Replace text in <app>gedit</app></title>
       <item><p>Open the Replace tool by clicking <guiseq><gui>Search</gui><gui>Replace</gui></guiseq> or press <keyseq><key>Ctrl</key><key>H</key></keyseq>.</p></item>
-      <item><p>Type the <em>old</em> text you wish to replace into the 'Search for' field.</p></item>
-      <item><p>Fill in the 'Replace with' field with the <em>new</em> text you want to replace the <em>old</em> text.</p></item>
+      <item><p>Enter the text that you wish to replace into the 'Search for:' field.</p></item>
+      <item><p>Enter the new, replacement text into the 'Replace with:' field.</p></item>
       <item>
-        <p>Replace the text:</p>
+        <p>Once you have entered the original and replacement text, select your desired replacement options:</p>
         <list>
-          <item><p>To replace <em>only</em> the currently-selected section of text, click <gui>Replace</gui>.</p></item>
-          <item><p>To replace all occurrences of the searched-for text, click <gui>Replace All</gui>.</p></item>
+          <item><p>To replace <em>only</em> the next matching portion of text, click <gui>Replace</gui>.</p></item>
+          <item><p>To replace <em>all occurrences</em> of the searched-for text, click <gui>Replace All</gui>.</p></item>
         </list>
       </item>
     </steps>
@@ -57,30 +39,10 @@
     <note style="warning">
       <p>Use the <gui>Replace All</gui> function with care. <gui>Replace All</gui> works on the entirety of your text file, and does not allow you to highlight portions of text where the replace function will be performed.</p>
     </note>
-  </section>
 
   <section>
     <title>More options</title>
-    <p>The following section provides options that can help you search and replace more efficiently with <app>gedit</app></p>
-
-    <terms>
-      <item>
-        <title>Incremental Search</title>
-        <!-- Include headings with Key Combos? -->
-        <p>The Incremental Search feature searches the text of the current document instantly. Results are highlighted as you type them, rather than after you click a button.</p>
-        <p>To use Incremental Search, press <keyseq><key>Ctrl</key><key>K</key></keyseq>. A small input field will pop up. Type your search terms in this field. Results are highlighted and scrolled to in the currently open file. To navigate to the next occurrence of the item you searched for press the 'down arrow', or the 'up arrow' for the previous occurrence. To close the window, press <key>Enter</key> or <key>Escape</key>.</p>
-      </item>
-      <item>
-        <title>Find Next/Find Previous</title>
-        <p>The Find Next and Find Previous commands are used to step through search results after you've searched for text. They work after using the Find, Replace, and Incremental Search features and behave identically to using the up or down arrows in an Incremental Search.</p>
-        <p>The Find Next/Previous commands can be accessed by clicking the <gui>Search</gui> menu or pressing <keyseq><key>Ctrl</key><key>G</key></keyseq> for Find Next and <keyseq><key>Shift</key><key>Ctrl</key><key>G</key></keyseq> for Find Previous.</p>
-      </item>
-      <item>
-        <title>Clear Highlight</title>
-        <p>The Clear Highlight command is used to clear highlights left over after performing a text search. To use the command click <guiseq><gui>Search</gui><gui>Clear Highlight</gui></guiseq> or press <keyseq><key>Shift</key><key>Ctrl</key><key>K</key></keyseq>.</p>
-      </item>
-    </terms>
-
+    <p>The following section provides options that can help you replace text more efficiently with <app>gedit</app>.</p>
     <terms>
       <title>Find/Replace options</title>
       <item>
@@ -88,11 +50,11 @@
       </item>
       <item>
         <title>Match case</title>
-        <p>The 'Match case' option allows you to specify whether you want your search to be case-specific. If this option is selected, searches will be case-specific. If not, searches will not be case-specific.</p>
+        <p>The <em>Match case</em> option allows you to specify whether you want your search to be case-sensitive. If this option is selected, searches will be case-sensitive. If not, searches will not be case-sensitive.</p>
       </item>
       <item>
         <title>Match entire word only</title>
-        <p>Use this option to search for a specific word without including fragments of other words. For example, if you searched for the word 'and' with this option selected, only times when the individual word 'and' showed up in the file would appear. Other words such as 'b<em>and</em>' or comm<em>and</em> would not be included in the search results.</p>
+        <p>Use this option to search for a specific word without including fragments of other words. For example, if you searched for the word 'and' with this option selected, the word 'and' would be matched, but the words 's<em>and</em>' and 'comm<em>and</em>er' would not be matched.</p>
       </item>
       <item>
         <title>Search backwards</title>
@@ -100,7 +62,7 @@
       </item>
       <item>
         <title>Wrap around</title>
-        <p><!-- FIXME -->?</p>
+        <p>With the <app>wrap around</app> option enabled, <app>gedit</app> will re-start the search/replace action at the top of the file after it has reached the bottom of the file. This ensures that your search/replace action is made across your entire file.</p>
       </item>
     </terms>
   </section>
diff --git a/help/C/gedit-search.page b/help/C/gedit-search.page
new file mode 100644
index 0000000..bcf9ad9
--- /dev/null
+++ b/help/C/gedit-search.page
@@ -0,0 +1,37 @@
+<page xmlns="http://projectmallard.org/1.0/"; 
+  type="topic" style="task" 
+  id="gedit-search">
+
+  <info>
+    <link type="guide" xref="index#gedit-working-with-files" />
+    <link type="seealso" xref="gedit-replace" />
+    <revision pkgversion="program_version" version="document_version" date="2010-10-09" status="incomplete" />
+    <credit type="author">
+      <name>Jim Campbell</name>
+      <email>jwcampbell gmail com</email>
+    </credit>
+
+    <revision pkgversion="0.3" version="0.2" date="2010-12-16" status="draft" />
+    <credit type="author">
+      <name>Daniel Neel</name>
+      <email>dneelyep gmail com</email>
+    </credit>
+  </info>
+
+  <title>Search for text</title>
+    <p>The Find tool can help you find specific sequences of text within in your file.</p>
+    <steps>
+      <title>Finding text</title>
+      <item><p>Open the <gui style="menu">search window</gui> by clicking <guiseq><gui>Search</gui><gui>Find</gui></guiseq> or pressing <keyseq><key>Ctrl</key><key>F</key></keyseq>. This will move your cursor to the start of the <gui>search window</gui>.</p></item>
+      <item><p>Type the text you wish to search for in the <gui>search window</gui>.</p></item>
+      <item><p>As you type, <app>gedit</app> will begin highlighting the portions of text that match what you have entered.</p></item>
+      <item><p>Use the <gui>up</gui> or <gui>down</gui> facing arrows next to the <gui>search window</gui> (or <keyseq><key>Ctrl</key><key>G</key></keyseq> or <keyseq><key>Ctrl</key><key>Shift</key><key>G</key></keyseq>) to scroll up or down through the highlighted text.</p></item>
+    </steps>
+
+  <p>To close the <gui>search window</gui>, press <key>Esc</key>.</p>
+
+    <note>
+      <p>The text that you've searched for will remain highlighted by gedit, even after you have completed your search.  To remove the highlight, click <guiseq><gui>Search</gui><gui>Clear Highlight</gui></guiseq>, or press <keyseq><key>Shift</key><key>Ctrl</key><key>K</key></keyseq>.</p>
+    </note>
+
+</page>