PageRenderTime 84ms CodeModel.GetById 65ms app.highlight 10ms RepoModel.GetById 1ms app.codeStats 1ms

/jEdit/tags/jedit-4-2-pre4/doc/users-guide/text-edit.xml

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