*usr_06.txt*	For Vim version 6.0j.  Last change: 2000 Oct 22

		     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 favirite 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 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.  They usually add a
nice feature for a limited audience (if it was for everybody it would have
been included in Vim itself).  A plugin is nothing more than a Vim script file
that is loaded automatically.

There are two types of plugins:

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

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

							*add-global-plugin*
There are only two steps for using 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.

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

There are two steps for adding another 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 more filetype plugins by dropping them in the right directory.
The name of this directory is in the same directory mentioned above for
global plugins, but with the last part looking like: >

	ftplugin/<filetype>/name.vim

Example for Unix: >

	~/.vim/ftplugin/cpp/stuff.vim

The <filetype> part is the name of the filetype the plugin is to be used for.
In this case it's "cpp".  Only files of this filetype will use the settings
from the plugin.  The name of the plugin doesn't matter, but 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.
|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:
