summaryrefslogtreecommitdiff
path: root/runtime/doc/insert.txt
blob: 1439dbeaf9fe4da6366fff5488d29186b460bc92 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
*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: