[gedit] First draft of 'Find and Replace text' file

[Ignacio Casal Quinteiro <icq src gnome org>]

commit 3c024b7cd0ad5b08f1d503d6fceb701dc4dd3bc8
Author: Daniel Neel <dneelyep gmail com>
Date:   Thu Dec 16 20:29:19 2010 -0500

    First draft of 'Find and Replace text' file
    
    Made a first draft of this file, with information about finding text
    and replacing text. Also described extra commands at the bottom of the
    document for people looking for more in-depth information. Might be best
    to split into a couple different files?

 help/C/gedit-replace.page |   95 ++++++++++++++++++++++++++++++++++++++++++---
 1 files changed, 89 insertions(+), 6 deletions(-)
---
diff --git a/help/C/gedit-replace.page b/help/C/gedit-replace.page
index f1ebc71..2f2cafc 100644
--- a/help/C/gedit-replace.page
+++ b/help/C/gedit-replace.page
@@ -3,16 +3,99 @@
   id="gedit-replace">
   <info>
     <link type="guide" xref="index#gedit-working-with-files" />
-    <link type="seealso" xref="gedit-search-find"/>
+    <link type="seealso" xref="gedit-search-find" />
     <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>*Replace text within your files</title>
-  <p>gedit includes features that help you search and find portions of your text.</p>
-  <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>
+  <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>
+
+  <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>
+
+  </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>
+      <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>Replace the text:</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>
+          </list>
+      </item>
+    </steps>
+
+    <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>
+
+    <terms>
+      <title>Find/Replace options</title>
+      <item>
+        <p>These options are located in the Find and Replace menus, accessible at <guiseq><gui>Search</gui><gui>Find</gui></guiseq> or <guiseq><gui>Search</gui><gui>Replace</gui></guiseq>.</p>
+      </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>
+      </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>
+      </item>
+      <item>
+        <title>Search backwards</title>
+        <p>This command behaves identically to the Find Previous command. If you wish to step through search results from end to beginning, select this option.</p>
+      </item>
+      <item>
+        <title>Wrap around</title>
+        <p><!-- FIXME -->?</p>
+      </item>
+    </terms>
+  </section>
 </page>