PageRenderTime 140ms CodeModel.GetById 49ms app.highlight 16ms RepoModel.GetById 65ms app.codeStats 0ms

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

#
XML | 1252 lines | 1013 code | 235 blank | 4 comment | 0 complexity | 4e33600f9808cb6e8ce8da380db6628c MD5 | raw file

Large files files are truncated, but you can click here to view the full file

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

Large files files are truncated, but you can click here to view the full file