vim: runtime/doc/insert.txt comparison

comparison runtime/doc/insert.txt @ 7:3fc0f57ecb91 v7.0001

updated for version 7.0001

author	vimboss
date	Sun, 13 Jun 2004 20:20:40 +0000
parents
children	4102fb4ea781

comparison

equal deleted inserted replaced

-:c2daee826b8f
+:3fc0f57ecb91
+*insert.txt*    For Vim version 7.0aa.  Last change: 2004 Apr 09
+		  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-[.
+						*i_CTRL-C*
+CTRL-C		Quit insert mode, go back to Normal mode.  Do not check for
+		abbreviations.
+						*i_CTRL-@*
+CTRL-@		Insert previously inserted text and stop insert.  {Vi: only
+		when typed as first char, only up to 128 chars}
+						*i_CTRL-A*
+CTRL-A		Insert previously inserted text.  {not in Vi}
+						*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.
+		{Vi: does not delete autoindents}
+						*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.
+		{not in Vi}
+						*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 in the current line (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.  {not in Vi}
+CTRL-N		Find next keyword (see |i_CTRL-N|).  {not in Vi}
+CTRL-P		Find previous keyword (see |i_CTRL-P|).  {not in Vi}
+CTRL-R {0-9a-z"%#*+:.-=}					*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
+			'='	the expression register: you are prompted to
+				enter an expression (see |expression|)
+		See |registers| about registers.  {not in Vi}
+CTRL-R CTRL-R {0-9a-z"%#*+/:.-=}			*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 "<C-R><C-O>r", see below.
+		The '.' register (last inserted text) is still inserted as
+		typed.  {not in Vi}
+CTRL-R CTRL-O {0-9a-z"%#*+/:.-=}			*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>|.
+		Does not replace characters!
+		The '.' register (last inserted text) is still inserted as
+		typed.  {not in Vi}
+CTRL-R CTRL-P {0-9a-z"%#*+/:.-=}			*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.  {not in Vi}
+						*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).  {Vi: only when in indent}
+						*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).  {Vi: CTRL-D works only when used after
+		autoindent}
+						*i_0_CTRL-D*
+0 CTRL-D	Delete all indent in the current line.  {Vi: CTRL-D works
+		only when used after autoindent}
+						*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.  {Vi: CTRL-D works only when used after autoindent}
+						*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.  {Vi: no decimal byte entry}
+		Note: When CTRL-V is mapped (e.g., to paste text) you can
+		often use CTRL-Q instead |i_CTRL-Q|.
+						*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-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|. {not in Vi}
+						*i_CTRL-E*
+CTRL-E		Insert the character which is below the cursor.  {not in Vi}
+						*i_CTRL-Y*
+CTRL-Y		Insert the character which is above the cursor.  {not in Vi}
+		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.
+		{not in Vi}
+		Only if compiled with the |+rightleft| feature (which is not
+		the default).
+						*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.
+		{not in Vi}
+						*i_CTRL-]*
+CTRL-]		Trigger abbreviation, without inserting a character.  {not in
+		Vi}
+						*i_<Insert>*
+<Insert>	Toggle between Insert and Replace mode.  {not in Vi}
+-----------------------------------------------------------------------
+						*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" and "2" 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.
+{Vi: does not cross lines, does not delete past start position of insert}
+						*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		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.
+						*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|.  These are not available
+when Vim was compiled without the |+insert_expand| feature.
+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.
+						*i_CTRL-X_CTRL-Y*
+CTRL-X CTRL-Y		scroll window one line down.
+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>*
+<MouseDown>	scroll three lines down			     *i_<MouseDown>*
+<S-MouseDown>	scroll a full page down			     *i_<S-MouseDown>*
+<MouseUp>	scroll three lines up			     *i_<MouseUp>*
+<S-MouseUp>	scroll a full page up			     *i_<S-MouseUp>*
+CTRL-O		execute one command, return to Insert mode   *i_CTRL-O*
+CTRL-G u	break undo sequence, start new change	     *i_CTRL-G_u*
+-----------------------------------------------------------------------
+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).
+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.
+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.
+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).  {Vi does not have the 'expandtab'
+option}
+							*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.  {not in Vi}
+							*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).  {Vi does not have the 'expandtab' option}
+==============================================================================
+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}
+{Vi does not have Virtual Replace mode}
+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 times characters beyond the cursor should appear to move
+are in 'list' mode, and occasionally when 'wrap' is set (and the line changes
+length to become shorter or wider than the width of the screen), or
+momentarily when typing over a CTRL character.  A CTRL character takes up two
+screen spaces.  When replacing it with two normal characters, the first will
+be inserted and the second will replace the CTRL character.
+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 modes, 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).
+These commands are not available when the |+insert_expand| feature was
+disabled at compile time.
+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. keywords in 'complete'				|i_CTRL-N|
+All these (except 2) 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).
+Also see the 'infercase' option if you want to adjust the case of the match.
+Note: The keys that are valid in CTRL-X mode are not mapped.  This allows for
+":map ^F ^X^F" to work (where ^F is CTRL-F and ^X is CTRL-X).  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.
+The following mappings are suggested to make typing the completion commands
+a bit easier (although they will hide other commands): >
+:inoremap ^] ^X^]
+:inoremap ^F ^X^F
+:inoremap ^D ^X^D
+:inoremap ^L ^X^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>"
+	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 in the current line before the
+			cursor.  Indent is ignored.  The found line is
+			inserted in front of the cursor.
+			The 'complete' option is used to decide in which
+			buffers a match is searched for.  But only loaded
+			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.
+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]);
+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 next 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.
+	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.
+							*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.
+			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.
+	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.
+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.
+							*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 |i_CTRL-Q|.
+	CTRL-V	or
+	CTRL-N		Search forwards for next match.  This match replaces
+			the previous one.
+	CTRL-P		Search backward 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 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.
+==============================================================================
+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.
+<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.
+							*gI*
+gI			Insert text in column 1 [count] times.  {not in Vi}
+							*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 wont be changed.
+			{not in Vi}
+							*o*
+o			Begin a new line below the cursor and insert text,
+			repeat [count] times.  {Vi: blank [count] screen
+			lines}
+							*O*
+O			Begin a new line above the cursor and insert text,
+			repeat [count] times.  {Vi: blank [count] screen
+			lines}
+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.
+'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.
+							*: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.
+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|.
+NOTE: ":append" and ":insert" don't work properly in between ":if" and
+":endif".
+							*: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.
+			{not in Vi}
+			{not available when compiled without the +ex_extra
+			feature}
+							*: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
+==============================================================================
+10. Inserting a file					*inserting-file*
+							*:r* *:re* *:read*
+:r[ead] [name]		Insert the file [name] (default: current file) below
+			the cursor.
+:{range}r[ead] [name]	Insert the file [name] (default: current file) below
+			the specified line.
+							*:r!* *:read!*
+:r[ead] !{cmd}		Execute {cmd} and insert its standard output below
+			the cursor.  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 |:!|.
+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.
+							*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-MS-DOS, Win32, and OS/2 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, MS-DOS, Win32, and OS/2 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:ft=help:norl:

Mercurial > vim

comparison runtime/doc/insert.txt @ 7:3fc0f57ecb91 v7.0001