*usr_43.txt*	For Vim version 6.0c.  Last change: 2000 Jul 15

		     VIM USER MANUAL - by Bram Moolenaar
		
			       Using filetypes


|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*  Settings for a filetype

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.

First of all, Vim will recognize the filetype.  This is done by looking at the
file name and sometimes by inspecting a few lines in the file.  Then it will
load scripts specifially for that filetype.  Both ones that were provided with
Vim and scripts you have added yourself.

To use the provided settings, use this command: >
	:filetype settings on
Then edit a C language file.  You will notice that the 'cindent' option has
been switched on, so that indents are automatically adjusted.  The same
happens for other filetypes.  You can look in the directory
$VIMRUNTIME/settings to see which filetypes have settings.  For most files
there is also a section in the help file |filetype.txt|.

Some of the settings files define mappings.  But since you can also define
mappings yourself, these default mappings need to know which key sequence they
can use.  You need to define this with the variable "localmapchar".  For
example, you could use the comma.  This is an existing Vim command, but it's
hardly ever used.  Thus it's probaly OK to let the default mappings start with
it. >
	:let localmapchar = ','
If you now edit a mail message, you will notice the mapping ",q" has been
defined, which quotes lines.


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 four steps:				*your-runtime-dir*
1. Create your own runtime directory.  For example >
	mkdir ~/vim
<  In this directory create the "settings" directory: >
	mkdir ~/vim/settings
2. Add the name of this directory to the 'runtimepath' option.  It's best to
   prepend it (in case we want to skip the default settings file): >
	:set vimruntime^=~/vim/settings
<  Put this line in your startup vimrc file.
3. Create the file "~/vim/settings/c.vim", with the contents: >
	setlocal softtabstop=4
	map <buffer> ,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.

The mapping for ",c" will also disappear when editing another buffer.  The
":map <buffer>" command creates a mapping that is local the the current
buffer.  This works with any mapping command: ":map!", ":vmap", etc.


Suppose you do want to use most of the default filetype settings, but not for
mail files.  You can do this by creating a file that just contains: >
	let b:did_settings = 1
Put it in your own "settings" directory under the name "mail.vim".  This will
be picked up for the "mail" filetype.

==============================================================================
*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

==============================================================================
 vim:tw=78:
