/jEdit/tags/jedit-4-5-pre1/doc/users-guide/text-edit.xml

<?xml version="1.0" encoding="UTF-8"?>
<chapter id="editing">
    <title>Editing Text</title>
    <!-- jEdit buffer-local properties:
         :tabSize=1:indentSize=1:noTabs=true:wrap=soft:maxLineLen=80:
         :xml.root=users-guide.xml: -->

    <section id="caret">
        <title>Moving The Caret</title>

        <para>The simplest way to move the caret is to click the mouse at the
        desired location in the text area. The caret can also be moved using the
        keyboard.</para>

        <para>The <keycap>LEFT</keycap>, <keycap>RIGHT</keycap>,
        <keycap>UP</keycap> and <keycap>DOWN</keycap> keys move the caret in the
        respective direction, and the <keycap>PAGE_UP</keycap> and
        <keycap>PAGE_DOWN</keycap> keys move the caret up and down one
        screen-full, respectively.</para>

        <para>When pressed once, the <keycap>HOME</keycap> key moves the caret
        to the first non-whitespace character of the current screen line.
        Pressing it a second time moves the caret to the beginning of the
        current buffer line. Pressing it a third time moves the caret to the
        first visible line.</para>

        <para>The <keycap>END</keycap> key behaves in a similar manner, going to
        the last non-whitespace character of the current screen line, the end of
        the current buffer line, and finally to the last visible line.</para>

        <para>If soft wrap is disabled, a <quote>screen line</quote> is the same
        as a <quote>buffer line</quote>. If soft wrap is enabled, a screen line
        is a section of a newline-delimited buffer line that fits within the
        wrap margin width. See <xref linkend="word-wrap" />.</para>

        <para><keycap>C+HOME</keycap> and <keycap>C+END</keycap> move the caret
        to the beginning and end of the buffer, respectively.</para>

        <para>More advanced caret movement is covered in <xref
        linkend="words" />, <xref linkend="lines" /> and <xref
        linkend="paragraphs" />.</para>

        <sidebar>
            <title>The Home and End keys</title>

            <para>If you prefer more traditional behavior for the
            <keycap>HOME</keycap> and <keycap>END</keycap> keys, you can
            reassign the respective keyboard shortcuts in the
            <guibutton>Shortcuts</guibutton> pane of the
            <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
            Options</guimenuitem>; see <xref linkend="shortcuts-pane" />.</para>

            <para>By default, the shortcuts are assigned as follows:</para>

            <itemizedlist>
                <listitem>
                    <para><keycap>HOME</keycap> is bound to <guimenuitem>Smart
                    Home</guimenuitem>.</para>
                </listitem>

                <listitem>
                    <para><keycap>END</keycap> is bound to <guimenuitem>Smart
                    End</guimenuitem>.</para>
                </listitem>

                <listitem>
                    <para><keycap>S+HOME</keycap> is bound to
                    <guimenuitem>Select to Smart Home
                    Position</guimenuitem>.</para>
                </listitem>

                <listitem>
                    <para><keycap>S+END</keycap> is bound to <guimenuitem>Select
                    to Smart End Position</guimenuitem>.</para>
                </listitem>
            </itemizedlist>

            <para>However you can rebind them to anything you want, for example,
            various combinations of the following, or indeed any other command
            or macro:</para>

            <itemizedlist>
                <listitem>
                    <para><guimenuitem>Go to Start/End of White
                    Space</guimenuitem>.</para>
                </listitem>

                <listitem>
                    <para><guimenuitem>Go to Start/End of
                    Line</guimenuitem>.</para>
                </listitem>

                <listitem>
                    <para><guimenuitem>Go to Start/End of
                    Buffer</guimenuitem>.</para>
                </listitem>

                <listitem>
                    <para><guimenuitem>Select to Start/End of White Space
                    </guimenuitem>.</para>
                </listitem>

                <listitem>
                    <para><guimenuitem>Select to Start/End of
                    Line</guimenuitem>.</para>
                </listitem>

                <listitem>
                    <para><guimenuitem>Select to Start/End of
                    Buffer</guimenuitem>.</para>
                </listitem>
            </itemizedlist>
        </sidebar>
    </section>

    <section id="selection">
        <title>Selecting Text</title>

        <para>A <firstterm>selection</firstterm> is a block of text marked for
        further manipulation. Range selections are equivalent to selections in
        most other text editors; they cover text between two points in a buffer.
        In addition to the standard text-selection mode, jEdit also allows
        <emphasis role="bold">rectangular selections</emphasis> that cover a
        rectangular area (some text editors refer to these as <quote>column
        selections</quote>). Furthermore, several chunks of text can be selected
        and operated on simultaneously.</para>

        <section>
            <title>Range Selection</title>

            <para>Dragging the mouse creates a range selection from where the
            mouse was pressed to where it was released. Holding down
            <keycap>Shift</keycap> while clicking a location in the buffer will
            create a selection from the caret position to the clicked
            location.</para>

            <para>Holding down <keycap>Shift</keycap> in addition to a caret
            movement key (<keycap>LEFT</keycap>, <keycap>UP</keycap>,
            <keycap>HOME</keycap>, etc) will extend a selection in the specified
            direction.</para>

            <para><guimenu>Edit</guimenu>&gt;<guimenuitem>Select
            All</guimenuitem> (shortcut: <keycap>C+a</keycap>) selects the
            entire buffer.</para>

            <para><guimenu>Edit</guimenu>&gt;<guisubmenu>More
            Selection</guisubmenu>&gt;<guimenuitem>Select None</guimenuitem>
            (shortcut: <keycap>ESCAPE</keycap>) deactivates the
            selection.</para>
        </section>

        <section id="rect-select">
            <title>Rectangular Selection</title>

            <para>Dragging with the <keycap>Control</keycap> key held down will
            create a rectangular selection. Holding down <keycap>Shift</keycap>
            and <keycap>Control</keycap> while clicking a location in the buffer
            will create a rectangular selection from the caret position to the
            clicked location.</para>

            <para>Alternatively, invoking
            <guimenu>Edit</guimenu>&gt;<guisubmenu>More
            Selection</guisubmenu>&gt;<guimenuitem>Rectangular
            Selection</guimenuitem> (shortcut: <keycap>A+\</keycap>) toggles
            rectangular selection mode. In rectangular selection mode, dragging
            the mouse always creates a rectangular selection, and keyboard
            commands that would normally create a range selection create a
            rectangular selection instead. A status bar indicator is shown when
            this mode is enabled.</para>

            <para>It is possible to select a rectangle with zero width but
            non-zero height. This can be used to insert a new column between two
            existing columns, for example. Such zero-width selections are shown
            as a thin vertical line.</para>

            <para>Inserting text into a rectangular selection repeats the text
            going down as many times as necessary, and shifts the selection to
            the right. This makes it behave like a <quote>tall</quote>
            caret.</para>

            <para>Rectangles can be deleted, copied, pasted, and operated on
            using ordinary editing commands. If necessary, rectangular
            selections are automatically filled in with whitespace to maintain
            alignment.</para>

            <para>Rectangular selections can extend beyond the end of a line
            into <quote>virtual space</quote>. Furthermore, if keyboard
            rectangular selection mode is on or if the <keycap>Control</keycap>
            key is being held down, clicking beyond the end of a line will
            insert the appropriate amount of whitespace in order to position the
            cursor at the clicked location.</para>

            <note>
                <para>Rectangular selections are implemented using character
                offsets, not absolute screen positions, so they might not behave
                as you might expect if a proportional-width font is being used
                or if soft wrap is enabled. The text area font can be changed in
                the <guibutton>Text Area</guibutton> pane of the
                <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
                Options</guimenuitem> dialog box. For information about soft
                wrap, see <xref linkend="word-wrap" />.</para>
            </note>
        </section>

        <section id="multi-select">
            <title>Multiple Selection</title>

            <para><guimenu>Edit</guimenu>&gt;<guisubmenu>More
            Selection</guisubmenu>&gt;<guimenuitem>Multiple
            Selection</guimenuitem> (keyboard shortcut: <keycap>C+\</keycap>)
            turns multiple selection mode on and off. In multiple selection
            mode, multiple fragments of text can be selected and operated on
            simultaneously, and the caret can be moved independently of the
            selection. The status bar indicates if multiple selection mode is
            active; see <xref linkend="status-bar" />.</para>

            <para>Various jEdit commands behave differently with multiple
            selections:</para>

            <itemizedlist>
                <listitem>
                    <para>Commands that copy text place the contents of each
                    selection, separated by line breaks, in the specified
                    register.</para>
                </listitem>

                <listitem>
                    <para>Commands that insert (or paste) text replace each
                    selection with the entire text that is being
                    inserted.</para>
                </listitem>

                <listitem>
                    <para>Commands that filter text (such as <guimenuitem>Spaces
                    to Tabs</guimenuitem>, <guimenuitem>Range
                    Comment</guimenuitem>, <guimenuitem>Replace in
                    Selection</guimenuitem>, and so on) behave as if each block
                    was selected independently, and the command invoked on each
                    in turn.</para>
                </listitem>

                <listitem>
                    <para>Line-based commands (such as <guimenuitem>Shift Indent
                    Left</guimenuitem>, <guimenuitem>Shift Indent
                    Right</guimenuitem>, and <guimenuitem>Line
                    Comment</guimenuitem>) operate on each line that contains at
                    least one selection.</para>
                </listitem>

                <listitem>
                    <para>Caret movement commands that would normally deactivate
                    the selection (such as the arrow keys, while
                    <keycap>Shift</keycap> is not being held down), move the
                    caret, leaving the selection as-is.</para>
                </listitem>

                <listitem>
                    <para>Some older plugins may not support multiple selection
                    at all.</para>
                </listitem>
            </itemizedlist>

            <para><guimenu>Edit</guimenu>&gt;<guisubmenu>More
            Selection</guisubmenu>&gt;<guimenuitem>Select None</guimenuitem>
            (shortcut: <keycap>ESCAPE</keycap>) deactivates the selection
            containing the caret, if there is one. Otherwise it deactivates all
            active selections.</para>

            <para><guimenu>Edit</guimenu>&gt;<guisubmenu>More
            Selection</guisubmenu>&gt;<guimenuitem>Invert
            Selection</guimenuitem> (shortcut: <keycap>C+e C+i</keycap>) selects
            a set of text chunks such that all text that was formerly part of a
            selection is now unselected, and all text that wasn't, is
            selected.</para>

            <note>
                <para>Deactivating multiple selection mode while multiple blocks
                of text are selected will leave the selections in place, but you
                will not be able to add new selections until multiple selection
                mode is reactivated.</para>
            </note>
        </section>
    </section>

    <section id="entering-text">
        <title>Inserting and Deleting Text</title>

        <para>Text entered at the keyboard is inserted into the buffer. In
        overwrite mode, which can be toggled by pressing
        <keycap>INSERT</keycap>, one character is deleted from in front of the
        caret position for every character that is inserted. The caret is drawn
        as a horizontal line while overwrite mode is active. The status bar also
        indicates if overwrite mode is active; see <xref linkend="status-bar" />
        for details.</para>

        <para>Inserting text while there is a selection will replace the
        selection with the inserted text.</para>

        <para>When inserting text, the <keycap>TAB</keycap> and
        <keycap>ENTER</keycap> keys might not behave entirely like you expect
        because of various indentation features; see <xref linkend="indent" />
        for details.</para>

        <para>The simplest way to delete text is with the
        <keycap>BACKSPACE</keycap> and <keycap>DELETE</keycap> keys. If nothing
        is selected, they delete the character before or after the caret,
        respectively. If a selection exists, both delete the selection.</para>

        <para>More advanced deletion commands are described in <xref
        linkend="words" />, <xref linkend="lines" /> and <xref
        linkend="paragraphs" />.</para>
    </section>

    <section id="undo-redo">
        <title>Undo and Redo</title>

        <para><guimenu>Edit</guimenu>&gt;<guimenuitem>Undo</guimenuitem>
        (shortcut: <keycap>C+z</keycap>) reverses the most recent editing
        command. For example, this can be used to restore unintentionally
        deleted text. More complicated operations, such as a search and replace,
        can also be undone.</para>

        <para>If you undo too many changes,
        <guimenu>Edit</guimenu>&gt;<guimenuitem>Redo</guimenuitem> (shortcut:
        <keycap>C+e C+z</keycap>) can restore the changes again. For example, if
        some text was inserted, <guimenuitem>Undo</guimenuitem> will remove it
        from the buffer. <guimenuitem>Redo</guimenuitem> will insert it
        again.</para>

        <para>By default, the last 100 edits is retained; older edits cannot be
        undone. The maximum number of undos and whether undos are reset when a
        buffer is saved can be changed in the <guibutton>Editing</guibutton>
        pane of the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
        Options</guimenuitem> dialog box; see <xref
        linkend="editing-pane" />.</para>
    </section>

    <section id="words">
        <title>Working With Words</title>

        <para><keycap>C+LEFT</keycap> and <keycap>C+RIGHT</keycap> move the
        caret a word at a time. Holding down <keycap>Shift</keycap> in addition
        to the above extends the selection a word at a time.</para>

        <para>A single word can be selected by double-clicking with the mouse,
        or using the <guimenu>Edit</guimenu>&gt;<guisubmenu>More
        Selection</guisubmenu>&gt;<guimenuitem>Select Word</guimenuitem> command
        (shortcut: <keycap>C+e w</keycap>). A selection that begins and ends on
        word boundaries can be created by double-clicking and dragging.</para>

        <para><keycap>C+BACKSPACE</keycap> and <keycap>C+DELETE</keycap> delete
        the word before or after the caret, respectively.</para>

        <para><guimenu>Edit</guimenu>&gt;<guimenuitem>Complete
        Word</guimenuitem> (shortcut: <keycap>C+b</keycap>) locates possible
        completions for the word at the caret, first by looking in the current
        edit mode's syntax highlighting keyword list, and then in the current
        buffer for words that begin with the word at the caret. This serves as a
        very basic code completion feature.</para>

        <para>If there is only one completion, it will be inserted into the
        buffer immediately.</para>

        <para>If multiple completions were found, the longest common prefix is
        inserted into the buffer, and a popup is shown below the caret position
        listing the completions.</para>

        <para>To insert a completion from the list, either select it using the
        <keycap>UP</keycap> and <keycap>DOWN</keycap> keys and press
        <keycap>ENTER</keycap>, press a digit to insert one of the first ten
        completions (1 is the first completion; 9 is the 9th; 0 is the 10th), or
        click the desired completion with the mouse. To close the popup without
        inserting a completion, press <keycap>ESCAPE</keycap>.</para>

        <para>Typing while the popup is visible will automatically update the
        popup and narrow the set of completions as necessary.</para>

        <para>The default word completion uses the visible buffers (buffers
        being shown in an EditPane) to find completions. The set of possible
        words can be expanded by enabling the <guimenuitem>Global Options - Text
        Area - Complete words from all open buffers</guimenuitem> option.
        Setting this option will use all open buffers to search for possible
        completions. Note, this can degrade completion performance if many
        buffers are open.</para>

        <para><guimenu>Edit</guimenu>&gt;<guimenuitem>Word Count</guimenuitem>
        displays a dialog box with the number of characters, words and lines in
        the current buffer.</para>

        <section>
            <title>What's a Word?</title>

            <para>The default behavior of the <keycap>C+LEFT</keycap>,
            <keycap>C+RIGHT</keycap>, <keycap>C+BACKSPACE</keycap> and
            <keycap>C+DELETE</keycap> commands is to stop both at the beginning
            and the end of each word. Normally, a word is a sequence of
            alphanumerics, but you can add other characters as part of
            what jEdit considers to be a 'word', set on a global or mode basis
            from <guimenuitem>Global Options -  Editing - Extra Word
            Characters</guimenuitem>.
            In addition, this behavior can be changed by remapping
            these keystrokes to alternative actions whose names end with
            <guimenuitem>(Eat Whitespace)</guimenuitem> in the
            <guibutton>Shortcuts</guibutton> pane of the
            <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
            Options</guimenuitem> dialog box; see <xref
            linkend="shortcuts-pane" />.</para>
        </section>
    </section>

    <section id="lines">
        <title>Working With Lines</title>

        <para>An entire line can be selected by triple-clicking with the mouse,
        or using the <guimenu>Edit</guimenu>&gt;<guisubmenu>More
        Selection</guisubmenu>&gt;<guimenuitem>Select Line</guimenuitem> command
        (shortcut: <keycap>C+e l</keycap>). A selection that begins and ends on
        line boundaries can be created by triple-clicking and dragging.</para>

        <para><guimenu>Edit</guimenu>&gt;<guimenuitem>Go to Line</guimenuitem>
        (shortcut: <keycap>C+l</keycap>) prompts for a line number and moves the
        caret there.</para>

        <para><guimenu>Edit</guimenu>&gt;<guisubmenu>More
        Selection</guisubmenu>&gt;<guimenuitem>Select Line Range</guimenuitem>
        (shortcut: <keycap>C+e C+l</keycap>) prompts for two line numbers and
        selects all text between them.</para>

        <para><guimenu>Edit</guimenu>&gt;<guisubmenu>Text</guisubmenu>&gt;<guimenuitem>Delete
        Line</guimenuitem> (shortcut: <keycap>C+d</keycap>) deletes the current
        line.</para>

        <para><guimenu>Edit</guimenu>&gt;<guisubmenu>Text</guisubmenu>&gt;<guimenuitem>Delete
        to Start Of Line</guimenuitem> (shortcut:
        <keycap>CS+BACK_SPACE</keycap>) deletes all text from the start of the
        current line to the caret.</para>

        <para><guimenu>Edit</guimenu>&gt;<guisubmenu>Text</guisubmenu>&gt;<guimenuitem>Delete
        to End Of Line</guimenuitem> (shortcut: <keycap>CS+DELETE</keycap>)
        deletes all text from the caret to the end of the current line.</para>

        <para><guimenu>Edit</guimenu>&gt;<guisubmenu>Text</guisubmenu>&gt;<guimenuitem>Join
        Lines</guimenuitem> (shortcut: <keycap>C+j</keycap>) removes any
        whitespace from the start of the next line and joins it with the current
        line. The caret is moved to the position where the two lines were
        joined. For example, if you invoke <guimenuitem>Join Lines</guimenuitem>
        with the caret on the first line of the following Java code:</para>

        <screen>new Widget(Foo
       .createDefaultFoo());</screen>

        <para>It will be changed to:</para>

        <screen>new Widget(Foo.createDefaultFoo());</screen>
    </section>

    <section id="paragraphs">
        <title>Working With Paragraphs</title>

        <para>As far as jEdit is concerned, <quote>paragraphs</quote> are
        delimited by double newlines. This is also how
        <application>TeX</application> defines a paragraph. Note that jEdit
        doesn't parse HTML files for <quote>&lt;P&gt;</quote> tags, nor does it
        support paragraphs delimited only by a leading indent.</para>

        <para><keycap>C+UP</keycap> and <keycap>C+DOWN</keycap> move the caret
        to the previous and next paragraph, respectively. Holding down
        <keycap>Shift</keycap> in addition to the above extends the selection a
        paragraph at a time.</para>

        <para><guimenu>Edit</guimenu>&gt;<guisubmenu>More
        Selection</guisubmenu>&gt;<guimenuitem>Select Paragraph</guimenuitem>
        (shortcut: <keycap>C+e p</keycap>) selects the paragraph containing the
        caret.</para>

        <para><guimenu>Edit</guimenu>&gt;<guisubmenu>Text</guisubmenu>&gt;<guimenuitem>Format
        Paragraph</guimenuitem> (shortcut: <keycap>C+e f</keycap>) splits and
        joins lines in the current selection to make it fit within the wrap
        column position. If nothing is selected, the paragraph containing the
        caret is formatted instead. See <xref linkend="word-wrap" /> for
        information about word wrap and changing the wrap column.</para>

        <para><guimenu>Edit</guimenu>&gt;<guisubmenu>Text</guisubmenu>&gt;<guimenuitem>Delete
        Paragraph</guimenuitem> (shortcut: <keycap>C+e d</keycap>) deletes the
        paragraph containing the caret.</para>
    </section>

    <section id="word-wrap">
        <title>Wrapping Long Lines</title>

        <para>The <firstterm>word wrap</firstterm> feature splits lines at word
        boundaries in order to fit text within a specified wrap margin. A word
        boundary, for the purposes of word wrap, means whitespace. Long lines
        without whitespace are currently not wrapped by jEdit. The wrap margin
        position is indicated in the text are as a faint blue vertical line.
        There are two <quote>wrap modes</quote>, <quote>soft</quote> and
        <quote>hard</quote>; they are described below. The current wrap mode is
        shown in the status bar; see <xref linkend="status-bar" />. The wrap
        mode can be changed in one of the following ways:</para>

        <itemizedlist>
            <listitem>
                <para>On a global or mode-specific basis in the
                <guibutton>Editing</guibutton> pane of the
                <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
                Options</guimenuitem> dialog box. See <xref
                linkend="editing-pane" />.</para>
            </listitem>

            <listitem>
                <para>In the current buffer for the duration of the editing
                session,</para>

                <itemizedlist>
                    <listitem>
                        <para>By clicking the status bar indicator.</para>
                    </listitem>

                    <listitem>
                        <para>In the
                        <guimenu>Utilities</guimenu>&gt;<guimenuitem>Buffer
                        Options</guimenuitem> dialog box. See <xref
                        linkend="buffer-opts" />.</para>
                    </listitem>

                    <listitem>
                        <para>From the keyboard, if a keyboard shortcut has been
                        assigned to the <guimenuitem>Toggle Word
                        Wrap</guimenuitem> command in the
                        <guibutton>Shortcuts</guibutton> pane of the
                        <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
                        Options</guimenuitem> dialog box. By default, this
                        command does not have a keyboard shortcut.</para>
                    </listitem>
                </itemizedlist>
            </listitem>

            <listitem>
                <para>In the current buffer for future editing sessions by
                placing the following in one of the first or last 10 lines of
                the buffer, where <replaceable>mode</replaceable> is either
                <quote>none</quote>, <quote>soft</quote> or <quote>hard</quote>,
                and <replaceable>column</replaceable> is the desired wrap
                margin:</para>

                <screen>:wrap=<replaceable>mode</replaceable>:maxLineLen=<replaceable>column</replaceable>:</screen>
            </listitem>
        </itemizedlist>

        <section>
            <title>Soft Wrap</title>

            <para>In soft wrap mode, lines are automatically wrapped when
            displayed on screen. Newlines are not inserted at the wrap
            positions, and the wrapping is automatically updated when text is
            inserted or removed.</para>

            <para>If the margin is set to 0, then the width of the text area
            window is used to determine where to wrap lines.</para>

            <para>If end of line markers are enabled in the <guibutton>Text
            Area</guibutton> pane of the
            <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
            Options</guimenuitem> dialog box, a colon (<quote>:</quote>) is
            painted at the end of wrapped lines. See <xref
            linkend="text-area-pane" />.</para>
        </section>

        <section>
            <title>Hard Wrap</title>

            <para>In hard wrap mode, inserting text at the end of a line will
            automatically break the line if it extends beyond the wrap margin.
            Inserting or removing text in the middle of a line has no effect,
            however text can be re-wrapped using the
            <guimenu>Edit</guimenu>&gt;<guisubmenu>Text</guisubmenu>&gt;<guimenuitem>Format
            Paragraph</guimenuitem> command. See <xref
            linkend="paragraphs" />.</para>

            <para>Hard wrap is implemented using character offsets, not screen
            positions, so it might not behave like you expect if a
            proportional-width font is being used. The text area font can be
            changed in the <guibutton>Text Area</guibutton> pane of the
            <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
            Options</guimenuitem> dialog box.</para>
        </section>
    </section>

    <section id="scrolling">
        <title>Scrolling</title>

        <para>If you have a mouse with a scroll wheel, you can use the wheel to
        scroll up and down in the text area. Various modifier keys change the
        action of the wheel:</para>

        <itemizedlist>
            <listitem>
                <para><keycap>Shift</keycap> - moves the horizontal scrollbar.
                time.</para>
            </listitem>

            <listitem>
                <para><keycap>Control</keycap> - scrolls a single line at a
                time.</para>
            </listitem>

            <listitem>
                <para><keycap>Alt</keycap> - moves the caret up and down instead
                of scrolling.</para>
            </listitem>

             <listitem>
                <para><keycap>CTRL+SHIFT</keycap> - scroll a page at a time. </para>
            </listitem>


            <listitem>
                <para><keycombo>
                        <keycap>Alt</keycap>

                        <keycap>Shift</keycap>
                    </keycombo> - extends the selection up and down instead of
                scrolling.</para>
            </listitem>
        </itemizedlist>

        <para>Keyboard commands for scrolling the text area are also
        available.</para>

        <para><guimenu>View</guimenu>&gt;<guisubmenu>Scrolling</guisubmenu>&gt;<guimenuitem>Scroll
        to Current Line</guimenuitem> (shortcut: <keycap>C+e C+j</keycap>)
        scrolls the text area in order to make the caret visible, if necessary.
        It does nothing if the caret is already visible.</para>

        <para><guimenu>View</guimenu>&gt;<guisubmenu>Scrolling</guisubmenu>&gt;<guimenuitem>Center
        Caret on Screen</guimenuitem> (shortcut: <keycap>C+e C+n</keycap>) moves
        the caret to the line in the middle of the screen.</para>

        <para><guimenu>View</guimenu>&gt;<guisubmenu>Scrolling</guisubmenu>&gt;<guimenuitem>Line
        Scroll Up</guimenuitem> (shortcut: <keycap>C+QUOTE</keycap>) scrolls the
        text area up by one line.</para>

        <para><guimenu>View</guimenu>&gt;<guisubmenu>Scrolling</guisubmenu>&gt;<guimenuitem>Line
        Scroll Down</guimenuitem> (shortcut: <keycap>C+SLASH</keycap>) scrolls
        the text area down by one line.</para>

        <para><guimenu>View</guimenu>&gt;<guisubmenu>Scrolling</guisubmenu>&gt;<guimenuitem>Page
        Scroll Up</guimenuitem> (shortcut: <keycap>A+QUOTE</keycap>) scrolls the
        text area up by one screenful.</para>

        <para><guimenu>View</guimenu>&gt;<guisubmenu>Scrolling</guisubmenu>&gt;<guimenuitem>Page
        Scroll Down</guimenuitem> (shortcut: <keycap>A+SLASH</keycap>) scrolls
        the text area down by one screenful.</para>

        <para>The above scrolling commands differ from the caret movement
        commands in that they don't actually move the caret; they just change
        the scroll bar position.</para>
    </section>

    <section id="text-transfer">
        <title>Transferring Text</title>

        <para>jEdit provides a rich set of commands for moving and copying text.
        Commands are provided for moving chunks of text from buffers to
        <firstterm>registers</firstterm> and vice-versa. A register is a holding
        area for an arbitrary length of text, with a single-character name. Most
        other programs can only transfer text to and from the system clipboard;
        in jEdit, the system clipboard is just another register, with the
        special name <filename>$</filename>.</para>

        <section>
            <title>The Clipboard</title>

            <para>jEdit offers the usual text transfer operations, that operate
            on the <filename>$</filename> register.</para>

            <para><guimenu>Edit</guimenu>&gt;<guimenuitem>Cut</guimenuitem>
            (shortcut: <keycap>C+x</keycap>) places the selected text in the
            clipboard and removes it from the buffer.</para>

            <para><guimenu>Edit</guimenu>&gt;<guimenuitem>Copy</guimenuitem>
            (shortcut: <keycap>C+c</keycap>) places the selected text in the
            clipboard and leaves it in the buffer.</para>

            <para><guimenu>Edit</guimenu>&gt;<guimenuitem>Paste</guimenuitem>
            (shortcut: <keycap>C+v</keycap>) inserts the clipboard contents in
            place of the selection (or at the caret position, if there is no
            selection).</para>

            <para>The <guimenuitem>Cut</guimenuitem> and
            <guimenuitem>Copy</guimenuitem> commands replace the old clipboard
            contents with the selected text. There are two alternative commands
            which add the selection at the end of the existing clipboard
            contents, instead of replacing it.</para>

            <para><guimenu>Edit</guimenu>&gt;<guisubmenu>More
            Clipboard</guisubmenu>&gt;<guimenuitem>Cut Append</guimenuitem>
            (shortcut: <keycap>C+e C+u</keycap>) appends the selected text to
            the clipboard, then removes it from the buffer. After this command
            has been invoked, the clipboard will consist of the former clipboard
            contents, followed by a newline, followed by the selected
            text.</para>

            <para><guimenu>Edit</guimenu>&gt;<guisubmenu>More
            Clipboard</guisubmenu>&gt;<guimenuitem>Copy Append</guimenuitem>
            (shortcut: <keycap>C+e C+a</keycap>) is the same as <guimenuitem>Cut
            Append</guimenuitem> except it does not remove the selection from
            the buffer.</para>
        </section>

        <section id="quick-copy">
            <title>Quick Copy</title>

            <para>The quick copy feature is usually found in Unix text editors.
            Quick copy is disabled by default, but it can be enabled in the
            <guibutton>Mouse</guibutton> pane of the
            <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
            Options</guimenuitem> dialog box.</para>

            <para>The quick copy feature is accessed using the middle mouse
            button. If you do not have a three-button mouse, then either
            <keycap>Alt</keycap>-click (on Windows and Unix) or
            <keycap>Option</keycap>-click (on MacOS X). The quick copy feature
            enables the following behavior:</para>

            <itemizedlist>
                <listitem>
                    <para>Clicking the middle mouse button in the text area
                    inserts the most recently selected text at the clicked
                    location. If you only have a two-button mouse, you can click
                    the left mouse button while holding down
                    <keycap>Alt</keycap> instead of middle-clicking.</para>
                </listitem>

                <listitem>
                    <para>Dragging with the middle mouse button creates a
                    selection without moving the caret. As soon as the mouse
                    button is released, the selected text is inserted at the
                    caret position and the selection is deactivated. A message
                    is shown in the status bar while text is being selected to
                    remind you that this is not an ordinary selection.</para>
                </listitem>

                <listitem>
                    <para>Holding down <keycap>Shift</keycap> while clicking the
                    middle mouse button will duplicate text between the caret
                    and the clicked location.</para>
                </listitem>

                <listitem>
                    <para>Holding down <keycap>Control</keycap> while clicking
                    the middle mouse button on a bracket will insert all text in
                    that bracket's scope at the caret position.</para>
                </listitem>
            </itemizedlist>

            <para>The most recently selected text is stored in the
            <filename>%</filename> register.</para>

            <para>If jEdit is being run under Java 2 version 1.4 on Unix, you
            will be able to transfer text with other X Windows applications
            using the quick copy feature. On other platforms and Java versions,
            the contents of the quick copy register are only accessible from
            within jEdit.</para>
        </section>

        <section id="registers">
            <title>General Register Commands</title>

            <para>These commands require more keystrokes than the two methods
            shown above, but they can operate on any register, allowing an
            arbitrary number of text chunks to be retained at a time.</para>

            <para>Each command prompts for a single-character register name to
            be entered after being invoked. Pressing <keycap>ESCAPE</keycap>
            instead of specifying a register name cancels the operation.</para>

            <para>Note that the content of registers other than the clipboard
            and quick copy register are automatically saved between jEdit
            sessions.</para>

            <para><guimenu>Edit</guimenu>&gt;<guisubmenu>More
            Clipboard</guisubmenu>&gt;<guimenuitem>Cut to Register</guimenuitem>
            (shortcut: <keycap>C+r C+x <replaceable>key</replaceable></keycap>)
            stores the selected text in the specified register, removing it from
            the buffer.</para>

            <para><guimenu>Edit</guimenu>&gt;<guisubmenu>More
            Clipboard</guisubmenu>&gt;<guimenuitem>Copy to
            Register</guimenuitem> (shortcut: <keycap>C+r C+c
            <replaceable>key</replaceable></keycap>) stores the selected text in
            the specified register, leaving it in the buffer.</para>

            <para><guimenu>Edit</guimenu>&gt;<guisubmenu>More
            Clipboard</guisubmenu>&gt;<guimenuitem>Cut Append to
            Register</guimenuitem> (shortcut: <keycap>C+r C+u
            <replaceable>key</replaceable></keycap>) adds the selected text to
            the existing contents of the specified register, and removes it from
            the buffer.</para>

            <para><guimenu>Edit</guimenu>&gt;<guisubmenu>More
            Clipboard</guisubmenu>&gt;<guimenuitem>Copy Append to
            Register</guimenuitem> (shortcut: <keycap>C+r C+a
            <replaceable>key</replaceable></keycap>) adds the selected text to
            the existing contents of the specified register, without removing it
            from the buffer.</para>

            <para><guimenu>Edit</guimenu>&gt;<guisubmenu>More
            Clipboard</guisubmenu>&gt;<guimenuitem>Paste from
            Register</guimenuitem> (shortcut: <keycap>C+r C+v
            <replaceable>key</replaceable></keycap>) replaces the selection with
            the contents of the specified register.</para>

            <para>The following three commands display dialog boxes instead of
            prompting for a register name.</para>

            <para><guimenu>Edit</guimenu>&gt;<guisubmenu>More
            Clipboard</guisubmenu>&gt;<guimenuitem>Paste Previous</guimenuitem>
            (shortcut: <keycap>C+e C+v</keycap>) displays a dialog box listing
            the 20 most recently copied and pasted text strings.</para>

            <para><guimenu>Edit</guimenu>&gt;<guisubmenu>More
            Clipboard</guisubmenu>&gt;<guimenuitem>Paste Deleted</guimenuitem>
            (shortcut: <keycap>C+e C+y</keycap>) is not really a register
            command; it displays a dialog box listing the 20 most recently
            deleted text strings.</para>

            <para><guimenu>Edit</guimenu>&gt;<guisubmenu>More
            Clipboard</guisubmenu>&gt;<guimenuitem>View Registers</guimenuitem>
            displays a dialog box for viewing register contents, including the
            clipboard and the quick copy.</para>
        </section>
    </section>

    <section id="markers">
        <title>Markers</title>

        <para>A <firstterm>marker</firstterm> is a pointer to a specific
        location within a buffer, which may or may not have a single-character
        <firstterm>shortcut</firstterm> associated with it. Markers are
        persistent; they are saved to
        <filename>.<replaceable>filename</replaceable>.marks</filename>, where
        <filename><replaceable>filename</replaceable></filename> is the name of
        the buffer. (The dot prefix makes the markers file hidden on Unix
        systems.) Marker saving can be disabled in the
        <guibutton>General</guibutton> pane of the
        <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
        Options</guimenuitem> dialog box; see <xref
        linkend="general-pane" />.</para>

        <para><guimenu>Markers</guimenu>&gt;<guimenuitem>Add/Remove
        Marker</guimenuitem> (shortcut: <keycap>C+e C+m</keycap>) adds a marker
        without a shortcut pointing to the current line. If a marker is already
        set on the current line, the marker is removed instead. If text is
        selected, markers are added to the first and last line of each
        selection.</para>

        <para>Markers are listed in the <guimenu>Markers</guimenu> menu;
        selecting a marker from this menu will move the caret to its
        location.</para>

        <para><guimenu>Markers</guimenu>&gt;<guimenuitem>Go to Previous
        Marker</guimenuitem> (shortcut: <keycap>C+e C+COMMA</keycap>) goes to
        the marker immediately before the caret position.</para>

        <para><guimenu>Markers</guimenu>&gt;<guimenuitem>Go to Next
        Marker</guimenuitem> (shortcut: <keycap>C+e C+PERIOD</keycap>) goes to
        the marker immediately after the caret position.</para>

        <para><guimenu>Markers</guimenu>&gt;<guimenuitem>Remove All
        Markers</guimenuitem> removes all markers set in the current
        buffer.</para>

        <para>Markers with shortcuts allow for quicker keyboard-based
        navigation. The following commands all prompt for a single-character
        shortcut when invoked. Pressing <keycap>ESCAPE</keycap> instead of
        specifying a shortcut will cancel the operation.</para>

        <para><guimenu>Markers</guimenu>&gt;<guimenuitem>Add Marker With
        Shortcut</guimenuitem> (shortcut: <keycap>C+t
        <replaceable>key</replaceable></keycap>) adds a marker with the
        specified shortcut. If marker with that shortcut already exists, it will
        remain in the buffer but lose its shortcut.</para>

        <para><guimenu>Markers</guimenu>&gt;<guimenuitem>Go to
        Marker</guimenuitem> (shortcut: <keycap>C+y
        <replaceable>key</replaceable></keycap>) moves the caret to the location
        of the marker with the specified shortcut.</para>

        <para><guimenu>Markers</guimenu>&gt;<guimenuitem>Select to
        Marker</guimenuitem> (shortcut: <keycap>C+u
        <replaceable>key</replaceable></keycap>) creates a selection from the
        caret location to the marker with the specified shortcut.</para>

        <para><guimenu>Markers</guimenu>&gt;<guimenuitem>Swap Caret and
        Marker</guimenuitem> (shortcut: <keycap>C+k
        <replaceable>key</replaceable></keycap>) moves the caret to the location
        of the marker with the specified shortcut, and moves the marker to the
        former caret position. Invoke this command multiple times to flip
        between two locations in the buffer.</para>

        <para>Lines which contain markers are indicated in the gutter with a
        highlight. Moving the mouse over the highlight displays a tool tip
        showing the marker's shortcut, if it has one. See <xref
        linkend="overview" /> for information about the gutter.</para>
    </section>

    <section id="search-replace">
        <title>Search and Replace</title>

        <section>
            <title>Searching For Text</title>

            <para><guimenu>Search</guimenu>&gt;<guimenuitem>Find</guimenuitem>
            (shortcut: <keycap>C+f</keycap>) displays the search and replace
            dialog box.</para>

            <para>The search string can be entered in the <guibutton>Search
            for</guibutton> text field. This text field remembers previously
            entered strings; see <xref linkend="history" /> for details.</para>

            <para>If text was selected in the text area and the selection does
            not span a line break, the selected text becomes the default search
            string.</para>

            <para>If the selection spans a line break, the <guibutton>Search in
            Selection</guibutton> and <guibutton>HyperSearch</guibutton> buttons
            will be pre-selected, and the search string field will be initially
            blank. (See <xref linkend="hypersearch" /> for information about the
            HyperSearch feature.) <!-- Note that finding the next or previous
    occurrence cannot be constrained to a selected range; only
    replacement and HyperSearch can be (see <xref linkend="hypersearch" />). --></para>

            <para>Selecting the <guibutton>Ignore case</guibutton> check box
            makes the search case insensitive - for example, searching for
            <quote>Hello</quote> will match <quote>hello</quote>,
            <quote>HELLO</quote> and <quote>HeLlO</quote>.</para>

            <para>To search for special characters (such as newlines or
            non-printable characters), inexact sequences of text, or strings
            that span multiple lines, we use
            <emphasis role="bold">Regular Expressions</emphasis>.
            Selecting the <guibutton>Regular expressions</guibutton> check
            box allows special characters to be used in the search string.
            Regular expression syntax is described in <xref linkend="regexps"/>.
            If you use (groups) in the search field, you back-reference them
            with $1 through $9 in the replace field. </para>

            <para>The <guibutton>Backward</guibutton> and
            <guibutton>Forward</guibutton> buttons specify the search direction.
            Note that regular expressions can only be used when searching in a
            forward direction.</para>

            <para>Clicking <guibutton>Find</guibutton> will locate the next
            occurrence of the search string (or previous occurrence, if
            searching backwards). If the <guibutton>Keep dialog</guibutton>
            check box is selected, the dialog box will remain open after the
            search string has been located; otherwise, it will close.</para>

            <para>If no occurrences could be found and the <guibutton>Auto
            wrap</guibutton> check box is selected, the search will
            automatically restart from the beginning of the buffer (or the end,
            if searching backwards). If <guibutton>Auto wrap</guibutton> is not
            selected, a confirmation dialog box is shown before restarting the
            search.</para>

            <para><guimenu>Search</guimenu>&gt;<guimenuitem>Find
            Next</guimenuitem> (shortcut: <keycap>C+g</keycap>) locates the next
            occurrence of the most recent search string without displaying the
            search and replace dialog box.</para>

            <para><guimenu>Search</guimenu>&gt;<guimenuitem>Find
            Previous</guimenuitem> (shortcut: <keycap>C+h</keycap>) locates the
            previous occurrence of the most recent search string without
            displaying the search and replace dialog box.</para>
        </section>

        <section>
            <title>Replacing Text</title>

            <para>The replace string text field of the search dialog remembers
            previously entered strings; see <xref linkend="history" /> for
            details.</para>

            <para>Clicking <guibutton>Replace &amp; Find</guibutton> will
            perform a replacement in the current selection and locate the next
            occurrence of the search string. Clicking <guibutton>Replace
            All</guibutton> will replace all occurrences of the search string
            with the replacement string in the current search scope (which is
            either the selection, the current buffer, or a set of buffers, as
            specified in the search and replace dialog box).</para>

            <para>Occurrences of the search string can be replaced with either a
            replacement string, or the return value of a BeanShell script
            snippet. Two radio buttons in the search and replace dialog box
            select between the two replacement modes, which are described in
            detail below.</para>

            <section>
                <title>Text Replace</title>

                <para>If the <guibutton>Text</guibutton> button is selected, the
                search string is simply replaced with the replacement
                string.</para>

                <para>If regular expressions are enabled, positional parameters
                (<literal>$0</literal>, <literal>$1</literal>,
                <literal>$2</literal>, and so on) can be used to insert the
                contents of matched subexpressions in the replacement string;
                see <xref linkend="regexps" /> for more information.</para>

                <para>If the search is case-insensitive, jEdit attempts to
                modify the case of the replacement string to match that of the
                particular instance of the search string being replaced. For
                example, searching for <quote>label</quote> and replacing it
                with <quote>text</quote>, will perform the following
                replacements:</para>

                <itemizedlist>
                    <listitem>
                        <para><quote>String label</quote> would become
                        <quote>String text</quote></para>
                    </listitem>

                    <listitem>
                        <para><quote>setLabel</quote> would become
                        <quote>setText</quote></para>
                    </listitem>

                    <listitem>
                        <para><quote>DEFAULT_LABEL</quote> would become
                        <quote>DEFAULT_TEXT</quote></para>
                    </listitem>
                </itemizedlist>
            </section>

            <section>
                <title>BeanShell Replace</title>

                <para>In BeanShell replacement mode, the search string is
                replaced with the return value of a BeanShell snippet. If
                you want to use multiple line snippet, enclose your BeanShell
                in braces. The following predefined variables can be referenced
                in the snippet:</para>

                <itemizedlist>
                    <listitem>
                        <para><varname>_0</varname> -- the text to be
                        replaced</para>
                    </listitem>

                    <listitem>
                        <para><varname>_1</varname> - <varname>_9</varname> --
                        if regular expressions are enabled, these contain the
                        values of matched subexpressions.</para>
                    </listitem>
                </itemizedlist>

                <para>BeanShell syntax and features are covered in great detail
                in <xref linkend="writing-macros-part" />, but here are some
                examples:</para>

                <informalexample>
                    <para>To replace each occurrence of <quote>Windows</quote>
                    with <quote>Linux</quote>, and each occurrence of
                    <quote>Linux</quote> with <quote>Windows</quote>, search for
                    the following regular expression:</para>

                    <programlisting>(Windows|Linux)</programlisting>

                    <para>Replacing it with the following BeanShell
                    snippet:</para>

                    <programlisting>_1.equals("Windows") ? "Linux" : "Windows"</programlisting>
                </informalexample>

                <informalexample>
                    <para>To convert all HTML tags to lower case, search for the
                    following regular expression:</para>

                    <programlisting>&lt;\S+</programlisting>

                    <para>Replacing it with the following BeanShell
                    snippet:</para>

                    <programlisting>_0.toLowerCase()</programlisting>
                </informalexample>

                <informalexample>
                    <para>To replace arithmetic expressions contained in curly
                    braces with the result of evaluating the expression, search
                    for the following regular expression:</para>

                    <programlisting>\{(.+?)\}</programlisting>

                    <para>Replacing it with the following BeanShell
                    snippet:</para>

                    <programlisting>eval(_1)</programlisting>
                </informalexample>

                <para>These examples only scratch the surface; the possibilities
                are endless.</para>
            </section>
        </section>

        <section id="hypersearch">
            <title>HyperSearch</title>

            <para>If the <guibutton>HyperSearch</guibutton> check box in the
            search and replace dialog box is selected, clicking
            <guibutton>Find</guibutton> lists all occurrences of the search
            string, instead of locating the next match.</para>

            <para>By default, HyperSearch results are shown in a floating
            window. This window can be docked using the commands in its top-left
            corner popup menu; see <xref linkend="docking" />.</para>

            <para>If the <guibutton>Multiple results</guibutton> check box is
            selected in the results window, past search results are
            retained.</para>

            <para>Running searches can be stopped in the
            <guimenu>Utilities</guimenu>&gt;<guisubmenu>Troubleshooting</guisubmenu>&gt;<guimenuitem>I/O
            Progress Monitor</guimenuitem> dialog box.</para>
        </section>

        <section>
            <title>Multiple File Search</title>

            <para>Search and replace commands can be performed over an arbitrary
            set of files in one step. The set of files to search is selected
            with a set of buttons in the search dialog box.</para>

            <para>If the <guibutton>Current buffer</guibutton> button is
            selected, only the current buffer is searched. This is the default
            behavior.</para>

            <para>If the <guibutton>All buffers</guibutton> button is selected,
            all open buffers whose names match the glob pattern entered in the
            <guibutton>Filter</guibutton> text field will be searched. See <xref
            linkend="globs" /> for more information about glob patterns.</para>

            <para>If the <guibutton>Directory</guibutton> radio button is
            selected, all files contained in the specified directory whose names
            match the glob will be searched. The directory to search in can
            either be entered in the <guibutton>Directory</guibutton> text
            field, or chosen in a file selector dialog box by clicking the
            <guibutton>Choose</guibutton> button next to the field. If the
            <guibutton>Search subdirectories</guibutton> check box is selected,
            all subdirectories of the specified directory will also be searched.
            Keep in mind that searching through directories containing many
            files can take a long time.</para>

            <para>The <guibutton>Directory</guibutton> and
            <guibutton>Filter</guibutton> text fields remember previously
            entered strings; see <xref linkend="history" /> for details.</para>

            <para>When the search and replace dialog box is opened, the
            directory and file name filter fields are set to their previous
            values. They can be set to match the current buffer's directory and
            file name extension by clicking
            <guibutton>Synchronize</guibutton>.</para>

            <para>Note that clicking the <guibutton>All Buffers</guibutton> or
            <guibutton>Directory</guibutton> radio buttons also selects the
            <guibutton>HyperSearch</guibutton> check box since that is what you
            would want, most of the time. However, the
            <guibutton>HyperSearch</guibutton> check box can be unchecked, for
            stepping through search results in multiple files one at a
            time.</para>

            <para>Two convenience commands are provided for performing multiple
            file searches.</para>

            <para><guimenu>Search</guimenu>&gt;<guimenuitem>Search in Open
            Buffers</guimenuitem> (shortcut: <keycap>C+e C+b</keycap>) displays
            the search dialog box and selects the <guibutton>All
            buffers</guibutton> button.</para>

            <para><guimenu>Search</guimenu>&gt;<guimenuitem>Search in
            Directory</guimenuitem> (shortcut: <keycap>C+e C+d</keycap>)
            displays the search dialog box and selects the
            <guibutton>Directory</guibutton> button.</para>
        </section>

        <section id="search-bar">
            <title>The Search Bar</title>

            <para>The search bar feature provides a convenient way to search in
            the current buffer without opening the search dialog box. The search
            bar does not support replacement or multiple file search. Previously
            entered strings can be recalled in the search bar with the
            <keycap>Up</keycap> and <keycap>Down</keycap> arrow keys; see <xref
            linkend="history" />.</para>

            <para>By default, the search bar remains hidden until one of the
            quick search commands (described below) is invoked; however you can
            choose to have it always visible in the <guibutton>View</guibutton>
            pane of the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
            Options</guimenuitem> dialog box; see <xref
            linkend="view-pane" />.</para>

            <para><guimenu>Search</guimenu>&gt;<guimenuitem>Incremental Search
            Bar</guimenuitem> (shortcut: <keycap>C+COMMA</keycap>) displays the
            search bar if necessary, and gives it keyboard focus. </para>

            <para><guimenu>Search</guimenu>&gt;<guimenuitem>Incremental Search
            for Word</guimenuitem> (shortcut: <keycap>A+COMMA</keycap>) behaves
            like the above command except it places the word at the caret in the
            search string field. If this command is invoked while there is a
            selection, the selection is placed in the search string
            field instead.</para>

            <para>Unless the <guibutton>HyperSearch</guibutton> check box is
            selected, the search bar will perform an <firstterm>incremental
            search</firstterm>. In incremental search mode, the first occurrence
            of the search string is located in the current buffer as it is being
            typed. Pressing <keycap>ENTER</keycap> and <keycap>S+ENTER</keycap>
            searches for the next and previous occurrence, respectively. Once
            the desired occurrence has been located, pressing
            <keycap>ESCAPE</keycap> returns keyboard focus to the text area.
            Unless the search bar is set to be always visible (see above),
            pressing <keycap>ESCAPE</keycap> will also hide the search
            bar.</para>

            <note>
                <para>Incremental searches cannot be not recorded in macros. If
                your macro needs to perform a search, use the search and replace
                dialog box instead. See <xref linkend="using-macros" /> for
                information about macros.</para>
            </note>

            <para><guimenu>Search</guimenu>&gt;<guimenuitem>HyperSearch
            Bar</guimenuitem> (shortcut: <keycap>C+PERIOD</keycap>) displays the
            search bar if necessary, gives it keyboard focus, and selects the
            <guibutton>HyperSearch</guibutton> check box. If this command is
            invoked while there is a selection, the selected text will be
            searched for immediately and the search bar will not be
            shown.</para>

            <para>If the <guibutton>HyperSearch</guibutton> check box is
            selected, pressing <keycap>Enter</keycap> in the search string field
            will perform a HyperSearch in the current buffer.</para>

            <para><guimenu>Search</guimenu>&gt;<guimenuitem>HyperSearch for
            Word</guimenuitem> (shortcut: <keycap>A+PERIOD</keycap>) performs a
            HyperSearch for the word at the caret. This command does not show
            the search bar or give it keyboard focus.</para>
        </section>
    </section>
</chapter>