PageRenderTime 95ms CodeModel.GetById 78ms app.highlight 11ms RepoModel.GetById 1ms app.codeStats 0ms

/jEdit/tags/jedit-4-0-pre5/doc/users-guide/source-edit.xml

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