FastFold, folding optimization              *FastFold* *fastfold*

===========================================================================
0. Introduction ~
                                          *FastFold-intro* *fastfold-intro*

Automatic folds - that is, folds generated by a fold method different
from `manual` - bog down VIM considerably in insert mode. Also, they are often
re-evaluated prematurely for example, when inserting an opening fold marker
whose closing counterpart has yet to be added to complete the fold.

See http://vim.wikia.com/wiki/Keep_folds_closed_while_inserting_text
for a discussion.

With this plug-in, the folds in the currently edited buffer are updated when
certain triggers are met:

- when saving the buffer
- when closing or opening folds (zo, za, zc, etc...)
- when moving or operating fold-wise (zj,zk,[z,]z)
- when typing `zuz` in normal mode

===========================================================================
1. Commands ~
                                    *FastFold-commands* *fastfold-commands*
                                                          *FastFoldUpdate!*

- `:FastFoldUpdate` updates all folds in the current buffer.
- `:FastFoldUpdate!` updates all folds & echoes what fold method was used

- The mapping `zuz` that invokes `:FastFoldUpdate!` can be changed to your
  favorite keystroke, say `<F5>`, by adding
>
    nmap <F5> <Plug>(FastFoldUpdate)
<
  to your `.vimrc`. It can be disabled by adding
>
    nmap <SID>(DisableFastFoldUpdate) <Plug>(FastFoldUpdate)
<
===========================================================================
2. Config ~
                                        *FastFold-config* *fastfold-config*

Each of the above triggers can be enabled or disabled by setting the
matching global flags in your `.vimrc`. Default values are shown.
>
  let g:fastfold_savehook = 1
  let g:fastfold_fdmhook = 0
  nmap zuz <Plug>(FastFoldUpdate)
  let g:fastfold_fold_command_suffixes =  ['x','X','a','A','o','O','c','C']
  let g:fastfold_fold_movement_commands = [']z', '[z', 'zj', 'zk']
<
For example, by adding the following  to your `.vimrc`
>
  let g:tex_fold_enabled=1
  let g:vimsyn_folding='af'
  let g:xml_syntax_folding = 1
  let g:php_folding = 1
  let g:perl_fold = 1
<
You will enable tex, vim, xml, php and perl syntax folding.

Set fold methods for every file type only! Setting it globally risks that
FastFold assumes the wrong, global, fold method instead of that intended by the
file type plug-in, for example TagList.

-----------------------------

- FastFold updates all folds when you open or close folds by the commands
  zx, zX, za, zA, zo, zO, zc, zC. This list of commands is configured by
>
  let g:fastfold_fold_command_suffixes =  ['x','X','a','A','o','O','c','C']
<
  To intercept all possible fold commands (such as zr,zm,...),change this to
>
  let g:fastfold_fold_command_suffixes =
  ['x','X','a','A','o','O','c','C','r','R','m','M','i','n','N']
<
  To disable all interceptions, change this to
>
  let g:fastfold_fold_command_suffixes = []
<
- FastFold updates all fold when you move or operate fold-wise by
  the commands zj,zk,[z or ]z. This list of commands is configured by
>
  let g:fastfold_fold_movement_commands = [']z', '[z', 'zj', 'zk']
<
  It can be disabled by
>
  let g:fastfold_fold_movement_commands = []
<
- FastFold updates all folds when you save a buffer. This hook is set by
>
  let g:fastfold_savehook = 1
<
- FastFold intercepts every change of the fold method by
>
  let g:fastfold_fdmhook = 1
<
  This is disabled by default as it could interfere with other plugins such as
  `easymotion`.

- To disable FastFold for a list of file types, such as 'taglist', add
>
` let g:fastfold_skip_filetypes`= [ 'taglist' ]
<
  to your 'vimrc'. Default value is [].

- Add a fold text-object, mapped to `iz` and `az`, by adding the lines

  xnoremap iz :<c-u>FastFoldUpdate<cr><esc>:<c-u>normal! ]zv[z<cr>
  xnoremap az :<c-u>FastFoldUpdate<cr><esc>:<c-u>normal! ]zV[z<cr>

    to your 'vimrc'.
===========================================================================
3. Extra Notes ~

3.1 Related Plugins ~

`FastFold` integrates with the plug-in `vim-stay` available at

https://github.com/kopischke/vim-stay

that stores and restores the last folds by `:mkview` and `:loadview`.

------------------------------

A fold-text function `CustomFoldText()` that displays the percentage of the
number of buffer lines that the folded text takes up and indents folds
according to their nesting level is available at

http://www.github.com/Konfekt/FoldText

3.2 Warning ~

FastFold overwrites your manual folds when saving the currently edited buffer,
unless

- FastFold is disabled for this filetype by `g:fastfold_skip_filetypes`, or
- the `foldmethod=manual` since having entered the buffer.

3.3 API ~

The last used fold method by which FastFold updates the folds in the current
buffer can be read off from the window local variable `w:lastdfm`.

3.4 Thanks go to... ~

- starcraftman for providing this documentation, and
- blueyed, kopischke, sabauma, willywampa, and many others for reporting
issues and suggesting code improvements.

vim:tw=78:ts=2:sts=2:sw=2:ft=help:norl