usr_05.txt (31628B)
1 *usr_05.txt* For Vim version 9.2. Last change: 2026 Aug 30 2 3 4 VIM USER MANUAL by Bram Moolenaar 5 6 7 Set your settings 8 9 10 Vim can be tuned to work like you want it to. This chapter shows you how to 11 make Vim start with options set to different values. Add plugins to extend 12 Vim's capabilities. Or define your own macros. 13 14 |05.1| The vimrc file 15 |05.2| The example vimrc file explained 16 |05.3| The defaults.vim file explained 17 |05.4| Simple mappings 18 |05.5| Adding a package 19 |05.6| Adding a plugin 20 |05.7| Adding a help file 21 |05.8| The option window 22 |05.9| Often used options 23 24 Next chapter: |usr_06.txt| Using syntax highlighting 25 Previous chapter: |usr_04.txt| Making small changes 26 Table of contents: |usr_toc.txt| 27 28 ============================================================================== 29 *05.1* The vimrc file *vimrc-intro* 30 31 You probably got tired of typing commands that you use very often. To start 32 Vim with all your favorite option settings and mappings, you write them in 33 what is called the vimrc file. Vim executes the commands in this file when it 34 starts up. 35 36 If you already have a vimrc file (e.g., when your sysadmin has one setup for 37 you), you can edit it this way: > 38 39 :edit $MYVIMRC 40 41 If you don't have a vimrc file yet, see |vimrc| to find out where you can 42 create a vimrc file. Also, the ":version" command mentions the name of the 43 "user vimrc file" Vim looks for. 44 45 For Unix and Macintosh this file is always used and is recommended: 46 47 ~/.vimrc ~ 48 49 For MS-Windows you can use one of these: 50 51 $HOME/_vimrc ~ 52 $VIM/_vimrc ~ 53 54 If you are creating the vimrc file for the first time, it is recommended to 55 put this line at the top: > 56 57 source $VIMRUNTIME/defaults.vim 58 59 This initializes Vim for new users (as opposed to traditional Vi users). See 60 |defaults.vim| for the details. 61 62 The vimrc file can contain all the commands that you type after a colon. The 63 simplest ones are for setting options. For example, if you want Vim to always 64 start with the 'incsearch' option on, add this line your vimrc file: > 65 66 set incsearch 67 68 For this new line to take effect you need to exit Vim and start it again. 69 Later you will learn how to do this without exiting Vim. 70 71 This chapter only explains the most basic items. For more information on how 72 to write a Vim script file: |usr_41.txt|. 73 74 ============================================================================== 75 *05.2* The example vimrc file explained *vimrc_example.vim* 76 77 In the first chapter was explained how the example vimrc (included in the 78 Vim distribution) file can be used to make Vim startup in not-compatible mode 79 (see |not-compatible|). The file can be found here: 80 81 $VIMRUNTIME/vimrc_example.vim ~ 82 83 In this section we will explain the various commands used in this file. This 84 will give you hints about how to set up your own preferences. Not everything 85 will be explained though. Use the ":help" command to find out more. 86 87 > 88 " Get the defaults that most users want. 89 source $VIMRUNTIME/defaults.vim 90 91 This loads the "defaults.vim" file in the $VIMRUNTIME directory. This sets up 92 Vim for how most users like it. If you are one of the few that don't, then 93 comment out this line. The commands are explained below: 94 |defaults.vim-explained| 95 96 > 97 if has("vms") 98 set nobackup 99 else 100 set backup 101 if has('persistent_undo') 102 set undofile 103 endif 104 endif 105 106 This tells Vim to keep a backup copy of a file when overwriting it. But not 107 on the VMS system, since it keeps old versions of files already. The backup 108 file will have the same name as the original file with "~" added. See |07.4| 109 110 This also sets the 'undofile' option, if available. This will store the 111 multi-level undo information in a file. The result is that when you change a 112 file, exit Vim, and then edit the file again, you can undo the changes made 113 previously. It's a very powerful and useful feature, at the cost of storing a 114 file. For more information see |undo-persistence|. 115 116 The "if" command is very useful to set options 117 only when some condition is met. More about that in |usr_41.txt|. 118 119 > 120 if &t_Co > 2 || has("gui_running") 121 set hlsearch 122 endif 123 124 This switches on the 'hlsearch' option, telling Vim to highlight matches with 125 the last used search pattern. 126 127 > 128 augroup vimrcEx 129 au! 130 autocmd FileType text setlocal textwidth=78 131 augroup END 132 133 This makes Vim break text to avoid lines getting longer than 78 characters. 134 But only for files that have been detected to be plain text. There are 135 actually two parts here. "autocmd FileType text" is an autocommand. This 136 defines that when the file type is set to "text" the following command is 137 automatically executed. "setlocal textwidth=78" sets the 'textwidth' option 138 to 78, but only locally in one file. 139 140 The wrapper with "augroup vimrcEx" and "augroup END" makes it possible to 141 delete the autocommand with the "au!" command. See |:augroup|. 142 143 > 144 if has('syntax') && has('eval') 145 packadd! matchit 146 endif 147 148 This loads the "matchit" plugin if the required features are available. 149 It makes the |%| command more powerful. This is explained at 150 |matchit-install|. 151 152 153 ============================================================================== 154 *05.3* The defaults.vim file explained *defaults.vim-explained* 155 156 The |defaults.vim| file is loaded when the user has no vimrc file. When you 157 create a new vimrc file, add this line near the top to keep using it: > 158 159 source $VIMRUNTIME/defaults.vim 160 161 Or use the vimrc_example.vim file, as explained above. 162 163 The following explains what defaults.vim is doing. 164 165 > 166 if exists('skip_defaults_vim') 167 finish 168 endif 169 170 Loading defaults.vim can be disabled with this command: > 171 let skip_defaults_vim = 1 172 This has to be done in the system vimrc file. See |system-vimrc|. If you 173 have a user vimrc this is not needed, since defaults.vim will not be loaded 174 automatically. 175 176 > 177 set nocompatible 178 179 As mentioned in the first chapter, these manuals explain Vim working in an 180 improved way, thus not completely Vi compatible. Setting the 'compatible' 181 option off, thus 'nocompatible' takes care of this. 182 183 > 184 set backspace=indent,eol,start 185 186 This specifies where in Insert mode the <BS> is allowed to delete the 187 character in front of the cursor. The three items, separated by commas, tell 188 Vim to delete the white space at the start of the line, a line break and the 189 character before where Insert mode started. See 'backspace'. 190 191 > 192 set history=200 193 194 Keep 200 commands and 200 search patterns in the history. Use another number 195 if you want to remember fewer or more lines. See 'history'. 196 197 > 198 set ruler 199 200 Always display the current cursor position in the lower right corner of the 201 Vim window. See 'ruler'. 202 203 > 204 set showcmd 205 206 Display an incomplete command in the lower right corner of the Vim window, 207 left of the ruler. For example, when you type "2f", Vim is waiting for you to 208 type the character to find and "2f" is displayed. When you press "w" next, 209 the "2fw" command is executed and the displayed "2f" is removed. 210 211 +-------------------------------------------------+ 212 |text in the Vim window | 213 |~ | 214 |~ | 215 |-- VISUAL -- 2f 43,8 17% | 216 +-------------------------------------------------+ 217 ^^^^^^^^^^^ ^^^^^^^^ ^^^^^^^^^^ 218 'showmode' 'showcmd' 'ruler' 219 220 221 > 222 set wildmenu 223 224 Display completion matches in a status line. That is when you type <Tab> and 225 there is more than one match. See 'wildmenu'. 226 227 > 228 set ttimeout 229 set ttimeoutlen=100 230 231 This makes typing Esc take effect more quickly. Normally Vim waits a second 232 to see if the Esc is the start of an escape sequence. If you have a very slow 233 remote connection, increase the number. See 'ttimeout'. 234 235 > 236 set display=truncate 237 238 Show @@@ in the last line if it is truncated, instead of hiding the whole 239 line. See 'display'. 240 241 > 242 set incsearch 243 244 Display the match for a search pattern when halfway typing it. See 245 'incsearch'. 246 247 > 248 set nrformats-=octal 249 250 Do not recognize numbers starting with a zero as octal. See 'nrformats'. 251 252 > 253 map Q gq 254 255 This defines a key mapping. More about that in the next section. This 256 defines the "Q" command to do formatting with the "gq" operator. This is how 257 it worked before Vim 5.0. Otherwise the "Q" command starts Ex mode, but you 258 will not need it. 259 260 > 261 inoremap <C-U> <C-G>u<C-U> 262 263 CTRL-U in insert mode deletes all entered text in the current line. Use 264 CTRL-G u to first break undo, so that you can undo CTRL-U after inserting a 265 line break. Revert with ":iunmap <C-U>". 266 267 > 268 if has('mouse') 269 set mouse=a 270 endif 271 272 Enable using the mouse if available. See 'mouse'. 273 274 > 275 vnoremap _g y:exe "grep /" .. escape(@", '\\/') .. "/ *.c *.h"<CR> 276 277 This mapping yanks the visually selected text and searches for it in C files. 278 You can see that a mapping can be used to do quite complicated things. Still, 279 it is just a sequence of commands that are executed like you typed them. 280 281 > 282 syntax on 283 284 Enable highlighting files in color. See |syntax|. 285 286 *vimrc-filetype* > 287 filetype plugin indent on 288 289 This switches on three very clever mechanisms: 290 1. Filetype detection. 291 Whenever you start editing a file, Vim will try to figure out what kind of 292 file this is. When you edit "main.c", Vim will see the ".c" extension and 293 recognize this as a "c" filetype. When you edit a file that starts with 294 "#!/bin/sh", Vim will recognize it as a "sh" filetype. 295 The filetype detection is used for syntax highlighting and the other two 296 items below. 297 See |filetypes|. 298 299 2. Using filetype plugin files 300 Many different filetypes are edited with different options. For example, 301 when you edit a "c" file, it's very useful to set the 'cindent' option to 302 automatically indent the lines. These commonly useful option settings are 303 included with Vim in filetype plugins. You can also add your own, see 304 |write-filetype-plugin|. 305 306 3. Using indent files 307 When editing programs, the indent of a line can often be computed 308 automatically. Vim comes with these indent rules for a number of 309 filetypes. See |:filetype-indent-on| and 'indentexpr'. 310 311 312 *restore-cursor* *last-position-jump* >vim 313 314 augroup RestoreCursor 315 autocmd! 316 autocmd BufReadPost * 317 \ let line = line("'\"") 318 \ | if line >= 1 && line <= line("$") && &filetype !~# 'commit' 319 \ && index(['xxd', 'gitrebase'], &filetype) == -1 320 \ && !&diff 321 \ | execute "normal! g`\"" 322 \ | endif 323 augroup END 324 325 Another autocommand. This time it is used after reading any file. The 326 complicated stuff after it checks if the '" mark is defined, and jumps to it 327 if so. It doesn't do that when: 328 - editing a commit or rebase message, which are likely a different one than 329 last time, 330 - using xxd(1) to filter and edit binary files, which transforms input files 331 back and forth, causing them to have dual nature, so to speak (see also 332 |using-xxd|) and 333 - Vim is in diff mode 334 335 The backslash at the start of a line is used to continue the command from the 336 previous line. That avoids a line getting very long. See |line-continuation|. 337 This only works in a Vim script file, not when typing commands at the 338 command line. 339 340 > 341 command DiffOrig vert new | set bt=nofile | r ++edit # | 0d_ 342 \ | diffthis | wincmd p | diffthis 343 344 This adds the ":DiffOrig" command. Use this in a modified buffer to see the 345 differences with the file it was loaded from. See |diff| and |:DiffOrig|. 346 347 > 348 set nolangremap 349 350 Prevent that the langmap option applies to characters that result from a 351 mapping. If set (default), this may break plugins (but it's backward 352 compatible). See 'langremap'. 353 354 ============================================================================== 355 *05.4* Simple mappings 356 357 A mapping enables you to bind a set of Vim commands to a single key. Suppose, 358 for example, that you need to surround certain words with curly braces. In 359 other words, you need to change a word such as "amount" into "{amount}". With 360 the :map command, you can tell Vim that the F5 key does this job. The command 361 is as follows: > 362 363 :map <F5> i{<Esc>ea}<Esc> 364 < 365 Note: 366 When entering this command, you must enter <F5> by typing four 367 characters. Similarly, <Esc> is not entered by pressing the <Esc> 368 key, but by typing five characters. Watch out for this difference 369 when reading the manual! 370 371 Let's break this down: 372 <F5> The F5 function key. This is the trigger key that causes the 373 command to be executed as the key is pressed. 374 375 i{<Esc> Insert the { character. The <Esc> key ends Insert mode. 376 377 e Move to the end of the word. 378 379 a}<Esc> Append the } to the word. 380 381 After you execute the ":map" command, all you have to do to put {} around a 382 word is to put the cursor on the first character and press F5. 383 384 In this example, the trigger is a single key; it can be any string. But when 385 you use an existing Vim command, that command will no longer be available. 386 You better avoid that. 387 One key that can be used with mappings is the backslash. Since you 388 probably want to define more than one mapping, add another character. You 389 could map "\p" to add parentheses around a word, and "\c" to add curly braces, 390 for example: > 391 392 :map \p i(<Esc>ea)<Esc> 393 :map \c i{<Esc>ea}<Esc> 394 395 You need to type the \ and the p quickly after another, so that Vim knows they 396 belong together. 397 398 The ":map" command (with no arguments) lists your current mappings. At 399 least the ones for Normal mode. More about mappings in section |40.1|. 400 401 ============================================================================== 402 *05.5* Adding a package *add-package* 403 404 A package is a set of files that you can add to Vim. There are two kinds of 405 packages: optional and automatically loaded on startup. 406 407 The Vim distribution comes with a few packages that you can optionally use. 408 409 In your |vimrc| use `:packadd!`: it only adds the package to 'runtimepath' 410 and leaves the loading to the usual startup. Without the "!" the package is 411 loaded directly, which is what you want when trying one out. See |:packadd|. 412 413 ------------------------------------------------------------------------------ 414 Adding the matchit package *matchit-install* *package-matchit* 415 ------------------------------------------------------------------------------ 416 For example, the matchit package This plugin makes the "%" command jump to 417 matching HTML tags, if/else/endif in Vim scripts, etc. Very useful, although 418 it's not backwards compatible (that's why it is not enabled by default). 419 420 To start using this plugin, add one line to your vimrc file: > 421 packadd! matchit 422 423 That's all! After restarting Vim you can find help about this plugin: > 424 :help matchit 425 426 This works, because `:packadd!` added the package directory in 'runtimepath', 427 so that the help file can be found. 428 429 You can find packages on the Internet in various places. It usually comes as 430 an archive or as a repository. For an archive you can follow these steps: 431 1. create the package directory: > 432 mkdir -p ~/.vim/pack/fancy 433 < "fancy" can be any name of your liking. Use one that describes the 434 package. 435 2. unpack the archive in that directory. This assumes the top 436 directory in the archive is "start": > 437 cd ~/.vim/pack/fancy 438 unzip /tmp/fancy.zip 439 < If the archive layout is different make sure that you end up with a 440 path like this: 441 ~/.vim/pack/fancy/start/fancytext/plugin/fancy.vim ~ 442 Here "fancytext" is the name of the package, it can be anything 443 else. 444 445 ------------------------------------------------------------------------------ 446 Adding the editorconfig package *editorconfig-install* *package-editorconfig* 447 ------------------------------------------------------------------------------ 448 449 To start using this plugin, add one line to your vimrc file: > 450 packadd! editorconfig 451 452 After restarting Vim the plugin is active and you can read about it at: > 453 :h editorconfig.txt 454 455 456 ------------------------------------------------------------------------------ 457 Adding the comment package *comment-install* *package-comment* 458 ------------------------------------------------------------------------------ 459 460 To start using this plugin, add one line to your vimrc file: > 461 packadd! comment 462 < 463 This way you can use the plugin with the default key bindings `gc` and similar 464 for commenting (which is a well-established mapping in the Vim community). 465 466 After restarting Vim the plugin is active and you can read about it at: > 467 :h comment.txt 468 469 470 ------------------------------------------------------------------------------ 471 Adding the nohlsearch package *nohlsearch-install* *package-nohlsearch* 472 ------------------------------------------------------------------------------ 473 474 To start using this plugin, add one line to your vimrc file: > 475 packadd! nohlsearch 476 < 477 Automatically execute |:nohlsearch| after 'updatetime' or getting into 478 |Insert| mode. 479 Thus assuming default updatetime, hlsearch would be suspended/turned off after 480 4 seconds of idle time. 481 482 To disable the effect of the plugin after it has been loaded: > 483 au! nohlsearch 484 < 485 486 ------------------------------------------------------------------------------ 487 Adding the highlight-yank package *hlyank-install* *package-hlyank* 488 ------------------------------------------------------------------------------ 489 490 To start using this plugin, add one line to your vimrc file: > 491 packadd! hlyank 492 < 493 This package briefly highlights the affected region of the last |yank| 494 command. See |52.6| for a simplified implementation using the 495 |getregionpos()| function. 496 497 The plugin understands the following configuration variables (the settings 498 show the default values). 499 500 To specify a different highlighting group, use: > 501 :let g:hlyank_hlgroup = 'IncSearch' 502 < 503 To use a different highlighting duration, use: > 504 :let g:hlyank_duration = 300 505 The unit is milliseconds, and the upper limit is 3000 ms. If you set a value 506 higher than this, the highlighting duration will be 3000 ms. 507 508 To highlight in visual mode, use: > 509 :let g:hlyank_invisual = v:true 510 511 To disable the effect of the plugin after it has been loaded: > 512 au! hlyank 513 514 Additionally, the plugin can also highlight regions that are put using the 515 |TextPutPost| autocommand. This is by default disabled and can be enabled 516 using: > 517 :let g:hlput_enable = v:true 518 < 519 The following configuration variables can be used are "g:hlput_hlgroup" and 520 "g:hlput_duration", which have the same effect as their yank counterparts: > 521 :let g:hlput_hlgroup = 'IncSearch' 522 :let g:hlput_duration = 300 523 524 ------------------------------------------------------------------------------ 525 Adding the osc52 package *osc52-install* *package-osc52* 526 ------------------------------------------------------------------------------ 527 528 To start using this plugin, add one line to your vimrc file: > 529 packadd! osc52 530 < 531 The osc52.vim package provides support for the OSC 52 terminal command, which 532 allows an application to access the clipboard by communicating directly with 533 your terminal. 534 535 Once the package is loaded, read about it at: > 536 :h osc52.txt 537 538 More information about packages can be found here: |packages|. 539 540 ============================================================================== 541 *05.6* Adding a plugin *add-plugin* *plugin* 542 543 Vim's functionality can be extended by adding plugins. A plugin is nothing 544 more than a Vim script file that is loaded automatically when Vim starts. You 545 can add a plugin very easily by dropping it in your plugin directory. 546 {not available when Vim was compiled without the |+eval| feature} 547 548 There are two types of plugins: 549 550 global plugin: Used for all kinds of files 551 filetype plugin: Only used for a specific type of file 552 553 The global plugins will be discussed first, then the filetype ones 554 |add-filetype-plugin|. 555 556 557 GLOBAL PLUGINS *standard-plugin* *distributed-plugins* 558 559 When you start Vim, it will automatically load a number of global plugins. 560 You don't have to do anything for this. They add functionality that most 561 people will want to use, but which was implemented as a Vim script instead of 562 being compiled into Vim. You can find them listed in the help index 563 |standard-plugin-list|. 564 565 For locally installed plugins and packages (which come with a separated help 566 file) a similar list can be found in the help section |local-additions|. 567 568 Also see |load-plugins|. 569 570 *add-global-plugin* 571 You can add a global plugin to add functionality that will always be present 572 when you use Vim. There are only two steps for adding a global plugin: 573 1. Get a copy of the plugin. 574 2. Drop it in the right directory. 575 576 577 GETTING A GLOBAL PLUGIN 578 579 Where can you find plugins? 580 - Some are always loaded, you can see them in the directory 581 $VIMRUNTIME/plugin. 582 - Some come with Vim. You can find them in the directory $VIMRUNTIME/macros 583 and its sub-directories and under $VIM/vimfiles/pack/dist/opt/. 584 - Download from the net. There is a large collection on http://www.vim.org. 585 - They are sometimes posted in a Vim |maillist|. 586 - You could write one yourself, see |write-plugin|. 587 588 Some plugins come as a vimball archive, see |vimball|. 589 Some plugins can be updated automatically, see |getscript|. 590 591 592 USING A GLOBAL PLUGIN 593 594 First read the text in the plugin itself to check for any special conditions. 595 Then copy the file to your plugin directory: 596 597 system plugin directory ~ 598 Unix ~/.vim/plugin/ 599 PC $HOME/vimfiles/plugin or $VIM/vimfiles/plugin 600 Amiga s:vimfiles/plugin 601 Macintosh $VIM:vimfiles:plugin 602 Mac OS X ~/.vim/plugin/ 603 604 Example for Unix (assuming you didn't have a plugin directory yet): > 605 606 mkdir ~/.vim 607 mkdir ~/.vim/plugin 608 cp /tmp/yourplugin.vim ~/.vim/plugin 609 610 That's all! Now you can use the commands defined in this plugin. 611 612 Instead of putting plugins directly into the plugin/ directory, you may 613 better organize them by putting them into subdirectories under plugin/. 614 As an example, consider using "~/.vim/plugin/perl/*.vim" for all your Perl 615 plugins. 616 617 618 FILETYPE PLUGINS *add-filetype-plugin* *ftplugins* 619 620 The Vim distribution comes with a set of plugins for different filetypes that 621 you can start using with this command: > 622 623 :filetype plugin on 624 625 That's all! See |vimrc-filetype|. 626 627 If you are missing a plugin for a filetype you are using, or you found a 628 better one, you can add it. There are two steps for adding a filetype plugin: 629 1. Get a copy of the plugin. 630 2. Drop it in the right directory. 631 632 633 GETTING A FILETYPE PLUGIN 634 635 You can find them in the same places as the global plugins. Watch out if the 636 type of file is mentioned, then you know if the plugin is a global or a 637 filetype one. The scripts in $VIMRUNTIME/macros are global ones, the filetype 638 plugins are in $VIMRUNTIME/ftplugin. 639 640 641 USING A FILETYPE PLUGIN *ftplugin-name* 642 643 You can add a filetype plugin by dropping it in the right directory. The 644 name of this directory is in the same directory mentioned above for global 645 plugins, but the last part is "ftplugin". Suppose you have found a plugin for 646 the "stuff" filetype, and you are on Unix. Then you can move this file to the 647 ftplugin directory: > 648 649 mv thefile ~/.vim/ftplugin/stuff.vim 650 651 If that file already exists you already have a plugin for "stuff". You might 652 want to check if the existing plugin doesn't conflict with the one you are 653 adding. If it's OK, you can give the new one another name: > 654 655 mv thefile ~/.vim/ftplugin/stuff_too.vim 656 657 The underscore is used to separate the name of the filetype from the rest, 658 which can be anything. If you use "otherstuff.vim" it wouldn't work, it would 659 be loaded for the "otherstuff" filetype. 660 661 On MS-DOS like filesystems you cannot use long filenames. You would run into 662 trouble if you add a second plugin and the filetype has more than six 663 characters. You can use an extra directory to get around this: > 664 665 mkdir $VIM/vimfiles/ftplugin/fortran 666 copy thefile $VIM/vimfiles/ftplugin/fortran/too.vim 667 668 The generic names for the filetype plugins are: > 669 670 ftplugin/<filetype>.vim 671 ftplugin/<filetype>_<name>.vim 672 ftplugin/<filetype>/<name>.vim 673 674 Here "<name>" can be any name that you prefer. 675 Examples for the "stuff" filetype on Unix: > 676 677 ~/.vim/ftplugin/stuff.vim 678 ~/.vim/ftplugin/stuff_def.vim 679 ~/.vim/ftplugin/stuff/header.vim 680 681 The <filetype> part is the name of the filetype the plugin is to be used for. 682 Only files of this filetype will use the settings from the plugin. The <name> 683 part of the plugin file doesn't matter, you can use it to have several plugins 684 for the same filetype. Note that it must end in ".vim". 685 686 687 Further reading: 688 |filetype-plugins| Documentation for the filetype plugins and information 689 about how to avoid that mappings cause problems. 690 |load-plugins| When the global plugins are loaded during startup. 691 |ftplugin-overrule| Overruling the settings from a global plugin. 692 |write-plugin| How to write a plugin script. 693 |plugin-details| For more information about using plugins or when your 694 plugin doesn't work. 695 |new-filetype| How to detect a new file type. 696 697 ============================================================================== 698 *05.7* Adding a help file *add-local-help* 699 700 If you are lucky, the plugin you installed also comes with a help file. We 701 will explain how to install the help file, so that you can easily find help 702 for your new plugin. 703 Let us use the "doit.vim" plugin as an example. This plugin comes with 704 documentation: "doit.txt". Let's first copy the plugin to the right 705 directory. This time we will do it from inside Vim. (You may skip some of 706 the "mkdir" commands if you already have the directory.) > 707 708 :!mkdir ~/.vim 709 :!mkdir ~/.vim/plugin 710 :!cp /tmp/doit.vim ~/.vim/plugin 711 712 The "cp" command is for Unix, on MS-Windows you can use "copy". 713 714 Now create a "doc" directory in one of the directories in 'runtimepath'. > 715 716 :!mkdir ~/.vim/doc 717 718 Copy the help file to the "doc" directory. > 719 720 :!cp /tmp/doit.txt ~/.vim/doc 721 722 Now comes the trick, which allows you to jump to the subjects in the new help 723 file: Generate the local tags file with the |:helptags| command. > 724 725 :helptags ~/.vim/doc 726 727 Now you can use the > 728 729 :help doit 730 731 command to find help for "doit" in the help file you just added. You can see 732 an entry for the local help file when you do: > 733 734 :help local-additions 735 736 The title lines from the local help files are automagically added to this 737 section. There you can see which local help files have been added and jump to 738 them through the tag. 739 740 For writing a local help file, see |write-local-help|. 741 742 ============================================================================== 743 *05.8* The option window 744 745 If you are looking for an option that does what you want, you can search in 746 the help files here: |options|. Another way is by using this command: > 747 748 :options 749 750 This opens a new window, with a list of options with a one-line explanation. 751 The options are grouped by subject. Move the cursor to a subject and press 752 <Enter> to jump there. Press <Enter> again to jump back. Or use CTRL-O. 753 754 You can change the value of an option. For example, move to the "displaying 755 text" subject. Then move the cursor down to this line: 756 757 set wrap nowrap ~ 758 759 When you hit <Enter>, the line will change to: 760 761 set nowrap wrap ~ 762 763 The option has now been switched off. 764 765 Just above this line is a short description of the 'wrap' option. Move the 766 cursor one line up to place it in this line. Now hit <Enter> and you jump to 767 the full help on the 'wrap' option. 768 769 For options that take a number or string argument you can edit the value. 770 Then press <Enter> to apply the new value. For example, move the cursor a few 771 lines up to this line: 772 773 set so=0 ~ 774 775 Position the cursor on the zero with "$". Change it into a five with "r5". 776 Then press <Enter> to apply the new value. When you now move the cursor 777 around you will notice that the text starts scrolling before you reach the 778 border. This is what the 'scrolloff' option does, it specifies an offset 779 from the window border where scrolling starts. 780 781 ============================================================================== 782 *05.9* Often used options 783 784 There are an awful lot of options. Most of them you will hardly ever use. 785 Some of the more useful ones will be mentioned here. Don't forget you can 786 find more help on these options with the ":help" command, with single quotes 787 before and after the option name. For example: > 788 789 :help 'wrap' 790 791 In case you have messed up an option value, you can set it back to the 792 default by putting an ampersand (&) after the option name. Example: > 793 794 :set iskeyword& 795 796 797 NOT WRAPPING LINES 798 799 Vim normally wraps long lines, so that you can see all of the text. Sometimes 800 it's better to let the text continue right of the window. Then you need to 801 scroll the text left-right to see all of a long line. Switch wrapping off 802 with this command: > 803 804 :set nowrap 805 806 Vim will automatically scroll the text when you move to text that is not 807 displayed. To see a context of ten characters, do this: > 808 809 :set sidescroll=10 810 811 This doesn't change the text in the file, only the way it is displayed. 812 813 814 WRAPPING MOVEMENT COMMANDS 815 816 Most commands for moving around will stop moving at the start and end of a 817 line. You can change that with the 'whichwrap' option. This sets it to the 818 default value: > 819 820 :set whichwrap=b,s 821 822 This allows the <BS> key, when used in the first position of a line, to move 823 the cursor to the end of the previous line. And the <Space> key moves from 824 the end of a line to the start of the next one. 825 826 To allow the cursor keys <Left> and <Right> to also wrap, use this command: > 827 828 :set whichwrap=b,s,<,> 829 830 This is still only for Normal mode. To let <Left> and <Right> do this in 831 Insert mode as well: > 832 833 :set whichwrap=b,s,<,>,[,] 834 835 There are a few other flags that can be added, see 'whichwrap'. 836 837 838 VIEWING TABS 839 840 When there are tabs in a file, you cannot see where they are. To make them 841 visible: > 842 843 :set list 844 845 Now every tab is displayed as ^I. And a $ is displayed at the end of each 846 line, so that you can spot trailing spaces that would otherwise go unnoticed. 847 A disadvantage is that this looks ugly when there are many Tabs in a file. 848 If you have a color terminal, or are using the GUI, Vim can show the spaces 849 and tabs as highlighted characters. Use the 'listchars' option: > 850 851 :set listchars=tab:>-,trail:- 852 853 Now every tab will be displayed as ">---" (with more or less "-") and trailing 854 white space as "-". Looks a lot better, doesn't it? 855 856 857 KEYWORDS 858 859 The 'iskeyword' option specifies which characters can appear in a word: > 860 861 :set iskeyword 862 < iskeyword=@,48-57,_,192-255 ~ 863 864 The "@" stands for all alphabetic letters. "48-57" stands for ASCII 865 characters 48 to 57, which are the numbers 0 to 9. "192-255" are the 866 printable latin characters. 867 Sometimes you will want to include a dash in keywords, so that commands 868 like "w" consider "upper-case" to be one word. You can do it like this: > 869 870 :set iskeyword+=- 871 :set iskeyword 872 < iskeyword=@,48-57,_,192-255,- ~ 873 874 If you look at the new value, you will see that Vim has added a comma for you. 875 To remove a character use "-=". For example, to remove the underscore: > 876 877 :set iskeyword-=_ 878 :set iskeyword 879 < iskeyword=@,48-57,192-255,- ~ 880 881 This time a comma is automatically deleted. 882 883 884 ROOM FOR MESSAGES 885 886 When Vim starts there is one line at the bottom that is used for messages. 887 When a message is long, it is either truncated, thus you can only see part of 888 it, or the text scrolls and you have to press <Enter> to continue. 889 You can set the 'cmdheight' option to the number of lines used for 890 messages. Example: > 891 892 :set cmdheight=3 893 894 This does mean there is less room to edit text, thus it's a compromise. 895 896 ============================================================================== 897 898 Next chapter: |usr_06.txt| Using syntax highlighting 899 900 Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl: