/jEdit/tags/jedit-4-2-pre4/doc/users-guide/source-edit.xml

<!-- jEdit buffer-local properties: -->
<!-- :tabSize=1:indentSize=1:noTabs=true:wrap=soft:maxLineLen=80: -->
<!-- :xml.root=users-guide.xml: -->

<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 existing 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 <filename>.c</filename>
    are opened with C mode, and files named <filename>Makefile</filename> are
    opened with 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 <filename>#!/bin/sh</filename> are opened with shell script mode.
   </para>
   <para>
    File name and first line globs can be changed in the
    <guibutton>Editing</guibutton> pane of the
    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
    dialog box. See <xref linkend="globs"/> for information about glob patterns.
    The default edit mode for files which do not match any pattern can also be set in the <guibutton>Editing</guibutton> pane.
   </para>
   <para>
    The edit mode can be specified manually as well. 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>
  </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 some kind of syntax highlighting.
   </para>
   <para>
    The colors and styles used to highlight syntax tokens can be changed
    in the <guibutton>Syntax Highlighting</guibutton> pane of the
    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
    dialog box; see <xref linkend="syntax-hilite-pane" />.
   </para>
  </sect2>
 </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 hard 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 auto indent routines. Both can be
   changed in one of several ways:
  </para>
  <itemizedlist>
   <listitem><para>On a global or mode-specific basis in the
   <guibutton>Editing</guibutton> pane
   of the the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
   Options</guimenuitem> dialog box. See <xref linkend="editing-pane"/>.
   </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>Indent</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>Indent</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>
  <para>
   <guimenu>Edit</guimenu>&gt;<guisubmenu>Indent</guisubmenu>&gt;<guimenuitem>Remove
   Trailing Whitespace</guimenuitem>
   (shortcut: <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
   <keycap>R</keycap>) removes all whitespace from the end of each selected line, or
   the current line if there is no selection.
  </para>
  <sect2 id="soft-tabs"><title>Soft Tabs</title>
   <para>
    Files containing hard tab characters may look less than ideal if
    the default tab size is changed, so some people prefer using
    multiple space characters instead of hard tabs to indent code.
   </para>
   <para>
    This feature is known as <firstterm>soft tabs</firstterm>.
    Soft tabs can be enabled or disabled in one of several ways:
   </para>
   <itemizedlist>
    <listitem><para>On a global or mode-specific basis in the
    <guibutton>Editing</guibutton> pane of the
    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
    Options</guimenuitem> dialog box. See <xref linkend="editing-pane"/>.</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>Indent</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>Indent</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 by looking at program structure.
   </para>
   <para>
    In the default configuration, pressing <keycap>Enter</keycap>
    will create a new line with the appropriate amount of
    indent automatically, and 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>
    The behavior of the <keycap>Enter</keycap> and <keycap>Tab</keycap> keys can
    be configured in the <guibutton>Shortcuts</guibutton> pane of the
    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
    dialog. box, just as with any other key. The <keycap>Enter</keycap> key can be bound
    to one of the following, or indeed any other command or macro:
   </para>
   <itemizedlist>
    <listitem><para><guimenuitem>Insert Newline</guimenuitem>.</para></listitem>
    <listitem><para><guimenuitem>Insert Newline and Indent</guimenuitem>, which
    is the default.</para></listitem>
   </itemizedlist>
   <para>
    The <keycap>Tab</keycap> can be bound to one of the following, or again,
    any other command or macro:
   </para>
   <itemizedlist>
    <listitem><para><guimenuitem>Insert Tab</guimenuitem>.</para></listitem>
    <listitem><para><guimenuitem>Insert Tab or Indent</guimenuitem>, which is
    the default.</para></listitem>
    <listitem><para><guimenuitem>Indent Selected Lines</guimenuitem>.</para></listitem>
   </itemizedlist>
   <para>
    See <xref linkend="shortcuts-pane"/> for details.
   </para>
   <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</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 the notion of
   <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 some in some modes such as HTML
   different parts of a buffer can have different comment strings.
   For example, in HTML files, different comment strings are used for
   HTML text and inline JavaScript.
  </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="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 before or 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>previous line</emphasis> is shown instead. This
   feature is very useful when your code is indented as follows, with braces
   on their own lines:
  </para>
  <programlisting>public void someMethod()
{
    if(isOK)
    {
        doSomething();
    }
}</programlisting>
  <para>
   Invoking
   <guimenu>Edit</guimenu>&gt;<guisubmenu>Source</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
   matching bracket.
  </para>
  <para>
   <guimenu>Edit</guimenu>&gt;<guisubmenu>Source</guisubmenu>&gt;<guimenuitem>Select
   Code Block</guimenuitem>
   (shortcut: <keycombo><keycap>Control</keycap><keycap>[</keycap></keycombo>)
   selects all text between the closest two brackets surrounding the caret.
  </para>
  <para>
   Holding down <keycap>Control</keycap> while clicking the scope indicator
   in the gutter or a bracket in the text area will select all text
   between the two matching brackets.
  </para>
  <para>
   <guimenu>Edit</guimenu>&gt;<guisubmenu>Source</guisubmenu>&gt;<guimenuitem>Go
   to Previous Bracket</guimenuitem> (shortcut:
   <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
   <keycombo><keycap>Control</keycap><keycap>[</keycap></keycombo>) moves the
   caret to the previous opening bracket.
  </para>
  <para>
   <guimenu>Edit</guimenu>&gt;<guisubmenu>Source</guisubmenu>&gt;<guimenuitem>Go
   to Next Bracket</guimenuitem> (shortcut:
   <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
   <keycombo><keycap>Control</keycap><keycap>]</keycap></keycombo>)
   moves the caret to the next closing bracket.
  </para>
  <para>
   Bracket highlighting in the text area and bracket scope display in the
   gutter can be customized 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, so for example unmatched brackets inside string
    literals and comments will be skipped when matching brackets that are part of
    program syntax.
   </para>
  </note>
 </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>.
   An abbreviation can either be global, in which case it can be used in all
   edit modes, or specific to a single mode.
  </para>
  <para>
   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="abbrevs-pane" />. The Java, VHDL. XML and XSL edit
   modes include some pre-defined abbreviations you might find useful. Other
   modes do not have any abbreviations defined by default.
  </para>
  <para>
   <guimenu>Edit</guimenu>&gt;<guimenuitem>Expand Abbreviation</guimenuitem>
   (keyboard shortcut: <keycombo><keycap>Control</keycap><keycap>;</keycap></keycombo>)
   attempts to expand the abbreviation named by 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. 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>
    Java mode defines 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>
    Expanding <literal>F#j#array.length#</literal> will insert the following
    text into the buffer:
   </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 be
    blank in the expansion, and extra parameters will be ignored.
    A status bar message will be shown stating
    the required number of parameters.
   </para>
  </sect2>
 </sect1>
 <sect1 id="folding"><title>Folding</title>
  <para>
   Program source code and other structured text files can be thought of
   as containing 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.
   Folding is disabled by default. To enable it, you must choose one of the
   available folding modes.
  </para>
  <para>
  <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>
   Some plugins might add additional folding modes; see
   <xref linkend="using-plugins"/> for information about plugins.
  </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> pane
   of the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
   Options</guimenuitem> dialog box. See <xref linkend="editing-pane"/>.</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>,
   <quote>explicit</quote>, or the name of a plugin folding mode:
   </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 can 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 drawn
    with a background color that depends on the fold level, 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 in the buffer.
   </para>
  </sect2>
  <sect2><title>Navigating Around With Folds</title>
   <para>
    <guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Go to Parent
    Fold</guimenuitem> (keyboard shortcut:
    <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
    <keycap>U</keycap>) 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>Down</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>
    Sometimes it is desirable to have files open with folds initially
    collapsed. This can be configured as follows:
   </para>
   <itemizedlist>
    <listitem><para>On a global or mode-specific
    basis in the <guibutton>Editing</guibutton> pane
    of the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
    Options</guimenuitem> dialog box. See <xref linkend="editing-pane"/>.</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>
    Holding down <keycap>Alt</keycap> while clicking a fold expansion triangle in the gutter will hide all lines the buffer except
    those contained in the clicked fold.
   </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>) shows lines that were hidden as a result of narrowing.
   </para>
  </sect2>
 </sect1>
</chapter>