PageRenderTime 71ms CodeModel.GetById 48ms app.highlight 13ms RepoModel.GetById 1ms app.codeStats 0ms


XML | 1134 lines | 1126 code | 2 blank | 6 comment | 0 complexity | c4f6ba311def0f7264481b1f5310eec8 MD5 | raw file
   1<!-- jEdit buffer-local properties: -->
   2<!-- :tabSize=1:indentSize=1:noTabs=true:wrap=soft:maxLineLen=80: -->
   3<!-- :xml.root=users-guide.xml: -->
   5<chapter id="editing"><title>Editing Text</title>
   6 <sect1 id="caret"><title>Moving The Caret</title>
   7  <para>
   8   The simplest way to move the caret is to click the
   9   mouse at the desired location in the text area. The caret can also be moved
  10   using the keyboard.
  11  </para>
  12  <para>
  13   The <keycap>LEFT</keycap>, <keycap>RIGHT</keycap>, <keycap>UP</keycap> and
  14   <keycap>DOWN</keycap> keys move the caret in the respective direction, and
  15   the <keycap>PAGE_UP</keycap> and <keycap>PAGE_DOWN</keycap> keys move the
  16   caret up and down one screenful, respectively.
  17  </para>
  18  <para>
  19   When pressed once, the <keycap>HOME</keycap> key moves the caret to the first
  20   non-whitespace character of the current screen line. Pressing it a second
  21   time moves the caret to the beginning of the current buffer line. Pressing it
  22   a third time moves the caret to the first visible line.
  23  </para>
  24  <para>
  25   The <keycap>END</keycap> key behaves in a
  26   similar manner, going to the last non-whitespace character of the current
  27   screen line, the end of
  28   the current buffer line, and finally to the last visible line.
  29  </para>
  30  <para>
  31   If soft wrap is disabled, a <quote>screen line</quote> is the
  32   same as a  <quote>buffer line</quote>. If soft wrap is enabled,
  33   a screen line is a section of a newline-delimited buffer line that fits
  34   within the wrap margin width. See <xref linkend="word-wrap"/>.
  35  </para>
  36  <para>
  37   <keycap>C+HOME</keycap> and
  38   <keycap>C+END</keycap> move the
  39   caret to the beginning and end of the buffer, respectively.
  40  </para>
  41  <para>
  42   More advanced caret movement is covered in
  43   <xref linkend="words" />, <xref linkend="lines" /> and
  44   <xref linkend="paragraphs" />.
  45  </para>
  46  <sidebar><title>The Home and End keys</title>
  47   <para>
  48    If you prefer more traditional behavior for the
  49    <keycap>HOME</keycap> and <keycap>END</keycap> keys, you can reassign
  50    the respective keyboard shortcuts in the <guibutton>Shortcuts</guibutton>
  51    pane of the
  52    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>; see <xref linkend="shortcuts-pane"/>.
  53   </para>
  54   <para>
  55    By default, the shortcuts are assigned as follows:
  56   </para>
  57   <itemizedlist>
  58    <listitem><para><keycap>HOME</keycap> is bound to <guimenuitem>Smart
  59    Home</guimenuitem>.</para></listitem>
  60    <listitem><para><keycap>END</keycap> is bound to <guimenuitem>Smart
  61    End</guimenuitem>.</para></listitem>
  62    <listitem><para><keycap>S+HOME</keycap> is bound to <guimenuitem>Select to Smart
  63    Home Position</guimenuitem>.</para></listitem>
  64    <listitem><para><keycap>S+END</keycap> is bound to <guimenuitem>Select to Smart
  65    End Position</guimenuitem>.</para></listitem>
  66   </itemizedlist>
  67   <para>
  68    However you can rebind them to anything you want, for example, various
  69    combinations of the following, or indeed any other command or macro:
  70   </para>
  71   <itemizedlist>
  72    <listitem><para><guimenuitem>Go to Start/End of White Space</guimenuitem>.</para></listitem>
  73    <listitem><para><guimenuitem>Go to Start/End of Line</guimenuitem>.</para></listitem>
  74    <listitem><para><guimenuitem>Go to Start/End of Buffer</guimenuitem>.</para>
  75    </listitem>
  76    <listitem><para><guimenuitem>Select to Start/End of White Space
  77    </guimenuitem>.</para></listitem>
  78    <listitem><para><guimenuitem>Select to Start/End of Line</guimenuitem>.</para>
  79    </listitem>
  80    <listitem><para><guimenuitem>Select to Start/End of Buffer</guimenuitem>.</para>
  81    </listitem>
  82   </itemizedlist>
  83  </sidebar>
  84 </sect1>
  85 <sect1 id="selection"><title>Selecting Text</title>
  86  <para>
  87   A <firstterm>selection</firstterm> is a block of text marked for further
  88   manipulation. Range selections are equivalent to selections in most other text editors; they cover text between two points in a buffer. jEdit also allows rectangular selections that cover a rectangular area (some text editors refer to these as <quote>column selections</quote>). Furthermore, several chunks of text can be
  89   selected and operated on simultaneously.
  90  </para>
  91  <sect2><title>Range Selection</title>
  92  <para>
  93   Dragging the mouse creates a range selection from where the mouse was
  94   pressed to where it was released.
  95   Holding down <keycap>Shift</keycap> while clicking a location in the
  96   buffer will create a selection from the caret position to the clicked
  97   location.
  98  </para>
  99  <para>
 100   Holding down <keycap>Shift</keycap> in addition to a caret movement key
 101   (<keycap>LEFT</keycap>, <keycap>UP</keycap>, <keycap>HOME</keycap>, etc) will
 102   extend a selection in the specified direction.
 103  </para>
 104  <para>
 105   <guimenu>Edit</guimenu>&gt;<guimenuitem>Select All</guimenuitem> (shortcut:
 106   <keycap>C+a</keycap>) selects the
 107   entire buffer.
 108  </para>
 109  <para>
 110   <guimenu>Edit</guimenu>&gt;<guisubmenu>More Selection</guisubmenu>&gt;<guimenuitem>Select None</guimenuitem> (shortcut:
 111   <keycap>ESCAPE</keycap>) deactivates the selection.
 112  </para>
 113  </sect2>
 114  <sect2 id="rect-select"><title>Rectangular Selection</title>
 115   <para>
 116    Dragging with the <keycap>Control</keycap> key held down will create a
 117    rectangular selection. Holding down
 118    <keycap>Shift</keycap> and <keycap>Control</keycap> while clicking a
 119    location in the buffer will create a rectangular selection from the caret
 120    position to the clicked location.
 121   </para>
 122   <para>
 123    Alternatively, invoking
 124    <guimenu>Edit</guimenu>&gt;<guisubmenu>More
 125    Selection</guisubmenu>&gt;<guimenuitem>Rectangular Selection</guimenuitem>
 126    (shortcut: <keycap>A+\</keycap>)
 127    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.
 128    A status bar indicator is shown when this mode is enabled.
 129   </para>
 130   <para>
 131    It is possible to select a rectangle with zero width but non-zero height.
 132    This can be used to insert a new column between two existing
 133    columns, for example. Such zero-width selections are shown as a thin
 134    vertical line.
 135   </para>
 136   <para>
 137    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.
 138   </para>
 139   <para>
 140    Rectangles can be deleted, copied, pasted, and operated on using ordinary
 141    editing commands. If necessary, rectangular selections are automatically filled in with whitespace to maintain alignment.
 142   </para>
 143   <para>
 144    Rectangular selections can extend beyond the end of a line into
 145    <quote>virtual space</quote>. Furthermore,
 146    if keyboard rectangular selection mode is on or if the
 147    <keycap>Control</keycap> key is being held down, clicking beyond the
 148    end of a line will insert the appropriate amount of whitespace in order
 149    to position the cursor at the clicked location.
 150   </para>
 151   <note>
 152    <para>
 153     Rectangular selections are implemented using character offsets,
 154     not absolute screen positions, so they might not behave as you might
 155     expect if a proportional-width font is being used or if soft wrap is
 156     enabled. The text area font can be changed in the
 157     <guibutton>Text Area</guibutton> pane of the
 158     <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
 159     dialog box. For information about soft wrap,
 160     see <xref linkend="word-wrap" />.
 161    </para>
 162   </note>
 163  </sect2>
 164  <sect2 id="multi-select"><title>Multiple Selection</title>
 165   <para>
 166    <guimenu>Edit</guimenu>&gt;<guisubmenu>More
 167    Selection</guisubmenu>&gt;<guimenuitem>Multiple Selection</guimenuitem>
 168    (keyboard shortcut: <keycap>C+\</keycap>)
 169    turns multiple selection mode on and
 170    off. In multiple selection mode, multiple fragments of text can be selected
 171    and operated on simultaneously, and the caret can be moved independently
 172    of the selection. The status bar indicates if multiple
 173    selection mode is active; see <xref linkend="status-bar"/>.
 174   </para>
 175   <para>
 176    Various jEdit commands behave differently with multiple selections:
 177   </para>
 178   <itemizedlist>
 179    <listitem><para>Commands that copy text place the contents of
 180    each selection, separated by line breaks, in the specified register.
 181    </para></listitem>
 182    <listitem><para>Commands that insert (or paste) text replace each selection
 183    with the entire text that is being inserted.</para></listitem>
 184    <listitem><para>Commands that filter text (such as <guimenuitem>Spaces to
 185    Tabs</guimenuitem>, <guimenuitem>Range Comment</guimenuitem>,
 186    <guimenuitem>Replace in Selection</guimenuitem>, and so on) behave as if
 187    each block was selected independently, and the command invoked on each in
 188    turn.</para></listitem>
 189    <listitem><para>Line-based commands (such as <guimenuitem>Shift Indent
 190    Left</guimenuitem>, <guimenuitem>Shift Indent Right</guimenuitem>, and
 191    <guimenuitem>Line Comment</guimenuitem>) operate on each line that contains
 192    at least one selection.
 193    </para></listitem>
 194    <listitem><para>Caret movement commands that would normally deactivate the
 195    selection (such as the arrow keys, while <keycap>Shift</keycap> is not being
 196    held down), move the caret, leaving the selection as-is.</para></listitem>
 197    <listitem><para>Some older plugins may not support multiple selection at
 198    all.</para></listitem>
 199   </itemizedlist>
 200   <para>
 201    <guimenu>Edit</guimenu>&gt;<guisubmenu>More
 202    Selection</guisubmenu>&gt;<guimenuitem>Select None</guimenuitem>
 203    (shortcut: <keycap>ESCAPE</keycap>) deactivates the selection containing the
 204    caret, if there is one. Otherwise it deactivates all active selections.
 205   </para>
 206   <para>
 207    <guimenu>Edit</guimenu>&gt;<guisubmenu>More
 208    Selection</guisubmenu>&gt;<guimenuitem>Invert Selection</guimenuitem>
 209    (shortcut: <keycap>C+e C+i</keycap>) selects a set of text chunks such that all text
 210    that was formerly part of a selection is now unselected, and all text that
 211    wasn't, is selected.
 212   </para>
 213   <note>
 214    <para>
 215     Deactivating multiple selection
 216     mode while multiple blocks of text are selected will leave the selections
 217     in place, but you will not be able to add new selections until
 218     multiple selection mode is reactivated.
 219    </para>
 220   </note>
 221  </sect2>
 222 </sect1>
 223 <sect1 id="entering-text"><title>Inserting and Deleting Text</title>
 224  <para>
 225   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
 226   front of the caret position for every character that is inserted. The caret is
 227   drawn as horizontal line while overwrite
 228   mode is active. The status bar also indicates if overwrite mode is active; see
 229   <xref linkend="status-bar"/> for details.
 230  </para>
 231  <para>
 232   Inserting text while there is a selection will replace the selection
 233   with the inserted text.
 234  </para>
 235  <para>
 236   When inserting text, the <keycap>TAB</keycap> and
 237   <keycap>ENTER</keycap> keys might
 238   not behave entirely like you expect because  of various indentation
 239   features; see <xref linkend="indent" /> for details.
 240  </para>
 241  <para>
 242   The simplest way to delete text is with the
 243   <keycap>BACKSPACE</keycap> and <keycap>DELETE</keycap> keys. If nothing is
 244   selected, they delete the character before or after the caret,
 245   respectively. If a selection exists, both delete the
 246   selection.
 247  </para>
 248  <para>
 249   More advanced deletion commands are described in
 250   <xref linkend="words" />, <xref linkend="lines" /> and
 251   <xref linkend="paragraphs" />.
 252  </para>
 253 </sect1>
 254 <sect1 id="undo-redo"><title>Undo and Redo</title>
 255  <para>
 256   <guimenu>Edit</guimenu>&gt;<guimenuitem>Undo</guimenuitem> (shortcut: <keycap>C+z</keycap>) reverses the
 257   most recent editing command. For example, this can be
 258   used to restore unintentionally deleted text. More complicated operations,
 259   such as a search and replace, can also be undone.
 260  </para>
 261  <para>
 262   If you undo too many changes,
 263   <guimenu>Edit</guimenu>&gt;<guimenuitem>Redo</guimenuitem> (shortcut:
 264   <keycap>C+e C+z</keycap>) can restore
 265   the changes again. For example, if some
 266   text was inserted, <guimenuitem>Undo</guimenuitem> will remove it from the
 267   buffer. <guimenuitem>Redo</guimenuitem> will insert it again.
 268  </para>
 269  <para>
 270   By default, the last 100 edits is retained; older edits cannot be undone.
 271   The maximum number of undos can be changed in the <guibutton>Editing</guibutton> pane
 272   of the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
 273   Options</guimenuitem> dialog box; see <xref linkend="editing-pane"/>.
 274  </para>
 275 </sect1>
 276 <sect1 id="words"><title>Working With Words</title>
 277  <para>
 278   <keycap>C+LEFT</keycap> and <keycap>C+RIGHT</keycap>
 279   move the caret a word at
 280   a time. Holding down <keycap>Shift</keycap> in addition to the above
 281   extends the selection a word at a time.
 282  </para>
 283  <para>
 284   A single word can be selected by double-clicking with the mouse,
 285   or using the
 286   <guimenu>Edit</guimenu>&gt;<guisubmenu>More
 287   Selection</guisubmenu>&gt;<guimenuitem>Select
 288   Word</guimenuitem> command (shortcut: <keycap>C+e w</keycap>).
 289   A selection that begins and ends on word boundaries can be created by
 290   double-clicking and dragging.
 291  </para>
 292  <para>
 293   <keycap>C+BACKSPACE</keycap> and <keycap>C+DELETE</keycap>
 294   delete the word
 295   before or after the caret, respectively.
 296  </para>
 297  <para>
 298   <guimenu>Edit</guimenu>&gt;<guimenuitem>Complete Word</guimenuitem> (shortcut: <keycap>C+b</keycap>) locates
 299   possible completions for the word at the caret, first by looking in the
 300   current edit mode's syntax highlighting
 301   keyword list, and then in the current buffer for words that begin with the
 302   word at the caret. This serves as a very basic code completion feature.
 303  </para>
 304  <para>
 305   If there is only one completion, it will be inserted into the buffer
 306   immediately.
 307  </para>
 308  <para>
 309   If multiple completions were found, the longest common prefix is inserted into the buffer, and a popup is shown below
 310   the caret position listing the completions.
 311  </para>
 312  <para>
 313   To insert a completion from the list, either select it using the <keycap>UP</keycap> and <keycap>DOWN</keycap> keys and
 314   press <keycap>ENTER</keycap>, press a digit to insert one of the first
 315   ten completions (1 is the first completion; 9 is the 9th; 0 is the 10th),
 316   or click the desired completion with the mouse. To close the popup without inserting a
 317   completion, press <keycap>ESCAPE</keycap>.
 318  </para>
 319  <para>
 320   Typing while the popup is
 321   visible will automatically update the popup and narrow the set of
 322   completions as necessary.
 323  </para>
 324  <para>
 325   <guimenu>Edit</guimenu>&gt;<guimenuitem>Word Count</guimenuitem>
 326   displays a dialog box with the number of characters,
 327   words and lines in the current buffer.
 328  </para>
 329  <sect2><title>What's a Word?</title>
 330   <para>
 331    The default behavior of the
 332    <keycap>C+LEFT</keycap>,
 333    <keycap>C+RIGHT</keycap>,
 334    <keycap>C+BACKSPACE</keycap> and <keycap>C+DELETE</keycap> commands is to
 335    stop both at the beginning and the end of each word. However this can be
 336    changed by remapping these keystrokes to alternative actions whose names end
 337    with <guimenuitem>(Eat Whitespace)</guimenuitem> in the
 338    <guibutton>Shortcuts</guibutton> pane of the
 339    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
 340    dialog box; see <xref linkend="shortcuts-pane"/>.
 341   </para>
 342  </sect2>
 343 </sect1>
 344 <sect1 id="lines"><title>Working With Lines</title>
 345  <para>
 346   An entire line can be selected by triple-clicking with the mouse,
 347   or using the
 348   <guimenu>Edit</guimenu>&gt;<guisubmenu>More
 349   Selection</guisubmenu>&gt;<guimenuitem>Select
 350   Line</guimenuitem> command (shortcut: <keycap>C+e l</keycap>).
 351   A selection that begins and ends on line boundaries can be created
 352   by triple-clicking and dragging.
 353  </para>
 354  <para>
 355   <guimenu>Edit</guimenu>&gt;<guimenuitem>Go to Line</guimenuitem> (shortcut:
 356   <keycap>C+l</keycap>) prompts
 357   for a line number and moves the caret there.
 358  </para>
 359  <para>
 360   <guimenu>Edit</guimenu>&gt;<guisubmenu>More
 361   Selection</guisubmenu>&gt;<guimenuitem>Select Line Range</guimenuitem>
 362   (shortcut: <keycap>C+e C+l</keycap>)
 363   prompts for two line numbers and selects all text between them.
 364  </para>
 365  <para>
 366   <guimenu>Edit</guimenu>&gt;<guisubmenu>Text</guisubmenu>&gt;<guimenuitem>Delete
 367   Line</guimenuitem>
 368   (shortcut: <keycap>C+d</keycap>)
 369   deletes the current line.
 370  </para>
 371  <para>
 372   <guimenu>Edit</guimenu>&gt;<guisubmenu>Text</guisubmenu>&gt;<guimenuitem>Delete
 373   to Start Of Line</guimenuitem>
 374   (shortcut: <keycap>CS+BACK_SPACE</keycap>)
 375   deletes all text from the start of the current line to the caret.
 376  </para>
 377  <para>
 378   <guimenu>Edit</guimenu>&gt;<guisubmenu>Text</guisubmenu>&gt;<guimenuitem>Delete
 379   to End Of Line</guimenuitem>
 380   (shortcut: <keycap>CS+DELETE</keycap>) deletes
 381   all text from the caret to the end of the current line.
 382  </para>
 383  <para>
 384   <guimenu>Edit</guimenu>&gt;<guisubmenu>Text</guisubmenu>&gt;<guimenuitem>Join
 385   Lines</guimenuitem> (shortcut: <keycap>C+j</keycap>)
 386   removes any whitespace from the start of the next line and joins it with
 387   the current line.
 388   The caret is moved to the position where the two lines were joined.
 389   For example, if you invoke <guimenuitem>Join Lines</guimenuitem>
 390   with the caret on the first line of the following Java code:
 391  </para>
 392  <screen>new Widget(Foo
 393       .createDefaultFoo());</screen>
 394  <para>
 395   It will be changed to:
 396  </para>
 397  <screen>new Widget(Foo.createDefaultFoo());</screen>
 398 </sect1>
 399 <sect1 id="paragraphs"><title>Working With Paragraphs</title>
 400  <para>
 401   As far as jEdit is concerned, <quote>paragraphs</quote> are delimited by
 402   double newlines. This is also how <application>TeX</application>
 403   defines a paragraph. Note that jEdit doesn't parse HTML files for
 404   <quote>&lt;P&gt;</quote> tags, nor does it support paragraphs delimited only
 405   by a leading indent.
 406  </para>
 407  <para>
 408   <keycap>C+UP</keycap> and <keycap>C+DOWN</keycap>
 409   move the caret to the previous and next paragraph, respectively.
 410   Holding down <keycap>Shift</keycap> in addition to the above
 411   extends the selection a paragraph at a time.
 412  </para>
 413  <para>
 414   <guimenu>Edit</guimenu>&gt;<guisubmenu>More Selection</guisubmenu>&gt;<guimenuitem>Select
 415   Paragraph</guimenuitem> (shortcut: <keycap>C+e p</keycap>)
 416   selects the paragraph containing the caret.
 417  </para>
 418  <para>
 419   <guimenu>Edit</guimenu>&gt;<guisubmenu>Text</guisubmenu>&gt;<guimenuitem>Format
 420   Paragraph</guimenuitem> (shortcut: <keycap>C+e f</keycap>) splits and joins lines in the current
 421   selection to make it fit within the wrap column position. If nothing is selected, the paragraph containing the caret is formatted instead. See
 422   <xref linkend="word-wrap" /> for information and word wrap and
 423   changing the wrap column.
 424  </para>
 425  <para>
 426   <guimenu>Edit</guimenu>&gt;<guisubmenu>Text</guisubmenu>&gt;<guimenuitem>Delete
 427   Paragraph</guimenuitem> (shortcut: <keycap>C+e d</keycap>)
 428   deletes the paragraph containing the caret.
 429  </para>
 430 </sect1>
 431 <sect1 id="word-wrap"><title>Wrapping Long Lines</title>
 432  <para>
 433   The <firstterm>word wrap</firstterm> feature splits lines at word
 434   boundaries in
 435   order to fit text within a specified wrap margin.
 436   The wrap margin
 437   position is indicated in the text are as a faint blue vertical line.
 438   There are two <quote>wrap modes</quote>, <quote>soft</quote> and
 439   <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
 440   changed in one of the following ways:
 441  </para>
 442  <itemizedlist>
 443   <listitem><para>On a global or mode-specific
 444   basis in the
 445   <guibutton>Editing</guibutton> pane
 446   of the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
 447   dialog box. See <xref linkend="editing-pane" />.</para></listitem>
 448   <listitem><para>In the current buffer
 449   for the duration of the editing session,</para>
 450   <itemizedlist>
 451    <listitem><para>By clicking the status bar indicator.</para></listitem>
 452    <listitem><para>In the
 453   <guimenu>Utilities</guimenu>&gt;<guimenuitem>Buffer Options</guimenuitem>
 454   dialog box. See <xref linkend="buffer-opts" />.</para></listitem>
 455    <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
 456     <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
 457     dialog box. By default, this command does not have a keyboard shortcut.</para></listitem>
 458    </itemizedlist>
 459   </listitem>
 460   <listitem><para>In the current buffer
 461   for future editing sessions by placing
 462   the following in one of the first or last 10 lines of the buffer, where
 463   <replaceable>mode</replaceable> is either <quote>none</quote>, <quote>soft</quote> or
 464   <quote>hard</quote>, and
 465   <replaceable>column</replaceable> is the desired wrap margin:
 466   </para>
 467   <screen>:wrap=<replaceable>mode</replaceable>:maxLineLen=<replaceable>column</replaceable>:</screen>
 468   </listitem>
 469  </itemizedlist>
 470  <sect2><title>Soft Wrap</title>
 471   <para>
 472    In soft wrap mode, lines are automatically wrapped when displayed on screen.
 473    Newlines are not inserted at the wrap positions, and the wrapping is
 474    automatically updated when text is inserted or removed.
 475   </para>
 476   <para>
 477    If end of line markers are enabled in the <guibutton>Text Area</guibutton>
 478    pane of the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
 479    dialog box, a colon (<quote>:</quote>) is painted at the end of wrapped lines. See <xref linkend="text-area-pane"/>.
 480   </para>
 481  </sect2>
 482  <sect2><title>Hard Wrap</title>
 483   <para>
 484    In hard wrap mode,
 485    inserting text at the end of a line will automatically break the line if
 486    it extends beyond the wrap margin. Inserting or removing text in the middle
 487    of a line has no effect, however text can be re-wrapped using the
 488    <guimenu>Edit</guimenu>&gt;<guisubmenu>Text</guisubmenu>&gt;<guimenuitem>Format
 489    Paragraph</guimenuitem> command. See <xref linkend="paragraphs"/>.
 490   </para>
 491   <para>
 492    Hard wrap is implemented using character offsets, not screen
 493    positions, so it might not behave like you expect if a
 494    proportional-width font is being used. The text area font can be changed in the
 495    <guibutton>Text Area</guibutton> pane of the
 496    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
 497    dialog box.
 498   </para>
 499  </sect2>
 500 </sect1>
 501 <sect1 id="scrolling"><title>Scrolling</title>
 502  <para>
 503    If you have a mouse with a scroll wheel and are running Java 2
 504    version 1.4, you can use the
 505    wheel to scroll up and down in the text area. Various modifier keys
 506    change the action of the wheel:
 507   </para>
 509   <itemizedlist>
 510    <listitem><para><keycap>Shift</keycap> - scrolls an entire page at a time.</para></listitem>
 511    <listitem><para><keycap>Control</keycap> - scrolls a single line at a time.</para></listitem>
 512    <listitem><para><keycap>Alt</keycap> - moves the caret up and down instead of scrolling.</para></listitem>
 513    <listitem><para><keycombo><keycap>Alt</keycap><keycap>Shift</keycap></keycombo>
 514     - extends the selection up and down instead of scrolling.</para></listitem>
 515   </itemizedlist>
 516  <para>
 517   Keyboard commands for scrolling the text area are also available.
 518  </para>
 519  <para>
 520   <guimenu>View</guimenu>&gt;<guisubmenu>Scrolling</guisubmenu>&gt;<guimenuitem>Scroll to
 521   Current Line</guimenuitem> (shortcut: <keycap>C+e C+j</keycap>) scrolls the
 522   text area in order to make the caret visible, if necessary. It does nothing if the
 523   caret is already visible.
 524  </para>
 525  <para>
 526   <guimenu>View</guimenu>&gt;<guisubmenu>Scrolling</guisubmenu>&gt;<guimenuitem>Center Caret
 527   on Screen</guimenuitem> (shortcut: <keycap>C+e C+n</keycap>)
 528   moves the caret to the
 529   line in the middle of the screen.
 530  </para>
 531  <para>
 532   <guimenu>View</guimenu>&gt;<guisubmenu>Scrolling</guisubmenu>&gt;<guimenuitem>Line
 533   Scroll Up</guimenuitem> (shortcut: <keycap>C+QUOTE</keycap>)
 534   scrolls the text area up by one line.
 535  </para>
 536  <para>
 537   <guimenu>View</guimenu>&gt;<guisubmenu>Scrolling</guisubmenu>&gt;<guimenuitem>Line
 538   Scroll Down</guimenuitem> (shortcut: <keycap>C+SLASH</keycap>) scrolls the
 539   text area down by one line.
 540  </para>
 541  <para>
 542   <guimenu>View</guimenu>&gt;<guisubmenu>Scrolling</guisubmenu>&gt;<guimenuitem>Page
 543   Scroll Up</guimenuitem> (shortcut: <keycap>A+QUOTE</keycap>) scrolls the text
 544   area up by one screenful.
 545  </para>
 546  <para>
 547   <guimenu>View</guimenu>&gt;<guisubmenu>Scrolling</guisubmenu>&gt;<guimenuitem>Page
 548   Scroll Down</guimenuitem> (shortcut: <keycap>A+SLASH</keycap>) scrolls the text
 549   area down by one screenful.
 550  </para>
 551  <para>
 552   The above scrolling commands differ from the caret movement commands
 553   in that they don't actually move the caret; they just change the
 554   scroll bar position.
 555  </para>
 556 </sect1>
 557 <sect1 id="text-transfer"><title>Transferring Text</title>
 558  <para>
 559   jEdit provides a rich set of commands for moving and copying text. Commands
 560   are provided for moving chunks of text from buffers to
 561   <firstterm>registers</firstterm> and vice-versa. A register is a holding area
 562   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>.
 563  </para>
 564  <sect2><title>The Clipboard</title>
 565   <para>
 566    jEdit offers the usual text transfer operations, that operate on the <filename>$</filename> register.
 567   </para>
 568   <para>
 569    <guimenu>Edit</guimenu>&gt;<guimenuitem>Cut</guimenuitem>
 570    (shortcut: <keycap>C+x</keycap>)
 571    places the selected text in the clipboard and removes it from the buffer.
 572   </para>
 573   <para>
 574    <guimenu>Edit</guimenu>&gt;<guimenuitem>Copy</guimenuitem>
 575    (shortcut: <keycap>C+c</keycap>)
 576    places the selected text in the clipboard and leaves it in the buffer.
 577   </para>
 578   <para>
 579    <guimenu>Edit</guimenu>&gt;<guimenuitem>Paste</guimenuitem>
 580    (shortcut: <keycap>C+v</keycap>)
 581    inserts the clipboard contents in place of the selection (or at the
 582    caret position, if there is no selection).
 583   </para>
 584   <para>
 585    The <guimenuitem>Cut</guimenuitem> and <guimenuitem>Copy</guimenuitem>
 586    commands replace the old clipboard contents with the selected text.
 587    There are two alternative commands which add the selection at the end of
 588    the existing clipboard contents, instead of replacing it.
 589   </para>
 590   <para>
 591    <guimenu>Edit</guimenu>&gt;<guisubmenu>More Clipboard</guisubmenu>&gt;<guimenuitem>Cut Append</guimenuitem>
 592    (shortcut: <keycap>C+e C+u</keycap>)
 593    appends the selected text to the clipboard, then removes it from the
 594    buffer. After this command has been invoked, the clipboard will consist of
 595    the former clipboard contents, followed by a newline, followed by the
 596    selected text.
 597   </para>
 598   <para>
 599    <guimenu>Edit</guimenu>&gt;<guisubmenu>More Clipboard</guisubmenu>&gt;<guimenuitem>Copy Append</guimenuitem>
 600    (shortcut: <keycap>C+e C+a</keycap>)
 601    is the same as <guimenuitem>Cut Append</guimenuitem> except it does not
 602    remove the selection from the buffer.
 603   </para>
 604  </sect2>
 605  <sect2 id="quick-copy"><title>Quick Copy</title>
 606   <para>
 607    The quick copy feature is usually found in Unix text editors.
 608    Quick copy is disabled by default, but it can be enabled in the
 609    <guibutton>Mouse</guibutton> pane of the
 610    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
 611    dialog box.
 612   </para>
 613   <para>
 614    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:
 615   </para>
 616   <itemizedlist>
 617    <listitem><para>
 618    Clicking the middle mouse button in the text area inserts the most recently
 619    selected text at the clicked location.
 620    If you only have a two-button mouse, you can click the left mouse button
 621    while holding down <keycap>Alt</keycap> instead of middle-clicking.
 622   </para></listitem>
 623   <listitem><para>
 624    Dragging with the middle mouse button
 625    creates a selection without moving the
 626    caret. As soon as the mouse button is released, the selected text is
 627    inserted at the caret position and the selection is deactivated.
 628    A message is shown in the status bar while text is being selected to
 629    remind you that this is not an ordinary selection.
 630   </para></listitem>
 631   <listitem><para>
 632    Holding down <keycap>Shift</keycap> while clicking the middle mouse
 633    button will duplicate text between the caret and the clicked location.
 634   </para></listitem>
 635   <listitem><para>
 636    Holding down <keycap>Control</keycap> while clicking the middle mouse
 637    button on a bracket will insert all text in that bracket's scope at the
 638    caret position.
 639   </para></listitem>
 640   </itemizedlist>
 641   <para>
 642    The most recently selected text is stored in the <filename>%</filename> register.
 643   </para>
 644   <para>
 645    If jEdit is being run under Java 2 version 1.4 on Unix, you will be
 646    able to transfer text with other X Windows applications using the
 647    quick copy feature. On other platforms and Java versions, the contents
 648    of the quick copy register are only accessible from within jEdit.
 649   </para>
 650  </sect2>
 651  <sect2 id="registers"><title>General Register Commands</title>
 652   <para>
 653    These commands require more keystrokes than the two methods shown above,
 654    but they can operate on any register, allowing an arbitrary number of
 655    text chunks to be retained at a time.
 656   </para>
 657   <para>
 658    Each command prompts for a single-character register name to be entered
 659    after being invoked.
 660    Pressing <keycap>ESCAPE</keycap> instead of specifying a register name
 661    cancels the operation.
 662   </para>
 663   <para>
 664    Note that the content of registers other than the clipboard and
 665    quick copy register are automatically saved between jEdit sessions.
 666   </para>
 667   <para>
 668    <guimenu>Edit</guimenu>&gt;<guisubmenu>More Clipboard</guisubmenu>&gt;<guimenuitem>Cut
 669    to Register</guimenuitem>
 670    (shortcut: <keycap>C+r C+x <replaceable>key</replaceable></keycap>)
 671    stores the selected text in the specified
 672    register, removing it from the buffer.
 673   </para>
 674   <para>
 675    <guimenu>Edit</guimenu>&gt;<guisubmenu>More Clipboard</guisubmenu>&gt;<guimenuitem>Copy
 676    to Register</guimenuitem>
 677    (shortcut: <keycap>C+r C+c <replaceable>key</replaceable></keycap>)
 678    stores the selected text in the specified
 679    register, leaving it in the buffer.
 680   </para>
 681   <para>
 682    <guimenu>Edit</guimenu>&gt;<guisubmenu>More Clipboard</guisubmenu>&gt;<guimenuitem>Cut
 683    Append to Register</guimenuitem>
 684    (shortcut: <keycap>C+r C+u <replaceable>key</replaceable></keycap>)
 685    adds the selected text to the existing contents of the specified
 686    register, and removes it from the buffer.
 687   </para>
 688   <para>
 689    <guimenu>Edit</guimenu>&gt;<guisubmenu>More Clipboard</guisubmenu>&gt;<guimenuitem>Copy
 690    Append to Register</guimenuitem>
 691    (shortcut: <keycap>C+r C+a <replaceable>key</replaceable></keycap>)
 692    adds the selected text to the existing contents of the specified
 693    register, without removing it from the buffer.
 694   </para>
 695   <para>
 696    <guimenu>Edit</guimenu>&gt;<guisubmenu>More Clipboard</guisubmenu>&gt;<guimenuitem>Paste
 697    from Register</guimenuitem>
 698    (shortcut: <keycap>C+r C+v <replaceable>key</replaceable></keycap>) 
 699    replaces the selection with the
 700    contents of the specified register.
 701   </para>
 702   <para>
 703    The following three commands display dialog boxes instead of prompting for a
 704    register name.
 705   </para>
 706   <para>
 707    <guimenu>Edit</guimenu>&gt;<guisubmenu>More Clipboard</guisubmenu>&gt;<guimenuitem>Paste Previous</guimenuitem>
 708    (shortcut: <keycap>C+e C+v</keycap>)
 709    displays a dialog box listing the 20 most recently copied and
 710    pasted text strings.
 711   </para>
 712   <para>
 713    <guimenu>Edit</guimenu>&gt;<guisubmenu>More Clipboard</guisubmenu>&gt;<guimenuitem>Paste Deleted</guimenuitem>
 714    (shortcut: <keycap>C+e C+y</keycap>) is not really a register command; it
 715    displays a dialog box listing the 20 most recently deleted text strings.
 716   </para>
 717   <para>
 718    <guimenu>Edit</guimenu>&gt;<guisubmenu>More Clipboard</guisubmenu>&gt;<guimenuitem>View
 719    Registers</guimenuitem> displays a dialog box for
 720    viewing register contents, including the clipboard and the quick copy.
 721   </para>
 722  </sect2>
 723 </sect1>
 724 <sect1 id="markers"><title>Markers</title>
 725  <para>
 726   A <firstterm>marker</firstterm> is a pointer to a specific location within
 727   a buffer, which may or may not have a single-character <firstterm>shortcut</firstterm> associated with it.
 728   Markers are persistent; they are saved to
 729   <filename>.<replaceable>filename</replaceable>.marks</filename>, where
 730   <filename><replaceable>filename</replaceable></filename> is the name of the
 731   buffer. (The dot prefix
 732   makes the markers file hidden on Unix systems.) Marker
 733   saving can be
 734   disabled in the <guibutton>General</guibutton> pane of the
 735   <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
 736   dialog box; see <xref linkend="general-pane" />.
 737  </para>
 738  <para>
 739   <guimenu>Markers</guimenu>&gt;<guimenuitem>Add/Remove Marker</guimenuitem>
 740   (shortcut: <keycap>C+e C+m</keycap>) adds a
 741   marker without a shortcut pointing to the current line. If a marker is
 742   already set on the current line, the marker is removed instead.
 743   If text is selected,
 744   markers are added to the first and last line of each selection.
 745  </para>
 746  <para>
 747   Markers are listed in the <guimenu>Markers</guimenu> menu; selecting a marker
 748   from this menu will move the caret to its location.
 749  </para>
 750  <para>
 751   <guimenu>Markers</guimenu>&gt;<guimenuitem>Go to Previous
 752   Marker</guimenuitem>
 753   (shortcut: <keycap>C+e C+COMMA</keycap>) goes
 754   to the marker immediately before the caret position.
 755  </para>
 756  <para>
 757   <guimenu>Markers</guimenu>&gt;<guimenuitem>Go to Next Marker</guimenuitem>
 758   (shortcut: <keycap>C+e C+PERIOD</keycap>)
 759   goes to the marker immediately after the caret position.
 760  </para>
 761  <para>
 762   <guimenu>Markers</guimenu>&gt;<guimenuitem>Remove All Markers</guimenuitem>
 763   removes all markers set in the current buffer.
 764  </para>
 765  <para>Markers with shortcuts allow for quicker keyboard-based navigation.
 766   The following commands all prompt for a single-character shortcut when
 767   invoked. Pressing <keycap>ESCAPE</keycap>
 768   instead of specifying a shortcut will cancel the operation.
 769  </para>
 770  <para>
 771   <guimenu>Markers</guimenu>&gt;<guimenuitem>Add Marker With
 772   Shortcut</guimenuitem>
 773   (shortcut: <keycap>C+t <replaceable>key</replaceable></keycap>) adds a marker with the
 774   specified shortcut. If marker with that shortcut
 775   already exists, it will remain in the buffer but lose its shortcut.
 776  </para>
 777  <para>
 778   <guimenu>Markers</guimenu>&gt;<guimenuitem>Go to Marker</guimenuitem>
 779   (shortcut: <keycap>C+y <replaceable>key</replaceable></keycap>) moves the caret to
 780   the location of the marker with the specified shortcut.
 781  </para>
 782  <para>
 783   <guimenu>Markers</guimenu>&gt;<guimenuitem>Select to Marker</guimenuitem>
 784   (shortcut: <keycap>C+u <replaceable>key</replaceable></keycap>) creates a selection from
 785   the caret location to the marker with the specified shortcut.
 786  </para>
 787  <para>
 788   <guimenu>Markers</guimenu>&gt;<guimenuitem>Swap Caret and
 789   Marker</guimenuitem> (shortcut: <keycap>C+k <replaceable>key</replaceable></keycap>)
 790   moves the caret to the location of the marker with the specified shortcut,
 791   and moves the marker to the former caret position. Invoke
 792   this command multiple times to flip between two locations in the buffer.
 793  </para>
 794  <para>
 795   Lines which contain markers are indicated in the gutter with a highlight.
 796   Moving the mouse over the highlight displays a tool tip showing the marker's
 797   shortcut, if it has one. See <xref linkend="overview" /> for information
 798   about the gutter.
 799  </para>
 800 </sect1>
 801 <sect1 id="search-replace"><title>Search and Replace</title>
 802  <sect2><title>Searching For Text</title>
 803   <para>
 804    <guimenu>Search</guimenu>&gt;<guimenuitem>Find</guimenuitem> (shortcut:
 805    <keycap>C+f</keycap>) displays
 806    the search and replace dialog box.
 807   </para>
 808   <para>
 809    The search string can be entered in the <guibutton>Search for</guibutton>
 810    text field. This text field remembers previously entered strings; see
 811    <xref linkend="history" /> for details.
 812   </para>
 813   <para>
 814    If text was selected in the text area and the selection
 815    does not span a line break, the selected text becomes the default search
 816    string.
 817   </para>
 818   <para>
 819    If the selection spans a line break, the
 820    <guibutton>Search in Selection</guibutton>
 821    and <guibutton>HyperSearch</guibutton>
 822    buttons will be pre-selected, and the search string field will be
 823    initially blank. (See <xref linkend="hypersearch"/> for information about
 824    the HyperSearch feature.)
 825    <!-- Note that finding the next or previous
 826    occurrence cannot be constrained to a selected range; only
 827    replacement and HyperSearch can be (see <xref linkend="hypersearch" />). -->
 828   </para>
 829   <para>
 830    Selecting the <guibutton>Ignore
 831    case</guibutton> check box makes the search case insensitive -
 832    for example, searching for
 833    <quote>Hello</quote> will match <quote>hello</quote>, <quote>HELLO</quote>
 834    and <quote>HeLlO</quote>.
 835   </para>
 836   <para>
 837    Selecting the <guibutton>Regular expressions</guibutton> check
 838    box allows a regular expression to be used in the search string. Regular
 839    expressions can
 840    match inexact sequences of text that optionally span more than one line.
 841    Regular expression syntax is described in
 842    <xref linkend="regexps" />.
 843   </para>
 844   <para>
 845    The <guibutton>Backward</guibutton> and <guibutton>Forward</guibutton>
 846    buttons specify the search direction.
 847    Note that regular expressions can only be used when
 848    searching in a forward direction.
 849   </para>
 850   <para>
 851    Clicking <guibutton>Find</guibutton> will locate the next occurrence of
 852    the search string (or previous occurrence, if
 853    searching backwards). If the
 854    <guibutton>Keep dialog</guibutton> check box is selected, the dialog box
 855    will remain open after the search string has been located; otherwise,
 856    it will close.
 857   </para>
 858   <para>
 859    If no occurrences could be found and the
 860    <guibutton>Auto wrap</guibutton> check box is selected, the search will
 861    automatically restart from the beginning of the buffer (or the end, if
 862    searching backwards).
 863    If <guibutton>Auto wrap</guibutton> is not selected, a confirmation dialog
 864    box is shown before restarting the search.
 865   </para>
 866   <para>
 867    <guimenu>Search</guimenu>&gt;<guimenuitem>Find Next</guimenuitem> (shortcut:
 868    <keycap>C+g</keycap>) locates the
 869    next occurrence of the most recent search string without displaying the
 870    search and replace dialog box.
 871   </para>
 872   <para>
 873    <guimenu>Search</guimenu>&gt;<guimenuitem>Find Previous</guimenuitem>
 874    (shortcut: <keycap>C+h</keycap>)
 875    locates the previous occurrence of the most recent search string without
 876    displaying the search and replace dialog box.
 877   </para>
 878  </sect2>
 879  <sect2><title>Replacing Text</title>
 880   <para>
 881    The replace string text field of the search dialog
 882    remembers previously entered strings;
 883    see <xref linkend="history" /> for details.
 884   </para>
 885   <para>
 886    Clicking <guibutton>Replace &amp; Find</guibutton> will perform a
 887    replacement in the current selection and locate the next occurrence of the
 888    search string. Clicking <guibutton>Replace All</guibutton> will replace all
 889    occurrences of the search string with the replacement string in the current
 890    search scope (which is either the selection, the current buffer, or a set of
 891    buffers, as specified in the search and replace dialog box).
 892   </para>
 893   <para>
 894    Occurrences of the search string can be replaced with either a replacement
 895    string, or the return value of a BeanShell script snippet. Two radio buttons
 896    in the search and replace dialog box select between the two replacement
 897    modes, which are described in detail below.
 898   </para>
 899   <sect3><title>Text Replace</title>
 900    <para>
 901     If the <guibutton>Text</guibutton> button is selected,
 902     the search string is simply replaced with the replacement
 903     string.
 904    </para>
 905    <para>
 906     If regular expressions are enabled, positional parameters
 907     (<literal>$0</literal>, <literal>$1</literal>, <literal>$2</literal>, and so
 908     on) can be used to insert the contents of matched subexpressions in the
 909     replacement string; see <xref linkend="regexps" /> for more information.
 910    </para>
 911    <para>
 912     If the search is case-insensitive, jEdit attempts to modify the
 913     case of the replacement string to match that of the particular instance
 914     of the search string being replaced. For example, searching
 915     for <quote>label</quote> and replacing it with <quote>text</quote>, will
 916     perform the following replacements:
 917    </para>
 918    <itemizedlist>
 919     <listitem><para><quote>String label</quote> would become <quote>String text</quote>
 920     </para></listitem>
 921     <listitem><para><quote>setLabel</quote> would become <quote>setText</quote>
 922     </para></listitem>
 923     <listitem><para><quote>DEFAULT_LABEL</quote> would become <quote>DEFAULT_TEXT</quote>
 924     </para></listitem>
 925    </itemizedlist>
 926   </sect3>
 927   <sect3><title>BeanShell Replace</title>
 928    <para>
 929     In BeanShell replacement mode, the search string is replaced with the return
 930     value of a BeanShell snippet. The following predefined variables can be
 931     referenced in the snippet:
 932    </para>
 933    <itemizedlist><listitem><para><varname>_0</varname> -- the text to be
 934    replaced</para>
 935    </listitem><listitem><para><varname>_1</varname> - <varname>_9</varname> --
 936    if regular expressions are enabled, these contain the values of matched
 937    subexpressions.
 938    </para></listitem></itemizedlist>
 939    <para>
 940     BeanShell syntax and features are covered in great detail in
 941     <xref linkend="writing-macros-part" />, but here are some examples:
 942    </para>
 943    <informalexample>
 944     <para>
 945      To replace each occurrence of <quote>Windows</quote> with <quote>Linux</quote>,
 946      and each occurrence of <quote>Linux</quote> with <quote>Windows</quote>,
 947      search for the following regular expression:
 948     </para>
 949     <programlisting>(Windows|Linux)</programlisting>
 950     <para>
 951      Replacing it with the following BeanShell snippet:
 952     </para>
 953     <programlisting>_1.equals("Windows") ? "Linux" : "Windows"</programlisting>
 954    </informalexample>
 955    <informalexample>
 956     <para>
 957      To convert all HTML tags to lower case, search
 958      for the following regular expression:
 959     </para>
 960     <programlisting><![CDATA[<\S+]]></programlisting>
 961     <para>
 962      Replacing it with the following BeanShell snippet:
 963     </para>
 964     <programlisting><![CDATA[_0.toLowerCase()]]></programlisting>
 965    </informalexample>
 966    <informalexample>
 967     <para>
 968      To replace arithmetic expressions contained in curly braces with the
 969      result of evaluating the expression,
 970      search for the following regular expression:
 971     </para>
 972     <programlisting><![CDATA[\{(.+?)\}]]></programlisting>
 973     <para>
 974      Replacing it with the following BeanShell snippet:
 975     </para>
 976     <programlisting><![CDATA[eval(_1)]]></programlisting>
 977    </informalexample>
 978    <para>
 979     These examples only scratch the surface; the possibilities are endless.
 980    </para>
 981   </sect3>
 982  </sect2>
 983  <sect2 id="hypersearch"><title>HyperSearch</title>
 984   <para>
 985    If the <guibutton>HyperSearch</guibutton> check box in the search and
 986    replace dialog box is selected, clicking <guibutton>Find</guibutton>
 987    lists all occurrences of the search string, instead of locating the next
 988    match.
 989   </para>
 990   <para>
 991    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" />.
 992   </para>
 993   <para>
 994    If the <guibutton>Multiple results</guibutton> check box is selected in
 995    the results window, past search results are retained.
 996   </para>
 997   <para>
 998    Running searches can be stopped in the
 999    <guimenu>Utilities</guimenu>&gt;<guisubmenu>Troubleshooting</guisubmenu>&gt;<guimenuitem>I/O Progress
1000    Monitor</guimenuitem> dialog box.
1001   </para>
1002  </sect2>
1003  <sect2><title>Multiple File Search</title>
1004   <para>
1005    Search and replace commands can be performed over an arbitrary set of files
1006    in one step. The set of files to search is selected with a set of buttons in
1007    the search dialog box.
1008   </para>
1009   <para>
1010    If the <guibutton>Current buffer</guibutton> button is selected, only the
1011    current buffer is searched. This is the default behavior.
1012   </para>
1013   <para>
1014    If the <guibutton>All buffers</guibutton> button is selected, all open
1015    buffers whose names match the glob pattern
1016    entered in the <guibutton>Filter</guibutton> text field will be searched.
1017    See <xref linkend="globs" /> for more information about glob patterns.
1018   </para>
1019   <para>
1020    If the <guibutton>Directory</guibutton> radio button is selected, all files
1021    contained in the specified directory whose names match the glob will be
1022    searched. The
1023    directory to search in can either be entered in the
1024    <guibutton>Directory</guibutton> text field, or chosen in a file selector
1025    dialog box by clicking the <guibutton>Choose</guibutton> button next to
1026    the field.
1027    If the <guibutton>Search subdirectories</guibutton> check box is selected,
1028    all subdirectories of the specified directory will also be searched. Keep
1029    in mind that searching through directories containing many files can take
1030    a long time.
1031   </para>
1032   <para>
1033    The <guibutton>Directory</guibutton> and <guibutton>Filter</guibutton>
1034    text fields remember previously entered strings; see <xref linkend="history" />
1035    for details.
1036   </para>
1037   <para>
1038    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>.
1039   </para>
1040   <para>
1041    Note that clicking the <guibutton>All Buffers</guibutton> or
1042    <guibutton>Directory</guibutton> radio buttons also selects the
1043    <guibutton>HyperSearch</guibutton> check box
1044    since that is what you would want, most of the time.
1045    However, the <guibutton>HyperSearch</guibutton> check box can be unchecked, for stepping through search results in multiple files one at a time.
1046   </para>
1047   <para>
1048    Two convenience commands are provided for performing multiple file searches.
1049   </para>
1050   <para>
1051    <guimenu>Search</guimenu>&gt;<guimenuitem>Search in Open
1052    Buffers</guimenuitem> (shortcut: <keycap>C+e C+b</keycap>) displays
1053    the search dialog box and selects the <guibutton>All
1054    buffers</guibutton> button.
1055   </para>
1056   <para>
1057    <guimenu>Search</guimenu>&gt;<guimenuitem>Search in Directory</guimenuitem>
1058    (shortcut: <keycap>C+e C+d</keycap>) displays
1059    the search dialog box and selects the
1060    <guibutton>Directory</guibutton> button.
1061   </para>
1062  </sect2>
1063  <sect2 id="search-bar"><title>The Search Bar</title>
1064   <para>
1065    The search bar feature provides a convenient way to search in the current
1066    buffer without
1067    opening the search dialog box. The search bar does not support replacement or multiple file search. Previously entered strings can be recalled in the
1068    search bar with the <keycap>Up</keycap> and <keycap>Down</keycap> arrow
1069    keys; see <xref linkend="history" />.
1070   </para>
1071   <para>
1072    By default, the search bar remains hidden until one of the quick search
1073    commands (described below) is invoked; however you can choose to have it
1074    always visible in the <guibutton>View</guibutton> pane of the
1075    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
1076    dialog box; see <xref linkend="view-pane"/>.
1077   </para>
1078   <para>
1079    <guimenu>Search</guimenu>&gt;<guimenuitem>Incremental Search Bar</guimenuitem>
1080    (shortcut: <keycap>C+COMMA</keycap>)
1081    displays the search bar if necessary, and gives it keyboard focus.
1082    If this command is invoked while there is a selection, the selection is
1083    placed in the search string field.
1084   </para>
1085   <para>
1086    <guimenu>Search</guimenu>&gt;<guimenuitem>Incremental Search
1087    for Word</guimenuitem>
1088    (shortcut: <keycap>A+COMMA</keycap>)
1089    behaves like the above command except it places the word at the caret in
1090    the search string field.
1091   </para>
1092   <para>
1093    Unless the <guibutton>HyperSearch</guibutton> check box is selected, the
1094    search bar will perform an <firstterm>incremental search</firstterm>.
1095    In incremental search mode, the first occurrence of the search
1096    string is located in the current buffer as it is being typed.
1097    Pressing <keycap>ENTER</keycap> and <keycap>S+ENTER</keycap>
1098    searches for the next and previous occurrence, respectively.
1099    Once the desired occurrence has been located, pressing <keycap>ESCAPE</keycap>
1100    returns keyboard focus to the text area. Unless the search bar is set to be
1101    always visible (see above), pressing <keycap>ESCAPE</keycap> will also hide
1102    the search bar.
1103   </para>
1104   <note>
1105    <para>
1106     Incremental searches cannot be not recorded in macros. If your macro
1107     needs to perform a search, use the
1108     search and replace dialog box instead. See <xref linkend="using-macros" />
1109     for information about macros.
1110    </para>
1111   </note>
1112   <para>
1113    <guimenu>Search</guimenu>&gt;<guimenuitem>HyperSearch Bar</guimenuitem>
1114    (shortcut: <keycap>C+PERIOD</keycap>)
1115    displays the search bar if necessary, gives it keyboard focus,
1116    and selects the <guibutton>HyperSearch</guibutton> check box.
1117    If this command is invoked while there is a selection, the selected text
1118    will be searched for immediately and the search bar will not be shown.
1119   </para>
1120   <para>
1121    If the <guibutton>HyperSearch</guibutton> check box is
1122    selected, pressing <keycap>Enter</keycap> in the search string field
1123    will perform a HyperSearch in the current buffer.
1124   </para>
1125   <para>
1126    <guimenu>Search</guimenu>&gt;<guimenuitem>HyperSearch
1127    for Word</guimenuitem>
1128    (shortcut: <keycap>A+PERIOD</keycap>)
1129    performs a HyperSearch for the word at the caret. This command does not
1130    show the search bar or give it keyboard focus.
1131   </para>
1132  </sect2>
1133 </sect1>