PageRenderTime 65ms CodeModel.GetById 32ms app.highlight 15ms RepoModel.GetById 1ms app.codeStats 1ms


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