VIM: insert

## INSERT

    *insert.txt*    For Vim version 9.1.  Last change: 2025 Sep 16

    		  VIM REFERENCE MANUAL    by Bram Moolenaar

    						*Insert* *Insert-mode*
    Inserting and replacing text				*mode-ins-repl*

    Most of this file is about Insert and Replace mode.  At the end are a few
    commands for inserting text in other ways.

    An overview of the most often used commands can be found in chapter 24 of the
    user manual |usr_24|.

    1. Special keys						|ins-special-keys|
    2. Special special keys					|ins-special-special|
    3. 'textwidth' and 'wrapmargin' options			|ins-textwidth|
    4. 'expandtab', 'smarttab' and 'softtabstop'  options	|ins-expandtab|
    5. Replace mode						|Replace-mode|
    6. Virtual Replace mode					|Virtual-Replace-mode|
    7. Insert mode completion				|ins-completion|
    8. Insert mode commands					|inserting|
    9. Ex insert commands					|inserting-ex|
    10. Inserting a file					|inserting-file|

    Also see 'virtualedit', for moving the cursor to positions where there is no
    character.  Useful for editing a table.

    1. Special keys						*ins-special-keys*

    In Insert and Replace mode, the following characters have a special meaning;
    other characters are inserted directly.  To insert one of these special
    characters into the buffer, precede it with CTRL-V.  To insert a <Nul>
    character use "CTRL-V CTRL-@" or "CTRL-V 000".  On some systems, you have to
    use "CTRL-V 003" to insert a CTRL-C.  Note: When CTRL-V is mapped you can
    often use CTRL-Q instead |i_CTRL-Q|.

    If you are working in a special language mode when inserting text, see the
    'langmap' option, 'langmap', on how to avoid switching this mode on and off
    all the time.

    If you have 'insertmode' set, <Esc> and a few other keys get another meaning.
    See 'insertmode'.

    char		action

    						*i_CTRL-[* *i_<Esc>*
    <Esc> or CTRL-[	End insert or Replace mode, go back to Normal mode.  Finish
    		abbreviation.
    		Note: If your <Esc> key is hard to hit on your keyboard, train
    		yourself to use CTRL-[.
    		If Esc doesn't work and you are using a Mac, try CTRL-<Esc>.
    		Or disable Listening under Accessibility preferences.
    						*i_CTRL-C*
    CTRL-C		Quit insert mode, go back to Normal mode.  Do not check for
    		abbreviations.  Does not trigger the |InsertLeave| autocommand
    		event.

    						*i_CTRL-@*
    CTRL-@		Insert previously inserted text and stop insert.

    						*i_CTRL-A*
    CTRL-A		Insert previously inserted text.

    						*i_CTRL-H* *i_<BS>* *i_BS*
    <BS> or CTRL-H	Delete the character before the cursor (see |i_backspacing|
    		about joining lines).
    		See |:fixdel| if your <BS> key does not do what you want.

    						*i_<Del>* *i_DEL*
    <Del>		Delete the character under the cursor.  If the cursor is at
    		the end of the line, and the 'backspace' option includes
    		"eol", delete the <EOL>; the next line is appended after the
    		current one.
    		See |:fixdel| if your <Del> key does not do what you want.
    						*i_CTRL-W*
    CTRL-W		Delete the word before the cursor (see |i_backspacing| about
    		joining lines).  See the section "word motions",
    		|word-motions|, for the definition of a word.
    						*i_CTRL-U*
    CTRL-U		Delete all entered characters before the cursor in the current
    		line.  If there are no newly entered characters and
    		'backspace' is not empty, delete all characters before the
    		cursor in the current line.
    		If C-indenting is enabled the indent will be adjusted if the
    		line becomes blank.
    		See |i_backspacing| about joining lines.
    						*i_CTRL-I* *i_<Tab>* *i_Tab*
    <Tab> or CTRL-I Insert a tab.  If the 'expandtab' option is on, the
    		equivalent number of spaces is inserted (use CTRL-V <Tab> to
    		avoid the expansion; use CTRL-Q <Tab> if CTRL-V is mapped
    		|i_CTRL-Q|).  See also the 'smarttab' option and
    		|ins-expandtab|.
    						*i_CTRL-J* *i_<NL>*
    <NL> or CTRL-J	Begin new line.
    						*i_CTRL-M* *i_<CR>*
    <CR> or CTRL-M	Begin new line.
    						*i_CTRL-K*
    CTRL-K {char1} [char2]
    		Enter digraph (see |digraphs|).  When {char1} is a special
    		key, the code for that key is inserted in <> form.  For
    		example, the string "<S-Space>" can be entered by typing
    		<C-K><S-Space> (two keys).  Neither char is considered for
    		mapping.

    CTRL-N		Find next keyword (see |i_CTRL-N|).
    CTRL-P		Find previous keyword (see |i_CTRL-P|).

    CTRL-R {register}				*i_CTRL-R*
    		Insert the contents of a register.  Between typing CTRL-R and
    		the second character, '"' will be displayed to indicate that
    		you are expected to enter the name of a register.
    		The text is inserted as if you typed it, but mappings and
    		abbreviations are not used.  If you have options like
    		'textwidth', 'formatoptions', or 'autoindent' set, this will
    		influence what will be inserted.  This is different from what
    		happens with the "p" command and pasting with the mouse.
    		Special registers:
    			'"'	the unnamed register, containing the text of
    				the last delete or yank
    			'%'	the current file name
    			'#'	the alternate file name
    			'*'	the clipboard contents (X11: primary selection)
    			'+'	the clipboard contents
    			'/'	the last search pattern
    			':'	the last command-line
    			'.'	the last inserted text
    							*i_CTRL-R_-*
    			'-'	the last small (less than a line) delete
    				register. This is repeatable using |.| since
    				it remembers the register to put instead of
    				the literal text to insert.
    							*i_CTRL-R_=*
    			'='	the expression register: you are prompted to
    				enter an expression (see |expression|)
    				Note that 0x80 (128 decimal) is used for
    				special keys.  E.g., you can use this to move
    				the cursor up:
    					CTRL-R ="\<Up>"
    				Use CTRL-R CTRL-R to insert text literally.
    				When the result is a |List| the items are used
    				as lines.  They can have line breaks inside
    				too.
    				When the result is a Float it's automatically
    				converted to a String.
    				When append() or setline() is invoked the undo
    				sequence will be broken.
    		See |registers| about registers.

    CTRL-R CTRL-R {register}			*i_CTRL-R_CTRL-R*
    		Insert the contents of a register.  Works like using a single
    		CTRL-R, but the text is inserted literally, not as if typed.
    		This differs when the register contains characters like <BS>.
    		Example, where register a contains "ab^Hc":
    	CTRL-R a		results in "ac".
    	CTRL-R CTRL-R a		results in "ab^Hc".
    		Options 'textwidth', 'formatoptions', etc. still apply.  If
    		you also want to avoid these, use CTRL-R CTRL-O, see below.
    		The '.' register (last inserted text) is still inserted as
    		typed.
    		After this command, the '.' register contains the text from
    		the register as if it was inserted by typing it.

    CTRL-R CTRL-O {register}			*i_CTRL-R_CTRL-O*
    		Insert the contents of a register literally and don't
    		auto-indent.  Does the same as pasting with the mouse
    		|<MiddleMouse>|. When the register is linewise this will
    		insert the text above the current line, like with `P`.
    		The '.' register (last inserted text) is still inserted as
    		typed.
    		After this command, the '.' register contains the command
    		typed and not the text. I.e., the literals "^R^O" and not the
    		text from the register.
    		Does not replace characters in |Replace-mode|!

    CTRL-R CTRL-P {register}			*i_CTRL-R_CTRL-P*
    		Insert the contents of a register literally and fix the
    		indent, like |[<MiddleMouse>|.
    		The '.' register (last inserted text) is still inserted as
    		typed.
    		After this command, the '.' register contains the command
    		typed and not the text. I.e., the literals "^R^P" and not the
    		text from the register.
    		Does not replace characters in |Replace-mode|!

    						*i_CTRL-T*
    CTRL-T		Insert one shiftwidth of indent at the start of the current
    		line.  The indent is always rounded to a 'shiftwidth' (this is
    		vi compatible).
    						*i_CTRL-D*
    CTRL-D		Delete one shiftwidth of indent at the start of the current
    		line.  The indent is always rounded to a 'shiftwidth' (this is
    		vi compatible).
    						*i_0_CTRL-D*
    0 CTRL-D	Delete all indent in the current line.

    						*i_^_CTRL-D*
    ^ CTRL-D	Delete all indent in the current line.  The indent is
    		restored in the next line.  This is useful when inserting a
    		label.

    						*i_CTRL-V*
    CTRL-V		Insert next non-digit literally.  For special keys, the
    		terminal code is inserted.  It's also possible to enter the
    		decimal, octal or hexadecimal value of a character
    		|i_CTRL-V_digit|.
    		The characters typed right after CTRL-V are not considered for
    		mapping.
    		Note: When CTRL-V is mapped (e.g., to paste text) you can
    		often use CTRL-Q instead |i_CTRL-Q|.
    		When |modifyOtherKeys| is enabled then special Escape sequence
    		is converted back to what it was without |modifyOtherKeys|,
    		unless the Shift key is also pressed.

    						*i_CTRL-Q*
    CTRL-Q		Same as CTRL-V.
    		Note: Some terminal connections may eat CTRL-Q, it doesn't
    		work then.  It does work in the GUI.

    CTRL-SHIFT-V				*i_CTRL-SHIFT-V* *i_CTRL-SHIFT-Q*
    CTRL-SHIFT-Q	Works just like CTRL-V, unless |modifyOtherKeys| is active,
    		then it inserts the Escape sequence for a key with modifiers.
    		Note: When CTRL-SHIFT-V is intercepted by your system (e.g.,
    		to paste text) you can often use CTRL-SHIFT-Q instead.
    		However, in some terminals (e.g. GNOME Terminal), CTRL-SHIFT-Q
    		quits the terminal without confirmation.

    CTRL-X		Enter CTRL-X mode.  This is a sub-mode where commands can
    		be given to complete words or scroll the window.  See
    		|i_CTRL-X| and |ins-completion|.

    						*i_CTRL-E*
    CTRL-E		Insert the character which is below the cursor.
    						*i_CTRL-Y*
    CTRL-Y		Insert the character which is above the cursor.
    		Note that for CTRL-E and CTRL-Y 'textwidth' is not used, to be
    		able to copy characters from a long line.

    						*i_CTRL-_*
    CTRL-_		Switch between languages, as follows:
    		-  When in a rightleft window, revins and nohkmap are toggled,
    		   since English will likely be inserted in this case.
    		-  When in a norightleft window, revins and hkmap are toggled,
    		   since Hebrew will likely be inserted in this case.

    		CTRL-_ moves the cursor to the end of the typed text.

    		This command is only available when the 'allowrevins' option
    		is set.
    		Please refer to |rileft| for more information about
    		right-to-left mode.
    		Only if compiled with the |+rightleft| feature.

    						*i_CTRL-^*
    CTRL-^		Toggle the use of typing language characters.
    		When language |:lmap| mappings are defined:
    		- If 'iminsert' is 1 (langmap mappings used) it becomes 0 (no
    		  langmap mappings used).
    		- If 'iminsert' has another value it becomes 1, thus langmap
    		  mappings are enabled.
    		When no language mappings are defined:
    		- If 'iminsert' is 2 (Input Method used) it becomes 0 (no
    		  Input Method used).
    		- If 'iminsert' has another value it becomes 2, thus the Input
    		  Method is enabled.
    		When set to 1, the value of the "b:keymap_name" variable, the
    		'keymap' option or "<lang>" appears in the status line.
    		The language mappings are normally used to type characters
    		that are different from what the keyboard produces.  The
    		'keymap' option can be used to install a whole number of them.

    						*i_CTRL-]*
    CTRL-]		Trigger abbreviation, without inserting a character.

    						*i_<Insert>*
    <Insert>	Toggle between Insert and Replace mode.

    						*i_backspacing*
    The effect of the <BS>, CTRL-W, and CTRL-U depend on the 'backspace' option
    (unless 'revins' is set).  This is a comma-separated list of items:

    item	    action
    indent	    allow backspacing over autoindent
    eol	    allow backspacing over line breaks (join lines)
    start	    allow backspacing over the start of insert; CTRL-W and CTRL-U stop
    	    once at the start of insert.
    nostop	    like start, except CTRL-W and CTRL-U do not stop at the start of
    	    insert.

    When 'backspace' is empty, Vi compatible backspacing is used.  You cannot
    backspace over autoindent, before column 1 or before where insert started.

    For backwards compatibility the values "0", "1", "2" and "3" are also allowed,
    see 'backspace'.

    If the 'backspace' option does contain "eol" and the cursor is in column 1
    when one of the three keys is used, the current line is joined with the
    previous line.  This effectively deletes the <EOL> in front of the cursor.

    						*i_CTRL-V_digit*
    With CTRL-V the decimal, octal or hexadecimal value of a character can be
    entered directly.  This way you can enter any character, except a line break
    (<NL>, value 10).  There are five ways to enter the character value:

    first char	mode	     max nr of chars   max value
    (none)		decimal		   3		255
    o or O		octal		   3		377	 (255)
    x or X		hexadecimal	   2		ff	 (255)
    u		hexadecimal	   4		ffff	 (65535)
    U		hexadecimal	   8		7fffffff (2147483647)

    Normally you would type the maximum number of characters.  Thus to enter a
    space (value 32) you would type <C-V>032.  You can omit the leading zero, in
    which case the character typed after the number must be a non-digit.  This
    happens for the other modes as well: As soon as you type a character that is
    invalid for the mode, the value before it will be used and the "invalid"
    character is dealt with in the normal way.

    If you enter a value of 10, it will end up in the file as a 0.  The 10 is a
    <NL>, which is used internally to represent the <Nul> character.  When writing
    the buffer to a file, the <NL> character is translated into <Nul>.  The <NL>
    character is written at the end of each line.  Thus if you want to insert a
    <NL> character in a file you will have to make a line break.
    Also see 'fileformat'.

    						*i_CTRL-X* *insert_expand*
    CTRL-X enters a sub-mode where several commands can be used.  Most of these
    commands do keyword completion; see |ins-completion|.

    Two commands can be used to scroll the window up or down, without exiting
    insert mode:

    						*i_CTRL-X_CTRL-E*
    CTRL-X CTRL-E		scroll window one line up.
    			When doing completion look here: |complete_CTRL-E|

    						*i_CTRL-X_CTRL-Y*
    CTRL-X CTRL-Y		scroll window one line down.
    			When doing completion look here: |complete_CTRL-Y|

    After CTRL-X is pressed, each CTRL-E (CTRL-Y) scrolls the window up (down) by
    one line unless that would cause the cursor to move from its current position
    in the file.  As soon as another key is pressed, CTRL-X mode is exited and
    that key is interpreted as in Insert mode.

    2. Special special keys				*ins-special-special*

    The following keys are special.  They stop the current insert, do something,
    and then restart insertion.  This means you can do something without getting
    out of Insert mode.  This is very handy if you prefer to use the Insert mode
    all the time, just like editors that don't have a separate Normal mode.  You
    may also want to set the 'backspace' option to "indent,eol,start" and set the
    'insertmode' option.  You can use CTRL-O if you want to map a function key to
    a command.

    The changes (inserted or deleted characters) before and after these keys can
    be undone separately.  Only the last change can be redone and always behaves
    like an "i" command.

    char		action

    <Up>		cursor one line up			     *i_<Up>*
    <Down>		cursor one line down			     *i_<Down>*
    CTRL-G <Up>	cursor one line up, insert start column	     *i_CTRL-G_<Up>*
    CTRL-G k	cursor one line up, insert start column	     *i_CTRL-G_k*
    CTRL-G CTRL-K	cursor one line up, insert start column	     *i_CTRL-G_CTRL-K*
    CTRL-G <Down>	cursor one line down, insert start column    *i_CTRL-G_<Down>*
    CTRL-G j	cursor one line down, insert start column    *i_CTRL-G_j*
    CTRL-G CTRL-J	cursor one line down, insert start column    *i_CTRL-G_CTRL-J*
    <Left>		cursor one character left		     *i_<Left>*
    <Right>		cursor one character right		     *i_<Right>*
    <S-Left>	cursor one word back (like "b" command)	     *i_<S-Left>*
    <C-Left>	cursor one word back (like "b" command)	     *i_<C-Left>*
    <S-Right>	cursor one word forward (like "w" command)   *i_<S-Right>*
    <C-Right>	cursor one word forward (like "w" command)   *i_<C-Right>*
    <Home>		cursor to first char in the line	     *i_<Home>*
    <End>		cursor to after last char in the line	     *i_<End>*
    <C-Home>	cursor to first char in the file	     *i_<C-Home>*
    <C-End>		cursor to after last char in the file	     *i_<C-End>*
    <LeftMouse>	cursor to position of mouse click	     *i_<LeftMouse>*
    <S-Up>		move window one page up			     *i_<S-Up>*
    <PageUp>	move window one page up			     *i_<PageUp>*
    <S-Down>	move window one page down		     *i_<S-Down>*
    <PageDown>	move window one page down		     *i_<PageDown>*
    <ScrollWheelDown>    move window three lines down	*i_<ScrollWheelDown>*
    <S-ScrollWheelDown>  move window one page down		*i_<S-ScrollWheelDown>*
    <ScrollWheelUp>      move window three lines up		*i_<ScrollWheelUp>*
    <S-ScrollWheelUp>    move window one page up		*i_<S-ScrollWheelUp>*
    <ScrollWheelLeft>    move window six columns left	*i_<ScrollWheelLeft>*
    <S-ScrollWheelLeft>  move window one page left		*i_<S-ScrollWheelLeft>*
    <ScrollWheelRight>   move window six columns right	*i_<ScrollWheelRight>*
    <S-ScrollWheelRight> move window one page right		*i_<S-ScrollWheelRight>*
    CTRL-O		execute one command, return to Insert mode   *i_CTRL-O*
    CTRL-\ CTRL-O	like CTRL-O but don't move the cursor	     *i_CTRL-\_CTRL-O*
    CTRL-L		when 'insertmode' is set: go to Normal mode  *i_CTRL-L*
    CTRL-G u	close undo sequence, start new change	     *i_CTRL-G_u*
    CTRL-G U	don't start a new undo block with the next   *i_CTRL-G_U*
    		left/right cursor movement, if the cursor
    		stays within the same line

    Note: If the cursor keys take you out of Insert mode, check the 'noesckeys'
    option.

    The CTRL-O command sometimes has a side effect: If the cursor was beyond the
    end of the line, it will be put on the last character in the line.  In
    mappings it's often better to use <Esc> (first put an "x" in the text, <Esc>
    will then always put the cursor on it).  Or use CTRL-\ CTRL-O, but then
    beware of the cursor possibly being beyond the end of the line.  Note that the
    command following CTRL-\ CTRL-O can still move the cursor, it is not restored
    to its original position.

    The CTRL-O command takes you to Normal mode.  If you then use a command enter
    Insert mode again it normally doesn't nest.  Thus when typing "a<C-O>a" and
    then <Esc> takes you back to Normal mode, you do not need to type <Esc> twice.
    An exception is when not typing the command, e.g. when executing a mapping or
    sourcing a script.  This makes mappings work that briefly switch to Insert
    mode.

    The shifted cursor keys are not available on all terminals.

    Another side effect is that a count specified before the "i" or "a" command is
    ignored.  That is because repeating the effect of the command after CTRL-O is
    too complicated.

    An example for using CTRL-G u:

    	:inoremap <C-H> <C-G>u<C-H>

    This redefines the backspace key to start a new undo sequence.  You can now
    undo the effect of the backspace key, without changing what you typed before
    that, with CTRL-O u.  Another example:

    	:inoremap <CR> <C-]><C-G>u<CR>

    This starts a new undo block at each line break.  It also expands
    abbreviations before this.

    An example for using CTRL-G U:

    	inoremap <Left>  <C-G>U<Left>
    	inoremap <Right> <C-G>U<Right>
    	inoremap <expr> <Home> col('.') == match(getline('.'), '\S') + 1 ?
    	 \ repeat('<C-G>U<Left>', col('.') - 1) :
    	 \ (col('.') < match(getline('.'), '\S') ?
    	 \     repeat('<C-G>U<Right>', match(getline('.'), '\S') + 0) :
    	 \     repeat('<C-G>U<Left>', col('.') - 1 - match(getline('.'), '\S')))
    	inoremap <expr> <End> repeat('<C-G>U<Right>', col('$') - col('.'))
    	inoremap ( ()<C-G>U<Left>

    This makes it possible to use the cursor keys in Insert mode, without starting
    a new undo block and therefore using |.| (redo) will work as expected.  Also
    entering a text like (with the "(" mapping from above):

       Lorem ipsum (dolor

    will be repeatable by using |.| to the expected

       Lorem ipsum (dolor)

    Using CTRL-O splits undo: the text typed before and after it is undone
    separately.  If you want to avoid this (e.g., in a mapping) you might be able
    to use CTRL-R = |i_CTRL-R|.  E.g., to call a function:
    	:imap <F2> <C-R>=MyFunc()<CR>

    When the 'whichwrap' option is set appropriately, the <Left> and <Right>
    keys on the first/last character in the line make the cursor wrap to the
    previous/next line.

    The CTRL-G j and CTRL-G k commands can be used to insert text in front of a
    column.  Example:
       int i;
       int j;
    Position the cursor on the first "int", type "istatic <C-G>j       ".  The
    result is:
       static int i;
    	  int j;
    When inserting the same text in front of the column in every line, use the
    Visual blockwise command "I" |v_b_I|.

    3. 'textwidth' and 'wrapmargin' options			*ins-textwidth*

    The 'textwidth' option can be used to automatically break a line before it
    gets too long.  Set the 'textwidth' option to the desired maximum line
    length.  If you then type more characters (not spaces or tabs), the
    last word will be put on a new line (unless it is the only word on the
    line).  If you set 'textwidth' to 0, this feature is disabled.

    The 'wrapmargin' option does almost the same.  The difference is that
    'textwidth' has a fixed width while 'wrapmargin' depends on the width of the
    screen.  When using 'wrapmargin' this is equal to using 'textwidth' with a
    value equal to (columns - 'wrapmargin'), where columns is the width of the
    screen.

    When 'textwidth' and 'wrapmargin' are both set, 'textwidth' is used.

    If you don't really want to break the line, but view the line wrapped at a
    convenient place, see the 'linebreak' option.

    The line is only broken automatically when using Insert mode, or when
    appending to a line.  When in replace mode and the line length is not
    changed, the line will not be broken.

    Long lines are broken if you enter a non-white character after the margin.
    The situations where a line will be broken can be restricted by adding
    characters to the 'formatoptions' option:
    "l"  Only break a line if it was not longer than 'textwidth' when the insert
         started.
    "v"  Only break at a white character that has been entered during the
         current insert command.  This is mostly Vi-compatible.
    "lv" Only break if the line was not longer than 'textwidth' when the insert
         started and only at a white character that has been entered during the
         current insert command.  Only differs from "l" when entering non-white
         characters while crossing the 'textwidth' boundary.

    Normally an internal function will be used to decide where to break the line.
    If you want to do it in a different way set the 'formatexpr' option to an
    expression that will take care of the line break.

    If you want to format a block of text, you can use the "gq" operator.  Type
    "gq" and a movement command to move the cursor to the end of the block.  In
    many cases, the command "gq}" will do what you want (format until the end of
    paragraph).  Alternatively, you can use "gqap", which will format the whole
    paragraph, no matter where the cursor currently is.  Or you can use Visual
    mode: hit "v", move to the end of the block, and type "gq".  See also |gq|.

    4. 'expandtab', 'softtabstop' and 'smarttab' options	*ins-expandtab*

    If the 'expandtab' option is on, spaces will be used to fill the amount of
    whitespace of the tab.  If you want to enter a real <Tab>, type CTRL-V first
    (use CTRL-Q when CTRL-V is mapped |i_CTRL-Q|).
    The 'expandtab' option is off by default.  Note that in Replace mode, a single
    character is replaced with several spaces.  The result of this is that the
    number of characters in the line increases.  Backspacing will delete one
    space at a time.  The original character will be put back for only one space
    that you backspace over (the last one).

    							*ins-softtabstop*
    When the 'softtabstop' option is non-zero, a <Tab> inserts 'softtabstop'
    positions, and a <BS> used to delete white space, will delete 'softtabstop'
    positions.  This feels like 'tabstop' was set to 'softtabstop', but a real
    <Tab> character still takes 'tabstop' positions, so your file will still look
    correct when used by other applications.

    If 'softtabstop' is non-zero, a <BS> will try to delete as much white space to
    move to the previous 'softtabstop' position, except when the previously
    inserted character is a space, then it will only delete the character before
    the cursor.  Otherwise you cannot always delete a single character before the
    cursor.  You will have to delete 'softtabstop' characters first, and then type
    extra spaces to get where you want to be.

    							*ins-smarttab*
    When the 'smarttab' option is on, the <Tab> key indents by 'shiftwidth' if the
    cursor is in leading whitespace.  The <BS> key has the opposite effect. This
    behaves as if 'softtabstop' were set to the value of 'shiftwidth'. This option
    allows the user to set 'softtabstop' to a value other than 'shiftwidth' and
    still use the <Tab> key for indentation.

    5. Replace mode				*Replace* *Replace-mode* *mode-replace*

    Enter Replace mode with the "R" command in normal mode.

    In Replace mode, one character in the line is deleted for every character you
    type.  If there is no character to delete (at the end of the line), the
    typed character is appended (as in Insert mode).  Thus the number of
    characters in a line stays the same until you get to the end of the line.
    If a <NL> is typed, a line break is inserted and no character is deleted.

    Be careful with <Tab> characters.  If you type a normal printing character in
    its place, the number of characters is still the same, but the number of
    columns will become smaller.

    If you delete characters in Replace mode (with <BS>, CTRL-W, or CTRL-U), what
    happens is that you delete the changes.  The characters that were replaced
    are restored.  If you had typed past the existing text, the characters you
    added are deleted.  This is effectively a character-at-a-time undo.

    If the 'expandtab' option is on, a <Tab> will replace one character with
    several spaces.  The result of this is that the number of characters in the
    line increases.  Backspacing will delete one space at a time.  The original
    character will be put back for only one space that you backspace over (the
    last one).

    6. Virtual Replace mode		*vreplace-mode* *Virtual-Replace-mode*

    Enter Virtual Replace mode with the "gR" command in normal mode.
    {not available when compiled without the |+vreplace| feature}

    Virtual Replace mode is similar to Replace mode, but instead of replacing
    actual characters in the file, you are replacing screen real estate, so that
    characters further on in the file never appear to move.

    So if you type a <Tab> it may replace several normal characters, and if you
    type a letter on top of a <Tab> it may not replace anything at all, since the
    <Tab> will still line up to the same place as before.

    Typing a <NL> still doesn't cause characters later in the file to appear to
    move.  The rest of the current line will be replaced by the <NL> (that is,
    they are deleted), and replacing continues on the next line.  A new line is
    NOT inserted unless you go past the end of the file.

    Interesting effects are seen when using CTRL-T and CTRL-D.  The characters
    before the cursor are shifted sideways as normal, but characters later in the
    line still remain still.  CTRL-T will hide some of the old line under the
    shifted characters, but CTRL-D will reveal them again.

    As with Replace mode, using <BS> etc will bring back the characters that were
    replaced.  This still works in conjunction with 'smartindent', CTRL-T and
    CTRL-D, 'expandtab', 'smarttab', 'softtabstop', etc.

    In 'list' mode, Virtual Replace mode acts as if it was not in 'list' mode,
    unless "L" is in 'cpoptions'.

    Note that the only situations for which characters beyond the cursor should
    appear to move are in List mode 'list', and occasionally when 'wrap' is set
    (and the line changes length to become shorter or wider than the width of the
    screen).  In other cases spaces may be inserted to avoid following characters
    to move.

    This mode is very useful for editing <Tab> separated columns in tables, for
    entering new data while keeping all the columns aligned.

    7. Insert mode completion				*ins-completion*

    In Insert and Replace mode, there are several commands to complete part of a
    keyword or line that has been typed.  This is useful if you are using
    complicated keywords (e.g., function names with capitals and underscores).

    Completion can be done for:

    1. Whole lines						|i_CTRL-X_CTRL-L|
    2. keywords in the current file				|i_CTRL-X_CTRL-N|
    3. keywords in 'dictionary'				|i_CTRL-X_CTRL-K|
    4. keywords in 'thesaurus', thesaurus-style		|i_CTRL-X_CTRL-T|
    5. keywords in the current and included files		|i_CTRL-X_CTRL-I|
    6. tags							|i_CTRL-X_CTRL-]|
    7. file names						|i_CTRL-X_CTRL-F|
    8. definitions or macros				|i_CTRL-X_CTRL-D|
    9. Vim command-line					|i_CTRL-X_CTRL-V|
    10. User defined completion				|i_CTRL-X_CTRL-U|
    11. omni completion					|i_CTRL-X_CTRL-O|
    12. Spelling suggestions				|i_CTRL-X_s|
    13. completions from 'complete'				|i_CTRL-N| |i_CTRL-P|
    14. contents from registers				|i_CTRL-X_CTRL-R|

    Additionally, |i_CTRL-X_CTRL-Z| stops completion without changing the text.

    All these, except CTRL-N and CTRL-P, are done in CTRL-X mode.  This is a
    sub-mode of Insert and Replace modes.  You enter CTRL-X mode by typing CTRL-X
    and one of the CTRL-X commands.  You exit CTRL-X mode by typing a key that is
    not a valid CTRL-X mode command.  Valid keys are the CTRL-X command itself,
    CTRL-N (next), and CTRL-P (previous).

    By default, the possible completions are showed in a menu and the first
    completion is inserted into the text. This can be adjusted with 'completeopt'.

    To get the current completion information, |complete_info()| can be used.
    Also see the 'infercase' option if you want to adjust the case of the match.

    When inserting a selected candidate word from the |popup-menu|, the part of
    the candidate word that does not match the query is highlighted using
    |hl-ComplMatchIns|.  If fuzzy is enabled in 'completeopt', highlighting will
    not be applied.

    							*complete_CTRL-E*
    When completion is active you can use CTRL-E to stop it and go back to the
    originally typed text.  The CTRL-E will not be inserted.

    							*complete_CTRL-Y*
    When the popup menu is displayed you can use CTRL-Y to stop completion and
    accept the currently selected entry.  The CTRL-Y is not inserted.  Typing a
    space, Enter, or some other unprintable character will leave completion mode
    and insert that typed character.

    When the popup menu is displayed there are a few more special keys, see
    |popupmenu-keys|.

    Note: The keys that are valid in CTRL-X mode are not mapped.  This allows for
    `:map <C-F> <C-X><C-F>` to work (assuming "<" is not in 'cpo').  The key that
    ends CTRL-X mode (any key that is not a valid CTRL-X mode command) is mapped.
    Also, when doing completion with 'complete' mappings apply as usual.

    								*E565*
    Note: While completion is active Insert mode can't be used recursively and
    buffer text cannot be changed.  Mappings that somehow invoke ":normal i.."
    will generate an E565 error.

    The following mappings are suggested to make typing the completion commands
    a bit easier (although they will hide other commands; this requires "<" is not
    in 'cpo'):
        :inoremap <C-]> <C-X><C-]>
        :inoremap <C-F> <C-X><C-F>
        :inoremap <C-D> <C-X><C-D>
        :inoremap <C-L> <C-X><C-L>

    As a special case, typing CTRL-R to perform register insertion (see
    |i_CTRL-R|) will not exit CTRL-X mode.  This is primarily to allow the use of
    the '=' register to call some function to determine the next operation.  If
    the contents of the register (or result of the '=' register evaluation) are
    not valid CTRL-X mode keys, then CTRL-X mode will be exited as if those keys
    had been typed.

    For example, the following will map <Tab> to either actually insert a <Tab> if
    the current line is currently only whitespace, or start/continue a CTRL-N
    completion operation:

    	function! CleverTab()
    	   if strpart( getline('.'), 0, col('.')-1 ) =~ '^\s*$'
    	      return "\<Tab>"
    	   else
    	      return "\<C-N>"
    	   endif
    	endfunction
    	inoremap <Tab> <C-R>=CleverTab()<CR>

    Completing whole lines					*compl-whole-line*

    							*i_CTRL-X_CTRL-L*
    CTRL-X CTRL-L		Search backwards for a line that starts with the
    			same characters as those in the current line before
    			the cursor.  Indent is ignored.  The matching line is
    			inserted in front of the cursor.
    			The 'complete' option is used to decide which buffers
    			are searched for a match.  Both loaded and unloaded
    			buffers are used.
    	CTRL-L	or
    	CTRL-P		Search backwards for next matching line.  This line
    			replaces the previous matching line.

    	CTRL-N		Search forward for next matching line.  This line
    			replaces the previous matching line.

    	CTRL-X CTRL-L	After expanding a line you can additionally get the
    			line next to it by typing CTRL-X CTRL-L again, unless
    			a double CTRL-X is used.  Only works for loaded
    			buffers.

    Completing keywords in current file			*compl-current*

    							*i_CTRL-X_CTRL-P*
    							*i_CTRL-X_CTRL-N*
    CTRL-X CTRL-N		Search forwards for words that start with the keyword
    			in front of the cursor.  The found keyword is inserted
    			in front of the cursor.

    CTRL-X CTRL-P		Search backwards for words that start with the keyword
    			in front of the cursor.  The found keyword is inserted
    			in front of the cursor.

    	CTRL-N		Search forward for next matching keyword.  This
    			keyword replaces the previous matching keyword.

    	CTRL-P		Search backwards for next matching keyword.  This
    			keyword replaces the previous matching keyword.

    	CTRL-X CTRL-N or
    	CTRL-X CTRL-P	Further use of CTRL-X CTRL-N or CTRL-X CTRL-P will
    			copy the words following the previous expansion in
    			other contexts unless a double CTRL-X is used.

    If there is a keyword in front of the cursor (a name made out of alphabetic
    characters and characters in 'iskeyword'), it is used as the search pattern,
    with "\<" prepended (meaning: start of a word).  Otherwise "\<\k\k" is used
    as search pattern (start of any keyword of at least two characters).

    In Replace mode, the number of characters that are replaced depends on the
    length of the matched string.  This works like typing the characters of the
    matched string in Replace mode.

    If there is not a valid keyword character before the cursor, any keyword of
    at least two characters is matched.
    	e.g., to get:
    	    printf("(%g, %g, %g)", vector[0], vector[1], vector[2]);
    	just type:
    	    printf("(%g, %g, %g)", vector[0], ^P[1], ^P[2]);

    The search wraps around the end of the file, the value of 'wrapscan' is not
    used here.

    Multiple repeats of the same completion are skipped; thus a different match
    will be inserted at each CTRL-N and CTRL-P (unless there is only one
    matching keyword).

    Single character matches are never included, as they usually just get in
    the way of what you were really after.
    	e.g., to get:
    		printf("name = %s\n", name);
    	just type:
    		printf("name = %s\n", n^P);
    	or even:
    		printf("name = %s\n", ^P);
    The 'n' in '\n' is skipped.

    After expanding a word, you can use CTRL-X CTRL-P or CTRL-X CTRL-N to get the
    word following the expansion in other contexts.  These sequences search for
    the text just expanded and further expand by getting an extra word.  This is
    useful if you need to repeat a sequence of complicated words.  Although CTRL-P
    and CTRL-N look just for strings of at least two characters, CTRL-X CTRL-P and
    CTRL-X CTRL-N can be used to expand words of just one character.
    	e.g., to get:
    		M&eacute;xico
    	you can type:
    		M^N^P^X^P^X^P
    CTRL-N starts the expansion and then CTRL-P takes back the single character
    "M", the next two CTRL-X CTRL-P's get the words "&eacute" and ";xico".

    If the previous expansion was split, because it got longer than 'textwidth',
    then just the text in the current line will be used.

    If the match found is at the end of a line, then the first word in the next
    line will be inserted and the message "Word from other line" displayed, if
    this word is accepted the next CTRL-X CTRL-P or CTRL-X CTRL-N will search
    for those lines starting with this word.

    Completing keywords in 'dictionary'			*compl-dictionary*

    							*i_CTRL-X_CTRL-K*
    CTRL-X CTRL-K		Search the files given with the 'dictionary' option
    			for words that start with the keyword in front of the
    			cursor.  This is like CTRL-N, but only the dictionary
    			files are searched, not the current file.  The found
    			keyword is inserted in front of the cursor.  This
    			could potentially be pretty slow, since all matches
    			are found before the first match is used.  By default,
    			the 'dictionary' option is empty.
    			For suggestions where to find a list of words, see the
    			'dictionary' option.
    			'ignorecase', 'smartcase' and 'infercase' apply.

    	CTRL-K	or
    	CTRL-N		Search forward for next matching keyword.  This
    			keyword replaces the previous matching keyword.

    	CTRL-P		Search backwards for next matching keyword.  This
    			keyword replaces the previous matching keyword.

    Completing words in 'thesaurus'				*compl-thesaurus*

    							*i_CTRL-X_CTRL-T*
    CTRL-X CTRL-T		Works as CTRL-X CTRL-K, but in a special way.  It uses
    			the 'thesaurus' option instead of 'dictionary'.  If a
    			match is found in the thesaurus file, all the
    			remaining words on the same line are included as
    			matches, even though they don't complete the word.
    			Thus a word can be completely replaced.

    	CTRL-T	or
    	CTRL-N		Search forward for next matching keyword.  This
    			keyword replaces the previous matching keyword.

    	CTRL-P		Search backwards for next matching keyword.  This
    			keyword replaces the previous matching keyword.

    In the file used by the 'thesaurus' option each line in the file should
    contain words with similar meaning, separated by non-keyword characters (white
    space is preferred).  Maximum line length is 510 bytes.

    For an example, imagine the 'thesaurus' file has a line like this:
    	angry furious mad enraged
    Placing the cursor after the letters "ang" and typing CTRL-X CTRL-T would
    complete the word "angry"; subsequent presses would change the word to
    "furious", "mad" etc.

    Other uses include translation between two languages, or grouping API
    functions by keyword.

    An English word list was added to this github issue:
    https://github.com/vim/vim/issues/629#issuecomment-443293282
    Unpack thesaurus_pkg.zip, put the thesaurus.txt file somewhere, e.g.
    ~/.vim/thesaurus/english.txt, and the 'thesaurus' option to this file name.

    Completing keywords with 'thesaurusfunc'		*compl-thesaurusfunc*

    If the 'thesaurusfunc' option is set, then the user specified function is
    invoked to get the list of completion matches and the 'thesaurus' option is
    not used. See |complete-functions| for an explanation of how the function is
    invoked and what it should return.

    Here is an example that uses the "aiksaurus" command (provided by Magnus
    Groß):

        func Thesaur(findstart, base)
          if a:findstart
    	return searchpos('\<', 'bnW', line('.'))[1] - 1
          endif
          let res = []
          let h = ''
          for l in systemlist('aiksaurus ' .. shellescape(a:base))
    	if l[:3] == '=== '
    	  let h = '(' .. substitute(l[4:], ' =*$', ')', '')
    	elseif l ==# 'Alphabetically similar known words are: '
    	  let h = "\U0001f52e"
    	elseif l[0] =~ '\a' || (h ==# "\U0001f52e" && l[0] ==# "\t")
    	  call extend(res, map(split(substitute(l, '^\t', '', ''), ', '), {_, val -> {'word': val, 'menu': h}}))
    	endif
          endfor
          return res
        endfunc

        if exists('+thesaurusfunc')
          set thesaurusfunc=Thesaur
        endif

    Completing keywords in the current and included files	*compl-keyword*

    The 'include' option is used to specify a line that contains an include file
    name.  The 'path' option is used to search for include files.

    							*i_CTRL-X_CTRL-I*
    CTRL-X CTRL-I		Search for the first keyword in the current and
    			included files that starts with the same characters
    			as those before the cursor.  The matched keyword is
    			inserted in front of the cursor.

    	CTRL-N		Search forwards for next matching keyword.  This
    			keyword replaces the previous matching keyword.
    			Note: CTRL-I is the same as <Tab>, which is likely to
    			be typed after a successful completion, therefore
    			CTRL-I is not used for searching for the next match.

    	CTRL-P		Search backward for previous matching keyword.  This
    			keyword replaces the previous matching keyword.

    	CTRL-X CTRL-I	Further use of CTRL-X CTRL-I will copy the words
    			following the previous expansion in other contexts
    			unless a double CTRL-X is used.

    Completing tags						*compl-tag*
    							*i_CTRL-X_CTRL-]*
    CTRL-X CTRL-]		Search for the first tag that starts with the same
    			characters as before the cursor.  The matching tag is
    			inserted in front of the cursor.  Alphabetic
    			characters and characters in 'iskeyword' are used
    			to decide which characters are included in the tag
    			name (same as for a keyword).  See also |CTRL-]|.
    			The 'showfulltag' option can be used to add context
    			from around the tag definition.
    	CTRL-]	or
    	CTRL-N		Search forwards for next matching tag.  This tag
    			replaces the previous matching tag.

    	CTRL-P		Search backward for previous matching tag.  This tag
    			replaces the previous matching tag.

    Completing file names					*compl-filename*
    							*i_CTRL-X_CTRL-F*
    CTRL-X CTRL-F		Search for the first file name that starts with the
    			same characters as before the cursor.  The matching
    			file name is inserted in front of the cursor.
    			Alphabetic characters and characters in 'isfname'
    			are used to decide which characters are included in
    			the file name.  Note: the 'path' option is not used
    			here (yet).
    	CTRL-F	or
    	CTRL-N		Search forwards for next matching file name.  This
    			file name replaces the previous matching file name.

    	CTRL-P		Search backward for previous matching file name.
    			This file name replaces the previous matching file
    			name.

    Completing definitions or macros			*compl-define*

    The 'define' option is used to specify a line that contains a definition.
    The 'include' option is used to specify a line that contains an include file
    name.  The 'path' option is used to search for include files.

    							*i_CTRL-X_CTRL-D*
    CTRL-X CTRL-D		Search in the current and included files for the
    			first definition (or macro) name that starts with
    			the same characters as before the cursor.  The found
    			definition name is inserted in front of the cursor.
    	CTRL-D	or
    	CTRL-N		Search forwards for next matching macro name.  This
    			macro name replaces the previous matching macro
    			name.

    	CTRL-P		Search backward for previous matching macro name.
    			This macro name replaces the previous matching macro
    			name.

    	CTRL-X CTRL-D	Further use of CTRL-X CTRL-D will copy the words
    			following the previous expansion in other contexts
    			unless a double CTRL-X is used.

    Completing Vim commands					*compl-vim*

    Completion is context-sensitive.  It works like on the Command-line.  It
    completes an Ex command as well as its arguments.  This is useful when writing
    a Vim script.

    							*i_CTRL-X_CTRL-V*
    CTRL-X CTRL-V		Guess what kind of item is in front of the cursor and
    			find the first match for it.
    			Note: When CTRL-V is mapped you can often use CTRL-Q
    			instead of |i_CTRL-Q|.
    	CTRL-V	or
    	CTRL-N		Search forwards for next match.  This match replaces
    			the previous one.

    	CTRL-P		Search backwards for previous match.  This match
    			replaces the previous one.

    	CTRL-X CTRL-V	Further use of CTRL-X CTRL-V will do the same as
    			CTRL-V.  This allows mapping a key to do Vim command
    			completion, for example:
    				:imap <Tab> <C-X><C-V>

    Completing contents from registers			*compl-register-words*
    							*i_CTRL-X_CTRL-R*
    CTRL-X CTRL-R		Guess what kind of item is in front of the cursor from
    			all registers and find the first match for it.
    			Further use of CTRL-R (without CTRL-X) will insert the
    			register content, see |i_CTRL-R|.
    			'ignorecase' applies to the matching.

    	CTRL-N		Search forwards for next match.  This match replaces
    			the previous one.

    	CTRL-P		Search backwards for previous match.  This match
    			replaces the previous one.

    	CTRL-X CTRL-R	Further use of CTRL-X CTRL-R will copy the line
    			following the previous expansion in other contexts
    			unless a double CTRL-X is used (e.g. this switches
    			from completing register words to register contents).

    User defined completion					*compl-function*

    Completion is done by a function that can be defined by the user with the
    'completefunc' option.  See below for how the function is called and an
    example |complete-functions|.

    							*i_CTRL-X_CTRL-U*
    CTRL-X CTRL-U		Guess what kind of item is in front of the cursor and
    			find the first match for it.
    	CTRL-U	or
    	CTRL-N		Use the next match.  This match replaces the previous
    			one.

    	CTRL-P		Use the previous match.  This match replaces the
    			previous one.

    Omni completion						*compl-omni*

    Completion is done by a function that can be defined by the user with the
    'omnifunc' option.  This is to be used for filetype-specific completion.

    See below for how the function is called and an example |complete-functions|.
    For remarks about specific filetypes see |compl-omni-filetypes|.
    More completion scripts will appear, check www.vim.org.  Currently there is a
    first version for C++.

    							*i_CTRL-X_CTRL-O*
    CTRL-X CTRL-O		Guess what kind of item is in front of the cursor and
    			find the first match for it.
    	CTRL-O	or
    	CTRL-N		Use the next match.  This match replaces the previous
    			one.

    	CTRL-P		Use the previous match.  This match replaces the
    			previous one.

    Spelling suggestions					*compl-spelling*

    A word before or at the cursor is located and correctly spelled words are
    suggested to replace it.  If there is a badly spelled word in the line, before
    or under the cursor, the cursor is moved to after it.  Otherwise the word just
    before the cursor is used for suggestions, even though it isn't badly spelled.

    NOTE: CTRL-S suspends display in many Unix terminals.  Use 's' instead.  Type
    CTRL-Q to resume displaying.

    						*i_CTRL-X_CTRL-S* *i_CTRL-X_s*
    CTRL-X CTRL-S   or
    CTRL-X s		Locate the word in front of the cursor and find the
    			first spell suggestion for it.
    	CTRL-S	or
    	CTRL-N		Use the next suggestion.  This replaces the previous
    			one.  Note that you can't use 's' here.

    	CTRL-P		Use the previous suggestion.  This replaces the
    			previous one.

    Completing from different sources			*compl-generic*

    							*i_CTRL-N*
    CTRL-N			Find the next match for a word ending at the cursor,
    			using the sources specified in the 'complete' option.
    			All sources complete from keywords, except functions,
    			which may complete from non-keyword.  The matched
    			text is inserted before the cursor.

    							*i_CTRL-P*
    CTRL-P			Same as CTRL-N, but find the previous match.

    	CTRL-N		Search forward through the matches and insert the
    			next one.

    	CTRL-P		Search backward through the matches and insert the
    			previous one.

    	CTRL-X CTRL-N or
    	CTRL-X CTRL-P	Further use of CTRL-X CTRL-N or CTRL-X CTRL-P will
    			copy the words following the previous expansion in
    			other contexts unless a double CTRL-X is used.

    Stop completion						*compl-stop*

    							*i_CTRL-X_CTRL-Z*
    CTRL-X CTRL-Z		Stop completion without changing the text.

    AUTOCOMPLETION						*ins-autocompletion*

    Vim can display a completion menu as you type, similar to using |i_CTRL-N|,
    but triggered automatically.  See 'autocomplete'. The menu items are collected
    from the sources listed in the 'complete' option, in order.

    A decaying timeout keeps Vim responsive.  Sources earlier in the 'complete'
    list get more time (higher priority), but all sources receive at least a small
    time slice.

    This mode is fully compatible with other completion modes.  You can invoke
    any of them at any time by typing |CTRL-X|, which temporarily suspends
    autocompletion.  To use |i_CTRL-N| or |i_CTRL-X_CTRL-N| specifically, press
    |CTRL-E| first to dismiss the popup menu (see |complete_CTRL-E|).

    						*ins-autocompletion-example*
    Example setup
    A typical configuration for automatic completion with a popup menu:
    	set autocomplete
    	set complete=.^5,w^5,b^5,u^5
    	set completeopt=popup

    	inoremap <silent><expr> <Tab>   pumvisible() ? "\<C-n>" : "\<Tab>"
    	inoremap <silent><expr> <S-Tab> pumvisible() ? "\<C-p>" : "\<S-Tab>"

    This enables automatic completion with suggestions from the current buffer,
    other windows, and listed buffers, displayed in a popup menu.  Each source is
    limited to 5 candidates.  <Tab> and <S-Tab> move through the items when the
    menu is visible.  Optionally, add "preinsert" to 'completeopt' to insert the
    longest common prefix automatically.  Additional sources (e.g., LSP clients)
    may be added to 'complete' to improve completion as required.

    See also 'autocomplete', 'autocompletedelay' and 'autocompletetimeout'.

    For command-line autocompletion, see |cmdline-autocompletion|.

    FUNCTIONS FOR FINDING COMPLETIONS			*complete-functions*

    This applies to 'completefunc', 'thesaurusfunc' and 'omnifunc'.

    The function is called in two different ways:
    - First the function is called to find the start of the text to be completed.
    - Later the function is called to actually find the matches.

    On the first invocation the arguments are:
       a:findstart  1
       a:base	empty

    The function must return the column where the completion starts.  It must be a
    number between zero and the cursor column "col('.')".  This involves looking
    at the characters just before the cursor and including those characters that
    could be part of the completed item.  The text between this column and the
    cursor column will be replaced with the matches.  If the returned value is
    larger than the cursor column, the cursor column is used.

    Negative return values:
       -2	To cancel silently and stay in completion mode.
       -3	To cancel silently and leave completion mode.
       Another negative value: completion starts at the cursor column

    On the second invocation the arguments are:
       a:findstart  0
       a:base	the text with which matches should match; the text that was
    		located in the first call (can be empty)

    The function must return a List with the matching words.  These matches
    usually include the "a:base" text.  When there are no matches return an empty
    List.  Note that the cursor may have moved since the first invocation, the
    text may have been changed.

    In order to return more information than the matching words, return a Dict
    that contains the List.  The Dict can have these items:
    	words		The List of matching words (mandatory).
    	refresh		A string to control re-invocation of the function
    			(optional).
    			The only value currently recognized is "always", the
    			effect is that the function is called whenever the
    			leading text is changed.

    If you want to suppress the warning message for an empty result, return
    |v:none|.  This is useful to implement asynchronous completion with
    |complete()|.

    Other items are ignored.

    For acting upon end of completion, see the |CompleteDonePre| and
    |CompleteDone| autocommand event.

    For example, the function can contain this:
    	let matches = ... list of words ...
    	return {'words': matches, 'refresh': 'always'}

    If looking for matches is time-consuming, |complete_check()| may be used to
    maintain responsiveness.

    						*complete-items*
    Each list item can either be a string or a Dictionary.  When it is a string it
    is used as the completion.  When it is a Dictionary it can contain these
    items:
    	word		the text that will be inserted, mandatory
    	abbr		abbreviation of "word"; when not empty it is used in
    			the menu instead of "word"
    	menu		extra text for the popup menu, displayed after "word"
    			or "abbr"
    	info		more information about the item, can be displayed in a
    			preview or popup window
    	kind		single letter indicating the type of completion
    	icase		when non-zero case is to be ignored when comparing
    			items to be equal; when omitted zero is used, thus
    			items that only differ in case are added
    	equal		when non-zero, always treat this item to be equal when
    			comparing. Which means, "equal=1" disables filtering
    			of this item.
    	dup		when non-zero this match will be added even when an
    			item with the same word is already present.
    	empty		when non-zero this match will be added even when it is
    			an empty string
    	user_data	custom data which is associated with the item and
    			available in |v:completed_item|; it can be any type;
    			defaults to an empty string
    	abbr_hlgroup	an additional highlight group whose attributes are
    			combined with |hl-PmenuSel| and |hl-Pmenu| or
    			|hl-PmenuMatchSel| and |hl-PmenuMatch| highlight
    			attributes in the popup menu to apply cterm and gui
    			properties (with higher priority) like strikethrough
    			to the completion items abbreviation
    	kind_hlgroup	an additional highlight group specifically for setting
    			the highlight attributes of the completion kind. When
    			this field is present, it will override the
    			|hl-PmenuKind| highlight group, allowing for the
    			customization of ctermfg and guifg properties for the
    			completion kind
    	match		See "matches" in |complete_info()|.

    All of these except "icase", "equal", "dup" and "empty" must be a string.  If
    an item does not meet these requirements then an error message is given and
    further items in the list are not used.  You can mix string and Dictionary
    items in the returned list.

    The "menu" item is used in the popup menu and may be truncated, thus it should
    be relatively short.  The "info" item can be longer, it will  be displayed in
    the preview window when "preview" appears in 'completeopt' or in a popup
    window when "popup" appears in 'completeopt'.  In the preview window the
    "info" item will also remain displayed after the popup menu has been removed.
    This is useful for function arguments.  Use a single space for "info" to
    remove existing text in the preview window.  The size of the preview window is
    three lines, but 'previewheight' is used when it has a value of 1 or 2.

    						*complete-popup*
    When "popup" is in 'completeopt' a popup window is used to display the "info".
    Then the 'completepopup' option specifies the properties of the popup.  This
    is used when the info popup is created.  The option is a comma-separated list
    of values:
    	height		maximum height of the popup
    	width		maximum width of the popup
    	highlight	highlight group of the popup (default is PmenuSel)
    	align		"item" (default) or "menu"
    	border		"on" (default) or "off"
    Example:
    	:set completepopup=height:10,width:60,highlight:InfoPopup

    When `"align"` is set to `"item"`, the popup is positioned near the selected
    item, and moves as the selection changes.
    When set to `"menu"`, the popup aligns with the top of the menu (if the menu
    appears below the text), or with the bottom (if the menu appears above).

    If the 'mouse' is enabled, a close button and resize handle will appear on the
    popup border.

    After creation, the info popup can be located with |popup_findinfo()| and
    modified using |popup_setoptions()|.

    						*complete-popuphidden*
    If the information for the popup is obtained asynchronously, use "popuphidden"
    in 'completeopt'.  The info popup will then be initially hidden and
    |popup_show()| must be called once it has been filled with the info.  This can
    be done with a |CompleteChanged| autocommand, something like this:
    	set completeopt+=popuphidden
    	au CompleteChanged * call UpdateCompleteInfo()
    	func UpdateCompleteInfo()
    	  " Cancel any pending info fetch
    	  let item = v:event.completed_item
    	  " Start fetching info for the item then call ShowCompleteInfo(info)
    	endfunc
    	func ShowCompleteInfo(info)
    	  let id = popup_findinfo()
    	  if id
    	    call popup_settext(id, 'async info: ' .. a:info)
    	    call popup_show(id)
    	  endif
    	endfunc

    						*complete-item-kind*
    The "kind" item uses a single letter to indicate the kind of completion.  This
    may be used to show the completion differently (different color or icon).
    Currently these types can be used:
    	v	variable
    	f	function or method
    	m	member of a struct or class
    	t	typedef
    	d	#define or macro

    When searching for matches takes some time call |complete_add()| to add each
    match to the total list.  These matches should then not appear in the returned
    list!  Call |complete_check()| now and then to allow the user to press a key
    while still searching for matches.  Stop searching when it returns non-zero.

    							*E840*
    The function is allowed to move the cursor, it is restored afterwards.
    The function is not allowed to move to another window or delete text.

    An example that completes the names of the months:
    	fun! CompleteMonths(findstart, base)
    	  if a:findstart
    	    " locate the start of the word
    	    let line = getline('.')
    	    let start = col('.') - 1
    	    while start > 0 && line[start - 1] =~ '\a'
    	      let start -= 1
    	    endwhile
    	    return start
    	  else
    	    " find months matching with "a:base"
    	    let res = []
    	    for m in split("Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec")
    	      if m =~ '^' .. a:base
    		call add(res, m)
    	      endif
    	    endfor
    	    return res
    	  endif
    	endfun
    	set completefunc=CompleteMonths

    The same, but now pretending searching for matches is slow:
    	fun! CompleteMonths(findstart, base)
    	  if a:findstart
    	    " locate the start of the word
    	    let line = getline('.')
    	    let start = col('.') - 1
    	    while start > 0 && line[start - 1] =~ '\a'
    	      let start -= 1
    	    endwhile
    	    return start
    	  else
    	    " find months matching with "a:base"
    	    for m in split("Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec")
    	      if m =~ '^' .. a:base
    		call complete_add(m)
    	      endif
    	      sleep 300m	" simulate searching for next match
    	      if complete_check()
    		break
    	      endif
    	    endfor
    	    return []
    	  endif
    	endfun
    	set completefunc=CompleteMonths

    INSERT COMPLETION POPUP MENU				*ins-completion-menu*
    							*popupmenu-completion*
    Vim can display the matches in a simplistic popup menu.

    The menu is used when:
    - The 'completeopt' option contains "menu" or "menuone".
    - The terminal supports at least 8 colors.
    - There are at least two matches.  One if "menuone" is used.

    The 'pumheight' option can be used to set a maximum height.  The default is to
    use all space available.
    The 'pumwidth' option can be used to set a minimum width.  The default is 15
    characters.

    							*compl-states*
    There are three states:
    1. A complete match has been inserted, e.g., after using CTRL-N or CTRL-P.
    2. A cursor key has been used to select another match.  The match was not
       inserted then, only the entry in the popup menu is highlighted.
    3. Only part of a match has been inserted and characters were typed or the
       backspace key was used.  The list of matches was then adjusted for what is
       in front of the cursor.

    You normally start in the first state, with the first match being inserted.
    When "longest" is in 'completeopt' and there is more than one match you start
    in the third state.

    If you select another match, e.g., with CTRL-N or CTRL-P, you go to the first
    state.  This doesn't change the list of matches.

    When you are back at the original text then you are in the third state.  To
    get there right away you can use a mapping that uses CTRL-P right after
    starting the completion:
    	:imap <F7> <C-N><C-P>

    						*popupmenu-keys*
    In the first state these keys have a special meaning:
    <BS> and CTRL-H   Delete one character, find the matches for the word before
    		  the cursor.  This reduces the list of matches, often to one
    		  entry, and switches to the second state.
    		  When 'autocomplete' is active, clears the selected item in
    		  the menu.
    Any non-special character:
    		  Stop completion without changing the match and insert the
    		  typed character.

    In the second and third state these keys have a special meaning:
    <BS> and CTRL-H   Delete one character, find the matches for the shorter word
    		  before the cursor.  This may find more matches.
    		  When 'autocomplete' is active, clears the selected item in
    		  the menu.
    CTRL-L		  Add one character from the current match, may reduce the
    		  number of matches.
    any printable, non-white character:
    		  Add this character and reduce the number of matches.

    In all three states these can be used:
    CTRL-Y		  Yes: Accept the currently selected match and stop completion.
    CTRL-E		  End completion, go back to what was there before selecting a
    		  match (what was typed or longest common string).
    <PageUp>	  Select a match several entries back, but don't insert it.
    <PageDown>	  Select a match several entries further, but don't insert it.
    <Up>		  Select the previous match, as if CTRL-P was used, but don't
    		  insert it.
    <Down>		  Select the next match, as if CTRL-N was used, but don't
    		  insert it.
    <Space> or <Tab>  Stop completion without changing the match and insert the
    		  typed character.

    The behavior of the <Enter> key depends on the state you are in:
    first state:	  Use the text as it is and insert a line break.
    second state:	  Insert the currently selected match.
    third state:	  Use the text as it is and insert a line break.

    In other words: If you used the cursor keys to select another entry in the
    list of matches then the <Enter> key inserts that match.  If you typed
    something else then <Enter> inserts a line break.

    The colors of the menu can be changed with these highlight groups:
    Pmenu		normal item  |hl-Pmenu|
    PmenuSel	selected item  |hl-PmenuSel|
    PmenuSbar	scrollbar  |hl-PmenuSbar|
    PmenuThumb	thumb of the scrollbar  |hl-PmenuThumb|

    There are no special mappings for when the popup menu is visible.  However,
    you can use an Insert mode mapping that checks the |pumvisible()| function to
    do something different.  Example:
    	:inoremap <Down> <C-R>=pumvisible() ? "\<lt>C-N>" : "\<lt>Down>"<CR>

    You can use of <expr> in mapping to have the popup menu used when typing a
    character and some condition is met.  For example, for typing a dot:
    	inoremap <expr> . MayComplete()
    	func MayComplete()
    	    if (can complete)
    	      return ".\<C-X>\<C-O>"
    	    endif
    	    return '.'
    	endfunc

    See |:map-<expr>| for more info.

    FILETYPE-SPECIFIC REMARKS FOR OMNI COMPLETION	    *compl-omni-filetypes*

    The file used for {filetype} should be autoload/{filetype}complete.vim
    in 'runtimepath'.  Thus for "java" it is autoload/javacomplete.vim.

    C							*ft-c-omni*

    Completion of C code requires a tags file.  You should use Universal/
    Exuberant ctags, because it adds extra information that is needed for
    completion.  You can find it here:
    	Universal Ctags: https://ctags.io
    	Exuberant Ctags: http://ctags.sourceforge.net

    Universal Ctags is preferred, Exuberant Ctags is no longer being developed.

    For Exuberant ctags, version 5.6 or later is recommended.  For version 5.5.4
    you should add a patch that adds the "typename:" field:
    	https://ftp.nluug.nl/pub/vim/unstable/patches/ctags-5.5.4.patch
    A compiled .exe for MS-Windows can be found at:
    	http://ctags.sourceforge.net/
    	https://github.com/universal-ctags/ctags-win32

    If you want to complete system functions you can do something like this.  Use
    ctags to generate a tags file for all the system header files:
    	% ctags -R -f ~/.vim/systags /usr/include /usr/local/include
    In your vimrc file add this tags file to the 'tags' option:
    	set tags+=~/.vim/systags

    When using CTRL-X CTRL-O after a name without any "." or "->" it is completed
    from the tags file directly.  This works for any identifier, also function
    names.  If you want to complete a local variable name, which does not appear
    in the tags file, use CTRL-P instead.

    When using CTRL-X CTRL-O after something that has "." or "->" Vim will attempt
    to recognize the type of the variable and figure out what members it has.
    This means only members valid for the variable will be listed.

    When a member name already was complete, CTRL-X CTRL-O will add a "." or
    "->" for composite types.

    Vim doesn't include a C compiler, only the most obviously formatted
    declarations are recognized.  Preprocessor stuff may cause confusion.
    When the same structure name appears in multiple places all possible members
    are included.

    CSS							*ft-css-omni*

    Complete properties and their appropriate values according to CSS 2.1
    specification.

    HTML							*ft-html-omni*
    XHTML							*ft-xhtml-omni*

    CTRL-X CTRL-O provides completion of various elements of (X)HTML files.  It is
    designed to support writing of XHTML 1.0 Strict files but will also work for
    other versions of HTML. Features:

    - after "<" complete tag name depending on context (no div suggestion inside
      of an a tag); '/>' indicates empty tags
    - inside of tag complete proper attributes (no width attribute for an a tag);
      show also type of attribute; '*' indicates required attributes
    - when attribute has limited number of possible values help to complete them
    - complete names of entities
    - complete values of "class" and "id" attributes with data obtained from
      <style> tag and included CSS files
    - when completing value of "style" attribute or working inside of "style" tag
      switch to |ft-css-omni| completion
    - when completing values of events attributes or working inside of "script"
      tag switch to |ft-javascript-omni| completion
    - when used after "</" CTRL-X CTRL-O will close the last opened tag

    Note: When used first time completion menu will be shown with little delay
    - this is time needed for loading of data file.
    Note: Completion may fail in badly formatted documents. In such case try to
    run |:make| command to detect formatting problems.

    HTML flavor						*html-flavor*

    The default HTML completion depends on the filetype.  For HTML files it is
    HTML 4.01 Transitional ('filetype' is "html"), for XHTML it is XHTML 1.0
    Strict ('filetype' is "xhtml").

    When doing completion outside of any other tag you will have possibility to
    choose DOCTYPE and the appropriate data file will be loaded and used for all
    next completions.

    More about format of data file in |xml-omni-datafile|. Some of the data files
    may be found on the Vim website (|www|).

    Note that b:html_omni_flavor may point to a file with any XML data.  This
    makes possible to mix PHP (|ft-php-omni|) completion with any XML dialect
    (assuming you have data file for it).  Without setting that variable XHTML 1.0
    Strict will be used.

    JAVASCRIPT					       *ft-javascript-omni*

    Completion of most elements of JavaScript language and DOM elements.

    Complete:

    - variables
    - function name; show function arguments
    - function arguments
    - properties of variables trying to detect type of variable
    - complete DOM objects and properties depending on context
    - keywords of language

    Completion works in separate JavaScript files (&ft==javascript), inside of
    <script> tag of (X)HTML and in values of event attributes (including scanning
    of external files).

    DOM compatibility

    At the moment (beginning of 2006) there are two main browsers - MS Internet
    Explorer and Mozilla Firefox. These two applications are covering over 90% of
    market. Theoretically standards are created by W3C organisation
    (http://www.w3c.org) but they are not always followed/implemented.

    		IE	FF	W3C  Omni completion
    		+/-	+/-	+    +
    		+	+	-    +
    		+	-	-    -
    		-	+	-    -

    Regardless from state of implementation in browsers but if element is defined
    in standards, completion plugin will place element in suggestion list. When
    both major engines implemented element, even if this is not in standards it
    will be suggested. All other elements are not placed in suggestion list.

    PHP							*ft-php-omni*

    Completion of PHP code requires a tags file for completion of data from
    external files and for class aware completion. You should use Universal/
    Exuberant ctags version 5.5.4 or newer. You can find it here:

    	Universal Ctags: https://ctags.io
    	Exuberant Ctags: http://ctags.sourceforge.net

    Script completes:

    - after $ variables name
      - if variable was declared as object add "->", if tags file is available show
        name of class
      - after "->" complete only function and variable names specific for given
        class. To find class location and contents tags file is required. Because
        PHP isn't strongly typed language user can use @var tag to declare class:

    	/* @var $myVar myClass */
    	$myVar->

        Still, to find myClass contents tags file is required.

    - function names with additional info:
      - in case of built-in functions list of possible arguments and after | type
        data returned by function
      - in case of user function arguments and name of file where function was
        defined (if it is not current file)

    - constants names
    - class names after "new" declaration

    Note: when doing completion first time Vim will load all necessary data into
    memory. It may take several seconds. After next use of completion delay
    should not be noticeable.

    Script detects if cursor is inside <?php ?> tags. If it is outside it will
    automatically switch to HTML/CSS/JavaScript completion. Note: contrary to
    original HTML files completion of tags (and only tags) isn't context aware.

    RUBY							*ft-ruby-omni*

    Completion of Ruby code requires that vim be built with |+ruby|.

    Ruby completion will parse your buffer on demand in order to provide a list of
    completions.  These completions will be drawn from modules loaded by 'require'
    and modules defined in the current buffer.

    The completions provided by CTRL-X CTRL-O are sensitive to the context:

    	  CONTEXT			   COMPLETIONS PROVIDED

     1. Not inside a class definition    Classes, constants and globals

     2. Inside a class definition	     Methods or constants defined in the class

     3. After '.', '::' or ':'	     Methods applicable to the object being
    				       dereferenced

     4. After ':' or ':foo'		     Symbol name (beginning with 'foo')

    Notes:
     - Vim will load/evaluate code in order to provide completions.  This may
       cause some code execution, which may be a concern. This is no longer
       enabled by default, to enable this feature add
         let g:rubycomplete_buffer_loading = 1
    - In context 1 above, Vim can parse the entire buffer to add a list of
       classes to the completion results. This feature is turned off by default,
       to enable it add
         let g:rubycomplete_classes_in_global = 1
      to your vimrc
     - In context 2 above, anonymous classes are not supported.
     - In context 3 above, Vim will attempt to determine the methods supported by
       the object.
     - Vim can detect and load the Rails environment for files within a rails
       project. The feature is disabled by default, to enable it add
         let g:rubycomplete_rails = 1
      to your vimrc

    SYNTAX							*ft-syntax-omni*

    Vim has the ability to color syntax highlight nearly 500 languages.  Part of
    this highlighting includes knowing what keywords are part of a language.  Many
    filetypes already have custom completion scripts written for them, the
    syntaxcomplete plugin provides basic completion for all other filetypes.  It
    does this by populating the omni completion list with the text Vim already
    knows how to color highlight.  It can be used for any filetype and provides a
    minimal language-sensitive completion.

    To enable syntax code completion you can run:
        setlocal omnifunc=syntaxcomplete#Complete

    You can automate this by placing the following in your |.vimrc| (after any
    ":filetype" command):
        if has("autocmd") && exists("+omnifunc")
    	autocmd Filetype *
    		    \	if &omnifunc == "" |
    		    \		setlocal omnifunc=syntaxcomplete#Complete |
    		    \	endif
        endif

    The above will set completion to this script only if a specific plugin does
    not already exist for that filetype.

    Each filetype can have a wide range of syntax items.  The plugin allows you to
    customize which syntax groups to include or exclude from the list.  Let's have
    a look at the PHP filetype to see how this works.

    If you edit a file called, index.php, run the following command:
        syntax list

    The first thing you will notice is that there are many different syntax groups.
    The PHP language can include elements from different languages like HTML,
    JavaScript and many more.  The syntax plugin will only include syntax groups
    that begin with the filetype, "php", in this case.  For example these syntax
    groups are included by default with the PHP: phpEnvVar, phpIntVar,
    phpFunctions.

    If you wish non-filetype syntax items to also be included, you can use a
    regular expression syntax (added in version 13.0 of
    autoload/syntaxcomplete.vim) to add items.  Looking at the output from
    ":syntax list" while editing a PHP file I can see some of these entries:
        htmlArg,htmlTag,htmlTagName,javaScriptStatement,javaScriptGlobalObjects

    To pick up any JavaScript and HTML keyword syntax groups while editing a PHP
    file, you can use 3 different regexs, one for each language.  Or you can
    simply restrict the include groups to a particular value, without using
    a regex string:
        let g:omni_syntax_group_include_php = 'php\w\+,javaScript\w\+,html\w\+'
        let g:omni_syntax_group_include_php = 'phpFunctions,phpMethods'

    The basic form of this variable is:
        let g:omni_syntax_group_include_{filetype} = 'regex,comma,separated'

    The PHP language has an enormous number of items which it knows how to syntax
    highlight.  These items will be available within the omni completion list.

    Some people may find this list unwieldy or are only interested in certain
    items.  There are two ways to prune this list (if necessary).  If you find
    certain syntax groups you do not wish displayed you can use two different
    methods to identify these groups.  The first specifically lists the syntax
    groups by name.  The second uses a regular expression to identify both
    syntax groups.  Simply add one the following to your vimrc:
        let g:omni_syntax_group_exclude_php = 'phpCoreConstant,phpConstant'
        let g:omni_syntax_group_exclude_php = 'php\w*Constant'

    Add as many syntax groups to this list by comma separating them.  The basic
    form of this variable is:
        let g:omni_syntax_group_exclude_{filetype} = 'regex,comma,separated'

    You can create as many of these variables as you need, varying only the
    filetype at the end of the variable name.

    The plugin uses the isKeyword option to determine where word boundaries are
    for the syntax items.  For example, in the Scheme language completion should
    include the "-", call-with-output-file.  Depending on your filetype, this may
    not provide the words you are expecting.  Setting the
    g:omni_syntax_use_iskeyword option to 0 will force the syntax plugin to break
    on word characters.   This can be controlled adding the following to your
    vimrc:
        let g:omni_syntax_use_iskeyword = 0

    For plugin developers, the plugin exposes a public function OmniSyntaxList.
    This function can be used to request a List of syntax items.  When editing a
    SQL file (:e syntax.sql) you can use the ":syntax list" command to see the
    various groups and syntax items.  For example:
        syntax list

    Yields data similar to this:
        sqlOperator    xxx some prior all like and any escape exists in is not
                           or intersect minus between distinct
                           links to Operator
        sqlType        xxx varbit varchar nvarchar bigint int uniqueidentifier
                           date money long tinyint unsigned xml text smalldate
                           double datetime nchar smallint numeric time bit char
                           varbinary binary smallmoney
                           image float integer timestamp real decimal

    There are two syntax groups listed here: sqlOperator and sqlType.  To retrieve
    a List of syntax items you can call OmniSyntaxList a number of different
    ways.  To retrieve all syntax items regardless of syntax group:
        echo OmniSyntaxList( [] )

    To retrieve only the syntax items for the sqlOperator syntax group:
        echo OmniSyntaxList( ['sqlOperator'] )

    To retrieve all syntax items for both the sqlOperator and sqlType groups:
        echo OmniSyntaxList( ['sqlOperator', 'sqlType'] )

    A regular expression can also be used:
        echo OmniSyntaxList( ['sql\w\+'] )

    From within a plugin, you would typically assign the output to a List:
        let myKeywords = []
        let myKeywords = OmniSyntaxList( ['sqlKeyword'] )

    SQL							*ft-sql-omni*

    Completion for the SQL language includes statements, functions, keywords.
    It will also dynamically complete tables, procedures, views and column lists
    with data pulled directly from within a database.  For detailed instructions
    and a tutorial see |omni-sql-completion|.

    The SQL completion plugin can be used in conjunction with other completion
    plugins.  For example, the PHP filetype has its own completion plugin.
    Since PHP is often used to generate dynamic website by accessing a database,
    the SQL completion plugin can also be enabled.  This allows you to complete
    PHP code and SQL code at the same time.

    XML							*ft-xml-omni*

    Vim 7 provides a mechanism for context aware completion of XML files.  It
    depends on a special |xml-omni-datafile| and two commands: |:XMLns| and
    |:XMLent|.  Features are:

    - after "<" complete the tag name, depending on context
    - inside of a tag complete proper attributes
    - when an attribute has a limited number of possible values help to complete
      them
    - complete names of entities (defined in |xml-omni-datafile| and in the
      current file with "<!ENTITY" declarations)
    - when used after "</" CTRL-X CTRL-O will close the last opened tag

    Format of XML data file					*xml-omni-datafile*

    XML data files are stored in the "autoload/xml" directory in 'runtimepath'.
    Vim distribution provides examples of data files in the
    "$VIMRUNTIME/autoload/xml" directory.  They have a meaningful name which will
    be used in commands.  It should be a unique name which will not create
    conflicts.  For example, the name xhtml10s.vim means it is the data file for
    XHTML 1.0 Strict.

    Each file contains a variable with a name like g:xmldata_xhtml10s . It is
    a compound from two parts:

    1. "g:xmldata_"  general prefix, constant for all data files
    2. "xhtml10s"    the name of the file and the name of the described XML
    		 dialect; it will be used as an argument for the |:XMLns|
    		 command

    Part two must be exactly the same as name of file.

    The variable is a |Dictionary|.  Keys are tag names and each value is a two
    element |List|.  The first element of the List is also a List with the names
    of possible children.  The second element is a |Dictionary| with the names of
    attributes as keys and the possible values of attributes as values.  Example:

        let g:xmldata_crippled = {
        \ "vimxmlentities": ["amp", "lt", "gt", "apos", "quot"],
        \ 'vimxmlroot': ['tag1'],
        \ 'tag1':
        \ [ ['childoftag1a', 'childoftag1b'], {'attroftag1a': [],
        \ 'attroftag1b': ['valueofattr1', 'valueofattr2']}],
        \ 'childoftag1a':
        \ [ [], {'attrofchild': ['attrofchild']}],
        \ 'childoftag1b':
        \ [ ['childoftag1a'], {'attrofchild': []}],
        \ "vimxmltaginfo": {
        \ 'tag1': ['Menu info', 'Long information visible in preview window']},
        \ 'vimxmlattrinfo': {
        \ 'attrofchild': ['Menu info', 'Long information visible in preview window']}}

    This example would be put in the "autoload/xml/crippled.vim" file and could
    help to write this file:

        <tag1 attroftag1b="valueofattr1">
            <childoftag1a attrofchild>
                    &amp; &lt;
            </childoftag1a>
            <childoftag1b attrofchild="5">
                <childoftag1a>
                    &gt; &apos; &quot;
                </childoftag1a>
            </childoftag1b>
        </tag1>

    In the example four special elements are visible:

    1. "vimxmlentities" - a special key with List containing entities of this XML
       dialect.
    2. If the list containing possible values of attributes has one element and
       this element is equal to the name of the attribute this attribute will be
       treated as boolean and inserted as 'attrname' and not as 'attrname="'
    3. "vimxmltaginfo" - a special key with a Dictionary containing tag
       names as keys and two element List as values, for additional menu info and
       the long description.
    4. "vimxmlattrinfo" - special key with Dictionary containing attribute names
       as keys and two element List as values, for additional menu info and long
       description.

    Note: Tag names in the data file MUST not contain a namespace description.
    Check xsl.vim for an example.
    Note: All data and functions are publicly available as global
    variables/functions and can be used for personal editing functions.

    DTD -> Vim							*dtd2vim*

    On |www| is the script |dtd2vim| which parses DTD and creates an XML data file
    for Vim XML omni completion.

        dtd2vim: http://www.vim.org/scripts/script.php?script_id=1462

    Check the beginning of that file for usage details.
    The script requires perl and:

        perlSGML: http://savannah.nongnu.org/projects/perlsgml

    Commands

    :XMLns {name} [{namespace}]					*:XMLns*

    Vim has to know which data file should be used and with which namespace.  For
    loading of the data file and connecting data with the proper namespace use
    |:XMLns| command.  The first (obligatory) argument is the name of the data
    (xhtml10s, xsl).  The second argument is the code of namespace (h, xsl).  When
    used without a second argument the dialect will be used as default - without
    namespace declaration.  For example to use XML completion in .xsl files:

    	:XMLns xhtml10s
    	:XMLns xsl xsl

    :XMLent {name}							*:XMLent*

    By default entities will be completed from the data file of the default
    namespace.  The XMLent command should be used in case when there is no default
    namespace:

    	:XMLent xhtml10s

    Usage

    While used in this situation (after declarations from previous part, | is
    cursor position):

    	<|

    Will complete to an appropriate XHTML tag, and in this situation:

    	<xsl:|

    Will complete to an appropriate XSL tag.

    The script xmlcomplete.vim, provided through the |autoload| mechanism,
    has the xmlcomplete#GetLastOpenTag() function which can be used in XML files
    to get the name of the last open tag (b:unaryTagsStack has to be defined):

    	:echo xmlcomplete#GetLastOpenTag("b:unaryTagsStack")

    8. Insert mode commands					*inserting*

    The following commands can be used to insert new text into the buffer.  They
    can all be undone and repeated with the "." command.

    							*a*
    a			Append text after the cursor [count] times.  If the
    			cursor is in the first column of an empty line Insert
    			starts there.  But not when 'virtualedit' is set!

    							*A*
    A			Append text at the end of the line [count] times.
    			For using "A" in Visual block mode see |v_b_A|.

    <insert>	or				*i* *insert* *<Insert>*
    i			Insert text before the cursor [count] times.
    			When using CTRL-O in Insert mode |i_CTRL-O| the count
    			is not supported.

    							*I*
    I			Insert text before the first non-blank in the line
    			[count] times.
    			When the 'H' flag is present in 'cpoptions' and the
    			line only contains blanks, insert start just before
    			the last blank.
    			For using "I" in Visual block mode see |v_b_I|.

    							*gI*
    gI			Insert text in column 1 [count] times.

    							*gi*
    gi			Insert text in the same position as where Insert mode
    			was stopped last time in the current buffer.
    			This uses the |'^| mark.  It's different from "`^i"
    			when the mark is past the end of the line.
    			The position is corrected for inserted/deleted lines,
    			but NOT for inserted/deleted characters.
    			When the |:keepjumps| command modifier is used the |'^|
    			mark won't be changed.

    							*o*
    o			Begin a new line below the cursor and insert text,
    			repeat [count] times.
    			When the '#' flag is in 'cpoptions' the count is
    			ignored.

    							*O*
    O			Begin a new line above the cursor and insert text,
    			repeat [count] times.
    			When the '#' flag is in 'cpoptions' the count is
    			ignored.

    These commands are used to start inserting text.  You can end insert mode with
    <Esc>.  See |mode-ins-repl| for the other special characters in Insert mode.
    The effect of [count] takes place after Insert mode is exited.

    When 'autoindent' is on, the indent for a new line is obtained from the
    previous line.  When 'smartindent' or 'cindent' is on, the indent for a line
    is automatically adjusted for C programs.

    'formatoptions' can be set to copy the comment leader when opening a new
    line.

    'textwidth' can be set to the maximum width for a line.  When a line becomes
    too long when appending characters a line break is automatically inserted.

    9. Ex insert commands					*inserting-ex*

    							*:a* *:append*
    :{range}a[ppend][!]	Insert several lines of text below the specified
    			line.  If the {range} is missing, the text will be
    			inserted after the current line.
    			Adding [!] toggles 'autoindent' for the time this
    			command is executed.
    			This command is not supported in |Vim9| script,
    			because it is too easily confused with a variable
    			name.

    							*:i* *:in* *:insert*
    :{range}i[nsert][!]	Insert several lines of text above the specified
    			line.  If the {range} is missing, the text will be
    			inserted before the current line.
    			Adding [!] toggles 'autoindent' for the time this
    			command is executed.
    			This command is not supported in |Vim9| script,
    			because it is too easily confused with a variable
    			name.

    These two commands will keep on asking for lines, until you type a line
    containing only a ".".  Watch out for lines starting with a backslash, see
    |line-continuation|.

    Text typed after a "|" command separator is used first. So the following
    command in ex mode:
    	:a|one
    	two
    	.
    	:visual
    appends the following text, after the cursor line:
    	one
    	two

    In |Ex-mode|, when these commands are used with |:global| or |:vglobal| then
    the lines are obtained from the text following the command.  Separate lines
    with a NL escaped with a backslash:
    	:global/abc/insert\
    	one line\
    	another line
    The final "." is not needed then.

    NOTE: ":append" and ":insert" don't work properly in between ":if" and
    ":endif", ":for" and ":endfor", ":while" and ":endwhile".

    							*:start* *:startinsert*
    :star[tinsert][!]	Start Insert mode just after executing this command.
    			Works like typing "i" in Normal mode.  When the ! is
    			included it works like "A", append to the line.
    			Otherwise insertion starts at the cursor position.
    			Note that when using this command in a function or
    			script, the insertion only starts after the function
    			or script is finished.
    			This command does not work from |:normal|.

    							*:stopi* *:stopinsert*
    :stopi[nsert]		Stop Insert mode as soon as possible.  Works like
    			typing <Esc> in Insert mode.
    			Can be used in an autocommand, example:
    				:au BufEnter scratch stopinsert

    					*replacing-ex* *:startreplace*
    :startr[eplace][!]	Start Replace mode just after executing this command.
    			Works just like typing "R" in Normal mode.  When the
    			! is included it acts just like "$R" had been typed
    			(ie. begin replace mode at the end-of-line).  Other-
    			wise replacement begins at the cursor position.
    			Note that when using this command in a function or
    			script that the replacement will only start after
    			the function or script is finished.

    							*:startgreplace*
    :startg[replace][!]	Just like |:startreplace|, but use Virtual Replace
    			mode, like with |gR|.

    10. Inserting a file					*inserting-file*

    							*:r* *:re* *:read*
    :r[ead] [++opt] [name]
    			Insert the file [name] (default: current file) below
    			the cursor.
    			See |++opt| for the possible values of [++opt].

    :{range}r[ead] [++opt] [name]
    			Insert the file [name] (default: current file) below
    			the specified line.
    			See |++opt| for the possible values of [++opt].

    							*:r!* *:read!*
    :[range]r[ead] [++opt] !{cmd}
    			Execute {cmd} and insert its standard output below
    			the cursor or the specified line.  A temporary file is
    			used to store the output of the command which is then
    			read into the buffer.  'shellredir' is used to save
    			the output of the command, which can be set to include
    			stderr or not.  {cmd} is executed like with ":!{cmd}",
    			any '!' is replaced with the previous command |:!|.
    			See |++opt| for the possible values of [++opt].

    These commands insert the contents of a file, or the output of a command,
    into the buffer.  They can be undone.  They cannot be repeated with the "."
    command.  They work on a line basis, insertion starts below the line in which
    the cursor is, or below the specified line.  To insert text above the first
    line use the command ":0r {name}".

    After the ":read" command, the cursor is left on the first non-blank in the
    first new line.  If in Ex mode, then the cursor is left on the last new
    line (sorry, this is Vi compatible).

    If a file name is given with ":r", it becomes the alternate file.  This can be
    used, for example, when you want to edit that file instead: ":e! #".  This can
    be switched off by removing the 'a' flag from the 'cpoptions' option.

    Of the [++opt] arguments one is specifically for ":read", the ++edit argument.
    This is useful when the ":read" command is actually used to read a file into
    the buffer as if editing that file.  Use this command in an empty buffer:
    	:read ++edit filename
    The effect is that the 'fileformat', 'fileencoding', 'bomb', etc. options are
    set to what has been detected for "filename".  Note that a single empty line
    remains, you may want to delete it.

    							*file-read*
    The 'fileformat' option sets the <EOL> style for a file:
    'fileformat'    characters	   name
      "dos"		<CR><NL> or <NL>   DOS format
      "unix"	<NL>		   Unix format
      "mac"		<CR>		   Mac format
    Previously 'textmode' was used.  It is obsolete now.

    If 'fileformat' is "dos", a <CR> in front of an <NL> is ignored and a CTRL-Z
    at the end of the file is ignored.

    If 'fileformat' is "mac", a <NL> in the file is internally represented by a
    <CR>.  This is to avoid confusion with a <NL> which is used to represent a
    <NUL>.  See |CR-used-for-NL|.

    If the 'fileformats' option is not empty Vim tries to recognize the type of
    <EOL> (see |file-formats|).  However, the 'fileformat' option will not be
    changed, the detected format is only used while reading the file.
    A similar thing happens with 'fileencodings'.

    On non-Win32 systems the message "[dos format]" is shown if a file is read in
    DOS format, to remind you that something unusual is done.
    On Macintosh and Win32 the message "[unix format]" is shown if a file is read
    in Unix format.
    On non-Macintosh systems, the message "[mac format]" is shown if a file is
    read in Mac format.

    An example on how to use ":r !":
    	:r !uuencode binfile binfile
    This command reads "binfile", uuencodes it and reads it into the current
    buffer.  Useful when you are editing e-mail and want to include a binary
    file.

    							*read-messages*
    When reading a file Vim will display a message with information about the read
    file.  In the table is an explanation for some of the items.  The others are
    self explanatory.  Using the long or the short version depends on the
    'shortmess' option.

    	long		short		meaning
    	[readonly]	{RO}		the file is write protected
    	[fifo/socket]			using a stream
    	[fifo]				using a fifo stream
    	[socket]			using a socket stream
    	[CR missing]			reading with "dos" 'fileformat' and a
    					NL without a preceding CR was found.
    	[NL found]			reading with "mac" 'fileformat' and a
    					NL was found (could be "unix" format)
    	[long lines split]		at least one line was split in two
    	[NOT converted]			conversion from 'fileencoding' to
    					'encoding' was desired but not
    					possible
    	[converted]			conversion from 'fileencoding' to
    					'encoding' done
    	[crypted]			file was decrypted
    	[READ ERRORS]			not all of the file could be read

     vim:tw=78:ts=8:noet:ft=help:norl:

Generated by vim2html on 16.10.2025