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