PageRenderTime 69ms CodeModel.GetById 52ms app.highlight 10ms RepoModel.GetById 0ms app.codeStats 1ms

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

#
XML | 670 lines | 534 code | 131 blank | 5 comment | 0 complexity | bb9fbad93af0445e0326462dde0f00a2 MD5 | raw file
  1<?xml version="1.0" encoding="UTF-8"?>
  2<chapter id="source-edit">
  3    <title>Editing Source Code</title>
  4
  5    <!-- jEdit buffer-local properties: -->
  6
  7    <!-- :tabSize=1:indentSize=1:noTabs=true:wrap=soft:maxLineLen=80: -->
  8
  9    <!-- :xml.root=users-guide.xml: -->
 10
 11    <section id="modes">
 12        <title>Edit Modes</title>
 13
 14        <para>An <firstterm>edit mode</firstterm> specifies syntax highlighting
 15        rules, auto indent behavior, and various other customizations for
 16        editing a certain file type. This section only covers using existing
 17        edit modes; information about writing your own can be found in <xref
 18        linkend="writing-modes-part" />.</para>
 19
 20        <para>When a file is opened, jEdit first checks the file name against a
 21        list of known patterns. For example, files whose names end with
 22        <filename>.c</filename> are opened with C mode, and files named
 23        <filename>Makefile</filename> are opened with Makefile mode. If a
 24        suitable match based on file name cannot be found, jEdit checks the
 25        first line of the file. For example, files whose first line is
 26        <filename>#!/bin/sh</filename> are opened with shell script mode.</para>
 27
 28        <section id="mode-selection">
 29            <title>Mode Selection</title>
 30
 31            <para>File name and first line matching is done using glob patterns
 32            similar to those used in Unix shells. Glob patterns associated with
 33            edit modes can be changed in the <guibutton>Editing</guibutton> pane
 34            of the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
 35            Options</guimenuitem> dialog box. Note that the glob patterns must
 36            match the file name or first line exactly; so to match files whose
 37            first line contains <literal>begin</literal>, you must use a first
 38            line glob of <literal>*begin*</literal>. See <xref
 39            linkend="globs" /> for a description of glob pattern syntax.</para>
 40
 41            <para>The default edit mode for files which do not match any pattern
 42            can be set in the <guibutton>Editing</guibutton> pane as
 43            well.</para>
 44
 45            <para>The edit mode can be specified manually as well. The current
 46            buffer's edit mode can be set on a one-time basis in the
 47            <guimenu>Utilities</guimenu>&gt;<guimenuitem>Buffer
 48            Options</guimenuitem> dialog box; see <xref
 49            linkend="buffer-opts" />. To set a buffer's edit mode for future
 50            editing sessions, place the following in one of the first or last 10
 51            lines of the buffer, where <replaceable>edit mode</replaceable> is
 52            the name of the desired edit mode:</para>
 53
 54            <screen>:mode=<replaceable>edit mode</replaceable>:</screen>
 55        </section>
 56
 57        <section id="syntax-hilite">
 58            <title>Syntax Highlighting</title>
 59
 60            <para>Syntax highlighting is the display of programming language
 61            tokens using different fonts and colors. This makes code easier to
 62            follow and errors such as misplaced quotes easier to spot. All edit
 63            modes except for the plain text mode perform some kind of syntax
 64            highlighting.</para>
 65
 66            <para>The colors and styles used to highlight syntax tokens can be
 67            changed in the <guibutton>Syntax Highlighting</guibutton> pane of
 68            the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
 69            Options</guimenuitem> dialog box; see <xref
 70            linkend="syntax-hilite-pane" />.</para>
 71        </section>
 72    </section>
 73
 74    <section id="indent">
 75        <title>Tabbing and Indentation</title>
 76
 77        <para>jEdit makes a distinction between the <firstterm>tab
 78        width</firstterm>, which is is used when displaying hard tab characters,
 79        and the <firstterm>indent width</firstterm>, which is used when a level
 80        of indent is to be added or removed, for example by mode-specific auto
 81        indent routines. Both can be changed in one of several ways:</para>
 82
 83        <itemizedlist>
 84            <listitem>
 85                <para>On a global or mode-specific basis in the
 86                <guibutton>Editing</guibutton> pane of the the
 87                <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
 88                Options</guimenuitem> dialog box. See <xref
 89                linkend="editing-pane" />.</para>
 90            </listitem>
 91
 92            <listitem>
 93                <para>In the current buffer for the duration of the editing
 94                session in the
 95                <guimenu>Utilities</guimenu>&gt;<guimenuitem>Buffer
 96                Options</guimenuitem> dialog box. See <xref
 97                linkend="buffer-opts" />.</para>
 98            </listitem>
 99
100            <listitem>
101                <para>In the current buffer for future editing sessions by
102                placing the following in one of the first or last 10 lines of
103                the buffer, where <replaceable>n</replaceable> is the desired
104                tab width, and <replaceable>m</replaceable> is the desired
105                indent width:</para>
106
107                <screen>:tabSize=<replaceable>n</replaceable>:indentSize=<replaceable>m</replaceable>:</screen>
108            </listitem>
109        </itemizedlist>
110
111        <para><guimenu>Edit</guimenu>&gt;<guisubmenu>Indent</guisubmenu>&gt;<guisubmenu>Shift
112        Indent Left</guisubmenu> (shortcut: <keycap>S+TAB</keycap> or
113        <keycap>A+LEFT</keycap>) removes one level of indent from each selected
114        line, or the current line if there is no selection.</para>
115
116        <para><guimenu>Edit</guimenu>&gt;<guisubmenu>Indent</guisubmenu>&gt;<guisubmenu>Shift
117        Indent Right</guisubmenu> (shortcut: <keycap>A+RIGHT</keycap>) adds one
118        level of indent to each selected line, or the current line if there is
119        no selection. Pressing <keycap>Tab</keycap> while a multi-line selection
120        is active has the same effect.</para>
121
122        <para><guimenu>Edit</guimenu>&gt;<guisubmenu>Indent</guisubmenu>&gt;<guimenuitem>Remove
123        Trailing Whitespace</guimenuitem> (shortcut: <keycap>C+e r</keycap>)
124        removes all whitespace from the end of each selected line, or the
125        current line if there is no selection.</para>
126
127        <section id="soft-tabs">
128            <title>Soft Tabs</title>
129
130            <para>Files containing hard tab characters may look less than ideal
131            if the default tab size is changed, so some people prefer using
132            multiple space characters instead of hard tabs to indent
133            code.</para>
134
135            <para>This feature is known as <firstterm>soft tabs</firstterm>.
136            Soft tabs can be enabled or disabled in one of several ways:</para>
137
138            <itemizedlist>
139                <listitem>
140                    <para>On a global or mode-specific basis in the
141                    <guibutton>Editing</guibutton> pane of the
142                    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
143                    Options</guimenuitem> dialog box. See <xref
144                    linkend="editing-pane" />.</para>
145                </listitem>
146
147                <listitem>
148                    <para>In the current buffer for the duration of the editing
149                    session in the
150                    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Buffer
151                    Options</guimenuitem> dialog box. See <xref
152                    linkend="buffer-opts" />.</para>
153                </listitem>
154
155                <listitem>
156                    <para>In the current buffer for future editing sessions by
157                    placing the following in one of the first or last 10 lines
158                    of the buffer, where <replaceable>flag</replaceable> is
159                    either <quote>true</quote> or <quote>false</quote>:</para>
160
161                    <screen>:noTabs=<replaceable>flag</replaceable>:</screen>
162                </listitem>
163            </itemizedlist>
164
165            <para>Changing the soft tabs setting has no effect on existing tab
166            characters; it only affects subsequently-inserted tabs.</para>
167
168            <para><guimenu>Edit</guimenu>&gt;<guisubmenu>Indent</guisubmenu>&gt;<guimenuitem>Spaces
169            to Tabs</guimenuitem> converts soft tabs to hard tabs in the current
170            selection, or the entire buffer if nothing is selected.</para>
171
172            <para><guimenu>Edit</guimenu>&gt;<guisubmenu>Indent</guisubmenu>&gt;<guimenuitem>Tabs
173            to Spaces</guimenuitem> converts hard tabs to soft tabs in the
174            current selection, or the entire buffer if nothing is
175            selected.</para>
176	 </section>
177	
178	 <section id="elastic-tabstops">
179            <title>Elastic Tabstops</title>
180
181            <para>Elastic tabstops are an alternative way to handle tabstops.
182            Elastic tabstops differ from traditional fixed tabstops because 
183	     columns in lines above and below the "cell" that is being 
184            changed are always kept aligned. As the width of text before a tab 
185            character changes, the tabstops on adjacent lines are also 
186            changed to fit the widest piece of text in that column. It provides
187            certain explicit benefits like it saves time
188	     spent on arranging the code and works seemlessly with variable width 
189            fonts.But at the same time it can make the code look unorganized 
190            on editors that do not support elastic tabstops.</para>
191
192            <para>This feature is known as <firstterm>elastic tabstops</firstterm>.
193            Elastic tabstops can be enabled or disabled in one of several ways:</para>
194
195            <itemizedlist>
196                <listitem>
197                    <para>On a global or mode-specific basis in the
198                    <guibutton>Editing</guibutton> pane of the
199                    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
200                    Options</guimenuitem> dialog box. See <xref
201                    linkend="editing-pane" />.</para>
202                </listitem>
203
204                <listitem>
205                    <para>In the current buffer for the duration of the editing
206                    session in the
207                    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Buffer
208                    Options</guimenuitem> dialog box. See <xref
209                    linkend="buffer-opts" />.</para>
210                </listitem>
211
212                <listitem>
213                    <para>In the current buffer for future editing sessions by
214                    placing the following in one of the first or last 10 lines
215                    of the buffer, where <replaceable>flag</replaceable> is
216                    either <quote>true</quote> or <quote>false</quote>:</para>
217
218                    <screen>:elasticTabstops=<replaceable>flag</replaceable>:</screen>
219                </listitem>
220            </itemizedlist>
221
222            <para>Note that this feature does not work with <firstterm>soft tabs</firstterm>.
223            where tabs are emulated as spaces</para>
224	 </section>
225
226        <section id="autoindent">
227            <title>Automatic Indent</title>
228
229            <para>The auto indent feature inserts the appropriate number of tabs
230            or spaces at the beginning of a line by looking at program
231            structure.</para>
232
233            <para>In the default configuration, pressing <keycap>ENTER</keycap>
234            will create a new line with the appropriate amount of indent
235            automatically, and pressing <keycap>TAB</keycap> at the beginning
236            of, or inside the leading whitespace of a line will insert the
237            appropriate amount of indentation. Pressing it again will insert a
238            tab character.</para>
239
240            <para>The behavior of the <keycap>ENTER</keycap> and
241            <keycap>TAB</keycap> keys can be configured in the
242            <guibutton>Shortcuts</guibutton> pane of the
243            <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
244            Options</guimenuitem> dialog. box, just as with any other key. The
245            <keycap>ENTER</keycap> key can be bound to one of the following, or
246            indeed any other command or macro:</para>
247
248            <itemizedlist>
249                <listitem>
250                    <para><guimenuitem>Insert Newline</guimenuitem>.</para>
251                </listitem>
252
253                <listitem>
254                    <para><guimenuitem>Insert Newline and Indent</guimenuitem>,
255                    which is the default.</para>
256                </listitem>
257            </itemizedlist>
258
259            <para>The <keycap>TAB</keycap> can be bound to one of the following,
260            or again, any other command or macro:</para>
261
262            <itemizedlist>
263                <listitem>
264                    <para><guimenuitem>Insert Tab</guimenuitem>.</para>
265                </listitem>
266
267                <listitem>
268                    <para><guimenuitem>Insert Tab or Indent</guimenuitem>, which
269                    is the default.</para>
270                </listitem>
271
272                <listitem>
273                    <para><guimenuitem>Indent Selected
274                    Lines</guimenuitem>.</para>
275                </listitem>
276            </itemizedlist>
277
278            <para>See <xref linkend="shortcuts-pane" /> for details.</para>
279
280            <para>Auto indent behavior is mode-specific. In most edit modes, the
281            indent of the previous line is simply copied over. However, in
282            C-like languages (C, C++, Java, JavaScript), curly brackets and
283            language statements are taken into account and indent is added and
284            removed as necessary.</para>
285
286            <para><guimenu>Edit</guimenu>&gt;<guisubmenu>Indent</guisubmenu>&gt;<guisubmenu>Indent
287            Selected Lines</guisubmenu> (shortcut: <keycap>C+i</keycap>) indents
288            all selected lines, or the current line if there is no
289            selection.</para>
290
291            <para>To insert a literal tab or newline without performing
292            indentation, prefix the tab or newline with <keycap>C+e v</keycap>.
293            For example, to create a new line without any indentation, type
294            <keycap>C+e v ENTER</keycap>.</para>
295        </section>
296    </section>
297
298    <section id="commenting">
299        <title>Commenting Out Code</title>
300
301        <para>Most programming and markup languages support the notion of
302        <quote>comments</quote>, or regions of code which are ignored by the
303        compiler/interpreter. jEdit has commands which make inserting comments
304        more convenient.</para>
305
306        <para>Comment strings are mode-specific, and some in some modes such as
307        HTML different parts of a buffer can have different comment strings. For
308        example, in HTML files, different comment strings are used for HTML text
309        and inline JavaScript.</para>
310
311        <para><guimenu>Edit</guimenu>&gt;<guisubmenu>Source
312        Code</guisubmenu>&gt;<guimenuitem>Range Comment</guimenuitem> (shortcut:
313        <keycap>C+e C+c</keycap>) encloses the selection with comment start and
314        end strings, for example <literal>/*</literal> and <literal>*/</literal>
315        in Java mode.</para>
316
317        <para><guimenu>Edit</guimenu>&gt;<guisubmenu>Source
318        Code</guisubmenu>&gt;<guimenuitem>Line Comment</guimenuitem> (shortcut:
319        <keycap>C+e C+k</keycap>) inserts the line comment string, for example
320        <literal>//</literal> in Java mode, at the start of each selected
321        line.</para>
322    </section>
323
324    <section id="bracket-matching">
325        <title>Bracket Matching</title>
326
327        <para>Misplaced and unmatched brackets are one of the most common syntax
328        errors encountered when writing code. jEdit has several features to make
329        brackets easier to deal with.</para>
330
331        <para>Positioning the caret immediately after a bracket will highlight
332        the corresponding closing or opening bracket (assuming it is visible),
333        and draw a scope indicator in the gutter. If the highlighted bracket is
334        not visible, the text of the matching line will be shown in the status
335        bar. If the matching line consists of only whitespace and the bracket
336        itself, the <emphasis>previous line</emphasis> is shown instead. This
337        feature is very useful when your code is indented as follows, with
338        braces on their own lines:</para>
339
340        <programlisting>public void someMethod()
341{
342    if(isOK)
343    {
344        doSomething();
345    }
346}</programlisting>
347
348        <para>Invoking
349        <guimenu>Edit</guimenu>&gt;<guisubmenu>Source</guisubmenu>&gt;<guimenuitem>Go
350        to Matching Bracket</guimenuitem> (shortcut: <keycap>C+]</keycap>) or
351        clicking the scope indicator in the gutter moves the caret to the
352        matching bracket.</para>
353
354        <para><guimenu>Edit</guimenu>&gt;<guisubmenu>Source</guisubmenu>&gt;<guimenuitem>Select
355        Code Block</guimenuitem> (shortcut: <keycap>C+[</keycap>) selects all
356        text between the closest two brackets surrounding the caret.</para>
357
358        <para>Holding down <keycap>Control</keycap> while clicking the scope
359        indicator in the gutter or a bracket in the text area will select all
360        text between the two matching brackets.</para>
361
362        <para><guimenu>Edit</guimenu>&gt;<guisubmenu>Source</guisubmenu>&gt;<guimenuitem>Go
363        to Previous Bracket</guimenuitem> (shortcut: <keycap>C+e C+[</keycap>)
364        moves the caret to the previous opening bracket.</para>
365
366        <para><guimenu>Edit</guimenu>&gt;<guisubmenu>Source</guisubmenu>&gt;<guimenuitem>Go
367        to Next Bracket</guimenuitem> (shortcut: <keycap>C+e C+]</keycap>) moves
368        the caret to the next closing bracket.</para>
369
370        <para>Bracket highlighting in the text area and bracket scope display in
371        the gutter can be customized in the <guibutton>Text Area</guibutton> and
372        <guibutton>Gutter</guibutton> panes of the
373        <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
374        Options</guimenuitem> dialog box; see <xref
375        linkend="global-opts" />.</para>
376
377        <tip>
378            <para>jEdit's bracket matching algorithm only checks syntax tokens
379            with the same type as the original bracket, so for example unmatched
380            brackets inside string literals and comments will be skipped when
381            matching brackets that are part of program syntax.</para>
382        </tip>
383    </section>
384
385    <section id="abbrevs">
386        <title>Abbreviations</title>
387
388        <para>Abbreviations are invoked by typing a couple of letters and then
389        issuing the <guimenu>Edit</guimenu>&gt;<guimenuitem>Expand
390        Abbreviation</guimenuitem> (keyboard shortcut: <keycap>C+;</keycap>),
391        which takes the word before the caret as the abbreviation name. If that
392        particular abbreviation was not yet set, a dialog will pop up, and you
393        can enter the text to insert before and after the caret. After the
394        abbreviation is created, it can be viewed or edited from the
395        <guibutton>Abbreviations</guibutton> pane of the
396        <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
397        Options</guimenuitem> dialog box; see <xref
398        linkend="abbrevs-pane" />.</para>
399
400        <para>Using abbreviations reduces the time spent typing long but
401        commonly used strings. For example, in Java mode, the abbreviation
402        <quote>sout</quote> is defined to expand to
403        <quote>System.out.println()</quote>, so to insert
404        <quote>System.out.println()</quote> in a Java buffer, you only need to
405        type <quote>sout</quote> followed by <keycap>C+;</keycap>. An
406        abbreviation can either be global, in which case it can be used in all
407        edit modes, or specific to a single mode.</para>
408
409        <para>The Java, VHDL. XML and XSL edit modes include some pre-defined
410        abbreviations you might find useful. Other modes do not have any
411        abbreviations defined by default.</para>
412
413        <para></para>
414
415        <para>Automatic abbreviation expansion can be enabled in the
416        <guibutton>Abbreviations</guibutton> pane of the
417        <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
418        Options</guimenuitem> dialog box. If enabled, pressing the space bar
419        after entering an abbreviation will automatically expand it.</para>
420
421        <para>If automatic expansion is enabled, a space can be inserted without
422        expanding the word before the caret by pressing <keycombo>
423                <keycap>Control</keycap>
424
425                <keycap>E</keycap>
426            </keycombo> <keycap>V</keycap> <keycap>Space</keycap>.</para>
427
428        <section id="positional-params">
429            <title>Positional Parameters</title>
430
431            <para>Positional parameters are an advanced feature that make
432            abbreviations much more useful. The best way to describe them is
433            with an example.</para>
434
435            <para>Java mode defines an abbreviation <quote>F</quote> that is set
436            to expand to the following:</para>
437
438            <programlisting>for(int $1 = 0; $1 &lt; $2; $1++)</programlisting>
439
440            <para>Expanding <literal>F#j#array.length#</literal> will insert the
441            following text into the buffer:</para>
442
443            <programlisting>for(int j = 0; j &lt; array.length; j++)</programlisting>
444
445            <para>Expansions can contain up to nine positional parameters. Note
446            that a trailing hash character (<quote>#</quote>) must be entered
447            when expanding an abbreviation with parameters.</para>
448
449            <para>If you do not specify the correct number of positional
450            parameters when expanding an abbreviation, any missing parameters
451            will be blank in the expansion, and extra parameters will be
452            ignored. A status bar message will be shown stating the required
453            number of parameters.</para>
454        </section>
455    </section>
456
457    <section id="folding">
458        <title>Folding</title>
459
460        <para>Program source code and other structured text files can be thought
461        of as containing a hierarchy of sections, which themselves might contain
462        sub-sections. The folding feature lets you selectively hide and show
463        these sections, replacing hidden ones with a single line that serves as
464        an <quote>overview</quote> of that section. Folding is disabled by
465        default. To enable it, you must choose one of the available folding
466        modes.</para>
467
468        <para><quote>Indent</quote> mode creates folds based on a line's leading
469        whitespace; the more leading whitespace a block of text has, the further
470        down it is in the hierarchy. For example:</para>
471
472        <screen>This is a section
473  This is a sub-section
474  This is another sub-section
475    This is a sub-sub-section
476Another top-level section</screen>
477
478        <para><quote>Explicit</quote> mode folds away blocks of text surrounded
479        with <quote>{{{</quote> and <quote>}}}</quote>. For example:</para>
480
481        <screen>{{{ The first line of a fold.
482When this fold is collapsed, only the above line will be visible.
483
484{{{ A sub-section.
485With text inside it.
486}}}
487
488{{{ Another sub-section.
489}}}
490
491}}}</screen>
492
493        <para>Both modes have distinct advantages and disadvantages; indent
494        folding requires no changes to be made to a buffer's text and does a
495        decent job with most program source. Explicit folding requires
496        <quote>fold markers</quote> to be inserted into the text, but is more
497        flexible in exactly what to fold away.</para>
498
499        <para>Some plugins might add additional folding modes; see <xref
500        linkend="using-plugins" /> for information about plugins.</para>
501
502        <para>Folding can be enabled in one of several ways:</para>
503
504        <itemizedlist>
505            <listitem>
506                <para>On a global or mode-specific basis in the
507                <guibutton>Editing</guibutton> pane of the
508                <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
509                Options</guimenuitem> dialog box. See <xref
510                linkend="editing-pane" />.</para>
511            </listitem>
512
513            <listitem>
514                <para>In the current buffer for the duration of the editing
515                session in the
516                <guimenu>Utilities</guimenu>&gt;<guimenuitem>Buffer
517                Options</guimenuitem> dialog box. See <xref
518                linkend="buffer-opts" />.</para>
519            </listitem>
520
521            <listitem>
522                <para>In the current buffer for future editing sessions by
523                placing the following in the first or last 10 lines of a buffer,
524                where <replaceable>mode</replaceable> is either
525                <quote>indent</quote>, <quote>explicit</quote>, or the name of a
526                plugin folding mode:</para>
527
528                <screen>:folding=<replaceable>mode</replaceable>:</screen>
529            </listitem>
530        </itemizedlist>
531
532        <warning>
533            <para>When using indent folding, portions of the buffer may become
534            inaccessible if you change the leading indent of the first line of a
535            collapsed fold. If you experience this, you can use the
536            <guimenuitem>Expand All Folds</guimenuitem> command to make the text
537            visible again.</para>
538        </warning>
539
540        <section>
541            <title>Collapsing and Expanding Folds</title>
542
543            <para>The first line of each fold has a triangle drawn next to it in
544            the gutter (see <xref linkend="overview" /> for more information
545            about the gutter). The triangle points toward the line when the fold
546            is collapsed, and downward when the fold is expanded. Clicking the
547            triangle collapses and expands the fold. To expand all sub-folds as
548            well, hold down the <keycap>Shift</keycap> while clicking.</para>
549
550            <para>The first line of a collapsed fold is drawn with a background
551            color that depends on the fold level, and the number of lines in the
552            fold is shown to the right of the line's text.</para>
553
554            <para>Folds can also be collapsed and expanded using menu item
555            commands and keyboard shortcuts.</para>
556
557            <para><guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Collapse
558            Fold</guimenuitem> (shortcut: <keycap>A+BACK_SPACE</keycap>)
559            collapses the fold containing the caret.</para>
560
561            <para><guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Expand Fold
562            One Level</guimenuitem> (shortcut: <keycap>A+ENTER</keycap>) expands
563            the fold containing the caret. Nested folds will remain collapsed,
564            and the caret will be positioned on the first nested fold (if
565            any).</para>
566
567            <para><guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Expand Fold
568            Fully</guimenuitem> (shortcut: <keycap>AS+ENTER</keycap>) expands
569            the fold containing the caret, also expanding any nested
570            folds.</para>
571
572            <para><guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Collapse All
573            Folds</guimenuitem> (shortcut: <keycap>C+e c</keycap>) collapses all
574            folds in the buffer.</para>
575
576            <para><guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Expand All
577            Folds</guimenuitem> (shortcut: <keycap>C+e x</keycap>) expands all
578            folds in the buffer.</para>
579        </section>
580
581        <section>
582            <title>Navigating Around With Folds</title>
583
584            <para><guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Go to Parent
585            Fold</guimenuitem> (shortcut: <keycap>C+e u</keycap>) moves the
586            caret to the fold containing the one at the caret position.</para>
587
588            <para><guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Go to
589            Previous Fold</guimenuitem> (shortcut: <keycap>A+UP</keycap>) moves
590            the caret to the fold immediately before the caret position.</para>
591
592            <para><guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Go to Next
593            Fold</guimenuitem> (shortcut: <keycap>A+DOWN</keycap>) moves the
594            caret to the fold immediately after the caret position.</para>
595        </section>
596
597        <section>
598            <title>Miscellaneous Folding Commands</title>
599
600            <para><guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Add Explicit
601            Fold</guimenuitem> (shortcut: <keycap>C+e a</keycap>) surrounds the
602            selection with <quote>{{{</quote> and <quote>}}}</quote>. If the
603            current buffer's edit mode defines comment strings (see <xref
604            linkend="commenting" />) the explicit fold markers will
605            automatically be commented out as well.</para>
606
607            <para><guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Select
608            Fold</guimenuitem> (shortcut: <keycap>C+e s</keycap>) selects all
609            lines within the fold containing the caret.
610            <keycap>Control</keycap>-clicking a fold expansion triangle in the
611            gutter has the same effect.</para>
612
613            <para><guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Expand Folds
614            With Level</guimenuitem> (shortcut: <keycap>C+e ENTER
615            <replaceable>key</replaceable></keycap>) reads the next character
616            entered at the keyboard, and expands folds in the buffer with a fold
617            level less than that specified, while collapsing all others.</para>
618
619            <para>Sometimes it is desirable to have files open with folds
620            initially collapsed. This can be configured as follows:</para>
621
622            <itemizedlist>
623                <listitem>
624                    <para>On a global or mode-specific basis in the
625                    <guibutton>Editing</guibutton> pane of the
626                    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
627                    Options</guimenuitem> dialog box. See <xref
628                    linkend="editing-pane" />.</para>
629                </listitem>
630
631                <listitem>
632                    <para>In the current buffer for future editing sessions by
633                    placing the following in the first or last 10 lines of a
634                    buffer, where <replaceable>level</replaceable> is the
635                    desired fold level:</para>
636
637                    <screen>:collapseFolds=<replaceable>level</replaceable>:</screen>
638                </listitem>
639            </itemizedlist>
640        </section>
641
642        <section id="narrowing">
643            <title>Narrowing</title>
644
645            <para>The narrowing feature temporarily <quote>narrows</quote> the
646            display of a buffer to a specified region. Text outside the region
647            is not shown, but is still present in the buffer. <!-- Both folding and
648    narrowing are implemented using the same code internally. --></para>
649
650            <para>Holding down <keycap>Alt</keycap> while clicking a fold
651            expansion triangle in the gutter will hide all lines the buffer
652            except those contained in the clicked fold.</para>
653
654            <para><guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Narrow Buffer
655            to Fold</guimenuitem> (shortcut: <keycap>C+e n n</keycap>) hides all
656            lines the buffer except those in the fold containing the caret. <!-- When this command is invoked, a message is shown in the
657    status bar reminding you that you need to invoke
658    <guimenuitem>Expand All Folds</guimenuitem> to make the rest of the buffer
659    visible again. --></para>
660
661            <para><guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Narrow Buffer
662            to Selection</guimenuitem> (shortcut: <keycap>C+e n s</keycap>)
663            hides all lines the buffer except those in the selection.</para>
664
665            <para><guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Expand All
666            Folds</guimenuitem> (shortcut: <keycap>C+e x</keycap>) shows lines
667            that were hidden as a result of narrowing.</para>
668        </section>
669    </section>
670</chapter>