PageRenderTime 38ms CodeModel.GetById 20ms app.highlight 12ms RepoModel.GetById 0ms app.codeStats 0ms


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