annotate runtime/doc/usr_43.txt @ 15464:3faa7cc8207c v8.1.0740

patch 8.1.0740: Tcl test fails commit https://github.com/vim/vim/commit/8309b0559da6e9a581a7816572594c90c2d7f942 Author: Bram Moolenaar <Bram@vim.org> Date: Sun Jan 13 16:46:22 2019 +0100 patch 8.1.0740: Tcl test fails Problem: Tcl test fails. Solution: When the argument is empty don't give an error, instead rely on the error reporting higher up.
author Bram Moolenaar <Bram@vim.org>
date Sun, 13 Jan 2019 17:00:06 +0100
parents 5c5908e81e93
children af69c9335223
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
13963
1174611ad715 Vim 8.1 release
Christian Brabandt <cb@256bit.org>
parents: 10198
diff changeset
1 *usr_43.txt* For Vim version 8.1. Last change: 2015 Oct 23
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
3 VIM USER MANUAL - by Bram Moolenaar
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
4
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
5 Using filetypes
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
6
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
8 When you are editing a file of a certain type, for example a C program or a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
9 shell script, you often use the same option settings and mappings. You
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
10 quickly get tired of manually setting these each time. This chapter explains
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
11 how to do it automatically.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
12
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
13 |43.1| Plugins for a filetype
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
14 |43.2| Adding a filetype
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
15
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
16 Next chapter: |usr_44.txt| Your own syntax highlighted
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
17 Previous chapter: |usr_42.txt| Add new menus
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
18 Table of contents: |usr_toc.txt|
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
19
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
20 ==============================================================================
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
21 *43.1* Plugins for a filetype *filetype-plugin*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
22
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
23 How to start using filetype plugins has already been discussed here:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
24 |add-filetype-plugin|. But you probably are not satisfied with the default
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
25 settings, because they have been kept minimal. Suppose that for C files you
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
26 want to set the 'softtabstop' option to 4 and define a mapping to insert a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
27 three-line comment. You do this with only two steps:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
28
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
29 *your-runtime-dir*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
30 1. Create your own runtime directory. On Unix this usually is "~/.vim". In
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
31 this directory create the "ftplugin" directory: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
32
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
33 mkdir ~/.vim
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
34 mkdir ~/.vim/ftplugin
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
35 <
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
36 When you are not on Unix, check the value of the 'runtimepath' option to
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
37 see where Vim will look for the "ftplugin" directory: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
38
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
39 set runtimepath
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
40
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
41 < You would normally use the first directory name (before the first comma).
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
42 You might want to prepend a directory name to the 'runtimepath' option in
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
43 your |vimrc| file if you don't like the default value.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
44
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
45 2. Create the file "~/.vim/ftplugin/c.vim", with the contents: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
46
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
47 setlocal softtabstop=4
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
48 noremap <buffer> <LocalLeader>c o/**************<CR><CR>/<Esc>
7183
ffad29dc7eee commit https://github.com/vim/vim/commit/a0f849ee40cbea3c889345256786b640b0becca2
Christian Brabandt <cb@256bit.org>
parents: 5294
diff changeset
49 let b:undo_ftplugin = "setl softtabstop< | unmap <buffer> <LocalLeader>c"
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
50
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
51 Try editing a C file. You should notice that the 'softtabstop' option is set
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
52 to 4. But when you edit another file it's reset to the default zero. That is
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
53 because the ":setlocal" command was used. This sets the 'softtabstop' option
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
54 only locally to the buffer. As soon as you edit another buffer, it will be
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
55 set to the value set for that buffer. For a new buffer it will get the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
56 default value or the value from the last ":set" command.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
57
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
58 Likewise, the mapping for "\c" will disappear when editing another buffer.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
59 The ":map <buffer>" command creates a mapping that is local to the current
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
60 buffer. This works with any mapping command: ":map!", ":vmap", etc. The
2033
de5a43c5eedc Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents: 1702
diff changeset
61 |<LocalLeader>| in the mapping is replaced with the value of the
de5a43c5eedc Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents: 1702
diff changeset
62 "maplocalleader" variable.
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
63
7183
ffad29dc7eee commit https://github.com/vim/vim/commit/a0f849ee40cbea3c889345256786b640b0becca2
Christian Brabandt <cb@256bit.org>
parents: 5294
diff changeset
64 The line to set b:undo_ftplugin is for when the filetype is set to another
ffad29dc7eee commit https://github.com/vim/vim/commit/a0f849ee40cbea3c889345256786b640b0becca2
Christian Brabandt <cb@256bit.org>
parents: 5294
diff changeset
65 value. In that case you will want to undo your preferences. The
ffad29dc7eee commit https://github.com/vim/vim/commit/a0f849ee40cbea3c889345256786b640b0becca2
Christian Brabandt <cb@256bit.org>
parents: 5294
diff changeset
66 b:undo_ftplugin variable is executed as a command. Watch out for characters
ffad29dc7eee commit https://github.com/vim/vim/commit/a0f849ee40cbea3c889345256786b640b0becca2
Christian Brabandt <cb@256bit.org>
parents: 5294
diff changeset
67 with a special meaning inside a string, such as a backslash.
ffad29dc7eee commit https://github.com/vim/vim/commit/a0f849ee40cbea3c889345256786b640b0becca2
Christian Brabandt <cb@256bit.org>
parents: 5294
diff changeset
68
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
69 You can find examples for filetype plugins in this directory: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
70
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
71 $VIMRUNTIME/ftplugin/
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
72
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
73 More details about writing a filetype plugin can be found here:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
74 |write-plugin|.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
75
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
76 ==============================================================================
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
77 *43.2* Adding a filetype
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
78
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
79 If you are using a type of file that is not recognized by Vim, this is how to
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
80 get it recognized. You need a runtime directory of your own. See
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
81 |your-runtime-dir| above.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
82
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
83 Create a file "filetype.vim" which contains an autocommand for your filetype.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
84 (Autocommands were explained in section |40.3|.) Example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
85
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
86 augroup filetypedetect
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
87 au BufNewFile,BufRead *.xyz setf xyz
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
88 augroup END
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
89
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
90 This will recognize all files that end in ".xyz" as the "xyz" filetype. The
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
91 ":augroup" commands put this autocommand in the "filetypedetect" group. This
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
92 allows removing all autocommands for filetype detection when doing ":filetype
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
93 off". The "setf" command will set the 'filetype' option to its argument,
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
94 unless it was set already. This will make sure that 'filetype' isn't set
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
95 twice.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
96
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
97 You can use many different patterns to match the name of your file. Directory
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
98 names can also be included. See |autocmd-patterns|. For example, the files
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
99 under "/usr/share/scripts/" are all "ruby" files, but don't have the expected
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
100 file name extension. Adding this to the example above: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
101
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
102 augroup filetypedetect
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
103 au BufNewFile,BufRead *.xyz setf xyz
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
104 au BufNewFile,BufRead /usr/share/scripts/* setf ruby
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
105 augroup END
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
106
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
107 However, if you now edit a file /usr/share/scripts/README.txt, this is not a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
108 ruby file. The danger of a pattern ending in "*" is that it quickly matches
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
109 too many files. To avoid trouble with this, put the filetype.vim file in
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
110 another directory, one that is at the end of 'runtimepath'. For Unix for
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
111 example, you could use "~/.vim/after/filetype.vim".
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
112 You now put the detection of text files in ~/.vim/filetype.vim: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
113
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
114 augroup filetypedetect
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
115 au BufNewFile,BufRead *.txt setf text
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
116 augroup END
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
117
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
118 That file is found in 'runtimepath' first. Then use this in
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
119 ~/.vim/after/filetype.vim, which is found last: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
120
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
121 augroup filetypedetect
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
122 au BufNewFile,BufRead /usr/share/scripts/* setf ruby
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
123 augroup END
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
124
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
125 What will happen now is that Vim searches for "filetype.vim" files in each
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
126 directory in 'runtimepath'. First ~/.vim/filetype.vim is found. The
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
127 autocommand to catch *.txt files is defined there. Then Vim finds the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
128 filetype.vim file in $VIMRUNTIME, which is halfway 'runtimepath'. Finally
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
129 ~/.vim/after/filetype.vim is found and the autocommand for detecting ruby
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
130 files in /usr/share/scripts is added.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
131 When you now edit /usr/share/scripts/README.txt, the autocommands are
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
132 checked in the order in which they were defined. The *.txt pattern matches,
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
133 thus "setf text" is executed to set the filetype to "text". The pattern for
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
134 ruby matches too, and the "setf ruby" is executed. But since 'filetype' was
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
135 already set to "text", nothing happens here.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
136 When you edit the file /usr/share/scripts/foobar the same autocommands are
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
137 checked. Only the one for ruby matches and "setf ruby" sets 'filetype' to
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
138 ruby.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
139
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
140
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
141 RECOGNIZING BY CONTENTS
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
142
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
143 If your file cannot be recognized by its file name, you might be able to
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
144 recognize it by its contents. For example, many script files start with a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
145 line like:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
146
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
147 #!/bin/xyz ~
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
148
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
149 To recognize this script create a file "scripts.vim" in your runtime directory
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
150 (same place where filetype.vim goes). It might look like this: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
151
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
152 if did_filetype()
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
153 finish
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
154 endif
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
155 if getline(1) =~ '^#!.*[/\\]xyz\>'
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
156 setf xyz
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
157 endif
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
158
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
159 The first check with did_filetype() is to avoid that you will check the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
160 contents of files for which the filetype was already detected by the file
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
161 name. That avoids wasting time on checking the file when the "setf" command
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
162 won't do anything.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
163 The scripts.vim file is sourced by an autocommand in the default
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
164 filetype.vim file. Therefore, the order of checks is:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
165
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
166 1. filetype.vim files before $VIMRUNTIME in 'runtimepath'
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
167 2. first part of $VIMRUNTIME/filetype.vim
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
168 3. all scripts.vim files in 'runtimepath'
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
169 4. remainder of $VIMRUNTIME/filetype.vim
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
170 5. filetype.vim files after $VIMRUNTIME in 'runtimepath'
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
171
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
172 If this is not sufficient for you, add an autocommand that matches all files
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
173 and sources a script or executes a function to check the contents of the file.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
174
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
175 ==============================================================================
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
176
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
177 Next chapter: |usr_44.txt| Your own syntax highlighted
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
178
14519
5c5908e81e93 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
179 Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl: