Mercurial > vim
annotate runtime/doc/usr_28.txt @ 10688:3d1872fbecc4 v8.0.0234
patch 8.0.0234: crash when using put in Visual mode
commit https://github.com/vim/vim/commit/941c12da3c087fd04aa6c120a76bf28f19349d96
Author: Bram Moolenaar <Bram@vim.org>
Date: Tue Jan 24 19:55:43 2017 +0100
patch 8.0.0234: crash when using put in Visual mode
Problem: When several lines are visually selected and one of them is short,
using put may cause a crash. (Axel Bender)
Solution: Check for a short line. (Christian Brabandt)
author | Christian Brabandt <cb@256bit.org> |
---|---|
date | Tue, 24 Jan 2017 20:00:04 +0100 |
parents | 9f48eab77d62 |
children | 1174611ad715 |
rev | line source |
---|---|
10198
9f48eab77d62
commit https://github.com/vim/vim/commit/bb76f24af2010943387ce696a7092175b4ecccf2
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
1 *usr_28.txt* For Vim version 8.0. Last change: 2008 Jun 14 |
7 | 2 |
3 VIM USER MANUAL - by Bram Moolenaar | |
4 | |
5 Folding | |
6 | |
7 | |
8 Structured text can be separated in sections. And sections in sub-sections. | |
9 Folding allows you to display a section as one line, providing an overview. | |
10 This chapter explains the different ways this can be done. | |
11 | |
12 |28.1| What is folding? | |
13 |28.2| Manual folding | |
14 |28.3| Working with folds | |
15 |28.4| Saving and restoring folds | |
16 |28.5| Folding by indent | |
17 |28.6| Folding with markers | |
18 |28.7| Folding by syntax | |
19 |28.8| Folding by expression | |
20 |28.9| Folding unchanged lines | |
4119 | 21 |28.10| Which fold method to use? |
7 | 22 |
23 Next chapter: |usr_29.txt| Moving through programs | |
24 Previous chapter: |usr_27.txt| Search commands and patterns | |
25 Table of contents: |usr_toc.txt| | |
26 | |
27 ============================================================================== | |
28 *28.1* What is folding? | |
29 | |
30 Folding is used to show a range of lines in the buffer as a single line on the | |
31 screen. Like a piece of paper which is folded to make it shorter: | |
32 | |
33 +------------------------+ | |
34 | line 1 | | |
35 | line 2 | | |
36 | line 3 | | |
37 |_______________________ | | |
38 \ \ | |
39 \________________________\ | |
40 / folded lines / | |
41 /________________________/ | |
42 | line 12 | | |
43 | line 13 | | |
44 | line 14 | | |
45 +------------------------+ | |
46 | |
47 The text is still in the buffer, unchanged. Only the way lines are displayed | |
48 is affected by folding. | |
49 | |
50 The advantage of folding is that you can get a better overview of the | |
51 structure of text, by folding lines of a section and replacing it with a line | |
52 that indicates that there is a section. | |
53 | |
54 ============================================================================== | |
55 *28.2* Manual folding | |
56 | |
57 Try it out: Position the cursor in a paragraph and type: > | |
58 | |
59 zfap | |
60 | |
61 You will see that the paragraph is replaced by a highlighted line. You have | |
62 created a fold. |zf| is an operator and |ap| a text object selection. You | |
63 can use the |zf| operator with any movement command to create a fold for the | |
64 text that it moved over. |zf| also works in Visual mode. | |
65 | |
66 To view the text again, open the fold by typing: > | |
67 | |
68 zo | |
69 | |
70 And you can close the fold again with: > | |
71 | |
72 zc | |
73 | |
74 All the folding commands start with "z". With some fantasy, this looks like a | |
75 folded piece of paper, seen from the side. The letter after the "z" has a | |
76 mnemonic meaning to make it easier to remember the commands: | |
77 | |
78 zf F-old creation | |
79 zo O-pen a fold | |
80 zc C-lose a fold | |
81 | |
82 Folds can be nested: A region of text that contains folds can be folded | |
83 again. For example, you can fold each paragraph in this section, and then | |
84 fold all the sections in this chapter. Try it out. You will notice that | |
85 opening the fold for the whole chapter will restore the nested folds as they | |
86 were, some may be open and some may be closed. | |
87 | |
88 Suppose you have created several folds, and now want to view all the text. | |
89 You could go to each fold and type "zo". To do this faster, use this command: > | |
90 | |
91 zr | |
92 | |
93 This will R-educe the folding. The opposite is: > | |
94 | |
95 zm | |
96 | |
97 This folds M-ore. You can repeat "zr" and "zm" to open and close nested folds | |
98 of several levels. | |
99 | |
100 If you have nested several levels deep, you can open all of them with: > | |
101 | |
102 zR | |
103 | |
104 This R-educes folds until there are none left. And you can close all folds | |
105 with: > | |
106 | |
107 zM | |
108 | |
109 This folds M-ore and M-ore. | |
110 | |
111 You can quickly disable the folding with the |zn| command. Then |zN| brings | |
112 back the folding as it was. |zi| toggles between the two. This is a useful | |
113 way of working: | |
114 - create folds to get overview on your file | |
115 - move around to where you want to do your work | |
116 - do |zi| to look at the text and edit it | |
117 - do |zi| again to go back to moving around | |
118 | |
119 More about manual folding in the reference manual: |fold-manual| | |
120 | |
121 ============================================================================== | |
122 *28.3* Working with folds | |
123 | |
124 When some folds are closed, movement commands like "j" and "k" move over a | |
125 fold like it was a single, empty line. This allows you to quickly move around | |
126 over folded text. | |
127 | |
128 You can yank, delete and put folds as if it was a single line. This is very | |
129 useful if you want to reorder functions in a program. First make sure that | |
130 each fold contains a whole function (or a bit less) by selecting the right | |
131 'foldmethod'. Then delete the function with "dd", move the cursor and put it | |
132 with "p". If some lines of the function are above or below the fold, you can | |
133 use Visual selection: | |
134 - put the cursor on the first line to be moved | |
135 - hit "V" to start Visual mode | |
136 - put the cursor on the last line to be moved | |
137 - hit "d" to delete the selected lines. | |
138 - move the cursor to the new position and "p"ut the lines there. | |
139 | |
140 It is sometimes difficult to see or remember where a fold is located, thus | |
141 where a |zo| command would actually work. To see the defined folds: > | |
142 | |
143 :set foldcolumn=4 | |
144 | |
145 This will show a small column on the left of the window to indicate folds. | |
146 A "+" is shown for a closed fold. A "-" is shown at the start of each open | |
147 fold and "|" at following lines of the fold. | |
148 | |
149 You can use the mouse to open a fold by clicking on the "+" in the foldcolumn. | |
150 Clicking on the "-" or a "|" below it will close an open fold. | |
151 | |
152 To open all folds at the cursor line use |zO|. | |
153 To close all folds at the cursor line use |zC|. | |
154 To delete a fold at the cursor line use |zd|. | |
155 To delete all folds at the cursor line use |zD|. | |
156 | |
157 When in Insert mode, the fold at the cursor line is never closed. That allows | |
158 you to see what you type! | |
159 | |
160 Folds are opened automatically when jumping around or moving the cursor left | |
161 or right. For example, the "0" command opens the fold under the cursor | |
162 (if 'foldopen' contains "hor", which is the default). The 'foldopen' option | |
163 can be changed to open folds for specific commands. If you want the line | |
164 under the cursor always to be open, do this: > | |
165 | |
166 :set foldopen=all | |
167 | |
168 Warning: You won't be able to move onto a closed fold then. You might want to | |
169 use this only temporarily and then set it back to the default: > | |
170 | |
171 :set foldopen& | |
172 | |
173 You can make folds close automatically when you move out of it: > | |
174 | |
175 :set foldclose=all | |
176 | |
177 This will re-apply 'foldlevel' to all folds that don't contain the cursor. | |
178 You have to try it out if you like how this feels. Use |zm| to fold more and | |
179 |zr| to fold less (reduce folds). | |
180 | |
181 The folding is local to the window. This allows you to open two windows on | |
182 the same buffer, one with folds and one without folds. Or one with all folds | |
183 closed and one with all folds open. | |
184 | |
185 ============================================================================== | |
186 *28.4* Saving and restoring folds | |
187 | |
188 When you abandon a file (starting to edit another one), the state of the folds | |
189 is lost. If you come back to the same file later, all manually opened and | |
190 closed folds are back to their default. When folds have been created | |
191 manually, all folds are gone! To save the folds use the |:mkview| command: > | |
192 | |
193 :mkview | |
194 | |
195 This will store the settings and other things that influence the view on the | |
196 file. You can change what is stored with the 'viewoptions' option. | |
197 When you come back to the same file later, you can load the view again: > | |
198 | |
199 :loadview | |
200 | |
201 You can store up to ten views on one file. For example, to save the current | |
202 setup as the third view and load the second view: > | |
203 | |
204 :mkview 3 | |
205 :loadview 2 | |
206 | |
207 Note that when you insert or delete lines the views might become invalid. | |
208 Also check out the 'viewdir' option, which specifies where the views are | |
209 stored. You might want to delete old views now and then. | |
210 | |
211 ============================================================================== | |
212 *28.5* Folding by indent | |
213 | |
214 Defining folds with |zf| is a lot of work. If your text is structured by | |
215 giving lower level items a larger indent, you can use the indent folding | |
216 method. This will create folds for every sequence of lines with the same | |
217 indent. Lines with a larger indent will become nested folds. This works well | |
218 with many programming languages. | |
219 | |
220 Try this by setting the 'foldmethod' option: > | |
221 | |
222 :set foldmethod=indent | |
223 | |
224 Then you can use the |zm| and |zr| commands to fold more and reduce folding. | |
225 It's easy to see on this example text: | |
226 | |
227 This line is not indented | |
228 This line is indented once | |
229 This line is indented twice | |
230 This line is indented twice | |
231 This line is indented once | |
232 This line is not indented | |
233 This line is indented once | |
234 This line is indented once | |
235 | |
236 Note that the relation between the amount of indent and the fold depth depends | |
237 on the 'shiftwidth' option. Each 'shiftwidth' worth of indent adds one to the | |
238 depth of the fold. This is called a fold level. | |
239 | |
240 When you use the |zr| and |zm| commands you actually increase or decrease the | |
241 'foldlevel' option. You could also set it directly: > | |
242 | |
243 :set foldlevel=3 | |
244 | |
245 This means that all folds with three times a 'shiftwidth' indent or more will | |
246 be closed. The lower the foldlevel, the more folds will be closed. When | |
247 'foldlevel' is zero, all folds are closed. |zM| does set 'foldlevel' to zero. | |
248 The opposite command |zR| sets 'foldlevel' to the deepest fold level that is | |
249 present in the file. | |
250 | |
251 Thus there are two ways to open and close the folds: | |
252 (A) By setting the fold level. | |
253 This gives a very quick way of "zooming out" to view the structure of the | |
254 text, move the cursor, and "zoom in" on the text again. | |
255 | |
256 (B) By using |zo| and |zc| commands to open or close specific folds. | |
257 This allows opening only those folds that you want to be open, while other | |
258 folds remain closed. | |
259 | |
260 This can be combined: You can first close most folds by using |zm| a few times | |
261 and then open a specific fold with |zo|. Or open all folds with |zR| and | |
262 then close specific folds with |zc|. | |
263 | |
264 But you cannot manually define folds when 'foldmethod' is "indent", as that | |
265 would conflict with the relation between the indent and the fold level. | |
266 | |
267 More about folding by indent in the reference manual: |fold-indent| | |
268 | |
269 ============================================================================== | |
270 *28.6* Folding with markers | |
271 | |
272 Markers in the text are used to specify the start and end of a fold region. | |
273 This gives precise control over which lines are included in a fold. The | |
274 disadvantage is that the text needs to be modified. | |
275 | |
276 Try it: > | |
277 | |
278 :set foldmethod=marker | |
279 | |
280 Example text, as it could appear in a C program: | |
281 | |
282 /* foobar () {{{ */ | |
283 int foobar() | |
284 { | |
285 /* return a value {{{ */ | |
286 return 42; | |
287 /* }}} */ | |
288 } | |
289 /* }}} */ | |
290 | |
291 Notice that the folded line will display the text before the marker. This is | |
292 very useful to tell what the fold contains. | |
293 | |
294 It's quite annoying when the markers don't pair up correctly after moving some | |
295 lines around. This can be avoided by using numbered markers. Example: | |
296 | |
297 /* global variables {{{1 */ | |
298 int varA, varB; | |
299 | |
300 /* functions {{{1 */ | |
301 /* funcA() {{{2 */ | |
302 void funcA() {} | |
303 | |
304 /* funcB() {{{2 */ | |
305 void funcB() {} | |
306 /* }}}1 */ | |
307 | |
308 At every numbered marker a fold at the specified level begins. This will make | |
309 any fold at a higher level stop here. You can just use numbered start markers | |
310 to define all folds. Only when you want to explicitly stop a fold before | |
311 another starts you need to add an end marker. | |
312 | |
313 More about folding with markers in the reference manual: |fold-marker| | |
314 | |
315 ============================================================================== | |
316 *28.7* Folding by syntax | |
317 | |
318 For each language Vim uses a different syntax file. This defines the colors | |
319 for various items in the file. If you are reading this in Vim, in a terminal | |
320 that supports colors, the colors you see are made with the "help" syntax file. | |
321 In the syntax files it is possible to add syntax items that have the "fold" | |
322 argument. These define a fold region. This requires writing a syntax file | |
323 and adding these items in it. That's not so easy to do. But once it's done, | |
324 all folding happens automatically. | |
325 Here we'll assume you are using an existing syntax file. Then there is | |
326 nothing more to explain. You can open and close folds as explained above. | |
327 The folds will be created and deleted automatically when you edit the file. | |
328 | |
329 More about folding by syntax in the reference manual: |fold-syntax| | |
330 | |
331 ============================================================================== | |
332 *28.8* Folding by expression | |
333 | |
334 This is similar to folding by indent, but instead of using the indent of a | |
335 line a user function is called to compute the fold level of a line. You can | |
336 use this for text where something in the text indicates which lines belong | |
337 together. An example is an e-mail message where the quoted text is indicated | |
338 by a ">" before the line. To fold these quotes use this: > | |
339 | |
340 :set foldmethod=expr | |
341 :set foldexpr=strlen(substitute(substitute(getline(v:lnum),'\\s','',\"g\"),'[^>].*','','')) | |
342 | |
343 You can try it out on this text: | |
344 | |
345 > quoted text he wrote | |
346 > quoted text he wrote | |
347 > > double quoted text I wrote | |
348 > > double quoted text I wrote | |
349 | |
350 Explanation for the 'foldexpr' used in the example (inside out): | |
351 getline(v:lnum) gets the current line | |
352 substitute(...,'\\s','','g') removes all white space from the line | |
237 | 353 substitute(...,'[^>].*','','') removes everything after leading '>'s |
7 | 354 strlen(...) counts the length of the string, which |
355 is the number of '>'s found | |
356 | |
357 Note that a backslash must be inserted before every space, double quote and | |
358 backslash for the ":set" command. If this confuses you, do > | |
359 | |
360 :set foldexpr | |
361 | |
362 to check the actual resulting value. To correct a complicated expression, use | |
363 the command-line completion: > | |
364 | |
365 :set foldexpr=<Tab> | |
366 | |
367 Where <Tab> is a real Tab. Vim will fill in the previous value, which you can | |
368 then edit. | |
369 | |
370 When the expression gets more complicated you should put it in a function and | |
371 set 'foldexpr' to call that function. | |
372 | |
373 More about folding by expression in the reference manual: |fold-expr| | |
374 | |
375 ============================================================================== | |
376 *28.9* Folding unchanged lines | |
377 | |
378 This is useful when you set the 'diff' option in the same window. The | |
379 |vimdiff| command does this for you. Example: > | |
380 | |
1622 | 381 :setlocal diff foldmethod=diff scrollbind nowrap foldlevel=1 |
7 | 382 |
383 Do this in every window that shows a different version of the same file. You | |
384 will clearly see the differences between the files, while the text that didn't | |
385 change is folded. | |
386 | |
387 For more details see |fold-diff|. | |
388 | |
389 ============================================================================== | |
390 *28.10* Which fold method to use? | |
391 | |
2283
7e1bd501306d
Mainly documentation updates.
Bram Moolenaar <bram@vim.org>
parents:
2154
diff
changeset
|
392 All these possibilities make you wonder which method you should choose. |
7 | 393 Unfortunately, there is no golden rule. Here are some hints. |
394 | |
395 If there is a syntax file with folding for the language you are editing, that | |
396 is probably the best choice. If there isn't one, you might try to write it. | |
397 This requires a good knowledge of search patterns. It's not easy, but when | |
398 it's working you will not have to define folds manually. | |
399 | |
400 Typing commands to manually fold regions can be used for unstructured text. | |
401 Then use the |:mkview| command to save and restore your folds. | |
402 | |
403 The marker method requires you to change the file. If you are sharing the | |
404 files with other people or you have to meet company standards, you might not | |
405 be allowed to add them. | |
406 The main advantage of markers is that you can put them exactly where you | |
407 want them. That avoids that a few lines are missed when you cut and paste | |
408 folds. And you can add a comment about what is contained in the fold. | |
409 | |
410 Folding by indent is something that works in many files, but not always very | |
411 well. Use it when you can't use one of the other methods. However, it is | |
412 very useful for outlining. Then you specifically use one 'shiftwidth' for | |
413 each nesting level. | |
414 | |
415 Folding with expressions can make folds in almost any structured text. It is | |
416 quite simple to specify, especially if the start and end of a fold can easily | |
417 be recognized. | |
418 If you use the "expr" method to define folds, but they are not exactly how | |
419 you want them, you could switch to the "manual" method. This will not remove | |
420 the defined folds. Then you can delete or add folds manually. | |
421 | |
422 ============================================================================== | |
423 | |
424 Next chapter: |usr_29.txt| Moving through programs | |
425 | |
426 Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: |