/jEdit/tags/jedit-4-0-pre3/doc/users-guide/source-edit.xml
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: -->
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 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>><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>><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>><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>><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>><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 < $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 < 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()
128{
129 if(isOK)
130 {
131 doSomething();
132 }
133}</programlisting>
134 <para>
135 Invoking
136 <guimenu>Edit</guimenu>><guisubmenu>Source
137 Code</guisubmenu>><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>><guisubmenu>Source
145 Code</guisubmenu>><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>><guisubmenu>Source
156 Code</guisubmenu>><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>><guisubmenu>Source
163 Code</guisubmenu>><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>><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>><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>><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>><guisubmenu>Source
212 Code</guisubmenu>><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>><guisubmenu>Source
220 Code</guisubmenu>><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>><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>><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>><guisubmenu>Text</guisubmenu>><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>><guisubmenu>Text</guisubmenu>><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>><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>><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>><guisubmenu>Source
312 Code</guisubmenu>><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>><guisubmenu>Source
341 Code</guisubmenu>><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>><guisubmenu>Source
349 Code</guisubmenu>><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.
383
384{{{ A sub-section.
385With text inside it.
386}}}
387
388{{{ Another sub-section.
389}}}
390
391}}}</screen>
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>><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>><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>><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>><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>><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>><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>><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>><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>><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>><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>><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>><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>><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>><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>><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>><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>><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>
570</chapter>