*version6.txt* For Vim version 6.0z. Last change: 2001 Mar 24 VIM REFERENCE MANUAL by Bram Moolenaar Welcome to Vim Version 6.0! Vim 2001, a folding space odyssey Where do you want to fold today? This document lists the differences between Vim 5.x and Vim 6.0. See |vi_diff.txt| for an overview of differences between Vi and Vim 5.0. See |version4.txt| for differences between Vim 3.0 and Vim 4.0. See |version5.txt| for differences between Vim 4.0 and Vim 5.0. INCOMPATIBLE CHANGES |incompatible-6| Cursor position in Visual mode |curpos-visual| substitute command |substitute-CR| 'include' option local |include-local| global option values used |new-global-values| 'fileencoding' changed |fileencoding-changed| Digraphs changed |digraphs-changed| Filetype detection changed |filetypedetect-changed| Unlisted buffers introduced |new-unlisted-buffers| CTRL-U in Command-line mode |CTRL-U-changed| Ctags gone |ctags-gone| Documentation |documentation-6| Small incompatibilities |incomp-small-6| NEW FEATURES Folding |new-folding| Vertically split windows |new-vertsplit| Extended search patterns |new-searchpat| Flexible indenting |new-indent-flex| UTF-8 support |new-utf-8| Multi-language support |new-multi-lang| Plugin support |new-plugins| Filetype plugins |new-filetype-plugins| Window for command-line editing |new-cmdwin| Debugging mode |new-debug-mode| Cursor in virtual position |new-virtedit| Debugger interface |new-debug-itf| Buffer types |new-buftype| Ports |ports-6| Quickfix extended |quickfix-6| Operator modifiers |new-operator-mod| Search Path |new-search-path| Editing files over a network |new-network-files| Writing files |new-file-writing| Argument list |new-argument-list| Restore a View |new-View| Various new items |new-items-6| IMPROVEMENTS |improvements-6| COMPILE TIME CHANGES |compile-changes-6| BUG FIXES |bug-fixes-6| ============================================================================== INCOMPATIBLE CHANGES *incompatible-6* These changes are incompatible with previous releases. Check this list if you run into a problem when upgrading from Vim 5.x to 6.0 Cursor position in Visual mode *curpos-visual* ------------------------------ When going from one window to another window on the same buffer while in Visual mode, the cursor position of the other window is adjusted to keep the same Visual area. This can be used to set the start of the Visual area in one window and the end in another. substitute command *substitute-CR* ------------------ The substitute string has been made Vi compatible. Previously a CTRL-V had a special meaning and could be used to prevent a to insert a line break. This made it impossible to insert a CTRL-V before a line break. Now a backslash is used to prevent a to cause a line break. Since the number of backslashes is halved, it is still possible to insert a line break at the end of the line. This now works just like Vi, but it's not compatible with Vim versions before 6.0. When a ":s" command doesn't make any substitutions, it doesn't set the '[ and '] marks. 'include' option local *include-local* ---------------------- The 'include' option is now local to the buffer. Each language may require another 'include' option value. This only matters if you set the 'include' option and expect it to have the new value in other buffers too. Global option values used *new-global-values* ------------------------- There are now global values for options which are local to a buffer or window. Previously the local options were copied from one buffer to another. When editing another file this could cause options set in a modeline to be used for the wrong file. Now the global values are used when entering a buffer that has not been used before. Also, when editing another buffer in a window, the local window options are reset to their global values. The ":set" command sets both the local and global values, this is still compatible. But a modeline only sets the local value, this is not backwards compatible. ":let &opt = val" now sets the local and global values, like ":set". New commands have been added to set the global or local value: :let &opt = val like ":set" :let &g:opt = val like ":setglobal" :let &l:opt = val like ":setlocal" 'fileencoding' changed *fileencoding-changed* ---------------------- 'fileencoding' was used in Vim 5.x to set the encoding used inside all of Vim. This was a bit strange, because it was local to a buffer and worked for all buffers. It could never be different between buffers, because it changed the way text in all buffers was interpreted. It is now used for the encoding of the file related to the buffer. If you still set 'fileencoding' it is likely to be overwritten by the detected encoding from 'fileencodings'. The FileEncoding autocommand now does the same as the new EncodingChanged event. Digraphs changed *digraphs-changed* ---------------- The default digraphs now correspond to RFC1345. This is different from what was used in Vim 5.x. |digraphs| Filetype detection changed *filetypedetect-changed* -------------------------- The filetype detection previously was using the "filetype" autocommand group. This caused confusion with the FileType event name. The group is now called "filetypedetect". It still works, but if the "filetype" group is used the autocommands will not be removed by ":filetype off". The support for 'runtimepath' has made the "myfiletypefile" and "mysyntaxfile" mechanism obsolete. They are still used for backwards compatibility. The connection between the FileType event and setting the 'syntax' option was previously in the "syntax" autocommand group. That caused confusion with the Syntax event name. The group is now called "syntaxset". The distributed syntax files no longer contain "syntax clear". That makes it possible to include one in the other without tricks. Unlisted buffers introduced *new-unlisted-buffers* --------------------------- Introduction of unlisted buffers: Make a difference between buffers which don't appear in the buffer list and buffers which are really not in the buffer list. Commands like ":ls", ":bnext", ":blast" and the Buffers menu will skip buffers not in the buffer list. |unlisted-buffer| The 'buflisted' option can be used to make a buffer appear in the buffer list or not. Several commands that previously added a buffer to the buffer list now create an unlisted buffer. This means that a ":bnext" or ":ball" will not find these files until they have actually been edited. For example, buffers used for the alternative file by ":w file" and ":r file". Other commands previously completely deleted a buffer and now only remove the buffer from the buffer list. Commands relying on a buffer not to be present might fail. For example A ":bdelete" command in an autocommand that relied on something following to fail (was used in the automatic tests). |:bwipeout| can be used for the old meaning of ":bdelete". The BufDelete autocommand event is now triggered when a buffer is removed from the buffer list. The BufCreate event is only triggered when a buffer is created that is added to the buffer list, or when an existing buffer is added to the buffer list. BufAdd is a new name for BufCreate. The new BufNew event is for creating any buffer and BufWipeout for really deleting a buffer. When doing Insert mode completion only buffers in the buffer list are scanned. Added the 'U' flag to 'complete' to do completion from unlisted buffers. Unlisted buffers are not stored in a viminfo file. CTRL-U in Command-line mode *CTRL-U-changed* --------------------------- CTRL-U in the command line cleared the whole line. Most shells only delete the characters before the cursor. Made it like that. (Steve Wall) You can get the old behavior with CTRL-E CTRL-U: > :cnoremap Ctags gone *ctags-gone* ---------- Ctags is no longer part of the Vim distribution. It's now a grown-up program by itself, it deserves to be distributed separately. However, the binary archives do include the ctags program, since it's small and useful. Ctags can be found here: http://darren.hiebert.com/ctags/index.html. Documentation *documentation-6* ------------- The documentation has been reorganized, an item may not be where you found it in Vim 5.x. - Split into a reference manual and a user manual. - Put the quick reference in a separate file (so that it can be printed). The examples in the documentation were previously marked with a ">" in the first column. This made it difficult to copy/paste them. There is now a single ">" before the example and it ends at a "<" or a non-blank in the first column. This also looks better without highlighting. When syntax highlighting is not enabled, the characters in the help file which mark examples ('>' and '<') and header lines ('~') are replaced with a space. When closing the help window restore the layout from before opening it, if the window layout didn't change since then. When opening the help window, put it at the top of the Vim window if the current window is less than 80 characters and not full width. 'helpfile' is no longer used to find the help tags file. This allows a user to add its own help files (e.g., for plugins). When doing ":help tag", don't open help.txt first, jump directly to the help tag. It's faster and avoids an extra message. Small incompatibilities *incomp-small-6* ----------------------- 'backupdir', 'cdpath', 'directory', 'equalprg', 'errorfile', 'formatprg', 'grepprg', 'helpfile', 'makeef', 'makeprg', 'keywordprg', 'cscopeprg', 'viminfo' and 'runtimepath' can no longer be set from a modeline, for better security. Removed '_' from the 'breakat' default: It's commonly used in keywords. The default for 'mousehide' is on, because this works well form most people. The Amiga binary is now always compiled with "big" features. The "big" binary archive no longer exists. The items "[RO]", "[+]", "[help]", "[Preview]" and "[filetype]" in 'statusline' no longer have a leading space. Non-Unix systems: When expanding wildcards for the Vim arguments, don't use 'suffixes'. It now works as if the shell had expanded the arguments. The 'lisp', 'smartindent' and 'cindent' options are not switched off when 'paste' is set. The auto-indenting is disabled when 'paste' is set, but manual indenting with "=" still works. When formatting with "=" uses 'cindent' or 'indentexpr' indenting, and there is no change in indent, this is not counted as a change ('modified' isn't set and there is nothing to undo). Report 'modified' as changed when 'fileencoding' or 'fileformat' was set. Thus it reflects the possibility to abandon the buffer without losing changes. The "Save As" menu entry now edits the saved file. Most people expect it to work like this. A buffer for a directory is no longer added to the Buffers menu. Renamed to , since that's what it's called on most keyboards. Thus it's now the hit-enter prompt instead of the hit-return prompt. When setting 'syntax' to a name for which there is no syntax file, the syntax highlighting is cleared. Previously the existing highlighting was kept. The default for the 'viminfo' option is now '50,"50,h when 'compatible' isn't set. Most people will want to use it, including beginners, but it required setting the option, which isn't that easy. After using ":colder" the newer error lists are overwritten. This makes it possible to use ":grep" to browse in a tree-like way. Must use ":cnewer 99" to get the old behavior. The patterns in 'errorformat' would sometimes ignore case (MS-Windows) and sometimes not (Unix). Now case is always ignored. Add "\C" to the pattern to match case. The 16 bit MS-DOS version is now compiled without the +listcmds feature (buffer list manipulation commands). They are not often needed and this executable needs to be smaller. 'sessionoptions' now includes "curdir" by default. This means that restoring a session will result in the current directory being restored, instead of going to the directory where the session file is located. A session deleted all buffers, deleting all marks. Now keep the buffer list, it shouldn't hurt for some existing buffers to remain present. When the argument list is empty ":argdel *" caused an error message. No longer put the search pattern from a tag jump in the history. Use "SpecialKey" highlighting for unprintable characters instead of "NonText". The idea is that unprintable text or any text that's displayed differently from the characters in the file is using "SpecialKey", and "NonText" is used for text that doesn't really exist in the file. Motif and Athena now use the system default colors for the menu and scrollbar. Used to be grey. It's still possible to set the colors with ":highlight" commands and resources. ============================================================================== NEW FEATURES Folding *new-folding* ------- Vim can now display a buffer with text folded. This allows overviewing the structure of a file quickly. It is also possible to move folded text, for example to move a function to another position. There is a whole bunch of new commands and options related to folding. See |folding|. Vertically split windows *new-vertsplit* ------------------------ Windows can also be split vertically. This makes it possible to have windows side by side. One nice use for this is to compare two similar files. The 'scrollbind' option can be used to synchronize scrolling. A vertical split can be created with the commands: :vsplit or CTRL-W v or CTRL-W CTRL-V |:vsplit| :vnew |:vnew| :vertical {cmd} |:vertical| The last one is a modifier, which has a meaning for any command that splits a window. For example: > :vertical stag main Will vertically split the window and jump to the tag "main" in the new window. Moving from window to window horizontally can be done with the |CTRL-W_h| and |CTRL-W_l| commands. The |CTRL-W_k| and |CTRL-W_j| commands have been changed to jump to the window above or below the cursor position. The vertical and horizontal splits can be mixed as you like. Resizing windows is easy when using the mouse, just position the pointer on a status line or vertical separator and drag it. In the GUI a special mouse pointer shape indicates where you can drag a status or separator line. To resize vertically split windows use the |CTRL-W_<| and |CTRL-W_>| commands. To make a window the maximum width use the CTRL-W | command |CTRL-W_bar|. To force a new window to use the full width or height of the Vim window, these two modifiers are available: :topleft {cmd} New window appears at the top with full width or at the left with full height. :botright {cmd} New window appears at the bottom with full width or at the right with full height. This can be combined with ":vertical" to force a vertical split: > :vert bot dsplit DEBUG This will open a window at the far right, occupying the full height of the Vim window, with the cursor on the first definition of "DEBUG". The help window is always opened at the top, like ":topleft" was used. A few options can be used to set the preferences for vertically split windows. They work similar to their existing horizontal equavalents: horizontal vertical ~ 'splitbelow' 'splitright' 'winheight' 'winwidth' 'winminheight' 'winminwidth' It's possible to set 'winminwidth' to zero, so that temporarliy unused windows hardly take up space without closing them. The new 'eadirection' option tells where 'equalalways' applies: :set eadirection=both both directions :set eadirection=ver equalize window heights :set eadirection=hor equalize windows widths This can be used to avoid changing window sizes when you want to keep them. Since windows can become quite narrow with vertical splits, text lines will often not fit. The 'sidescrolloff' has been added to keep some context left and right of the cursor. The 'listchars' option has been extended with the "precedes" item, to show a "<" for example, when there is text left off the screen. (Utz-Uwe Haus) "-O" command line argument: open windows vertically. (Scott Urban) Added commands to move the current window to the very top (CTRL-W K), bottom (CTRL-W J), left (CTRL-W H) and right (CTRL-W L). In the new position the window uses the full width/height of the screen. When there is not enough room in the status line for both the file name and the ruler, use up to half the width for the ruler. Useful for narrow windows. Flexible indenting *new-indent-flex* ------------------ Automatic indenting is now possible for any language. It works with a Vim script, which makes it very flexible to compute the indent. The 'indentexpr' option is evaluated to get the indent for a line. The 'indentkeys' option tells when to trigger re-indenting. Normally these options are set from an indent script. Like Syntax files, indent scripts will be created and maintained by many people. Extended search patterns *new-searchpat* ------------------------ Multi-line patterns: (partly by Loic Grenie) \n match end-of-line, also in [] \_[] match characters in range and end-of-line \_x match character class and end-of-line \_. match any character or end-of-line \_^ match start-of-line, can be used anywhere in the regexp \_$ match end-of-line, can be used anywhere in the regexp \c ignore case for the whole pattern \C match case for the whole pattern \m magic on for the following \M magic off for the following \v make following characters "very magic" \V make following characters "very nomagic" \@! don't match atom before it. Example: "foo\(bar\)\@!" matches "foo " but not "foobar". \@= match atom, resulting in zero-width match Example: "foo\(bar\)\@=" matches "foo" in "foobar". \@ match preceding atom as a subexpression \& match only when branch before and after it match \%[] optionally match a list of atoms; "end\%[if]" matches "end", "endi" and "endif" \%(\) like \(\), but without creating a back-reference; there can be any number of these, overcomes the limit of nine \( \) pairs \%^ match start-of-file (Chase Tingley) \%$ match end-of-file (Chase Tingley) \%# Match with the cursor position. (Chase Tingley) \? Just like "\=" but can't be used in a "?" command. \%23l match in line 23 \%<23l match before line 23 \%>23l match after line 23 \%23c, \%<23c, \%>23c match in/before/after column 23 \%23v, \%<23v, \%>23v match in/before/after virtual column 23 For syntax items: \z(...\) external reference match set (in region start pattern) \z1 - \z9 external reference match use (in region skip or end pattern) (Scott Bigham) \zs use position as start of match \ze use position as end of match Removed limit of matching only up to 32767 times with *, \+, etc. Added some support for double-byte characters. (Muraoka) UTF-8 support *new-utf-8* ------------- Vim can now edit files in UTF-8 encoding. Up to 31 bit characters can be used, but only 16 bit characters are displayed. Up to two combining characters are supported, they overprint the preceding character. Double-width characters are also supported. See |UTF-8|. UCS-2, UCS-4 and UTF-16 encodings are supported too, they are converted to UTF-8 internally. There is also support for editing Unicode files in a Latin1 environment. Other encodings are converted with iconv() or an external converter specified with 'charconvert'. Many new items for Multi-byte support: - Added 'encoding' option: specifies character coding used inside Vim. It can be any 8-bit encoding, some double-byte encodings or Unicode. It is initialized from the environment when a supported value is found. - Added 'fileencoding' and 'fileencodings': specify character coding in a file, similar to 'fileformat' and 'fileformats'. When 'encoding' is "utf-8" and 'fileencodings' is "utf-8,latin1" this will automatically switch to latin1 if a file does not contain valid UTF-8. - Added 'guifontwide' for double-width font. - Added Korean support for character class detection. Also fix cls() in search.c. (Chong-Dae Park) - Added 'bomb' option and detection of a BOM at the start of a file. Can be used with "ucs-bom" in 'fileencodings' to automatically detect a Unicode file if it starts with a BOM. Especially useful on MS-Windows (NT and 2000), which uses ucs-2le files with a BOM (e.g., when exporting the registry). - Win32: Typing multi-byte characters without IME. (Alexander Smishlajev) - Win32 with Mingw: compile with iconv library. (Ron Aaron) - Win32 with MSVC: dynamically load iconv.dll library. (Muraoka Taro) - Added 'delcombing' option: Delete combining character separately. (Ron Aaron) - When 'viminfo' contains the 'c' flag, the viminfo file is converted from the 'encoding' it was written with to the current 'encoding'. - Added the 'termencoding' option: Specifies the encoding used for the terminal. Useful to put Vim in utf-8 mode while in a non-Unicode locale: > :let &termencoding = &encoding :set encoding=utf-8 - Added ":scriptencoding" command: convert lines in a sourced script to 'encoding'. Useful for menu files. - Made "\<" and "\>" in regexp work for UTF-8. (Muraoka Taro) - Support double-byte single-width characters for euc-jp: Characters starting with 0x8E. Added ScreenLines2[] to store the second byte. - The "xfontset" feature isn't required for "xim". These are now two independent features. - XIM: enable XIM when typing a language character (Insert mode, Search pattern, "f" or "r" command). Disable XIM when typing a Normal mode command. - Added 'm' flag to 'formatoptions': When wrapping words, allow splitting at each multibyte character, not only at a space. - Patterns should now work properly with all kinds of multi-byte characters. Allow defining digraphs for multi-byte characters. Added RFC1345 digraphs for Unicode. Most Normal mode commands that accept a character argument, like "r", "t" and "f" now accept a digraph. The 'D' flag in 'cpoptions' disables this to remain Vi compatible. Added Language mapping and 'keymap' to be able to type multi-byte characters: - Added the ":lmap" command and friends: Define mappings that are used when typing characters in the language of the text. Also for "r", "t", etc. In Insert and Command-line mode CTRL-^ switches the use of the mappings on/off. - "" argument to ":map", allows to specify the decimal, octal or hexadecimal value of a character. - Implemented the 'keymap' option: Load a keymap file. Uses ":lnoremap" to define mappings for the keymap. The new ":loadkeymap" command is used in the keymap file. - Added 'k' flag in 'statusline': Value of "b:keymap_name" or 'keymap' when it's being used. Uses "" when no keymap is loaded and ":lmap"s are active. Show this text in the default statusline too. - When typing a mapping that's not finished yet, display the last character under the cursor in Insert mode and Command-line mode. Looks good for dead characters. - Made the 'langmap' option recognize multi-byte characters. But mapping only works for 8-bit characters. Helps when using UTF-8. Multi-language support *new-multi-lang* ---------------------- - Added +multi_lang feature. - Prepared for use of gettext() by putting translatable strings in _(). Added "po" directory with message translations. (Marcin Dalecki) The src/po/README.txt file explains a few things about translation. - Added v:lang variable to be able to get current language setting. (Marcin Dalecki) - Added ":language" command to set the language (locale) for messages and character type. - Added ":menutrans" to be able to translate menu paths. - Added German and Polish menu translations (Marcin Dalecki), Italian menu translations (Antonio Colombo). - Added Hungarian menus. (Zoltan Arpadffy) - removed "broken locale" (Marcin Dalecki). - don't user color names in icons, use RGB values. The names could be translated. - Win32: Added global IME support (Muraoka) - ":messages" prints a message about who maintains the messages or the translations. Useful to find out where to make a remark about a wrong translation. - --disable-nls argument for configure: Disable use of gettext(). (Sung-Hyun Nam) - Added NLS support for Win32 with the MingW compiler. (Eduardo Fernandez) - Made it possible to have vimtutor use different languages. Spanish and Italian translations are included. (Eduardo Fernandez) Plugin support *new-plugins* -------------- To make it really easy to load a Vim script when starting Vim, the "plugin" runtime directory can be used. All "*.vim" files in it will be automatically loaded. For Unix, the directory "~/.vim/plugin" is used by default. The 'runtimepath' option can be set to look in other directories for plugins. |load-plugins| |add-plugin| The |:runtime| command has been added to load one or more files in 'runtimepath'. Standard plugins: netrw.vim - Edit files over a network gzip.vim - Edit compressed files explorer.vim - Browse directories Added support for local help files. |add-local-help|. When searching for help tags, all "doc/tags" files in 'runtimepath' are used. Added the ":helptags" command: Generate a tags file for a help directory. The first line of each help file is automagically added to the "LOCAL ADDITIONS" section in doc/help.txt. argument to ":map": only add a mapping when it wasn't defined before. When displaying an option value with 'verbose' set will give a message about where the option was last set. Very useful to find out which script did set the value. The new |:scriptnames| command displays a list of all scripts that have been sourced. Filetype plugins *new-filetype-plugins* ----------------- A new group of files has been added to do settings for specific file types. These can be options and mappings which are specifically used for one value of 'filetype'. The files are located in "$VIMRUNTIME/ftplugin". The 'runtimepath' option makes it possible to use several sets of plugins: Your own, system-wide, included in the Vim distribution, etc. To be able to make this work, several features were added: - Added the "s:" variables, local to a script. Avoids name conflicts with global variables. They can be used in the script and in functions, autocommands and user commands defined in the script. They are kept between invocations of the same script. |s:var| - Added the global value for local options. This value is used when opening a new buffer or editing another file. The option value specified in a modeline or filetype setting is not carried over to another buffer. ":set" sets both the local and the global value. ":setlocal" sets the local option value only. ":setglobal" displays the global value for a local option. Setting only the global value isn't implemented yet. - Added the buffer-local value for some global options: 'equalprg', 'makeprg', 'grepprg', 'path', 'dictionary', 'thesaurus', 'tags' and 'define'. This allows setting a local value for these global options, without making it incompatible. - Added mappings and abbreviations local to a buffer: ":map ". - In a mapping "" can be used to get the value of the "mapleader" variable. This simplifies mappings that use "mapleader". "" defaults to "\". "" does the same with "maplocalleader". This is to be used for mappings local to a buffer. - Added Script ID to define functions and mappings local to a script. - Added