*usr_06.txt*	For Vim version 6.0ad.  Last change: 2001 Feb 18

		     VIM USER MANUAL - by Bram Moolenaar
		
			      Set your settings


|06.1|  The vimrc file
|06.2|  The default vimrc file explained
|06.3|  Adding a plugin
|06.4|  Adding a help file
|06.5|  Often used options

     Next chapter: |usr_07.txt|  Using syntax highlighting
 Previous chapter: |usr_05.txt|  Making big changes
Table of contents: |usr_toc.txt|

==============================================================================
*06.1*  The vimrc file

You probably got tired of typing commands that you use very often.  To start
with all your favorite option settings and mappings, you write them in what is
called the vimrc file.

--todo--

If you look in the "runtime" directory of the distributed Vim files, you will
find the "vimrc_example.vim" file.  If you don't know where it is, you can
edit it with this command: >
	:e $VIMRUNTIME/vimrc_example.vim
Then use "CTRL-G" to see the full name of the file.

This file contains a number of useful items when running Vim.  You can use it
as the start for your own vimrc file.  To do this, make a copy, so that you
can modify it.  When you do this from Vim the $VIMRUNTIME will be expanded
automatically.  Example for Unix: >

	:!cp -i $VIMRUNTIME/vimrc_example.vim ~/.vimrc

Note the use of the "-i" argument, which is just to avoid overwriting an
existing .vimrc file.

--todo--

For more information on how to write a Vim script file: |usr_40.txt|.

==============================================================================
*06.2*  The default vimrc file explained

--todo--

							*vimrc-filetype*
This line: >
	filetype plugin indent on

switches on three very clever mechanisms:
1. Filetype detection.
   Whenever you start editing a file, Vim will try to figure out what kind of
   file this is.  When you edit "main.c", Vim will see the ".c" extension and
   recognize this as a "c" filetype.  When you edit a file that starts with
   "#!/bin/sh", Vim will recognize it as a "sh" filetype.
   The filetype detection is used for syntax highlighting and the other two
   items below.
   See |filetypes|.

2. Using filetype plugin files
   Many different filetypes are edited with different options.  For example,
   when you edit a "c" file, it's very useful to set the 'cindent' option to
   automatically indent the lines.  These commonly useful option settings are
   included with Vim in filetype plugins.  You can also add your own, see
   |write-filetype-plugin|.

3. Using indent files
   When editing programs, the indent of a line can often be computed
   automatically.  Vim comes with these indent rules for a number of
   filetypes.  See |:filetype-indent-on| and 'indentexpr'.

--todo--

==============================================================================
*06.3*  Adding a plugin						*add-plugin*

Vim's functionality can be extended by adding plugins.  A plugin is nothing
more than a Vim script file that is loaded automatically when Vim starts.  You
can add a plugin very easy by dropping it in a plugin directory.
{not available when Vim was compiled without the |+eval| feature}

There are two types of plugins:

    global plugin: Used for all kinds of files
  filetype plugin: Only used for a specific type of file

The global plugins will be discussed first, then the filetype ones
|add-filetype-plugin|.


GLOBAL PLUGINS
							*standard-plugin*
When you start Vim, it will automatically load a number of global plugins.
You don't have to do anything for this.  They add functionality that most
people will want to use, but which was implemented as a Vim script instead of
being compiled into Vim.  You can find them listed in the help index
|standard-plugin-list|.  Also see |load-plugins|.

							*add-global-plugin*
You can add a global plugin to add functionality that will always be present
when you use Vim.  There are only two steps for adding a global plugin:
1. Get a copy of the plugin.
2. Drop it in the right directory.


GETTING A GLOBAL PLUGIN

Where can you find plugins?
- Some come with Vim.  You can find them in the directory $VIMRUNTIME/macros
  and its sub-directories.
- Download from the net, check out http://www.vim.org.
- They are sometimes posted in a Vim |maillist|.
- You could write one yourself, see |write-plugin|.


USING A GLOBAL PLUGIN

First read the text in the plugin itself to check for any special conditions.
Then copy the file to your plugin directory:

	system		plugin directory ~
	Unix		~/.vim/plugin/
	PC and OS/2	$HOME/vimfiles/plugin or $VIM/vimfiles/plugin
	Amiga		s:vimfiles/plugin
	Macintosh	$VIM:vimfiles:plugin
	RISC-OS		Choices:vimfiles.plugin

Example for Unix (assuming you didn't have a plugin directory yet): >

	mkdir ~/.vim
	mkdir ~/.vim/plugin
	cp /usr/local/share/vim/vim60/macros/justify.vim ~/.vim/plugin

That's all!  Now you can use the commands defined in this plugin to justify
text.


FILETYPE PLUGINS
							*add-filetype-plugin*
The Vim distribution comes with a set of plugins for different filetypes that
you can start using with this command: >

	:filetype plugin on

That's all!  See |vimrc-filetype|.

If you are missing a plugin for a filetype you are using, or you found a
better one, you can add it.
There are two steps for adding a filetype plugin:
1. Get a copy of the plugin.
2. Drop it in the right directory.


GETTING A FILETYPE PLUGIN

You can find them in the same places as the global plugins.  Watch out if the
type of file is mentioned, then you know if the plugin is a global or a
filetype one.  The scripts in $VIMRUNTIME/macros are global ones, the filetype
plugins are in $VIMRUNTIME/ftplugin.


USING A FILETYPE PLUGIN

You can add a filetype plugins by dropping it in the right directory.  The
name of this directory is in the same directory mentioned above for global
plugins, but the last part is "ftplugin".  Suppose you have found a plugin for
the "stuff" filetype, and you are on Unix.  Then you can move this file to the
ftplugin directory: >

	mv thefile ~/.vim/ftplugin/stuff.vim

If that file already exists you already have a plugin for "stuff".  You might
want to check if the existing plugin doesn't conflict with the one you are
adding.  If it's OK, you can give the new one another name: >

	mv thefile ~/.vim/ftplugin/stuff_too.vim

The underscore is used to separate the name of the filetype from the rest,
which can be anything.

On MS-DOS you cannot use long filenames.  You would run into trouble if you
add a second plugin and the filetype has more than six characters.  You can
use an extra directory to get around this: >

	mkdir $VIM/vimfiles/ftplugin/fortran
	copy thefile $VIM/vimfiles/ftplugin/fortran/too.vim

The generic names for the filetype plugins are: >

	ftplugin/<filetype>.vim
	ftplugin/<filetype>_<name>.vim
	ftplugin/<filetype>/<name>.vim

Examples for the "stuff" filetype on Unix: >

	~/.vim/ftplugin/stuff.vim
	~/.vim/ftplugin/stuff_def.vim
	~/.vim/ftplugin/stuff/header.vim

The <filetype> part is the name of the filetype the plugin is to be used for.
Only files of this filetype will use the settings from the plugin.  The <name>
part of the plugin file doesn't matter, you can use it to have several plugins
for the same filetype.  Note that it must end in ".vim".


Further reading:
|filetype-plugins|	Documentation for the filetype plugins and information
			about how to avoid that mappings cause problems.
|load-plugins|		When the global plugins are loaded during startup.
|ftplugin-overrule|	Overruling the settings from a global plugin.
|write-plugin|		How to write a plugin script.
|plugin-details|	For more information about using plugins or when your
			plugin doesn't work.

==============================================================================
*06.4*  Adding a help file			*add-local-help*

If you are lucky, the plugin you installed also comes with a help file.

To add a help file locally (examples are for Unix): >
1. Create a "doc" directory in one of the directories in 'runtimepath'. >

	mkdir ~/.vim/doc

2. Move your help file to the "doc" directory. >

	mv ~/in/myhelp.txt ~/.vim/doc/myhelp.txt

3. Now comes the trick, which allows you to jump to the subjects in the new
   help file: Generate the local tags file with the |:helptags| command. >

	vim
	:helptags ~/.vim/doc

Now you can use the >

	:help myhelp

command to find "myhelp" in the help file you just added.  You can see an
entry for the local help file when you do >

	:help

and go down to the "LOCAL ADDITIONS" section.  The title lines from the local
help files are automagically added to this section.  There you can see which
local help files have been added and jump to them through the tag.

For writing a local help file, see |write-local-help|.

==============================================================================
*06.5*  Often used options

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