vim

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

insert.txt (93158B)


      1 *insert.txt*	For Vim version 9.2.  Last change: 2026 Aug 25
      2 
      3 
      4 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
      5 
      6 
      7 						*Insert* *Insert-mode*
      8 Inserting and replacing text				*mode-ins-repl*
      9 
     10 Most of this file is about Insert and Replace mode.  At the end are a few
     11 commands for inserting text in other ways.
     12 
     13 An overview of the most often used commands can be found in chapter 24 of the
     14 user manual |usr_24.txt|.
     15 
     16 1. Special keys						|ins-special-keys|
     17 2. Special special keys					|ins-special-special|
     18 3. 'textwidth' and 'wrapmargin' options			|ins-textwidth|
     19 4. 'expandtab', 'smarttab' and 'softtabstop'  options	|ins-expandtab|
     20 5. Replace mode						|Replace-mode|
     21 6. Virtual Replace mode					|Virtual-Replace-mode|
     22 7. Insert mode completion				|ins-completion|
     23 8. Insert mode commands					|inserting|
     24 9. Ex insert commands					|inserting-ex|
     25 10. Inserting a file					|inserting-file|
     26 
     27 Also see 'virtualedit', for moving the cursor to positions where there is no
     28 character.  Useful for editing a table.
     29 
     30 ==============================================================================
     31 1. Special keys						*ins-special-keys*
     32 
     33 In Insert and Replace mode, the following characters have a special meaning;
     34 other characters are inserted directly.  To insert one of these special
     35 characters into the buffer, precede it with CTRL-V.  To insert a <Nul>
     36 character use "CTRL-V CTRL-@" or "CTRL-V 000".  On some systems, you have to
     37 use "CTRL-V 003" to insert a CTRL-C.  Note: When CTRL-V is mapped you can
     38 often use CTRL-Q instead |i_CTRL-Q|.
     39 
     40 If you are working in a special language mode when inserting text, see the
     41 'langmap' option, 'langmap', on how to avoid switching this mode on and off
     42 all the time.
     43 
     44 If you have 'insertmode' set, <Esc> and a few other keys get another meaning.
     45 See 'insertmode'.
     46 
     47 char		action	~
     48 -----------------------------------------------------------------------
     49 						*i_CTRL-[* *i_<Esc>*
     50 <Esc> or CTRL-[	End insert or Replace mode, go back to Normal mode.  Finish
     51 		abbreviation.
     52 		Note: If your <Esc> key is hard to hit on your keyboard, train
     53 		yourself to use CTRL-[.
     54 		If Esc doesn't work and you are using a Mac, try CTRL-<Esc>.
     55 		Or disable Listening under Accessibility preferences.
     56 						*i_CTRL-C*
     57 CTRL-C		Quit insert mode, go back to Normal mode.  Do not check for
     58 		abbreviations.  Does not trigger the |InsertLeave| autocommand
     59 		event.
     60 
     61 						*i_CTRL-@*
     62 CTRL-@		Insert previously inserted text and stop insert.
     63 
     64 						*i_CTRL-A*
     65 CTRL-A		Insert previously inserted text.
     66 
     67 						*i_CTRL-H* *i_<BS>* *i_BS*
     68 <BS> or CTRL-H	Delete the character before the cursor (see |i_backspacing|
     69 		about joining lines).
     70 		See |:fixdel| if your <BS> key does not do what you want.
     71 
     72 						*i_<Del>* *i_DEL*
     73 <Del>		Delete the character under the cursor.  If the cursor is at
     74 		the end of the line, and the 'backspace' option includes
     75 		"eol", delete the <EOL>; the next line is appended after the
     76 		current one.
     77 		See |:fixdel| if your <Del> key does not do what you want.
     78 						*i_CTRL-W*
     79 CTRL-W		Delete the word before the cursor (see |i_backspacing| about
     80 		joining lines).  See the section "word motions",
     81 		|word-motions|, for the definition of a word.
     82 						*i_CTRL-U*
     83 CTRL-U		Delete all characters that were entered after starting Insert
     84 		mode and before the cursor in the current line.
     85 		If there are no newly entered characters and 'backspace' is
     86 		not empty, delete all characters before the cursor in the
     87 		current line.
     88 		If C-indenting is enabled the indent will be adjusted if the
     89 		line becomes blank.
     90 		See |i_backspacing| about joining lines.
     91 						*i_CTRL-I* *i_<Tab>* *i_Tab*
     92 <Tab> or CTRL-I Insert a tab.  If the 'expandtab' option is on, the
     93 		equivalent number of spaces is inserted (use CTRL-V <Tab> to
     94 		avoid the expansion; use CTRL-Q <Tab> if CTRL-V is mapped
     95 		|i_CTRL-Q|).  See also the 'smarttab' option and
     96 		|ins-expandtab|.
     97 						*i_CTRL-J* *i_<NL>*
     98 <NL> or CTRL-J	Begin new line.
     99 						*i_CTRL-M* *i_<CR>*
    100 <CR> or CTRL-M	Begin new line.
    101 						*i_CTRL-K*
    102 CTRL-K {char1} [char2]
    103 		Enter digraph (see |digraphs|).  When {char1} is a special
    104 		key, the code for that key is inserted in <> form.  For
    105 		example, the string "<S-Space>" can be entered by typing
    106 		<C-K><S-Space> (two keys).  Neither char is considered for
    107 		mapping.
    108 
    109 CTRL-N		Find next keyword (see |i_CTRL-N|).
    110 CTRL-P		Find previous keyword (see |i_CTRL-P|).
    111 
    112 CTRL-R {register}				*i_CTRL-R*
    113 		Insert the contents of a register.  Between typing CTRL-R and
    114 		the second character, '"' will be displayed to indicate that
    115 		you are expected to enter the name of a register.
    116 		The text is inserted as if you typed it, but mappings and
    117 		abbreviations are not used.  If you have options like
    118 		'textwidth', 'formatoptions', or 'autoindent' set, this will
    119 		influence what will be inserted.  This is different from what
    120 		happens with the "p" command and pasting with the mouse.
    121 		Special registers:
    122 			'"'	the unnamed register, containing the text of
    123 				the last delete or yank
    124 			'%'	the current file name
    125 			'#'	the alternate file name
    126 			'*'	the clipboard contents (X11: primary selection)
    127 			'+'	the clipboard contents
    128 			'/'	the last search pattern
    129 			':'	the last command-line
    130 			'.'	the last inserted text
    131 							*i_CTRL-R_-*
    132 			'-'	the last small (less than a line) delete
    133 				register.  This is repeatable using |.| since
    134 				it remembers the register to put instead of
    135 				the literal text to insert.
    136 							*i_CTRL-R_=*
    137 			'='	the expression register: you are prompted to
    138 				enter an expression (see |expression|)
    139 				Note that 0x80 (128 decimal) is used for
    140 				special keys.  E.g., you can use this to move
    141 				the cursor up:
    142 					CTRL-R ="\<Up>"
    143 				Use CTRL-R CTRL-R to insert text literally.
    144 				When the result is a |List| the items are used
    145 				as lines.  They can have line breaks inside
    146 				too.
    147 				When the result is a Float it's automatically
    148 				converted to a String.
    149 				When append() or setline() is invoked the undo
    150 				sequence will be broken.
    151 		See |registers| about registers.
    152 
    153 CTRL-R CTRL-R {register}			*i_CTRL-R_CTRL-R*
    154 		Insert the contents of a register.  Works like using a single
    155 		CTRL-R, but the text is inserted literally, not as if typed.
    156 		This differs when the register contains characters like <BS>.
    157 		Example, where register a contains "ab^Hc": >
    158 	CTRL-R a		results in "ac".
    159 	CTRL-R CTRL-R a		results in "ab^Hc".
    160 <		Options 'textwidth', 'formatoptions', etc. still apply.  If
    161 		you also want to avoid these, use CTRL-R CTRL-O, see below.
    162 		The '.' register (last inserted text) is still inserted as
    163 		typed.
    164 		After this command, the '.' register contains the text from
    165 		the register as if it was inserted by typing it.
    166 
    167 CTRL-R CTRL-O {register}			*i_CTRL-R_CTRL-O*
    168 		Insert the contents of a register literally and don't
    169 		auto-indent.  Does the same as pasting with the mouse
    170 		|<MiddleMouse>|.  When the register is linewise this will
    171 		insert the text above the current line, like with `P`.
    172 		The '.' register (last inserted text) is still inserted as
    173 		typed.
    174 		After this command, the '.' register contains the command
    175 		typed and not the text.  I.e., the literals "^R^O" and not the
    176 		text from the register.
    177 		Does not replace characters in |Replace-mode|!
    178 
    179 CTRL-R CTRL-P {register}			*i_CTRL-R_CTRL-P*
    180 		Insert the contents of a register literally and fix the
    181 		indent, like |[<MiddleMouse>|.
    182 		The '.' register (last inserted text) is still inserted as
    183 		typed.
    184 		After this command, the '.' register contains the command
    185 		typed and not the text.  I.e., the literals "^R^P" and not the
    186 		text from the register.
    187 		Does not replace characters in |Replace-mode|!
    188 
    189 						*i_CTRL-T*
    190 CTRL-T		Insert one shiftwidth of indent at the start of the current
    191 		line.  The indent is always rounded to a 'shiftwidth' (this is
    192 		vi compatible).
    193 						*i_CTRL-D*
    194 CTRL-D		Delete one shiftwidth of indent at the start of the current
    195 		line.  The indent is always rounded to a 'shiftwidth' (this is
    196 		vi compatible).
    197 						*i_0_CTRL-D*
    198 0 CTRL-D	Delete all indent in the current line.
    199 
    200 						*i_^_CTRL-D*
    201 ^ CTRL-D	Delete all indent in the current line.  The indent is
    202 		restored in the next line.  This is useful when inserting a
    203 		label.
    204 
    205 						*i_CTRL-V*
    206 CTRL-V		Insert next non-digit literally.  For special keys, the
    207 		terminal code is inserted.  It's also possible to enter the
    208 		decimal, octal or hexadecimal value of a character
    209 		|i_CTRL-V_digit|.
    210 		The characters typed right after CTRL-V are not considered for
    211 		mapping.
    212 		Note: When CTRL-V is mapped (e.g., to paste text) you can
    213 		often use CTRL-Q instead |i_CTRL-Q|.
    214 		When |modifyOtherKeys| is enabled then special Escape sequence
    215 		is converted back to what it was without |modifyOtherKeys|,
    216 		unless the Shift key is also pressed.
    217 
    218 						*i_CTRL-Q*
    219 CTRL-Q		Same as CTRL-V.
    220 		Note: Some terminal connections may eat CTRL-Q, it doesn't
    221 		work then.  It does work in the GUI.
    222 
    223 CTRL-SHIFT-V				*i_CTRL-SHIFT-V* *i_CTRL-SHIFT-Q*
    224 CTRL-SHIFT-Q	Works just like CTRL-V, unless |modifyOtherKeys| is active,
    225 		then it inserts the Escape sequence for a key with modifiers.
    226 		Note: When CTRL-SHIFT-V is intercepted by your system (e.g.,
    227 		to paste text) you can often use CTRL-SHIFT-Q instead.
    228 		However, in some terminals (e.g. GNOME Terminal), CTRL-SHIFT-Q
    229 		quits the terminal without confirmation.
    230 
    231 CTRL-X		Enter CTRL-X mode.  This is a sub-mode where commands can
    232 		be given to complete words or scroll the window.  See
    233 		|i_CTRL-X| and |ins-completion|.
    234 
    235 						*i_CTRL-E*
    236 CTRL-E		Insert the character which is below the cursor.
    237 						*i_CTRL-Y*
    238 CTRL-Y		Insert the character which is above the cursor.
    239 		Note that for CTRL-E and CTRL-Y 'textwidth' is not used, to be
    240 		able to copy characters from a long line.
    241 
    242 						*i_CTRL-_*
    243 CTRL-_		Switch between languages, as follows:
    244 		-  When in a rightleft window, revins and nohkmap are toggled,
    245 		   since English will likely be inserted in this case.
    246 		-  When in a norightleft window, revins and hkmap are toggled,
    247 		   since Hebrew will likely be inserted in this case.
    248 
    249 		CTRL-_ moves the cursor to the end of the typed text.
    250 
    251 		This command is only available when the 'allowrevins' option
    252 		is set.
    253 		Please refer to |rileft.txt| for more information about
    254 		right-to-left mode.
    255 		Only if compiled with the |+rightleft| feature.
    256 
    257 						*i_CTRL-^*
    258 CTRL-^		Toggle the use of typing language characters.
    259 		When language |:lmap| mappings are defined:
    260 		- If 'iminsert' is 1 (langmap mappings used) it becomes 0 (no
    261 		  langmap mappings used).
    262 		- If 'iminsert' has another value it becomes 1, thus langmap
    263 		  mappings are enabled.
    264 		When no language mappings are defined:
    265 		- If 'iminsert' is 2 (Input Method used) it becomes 0 (no
    266 		  Input Method used).
    267 		- If 'iminsert' has another value it becomes 2, thus the Input
    268 		  Method is enabled.
    269 		When set to 1, the value of the "b:keymap_name" variable, the
    270 		'keymap' option or "<lang>" appears in the status line.
    271 		The language mappings are normally used to type characters
    272 		that are different from what the keyboard produces.  The
    273 		'keymap' option can be used to install a whole number of them.
    274 
    275 						*i_CTRL-]*
    276 CTRL-]		Trigger abbreviation, without inserting a character.
    277 
    278 						*i_<Insert>*
    279 <Insert>	Toggle between Insert and Replace mode.
    280 -----------------------------------------------------------------------
    281 
    282 						*i_backspacing*
    283 The effect of the <BS>, CTRL-W, and CTRL-U depend on the 'backspace' option
    284 (unless 'revins' is set).  This is a comma-separated list of items:
    285 
    286 item	    action ~
    287 indent	    allow backspacing over autoindent
    288 eol	    allow backspacing over line breaks (join lines)
    289 start	    allow backspacing over the start of insert; CTRL-W and CTRL-U stop
    290 	    once at the start of insert.
    291 nostop	    like start, except CTRL-W and CTRL-U do not stop at the start of
    292 	    insert.
    293 
    294 When 'backspace' is empty, Vi compatible backspacing is used.  You cannot
    295 backspace over autoindent, before column 1 or before where insert started.
    296 
    297 For backwards compatibility the values "0", "1", "2" and "3" are also allowed,
    298 see 'backspace'.
    299 
    300 If the 'backspace' option does contain "eol" and the cursor is in column 1
    301 when one of the three keys is used, the current line is joined with the
    302 previous line.  This effectively deletes the <EOL> in front of the cursor.
    303 
    304 						*i_CTRL-V_digit*
    305 With CTRL-V the decimal, octal or hexadecimal value of a character can be
    306 entered directly.  This way you can enter any character, except a line break
    307 (<NL>, value 10).  There are five ways to enter the character value:
    308 
    309 first char	mode	     max nr of chars   max value ~
    310 (none)		decimal		   3		255
    311 o or O		octal		   3		377	 (255)
    312 x or X		hexadecimal	   2		ff	 (255)
    313 u		hexadecimal	   4		ffff	 (65535)
    314 U		hexadecimal	   8		7fffffff (2147483647)
    315 
    316 Normally you would type the maximum number of characters.  Thus to enter a
    317 space (value 32) you would type <C-V>032.  You can omit the leading zero, in
    318 which case the character typed after the number must be a non-digit.  This
    319 happens for the other modes as well: As soon as you type a character that is
    320 invalid for the mode, the value before it will be used and the "invalid"
    321 character is dealt with in the normal way.
    322 
    323 If you enter a value of 10, it will end up in the file as a 0.  The 10 is a
    324 <NL>, which is used internally to represent the <Nul> character.  When writing
    325 the buffer to a file, the <NL> character is translated into <Nul>.  The <NL>
    326 character is written at the end of each line.  Thus if you want to insert a
    327 <NL> character in a file you will have to make a line break.
    328 Also see 'fileformat'.
    329 
    330 						*i_CTRL-X* *insert_expand*
    331 CTRL-X enters a sub-mode where several commands can be used.  Most of these
    332 commands do keyword completion; see |ins-completion|.
    333 
    334 Two commands can be used to scroll the window up or down, without exiting
    335 insert mode:
    336 
    337 						*i_CTRL-X_CTRL-E*
    338 CTRL-X CTRL-E		scroll window one line up.
    339 			When doing completion look here: |complete_CTRL-E|
    340 
    341 						*i_CTRL-X_CTRL-Y*
    342 CTRL-X CTRL-Y		scroll window one line down.
    343 			When doing completion look here: |complete_CTRL-Y|
    344 
    345 After CTRL-X is pressed, each CTRL-E (CTRL-Y) scrolls the window up (down) by
    346 one line unless that would cause the cursor to move from its current position
    347 in the file.  As soon as another key is pressed, CTRL-X mode is exited and
    348 that key is interpreted as in Insert mode.
    349 
    350 
    351 ==============================================================================
    352 2. Special special keys				*ins-special-special*
    353 
    354 The following keys are special.  They stop the current insert, do something,
    355 and then restart insertion.  This means you can do something without getting
    356 out of Insert mode.  This is very handy if you prefer to use the Insert mode
    357 all the time, just like editors that don't have a separate Normal mode.  You
    358 may also want to set the 'backspace' option to "indent,eol,start" and set the
    359 'insertmode' option.  You can use CTRL-O if you want to map a function key to
    360 a command.
    361 
    362 The changes (inserted or deleted characters) before and after these keys can
    363 be undone separately.  Only the last change can be redone and always behaves
    364 like an "i" command.
    365 
    366 char		action	~
    367 -----------------------------------------------------------------------
    368 <Up>		cursor one line up			     *i_<Up>*
    369 <Down>		cursor one line down			     *i_<Down>*
    370 CTRL-G <Up>	cursor one line up, insert start column	     *i_CTRL-G_<Up>*
    371 CTRL-G k	cursor one line up, insert start column	     *i_CTRL-G_k*
    372 CTRL-G CTRL-K	cursor one line up, insert start column	     *i_CTRL-G_CTRL-K*
    373 CTRL-G <Down>	cursor one line down, insert start column    *i_CTRL-G_<Down>*
    374 CTRL-G j	cursor one line down, insert start column    *i_CTRL-G_j*
    375 CTRL-G CTRL-J	cursor one line down, insert start column    *i_CTRL-G_CTRL-J*
    376 <Left>		cursor one character left		     *i_<Left>*
    377 <Right>		cursor one character right		     *i_<Right>*
    378 <S-Left>	cursor one word back (like "b" command)	     *i_<S-Left>*
    379 <C-Left>	cursor one word back (like "b" command)	     *i_<C-Left>*
    380 <S-Right>	cursor one word forward (like "w" command)   *i_<S-Right>*
    381 <C-Right>	cursor one word forward (like "w" command)   *i_<C-Right>*
    382 <Home>		cursor to first char in the line	     *i_<Home>*
    383 <End>		cursor to after last char in the line	     *i_<End>*
    384 <C-Home>	cursor to first char in the file	     *i_<C-Home>*
    385 <C-End>		cursor to after last char in the file	     *i_<C-End>*
    386 <LeftMouse>	cursor to position of mouse click	     *i_<LeftMouse>*
    387 <S-Up>		move window one page up			     *i_<S-Up>*
    388 <PageUp>	move window one page up			     *i_<PageUp>*
    389 <S-Down>	move window one page down		     *i_<S-Down>*
    390 <PageDown>	move window one page down		     *i_<PageDown>*
    391 <ScrollWheelDown>    move window three lines down	*i_<ScrollWheelDown>*
    392 <S-ScrollWheelDown>  move window one page down		*i_<S-ScrollWheelDown>*
    393 <ScrollWheelUp>      move window three lines up		*i_<ScrollWheelUp>*
    394 <S-ScrollWheelUp>    move window one page up		*i_<S-ScrollWheelUp>*
    395 <ScrollWheelLeft>    move window six columns left	*i_<ScrollWheelLeft>*
    396 <S-ScrollWheelLeft>  move window one page left		*i_<S-ScrollWheelLeft>*
    397 <ScrollWheelRight>   move window six columns right	*i_<ScrollWheelRight>*
    398 <S-ScrollWheelRight> move window one page right		*i_<S-ScrollWheelRight>*
    399 CTRL-O		execute one command, return to Insert mode   *i_CTRL-O*
    400 CTRL-\ CTRL-O	like CTRL-O but don't move the cursor	     *i_CTRL-\_CTRL-O*
    401 CTRL-L		when 'insertmode' is set: go to Normal mode  *i_CTRL-L*
    402 CTRL-G u	close undo sequence, start new change	     *i_CTRL-G_u*
    403 CTRL-G U	don't start a new undo block with the next   *i_CTRL-G_U*
    404 		left/right cursor movement, if the cursor
    405 		stays within the same line
    406 -----------------------------------------------------------------------
    407 
    408 Note: If the cursor keys take you out of Insert mode, check the 'noesckeys'
    409 option.
    410 
    411 The CTRL-O command sometimes has a side effect: If the cursor was beyond the
    412 end of the line, it will be put on the last character in the line.  In
    413 mappings it's often better to use <Esc> (first put an "x" in the text, <Esc>
    414 will then always put the cursor on it).  Or use CTRL-\ CTRL-O, but then
    415 beware of the cursor possibly being beyond the end of the line.  Note that the
    416 command following CTRL-\ CTRL-O can still move the cursor, it is not restored
    417 to its original position.
    418 
    419 The CTRL-O command takes you to Normal mode.  If you then use a command enter
    420 Insert mode again it normally doesn't nest.  Thus when typing "a<C-O>a" and
    421 then <Esc> takes you back to Normal mode, you do not need to type <Esc> twice.
    422 An exception is when not typing the command, e.g. when executing a mapping or
    423 sourcing a script.  This makes mappings work that briefly switch to Insert
    424 mode.
    425 
    426 The shifted cursor keys are not available on all terminals.
    427 
    428 Another side effect is that a count specified before the "i" or "a" command is
    429 ignored.  That is because repeating the effect of the command after CTRL-O is
    430 too complicated.
    431 
    432 An example for using CTRL-G u: >
    433 
    434 	:inoremap <C-H> <C-G>u<C-H>
    435 
    436 This redefines the backspace key to start a new undo sequence.  You can now
    437 undo the effect of the backspace key, without changing what you typed before
    438 that, with CTRL-O u.  Another example: >
    439 
    440 	:inoremap <CR> <C-]><C-G>u<CR>
    441 
    442 This starts a new undo block at each line break.  It also expands
    443 abbreviations before this.
    444 
    445 An example for using CTRL-G U: >
    446 
    447 	inoremap <Left>  <C-G>U<Left>
    448 	inoremap <Right> <C-G>U<Right>
    449 	inoremap <expr> <Home> col('.') == match(getline('.'), '\S') + 1 ?
    450 	 \ repeat('<C-G>U<Left>', col('.') - 1) :
    451 	 \ (col('.') < match(getline('.'), '\S') ?
    452 	 \     repeat('<C-G>U<Right>', match(getline('.'), '\S') + 0) :
    453 	 \     repeat('<C-G>U<Left>', col('.') - 1 - match(getline('.'), '\S')))
    454 	inoremap <expr> <End> repeat('<C-G>U<Right>', col('$') - col('.'))
    455 	inoremap ( ()<C-G>U<Left>
    456 
    457 This makes it possible to use the cursor keys in Insert mode, without starting
    458 a new undo block and therefore using |.| (redo) will work as expected.  Also
    459 entering a text like (with the "(" mapping from above):
    460 
    461    Lorem ipsum (dolor
    462 
    463 will be repeatable by using |.| to the expected
    464 
    465    Lorem ipsum (dolor)
    466 
    467 Using CTRL-O splits undo: the text typed before and after it is undone
    468 separately.  If you want to avoid this (e.g., in a mapping) you might be able
    469 to use CTRL-R = |i_CTRL-R|.  E.g., to call a function: >
    470 	:imap <F2> <C-R>=MyFunc()<CR>
    471 
    472 When the 'whichwrap' option is set appropriately, the <Left> and <Right>
    473 keys on the first/last character in the line make the cursor wrap to the
    474 previous/next line.
    475 
    476 The CTRL-G j and CTRL-G k commands can be used to insert text in front of a
    477 column.  Example: >
    478    int i;
    479    int j;
    480 Position the cursor on the first "int", type "istatic <C-G>j       ".  The
    481 result is: >
    482    static int i;
    483 	  int j;
    484 When inserting the same text in front of the column in every line, use the
    485 Visual blockwise command "I" |v_b_I|.
    486 
    487 ==============================================================================
    488 3. 'textwidth' and 'wrapmargin' options			*ins-textwidth*
    489 
    490 The 'textwidth' option can be used to automatically break a line before it
    491 gets too long.  Set the 'textwidth' option to the desired maximum line
    492 length.  If you then type more characters (not spaces or tabs), the
    493 last word will be put on a new line (unless it is the only word on the
    494 line).  If you set 'textwidth' to 0, this feature is disabled.
    495 
    496 The 'wrapmargin' option does almost the same.  The difference is that
    497 'textwidth' has a fixed width while 'wrapmargin' depends on the width of the
    498 screen.  When using 'wrapmargin' this is equal to using 'textwidth' with a
    499 value equal to (columns - 'wrapmargin'), where columns is the width of the
    500 screen.
    501 
    502 When 'textwidth' and 'wrapmargin' are both set, 'textwidth' is used.
    503 
    504 If you don't really want to break the line, but view the line wrapped at a
    505 convenient place, see the 'linebreak' option.
    506 
    507 The line is only broken automatically when using Insert mode, or when
    508 appending to a line.  When in replace mode and the line length is not
    509 changed, the line will not be broken.
    510 
    511 Long lines are broken if you enter a non-white character after the margin.
    512 The situations where a line will be broken can be restricted by adding
    513 characters to the 'formatoptions' option:
    514 "l"  Only break a line if it was not longer than 'textwidth' when the insert
    515      started.
    516 "v"  Only break at a white character that has been entered during the
    517      current insert command.  This is mostly Vi-compatible.
    518 "lv" Only break if the line was not longer than 'textwidth' when the insert
    519      started and only at a white character that has been entered during the
    520      current insert command.  Only differs from "l" when entering non-white
    521      characters while crossing the 'textwidth' boundary.
    522 
    523 Normally an internal function will be used to decide where to break the line.
    524 If you want to do it in a different way set the 'formatexpr' option to an
    525 expression that will take care of the line break.
    526 
    527 If you want to format a block of text, you can use the "gq" operator.  Type
    528 "gq" and a movement command to move the cursor to the end of the block.  In
    529 many cases, the command "gq}" will do what you want (format until the end of
    530 paragraph).  Alternatively, you can use "gqap", which will format the whole
    531 paragraph, no matter where the cursor currently is.  Or you can use Visual
    532 mode: hit "v", move to the end of the block, and type "gq".  See also |gq|.
    533 
    534 ==============================================================================
    535 4. 'expandtab', 'softtabstop' and 'smarttab' options	*ins-expandtab*
    536 
    537 If the 'expandtab' option is on, spaces will be used to fill the amount of
    538 whitespace of the tab.  If you want to enter a real <Tab>, type CTRL-V first
    539 (use CTRL-Q when CTRL-V is mapped |i_CTRL-Q|).
    540 The 'expandtab' option is off by default.  Note that in Replace mode, a single
    541 character is replaced with several spaces.  The result of this is that the
    542 number of characters in the line increases.  Backspacing will delete one
    543 space at a time.  The original character will be put back for only one space
    544 that you backspace over (the last one).
    545 
    546 							*ins-softtabstop*
    547 When the 'softtabstop' option is non-zero, a <Tab> inserts 'softtabstop'
    548 positions, and a <BS> used to delete white space, will delete 'softtabstop'
    549 positions.  This feels like 'tabstop' was set to 'softtabstop', but a real
    550 <Tab> character still takes 'tabstop' positions, so your file will still look
    551 correct when used by other applications.
    552 
    553 If 'softtabstop' is non-zero, a <BS> will try to delete as much white space to
    554 move to the previous 'softtabstop' position, except when the previously
    555 inserted character is a space, then it will only delete the character before
    556 the cursor.  Otherwise you cannot always delete a single character before the
    557 cursor.  You will have to delete 'softtabstop' characters first, and then type
    558 extra spaces to get where you want to be.
    559 
    560 							*ins-smarttab*
    561 When the 'smarttab' option is on, the <Tab> key indents by 'shiftwidth' if the
    562 cursor is in leading whitespace.  The <BS> key has the opposite effect.  This
    563 behaves as if 'softtabstop' were set to the value of 'shiftwidth'.  This
    564 option allows the user to set 'softtabstop' to a value other than 'shiftwidth'
    565 and still use the <Tab> key for indentation.
    566 
    567 ==============================================================================
    568 5. Replace mode				*Replace* *Replace-mode* *mode-replace*
    569 
    570 Enter Replace mode with the "R" command in normal mode.
    571 
    572 In Replace mode, one character in the line is deleted for every character you
    573 type.  If there is no character to delete (at the end of the line), the
    574 typed character is appended (as in Insert mode).  Thus the number of
    575 characters in a line stays the same until you get to the end of the line.
    576 If a <NL> is typed, a line break is inserted and no character is deleted.
    577 
    578 Be careful with <Tab> characters.  If you type a normal printing character in
    579 its place, the number of characters is still the same, but the number of
    580 columns will become smaller.
    581 
    582 If you delete characters in Replace mode (with <BS>, CTRL-W, or CTRL-U), what
    583 happens is that you delete the changes.  The characters that were replaced
    584 are restored.  If you had typed past the existing text, the characters you
    585 added are deleted.  This is effectively a character-at-a-time undo.
    586 
    587 If the 'expandtab' option is on, a <Tab> will replace one character with
    588 several spaces.  The result of this is that the number of characters in the
    589 line increases.  Backspacing will delete one space at a time.  The original
    590 character will be put back for only one space that you backspace over (the
    591 last one).
    592 
    593 ==============================================================================
    594 6. Virtual Replace mode		*vreplace-mode* *Virtual-Replace-mode*
    595 
    596 Enter Virtual Replace mode with the "gR" command in normal mode.
    597 {not available when compiled without the |+vreplace| feature}
    598 
    599 Virtual Replace mode is similar to Replace mode, but instead of replacing
    600 actual characters in the file, you are replacing screen real estate, so that
    601 characters further on in the file never appear to move.
    602 
    603 So if you type a <Tab> it may replace several normal characters, and if you
    604 type a letter on top of a <Tab> it may not replace anything at all, since the
    605 <Tab> will still line up to the same place as before.
    606 
    607 Typing a <NL> still doesn't cause characters later in the file to appear to
    608 move.  The rest of the current line will be replaced by the <NL> (that is,
    609 they are deleted), and replacing continues on the next line.  A new line is
    610 NOT inserted unless you go past the end of the file.
    611 
    612 Interesting effects are seen when using CTRL-T and CTRL-D.  The characters
    613 before the cursor are shifted sideways as normal, but characters later in the
    614 line still remain still.  CTRL-T will hide some of the old line under the
    615 shifted characters, but CTRL-D will reveal them again.
    616 
    617 As with Replace mode, using <BS> etc will bring back the characters that were
    618 replaced.  This still works in conjunction with 'smartindent', CTRL-T and
    619 CTRL-D, 'expandtab', 'smarttab', 'softtabstop', etc.
    620 
    621 In 'list' mode, Virtual Replace mode acts as if it was not in 'list' mode,
    622 unless "L" is in 'cpoptions'.
    623 
    624 Note that the only situations for which characters beyond the cursor should
    625 appear to move are in List mode 'list', and occasionally when 'wrap' is set
    626 (and the line changes length to become shorter or wider than the width of the
    627 screen).  In other cases spaces may be inserted to avoid following characters
    628 to move.
    629 
    630 This mode is very useful for editing <Tab> separated columns in tables, for
    631 entering new data while keeping all the columns aligned.
    632 
    633 ==============================================================================
    634 7. Insert mode completion				*ins-completion*
    635 
    636 In Insert and Replace mode, there are several commands to complete part of a
    637 keyword or line that has been typed.  This is useful if you are using
    638 complicated keywords (e.g., function names with capitals and underscores).
    639 
    640 Completion can be done for:
    641 
    642 1. Whole lines						|i_CTRL-X_CTRL-L|
    643 2. keywords in the current file				|i_CTRL-X_CTRL-N|
    644 3. keywords in 'dictionary'				|i_CTRL-X_CTRL-K|
    645 4. keywords in 'thesaurus', thesaurus-style		|i_CTRL-X_CTRL-T|
    646 5. keywords in the current and included files		|i_CTRL-X_CTRL-I|
    647 6. tags							|i_CTRL-X_CTRL-]|
    648 7. file names						|i_CTRL-X_CTRL-F|
    649 8. definitions or macros				|i_CTRL-X_CTRL-D|
    650 9. Vim command-line					|i_CTRL-X_CTRL-V|
    651 10. User defined completion				|i_CTRL-X_CTRL-U|
    652 11. omni completion					|i_CTRL-X_CTRL-O|
    653 12. Spelling suggestions				|i_CTRL-X_s|
    654 13. completions from 'complete'				|i_CTRL-N| |i_CTRL-P|
    655 14. contents from registers				|i_CTRL-X_CTRL-R|
    656 
    657 Additionally, |i_CTRL-X_CTRL-Z| stops completion without changing the text.
    658 
    659 All these, except CTRL-N and CTRL-P, are done in CTRL-X mode.  This is a
    660 sub-mode of Insert and Replace modes.  You enter CTRL-X mode by typing CTRL-X
    661 and one of the CTRL-X commands.  You exit CTRL-X mode by typing a key that is
    662 not a valid CTRL-X mode command.  Valid keys are the CTRL-X command itself,
    663 CTRL-N (next), and CTRL-P (previous).
    664 
    665 By default, the possible completions are showed in a menu and the first
    666 completion is inserted into the text.  This can be adjusted with
    667 'completeopt'.
    668 
    669 To get the current completion information, |complete_info()| can be used.
    670 Also see the 'infercase' option if you want to adjust the case of the match.
    671 
    672 When inserting a selected candidate word from the |popup-menu|, the part of
    673 the candidate word that does not match the query is highlighted using
    674 |hl-ComplMatchIns|.  If fuzzy is enabled in 'completeopt', highlighting will
    675 not be applied.
    676 
    677 							*complete_CTRL-E*
    678 When completion is active you can use CTRL-E to stop it and go back to the
    679 originally typed text.  The CTRL-E will not be inserted.
    680 
    681 							*complete_CTRL-Y*
    682 When the popup menu is displayed you can use CTRL-Y to stop completion and
    683 accept the currently selected entry.  The CTRL-Y is not inserted.  Typing a
    684 space, Enter, or some other unprintable character will leave completion mode
    685 and insert that typed character.
    686 
    687 When the popup menu is displayed there are a few more special keys, see
    688 |popupmenu-keys|.
    689 
    690 Note: The keys that are valid in CTRL-X mode are not mapped.  This allows for
    691 `:map <C-F> <C-X><C-F>` to work (assuming "<" is not in 'cpo').  The key that
    692 ends CTRL-X mode (any key that is not a valid CTRL-X mode command) is mapped.
    693 Also, when doing completion with 'complete' or when completion was started
    694 with |complete()| mappings apply as usual.
    695 
    696 								*E565*
    697 Note: While completion is active Insert mode can't be used recursively and
    698 buffer text cannot be changed.  Mappings that somehow invoke ":normal i.."
    699 will generate an E565 error.
    700 
    701 The following mappings are suggested to make typing the completion commands
    702 a bit easier (although they will hide other commands; this requires "<" is not
    703 in 'cpo'): >
    704     :inoremap <C-]> <C-X><C-]>
    705     :inoremap <C-F> <C-X><C-F>
    706     :inoremap <C-D> <C-X><C-D>
    707     :inoremap <C-L> <C-X><C-L>
    708 
    709 As a special case, typing CTRL-R to perform register insertion (see
    710 |i_CTRL-R|) will not exit CTRL-X mode.  This is primarily to allow the use of
    711 the '=' register to call some function to determine the next operation.  If
    712 the contents of the register (or result of the '=' register evaluation) are
    713 not valid CTRL-X mode keys, then CTRL-X mode will be exited as if those keys
    714 had been typed.
    715 
    716 For example, the following will map <Tab> to either actually insert a <Tab> if
    717 the current line is currently only whitespace, or start/continue a CTRL-N
    718 completion operation: >
    719 
    720 	function! CleverTab()
    721 	   if strpart( getline('.'), 0, col('.')-1 ) =~ '^\s*$'
    722 	      return "\<Tab>"
    723 	   else
    724 	      return "\<C-N>"
    725 	   endif
    726 	endfunction
    727 	inoremap <Tab> <C-R>=CleverTab()<CR>
    728 
    729 
    730 
    731 Completing whole lines					*compl-whole-line*
    732 
    733 							*i_CTRL-X_CTRL-L*
    734 CTRL-X CTRL-L		Search backwards for a line that starts with the
    735 			same characters as those in the current line before
    736 			the cursor.  Indent is ignored.  The matching line is
    737 			inserted in front of the cursor.
    738 			The 'complete' option is used to decide which buffers
    739 			are searched for a match.  Both loaded and unloaded
    740 			buffers are used.
    741 	CTRL-L	or
    742 	CTRL-P		Search backwards for next matching line.  This line
    743 			replaces the previous matching line.
    744 
    745 	CTRL-N		Search forward for next matching line.  This line
    746 			replaces the previous matching line.
    747 
    748 	CTRL-X CTRL-L	After expanding a line you can additionally get the
    749 			line next to it by typing CTRL-X CTRL-L again, unless
    750 			a double CTRL-X is used.  Only works for loaded
    751 			buffers.
    752 
    753 Completing keywords in current file			*compl-current*
    754 
    755 							*i_CTRL-X_CTRL-P*
    756 							*i_CTRL-X_CTRL-N*
    757 CTRL-X CTRL-N		Search forwards for words that start with the keyword
    758 			in front of the cursor.  The found keyword is inserted
    759 			in front of the cursor.
    760 
    761 CTRL-X CTRL-P		Search backwards for words that start with the keyword
    762 			in front of the cursor.  The found keyword is inserted
    763 			in front of the cursor.
    764 
    765 	CTRL-N		Search forward for next matching keyword.  This
    766 			keyword replaces the previous matching keyword.
    767 
    768 	CTRL-P		Search backwards for next matching keyword.  This
    769 			keyword replaces the previous matching keyword.
    770 
    771 	CTRL-X CTRL-N or
    772 	CTRL-X CTRL-P	Further use of CTRL-X CTRL-N or CTRL-X CTRL-P will
    773 			copy the words following the previous expansion in
    774 			other contexts unless a double CTRL-X is used.
    775 
    776 If there is a keyword in front of the cursor (a name made out of alphabetic
    777 characters and characters in 'iskeyword'), it is used as the search pattern,
    778 with "\<" prepended (meaning: start of a word).  Otherwise "\<\k\k" is used
    779 as search pattern (start of any keyword of at least two characters).
    780 
    781 In Replace mode, the number of characters that are replaced depends on the
    782 length of the matched string.  This works like typing the characters of the
    783 matched string in Replace mode.
    784 
    785 If there is not a valid keyword character before the cursor, any keyword of
    786 at least two characters is matched.
    787 	e.g., to get:
    788 	    printf("(%g, %g, %g)", vector[0], vector[1], vector[2]);
    789 	just type:
    790 	    printf("(%g, %g, %g)", vector[0], ^P[1], ^P[2]);
    791 
    792 The search wraps around the end of the file, the value of 'wrapscan' is not
    793 used here.
    794 
    795 Multiple repeats of the same completion are skipped; thus a different match
    796 will be inserted at each CTRL-N and CTRL-P (unless there is only one
    797 matching keyword).
    798 
    799 Single character matches are never included, as they usually just get in
    800 the way of what you were really after.
    801 	e.g., to get:
    802 		printf("name = %s\n", name);
    803 	just type:
    804 		printf("name = %s\n", n^P);
    805 	or even:
    806 		printf("name = %s\n", ^P);
    807 The 'n' in '\n' is skipped.
    808 
    809 After expanding a word, you can use CTRL-X CTRL-P or CTRL-X CTRL-N to get the
    810 word following the expansion in other contexts.  These sequences search for
    811 the text just expanded and further expand by getting an extra word.  This is
    812 useful if you need to repeat a sequence of complicated words.  Although CTRL-P
    813 and CTRL-N look just for strings of at least two characters, CTRL-X CTRL-P and
    814 CTRL-X CTRL-N can be used to expand words of just one character.
    815 	e.g., to get:
    816 		M&eacute;xico
    817 	you can type:
    818 		M^N^P^X^P^X^P
    819 CTRL-N starts the expansion and then CTRL-P takes back the single character
    820 "M", the next two CTRL-X CTRL-P's get the words "&eacute" and ";xico".
    821 
    822 If the previous expansion was split, because it got longer than 'textwidth',
    823 then just the text in the current line will be used.
    824 
    825 If the match found is at the end of a line, then the first word in the next
    826 line will be inserted and the message "Word from other line" displayed, if
    827 this word is accepted the next CTRL-X CTRL-P or CTRL-X CTRL-N will search
    828 for those lines starting with this word.
    829 
    830 
    831 Completing keywords in 'dictionary'			*compl-dictionary*
    832 
    833 							*i_CTRL-X_CTRL-K*
    834 CTRL-X CTRL-K		Search the files given with the 'dictionary' option
    835 			for words that start with the keyword in front of the
    836 			cursor.  This is like CTRL-N, but only the dictionary
    837 			files are searched, not the current file.  The found
    838 			keyword is inserted in front of the cursor.  This
    839 			could potentially be pretty slow, since all matches
    840 			are found before the first match is used.  By default,
    841 			the 'dictionary' option is empty.
    842 			For suggestions where to find a list of words, see the
    843 			'dictionary' option.
    844 			'ignorecase', 'smartcase' and 'infercase' apply.
    845 
    846 	CTRL-K	or
    847 	CTRL-N		Search forward for next matching keyword.  This
    848 			keyword replaces the previous matching keyword.
    849 
    850 	CTRL-P		Search backwards for next matching keyword.  This
    851 			keyword replaces the previous matching keyword.
    852 
    853 
    854 Completing words in 'thesaurus'				*compl-thesaurus*
    855 
    856 							*i_CTRL-X_CTRL-T*
    857 CTRL-X CTRL-T		Works as CTRL-X CTRL-K, but in a special way.  It uses
    858 			the 'thesaurus' option instead of 'dictionary'.  If a
    859 			match is found in the thesaurus file, all the
    860 			remaining words on the same line are included as
    861 			matches, even though they don't complete the word.
    862 			Thus a word can be completely replaced.
    863 
    864 	CTRL-T	or
    865 	CTRL-N		Search forward for next matching keyword.  This
    866 			keyword replaces the previous matching keyword.
    867 
    868 	CTRL-P		Search backwards for next matching keyword.  This
    869 			keyword replaces the previous matching keyword.
    870 
    871 In the file used by the 'thesaurus' option each line in the file should
    872 contain words with similar meaning, separated by non-keyword characters (white
    873 space is preferred).  Maximum line length is 510 bytes.
    874 
    875 For an example, imagine the 'thesaurus' file has a line like this: >
    876 	angry furious mad enraged
    877 Placing the cursor after the letters "ang" and typing CTRL-X CTRL-T would
    878 complete the word "angry"; subsequent presses would change the word to
    879 "furious", "mad" etc.
    880 
    881 Other uses include translation between two languages, or grouping API
    882 functions by keyword.
    883 
    884 An English word list was added to this github issue:
    885 https://github.com/vim/vim/issues/629#issuecomment-443293282
    886 Unpack thesaurus_pkg.zip, put the thesaurus.txt file somewhere, e.g.
    887 ~/.vim/thesaurus/english.txt, and the 'thesaurus' option to this file name.
    888 
    889 
    890 Completing keywords with 'thesaurusfunc'		*compl-thesaurusfunc*
    891 
    892 If the 'thesaurusfunc' option is set, then the user specified function is
    893 invoked to get the list of completion matches and the 'thesaurus' option is
    894 not used.  See |complete-functions| for an explanation of how the function is
    895 invoked and what it should return.
    896 
    897 Here is an example that uses the "aiksaurus" command (provided by Magnus
    898 Groß): >
    899 
    900     func Thesaur(findstart, base)
    901       if a:findstart
    902 	return searchpos('\<', 'bnW', line('.'))[1] - 1
    903       endif
    904       let res = []
    905       let h = ''
    906       for l in systemlist('aiksaurus ' .. shellescape(a:base))
    907 	if l[:3] == '=== '
    908 	  let h = '(' .. substitute(l[4:], ' =*$', ')', '')
    909 	elseif l ==# 'Alphabetically similar known words are: '
    910 	  let h = "\U0001f52e"
    911 	elseif l[0] =~ '\a' || (h ==# "\U0001f52e" && l[0] ==# "\t")
    912 	  call extend(res, map(split(substitute(l, '^\t', '', ''), ', '), {_, val -> {'word': val, 'menu': h}}))
    913 	endif
    914       endfor
    915       return res
    916     endfunc
    917 
    918     if exists('+thesaurusfunc')
    919       set thesaurusfunc=Thesaur
    920     endif
    921 
    922 
    923 Completing keywords in the current and included files	*compl-keyword*
    924 
    925 The 'include' option is used to specify a line that contains an include file
    926 name.  The 'path' option is used to search for include files.
    927 
    928 							*i_CTRL-X_CTRL-I*
    929 CTRL-X CTRL-I		Search for the first keyword in the current and
    930 			included files that starts with the same characters
    931 			as those before the cursor.  The matched keyword is
    932 			inserted in front of the cursor.
    933 
    934 	CTRL-N		Search forwards for next matching keyword.  This
    935 			keyword replaces the previous matching keyword.
    936 			Note: CTRL-I is the same as <Tab>, which is likely to
    937 			be typed after a successful completion, therefore
    938 			CTRL-I is not used for searching for the next match.
    939 
    940 	CTRL-P		Search backward for previous matching keyword.  This
    941 			keyword replaces the previous matching keyword.
    942 
    943 	CTRL-X CTRL-I	Further use of CTRL-X CTRL-I will copy the words
    944 			following the previous expansion in other contexts
    945 			unless a double CTRL-X is used.
    946 
    947 Completing tags						*compl-tag*
    948 							*i_CTRL-X_CTRL-]*
    949 CTRL-X CTRL-]		Search for the first tag that starts with the same
    950 			characters as before the cursor.  The matching tag is
    951 			inserted in front of the cursor.  Alphabetic
    952 			characters and characters in 'iskeyword' are used
    953 			to decide which characters are included in the tag
    954 			name (same as for a keyword).  See also |CTRL-]|.
    955 			The 'showfulltag' option can be used to add context
    956 			from around the tag definition.
    957 	CTRL-]	or
    958 	CTRL-N		Search forwards for next matching tag.  This tag
    959 			replaces the previous matching tag.
    960 
    961 	CTRL-P		Search backward for previous matching tag.  This tag
    962 			replaces the previous matching tag.
    963 
    964 
    965 Completing file names					*compl-filename*
    966 							*i_CTRL-X_CTRL-F*
    967 CTRL-X CTRL-F		Search for the first file name that starts with the
    968 			same characters as before the cursor.  The matching
    969 			file name is inserted in front of the cursor.
    970 			Alphabetic characters and characters in 'isfname'
    971 			are used to decide which characters are included in
    972 			the file name.  Note: the 'path' option is not used
    973 			here (yet).
    974 	CTRL-F	or
    975 	CTRL-N		Search forwards for next matching file name.  This
    976 			file name replaces the previous matching file name.
    977 
    978 	CTRL-P		Search backward for previous matching file name.
    979 			This file name replaces the previous matching file
    980 			name.
    981 
    982 
    983 Completing definitions or macros			*compl-define*
    984 
    985 The 'define' option is used to specify a line that contains a definition.
    986 The 'include' option is used to specify a line that contains an include file
    987 name.  The 'path' option is used to search for include files.
    988 
    989 							*i_CTRL-X_CTRL-D*
    990 CTRL-X CTRL-D		Search in the current and included files for the
    991 			first definition (or macro) name that starts with
    992 			the same characters as before the cursor.  The found
    993 			definition name is inserted in front of the cursor.
    994 	CTRL-D	or
    995 	CTRL-N		Search forwards for next matching macro name.  This
    996 			macro name replaces the previous matching macro
    997 			name.
    998 
    999 	CTRL-P		Search backward for previous matching macro name.
   1000 			This macro name replaces the previous matching macro
   1001 			name.
   1002 
   1003 	CTRL-X CTRL-D	Further use of CTRL-X CTRL-D will copy the words
   1004 			following the previous expansion in other contexts
   1005 			unless a double CTRL-X is used.
   1006 
   1007 
   1008 Completing Vim commands					*compl-vim*
   1009 
   1010 Completion is context-sensitive.  It works like on the Command-line.  It
   1011 completes an Ex command as well as its arguments.  This is useful when writing
   1012 a Vim script.
   1013 
   1014 							*i_CTRL-X_CTRL-V*
   1015 CTRL-X CTRL-V		Guess what kind of item is in front of the cursor and
   1016 			find the first match for it.
   1017 			Note: When CTRL-V is mapped you can often use CTRL-Q
   1018 			instead of |i_CTRL-Q|.
   1019 	CTRL-V	or
   1020 	CTRL-N		Search forwards for next match.  This match replaces
   1021 			the previous one.
   1022 
   1023 	CTRL-P		Search backwards for previous match.  This match
   1024 			replaces the previous one.
   1025 
   1026 	CTRL-X CTRL-V	Further use of CTRL-X CTRL-V will do the same as
   1027 			CTRL-V.  This allows mapping a key to do Vim command
   1028 			completion, for example: >
   1029 				:imap <Tab> <C-X><C-V>
   1030 
   1031 
   1032 Completing contents from registers			*compl-register-words*
   1033 							*i_CTRL-X_CTRL-R*
   1034 CTRL-X CTRL-R		Guess what kind of item is in front of the cursor from
   1035 			all registers and find the first match for it.
   1036 			Further use of CTRL-R (without CTRL-X) will insert the
   1037 			register content, see |i_CTRL-R|.
   1038 			'ignorecase' applies to the matching.
   1039 
   1040 	CTRL-N		Search forwards for next match.  This match replaces
   1041 			the previous one.
   1042 
   1043 	CTRL-P		Search backwards for previous match.  This match
   1044 			replaces the previous one.
   1045 
   1046 	CTRL-X CTRL-R	Further use of CTRL-X CTRL-R will copy the line
   1047 			following the previous expansion in other contexts
   1048 			unless a double CTRL-X is used (e.g. this switches
   1049 			from completing register words to register contents).
   1050 
   1051 User defined completion					*compl-function*
   1052 
   1053 Completion is done by a function that can be defined by the user with the
   1054 'completefunc' option.  See below for how the function is called and an
   1055 example |complete-functions|.
   1056 
   1057 							*i_CTRL-X_CTRL-U*
   1058 CTRL-X CTRL-U		Guess what kind of item is in front of the cursor and
   1059 			find the first match for it.
   1060 	CTRL-U	or
   1061 	CTRL-N		Use the next match.  This match replaces the previous
   1062 			one.
   1063 
   1064 	CTRL-P		Use the previous match.  This match replaces the
   1065 			previous one.
   1066 
   1067 
   1068 Omni completion						*compl-omni*
   1069 
   1070 Completion is done by a function that can be defined by the user with the
   1071 'omnifunc' option.  This is to be used for filetype-specific completion.
   1072 
   1073 See below for how the function is called and an example |complete-functions|.
   1074 For remarks about specific filetypes see |compl-omni-filetypes|.
   1075 More completion scripts will appear, check www.vim.org.  Currently there is a
   1076 first version for C++.
   1077 
   1078 							*i_CTRL-X_CTRL-O*
   1079 CTRL-X CTRL-O		Guess what kind of item is in front of the cursor and
   1080 			find the first match for it.
   1081 	CTRL-O	or
   1082 	CTRL-N		Use the next match.  This match replaces the previous
   1083 			one.
   1084 
   1085 	CTRL-P		Use the previous match.  This match replaces the
   1086 			previous one.
   1087 
   1088 
   1089 Spelling suggestions					*compl-spelling*
   1090 
   1091 A word before or at the cursor is located and correctly spelled words are
   1092 suggested to replace it.  If there is a badly spelled word in the line, before
   1093 or under the cursor, the cursor is moved to after it.  Otherwise the word just
   1094 before the cursor is used for suggestions, even though it isn't badly spelled.
   1095 
   1096 NOTE: CTRL-S suspends display in many Unix terminals.  Use 's' instead.  Type
   1097 CTRL-Q to resume displaying.
   1098 
   1099 						*i_CTRL-X_CTRL-S* *i_CTRL-X_s*
   1100 CTRL-X CTRL-S   or
   1101 CTRL-X s		Locate the word in front of the cursor and find the
   1102 			first spell suggestion for it.
   1103 	CTRL-S	or
   1104 	CTRL-N		Use the next suggestion.  This replaces the previous
   1105 			one.  Note that you can't use 's' here.
   1106 
   1107 	CTRL-P		Use the previous suggestion.  This replaces the
   1108 			previous one.
   1109 
   1110 
   1111 Completing from different sources			*compl-generic*
   1112 
   1113 							*i_CTRL-N*
   1114 CTRL-N			Find the next match for a word ending at the cursor,
   1115 			using the sources specified in the 'complete' option.
   1116 			All sources complete from keywords, except functions,
   1117 			which may complete from non-keyword.  The matched
   1118 			text is inserted before the cursor.
   1119 
   1120 							*i_CTRL-P*
   1121 CTRL-P			Same as CTRL-N, but find the previous match.
   1122 
   1123 	CTRL-N		Search forward through the matches and insert the
   1124 			next one.
   1125 
   1126 	CTRL-P		Search backward through the matches and insert the
   1127 			previous one.
   1128 
   1129 	CTRL-X CTRL-N or
   1130 	CTRL-X CTRL-P	Further use of CTRL-X CTRL-N or CTRL-X CTRL-P will
   1131 			copy the words following the previous expansion in
   1132 			other contexts unless a double CTRL-X is used.
   1133 
   1134 
   1135 Stop completion						*compl-stop*
   1136 
   1137 							*i_CTRL-X_CTRL-Z*
   1138 CTRL-X CTRL-Z		Stop completion without changing the text.
   1139 
   1140 
   1141 AUTOCOMPLETION						*ins-autocompletion*
   1142 
   1143 Vim can display a completion menu as you type, similar to using |i_CTRL-N|,
   1144 but triggered automatically.  See 'autocomplete'.  The menu items are
   1145 collected from the sources listed in the 'complete' option, in order.
   1146 
   1147 A decaying timeout keeps Vim responsive.  Sources earlier in the 'complete'
   1148 list get more time (higher priority), but all sources receive at least a small
   1149 time slice.
   1150 
   1151 This mode is fully compatible with other completion modes.  You can invoke
   1152 any of them at any time by typing |CTRL-X|, which temporarily suspends
   1153 autocompletion.  To use |i_CTRL-N| or |i_CTRL-X_CTRL-N| specifically, press
   1154 |CTRL-E| first to dismiss the popup menu (see |complete_CTRL-E|).
   1155 
   1156 						*ins-autocompletion-example*
   1157 Example setup ~
   1158 A typical configuration for automatic completion with a popup menu: >
   1159 	set autocomplete
   1160 	set complete=.^5,w^5,b^5,u^5
   1161 	set completeopt=popup
   1162 
   1163 	inoremap <silent><expr> <Tab>   pumvisible() ? "\<C-n>" : "\<Tab>"
   1164 	inoremap <silent><expr> <S-Tab> pumvisible() ? "\<C-p>" : "\<S-Tab>"
   1165 <
   1166 This enables automatic completion with suggestions from the current buffer,
   1167 other windows, and listed buffers, displayed in a popup menu.  Each source is
   1168 limited to 5 candidates.  <Tab> and <S-Tab> move through the items when the
   1169 menu is visible.  Optionally, add "preinsert" to 'completeopt' to insert the
   1170 longest common prefix automatically.  Additional sources (e.g., LSP clients)
   1171 may be added to 'complete' to improve completion as required.
   1172 
   1173 See also 'autocomplete', 'autocompletedelay' and 'autocompletetimeout'.
   1174 
   1175 For command-line autocompletion, see |cmdline-autocompletion|.
   1176 
   1177 
   1178 FUNCTIONS FOR FINDING COMPLETIONS			*complete-functions*
   1179 
   1180 This applies to 'completefunc', 'thesaurusfunc' and 'omnifunc'.
   1181 
   1182 The function is called in two different ways:
   1183 - First the function is called to find the start of the text to be completed.
   1184 - Later the function is called to actually find the matches.
   1185 
   1186 On the first invocation the arguments are:
   1187    a:findstart  1
   1188    a:base	empty
   1189 
   1190 The function must return the column where the completion starts.  It must be a
   1191 number between zero and the cursor column "col('.')".  This involves looking
   1192 at the characters just before the cursor and including those characters that
   1193 could be part of the completed item.  The text between this column and the
   1194 cursor column will be replaced with the matches.  If the returned value is
   1195 larger than the cursor column, the cursor column is used.
   1196 
   1197 Negative return values:
   1198    -2	To cancel silently and stay in completion mode.
   1199    -3	To cancel silently and leave completion mode.
   1200    Another negative value: completion starts at the cursor column
   1201 
   1202 On the second invocation the arguments are:
   1203    a:findstart  0
   1204    a:base	the text with which matches should match; the text that was
   1205 		located in the first call (can be empty)
   1206 
   1207 The function must return a List with the matching words.  These matches
   1208 usually include the "a:base" text.  When there are no matches return an empty
   1209 List.  Note that the cursor may have moved since the first invocation, the
   1210 text may have been changed.
   1211 
   1212 In order to return more information than the matching words, return a Dict
   1213 that contains the List.  The Dict can have these items:
   1214 	words		The List of matching words (mandatory).
   1215 	refresh		A string to control re-invocation of the function
   1216 			(optional).
   1217 			The only value currently recognized is "always", the
   1218 			effect is that the function is called whenever the
   1219 			leading text is changed.
   1220 
   1221 If you want to suppress the warning message for an empty result, return
   1222 |v:none|.  This is useful to implement asynchronous completion with
   1223 |complete()|.
   1224 
   1225 Other items are ignored.
   1226 
   1227 For acting upon end of completion, see the |CompleteDonePre| and
   1228 |CompleteDone| autocommand event.
   1229 
   1230 For example, the function can contain this: >
   1231 	let matches = ... list of words ...
   1232 	return {'words': matches, 'refresh': 'always'}
   1233 <
   1234 If looking for matches is time-consuming, |complete_check()| may be used to
   1235 maintain responsiveness.
   1236 
   1237 						*complete-items*
   1238 Each list item can either be a string or a Dictionary.  When it is a string it
   1239 is used as the completion.  When it is a Dictionary it can contain these
   1240 items:
   1241 	word		the text that will be inserted, mandatory
   1242 	abbr		abbreviation of "word"; when not empty it is used in
   1243 			the menu instead of "word"
   1244 	menu		extra text for the popup menu, displayed after "word"
   1245 			or "abbr"
   1246 	info		more information about the item, can be displayed in a
   1247 			preview or popup window
   1248 	kind		single letter indicating the type of completion
   1249 	icase		when non-zero case is to be ignored when comparing
   1250 			items to be equal; when omitted zero is used, thus
   1251 			items that only differ in case are added
   1252 	equal		when non-zero, always treat this item to be equal when
   1253 			comparing.  Which means, "equal=1" disables filtering
   1254 			of this item.
   1255 	dup		when non-zero this match will be added even when an
   1256 			item with the same word is already present.
   1257 	empty		when non-zero this match will be added even when it is
   1258 			an empty string
   1259 	user_data	custom data which is associated with the item and
   1260 			available in |v:completed_item|; it can be any type;
   1261 			defaults to an empty string
   1262 	abbr_hlgroup	an additional highlight group whose attributes are
   1263 			combined with |hl-PmenuSel| and |hl-Pmenu| or
   1264 			|hl-PmenuMatchSel| and |hl-PmenuMatch| highlight
   1265 			attributes in the popup menu to apply cterm and gui
   1266 			properties (with higher priority) like strikethrough
   1267 			to the completion items abbreviation.
   1268 			The group can be defined later.
   1269 	kind_hlgroup	an additional highlight group specifically for setting
   1270 			the highlight attributes of the completion kind.  When
   1271 			this field is present, it will override the
   1272 			|hl-PmenuKind| highlight group, allowing for the
   1273 			customization of ctermfg and guifg properties for the
   1274 			completion kind.
   1275 			The group can be defined later.
   1276 	match		See "matches" in |complete_info()|.
   1277 
   1278 All of these except "icase", "equal", "dup" and "empty" must be a string.  If
   1279 an item does not meet these requirements then an error message is given and
   1280 further items in the list are not used.  You can mix string and Dictionary
   1281 items in the returned list.
   1282 
   1283 The "menu" item is used in the popup menu and may be truncated, thus it should
   1284 be relatively short.  The "info" item can be longer, it will  be displayed in
   1285 the preview window when "preview" appears in 'completeopt' or in a popup
   1286 window when "popup" appears in 'completeopt'.  In the preview window the
   1287 "info" item will also remain displayed after the popup menu has been removed.
   1288 This is useful for function arguments.  Use a single space for "info" to
   1289 remove existing text in the preview window.  The size of the preview window is
   1290 three lines, but 'previewheight' is used when it has a value of 1 or 2.
   1291 
   1292 						*complete-popup*
   1293 When "popup" is included in 'completeopt', a popup window is used to display
   1294 the completion "info" text.  The appearance and behavior of this popup are
   1295 controlled by the 'completepopup' option when the popup is created.
   1296 After creation, the info popup can be located with |popup_findinfo()| and
   1297 modified using |popup_setoptions()|.
   1298 
   1299 						*complete-popuphidden*
   1300 If the information for the popup is obtained asynchronously, use "popuphidden"
   1301 in 'completeopt'.  The info popup will then be initially hidden and
   1302 |popup_show()| must be called once it has been filled with the info.  This can
   1303 be done with a |CompleteChanged| autocommand, something like this: >
   1304 	set completeopt+=popuphidden
   1305 	au CompleteChanged * call UpdateCompleteInfo()
   1306 	func UpdateCompleteInfo()
   1307 	  " Cancel any pending info fetch
   1308 	  let item = v:event.completed_item
   1309 	  " Start fetching info for the item then call ShowCompleteInfo(info)
   1310 	endfunc
   1311 	func ShowCompleteInfo(info)
   1312 	  let id = popup_findinfo()
   1313 	  if id
   1314 	    call popup_settext(id, 'async info: ' .. a:info)
   1315 	    call popup_show(id)
   1316 	  endif
   1317 	endfunc
   1318 
   1319 <						*complete-item-kind*
   1320 The "kind" item uses a single letter to indicate the kind of completion.  This
   1321 may be used to show the completion differently (different color or icon).
   1322 Currently these types can be used:
   1323 	v	variable
   1324 	f	function or method
   1325 	m	member of a struct or class
   1326 	t	typedef
   1327 	d	#define or macro
   1328 
   1329 When searching for matches takes some time call |complete_add()| to add each
   1330 match to the total list.  These matches should then not appear in the returned
   1331 list!  Call |complete_check()| now and then to allow the user to press a key
   1332 while still searching for matches.  Stop searching when it returns non-zero.
   1333 
   1334 							*E840*
   1335 The function is allowed to move the cursor, it is restored afterwards.
   1336 The function is not allowed to move to another window or delete text.
   1337 
   1338 An example that completes the names of the months: >
   1339 	fun! CompleteMonths(findstart, base)
   1340 	  if a:findstart
   1341 	    " locate the start of the word
   1342 	    let line = getline('.')
   1343 	    let start = col('.') - 1
   1344 	    while start > 0 && line[start - 1] =~ '\a'
   1345 	      let start -= 1
   1346 	    endwhile
   1347 	    return start
   1348 	  else
   1349 	    " find months matching with "a:base"
   1350 	    let res = []
   1351 	    for m in split("Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec")
   1352 	      if m =~ '^' .. a:base
   1353 		call add(res, m)
   1354 	      endif
   1355 	    endfor
   1356 	    return res
   1357 	  endif
   1358 	endfun
   1359 	set completefunc=CompleteMonths
   1360 <
   1361 The same, but now pretending searching for matches is slow: >
   1362 	fun! CompleteMonths(findstart, base)
   1363 	  if a:findstart
   1364 	    " locate the start of the word
   1365 	    let line = getline('.')
   1366 	    let start = col('.') - 1
   1367 	    while start > 0 && line[start - 1] =~ '\a'
   1368 	      let start -= 1
   1369 	    endwhile
   1370 	    return start
   1371 	  else
   1372 	    " find months matching with "a:base"
   1373 	    for m in split("Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec")
   1374 	      if m =~ '^' .. a:base
   1375 		call complete_add(m)
   1376 	      endif
   1377 	      sleep 300m	" simulate searching for next match
   1378 	      if complete_check()
   1379 		break
   1380 	      endif
   1381 	    endfor
   1382 	    return []
   1383 	  endif
   1384 	endfun
   1385 	set completefunc=CompleteMonths
   1386 <
   1387 
   1388 INSERT COMPLETION POPUP MENU				*ins-completion-menu*
   1389 							*popupmenu-completion*
   1390 Vim can display the matches in a simplistic popup menu.
   1391 
   1392 The menu is used when:
   1393 - The 'completeopt' option contains "menu" or "menuone".
   1394 - There are at least two matches.  One if "menuone" is used.
   1395 
   1396 The 'pumheight' option can be used to set a maximum height.  The default is to
   1397 use all space available.
   1398 The 'pumwidth' option can be used to set a minimum width.  The default is 15
   1399 characters.
   1400 
   1401 							*compl-states*
   1402 There are three states:
   1403 1. A complete match has been inserted, e.g., after using CTRL-N or CTRL-P.
   1404 2. A cursor key has been used to select another match.  The match was not
   1405    inserted then, only the entry in the popup menu is highlighted.
   1406 3. Only part of a match has been inserted and characters were typed or the
   1407    backspace key was used.  The list of matches was then adjusted for what is
   1408    in front of the cursor.
   1409 
   1410 You normally start in the first state, with the first match being inserted.
   1411 When "longest" is in 'completeopt' and there is more than one match you start
   1412 in the third state.
   1413 
   1414 If you select another match, e.g., with CTRL-N or CTRL-P, you go to the first
   1415 state.  This doesn't change the list of matches.
   1416 
   1417 When you are back at the original text then you are in the third state.  To
   1418 get there right away you can use a mapping that uses CTRL-P right after
   1419 starting the completion: >
   1420 	:imap <F7> <C-N><C-P>
   1421 <
   1422 						*popupmenu-keys*
   1423 In the first state these keys have a special meaning:
   1424 <BS> and CTRL-H   Delete one character, find the matches for the word before
   1425 		  the cursor.  This reduces the list of matches, often to one
   1426 		  entry, and switches to the second state.
   1427 		  When 'autocomplete' is active, clears the selected item in
   1428 		  the menu.
   1429 Any non-special character:
   1430 		  Stop completion without changing the match and insert the
   1431 		  typed character.
   1432 
   1433 In the second and third state these keys have a special meaning:
   1434 <BS> and CTRL-H   Delete one character, find the matches for the shorter word
   1435 		  before the cursor.  This may find more matches.
   1436 		  When 'autocomplete' is active, clears the selected item in
   1437 		  the menu.
   1438 CTRL-L		  Add one character from the current match, may reduce the
   1439 		  number of matches.
   1440 any printable, non-white character:
   1441 		  Add this character and reduce the number of matches.
   1442 
   1443 In all three states these can be used:
   1444 CTRL-Y		  Yes: Accept the currently selected match and stop
   1445 		  completion.
   1446 CTRL-E		  End completion, go back to what was there before selecting a
   1447 		  match (what was typed or longest common string).
   1448 <PageUp>	  Select a match several entries back, but don't insert it.
   1449 <PageDown>	  Select a match several entries further, but don't insert it.
   1450 <Up>		  Select the previous match, as if CTRL-P was used, but don't
   1451 		  insert it.
   1452 <Down>		  Select the next match, as if CTRL-N was used, but don't
   1453 		  insert it.
   1454 CTRL-SHIFT-<Up>
   1455 		  Scroll the info popup up one line, when it is shown, see
   1456 		  |complete-popup|.
   1457 		  Note: these CTRL-SHIFT keys need the GUI or a terminal that
   1458 		  reports key modifiers; the Linux console does not.
   1459 CTRL-SHIFT-<Down>
   1460 		  Scroll the info popup down one line.
   1461 CTRL-SHIFT-<PageUp>
   1462 		  Scroll the info popup up one page.
   1463 CTRL-SHIFT-<PageDown>
   1464 		  Scroll the info popup down one page.
   1465 CTRL-SHIFT-P	  Like CTRL-SHIFT-<Up>, scroll the info popup up one line.
   1466 CTRL-SHIFT-N	  Like CTRL-SHIFT-<Down>, scroll the info popup down one line.
   1467 		  Note: CTRL-SHIFT-N and CTRL-SHIFT-P additionally need the
   1468 		  terminal to report modifiers for letter keys, see
   1469 		  |modifyOtherKeys|.
   1470 <Space> or <Tab>  Stop completion without changing the match and insert the
   1471 		  typed character.
   1472 
   1473 The behavior of the <Enter> key depends on the state you are in:
   1474 first state:	  Use the text as it is and insert a line break.
   1475 second state:	  Insert the currently selected match.
   1476 third state:	  Use the text as it is and insert a line break.
   1477 
   1478 In other words: If you used the cursor keys to select another entry in the
   1479 list of matches then the <Enter> key inserts that match.  If you typed
   1480 something else then <Enter> inserts a line break.
   1481 
   1482 
   1483 The colors of the menu can be changed with these highlight groups:
   1484 Pmenu		normal item  |hl-Pmenu|
   1485 PmenuSel	selected item  |hl-PmenuSel|
   1486 PmenuSbar	scrollbar  |hl-PmenuSbar|
   1487 PmenuThumb	thumb of the scrollbar  |hl-PmenuThumb|
   1488 
   1489 There are no special mappings for when the popup menu is visible.  However,
   1490 you can use an Insert mode mapping that checks the |pumvisible()| function to
   1491 do something different.  Example: >
   1492 	:inoremap <Down> <C-R>=pumvisible() ? "\<lt>C-N>" : "\<lt>Down>"<CR>
   1493 
   1494 You can use of <expr> in mapping to have the popup menu used when typing a
   1495 character and some condition is met.  For example, for typing a dot: >
   1496 	inoremap <expr> . MayComplete()
   1497 	func MayComplete()
   1498 	    if (can complete)
   1499 	      return ".\<C-X>\<C-O>"
   1500 	    endif
   1501 	    return '.'
   1502 	endfunc
   1503 
   1504 See |:map-<expr>| for more info.
   1505 
   1506 
   1507 FILETYPE-SPECIFIC REMARKS FOR OMNI COMPLETION	    *compl-omni-filetypes*
   1508 
   1509 The file used for {filetype} should be autoload/{filetype}complete.vim
   1510 in 'runtimepath'.  Thus for "java" it is autoload/javacomplete.vim.
   1511 
   1512 
   1513 C							*ft-c-omni*
   1514 
   1515 Completion of C code requires a tags file.  You should use Universal/
   1516 Exuberant ctags, because it adds extra information that is needed for
   1517 completion.  You can find it here:
   1518 	Universal Ctags: https://ctags.io
   1519 	Exuberant Ctags: http://ctags.sourceforge.net
   1520 
   1521 Universal Ctags is preferred, Exuberant Ctags is no longer being developed.
   1522 
   1523 For Exuberant ctags, version 5.6 or later is recommended.  For version 5.5.4
   1524 you should add a patch that adds the "typename:" field:
   1525 	https://ftp.nluug.nl/pub/vim/unstable/patches/ctags-5.5.4.patch
   1526 A compiled .exe for MS-Windows can be found at:
   1527 	http://ctags.sourceforge.net/
   1528 	https://github.com/universal-ctags/ctags-win32
   1529 
   1530 If you want to complete system functions you can do something like this.  Use
   1531 ctags to generate a tags file for all the system header files: >
   1532 	% ctags -R -f ~/.vim/systags /usr/include /usr/local/include
   1533 In your vimrc file add this tags file to the 'tags' option: >
   1534 	set tags+=~/.vim/systags
   1535 
   1536 When using CTRL-X CTRL-O after a name without any "." or "->" it is completed
   1537 from the tags file directly.  This works for any identifier, also function
   1538 names.  If you want to complete a local variable name, which does not appear
   1539 in the tags file, use CTRL-P instead.
   1540 
   1541 When using CTRL-X CTRL-O after something that has "." or "->" Vim will attempt
   1542 to recognize the type of the variable and figure out what members it has.
   1543 This means only members valid for the variable will be listed.
   1544 
   1545 When a member name already was complete, CTRL-X CTRL-O will add a "." or
   1546 "->" for composite types.
   1547 
   1548 Vim doesn't include a C compiler, only the most obviously formatted
   1549 declarations are recognized.  Preprocessor stuff may cause confusion.
   1550 When the same structure name appears in multiple places all possible members
   1551 are included.
   1552 
   1553 
   1554 CSS							*ft-css-omni*
   1555 
   1556 Complete properties and their appropriate values according to CSS 2.1
   1557 specification.
   1558 
   1559 
   1560 HTML							*ft-html-omni*
   1561 XHTML							*ft-xhtml-omni*
   1562 
   1563 CTRL-X CTRL-O provides completion of various elements of (X)HTML files.  It is
   1564 designed to support writing of XHTML 1.0 Strict files but will also work for
   1565 other versions of HTML.  Features:
   1566 
   1567 - after "<" complete tag name depending on context (no div suggestion inside
   1568   of an a tag); '/>' indicates empty tags
   1569 - inside of tag complete proper attributes (no width attribute for an a tag);
   1570   show also type of attribute; '*' indicates required attributes
   1571 - when attribute has limited number of possible values help to complete them
   1572 - complete names of entities
   1573 - complete values of "class" and "id" attributes with data obtained from
   1574   <style> tag and included CSS files
   1575 - when completing value of "style" attribute or working inside of "style" tag
   1576   switch to |ft-css-omni| completion
   1577 - when completing values of events attributes or working inside of "script"
   1578   tag switch to |ft-javascript-omni| completion
   1579 - when used after "</" CTRL-X CTRL-O will close the last opened tag
   1580 
   1581 Note: When used first time completion menu will be shown with little delay
   1582 - this is time needed for loading of data file.
   1583 Note: Completion may fail in badly formatted documents.  In such case try to
   1584 run |:make| command to detect formatting problems.
   1585 
   1586 
   1587 HTML flavor						*html-flavor*
   1588 
   1589 The default HTML completion depends on the filetype.  For HTML files it is
   1590 HTML 4.01 Transitional ('filetype' is "html"), for XHTML it is XHTML 1.0
   1591 Strict ('filetype' is "xhtml").
   1592 
   1593 When doing completion outside of any other tag you will have possibility to
   1594 choose DOCTYPE and the appropriate data file will be loaded and used for all
   1595 next completions.
   1596 
   1597 More about format of data file in |xml-omni-datafile|.  Some of the data files
   1598 may be found on the Vim website (|www|).
   1599 
   1600 Note that b:html_omni_flavor may point to a file with any XML data.  This
   1601 makes possible to mix PHP (|ft-php-omni|) completion with any XML dialect
   1602 (assuming you have data file for it).  Without setting that variable XHTML 1.0
   1603 Strict will be used.
   1604 
   1605 
   1606 JAVASCRIPT					       *ft-javascript-omni*
   1607 
   1608 Completion of most elements of JavaScript language and DOM elements.
   1609 
   1610 Complete:
   1611 
   1612 - variables
   1613 - function name; show function arguments
   1614 - function arguments
   1615 - properties of variables trying to detect type of variable
   1616 - complete DOM objects and properties depending on context
   1617 - keywords of language
   1618 
   1619 Completion works in separate JavaScript files (&ft==javascript), inside of
   1620 <script> tag of (X)HTML and in values of event attributes (including scanning
   1621 of external files).
   1622 
   1623 DOM compatibility
   1624 
   1625 At the moment (beginning of 2006) there are two main browsers - MS Internet
   1626 Explorer and Mozilla Firefox.  These two applications are covering over 90% of
   1627 market.  Theoretically standards are created by W3C organisation
   1628 (http://www.w3c.org) but they are not always followed/implemented.
   1629 
   1630 		IE	FF	W3C  Omni completion ~
   1631 		+/-	+/-	+    +		     ~
   1632 		+	+	-    +		     ~
   1633 		+	-	-    -		     ~
   1634 		-	+	-    -		     ~
   1635 
   1636 Regardless from state of implementation in browsers but if element is defined
   1637 in standards, completion plugin will place element in suggestion list.  When
   1638 both major engines implemented element, even if this is not in standards it
   1639 will be suggested.  All other elements are not placed in suggestion list.
   1640 
   1641 
   1642 PHP							*ft-php-omni*
   1643 
   1644 Completion of PHP code requires a tags file for completion of data from
   1645 external files and for class aware completion.  You should use Universal/
   1646 Exuberant ctags version 5.5.4 or newer.  You can find it here:
   1647 
   1648 	Universal Ctags: https://ctags.io
   1649 	Exuberant Ctags: http://ctags.sourceforge.net
   1650 
   1651 Script completes:
   1652 
   1653 - after $ variables name
   1654   - if variable was declared as object add "->", if tags file is available
   1655     show name of class
   1656   - after "->" complete only function and variable names specific for given
   1657     class.  To find class location and contents tags file is required.
   1658     Because PHP isn't strongly typed language user can use @var tag to declare
   1659     class: >
   1660 
   1661 	/* @var $myVar myClass */
   1662 	$myVar->
   1663 <
   1664     Still, to find myClass contents tags file is required.
   1665 
   1666 - function names with additional info:
   1667   - in case of built-in functions list of possible arguments and after | type
   1668     data returned by function
   1669   - in case of user function arguments and name of file where function was
   1670     defined (if it is not current file)
   1671 
   1672 - constants names
   1673 - class names after "new" declaration
   1674 
   1675 
   1676 Note: when doing completion first time Vim will load all necessary data into
   1677 memory.  It may take several seconds.  After next use of completion delay
   1678 should not be noticeable.
   1679 
   1680 Script detects if cursor is inside <?php ?> tags.  If it is outside it will
   1681 automatically switch to HTML/CSS/JavaScript completion.  Note: contrary to
   1682 original HTML files completion of tags (and only tags) isn't context aware.
   1683 
   1684 
   1685 RUBY							*ft-ruby-omni*
   1686 
   1687 Completion of Ruby code requires that vim be built with |+ruby|.
   1688 
   1689 Ruby completion will parse your buffer on demand in order to provide a list of
   1690 completions.  These completions will be drawn from modules loaded by 'require'
   1691 and modules defined in the current buffer.
   1692 
   1693 The completions provided by CTRL-X CTRL-O are sensitive to the context:
   1694 
   1695 	  CONTEXT			   COMPLETIONS PROVIDED ~
   1696 
   1697  1. Not inside a class definition    Classes, constants and globals
   1698 
   1699  2. Inside a class definition	     Methods or constants defined in the class
   1700 
   1701  3. After '.', '::' or ':'	     Methods applicable to the object being
   1702 				       dereferenced
   1703 
   1704  4. After ':' or ':foo'		     Symbol name (beginning with 'foo')
   1705 
   1706 Notes:
   1707  - Vim will load/evaluate code in order to provide completions.  This may
   1708    cause some code execution, which may be a concern.  This is no longer
   1709    enabled by default, to enable this feature add >
   1710      let g:rubycomplete_buffer_loading = 1
   1711 <- In context 1 above, Vim can parse the entire buffer to add a list of
   1712    classes to the completion results.  This feature is turned off by default,
   1713    to enable it add >
   1714      let g:rubycomplete_classes_in_global = 1
   1715 <  to your vimrc
   1716  - In context 2 above, anonymous classes are not supported.
   1717  - In context 3 above, Vim will attempt to determine the methods supported by
   1718    the object.
   1719  - Vim can detect and load the Rails environment for files within a rails
   1720    project.  The feature is disabled by default, to enable it add >
   1721      let g:rubycomplete_rails = 1
   1722 <  to your vimrc
   1723 
   1724 
   1725 VIM							*ft-vim-omni*
   1726 
   1727 Simple completion of Vim script and Vim9 script languages.
   1728 
   1729 Complete:
   1730 
   1731 - set and & options
   1732 - commands and command arguments
   1733 - function names after ->
   1734 - expressions
   1735 - l:, v:, g:, s: and b: variables
   1736 - fallback to command line completion to get candidates
   1737 
   1738 Notes
   1739 
   1740 - It doesn't complete command arguments that rely on 'shellcmd' completion
   1741   type in Windows and WSL due to general slowness of candidate gathering,
   1742   e.g.
   1743 >
   1744      terminal dir
   1745      !dir
   1746 <
   1747   These completions might take several seconds to gather candidates.
   1748 
   1749 - 'autocomplete' can't complete "no" options:
   1750 >
   1751      set noautoindent
   1752      set nobuflisted
   1753 <
   1754 
   1755 SYNTAX							*ft-syntax-omni*
   1756 
   1757 Vim has the ability to color syntax highlight nearly 500 languages.  Part of
   1758 this highlighting includes knowing what keywords are part of a language.  Many
   1759 filetypes already have custom completion scripts written for them, the
   1760 syntaxcomplete plugin provides basic completion for all other filetypes.  It
   1761 does this by populating the omni completion list with the text Vim already
   1762 knows how to color highlight.  It can be used for any filetype and provides a
   1763 minimal language-sensitive completion.
   1764 
   1765 To enable syntax code completion you can run: >
   1766     setlocal omnifunc=syntaxcomplete#Complete
   1767 
   1768 You can automate this by placing the following in your |.vimrc| (after any
   1769 ":filetype" command): >
   1770     if has("autocmd") && exists("+omnifunc")
   1771 	autocmd Filetype *
   1772 		    \	if &omnifunc == "" |
   1773 		    \		setlocal omnifunc=syntaxcomplete#Complete |
   1774 		    \	endif
   1775     endif
   1776 
   1777 The above will set completion to this script only if a specific plugin does
   1778 not already exist for that filetype.
   1779 
   1780 Each filetype can have a wide range of syntax items.  The plugin allows you to
   1781 customize which syntax groups to include or exclude from the list.  Let's have
   1782 a look at the PHP filetype to see how this works.
   1783 
   1784 If you edit a file called, index.php, run the following command: >
   1785     syntax list
   1786 
   1787 The first thing you will notice is that there are many different syntax
   1788 groups.  The PHP language can include elements from different languages like
   1789 HTML, JavaScript and many more.  The syntax plugin will only include syntax
   1790 groups that begin with the filetype, "php", in this case.  For example these
   1791 syntax groups are included by default with the PHP: phpEnvVar, phpIntVar,
   1792 phpFunctions.
   1793 
   1794 If you wish non-filetype syntax items to also be included, you can use a
   1795 regular expression syntax (added in version 13.0 of
   1796 autoload/syntaxcomplete.vim) to add items.  Looking at the output from
   1797 ":syntax list" while editing a PHP file I can see some of these entries: >
   1798     htmlArg,htmlTag,htmlTagName,javaScriptStatement,javaScriptGlobalObjects
   1799 
   1800 To pick up any JavaScript and HTML keyword syntax groups while editing a PHP
   1801 file, you can use 3 different regexps, one for each language.  Or you can
   1802 simply restrict the include groups to a particular value, without using
   1803 a regexp string: >
   1804     let g:omni_syntax_group_include_php = 'php\w\+,javaScript\w\+,html\w\+'
   1805     let g:omni_syntax_group_include_php = 'phpFunctions,phpMethods'
   1806 <
   1807 The basic form of this variable is: >
   1808     let g:omni_syntax_group_include_{filetype} = 'regex,comma,separated'
   1809 
   1810 The PHP language has an enormous number of items which it knows how to syntax
   1811 highlight.  These items will be available within the omni completion list.
   1812 
   1813 Some people may find this list unwieldy or are only interested in certain
   1814 items.  There are two ways to prune this list (if necessary).  If you find
   1815 certain syntax groups you do not wish displayed you can use two different
   1816 methods to identify these groups.  The first specifically lists the syntax
   1817 groups by name.  The second uses a regular expression to identify both
   1818 syntax groups.  Simply add one the following to your vimrc: >
   1819     let g:omni_syntax_group_exclude_php = 'phpCoreConstant,phpConstant'
   1820     let g:omni_syntax_group_exclude_php = 'php\w*Constant'
   1821 
   1822 Add as many syntax groups to this list by comma separating them.  The basic
   1823 form of this variable is: >
   1824     let g:omni_syntax_group_exclude_{filetype} = 'regex,comma,separated'
   1825 
   1826 You can create as many of these variables as you need, varying only the
   1827 filetype at the end of the variable name.
   1828 
   1829 The plugin uses the isKeyword option to determine where word boundaries are
   1830 for the syntax items.  For example, in the Scheme language completion should
   1831 include the "-", call-with-output-file.  Depending on your filetype, this may
   1832 not provide the words you are expecting.  Setting the
   1833 g:omni_syntax_use_iskeyword option to 0 will force the syntax plugin to break
   1834 on word characters.  This can be controlled adding the following to your
   1835 vimrc: >
   1836     let g:omni_syntax_use_iskeyword = 0
   1837 
   1838 For plugin developers, the plugin exposes a public function
   1839 syntaxcomplete#OmniSyntaxList.  This function can be used to request a List of
   1840 syntax items.  When editing a SQL file (:e syntax.sql) you can use the
   1841 ":syntax list" command to see the various groups and syntax items.  For
   1842 example: >
   1843     syntax list
   1844 
   1845 Yields data similar to this:
   1846     sqlOperator    xxx some prior all like and any escape exists in is not ~
   1847                        or intersect minus between distinct ~
   1848                        links to Operator ~
   1849     sqlType        xxx varbit varchar nvarchar bigint int uniqueidentifier ~
   1850                        date money long tinyint unsigned xml text smalldate ~
   1851                        double datetime nchar smallint numeric time bit char ~
   1852                        varbinary binary smallmoney ~
   1853                        image float integer timestamp real decimal ~
   1854 
   1855 There are two syntax groups listed here: sqlOperator and sqlType.  To retrieve
   1856 a List of syntax items you can call syntaxcomplete#OmniSyntaxList a number of
   1857 different ways.  To retrieve all syntax items regardless of syntax group:  >
   1858     echo syntaxcomplete#OmniSyntaxList( [] )
   1859 
   1860 To retrieve only the syntax items for the sqlOperator syntax group: >
   1861     echo syntaxcomplete#OmniSyntaxList( ['sqlOperator'] )
   1862 
   1863 To retrieve all syntax items for both the sqlOperator and sqlType groups: >
   1864     echo syntaxcomplete#OmniSyntaxList( ['sqlOperator', 'sqlType'] )
   1865 
   1866 A regular expression can also be used: >
   1867     echo syntaxcomplete#OmniSyntaxList( ['sql\w\+'] )
   1868 
   1869 From within a plugin, you would typically assign the output to a List: >
   1870     let myKeywords = []
   1871     let myKeywords = syntaxcomplete#OmniSyntaxList( ['sqlKeyword'] )
   1872 
   1873 
   1874 SQL							*ft-sql-omni*
   1875 
   1876 Completion for the SQL language includes statements, functions, keywords.
   1877 It will also dynamically complete tables, procedures, views and column lists
   1878 with data pulled directly from within a database.  For detailed instructions
   1879 and a tutorial see |omni-sql-completion|.
   1880 
   1881 The SQL completion plugin can be used in conjunction with other completion
   1882 plugins.  For example, the PHP filetype has its own completion plugin.
   1883 Since PHP is often used to generate dynamic website by accessing a database,
   1884 the SQL completion plugin can also be enabled.  This allows you to complete
   1885 PHP code and SQL code at the same time.
   1886 
   1887 
   1888 XML							*ft-xml-omni*
   1889 
   1890 Vim 7 provides a mechanism for context aware completion of XML files.  It
   1891 depends on a special |xml-omni-datafile| and two commands: |:XMLns| and
   1892 |:XMLent|.  Features are:
   1893 
   1894 - after "<" complete the tag name, depending on context
   1895 - inside of a tag complete proper attributes
   1896 - when an attribute has a limited number of possible values help to complete
   1897   them
   1898 - complete names of entities (defined in |xml-omni-datafile| and in the
   1899   current file with "<!ENTITY" declarations)
   1900 - when used after "</" CTRL-X CTRL-O will close the last opened tag
   1901 
   1902 Format of XML data file					*xml-omni-datafile*
   1903 
   1904 XML data files are stored in the "autoload/xml" directory in 'runtimepath'.
   1905 Vim distribution provides examples of data files in the
   1906 "$VIMRUNTIME/autoload/xml" directory.  They have a meaningful name which will
   1907 be used in commands.  It should be a unique name which will not create
   1908 conflicts.  For example, the name xhtml10s.vim means it is the data file for
   1909 XHTML 1.0 Strict.
   1910 
   1911 Each file contains a variable with a name like g:xmldata_xhtml10s .  It is
   1912 a compound from two parts:
   1913 
   1914 1. "g:xmldata_"  general prefix, constant for all data files
   1915 2. "xhtml10s"    the name of the file and the name of the described XML
   1916 		 dialect; it will be used as an argument for the |:XMLns|
   1917 		 command
   1918 
   1919 Part two must be exactly the same as name of file.
   1920 
   1921 The variable is a |Dictionary|.  Keys are tag names and each value is a two
   1922 element |List|.  The first element of the List is also a List with the names
   1923 of possible children.  The second element is a |Dictionary| with the names of
   1924 attributes as keys and the possible values of attributes as values.  Example: >
   1925 
   1926     let g:xmldata_crippled = {
   1927     \ "vimxmlentities": ["amp", "lt", "gt", "apos", "quot"],
   1928     \ 'vimxmlroot': ['tag1'],
   1929     \ 'tag1':
   1930     \ [ ['childoftag1a', 'childoftag1b'], {'attroftag1a': [],
   1931     \ 'attroftag1b': ['valueofattr1', 'valueofattr2']}],
   1932     \ 'childoftag1a':
   1933     \ [ [], {'attrofchild': ['attrofchild']}],
   1934     \ 'childoftag1b':
   1935     \ [ ['childoftag1a'], {'attrofchild': []}],
   1936     \ "vimxmltaginfo": {
   1937     \ 'tag1': ['Menu info', 'Long information visible in preview window']},
   1938     \ 'vimxmlattrinfo': {
   1939     \ 'attrofchild': ['Menu info', 'Long information visible in preview window']}}
   1940 
   1941 This example would be put in the "autoload/xml/crippled.vim" file and could
   1942 help to write this file: >
   1943 
   1944     <tag1 attroftag1b="valueofattr1">
   1945         <childoftag1a attrofchild>
   1946                 &amp; &lt;
   1947         </childoftag1a>
   1948         <childoftag1b attrofchild="5">
   1949             <childoftag1a>
   1950                 &gt; &apos; &quot;
   1951             </childoftag1a>
   1952         </childoftag1b>
   1953     </tag1>
   1954 
   1955 In the example four special elements are visible:
   1956 
   1957 1. "vimxmlentities" - a special key with List containing entities of this XML
   1958    dialect.
   1959 2. If the list containing possible values of attributes has one element and
   1960    this element is equal to the name of the attribute this attribute will be
   1961    treated as boolean and inserted as 'attrname' and not as 'attrname="'
   1962 3. "vimxmltaginfo" - a special key with a Dictionary containing tag
   1963    names as keys and two element List as values, for additional menu info and
   1964    the long description.
   1965 4. "vimxmlattrinfo" - special key with Dictionary containing attribute names
   1966    as keys and two element List as values, for additional menu info and long
   1967    description.
   1968 
   1969 Note: Tag names in the data file MUST not contain a namespace description.
   1970 Check xsl.vim for an example.
   1971 Note: All data and functions are publicly available as global
   1972 variables/functions and can be used for personal editing functions.
   1973 
   1974 
   1975 DTD -> Vim							*dtd2vim*
   1976 
   1977 On |www| is the script |dtd2vim| which parses DTD and creates an XML data file
   1978 for Vim XML omni completion.
   1979 
   1980     dtd2vim: http://www.vim.org/scripts/script.php?script_id=1462
   1981 
   1982 Check the beginning of that file for usage details.
   1983 The script requires perl and:
   1984 
   1985     perlSGML: http://savannah.nongnu.org/projects/perlsgml
   1986 
   1987 
   1988 Commands
   1989 
   1990 :XMLns {name} [{namespace}]					*:XMLns*
   1991 
   1992 Vim has to know which data file should be used and with which namespace.  For
   1993 loading of the data file and connecting data with the proper namespace use
   1994 |:XMLns| command.  The first (obligatory) argument is the name of the data
   1995 (xhtml10s, xsl).  The second argument is the code of namespace (h, xsl).  When
   1996 used without a second argument the dialect will be used as default - without
   1997 namespace declaration.  For example to use XML completion in .xsl files: >
   1998 
   1999 	:XMLns xhtml10s
   2000 	:XMLns xsl xsl
   2001 
   2002 
   2003 :XMLent {name}							*:XMLent*
   2004 
   2005 By default entities will be completed from the data file of the default
   2006 namespace.  The XMLent command should be used in case when there is no default
   2007 namespace: >
   2008 
   2009 	:XMLent xhtml10s
   2010 
   2011 Usage
   2012 
   2013 While used in this situation (after declarations from previous part, | is
   2014 cursor position): >
   2015 
   2016 	<|
   2017 
   2018 Will complete to an appropriate XHTML tag, and in this situation: >
   2019 
   2020 	<xsl:|
   2021 
   2022 Will complete to an appropriate XSL tag.
   2023 
   2024 
   2025 The script xmlcomplete.vim, provided through the |autoload| mechanism,
   2026 has the xmlcomplete#GetLastOpenTag() function which can be used in XML files
   2027 to get the name of the last open tag (b:unaryTagsStack has to be defined): >
   2028 
   2029 	:echo xmlcomplete#GetLastOpenTag("b:unaryTagsStack")
   2030 
   2031 
   2032 
   2033 ==============================================================================
   2034 8. Insert mode commands					*inserting*
   2035 
   2036 The following commands can be used to insert new text into the buffer.  They
   2037 can all be undone and repeated with the "." command.
   2038 
   2039 							*a*
   2040 a			Append text after the cursor [count] times.  If the
   2041 			cursor is in the first column of an empty line Insert
   2042 			starts there.  But not when 'virtualedit' is set!
   2043 
   2044 							*A*
   2045 A			Append text at the end of the line [count] times.
   2046 			For using "A" in Visual block mode see |v_b_A|.
   2047 
   2048 <insert>	or				*i* *insert* *<Insert>*
   2049 i			Insert text before the cursor [count] times.
   2050 			When using CTRL-O in Insert mode |i_CTRL-O| the count
   2051 			is not supported.
   2052 
   2053 							*I*
   2054 I			Insert text before the first non-blank in the line
   2055 			[count] times.
   2056 			When the 'H' flag is present in 'cpoptions' and the
   2057 			line only contains blanks, insert start just before
   2058 			the last blank.
   2059 			For using "I" in Visual block mode see |v_b_I|.
   2060 
   2061 							*gI*
   2062 gI			Insert text in column 1 [count] times.
   2063 
   2064 							*gi*
   2065 gi			Insert text in the same position as where Insert mode
   2066 			was stopped last time in the current buffer.
   2067 			This uses the |'^| mark.  It's different from "`^i"
   2068 			when the mark is past the end of the line.
   2069 			The position is corrected for inserted/deleted lines,
   2070 			but NOT for inserted/deleted characters.
   2071 			When the |:keepjumps| command modifier is used the |'^|
   2072 			mark won't be changed.
   2073 
   2074 							*o*
   2075 o			Begin a new line below the cursor and insert text,
   2076 			repeat [count] times.
   2077 			When the '#' flag is in 'cpoptions' the count is
   2078 			ignored.
   2079 
   2080 							*O*
   2081 O			Begin a new line above the cursor and insert text,
   2082 			repeat [count] times.
   2083 			When the '#' flag is in 'cpoptions' the count is
   2084 			ignored.
   2085 
   2086 These commands are used to start inserting text.  You can end insert mode with
   2087 <Esc>.  See |mode-ins-repl| for the other special characters in Insert mode.
   2088 The effect of [count] takes place after Insert mode is exited.
   2089 
   2090 When 'autoindent' is on, the indent for a new line is obtained from the
   2091 previous line.  When 'smartindent' or 'cindent' is on, the indent for a line
   2092 is automatically adjusted for C programs.
   2093 
   2094 'formatoptions' can be set to copy the comment leader when opening a new
   2095 line.
   2096 
   2097 'textwidth' can be set to the maximum width for a line.  When a line becomes
   2098 too long when appending characters a line break is automatically inserted.
   2099 
   2100 
   2101 ==============================================================================
   2102 9. Ex insert commands					*inserting-ex*
   2103 
   2104 							*:a* *:append*
   2105 :{range}a[ppend][!]	Insert several lines of text below the specified
   2106 			line.  If the {range} is missing, the text will be
   2107 			inserted after the current line.
   2108 			Adding [!] toggles 'autoindent' for the time this
   2109 			command is executed.
   2110 			This command is not supported in |Vim9| script,
   2111 			because it is too easily confused with a variable
   2112 			name.
   2113 
   2114 							*:i* *:in* *:insert*
   2115 :{range}i[nsert][!]	Insert several lines of text above the specified
   2116 			line.  If the {range} is missing, the text will be
   2117 			inserted before the current line.
   2118 			Adding [!] toggles 'autoindent' for the time this
   2119 			command is executed.
   2120 			This command is not supported in |Vim9| script,
   2121 			because it is too easily confused with a variable
   2122 			name.
   2123 
   2124 These two commands will keep on asking for lines, until you type a line
   2125 containing only a ".".  Watch out for lines starting with a backslash, see
   2126 |line-continuation|.
   2127 
   2128 Text typed after a "|" command separator is used first.  So the following
   2129 command in ex mode: >
   2130 	:a|one
   2131 	two
   2132 	.
   2133 	:visual
   2134 appends the following text, after the cursor line: >
   2135 	one
   2136 	two
   2137 <
   2138 In |Ex-mode|, when these commands are used with |:global| or |:vglobal| then
   2139 the lines are obtained from the text following the command.  Separate lines
   2140 with a NL escaped with a backslash: >
   2141 	:global/abc/insert\
   2142 	one line\
   2143 	another line
   2144 The final "." is not needed then.
   2145 
   2146 NOTE: ":append" and ":insert" don't work properly in between ":if" and
   2147 ":endif", ":for" and ":endfor", ":while" and ":endwhile".
   2148 
   2149 							*:start* *:startinsert*
   2150 :star[tinsert][!]	Start Insert mode just after executing this command.
   2151 			Works like typing "i" in Normal mode.  When the ! is
   2152 			included it works like "A", append to the line.
   2153 			Otherwise insertion starts at the cursor position.
   2154 			Note that when using this command in a function or
   2155 			script, the insertion only starts after the function
   2156 			or script is finished.
   2157 			This command does not work from |:normal|.
   2158 
   2159 							*:stopi* *:stopinsert*
   2160 :stopi[nsert]		Stop Insert mode as soon as possible.  Works like
   2161 			typing <Esc> in Insert mode.
   2162 			Can be used in an autocommand, example: >
   2163 				:au BufEnter scratch stopinsert
   2164 <
   2165 					*replacing-ex* *:startreplace*
   2166 :startr[eplace][!]	Start Replace mode just after executing this command.
   2167 			Works just like typing "R" in Normal mode.  When the
   2168 			! is included it acts just like "$R" had been typed
   2169 			(ie. begin replace mode at the end-of-line).  Other-
   2170 			wise replacement begins at the cursor position.
   2171 			Note that when using this command in a function or
   2172 			script that the replacement will only start after
   2173 			the function or script is finished.
   2174 
   2175 							*:startgreplace*
   2176 :startg[replace][!]	Just like |:startreplace|, but use Virtual Replace
   2177 			mode, like with |gR|.
   2178 
   2179 ==============================================================================
   2180 10. Inserting a file					*inserting-file*
   2181 
   2182 							*:r* *:re* *:read*
   2183 :r[ead] [++opt] [name]
   2184 			Insert the file [name] (default: current file) below
   2185 			the cursor.
   2186 			See |++opt| for the possible values of [++opt].
   2187 
   2188 :{range}r[ead] [++opt] [name]
   2189 			Insert the file [name] (default: current file) below
   2190 			the specified line.
   2191 			See |++opt| for the possible values of [++opt].
   2192 
   2193 							*:r!* *:read!*
   2194 :[range]r[ead] [++opt] !{cmd}
   2195 			Execute {cmd} and insert its standard output below
   2196 			the cursor or the specified line.  A temporary file is
   2197 			used to store the output of the command which is then
   2198 			read into the buffer.  'shellredir' is used to save
   2199 			the output of the command, which can be set to include
   2200 			stderr or not.  {cmd} is executed like with ":!{cmd}",
   2201 			any '!' is replaced with the previous command |:!|.
   2202 			See |++opt| for the possible values of [++opt].
   2203 
   2204 These commands insert the contents of a file, or the output of a command,
   2205 into the buffer.  They can be undone.  They cannot be repeated with the "."
   2206 command.  They work on a line basis, insertion starts below the line in which
   2207 the cursor is, or below the specified line.  To insert text above the first
   2208 line use the command ":0r {name}".
   2209 
   2210 After the ":read" command, the cursor is left on the first non-blank in the
   2211 first new line.  If in Ex mode, then the cursor is left on the last new
   2212 line (sorry, this is Vi compatible).
   2213 
   2214 If a file name is given with ":r", it becomes the alternate file.  This can be
   2215 used, for example, when you want to edit that file instead: ":e! #".  This can
   2216 be switched off by removing the 'a' flag from the 'cpoptions' option.
   2217 
   2218 Of the [++opt] arguments one is specifically for ":read", the ++edit argument.
   2219 This is useful when the ":read" command is actually used to read a file into
   2220 the buffer as if editing that file.  Use this command in an empty buffer: >
   2221 	:read ++edit filename
   2222 The effect is that the 'fileformat', 'fileencoding', 'bomb', etc. options are
   2223 set to what has been detected for "filename".  Note that a single empty line
   2224 remains, you may want to delete it.
   2225 
   2226 							*file-read*
   2227 The 'fileformat' option sets the <EOL> style for a file:
   2228 'fileformat'    characters	   name				~
   2229   "dos"		<CR><NL> or <NL>   DOS format
   2230   "unix"	<NL>		   Unix format
   2231   "mac"		<CR>		   Mac format
   2232 Previously 'textmode' was used.  It is obsolete now.
   2233 
   2234 If 'fileformat' is "dos", a <CR> in front of an <NL> is ignored and a CTRL-Z
   2235 at the end of the file is ignored.
   2236 
   2237 If 'fileformat' is "mac", a <NL> in the file is internally represented by a
   2238 <CR>.  This is to avoid confusion with a <NL> which is used to represent a
   2239 <NUL>.  See |CR-used-for-NL|.
   2240 
   2241 If the 'fileformats' option is not empty Vim tries to recognize the type of
   2242 <EOL> (see |file-formats|).  However, the 'fileformat' option will not be
   2243 changed, the detected format is only used while reading the file.
   2244 A similar thing happens with 'fileencodings'.
   2245 
   2246 On non-Win32 systems the message "[dos format]" is shown if a file is read in
   2247 DOS format, to remind you that something unusual is done.
   2248 On Macintosh and Win32 the message "[unix format]" is shown if a file is read
   2249 in Unix format.
   2250 On non-Macintosh systems, the message "[mac format]" is shown if a file is
   2251 read in Mac format.
   2252 
   2253 An example on how to use ":r !": >
   2254 	:r !uuencode binfile binfile
   2255 This command reads "binfile", uuencodes it and reads it into the current
   2256 buffer.  Useful when you are editing e-mail and want to include a binary
   2257 file.
   2258 
   2259 							*read-messages*
   2260 When reading a file Vim will display a message with information about the read
   2261 file.  In the table is an explanation for some of the items.  The others are
   2262 self explanatory.  Using the long or the short version depends on the
   2263 'shortmess' option.
   2264 
   2265 	long		short		meaning ~
   2266 	[readonly]	{RO}		the file is write protected
   2267 	[fifo/socket]			using a stream
   2268 	[fifo]				using a fifo stream
   2269 	[socket]			using a socket stream
   2270 	[CR missing]			reading with "dos" 'fileformat' and a
   2271 					NL without a preceding CR was found.
   2272 	[NL found]			reading with "mac" 'fileformat' and a
   2273 					NL was found (could be "unix" format)
   2274 	[long lines split]		at least one line was split in two
   2275 	[NOT converted]			conversion from 'fileencoding' to
   2276 					'encoding' was desired but not
   2277 					possible
   2278 	[converted]			conversion from 'fileencoding' to
   2279 					'encoding' done
   2280 	[crypted]			file was decrypted
   2281 	[READ ERRORS]			not all of the file could be read
   2282 
   2283 
   2284  vim:tw=78:ts=8:noet:ft=help:norl: