1. rcrnstn/vim-unobtrusive-fold
  2. doc
  3. unobtrusive-fold.txt
Browse code

Add implementation

Robert Cranston authored on 03/06/2022 01:42:07
Showing 1 changed files
doc/unobtrusive-fold.txt
History View file @ 214888c
1 1 
new file mode 100644
... ... 
@@ -0,0 +1,107 @@
1 
+*unobtrusive-fold.txt*	A Vim plugin for unobtrusive folds
2 
+Robert Cranston                                             *unobtrusive-fold*
3 
+
4 
+==============================================================================
5 
+CONTENTS                                           *unobtrusive-fold-contents*
6 
+  1. Introduction.....................................|unobtrusive-fold-intro|
7 
+  2. Configuration...................................|unobtrusive-fold-config|
8 
+  3. Commands......................................|unobtrusive-fold-commands|
9 
+  4. Functions....................................|unobtrusive-fold-functions|
10 
+  5. Example........................................|unobtrusive-fold-example|
11 
+  6. About............................................|unobtrusive-fold-about|
12 
+
13 
+==============================================================================
14 
+INTRODUCTION                                          *unobtrusive-fold-intro*
15 
+
16 
+unobtrusive-fold provides commands that define folds from text that blends in
17 
+with the rest of the content, such as comments or markup headings. Optionally,
18 
+this can be combined with folds for indented paragraphs. Folds are
19 
+automatically ended when the indentation drops below that of the line where
20 
+the fold was introduced. It also provides 'foldtext' function and a command
21 
+for debugging 'foldexpr's.
22 
+
23 
+==============================================================================
24 
+CONFIGURATION                                        *unobtrusive-fold-config*
25 
+
26 
+Since this method of folding is more involved than the built-in ones it can be
27 
+slow for very big files. Options are provided to mitigate this.
28 
+
29 
+                                                *g:unobtrusive_fold_max_lines*
30 
+Set to non-zero value to make the commands below do nothing if the number of
31 
+lines in the current buffer is higher than the given value. Defaults to 0.
32 
+
33 
+                                            *g:unobtrusive_fold_max_prevlines*
34 
+Set to non-zero value to look at at most this many previous lines when
35 
+calculating folds. Defaults to 0.
36 
+
37 
+==============================================================================
38 
+COMMANDS                                           *unobtrusive-fold-commands*
39 
+
40 
+:UnobtrusiveFoldComment[!]                           *:UnobtrusiveFoldComment*
41 
+  Sets the current window's 'foldmethod', 'foldexpr', and plugin-internal
42 
+  variables based on the current buffer's 'commentstring'. Does nothing when
43 
+  it is empty. Give ! to enable indented paragraph folding.
44 
+
45 
+  Defines folds with a fold level equal to the number of times the last
46 
+  character (ignoring whitespace) of the first part of 'commentstring' is
47 
+  repeated (not including the first occurrence) at the start of line. For
48 
+  example, if 'commentstring' is `/* %s */`, `/**` starts a level 1 fold,
49 
+  `/***` starts a level 2 fold, etc.
50 
+
51 
+:UnobtrusiveFoldChar[!] {char}                          *:UnobtrusiveFoldChar*
52 
+  Sets the current window's 'foldmethod', 'foldexpr' and plugin-internal
53 
+  variables based on {char}. Lines in syntax groups whose names contain
54 
+  "Comment", "Code", or "Snippet" are ignored. Give ! to enable indented
55 
+  paragraph folding.
56 
+
57 
+  Defines folds with a fold level equal to the number of times {char} is
58 
+  repeated at the start of line (including the first occurrence) at the start
59 
+  of line. For example, if {char} is `#`, `#` starts a level 1 fold, `##`
60 
+  starts a level 2 fold, etc.
61 
+
62 
+:UnobtrusiveFoldDebug                                  *:UnobtrusiveFoldDebug*
63 
+  Inserts the return value of 'foldexpr' and the effective |foldlevel()| into
64 
+  the leftmost columns of the current buffer.
65 
+
66 
+==============================================================================
67 
+FUNCTIONS                                         *unobtrusive-fold-functions*
68 
+
69 
+unobtrusive_fold#text()                              *unobtrusive_fold#text()*
70 
+  Set 'foldtext' to this function to get an improved version of
71 
+  `getline(v:foldstart)`. Leading tabs are expanded to 'tabstop' spaces. If
72 
+  'fillchars' `fold:` is not space, the number of lines included in the fold
73 
+  is printed, padded with `fold:` so that it lines up with one column short of
74 
+  the right edge of the window, or 'textwidth' (if not 0), whichever is
75 
+  smaller. The empty column at the far right is nice for people who set
76 
+  'colorcolumn' to `+1`. The rest of the line is cleared (i.e. not filled
77 
+  automatically by Vim with 'fillchars' `fold:`). A good value for `fold:`
78 
+  might be the box drawing character `─`.
79 
+
80 
+==============================================================================
81 
+EXAMPLE                                             *unobtrusive-fold-example*
82 
+
83 
+Example |vimrc|:
84 
+>
85 
+  set commentstring=
86 
+  set shiftwidth=2
87 
+  set textwidth=79
88 
+  set fillchars+=fold:─
89 
+  set foldtext=unobtrusive_fold#text()
90 
+
91 
+  syntax enable
92 
+  filetype plugin indent on
93 
+
94 
+  autocmd FileType *        UnobtrusiveFoldComment
95 
+  autocmd FileType markdown UnobtrusiveFoldChar #
96 
+<
97 
+
98 
+==============================================================================
99 
+ABOUT                                                 *unobtrusive-fold-about*
100 
+
101 
+Version: 1.0.0
102 
+Author:  Robert Cranston
103 
+License: ISC
104 
+URL:     https://git.rcrnstn.net/rcrnstn/vim-unobtrusive-fold
105 
+
106 
+
107 
+vim:tw=78:ts=8:ft=help:norl: