| blob | 04a0c017a9934f22f5b36de28794ff7dcec9d258 |
1 .\" $NetBSD: vi.ref,v 1.2 2014/09/10 21:44:22 christos Exp $
2 .\"
3 .\" Copyright (c) 1994
4 .\" The Regents of the University of California. All rights reserved.
5 .\" Copyright (c) 1994, 1995, 1996
6 .\" Keith Bostic. All rights reserved.
7 .\"
8 .\" This document may not be republished without written permission from
9 .\" Keith Bostic.
10 .\"
11 .\" See the LICENSE file for redistribution information.
12 .\"
13 .\" @(#)vi.ref 8.88 (Berkeley) 10/19/96
14 .\"
15 .\"
16 .so ref.so
17 .tp
18 .(l C
19 .ps 12
20 .ft B
21 Vi/Ex Reference Manual
22 .ft
23 .ps
24 .sp
25 .i "Keith Bostic"
26 .sp
27 Computer Science Division
28 Department of Electrical Engineering and Computer Science
29 University of California, Berkeley
30 Berkeley, California 94720
31 .sp 1
32 \*(td
33 .)l
34 .sp 3
35 .(l C
36 .i Abstract
37 .)l
38 .(q
39 .pp
40 This document is the reference guide for the 4.4BSD
41 implementations of
42 .EV nex nvi ,
43 which are implementations of the historic Berkeley
44 .EV ex vi
45 editors.
46 .)q
47 .sp 3
48 .(l C
49 .i Licensing
50 .)l
51 .sp
52 .lp
53 Copyright (c) 1991, 1992, 1993, 1994
54 .ti +5
55 The Regents of the University of California. All Rights Reserved.
56 .lp
57 Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996
58 .ti +5
59 Keith Bostic. All Rights Reserved.
60 .sp
61 .pp
62 The vi program is freely redistributable. You are welcome to copy,
63 modify and share it with others under the conditions listed in the
64 LICENSE file. If any company (not individual!) finds vi sufficiently
65 useful that you would have purchased it, or if any company wishes to
66 redistribute it, contributions to the authors would be appreciated.
67 .bp 2
68 .(l C
69 .i Acknowledgements
70 .)l
71 .sp
72 .(q
73 .pp
74 Bruce Englar encouraged the early development of the historic
75 .EV ex vi
76 editor.
77 Peter Kessler helped bring sanity to version 2's command layout.
78 Bill Joy wrote versions 1 and 2.0 through 2.7,
79 and created the framework that users see in the present editor.
80 Mark Horton added macros and other features and made
81 .EV ex vi
82 work on a large number of terminals and Unix systems.
83 .pp
84 .CO Nvi
85 is originally derived from software contributed to the University of
86 California, Berkeley by Steve Kirkendall, the author of the
87 .CO vi
88 clone
89 .CO elvis .
90 .pp
91 IEEE Standard Portable Operating System Interface for Computer
92 Environments (POSIX) 1003.2 style Regular Expression support was
93 done by Henry Spencer.
94 .pp
95 The curses library was originally done by Ken Arnold.
96 Scrolling and reworking for
97 .CO nvi
98 was done by Elan Amir.
99 .pp
100 George Neville-Neil added the Tcl interpreter,
101 and Sven Verdoolaege added the Perl interpreter.
102 .pp
103 Rob Mayoff added Cscope support.
104 .pp
105 The Institute of Electrical and Electronics Engineers has
106 given us permission to reprint portions of their documentation.
107 Portions of this document are reprinted and reproduced from
108 IEEE Std 1003.2-1992, IEEE Standard Portable Operating
109 System Interface for Computer Environments (POSIX),
110 copyright 1992 by the Institute of Electrical and Electronics
111 Engineers, Inc.
112 .pp
113 The financial support of UUNET Communications Services is gratefully
114 acknowledged.
115 .)q
116 .if \n[.U]==0 .sy echo -n >index
117 .oh 'Vi/Ex Reference''USD:13-%'
118 .eh 'USD:13-%''Vi/Ex Reference'
119 .bp 4
120 .SH 1 Description
121 .pp
122 .CO Vi
123 is a screen oriented text editor.
124 .CO Ex
125 is a line-oriented text editor.
126 .CO Ex
127 and
128 .CO vi
129 are different interfaces to the same program,
130 and it is possible to switch back and forth during an edit session.
131 .CO View
132 is the equivalent of using the
133 .b \-R
134 (read-only) option of
135 .CO vi .
136 .pp
137 This reference manual is the one provided with the
138 .EV nex nvi
139 versions of the
140 .EV ex vi
141 text editors.
142 .EV Nex nvi
143 are intended as bug-for-bug compatible replacements for the original
144 Fourth Berkeley Software Distribution (4BSD)
145 .EV ex vi
146 programs.
147 This reference manual is accompanied by a traditional-style manual page.
148 That manual page describes the functionality found in
149 .EV ex vi
150 in far less detail than the description here.
151 In addition, it describes the system interface to
152 .EV ex vi ,
153 e.g. command line options, session recovery, signals,
154 environmental variables, and similar things.
155 .pp
156 This reference is intended for users already familiar with
157 .EV ex vi .
158 Anyone else should almost certainly read a good tutorial on the
159 editor first.
160 If you are in an unfamiliar environment,
161 and you absolutely have to get work done immediately,
162 see the section entitled
163 .QB "Fast Startup"
164 in the manual page.
165 It is probably enough to get you started.
166 .pp
167 There are a few features in
168 .EV nex nvi
169 that are not found in historic versions of
170 .EV ex vi .
171 Some of the more interesting of those features are briefly described
172 in the next section, entitled
173 .QB "Additional Features" .
174 For the rest of this document,
175 .EV nex nvi
176 is used only when it is necessary to distinguish it from the historic
177 implementations of
178 .EV ex vi .
179 .pp
180 Future versions of this software will be periodically made available
181 by anonymous ftp, and can be retrieved from
182 .LI ftp.cs.berkeley.edu ,
183 in the directory
184 .LI ucb/4bsd .
185 .SH 1 "Additional Features in Nex/Nvi"
186 .pp
187 There are a few features in
188 .EV nex nvi
189 that are not found in historic versions of
190 .EV ex vi .
191 Some of the more interesting of these are as follows:
192 .IP "8-bit clean data, large lines, files"
193 .EV Nex nvi
194 will edit any format file.
195 Line lengths are limited by available memory,
196 and file sizes are limited by available disk space.
197 The
198 .CO vi
199 text input mode command
200 .CO <control-X>
201 can insert any possible character value into the text.
202 .IP "Background and foreground screens"
203 The
204 .CO bg
205 command backgrounds the current screen, and the
206 .CO fg
207 command foregrounds backgrounded screens.
208 The
209 .CO display
210 command can be used to list the background screens.
211 .IP "Command Editing"
212 You can enter a normal editing window on the collected commands that
213 you've entered on the
214 .CO vi
215 colon command-line,
216 and then modify and/or execute the commands.
217 See the
218 .OP cedit
219 edit option for more information.
220 .IP "Displays"
221 The
222 .CO display
223 command can be used to display the current buffers, the backgrounded
224 screens, and the tags stack.
225 .IP "Extended Regular Expressions"
226 The
227 .CO extended
228 option causes Regular Expressions to be interpreted as as Extended
229 Regular Expressions, (i.e. \fIegrep\fP(1) style Regular Expressions).
230 .IP "File Name Completion"
231 It is possible to do file name completion and file name displays when
232 entering commands on the
233 .CO vi
234 colon command-line.
235 See the
236 .OP filec
237 option for more information.
238 .IP "Infinite undo"
239 Changes made during an edit session may be rolled backward and forward.
240 A
241 .CO \&.
242 command immediately after a
243 .CO u
244 command continues either forward or backward depending on whether the
245 .CO u
246 command was an undo or a redo.
247 .IP "Left-right scrolling"
248 The
249 .CO leftright
250 option causes
251 .CO nvi
252 to do left-right screen scrolling, instead of the traditional
253 .CO vi
254 line wrapping.
255 .IP "Message Catalogs"
256 It is possible to display informational and error messages in different
257 languages by providing a catalog of messages.
258 See the
259 .OP msgcat
260 option and the file
261 .LI "catalog/README"
262 for more information.
263 .IP "Incrementing numbers"
264 The
265 .CO \&#
266 command increments or decrements the number referenced by the cursor.
267 .IP "Previous file"
268 The
269 .CO previous
270 command edits the previous file from the argument list.
271 .IP "Scripting languages"
272 The
273 .CO ":pe[rl] cmd" ,
274 .CO ":perld[o] cmd"
275 and
276 .CO ":tc[l] cmd"
277 commands execute Perl and Tcl/Tk commands, respectively,
278 on lines from the edit buffer.
279 See the
280 .QB "Scripting Languages"
281 section and the specific commands for more information.
282 .\".IP "Shell screens"
283 .\"The
284 .\".CO ":sc[ript] [file ...]"
285 .\"command runs a shell in the screen.
286 .\"Editing is unchanged, with the exception that a \fC<carriage-return>\fP
287 .\"enters the current line (stripped of any prompt) as input to the
288 .\"shell.
289 .IP "Split screens"
290 The
291 .CO Edit ,
292 .CO Ex ,
293 .CO Next ,
294 .CO Previous ,
295 .CO Tag
296 and
297 .CO Visual
298 (in
299 .CO vi
300 mode) commands divide the screen into multiple editing regions and
301 then perform their normal function in a new screen area.
302 The
303 .CO <control-W>
304 command rotates between the foreground screens.
305 The
306 .CO resize
307 command can be used to grow or shrink a particular screen.
308 .IP "Tag stacks"
309 Tags are now maintained in a stack.
310 The
311 .CO <control-T>
312 command returns to the previous tag location.
313 The
314 .CO tagpop
315 command returns to the most recent tag location by default, or,
316 optionally to a specific tag number in the tag stack,
317 or the most recent tag from a specified file.
318 The
319 .CO display
320 command can be used to list the tags stack.
321 The
322 .CO tagtop
323 command returns to the top of the tag stack.
324 .IP "Usage information"
325 The
326 .CO exusage
327 and
328 .CO viusage
329 commands provide usage information for all of the
330 .CO ex
331 and
332 .CO vi
333 commands by default, or, optionally, for a specific command or key.
334 .IP "Word search"
335 The
336 .CO <control-A>
337 command searches for the word referenced by the cursor.
338 .SH 1 "Startup Information"
339 .pp
340 .EV Ex vi
341 interprets one of two possible environmental variables and reads up to
342 three of five possible files during startup.
343 The variables and files are expected to contain
344 .CO ex
345 commands, not
346 .CO vi
347 commands.
348 In addition, they are interpreted
349 .i before
350 the file to be edited is read, and therefore many
351 .CO ex
352 commands may not be used.
353 Generally, any command that requires output to the screen or that
354 needs a file upon which to operate, will cause an error if included
355 in a startup file or environmental variable.
356 .pp
357 Because the
358 .CO ex
359 command set supported by
360 .EV nex nvi
361 is a superset of the command set supported by historical implementations of
362 .CO ex ,
363 .EV nex nvi
364 can use the startup files created for the historical implementations,
365 but the converse may not be true.
366 .pp
367 If the
368 .b \-s
369 (the historic \- option)
370 is specified, or if standard input is redirected from a file,
371 all environmental variables and startup files are ignored.
372 .pp
373 Otherwise, startup files and environmental variables are handled
374 in the following order:
375 .np
376 The file
377 .LI /etc/vi.exrc
378 is read,
379 as long as it is owned by root or the effective user ID of the user.
380 .np
381 The environmental variable
382 .LI NEXINIT
383 (or the variable
384 .LI EXINIT ,
385 if
386 .LI NEXINIT
387 is not set) is interpreted.
388 .np
389 If neither
390 .LI NEXINIT
391 or
392 .LI EXINIT
393 was set, and the
394 .LI HOME
395 environmental variable is set, the file
396 .LI $HOME/.nexrc
397 (or the file
398 .LI $HOME/.exrc ,
399 if
400 .LI $HOME/.nexrc
401 does not exist) is read,
402 as long as the effective user ID of the user is root or is the same as
403 the owner of the file.
404 .sp
405 When the $HOME directory is being used for both
406 .EV nex nvi
407 and an historic implementation of
408 .EV ex vi ,
409 a possible solution is to put
410 .EV nex nvi
411 specific commands in the
412 .LI \&.nexrc
413 file, along with a
414 .CO ":source $HOME/.exrc"
415 command to read in the commands common to both implementations.
416 .np
417 If the
418 .OP exrc
419 option was turned on by one of the previous startup information
420 sources, the file
421 .LI \&.nexrc
422 (or the file
423 .LI \&.exrc ,
424 if
425 .LI \&.nexrc
426 does not exist) is read, as long as the effective user ID of the user
427 is the same as the owner of the file.
428 .pp
429 No startup file is read if it is writable by anyone other than its owner.
430 .pp
431 It is not an error for any of the startup environmental variables or files
432 not to exist.
433 .pp
434 Once all environmental variables are interpreted,
435 and all startup files are read,
436 the first file to be edited is read in (or a temporary file is created).
437 .pp
438 As soon as an existing file is loaded
439 (either due to the command line parameters or from within the editor),
440 any command specified using the
441 .b \-c
442 option is executed, in the context of that file.
443 Note that such a command is an
444 .CO ex
445 command and thus obeys the
446 .CO ex
447 behaviour by first jumping to the end of the file, even if used with
448 .CO vi .
449 .SH 1 "Recovery"
450 .pp
451 There is no recovery program for
452 .EV nex nvi ,
453 nor does
454 .EV nex nvi
455 run setuid.
456 Recovery files are created readable and writable by the owner only.
457 Users may recover any file which they can read,
458 and the superuser may recover any edit session.
459 .pp
460 Edit sessions are backed by files in the directory named by the
461 .OP recdir
462 option (the directory
463 .LI /var/tmp/vi.recover
464 by default), and are named
465 .QC vi.XXXXXX ,
466 where
467 .QC XXXXXX
468 is a number related to the process ID.
469 When a file is first modified,
470 a second recovery file containing an email message for the user is created,
471 and is named
472 .QC recover.XXXXXX ,
473 where, again,
474 .QC XXXXXX
475 is associated with the process ID.
476 Both files are removed at the end of a normal edit session,
477 but will remain if the edit session is abnormally terminated
478 or the user runs the
479 .CO ex
480 .CO preserve
481 command.
482 .pp
483 The
484 .OP recdir
485 option may be set in either the user's or system's startup information,
486 changing the recovery directory.
487 (Note, however, that if a memory based file system is used as the backup
488 directory, each system reboot will delete all of the recovery files!
489 The same caution applies to directories such as
490 .LI /tmp
491 which are cleared of their contents by a system reboot, or
492 .LI /usr/tmp
493 which is periodically cleared of old files on many systems.)
494 .pp
495 The recovery directory should be owned by root, or at least by a pseudo-user.
496 In addition, if directory
497 .QQ sticky-bit
498 semantics are available, the directory should have the sticky-bit
499 set so that files may only be removed by their owners.
500 The recovery directory must be read, write, and executable by any user,
501 i.e. mode 1777.
502 .pp
503 If the recovery directory does not exist,
504 .EV ex vi
505 will attempt to create it.
506 This can result in the recovery directory being owned by a normal user,
507 which means that that user will be able to remove other user's recovery
508 and backup files.
509 This is annoying, but is not a security issue as the user cannot
510 otherwise access or modify the files.
511 .pp
512 The recovery file has all of the necessary information in it to enable the
513 user to recover the edit session.
514 In addition, it has all of the necessary email headers for
515 .XR sendmail 8 .
516 When the system is rebooted, all of the files in
517 .LI /var/tmp/vi.recover
518 named
519 .QC recover.XXXXXX
520 should be sent to their owners, by email, using the
521 .b \-t
522 option of
523 .CO sendmail
524 (or a similar mechanism in other mailers).
525 If
526 .EV ex vi
527 receives a hangup (SIGHUP) signal, or the user executes the
528 .CO ex
529 .CO preserve
530 command,
531 .EV ex vi
532 will automatically email the recovery information to the user.
533 .pp
534 If your system does not have the
535 .CO sendmail
536 utility (or a mailer program which supports its interface)
537 the source file
538 .LI nvi/common/recover.c
539 will have to be modified to use your local mail delivery programs.
540 Note, if
541 .EV nex nvi
542 is changed to use another mailer,
543 it is important to remember that the owner of the file given to
544 the mailer is the
545 .EV nex nvi
546 user, so nothing in the file should be trusted as it may have been
547 modified in an effort to compromise the system.
548 .pp
549 Finally, the owner execute bit is set on backup files when they are
550 created, and unset when they are first modified, e.g. backup files
551 that have no associated email recovery file will have this bit set.
552 (There is also a small window where empty files can be created and
553 not yet have this bit set.
554 This is due to the method in which the files are created.)
555 Such files should be deleted when the system reboots.
556 .pp
557 A simple way to do this cleanup is to run the Bourne shell script
558 .CO recover ,
559 from your
560 .LI /etc/rc.local
561 (or other system startup) file.
562 The script should work with the historic Bourne shell,
563 a POSIX 1003.2 shell or the Korn shell.
564 The
565 .CO recover
566 script is installed as part of the
567 .EV nex nvi
568 installation process.
569 .pp
570 Consult the manual page for details on recovering preserved or
571 aborted editing sessions.
572 .SH 1 "Sizing the Screen"
573 .pp
574 The size of the screen can be set in a number of ways.
575 .EV Ex vi
576 takes the following steps until values are obtained for both the
577 number of rows and number of columns in the screen.
578 .np
579 If the environmental variable
580 .LI LINES
581 exists,
582 it is used to specify the number of rows in the screen.
583 .np
584 If the environmental variable
585 .LI COLUMNS
586 exists,
587 it is used to specify the number of columns in the screen.
588 .np
589 The TIOCGWINSZ
590 .XR ioctl 2
591 is attempted on the standard error file descriptor.
592 .np
593 The termcap entry (or terminfo entry on System V machines)
594 is checked for the
595 .QQ li
596 entry (rows) and the
597 .QQ co
598 entry (columns).
599 .np
600 The number of rows is set to 24, and the number of columns is set to 80.
601 .pp
602 If a window change size signal (SIGWINCH) is received,
603 the new window size is retrieved using the TIOCGWINSZ
604 .XR ioctl 2
605 call, and all other information is ignored.
606 .SH 1 "Character Display"
607 .pp
608 In both
609 .CO ex
610 and
611 .CO vi
612 printable characters as defined by
613 .XR isprint 3
614 are displayed using the local character set.
615 .pp
616 Non-printable characters, for which
617 .XR iscntrl 3
618 returns true, and which are less than octal \e040,
619 are displayed as the string
620 .QT ^<character> ,
621 where
622 .LI <character>
623 is the character that is the original character's value offset from the
624 .QT @
625 character.
626 For example, the octal character \e001 is displayed as
627 .QT ^A .
628 If
629 .XR iscntrl 3
630 returns true for the octal character \e177,
631 it is displayed as the string
632 .QT ^? .
633 All other characters are displayed as either hexadecimal values,
634 in the form
635 .QT "0x<high-halfbyte> ... 0x<low-halfbyte>" ,
636 or as octal values, in the form
637 .QT "\e<high-one-or-two-bits> ... \e<low-three-bits>" .
638 The display of unknown characters is based on the value of the
639 .OP octal
640 option.
641 .pp
642 In
643 .CO vi
644 command mode, the cursor is always positioned on the last column of
645 characters which take up more than one column on the screen.
646 In
647 .CO vi
648 text input mode, the cursor is positioned on the first column of
649 characters which take up more than one column on the screen.
650 .SH 1 "Multiple Screens"
651 .pp
652 .CO Nvi
653 supports multiple screens by dividing the window into regions.
654 It also supports stacks of screens by permitting the user to change
655 the set of screens that are currently displayed.
656 .pp
657 The
658 .CO Edit ,
659 .CO Ex ,
660 .CO Fg ,
661 .CO Next ,
662 .CO Previous ,
663 .CO Tag
664 and
665 .CO Visual
666 (in
667 .CO vi
668 mode)
669 commands divide the current screen into two regions of approximately
670 equal size and then perform their usual action in a new screen area.
671 If the cursor is in the lower half of the screen, the screen will split
672 up, i.e. the new screen will be above the old one.
673 If the cursor is in the upper half of the screen, the new screen will be
674 below the old one.
675 .pp
676 When more than one screen is editing a file, changes in any screen are
677 reflected in all other screens editing the same file.
678 Exiting a screen without saving any changes (or explicitly discarding
679 them) is permitted until the last screen editing the file is exited,
680 at which time the changes must be saved or discarded.
681 .pp
682 The
683 .CO resize
684 command permits resizing of individual screens.
685 Screens may be grown, shrunk or set to an absolute number of rows.
686 .pp
687 The
688 .CO ^W
689 command is used to switch between screens.
690 Each
691 .CO ^W
692 moves to the next lower screen in the window, or to the first screen
693 in the window if there are no lower screens.
694 .pp
695 The
696 .CO bg
697 command
698 .QQ backgrounds
699 the current screen.
700 The screen disappears from the window,
701 and the rows it occupied are taken over by a neighboring screen.
702 It is an error to attempt to background the only screen in the window.
703 .pp
704 The
705 .CO "display screens"
706 command displays the names of the files associated with the current
707 backgrounded screens in the window.
708 .pp
709 The
710 .CO "fg [file]"
711 command moves the specified screen from the list of backgrounded screens
712 to the foreground.
713 If no file argument is specified, the first screen on the list is
714 foregrounded.
715 By default,
716 foregrounding consists of backgrounding the current screen,
717 and replacing its space in the window with the foregrounded screen.
718 .pp
719 Capitalizing the first letter of the command, i.e.
720 .CO Fg ,
721 will foreground the backgrounded screen in a new screen instead of
722 swapping it with the current screen.
723 .pp
724 If the last foregrounded screen in the window is exited,
725 and there are backgrounded screens,
726 the first screen on the list of backgrounded screens takes over the window.
727 .SH 1 "Tags, Tag Stacks, and Cscope"
728 .pp
729 .CO Nvi
730 supports the historic
731 .CO vi
732 tag command
733 .CO <control-]> ,
734 and the historic
735 .CO ex
736 tag command
737 .CO tag .
738 These commands change the current file context to a new location,
739 based on information found in the
740 .LI tags
741 files.
742 If you are unfamiliar with these commands,
743 you should review their description in the
744 .CO ex
745 and
746 .CO vi
747 commands section of this manual.
748 For additional information on tags files,
749 see the discussion of the
750 .OP tags
751 edit option and the system
752 .XR ctags 1
753 manual page.
754 .pp
755 In addition,
756 .CO nvi
757 supports the notion of
758 .QQ "tags stacks" ,
759 using the
760 .CO <control-T>
761 command.
762 The
763 .CO <control-T>
764 command returns the user to the previous context, i.e.,
765 the last place from which a
766 .CO <control-]>
767 or
768 .CO "tag"
769 command was entered.
770 These three commands provide the basic functionality which allows you
771 to use
772 .CO vi
773 to review source code in a structured manner.
774 .pp
775 .CO Nvi
776 also provides two other basic
777 .CO ex
778 commands for tag support:
779 .CO tagpop
780 and
781 .CO tagtop .
782 The
783 .CO tagpop
784 command is identical to the
785 .CO <control-T>
786 command,
787 with the additional functionality that you may specify that modifications
788 to the current file are to be discarded.
789 This cannot be done using the
790 .CO <control-T>
791 command.
792 The
793 .CO tagtop
794 command discards all of the contexts that have been pushed onto the tag
795 stack, returning to the context from which the first
796 .CO <control-]>
797 or
798 .CO tag
799 command was entered.
800 .pp
801 The historic
802 .XR ctags 1
803 tags file format supports only a single location per tag,
804 normally the function declaration or structure or string definition.
805 More sophisticated source code tools often provide multiple locations
806 per tag, e.g.,
807 a list of the places from which a function is called or a string
808 definition is used.
809 An example of this functionality is the System V source code tool,
810 .CO cscope .
811 .sp
812 .CO Cscope
813 creates a database of information on source code files,
814 and supports a query language for that information as described in the
815 .XR cscope 1
816 manual page.
817 .CO Nvi
818 contains an interface to the
819 .CO cscope
820 query language which permits you to query
821 .CO cscope
822 and then sequentially step through the locations in the sources files which
823 .CO cscope
824 returns.
825 There are two
826 .CO nvi
827 commands which support this ability to step through multiple locations.
828 They are the
829 .CO ex
830 commands
831 .CO tagnext
832 and
833 .CO tagprev .
834 The
835 .CO tagnext
836 command moves to the next location for the current tag.
837 The
838 .CO tagprev
839 command moves to the previous location for the current tag.
840 (See the
841 .CO tagnext
842 and
843 .CO tagprev
844 command discussion in the
845 .CO ex
846 commands section of this manual for more information.)
847 At any time during this sequential walk,
848 you may use the
849 .CO <control-]> ,
850 .CO tag
851 or
852 .CO cscope
853 commands to move to a new tag context, and then use the
854 .CO <control-T>
855 or
856 .CO tagpop
857 commands to return and continue stepping through the locations for this
858 tag.
859 This is similar to the previous model of a simple tag stack,
860 except that each entry in the tag stack may have more than one file context
861 that is of interest.
862 .pp
863 Although there is no widely distributed version of
864 .XR ctags 1
865 that creates tags files with multiple locations per tag,
866 .CO nvi
867 has been written to understand the obvious extension to the historic
868 tags file format, i.e., more than a single line in the tags file with
869 the same initial tag name.
870 If you wish to extend your
871 .CO ctags
872 implementation or other tool with which you build tags files,
873 this extension should be simple and will require no changes to
874 .CO nvi .
875 .pp
876 The
877 .CO nvi
878 and
879 .CO cscope
880 interface is based on the new
881 .CO ex
882 command
883 .CO cscope ,
884 which has five subcommands:
885 .CO add ,
886 .CO find ,
887 .CO help ,
888 .CO kill
889 and
890 .CO reset .
891 The subcommand
892 .CO find
893 itself has eight subcommands:
894 .CO \&c ,
895 .CO \&d ,
896 .CO \&e ,
897 .CO \&f ,
898 .CO \&g ,
899 .CO \&i ,
900 .CO \&s
901 and
902 .CO \&t .
903 .pp
904 .IP "cs[cope] a[dd] file"
905 The
906 .CO add
907 command attaches to the specified
908 .CO cscope
909 database.
910 The file name is expanded using the standard filename expansions.
911 If
912 .CO file
913 is a directory, the file
914 .QQ cscope.out
915 in that directory is used as the database.
916 .pp
917 After
918 .CO nvi
919 attaches to a new database,
920 all subsequent
921 .CO cscope
922 queries will be asked of that database.
923 The result of any single query is the collection of response to the query
924 from all of the attached databases.
925 .sp
926 If the
927 .QQ CSCOPE_DIRS
928 environmental variable is set when
929 .CO nvi
930 is run,
931 it is expected to be a <colon> or <blank>-separated list of
932 .CO cscope
933 databases or directories containing
934 .CO cscope
935 databases, to which the user wishes to attach.
936 .IP ":cs[cope] f[ind] c|d|e|f|g|i|s|t buffer|pattern"
937 The
938 .CO find
939 command is the
940 .CO cscope
941 query command for
942 .CO nvi .
943 For this command,
944 .CO nvi
945 queries all attached
946 .CO cscope
947 databases for the pattern.
948 If the pattern is a double-quote character followed by a valid buffer
949 name (e.g.,
950 .LI """<character>" ),
951 then the contents of the named buffer are used as the pattern.
952 Otherwise, the pattern is a Regular Expression.
953 .sp
954 The
955 .CO find
956 command pushes the current location onto the tags stack,
957 and switches to the first location resulting from the query,
958 if the query returned at least one result.
959 .sp
960 File names returned by the
961 .CO cscope
962 query, if not absolute paths, are searched for relative to the directory
963 where the
964 .CO cscope
965 database is located.
966 In addition, if the file
967 .QQ cscope.tpath
968 appears in the same directory as the
969 .CO cscope
970 database,
971 it is expected to contain a colon-separated list of directory names
972 where files referenced by its associated
973 .CO cscope
974 database may be found.
975 .sp
976 The
977 .CO find
978 subcommand is one of the following:
979 .SS
980 .SP \&c
981 Find callers of the name.
982 .SP \&d
983 Find all function calls made from name.
984 .SP \&e
985 Find pattern.
986 .SP \&f
987 Find files with name as substring.
988 .SP \&g
989 Find definition of name.
990 .SP \&i
991 Find files #including name.
992 .SP \&s
993 Find all uses of name.
994 .SP \&t
995 Find assignments to name.
996 .SE
997 .IP ":cs[cope] h[elp] [command]"
998 List the
999 .CO cscope
1000 commands,
1001 or optionally list usage help for any single
1002 .CO cscope
1003 command.
1004 .IP ":display c[onnections]"
1005 Display the list of
1006 .CO cscope
1007 databases to which
1008 .CO nvi
1009 is currently connected.
1010 .IP ":cs[cope] k[ill] #"
1011 Disconnect from a specific
1012 .CO cscope
1013 database.
1014 The connection number is the one displayed by the
1015 .CO ex
1016 .CO "display connections"
1017 command.
1018 .IP ":cs[cope] r[eset]"
1019 Disconnect from all attached
1020 .CO cscope
1021 databases.
1022 .pp
1023 Cscope is not freely redistributable software,
1024 but is fairly inexpensive and easily available.
1025 To purchase a copy of
1026 .CO cscope ,
1027 see http://www.att.com/ssg/products/toolchest.html.
1028 .SH 1 "Regular Expressions and Replacement Strings"
1029 .pp
1030 Regular expressions are used in line addresses,
1031 as the first part of the
1032 .CO ex
1033 .CO substitute ,
1034 .CO global ,
1035 and
1036 .CO v
1037 commands, and in search patterns.
1038 .pp
1039 The regular expressions supported by
1040 .EV ex vi
1041 are, by default, the Basic Regular Expressions (BRE's) described in the
1042 IEEE POSIX Standard 1003.2.
1043 The
1044 .OP extended
1045 option causes all regular expressions to be interpreted as the Extended
1046 Regular Expressions (ERE's) described by the same standard.
1047 (See
1048 .XR re_format 7
1049 for more information.)
1050 Generally speaking, BRE's are the Regular Expressions found in
1051 .XR ed 1
1052 and
1053 .XR grep 1 ,
1054 and ERE's are the Regular Expressions found in
1055 .XR egrep 1 .
1056 .pp
1057 The following is not intended to provide a description of Regular
1058 Expressions.
1059 The information here only describes strings and characters which
1060 have special meanings in the
1061 .EV ex vi
1062 version of RE's,
1063 or options which change the meanings of characters that normally
1064 have special meanings in RE's.
1065 .np
1066 An empty RE (e.g.
1067 .QT //
1068 or
1069 .QT ??
1070 is equivalent to the last RE used.
1071 .np
1072 The construct
1073 .QT \e<
1074 matches the beginning of a word.
1075 .np
1076 The construct
1077 .QT \e>
1078 matches the end of a word.
1079 .np
1080 The character
1081 .QT ~
1082 matches the replacement part of the last
1083 .CO substitute
1084 command.
1085 .pp
1086 When the
1087 .OP magic
1088 option is
1089 .i not
1090 set, the only characters with special meanings are a
1091 .QT ^
1092 character at the beginning of an RE, a
1093 .QT $
1094 character at the end of an RE, and the escaping character
1095 .QT \e .
1096 The characters
1097 .QT \&. ,
1098 .QT * ,
1099 .QT [
1100 and
1101 .QT ~
1102 are treated as ordinary characters unless preceded by a
1103 .QT \e ;
1104 when preceded by a
1105 .QT \e
1106 they regain their special meaning.
1107 .pp
1108 Replacement strings are the second part of a
1109 .CO substitute
1110 command.
1111 .pp
1112 The character
1113 .QT &
1114 (or
1115 .QT \e&
1116 if the
1117 .OP magic
1118 option is
1119 .i not
1120 set) in the replacement string stands for the text matched by the RE
1121 that is being replaced.
1122 The character
1123 .QT ~
1124 (or
1125 .QT \e~
1126 if the
1127 .OP magic
1128 option is
1129 .i not
1130 set) stands for the replacement part of the previous
1131 .CO substitute
1132 command.
1133 It is only valid after a
1134 .CO substitute
1135 command has been performed.
1136 .pp
1137 The string
1138 .QT \e# ,
1139 where
1140 .QT #
1141 is an integer value from 1 to 9, stands for the text matched by
1142 the portion of the RE enclosed in the
1143 .QT # 'th
1144 set of escaped parentheses, e.g.
1145 .QT \e(
1146 and
1147 .QT \e) .
1148 For example,
1149 .QT "s/abc\e(.*\e)def/\e1/"
1150 deletes the strings
1151 .QT abc
1152 and
1153 .QT def
1154 from the matched pattern.
1155 .pp
1156 The strings
1157 .QT \el ,
1158 .QT \eu ,
1159 .QT \eL
1160 and
1161 .QT \eU
1162 can be used to modify the case of elements in the replacement string.
1163 The string
1164 .QT \el
1165 causes the next character to be converted to lowercase;
1166 the string
1167 .QT \eu
1168 behaves similarly, but converts to uppercase
1169 (e.g.
1170 .LI s/abc/\eU&/
1171 replaces the string
1172 .LI abc
1173 with
1174 .LI ABC ).
1175 The string
1176 .QT \eL
1177 causes characters up to the end of the string or the next occurrence
1178 of the strings
1179 .QT \ee
1180 or
1181 .QT \eE
1182 to be converted to lowercase;
1183 the string
1184 .QT \eU
1185 behaves similarly, but converts to uppercase.
1186 .pp
1187 If the entire replacement pattern is
1188 .QT % ,
1189 then the last replacement pattern is used again.
1190 .pp
1191 In
1192 .CO vi ,
1193 inserting a
1194 .LI <control-M>
1195 into the replacement string will cause
1196 the matched line to be split into two lines at that point.
1197 (The
1198 .LI <control-M>
1199 will be discarded.)
1200 .SH 1 "Scripting Languages"
1201 .pp
1202 The
1203 .CO nvi
1204 editor currently supports two scripting languages, Tcl/Tk and Perl.
1205 (Note that Perl4 isn't sufficient, and that the Perl5 used must be
1206 version 5.002 or later.
1207 See the
1208 .QB "Building Nvi"
1209 section for more information.
1210 .pp
1211 The scripting language interface is still being worked on,
1212 therefore the following information is probably incomplete,
1213 probably wrong in cases, and likely to change.
1214 See the
1215 .LI perl_api
1216 and
1217 .LI tcl_api
1218 source directories for more information.
1219 As a quick reference, the following function calls are provided for
1220 both the Perl and Tcl interfaces.
1221 The Perl interface uses a slightly different naming convention,
1222 e.g. ``viFindScreen'' is named ``VI::FindScreen''.
1223 .IP "viFindScreen file"
1224 Return the
1225 .LI "screenId" associated with
1226 .LI file .
1227 .IP "viAppendLine screenId lineNumber text"
1228 Append
1229 .LI text
1230 as a new line after line number
1231 .LI lineNumber ,
1232 in the screen
1233 .LI screenId .
1234 .IP "viDelLine screenId lineNum"
1235 Delete the line
1236 .LI lineNumber
1237 from the screen
1238 .LI screenId .
1239 .IP "viGetLine screenId lineNumber"
1240 Return the line
1241 .LI lineNumber
1242 from the screen
1243 .LI screenId .
1244 .IP "viInsertLine screenId lineNumber text"
1245 Insert
1246 .LI text
1247 as a new line before line number
1248 .LI lineNumber
1249 in the screen
1250 .LI screenId .
1251 .IP "viLastLine screenId"
1252 Return the line number of the last line in the screen
1253 .LI screenId .
1254 .IP "viSetLine screenId lineNumber text"
1255 Change the line
1256 .LI lineNumber
1257 in the screen
1258 .LI screenId
1259 to match the specified
1260 .LI text .
1261 .IP "viGetMark screenId mark"
1262 Return the current line and column for the specified
1263 .LI mark
1264 from the screen
1265 .LI screenId .
1266 .IP "viSetMark screenId mark line column"
1267 Set the specified
1268 .LI mark
1269 to be at line
1270 .LI line ,
1271 column
1272 .LI column ,
1273 in the screen
1274 .LI screenId .
1275 .IP "viGetCursor screenId"
1276 Return the current line and column for the cursor in the screen
1277 .LI screenId .
1278 .IP "viSetCursor screenId line column"
1279 Set the cursor in the screen
1280 .LI screenId
1281 to the specified
1282 .LI line
1283 and
1284 .LI column .
1285 .IP "viMsg screenId text"
1286 Display the specified
1287 .LI text
1288 as a vi message in the screen
1289 .LI screenId .
1290 .IP "viNewScreen screenId [file]"
1291 Create a new screen.
1292 .IP "viEndScreen screenId"
1293 Exit the screen
1294 .LI screenId .
1295 .IP "viSwitchScreen screenId screenId"
1296 Switch from the screen
1297 .LI screenId
1298 to the screen
1299 .LI screenId .
1300 .IP "viMapKey screenId key tclproc"
1301 Map the specified
1302 .LI key
1303 in the screen
1304 .LI screenId
1305 to the Tcl procedure
1306 .LI tclproc .
1307 .IP "viUnmMapKey screenId key"
1308 Unmap the specified
1309 .LI key
1310 in the screen
1311 .LI screenId
1312 .IP "viGetOpt screenId option"
1313 Return the value of the specified
1314 .LI option
1315 from the screen
1316 .LI screenId .
1317 .IP "viSetOpt screenId command"
1318 Set one or more options in the screen
1319 .LI screenId .
1320 .SH 1 "General Editor Description"
1321 .pp
1322 When
1323 .CO ex
1324 or
1325 .CO vi
1326 are executed,
1327 the text of a file is read (or a temporary file is created),
1328 and then all editing changes happen within the context of the
1329 copy of the file.
1330 .i "No changes affect the actual file until the file is written out" ,
1331 either using a write command or another command which is affected by the
1332 .OP autowrite
1333 option.
1334 .pp
1335 All files are locked (using the
1336 .XR flock 2
1337 or
1338 .XR fcntl 2
1339 interfaces) during the edit session,
1340 to avoid inadvertently making modifications to multiple copies of the file.
1341 If a lock cannot be obtained for a file because it is locked by another
1342 process, the edit session is read-only (as if the
1343 .OP readonly
1344 option or the
1345 .b \-R
1346 flag had been specified).
1347 If a lock cannot be obtained for other reasons, the edit session will
1348 continue, but the file status information
1349 (see the
1350 .CO <control-G>
1351 command) will reflect this fact.
1352 .pp
1353 Both
1354 .CO ex
1355 and
1356 .CO vi
1357 are modeful editors, i.e. they have two modes,
1358 .QQ command
1359 mode and
1360 .QQ "text input"
1361 mode.
1362 The former is intended to permit you to enter commands which modifies
1363 already existing text.
1364 The latter is intended to permit you to enter new text.
1365 When
1366 .CO ex
1367 first starts running, it is in command mode, and usually displays a prompt
1368 (see the
1369 .OP prompt
1370 option for more information).
1371 The prompt is a single colon
1372 .PQ :
1373 character.
1374 There are three commands that switch
1375 .CO ex
1376 into text input mode:
1377 .CO append ,
1378 .CO change
1379 and
1380 .CO insert .
1381 Once in input mode, entering a line containing only a single period
1382 .PQ \&.
1383 ends text input mode and returns to command mode,
1384 where the prompt is redisplayed.
1385 .pp
1386 When
1387 .CO vi
1388 first starts running, it is in command mode as well.
1389 There are eleven commands that switch
1390 .CO vi
1391 into text input mode:
1392 .CO A ,
1393 .CO a ,
1394 .CO C ,
1395 .CO c ,
1396 .CO I ,
1397 .CO i ,
1398 .CO O ,
1399 .CO o ,
1400 .CO R ,
1401 .CO S
1402 and
1403 .CO s .
1404 Once in input mode, entering an
1405 .LI <escape>
1406 character ends text input mode and returns to command mode.
1407 .pp
1408 .EV Ex vi
1409 present three different interfaces to editing a file.
1410 .CO Ex
1411 presents a line oriented interface.
1412 .CO Vi
1413 presents a full screen display oriented interface,
1414 also known as
1415 .QQ "visual mode" .
1416 In addition, there is a third mode,
1417 .QQ "open mode" ,
1418 which is line oriented,
1419 but supports cursor movement and editing within the displayed line,
1420 similarly to visual mode.
1421 Open mode is not yet implemented in
1422 .CO nvi .
1423 .pp
1424 The following words have special meanings in both the
1425 .CO ex
1426 and
1427 .CO vi
1428 command descriptions:
1429 .KY <interrupt>
1430 .IP <interrupt>
1431 The interrupt character is used to interrupt the current operation.
1432 Normally
1433 .LI <control-C> ,
1434 whatever character is set for the current terminal is used.
1435 .KY "<literal-next>"
1436 .IP "<literal-next>"
1437 The literal next character is used to escape the subsequent character
1438 from any special meaning.
1439 This character is always
1440 .LI <control-V> .
1441 If the terminal is not set up to do XON/XOFF flow control,
1442 then
1443 .LI <control-Q>
1444 is used to mean literal next as well.
1445 .KY "current pathname"
1446 .IP "current pathname"
1447 The pathname of the file currently being edited by vi.
1448 When the percent character
1449 .PQ %
1450 appears in a file name entered as part of an
1451 .CO ex
1452 command argument, it is replaced by the current pathname.
1453 (The
1454 .QT %
1455 character can be escaped by preceding it with a backslash.)
1456 .KY "alternate pathname"
1457 .IP "alternate pathname"
1458 The name of the last file name mentioned in an
1459 .CO ex
1460 command, or,
1461 the previous current pathname if the last file mentioned
1462 becomes the current file.
1463 When the hash mark character
1464 .PQ #
1465 appears in a file name entered as part of an
1466 .CO ex
1467 command argument, it is replaced by the alternate pathname.
1468 (The
1469 .QT #
1470 character can be escaped by preceding it with a backslash.)
1471 .KY buffer
1472 .IP buffer
1473 One of a number of named areas for saving copies of text.
1474 Commands that change or delete text can save the changed or deleted
1475 text into a specific buffer, for later use, if the command allows
1476 it (i.e. the
1477 .CO ex
1478 .CO change
1479 command cannot save the changed text in a named buffer).
1480 Buffers are named with a single character, preceded by a double quote,
1481 e.g.
1482 .LI """<character>"
1483 in
1484 .CO vi
1485 and
1486 without the double quote, e.g.
1487 .LI <character> ,
1488 in
1489 .CO ex .
1490 (The double quote isn't necessary for
1491 .CO ex
1492 because buffers names are denoted by their position in the command line.)
1493 Historic implementations of
1494 .EV ex vi
1495 limited
1496 .LI <character>
1497 to the alphanumeric characters;
1498 .EV nex nvi
1499 permits the use of any character without another meaning in the position
1500 where a buffer name is expected.
1501 .sp
1502 Buffers named by uppercase characters are the same as buffers
1503 named by lowercase characters, e.g. the buffer named by the
1504 English character
1505 .QT A
1506 is the same as the buffer named by the character
1507 .QT a ,
1508 with the exception that, if the buffer contents are being changed (as
1509 with a text deletion or
1510 .CO vi
1511 .CO change
1512 command), the text is
1513 .i appended
1514 to the buffer, instead of replacing the current contents.
1515 .sp
1516 The buffers named by the numeric characters (in English,
1517 .QT 1
1518 through
1519 .QT 9 ),
1520 are special.
1521 If a region of text including characters from more than one line,
1522 or a single line of text specified by using a line-oriented motion,
1523 is changed or deleted in the file using the
1524 .CO vi
1525 .CO change
1526 or
1527 .CO delete
1528 commands, a copy of the text is placed into the numeric buffer
1529 .QT 1 ,
1530 regardless of the user specifying another buffer in which to save it.
1531 In addition, there are a few commands which, when used as a
1532 .LI motion
1533 with the
1534 .CO vi
1535 .CO change
1536 and
1537 .CO delete
1538 commands,
1539 .i always
1540 copy the specified region of text into the numeric buffers regardless
1541 of the region including characters from more than one line.
1542 These commands are:
1543 .sp
1544 .ne 3v
1545 .ft C
1546 .TS
1547 r r r r.
1548 <control-A> % ( )
1549 `<character> / ? N
1550 n { }
1551 .TE
1552 .ft R
1553 .sp
1554 Before this copy is done, the previous contents of buffer
1555 .QT 1
1556 are moved into buffer
1557 .QT 2 ,
1558 .QT 2
1559 into buffer
1560 .QT 3 ,
1561 and so on.
1562 The contents of buffer
1563 .QT 9
1564 are discarded.
1565 In
1566 .CO vi ,
1567 text may be explicitly stored into the numeric buffers.
1568 In this case, the buffer rotation described above occurs before the
1569 replacement of the buffer's contents.
1570 The numeric buffers are only available in
1571 .LI visual
1572 and
1573 .LI open
1574 modes,
1575 and are not accessible by
1576 .CO ex
1577 in any way, although changed and deleted text is still stored there
1578 while in
1579 .CO ex
1580 mode.
1581 .sp
1582 When a
1583 .CO vi
1584 command synopsis shows both a
1585 .LI [buffer]
1586 and a
1587 .LI [count] ,
1588 they may be presented in any order.
1589 .sp
1590 Finally, all buffers are either
1591 .QQ line
1592 or
1593 .QQ character
1594 oriented.
1595 All
1596 .CO ex
1597 commands which store text into buffers are line oriented.
1598 Some
1599 .CO vi
1600 commands which store text into buffers are line oriented,
1601 and some are character oriented; the description for each applicable
1602 .CO vi
1603 command notes whether text copied into buffers using the command
1604 is line or character oriented.
1605 In addition, the
1606 .CO vi
1607 command
1608 .CO "display buffers"
1609 displays the current orientation for each buffer.
1610 Generally, the only importance attached to this orientation is that
1611 if the buffer is subsequently inserted into the text, line oriented
1612 buffers create new lines for each of the lines they contain, and
1613 character oriented buffers create new lines for any lines
1614 .i other
1615 than the first and last lines they contain.
1616 The first and last lines are inserted into the text at the current
1617 cursor position, becoming part of the current line.
1618 If there is more than one line in the buffer, however, the current
1619 line itself will be split.
1620 .KY "unnamed buffer"
1621 .IP "unnamed buffer"
1622 The unnamed buffer is a text storage area which is used by commands
1623 that use or operate on a buffer when no buffer is specified by the user.
1624 If the command stores text into a buffer,
1625 the text is stored into the unnamed buffer even if a buffer is also
1626 specified by the user.
1627 It is not possible to append text to the unnamed buffer.
1628 If text is appended to a named buffer,
1629 the named buffer contains both the old and new text,
1630 while the unnamed buffer contains only the new text.
1631 There is no way to explicitly reference the unnamed buffer.
1632 .sp
1633 Historically, the contents of the unnamed buffer were discarded by many
1634 different commands, even ones that didn't store text into it.
1635 .EV Nex nvi
1636 never discards the contents of the unnamed buffer until new text
1637 replaces them.
1638 .KY whitespace
1639 .IP whitespace
1640 The characters <tab> and <space>.
1641 .KY "<carriage-return>"
1642 .IP "<carriage-return>"
1643 The character represented by an ASCII
1644 .LI <control-M> .
1645 This character is almost always treated identically to a
1646 .LI <newline>
1647 character, but differs in that it can be escaped into the file text or
1648 into a command.
1649 .KY <newline>
1650 .IP <newline>
1651 The character represented by an ASCII
1652 .LI <control-J> .
1653 This character is almost always treated identically to a
1654 .LI <control-M>
1655 character, but differs in that it cannot be escaped into the file text or
1656 into a command.
1657 .oh 'Vi/Ex Reference (Vi Commands)''USD:13-%'
1658 .eh 'USD:13-%''Vi/Ex Reference (Vi Commands)'
1659 .so vi.cmd.roff
1660 .oh 'Vi/Ex Reference''USD:13-%'
1661 .eh 'USD:13-%''Vi/Ex Reference'
1662 .SH 1 "Ex Addressing"
1663 .pp
1664 Addressing in
1665 .CO ex
1666 (and when
1667 .CO ex
1668 commands are executed from
1669 .CO vi )
1670 relates to the current line.
1671 In general, the current line is the last line affected by a command.
1672 The exact effect on the current line is discussed under the description
1673 of each command.
1674 When the file contains no lines, the current line is zero.
1675 .pp
1676 Addresses are constructed by one or more of the following methods:
1677 .np
1678 The address
1679 .QT \&.
1680 refers to the current line.
1681 .np
1682 The address
1683 .QT $
1684 refers to the last line of the file.
1685 .np
1686 The address
1687 .QT N ,
1688 where
1689 .LI N
1690 is a positive number, refers to the N-th line of the file.
1691 .np
1692 The address
1693 .QT '<character>
1694 or
1695 .QT `<character>
1696 refers to the line marked with the name
1697 .LI <character> .
1698 (See the
1699 .CO k
1700 or
1701 .CO m
1702 commands for more information on how to mark lines.)
1703 .np
1704 A regular expression (RE) enclosed by slashes
1705 .PQ /
1706 is an address,
1707 and it refers to the first line found by searching forward from the line
1708 .i after
1709 the current line toward the end of the file, and stopping at the
1710 first line containing a string matching the RE.
1711 (The trailing slash can be omitted at the end of the command line.)
1712 .sp
1713 If no RE is specified, i.e. the pattern is
1714 .QT // ,
1715 the last RE used in any command is used in the search.
1716 .sp
1717 If the
1718 .OP extended
1719 option is set, the RE is handled as an extended RE, not a basic RE.
1720 If the
1721 .OP wrapscan
1722 option is set, the search wraps around to the beginning of the file
1723 and continues up to and including the current line, so that the entire
1724 file is searched.
1725 .sp
1726 The form
1727 .QT \e/
1728 is accepted for historic reasons,
1729 and is identical to
1730 .QT // .
1731 .np
1732 An RE enclosed in question marks
1733 .PQ ?
1734 addresses the first line found by searching backward from the line
1735 .i preceding
1736 the current line, toward the beginning of the file and stopping at the
1737 first line containing a string matching the RE.
1738 (The trailing question mark can be omitted at the end of a command line.)
1739 .sp
1740 If no RE is specified, i.e. the pattern is
1741 .QT ?? ,
1742 the last RE used in any command is used in the search.
1743 .sp
1744 If the
1745 .OP extended
1746 option is set, the RE is handled as an extended RE, not a basic RE.
1747 If the
1748 .OP wrapscan
1749 option is set, the search wraps around from the beginning of the file to
1750 the end of the file and continues up to and including the current line,
1751 so that the entire file is searched.
1752 .sp
1753 The form
1754 .QT \e?
1755 is accepted for historic reasons, and is identical to
1756 .QT ?? .
1757 .np
1758 An address followed by a plus sign
1759 .PQ +
1760 or a minus sign
1761 .PQ -
1762 followed by a number is an offset address and refers to the address
1763 plus (or minus) the indicated number of lines.
1764 If the address is omitted, the addition or subtraction is done with
1765 respect to the current line.
1766 .np
1767 An address of
1768 .QT +
1769 or
1770 .QT \-
1771 followed by a number is an offset from the current line.
1772 For example,
1773 .QT \-5
1774 is the same as
1775 .QT \&.\-5 .
1776 .np
1777 An address ending with
1778 .QT +
1779 or
1780 .QT -
1781 has 1 added to or subtracted from the address, respectively.
1782 As a consequence of this rule and of the previous rule, the address
1783 .QT \-
1784 refers to the line preceding the current line.
1785 Moreover, trailing
1786 .QT +
1787 and
1788 .QT \-
1789 characters have a cumulative effect.
1790 For example,
1791 .QT ++\-++
1792 refers to the current line plus 3.
1793 .np
1794 A percent sign
1795 .PQ %
1796 is equivalent to the address range
1797 .QT 1,$ .
1798 .pp
1799 .CO Ex
1800 commands require zero, one, or two addresses.
1801 It is an error to specify an address to a command which requires zero
1802 addresses.
1803 .pp
1804 If the user provides more than the expected number of addresses to any
1805 .CO ex
1806 command, the first addresses specified are discarded.
1807 For example,
1808 .QT 1,2,3,5 print
1809 prints lines 3 through 5, because the
1810 .CO print
1811 command only takes two addresses.
1812 .pp
1813 The addresses in a range are separated from each other by a comma
1814 .PQ ,
1815 or a semicolon
1816 .PQ ; .
1817 In the latter case, the current line
1818 .PQ \&.
1819 is set to the first address, and only then is the second address calculated.
1820 This feature can be used to determine the starting line for forward and
1821 backward searches (see rules (5) and (6) above).
1822 The second address of any two-address sequence corresponds to a line that
1823 follows, in the file, the line corresponding to the first address.
1824 The first address must be less than or equal to the second address.
1825 The first address must be greater than or equal to the first line of the
1826 file, and the last address must be less than or equal to the last line
1827 of the file.
1828 .oh 'Vi/Ex Reference (Ex Commands)''USD:13-%'
1829 .eh 'USD:13-%''Vi/Ex Reference (Ex Commands)'
1830 .so ex.cmd.roff
1831 .oh 'Vi/Ex Reference (Options)''USD:13-%'
1832 .eh 'USD:13-%''Vi/Ex Reference (Options)'
1833 .so set.opt.roff
1834 .oh 'Vi/Ex Reference''USD:13-%'
1835 .eh 'USD:13-%''Vi/Ex Reference'
1836 .bp
1837 .SH 1 Index
1838 .lp
1839 .2c +0.5i 3
1840 .ta \n($luR
1841 .nf
1842 .so index.so
1843 .fi
1844 .\" Force the TOC to an odd page, in case it's a duplex printer.
1845 .if o .bp
1846 .bp 3
1847 .1c
1848 .ce 1
1849 \fB\s+2Table of Contents\s0\fP
1850 .sp
1851 .xp