<page xmlns="http://projectmallard.org/1.0/" 
  type="topic" style="task" 
  id="gedit-replace">

  <info>
    <link type="guide" xref="index#gedit-working-with-files" />
    <link type="seealso" xref="gedit-search" />
    <revision pkgversion="3.0" version="1.0" date="2011-03-25" status="final"/>
    <credit type="author">
      <name>Jim Campbell</name>
      <email>jwcampbell@gmail.com</email>
    </credit>

    <credit type="author">
      <name>Daniel Neel</name>
      <email>dneelyep@gmail.com</email>
    </credit>
  </info>

  <title>Replace text</title>

    <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>

    <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>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>Once you have entered the original and replacement text, select your desired replacement options:</p>
        <list>
          <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>

    <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 id="replace-options">
    <title>More options</title>
    <terms>
      <item>
        <title>Match case</title>
        <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, 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>
        <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>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>
</page>
