*usr_43.txt*	For Vim version 6.0aj.  Last change: 2001 Jun 03

		     VIM USER MANUAL - by Bram Moolenaar
		
			       Using filetypes


Introduction.

|43.1|  Settings for a filetype
|43.2|  Adding a filetype
|43.3|  Automatic commands

     Next chapter: |usr_44.txt|  Your own syntax highlighted
 Previous chapter: |usr_42.txt|  Add new menus
Table of contents: |usr_toc.txt|

==============================================================================
*43.1*  Plugins for a filetype				*filetype-plugin*

When you are editing a certain kind of file you tend to use the same option
values and mappings, but different from when editing other files.  And you
don't want to set these manually each time.  Vim has support for this.

How to start using filetype plugins has already been discussed here:
|add-filetype-plugin|.

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
'softtabstop' option to 4 and define a mapping to insert a three-line comment.
You do this with only two steps:			*your-runtime-dir*

1. Create your own runtime directory.  For example >
	mkdir ~/.vim
<  In this directory create the "ftplugin" directory: >
	mkdir ~/.vim/ftplugin
<  And then a directory with the name of the filetype, in this case it's "c": >
	mkdir ~/.vim/ftplugin/c
<
   Check the value of the 'runtimepath' option to see where Vim will look for
   the "ftplugin" directory: >
	set runtimepath
<  You would normally use the first directory name (before the comma).  You
   might want to set this option in your |vimrc| file if you don't like the
   default value.

2. Create the file "~/.vim/ftplugin/c/c.vim", with the contents: >
	setlocal softtabstop=4
	noremap <buffer> <LocalLeader>c o/**************<CR><CR>/<Esc>

Try editing a C file.  You should notice that the 'softtabstop' option is set
to 4.  But when you edit another file it's reset to the default zero.  That is
because the ":setlocal" command was used.  This sets an option only locally to
the buffer.  As soon as you edit another buffer, it will be set to the value
set for that buffer.  For a new buffer it will get the value last set with a
":set" command or the default value.

Also, the mapping for "\c" will disappear when editing another buffer.  The
":map <buffer>" command creates a mapping that is local to the current buffer.
This works with any mapping command: ":map!", ":vmap", etc.  The
|<LocalLeader>| in the mapping is replaced with the value of "maplocalleader".

You can find examples for filetype plugins below this directory: >
	$VIMRUNTIME/ftplugin/
More details about writing a filetype plugin can be found here:
|write-plugin|.

==============================================================================
*43.2*  Adding a filetype

If you are using a filetype that is not recognized by Vim, this is how to get
them recognized.  You need a runtime directory of your own. See
|your-runtime-dir| above.

Create a file "filetype.vim" which contains an autocommand for your filetype.
Example: >
	augroup filetypedetect
	au BufNewFile,BufRead *.xyz	SetFT xyz
	augroup END
This will recognize all files that end in ".xyz" as a "xyz" filetype.  The
":augroup" commands put this autocommand in the "filetypedetect" group.  This
allows removing all autocommands for filetype detection when doing ":filetype
off".  The "SetFT" command is defined in the default filetype.vim.  It will
set the 'filetype' option to its argument, unless it was set already.  This
will make sure that 'filetype' isn't set twice.

You can use many different patterns to match the name of your file.  Directory
names can also be included.  See |autocmd-patterns|.

If your file cannot be recognized by its file name, you might be able to
recognize it by its contents.  For example, many script files start with a
line like: >
	#!/bin/xyz
To recognize this script create a file "scripts.vim" in your runtime
directory.  It might look like this: >
	if did_filetype()
	  finish
	endif
	if getline(1) =~ '^#!.*[/\\]t\=csh\>'
	  setlocal ft=csh
	endif
The first check with did_filetype() is to avoid that you will check the
contents of files for which filetype was already detected by the file name.
Not only might this result in a wrong filetype, it also takes a bit more time.

Now you need to make your scripts.vim file be called.  This isn't done
automatically, like with the filetype.vim file.  Add a line to your
filetype.vim file: >
	au BufNewFile,BufRead,StdinReadPost *  if !did_filetype()|so <sfile>:p:h/scripts.vim|endif
Normally you would put this line at the end to make it run after the other
autocommands.  You can also put it at the start, so that it overrules the
following autocommands.  But always put it inside the "augroup" commands.  You
could also use two scripts, one sourced first, then the autocommands that match
with the file name, and then another script: >
	augroup filetypedetect
	au BufNewFile,BufRead,StdinReadPost *  if !did_filetype()|so <sfile>:p:h/scripts1.vim|endif
	au BufNewFile,BufRead *.xyz	SetFT xyz
	au BufNewFile,BufRead,StdinReadPost *  if !did_filetype()|so <sfile>:p:h/scripts2.vim|endif
	augroup END
But you probably don't need to make it this complicated.  But it explains why
your scripts.vim isn't loaded automatically: Vim doesn't know when you want to
do it.

Note the use of "<sfile>:p:h", which gets the directory name of where the
"filetype.vim" file is.  Thus the "scripts.vim" file is sourced from the same
directory.

==============================================================================
*43.3*  Automatic commands

==============================================================================

Next chapter: |usr_44.txt|  Your own syntax highlighted

Copyright: see |manual-copyright|  vim:tw=78:
