Initial import from FreeBSD RELENG_4:
[dragonfly.git] / contrib / nvi / docs / USD.doc / vi.man / vi.1
1 .\" Copyright (c) 1994
2 .\"     The Regents of the University of California.  All rights reserved.
3 .\" Copyright (c) 1994, 1995, 1996
4 .\"     Keith Bostic.  All rights reserved.
5 .\"
6 .\" This document may not be republished without written permission from
7 .\" Keith Bostic. 
8 .\"
9 .\" See the LICENSE file for redistribution information.
10 .\"
11 .\"     @(#)vi.1        8.51 (Berkeley) 10/10/96
12 .\"     $FreeBSD: src/contrib/nvi/docs/USD.doc/vi.man/vi.1,v 1.4.6.1 2001/01/03 18:33:27 ben Exp $
13 .\"
14 .TH VI 1 "October 10, 1996"
15 .UC
16 .SH NAME
17 ex, vi, view \- text editors
18 .SH SYNOPSIS
19 .B ex
20 [\c
21 .B -eFGRrSsv\c
22 ] [\c
23 .BI -c " cmd"\c
24 ] [\c
25 .BI -t " tag"\c
26 ] [\c
27 .BI -w " size"\c
28 ] [file ...]
29 .br
30 .B vi
31 [\c
32 .B -eFGlRrSv\c
33 ] [\c
34 .BI -c " cmd"\c
35 ] [\c
36 .BI -t " tag"\c
37 ] [\c
38 .BI -w " size"\c
39 ] [file ...]
40 .br
41 .B view
42 [\c
43 .B -eFGRrSv\c
44 ] [\c
45 .BI -c " cmd"\c
46 ] [\c
47 .BI -t " tag"\c
48 ] [\c
49 .BI -w " size"\c
50 ] [file ...]
51 .SH LICENSE
52 The vi program is freely redistributable.  You are welcome to copy,
53 modify and share it with others under the conditions listed in the
54 LICENSE file.  If any company (not individual!) finds vi sufficiently
55 useful that you would have purchased it, or if any company wishes to
56 redistribute it, contributions to the authors would be appreciated.
57 .SH DESCRIPTION
58 .I \&Vi
59 is a screen oriented text editor.
60 .I \&Ex
61 is a line-oriented text editor.
62 .I \&Ex
63 and
64 .I \&vi
65 are different interfaces to the same program,
66 and it is possible to switch back and forth during an edit session.
67 .I View
68 is the equivalent of using the
69 .B \-R
70 (read-only) option of
71 .IR \&vi .
72 .PP
73 This manual page is the one provided with the
74 .I nex/nvi
75 versions of the
76 .I ex/vi
77 text editors.
78 .I Nex/nvi
79 are intended as bug-for-bug compatible replacements for the original
80 Fourth Berkeley Software Distribution (4BSD)
81 .I \&ex
82 and
83 .I \&vi
84 programs.
85 For the rest of this manual page,
86 .I nex/nvi
87 is used only when it's necessary to distinguish it from the historic
88 implementations of
89 .IR ex/vi .
90 .PP
91 This manual page is intended for users already familiar with
92 .IR ex/vi .
93 Anyone else should almost certainly read a good tutorial on the
94 editor before this manual page.
95 If you're in an unfamiliar environment, and you absolutely have to
96 get work done immediately, read the section after the options
97 description, entitled ``Fast Startup''.
98 It's probably enough to get you going.
99 .PP
100 The following options are available:
101 .TP
102 .B \-c
103 Execute
104 .B cmd
105 immediately after starting the edit session.
106 Particularly useful for initial positioning in the file, however
107 .B cmd
108 is not limited to positioning commands.
109 This is the POSIX 1003.2 interface for the historic ``+cmd'' syntax.
110 .I Nex/nvi
111 supports both the old and new syntax.
112 .TP
113 .B \-e
114 Start editing in ex mode, as if the command name were
115 .IR \&ex .
116 .TP
117 .B \-F
118 Don't copy the entire file when first starting to edit.
119 (The default is to make a copy in case someone else modifies
120 the file during your edit session.)
121 .TP
122 .B \-l
123 Start editing with the lisp and showmatch options set.
124 .TP
125 .B \-G
126 Start editing in gtags mode, as if the gtagsmode option was set.
127 .TP
128 .B \-R
129 Start editing in read-only mode, as if the command name was
130 .IR view ,
131 or the
132 .B readonly
133 option was set.
134 .TP
135 .B \-r
136 Recover the specified files, or, if no files are specified,
137 list the files that could be recovered.
138 If no recoverable files by the specified name exist,
139 the file is edited as if the
140 .B \-r
141 option had not been specified.
142 .TP
143 .B \-S
144 Run with the
145 .B secure
146 edit option set, disallowing all access to external programs.
147 .TP
148 .B \-s
149 Enter batch mode; applicable only to
150 .I \&ex
151 edit sessions.
152 Batch mode is useful when running
153 .I \&ex
154 scripts.
155 Prompts, informative messages and other user oriented message
156 are turned off,
157 and no startup files or environment variables are read.
158 This is the POSIX 1003.2 interface for the historic ``\-'' argument.
159 .I \&Nex/nvi
160 supports both the old and new syntax.
161 .TP
162 .B \-t
163 Start editing at the specified tag.
164 (See
165 .IR ctags (1)).
166 .TP
167 .B \-w
168 Set the initial window size to the specified number of lines.
169 .TP
170 .B \-v
171 Start editing in vi mode, as if the command name was
172 .I \&vi
173 or
174 .IR view .
175 .PP
176 Command input for
177 .I ex/vi
178 is read from the standard input.
179 In the
180 .I \&vi
181 interface, it is an error if standard input is not a terminal.
182 In the
183 .I \&ex
184 interface, if standard input is not a terminal,
185 .I \&ex
186 will read commands from it regardless, however, the session will be a
187 batch mode session, exactly as if the
188 .B \-s
189 option had been specified.
190 .PP
191 .I Ex/vi
192 exits 0 on success, and greater than 0 if an error occurs.
193 .SH FAST STARTUP
194 This section will tell you the minimum amount that you need to
195 do simple editing tasks using
196 .IR \&vi .
197 If you've never used any screen editor before, you're likely to have
198 problems even with this simple introduction.
199 In that case you should find someone that already knows
200 .I \&vi
201 and have them walk you through this section.
202 .PP
203 .I \&Vi
204 is a screen editor.
205 This means that it takes up almost the entire screen, displaying part
206 of the file on each screen line, except for the last line of the screen.
207 The last line of the screen is used for you to give commands to
208 .IR \&vi ,
209 and for
210 .I \&vi
211 to give information to you.
212 .PP
213 The other fact that you need to understand is that
214 .I \&vi
215 is a modeful editor, i.e. you are either entering text or you
216 are executing commands, and you have to be in the right mode
217 to do one or the other.
218 You will be in command mode when you first start editing a file.
219 There are commands that switch you into input mode.
220 There is only one key that takes you out of input mode,
221 and that is the <escape> key.
222 (Key names are written using less-than and greater-than signs, e.g.
223 <escape> means the ``escape'' key, usually labeled ``esc'' on your
224 terminal's keyboard.)
225 If you're ever confused as to which mode you're in,
226 keep entering the <escape> key until
227 .I \&vi
228 beeps at you.
229 (Generally,
230 .I \&vi
231 will beep at you if you try and do something that's not allowed.
232 It will also display error messages.)
233 .PP
234 To start editing a file, enter the command ``vi file_name<carriage-return>''.
235 The command you should enter as soon as you start editing is
236 ``:set verbose showmode<carriage-return>''.
237 This will make the editor give you verbose error messages and display
238 the current mode at the bottom of the screen.
239 .PP
240 The commands to move around the file are:
241 .TP
242 .B h
243 Move the cursor left one character.
244 .TP
245 .B j
246 Move the cursor down one line.
247 .TP
248 .B k
249 Move the cursor up one line.
250 .TP
251 .B l
252 Move the cursor right one character.
253 .TP
254 .B <cursor-arrows>
255 The cursor arrow keys should work, too.
256 .TP
257 .B /text<carriage-return>
258 Search for the string ``text'' in the file,
259 and move the cursor to its first character.
260 .PP
261 The commands to enter new text are:
262 .TP
263 .B a
264 Append new text,
265 .I after
266 the cursor.
267 .TP
268 .B i
269 Insert new text,
270 .I before
271 the cursor.
272 .TP
273 .B o
274 Open a new line below the line the cursor is on, and start
275 entering text.
276 .TP
277 .B O
278 Open a new line above the line the cursor is on, and start
279 entering text.
280 .TP
281 .B <escape>
282 Once you've entered input mode using the one of the
283 .BR \&a ,
284 .BR \&i ,
285 .BR \&O
286 or 
287 .B \&o
288 commands, use
289 .B <escape>
290 to quit entering text and return to command mode.
291 .PP
292 The commands to copy text are:
293 .TP
294 .B yy
295 Copy the line the cursor is on.
296 .TP
297 .B p
298 Append the copied line after the line the cursor is on.
299 .PP
300 The commands to delete text are:
301 .TP
302 .B dd
303 Delete the line the cursor is on.
304 .TP
305 .B x
306 Delete the character the cursor is on.
307 .PP
308 The commands to write the file are:
309 .TP
310 .B :w<carriage-return>
311 Write the file back to the file with the name that you originally used
312 as an argument on the
313 .I \&vi
314 command line.
315 .TP
316 .B ":w file_name<carriage-return>"
317 Write the file back to the file with the name ``file_name''.
318 .PP
319 The commands to quit editing and exit the editor are:
320 .TP
321 .B :q<carriage-return>
322 Quit editing and leave vi (if you've modified the file, but not
323 saved your changes,
324 .I \&vi
325 will refuse to quit).
326 .TP
327 .B :q!<carriage-return>
328 Quit, discarding any modifications that you may have made.
329 .PP
330 One final caution.
331 Unusual characters can take up more than one column on the screen,
332 and long lines can take up more than a single screen line.
333 The above commands work on ``physical'' characters and lines,
334 i.e. they affect the entire line no matter how many screen lines it
335 takes up and the entire character no matter how many screen columns
336 it takes up.
337 .SH VI COMMANDS
338 The following section describes the commands available in the command
339 mode of the
340 .I \&vi
341 editor.
342 In each entry below, the tag line is a usage synopsis for the command
343 character.
344 .PP
345 .TP
346 .B "[count] <control-A>"
347 Search forward
348 .I count
349 times for the current word.
350 .TP
351 .B "[count] <control-B>"
352 Page backwards
353 .I count
354 screens.
355 .TP
356 .B "[count] <control-D>"
357 Scroll forward
358 .I count
359 lines.
360 .TP
361 .B "[count] <control-E>"
362 Scroll forward
363 .I count
364 lines, leaving the current line and column as is, if possible.
365 .TP
366 .B "[count] <control-F>"
367 Page forward
368 .I count
369 screens.
370 .TP
371 .B "<control-G>"
372 Display the file information.
373 .TP
374 .B "<control-H>"
375 .TP
376 .B "[count] h"
377 Move the cursor back
378 .I count
379 characters in the current line.
380 .TP
381 .B "[count] <control-J>"
382 .TP
383 .B "[count] <control-N>"
384 .TP
385 .B "[count] j"
386 Move the cursor down
387 .I count
388 lines without changing the current column.
389 .TP
390 .B "<control-L>"
391 .TP
392 .B "<control-R>"
393 Repaint the screen.
394 .TP
395 .B "[count] <control-M>"
396 .TP
397 .B "[count] +"
398 Move the cursor down
399 .I count
400 lines to the first nonblank character of that line.
401 .TP
402 .B "[count] <control-P>"
403 .TP
404 .B "[count] k"
405 Move the cursor up
406 .I count
407 lines, without changing the current column.
408 .TP
409 .B "<control-T>"
410 Return to the most recent tag context.
411 .TP
412 .B "<control-U>"
413 Scroll backwards
414 .I count
415 lines.
416 .TP
417 .B "<control-W>"
418 Switch to the next lower screen in the window, or, to the first
419 screen if there are no lower screens in the window.
420 .TP
421 .B "<control-Y>"
422 Scroll backwards
423 .I count
424 lines, leaving the current line and column as is, if possible.
425 .TP
426 .B "<control-Z>"
427 Suspend the current editor session.
428 .TP
429 .B "<escape>"
430 Execute
431 .I \&ex
432 commands or cancel partial commands.
433 .TP
434 .B "<control-]>"
435 Push a tag reference onto the tag stack.
436 In gtagsmode, if at the first column of line,
437 locate function references otherwise function definitions.
438 .TP
439 .B "<control-^>"
440 Switch to the most recently edited file.
441 .TP
442 .B "[count] <space>"
443 .TP
444 .B "[count] l"
445 Move the cursor forward
446 .I count
447 characters without changing the current line.
448 .TP
449 .B "[count] ! motion shell-argument(s)"
450 Replace text with results from a shell command.
451 .TP
452 .B "[count] # #|+|-"
453 Increment or decrement the cursor number.
454 .TP
455 .B "[count] $"
456 Move the cursor to the end of a line.
457 .TP
458 .B "%"
459 Move to the matching character.
460 .TP
461 .B "&"
462 Repeat the previous substitution command on the current line.
463 .TP
464 .B "'<character>"
465 .TP
466 .B "`<character>"
467 Return to a context marked by the character
468 .IR <character> .
469 .TP
470 .B "[count] ("
471 Back up
472 .I count
473 sentences.
474 .TP
475 .B "[count] )"
476 Move forward
477 .I count
478 sentences.
479 .TP
480 .B "[count] ,"
481 Reverse find character
482 .I count
483 times.
484 .TP
485 .B "[count] -"
486 Move to first nonblank of the previous line,
487 .I count
488 times.
489 .TP
490 .B "[count] ."
491 Repeat the last
492 .I \&vi
493 command that modified text.
494 .TP
495 .B "/RE<carriage-return>"
496 .TP
497 .B "/RE/ [offset]<carriage-return>"
498 .TP
499 .B "?RE<carriage-return>"
500 .TP
501 .B "?RE? [offset]<carriage-return>"
502 .TP
503 .B "N"
504 .TP
505 .B "n"
506 Search forward or backward for a regular expression.
507 .TP
508 .B "0"
509 Move to the first character in the current line.
510 .TP
511 .B ":"
512 Execute an ex command.
513 .TP
514 .B "[count] ;"
515 Repeat the last character find
516 .I count
517 times.
518 .TP
519 .B "[count] < motion"
520 .TP
521 .B "[count] > motion"
522 Shift lines left or right.
523 .TP
524 .B "@ buffer"
525 Execute a named buffer.
526 .TP
527 .B "[count] A"
528 Enter input mode, appending the text after the end of the line.
529 .TP
530 .B "[count] B"
531 Move backwards
532 .I count
533 bigwords.
534 .TP
535 .B "[buffer] [count] C"
536 Change text from the current position to the end-of-line.
537 .TP
538 .B "[buffer] D"
539 Delete text from the current position to the end-of-line.
540 .TP
541 .B "[count] E"
542 Move forward
543 .I count
544 end-of-bigwords.
545 .TP
546 .B "[count] F <character>"
547 Search
548 .I count
549 times backward through the current line for
550 .IR <character> .
551 .TP
552 .B "[count] G"
553 Move to line
554 .IR count ,
555 or the last line of the file if
556 .I count
557 not specified.
558 .TP
559 .B "[count] H"
560 Move to the screen line
561 .I "count - 1"
562 lines below the top of the screen.
563 .TP
564 .B "[count] I"
565 Enter input mode, inserting the text at the beginning of the line.
566 .TP
567 .B "[count] J"
568 Join lines.
569 .TP
570 .B "[count] L"
571 Move to the screen line
572 .I "count - 1"
573 lines above the bottom of the screen.
574 .TP
575 .B " M"
576 Move to the screen line in the middle of the screen.
577 .TP
578 .B "[count] O"
579 Enter input mode, appending text in a new line above the current line.
580 .TP
581 .B "[buffer] P"
582 Insert text from a buffer.
583 .TP
584 .B "Q"
585 Exit
586 .I \&vi
587 (or visual) mode and switch to
588 .I \&ex
589 mode.
590 .TP
591 .B "[count] R"
592 Enter input mode, replacing the characters in the current line.
593 .TP
594 .B "[buffer] [count] S"
595 Substitute
596 .I count
597 lines.
598 .TP
599 .B "[count] T <character>"
600 Search backwards,
601 .I count
602 times,
603 through the current line for the character
604 .I after
605 the specified
606 .IR <character> .
607 .TP
608 .B "U"
609 Restore the current line to its state before the cursor last
610 moved to it.
611 .TP
612 .B "[count] W"
613 Move forward
614 .I count
615 bigwords.
616 .TP
617 .B "[buffer] [count] X"
618 Delete
619 .I count
620 characters before the cursor.
621 .TP
622 .B "[buffer] [count] Y"
623 Copy (or ``yank'')
624 .I count
625 lines into the specified buffer.
626 .TP
627 .B "ZZ"
628 Write the file and exit
629 .IR \&vi .
630 .TP
631 .B "[count] [["
632 Back up
633 .I count
634 section boundaries.
635 .TP
636 .B "[count] ]]"
637 Move forward
638 .I count
639 section boundaries.
640 .TP
641 .B "\&^"
642 Move to first nonblank character on the current line.
643 .TP
644 .B "[count] _"
645 Move down
646 .I "count - 1"
647 lines, to the first nonblank character.
648 .TP
649 .B "[count] a"
650 Enter input mode, appending the text after the cursor.
651 .TP
652 .B "[count] b"
653 Move backwards
654 .I count
655 words.
656 .TP
657 .B "[buffer] [count] c motion"
658 Change a region of text.
659 .TP
660 .B "[buffer] [count] d motion"
661 Delete a region of text.
662 .TP
663 .B "[count] e"
664 Move forward
665 .I count
666 end-of-words.
667 .TP
668 .B "[count] f<character>"
669 Search forward,
670 .I count
671 times, through the rest of the current line for
672 .IR <character> .
673 .TP
674 .B "[count] i"
675 Enter input mode, inserting the text before the cursor.
676 .TP
677 .B "m <character>"
678 Save the current context (line and column) as
679 .IR <character> .
680 .TP
681 .B "[count] o"
682 Enter input mode, appending text in a new line under the current line.
683 .TP
684 .B "[buffer] p"
685 Append text from a buffer.
686 .TP
687 .B "[count] r <character>"
688 Replace
689 .I count
690 characters.
691 .TP
692 .B "[buffer] [count] s"
693 Substitute
694 .I count
695 characters in the current line starting with the current character.
696 .TP
697 .B "[count] t <character>"
698 Search forward,
699 .I count
700 times, through the current line for the character immediately
701 .I before
702 .IR <character> .
703 .TP
704 .B "u"
705 Undo the last change made to the file.
706 .TP
707 .B "[count] w"
708 Move forward
709 .I count
710 words.
711 .TP
712 .B "[buffer] [count] x"
713 Delete
714 .I count
715 characters.
716 .TP
717 .B "[buffer] [count] y motion"
718 Copy (or ``yank'')
719 a text region specified by the
720 .I count
721 and motion into a buffer.
722 .TP
723 .B "[count1] z [count2] -|.|+|^|<carriage-return>"
724 Redraw, optionally repositioning and resizing the screen.
725 .TP
726 .B "[count] {"
727 Move backward
728 .I count
729 paragraphs.
730 .TP
731 .B "[count] |"
732 Move to a specific
733 .I column
734 position on the current line.
735 .TP
736 .B "[count] }"
737 Move forward
738 .I count
739 paragraphs.
740 .TP
741 .B "[count] ~"
742 Reverse the case of the next
743 .I count
744 character(s).
745 .TP
746 .B "[count] ~ motion"
747 Reverse the case of the characters in a text region specified by the
748 .I count
749 and
750 .IR motion .
751 .TP
752 .B "<interrupt>"
753 Interrupt the current operation.
754 .SH VI TEXT INPUT COMMANDS
755 The following section describes the commands available in the text
756 input mode of the
757 .I \&vi
758 editor.
759 .PP
760 .TP
761 .B "<nul>"
762 Replay the previous input.
763 .TP
764 .B "<control-D>"
765 Erase to the previous
766 .B shiftwidth
767 column boundary.
768 .TP
769 .B "^<control-D>"
770 Erase all of the autoindent characters, and reset the autoindent level.
771 .TP
772 .B "0<control-D>"
773 Erase all of the autoindent characters.
774 .TP
775 .B "<control-T>"
776 Insert sufficient
777 .I <tab>
778 and
779 .I <space>
780 characters to move forward to the next
781 .B shiftwidth
782 column boundary.
783 .TP
784 .B "<erase>
785 .TP
786 .B "<control-H>"
787 Erase the last character.
788 .TP
789 .B "<literal next>"
790 Quote the next character.
791 .TP
792 .B "<escape>
793 Resolve all text input into the file, and return to command mode.
794 .TP
795 .B "<line erase>"
796 Erase the current line.
797 .TP
798 .B "<control-W>"
799 .TP
800 .B "<word erase>"
801 Erase the last word.
802 The definition of word is dependent on the
803 .B altwerase
804 and
805 .B ttywerase
806 options.
807 .TP
808 .B "<control-X>[0-9A-Fa-f]+"
809 Insert a character with the specified hexadecimal value into the text.
810 .TP
811 .B "<interrupt>"
812 Interrupt text input mode, returning to command mode.
813 .SH EX COMMANDS
814 The following section describes the commands available in the
815 .I \&ex
816 editor.
817 In each entry below, the tag line is a usage synopsis for the command.
818 .PP
819 .TP
820 .B "<end-of-file>"
821 Scroll the screen.
822 .TP
823 .B "! argument(s)"
824 .TP
825 .B "[range]! argument(s)"
826 Execute a shell command, or filter lines through a shell command.
827 .TP
828 .B \&"
829 A comment.
830 .TP
831 .B "[range] nu[mber] [count] [flags]"
832 .TP
833 .B "[range] # [count] [flags]"
834 Display the selected lines, each preceded with its line number.
835 .TP
836 .B "@ buffer"
837 .TP
838 .B "* buffer"
839 Execute a buffer.
840 .TP
841 .B "[line] a[ppend][!]"
842 The input text is appended after the specified line.
843 .TP
844 .B "[range] c[hange][!] [count]"
845 The input text replaces the specified range.
846 .TP
847 .B "cs[cope] add | find | help | kill | reset"
848 Execute a Cscope command.
849 .TP
850 .B "[range] d[elete] [buffer] [count] [flags]"
851 Delete the lines from the file.
852 .TP
853 .B "di[splay] b[uffers] | c[onnections] | s[creens] | t[ags]"
854 Display buffers, Cscope connections, screens or tags.
855 .TP
856 .B "[Ee][dit][!] [+cmd] [file]"
857 .TP
858 .B "[Ee]x[!] [+cmd] [file]"
859 Edit a different file.
860 .TP
861 .B "exu[sage] [command]"
862 Display usage for an
863 .I \&ex
864 command.
865 .TP
866 .B "f[ile] [file]"
867 Display and optionally change the file name.
868 .TP
869 .B "[Ff]g [name]"
870 .I \&Vi
871 mode only.
872 Foreground the specified screen.
873 .TP
874 .B "[range] g[lobal] /pattern/ [commands]"
875 .TP
876 .B "[range] v /pattern/ [commands]"
877 Apply commands to lines matching (or not matching) a pattern.
878 .TP
879 .B "he[lp]"
880 Display a help message.
881 .TP
882 .B "[line] i[nsert][!]"
883 The input text is inserted before the specified line.
884 .TP
885 .B "[range] j[oin][!] [count] [flags]"
886 Join lines of text together.
887 .TP
888 .B "[range] l[ist] [count] [flags]"
889 Display the lines unambiguously.
890 .TP
891 .B "map[!] [lhs rhs]"
892 Define or display maps (for
893 .I \&vi
894 only).
895 .TP
896 .B "[line] ma[rk] <character>"
897 .TP
898 .B "[line] k <character>"
899 Mark the line with the mark
900 .IR <character> .
901 .TP
902 .B "[range] m[ove] line"
903 Move the specified lines after the target line.
904 .TP
905 .B "mk[exrc][!] file"
906 Write the abbreviations, editor options and maps to the specified
907 file.
908 .TP
909 .B "[Nn][ext][!] [file ...]"
910 Edit the next file from the argument list.
911 .TP
912 .B "[line] o[pen] /pattern/ [flags]"
913 Enter open mode.
914 .TP
915 .B "pre[serve]"
916 Save the file in a form that can later be recovered using the
917 .I \&ex
918 .B \-r
919 option.
920 .TP
921 .B "[Pp]rev[ious][!]"
922 Edit the previous file from the argument list.
923 .TP
924 .B "[range] p[rint] [count] [flags]"
925 Display the specified lines.
926 .TP
927 .B "[line] pu[t] [buffer]"
928 Append buffer contents to the current line.
929 .TP
930 .B "q[uit][!]"
931 End the editing session.
932 .TP
933 .B "[line] r[ead][!] [file]"
934 Read a file.
935 .TP
936 .B "rec[over] file"
937 Recover
938 .I file
939 if it was previously saved.
940 .TP
941 .B "res[ize] [+|-]size"
942 .I \&Vi
943 mode only.
944 Grow or shrink the current screen.
945 .TP
946 .B "rew[ind][!]"
947 Rewind the argument list.
948 .TP
949 .B "rta[g][!] tagstring"
950 Edit the file referring the specified tag. (Only in gtagsmode)
951 .TP
952 .B "se[t] [option[=[value]] ...] [nooption ...] [option? ...] [all]"
953 Display or set editor options.
954 .TP
955 .B "sh[ell]"
956 Run a shell program.
957 .TP
958 .B "so[urce] file"
959 Read and execute
960 .I \&ex
961 commands from a file.
962 .TP
963 .B "[range] s[ubstitute] [/pattern/replace/] [options] [count] [flags]"
964 .TP
965 .B "[range] & [options] [count] [flags]"
966 .TP
967 .B "[range] ~ [options] [count] [flags]"
968 Make substitutions.
969 .TP
970 .B "su[spend][!]"
971 .TP
972 .B "st[op][!]"
973 .TP
974 .B <suspend>
975 Suspend the edit session.
976 .TP
977 .B "[Tt]a[g][!] tagstring"
978 Edit the file containing the specified tag.
979 .TP
980 .B "tagn[ext][!]"
981 Edit the file containing the next context for the current tag.
982 .TP
983 .B "tagp[op][!] [file | number]"
984 Pop to the specified tag in the tags stack.
985 .TP
986 .B "tagp[rev][!]"
987 Edit the file containing the previous context for the current tag.
988 .TP
989 .B "unm[ap][!] lhs"
990 Unmap a mapped string.
991 .TP
992 .B "ve[rsion]"
993 Display the version of the
994 .I \&ex/vi
995 editor.
996 .TP
997 .B "[line] vi[sual] [type] [count] [flags]"
998 .I \&Ex
999 mode only.
1000 Enter
1001 .IR \&vi .
1002 .TP
1003 .B "[Vi]i[sual][!] [+cmd] [file]"
1004 .I \&Vi
1005 mode only.
1006 Edit a new file.
1007 .TP
1008 .B "viu[sage] [command]"
1009 Display usage for a
1010 .I \&vi
1011 command.
1012 .TP
1013 .B "[range] w[rite][!] [>>] [file]"
1014 .TP
1015 .B "[range] w[rite] [!] [file]"
1016 .TP
1017 .B "[range] wn[!] [>>] [file]"
1018 .TP
1019 .B "[range] wq[!] [>>] [file]"
1020 Write the file.
1021 .TP
1022 .B "[range] x[it][!] [file]"
1023 Write the file if it has been modified.
1024 .TP
1025 .B "[range] ya[nk] [buffer] [count]"
1026 Copy the specified lines to a buffer.
1027 .TP
1028 .B "[line] z [type] [count] [flags]"
1029 Adjust the window.
1030 .SH SET OPTIONS
1031 There are a large number of options that may be set (or unset) to
1032 change the editor's behavior.
1033 This section describes the options, their abbreviations and their
1034 default values.
1035 .PP
1036 In each entry below, the first part of the tag line is the full name
1037 of the option, followed by any equivalent abbreviations.
1038 The part in square brackets is the default value of the option.
1039 Most of the options are boolean, i.e. they are either on or off,
1040 and do not have an associated value.
1041 .PP
1042 Options apply to both
1043 .I \&ex
1044 and
1045 .I \&vi
1046 modes, unless otherwise specified.
1047 .PP
1048 .TP
1049 .B "altwerase [off]"
1050 .I \&Vi
1051 only.
1052 Select an alternate word erase algorithm.
1053 .TP
1054 .B "autoindent, ai [off]"
1055 Automatically indent new lines.
1056 .TP
1057 .B "autoprint, ap [off]"
1058 .I \&Ex
1059 only.
1060 Display the current line automatically.
1061 .TP
1062 .B "autowrite, aw [off]"
1063 Write modified files automatically when changing files.
1064 .\" I cannot get a double quote to print between the square brackets
1065 .\" to save my life.  The ONLY way I've been able to get this to work
1066 .\" is with the .tr command.
1067 .tr Q"
1068 .ds ms backup [QQ]
1069 .TP
1070 .B "\*(ms"
1071 .tr QQ
1072 Backup files before they are overwritten.
1073 .TP
1074 .B "beautify, bf [off]"
1075 Discard control characters.
1076 .TP
1077 .B "cdpath [environment variable CDPATH, or current directory]"
1078 The directory paths used as path prefixes for the
1079 .B cd
1080 command.
1081 .TP
1082 .B "cedit [no default]"
1083 Set the character to edit the colon command-line history.
1084 .TP
1085 .B "columns, co [80]"
1086 Set the number of columns in the screen.
1087 .TP
1088 .B "comment [off]"
1089 .I \&Vi
1090 only.
1091 Skip leading comments in shell, C and C++ language files.
1092 .TP
1093 .B "directory, dir [environment variable TMPDIR, or /tmp]"
1094 The directory where temporary files are created.
1095 .TP
1096 .B "edcompatible, ed [off]"
1097 Remember the values of the ``c'' and ``g'' suffices to the
1098 .B substitute
1099 commands, instead of initializing them as unset for each new
1100 command.
1101 .TP
1102 .B "errorbells, eb [off]"
1103 .I \&Ex
1104 only.
1105 Announce error messages with a bell.
1106 .TP
1107 .B "exrc, ex [off]"
1108 Read the startup files in the local directory.
1109 .TP
1110 .B "extended [off]"
1111 Regular expressions are extended (i.e.
1112 .IR egrep (1)\-\c
1113 style) expressions.
1114 .TP
1115 .B "filec [no default]"
1116 Set the character to perform file path completion on the colon
1117 command line.
1118 .TP
1119 .B "flash [on]"
1120 Flash the screen instead of beeping the keyboard on error.
1121 .TP
1122 .B "gtagsmode, gt [off]"
1123 Use GTAGS and GRTAGS instead of tags.
1124 .TP
1125 .B "hardtabs, ht [8]"
1126 Set the spacing between hardware tab settings.
1127 .TP
1128 .B "iclower [off]"
1129 Makes all Regular Expressions case-insensitive,
1130 as long as an upper-case letter does not appear in the search string.
1131 .TP
1132 .B "ignorecase, ic [off]"
1133 Ignore case differences in regular expressions.
1134 .TP
1135 .B "keytime [6]"
1136 The 10th's of a second
1137 .I ex/vi
1138 waits for a subsequent key to complete a key mapping.
1139 .TP
1140 .B "leftright [off]"
1141 .I \&Vi
1142 only.
1143 Do left-right scrolling.
1144 .TP
1145 .B "lines, li [24]"
1146 .I \&Vi
1147 only.
1148 Set the number of lines in the screen.
1149 .TP
1150 .B "lisp [off]"
1151 .I \&Vi
1152 only.
1153 Modify various search commands and options to work with Lisp.
1154 .I "This option is not yet implemented."
1155 .TP
1156 .B "list [off]"
1157 Display lines in an unambiguous fashion.
1158 .TP
1159 .B "lock [on]"
1160 Attempt to get an exclusive lock on any file being edited,
1161 read or written.
1162 .TP
1163 .B "magic [on]"
1164 Treat certain characters specially in regular expressions.
1165 .TP
1166 .B "matchtime [7]"
1167 .I \&Vi
1168 only.
1169 The 10th's of a second
1170 .I ex/vi
1171 pauses on the matching character when the
1172 .B showmatch
1173 option is set.
1174 .TP
1175 .B "mesg [on]"
1176 Permit messages from other users.
1177 .TP
1178 .B "modelines, modeline [off]"
1179 Read the first and last few lines of each file for
1180 .I ex
1181 commands.
1182 .I "This option will never be implemented."
1183 .\" I cannot get a double quote to print between the square brackets
1184 .\" to save my life.  The ONLY way I've been able to get this to work
1185 .\" is with the .tr command.
1186 .tr Q"
1187 .ds ms noprint [QQ]
1188 .TP
1189 .B "\*(ms"
1190 .tr QQ
1191 Characters that are never handled as printable characters.
1192 .TP
1193 .B "number, nu [off]"
1194 Precede each line displayed with its current line number.
1195 .TP
1196 .B "octal [off]"
1197 Display unknown characters as octal numbers, instead of the default
1198 hexadecimal.
1199 .TP
1200 .B "open [on]"
1201 .I \&Ex
1202 only.
1203 If this option is not set, the
1204 .B open
1205 and
1206 .B visual
1207 commands are disallowed.
1208 .TP
1209 .B "optimize, opt [on]"
1210 .I \&Vi
1211 only.
1212 Optimize text throughput to dumb terminals.
1213 .I "This option is not yet implemented."
1214 .TP
1215 .B "paragraphs, para [IPLPPPQPP LIpplpipbp]"
1216 .I \&Vi
1217 only.
1218 Define additional paragraph boundaries for the
1219 .B \&{
1220 and
1221 .B \&}
1222 commands.
1223 .TP
1224 .B "path []"
1225 Define additional directories to search for files being edited.
1226 .\" I cannot get a double quote to print between the square brackets
1227 .\" to save my life.  The ONLY way I've been able to get this to work
1228 .\" is with the .tr command.
1229 .tr Q"
1230 .ds ms print [QQ]
1231 .TP
1232 .B "\*(ms"
1233 .tr QQ
1234 Characters that are always handled as printable characters.
1235 .TP
1236 .B "prompt [on]"
1237 .I \&Ex
1238 only.
1239 Display a command prompt.
1240 .TP
1241 .B "readonly, ro [off]"
1242 Mark the file and session as read-only.
1243 .TP
1244 .B "recdir [/var/tmp/vi.recover]"
1245 The directory where recovery files are stored.
1246 .TP
1247 .B "redraw, re [off]"
1248 .I \&Vi
1249 only.
1250 Simulate an intelligent terminal on a dumb one.
1251 .I "This option is not yet implemented."
1252 .TP
1253 .B "remap [on]"
1254 Remap keys until resolved.
1255 .TP
1256 .B "report [5]"
1257 Set the number of lines about which the editor reports changes
1258 or yanks.
1259 .TP
1260 .B "ruler [off]"
1261 .I \&Vi
1262 only.
1263 Display a row/column ruler on the colon command line.
1264 .TP
1265 .B "scroll, scr [window / 2]"
1266 Set the number of lines scrolled.
1267 .TP
1268 .B "searchincr [off]"
1269 Makes the
1270 .B \&/
1271 and
1272 .B \&?
1273 commands incremental.
1274 .TP
1275 .B "sections, sect [NHSHH HUnhsh]"
1276 .I \&Vi
1277 only.
1278 Define additional section boundaries for the
1279 .B \&[[
1280 and
1281 .B \&]]
1282 commands.
1283 .TP
1284 .B "secure [off]"
1285 Turns off all access to external programs.
1286 .TP
1287 .B "shell, sh [environment variable SHELL, or /bin/sh]"
1288 Select the shell used by the editor.
1289 .\" I cannot get a double quote to print between the square brackets
1290 .\" to save my life.  The ONLY way I've been able to get this to work
1291 .\" is with the .tr command.
1292 .tr Q"
1293 .ds ms shellmeta [~{[*?$`'Q\e]
1294 .TP
1295 .B "\*(ms"
1296 .tr QQ
1297 Set the meta characters checked to determine if file name expansion
1298 is necessary.
1299 .TP
1300 .B "shiftwidth, sw [8]"
1301 Set the autoindent and shift command indentation width.
1302 .TP
1303 .B "showmatch, sm [off]"
1304 .I \&Vi
1305 only.
1306 Note matching ``{'' and ``('' for ``}'' and ``)'' characters.
1307 .TP
1308 .B "showmode, smd [off]"
1309 .I \&Vi
1310 only.
1311 Display the current editor mode and a ``modified'' flag.
1312 .TP
1313 .B "sidescroll [16]"
1314 .I \&Vi
1315 only.
1316 Set the amount a left-right scroll will shift.
1317 .TP
1318 .B "slowopen, slow [off]"
1319 Delay display updating during text input.
1320 .I "This option is not yet implemented."
1321 .TP
1322 .B "sourceany [off]"
1323 Read startup files not owned by the current user.
1324 .I "This option will never be implemented."
1325 .TP
1326 .B "tabstop, ts [8]"
1327 This option sets tab widths for the editor display.
1328 .TP
1329 .B "taglength, tl [0]"
1330 Set the number of significant characters in tag names.
1331 .TP
1332 .B "tags, tag [tags /var/db/libc.tags /sys/kern/tags]"
1333 Set the list of tags files.
1334 .TP
1335 .B "term, ttytype, tty [environment variable TERM]"
1336 Set the terminal type.
1337 .TP
1338 .B "terse [off]"
1339 This option has historically made editor messages less verbose.
1340 It has no effect in this implementation.
1341 .TP
1342 .B "tildeop [off]"
1343 Modify the
1344 .B \&~
1345 command to take an associated motion.
1346 .TP
1347 .B "timeout, to [on]"
1348 Time out on keys which may be mapped.
1349 .TP
1350 .B "ttywerase [off]"
1351 .I \&Vi
1352 only.
1353 Select an alternate erase algorithm.
1354 .TP
1355 .B "verbose [off]"
1356 .I \&Vi
1357 only.
1358 Display an error message for every error.
1359 .TP
1360 .B "w300 [no default]"
1361 .I \&Vi
1362 only.
1363 Set the window size if the baud rate is less than 1200 baud.
1364 .TP
1365 .B "w1200 [no default]"
1366 .I \&Vi
1367 only.
1368 Set the window size if the baud rate is equal to 1200 baud.
1369 .TP
1370 .B "w9600 [no default]"
1371 .I \&Vi
1372 only.
1373 Set the window size if the baud rate is greater than 1200 baud.
1374 .TP
1375 .B "warn [on]"
1376 .I \&Ex
1377 only.
1378 This option causes a warning message to the terminal if the file has
1379 been modified, since it was last written, before a
1380 .B \&!
1381 command.
1382 .TP
1383 .B "window, w, wi [environment variable LINES]"
1384 Set the window size for the screen.
1385 .TP
1386 .B "windowname [off]"
1387 Change the icon/window name to the current file name even if it can't
1388 be restored on editor exit.
1389 .TP
1390 .B "wraplen, wl [0]"
1391 .I \&Vi
1392 only.
1393 Break lines automatically, the specified number of columns from the
1394 left-hand margin.
1395 If both the
1396 .B wraplen
1397 and
1398 .B wrapmargin
1399 edit options are set, the
1400 .B wrapmargin
1401 value is used.
1402 .TP
1403 .B "wrapmargin, wm [0]"
1404 .I \&Vi
1405 only.
1406 Break lines automatically, the specified number of columns from the
1407 right-hand margin.
1408 If both the
1409 .B wraplen
1410 and
1411 .B wrapmargin
1412 edit options are set, the
1413 .B wrapmargin
1414 value is used.
1415 .TP
1416 .B "wrapscan, ws [on]"
1417 Set searches to wrap around the end or beginning of the file.
1418 .TP
1419 .B "writeany, wa [off]"
1420 Turn off file-overwriting checks.
1421 .SH ENVIRONMENT VARIABLES
1422 .TP
1423 .I COLUMNS
1424 The number of columns on the screen.
1425 This value overrides any system or terminal specific values.
1426 If the
1427 .I COLUMNS
1428 environment variable is not set when
1429 .I ex/vi
1430 runs, or the
1431 .B columns
1432 option is explicitly reset by the user,
1433 .I ex/vi
1434 enters the value into the environment.
1435 .TP
1436 .I EXINIT
1437 A list of
1438 .I \&ex
1439 startup commands, read if the variable
1440 .I NEXINIT
1441 is not set.
1442 .TP
1443 .I HOME
1444 The user's home directory, used as the initial directory path
1445 for the startup ``$\fIHOME\fP/.nexrc'' and ``$\fIHOME\fP/.exrc''
1446 files.
1447 This value is also used as the default directory for the
1448 .I \&vi
1449 .B \&cd
1450 command.
1451 .TP
1452 .I LINES
1453 The number of rows on the screen.
1454 This value overrides any system or terminal specific values.
1455 If the
1456 .I LINES
1457 environment variable is not set when
1458 .I ex/vi
1459 runs, or the
1460 .B lines
1461 option is explicitly reset by the user,
1462 .I ex/vi
1463 enters the value into the environment.
1464 .TP
1465 .I NEXINIT
1466 A list of
1467 .I \&ex
1468 startup commands.
1469 .TP
1470 .I SHELL
1471 The user's shell of choice (see also the
1472 .B shell
1473 option).
1474 .TP
1475 .I TERM
1476 The user's terminal type.
1477 The default is the type ``unknown''.
1478 If the
1479 .I TERM
1480 environment variable is not set when
1481 .I ex/vi
1482 runs, or the
1483 .B term
1484 option is explicitly reset by the user,
1485 .I ex/vi
1486 enters the value into the environment.
1487 .TP
1488 .I TMPDIR
1489 The location used to stored temporary files (see also the
1490 .B directory
1491 edit option).
1492 .SH ASYNCHRONOUS EVENTS
1493 .TP
1494 SIGALRM
1495 .I \&Vi/ex
1496 uses this signal for periodic backups of file modifications and to
1497 display ``busy'' messages when operations are likely to take a long time.
1498 .TP
1499 SIGHUP
1500 .TP
1501 SIGTERM
1502 If the current buffer has changed since it was last written in its
1503 entirety, the editor attempts to save the modified file so it can
1504 be later recovered.
1505 See the
1506 .I \&vi/ex
1507 Reference manual section entitled ``Recovery'' for more information.
1508 .TP
1509 SIGINT
1510 When an interrupt occurs,
1511 the current operation is halted,
1512 and the editor returns to the command level.
1513 If interrupted during text input,
1514 the text already input is resolved into the file as if the text
1515 input had been normally terminated.
1516 .TP
1517 SIGWINCH
1518 The screen is resized.
1519 See the
1520 .I \&vi/ex
1521 Reference manual section entitled ``Sizing the Screen'' for more information.
1522 .TP
1523 SIGCONT
1524 .TP
1525 SIGQUIT
1526 .TP
1527 SIGTSTP
1528 .I \&Vi/ex
1529 ignores these signals.
1530 .SH FILES
1531 .TP
1532 /bin/sh
1533 The default user shell.
1534 .TP
1535 /etc/vi.exrc
1536 System-wide vi startup file.
1537 .TP
1538 /tmp
1539 Temporary file directory.
1540 .TP
1541 /var/tmp/vi.recover
1542 The default recovery file directory.
1543 .TP
1544 $HOME/.nexrc
1545 1st choice for user's home directory startup file.
1546 .TP
1547 $HOME/.exrc
1548 2nd choice for user's home directory startup file.
1549 .TP
1550 \&.nexrc
1551 1st choice for local directory startup file.
1552 .TP
1553 \&.exrc
1554 2nd choice for local directory startup file.
1555 .SH SEE ALSO
1556 .IR ctags (1),
1557 .IR more (1),
1558 .IR curses (3),
1559 .IR dbopen (3)
1560 .sp
1561 The ``Vi Quick Reference'' card.
1562 .sp
1563 ``An Introduction to Display Editing with Vi'', found in the
1564 ``UNIX User's Manual Supplementary Documents''
1565 section of both the 4.3BSD and 4.4BSD manual sets.
1566 This document is the closest thing available to an introduction to the
1567 .I \&vi
1568 screen editor.
1569 .sp
1570 ``Ex Reference Manual (Version 3.7)'',
1571 found in the
1572 ``UNIX User's Manual Supplementary Documents''
1573 section of both the 4.3BSD and 4.4BSD manual sets.
1574 This document is the final reference for the
1575 .I \&ex
1576 editor, as distributed in most historic 4BSD and System V systems.
1577 .sp
1578 ``Edit: A tutorial'',
1579 found in the
1580 ``UNIX User's Manual Supplementary Documents''
1581 section of the 4.3BSD manual set.
1582 This document is an introduction to a simple version of the
1583 .I \&ex
1584 screen editor.
1585 .sp
1586 ``Ex/Vi Reference Manual'',
1587 found in the
1588 ``UNIX User's Manual Supplementary Documents''
1589 section of the 4.4BSD manual set.
1590 This document is the final reference for the
1591 .I \&nex/nvi
1592 text editors, as distributed in 4.4BSD and 4.4BSD-Lite.
1593 .PP
1594 .I Roff
1595 source for all of these documents is distributed with
1596 .I nex/nvi
1597 in the
1598 .I nvi/USD.doc
1599 directory of the
1600 .I nex/nvi
1601 source code.
1602 .sp
1603 The files ``autowrite'', ``input'', ``quoting'' and ``structures''
1604 found in the
1605 .I nvi/docs/internals
1606 directory of the
1607 .I nex/nvi
1608 source code.
1609 .SH HISTORY
1610 The
1611 .I nex/nvi
1612 replacements for the
1613 .I ex/vi
1614 editor first appeared in 4.4BSD.
1615 .SH STANDARDS
1616 .I \&Nex/nvi
1617 is close to IEEE Std1003.2 (``POSIX'').
1618 That document differs from historical
1619 .I ex/vi
1620 practice in several places; there are changes to be made on both sides.