*insert.txt*    For Vim version 5.0j.  Last modification: 1997 May 29


		  VIM REFERENCE MANUAL    by Bram Moolenaar


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.

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. Insert mode completion				|ins_completion|
7. Insert mode commands					|inserting|
8. Ex insert commands					|inserting-ex|
9. Inserting a file					|inserting-file|

==============================================================================
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.

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.

char		action
-----------------------------------------------------------------------
						*i_CTRL-[* *i_<Esc>*
<Esc> or CTRL-[	End insert or Replace mode, go back to Normal mode.  Finish
		abbreviation.
						*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>*
<BS> or CTRL-H	Delete the character before the cursor (see |i_backspacing|
		about joining lines).  See |:fixdel| if your <BS> does not do
		what you want.  {Vi: does not delete autoindents}
						*i_<Del>*
<Del>		Delete the character under the cursor.  If the cursor is at
		the end of the line, and the 'backspace' option is non-zero,
		delete the newline; 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>*
<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).  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 4.7, |digraphs|).  When {char1} is a special
		key, the code for that key is inserted.  Neither char is
		considered for mapping.  {not in Vi}

CTRL-N		Find next keyword (see 4.3.6, |i_CTRL-N|).  {not in Vi}
CTRL-P		Find previous keyword (see 4.3.6, |i_CTRL-P|).  {not in Vi}

CTRL-R <0-9a-z"%#:.-=>				*i_CTRL-R*
		Insert the contents of 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 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}

						*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.  Up to three digits form the
		decimal value of a single byte (see below |i_CTRL-V_digit|.
		The non-digit and the three digits are not considered for
		mapping.  {Vi: no decimal byte entry}

						*i_CTRL-Q*
CTRL-Q		Same as CTRL-V.

CTRL-X		Enter CTRL-X mode.  This is a sub-mode where commands can
		be given to complete words or scroll the window. See below,
		|i_CTRL-X|, and in 4.3.6, |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}

						*i_CTRL-B*
CTRL-B		Toggle the 'revins' option (B for Backwards).  Only if
		compiled with RIGHTLEFT (which is not the default).  See
		|ins_reverse|.  {not in Vi}
						*i_CTRL-_*
CTRL-_		This key is only available if Vim was compiled with RIGHTLEFT.
		Its purpose is to switch between languages while in insert
		mode, 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, unlike
		CTRL-B which leaves the cursor in the same place.

		Please refer to |rightleft.txt| for more information about
		right-to-left mode.  {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):

backspace	action
 option
   0	   delete stops in column 1 and start position of insert
   1	   delete stops at start position of insert
   2	   delete always; CTRL-W and CTRL-U stop once at start position of
	   insert

If the 'backspace' option is non-zero 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 newline 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 followed by one, two, or three digits, you can enter the decimal
value of any byte, except 10.  Normally CTRL-V is followed by three digits.
The formed byte is inserted as soon as you type the third digit.  If you type
only one or two digits and then a non-digit, the decimal value of those one
or two digits form the byte.  After that the non-digit 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.  The maximum value that can be entered is 255.

						*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 4.3.6, |ins_completion|.  These are only
available when Vim was compiled with INSERT_EXPAND defined.  If ":version"
shows "+insert_expand" then it was; if it shows "-insert_expand" then these
commands are not available.  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 2 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>*
<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>*
CTRL-O		execute one command, return to Insert mode   *i_CTRL-O*
-----------------------------------------------------------------------

The CTRL-O command sometimes has one side effect: If the cursor was beyond the
end of the line, it will be put on the last character in the line.
The shifted cursor keys are not available on all terminals.

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.

==============================================================================
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.

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.
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_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. 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).
Completion can be done for:

1. Whole lines						|i_CTRL-X_CTRL-L|
2. keywords in the current file				|i_CTRL-N|
3. keywords in 'dictionary'				|i_CTRL-X_CTRL-K|
4. keywords in the current and included files		|i_CTRL-X_CTRL-I|
5. tags							|i_CTRL-X_CTRL-]|
6. file names						|i_CTRL-X_CTRL-F|
7. definitions or macros				|i_CTRL-X_CTRL-D|

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.

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


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.
	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.

Completing keywords in current file			*compl_current*

							*i_CTRL-P*
							*i_CTRL-N*
The keys CTRL-N and CTRL-P can be used to complete the keyword that is in
front of the cursor.  This is useful if you are writing a program that has
complicated variable names, and you want to copy a name from the text before
or after the cursor.

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).

With CTRL-N (next), the search goes forward; with CTRL-P (previous), the
search goes backward.  The first time the search starts where the cursor is.
Subsequently, the search starts at the last found position.  If you type any
other character than CTRL-P or CTRL-N, the current text is accepted and the
search pattern is forgotten.

If the search found a match, it is inserted at the cursor position.  Any
previous match is replaced.  If no match was found, Vim will beep.

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).

If there is only one completion found, then a second CTRL-P or CTRL-N will
give the message 'No other matches'.

If the only match in the file is an exact match, where no extra characters
would be typed, then the message 'Exact match only' is given (this is also
useful for checking that you typed the word correctly).

The mode "-- INSERT --" is shown, unless there is another more important
message (e.g., "Pattern not found").  This other message will stay until
another key is hit, and then the mode is shown again.

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.


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.


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 succesful 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.


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-]|.
	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.

==============================================================================
7. 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.

							*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.

							*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}

							*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.


==============================================================================
8. 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* *: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 ".".

==============================================================================
9. Inserting a file					*inserting-file*

							*:r* *: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.

							*textmode_read*
The <NL> character is recognized as end-of-line marker.  If the 'textmode'
option is on, a <CR> in front of an <NL> is ignored and a CTRL-Z at the end
of the file is ignored.  The 'textmode' option is default on for MS-DOS, Win32
and OS/2.

If the 'textauto' option is on Vim tries to recognize the type of end-of-line
marker (see |textmode_io|).  However, the 'textmode' option will not be
changed.  Only while reading the file the text mode is used or not.

On non-MS-DOS, Win32, and OS/2 systems the message "[textmode]" is shown if a
file is read in text mode, to remind you that something unusual is done.  On
MS-DOS, Win32, and OS/2 the message "[notextmode]" is shown if a file is read
without text mode.

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.

 vim:tw=78:ts=8:sw=8: