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