*usr_28.txt*	Nvim

		     VIM USER MANUAL - by Bram Moolenaar

				   Folding


Structured text can be separated in sections.  And sections in sub-sections.
Folding allows you to display a section as one line, providing an overview.
This chapter explains the different ways this can be done.

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

     Next chapter: |usr_29.txt|  Moving through programs
 Previous chapter: |usr_27.txt|  Search commands and patterns
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.  |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 paper, seen from the side.  The letter after the "z" 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 section, and then
fold all the sections in this 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 repeat "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