updated for version 7.0001
diff --git a/runtime/doc/usr_28.txt b/runtime/doc/usr_28.txt
new file mode 100644
index 0000000..522dc3f
--- /dev/null
+++ b/runtime/doc/usr_28.txt
@@ -0,0 +1,426 @@
+*usr_28.txt* For Vim version 7.0aa. Last change: 2003 Dec 21
+
+ 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 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=4
+
+This will show a small column on the left of the window to indicate folds.
+A "+" is shown for a closed fold. A "-" is shown at the start of each open
+fold and "|" at following lines of the fold.
+
+You can use the mouse to open a fold by clicking on the "+" in the foldcolumn.
+Clicking on the "-" or a "|" below it will close an open fold.
+
+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 fold at the cursor line is never closed. That allows
+you to see what you type!
+
+Folds are opened automatically when jumping around or moving the cursor left
+or right. For example, the "0" command opens the fold under the cursor
+(if 'foldopen' contains "hor", which is the default). The 'foldopen' option
+can be changed to open folds for specific commands. If you want the line
+under the cursor always to be open, do this: >
+
+ :set foldopen=all
+
+Warning: You won't be able to move onto a closed fold then. You might want to
+use this only temporarily and then set it back to the default: >
+
+ :set foldopen&
+
+You can make folds close automatically when you move out of it: >
+
+ :set foldclose=all
+
+This will re-apply 'foldlevel' to all folds that don't contain the cursor.
+You have to try it out if you like how this feels. Use |zm| to fold more and
+|zr| to fold less (reduce folds).
+
+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* Saving and restoring folds
+
+When you abandon a file (starting to edit another one), the state of the folds
+is lost. If you come back to the same file later, all manually opened and
+closed folds are back to their default. When folds have been created
+manually, all folds are gone! To save the folds use the |:mkview| command: >
+
+ :mkview
+
+This will store the settings and other things that influence the view on the
+file. You can change what is stored with the 'viewoptions' option.
+When you come back to the same file later, you can load the view again: >
+
+ :loadview
+
+You can store up to ten views on one file. For example, to save the current
+setup as the third view and load the second view: >
+
+ :mkview 3
+ :loadview 2
+
+Note that when you insert or delete lines the views might become invalid.
+Also check out the 'viewdir' option, which specifies where the views are
+stored. You might want to delete old views now and then.
+
+==============================================================================
+*28.5* 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 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 folds 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.6* 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;
+ /* }}} */
+ }
+ /* }}} */
+
+Notice 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.7* Folding by syntax
+
+For each language Vim uses a different syntax file. This defines the colors
+for various items in the file. If you are reading this in Vim, in a terminal
+that supports colors, the colors you see are made with the "help" syntax file.
+ In the syntax files it is possible to add syntax items that have the "fold"
+argument. These define a fold region. This requires writing a syntax file
+and adding these items in it. That's not so easy to do. But once it's done,
+all folding happens automatically.
+ Here we'll assume you are using an existing syntax file. Then there is
+nothing more to explain. You can open and close folds as explained above.
+The folds will be created and deleted automatically when you edit the file.
+
+More about folding by syntax in the reference manual: |fold-syntax|
+
+==============================================================================
+*28.8* 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.
+
+When the expression gets more complicated you should put it in a function and
+set 'foldexpr' to call that function.
+
+More about folding by expression in the reference manual: |fold-expr|
+
+==============================================================================
+*28.9* Folding unchanged lines
+
+This is useful when you set the 'diff' option in the same window. The
+|vimdiff| command does this for you. Example: >
+
+ setlocal diff foldmethod=diff scrollbind nowrap foldlevel=1
+
+Do this in every window that shows a different version of the same file. You
+will clearly see the differences between the files, while the text that didn't
+change is folded.
+
+For more details see |fold-diff|.
+
+==============================================================================
+*28.10* Which fold method to use?
+
+All these possibilities makes you wonder which method you should chose.
+Unfortunately, there is no golden rule. Here are some hints.
+
+If there is a syntax file with folding for the language you are editing, that
+is probably the best choice. If there isn't one, you might try to write it.
+This requires a good knowledge of search patterns. It's not easy, but when
+it's working you will not have to define folds manually.
+
+Typing commands to manually fold regions can be used for unstructured text.
+Then use the |:mkview| command to save and restore your folds.
+
+The marker method requires you to change the file. If you are sharing the
+files with other people or you have to meet company standards, you might not
+be allowed to add them.
+ The main advantage of markers is that you can put them exactly where you
+want them. That avoids that a few lines are missed when you cut and paste
+folds. And you can add a comment about what is contained in the fold.
+
+Folding by indent is something that works in many files, but not always very
+well. Use it when you can't use one of the other methods. However, it is
+very useful for outlining. Then you specifically use one 'shiftwidth' for
+each nesting level.
+
+Folding with expressions can make folds in almost any structured text. It is
+quite simple to specify, especially if the start and end of a fold can easily
+be recognized.
+ 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.
+
+==============================================================================
+
+Next chapter: |usr_29.txt| Moving through programs
+
+Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: