summaryrefslogtreecommitdiffstats
path: root/runtime/doc/insert.txt
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--runtime/doc/insert.txt2138
1 files changed, 2138 insertions, 0 deletions
diff --git a/runtime/doc/insert.txt b/runtime/doc/insert.txt
new file mode 100644
index 0000000..ccf5178
--- /dev/null
+++ b/runtime/doc/insert.txt
@@ -0,0 +1,2138 @@
+*insert.txt* For Vim version 9.0. Last change: 2022 Sep 30
+
+
+ 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.txt|.
+
+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
+ '-' the last small (less than a line) delete
+ *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`.
+ Does not replace characters!
+ 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.
+
+CTRL-R CTRL-P {register} *i_CTRL-R_CTRL-P*
+ Insert the contents of a register literally and fix the
+ indent, like |[<MiddleMouse>|.
+ Does not replace characters!
+ 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.
+
+ *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.
+
+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.txt| 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 end-of-line (join lines)
+start allow backspacing over the start position of insert; CTRL-W and
+ CTRL-U stop once at the start position
+
+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', 'smarttab' and 'softtabstop' 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-smarttab*
+When the 'smarttab' option is on, a <Tab> inserts 'shiftwidth' positions at
+the beginning of a line and 'tabstop' positions in other places. This means
+that often spaces instead of a <Tab> character are inserted. When 'smarttab'
+is off, a <Tab> always inserts 'tabstop' positions, and 'shiftwidth' is only
+used for ">>" and the like.
+
+ *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.
+
+==============================================================================
+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. keywords in 'complete' |i_CTRL-N| |i_CTRL-P|
+
+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).
+
+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.
+
+ *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>
+
+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 keywords from different sources *compl-generic*
+
+ *i_CTRL-N*
+CTRL-N Find next match for words that start with the
+ keyword in front of the cursor, looking in places
+ specified with the 'complete' option. The found
+ keyword is inserted in front of the cursor.
+
+ *i_CTRL-P*
+CTRL-P Find previous match for words that start with the
+ keyword in front of the cursor, looking in places
+ specified with the 'complete' option. 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.
+
+
+Stop completion *compl-stop*
+
+ *i_CTRL-X_CTRL-Z*
+CTRL-X CTRL-Z Stop completion without changing the text.
+
+
+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'}
+<
+ *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
+
+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 the "align" value is "item" then the popup is positioned close to the
+selected item. Changing the selection will also move the popup. When "align"
+is "menu" then the popup is aligned with the top of the menu if the menu is
+below the text, and the bottom of the menu otherwise.
+
+After the info popup is created it can be found with |popup_findinfo()| and
+properties can be changed with |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.
+
+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.
+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.
+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:
+ ftp://ftp.vim.org/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|.
+
+When in Ex mode (see |-e|) a backslash at the end of the line can be used to
+insert a NUL character. To be able to have a line ending in a backslash use
+two backslashes. This means that the number of backslashes is halved, but
+only at the end of the line.
+
+NOTE: These commands cannot be used with |:global| or |:vglobal|.
+":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. Unless 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: