/usr/share/doc/vim-doc/html/usr_43.html is in vim-doc 2:7.4.488-7+deb8u3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 | <HTML>
<HEAD>
<META HTTP-EQUIV="Content-type" content="text/html; charset=ISO-8859-1">
<TITLE>Vim documentation: usr_43</TITLE>
</HEAD>
<BODY BGCOLOR="#ffffff">
<H1>Vim documentation: usr_43</H1>
<A NAME="top"></A>
<A HREF="index.html">main help file</A>
<HR>
<PRE>
*<A NAME="usr_43.txt"></A><B>usr_43.txt</B>* For Vim version 7.4. Last change: 2008 Dec 28
VIM USER MANUAL - by <A HREF="intro.html#Bram">Bram</A> <A HREF="intro.html#Moolenaar">Moolenaar</A>
Using <A HREF="filetype.html#filetypes">filetypes</A>
When you are editing a file of a certain type, for example a C program or a
shell <A HREF="usr_41.html#script">script</A>, you often use the same option settings and mappings. You
quickly get tired of manually setting these each time. This chapter explains
how to <A HREF="diff.html#do">do</A> <A HREF="motion.html#it">it</A> automatically.
|<A HREF="#43.1">43.1</A>| Plugins for a <A HREF="filetype.html#filetype">filetype</A>
|<A HREF="#43.2">43.2</A>| Adding a <A HREF="filetype.html#filetype">filetype</A>
Next chapter: |<A HREF="usr_44.html">usr_44.txt</A>| Your own <A HREF="syntax.html#syntax">syntax</A> highlighted
Previous chapter: |<A HREF="usr_42.html">usr_42.txt</A>| Add new <A HREF="gui.html#menus">menus</A>
Table of contents: |<A HREF="usr_toc.html">usr_toc.txt</A>|
==============================================================================
*<A NAME="43.1"></A><B>43.1</B>* Plugins for a <A HREF="filetype.html#filetype">filetype</A> *<A NAME="filetype-plugin"></A><B>filetype-plugin</B>*
How to start using <A HREF="filetype.html#filetype">filetype</A> plugins has already been discussed here:
|<A HREF="usr_05.html#add-filetype-plugin">add-filetype-plugin</A>|. But you probably are not satisfied with the default
settings, because they have been kept minimal. Suppose that for C files you
want to set the <A HREF="options.html#'softtabstop'">'softtabstop'</A> option to 4 and define a <A HREF="map.html#mapping">mapping</A> to insert a
three-line comment. You <A HREF="diff.html#do">do</A> this with only two steps:
*<A NAME="your-runtime-dir"></A><B>your-runtime-dir</B>*
1. Create your own runtime directory. On <A HREF="os_unix.html#Unix">Unix</A> this usually is "~/.vim". In
this directory create the "<A HREF="usr_41.html#ftplugin">ftplugin</A>" directory:
<B> mkdir ~/.vim</B>
<B> mkdir ~/.vim/ftplugin</B>
When you are not on <A HREF="os_unix.html#Unix">Unix</A>, check the value of the <A HREF="options.html#'runtimepath'">'runtimepath'</A> option to
see where Vim will look for the "<A HREF="usr_41.html#ftplugin">ftplugin</A>" directory:
<B> set runtimepath</B>
You would normally use the first directory name (before the first comma).
You might want to prepend a directory name to the <A HREF="options.html#'runtimepath'">'runtimepath'</A> option in
your |<A HREF="starting.html#vimrc">vimrc</A>| file if you don't like the default value.
2. Create the file "~/.vim/ftplugin/c.vim", with the contents:
<B> setlocal softtabstop=4</B>
<B> noremap <buffer> <LocalLeader>c o/**************<CR><CR>/<Esc></B>
Try editing a C file. You should notice that the <A HREF="options.html#'softtabstop'">'softtabstop'</A> option is set
to 4. But when you edit another file it's reset to the default zero. That is
because the "<A HREF="options.html#:setlocal">:setlocal</A>" command was used. This sets the <A HREF="options.html#'softtabstop'">'softtabstop'</A> option
only locally to the buffer. As soon <A HREF="motion.html#as">as</A> you edit another buffer, <A HREF="motion.html#it">it</A> will be
set to the value set for that buffer. For a new buffer <A HREF="motion.html#it">it</A> will get the
default value or the value from the last "<A HREF="options.html#:set">:set</A>" command.
Likewise, the <A HREF="map.html#mapping">mapping</A> for "\c" will disappear when editing another buffer.
The "<A HREF="map.html#:map">:map</A> <buffer>" command creates a <A HREF="map.html#mapping">mapping</A> that is local to the current
buffer. This works with any <A HREF="map.html#mapping">mapping</A> command: "<A HREF="map.html#:map!">:map!</A>", "<A HREF="map.html#:vmap">:vmap</A>", etc. The
|<A HREF="map.html#<LocalLeader>"><LocalLeader></A>| in the <A HREF="map.html#mapping">mapping</A> is replaced with the value of the
"<A HREF="map.html#maplocalleader">maplocalleader</A>" variable.
You can find examples for <A HREF="filetype.html#filetype">filetype</A> plugins in this directory:
<B> $VIMRUNTIME/ftplugin/</B>
More details about <A HREF="editing.html#writing">writing</A> a <A HREF="filetype.html#filetype">filetype</A> <A HREF="usr_05.html#plugin">plugin</A> can be found here:
|<A HREF="usr_41.html#write-plugin">write-plugin</A>|.
==============================================================================
*<A NAME="43.2"></A><B>43.2</B>* Adding a <A HREF="filetype.html#filetype">filetype</A>
If you are using a type of file that is not recognized by Vim, this is how to
get <A HREF="motion.html#it">it</A> recognized. You need a runtime directory of your own. See
|<A HREF="#your-runtime-dir">your-runtime-dir</A>| above.
Create a file "filetype.vim" which contains an <A HREF="autocmd.html#autocommand">autocommand</A> for your <A HREF="filetype.html#filetype">filetype</A>.
(Autocommands were explained in section |<A HREF="usr_40.html#40.3">40.3</A>|.) Example:
<B> augroup filetypedetect</B>
<B> au BufNewFile,BufRead *.xyz setf xyz</B>
<B> augroup END</B>
This will recognize all files that end in ".xyz" <A HREF="motion.html#as">as</A> the "xyz" <A HREF="filetype.html#filetype">filetype</A>. The
"<A HREF="autocmd.html#:augroup">:augroup</A>" commands put this <A HREF="autocmd.html#autocommand">autocommand</A> in the "filetypedetect" group. This
allows removing all autocommands for <A HREF="filetype.html#filetype">filetype</A> detection when doing "<A HREF="filetype.html#:filetype">:filetype</A>
off". The "setf" command will set the <A HREF="options.html#'filetype'">'filetype'</A> option to its argument,
unless <A HREF="motion.html#it">it</A> was set already. This will make sure that <A HREF="options.html#'filetype'">'filetype'</A> isn't set
<A HREF="if_cscop.html#twice">twice</A>.
You can use many different patterns to match the name of your file. Directory
names can also be included. See |<A HREF="autocmd.html#autocmd-patterns">autocmd-patterns</A>|. For example, the files
under "/usr/share/scripts/" are all "<A HREF="if_ruby.html#ruby">ruby</A>" files, but don't have the expected
file name extension. Adding this to the example above:
<B> augroup filetypedetect</B>
<B> au BufNewFile,BufRead *.xyz setf xyz</B>
<B> au BufNewFile,BufRead /usr/share/scripts/* setf ruby</B>
<B> augroup END</B>
However, if you now edit a file /usr/share/scripts/README.txt, this is not a
<A HREF="if_ruby.html#ruby">ruby</A> file. The danger of a <A HREF="pattern.html#pattern">pattern</A> ending in "*" is that <A HREF="motion.html#it">it</A> quickly matches
too many files. To avoid trouble with this, put the filetype.vim file in
another directory, one that is at the end of <A HREF="options.html#'runtimepath'">'runtimepath'</A>. For <A HREF="os_unix.html#Unix">Unix</A> for
example, you could use "~/.vim/after/filetype.vim".
You now put the detection of text files in ~/.vim/filetype.vim:
<B> augroup filetypedetect</B>
<B> au BufNewFile,BufRead *.txt setf text</B>
<B> augroup END</B>
That file is found in <A HREF="options.html#'runtimepath'">'runtimepath'</A> first. Then use this in
~/.vim/after/filetype.vim, which is found last:
<B> augroup filetypedetect</B>
<B> au BufNewFile,BufRead /usr/share/scripts/* setf ruby</B>
<B> augroup END</B>
What will happen now is that Vim searches for "filetype.vim" files in each
directory in <A HREF="options.html#'runtimepath'">'runtimepath'</A>. First ~/.vim/filetype.vim is found. The
<A HREF="autocmd.html#autocommand">autocommand</A> to catch *.txt files is defined there. Then Vim finds the
filetype.vim file in <A HREF="starting.html#$VIMRUNTIME">$VIMRUNTIME</A>, which is halfway <A HREF="options.html#'runtimepath'">'runtimepath'</A>. Finally
~/.vim/after/filetype.vim is found and the <A HREF="autocmd.html#autocommand">autocommand</A> for detecting <A HREF="if_ruby.html#ruby">ruby</A>
files in /usr/share/scripts is added.
When you now edit /usr/share/scripts/README.txt, the autocommands are
checked in the order in which they were defined. The *.txt <A HREF="pattern.html#pattern">pattern</A> matches,
thus "setf text" is executed to set the <A HREF="filetype.html#filetype">filetype</A> to "text". The <A HREF="pattern.html#pattern">pattern</A> for
<A HREF="if_ruby.html#ruby">ruby</A> matches too, and the "setf ruby" is executed. But since <A HREF="options.html#'filetype'">'filetype'</A> was
already set to "text", nothing happens here.
When you edit the file /usr/share/scripts/foobar the same autocommands are
checked. Only the one for <A HREF="if_ruby.html#ruby">ruby</A> matches and "setf ruby" sets <A HREF="options.html#'filetype'">'filetype'</A> to
<A HREF="if_ruby.html#ruby">ruby</A>.
RECOGNIZING BY CONTENTS
If your file cannot be recognized by its file name, you might be able to
recognize <A HREF="motion.html#it">it</A> by its contents. For example, many <A HREF="usr_41.html#script">script</A> files start with a
line like:
<B><FONT COLOR="PURPLE"> #!/bin/xyz </FONT></B>
To recognize this <A HREF="usr_41.html#script">script</A> create a file "scripts.vim" in your runtime directory
(same place where filetype.vim goes). It might look like this:
<B> if did_filetype()</B>
<B> finish</B>
<B> endif</B>
<B> if getline(1) =~ '^#!.*[/\\]xyz\>'</B>
<B> setf xyz</B>
<B> endif</B>
The first check with <A HREF="eval.html#did_filetype()">did_filetype()</A> is to avoid that you will check the
contents of files for which the <A HREF="filetype.html#filetype">filetype</A> was already detected by the file
name. That avoids wasting time on checking the file when the "setf" command
won't <A HREF="diff.html#do">do</A> anything.
The scripts.vim file is sourced by an <A HREF="autocmd.html#autocommand">autocommand</A> in the default
filetype.vim file. Therefore, the order of checks is:
1. filetype.vim files before <A HREF="starting.html#$VIMRUNTIME">$VIMRUNTIME</A> in <A HREF="options.html#'runtimepath'">'runtimepath'</A>
2. first part of $VIMRUNTIME/filetype.vim
3. all scripts.vim files in <A HREF="options.html#'runtimepath'">'runtimepath'</A>
4. remainder of $VIMRUNTIME/filetype.vim
5. filetype.vim files after <A HREF="starting.html#$VIMRUNTIME">$VIMRUNTIME</A> in <A HREF="options.html#'runtimepath'">'runtimepath'</A>
If this is not sufficient for you, add an <A HREF="autocmd.html#autocommand">autocommand</A> that matches all files
and sources a <A HREF="usr_41.html#script">script</A> or executes a function to check the contents of the file.
==============================================================================
Next chapter: |<A HREF="usr_44.html">usr_44.txt</A>| Your own <A HREF="syntax.html#syntax">syntax</A> highlighted
Copyright: see |<A HREF="usr_01.html#manual-copyright">manual-copyright</A>| vim:tw=78:ts=8:ft=help:norl:
<A HREF="#top">top</A> - <A HREF="index.html">main help file</A>
</PRE>
</BODY>
</HTML>
|