*unobtrusive-fold.txt*	A Vim plugin for unobtrusive folds
Robert Cranston                                             *unobtrusive-fold*

==============================================================================
CONTENTS                                           *unobtrusive-fold-contents*
  1. Introduction.....................................|unobtrusive-fold-intro|
  2. Configuration...................................|unobtrusive-fold-config|
  3. Commands......................................|unobtrusive-fold-commands|
  4. Functions....................................|unobtrusive-fold-functions|
  5. Example........................................|unobtrusive-fold-example|
  6. About............................................|unobtrusive-fold-about|

==============================================================================
INTRODUCTION                                          *unobtrusive-fold-intro*

unobtrusive-fold provides commands that define folds from text that blends in
with the rest of the content, such as comments or markup headings. Optionally,
this can be combined with folds for indented paragraphs. Folds are
automatically ended when the indentation drops below that of the line where
the fold was introduced. It also provides 'foldtext' function and a command
for debugging 'foldexpr's.

==============================================================================
CONFIGURATION                                        *unobtrusive-fold-config*

Since this method of folding is more involved than the built-in ones it can be
slow for very big files. Options are provided to mitigate this.

                                                *g:unobtrusive_fold_max_lines*
Set to non-zero value to make the commands below do nothing if the number of
lines in the current buffer is higher than the given value. Defaults to 0.

                                            *g:unobtrusive_fold_max_prevlines*
Set to non-zero value to look at at most this many previous lines when
calculating folds. Defaults to 0.

==============================================================================
COMMANDS                                           *unobtrusive-fold-commands*

:UnobtrusiveFoldComment[!]                           *:UnobtrusiveFoldComment*
  Sets the current window's 'foldmethod', 'foldexpr', and plugin-internal
  variables based on the current buffer's 'commentstring'. Does nothing when
  it is empty. Give ! to enable indented paragraph folding.

  Defines folds with a fold level equal to the number of times the last
  character (ignoring whitespace) of the first part of 'commentstring' is
  repeated (not including the first occurrence) at the start of line. For
  example, if 'commentstring' is `/* %s */`, `/**` starts a level 1 fold,
  `/***` starts a level 2 fold, etc.

:UnobtrusiveFoldChar[!] {char}                          *:UnobtrusiveFoldChar*
  Sets the current window's 'foldmethod', 'foldexpr' and plugin-internal
  variables based on {char}. Lines in syntax groups whose names contain
  "Comment", "Code", or "Snippet" are ignored. Give ! to enable indented
  paragraph folding.

  Defines folds with a fold level equal to the number of times {char} is
  repeated at the start of line (including the first occurrence) at the start
  of line. For example, if {char} is `#`, `#` starts a level 1 fold, `##`
  starts a level 2 fold, etc.

:UnobtrusiveFoldDebug                                  *:UnobtrusiveFoldDebug*
  Inserts the return value of 'foldexpr' and the effective |foldlevel()| into
  the leftmost columns of the current buffer.

==============================================================================
FUNCTIONS                                         *unobtrusive-fold-functions*

unobtrusive_fold#text()                              *unobtrusive_fold#text()*
  Set 'foldtext' to this function to get an improved version of
  `getline(v:foldstart)`. Leading tabs are expanded to 'tabstop' spaces. If
  'fillchars' `fold:` is not space, the number of lines included in the fold
  is printed, padded with `fold:` so that it lines up with one column short of
  the right edge of the window, or 'textwidth' (if not 0), whichever is
  smaller. The empty column at the far right is nice for people who set
  'colorcolumn' to `+1`. The rest of the line is cleared (i.e. not filled
  automatically by Vim with 'fillchars' `fold:`). A good value for `fold:`
  might be the box drawing character `─`.

==============================================================================
EXAMPLE                                             *unobtrusive-fold-example*

Example |vimrc|:
>
  set commentstring=
  set shiftwidth=2
  set textwidth=79
  set fillchars+=fold:─
  set foldtext=unobtrusive_fold#text()

  syntax enable
  filetype plugin indent on

  autocmd FileType *        UnobtrusiveFoldComment
  autocmd FileType markdown UnobtrusiveFoldChar #
<

==============================================================================
ABOUT                                                 *unobtrusive-fold-about*

Version: 1.0.0
Author:  Robert Cranston
License: ISC
URL:     https://git.rcrnstn.net/rcrnstn/vim-unobtrusive-fold


vim:tw=78:ts=8:ft=help:norl: