PageRenderTime 120ms CodeModel.GetById 76ms app.highlight 19ms RepoModel.GetById 15ms app.codeStats 1ms

/jEdit/tags/jedit-4-0-pre3/doc/users-guide/text-edit.xml

#
XML | 974 lines | 971 code | 1 blank | 2 comment | 0 complexity | 747d4c8d0990dde51fc94f6829b5be4b MD5 | raw file
  1<!-- jEdit buffer-local properties: -->
  2<!-- :tabSize=1:indentSize=1:noTabs=true: -->
  3
  4<chapter id="editing"><title>Editing Text</title>
  5 <sect1 id="caret"><title>Moving The Caret</title>
  6  <para>
  7   The most direct way to move the caret is to click the
  8   mouse at the desired location in the text area. It can also be moved
  9   using the keyboard.
 10  </para>
 11  <para>
 12   The <keycap>Left</keycap>, <keycap>Right</keycap>, <keycap>Up</keycap> and
 13   <keycap>Down</keycap> keys move the caret in the respective direction, and
 14   the <keycap>Page Up</keycap> and <keycap>Page Down</keycap> keys move the
 15   caret up and down one screenful, respectively.
 16  </para>
 17  <para>
 18   When pressed once, the <keycap>Home</keycap> key moves the caret to the first
 19   non-whitespace character of the current line. Pressing it a second time
 20   moves the caret to the beginning of the line. Pressing it a third time
 21   moves the caret to the first visible line.
 22  </para>
 23  <para>
 24   The <keycap>End</keycap> key behaves in a
 25   similar manner, going to the last non-whitespace character, the end of
 26   the line, and finally to the last visible line.
 27  </para>
 28  <para>
 29   If there is a selection, <keycap>Home</keycap> and <keycap>End</keycap>
 30   behave the same as above, except that instead of operating on the current
 31   line, they move the caret to the first and last lines of the selection,
 32   respectively.
 33  </para>
 34  <para>
 35   <keycombo><keycap>Control</keycap><keycap>Home</keycap></keycombo> and
 36   <keycombo><keycap>Control</keycap><keycap>End</keycap></keycombo> move the
 37   caret to the beginning and end of the buffer.
 38  </para>
 39  <para>
 40   More advanced caret movement is covered in
 41   <xref linkend="words" />, <xref linkend="lines" /> and
 42   <xref linkend="paragraphs" />.
 43  </para>
 44 </sect1>
 45 <sect1 id="selection"><title>Selecting Text</title>
 46  <para>
 47   A <firstterm>selection</firstterm> is a a block of text marked for further
 48   manipulation. Unlike many other applications, jEdit supports both
 49   range and rectangular selections, and several chunks of text can be
 50   selected simultaneously.
 51  </para>
 52  <para>
 53   Dragging the mouse creates a range selection from where the mouse was
 54   pressed to where it was released.
 55   Holding down <keycap>Shift</keycap> while clicking a location in the
 56   buffer will create a selection from the caret position to the clicked
 57   location.
 58  </para>
 59  <para>
 60   Holding down <keycap>Shift</keycap> in addition to a caret movement key
 61   (<keycap>Left</keycap>, <keycap>Up</keycap>, <keycap>Home</keycap>, etc) will
 62   extend the selection in the specified direction. If no selection exists, one
 63   will be created.
 64  </para>
 65  <para>
 66   <guimenu>Edit</guimenu>&gt;<guimenuitem>Select All</guimenuitem> (shortcut:
 67   <keycombo><keycap>Control</keycap><keycap>A</keycap></keycombo>) selects the
 68   entire buffer.
 69  </para>
 70  <para>
 71   <guimenu>Edit</guimenu>&gt;<guimenuitem>Select None</guimenuitem> (shortcut:
 72   <keycap>Escape</keycap>) deactivates the selection.
 73  </para>
 74  <sect2><title>Rectangular Selection</title>
 75   <para>
 76    Holding down <keycap>Control</keycap> and dragging will create a rectangular
 77    selection. Holding down
 78    <keycap>Shift</keycap> and <keycap>Control</keycap> while clicking a location in
 79    the buffer will create a rectangular selection from the caret position to
 80    the clicked location.
 81   </para>
 82   <para>
 83    It is possible to select a rectangle with zero width but non-zero height.
 84    This can be used to insert a new column between two existing
 85    columns, for example. Such zero-width selections are shown as a thin
 86    vertical line.
 87   </para>
 88   <para>
 89    Rectangles can be deleted, copied, pasted, and operated on using ordinary
 90    editing commands.
 91   </para>
 92   <note>
 93    <para>
 94     Rectangular selections are implemented using character offsets,
 95     not absolute screen positions, so they might not behave as you might
 96     expect if a proportional-width font is being used, or hard tabs are
 97     enabled. For information about changing the font used in the text
 98     area, see <xref linkend="global-opts" />. For more information about
 99     hard and soft tabs, see <xref linkend="soft-tabs" />.
100    </para>
101   </note>
102  </sect2>
103  <sect2 id="multi-select"><title>Multiple Selection</title>
104   <para>
105    Pressing <keycombo><keycap>Control</keycap> <keycap>\</keycap></keycombo>
106    turns multiple selection mode on and
107    off. In multiple selection mode, multiple fragments of text can be selected
108    and operated on simultaneously, and the text <literal>multi</literal> is shown
109    in the status bar.
110   </para>
111   <para>
112    While multiple selection mode is active, you can click and drag the mouse
113    to reposition the caret and create new selections.
114   </para>
115   <para>
116    Various jEdit commands behave differently with multiple selections:
117   </para>
118   <itemizedlist>
119    <listitem><para>Commands that copy text place the contents of
120    each selection, separated by line breaks, in the specified register. Note
121    that the selections are appended in the order they were created, not the
122    order they appear in the buffer. For example, if you select a chunk of
123    text near the end of the buffer, another near the beginning, then invoke
124    <guimenuitem>Copy</guimenuitem>, the clipboard will contain the later chunk,
125    followed by a line break, followed by the earlier chunk.
126    </para></listitem>
127    <listitem><para>Commands that insert (or paste) text replace each selection
128    with the entire text that is being inserted.</para></listitem>
129    <listitem><para>Commands that filter text (such as <guimenuitem>Spaces to
130    Tabs</guimenuitem>, <guimenuitem>Range Comment</guimenuitem>, and even
131    <guimenuitem>Replace in Selection</guimenuitem>) operate on each selection,
132    in turn.</para></listitem>
133    <listitem><para>Line-based commands (such as <guimenuitem>Shift Indent
134    Left</guimenuitem>, <guimenuitem>Shift Indent Right</guimenuitem>, and
135    <guimenuitem>Line Comment</guimenuitem>) operate on each line that contains
136    at least one selection, in addition to the line containing the caret.
137    </para></listitem>
138    <listitem><para>Caret movement commands that would normally deactivate the
139    selection (such as the arrow keys, while <keycap>Shift</keycap> is not being
140    held down), move the caret, leaving the selection as-is.</para></listitem>
141    <listitem><para>Some older plugins may not support multiple selection at
142    all.</para></listitem>
143   </itemizedlist>
144   <para>
145    <guimenu>Edit</guimenu>&gt;<guimenuitem>Invert Selection</guimenuitem>
146    (shortcut: <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
147    <keycap>I</keycap>) selects a set of text chunks such that all text
148    that was formely part of a selection is now unselected, and all text that
149    wasn't, is selected.
150   </para>
151   <tip>
152    <para>
153     Deactivating multiple selection
154     mode while a fragmented selection exists will leave the selection in place,
155     but it will prevent you from making further fragmented selections.
156    </para>
157   </tip>
158  </sect2>
159 </sect1>
160 <sect1 id="entering-text"><title>Inserting and Deleting Text</title>
161  <para>
162   Text entered at the keyboard is inserted into the buffer. If
163   overwrite mode is on, one character is deleted from in
164   front of the caret position for every character that is inserted.
165   To activate overwrite mode, press <keycap>Insert</keycap>. The caret is
166   drawn as horizontal line while in overwrite
167   mode; the text <literal>ovr</literal> also appears in the status bar.
168  </para>
169  <para>
170   Inserting text while there is a selection will replace the selection
171   with the inserted text.
172  </para>
173  <para>
174   Inserting text at the end of a line beyond the wrap column will
175   automatically break the line
176   at the appropriate word boundary. The wrap column is indicated in the
177   text area as a faint blue line and its location (specified in number of
178   character positions from the left margin) can be changed in one of
179   several ways:
180  </para>
181  <itemizedlist>
182   <listitem><para>On a global or mode-specific
183   basis in the
184   <guibutton>Editing</guibutton> and <guibutton>Mode-Specific</guibutton> panes
185   of the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
186   dialog box; see <xref linkend="global-opts" />.</para></listitem>
187   <listitem><para>In the current buffer
188   for the duration of the editing session in the
189   <guimenu>Utilities</guimenu>&gt;<guimenuitem>Buffer Options</guimenuitem>
190   dialog box; see <xref linkend="buffer-opts" />.
191   </para></listitem>
192   <listitem><para>In the current buffer
193   for future editing sessions by placing
194   the following in one of the first 10 lines of the buffer, where
195   <replaceable>column</replaceable> is the desired wrap column position:
196   </para>
197   <screen>:maxLineLen=<replaceable>column</replaceable>:</screen>
198   </listitem>
199  </itemizedlist>
200  <para>
201   To disable word wrap completely, set the wrap column to 0 using any of the
202   above means.
203  </para>
204  <note>
205   <para>
206    Word wrap is implemented using character offsets, not screen
207    positions, so it might not behave like you expect if a
208    proportional-width font is being used. For information about
209    changing the font used in the text area, see <xref linkend="global-opts" />.
210   </para>
211  </note>
212  <para>
213   When inserting text, keep in mind that the <keycap>Tab</keycap> and
214   <keycap>Enter</keycap> keys might
215   not behave entirely like you expect because  of various indentation
216   features; see <xref linkend="indent" /> for details.
217  </para>
218  <para>
219   The simplest way to delete text is with the
220   <keycap>Backspace</keycap> and <keycap>Delete</keycap> keys. If nothing is
221   selected, they delete the character before or after the caret,
222   respectively. If a selection exists, both delete the
223   selection.
224  </para>
225  <para>
226   More advanced deletion commands are described in
227   <xref linkend="words" />, <xref linkend="lines" /> and
228   <xref linkend="paragraphs" />.
229  </para>
230 </sect1>
231 <sect1 id="undo-redo"><title>Undo and Redo</title>
232  <para>
233   <guimenu>Edit</guimenu>&gt;<guimenuitem>Undo</guimenuitem> (shortcut:
234   <keycombo><keycap>Control</keycap><keycap>Z</keycap></keycombo>) undoes the
235   effects of the most recent text editing command. For example, this can be
236   used to restore unintentionally deleted text. More complicated operations,
237   such as a search and replace, can also be undone. By default, the undo
238   queue remembers the last 100 edits; older edits are discarded.
239   The undo queue size can be changed in the <guibutton>Editing</guibutton> pane
240   of the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
241   Options</guimenuitem> dialog box.
242  </para>
243  <para>
244   <guimenu>Edit</guimenu>&gt;<guimenuitem>Redo</guimenuitem> (shortcut:
245   <keycombo><keycap>Control</keycap><keycap>R</keycap></keycombo>) goes forward
246   in the undo queue, redoing changes which were undone. For example, if some
247   text was inserted, <guimenuitem>Undo</guimenuitem> will remove it from the
248   buffer. <guimenuitem>Redo</guimenuitem> will insert it again.
249  </para>
250 </sect1>
251 <sect1 id="words"><title>Working With Words</title>
252  <para>
253   Holding down <keycap>Control</keycap> in addition to <keycap>Left</keycap> or
254   <keycap>Right</keycap> moves the caret a word at
255   a time. Holding down <keycap>Shift</keycap> and <keycap>Control</keycap>
256   in addition to <keycap>Left</keycap> or <keycap>Right</keycap> 
257   extends the selection a word at a time.
258  </para>
259  <para>
260   A single word can be selected by double-clicking with the mouse,
261   or using the
262   <guimenu>Edit</guimenu>&gt;<guisubmenu>Text</guisubmenu>&gt;<guimenuitem>Select
263   Word</guimenuitem> command (shortcut:
264   <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo> <keycap>W</keycap>).
265   A selection that begins and ends on word boundaries can be created by
266   double-clicking and dragging.
267  </para>
268  <para>
269   Pressing <keycap>Control</keycap> in addition to
270   <keycap>Backspace</keycap> or <keycap>Delete</keycap> deletes the word
271   before or after the caret, respectively.
272  </para>
273  <para>
274   <guimenu>Edit</guimenu>&gt;<guimenuitem>Word Count</guimenuitem>
275   displays a dialog box with the number of characters,
276   words and lines in the current buffer.
277  </para>
278  <para>
279   <guimenu>Edit</guimenu>&gt;<guimenuitem>Complete Word</guimenuitem> (shortcut:
280   <keycombo><keycap>Control</keycap><keycap>B</keycap></keycombo>) searches the
281   current buffer for possible completions of the current word.
282   This feature be used to avoid retyping
283   previously entered identifiers in program source, for example.
284  </para>
285  <para>
286   If there is only one completion, it will be inserted into the buffer
287   immediately.
288   If multiple completions were found, they will be listed in a popup below
289   the caret position. To insert a completion from the list, either click it
290   with the mouse,
291   or select it using the <keycap>Up</keycap> and <keycap>Down</keycap> keys and
292   press <keycap>Enter</keycap>. To close the popup without inserting a
293   completion, press <keycap>Escape</keycap>.
294  </para>
295 </sect1>
296 <sect1 id="lines"><title>Working With Lines</title>
297  <para>
298   An entire line can be selected by triple-clicking with the mouse,
299   or using the
300   <guimenu>Edit</guimenu>&gt;<guisubmenu>Text</guisubmenu>&gt;<guimenuitem>Select
301   Line</guimenuitem> command (shortcut:
302   <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo> <keycap>L</keycap>).
303   A selection that begins and ends on line boundaries can be created
304   by triple-clicking and dragging.
305  </para>
306  <para>
307   <guimenu>Edit</guimenu>&gt;<guimenuitem>Go to Line</guimenuitem> (shortcut:
308   <keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>) displays an
309   input dialog box and moves the caret to the specified line number.
310  </para>
311  <para>
312   <guimenu>Edit</guimenu>&gt;<guimenuitem>Select Line Range</guimenuitem>
313   (shortcut
314   <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
315   <keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo>)
316   selects all text between between two specified line numbers, inclusive.
317  </para>
318  <para>
319   <guimenu>Edit</guimenu>&gt;<guisubmenu>Text</guisubmenu>&gt;<guimenuitem>Join
320   Lines</guimenuitem> (shortcut:
321   <keycombo><keycap>Control</keycap><keycap>J</keycap></keycombo>)
322   removes any whitespace from the start of the next line and joins it with
323   the current line. For example, invoking <guimenuitem>Join Lines</guimenuitem>
324   on the first line of the following Java code:
325  </para>
326  <screen>new Widget(Foo
327       .createDefaultFoo());</screen>
328  <para>
329   Will change it to:
330  </para>
331  <screen>new Widget(Foo.createDefaultFoo());</screen>
332  <para>
333   <guimenu>Edit</guimenu>&gt;<guisubmenu>Text</guisubmenu>&gt;<guimenuitem>Delete
334   Line</guimenuitem>
335   (shortcut: <keycombo><keycap>Control</keycap><keycap>D</keycap></keycombo>)
336   deletes the current line.
337  </para>
338  <para>
339   <guimenu>Edit</guimenu>&gt;<guisubmenu>Text</guisubmenu>&gt;<guimenuitem>Delete
340   to Start Of Line</guimenuitem>
341   (shortcut:
342   <keycombo><keycap>Shift</keycap><keycap>Backspace</keycap></keycombo>)
343   deletes all text from the start of the current line to the caret.
344  </para>
345  <para>
346   <guimenu>Edit</guimenu>&gt;<guisubmenu>Text</guisubmenu>&gt;<guimenuitem>Delete
347   to End Of Line</guimenuitem>
348   (shortcut:
349   <keycombo><keycap>Shift</keycap><keycap>Delete</keycap></keycombo>) deletes
350   all text from the caret to the end of the current line.
351  </para>
352  <para>
353   <guimenu>Edit</guimenu>&gt;<guisubmenu>Text</guisubmenu>&gt;<guimenuitem>Remove
354   Trailing Whitespace</guimenuitem>
355   (shortcut: <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
356   <keycap>R</keycap>) removes all whitespace from the end of each selected line, or
357   the current line if there is no selection.
358  </para>
359 </sect1>
360 <sect1 id="paragraphs"><title>Working With Paragraphs</title>
361  <para>
362   As far as jEdit is concerned, <quote>paragraphs</quote> are delimited by
363   double newlines. This is also how <application>TeX</application>
364   defines a paragraph. Note that jEdit doesn't parse HTML files for
365   <quote>&lt;P&gt;</quote> tags, nor does it support paragraphs delimited only
366   by a leading indent.
367  </para>
368  <para>
369   Holding down <keycap>Control</keycap> in addition to <keycap>Up</keycap>
370   or <keycap>Down</keycap>
371   moves the caret to the previous and next paragraph, respectively.
372   As with other caret movement commands, holding down <keycap>Shift</keycap>
373   in addition to the above
374   extends the selection, a paragraph at a time.
375  </para>
376  <para>
377   <guimenu>Edit</guimenu>&gt;<guisubmenu>Text</guisubmenu>&gt;<guimenuitem>Select
378   Paragraph</guimenuitem> (shortcut:
379   <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
380   <keycap>P</keycap>)
381   selects the paragraph containing the caret.
382  </para>
383  <para>
384   <guimenu>Edit</guimenu>&gt;<guisubmenu>Text</guisubmenu>&gt;<guimenuitem>Delete
385   Paragraph</guimenuitem> (shortcut:
386   <keycombo><keycap>Control</keycap><keycap>E</keycap>
387   </keycombo> <keycap>D</keycap>)
388   deletes the paragraph containing the caret.
389  </para>
390  <para>
391   <guimenu>Edit</guimenu>&gt;<guisubmenu>Text</guisubmenu>&gt;<guimenuitem>Format
392   Paragraph</guimenuitem> (shortcut:
393   <keycombo><keycap>Control</keycap><keycap>E</keycap>
394   </keycombo> <keycap>F</keycap>) splits and joins lines in the current
395   paragraph to make them fit within the wrap column position. See
396   <xref linkend="entering-text" /> for information and word wrap and
397   changing the wrap column.
398  </para>
399 </sect1>
400 <sect1 id="scrolling"><title>Scrolling</title>
401  <para>
402   <guimenu>View</guimenu>&gt;<guisubmenu>Scrolling</guisubmenu>&gt;<guimenuitem>Scroll to
403   Current Line</guimenuitem> (shortcut:
404   <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
405   <keycombo><keycap>Control</keycap><keycap>J</keycap></keycombo>) centers the
406   line containing the caret on the screen.
407  </para>
408  <para>
409   <guimenu>View</guimenu>&gt;<guisubmenu>Scrolling</guisubmenu>&gt;<guimenuitem>Center Caret
410   on Screen</guimenuitem> (shortcut:
411   <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
412   <keycombo><keycap>Control</keycap><keycap>I</keycap></keycombo>)
413   moves the caret to the
414   line in the middle of the screen.
415  </para>
416  <para>
417   <guimenu>View</guimenu>&gt;<guisubmenu>Scrolling</guisubmenu>&gt;<guimenuitem>Line
418   Scroll Up</guimenuitem> (shortcut:
419   <keycombo><keycap>Control</keycap><keycap>'</keycap></keycombo>)
420   scrolls the text area up by one line.
421  </para>
422  <para>
423   <guimenu>View</guimenu>&gt;<guisubmenu>Scrolling</guisubmenu>&gt;<guimenuitem>Line
424   Scroll Down</guimenuitem> (shortcut:
425   <keycombo><keycap>Control</keycap><keycap>/</keycap></keycombo>) scrolls the
426   text area down by one line.
427  </para>
428  <para>
429   <guimenu>View</guimenu>&gt;<guisubmenu>Scrolling</guisubmenu>&gt;<guimenuitem>Page
430   Scroll Up</guimenuitem> (shortcut:
431   <keycombo><keycap>Alt</keycap><keycap>'</keycap></keycombo>) scrolls the text
432   area up by one screenful.
433  </para>
434  <para>
435   <guimenu>View</guimenu>&gt;<guisubmenu>Scrolling</guisubmenu>&gt;<guimenuitem>Page
436   Scroll Down</guimenuitem> (shortcut:
437   <keycombo><keycap>Alt</keycap><keycap>/</keycap></keycombo>) scrolls the text
438   area down by one screenful.
439  </para>
440  <para>
441   The above scrolling commands differ from the caret movement commands
442   in that they don't actually move the caret; they just change the
443   scroll bar position.
444  </para>
445  <para>
446   <guimenu>View</guimenu>&gt;<guisubmenu>Scrolling</guisubmenu>&gt;<guimenuitem>Synchronized
447   Scrolling</guimenuitem> is a check box menu item, that if selected,
448   forces scrolling performed in one text area to be propagated to all
449   other text areas in the current view. Invoking the command a second
450   time disables the feature.
451  </para>
452 </sect1>
453 <sect1 id="text-transfer"><title>Transferring Text</title>
454  <para>
455   jEdit provides a rich set of commands for moving and copying text
456   using <firstterm>registers</firstterm>. A register is a holding
457   area with a single-character name that can hold once piece of text at a time.
458   Registers are global to the editor; all buffers share the same set. With the
459   exception of the clipboard, register contents are only accessable inside
460   jEdit.
461  </para>
462  <para>
463   jEdit has three sets of commands for working with registers.
464   The <quote>quick copy</quote> and system clipboard features allow easy
465   access to two specific registers. A third set of commands allows access to
466   all other registers.
467  </para>
468  <sect2><title>Quick Copy</title>
469   <para>
470    Holding down the <keycap>Alt</keycap> key and clicking the left mouse button
471    in the text area inserts the most recently
472    selected text at the clicked location. If you have a three-button mouse, you
473    can simply click the middle mouse button, without holding down
474    <keycap>Alt</keycap>.
475   </para>
476   <para>
477    Internally, this is implemented by storing the most recently selected text
478    in the <filename>%</filename> register (recall that registers have
479    single-character names).
480   </para>
481   <sidebar><title>X Windows primary selection</title>
482    <para>
483     If jEdit is being run under Java 2 version 1.4 on Unix, you will be
484     able to transfer text with other X Windows applications using the
485     quick copy feature. On other platforms and Java versions, the contents
486     of the quick copy register are only accessable from within jEdit.
487    </para>
488   </sidebar>
489  </sect2>
490  <sect2><title>The System Clipboard</title>
491   <para>
492    Quick copy is very useful in many situations, but it has a number of
493    drawbacks; it requires the use of the mouse, it cannot be used to replace an
494    existing selection, and it cannot be used to transfer text between different
495    applications (unless you are using Java 2 version 1.4 on Unix).
496   </para>
497   <para>
498    The system clipboard, internally known as the <filename>$</filename>
499    register, does not have these limitations, but can be slightly less
500    convinient to use.
501   </para>
502   <para>
503    <guimenu>Edit</guimenu>&gt;<guimenuitem>Cut</guimenuitem>
504    (shortcut: <keycombo><keycap>Control</keycap><keycap>X</keycap></keycombo>)
505    places the selected text in the clipboard and removes it from the buffer.
506   </para>
507   <para>
508    <guimenu>Edit</guimenu>&gt;<guimenuitem>Copy</guimenuitem>
509    (shortcut: <keycombo><keycap>Control</keycap><keycap>C</keycap></keycombo>)
510    places the selected text in the clipboard and leaves it in the buffer.
511   </para>
512   <para>
513    <guimenu>Edit</guimenu>&gt;<guimenuitem>Cut Append</guimenuitem>
514    (shortcut: <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
515    <keycombo><keycap>Control</keycap><keycap>U</keycap></keycombo>)
516    appends the selected text to the clipboard, then removes it from the
517    buffer. After this command has been invoked, the clipboard will consist of
518    the former clipboard contents, followed by a newline, followed by the
519    selected text.
520   </para>
521   <para>
522    <guimenu>Edit</guimenu>&gt;<guimenuitem>Copy Append</guimenuitem>
523    (shortcut: <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
524    <keycombo><keycap>Control</keycap><keycap>A</keycap></keycombo>)
525    appends the selected text to the clipboard, and leaves it in the
526    buffer. After this command has been invoked, the clipboard will consist of
527    the former clipboard contents, followed by a newline, followed by the
528    selected text.
529   </para>
530   <para>
531    <guimenu>Edit</guimenu>&gt;<guimenuitem>Paste</guimenuitem>
532    (shortcut: <keycombo><keycap>Control</keycap><keycap>V</keycap></keycombo>)
533    inserts the clipboard contents in place of the selection (or at the
534    caret position, if there is no selection).
535   </para>
536  </sect2>
537  <sect2><title>General Register Commands</title>
538   <para>
539    These commands are slightly less convinient to use than the two methods of
540    transferring text described above, but have the advantage that they allow
541    any number of strings to be copied simultaneously.
542   </para>
543   <para>
544    These commands all expect a single-character
545    register name to be typed at the keyboard after the command is
546    invoked, and subsequently operate on that register.
547    Pressing <keycap>Escape</keycap> instead of specifying a register name
548    will cancel the operation.
549   </para>
550   <para>
551    <guimenu>Edit</guimenu>&gt;<guisubmenu>Registers</guisubmenu>&gt;<guimenuitem>Cut
552    to Register</guimenuitem>
553    (shortcut: <keycombo><keycap>Control</keycap><keycap>R</keycap></keycombo>
554    <keycombo><keycap>Control</keycap><keycap>X</keycap></keycombo>
555    <keycap><replaceable>key</replaceable></keycap>)
556    stores the selected text in the specified
557    register, removing it from the buffer.
558   </para>
559   <para>
560    <guimenu>Edit</guimenu>&gt;<guisubmenu>Registers</guisubmenu>&gt;<guimenuitem>Copy
561    to Register</guimenuitem>
562    (shortcut: <keycombo><keycap>Control</keycap><keycap>R</keycap></keycombo>
563    <keycombo><keycap>Control</keycap><keycap>C</keycap></keycombo>
564    <keycap><replaceable>key</replaceable></keycap>)
565    stores the selected text in the specified
566    register, leaving it in the buffer.
567   </para>
568   <para>
569    <guimenu>Edit</guimenu>&gt;<guisubmenu>Registers</guisubmenu>&gt;<guimenuitem>Cut
570    Append to Register</guimenuitem>
571    (shortcut: <keycombo><keycap>Control</keycap><keycap>R</keycap></keycombo>
572    <keycombo><keycap>Control</keycap><keycap>U</keycap></keycombo>
573    <keycap><replaceable>key</replaceable></keycap>)
574    adds the selected text to the existing contents of the specified
575    register, and removes it from the buffer.
576   </para>
577   <para>
578    <guimenu>Edit</guimenu>&gt;<guisubmenu>Registers</guisubmenu>&gt;<guimenuitem>Copy
579    Append to Register</guimenuitem>
580    (shortcut: <keycombo><keycap>Control</keycap><keycap>R</keycap></keycombo>
581    <keycombo><keycap>Control</keycap><keycap>A</keycap></keycombo>
582    <keycap><replaceable>key</replaceable></keycap>)
583    adds the selected text to the existing contents of the specified
584    register, without removing it from the buffer.
585   </para>
586   <para>
587    <guimenu>Edit</guimenu>&gt;<guisubmenu>Registers</guisubmenu>&gt;<guimenuitem>Paste
588    from Register</guimenuitem>
589    (shortcut: <keycombo><keycap>Control</keycap><keycap>R</keycap></keycombo>
590    <keycombo><keycap>Control</keycap><keycap>V</keycap></keycombo>
591    <keycap><replaceable>key</replaceable></keycap>) 
592    replaces the selection with the
593    contents of the specified register.
594   </para>
595   <para>
596    <guimenu>Edit</guimenu>&gt;<guimenuitem>Paste Previous</guimenuitem>
597    (shortcut:
598    <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
599    <keycombo><keycap>Control</keycap><keycap>V</keycap></keycombo>)
600    displays a dialog box listing recently copied and
601    pasted text. By default, the last 20 strings are remembered; this can be
602    changed in the <guibutton>General</guibutton> pane of the
603    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
604    dialog box; see <xref linkend="global-opts" />.
605   </para>
606   <para>
607    <guimenu>Edit</guimenu>&gt;<guisubmenu>Registers</guisubmenu>&gt;<guimenuitem>View
608    Registers</guimenuitem> displays a dialog box for
609    viewing the contents of registers (including the clipboard).
610   </para>
611  </sect2>
612 </sect1>
613 <sect1 id="markers"><title>Markers</title>
614  <para>
615   Each buffer can have any number of <firstterm>markers</firstterm> defined,
616   pointing to
617   specific locations within that buffer. Each line in a buffer can have
618   at most one marker set pointing to it. Markers are persistent; they are
619   saved to
620   <filename>.<replaceable>filename</replaceable>.marks</filename>, where
621   <filename><replaceable>filename</replaceable></filename> is the file
622   name. (The dot prefix
623   makes the markers file hidden on Unix systems.) Marker
624   saving can be
625   disabled in the <guibutton>Loading and Saving</guibutton> pane of the
626   <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
627   dialog box; see <xref linkend="global-opts" />.
628  </para>
629  <para>
630   Markers are listed in the <guimenu>Markers</guimenu> menu; selecting a marker
631   from this menu is the simplest way to return to its location.
632   Each marker can optionally have a single-character shortcut; markers without
633   a shortcut can only be returned to using the menu, markers with a shortcut
634   can be accessed more quickly from the keyboard.
635  </para>
636  <para>
637   Lines which contain markers are indicated in the gutter with a highlight.
638   Moving the mouse over the highlight displays a tool tip showing the marker's
639   shortcut, if it has one. See <xref linkend="textarea" /> for information
640   about the gutter.
641  </para>
642  <para>
643   <guimenu>Markers</guimenu>&gt;<guimenuitem>Add/Remove Marker</guimenuitem>
644   (shortcut:
645   <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
646   <keycombo><keycap>Control</keycap><keycap>M</keycap></keycombo>) adds a
647   marker without a shortcut pointing to the current line. If a marker is
648   already set on the current line, the marker is removed instead.
649   If text is selected,
650   markers are added to the first and last line of each selection.
651  </para>
652  <para>
653   <guimenu>Markers</guimenu>&gt;<guimenuitem>Add Marker With
654   Shortcut</guimenuitem>
655   (shortcut: <keycombo><keycap>Control</keycap><keycap>T</keycap></keycombo>
656   <keycap><replaceable>key</replaceable></keycap>)
657   reads the next character entered at the keyboard, and adds a marker with that
658   shortcut pointing to the current line. If a previously-defined marker already
659   has that shortcut, it will no longer have that shortcut, but will remain
660   in the buffer. Pressing <keycap>Escape</keycap> instead of specifying a
661   marker shortcut after invoking the command will cancel the operation.
662  </para>
663  <para>
664   <guimenu>Markers</guimenu>&gt;<guimenuitem>Go to Marker</guimenuitem>
665   (shortcut: <keycombo><keycap>Control</keycap><keycap>Y</keycap></keycombo>
666   <keycap><replaceable>key</replaceable></keycap>)
667   reads the next character entered at the keyboard, and moves the caret to the
668   location of the marker with that shortcut. Pressing <keycap>Escape</keycap>
669   instead of specifying a marker
670   shortcut after invoking the command will cancel the operation.
671  </para>
672  <para>
673   <guimenu>Markers</guimenu>&gt;<guimenuitem>Select to Marker</guimenuitem>
674   (shortcut: <keycombo><keycap>Control</keycap><keycap>U</keycap></keycombo>
675   <keycap><replaceable>key</replaceable></keycap>)
676   reads the next character entered at the keyboard, and extends
677   the selection to the location of the marker with that shortcut.
678    Pressing <keycap>Escape</keycap> instead of specifying a marker
679   shortcut after invoking the command will cancel the operation.
680  </para>
681  <para>
682   <guimenu>Markers</guimenu>&gt;<guimenuitem>Swap Caret and
683   Marker</guimenuitem> (shortcut:
684   <keycombo><keycap>Control</keycap><keycap>U</keycap></keycombo>
685   <keycap><replaceable>key</replaceable></keycap>)
686   reads the next character entered at the keyboard, and swaps the
687   position of the caret with the location of the marker with that shortcut.
688   Pressing <keycap>Escape</keycap> instead of specifying a marker
689   shortcut after invoking the command will cancel the operation.
690  </para>
691  <para>
692   <guimenu>Markers</guimenu>&gt;<guimenuitem>Go to Previous
693   Marker</guimenuitem>
694   (shortcut: <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
695   <keycap>,</keycap>) goes
696   to the marker immediately before the caret position.
697  </para>
698  <para>
699   <guimenu>Markers</guimenu>&gt;<guimenuitem>Go to Next Marker</guimenuitem>
700   (shortcut: <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
701   <keycap>.</keycap>)
702   goes to the marker immediately after the caret position.
703  </para>
704  <para>
705   <guimenu>Markers</guimenu>&gt;<guimenuitem>Remove All Markers</guimenuitem>
706   removes all markers set in the current buffer.
707  </para>
708 </sect1>
709 <sect1 id="search-replace"><title>Search and Replace</title>
710  <sect2><title>Searching For Text</title>
711   <para>
712    <guimenu>Search</guimenu>&gt;<guimenuitem>Find</guimenuitem> (shortcut:
713    <keycombo><keycap>Control</keycap><keycap>F</keycap></keycombo>) displays
714    the search and replace dialog box. If text is selected and the selection
715    does not span a line break, the selected text becomes the default search
716    string.
717   </para>
718   <para>
719    If the selection does span one or more line breaks, the default
720    search string is empty, and the <guibutton>Search in Selection</guibutton>
721    and <guibutton>HyperSearch</guibutton>
722    buttons are pre-selected. Note that finding the next or previous
723    ocurrence cannot be constrained to a selected range; only
724    replacement and HyperSearch can be (see <xref linkend="hypersearch" />).
725   </para>
726   <para>
727    The search string can be entered in the <guibutton>Search for</guibutton>
728    text field. This text field remembers previously entered strings; see
729    <xref linkend="history" /> for details.
730   </para>
731   <para>
732    The search can be made case insensitive (for example, searching for
733    <quote>Hello</quote> will match <quote>hello</quote>, <quote>HELLO</quote>
734    and <quote>HeLlO</quote>) by selecting the <guibutton>Ignore
735    case</guibutton> check box. Regular expressions may be used to match inexact
736    sequences of text if the <guibutton>Regular expressions</guibutton> check
737    box is selected; see <xref linkend="regexps" /> for more information about
738    regular expressions. Note that regular expressions can only be used when
739    searching forwards.
740   </para>
741   <para>
742    Clicking <guibutton>Find</guibutton> will locate the next (or previous, if
743    searching backwards) occurrence of the
744    search string after the caret position. If the
745    <guibutton>Keep dialog</guibutton> check box is selected, the dialog box
746    will remain open; otherwise, it will be closed after the search string is
747    located.
748   </para>
749   <para>
750    If no occurrences could be found and the
751    <guibutton>Auto wrap</guibutton> check box is selected, the search will
752    automatically be restarted and a message will be shown in the status bar
753    to indicate that. If the check box is not selected, a dialog
754    box will be displayed, offering to restart the search.
755   </para>
756   <para>
757    <guimenu>Search</guimenu>&gt;<guimenuitem>Find Next</guimenuitem> (shortcut:
758    <keycombo><keycap>Control</keycap><keycap>G</keycap></keycombo>) locates the
759    next occurrence of the most recent search string without displaying the
760    search and replace dialog box.
761   </para>
762   <para>
763    <guimenu>Search</guimenu>&gt;<guimenuitem>Find Previous</guimenuitem>
764    (shortcut: <keycombo><keycap>Control</keycap><keycap>H</keycap></keycombo>)
765    locates the previous occurrence of the most recent search string without
766    displaying the search and replace dialog box.
767   </para>
768  </sect2>
769  <sect2><title>Replacing Text</title>
770   <para>
771    Occurrences of the search string can be replaced with either a replacement
772    string or the result of a BeanShell script snippet. Two radio buttons in
773    the search and replace dialog box can be used to choose between these two
774    behaviors.
775   </para>
776   <para>
777    The replace string text field remembers previously entered strings;
778    see <xref linkend="history" /> for details.
779   </para>
780   <para>
781    Clicking <guibutton>Replace</guibutton> will perform a replacement in each
782    text selection.
783    Clicking <guibutton>Replace &amp; Find</guibutton> will perform a
784    replacement in each text selection and locate the next occurrence of the
785    search string. Clicking <guibutton>Replace All</guibutton> will perform a
786    replacement in each buffer to be searched.
787   </para>
788   <para>
789    In text replacement mode, the search string is replaced with the replacement
790    string. If regular expressions are enabled, positional parameters
791    (<literal>$0</literal>, <literal>$1</literal>, <literal>$2</literal>, and so
792    on) can be used to insert the contents of matched subexpressions in the
793    replacement text; see <xref linkend="regexps" /> for more information.
794   </para>
795   <para>
796    In BeanShell replacement mode, the search string is replaced with the return
797    value of a BeanShell snippet. The following predefined variables can be
798    referenced in the snippet:
799   </para>
800   <itemizedlist><listitem><para><varname>_0</varname> -- the text to be
801   replaced</para>
802   </listitem><listitem><para><varname>_1</varname> - <varname>_9</varname> --
803   if regular expressions are enabled, these contain the values of matched
804   subexpressions.
805   </para></listitem></itemizedlist>
806   <para>
807    BeanShell syntax and features are covered in great detail in
808    <xref linkend="writing-macros-part" />, but here are some examples:
809   </para>
810   <informalexample>
811    <para>
812     To convert all HTML tags to lower case, search
813     for the following regular expression:
814    </para>
815    <programlisting><![CDATA[<(.*?)>]]></programlisting>
816    <para>
817     Replacing it with the following BeanShell snippet:
818    </para>
819    <programlisting><![CDATA["<" + _1.toLowerCase() + ">"]]></programlisting>
820   </informalexample>
821   <informalexample>
822    <para>
823     To replace arithmetic expressions between curly braces with their result,
824     search for the following regular expression:
825    </para>
826    <programlisting><![CDATA[\{(.+)\}]]></programlisting>
827    <para>
828     Replacing it with the following BeanShell snippet:
829    </para>
830    <programlisting><![CDATA[eval(_1)]]></programlisting>
831   </informalexample>
832   <para>
833    These two examples only scratch the surface; the possibilities are endless.
834   </para>
835  </sect2>
836  <sect2 id="hypersearch"><title>HyperSearch</title>
837   <para>
838    If the <guibutton>HyperSearch</guibutton> check box in the search and
839    replace dialog box is selected, clicking <guibutton>Find</guibutton> will
840    list all occurrences of the search string, rather than locating them one
841    by one.
842   </para>
843   <para>
844    By default, HyperSearch results are shown in a floating window;
845    the window can be set to dock into the view
846    in the <guibutton>Docking</guibutton> pane of the
847    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
848    dialog box; see <xref linkend="docking" />.
849   </para>
850   <para>
851    Running searches can be stopped in the
852    <guimenu>Utilities</guimenu>&gt;<guimenuitem>I/O Progress
853    Monitor</guimenuitem> dialog box.
854   </para>
855  </sect2>
856  <sect2><title>Multiple File Search</title>
857   <para>
858    Searching, replacement and HyperSearch can also be performed in all
859    open buffers or all files in a directory.
860   </para>
861   <para>
862    If the <guibutton>All buffers</guibutton> radio button in the search and
863    replace dialog box is selected, all open buffers whose names match the glob
864    pattern
865    entered in the <guibutton>Filter</guibutton> text field will be searched.
866    See <xref linkend="globs" /> for more information about glob patterns.
867   </para>
868   <para>
869    If the <guibutton>Directory</guibutton> radio button is selected, all files
870    in the directory whose names match the glob will be searched. The
871    directory to search in can either be entered in the
872    <guibutton>Directory</guibutton> text field, or chosen in a file selector
873    dialog box by clicking <guibutton>Choose</guibutton>.
874    If the <guibutton>Search subdirectories</guibutton> check box is selected,
875    all subdirectories of the specified directory will also be searched. Keep
876    in mind that searching through directories with many files can take
877    a long time and consume a large amount of memory.
878   </para>
879   <para>
880    The <guibutton>Directory</guibutton> and <guibutton>Filter</guibutton>
881    text fields remember previously entered strings; see <xref linkend="history" />
882    for details.
883   </para>
884   <para>
885    Note that selecting the <guibutton>All Buffers</guibutton> or
886    <guibutton>Directory</guibutton> radio buttons also selects the
887    <guibutton>HyperSearch</guibutton> check box. This is merely for
888    convinience, however; normal searching is supported as well.
889   </para>
890   <para>
891    Two convinience commands are provided for performing multiple file searches.
892   </para>
893   <para>
894    <guimenu>Search</guimenu>&gt;<guimenuitem>Search in Open
895    Buffers</guimenuitem> (shortcut:
896    <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
897    <keycombo><keycap>Control</keycap><keycap>B</keycap></keycombo>) displays
898    the search and replace dialog box, and selects the <guibutton>All
899    buffers</guibutton> radio button.
900   </para>
901   <para>
902    <guimenu>Search</guimenu>&gt;<guimenuitem>Search in Directory</guimenuitem>
903    (shortcut:
904    <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
905    <keycombo><keycap>Control</keycap><keycap>D</keycap></keycombo>) displays
906    the search and replace dialog box, and selects the
907    <guibutton>Directory</guibutton> radio button.
908   </para>
909  </sect2>
910  <sect2><title>The Search Bar</title>
911   <para>
912    The search bar at the top of the view provides a convenient way to
913    perform simple searches without
914    opening the search and replace dialog box first. Neither multiple file
915    search nor replacement can be done from the search bar.
916    The search bar remembers
917    previously entered strings; see <xref linkend="history" /> for details.
918   </para>
919   <para>
920    Unless the <guibutton>HyperSearch</guibutton> check box is selected, the
921    search bar will perform an <firstterm>incremental search</firstterm>.
922    In incremental search mode, the first occurrence of the search
923    string is located in the current buffer as is it is being typed.
924    Pressing <keycap>Enter</keycap>
925    and <keycombo><keycap>Shift</keycap><keycap>Enter</keycap></keycombo>
926    searches for the next and previous occurrence, respectively.
927    Once the desired occurrence has been found, press <keycap>Escape</keycap>
928    to return keyboard focus to the text area.
929   </para>
930   <para>
931    If the <guibutton>HyperSearch</guibutton> check box is selected, entering a
932    search string and pressing <keycap>Enter</keycap> will perform a
933    HyperSearch.
934   </para>
935   <para>
936    <guimenu>Search</guimenu>&gt;<guimenuitem>Incremental Search</guimenuitem>
937    (shortcut: <keycombo><keycap>Control</keycap><keycap>,</keycap></keycombo>)
938    moves keyboard focus to the search bar. If text is selected when this
939    command is invoked, the selection is inserted into the search bar
940    automatically.
941   </para>
942   <para>
943    <guimenu>Search</guimenu>&gt;<guimenuitem>Quick HyperSearch</guimenuitem>
944    (shortcut: <keycombo><keycap>Control</keycap><keycap>.</keycap></keycombo>)
945    moves keyboard focus to the search bar and pre-selects the
946    <guibutton>HyperSearch</guibutton> check box. If text is selected when this
947    command is invoked, a HyperSearch for that text is performed immediately.
948   </para>
949   <para>
950    The
951    <guimenu>Search</guimenu>&gt;<guimenuitem>Incremental Search
952    for Word</guimenuitem>
953    (shortcut: <keycombo><keycap>Alt</keycap><keycap>,</keycap></keycombo>)
954    and <guimenu>Search</guimenu>&gt;<guimenuitem>Quick HyperSearch
955    for Word</guimenuitem>
956    (shortcut: <keycombo><keycap>Alt</keycap><keycap>.</keycap></keycombo>)
957    commands perform an incremental search and HyperSearch, respectively,
958    for the word under the caret.
959   </para>
960   <para>
961    The search bar can be disabled in the <guibutton>General</guibutton> pane of
962    the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
963    Options</guimenuitem> dialog box.
964   </para>
965   <note>
966    <para>
967     Incremental searches cannot be not recorded in macros. Use the
968     search and replace dialog box instead. See <xref linkend="using-macros" />
969     for information about macros.
970    </para>
971   </note>
972  </sect2>
973 </sect1>
974</chapter>