Mercurial > vim
annotate runtime/doc/usr_05.txt @ 14972:5d52b21b2e7f v8.1.0497
patch 8.1.0497: :%diffput changes order of lines
commit https://github.com/vim/vim/commit/5f57bdcab77bc417ae0357fe8ad6c7259b6d25df
Author: Bram Moolenaar <Bram@vim.org>
Date: Thu Oct 25 17:52:23 2018 +0200
patch 8.1.0497: :%diffput changes order of lines
Problem: :%diffput changes order of lines. (Markus Braun)
Solution: Do adjust marks when using internal diff.
author | Bram Moolenaar <Bram@vim.org> |
---|---|
date | Thu, 25 Oct 2018 18:00:07 +0200 |
parents | 5c5908e81e93 |
children | fe57e4f0eac1 |
rev | line source |
---|---|
13963 | 1 *usr_05.txt* For Vim version 8.1. Last change: 2018 Feb 20 |
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 | |
14 |05.3| Simple mappings | |
8720
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
15 |05.4| Adding a package |
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
16 |05.5| Adding a plugin |
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
17 |05.6| Adding a help file |
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
18 |05.7| The option window |
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
19 |05.8| Often used options |
7 | 20 |
21 Next chapter: |usr_06.txt| Using syntax highlighting | |
22 Previous chapter: |usr_04.txt| Making small changes | |
23 Table of contents: |usr_toc.txt| | |
24 | |
25 ============================================================================== | |
26 *05.1* The vimrc file *vimrc-intro* | |
27 | |
28 You probably got tired of typing commands that you use very often. To start | |
819 | 29 Vim with all your favorite option settings and mappings, you write them in |
30 what is called the vimrc file. Vim executes the commands in this file when it | |
31 starts up. | |
7 | 32 |
819 | 33 If you already have a vimrc file (e.g., when your sysadmin has one setup for |
34 you), you can edit it this way: > | |
7 | 35 |
819 | 36 :edit $MYVIMRC |
37 | |
38 If you don't have a vimrc file yet, see |vimrc| to find out where you can | |
7 | 39 create a vimrc file. Also, the ":version" command mentions the name of the |
40 "user vimrc file" Vim looks for. | |
41 | |
819 | 42 For Unix and Macintosh this file is always used and is recommended: |
7 | 43 |
819 | 44 ~/.vimrc ~ |
7 | 45 |
819 | 46 For MS-DOS and MS-Windows you can use one of these: |
7 | 47 |
819 | 48 $HOME/_vimrc ~ |
49 $VIM/_vimrc ~ | |
7 | 50 |
13341
acd7eaa13d2b
Updated runtime files.
Christian Brabandt <cb@256bit.org>
parents:
10198
diff
changeset
|
51 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
|
52 put this line at the top: > |
acd7eaa13d2b
Updated runtime files.
Christian Brabandt <cb@256bit.org>
parents:
10198
diff
changeset
|
53 |
acd7eaa13d2b
Updated runtime files.
Christian Brabandt <cb@256bit.org>
parents:
10198
diff
changeset
|
54 source $VIMRUNTIME/defaults.vim |
acd7eaa13d2b
Updated runtime files.
Christian Brabandt <cb@256bit.org>
parents:
10198
diff
changeset
|
55 |
acd7eaa13d2b
Updated runtime files.
Christian Brabandt <cb@256bit.org>
parents:
10198
diff
changeset
|
56 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
|
57 |defaults.vim| for the details. |
acd7eaa13d2b
Updated runtime files.
Christian Brabandt <cb@256bit.org>
parents:
10198
diff
changeset
|
58 |
7 | 59 The vimrc file can contain all the commands that you type after a colon. The |
60 most simple ones are for setting options. For example, if you want Vim to | |
3967 | 61 always start with the 'incsearch' option on, add this line your vimrc file: > |
7 | 62 |
63 set incsearch | |
64 | |
65 For this new line to take effect you need to exit Vim and start it again. | |
66 Later you will learn how to do this without exiting Vim. | |
67 | |
68 This chapter only explains the most basic items. For more information on how | |
69 to write a Vim script file: |usr_41.txt|. | |
70 | |
71 ============================================================================== | |
72 *05.2* The example vimrc file explained *vimrc_example.vim* | |
73 | |
74 In the first chapter was explained how the example vimrc (included in the | |
75 Vim distribution) file can be used to make Vim startup in not-compatible mode | |
76 (see |not-compatible|). The file can be found here: | |
77 | |
78 $VIMRUNTIME/vimrc_example.vim ~ | |
79 | |
80 In this section we will explain the various commands used in this file. This | |
81 will give you hints about how to set up your own preferences. Not everything | |
82 will be explained though. Use the ":help" command to find out more. | |
83 | |
84 > | |
85 set nocompatible | |
86 | |
87 As mentioned in the first chapter, these manuals explain Vim working in an | |
88 improved way, thus not completely Vi compatible. Setting the 'compatible' | |
89 option off, thus 'nocompatible' takes care of this. | |
90 | |
91 > | |
92 set backspace=indent,eol,start | |
93 | |
94 This specifies where in Insert mode the <BS> is allowed to delete the | |
95 character in front of the cursor. The three items, separated by commas, tell | |
96 Vim to delete the white space at the start of the line, a line break and the | |
97 character before where Insert mode started. | |
98 > | |
99 | |
100 set autoindent | |
101 | |
102 This makes Vim use the indent of the previous line for a newly created line. | |
103 Thus there is the same amount of white space before the new line. For example | |
104 when pressing <Enter> in Insert mode, and when using the "o" command to open a | |
105 new line. | |
106 > | |
107 | |
108 if has("vms") | |
109 set nobackup | |
110 else | |
111 set backup | |
112 endif | |
113 | |
114 This tells Vim to keep a backup copy of a file when overwriting it. But not | |
115 on the VMS system, since it keeps old versions of files already. The backup | |
116 file will have the same name as the original file with "~" added. See |07.4| | |
117 > | |
118 | |
119 set history=50 | |
120 | |
121 Keep 50 commands and 50 search patterns in the history. Use another number if | |
122 you want to remember fewer or more lines. | |
123 > | |
124 | |
125 set ruler | |
126 | |
127 Always display the current cursor position in the lower right corner of the | |
128 Vim window. | |
129 | |
130 > | |
131 set showcmd | |
132 | |
133 Display an incomplete command in the lower right corner of the Vim window, | |
134 left of the ruler. For example, when you type "2f", Vim is waiting for you to | |
135 type the character to find and "2f" is displayed. When you press "w" next, | |
136 the "2fw" command is executed and the displayed "2f" is removed. | |
137 | |
138 +-------------------------------------------------+ | |
139 |text in the Vim window | | |
140 |~ | | |
141 |~ | | |
142 |-- VISUAL -- 2f 43,8 17% | | |
143 +-------------------------------------------------+ | |
144 ^^^^^^^^^^^ ^^^^^^^^ ^^^^^^^^^^ | |
145 'showmode' 'showcmd' 'ruler' | |
146 | |
147 > | |
148 set incsearch | |
149 | |
150 Display the match for a search pattern when halfway typing it. | |
151 | |
152 > | |
153 map Q gq | |
154 | |
155 This defines a key mapping. More about that in the next section. This | |
156 defines the "Q" command to do formatting with the "gq" operator. This is how | |
157 it worked before Vim 5.0. Otherwise the "Q" command starts Ex mode, but you | |
158 will not need it. | |
159 | |
160 > | |
43 | 161 vnoremap _g y:exe "grep /" . escape(@", '\\/') . "/ *.c *.h"<CR> |
7 | 162 |
43 | 163 This mapping yanks the visually selected text and searches for it in C files. |
164 This is a complicated mapping. You can see that mappings can be used to do | |
165 quite complicated things. Still, it is just a sequence of commands that are | |
7 | 166 executed like you typed them. |
167 | |
168 > | |
169 if &t_Co > 2 || has("gui_running") | |
170 syntax on | |
171 set hlsearch | |
172 endif | |
173 | |
174 This switches on syntax highlighting, but only if colors are available. And | |
175 the 'hlsearch' option tells Vim to highlight matches with the last used search | |
176 pattern. The "if" command is very useful to set options only when some | |
177 condition is met. More about that in |usr_41.txt|. | |
178 | |
179 *vimrc-filetype* > | |
180 filetype plugin indent on | |
181 | |
182 This switches on three very clever mechanisms: | |
183 1. Filetype detection. | |
184 Whenever you start editing a file, Vim will try to figure out what kind of | |
185 file this is. When you edit "main.c", Vim will see the ".c" extension and | |
186 recognize this as a "c" filetype. When you edit a file that starts with | |
187 "#!/bin/sh", Vim will recognize it as a "sh" filetype. | |
188 The filetype detection is used for syntax highlighting and the other two | |
189 items below. | |
190 See |filetypes|. | |
191 | |
192 2. Using filetype plugin files | |
193 Many different filetypes are edited with different options. For example, | |
194 when you edit a "c" file, it's very useful to set the 'cindent' option to | |
195 automatically indent the lines. These commonly useful option settings are | |
196 included with Vim in filetype plugins. You can also add your own, see | |
197 |write-filetype-plugin|. | |
198 | |
199 3. Using indent files | |
200 When editing programs, the indent of a line can often be computed | |
201 automatically. Vim comes with these indent rules for a number of | |
202 filetypes. See |:filetype-indent-on| and 'indentexpr'. | |
203 | |
204 > | |
205 autocmd FileType text setlocal textwidth=78 | |
206 | |
207 This makes Vim break text to avoid lines getting longer than 78 characters. | |
208 But only for files that have been detected to be plain text. There are | |
209 actually two parts here. "autocmd FileType text" is an autocommand. This | |
210 defines that when the file type is set to "text" the following command is | |
211 automatically executed. "setlocal textwidth=78" sets the 'textwidth' option | |
212 to 78, but only locally in one file. | |
213 | |
1125 | 214 *restore-cursor* > |
7 | 215 autocmd BufReadPost * |
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
216 \ if line("'\"") > 1 && line("'\"") <= line("$") | |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
217 \ exe "normal! g`\"" | |
7 | 218 \ endif |
219 | |
220 Another autocommand. This time it is used after reading any file. The | |
221 complicated stuff after it checks if the '" mark is defined, and jumps to it | |
222 if so. The backslash at the start of a line is used to continue the command | |
223 from the previous line. That avoids a line getting very long. | |
224 See |line-continuation|. This only works in a Vim script file, not when | |
225 typing commands at the command-line. | |
226 | |
227 ============================================================================== | |
228 *05.3* Simple mappings | |
229 | |
230 A mapping enables you to bind a set of Vim commands to a single key. Suppose, | |
231 for example, that you need to surround certain words with curly braces. In | |
232 other words, you need to change a word such as "amount" into "{amount}". With | |
233 the :map command, you can tell Vim that the F5 key does this job. The command | |
234 is as follows: > | |
235 | |
236 :map <F5> i{<Esc>ea}<Esc> | |
237 < | |
238 Note: | |
239 When entering this command, you must enter <F5> by typing four | |
240 characters. Similarly, <Esc> is not entered by pressing the <Esc> | |
241 key, but by typing five characters. Watch out for this difference | |
242 when reading the manual! | |
243 | |
244 Let's break this down: | |
245 <F5> The F5 function key. This is the trigger key that causes the | |
246 command to be executed as the key is pressed. | |
247 | |
248 i{<Esc> Insert the { character. The <Esc> key ends Insert mode. | |
249 | |
250 e Move to the end of the word. | |
251 | |
252 a}<Esc> Append the } to the word. | |
253 | |
254 After you execute the ":map" command, all you have to do to put {} around a | |
255 word is to put the cursor on the first character and press F5. | |
256 | |
257 In this example, the trigger is a single key; it can be any string. But when | |
258 you use an existing Vim command, that command will no longer be available. | |
259 You better avoid that. | |
260 One key that can be used with mappings is the backslash. Since you | |
261 probably want to define more than one mapping, add another character. You | |
164 | 262 could map "\p" to add parentheses around a word, and "\c" to add curly braces, |
263 for example: > | |
7 | 264 |
265 :map \p i(<Esc>ea)<Esc> | |
266 :map \c i{<Esc>ea}<Esc> | |
267 | |
268 You need to type the \ and the p quickly after another, so that Vim knows they | |
269 belong together. | |
270 | |
271 The ":map" command (with no arguments) lists your current mappings. At | |
272 least the ones for Normal mode. More about mappings in section |40.1|. | |
273 | |
274 ============================================================================== | |
8720
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
275 *05.4* Adding a package *add-package* *matchit-install* |
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
276 |
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
277 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
|
278 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
|
279 |
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
280 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
|
281 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
|
282 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
|
283 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
|
284 |
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
285 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
|
286 packadd! matchit |
8720
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
287 |
8748
b1a19a2f73f0
commit https://github.com/vim/vim/commit/4f3f668c8486444e53163c29d2fc79bf47eb3c82
Christian Brabandt <cb@256bit.org>
parents:
8720
diff
changeset
|
288 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
|
289 :help matchit |
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
290 |
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
291 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
|
292 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
|
293 |
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
294 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
|
295 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
|
296 1. create the package directory: > |
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
297 mkdir -p ~/.vim/pack/fancy |
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
298 < "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
|
299 package. |
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
300 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
|
301 directory in the archive is "start": > |
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
302 cd ~/.vim/pack/fancy |
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
303 unzip /tmp/fancy.zip |
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
304 < 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
|
305 path like this: |
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
306 ~/.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
|
307 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
|
308 else. |
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
309 |
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
310 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
|
311 |
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
312 ============================================================================== |
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
313 *05.5* Adding a plugin *add-plugin* *plugin* |
7 | 314 |
315 Vim's functionality can be extended by adding plugins. A plugin is nothing | |
316 more than a Vim script file that is loaded automatically when Vim starts. You | |
317 can add a plugin very easily by dropping it in your plugin directory. | |
318 {not available when Vim was compiled without the |+eval| feature} | |
319 | |
320 There are two types of plugins: | |
321 | |
322 global plugin: Used for all kinds of files | |
323 filetype plugin: Only used for a specific type of file | |
324 | |
325 The global plugins will be discussed first, then the filetype ones | |
326 |add-filetype-plugin|. | |
327 | |
328 | |
329 GLOBAL PLUGINS *standard-plugin* | |
330 | |
331 When you start Vim, it will automatically load a number of global plugins. | |
332 You don't have to do anything for this. They add functionality that most | |
333 people will want to use, but which was implemented as a Vim script instead of | |
334 being compiled into Vim. You can find them listed in the help index | |
335 |standard-plugin-list|. Also see |load-plugins|. | |
336 | |
337 *add-global-plugin* | |
338 You can add a global plugin to add functionality that will always be present | |
339 when you use Vim. There are only two steps for adding a global plugin: | |
340 1. Get a copy of the plugin. | |
341 2. Drop it in the right directory. | |
342 | |
343 | |
344 GETTING A GLOBAL PLUGIN | |
345 | |
346 Where can you find plugins? | |
14372 | 347 - Some are always loaded, you can see them in the directory $VIMRUNTIME/plugin. |
7 | 348 - Some come with Vim. You can find them in the directory $VIMRUNTIME/macros |
14372 | 349 and its sub-directories and under $VIM/vimfiles/pack/dist/opt/. |
800 | 350 - Download from the net. There is a large collection on http://www.vim.org. |
7 | 351 - They are sometimes posted in a Vim |maillist|. |
352 - You could write one yourself, see |write-plugin|. | |
353 | |
800 | 354 Some plugins come as a vimball archive, see |vimball|. |
355 Some plugins can be updated automatically, see |getscript|. | |
356 | |
7 | 357 |
358 USING A GLOBAL PLUGIN | |
359 | |
360 First read the text in the plugin itself to check for any special conditions. | |
361 Then copy the file to your plugin directory: | |
362 | |
363 system plugin directory ~ | |
364 Unix ~/.vim/plugin/ | |
365 PC and OS/2 $HOME/vimfiles/plugin or $VIM/vimfiles/plugin | |
366 Amiga s:vimfiles/plugin | |
367 Macintosh $VIM:vimfiles:plugin | |
368 Mac OS X ~/.vim/plugin/ | |
369 RISC-OS Choices:vimfiles.plugin | |
370 | |
371 Example for Unix (assuming you didn't have a plugin directory yet): > | |
372 | |
373 mkdir ~/.vim | |
374 mkdir ~/.vim/plugin | |
8795
aba2d0a01290
commit https://github.com/vim/vim/commit/7db8f6f4f85e5d0526d23107b2a5e2334dc23354
Christian Brabandt <cb@256bit.org>
parents:
8748
diff
changeset
|
375 cp /tmp/yourplugin.vim ~/.vim/plugin |
7 | 376 |
8795
aba2d0a01290
commit https://github.com/vim/vim/commit/7db8f6f4f85e5d0526d23107b2a5e2334dc23354
Christian Brabandt <cb@256bit.org>
parents:
8748
diff
changeset
|
377 That's all! Now you can use the commands defined in this plugin. |
7 | 378 |
548 | 379 Instead of putting plugins directly into the plugin/ directory, you may |
380 better organize them by putting them into subdirectories under plugin/. | |
381 As an example, consider using "~/.vim/plugin/perl/*.vim" for all your Perl | |
382 plugins. | |
541 | 383 |
7 | 384 |
385 FILETYPE PLUGINS *add-filetype-plugin* *ftplugins* | |
386 | |
387 The Vim distribution comes with a set of plugins for different filetypes that | |
388 you can start using with this command: > | |
389 | |
390 :filetype plugin on | |
391 | |
392 That's all! See |vimrc-filetype|. | |
393 | |
394 If you are missing a plugin for a filetype you are using, or you found a | |
395 better one, you can add it. There are two steps for adding a filetype plugin: | |
396 1. Get a copy of the plugin. | |
397 2. Drop it in the right directory. | |
398 | |
399 | |
400 GETTING A FILETYPE PLUGIN | |
401 | |
402 You can find them in the same places as the global plugins. Watch out if the | |
403 type of file is mentioned, then you know if the plugin is a global or a | |
404 filetype one. The scripts in $VIMRUNTIME/macros are global ones, the filetype | |
405 plugins are in $VIMRUNTIME/ftplugin. | |
406 | |
407 | |
408 USING A FILETYPE PLUGIN *ftplugin-name* | |
409 | |
410 You can add a filetype plugin by dropping it in the right directory. The | |
411 name of this directory is in the same directory mentioned above for global | |
412 plugins, but the last part is "ftplugin". Suppose you have found a plugin for | |
413 the "stuff" filetype, and you are on Unix. Then you can move this file to the | |
414 ftplugin directory: > | |
415 | |
416 mv thefile ~/.vim/ftplugin/stuff.vim | |
417 | |
418 If that file already exists you already have a plugin for "stuff". You might | |
419 want to check if the existing plugin doesn't conflict with the one you are | |
420 adding. If it's OK, you can give the new one another name: > | |
421 | |
422 mv thefile ~/.vim/ftplugin/stuff_too.vim | |
423 | |
424 The underscore is used to separate the name of the filetype from the rest, | |
10 | 425 which can be anything. If you use "otherstuff.vim" it wouldn't work, it would |
426 be loaded for the "otherstuff" filetype. | |
7 | 427 |
428 On MS-DOS you cannot use long filenames. You would run into trouble if you | |
429 add a second plugin and the filetype has more than six characters. You can | |
430 use an extra directory to get around this: > | |
431 | |
432 mkdir $VIM/vimfiles/ftplugin/fortran | |
433 copy thefile $VIM/vimfiles/ftplugin/fortran/too.vim | |
434 | |
435 The generic names for the filetype plugins are: > | |
436 | |
437 ftplugin/<filetype>.vim | |
438 ftplugin/<filetype>_<name>.vim | |
439 ftplugin/<filetype>/<name>.vim | |
440 | |
441 Here "<name>" can be any name that you prefer. | |
442 Examples for the "stuff" filetype on Unix: > | |
443 | |
444 ~/.vim/ftplugin/stuff.vim | |
445 ~/.vim/ftplugin/stuff_def.vim | |
446 ~/.vim/ftplugin/stuff/header.vim | |
447 | |
448 The <filetype> part is the name of the filetype the plugin is to be used for. | |
449 Only files of this filetype will use the settings from the plugin. The <name> | |
450 part of the plugin file doesn't matter, you can use it to have several plugins | |
451 for the same filetype. Note that it must end in ".vim". | |
452 | |
453 | |
454 Further reading: | |
455 |filetype-plugins| Documentation for the filetype plugins and information | |
456 about how to avoid that mappings cause problems. | |
457 |load-plugins| When the global plugins are loaded during startup. | |
458 |ftplugin-overrule| Overruling the settings from a global plugin. | |
459 |write-plugin| How to write a plugin script. | |
460 |plugin-details| For more information about using plugins or when your | |
461 plugin doesn't work. | |
462 |new-filetype| How to detect a new file type. | |
463 | |
464 ============================================================================== | |
8720
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
465 *05.6* Adding a help file *add-local-help* |
7 | 466 |
467 If you are lucky, the plugin you installed also comes with a help file. We | |
468 will explain how to install the help file, so that you can easily find help | |
469 for your new plugin. | |
8720
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
470 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
|
471 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
|
472 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
|
473 the "mkdir" commands if you already have the directory.) > |
7 | 474 |
475 :!mkdir ~/.vim | |
476 :!mkdir ~/.vim/plugin | |
8720
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
477 :!cp /tmp/doit.vim ~/.vim/plugin |
7 | 478 |
22 | 479 The "cp" command is for Unix, on MS-DOS you can use "copy". |
480 | |
7 | 481 Now create a "doc" directory in one of the directories in 'runtimepath'. > |
482 | |
483 :!mkdir ~/.vim/doc | |
484 | |
485 Copy the help file to the "doc" directory. > | |
486 | |
8720
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
487 :!cp /tmp/doit.txt ~/.vim/doc |
7 | 488 |
489 Now comes the trick, which allows you to jump to the subjects in the new help | |
490 file: Generate the local tags file with the |:helptags| command. > | |
491 | |
492 :helptags ~/.vim/doc | |
493 | |
494 Now you can use the > | |
495 | |
8720
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
496 :help doit |
7 | 497 |
8720
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
498 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
|
499 an entry for the local help file when you do: > |
7 | 500 |
501 :help local-additions | |
502 | |
503 The title lines from the local help files are automagically added to this | |
504 section. There you can see which local help files have been added and jump to | |
505 them through the tag. | |
506 | |
507 For writing a local help file, see |write-local-help|. | |
508 | |
509 ============================================================================== | |
8720
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
510 *05.7* The option window |
7 | 511 |
512 If you are looking for an option that does what you want, you can search in | |
513 the help files here: |options|. Another way is by using this command: > | |
514 | |
515 :options | |
516 | |
517 This opens a new window, with a list of options with a one-line explanation. | |
518 The options are grouped by subject. Move the cursor to a subject and press | |
519 <Enter> to jump there. Press <Enter> again to jump back. Or use CTRL-O. | |
520 | |
521 You can change the value of an option. For example, move to the "displaying | |
522 text" subject. Then move the cursor down to this line: | |
523 | |
524 set wrap nowrap ~ | |
525 | |
526 When you hit <Enter>, the line will change to: | |
527 | |
528 set nowrap wrap ~ | |
529 | |
530 The option has now been switched off. | |
531 | |
532 Just above this line is a short description of the 'wrap' option. Move the | |
533 cursor one line up to place it in this line. Now hit <Enter> and you jump to | |
534 the full help on the 'wrap' option. | |
535 | |
536 For options that take a number or string argument you can edit the value. | |
537 Then press <Enter> to apply the new value. For example, move the cursor a few | |
538 lines up to this line: | |
539 | |
540 set so=0 ~ | |
541 | |
542 Position the cursor on the zero with "$". Change it into a five with "r5". | |
543 Then press <Enter> to apply the new value. When you now move the cursor | |
544 around you will notice that the text starts scrolling before you reach the | |
545 border. This is what the 'scrolloff' option does, it specifies an offset | |
546 from the window border where scrolling starts. | |
547 | |
548 ============================================================================== | |
8720
9380c37723f8
commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
549 *05.8* Often used options |
7 | 550 |
551 There are an awful lot of options. Most of them you will hardly ever use. | |
552 Some of the more useful ones will be mentioned here. Don't forget you can | |
553 find more help on these options with the ":help" command, with single quotes | |
554 before and after the option name. For example: > | |
555 | |
556 :help 'wrap' | |
557 | |
558 In case you have messed up an option value, you can set it back to the | |
10 | 559 default by putting an ampersand (&) after the option name. Example: > |
7 | 560 |
561 :set iskeyword& | |
562 | |
563 | |
564 NOT WRAPPING LINES | |
565 | |
566 Vim normally wraps long lines, so that you can see all of the text. Sometimes | |
567 it's better to let the text continue right of the window. Then you need to | |
10 | 568 scroll the text left-right to see all of a long line. Switch wrapping off |
569 with this command: > | |
7 | 570 |
571 :set nowrap | |
572 | |
573 Vim will automatically scroll the text when you move to text that is not | |
574 displayed. To see a context of ten characters, do this: > | |
575 | |
576 :set sidescroll=10 | |
577 | |
578 This doesn't change the text in the file, only the way it is displayed. | |
579 | |
580 | |
581 WRAPPING MOVEMENT COMMANDS | |
582 | |
583 Most commands for moving around will stop moving at the start and end of a | |
584 line. You can change that with the 'whichwrap' option. This sets it to the | |
585 default value: > | |
586 | |
587 :set whichwrap=b,s | |
588 | |
589 This allows the <BS> key, when used in the first position of a line, to move | |
590 the cursor to the end of the previous line. And the <Space> key moves from | |
591 the end of a line to the start of the next one. | |
592 | |
593 To allow the cursor keys <Left> and <Right> to also wrap, use this command: > | |
594 | |
595 :set whichwrap=b,s,<,> | |
596 | |
597 This is still only for Normal mode. To let <Left> and <Right> do this in | |
598 Insert mode as well: > | |
599 | |
600 :set whichwrap=b,s,<,>,[,] | |
601 | |
602 There are a few other flags that can be added, see 'whichwrap'. | |
603 | |
604 | |
605 VIEWING TABS | |
606 | |
607 When there are tabs in a file, you cannot see where they are. To make them | |
608 visible: > | |
609 | |
610 :set list | |
611 | |
1278 | 612 Now every tab is displayed as ^I. And a $ is displayed at the end of each |
7 | 613 line, so that you can spot trailing spaces that would otherwise go unnoticed. |
614 A disadvantage is that this looks ugly when there are many Tabs in a file. | |
615 If you have a color terminal, or are using the GUI, Vim can show the spaces | |
616 and tabs as highlighted characters. Use the 'listchars' option: > | |
617 | |
618 :set listchars=tab:>-,trail:- | |
619 | |
620 Now every tab will be displayed as ">---" (with more or less "-") and trailing | |
621 white space as "-". Looks a lot better, doesn't it? | |
622 | |
623 | |
624 KEYWORDS | |
625 | |
626 The 'iskeyword' option specifies which characters can appear in a word: > | |
627 | |
628 :set iskeyword | |
629 < iskeyword=@,48-57,_,192-255 ~ | |
630 | |
631 The "@" stands for all alphabetic letters. "48-57" stands for ASCII | |
632 characters 48 to 57, which are the numbers 0 to 9. "192-255" are the | |
633 printable latin characters. | |
634 Sometimes you will want to include a dash in keywords, so that commands | |
635 like "w" consider "upper-case" to be one word. You can do it like this: > | |
636 | |
637 :set iskeyword+=- | |
638 :set iskeyword | |
639 < iskeyword=@,48-57,_,192-255,- ~ | |
640 | |
641 If you look at the new value, you will see that Vim has added a comma for you. | |
642 To remove a character use "-=". For example, to remove the underscore: > | |
643 | |
644 :set iskeyword-=_ | |
645 :set iskeyword | |
646 < iskeyword=@,48-57,192-255,- ~ | |
647 | |
648 This time a comma is automatically deleted. | |
649 | |
650 | |
651 ROOM FOR MESSAGES | |
652 | |
653 When Vim starts there is one line at the bottom that is used for messages. | |
654 When a message is long, it is either truncated, thus you can only see part of | |
655 it, or the text scrolls and you have to press <Enter> to continue. | |
656 You can set the 'cmdheight' option to the number of lines used for | |
657 messages. Example: > | |
658 | |
659 :set cmdheight=3 | |
660 | |
661 This does mean there is less room to edit text, thus it's a compromise. | |
662 | |
663 ============================================================================== | |
664 | |
665 Next chapter: |usr_06.txt| Using syntax highlighting | |
666 | |
14519 | 667 Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl: |