PageRenderTime 39ms CodeModel.GetById 20ms app.highlight 11ms RepoModel.GetById 2ms app.codeStats 0ms

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

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