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