Mercurial > vim
annotate runtime/doc/usr_28.txt @ 34625:ad1b0609b2f8 v9.1.0201
patch 9.1.0201: gM not working correctly with virt text
Commit: https://github.com/vim/vim/commit/366c81a2005370ac738618d889ec0337397a9f96
Author: Dylan Thacker-Smith <dylan.ah.smith@gmail.com>
Date: Sun Mar 24 09:46:56 2024 +0100
patch 9.1.0201: gM not working correctly with virt text
Problem: `gM` would include outer virtual text and its padding when
getting the line length used to calculate the middle of the
line, putting the cursor much closer to virtual text lines.
Solution: Exclude outer virtual text in getting the line length for
`gM`, so that virtual text doesn't influence where the cursor
is moved to (Dylan Thacker-Smith).
closes: #14262
Signed-off-by: Dylan Thacker-Smith <dylan.ah.smith@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>
| author | Christian Brabandt <cb@256bit.org> |
|---|---|
| date | Sun, 24 Mar 2024 10:00:07 +0100 |
| parents | 4635e43f2c6f |
| children |
| rev | line source |
|---|---|
|
34057
4635e43f2c6f
patch 9.1.0000: Vim 9.1 release
Christian Brabandt <cb@256bit.org>
parents:
29314
diff
changeset
|
1 *usr_28.txt* For Vim version 9.1. 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 | |
| 14519 | 426 Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl: |