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

<!-- jEdit buffer-local properties: -->
<!-- :tabSize=1:indentSize=1:noTabs=true: -->

<chapter id="source-edit"><title>Editing Source Code</title>
 <sect1 id="modes"><title>Edit Modes</title>
  <para>
   An <firstterm>edit mode</firstterm> specifies syntax highlighting
   rules, auto indent behavior, and various other customizations for editing
   a certain file type. This section
   only covers using and selecting edit modes; information about writing your
   own can be found in <xref linkend="writing-modes-part" />.
  </para>
  <sect2 id="mode-selection"><title>Mode Selection</title>
   <para>
    When a file is opened, jEdit first checks the file name against a list
    of known patterns. For example, files whose names end with <quote>.c</quote>
    are edited in C mode, and files named <filename>Makefile</filename> are
    edited in Makefile mode. If a suitable match based on file name cannot be
    found, jEdit checks the first line of the file. For example, files whose
    first line is <quote>#!/bin/sh</quote> are edited in shell script mode.
   </para>
   <para>
    File name and first line globs can be changed in the
    <guibutton>Mode-Specific</guibutton> pane of the
    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
    dialog box (see <xref linkend="global-opts"/>).
   </para>
   <para>
    If automatic mode selection is not appropriate, the edit mode can
    be specified manually. The current buffer's edit mode can be set
    on a one-time basis in the
    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Buffer Options</guimenuitem>
    dialog box; see <xref linkend="buffer-opts" />. To set a buffer's edit mode
    for future editing sessions,
    place the following in one of the first or last 10 lines of the buffer,
    where <replaceable>edit mode</replaceable> is the name of the desired edit
    mode:
   </para>
   <screen>:mode=<replaceable>edit mode</replaceable>:</screen>
   <para>
    A list of edit modes can be found in the
    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Buffer Options</guimenuitem>
    dialog box.
   </para>
  </sect2>
  <sect2 id="syntax-hilite"><title>Syntax Highlighting</title>
   <para>
    Syntax highlighting is the display of programming language
    tokens using different fonts and colors. This makes code
    easier to follow and errors such as misplaced quotes easier to spot.
    All edit modes except for
    the plain text mode perform syntax highlighting.
   </para>
   <para>
    The colors and styles used to highlight syntax tokens can be changed
    in the <guibutton>Styles</guibutton> pane of the
    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
    dialog box; see <xref linkend="global-opts" />.
   </para>
  </sect2>
 </sect1>
 <sect1 id="abbrevs"><title>Abbreviations</title>
  <para>
   Using abbreviations reduces the time spent typing long but commonly used
   strings. For example, in Java mode, the abbreviation <quote>sout</quote> is
   defined to expand to <quote>System.out.println()</quote>, so to insert
   <quote>System.out.println()</quote> in a Java buffer, you only need to type
   <quote>sout</quote> followed by
   <keycombo><keycap>Control</keycap><keycap>;</keycap></keycombo>.
   Each abbreviation can either be global, in which case it will expand in all
   edit modes, or mode-specific. Abbreviations can be edited
   in the <guibutton>Abbreviations</guibutton> pane of the
   <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
   dialog box; see <xref linkend="global-opts" />. The Java, VHDL and XSL edit
   modes include some pre-defined abbreviations you might find useful.
  </para>
  <para>
   <guimenu>Edit</guimenu>&gt;<guimenuitem>Expand Abbreviation</guimenuitem>
   (keyboard shortcut: <keycombo><keycap>Control</keycap><keycap>;</keycap></keycombo>)
   attempts to expand the word before the caret. If no expansion could
   be found, it will offer to define one.
  </para>
  <para>
   Automatic abbreviation expansion can be enabled in the
   <guibutton>Abbreviations</guibutton> pane of the
   <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
   dialog box; see <xref linkend="global-opts" />. If enabled, pressing the
   space bar after entering an
   abbreviation will automatically expand it.
  </para>
  <para>
   If automatic expansion
   is enabled, a space can be inserted without expanding the word before
   the caret by pressing
   <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
   <keycap>V</keycap> <keycap>Space</keycap>.
  </para>
  <sect2 id="positional-params"><title>Positional Parameters</title>
   <para>
    Positional parameters are an advanced feature that make abbreviations much
    more useful. The best way to describe them is with an example.
   </para>
   <para>
    Suppose you have an abbreviation <quote>F</quote> that is set to expand to
    the following:
   </para>
   <programlisting>for(int $1 = 0; $1 &lt; $2; $1++)</programlisting>
   <para>
    Now, simply entering <quote>F</quote> in the buffer and expanding it will
    insert the above text as-is. However, if you expand
    <literal>F#j#array.length#</literal>,
    the following will be inserted:
   </para>
   <programlisting>for(int j = 0; j &lt; array.length; j++)</programlisting>
   <para>
    Expansions can contain up to nine positional parameters. Note that a
    trailing hash character (<quote>#</quote>) must be entered when expanding an
    abbreviation with parameters.
   </para>
   <para>
    If you do not specify the correct number of positional parameters when
    expanding an abbreviation, any missing parameters will appear
    blank in the expansion, and extra parameters will be ignored.
    A status bar message will be shown stating what
    the correct number of parameters is.
   </para>
  </sect2>
 </sect1>
 <sect1 id="bracket-matching"><title>Bracket Matching</title>
  <para>
   Misplaced and unmatched brackets are one of the most common syntax
   errors encountered when writing code. jEdit has several features
   to make brackets easier to deal with.
  </para>
  <para>
   Positioning the caret immediately after a bracket will highlight the
   corresponding closing or opening bracket (assuming it is visible)
   and draw a scope indicator in the gutter. If the highlighted bracket is
   not visible, the text of the matching line will be shown in the status
   bar. If the matching line consists of only whitespace and the bracket
   itself, the <emphasis>line before</emphasis> is shown instead. This
   feature is very useful for code with brackets indented like so:
  </para>
  <programlisting>public void someMethod()
{
    if(isOK)
    {
        doSomething();
    }
}</programlisting>
  <para>
   Invoking
   <guimenu>Edit</guimenu>&gt;<guisubmenu>Source
   Code</guisubmenu>&gt;<guimenuitem>Go to Matching
   Bracket</guimenuitem> (shortcut:
   <keycombo><keycap>Control</keycap><keycap>]</keycap></keycombo>), or
   clicking the scope indicator in the gutter moves the caret to the
   highlighted bracket.
  </para>
  <para>
   <guimenu>Edit</guimenu>&gt;<guisubmenu>Source
   Code</guisubmenu>&gt;<guimenuitem>Select Code Block</guimenuitem>
   (shortcut: <keycombo><keycap>Control</keycap><keycap>[</keycap></keycombo>)
   selects all text between the two brackets surrounding the caret.
  </para>
  <para>
   Holding down <keycap>Control</keycap> while clicking the scope indicator
   or a bracket in the text area will select all text
   between the two matching brackets.
  </para>
  <para>
   <guimenu>Edit</guimenu>&gt;<guisubmenu>Source
   Code</guisubmenu>&gt;<guimenuitem>Go to Previous
   Bracket</guimenuitem> (shortcut:
   <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
   <keycap>[</keycap>) moves the caret to the previous opening bracket.
  </para>
  <para>
   <guimenu>Edit</guimenu>&gt;<guisubmenu>Source
   Code</guisubmenu>&gt;<guimenuitem>Go to Next Bracket</guimenuitem> (shortcut:
   <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo> <keycap>]</keycap>)
   moves the caret to the next closing bracket.
  </para>
  <para>
   Bracket highlighting for the text area and gutter, respectively,
   can be disabled in the
   <guibutton>Text Area</guibutton> and <guibutton>Gutter</guibutton> panes of the
   <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
   dialog box; see <xref linkend="global-opts" />.
  </para>
  <note>
   <para>
    jEdit's bracket matching algorithm only checks syntax tokens with the same
    type as the original bracket for matches. So brackets inside string
    literals and comments will not cause problems, as they will
    be skipped.
   </para>
  </note>
 </sect1>
 <sect1 id="indent"><title>Tabbing and Indentation</title>
  <para>
   jEdit makes a distinction between the <firstterm>tab width</firstterm>,
   which is is used when displaying tab characters, and the <firstterm>indent
   width</firstterm>, which is used when a level of indent is to be added or
   removed, for example by mode-specific smart indent routines. Both can be
   changed in one of several ways:
  </para>
  <itemizedlist>
   <listitem><para>On a global or mode-specific basis in
   <guibutton>Editing</guibutton> and <guibutton>Mode-Specific</guibutton> panes
   of the the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
   Options</guimenuitem> dialog box.
   </para></listitem>
   <listitem><para>In the current buffer
   for the duration of the editing session in the
   <guimenu>Utilities</guimenu>&gt;<guimenuitem>Buffer Options</guimenuitem>
   dialog box; see <xref linkend="buffer-opts" />.</para></listitem>
   <listitem><para>In the current buffer
   for future editing sessions by placing the
   following in one of the first or last 10 lines of the buffer, where
   <replaceable>n</replaceable> is the desired tab width, and
   <replaceable>m</replaceable> is the desired indent width:
   </para>
   <screen>:tabSize=<replaceable>n</replaceable>:indentSize=<replaceable>m</replaceable>:</screen>
   </listitem>
  </itemizedlist>
  <para>
   <guimenu>Edit</guimenu>&gt;<guisubmenu>Source
   Code</guisubmenu>&gt;<guisubmenu>Shift Indent Left</guisubmenu>
   (shortcut: <keycombo><keycap>Shift</keycap><keycap>Tab</keycap></keycombo>
   or <keycombo><keycap>Alt</keycap><keycap>Left</keycap></keycombo>)
   adds one level of indent to each selected line, or the current line
   if there is no selection.
  </para>
  <para>
   <guimenu>Edit</guimenu>&gt;<guisubmenu>Source
   Code</guisubmenu>&gt;<guisubmenu>Shift Indent Right</guisubmenu>
   (shortcut: <keycombo><keycap>Alt</keycap><keycap>Right</keycap></keycombo>)
   removes one level of indent from each selected line, or the current line
   if there is no selection. Pressing <keycap>Tab</keycap> while a multi-line
   selection is active has the same effect.
  </para>
  <sect2 id="soft-tabs"><title>Soft Tabs</title>
   <para>
    Because files indented using tab characters may look less than ideal when
    viewed on a system with a different default tab size, it is sometimes
    desirable to use multiple spaces, known as <firstterm>soft tabs</firstterm>,
    instead of real tab characters, to indent code.
   </para>
   <para>
    Soft tabs can be enabled or disabled in one of several ways:
   </para>
   <itemizedlist>
    <listitem><para>On a global or edit mode-specific basis in the
    <guibutton>Editing</guibutton> and <guibutton>Mode-Specific</guibutton>
    panes of the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
    Options</guimenuitem> dialog box.</para></listitem>
    <listitem><para>In the current buffer for
    the duration of the editing session in the
    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Buffer Options</guimenuitem>
    dialog box; see <xref linkend="buffer-opts" />.</para></listitem>
    <listitem><para>In the current buffer for
    future editing sessions by placing the following in one of the first
    or last 10 lines of the buffer, where <replaceable>flag</replaceable> is either
    <quote>true</quote> or <quote>false</quote>:
    </para>
    <screen>:noTabs=<replaceable>flag</replaceable>:</screen>
    </listitem>
   </itemizedlist>
   <para>
    Changing the soft tabs setting has no effect on existing tab characters;
    it only affects subsequently-inserted tabs.
   </para>
   <para>
    <guimenu>Edit</guimenu>&gt;<guisubmenu>Source</guisubmenu>&gt;<guimenuitem>Spaces
    to Tabs</guimenuitem>
    converts soft tabs to hard tabs in the current selection, or the entire
    buffer if nothing is selected.
   </para>
   <para>
    <guimenu>Edit</guimenu>&gt;<guisubmenu>Source</guisubmenu>&gt;<guimenuitem>Tabs
     to Spaces</guimenuitem>
    converts hard tabs to soft tabs in the current selection, or the entire
    buffer if nothing is selected.
   </para>
  </sect2>
  <sect2 id="autoindent"><title>Automatic Indent</title>
   <para>
    The auto indent feature inserts the appropriate number of tabs or
    spaces at the beginning of a line.
   </para>
   <para>
    If indent on enter is enabled, pressing <keycap>Enter</keycap>
    will create a new line with the appropriate amount of
    indent automatically.  If indent on tab is enabled, pressing
    <keycap>Tab</keycap> at the beginning of, or inside the leading
    whitespace of, a line will insert the appropriate amount of
    indentation. Pressing it again will insert a tab character.
   </para>
   <para>
    By default, both indent on enter and indent on tab is enabled.
    This can be changed in one of several ways:
   </para>
   <itemizedlist>
    <listitem><para>On a global or mode-specific
    basis in the <guibutton>Editing</guibutton> and
    <guibutton>Mode-Specific</guibutton> panes
    of the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
    Options</guimenuitem> dialog box.</para></listitem>
    <listitem><para>In the current buffer for the duration of the editing
    session in the
    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Buffer Options</guimenuitem>
    dialog box; see <xref linkend="buffer-opts" />. </para></listitem>
    <listitem><para>In the current buffer for future editing sessions
    by placing the following in the first or last 10 lines of a buffer,
    where <replaceable>flag</replaceable> is either <quote>true</quote> or
    <quote>false</quote>:
    </para>
    <screen>:indentOnEnter=<replaceable>flag</replaceable>:indentOnTab=<replaceable>flag</replaceable>:</screen>
    </listitem>
   </itemizedlist>
   <para>
    Auto indent behavior is mode-specific. In most edit modes,
    the indent of the previous line is simply copied over.
    However, in C-like languages (C, C++, Java, JavaScript), curly
    brackets and language statements are taken into account and indent
    is added and removed as necessary.
   </para>
   <para>
    <guimenu>Edit</guimenu>&gt;<guisubmenu>Source
    Code</guisubmenu>&gt;<guisubmenu>Indent Selected Lines</guisubmenu>
    (shortcut: <keycombo><keycap>Control</keycap><keycap>I</keycap></keycombo>)
    indents all selected lines, or the current line if there is no
    selection.
   </para>
   <para>
    To insert a literal tab or newline without performing
    indentation, prefix the tab or newline with
    <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
    <keycap>V</keycap>. For example,
    to create a new line without any indentation, type
    <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
    <keycap>V</keycap> <keycap>Enter</keycap>.
   </para>
  </sect2>
 </sect1>
 <sect1 id="commenting"><title>Commenting Out Code</title>
  <para>
   Most programming and markup languages support <quote>comments</quote>, or
   regions of  code which are ignored by the compiler/interpreter. jEdit
   has commands which make inserting comments more convenient.
  </para>
  <para>
   Comment strings are mode-specific, and modes such as HTML where
   different parts of a buffer can have different comment strings
   (for example, in HTML text and inline JavaScript) are handled correctly.
  </para>
  <para>
   <guimenu>Edit</guimenu>&gt;<guisubmenu>Source
   Code</guisubmenu>&gt;<guimenuitem>Range Comment</guimenuitem>
   (shortcut: <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
   <keycombo><keycap>Control</keycap><keycap>C</keycap></keycombo>) encloses the
   selection with comment start and end strings, for example <literal>/*</literal>
   and <literal>*/</literal> in Java mode.
  </para>
  <para>
   <guimenu>Edit</guimenu>&gt;<guisubmenu>Source
   Code</guisubmenu>&gt;<guimenuitem>Line Comment</guimenuitem>
   (shortcut: <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
   <keycombo><keycap>Control</keycap><keycap>K</keycap></keycombo>) inserts the
   line comment string, for example <literal>//</literal> in Java mode,
   at the start of each selected line.
  </para>
 </sect1>
 <sect1 id="folding"><title>Folding</title>
  <para>
   Program source code and other structured text files can be thought of
   as a hierarchy of sections, which themselves might contain sub-sections.
   The folding feature lets you selectively hide and show these sections,
   replacing hidden ones with a single line that serves as an
   <quote>overview</quote> of that section.
  </para>
  <para>
   Folding is disabled by default. To enable it, you must choose one of the
   two available <quote>folding modes</quote>. <quote>Indent</quote>
   mode creates folds based on a line's leading whitespace; the more
   leading whitespace a block of text has, the further down it is
   in the hierarchy. For example:
  </para>
  <screen>This is a section
  This is a sub-section
  This is another sub-section
    This is a sub-sub-section
Another top-level section</screen>
  <para>
   <quote>Explicit</quote> mode folds away blocks of
   text surrounded with <quote>{{{</quote> and <quote>}}}</quote>.
   For example:
  </para>
  <screen>{{{ The first line of a fold.
When this fold is collapsed, only the above line will be visible.

{{{ A sub-section.
With text inside it.
}}}

{{{ Another sub-section.
}}}

}}}</screen>
  <para>
   Both modes have distinct advantages and disadvantages; indent folding
   requires no changes to be made to a buffer's text and does a decent
   job with most program source. Explicit folding requires <quote>fold
   markers</quote> to be inserted into the text, but is more flexible in
   exactly what to fold away.
  </para>
  <para>
   Folding can be enabled in one of several ways:
  </para>
  <itemizedlist>
   <listitem><para>On a global or mode-specific
   basis in the <guibutton>Editing</guibutton> and
   <guibutton>Mode-Specific</guibutton> panes
   of the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
   Options</guimenuitem> dialog box.</para></listitem>
   <listitem><para>In the current buffer for the duration of the editing
   session in the
   <guimenu>Utilities</guimenu>&gt;<guimenuitem>Buffer Options</guimenuitem>
   dialog box; see <xref linkend="buffer-opts" />. </para></listitem>
   <listitem><para>In the current buffer for future editing sessions
   by placing the following in the first or last 10 lines of a buffer,
   where <replaceable>mode</replaceable> is either <quote>indent</quote> or
   <quote>explicit</quote>:
   </para>
   <screen>:folding=<replaceable>mode</replaceable>:</screen>
   </listitem>
  </itemizedlist>
  <warning>
   <para>
    When using indent folding, portions of the buffer may become
    inaccessible if you change the leading indent of the first line of a
    collapsed fold. If you experience this, you will need to use the
    <guimenuitem>Expand All Folds</guimenuitem> command to make the text
    visible again.
   </para>
  </warning>
  <sect2><title>Collapsing and Expanding Folds</title>
   <para>
    The first line of each fold has a triangle
    drawn next to it in the gutter (see <xref linkend="textarea"/> for
    more information about the gutter). The triangle points toward the
    line when the fold is collapsed, and downward when the fold is
    expanded.
    Clicking the triangle collapses and
    expands the fold. To expand all sub-folds as well, hold down the
    <keycap>Shift</keycap> while clicking.
   </para>
   <para>
    The first line of a collapsed fold is also drawn
    with a different background color, and the number of lines in the
    fold is shown to the right of the line's text.
   </para>
   <para>
    Folds can also be collapsed and expanded using menu item commands and
    keyboard shortcuts.
   </para>
   <para>
    <guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Collapse
    Fold</guimenuitem> (keyboard shortcut:
    <keycombo><keycap>Alt</keycap><keycap>Backspace</keycap></keycombo>)
    collapses the fold
    containing the caret position.
   </para>
   <para>
    <guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Expand
    Fold One Level</guimenuitem> (keyboard shortcut:
    <keycombo><keycap>Alt</keycap><keycap>Enter</keycap></keycombo>) expands the
    fold containing the caret position. Nested folds will remain collapsed,
    and the caret is positioned on the first nested fold (if any).
   </para>
   <para>
    <guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Expand
    Fold Fully</guimenuitem> (keyboard shortcut:
    <keycombo><keycap>Alt</keycap><keycap>Shift</keycap><keycap>Enter</keycap></keycombo>)
    expands the fold
    containing the caret position, also expanding any nested folds.
   </para>
   <para>
    <guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Collapse
    All Folds</guimenuitem> (keyboard shortcut:
    <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
    <keycap>C</keycap>) collapses all folds in the buffer.
   </para>
   <para>
    <guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Expand
    All Folds</guimenuitem> (keyboard shortcut:
    <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
    <keycap>X</keycap>)
    expands all folds, thus making all lines in the buffer visible.
   </para>
  </sect2>
  <sect2><title>Navigating Around With Folds</title>
   <para>
    <guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Go to Parent
    Fold</guimenuitem> (keyboard shortcut:
    <keycombo><keycap>Alt</keycap><keycap>Up</keycap></keycombo>) moves
    the caret to the fold containing the one at the caret position.
   </para>
   <para>
    <guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Go to Previous
    Fold</guimenuitem> (keyboard shortcut:
    <keycombo><keycap>Alt</keycap><keycap>Up</keycap></keycombo>) moves
    the caret to the fold immediately before the caret position.
   </para>
   <para>
    <guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Go to Next
    Fold</guimenuitem> (keyboard shortcut:
    <keycombo><keycap>Alt</keycap><keycap>Up</keycap></keycombo>) moves
    the caret to the fold immediately after the caret position.
   </para>
  </sect2>
  <sect2><title>Miscellaneous Folding Commands</title>
   <para>
    <guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Add
    Explicit Fold</guimenuitem> (keyboard shortcut:
    <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
    <keycap>A</keycap>) is a convenience command that surrounds the
    selection with <quote>{{{</quote> and <quote>}}}</quote>. If the
    current buffer's edit mode defines comment strings (see
    <xref linkend="commenting" />) the explicit fold markers will
    automatically be commented out as well.
   </para>
   <para>
    <guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Select
    Fold</guimenuitem>
    (keyboard shortcut:
    <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
    <keycap>S</keycap>)
    selects all lines within the fold containing the caret position.
    <keycap>Control</keycap>-clicking a fold expansion triangle
    in the gutter has the same effect.
   </para>
   <para>
    <guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Expand
    Folds With Level</guimenuitem> (keyboard shortcut:
    <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
    <keycap>Enter</keycap> <keycap><replaceable>key</replaceable></keycap>)
    reads the next character entered at the keyboard, and
    expands folds in the buffer
    with a fold level less than that specified, while collapsing all others.
   </para>
   <para>
    You can have all folds with a fold level higher than that specified
    be collapsed automatically when a buffer is loaded. This can be configured
    as follows:
   </para>
   <itemizedlist>
    <listitem><para>On a global or mode-specific
    basis in the <guibutton>Editing</guibutton> and
    <guibutton>Mode-Specific</guibutton> panes
    of the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
    Options</guimenuitem> dialog box.</para></listitem>
    <listitem><para>In the current buffer for future editing sessions
    by placing the following in the first or last 10 lines of a buffer,
    where <replaceable>level</replaceable> is the desired fold level:
    </para>
    <screen>:collapseFolds=<replaceable>level</replaceable>:</screen>
    </listitem>
   </itemizedlist>
  </sect2>
  <sect2 id="narrowing"><title>Narrowing</title>
   <para>
    The narrowing feature temporarily <quote>narrows</quote> the display
    of a buffer to a specified region. Text outside the region is not
    shown, but is still present in the buffer. Both folding and
    narrowing are implemented using the same code internally.
   </para>
   <para>
    <guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Narrow
    Buffer to Fold</guimenuitem> (keyboard shortcut:
    <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
    <keycap>N</keycap> <keycap>N</keycap>) hides all lines the buffer except
    those in the fold containing the caret.
    When this command is invoked, a message is shown in the
    status bar reminding you that you need to invoke
    <guimenuitem>Expand All Folds</guimenuitem> to make the rest of the buffer
    visible again.
   </para>
   <para>
    <guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Narrow
    Buffer to Selection</guimenuitem> (keyboard shortcut:
    <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
    <keycap>N</keycap> <keycap>S</keycap>) hides all lines the buffer
    except those in the selection.
   </para>
   <para>
    <guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Expand
    All Folds</guimenuitem> (keyboard shortcut:
    <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
    <keycap>X</keycap>) will make visible any lines hidden by narrowing.
   </para>
  </sect2>
 </sect1>
</chapter>