8.3 Editing the folding.vim file directly

If you are using version 1.5 of Latex-Suite or older, you will need to directly edit the $VIM/ftplugin/latex-suite/folding.vim file if you wish to modify the folding scheme. You will need to modify the function MakeTexFolds() defined in that file to modify the fold syntax. MakeTexFolds makes a number of calls to AddSyntaxFoldItem. Each such call defines a new "fold item". The order in which these calls are made defines how the folds are nested. For example, if you desire an figure environment to be nested within a section, then you should define the fold for the figure first. The syntax of AddSyntaxFoldItem is as follows:

AddSyntaxFoldItem(startpat, endpat, startoff, endoff [, startskip, endskip])

If the last two arguments are omitted, then they are assumed to default to the empty strings ''. The explanation for each argument is as follows:

startpata line matching this pattern defines the beginning of a fold.
endpat a line matching this pattern defines the end of a fold.
startoff this is the offset from the starting line at which folding will actually start
endoff like startoff, but gives the offset of the actual fold end from the line satisfying endpat. startoff and endoff are necessary when the folding region does not have a specific end pattern corresponding to a start pattern. for example in LaTeX, \section{Section Name} defines the beginning of a section, but there is no command which specifically ends a section. Thus a \section is assumed to end 1 line before another section starts.
startskip A Pattern Which Defines The Beginning Of A "Skipped" Region. For example, suppose we define a \itemize fold as follows:
startpat =  '^\s*\\item',
endpat = '^\s*\\item\|^\s*\\end{\(enumerate\|itemize\|description\)}',
startoff = 0,
endoff = -1
This defines a fold which starts with a line beginning with an \item and ending one line before a line beginning with an \item or \end{enumerate} etc. Then, as long as \item's are not nested things are fine. However, once items begin to nest, the fold started by one \item can end because of an \item in an \itemize environment within this \item. i.e, the following can happen:
\item Some text                         <------- fold will start here
This item will contain a nested item
\begin{itemize}                         <----- fold will end here because next line contains \item...
\item Hello  
\end{itemize}                           <----- ... instead of here.
\item Next item of the parent itemize  
Therefore, in order to completely define a folding item which allows nesting, we need to also define a "skip" pattern. startskip and end skip do that. Leave '' when there is no nesting.
endskip the pattern which defines the end of the "skip" pattern for nested folds.

Example 1

A syntax fold region for the latex section is defined with the following arguments to AddSyntaxFoldItem:

startpat = "\\section{"
endpat   = "\\section{"
startoff = 0
endoff   = -1
startskip = ''
endskip = ''

Note that the start and end patterns are thus the same and endoff has a negative value to capture the effect of a section ending one line before the next starts.

Example 2

A syntax fold region for the \itemize environment is:

startpat = '^\s*\\item',
endpat = '^\s*\\item\|^\s*\\end{\(enumerate\|itemize\|description\)}',
startoff = 0,
endoff = -1,
startskip = '^\s*\\begin{\(enumerate\|itemize\|description\)}',
endskip = '^\s*\\end{\(enumerate\|itemize\|description\)}'

Note the use of startskip and endskip to allow nesting.