vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

usr_05.txt (31628B)


      1 *usr_05.txt*	For Vim version 9.2.  Last change: 2026 Aug 30
      2 
      3 
      4 		     VIM USER MANUAL	by Bram Moolenaar
      5 
      6 
      7 			      Set your settings
      8 
      9 
     10 Vim can be tuned to work like you want it to.  This chapter shows you how to
     11 make Vim start with options set to different values.  Add plugins to extend
     12 Vim's capabilities.  Or define your own macros.
     13 
     14 |05.1|	The vimrc file
     15 |05.2|	The example vimrc file explained
     16 |05.3|	The defaults.vim file explained
     17 |05.4|	Simple mappings
     18 |05.5|	Adding a package
     19 |05.6|	Adding a plugin
     20 |05.7|	Adding a help file
     21 |05.8|	The option window
     22 |05.9|	Often used options
     23 
     24      Next chapter: |usr_06.txt|  Using syntax highlighting
     25  Previous chapter: |usr_04.txt|  Making small changes
     26 Table of contents: |usr_toc.txt|
     27 
     28 ==============================================================================
     29 *05.1*	The vimrc file					*vimrc-intro*
     30 
     31 You probably got tired of typing commands that you use very often.  To start
     32 Vim with all your favorite option settings and mappings, you write them in
     33 what is called the vimrc file.  Vim executes the commands in this file when it
     34 starts up.
     35 
     36 If you already have a vimrc file (e.g., when your sysadmin has one setup for
     37 you), you can edit it this way: >
     38 
     39 	:edit $MYVIMRC
     40 
     41 If you don't have a vimrc file yet, see |vimrc| to find out where you can
     42 create a vimrc file.  Also, the ":version" command mentions the name of the
     43 "user vimrc file" Vim looks for.
     44 
     45 For Unix and Macintosh this file is always used and is recommended:
     46 
     47 	~/.vimrc ~
     48 
     49 For MS-Windows you can use one of these:
     50 
     51 	$HOME/_vimrc ~
     52 	$VIM/_vimrc ~
     53 
     54 If you are creating the vimrc file for the first time, it is recommended to
     55 put this line at the top: >
     56 
     57 	source $VIMRUNTIME/defaults.vim
     58 
     59 This initializes Vim for new users (as opposed to traditional Vi users). See
     60 |defaults.vim| for the details.
     61 
     62 The vimrc file can contain all the commands that you type after a colon.  The
     63 simplest ones are for setting options.  For example, if you want Vim to always
     64 start with the 'incsearch' option on, add this line your vimrc file: >
     65 
     66 	set incsearch
     67 
     68 For this new line to take effect you need to exit Vim and start it again.
     69 Later you will learn how to do this without exiting Vim.
     70 
     71 This chapter only explains the most basic items.  For more information on how
     72 to write a Vim script file: |usr_41.txt|.
     73 
     74 ==============================================================================
     75 *05.2*	The example vimrc file explained		*vimrc_example.vim*
     76 
     77 In the first chapter was explained how the example vimrc (included in the
     78 Vim distribution) file can be used to make Vim startup in not-compatible mode
     79 (see |not-compatible|).  The file can be found here:
     80 
     81 	$VIMRUNTIME/vimrc_example.vim ~
     82 
     83 In this section we will explain the various commands used in this file.  This
     84 will give you hints about how to set up your own preferences.  Not everything
     85 will be explained though.  Use the ":help" command to find out more.
     86 
     87 >
     88 	" Get the defaults that most users want.
     89 	source $VIMRUNTIME/defaults.vim
     90 
     91 This loads the "defaults.vim" file in the $VIMRUNTIME directory.  This sets up
     92 Vim for how most users like it.  If you are one of the few that don't, then
     93 comment out this line.  The commands are explained below:
     94 |defaults.vim-explained|
     95 
     96 >
     97 	if has("vms")
     98 	  set nobackup
     99 	else
    100 	  set backup
    101 	  if has('persistent_undo')
    102 	    set undofile
    103 	  endif
    104 	endif
    105 
    106 This tells Vim to keep a backup copy of a file when overwriting it.  But not
    107 on the VMS system, since it keeps old versions of files already.  The backup
    108 file will have the same name as the original file with "~" added.  See |07.4|
    109 
    110 This also sets the 'undofile' option, if available.  This will store the
    111 multi-level undo information in a file.  The result is that when you change a
    112 file, exit Vim, and then edit the file again, you can undo the changes made
    113 previously.  It's a very powerful and useful feature, at the cost of storing a
    114 file.  For more information see |undo-persistence|.
    115 
    116 The "if" command is very useful to set options
    117 only when some condition is met.  More about that in |usr_41.txt|.
    118 
    119 >
    120 	if &t_Co > 2 || has("gui_running")
    121 	  set hlsearch
    122 	endif
    123 
    124 This switches on the 'hlsearch' option, telling Vim to highlight matches with
    125 the last used search pattern.
    126 
    127 >
    128 	augroup vimrcEx
    129 	  au!
    130 	  autocmd FileType text setlocal textwidth=78
    131 	augroup END
    132 
    133 This makes Vim break text to avoid lines getting longer than 78 characters.
    134 But only for files that have been detected to be plain text.  There are
    135 actually two parts here.  "autocmd FileType text" is an autocommand.  This
    136 defines that when the file type is set to "text" the following command is
    137 automatically executed.  "setlocal textwidth=78" sets the 'textwidth' option
    138 to 78, but only locally in one file.
    139 
    140 The wrapper with "augroup vimrcEx" and "augroup END" makes it possible to
    141 delete the autocommand with the "au!" command.  See |:augroup|.
    142 
    143 >
    144 	if has('syntax') && has('eval')
    145 	  packadd! matchit
    146 	endif
    147 
    148 This loads the "matchit" plugin if the required features are available.
    149 It makes the |%| command more powerful.  This is explained at
    150 |matchit-install|.
    151 
    152 
    153 ==============================================================================
    154 *05.3*	The defaults.vim file explained		*defaults.vim-explained*
    155 
    156 The |defaults.vim| file is loaded when the user has no vimrc file.  When you
    157 create a new vimrc file, add this line near the top to keep using it: >
    158 
    159 	source $VIMRUNTIME/defaults.vim
    160 
    161 Or use the vimrc_example.vim file, as explained above.
    162 
    163 The following explains what defaults.vim is doing.
    164 
    165 >
    166 	if exists('skip_defaults_vim')
    167 	  finish
    168 	endif
    169 
    170 Loading defaults.vim can be disabled with this command: >
    171 	let skip_defaults_vim = 1
    172 This has to be done in the system vimrc file.  See |system-vimrc|.  If you
    173 have a user vimrc this is not needed, since defaults.vim will not be loaded
    174 automatically.
    175 
    176 >
    177 	set nocompatible
    178 
    179 As mentioned in the first chapter, these manuals explain Vim working in an
    180 improved way, thus not completely Vi compatible.  Setting the 'compatible'
    181 option off, thus 'nocompatible' takes care of this.
    182 
    183 >
    184 	set backspace=indent,eol,start
    185 
    186 This specifies where in Insert mode the <BS> is allowed to delete the
    187 character in front of the cursor.  The three items, separated by commas, tell
    188 Vim to delete the white space at the start of the line, a line break and the
    189 character before where Insert mode started.  See 'backspace'.
    190 
    191 >
    192 	set history=200
    193 
    194 Keep 200 commands and 200 search patterns in the history.  Use another number
    195 if you want to remember fewer or more lines.  See 'history'.
    196 
    197 >
    198 	set ruler
    199 
    200 Always display the current cursor position in the lower right corner of the
    201 Vim window.  See 'ruler'.
    202 
    203 >
    204 	set showcmd
    205 
    206 Display an incomplete command in the lower right corner of the Vim window,
    207 left of the ruler.  For example, when you type "2f", Vim is waiting for you to
    208 type the character to find and "2f" is displayed.  When you press "w" next,
    209 the "2fw" command is executed and the displayed "2f" is removed.
    210 
    211 	+-------------------------------------------------+
    212 	|text in the Vim window				  |
    213 	|~						  |
    214 	|~						  |
    215 	|-- VISUAL --			2f     43,8   17% |
    216 	+-------------------------------------------------+
    217 	 ^^^^^^^^^^^		      ^^^^^^^^ ^^^^^^^^^^
    218 	  'showmode'		     'showcmd'	'ruler'
    219 
    220 
    221 >
    222 	set wildmenu
    223 
    224 Display completion matches in a status line.  That is when you type <Tab> and
    225 there is more than one match.  See 'wildmenu'.
    226 
    227 >
    228 	set ttimeout
    229 	set ttimeoutlen=100
    230 
    231 This makes typing Esc take effect more quickly.  Normally Vim waits a second
    232 to see if the Esc is the start of an escape sequence.  If you have a very slow
    233 remote connection, increase the number.  See 'ttimeout'.
    234 
    235 >
    236 	set display=truncate
    237 
    238 Show @@@ in the last line if it is truncated, instead of hiding the whole
    239 line.  See 'display'.
    240 
    241 >
    242 	set incsearch
    243 
    244 Display the match for a search pattern when halfway typing it.  See
    245 'incsearch'.
    246 
    247 >
    248 	set nrformats-=octal
    249 
    250 Do not recognize numbers starting with a zero as octal.  See 'nrformats'.
    251 
    252 >
    253 	map Q gq
    254 
    255 This defines a key mapping.  More about that in the next section.  This
    256 defines the "Q" command to do formatting with the "gq" operator.  This is how
    257 it worked before Vim 5.0.  Otherwise the "Q" command starts Ex mode, but you
    258 will not need it.
    259 
    260 >
    261 	inoremap <C-U> <C-G>u<C-U>
    262 
    263 CTRL-U in insert mode deletes all entered text in the current line.  Use
    264 CTRL-G u to first break undo, so that you can undo CTRL-U after inserting a
    265 line break.  Revert with ":iunmap <C-U>".
    266 
    267 >
    268 	if has('mouse')
    269 	  set mouse=a
    270 	endif
    271 
    272 Enable using the mouse if available.  See 'mouse'.
    273 
    274 >
    275 	vnoremap _g y:exe "grep /" .. escape(@", '\\/') .. "/ *.c *.h"<CR>
    276 
    277 This mapping yanks the visually selected text and searches for it in C files.
    278 You can see that a mapping can be used to do quite complicated things.  Still,
    279 it is just a sequence of commands that are executed like you typed them.
    280 
    281 >
    282 	syntax on
    283 
    284 Enable highlighting files in color.  See |syntax|.
    285 
    286 							*vimrc-filetype*  >
    287 	filetype plugin indent on
    288 
    289 This switches on three very clever mechanisms:
    290 1. Filetype detection.
    291    Whenever you start editing a file, Vim will try to figure out what kind of
    292    file this is.  When you edit "main.c", Vim will see the ".c" extension and
    293    recognize this as a "c" filetype.  When you edit a file that starts with
    294    "#!/bin/sh", Vim will recognize it as a "sh" filetype.
    295    The filetype detection is used for syntax highlighting and the other two
    296    items below.
    297    See |filetypes|.
    298 
    299 2. Using filetype plugin files
    300    Many different filetypes are edited with different options.  For example,
    301    when you edit a "c" file, it's very useful to set the 'cindent' option to
    302    automatically indent the lines.  These commonly useful option settings are
    303    included with Vim in filetype plugins.  You can also add your own, see
    304    |write-filetype-plugin|.
    305 
    306 3. Using indent files
    307    When editing programs, the indent of a line can often be computed
    308    automatically.  Vim comes with these indent rules for a number of
    309    filetypes.  See |:filetype-indent-on| and 'indentexpr'.
    310 
    311 
    312 				*restore-cursor* *last-position-jump*  >vim
    313 
    314     augroup RestoreCursor
    315       autocmd!
    316       autocmd BufReadPost *
    317         \ let line = line("'\"")
    318         \ | if line >= 1 && line <= line("$") && &filetype !~# 'commit'
    319         \      && index(['xxd', 'gitrebase'], &filetype) == -1
    320         \      && !&diff
    321         \ |   execute "normal! g`\""
    322         \ | endif
    323     augroup END
    324 
    325 Another autocommand.  This time it is used after reading any file.  The
    326 complicated stuff after it checks if the '" mark is defined, and jumps to it
    327 if so.  It doesn't do that when:
    328  - editing a commit or rebase message, which are likely a different one than
    329    last time,
    330  - using xxd(1) to filter and edit binary files, which transforms input files
    331    back and forth, causing them to have dual nature, so to speak (see also
    332    |using-xxd|) and
    333  - Vim is in diff mode
    334 
    335 The backslash at the start of a line is used to continue the command from the
    336 previous line.  That avoids a line getting very long.  See |line-continuation|.
    337 This only works in a Vim script file, not when typing commands at the
    338 command line.
    339 
    340 >
    341 	command DiffOrig vert new | set bt=nofile | r ++edit # | 0d_
    342 		  \ | diffthis | wincmd p | diffthis
    343 
    344 This adds the ":DiffOrig" command.  Use this in a modified buffer to see the
    345 differences with the file it was loaded from.  See |diff| and |:DiffOrig|.
    346 
    347 >
    348 	set nolangremap
    349 
    350 Prevent that the langmap option applies to characters that result from a
    351 mapping.  If set (default), this may break plugins (but it's backward
    352 compatible).  See 'langremap'.
    353 
    354 ==============================================================================
    355 *05.4*	Simple mappings
    356 
    357 A mapping enables you to bind a set of Vim commands to a single key.  Suppose,
    358 for example, that you need to surround certain words with curly braces.  In
    359 other words, you need to change a word such as "amount" into "{amount}".  With
    360 the :map command, you can tell Vim that the F5 key does this job.  The command
    361 is as follows: >
    362 
    363 	:map <F5> i{<Esc>ea}<Esc>
    364 <
    365 	Note:
    366 	When entering this command, you must enter <F5> by typing four
    367 	characters.  Similarly, <Esc> is not entered by pressing the <Esc>
    368 	key, but by typing five characters.  Watch out for this difference
    369 	when reading the manual!
    370 
    371 Let's break this down:
    372     <F5>	The F5 function key.  This is the trigger key that causes the
    373 		command to be executed as the key is pressed.
    374 
    375     i{<Esc>	Insert the { character.  The <Esc> key ends Insert mode.
    376 
    377     e		Move to the end of the word.
    378 
    379     a}<Esc>	Append the } to the word.
    380 
    381 After you execute the ":map" command, all you have to do to put {} around a
    382 word is to put the cursor on the first character and press F5.
    383 
    384 In this example, the trigger is a single key; it can be any string.  But when
    385 you use an existing Vim command, that command will no longer be available.
    386 You better avoid that.
    387    One key that can be used with mappings is the backslash.  Since you
    388 probably want to define more than one mapping, add another character.  You
    389 could map "\p" to add parentheses around a word, and "\c" to add curly braces,
    390 for example: >
    391 
    392 	:map \p i(<Esc>ea)<Esc>
    393 	:map \c i{<Esc>ea}<Esc>
    394 
    395 You need to type the \ and the p quickly after another, so that Vim knows they
    396 belong together.
    397 
    398 The ":map" command (with no arguments) lists your current mappings.  At
    399 least the ones for Normal mode.  More about mappings in section |40.1|.
    400 
    401 ==============================================================================
    402 *05.5*	Adding a package  *add-package*
    403 
    404 A package is a set of files that you can add to Vim.  There are two kinds of
    405 packages: optional and automatically loaded on startup.
    406 
    407 The Vim distribution comes with a few packages that you can optionally use.
    408 
    409 In your |vimrc| use `:packadd!`: it only adds the package to 'runtimepath'
    410 and leaves the loading to the usual startup.  Without the "!" the package is
    411 loaded directly, which is what you want when trying one out.  See |:packadd|.
    412 
    413 ------------------------------------------------------------------------------
    414 Adding the matchit package		*matchit-install* *package-matchit*
    415 ------------------------------------------------------------------------------
    416 For example, the matchit package  This plugin makes the "%" command jump to
    417 matching HTML tags, if/else/endif in Vim scripts, etc.  Very useful, although
    418 it's not backwards compatible (that's why it is not enabled by default).
    419 
    420 To start using this plugin, add one line to your vimrc file: >
    421 	packadd! matchit
    422 
    423 That's all!  After restarting Vim you can find help about this plugin: >
    424 	:help matchit
    425 
    426 This works, because `:packadd!` added the package directory in 'runtimepath',
    427 so that the help file can be found.
    428 
    429 You can find packages on the Internet in various places.  It usually comes as
    430 an archive or as a repository.  For an archive you can follow these steps:
    431 	1. create the package directory: >
    432 		mkdir -p ~/.vim/pack/fancy
    433 <	   "fancy" can be any name of your liking.  Use one that describes the
    434 	   package.
    435 	2. unpack the archive in that directory.  This assumes the top
    436 	   directory in the archive is "start": >
    437 		cd ~/.vim/pack/fancy
    438 		unzip /tmp/fancy.zip
    439 <	   If the archive layout is different make sure that you end up with a
    440 	   path like this:
    441 		~/.vim/pack/fancy/start/fancytext/plugin/fancy.vim ~
    442 	   Here "fancytext" is the name of the package, it can be anything
    443 	   else.
    444 
    445 ------------------------------------------------------------------------------
    446 Adding the editorconfig package *editorconfig-install* *package-editorconfig*
    447 ------------------------------------------------------------------------------
    448 
    449 To start using this plugin, add one line to your vimrc file: >
    450 	packadd! editorconfig
    451 
    452 After restarting Vim the plugin is active and you can read about it at: >
    453 	:h editorconfig.txt
    454 
    455 
    456 ------------------------------------------------------------------------------
    457 Adding the comment package		*comment-install* *package-comment*
    458 ------------------------------------------------------------------------------
    459 
    460 To start using this plugin, add one line to your vimrc file: >
    461 	packadd! comment
    462 <
    463 This way you can use the plugin with the default key bindings `gc` and similar
    464 for commenting (which is a well-established mapping in the Vim community).
    465 
    466 After restarting Vim the plugin is active and you can read about it at: >
    467 	:h comment.txt
    468 
    469 
    470 ------------------------------------------------------------------------------
    471 Adding the nohlsearch package	*nohlsearch-install* *package-nohlsearch*
    472 ------------------------------------------------------------------------------
    473 
    474 To start using this plugin, add one line to your vimrc file: >
    475 	packadd! nohlsearch
    476 <
    477 Automatically execute |:nohlsearch| after 'updatetime' or getting into
    478 |Insert| mode.
    479 Thus assuming default updatetime, hlsearch would be suspended/turned off after
    480 4 seconds of idle time.
    481 
    482 To disable the effect of the plugin after it has been loaded: >
    483 	au! nohlsearch
    484 <
    485 
    486 ------------------------------------------------------------------------------
    487 Adding the highlight-yank package	*hlyank-install* *package-hlyank*
    488 ------------------------------------------------------------------------------
    489 
    490 To start using this plugin, add one line to your vimrc file: >
    491 	packadd! hlyank
    492 <
    493 This package briefly highlights the affected region of the last |yank|
    494 command.  See |52.6| for a simplified implementation using the
    495 |getregionpos()| function.
    496 
    497 The plugin understands the following configuration variables (the settings
    498 show the default values).
    499 
    500 To specify a different highlighting group, use: >
    501 	:let g:hlyank_hlgroup = 'IncSearch'
    502 <
    503 To use a different highlighting duration, use: >
    504 	:let g:hlyank_duration = 300
    505 The unit is milliseconds, and the upper limit is 3000 ms.  If you set a value
    506 higher than this, the highlighting duration will be 3000 ms.
    507 
    508 To highlight in visual mode, use: >
    509 	:let g:hlyank_invisual = v:true
    510 
    511 To disable the effect of the plugin after it has been loaded: >
    512 	au! hlyank
    513 
    514 Additionally, the plugin can also highlight regions that are put using the
    515 |TextPutPost| autocommand.  This is by default disabled and can be enabled
    516 using: >
    517 	:let g:hlput_enable = v:true
    518 <
    519 The following configuration variables can be used are "g:hlput_hlgroup" and
    520 "g:hlput_duration", which have the same effect as their yank counterparts: >
    521 	:let g:hlput_hlgroup = 'IncSearch'
    522 	:let g:hlput_duration = 300
    523 
    524 ------------------------------------------------------------------------------
    525 Adding the osc52 package		*osc52-install* *package-osc52*
    526 ------------------------------------------------------------------------------
    527 
    528 To start using this plugin, add one line to your vimrc file: >
    529 	packadd! osc52
    530 <
    531 The osc52.vim package provides support for the OSC 52 terminal command, which
    532 allows an application to access the clipboard by communicating directly with
    533 your terminal.
    534 
    535 Once the package is loaded, read about it at: >
    536 	:h osc52.txt
    537 
    538 More information about packages can be found here: |packages|.
    539 
    540 ==============================================================================
    541 *05.6*	Adding a plugin					*add-plugin* *plugin*
    542 
    543 Vim's functionality can be extended by adding plugins.  A plugin is nothing
    544 more than a Vim script file that is loaded automatically when Vim starts.  You
    545 can add a plugin very easily by dropping it in your plugin directory.
    546 {not available when Vim was compiled without the |+eval| feature}
    547 
    548 There are two types of plugins:
    549 
    550     global plugin: Used for all kinds of files
    551   filetype plugin: Only used for a specific type of file
    552 
    553 The global plugins will be discussed first, then the filetype ones
    554 |add-filetype-plugin|.
    555 
    556 
    557 GLOBAL PLUGINS				*standard-plugin* *distributed-plugins*
    558 
    559 When you start Vim, it will automatically load a number of global plugins.
    560 You don't have to do anything for this.  They add functionality that most
    561 people will want to use, but which was implemented as a Vim script instead of
    562 being compiled into Vim.  You can find them listed in the help index
    563 |standard-plugin-list|.
    564 
    565 For locally installed plugins and packages (which come with a separated help
    566 file) a similar list can be found in the help section |local-additions|.
    567 
    568 Also see |load-plugins|.
    569 
    570 							*add-global-plugin*
    571 You can add a global plugin to add functionality that will always be present
    572 when you use Vim.  There are only two steps for adding a global plugin:
    573 1. Get a copy of the plugin.
    574 2. Drop it in the right directory.
    575 
    576 
    577 GETTING A GLOBAL PLUGIN
    578 
    579 Where can you find plugins?
    580 - Some are always loaded, you can see them in the directory
    581   $VIMRUNTIME/plugin.
    582 - Some come with Vim.  You can find them in the directory $VIMRUNTIME/macros
    583   and its sub-directories and under $VIM/vimfiles/pack/dist/opt/.
    584 - Download from the net.  There is a large collection on http://www.vim.org.
    585 - They are sometimes posted in a Vim |maillist|.
    586 - You could write one yourself, see |write-plugin|.
    587 
    588 Some plugins come as a vimball archive, see |vimball|.
    589 Some plugins can be updated automatically, see |getscript|.
    590 
    591 
    592 USING A GLOBAL PLUGIN
    593 
    594 First read the text in the plugin itself to check for any special conditions.
    595 Then copy the file to your plugin directory:
    596 
    597 	system		plugin directory ~
    598 	Unix		~/.vim/plugin/
    599 	PC		$HOME/vimfiles/plugin or $VIM/vimfiles/plugin
    600 	Amiga		s:vimfiles/plugin
    601 	Macintosh	$VIM:vimfiles:plugin
    602 	Mac OS X	~/.vim/plugin/
    603 
    604 Example for Unix (assuming you didn't have a plugin directory yet): >
    605 
    606 	mkdir ~/.vim
    607 	mkdir ~/.vim/plugin
    608 	cp /tmp/yourplugin.vim ~/.vim/plugin
    609 
    610 That's all!  Now you can use the commands defined in this plugin.
    611 
    612 Instead of putting plugins directly into the plugin/ directory, you may
    613 better organize them by putting them into subdirectories under plugin/.
    614 As an example, consider using "~/.vim/plugin/perl/*.vim" for all your Perl
    615 plugins.
    616 
    617 
    618 FILETYPE PLUGINS			*add-filetype-plugin* *ftplugins*
    619 
    620 The Vim distribution comes with a set of plugins for different filetypes that
    621 you can start using with this command: >
    622 
    623 	:filetype plugin on
    624 
    625 That's all!  See |vimrc-filetype|.
    626 
    627 If you are missing a plugin for a filetype you are using, or you found a
    628 better one, you can add it.  There are two steps for adding a filetype plugin:
    629 1. Get a copy of the plugin.
    630 2. Drop it in the right directory.
    631 
    632 
    633 GETTING A FILETYPE PLUGIN
    634 
    635 You can find them in the same places as the global plugins.  Watch out if the
    636 type of file is mentioned, then you know if the plugin is a global or a
    637 filetype one.  The scripts in $VIMRUNTIME/macros are global ones, the filetype
    638 plugins are in $VIMRUNTIME/ftplugin.
    639 
    640 
    641 USING A FILETYPE PLUGIN					*ftplugin-name*
    642 
    643 You can add a filetype plugin by dropping it in the right directory.  The
    644 name of this directory is in the same directory mentioned above for global
    645 plugins, but the last part is "ftplugin".  Suppose you have found a plugin for
    646 the "stuff" filetype, and you are on Unix.  Then you can move this file to the
    647 ftplugin directory: >
    648 
    649 	mv thefile ~/.vim/ftplugin/stuff.vim
    650 
    651 If that file already exists you already have a plugin for "stuff".  You might
    652 want to check if the existing plugin doesn't conflict with the one you are
    653 adding.  If it's OK, you can give the new one another name: >
    654 
    655 	mv thefile ~/.vim/ftplugin/stuff_too.vim
    656 
    657 The underscore is used to separate the name of the filetype from the rest,
    658 which can be anything.  If you use "otherstuff.vim" it wouldn't work, it would
    659 be loaded for the "otherstuff" filetype.
    660 
    661 On MS-DOS like filesystems you cannot use long filenames.  You would run into
    662 trouble if you add a second plugin and the filetype has more than six
    663 characters.  You can use an extra directory to get around this: >
    664 
    665 	mkdir $VIM/vimfiles/ftplugin/fortran
    666 	copy thefile $VIM/vimfiles/ftplugin/fortran/too.vim
    667 
    668 The generic names for the filetype plugins are: >
    669 
    670 	ftplugin/<filetype>.vim
    671 	ftplugin/<filetype>_<name>.vim
    672 	ftplugin/<filetype>/<name>.vim
    673 
    674 Here "<name>" can be any name that you prefer.
    675 Examples for the "stuff" filetype on Unix: >
    676 
    677 	~/.vim/ftplugin/stuff.vim
    678 	~/.vim/ftplugin/stuff_def.vim
    679 	~/.vim/ftplugin/stuff/header.vim
    680 
    681 The <filetype> part is the name of the filetype the plugin is to be used for.
    682 Only files of this filetype will use the settings from the plugin.  The <name>
    683 part of the plugin file doesn't matter, you can use it to have several plugins
    684 for the same filetype.  Note that it must end in ".vim".
    685 
    686 
    687 Further reading:
    688 |filetype-plugins|	Documentation for the filetype plugins and information
    689 			about how to avoid that mappings cause problems.
    690 |load-plugins|		When the global plugins are loaded during startup.
    691 |ftplugin-overrule|	Overruling the settings from a global plugin.
    692 |write-plugin|		How to write a plugin script.
    693 |plugin-details|	For more information about using plugins or when your
    694 			plugin doesn't work.
    695 |new-filetype|		How to detect a new file type.
    696 
    697 ==============================================================================
    698 *05.7*	Adding a help file				*add-local-help*
    699 
    700 If you are lucky, the plugin you installed also comes with a help file.  We
    701 will explain how to install the help file, so that you can easily find help
    702 for your new plugin.
    703    Let us use the "doit.vim" plugin as an example.  This plugin comes with
    704 documentation: "doit.txt".  Let's first copy the plugin to the right
    705 directory.  This time we will do it from inside Vim.  (You may skip some of
    706 the "mkdir" commands if you already have the directory.) >
    707 
    708 	:!mkdir ~/.vim
    709 	:!mkdir ~/.vim/plugin
    710 	:!cp /tmp/doit.vim ~/.vim/plugin
    711 
    712 The "cp" command is for Unix, on MS-Windows you can use "copy".
    713 
    714 Now create a "doc" directory in one of the directories in 'runtimepath'. >
    715 
    716 	:!mkdir ~/.vim/doc
    717 
    718 Copy the help file to the "doc" directory. >
    719 
    720 	:!cp /tmp/doit.txt ~/.vim/doc
    721 
    722 Now comes the trick, which allows you to jump to the subjects in the new help
    723 file: Generate the local tags file with the |:helptags| command. >
    724 
    725 	:helptags ~/.vim/doc
    726 
    727 Now you can use the >
    728 
    729 	:help doit
    730 
    731 command to find help for "doit" in the help file you just added.  You can see
    732 an entry for the local help file when you do: >
    733 
    734 	:help local-additions
    735 
    736 The title lines from the local help files are automagically added to this
    737 section.  There you can see which local help files have been added and jump to
    738 them through the tag.
    739 
    740 For writing a local help file, see |write-local-help|.
    741 
    742 ==============================================================================
    743 *05.8*	The option window
    744 
    745 If you are looking for an option that does what you want, you can search in
    746 the help files here: |options|.  Another way is by using this command: >
    747 
    748 	:options
    749 
    750 This opens a new window, with a list of options with a one-line explanation.
    751 The options are grouped by subject.  Move the cursor to a subject and press
    752 <Enter> to jump there.  Press <Enter> again to jump back.  Or use CTRL-O.
    753 
    754 You can change the value of an option.  For example, move to the "displaying
    755 text" subject.  Then move the cursor down to this line:
    756 
    757 	set wrap	nowrap ~
    758 
    759 When you hit <Enter>, the line will change to:
    760 
    761 	set nowrap	wrap ~
    762 
    763 The option has now been switched off.
    764 
    765 Just above this line is a short description of the 'wrap' option.  Move the
    766 cursor one line up to place it in this line.  Now hit <Enter> and you jump to
    767 the full help on the 'wrap' option.
    768 
    769 For options that take a number or string argument you can edit the value.
    770 Then press <Enter> to apply the new value.  For example, move the cursor a few
    771 lines up to this line:
    772 
    773 	set so=0 ~
    774 
    775 Position the cursor on the zero with "$".  Change it into a five with "r5".
    776 Then press <Enter> to apply the new value.  When you now move the cursor
    777 around you will notice that the text starts scrolling before you reach the
    778 border.  This is what the 'scrolloff' option does, it specifies an offset
    779 from the window border where scrolling starts.
    780 
    781 ==============================================================================
    782 *05.9*	Often used options
    783 
    784 There are an awful lot of options.  Most of them you will hardly ever use.
    785 Some of the more useful ones will be mentioned here.  Don't forget you can
    786 find more help on these options with the ":help" command, with single quotes
    787 before and after the option name.  For example: >
    788 
    789 	:help 'wrap'
    790 
    791 In case you have messed up an option value, you can set it back to the
    792 default by putting an ampersand (&) after the option name.  Example: >
    793 
    794 	:set iskeyword&
    795 
    796 
    797 NOT WRAPPING LINES
    798 
    799 Vim normally wraps long lines, so that you can see all of the text.  Sometimes
    800 it's better to let the text continue right of the window.  Then you need to
    801 scroll the text left-right to see all of a long line.  Switch wrapping off
    802 with this command: >
    803 
    804 	:set nowrap
    805 
    806 Vim will automatically scroll the text when you move to text that is not
    807 displayed.  To see a context of ten characters, do this: >
    808 
    809 	:set sidescroll=10
    810 
    811 This doesn't change the text in the file, only the way it is displayed.
    812 
    813 
    814 WRAPPING MOVEMENT COMMANDS
    815 
    816 Most commands for moving around will stop moving at the start and end of a
    817 line.  You can change that with the 'whichwrap' option.  This sets it to the
    818 default value: >
    819 
    820 	:set whichwrap=b,s
    821 
    822 This allows the <BS> key, when used in the first position of a line, to move
    823 the cursor to the end of the previous line.  And the <Space> key moves from
    824 the end of a line to the start of the next one.
    825 
    826 To allow the cursor keys <Left> and <Right> to also wrap, use this command: >
    827 
    828 	:set whichwrap=b,s,<,>
    829 
    830 This is still only for Normal mode.  To let <Left> and <Right> do this in
    831 Insert mode as well: >
    832 
    833 	:set whichwrap=b,s,<,>,[,]
    834 
    835 There are a few other flags that can be added, see 'whichwrap'.
    836 
    837 
    838 VIEWING TABS
    839 
    840 When there are tabs in a file, you cannot see where they are.  To make them
    841 visible: >
    842 
    843 	:set list
    844 
    845 Now every tab is displayed as ^I.  And a $ is displayed at the end of each
    846 line, so that you can spot trailing spaces that would otherwise go unnoticed.
    847    A disadvantage is that this looks ugly when there are many Tabs in a file.
    848 If you have a color terminal, or are using the GUI, Vim can show the spaces
    849 and tabs as highlighted characters.  Use the 'listchars' option: >
    850 
    851 	:set listchars=tab:>-,trail:-
    852 
    853 Now every tab will be displayed as ">---" (with more or less "-") and trailing
    854 white space as "-".  Looks a lot better, doesn't it?
    855 
    856 
    857 KEYWORDS
    858 
    859 The 'iskeyword' option specifies which characters can appear in a word: >
    860 
    861 	:set iskeyword
    862 <	  iskeyword=@,48-57,_,192-255 ~
    863 
    864 The "@" stands for all alphabetic letters.  "48-57" stands for ASCII
    865 characters 48 to 57, which are the numbers 0 to 9.  "192-255" are the
    866 printable latin characters.
    867    Sometimes you will want to include a dash in keywords, so that commands
    868 like "w" consider "upper-case" to be one word.  You can do it like this: >
    869 
    870 	:set iskeyword+=-
    871 	:set iskeyword
    872 <	  iskeyword=@,48-57,_,192-255,- ~
    873 
    874 If you look at the new value, you will see that Vim has added a comma for you.
    875    To remove a character use "-=".  For example, to remove the underscore: >
    876 
    877 	:set iskeyword-=_
    878 	:set iskeyword
    879 <	  iskeyword=@,48-57,192-255,- ~
    880 
    881 This time a comma is automatically deleted.
    882 
    883 
    884 ROOM FOR MESSAGES
    885 
    886 When Vim starts there is one line at the bottom that is used for messages.
    887 When a message is long, it is either truncated, thus you can only see part of
    888 it, or the text scrolls and you have to press <Enter> to continue.
    889    You can set the 'cmdheight' option to the number of lines used for
    890 messages.  Example: >
    891 
    892 	:set cmdheight=3
    893 
    894 This does mean there is less room to edit text, thus it's a compromise.
    895 
    896 ==============================================================================
    897 
    898 Next chapter: |usr_06.txt|  Using syntax highlighting
    899 
    900 Copyright: see |manual-copyright|  vim:tw=78:ts=8:noet:ft=help:norl: