docs/*/Makefile: create html subdir if needed
[nvi.git] / docs / vitut / vi.apwh.ms
blob1f5f9c5cad94e82f4e75f3c9d318d102364e0428
1 .\" Copyright (c) 1980, 1993
2 .\"     The Regents of the University of California.  All rights reserved.
3 .\"
4 .\" %sccs.include.redist.roff%
5 .\"
6 .\"     $Id: vi.apwh.ms,v 8.3 2001/01/28 13:48:01 skimo Exp $ (Berkeley) $Date: 2001/01/28 13:48:01 $
7 .\"
8 .nr LL 6.5i
9 .nr FL 6.5i
10 .TL
11 Vi Command & Function Reference
12 .AU
13 Alan P.W. Hewett
14 .sp
15 Revised for version 2.12 by Mark Horton
16 .NH 1
17 Author's Disclaimer
18 .LP
19 This document does not claim to be 100% complete.  There are a
20 few commands listed in the original document that I was unable
21 to test either because I do not speak \fBlisp\fR, because they
22 required programs we don't have, or because I wasn't able to make
23 them work.  In these cases I left the command out.  The commands
24 listed in this document have been tried and are known to work.
25 It is expected that prospective users of this document will read
26 it once to get the flavor of everything that \fBvi\fR can do
27 and then use it as a reference document.  Experimentation is
28 recommended.  If you don't understand a command, try it and
29 see what happens.
30 .LP
31 [Note: In revising this document, I have attempted to make it
32 completely reflect version 2.12 of
33 .B vi .
34 It does not attempt to document the VAX version (version 3),
35 but with one or two exceptions (wrapmargin, arrow keys)
36 everything said about 2.12 should apply to 3.1.
37 .I "Mark Horton" ]
38 .NH 1
39 Notation
40 .LP
41 \fB[option]\fR is used to denote optional parts of a command.
42 Many \fBvi\fR commands have an optional count.  \fB[cnt]\fR
43 means that an optional number may precede the command to
44 multiply or iterate the command.
45 \fB{variable item}\fR is used to denote parts of the command
46 which must appear, but can take a number of different values.
47 \fB<character [-character]>\fR means that the character or
48 one of the characters in the range described between the
49 two angle brackets is to be typed.
50 For example \fB<esc>\fR means
51 the \fBescape\fR key is to be typed.  \fB<a-z>\fR means that a
52 lower case letter is to be typed.  \fB^<character>\fR means that
53 the character is to be typed as a \fBcontrol\fR character, that is,
54 with the \fB<cntl>\fR key held down while simultaneously typing
55 the specified character.  In this document control characters will
56 be denoted using the \fIupper case\fR character, but
57 ^<uppercase chr> and ^<lowercase chr> are equivalent.  That is, for
58 example, \fB<^D>\fR is equal to \fB<^d>\fR.
59 The most common character abbreviations
60 used in this list are as follows:
61 .IP <esc> 8
62 escape, octal 033
63 .IP <cr> 8
64 carriage return, ^M, octal 015
65 .IP <lf> 8
66 linefeed ^J, octal 012
67 .IP <nl> 8
68 newline, ^J, octal 012 (same as linefeed)
69 .IP <bs> 8
70 backspace, ^H, octal 010
71 .IP <tab> 8
72 tab, ^I, octal 011
73 .IP <bell> 8
74 bell, ^G, octal 07
75 .IP <ff> 8
76 formfeed, ^L, octal 014
77 .IP <sp> 8
78 space, octal 040
79 .IP <del> 8
80 delete, octal 0177
81 .sp 1
82 .NH 1
83 Basics
84 .LP
85 To run \fBvi\fR the shell variable \fBTERM\fR must be defined and
86 exported to your environment.
87 How you do this depends on which shell you are using.
88 You can tell which shell you have by the character it
89 prompts you for commands with.
90 The Bourne shell prompts with `$', and the C shell prompts with `%'.
91 For these examples, we will suppose
92 that you are using an HP 2621 terminal, whose termcap name is ``2621''.
93 .NH 2
94 Bourne Shell
95 .LP
96 To manually set your terminal type to 2621 you would type:
97 .DS
98 TERM=2621
99 export TERM
102 There are various ways of having this automatically or
103 semi-automatically done when you log in.
104 Suppose you usually dial in on a 2621.
105 You want to tell this to the machine, but still have it
106 work when you use a hardwired terminal.
107 The recommended way, if you have the
108 .B tset
109 program, is to use the sequence
111 tset \-s \-d 2621 > tset$$
112 \&. tset$$
113 rm tset$$
115 in your .login (for csh) or the same thing using `.' instead of `source'
116 in your .profile (for sh).
117 The above line says that if you are dialing in you are on a 2621,
118 but if you are on a hardwired terminal it figures out your terminal
119 type from an on-line list.
120 .NH 2
121 The C Shell
123 To manually set your terminal type to 2621 you would type:
125 setenv TERM 2621
128 There are various ways of having this automatically or
129 semi-automatically done when you log in.
130 Suppose you usually dial in on a 2621.
131 You want to tell this to the machine, but still have it
132 work when you use a hardwired terminal.
133 The recommended way, if you have the
134 .B tset
135 program, is to use the sequence
137 tset \-s \-d 2621 > tset$$
138 source tset$$
139 rm tset$$
141 in your .login.*
143 * On a version 6 system
144 without environments, the invocation of tset
145 is simpler, just add the line ``tset \-d 2621''
146 to your .login or .profile.
148 The above line says that if you are dialing in you are on a 2621,
149 but if you are on a hardwired terminal it figures out your terminal
150 type from an on-line list.
151 .NH 1
152 Normal Commands
154 \fBVi\fR is a visual editor with a window on the file.  What
155 you see on the screen is \fBvi\fR's current notion of
156 what your file will contain,
157 (at this point in the file),
158 when it is written out.
159 Most commands do not cause any change in the screen until the
160 complete command is typed.  Should you get confused while
161 typing a command, you can abort the command by typing an
162 <del> character.  You will know you are back to command level
163 when you hear a <bell>.  Usually typing an <esc> will produce the
164 same result.  When \fBvi\fR gets an improperly formatted command
165 it rings the <bell>.
166 Following are the \fBvi\fR commands broken down by function.
167 .NH 2
168 Entry and Exit
170 To enter
171 .B vi
172 on a particular
173 .I file ,
174 type
176 \fBvi\fP \fIfile\fP
178 The file will be read in and the cursor will be placed at the beginning
179 of the first line.
180 The first screenfull of the file will be displayed on the terminal.
182 To get out of the editor, type
186 If you are in some special mode, such as input mode
187 or the middle of a multi-keystroke command, it may
188 be necessary to type <esc> first.
189 .NH 2
190 Cursor and Page Motion
192 .B NOTE:
193 The arrow keys (see the next four commands)
194 on certain kinds of terminals will not work with the
195 PDP-11 version of vi.  The control versions or the hjkl versions will
196 work on any terminal.  Experienced users prefer the hjkl keys because
197 they are always right under their fingers.  Beginners often prefer
198 the arrow keys, since they do not require memorization of which hjkl
199 key is which.
200 The mnemonic value of hjkl is clear from looking at the keyboard of an adm3a.
202 .IP "[cnt]<bs> or [cnt]h or [cnt]\(<-" 16
204 Move the cursor to the left one character.  Cursor stops at the left
205 margin of the page.
206 If cnt is given, these commands move that many spaces.
207 .IP "[cnt]^N or [cnt]j or [cnt]\(da or [cnt]<lf>" 16
209 Move down one line.
210 Moving off the screen scrolls the window to force a new line
211 onto the screen.
212 Mnemonic: \fBN\fRext
213 .IP "[cnt]^P or [cnt]k or [cnt]\(ua" 16
215 Move up one line.
216 Moving off the top of the screen forces new text onto the screen.
217 Mnemonic: \fBP\fRrevious
218 .IP "[cnt]<sp> or [cnt]l or [cnt]\(->" 16
220 Move to the right one character.
221 Cursor will not go beyond the end of the line.
222 .IP [cnt]- 16
223 Move the cursor up the screen to the beginning of the next line.
224 Scroll if necessary.
225 .IP "[cnt]+ or [cnt]<cr>" 16
226 .sp 1
227 Move the cursor down the screen to the beginning of the next line.
228 Scroll up if necessary.
229 .IP "[cnt]$" 16
230 Move the cursor to the end of the line.
231 If there is a count, move to the end of the line "cnt" lines
232 forward in the file.
233 .IP "^" 16
234 Move the cursor to the beginning of the first word on the line.
235 .IP "0" 16
236 Move the cursor to the left margin of the current line.
237 .IP "[cnt]|" 16
238 Move the cursor to the column specified by the count.  The default is
239 column zero.
240 .IP "[cnt]w" 16
241 Move the cursor to the beginning of the next word. If there
242 is a count, then move forward that many words and
243 position the cursor at the beginning of the word.
244 Mnemonic: next-\fBw\fRord
245 .IP "[cnt]W" 16
246 Move the cursor to the beginning of the next word which follows
247 a "white space" (<sp>,<tab>, or <nl>).  Ignore other punctuation.
248 .IP "[cnt]b" 16
249 Move the cursor to the preceding word.  Mnemonic: \fBb\fRackup-word
250 .IP "[cnt]B" 16
251 Move the cursor to the preceding word that is separated from the
252 current word by a "white space" (<sp>,<tab>, or <nl>).
253 .IP "[cnt]e" 16
254 Move the cursor to the end of the current word or the end of the
255 "cnt"'th word hence.  Mnemonic: \fBe\fRnd-of-word
256 .IP "[cnt]E" 16
257 Move the cursor to the end of the current word which is delimited by
258 "white space" (<sp>,<tab>, or <nl>).
259 .IP "[line number]G" 16
261 Move the cursor to the line specified.  Of particular use are the
262 sequences "1G" and "G", which move the cursor to the beginning and
263 the end of the file respectively.  Mnemonic: \fBG\fRo-to
265 .B NOTE:
266 The next four commands (^D, ^U, ^F, ^B)
267 are not true motion commands, in that they
268 cannot be used as the object of commands such as delete or change.
269 .IP "[cnt]^D" 16
270 Move the cursor down in the file by "cnt" lines (or the last "cnt"
271 if a new count isn't given.  The initial default is half a page.)  The
272 screen is simultaneously scrolled up.  Mnemonic: \fBD\fRown
273 .IP "[cnt]^U" 16
274 Move the cursor up in the file by "cnt" lines.  The screen is simultaneously
275 scrolled down.  Mnemonic: \fBU\fRp
276 .IP "[cnt]^F" 16
277 Move the cursor to the next page.  A count moves that many pages.
278 Two lines of the previous page are kept on the screen for continuity if
279 possible.  Mnemonic: \fBF\fRorward-a-page
280 .IP "[cnt]^B" 16
281 Move the cursor to the previous page.  Two lines of the current page
282 are kept if possible.  Mnemonic: \fBB\fRackup-a-page
283 .IP "[cnt](" 16
284 Move the cursor to the beginning of the next sentence.
285 A sentence is defined as ending with a ".", "!", or "?"
286 followed by two spaces or a <nl>.
287 .IP "[cnt])" 16
288 Move the cursor backwards to the beginning of a sentence.
289 .IP "[cnt]}" 16
290 Move the cursor to the beginning of the next paragraph.  This command
291 works best inside \fBnroff\fR documents.  It understands two sets of
292 \fBnroff\fR macros, \fB\-ms\fR and \fB\-mm\fR, for which the
293 commands ".IP", ".LP", ".PP", ".QP", "P", as well as the nroff command ".bp"
294 are considered to be paragraph delimiters.
295 A blank line also delimits a paragraph.
296 The \fBnroff\fR macros that it accepts as paragraph delimiters is
297 adjustable.  See \fBparagraphs\fR under the \fBSet Commands\fR section.
298 .IP "[cnt]{" 16
299 Move the cursor backwards to the beginning of a paragraph.
300 .IP "]]" 16
301 Move the cursor to the next "section", where a section is defined by
302 two sets of \fBnroff\fR macros, \fB\-ms\fR and \fB\-mm\fR, in which
303 ".NH", ".SH", and ".H" delimit a section.  A line beginning with a <ff><nl>
304 sequence, or a line beginning with a "{" are also considered to
305 be section delimiters.  The last option makes it
306 useful for finding the beginnings of C functions.
307 The \fBnroff\fR macros that are used for section delimiters can be adjusted.
308 See \fBsections\fR under the \fBSet Commands\fR section.
309 .IP "[[" 16
310 Move the cursor backwards to the beginning of a section.
311 .IP "%" 16
312 Move the cursor to the matching parenthesis
313 or brace.  This is very useful in C or lisp code.  If the
314 cursor is sitting on a \fB( ) {\fR or \fB}\fR the cursor
315 is moved to the matching character at the other end of the
316 section.  If the cursor is not sitting on a brace or a
317 parenthesis, \fBvi\fR searches forward until it finds one
318 and then jumps to the match mate.
319 .IP "[cnt]H" 16
320 If there is no count move the cursor to the top left position on the screen.
321 If there is a count, then move the cursor to the beginning of the line
322 "cnt" lines from the top of the screen.  Mnemonic:  \fBH\fRome
323 .IP "[cnt]L" 16
324 If there is no count move the cursor to the beginning
325 of the last line on the screen.
326 If there is a count, then move the cursor to the beginning of the line
327 "cnt" lines from the bottom of the screen.  Mnemonic: \fBL\fRast
328 .IP "M" 16
329 Move the cursor to the beginning of the middle line on the screen.
330 Mnemonic: \fBM\fRiddle
331 .IP "m<a-z>" 16
332 This command does not move the cursor, but it \fBmarks\fR the place
333 in the file and the character "<a-z>" becomes the label for referring
334 to this location in the file.  See the next two commands.  Mnemonic:
335 \fBm\fRark
336 .B NOTE:
337 The mark command is not a motion, and cannot be used as the target
338 of commands such as delete.
339 .IP "\(aa<a-z>" 16
340 Move the cursor to the beginning of the line that is marked with the label
341 "<a-z>".
342 .IP "\(ga<a-z>" 16
343 Move the cursor to the exact position on the line that was marked with
344 with the label "<a-z>".
345 .IP "\(aa\(aa" 16
346 Move the cursor back to the beginning of the line where it was before the
347 last "non-relative" move.  A "non-relative" move is something such as a
348 search or a jump to a specific line in the file, rather than moving the
349 cursor or scrolling the screen.
350 .IP "\(ga\(ga" 16
351 Move the cursor back to the exact spot on the line where it was located
352 before the last "non-relative" move.
353 .NH 2
354 Searches
356 The following commands allow you to search for items in a file.
357 .IP [cnt]f{chr} 16
358 .sp 1
359 Search forward on the line for the next or "cnt"'th occurrence of
360 the character "chr".  The cursor is placed \fBat\fR the character
361 of interest.  Mnemonic: \fBf\fRind character
362 .IP [cnt]F{chr} 16
363 .sp 1
364 Search backwards on the line for the next or "cnt"'th occurrence of
365 the character "chr".  The cursor is placed \fBat\fR the character
366 of interest.
367 .IP [cnt]t{chr} 16
368 .sp 1
369 Search forward on the line for the next or "cnt"'th occurrence of
370 the character "chr".  The cursor is placed \fBjust preceding\fR
371 the character of interest.  Mnemonic: move cursor up \fBt\fRo character
372 .IP [cnt]T{chr} 16
373 .sp 1
374 Search backwards on the line for the next or "cnt"'th occurrence of
375 the character "chr".  The cursor is placed \fBjust preceding\fR
376 the character of interest.
377 .IP "[cnt];" 16
378 Repeat the last "f", "F", "t" or "T" command.
379 .IP "[cnt]," 16
380 Repeat the last "f", "F", "t" or "T" command, but in the opposite
381 search direction.  This is useful if you overshoot.
382 .IP "[cnt]/[string]/<nl>" 16
384 Search forward for the next occurrence of "string".
385 Wrap around at the end of the file
386 does occur.
387 The final \fB</>\fR is not required.
388 .IP "[cnt]?[string]?<nl>" 16
390 Search backwards for the next occurrence of "string".  If a count is
391 specified, the count becomes the new window size.  Wrap around at the beginning
392 of the file does occur.
393 The final \fB<?>\fR is not required.
394 .IP n 16
395 Repeat the last /[string]/ or ?[string]? search.  Mnemonic: \fBn\fRext
396 occurrence.
397 .IP N 16
398 Repeat the last /[string]/ or ?[string]? search, but in the reverse
399 direction.
400 .IP ":g/[string]/[editor command]<nl>" 16
401 .sp 1
402 Using the \fB:\fR syntax it is possible to do global searches ala the
403 standard UNIX "ed" editor.
404 .NH 2
405 Text Insertion
407 The following commands allow for the insertion of text.  All multicharacter
408 text insertions are terminated with an <esc> character.
409 The last change
410 can always be \fBundone\fR by typing a \fBu\fR.
411 The text insert in insertion mode can contain newlines.
412 .IP a{text}<esc> 16
413 Insert text immediately following the cursor position.
414 Mnemonic: \fBa\fRppend
415 .IP A{text}<esc> 16
416 Insert text at the end of the current line.
417 Mnemonic: \fBA\fRppend
418 .IP i{text}<esc> 16
419 Insert text immediately preceding the cursor position.
420 Mnemonic: \fBi\fRnsert
421 .IP I{text}<esc> 16
422 Insert text at the beginning of the current line.
423 .IP o{text}<esc> 16
424 Insert a new line after the line on which the cursor appears and
425 insert text there.  Mnemonic:  \fBo\fRpen new line
426 .IP O{text}<esc> 16
427 Insert a new line preceding the line on which the cursor appears
428 and insert text there.
429 .NH 2
430 Text Deletion
432 The following commands allow the user to delete text in various ways.
433 All changes can always be \fBundone\fR by typing the \fBu\fR command.
434 .IP "[cnt]x" 16
435 Delete the character or characters starting at the cursor position.
436 .IP "[cnt]X" 16
437 Delete the character or characters starting at the character preceding
438 the cursor position.
439 .IP "D" 16
440 Deletes the remainder of the line starting at the cursor.
441 Mnemonic: \fBD\fRelete the rest of line
442 .IP "[cnt]d{motion}" 16
444 Deletes one or more occurrences of the specified motion.
445 Any motion from sections 4.1 and 4.2 can be used here.
446 The d can be stuttered (e.g. [cnt]dd) to delete cnt lines.
447 .NH 2
448 Text Replacement
450 The following commands allow the user to simultaneously delete and
451 insert new text.  All such actions can be \fBundone\fR by typing
452 \fBu\fR following the command.
453 .IP "r<chr>" 16
454 Replaces the character at the current cursor position with <chr>.  This
455 is a one character replacement.  No <esc> is required for termination.
456 Mnemonic:  \fBr\fReplace character
457 .IP "R{text}<esc>" 16
458 Starts overlaying the characters on the screen with whatever you type.
459 It does not stop until an <esc> is typed.
460 .IP "[cnt]s{text}<esc>" 16
461 Substitute for "cnt" characters beginning at the current cursor
462 position.  A "$" will appear at the position in the text where the
463 "cnt"'th character appears so you will know how much you are erasing.
464 Mnemonic: \fBs\fRubstitute
465 .IP "[cnt]S{text}<esc>" 16
466 Substitute for the entire current line (or lines).  If no count is given,
467 a "$" appears at the end of the current line.  If a count of more than
468 1 is given, all the lines to be replaced are deleted before the insertion
469 begins.
470 .IP "[cnt]c{motion}{text}<esc>" 16
472 Change the specified "motion" by replacing it with the
473 insertion text.  A "$" will appear at the end of the last item
474 that is being deleted unless the deletion involves whole lines.
475 Motion's can be any motion from sections 4.1 or 4.2.
476 Stuttering the c (e.g. [cnt]cc) changes cnt lines.
477 .NH 2
478 Moving Text
480 \fBVi\fR provides a number of ways of moving chunks of text around.
481 There are nine buffers into which each piece of text which is deleted
482 or "yanked" is put in addition to the "undo" buffer.
483 The most recent deletion or yank is in the "undo" buffer and also
484 usually in buffer
485 1, the next most recent in buffer 2, and so forth.  Each new deletion
486 pushes down all the older deletions.  Deletions older than 9
487 disappear.  There is also
488 a set of named registers, a-z, into which text can optionally
489 be placed.  If any delete or replacement type command is preceded
490 by \fB"<a-z>\fR, that named buffer will contain the text deleted
491 after the command is executed.  For example, \fB"a3dd\fR will delete
492 three lines starting at the current line and put them in buffer \fB"a\fR.*
494 * Referring to an upper case letter as a buffer name (A-Z) is the
495 same as referring to the lower case letter, except that text placed
496 in such a buffer is appended to it instead of replacing it.
498 There are two more basic commands and
499 some variations useful in getting and putting text into a file.
500 .IP ["<a-z>][cnt]y{motion} 16
501 .sp 1
502 Yank the specified item or "cnt" items and put in the "undo" buffer or
503 the specified buffer.  The variety of "items" that can be yanked
504 is the same as those that can be deleted with the "d" command or
505 changed with the "c" command.  In the same way that "dd" means
506 delete the current line and "cc" means replace the current line,
507 "yy" means yank the current line.
508 .IP ["<a-z>][cnt]Y 16
509 Yank the current line or the "cnt" lines starting from the current
510 line.  If no buffer is specified, they will go into the "undo" buffer,
511 like any delete would.  It is equivalent to "yy".
512 Mnemonic:  \fBY\fRank
513 .IP ["<a-z>]p 16
514 Put "undo" buffer or the specified buffer down \fBafter\fR the cursor.
515 If whole lines were yanked or deleted into the buffer, then they will be
516 put down on the line following the line the cursor is on.  If
517 something else was deleted, like a word or sentence, then it will
518 be inserted immediately following the cursor.
519 Mnemonic:  \fBp\fRut buffer
521 It should be noted that text in the named buffers remains there when you
522 start editing a new file with the \fB:e file<esc>\fR command.  Since
523 this is so, it is possible to copy or delete text from one file and
524 carry it over to another file in the buffers.
525 However, the undo buffer and the ability to undo are lost when
526 changing files.
527 .IP ["<a-z>]P 16
528 Put "undo" buffer or the specified buffer down \fBbefore\fR the cursor.
529 If whole lines where yanked or deleted into the buffer, then they will be
530 put down on the line preceding the line the cursor is on.  If
531 something else was deleted, like a word or sentence, then it will
532 be inserted immediately preceding the cursor.
533 .IP [cnt]>{motion} 16
534 The shift operator will right shift all the text from the line on which
535 the cursor is located to the line where the \fBmotion\fR is located.
536 The text is shifted by one \fBshiftwidth\fR.  (See section 6.)
537 \fB>>\fR means right shift the current line or lines.
538 .IP [cnt]<{motion} 16
539 The shift operator will left shift all the text from the line on which
540 the cursor is located to the line where the \fBitem\fR is located.
541 The text is shifted by one \fBshiftwidth\fR.  (See section 6.)
542 \fB<<\fR means left shift the current line or lines.
543 Once the line has reached the left margin it is not further affected.
544 .IP [cnt]={motion} 16
545 Prettyprints the indicated area according to
546 .B lisp
547 conventions.
548 The area should be a lisp s-expression.
549 .NH 2
550 Miscellaneous Commands
552 \fBVi\fR has a number of miscellaneous commands that are very
553 useful.  They are:
554 .IP ZZ 16
555 This is the normal way to exit from vi.
556 If any changes have been made, the file is written out.
557 Then you are returned to the shell.
558 .IP ^L 16
559 Redraw the current screen.  This is useful if someone "write"s you
560 while you are in "vi" or if for any reason garbage gets onto the
561 screen.
562 .IP ^R 16
563 On dumb terminals, those not having the "delete line" function
564 (the vt100 is such a terminal), \fBvi\fR saves redrawing the
565 screen when you delete a line by just marking the line with an
566 "@" at the beginning and blanking the line.  If you want to
567 actually get rid of the lines marked with "@" and see what the
568 page looks like, typing a ^R will do this.
569 .IP \s+4.\s0 16
570 "Dot" is a particularly useful command.  It repeats the last
571 text modifying command.  Therefore you can type a command once and
572 then to another place and repeat it by just typing ".".
573 .IP u 16
574 Perhaps the most important command in the editor,
575 u undoes the last command that changed the buffer.
576 Mnemonic:  \fBu\fRndo
577 .IP U 16
578 Undo all the text modifying commands performed on the current line
579 since the last time you moved onto it.
580 .IP [cnt]J 16
581 Join the current line and the following line.  The <nl> is deleted
582 and the two lines joined, usually with a space between the
583 end of the first line and the beginning of what was the second
584 line.  If the first line ended with a "period", then two spaces
585 are inserted.
586 A count joins the next cnt lines.
587 Mnemonic: \fBJ\fRoin lines
588 .IP Q 16
589 Switch to \fBex\fR editing mode.
590 In this mode \fBvi\fR will behave very much like \fBed\fR.
591 The editor in this mode will operate on single lines normally and
592 will not attempt to keep the "window" up to date.
593 Once in this mode it is also possible to switch to the \fBopen\fR
594 mode of editing.  By entering the command \fB[line number]open<nl>\fR
595 you enter this mode.  It is similar to the normal visual mode
596 except the window is only \fBone\fR line long.
597 Mnemonic: \fBQ\fRuit visual mode
598 .IP ^] 16
599 An abbreviation for a tag command.
600 The cursor should be positioned at the beginning of a word.
601 That word is taken as a tag name, and the tag with that
602 name is found as if it had been typed in a :tag command.
603 .IP [cnt]!{motion}{UNIX\ cmd}<nl> 16
605 Any UNIX filter
606 (e.g. command that reads the standard input and outputs something
607 to the standard output) can be sent a section of the current file and
608 have the output of the command replace the original text.  Useful
609 examples are programs like \fBcb\fR, \fBsort\fR, and
610 \fBnroff\fR.  For instance, using \fBsort\fR it would be possible to
611 sort a section of the current file into a new list.
612 Using \fB!!\fR means take a line or lines starting at the line the
613 cursor is currently on and pass them to the UNIX command.
614 .B NOTE:
615 To just escape to the shell for one command,
616 use :!{cmd}<nl>, see section 5.
617 .IP z{cnt}<nl> 16
618 This resets the current window size to "cnt" lines and redraws the screen.
619 .NH 2
620 Special Insert Characters
622 There are some characters that have special meanings during
623 insert modes.  They are:
624 .IP ^V 16
625 During inserts, typing a ^V allows you to quote control characters
626 into the file.  Any character typed after the ^V will be inserted
627 into the file.
628 .IP [^]^D\ or\ [0]^D 16
629 <^D> without any argument backs up one \fBshiftwidth\fR.  This is necessary
630 to remove indentation that was inserted by the \fBautoindent\fR feature.
631 ^<^D> temporarily removes all the autoindentation, thus placing the cursor
632 at the left margin.  On the next line, the previous indent level will be
633 restored.  This is useful for putting "labels" at the left margin.
634 0<^D> says remove all autoindents and stay that way.  Thus the cursor
635 moves to the left margin and stays there on successive lines until
636 <tab>'s are typed.  As with the <tab>, the <^D> is only effective before
637 any other "non-autoindent" controlling characters are typed.
638 Mnemonic: \fBD\fRelete a shiftwidth
639 .IP ^W 16
640 If the cursor is sitting on a word, <^W> moves the cursor back to the beginning
641 of the word, thus erasing the word from the insert.
642 Mnemonic: erase \fBW\fRord
643 .IP <bs> 16
644 The backspace always serves as an erase during insert modes in addition
645 to your normal "erase" character.  To insert a <bs> into your file, use
646 the <^V> to quote it.
647 .NH 1
648 \fB:\fR Commands
650 Typing a ":" during command mode causes \fBvi\fR to put the cursor at
651 the bottom on the screen in preparation for a command.  In the
652 ":" mode, \fBvi\fR can be given most \fBed\fR commands.  It is
653 also from this mode that you exit from \fBvi\fR or switch to different
654 files.  All commands of this variety are terminated by a <nl>, <cr>,
655 or <esc>.
656 .IP ":w[!] [file]" 16
657 Causes \fBvi\fR to write out the current text to the disk.  It is
658 written to the file you are editing unless "file" is supplied.  If
659 "file" is supplied, the write is directed to that file instead.  If
660 that file already exists, \fBvi\fR will not perform the write unless
661 the "!" is supplied indicating you
662 .I really
663 want to destroy the older copy of the file.
664 .IP :q[!] 16
665 Causes \fBvi\fR to exit.  If you have modified the file you are
666 looking at currently and haven't written it out, \fBvi\fR will
667 refuse to exit unless the "!" is supplied.
668 .IP ":e[!] [+[cmd]] [file]" 16
669 .sp 1
670 Start editing a new file called "file" or start editing the current
671 file over again.  The command ":e!" says "ignore the changes I've made
672 to this file and start over from the beginning".  It is useful if
673 you really mess up the file.  The optional "+" says instead of starting
674 at the beginning, start at the "end", or,
675 if "cmd" is supplied, execute "cmd" first.
676 Useful cases of this are where cmd is "n" (any integer) which starts
677 at line number n,
678 and "/text", which searches for "text" and starts at the line where
679 it is found.
680 .IP "^^" 16
681 Switch back to the place you were before your last tag command.
682 If your last tag command stayed within the file, ^^ returns to that tag.
683 If you have no recent tag command, it will return to the
684 same place in the previous file that it was showing when you switched
685 to the current file.
686 .IP ":n[!]" 16
687 Start editing the next file in the argument list.  Since \fBvi\fR
688 can be called with multiple file names, the ":n" command tells it to
689 stop work on the current file and switch to the next file.  If the
690 current file was modifies, it has to be written out before the ":n"
691 will work or else the "!" must be supplied, which says discard the
692 changes I made to the current file.
693 .IP ":n[!] file [file file ...]" 16
695 Replace the current argument list with a new list of files and start
696 editing the first file in this new list.
697 .IP ":r file" 16
698 Read in a copy of "file" on the line after the cursor.
699 .IP ":r !cmd" 16
700 Execute the "cmd" and take its output and put it into the file after
701 the current line.
702 .IP ":!cmd" 16
703 Execute any UNIX shell command.
704 .IP ":ta[!] tag" 16
705 .B Vi
706 looks in the file named
707 .B tags
708 in the current directory.
709 .B Tags
710 is a file of lines in the format:
711 .sp 1
712 .ti +8
713 tag filename \fBvi\fR-search-command
714 .sp 1
715 If \fBvi\fR finds the tag you specified in the \fB:ta\fR command,
716 it stops editing the current file if necessary and if the current file is
717 up to date on the disk and switches to the file specified and uses the
718 search pattern specified to find the "tagged" item of interest.  This
719 is particularly useful when editing multi-file C programs such as the
720 operating system.  There is a program called \fBctags\fR which will
721 generate an appropriate \fBtags\fR file for C and f77
722 programs so that by saying
723 \fB:ta function<nl>\fR you will be switched to that function.
724 It could also be useful when editing multi-file documents, though the
725 \fBtags\fR file would have to be generated manually.
726 .NH 1
727 Special Arrangements for Startup
729 \fBVi\fR takes the value of \fB$TERM\fR and looks up the characteristics
730 of that terminal in the file \fB/etc/termcap\fR.
731 If you don't know \fBvi\fR's name for the terminal you are working
732 on, look in \fB/etc/termcap\fR.
734 When \fBvi\fR starts, it attempts to read the variable EXINIT
735 from your environment.*
736 If that exists, it takes the values in it as the default values
737 for certain of its internal constants.  See the section on "Set Values"
738 for further details.
739 If EXINIT doesn't exist you will get all the normal defaults.
741 * On version 6 systems
742 Instead of EXINIT, put the startup commands in the file .exrc
743 in your home directory.
746 Should you inadvertently hang up the phone while inside
747 .B vi ,
748 or should the computer crash,
749 all may not be lost.
750 Upon returning to the system, type:
752 vi \-r file
754 This will normally recover the file.  If there is more than one
755 temporary file for a specific file name, \fBvi\fR recovers the
756 newest one.  You can get an older version by recovering the
757 file more than once.
758 The command "vi -r" without a file name gives you the list of files
759 that were saved in the last system crash
760 (but
761 .I not
762 the file just saved when the phone was hung up).
763 .NH 1
764 Set Commands
766 \fBVi\fR has a number of internal variables and switches which can be
767 set to achieve special affects.
768 These options come in three forms, those that are switches, which toggle
769 from off to on and back, those that require a numeric value, and those
770 that require an alphanumeric string value.
771 The toggle options are set by a command of the form:
773 :set option<nl>
775 and turned off with the command:
777 :set nooption<nl>
779 Commands requiring a value are set with a command of the form:
781 :set option=value<nl>
783 To display the value of a specific option type:
785 :set option?<nl>
787 To display only those that you have changed type:
789 :set<nl>
791 and to display the long table of all the settable parameters and
792 their current values type:
794 :set all<nl>
797 Most of the options have a long form and an abbreviation.  Both are
798 listed in the following table as well as the normal default value.
800 To arrange to have values other than the default used every time you
801 enter
802 .B vi ,
803 place the appropriate
804 .B set
805 command in EXINIT in your environment, e.g.
807 EXINIT='set ai aw terse sh=/bin/csh'
808 export EXINIT
812 setenv EXINIT 'set ai aw terse sh=/bin/csh'
815 .B sh
817 .B csh ,
818 respectively.
819 These are usually placed in your .profile or .login.
820 If you are running a system without environments (such as version 6)
821 you can place the set command in the file .exrc in your home
822 directory.
823 .IP autoindent\ ai 16
824 Default: noai Type: toggle
826 When in autoindent mode, vi helps you indent code by starting each
827 line in the same column as the preceding line.
828 Tabbing to the right with <tab> or <^T> will move this boundary to
829 the right, and it can be moved to the left with <^D>.
830 .IP autoprint\ ap 16
831 Default: ap Type: toggle
833 Causes the current line to be printed after each ex text modifying command.
834 This is not of much interest in the normal \fBvi\fR visual mode.
835 .IP autowrite\ aw 16
836 Default: noaw type: toggle
838 Autowrite causes an automatic write to be done if there are unsaved
839 changes before certain commands which change files or otherwise
840 interact with the outside world.
841 These commands are :!, :tag, :next, :rewind, ^^, and ^].
842 .IP beautify\ bf 16
843 Default: nobf Type: toggle
845 Causes all control characters except <tab>, <nl>, and <ff> to be discarded.
846 .IP directory\ dir 16
847 Default: dir=/tmp Type: string
849 This is the directory in which \fBvi\fR puts its temporary file.
850 .IP errorbells\ eb 16
851 Default: noeb Type: toggle
853 Error messages are preceded by a <bell>.
854 .IP hardtabs\ ht 16
855 Default: hardtabs=8 Type: numeric
857 This option contains the value of hardware tabs in your terminal, or
858 of software tabs expanded by the Unix system.
859 .IP ignorecase\ ic 16
860 Default: noic Type: toggle
862 All upper case characters are mapped to lower case in regular expression
863 matching.
864 .IP lisp 16
865 Default: nolisp Type: toggle
867 Autoindent for \fBlisp\fR code.  The commands \fB( ) [[\fR and \fB]]\fR
868 are modified appropriately to affect s-expressions and functions.
869 .IP list 16
870 Default: nolist Type: toggle
872 All printed lines have the <tab> and <nl> characters displayed visually.
873 .IP magic 16
874 Default: magic Type: toggle
876 Enable the metacharacters for matching.  These include \fB. * < > [string]
877 [^string]\fR and \fB[<chr>-<chr>]\fR.
878 .IP number\ nu 16
879 Default: nonu Type: toggle
881 Each line is displayed with its line number.
882 .IP open 16
883 Default: open Type: toggle
885 When set, prevents entering open or visual modes from ex or edit.
886 Not of interest from vi.
887 .IP optimize\ opt 16
888 Default: opt Type: toggle
890 Basically of use only when using the \fBex\fR capabilities.  This
891 option prevents automatic <cr>s from taking place,
892 and speeds up output of indented lines,
893 at the expense of losing typeahead on some versions of UNIX.
894 .IP paragraphs\ para 16
895 Default: para=IPLPPPQPP\ bp Type: string
897 Each pair of characters in the string indicate \fBnroff\fR macros
898 which are to be treated as the beginning of a paragraph for the
899 \fB{\fR and \fB}\fR commands.  The default string is for the \fB-ms\fR
900 and \fB-mm\fR macros.
901 To indicate one letter \fBnroff\fR macros, such as \fB.P\fR or \fB.H\fR,
902 quote a space in for the second character position.  For example:
903 .sp 1
904 .ti +8
905 :set paragraphs=P\e bp<nl>
906 .sp 1
907 would cause \fBvi\fR to consider \fB.P\fR and \fB.bp\fR as paragraph
908 delimiters.
909 .IP prompt 16
910 Default: prompt Type: toggle
913 .B ex
914 command mode the prompt character \fB:\fR will be printed when
915 \fBex\fR is waiting for a command.  This is not of interest from vi.
916 .IP redraw 16
917 Default: noredraw Type: toggle
919 On dumb terminals, force the screen to always be up to date,
920 by sending great amounts of output.  Useful only at high speeds.
921 .IP report 16
922 Default: report=5 Type: numeric
924 This sets the threshold for the number of lines modified.  When
925 more than this number of lines are modified, removed, or yanked,
926 \fBvi\fR will report the number of lines changed at the bottom of
927 the screen.
928 .IP scroll 16
929 Default: scroll={1/2 window} Type: numeric
931 This is the number of lines that the screen scrolls up or down when
932 using the <^U> and <^D> commands.
933 .IP sections 16
934 Default: sections=SHNHH HU Type: string
936 Each two character pair of this string specify \fBnroff\fR macro names
937 which are to be treated as the beginning of a section by the
938 \fB]]\fR and \fB[[\fR commands.  The default string is for the \fB-ms\fR
939 and \fB-mm\fR macros.
940 To enter one letter \fBnroff\fR macros, use a quoted space as the
941 second character.
942 See \fBparagraphs\fR for a fuller explanation.
943 .IP shell\ sh 16
944 Default: sh=from environment SHELL or /bin/sh   Type: string
946 This is the name of the \fBsh\fR to be used for "escaped" commands.
947 .IP shiftwidth\ sw 16
948 Default: sw=8 Type: numeric
950 This is the number of spaces that a <^T> or <^D> will move over for
951 indenting, and the amount < and > shift by.
952 .IP showmatch\ sm 16
953 Default: nosm Type: toggle
955 When a \fB)\fR or \fB}\fR is typed, show the matching \fB(\fR or \fB{\fR
956 by moving the cursor to it for one second if it is on the current screen.
957 .IP slowopen\ slow 16
958 Default: terminal dependent Type: toggle
960 On terminals that are slow and unintelligent, this option prevents the
961 updating of the screen some of the time to improve speed.
962 .IP tabstop\ ts 16
963 Default: ts=8 Type: numeric
965 <tab>s are expanded to boundaries that are multiples of this value.
966 .IP taglength\ tl 16
967 Default: tl=0 Type: numeric
969 If nonzero, tag names are only significant to this many characters.
970 .IP term 16
971 Default: (from environment \fBTERM\fP, else dumb) Type: string
973 This is the terminal and controls the visual displays.  It cannot be
974 changed when in "visual" mode,
975 you have to Q to command mode, type a
976 set term command, and do ``vi.'' to get back into visual.
977 Or exit vi, fix $TERM, and reenter.
978 The definitions that drive a particular
979 terminal type are found in the file \fB/etc/termcap\fR.
980 .IP terse 16
981 Default: terse Type: toggle
983 When set, the error diagnostics are short.
984 .IP warn 16
985 Default: warn Type: toggle
987 The user is warned if she/he tries to escape to
988 the shell without writing out the current changes.
989 .IP window 16
990 Default: window={8 at 600 baud or less, 16 at 1200 baud, and screen
991 size \- 1 at 2400 baud or more} Type: numeric
993 This is the number of lines in the window whenever \fBvi\fR must redraw
994 an entire screen.  It is useful to make this size smaller if you are
995 on a slow line.
996 .IP w300,\ w1200,\ w9600
998 These set window, but only within the corresponding speed ranges.
999 They are useful in an EXINIT to fine tune window sizes.
1000 For example,
1002 set w300=4 w1200=12
1004 causes a 4 lines window at speed up to 600 baud, a 12 line window at 1200
1005 baud, and a full screen (the default) at over 1200 baud.
1006 .IP wrapscan\ ws 16
1007 Default: ws Type: toggle
1009 Searches will wrap around the end of the file when is option is set.  When
1010 it is off, the search will terminate when it reaches the end or the
1011 beginning of the file.
1012 .IP wrapmargin\ wm 16
1013 Default: wm=0 Type: numeric
1015 \fBVi\fR will automatically insert a <nl> when it finds a natural
1016 break point (usually a <sp> between words) that occurs within
1017 "wm" spaces of the right margin.
1018 Therefore with "wm=0" the option is off.  Setting it to 10 would
1019 mean that any time you are within 10 spaces of the right margin
1020 \fBvi\fR would be looking for a <sp> or <tab> which it could
1021 replace with a <nl>.  This is convenient for people who forget
1022 to look at the screen while they type.
1023 (In version 3, wrapmargin behaves more like nroff, in that the
1024 boundary specified by the distance from the right edge of the screen
1025 is taken as the rightmost edge of the area where a break is allowed,
1026 instead of the leftmost edge.)
1027 .IP writeany\ wa 16
1028 Default: nowa Type: toggle
1030 \fBVi\fR normally makes a number of checks before it writes out a file.
1031 This prevents the user from inadvertently destroying a file.  When the
1032 "writeany" option is enabled, \fBvi\fR no longer makes these checks.