PageRenderTime 99ms CodeModel.GetById 89ms app.highlight 5ms RepoModel.GetById 1ms app.codeStats 0ms

/jEdit/tags/jedit-4-2-pre14/doc/users-guide/source-edit.xml

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