/jEdit/tags/jedit-4-5-pre1/doc/users-guide/source-edit.xml

<?xml version="1.0" encoding="UTF-8"?>
<chapter id="source-edit">
    <title>Editing Source Code</title>

    <!-- jEdit buffer-local properties: -->

    <!-- :tabSize=1:indentSize=1:noTabs=true:wrap=soft:maxLineLen=80: -->

    <!-- :xml.root=users-guide.xml: -->

    <section 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>

        <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>

        <section id="mode-selection">
            <title>Mode Selection</title>

            <para>File name and first line matching is done using glob patterns
            similar to those used in Unix shells. Glob patterns associated with
            edit modes can be changed in the <guibutton>Editing</guibutton> pane
            of the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
            Options</guimenuitem> dialog box. Note that the glob patterns must
            match the file name or first line exactly; so to match files whose
            first line contains <literal>begin</literal>, you must use a first
            line glob of <literal>*begin*</literal>. See <xref
            linkend="globs" /> for a description of glob pattern syntax.</para>

            <para>The default edit mode for files which do not match any pattern
            can be set in the <guibutton>Editing</guibutton> pane as
            well.</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>
        </section>

        <section 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>
        </section>
    </section>

    <section 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: <keycap>S+TAB</keycap> or
        <keycap>A+LEFT</keycap>) removes one level of indent from 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: <keycap>A+RIGHT</keycap>) adds one
        level of indent to 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: <keycap>C+e r</keycap>)
        removes all whitespace from the end of each selected line, or the
        current line if there is no selection.</para>

        <section 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>
	 </section>
	
	 <section id="elastic-tabstops">
            <title>Elastic Tabstops</title>

            <para>Elastic tabstops are an alternative way to handle tabstops.
            Elastic tabstops differ from traditional fixed tabstops because 
	     columns in lines above and below the "cell" that is being 
            changed are always kept aligned. As the width of text before a tab 
            character changes, the tabstops on adjacent lines are also 
            changed to fit the widest piece of text in that column. It provides
            certain explicit benefits like it saves time
	     spent on arranging the code and works seemlessly with variable width 
            fonts.But at the same time it can make the code look unorganized 
            on editors that do not support elastic tabstops.</para>

            <para>This feature is known as <firstterm>elastic tabstops</firstterm>.
            Elastic tabstops 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>:elasticTabstops=<replaceable>flag</replaceable>:</screen>
                </listitem>
            </itemizedlist>

            <para>Note that this feature does not work with <firstterm>soft tabs</firstterm>.
            where tabs are emulated as spaces</para>
	 </section>

        <section 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>Indent</guisubmenu>&gt;<guisubmenu>Indent
            Selected Lines</guisubmenu> (shortcut: <keycap>C+i</keycap>) 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 <keycap>C+e v</keycap>.
            For example, to create a new line without any indentation, type
            <keycap>C+e v ENTER</keycap>.</para>
        </section>
    </section>

    <section 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:
        <keycap>C+e C+c</keycap>) 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:
        <keycap>C+e C+k</keycap>) inserts the line comment string, for example
        <literal>//</literal> in Java mode, at the start of each selected
        line.</para>
    </section>

    <section 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>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: <keycap>C+]</keycap>) 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: <keycap>C+[</keycap>) 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: <keycap>C+e C+[</keycap>)
        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: <keycap>C+e C+]</keycap>) 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>

        <tip>
            <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>
        </tip>
    </section>

    <section id="abbrevs">
        <title>Abbreviations</title>

        <para>Abbreviations are invoked by typing a couple of letters and then
        issuing the <guimenu>Edit</guimenu>&gt;<guimenuitem>Expand
        Abbreviation</guimenuitem> (keyboard shortcut: <keycap>C+;</keycap>),
        which takes the word before the caret as the abbreviation name. If that
        particular abbreviation was not yet set, a dialog will pop up, and you
        can enter the text to insert before and after the caret. After the
        abbreviation is created, it can be viewed or edited from the
        <guibutton>Abbreviations</guibutton> pane of the
        <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
        Options</guimenuitem> dialog box; see <xref
        linkend="abbrevs-pane" />.</para>

        <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 <keycap>C+;</keycap>. 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>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></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>

        <section 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>
        </section>
    </section>

    <section 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>

        <section>
            <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="overview" /> 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> (shortcut: <keycap>A+BACK_SPACE</keycap>)
            collapses the fold containing the caret.</para>

            <para><guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Expand Fold
            One Level</guimenuitem> (shortcut: <keycap>A+ENTER</keycap>) expands
            the fold containing the caret. Nested folds will remain collapsed,
            and the caret will be positioned on the first nested fold (if
            any).</para>

            <para><guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Expand Fold
            Fully</guimenuitem> (shortcut: <keycap>AS+ENTER</keycap>) expands
            the fold containing the caret, also expanding any nested
            folds.</para>

            <para><guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Collapse All
            Folds</guimenuitem> (shortcut: <keycap>C+e c</keycap>) collapses all
            folds in the buffer.</para>

            <para><guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Expand All
            Folds</guimenuitem> (shortcut: <keycap>C+e x</keycap>) expands all
            folds in the buffer.</para>
        </section>

        <section>
            <title>Navigating Around With Folds</title>

            <para><guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Go to Parent
            Fold</guimenuitem> (shortcut: <keycap>C+e 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> (shortcut: <keycap>A+UP</keycap>) moves
            the caret to the fold immediately before the caret position.</para>

            <para><guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Go to Next
            Fold</guimenuitem> (shortcut: <keycap>A+DOWN</keycap>) moves the
            caret to the fold immediately after the caret position.</para>
        </section>

        <section>
            <title>Miscellaneous Folding Commands</title>

            <para><guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Add Explicit
            Fold</guimenuitem> (shortcut: <keycap>C+e a</keycap>) 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> (shortcut: <keycap>C+e s</keycap>) selects all
            lines within the fold containing the caret.
            <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> (shortcut: <keycap>C+e ENTER
            <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>
        </section>

        <section 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> (shortcut: <keycap>C+e n 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> (shortcut: <keycap>C+e n s</keycap>)
            hides all lines the buffer except those in the selection.</para>

            <para><guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Expand All
            Folds</guimenuitem> (shortcut: <keycap>C+e x</keycap>) shows lines
            that were hidden as a result of narrowing.</para>
        </section>
    </section>
</chapter>