<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" />
    <desc>Replace portions of text in a file.</desc>
    <revision pkgversion="3.8" date="2013-02-24" status="review"/>
    <revision pkgversion="3.10" date="2013-11-05" status="candidate"/>
    <revision pkgversion="3.14" date="2014-11-28" status="review"/>
    <revision pkgversion="3.24" date="2017-09-17" status="review"/>
    <credit type="author">
      <name>Jim Campbell</name>
      <email>jcampbell@gnome.org</email>
    </credit>
    <credit type="author">
      <name>Daniel Neel</name>
      <email>dneelyep@gmail.com</email>
    </credit>
    <credit type="editor">
      <name>Sindhu S</name>
      <email>sindhus@live.in</email>
    </credit>
    <credit type="editor">
      <name>Ekaterina Gerasimova</name>
      <email>kittykat3756@gmail.com</email>
    </credit>
    <credit type="editor">
      <name>Shobha Tyagi</name>
      <email>tyagishobha@gmail.com</email>
    </credit>
    <credit type="editor">
      <name>Young Li</name>
      <email>li.young1618@gmail.com</email>
    </credit>
    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>
  </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 <gui>Replace</gui> tool by clicking
      <guiseq><gui style="button">Menu button</gui><gui style="menuitem">Find 
      and 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 <gui>Find</gui>
      field.</p>
    </item>
    <item>
      <p>Enter the new, replacement text into the <gui>Replace with</gui>
      field.</p>
    </item>
    <item>
      <p>Once you have entered the original and replacement text, you can add
      extra parameters to the search. You can also choose what you want to
      replace:</p>
      <list>
        <item>
          <p>To replace <em>only</em> the next match, 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>

  <p>If you wish, you can add some extra parameters to your search:</p>

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

<section id="escape-sequences">
  <title>Using escape sequences</title>

  <p>You can use <em>escape sequences</em> to search for line breaks, carriage
  returns, and tabs.</p>

  <terms>
    <item>
      <title>\n</title>
      <p>Newline</p>
    </item>
    <item>
      <title>\r</title>
      <p>Carriage return</p>
    </item>
    <item>
      <title>\t</title>
      <p>Tab</p>
    </item>
  </terms>

  <p>If you actually want to search for a <output>\</output> (backslash) or one
  of the escape sequences in the text, you need to escape the backslash with an
  extra backslash. For example, to search for <input>\</input>, you need to
  enter <input>\\</input> into the search or replace field. You can search for
  escape sequences in the same way: to search for or replace with a
  <input>\n</input>, use the <input>\\n</input> term.</p>

</section>

</page>
