*usr_28.txt*	For Vim version 6.0c.  Last change: 2000 Jul 08

		     VIM USER MANUAL - by Bram Moolenaar
		
				   Folding


|28.1|	What is folding?
|28.2|  Manual folding
|28.3|  Working with folds
|28.4|  Folding by indent
|28.5|  Folding with markers
|28.6|  Folding by syntax
|28.7|  Folding by expression
|28.8|  Which fold method to use?

     Next chapter: |usr_27.txt|  Search patterns
 Previous chapter: |usr_29.txt|  Editing programs
Table of contents: |usr_toc.txt|

==============================================================================
*28.1*	What is folding?

Folding is used to show a range of lines in the buffer as a single line on the
screen.  Like a piece of paper which is folded to make it shorter:

	+------------------------+
	| line 1                 |
	| line 2                 |
	| line 3                 |
	|_______________________ |
	\                        \
	 \________________________\
	 / folded lines           /
	/________________________/
	| line 12                |
	| line 13                |
	| line 14                |
	+------------------------+

The text is still in the buffer, unchanged.  Only the way lines are displayed
is affected by folding.

The advantage of folding is that you can get a better overview of the
structure of text, by folding lines of a section and replacing it with a line
that indicates that there is a section. 

==============================================================================
*28.2*  Manual folding

Try it out: Position the cursor in a paragraph and type: >
	zfap
You will see that the paragraph is replaced by a highlighted line.  You have
created a fold.  Note that |zf| is an operator and |ap| a text object
selection.  You can use the |zf| operator with any movement command to create
a fold for the text that it moved over.  |zf| also works in Visual mode.

To view the text again, open the fold by typing: >
	zo
And you can close the fold again with: >
	zc

All the folding commands start with 'z'.  With some fantasy, this looks like a
folded piece of papre, seen from the side.  The following letter has a
mnemonic meaning to make it easier to remember the commands:
	zf	F-old creation
	zo	O-pen a fold
	zc	C-lose a fold

Folds can be nested: A region of text that contains folds can be folded
again.  For example, you can fold each paragraph in this chapter, and then
fold the whole chapter.  Try it out.  You will notice that opening the fold
for the whole chapter will restore the nested folds as they were, some may be
open and some may be closed.

Suppose you have created several folds, and now want to view all the text.
You could go to each fold and type "zo".  To do this faster, use this command: >
	zr
This will R-educe the folding.  The opposite is: >
	zm
This folds M-ore.  You can repate "zr" and "zm" to open and close nested folds
of several levels.

If you have nested several levels deep, you can open all of them with: >
	zR
This R-educes folds until there are none left.  And you can close all folds
with: >
	zM
This folds M-ore and M-ore.

You can quickly disable the folding with the |zn| command.  Then |zN| brings
back the folding as it was.  |zi| toggles between the two.  This is a useful
way of working:
- create folds to get overview on your file
- move around to where you want to do your work
- do |zi| to look at the text and edit it
- do |zi| again to go back to moving around

More about manual folding in the reference manual: |fold-manual|

==============================================================================
*28.3*  Working with folds

When some folds are closed, movement commands like "j" and "k" move over a
fold like it was a single, empty line.  This allows you to quickly move around
over folded text.

You can yank delete and put folds as if it was a single line.  This is very
useful if you want to reorder functions in a program.  First make sure that
each fold contains a whole function (or a bit less) by selecting the right
'foldmethod'.  Then delete the function with "dd", move the cursor and put it
with "p".  If some lines of the function are above or below the fold, you can
use Visual selection:
- put the cursor on the first line to be moved
- hit "V" to start Visual mode
- put the cursor on the last line to be moved
- hit "d" to delete the selected lines.
- move the cursor to the new position and "p"ut the lines there.

It is sometimes difficult to see or remember where a fold is located, thus
where a |zo| command would actually work.  To see the defined folds: >
	:set foldcolumn
This will show a small column on the left of the window to indicate folds.
A "-" is shown at the start of each fold.  A number indicates the fold level.

To open all folds at the cursor line use |zO|.
To close all folds at the cursor line use |zC|.
To delete a fold at the cursor line use |zd|.
To delete all folds at the cursor line use |zD|.

When in Insert mode, the cursor line is never folded.  That allows you to see
what you type!

The folding is local to the window.  This allows you to open two windows on
the same buffer, one with folds and one without folds.  Or one with all folds
closed and one with all folds open.

==============================================================================
*28.4*  Folding by indent

Defining folds with |zf| is a lot of work.  If your text is structured by
giving lower level items a larger indent, you can use the indent folding
method.  This will create folds for every sequence of lines with the same
indent.  Lines with a larger indent will become nested folds.  This works well
with many programming languages.

Try this by setting the 'foldmethod' option: >
	:set foldmethod=indent
Then you can use the |zm| and |zr| commands to fold more and reduce folding.
It's easy to see on this example text:

This line is not indented
	This line is indented once
	    	This line is indented twice
	This line is indented once
This line is not indented
	This line is indented once
	This line is indented once

Note that the relation between the amount of indent and the fold depth depends
on the 'shiftwidth' option.  Each 'shiftwidth' worth of indent adds one to the
depth of the fold.  This is called a fold level.

When you use the |zr| and |zm| commands you actually increase or decrease the
'foldlevel' option.  You could also set it directly: >
	:set foldlevel=3
This means that all folds with three times a 'shiftwidth' indent or more will
be closed.  The lower the foldlevel, the more folds will be closed.  When
'foldlevel' is zero, all folds are closed.  |zM| does set 'foldlevel' to zero.
The opposite command |zR| sets 'foldlevel' to the deepest fold level that is
present in the file.

Thus there are two ways to open and close the folds:
(A) By setting the fold level.
    This gives a very quick way of "zooming out" to view the structure of the
    text, move the cursor, and "zoom in" on the text again.

(B) By using |zo| and |zc| commands to open or close specific folds.
    This allows opening only those folds that you want to be open, while other
    folds remain closed.

This can be combined: You can first close most folds by using |zm| a few times
and then open a specific fold with |zo|.  Or open all folds with |zR| and
then close specific folgs with |zc|.

But you cannot manually define folds when 'foldmethod' is "indent", as that
would conflict with the relation between the indent and the fold level.

More about folding by indent in the reference manual: |fold-indent|

==============================================================================
*28.5*  Folding with markers

Markers in the text are used to specify the start and end of a fold region.
This gives precise control over which lines are included in a fold.  The
disadvantage is that the text needs to be modified.

Try it: >
	:set foldmethod=marker

Example text, as it could appear in a C program:

	/* foobar () {{{ */
	int foobar()
	{
		/* return a value {{{ */
		return 42;
		/* }}} */
	}
	/* }}} */

Note that the folded line will display the text before the marker.  This is
very useful to tell what the fold contains.

It's quite annoying when the markers don't pair up correctly after moving some
lines around.  This can be avoided by using numbered markers.  Example:

	/* global variables {{{1 */
	int varA, varB;

	/* functions {{{1 */
	/* funcA() {{{2 */
	void funcA() {}

	/* funcB() {{{2 */
	void funcB() {}
	/* }}}1 */

At every numbered marker a fold at the specified level begins.  This will make
any fold at a higher level stop here.  You can just use numbered start markers
to define all folds.  Only when you want to explicitly stop a fold before
another starts you need to add an end marker.

More about folding with markers in the reference manual: |fold-marker|

==============================================================================
*28.6*  Folding by syntax

Syntax items that have the "fold" argument define a fold region.

More about folding by syntax in the reference manual: |fold-syntax|

==============================================================================
*28.7*  Folding by expression

This is similar to folding by indent, but instead of using the indent of a
line a user function is called to compute the fold level of a line.  You can
use this for text where something in the text indicates which lines belong
together.  An example is an e-mail message where the quoted text is indicated
by a ">" before the line.  To fold these quotes use this: >
	:set foldmethod=expr
	:set foldexpr=strlen(substitute(substitute(getline(v:lnum),'\\s','',\"g\"),'[^>].*','',''))

You can try it out on this text:

> quoted text he wrote
> quoted text he wrote
> > double quoted text I wrote
> > double quoted text I wrote

Explanation for the 'foldexpr' used in the example (inside out):
   getline(v:lnum)			gets the current line
   substitute(...,'\\s','','g') 	removes all white space from the line
   substitute(...,'[^>].*','',''))	removes everything after leading '>'s
   strlen(...)				counts the length of the string, which
					is the number of '>'s found

Note that a backslash must be inserted before every space, double quote and
backslash for the ":set" command.  If this confuses you, do >
	:set foldexpr
to check the actual resulting value.  To correct a complicated expression, use
the command-line completion: >
	:set foldexpr=<Tab>
Where <Tab> is a real Tab.  Vim will fill in the previous value, which you can
then edit.

More about folding by expression in the reference manual: |fold-expr|

==============================================================================
*28.8*  Which fold method to use?

'foldmethod'	'foldlevel'	change text
"manual"          nesting           no
"indent"          indent            no
"expr"            value             no
"marker"          nesting           yes
"syntax"          nesting	    no

TODO

If you use the "expr" method to define folds, but they are not exactly how you
want them, you could switch to the "manual" method.  This will not remove the
defined folds.  Then you can delete or add folds manually.

==============================================================================
 vim:tw=78:
