diff options
Diffstat (limited to 'runtime/doc/options.txt')
| -rw-r--r-- | runtime/doc/options.txt | 6826 |
1 files changed, 6826 insertions, 0 deletions
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt new file mode 100644 index 0000000000..5dfb582e8c --- /dev/null +++ b/runtime/doc/options.txt @@ -0,0 +1,6826 @@ +*options.txt* For Vim version 7.0aa. Last change: 2004 Jun 08 + + + VIM REFERENCE MANUAL by Bram Moolenaar + + +Options *options* + +1. Setting options |set-option| +2. Automatically setting options |auto-setting| +3. Options summary |option-summary| + +For an overview of options see help.txt |option-list|. + +Vim has a number of internal variables and switches which can be set to +achieve special effects. These options come in three forms: + boolean can only be on or off *boolean* *toggle* + number has a numeric value + string has a string value + +============================================================================== +1. Setting options *set-option* + + *:se* *:set* +:se[t] Show all options that differ from their default value. + +:se[t] all Show all but terminal options. + +:se[t] termcap Show all terminal options. Note that in the GUI the + key codes are not shown, because they are generated + internally and can't be changed. Changing the terminal + codes in the GUI is not useful either... + + *E518* *E519* +:se[t] {option}? Show value of {option}. + +:se[t] {option} Toggle option: set, switch it on. + Number option: show value. + String option: show value. + +:se[t] no{option} Toggle option: Reset, switch it off. + +:se[t] {option}! or +:se[t] inv{option} Toggle option: Invert value. {not in Vi} + + *:set-default* *:set-&* *:set-&vi* *:set-&vim* +:se[t] {option}& Reset option to its default value. May depend on the + current value of 'compatible'. {not in Vi} +:se[t] {option}&vi Reset option to its Vi default value. {not in Vi} +:se[t] {option}&vim Reset option to its Vim default value. {not in Vi} + +:se[t] all& Set all options, except terminal options, to their + default value. The values of 'term', 'lines' and + 'columns' are not changed. {not in Vi} + + *:set-args* *E487* *E521* +:se[t] {option}={value} or +:se[t] {option}:{value} + Set string or number option to {value}. + For numeric options the value can be given in decimal, + hex (preceded with 0x) or octal (preceded with '0') + (hex and octal are only available for machines which + have the strtol() function). + The old value can be inserted by typing 'wildchar' (by + default this is a <Tab> or CTRL-E if 'compatible' is + set). See |cmdline-completion|. + White space between {option} and '=' is allowed and + will be ignored. White space between '=' and {value} + is not allowed. + See |option-backslash| for using white space and + backslashes in {value}. + +:se[t] {option}+={value} *:set+=* + Add the {value} to a number option, or append the + {value} to a string option. When the option is a + comma separated list, a comma is added, unless the + value was empty. + If the option is a list of flags, superfluous flags + are removed. Otherwise there is no check for doubled + values. You can avoid this by removing a value first. + Example: > + :set guioptions-=T guioptions+=T +< Also see |:set-args| above. + {not in Vi} + +:se[t] {option}^={value} *:set^=* + Multiply the {value} to a number option, or prepend + the {value} to a string option. When the option is a + comma separated list, a comma is added, unless the + value was empty. + Also see |:set-args| above. + {not in Vi} + +:se[t] {option}-={value} *:set-=* + Subtract the {value} from a number option, or remove + the {value} from a string option, if it is there. + If the {value} is not found in a string option, there + is no error or warning. When the option is a comma + separated list, a comma is deleted, unless the option + becomes empty. + When the option is a list of flags, {value} must be + exactly as they appear in the option. Remove flags + one by one to avoid problems. + Also see |:set-args| above. + {not in Vi} + +The {option} arguments to ":set" may be repeated. For example: > + :set ai nosi sw=3 ts=3 +If you make an error in one of the arguments, an error message will be given +and the following arguments will be ignored. + + *:set-verbose* +When 'verbose' is non-zero, displaying an option value will also tell where it +was last set. Example: > + :verbose set shiftwidth cindent? + shiftwidth=4 + Last set from modeline + cindent + Last set from /usr/local/share/vim/vim60/ftplugin/c.vim +This is only done when specific option values are requested, not for ":set +all" or ":set" without an argument. +When the option was set by hand there is no "Last set" message. There is only +one value for all local options with the same name. Thus the message applies +to the option name, not necessarily its value. +When the option was set while executing a function, user command or +autocommand, the script in which it was defined is reported. +Note that an option may also have been set as a side effect of setting +'compatible'. +{not available when compiled without the +eval feature} + + *:set-termcap* *E522* +For {option} the form "t_xx" may be used to set a termcap option. This will +override the value from the termcap. You can then use it in a mapping. If +the "xx" part contains special characters, use the <t_xx> form: > + :set <t_#4>=^[Ot +This can also be used to translate a special code for a normal key. For +example, if Alt-b produces <Esc>b, use this: > + :set <M-b>=^[b +(the ^[ is a real <Esc> here, use CTRL-V <Esc> to enter it) +The advantage over a mapping is that it works in all situations. + +The listing from ":set" looks different from Vi. Long string options are put +at the end of the list. The number of options is quite large. The output of +"set all" probably does not fit on the screen, causing Vim to give the +|more-prompt|. + + *option-backslash* +To include white space in a string option value it has to be preceded with a +backslash. To include a backslash you have to use two. Effectively this +means that the number of backslashes in an option value is halved (rounded +down). +A few examples: > + :set tags=tags\ /usr/tags results in "tags /usr/tags" + :set tags=tags\\,file results in "tags\,file" + :set tags=tags\\\ file results in "tags\ file" + +The "|" character separates a ":set" command from a following command. To +include the "|" in the option value, use "\|" instead. This example sets the +'titlestring' option to "hi|there": > + :set titlestring=hi\|there +This sets the 'titlestring' option to "hi" and 'iconstring' to "there": > + :set titlestring=hi|set iconstring=there + +For MS-DOS and WIN32 backslashes in file names are mostly not removed. More +precise: For options that expect a file name (those where environment +variables are expanded) a backslash before a normal file name character is not +removed. But a backslash before a special character (space, backslash, comma, +etc.) is used like explained above. +There is one special situation, when the value starts with "\\": > + :set dir=\\machine\path results in "\\machine\path" + :set dir=\\\\machine\\path results in "\\machine\path" + :set dir=\\path\\file results in "\\path\file" (wrong!) +For the first one the start is kept, but for the second one the backslashes +are halved. This makes sure it works both when you expect backslashes to be +halved and when you expect the backslashes to be kept. The third gives a +result which is probably not what you want. Avoid it. + + *add-option-flags* *remove-option-flags* + *E539* *E550* *E551* *E552* +Some options are a list of flags. When you want to add a flag to such an +option, without changing the existing ones, you can do it like this: > + :set guioptions+=a +Remove a flag from an option like this: > + :set guioptions-=a +This removes the 'a' flag from 'guioptions'. +Note that you should add or remove one flag at a time. If 'guioptions' has +the value "ab", using "set guioptions-=ba" won't work, because the string "ba" +doesn't appear. + + *:set_env* *expand-env* *expand-environment-var* +Environment variables in most string options will be expanded. If the +environment variable exists the '$' and the following environment variable +name is replaced with its value. If it does not exist the '$' and the name +are not modified. Any non-id character (not a letter, digit or '_') may +follow the environment variable name. That character and what follows is +appended to the value of the environment variable. Examples: > + :set term=$TERM.new + :set path=/usr/$INCLUDE,$HOME/include,. +When adding or removing a string from an option with ":set opt-=val" or ":set +opt+=val" the expansion is done before the adding or removing. + + +Handling of local options *local-options* + +Some of the options only apply to a window or buffer. Each window or buffer +has its own copy of this option, thus can each have their own value. This +allows you to set 'list' in one window but not in another. And set +'shiftwidth' to 3 in one buffer and 4 in another. + +The following explains what happens to these local options in specific +situations. You don't really need to know all of this, since Vim mostly uses +the option values you would expect. Unfortunately, doing what the user +expects is a bit complicated... + +When splitting a window, the local options are copied to the new window. Thus +right after the split the contents of the two windows look the same. + +When editing a new buffer, its local option values must be initialized. Since +the local options of the current buffer might be specifically for that buffer, +these are not used. Instead, for each buffer-local option there also is a +global value, which is used for new buffers. With ":set" both the local and +global value is changed. With "setlocal" only the local value is changed, +thus this value is not used when editing a new buffer. + +When editing a buffer that has been edited before, the last used window +options are used again. If this buffer has been edited in this window, the +values from back then are used. Otherwise the values from the window where +the buffer was edited last are used. + +It's possible to set a local window option specifically for a type of buffer. +When you edit another buffer in the same window, you don't want to keep +using these local window options. Therefore Vim keeps a global value of the +local window options, which is used when editing another buffer. Each window +has its own copy of these values. Thus these are local to the window, but +global to all buffers in the window. With this you can do: > + :e one + :set list + :e two +Now the 'list' option will also be set in "two", since with the ":set list" +command you have also set the global value. > + :set nolist + :e one + :setlocal list + :e two +Now the 'list' option is not set, because ":set nolist" resets the global +value, ":setlocal list" only changes the local value and ":e two" gets the +global value. Note that if you do this next: > + :e one +You will not get back the 'list' value as it was the last time you edited +"one". The options local to a window are not remembered for each buffer. + + *:setl* *:setlocal* +:setl[ocal] ... Like ":set" but set only the value local to the + current buffer or window. Not all options have a + local value. If the option does not have a local + value the global value is set. + With the "all" argument: display all local option's + local values. + Without argument: Display all local option's local + values which are different from the default. + When displaying a specific local option, show the + local value. For a global option the global value is + shown (but that might change in the future). + {not in Vi} + +:setl[ocal] {option}< Set the local value of {option} to its global value. + {not in Vi} + + *:setg* *:setglobal* +:setg[lobal] ... Like ":set" but set only the global value for a local + option without changing the local value. + When displaying an option, the global value is shown. + With the "all" argument: display all local option's + global values. + Without argument: display all local option's global + values which are different from the default. + {not in Vi} + +For buffer-local and window-local options: + Command global value local value ~ + :set option=value set set + :setlocal option=value - set +:setglobal option=value set - + :set option? - display + :setlocal option? - display +:setglobal option? display - + + +Global options with a local value *global-local* + +Options are global when you mostly use one value for all buffers. For some +global options it's useful to sometimes have a different local value. You can +set the local value with ":setlocal". That buffer will then use the local +value, while other buffers continue using the global value. + +For example, you have two windows, both on C source code. They use the global +'makeprg' option. If you do this in one of the two windows: > + :set makeprg=gmake +then the other window will switch to the same value. There is no need to set +the 'makeprg' option in the other C source window too. +However, if you start editing a Perl file in a new window, you want to use +another 'makeprog' for it, without changing the value used for the C source +files. You use this command: > + :setlocal makeprg=perlmake +You can switch back to using the global value by making the local value empty: > + :setlocal makeprg= +This only works for a string option. For a boolean option you need to use the +"<" flag, like this: > + :setlocal autoread< +Note that for non-boolean options using "<" copies the global value to the +local value, it doesn't switch back to using the global value (that matters +when changing the global value later). +Note: In the future more global options can be made global-local. Using +":setlocal" on a global option might work differently then. + + +Setting the filetype + +:setf[iletype] {filetype} *:setf* *:setfiletype* + Set the 'filetype' option to {filetype}, but only if + not done yet in a sequence of (nested) autocommands. + This is short for: > + :if !did_filetype() + : setlocal filetype={filetype} + :endif +< This command is used in a filetype.vim file to avoid + setting the 'filetype' option twice, causing different + settings and syntax files to be loaded. + {not in Vi} + +:bro[wse] se[t] *:set-browse* *:browse-set* *:opt* *:options* +:opt[ions] Open a window for viewing and setting all options. + Options are grouped by function. + Offers short help for each option. Hit <CR> on the + short help to open a help window with more help for + the option. + Modify the value of the option and hit <CR> on the + "set" line to set the new value. For window and + buffer specific options, the last accessed window is + used to set the option value in, unless this is a help + window, in which case the window below help window is + used (skipping the option-window). + {not available when compiled without the |+eval| or + |+autocmd| features} + + *$HOME* +Using "~" is like using "$HOME", but it is only recognized at the start of an +option and after a space or comma. + +On Unix systems "~user" can be used too. It is replaced by the home directory +of user "user". Example: > + :set path=~mool/include,/usr/include,. + +On Unix systems the form "${HOME}" can be used too. The name between {} can +contain non-id characters then. Note that if you want to use this for the +"gf" command, you need to add the '{' and '}' characters to 'isfname'. + +NOTE: expanding environment variables and "~/" is only done with the ":set" +command, not when assigning a value to an option with ":let". + + +Note the maximum length of an expanded option is limited. How much depends on +the system, mostly it is something like 256 or 1024 characters. + + *:fix* *:fixdel* +:fix[del] Set the value of 't_kD': + 't_kb' is 't_kD' becomes ~ + CTRL-? CTRL-H + not CTRL-? CTRL-? + + (CTRL-? is 0177 octal, 0x7f hex) {not in Vi} + + If your delete key terminal code is wrong, but the + code for backspace is alright, you can put this in + your .vimrc: > + :fixdel +< This works no matter what the actual code for + backspace is. + + If the backspace key terminal code is wrong you can + use this: > + :if &term == "termname" + : set t_kb=^V<BS> + : fixdel + :endif +< Where "^V" is CTRL-V and "<BS>" is the backspace key + (don't type four characters!). Replace "termname" + with your terminal name. + + If your <Delete> key sends a strange key sequence (not + CTRL-? or CTRL-H) you cannot use ":fixdel". Then use: > + :if &term == "termname" + : set t_kD=^V<Delete> + :endif +< Where "^V" is CTRL-V and "<Delete>" is the delete key + (don't type eight characters!). Replace "termname" + with your terminal name. + + *Linux-backspace* + Note about Linux: By default the backspace key + produces CTRL-?, which is wrong. You can fix it by + putting this line in your rc.local: > + echo "keycode 14 = BackSpace" | loadkeys +< + *NetBSD-backspace* + Note about NetBSD: If your backspace doesn't produce + the right code, try this: > + xmodmap -e "keycode 22 = BackSpace" +< If this works, add this in your .Xmodmap file: > + keysym 22 = BackSpace +< You need to restart for this to take effect. + +============================================================================== +2. Automatically setting options *auto-setting* + +Besides changing options with the ":set" command, there are three alternatives +to set options automatically for one or more files: + +1. When starting Vim initializations are read from various places. See + |initialization|. Most of them are performed for all editing sessions, + and some of them depend on the directory where Vim is started. + You can create an initialization file with |:mkvimrc|, |:mkview| and + |:mksession|. +2. If you start editing a new file, the automatic commands are executed. + This can be used to set options for files matching a particular pattern and + many other things. See |autocommand|. +3. If you start editing a new file, and the 'modeline' option is on, a + number of lines at the beginning and end of the file are checked for + modelines. This is explained here. + + *modeline* *vim:* *vi:* *ex:* *E520* +There are two forms of modelines. The first form: + [text]{white}{vi:|vim:|ex:}[white]{options} + +[text] any text or empty +{white} at least one blank character (<Space> or <Tab>) +{vi:|vim:|ex:} the string "vi:", "vim:" or "ex:" +[white] optional white space +{options} a list of option settings, separated with white space or ':', + where each part between ':' is the argument for a ":set" + command + +Example: > + vi:noai:sw=3 ts=6 + +The second form (this is compatible with some versions of Vi): + + [text]{white}{vi:|vim:|ex:}[white]se[t] {options}:[text] + +[text] any text or empty +{white} at least one blank character (<Space> or <Tab>) +{vi:|vim:|ex:} the string "vi:", "vim:" or "ex:" +[white] optional white space +se[t] the string "set " or "se " (note the space) +{options} a list of options, separated with white space, which is the + argument for a ":set" command +: a colon +[text] any text or empty + +Example: > + /* vim: set ai tw=75: */ + +The white space before {vi:|vim:|ex:} is required. This minimizes the chance +that a normal word like "lex:" is caught. There is one exception: "vi:" and +"vim:" can also be at the start of the line (for compatibility with version +3.0). Using "ex:" at the start of the line will be ignored (this could be +short for "example:"). + + *modeline-local* +The options are set like with ":setlocal": The new value only applies to the +buffer that contains the window. Although it's possible to set global options +from a modeline, this is unusual. If you have two windows open and the files +in it set the same global option to a different value, the result depends on +which one was opened last. + + *modeline-version* +If the modeline is only to be used for some versions of Vim, the version +number can be specified where "vim:" is used: + vim{vers}: version {vers} or later + vim<{vers}: version before {vers} + vim={vers}: version {vers} + vim>{vers}: version after {vers} +{vers} is 600 for Vim 6.0 (hundred times the major version plus minor). +For example, to use a modeline only for Vim 6.0 and later: > + /* vim600: set foldmethod=marker: */ +To use a modeline for Vim before version 5.7: > + /* vim<570: set sw=4: */ +There can be no blanks between "vim" and the ":". + + +The number of lines that are checked can be set with the 'modelines' option. +If 'modeline' is off or 'modelines' is 0 no lines are checked. + +Note that for the first form all of the rest of the line is used, thus a line +like: > + /* vi:ts=4: */ +will give an error message for the trailing "*/". This line is OK: > + /* vi:set ts=4: */ + +If an error is detected the rest of the line is skipped. + +If you want to include a ':' in a set command precede it with a '\'. The +backslash in front of the ':' will be removed. Example: > + /* vi:set dir=c\:\tmp: */ +This sets the 'dir' option to "c:\tmp". Only a single backslash before the +':' is removed. Thus to include "\:" you have to specify "\\:". + +No other commands than "set" are supported, for security reasons (somebody +might create a Trojan horse text file with modelines). + +Hint: If you would like to do something else than setting an option, you could +define an autocommand that checks the file for a specific string. For +example: > + au BufReadPost * if getline(1) =~ "VAR" | call SetVar() | endif +And define a function SetVar() that does something with the line containing +"VAR". + +============================================================================== +3. Options summary *option-summary* + +In the list below all the options are mentioned with their full name and with +an abbreviation if there is one. Both forms may be used. + +In this document when a boolean option is "set" that means that ":set option" +is entered. When an option is "reset", ":set nooption" is used. + +For some options there are two default values: The "Vim default", which is +used when 'compatible' is not set, and the "Vi default", which is used when +'compatible' is set. + +Most options are the same in all windows and buffers. There are a few that +are specific to how the text is presented in a window. These can be set to a +different value in each window. For example the 'list' option can be set in +one window and reset in another for the same text, giving both types of view +at the same time. There are a few options that are specific to a certain +file. These can have a different value for each file or buffer. For example +the 'textwidth' option can be 78 for a normal text file and 0 for a C +program. + + global one option for all buffers and windows + local to window each window has its own copy of this option + local to buffer each buffer has its own copy of this option + +When creating a new window the option values from the currently active window +are used as a default value for the window-specific options. For the +buffer-specific options this depends on the 's' and 'S' flags in the +'cpoptions' option. If 's' is included (which is the default) the values for +buffer options are copied from the currently active buffer when a buffer is +first entered. If 'S' is present the options are copied each time the buffer +is entered, this is almost like having global options. If 's' and 'S' are not +present, the options are copied from the currently active buffer when the +buffer is created. + +Not all options are supported in all versions. To test if option "foo" can be +used with ":set" use "exists('&foo')". This doesn't mean the value is +actually remembered and works. Some options are hidden, which means that you +can set them but the value is not remembered. To test if option "foo" is +really supported use "exists('+foo')". + + *E355* +A jump table for the options with a short description can be found at |Q_op|. + + *'aleph'* *'al'* *aleph* *Aleph* +'aleph' 'al' number (default 128 for MS-DOS, 224 otherwise) + global + {not in Vi} + {only available when compiled with the |+rightleft| + feature} + The ASCII code for the first letter of the Hebrew alphabet. The + routine that maps the keyboard in Hebrew mode, both in Insert mode + (when hkmap is set) and on the command-line (when hitting CTRL-_) + outputs the Hebrew characters in the range [aleph..aleph+26]. + aleph=128 applies to PC code, and aleph=224 applies to ISO 8859-8. + See |rileft.txt|. + + *'allowrevins'* *'ari'* *'noallowrevins'* *'noari'* +'allowrevins' 'ari' boolean (default off) + global + {not in Vi} + {only available when compiled with the |+rightleft| + feature} + Allow CTRL-_ in Insert and Command-line mode. This is default off, to + avoid that users that accidentally type CTRL-_ instead of SHIFT-_ get + into reverse Insert mode, and don't know how to get out. See + 'revins'. + NOTE: This option is reset when 'compatible' is set. + + *'altkeymap'* *'akm'* *'noaltkeymap'* *'noakm'* +'altkeymap' 'akm' boolean (default off) + global + {not in Vi} + {only available when compiled with the |+farsi| + feature} + When on, the second language is Farsi. In editing mode CTRL-_ toggles + the keyboard map between Farsi and English, when 'allowrevins' set. + + When off, the keyboard map toggles between Hebrew and English. This + is useful to start the Vim in native mode i.e. English (left-to-right + mode) and have default second language Farsi or Hebrew (right-to-left + mode). See |farsi.txt|. + + *'ambiwidth'* *'ambw'* +'ambiwidth' 'ambw' string (default: "single") + global + {not in Vi} + {only available when compiled with the |+multi_byte| + feature} + Only effective when 'encoding' is "utf-8" or another Unicode encoding. + Tells Vim what to do with characters with East Asian Width Class + Ambiguous (such as Euro, Registered Sign, Copyright Sign, Greek + letters, Cyrillic letters). + + There are currently two possible values: + "single": Use the same width as characters in US-ASCII. This is + expected by most users. + "double": Use twice the width of ASCII characters. + + There are a number of CJK fonts for which the width of glyphs for + those characters are solely based on how many octets they take in + legacy/traditional CJK encodings. In those encodings, Euro, + Registered sign, Greek/Cyrillic letters are represented by two octets, + therefore those fonts have "wide" glyphs for them. This is also + true of some line drawing characters used to make tables in text + file. Therefore, when a CJK font is used for GUI Vim or + Vim is running inside a terminal (emulators) that uses a CJK font + (or Vim is run inside an xterm invoked with "-cjkwidth" option.), + this option should be set to "double" to match the width perceived + by Vim with the width of glyphs in the font. Perhaps it also has + to be set to "double" under CJK Windows 9x/ME or Windows 2k/XP + when the system locale is set to one of CJK locales. See Unicode + Standard Annex #11 (http://www.unicode.org/reports/tr11). + + *'antialias'* *'anti'* *'noantialias'* *'noanti'* +'antialias' 'anti' boolean (default: off) + global + {not in Vi} + {only available when compiled with GUI enabled + on Mac OS X} + This option only has an effect in the GUI version of Vim on Mac OS X + v10.2 or later. When on, Vim will use smooth ("antialiased") fonts, + which can be easier to read at certain sizes on certain displays. + Setting this option can sometimes cause problems if 'guifont' is set + to its default (empty string). + + *'autochdir'* *'acd'* *'noautochdir'* *'noacd'* +'autochdir' 'acd' boolean (default off) + global + {not in Vi} + {only available when compiled with the + |+netbeans_intg| or |+sun_workshop| feature} + When on, Vim will change its value for the current working directory + whenever you open a file, switch buffers, delete a buffer or + open/close a window. It will change to the directory containing the + file which was opened or selected. This option is provided for + backward compatibility with the Vim released with Sun ONE Studio 4 + Enterprise Edition. + + *'arabic'* *'arab'* *'noarabic'* *'noarab'* +'arabic' 'arab' boolean (default off) + local to window + {not in Vi} + {only available when compiled with the |+arabic| + feature} + This option can be set to start editing Arabic text. + Setting this option will: + - Set the 'rightleft' option, unless 'termbidi' is set. + - Set the 'arabicshape' option, unless 'termbidi' is set. + - Set the 'keymap' option to "arabic"; in Insert mode CTRL-^ toggles + between typing English and Arabic key mapping. + - Set the 'delcombine' option + Note that 'encoding' must be "utf-8" for working with Arabic text. + + Resetting this option will: + - Reset the 'rightleft' option. + - Disable the use of 'keymap' (without changing its value). + Note that 'arabicshape' and 'delcombine' are not reset (it is a global + option. + Also see |arabic.txt|. + + *'arabicshape'* *'arshape'* + *'noarabicshape'* *'noarshape'* +'arabicshape' 'arshape' boolean (default on) + global + {not in Vi} + {only available when compiled with the |+arabic| + feature} + When on and 'termbidi' is off, the required visual character + corrections that need to take place for displaying the Arabic language + take affect. Shaping, in essence, gets enabled; the term is a broad + one which encompasses: + a) the changing/morphing of characters based on their location + within a word (initial, medial, final and stand-alone). + b) the enabling of the ability to compose characters + c) the enabling of the required combining of some characters + When disabled the character display reverts back to each character's + true stand-alone form. + Arabic is a complex language which requires other settings, for + further details see |arabic.txt|. + + *'autoindent'* *'ai'* *'noautoindent'* *'noai'* +'autoindent' 'ai' boolean (default off) + local to buffer + Copy indent from current line when starting a new line (typing <CR> + in Insert mode or when using the "o" or "O" command). If you do not + type anything on the new line except <BS> or CTRL-D and then type + <Esc> or <CR>, the indent is deleted again. When autoindent is on, + formatting (with the "gq" command or when you reach 'textwidth' in + Insert mode) uses the indentation of the first line. + When 'smartindent' or 'cindent' is on the indent is changed in + a different way. + The 'autoindent' option is reset when the 'paste' option is set. + {small difference from Vi: After the indent is deleted when typing + <Esc> or <CR>, the cursor position when moving up or down is after the + deleted indent; Vi puts the cursor somewhere in the deleted indent}. + + *'autoread'* *'ar'* *'noautoread'* *'noar'* +'autoread' 'ar' boolean (default off) + global or local to buffer |global-local| + {not in Vi} + When a file has been detected to have been changed outside of Vim and + it has not been changed inside of Vim, automatically read it again. + When the file has been deleted this is not done. |timestamp| + If this option has a local value, use this command to switch back to + using the global value: > + :set autoread< +< + *'autowrite'* *'aw'* *'noautowrite'* *'noaw'* +'autowrite' 'aw' boolean (default off) + global + Write the contents of the file, if it has been modified, on each + :next, :rewind, :last, :first, :previous, :stop, :suspend, :tag, :!, + :make, CTRL-] and CTRL-^ command; and when a CTRL-O, CTRL-I, + '{A-Z0-9}, or `{A-Z0-9} command takes one to another file. + Note that for some commands the 'autowrite' option is not used, see + 'autowriteall' for that. + + *'autowriteall'* *'awa'* *'noautowriteall'* *'noawa'* +'autowriteall' 'awa' boolean (default off) + global + {not in Vi} + Like 'autowrite', but also used for commands ":edit", ":enew", ":quit", + ":qall", ":exit", ":xit", ":recover" and closing the Vim window. + Setting this option also implies that Vim behaves like 'autowrite' has + been set. + + *'background'* *'bg'* +'background' 'bg' string (default "dark" or "light") + global + {not in Vi} + When set to "dark", Vim will try to use colors that look good on a + dark background. When set to "light", Vim will try to use colors that + look good on a light background. Any other value is illegal. + Vim tries to set the default value according to the terminal used. + This will not always be correct. + Setting this option does not change the background color, it tells Vim + what the background color looks like. For changing the background + color, see |:hi-normal|. + + When 'background' is set Vim will adjust the default color groups for + the new value. But the colors used for syntax highlighting will not + change. + When a color scheme is loaded (the "colors_name" variable is set) + setting 'background' will cause the color scheme to be reloaded. If + the color scheme adjusts to the value of 'background' this will work. + However, if the color scheme sets 'background' itself the effect may + be undone. First delete the "colors_name" variable when needed. + + When setting 'background' to the default value with: > + :set background& +< Vim will guess the value. In the GUI this should work correctly, + in other cases Vim might not be able to guess the right value. + + When starting the GUI, the default value for 'background' will be + "light". When the value is not set in the .gvimrc, and Vim detects + that the background is actually quite dark, 'background' is set to + "dark". But this happens only AFTER the .gvimrc file has been read + (because the window needs to be opened to find the actual background + color). To get around this, force the GUI window to be opened by + putting a ":gui" command in the .gvimrc file, before where the value + of 'background' is used (e.g., before ":syntax on"). + Normally this option would be set in the .vimrc file. Possibly + depending on the terminal name. Example: > + :if &term == "pcterm" + : set background=dark + :endif +< When this option is set, the default settings for the highlight groups + will change. To use other settings, place ":highlight" commands AFTER + the setting of the 'background' option. + This option is also used in the "$VIMRUNTIME/syntax/syntax.vim" file + to select the colors for syntax highlighting. After changing this + option, you must load syntax.vim again to see the result. This can be + done with ":syntax on". + + *'backspace'* *'bs'* +'backspace' 'bs' string (default "") + global + {not in Vi} + Influences the working of <BS>, <Del>, CTRL-W and CTRL-U in Insert + mode. This is a list of items, separated by commas. Each item allows + a way to backspace over something: + value effect ~ + indent allow backspacing over autoindent + eol allow backspacing over line breaks (join lines) + start allow backspacing over the start of insert; CTRL-W and CTRL-U + stop once at the start of insert. + + When the value is empty, Vi compatible backspacing is used. + + For backwards compatibility with version 5.4 and earlier: + value effect ~ + 0 same as ":set backspace=" (Vi compatible) + 1 same as ":set backspace=indent,eol" + 2 same as ":set backspace=indent,eol,start" + + See |:fixdel| if your <BS> or <Del> key does not do what you want. + NOTE: This option is set to "" when 'compatible' is set. + + *'backup'* *'bk'* *'nobackup'* *'nobk'* +'backup' 'bk' boolean (default off) + global + {not in Vi} + Make a backup before overwriting a file. Leave it around after the + file has been successfully written. If you do not want to keep the + backup file, but you do want a backup while the file is being + written, reset this option and set the 'writebackup' option (this is + the default). If you do not want a backup file at all reset both + options (use this if your file system is almost full). See the + |backup-table| for more explanations. + When the 'backupskip' pattern matches, a backup is not made anyway. + When 'patchmode' is set, the backup may be renamed to become the + oldest version of a file. + NOTE: This option is reset when 'compatible' is set. + + *'backupcopy'* *'bkc'* +'backupcopy' 'bkc' string (Vi default for Unix: "yes", otherwise: "auto") + global + {not in Vi} + When writing a file and a backup is made, this option tells how it's + done. This is a comma separated list of words. + + The main values are: + "yes" make a copy of the file and overwrite the original one + "no" rename the file and write a new one + "auto" one of the previous, what works best + + Extra values that can be combined with the ones above are: + "breaksymlink" always break symlinks when writing + "breakhardlink" always break hardlinks when writing + + Making a copy and overwriting the original file: + - Takes extra time to copy the file. + + When the file has special attributes, is a (hard/symbolic) link or + has a resource fork, all this is preserved. + - When the file is a link the backup will have the name of the link, + not of the real file. + + Renaming the file and writing a new one: + + It's fast. + - Sometimes not all attributes of the file can be copied to the new + file. + - When the file is a link the new file will not be a link. + + The "auto" value is the middle way: When Vim sees that renaming file + is possible without side effects (the attributes can be passed on and + and the file is not a link) that is used. When problems are expected, + a copy will be made. + + The "breaksymlink" and "breakhardlink" values can be used in + combination with any of "yes", "no" and "auto". When included, they + force Vim to always break either symbolic or hard links by doing + exactly what the "no" option does, renaming the original file to + become the backup and writing a new file in its place. This can be + useful for example in source trees where all the files are symbolic or + hard links and any changes should stay in the local source tree, not + be propagated back to the original source. + *crontab* + One situation where "no" and "auto" will cause problems: A program + that opens a file, invokes Vim to edit that file, and then tests if + the open file was changed (through the file descriptor) will check the + backup file instead of the newly created file. "crontab -e" is an + example. + + When a copy is made, the original file is truncated and then filled + with the new text. This means that protection bits, owner and + symbolic links of the original file are unmodified. The backup file + however, is a new file, owned by the user who edited the file. The + group of the backup is set to the group of the original file. If this + fails, the protection bits for the group are made the same as for + others. + + When the file is renamed this is the other way around: The backup has + the same attributes of the original file, and the newly written file + is owned by the current user. When the file was a (hard/symbolic) + link, the new file will not! That's why the "auto" value doesn't + rename when the file is a link. The owner and group of the newly + written file will be set to the same ones as the original file |