diff options
Diffstat (limited to 'contrib/nvi/docs')
42 files changed, 25684 insertions, 0 deletions
diff --git a/contrib/nvi/docs/TODO b/contrib/nvi/docs/TODO new file mode 100644 index 000000000000..6fe88295d5ff --- /dev/null +++ b/contrib/nvi/docs/TODO @@ -0,0 +1,147 @@ +CL: In single-line screens, have to press 'q' twice when quitting out + of a ":set all" display. + +COMMON: There's a serious problem with error returns -- we need to separate + command failure from fatal error, consistently, over the entire source + tree. + + We need to rework all of vi to have three return values: + + 0: success + 1: vi error, continue + 2: fatal error, die + + Right now we don't recognize fatal errors for what they are. + +VI: Change the screen scrolling to not eat user characters... i.e. + g/pattern/foo should not eat already entered chars. + +COMMON: It's known that it's possible to sync the backing files in the + wrong manner, leaving backup files that aren't recoverable. This + is going to be left alone until we have a logging version of DB, + which will hopefully fix this (or at least make it possible to + easily do so). + +COMMON: The complete list of POSIX.1 calls that can return EINTR are: + + wait, waitpid, sleep, dup2, close, read, write, + fcntl(SETLCKW) tcsetattr, tcdrain + + The problem is that technically, any system/library call can + return EINTR, so, while nvi blocks (most of?) the obvious ones, + someone may have to do a complete pass and block signals + everywhere. + +COMMON: The vi main command loop should use the general-purpose overflow + and underflow routines. In addition, the vi command loop uses + unsigned longs -- should probably be fixed as a 32-bit unsigned + type, and then check to make sure it's never used as as variable + type again. + +DB: When nvi edits files that don't have trailing newlines, it appends + one, regardless. This is required, by default, from POSIX.2. + +COMMON: Open mode is not yet implemented. + +COMMON: ^C isn't passed to the shell in the script windows as an interrupt + character. + +COMMON: The options: + + hardtabs, lisp, optimize, redraw, slowopen + + are recognized, but not implemented. These options are unlikely + to be implemented, so if you want them you might want to say + something! I will implement lisp if anyone ever documents how it + worked. + +COMMON: If you run out of space in the recovery directory, the recovery + file is left in place. + +COMMON: Should "view" set a lock on the file? + +COMMON: Field editing shouldn't be hard to add to nvi: + + Field editing file template: + + version # + field # row/column start row/column stop + label field # Label string + re field # Matching re string. + field # row/column start row/column stop + label field # Label string + re field # Matching re string. + + <tab> moves to the next field + <bs> in column 0 moves to the previous field + +COMMON: Let's rethink using an IPC mechanism: + + Two way channel, with events passing in both directions. + + Load into the same address space (else, how do file permissions) forks + in v_init -- screens get events from vi, vi gets events queued up from + screens. + + Vi: + E_CHARACTER, /* Input character: e_c set. */ + E_EOF, /* End of input (NOT ^D). */ + E_ERR, /* Input error. */ + E_INTERRUPT, /* Interrupt. */ + E_REPAINT, /* Repaint: e_flno, e_tlno set. */ + E_RESIZE, /* SIGWINCH: e_lno, e_cno set. */ + E_SIGCONT, /* SIGCONT arrived. */ + E_SIGFATAL, /* fatal signal arrived. + E_START, /* Start ex/vi. */ + E_STOP, /* Stop ex/vi. */ + E_STRING, /* Input string: e_csp, e_len set. */ + + Screen: + E_ADDSTR /* Add a string to the screen. */ + E_ATTRIBUTE /* Screen attribute. */ + E_BELL /* Beep/bell/flash the terminal. */ + E_BUSY /* Display a busy message. */ + E_CANONICAL /* Enter tty canonical mode. */ + E_CLRTOEOL /* Clear to the end of the line. */ + E_CURSOR /* Return the cursor location. */ + E_DELETELN /* Delete a line. */ + E_DISCARD /* Discard a screen. */ + E_EXADJUST /* Ex: screen adjustment routine. */ + E_FMAP /* Set a function key. */ + E_GETKEY /* Get a key event. */ + E_INSERTLN /* Insert a line. */ + E_MOVE /* Move the cursor. */ + E_MESSAGE /* Message or ex output. */ + E_REFRESH /* Refresh the screen. */ + E_RESIZE /* Resize two screens. */ + E_SPLIT /* Split the screen. */ + E_SUSPEND /* Suspend the editor. */ + +EX: It would be nice to inverse video the replaced text during + interactive substitute. + +EX: The :args command should put the current file name out in reverse + video. This isn't going to be easy, currently only full lines can + be in reverse video, not just parts. + +TK: We currently permit the user to change the lines, columns and term + edit options. Shouldn't that be illegal in tknvi? + +VI: The strings found by searches should be highlighted until the next + character is entered. + +VI: Display a split vi screen for the :help command. + +VI: When getting a key for a continue screen, we should always read from + the terminal, not from a mapped key. + +VI: The sentence, paragraph and section movement commands don't match + historic practice in some boundary cases. This should be left + alone until POSIX 1003.2 makes up its mind. + +VI: The vs_sm_fill routine should scroll if possible, not always redraw. + +VI: Think about setting a dirty/inuse bits on the lines of the SMAP + structure. That way the message routines could steal lines and + refresh would continue to work, because it would know not to touch + the lines that were in use. diff --git a/contrib/nvi/docs/USD.doc/edit/Makefile b/contrib/nvi/docs/USD.doc/edit/Makefile new file mode 100644 index 000000000000..0c59f6d0816e --- /dev/null +++ b/contrib/nvi/docs/USD.doc/edit/Makefile @@ -0,0 +1,11 @@ +# @(#)Makefile 8.4 (Berkeley) 8/18/96 + +ROFF= groff +TBL= tbl + +edittut.ps: edittut.ms + ${TBL} edittut.ms | ${ROFF} -ms > $@ + chmod 444 $@ + +clean: + rm -f edittut.ps diff --git a/contrib/nvi/docs/USD.doc/edit/edit.vindex b/contrib/nvi/docs/USD.doc/edit/edit.vindex new file mode 100644 index 000000000000..2098f14ea190 --- /dev/null +++ b/contrib/nvi/docs/USD.doc/edit/edit.vindex @@ -0,0 +1,115 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)edit.vindex 8.1 (Berkeley) 6/8/93 +.\" +.bd I +.ND +.TL +Index +.sp 3 +.2C +.nf +addressing, \fIsee\fR line numbers +append mode, 4 +backslash (\\), 18 +buffer, 2 +command mode, 4 +context search, 8, 10, 13, 18 +control characters (``^'' notation), 8 +control-d, 6 +current filename, 19, 20 +current line (.), 9, 15 +diagnostic messages, 4 +disk, 2 +documentation, 21 +edit (to begin editing session), 3, 7 +editing commands: +.in +2 +append (a), 4, 7 +change (c), 16 +copy (co), 13 +delete (d), 13-14 +edit (e), 12 +file (f), 19 +global (g), 18-19 +move (m), 12-13 +number (nu), 9 +preserve (pre), 20-21 +print (p), 8 +quit (q), 5, 11 +quit! (q!), 11 +read (r), 20 +recover (rec), 20 +substitute (s), 9-10, 17, 18 +undo (u), 14, 17 +write (w), 5-6, 11, 19-20 +z, 11 +.sp 10i +! (shell escape), 19 +$= , 15 ++, 15 +\-, 15 +//, 8, 18 +??, 18 +\&\fB.\fR, 9, 15 +\&\fB.\fR=, 9, 15 +.in -2 +erasing +.ti +2 +characters (#), 8 +.ti +2 +lines (@), 8 +ex (text editor), 21 +\fIEx Reference Manual\fR, 21 +file, 1 +file recovery, 20 +filename, 2 +Interrupt (message), 7 +line numbers, \fIsee also\fR current line +.ti +2 +dollar sign ($), 8, 12-13, 15 +.ti +2 +dot (.), 9, 15 +.ti +2 +relative (+ and \-), 15, 16 +logging out, 6 +login procedure, 2 +``magic'' characters, 21 +non-printing characters, 8 +``not found'' (message), 3 +program, 1 +recovery \fIsee\fR file recovery +shell, 18 +shell escape (!), 19 +special characters (^, $, \e), 18 +text input mode, 4 +UNIX, 1 diff --git a/contrib/nvi/docs/USD.doc/edit/edittut.ms b/contrib/nvi/docs/USD.doc/edit/edittut.ms new file mode 100644 index 000000000000..8a9d66ede2e6 --- /dev/null +++ b/contrib/nvi/docs/USD.doc/edit/edittut.ms @@ -0,0 +1,2280 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)edittut.ms 8.3 (Berkeley) 8/18/96 +.\" +.ll 6.5i +.nr LL 6.5i +.EH 'USD:11-%''Edit: A Tutorial' +.OH 'Edit: A Tutorial''USD:11-%' +.LP +.ds u \s-2UNIX\s0 +.ND +.sp 4 +.ce +\f3\s+2Edit: A Tutorial\s0\f1 +.sp +.ce 3 +.I +Ricki Blau +.sp +James Joyce +.R +.sp +.ce 3 +Computing Services +University of California +Berkeley, California 94720 +.sp 3 +.ce +.I +ABSTRACT +.R +.sp +.LP +This narrative introduction to the use of the text editor +.I edit +assumes no prior familiarity with computers or with text editing. +Its aim is to lead the beginning \s-2UNIX\(dg\s+2 user through the +.FS +\(dgUNIX is a trademark of Bell Laboratories. +.FE +fundamental steps of writing and revising a file of text. +Edit, +a version of the text editor +.I ex, +was designed to provide an informative environment +for new and casual users. +.PP +We welcome comments and suggestions about this tutorial +and the \s-2UNIX\s+2 documentation in general. +.sp .5v +September 1981 +.bp +.ll 6.5i +.nr LL 6.5i +.nr LT 6.5i +.ds u \s-2UNIX\s0 +.ce +\s+2\f3Contents\f1\s0 +.LP +.nf +Introduction\ \ \ 3 +.sp +Session 1\ \ 4 +.in +.5i +Making contact with \s-2UNIX\s+2\ \ \ 4 +Logging in\ \ 4 +Asking for \fIedit\fR\ \ \ 4 +The ``Command not found'' message\ \ \ 5 +A summary\ \ 5 +Entering text\ \ \ 5 +Messages from \fIedit\fR\ \ \ 5 +Text input mode\ \ \ 6 +Making corrections\ \ \ 6 +Writing text to disk\ \ \ 7 +Signing off\ \ 7 +.in -.5i +.sp +Session 2\ \ \ 8 +.in +.5i +Adding more text to the file\ \ \ 8 +Interrupt\ \ \ 8 +Making corrections\ \ \ 8 +Listing what's in the buffer (p)\ \ \ 9 +Finding things in the buffer\ \ \ 9 +The current line\ \ \ 10 +Numbering lines (nu)\ \ \ 10 +Substitute command (s)\ \ \ 10 +Another way to list what's in the buffer (z)\ \ \ 11 +Saving the modified text\ \ \ 12 +.in -.5i +.sp +Session 3\ \ \ 13 +.in +.5i +Bringing text into the buffer (e)\ \ \ 13 +Moving text in the buffer (m)\ \ \ 13 +Copying lines (copy)\ \ \ 14 +Deleting lines (d)\ \ \ 14 +A word or two of caution\ \ \ 15 +Undo (u) to the rescue\ \ \ 15 +More about the dot (.) and buffer end ($)\ \ \ 16 +Moving around in the buffer (+ and \-)\ \ \ 16 +Changing lines (c)\ \ \ 17 +.in -.5i +.sp +Session 4\ \ \ 18 +.in +.5i +Making commands global (g)\ \ \ 18 +More about searching and substituting\ \ \ 19 +Special characters\ \ \ 19 +Issuing \s-2UNIX\s+2 commands from the editor\ \ \ 20 +Filenames and file manipulation\ \ \ 20 +The file (f) command\ \ \ 20 +Reading additional files (r)\ \ \ 21 +Writing parts of the buffer\ \ \ 21 +Recovering files\ \ \ 21 +Other recovery techniques\ \ \ 21 +Further reading and other information\ \ \ 22 +Using \fIex\fR\ \ \ 22 +.in -.5i +.sp +Index\ \ \ 23 +.bp +.SH +.ce +\s+2Introduction\s0 +.PP +Text editing using a terminal connected to a computer +allows you to create, modify, and print text +easily. +A +.I +text editor +.R +is a program +that assists you +as you create and modify text. +The text editor you will learn here is named +.I edit. +Creating text using edit is as easy as typing it +on an electric typewriter. +Modifying text involves telling the text editor +what you want to add, change, or delete. +You can review your text +by typing a command +to print the file contents +as they are currently. +Another program (which we do not discuss in this +document), a text formatter, +rearranges your text +for you into ``finished form.'' +.PP +These lessons assume no prior familiarity with computers +or with text editing. +They consist of a series of text editing sessions +which lead you through the fundamental steps +of creating and revising text. +After scanning each lesson and before beginning the next, +you should try the examples at a terminal to get a feeling +for the actual process of text editing. +If you set aside some time for experimentation, +you will soon become familiar with using the +computer to write and modify text. +In addition to the actual use of the text editor, +other features of \s-2UNIX\s0 will be very important to your work. +You can begin to +learn about these other features by +reading one of the other tutorials +that provide a general introduction to the system. +You will be ready to proceed with this lesson as soon as +you are familiar with (1) your terminal and its special keys, +(2) how to login, +(3) and the ways of correcting typing errors. +Let's first define some terms: +.sp .5 +.IP program 12 +A set of instructions, given to the computer, +describing the sequence of steps the computer performs +in order to accomplish a specific task. +The task must be specific, +such as balancing your checkbook +or editing your text. +A general task, +such as working for world peace, +is something we can all do, +but not something we can currently write programs to do. +.IP UNIX +\s-2UNIX\s0 is a special type of program, +called an operating system, that supervises the machinery +and all other programs comprising the total +computer system. +.IP edit +.I edit +is the name of the \s-2UNIX\s0 text editor you will be learning to use, +and is a program that aids you in writing or revising text. +Edit was designed for beginning users, +and is a simplified version of an editor named +.I ex. +.IP file +Each \s-2UNIX\s0 account is allotted +space for the permanent storage of information, +such as programs, data or text. +A file is a logical unit of data, +for example, an essay, a program, +or a chapter from a book, +which is stored on a computer system. +Once you create a file, +it is kept until you instruct the system to remove it. +You may create a file during one \s-2UNIX\s0 session, +end the session, +and return to use it at a later time. +Files contain anything you choose to write and store in them. +The sizes of files vary to suit your needs; +one file might hold only a single number, +yet another might contain +a very long document or program. +The only way to save +information from one session to the next is to store it in a file, +which you will learn in Session 1. +.IP filename +Filenames are used to distinguish one file from another, +serving the same purpose as the labels of manila +folders in a file cabinet. +In order to write or access information in a file, +you use the name of that file in a \s-2UNIX\s0 command, +and the system will automatically locate the file. +.IP disk +Files are stored on an input/output device called a disk, +which looks something like a stack of phonograph records. +Each surface is coated with a material similar to that +on magnetic recording tape, +and information is recorded on it. +.IP buffer +A temporary work space, made available to the user +for the duration of a session of text editing +and used for creating and modifying +the text file. +We can think of the buffer as a blackboard that is +erased after each class, where each session with the editor +is a class. +.bp +.SH +.ce 1 +\s+2Session 1\s0 +.sp 1 +.SH +Making contact with \s-1UNIX\s0 +.PP +To use the editor you must first make contact with the computer +by logging in to \s-2UNIX\s0. +We'll quickly review the standard \s-2UNIX\s0 login procedure +for the two ways you can make contact: +on a terminal that is directly linked to the computer, +or over a telephone line where the computer answers your call. +.SH +Directly-linked terminals +.PP +Turn on your terminal and press the \s-1RETURN\s0 key. +You are now ready to login. +.SH +Dial-up terminals +.PP +If your terminal connects with the computer over a telephone line, +turn on the terminal, dial the system access number, +and, when you hear a high-pitched tone, place the +telephone handset in the acoustic coupler, if you are using one. +You are now ready to login. +.SH +Logging in +.PP +The message inviting you to login is: +.DS I 1i +login: +.DE +.LP +Type your login name, which identifies you to \s-2UNIX\s0, +on the same line as the login message, +and press \s-2RETURN\s+2. +If the terminal you are using +has both upper and lower case, +.B +be sure you enter your login name in lower case; +.R +otherwise \s-2UNIX\s0 assumes your terminal +has only upper case and will not recognize lower case +letters you may type. +\s-2UNIX\s0 types ``login:'' and you reply +with your login name, for example ``susan'': +.DS I 1i +login: \fBsusan\fR \fI(and press the \s-2RETURN\s0 key)\fR +.DE +(In the examples, input you would type appears in +.B "bold face" +to distinguish it from the responses from \s-2UNIX\s0.) +.PP +\s-2UNIX\s0 will next respond with a request for a password +as an additional precaution to prevent +unauthorized people from using your account. +The password will not appear when you type it, +to prevent others from seeing it. +The message is: +.DS I 1i +Password: \fI(type your password and press \s-2RETURN\s+2)\fR +.DE +If any of the information you gave during the login +sequence was mistyped or incorrect, +\s-2UNIX\s0 will respond with +.DS I 1i +Login incorrect. +.if t .sp .2v +.if n .sp 1 +login: +.DE +in which case you should start the login process anew. +Assuming that you have successfully +logged in, \s-2UNIX\s0 +will print the message of the day and eventually will present +you with a % at the beginning of a fresh line. +The % is the \s-2UNIX\s0 prompt symbol +which tells you that \s-2UNIX\s0 is ready to accept a command. +.bd I 3 +.SH +Asking for \fIedit\fP +.fl +.bd I +.PP +You are ready to tell \s-2UNIX\s0 that you +want to work with edit, the text editor. +Now is a convenient time to choose +a name for the file of text you are about to create. +To begin your editing session, +type +.B edit +followed by a space and then the filename +you have selected; for example, ``text''. +After that, +press the \s-2RETURN\s0 key and wait for edit's response: +.DS I 1i +% \fBedit text\fP \fI(followed by a \s-2RETURN\s+2)\fR +"text" No such file or directory +: +.DE +If you typed the command correctly, +you will now be in communication with edit. +Edit has set aside a buffer for use as +a temporary working space during your current editing session. +Since ``text'' is a new file we are about to create +the editor was unable to find that file, which it +confirms by saying: +.DS I 1i +"text" No such file or directory +.DE +On the next line appears edit's prompt ``:'', +announcing that you are in \f2command mode\f1 and +edit expects a command from you. +You may now begin to create the new file. +.SH +The ``Command not found'' message +.PP +If you misspelled edit by typing, say, ``editor'', +this might appear: +.DS I 1i +% \fBeditor\fP +editor: Command not found +% +.DE +Your mistake in calling edit ``editor'' was +treated by \s-2UNIX\s0 as a request +for a program named ``editor''. +Since there is no program +named ``editor'', +\s-2UNIX\s0 reported that the program was ``not found''. +A new % indicates that \s-2UNIX\s0 is ready for another command, +and you may then enter the correct command. +.SH +A summary +.PP +Your exchange with \s-2UNIX\s0 as you logged in and made contact with edit +should look something like this: +.DS I 1i +login: \fBsusan\fP +Password: +\&... A Message of General Interest ... +% \fBedit text\fP +"text" No such file or directory +: +.DE +.SH +Entering text +.PP +You may now begin entering text into the buffer. +This is done by \fIappending\fP (or adding) text to whatever +is currently in the buffer. +Since there is nothing in the buffer at the moment, +you are appending text to nothing; +in effect, +since you are adding text to nothing +you are creating text. +Most edit commands have two equivalent forms: +a word that suggests what the command does, +and a shorter abbreviation of that word. +Many beginners find the full command names +easier to remember at first, +but once you are familiar with editing you may +prefer to type the shorter abbreviations. +The command to input text is ``append''. +(It may be abbreviated ``a''.) +Type +.B append +and press the \s-2RETURN\s0 key. +.DS I 1i +% \fBedit text +\fR:\|\fBappend +.R +.DE +.SH +.bd I 3 +Messages from +.I edit +.fl +.bd I +.PP +If you make a mistake in entering a command and +type something that edit does not recognize, +edit will respond with a message +intended to help you diagnose your error. +For example, if you misspell the command to input text by typing, +perhaps, ``add'' instead of ``append'' or ``a'', +you will receive this message: +.DS I 1i +:\|\fBadd\fR +add: Not an editor command +: +.DE +When you receive a diagnostic message, +check what you typed in order to determine what +part of your command confused edit. +The message above means that edit +was unable to recognize your mistyped command +and, therefore, did not execute it. +Instead, a new ``:'' +appeared to let you know that +edit is again ready to execute a command. +.SH +Text input mode +.PP +By giving the command ``append'' (or using the abbreviation ``a''), +you entered +.I +text input mode, +.R +also known as +.I +append mode. +.R +When you enter text input mode, +edit stops sending you a prompt. +You will not receive any prompts +or error messages +while in text input mode. +You can enter +pretty much anything you want on the lines. +The lines are transmitted one by one to the buffer +and held there during the editing session. +You may append as much text as you want, and +.I +when you wish to stop entering text lines you should +type a period as the only character on the line +and press the \s-2RETURN\s0 key. +.R +When you type the period and press \s-2RETURN\s0, +you signal that you want to stop appending text, +and edit responds by allowing +you to exit text input mode and reenter command mode. +Edit will again +prompt you for a command by printing ``:''. +.PP +Leaving append mode does not destroy the text in +the buffer. +You have to leave append +mode to do any of the other kinds of editing, +such as changing, adding, or printing text. +If you type a period as the first character and +type any other character on the same line, +edit will believe you want to remain in append mode +and will not let you out. +As this can be very frustrating, +be sure to type +.B only +the period and the \s-2RETURN\s0 key. +.PP +This is a good place to learn an important +lesson about computers and text: a blank space is +a character as far as a computer is concerned. +If you so much as type a period followed by a blank +(that is, type a period and then the space bar on the keyboard), +you will remain in append mode with the last line of text +being: +.DS I 1i +.B +.ps +2 +\&. +.ps -2 +.R +.DE +Let's say that you enter the lines +(try to type +.B exactly +what you see, including ``thiss''): +.DS I 1i +.B +This is some sample text. +And thiss is some more text. +Text editing is strange, but nice. +\&. +.R +.DE +The last line is the period followed by a \s-2RETURN\s0 +that gets you out of append mode. +.SH +Making corrections +.PP +If you have read a general introduction to \s-2UNIX\s0, +you will recall that it is possible to erase individual +letters that you have typed. +This is done by typing the designated erase character +as many times as there are characters +you want to erase. +.PP +The usual erase character varies from place to place and +user to user. Often it +is the backspace (control-H), +so you can correct typing errors +in the line you are typing +by holding down the \s-1CTRL\s+1 key +and typing the ``H'' key. (Sometimes it is the DEL key.) +If you type the erase character +you will notice +that the terminal backspaces in the line you are on. +You can backspace over your error, +and then type what you want to be the rest of the line. +.PP +If you make a bad start +in a line +and would like to begin again, +you can either backspace to the beginning of the line +or you can use the at-sign ``@'' to erase everything on the line: +.DS I 1i +.B +Text edtiing is strange, but@ +Text editing is strange, but nice. +.R +.fl +.bd S +.DE +When you type the at-sign (@), you erase +the entire line typed so far +and are given a fresh line to type on. +You may immediately begin to retype the line. +This, unfortunately, does not work after you type the +line and press \s-2RETURN\s+2. +To make corrections in lines that have been completed, +it is necessary to use the editing commands +covered in the next sessions. +.SH +Writing text to disk +.PP +You are now ready to edit the text. One common operation +is to write the text to disk as a file for safekeeping +after the session is over. +This is the only way to save information from one session to the next, +since the editor's buffer is temporary and will last only until the +end of the editing session. +Learning how to write a file to disk is second in +importance only to entering the text. +To write the contents of the buffer to a disk +file, use the command ``write'' +(or its abbreviation ``w''): +.DS I 1i +:\|\fBwrite +.R +.DE +Edit will copy the contents of the buffer to a disk file. +If the file does not yet exist, +a new file will be created automatically +and the presence of a ``[New file]'' will be noted. +The newly-created file will be given the name specified when +you entered the editor, in this case ``text''. +To confirm that the disk file has been successfully written, +edit will repeat the filename and give +the number of lines and the total +number of characters in the file. +The buffer remains unchanged by the ``write'' command. +All of the lines that were written to disk will still be +in the buffer, +should you want to modify or add to them. +.PP +Edit must have a name for the file to be written. +If you forgot to indicate the name of the file +when you began to edit, +edit will print in response to your write command: +.DS I 1i +No current filename +.DE +If this happens, you can specify the filename in a new write command: +.DS I 1i +:\|\fBwrite text +.R +.DE +After the ``write'' (or ``w''), type a space and then the name of the file. +.SH +Signing off +.PP +We have done enough for this first lesson on using the +\s-2UNIX\s0 text editor, and are ready to quit the session with edit. +To do this we type ``quit'' (or ``q'') and press \s-2RETURN\s+2: +.DS I 1i +:\|\fBwrite +.R +"text" [New file] 3 lines, 90 characters +:\|\fBquit\fR +% +.DE +The % is from \s-2UNIX\s0 to tell you that your session with edit is +over and you may command \s-2UNIX\s0 further. +Since we want +to end the entire session at the terminal, we also need to +exit from \s-2UNIX\s0. +In response to the \s-2UNIX\s0 prompt of ``\|%\|'' +type the command +.DS I 1i +%\|\fBlogout\fR +.DE +This will end your session with \s-2UNIX\s0, and will ready the +terminal for the next user. +It is always important to type \fBlogout\fR at the end of a session +to make absolutely sure no one +could accidentally stumble into your abandoned +session and thus gain access to your files, +tempting even the most honest of souls. +.sp 1 +.PP +This is the end of the first session on \s-2UNIX\s0 text editing. +.bp +.TL +Session 2 +.sp +.PP +Login with \s-2UNIX\s0 as in the first session: +.DS I 1i +login: \fBsusan\fP \fI(carriage return)\fR +Password: \fI(give password and carriage return)\fR +.if t .sp .2v +.if n .sp 1 +\&... A Message of General Interest ... +% +.DE +When you indicate you want to edit, +you can specify the name of the file you worked on last time. +This will +start edit working, and it will fetch the contents of the +file into the buffer, so that you can resume editing the same file. +When edit has copied the file into the buffer, it +will repeat its name and tell +you the number of lines and characters it contains. +Thus, +.DS I 1i +.B +% edit text +.R +"text" 3 lines, 90 characters +: +.DE +means you asked edit to fetch +the file named ``text'' for editing, +causing it to copy the +90 characters of text into the buffer. +Edit awaits +your further instructions, +and indicates this by its prompt character, the colon (:). +In this session, we will append more text to our file, +print the contents of the buffer, and learn to change the text of a line. +.SH +Adding more text to the file +.PP +If you want to add more to the end of your +text you may do so by using the append command to enter text input mode. +When ``append'' is the first command +of your editing session, +the lines you enter +are placed at the end of the buffer. +Here we'll use the abbreviation for the append command, ``a'': +.DS I 1i +:\|\fBa +This is text added in Session 2. +It doesn't mean much here, but +it does illustrate the editor. +\|\fB\s+2\&.\s-2 +.R +.DE +You may recall that once you enter append mode +using the ``a'' (or ``append'') command, +you need to type a line containing only a period (.) +to exit append mode. +.SH +Interrupt +.PP +Should you press the \s-2RUB\s+2 key (sometimes labelled \s-2DELETE\s+2) +while working with edit, +it will send this message to you: +.DS I 1i +Interrupt +: +.DE +Any command that edit might be executing +is terminated by rub or delete, +causing edit to prompt you for a new command. +If you are appending text at the time, +you will exit from append mode +and be expected to give another command. +The line of text you were typing +when the append command was interrupted +will not be entered into the buffer. +.SH +Making corrections +.PP +If while typing the line you hit an incorrect key, +recall that +you may delete the incorrect character +or cancel the entire line of input by erasing in the usual way. +Refer either +to the last few pages of Session 1 +if you need to review +the procedures for making a correction. +The most important idea to remember is that +erasing a character or cancelling a line must be done +before you press the \s-2RETURN\s+2 key. +.SH +Listing what's in the buffer (p) +.PP +Having appended text to what you wrote in Session 1, +you might want to see all the lines in the buffer. +To print the contents of the buffer, type the command: +.DS I 1i +:\|\fB1,$p +.R +.DE +The ``1''\(dg +.FS +\(dgThe numeral ``one'' is the top left-most key, +and should not be confused with the letter ``el''. +.FE +stands for line 1 of the buffer, +the ``$'' is a special symbol designating the last line +of the buffer, +and ``p'' (or \fBprint\fR) is the command to print from line 1 +to the end of the buffer. +The command ``1,$p'' gives you: +.DS I 1i +This is some sample text. +And thiss is some more text. +Text editing is strange, but nice. +This is text added in Session 2. +It doesn't mean much here, but +it does illustrate the editor. +.DE +Occasionally, you may accidentally +type a character that can't be printed, +which can be done by striking a key +while the \s-2CTRL\s0 key is pressed. +In printing lines, edit uses a special notation to +show the existence of non-printing characters. +Suppose you had introduced the non-printing character ``control-A'' +into the word ``illustrate'' +by accidently pressing the \s-2CTRL\s0 key while +typing ``a''. +This can happen on many terminals +because the \s-2CTRL\s+2 key and the ``A'' key +are beside each other. +If your finger presses between the two keys, +control-A results. +When asked to print the contents of the buffer, +edit would display +.DS I 1i +it does illustr^Ate the editor. +.DE +To represent the control-A, edit shows ``^A''. +The sequence ``^'' followed by a capital +letter stands for the one character +entered by holding down the \s-2CTRL\s0 key and typing the letter +which appears after the ``^''. +We'll soon discuss the commands that can be used +to correct this typing error. +.PP +In looking over the text we see that +``this'' is typed as ``thiss'' in the second line, +a deliberate error so we can learn to make corrections. +Let's correct the spelling. +.SH +Finding things in the buffer +.PP +In order to change something in the buffer we first need to +find it. +We can find ``thiss'' in the text we have +entered by looking at a listing +of the lines. +Physically speaking, we search the lines +of text looking for ``thiss'' and stop searching when +we have found it. +The way to tell edit to search for something +is to type it inside slash marks: +.DS I 1i +:\|\fB/thiss/ +.R +.DE +By typing +.B /thiss/ +and pressing \s-1RETURN\s0, +you instruct edit to search for ``thiss''. +If you ask edit to look for a pattern of characters +which it cannot find in the buffer, +it will respond ``Pattern not found''. +When edit finds +the characters ``thiss'', it will print the line of text +for your inspection: +.DS I 1i +And thiss is some more text. +.DE +Edit is now positioned in the buffer at the +line it just printed, +ready to make a change in the line. +.bp +.SH +The current line +.PP +Edit keeps track of the line in the buffer where it is located +at all times during an editing session. +In general, the line that has been most recently +printed, entered, or changed +is the current location in the buffer. +The editor is prepared to make changes +at the current location in the buffer, +unless you direct it to another location. +.PP +In particular, +when you bring a file into the buffer, +you will be located at the last line in the file, +where the editor left off copying the lines +from the file to the buffer. +If your first editing command is ``append'', +the lines you enter are added +to the end of the file, +after the current line \(em +the last line in the file. +.PP +You can refer to your current location in the buffer by the +symbol +period (.) usually known by the name ``dot''. +If you type ``.'' and carriage +return you will be instructing edit to print the current line: +.DS I 1i +:\|\fB\s+2\&.\s-2 +.R +And thiss is some more text. +.DE +.PP +If you want to know the number of the current line, +you can type +.B \&.= +and press \s-2RETURN\s+2, +and edit will respond with the line number: +.DS I 1i +:\|\fB\s+2.\s-2= +.R +2 +.DE +If you type the number of any line and press \s-2RETURN\s+2, +edit will position you at that line and +print its contents: +.DS I 1i +:\|\fB2 +.R +And thiss is some more text. +.DE +You should experiment with these commands +to gain experience in using them to make changes. +.SH +Numbering lines (nu) +.PP +The +.B +number (nu) +.R +command is similar to print, +giving both the number and the text of each printed line. +To see the number and the text of the current line type +.DS I 1i +:\|\fBnu +.R +\0\0\0\0\02\0\0And thiss is some more text. +.DE +Note that the shortest abbreviation for the number command is +``nu'' (and not ``n'', which is used for a different command). +You may specify a range of lines +to be listed by the number command in the same way that lines +are specified for print. +For example, \f31,$nu\f1 lists all lines in the buffer with their +corresponding line numbers. +.SH +Substitute command (s) +.PP +Now that you have found the misspelled word, +you can change it from ``thiss'' to ``this''. +As far as edit is concerned, +changing things is a matter of +substituting one thing for another. +As +.I a +stood for +.I append, +so +.I s +stands for +.I substitute. +We will use the abbreviation ``s'' to reduce the chance +of mistyping the substitute command. +This command will instruct edit to make the change: +.DS I 1i +\f32s/thiss/this/\f1 +.DE +We first indicate the line to be changed, line 2, +and then +type an ``s'' to indicate we want +edit to make a substitution. +Inside the first set of slashes +are the characters that we want to change, +followed by the characters to replace them, +and then a closing slash mark. +To summarize: +.DS I 1i +2s/ \fIwhat is to be changed\fR / \fIwhat to change it to \fR/ +.DE +If edit finds an exact match of the characters to be +changed it will make the change +.B only +in the first occurrence of the characters. +If it does not find the characters +to be changed, it will respond: +.DS I 1i +Substitute pattern match failed +.DE +indicating that your instructions could not be carried out. +When edit does find the characters that you want to change, +it will make the substitution and automatically print +the changed line, so that you can check that the correct substitution +was made. +In the example, +.DS I 1i +:\|\fB2s/thiss/this/ +.R +And this is some more text. +.DE +line 2 (and line 2 only) will be searched for the characters +``thiss'', and when the first exact match is found, ``thiss'' +will be changed to ``this''. +Strictly speaking, it was not necessary above to +specify the number of the line to be changed. +In +.DS I 1i +:\|\fBs/thiss/this/ +.R +.DE +edit will assume that we mean to change +the line where we are currently located (``.''). +In this case, +the command without a line number would have produced the same result +because we were already located +at the line we wished to change. +.PP +For another illustration of the substitute command, +let us choose the line: +.DS I 1i +Text editing is strange, but nice. +.DE +You can make this line a bit more positive +by taking out the characters ``strange, but\ '' so the line +reads: +.DS I 1i +Text editing is nice. +.DE +A command that will first position edit at the desired line +and then make the substitution is: +.DS I 1i +:\|\fB/strange/s/strange, but // +.R +.DE +.LP +What we have done here is combine our search with +our substitution. +Such combinations are perfectly legal, +and speed up editing quite a bit +once you get used to them. +That is, you do not necessarily have to use +line numbers to identify a line to edit. +Instead, you may identify the line you want to change +by asking edit to search for a specified pattern of letters +that occurs in that line. +The parts of the above command are: +.in +1i +.TS +l l. +\fB/strange/\fP tells edit to find the characters ``strange'' in the text +\fBs\fP tells edit to make a substitution +\fB/strange, but //\fP substitutes nothing at all for the characters ``strange, but '' +.TE +.in -1i +.PP +You should note the space after ``but'' in ``/strange, but /''. +If you do not indicate that the space is to be taken out, +your line will read: +.DS I 1i +.if t Text editing is nice. +.if n Text editing is nice. +.DE +which looks a little funny +because of the extra space between ``is'' and ``nice''. +Again, we realize from this that a blank space +is a real character to a computer, and in editing text +we need to be aware of spaces +within a line just as we would be aware of an ``a'' or +a ``4''. +.SH +Another way to list what's in the buffer (z) +.PP +Although the print command is useful for looking at specific lines +in the buffer, +other commands may be more convenient for +viewing large sections of text. +You can ask to see a screen full of text at a time +by using the command +.B z. +If you type +.DS I 1i +:\|\fB1z +.R +.DE +edit will start with line 1 and continue printing lines, +stopping either when the screen of +your terminal is full +or when the last line in the buffer has been printed. +If you want to read the next segment of text, type the command +.DS I 1i +:\|\fBz +.DE +If no starting line number is given for the z command, +printing will start at the ``current'' line, in this case the +last line printed. +Viewing lines in the buffer one screen full at a time +is known as \fIpaging\fR. +Paging can also be used to print +a section of text on a hard-copy terminal. +.SH +Saving the modified text +.PP +This seems to be a good place to pause in our work, +and so we should end the second session. +If you (in haste) type ``q'' to quit the session +your dialogue with edit will be: +.DS I 1i +:\|\fBq +.R +No write since last change (:quit! overrides) +: +.DE +This is edit's warning that you have not written +the modified contents of the buffer to disk. +You run the risk of losing the work you did +during the editing session since you typed the latest write +command. +Because in this lesson we have not written +to disk at all, everything we have done +would have been lost +if edit had obeyed the \fBq\fR command. +If you did not want to save the work done during +this editing session, you would have to type ``q!'' +or (``quit!'') +to confirm that you indeed wanted to end the session +immediately, +leaving the file as it was +after the most recent ``write'' command. +However, +since you want to save what +you have edited, you need to type: +.DS I 1i +:\|\fBw +.R +"text" 6 lines, 171 characters +.DE +and then follow with the commands to quit and logout: +.DS I 1i +:\|\fBq +% \fBlogout\fR +.DE +and hang up the phone or turn off the terminal when +\s-2UNIX\s0 asks for a name. +Terminals connected to the port selector +will stop after the logout command, +and pressing keys on the keyboard will do nothing. +.sp 1 +.PP +This is the end of the second session on \s-2UNIX\s0 text editing. +.bp +.TL +Session 3 +.SH +Bringing text into the buffer (e) +.PP +Login to \s-2UNIX\s0 and make contact with edit. +You should try to login without +looking at the notes, but if you must +then by all means do. +.PP +Did you remember to give the name of the file +you wanted to edit? +That is, did you type +.DS I 1i +% \fBedit text\fR +.DE +or simply +.DS I 1i +% \fBedit\fR +.DE +Both ways get you in contact with edit, but the first way +will bring a copy of the file named ``text'' into +the buffer. +If you did forget to tell edit the name of your file, +you can get it into the buffer by +typing: +.DS I 1i +:\|\fBe text +.R +"text" 6 lines, 171 characters +.DE +The command +.B edit, +which may be abbreviated \fBe\fR, +tells edit that you want +to erase anything that might already be in +the buffer and bring a copy of the file ``text'' into the buffer +for editing. +You may also use the edit (e) command to change files in +the middle of an editing session, +or to give edit the name of a new file that you want to create. +Because the edit command clears the buffer, +you will receive a warning if you try to edit a new file without +having saved a copy of the old file. +This gives you a chance to write the contents of the buffer to disk +before editing the next file. +.SH +Moving text in the buffer (m) +.PP +Edit allows you to move lines of text +from one location in the buffer to another +by means of the +.B move +(\fBm\fR) command. +The first two examples are for illustration only, +though after you have read this Session +you are welcome to return to them for practice. +The command +.DS I 1i +:\|\fB2,4m$ +.R +.DE +directs edit to move lines 2, 3, and 4 +to the end of the buffer ($). +The format for the move command is that you specify +the first line to be moved, the last line to be moved, +the move command ``m'', and the line after which +the moved text is to be placed. +So, +.DS I 1i +:\|\fB1,3m6 +.R +.DE +would instruct edit to move lines 1 through 3 (inclusive) +to a location after line 6 in the buffer. +To move only one line, say, line 4, +to a location in the buffer after line 5, +the command would be ``4m5''. +.PP +Let's move some text using the command: +.DS I 1i +:\|\fB5,$m1 +.R +2 lines moved +it does illustrate the editor. +.DE +After executing a command that moves more than one line of the buffer, +edit tells how many lines were affected by the move +and prints the last moved line for your inspection. +If you want to see more than just the last line, +you can then +use the print (p), z, or number (nu) command to view more text. +The buffer should now contain: +.DS I 1i +This is some sample text. +It doesn't mean much here, but +it does illustrate the editor. +And this is some more text. +Text editing is nice. +This is text added in Session 2. +.DE +You can restore the original order by typing: +.DS I 1i +:\|\fB4,$m1 +.R +.DE +or, combining context searching and the move command: +.DS I 1i +:\|\fB/And this is some/,/This is text/m/This is some sample/ +.R +.DE +(Do not type both examples here!) +The problem with combining context searching +with the move command +is that your chance of making a typing error +in such a long command is greater than +if you type line numbers. +.SH +Copying lines (copy) +.PP +The +.B copy +command +is used to make a second copy of specified lines, +leaving the original lines where they were. +Copy +has the same format as the move command, for example: +.DS I 1i +:\|\fB2,5copy $ +.R +.DE +makes a copy of lines 2 through 5, +placing the added lines after the buffer's end ($). +Experiment with the copy command +so that you can become familiar with how it works. +Note that the shortest abbreviation for copy is +\f3co\f1 (and +not the letter ``c'', which has another meaning). +.SH +Deleting lines (d) +.PP +Suppose you want to delete +the line +.DS I 1i +This is text added in Session 2. +.DE +from the buffer. +If you know the number of the line to be deleted, +you can type +that number followed by +\fBdelete\fR or \fBd\fR. +This example deletes line 4, +which is ``This is text added in Session 2.'' +if you typed the commands +suggested so far. +.DS I 1i +:\|\fB4d +.R +It doesn't mean much here, but +.DE +Here ``4'' is the number of the line to be deleted, +and ``delete'' or ``d'' is the command to delete the line. +After executing the delete command, +edit prints the line that has become the current line (``.''). +.PP +If you do not happen to know the line number +you can search for the line and then delete it using this +sequence of commands: +.DS I 1i +:\|\fB/added in Session 2./ +.R +This is text added in Session 2. +:\|\fBd +.R +It doesn't mean much here, but +.DE +The ``/added in Session 2./'' +asks edit to locate and print +the line containing the indicated text, +starting its search at the current line +and moving line by line +until it finds the text. +Once you are sure that you have correctly specified the line +you want to delete, +you can enter the delete (d) command. +In this case it is not necessary to +specify a line number before the ``d''. +If no line number is given, +edit deletes the current line (``.''), +that is, the line found by our search. +After the deletion, your buffer should contain: +.DS I 1i +This is some sample text. +And this is some more text. +Text editing is nice. +It doesn't mean much here, but +it does illustrate the editor. +And this is some more text. +Text editing is nice. +This is text added in Session 2. +It doesn't mean much here, but +.DE +To delete both lines 2 and 3: +.DS I 1i +And this is some more text. +Text editing is nice. +.DE +you type +.DS I 1i +:\|\f32,3d\f1 +2 lines deleted +.DE +which specifies the range of lines from 2 to 3, +and the operation on those lines \(em ``d'' for delete. +If you delete more than one line +you will receive a message +telling you the number of lines deleted, +as indicated in the example above. +.PP +The previous example assumes that you know the line numbers for +the lines to be deleted. +If you do not you might combine the search command +with the delete command: +.DS I 1i +:\|\fB/And this is some/,/Text editing is nice./d +.R +.DE +.SH +A word or two of caution +.PP +In using the search function to locate lines to +be deleted you should be +.B +absolutely sure +.R +the characters you give as the basis for the search +will take edit to the line you want deleted. +Edit will search for the first +occurrence of the characters starting from where +you last edited \- +that is, from the line you see printed if you type dot (.). +.PP +A search based on too few +characters may result in the wrong lines being deleted, +which edit will do as easily as if you had meant it. +For this reason, it is usually safer +to specify the search and then delete in two separate steps, +at least until you become familiar enough with using the editor +that you understand how best to specify searches. +For a beginner it is not a bad idea to double-check +each command before pressing \s-2RETURN\s+2 to send the command on its way. +.SH +Undo (u) to the rescue +.PP +The +.B +undo (u) +.R +command has the ability to +reverse the effects of the last command that changed the buffer. +To undo the previous command, type +``u'' or ``undo''. +Undo can rescue +the contents of the buffer from many an unfortunate mistake. +However, its powers are not unlimited, +so it is still wise to be reasonably +careful about the commands you give. +.PP +It is possible to undo only commands which +have the power to change the buffer \(em for example, +delete, append, move, copy, substitute, and even undo itself. +The commands write (w) and edit (e), which interact with disk files, +cannot be undone, nor can commands that do not change +the buffer, such as print. +Most importantly, +the +.B only +command that can be reversed by undo +is the +last ``undo-able'' command you typed. +You can use control-H and @ to change +commands while you are typing them, +and undo to reverse the effect of the commands +after you have typed them and pressed \s-2RETURN\s+2. +.PP +To illustrate, +let's issue an undo command. +Recall that the last buffer-changing command we gave deleted +the lines formerly numbered 2 and 3. +Typing undo at this moment will reverse the effects +of the deletion, causing those two lines to be +replaced in the buffer. +.DS I 1i +:\|\fBu +.R +2 more lines in file after undo +And this is some more text. +.DE +Here again, edit informs you if the command affects more +than one line, +and prints +the text of the line which is now ``dot'' (the current line). +.SH +More about the dot (.) and buffer end ($) +.PP +The function assumed by the symbol dot depends on its context. +It can be used: +.IP +1. to exit from append mode; we type dot (and only a dot) on +a line and press \s-2RETURN\s+2; +.IP +2. to refer to the line we are at in the buffer. +.LP +Dot can also be combined with the equal sign to get +the number of the line currently being edited: +.DS I 1i +:\|\fB\&.= +.R +.DE +If we type ``\fB.\fR='' we are asking for the number of the line, +and if we type ``\fB.\fR'' we are asking for the text of the line. +.PP +In this editing session and the last, we used the dollar +sign to indicate the end of the buffer +in commands such as print, copy, and move. +The dollar sign as a command asks edit to print the last +line in the buffer. +If the dollar sign is combined with the equal sign (\f3$=\f1) +edit will print the line number corresponding to the +last line in the buffer. +.PP +``\fB.\fR'' and ``$'', then, represent line numbers. +Whenever appropriate, these symbols can be used in +place of line numbers in commands. +For example +.DS I 1i +:\|\fB\s+2.\s-2,$d +.R +.DE +instructs edit to delete all lines from the current line (\fB.\fR) +to the end of the buffer. +.SH +Moving around in the buffer (+ and \-) +.PP +When you are editing +you often want +to go back and re-read a previous line. +You could specify a context search for a line you want to +read if you remember some of its text, +but if you simply want to see what was written a few, say 3, lines +ago, you can type +.DS I 1i +\-3p +.DE +This tells edit to move back to a position 3 lines +before the current line (.) +and print that line. +You can move forward in the buffer similarly: +.DS I 1i ++2p +.DE +instructs edit to print the line that is 2 +ahead of your current position. +.PP +You may use ``+'' and ``\-'' in any command where edit +accepts line numbers. +Line numbers specified with ``+'' or ``\-'' +can be combined to print a range of lines. +The command +.DS I 1i +:\|\fB\-1,+2copy$ +.R +.DE +makes a copy of 4 lines: the current line, the line before it, +and the two after it. +The copied lines will be placed after the last line +in the buffer ($), +and the original lines referred to by ``\-1'' and ``+2'' +remain where they are. +.PP +Try typing only ``\-''; you will move back one line just as +if you had typed ``\-1p''. +Typing the command ``+'' works similarly. +You might also try typing a few plus or minus signs in a row +(such as ``+++'') to see edit's response. +Typing \s-2RETURN\s+2 alone on a line is the equivalent +of typing ``+1p''; it will move you one line ahead in the buffer +and print that line. +.PP +If you are at the last line of the buffer and try +to move further ahead, perhaps by typing a ``+'' or +a carriage return alone on the line, +edit will remind you that you are at the end of the buffer: +.sp +.nf +.ti 1i +At end-of-file +.br +or +.ti 1i +Not that many lines in buffer +.fi +.LP +Similarly, if you try to move to a position before the first line, +edit will print one of these messages: +.sp +.nf +.ti 1i +Nonzero address required on this command +.br +or +.ti 1i +Negative address \- first buffer line is 1 +.fi +.LP +The number associated with a buffer line is the line's ``address'', +in that it can be used to locate the line. +.SH +Changing lines (c) +.PP +You can also delete certain lines and +insert new text in their place. +This can be accomplished easily with the +.B "change (c)" +command. +The change command instructs edit to delete specified lines +and then switch to text input mode to +accept the text that will replace them. +Let's say you want to change the first two lines in the buffer: +.DS I 1i +This is some sample text. +And this is some more text. +.DE +to read +.DS I 1i +This text was created with the \s-2UNIX\s0 text editor. +.DE +To do so, you type: +.DS I 1i +:\|\fB1,2c +.R +2 lines changed +.B +This text was created with the \s-2UNIX\s0 text editor. +\s+2\&.\s-2 +.R +: +.DE +In the command +.B 1,2c +we specify that we want to change +the range of lines beginning with 1 and ending with 2 +by giving line numbers as with the print command. +These lines will be deleted. +After you type \s-2RETURN\s+2 to end the change command, +edit notifies you if more than one line will be changed +and places you in text input mode. +Any text typed on the following lines will be inserted into +the position where lines were deleted by the change command. +.B +You will remain in text input mode until you exit in the usual way, +by typing a period alone on a line. +.R +Note that the number of lines added to the buffer need not be +the same as the number of lines deleted. +.sp 1 +.PP +This is the end of the third session on text editing with \s-2UNIX\s0. +.bp +.SH +.ce 1 +\s+2Session 4\s0 +.sp +.PP +This lesson covers several topics, starting with +commands that apply throughout the buffer, +characters with special meanings, +and how to issue \s-2UNIX\s0 commands while in the editor. +The next topics deal with files: +more on reading and writing, +and methods of recovering files lost in a crash. +The final section suggests sources of further information. +.SH +Making commands global (g) +.PP +One disadvantage to the commands we have used for +searching or substituting is that if you +have a number of instances of a word to change +it appears that you have to type the command +repeatedly, once for +each time the change needs to be made. +Edit, however, provides a way to make commands +apply to the entire contents of the buffer \- +the +.B +global (g) +.R +command. +.PP +To print all lines +containing a certain sequence of characters +(say, ``text'') +the command is: +.DS I 1i +:\|\fBg/text/p +.R +.DE +The ``g'' instructs edit to +make a global search for all lines +in the buffer containing the characters ``text''. +The ``p'' prints the lines found. +.PP +To issue a global command, start by typing a ``g'' and then a search +pattern identifying +the lines to be affected. +Then, on the same line, type the command to be +executed for the identified lines. +Global substitutions are frequently useful. +For example, +to change all instances of the word ``text'' to the word ``material'' +the command would be a combination of the global search and the +substitute command: +.DS I 1i +:\|\fBg/text/s/text/material/g +.R +.DE +Note the ``g'' at the end of the global command, +which instructs edit to change +each and every instance of ``text'' to ``material''. +If you do not type the ``g'' at the end of the command +only the +.I first +instance of ``text'' \fIin each line\fR will be changed +(the normal result of the substitute command). +The ``g'' at the end of the command is independent of the ``g'' +at the beginning. +You may give a command such as: +.DS I 1i +:\|\fB5s/text/material/g +.R +.DE +to change every instance of ``text'' in line 5 alone. +Further, neither command will change ``text'' to ``material'' +if ``Text'' begins with a capital rather than a lower-case +.I t. +.PP +Edit does not automatically print the lines modified by a +global command. +If you want the lines to be printed, type a ``p'' +at the end of the global command: +.DS I 1i +:\|\fBg/text/s/text/material/gp +.R +.DE +You should be careful +about using the global command in combination with any other \- +in essence, be sure of what you are telling edit to do +to the entire buffer. +For example, +.DS I 1i +:\|\fBg/ /d +.R +72 less lines in file after global +.DE +will delete every line containing a blank anywhere in it. +This could adversely affect +your document, since most lines have spaces between words +and thus would be deleted. +After executing the global command, +edit will print a warning if the command added or deleted more than one line. +Fortunately, the undo command can reverse +the effects of a global command. +You should experiment with the global command +on a small file of text to see what it can do for you. +.SH +More about searching and substituting +.PP +In using slashes to identify a character string +that we want to search for or change, +we have always specified the exact characters. +There is a less tedious way to +repeat the same string of characters. +To change ``text'' to ``texts'' we may type either +.DS I 1i +:\|\fB/text/s/text/texts/ +.R +.DE +as we have done in the past, +or a somewhat abbreviated command: +.DS I 1i +:\|\fB/text/s//texts/ +.R +.DE +In this example, the characters to be changed +are not specified \- +there are no characters, not even a space, +between the two slash marks +that indicate what is to be changed. +This lack of characters between the slashes +is taken by the editor to mean +``use the characters we last searched for as the characters to be changed.'' +.PP +Similarly, the last context search may be repeated +by typing a pair of slashes with nothing between them: +.DS I 1i +:\|\fB/does/ +.R +It doesn't mean much here, but +:\|\fB// +.R +it does illustrate the editor. +.DE +(You should note that the search command found the characters ``does'' +in the word ``doesn't'' in the first search request.) +Because no characters are specified for the second search, +the editor scans the buffer for the next occurrence of the +characters ``does''. +.PP +Edit normally searches forward through the buffer, +wrapping around from the end of the buffer to the beginning, +until the specified character string is found. +If you want to search in the reverse direction, +use question marks (?) instead of slashes +to surround the characters you are searching for. +.PP +It is also possible +to repeat the last substitution +without having to retype the entire command. +An ampersand (&) used as a command +repeats the most recent substitute command, +using the same search and replacement patterns. +After altering the current line by typing +.DS I 1i +:\|\fBs/text/texts/ +.R +.DE +you type +.DS I 1i +:\|\fB/text/& +.R +.DE +or simply +.DS I 1i +:\|\fB//& +.R +.DE +to make the same change on the next line in the buffer +containing the characters ``text''. +.SH +Special characters +.PP +Two characters have special meanings when +used in specifying searches: ``$'' and ``^''. +``$'' is taken by the editor to mean ``end of the line'' +and is used to identify strings +that occur at the end of a line. +.DS I 1i +:\|\fBg/text.$/s//material./p +.R +.DE +tells the editor to search for all lines ending in ``text.'' +(and nothing else, not even a blank space), +to change each final ``text.'' to ``material.'', +and print the changed lines. +.PP +The symbol ``^'' indicates the beginning of a line. +Thus, +.DS I 1i +:\|\fBs/^/1. / +.R +.DE +instructs the editor to insert ``1.'' and a space at the beginning +of the current line. +.PP +The characters ``$'' and ``^'' have special meanings only in the context +of searching. +At other times, they are ordinary characters. +If you ever need to search for a character that has a special meaning, +you must indicate that the +character is to lose temporarily +its special significance by typing another special character, +the backslash (\\), before it. +.DS I 1i +:\|\fBs/\\\\\&$/dollar/ +.R +.DE +looks for the character ``$'' in the current +line and replaces it by the word ``dollar''. +Were it not for the backslash, the ``$'' would have represented +``the end of the line'' in your search +rather than the character ``$''. +The backslash retains its special significance +unless it is preceded by another backslash. +.SH +Issuing \s-2UNIX\s0 commands from the editor +.PP +After creating several files with the editor, +you may want to delete files +no longer useful to you or ask for a list of your files. +Removing and listing files are not functions of the editor, +and so they require the use of \s-2UNIX\s0 system commands +(also referred to as ``shell'' commands, as +``shell'' is the name of the program that processes \s-2UNIX\s0 commands). +You do not need to quit the editor to execute a \s-2UNIX\s0 command +as long as you indicate that it +is to be sent to the shell for execution. +To use the \s-2UNIX\s0 command +.B rm +to remove the file named ``junk'' type: +.DS I 1i +:\|\fB!rm junk +.R +! +: +.DE +The exclamation mark (!) +indicates that the rest of the line is to be processed as a shell command. +If the buffer contents have not been written since the last change, +a warning will be printed before the command is executed: +.DS I 1i +[No write since last change] +.DE +The editor prints a ``!'' when the command is completed. +Other tutorials describe useful features of the system, +of which an editor is only one part. +.SH +Filenames and file manipulation +.PP +Throughout each editing session, +edit keeps track of the name of the file being edited as the +.I "current filename." +Edit remembers as the current filename the name given +when you entered the editor. +The current filename changes whenever the edit (e) command +is used to specify a new file. +Once edit has recorded a current filename, +it inserts that name into any command where a filename has been omitted. +If a write command does not specify a file, +edit, as we have seen, supplies the current filename. +If you are editing a file named ``draft3'' having 283 lines in it, +you can have the editor write onto a different file +by including its name in the write command: +.DS I 1i +:\fB\|w chapter3 +.R +"chapter3" [new file] 283 lines, 8698 characters +.DE +The current filename remembered by the editor +.I +will not be changed as a result of the write command. +.R +Thus, if the next write command +does not specify a name, +edit will write onto the current file (``draft3'') +and not onto the file ``chapter3''. +.SH +The file (f) command +.PP +To ask for the current filename, type +.B file +(or +.B f ). +In response, the editor provides current information about the buffer, +including the filename, your current position, the number of +lines in the buffer, +and the percent of the distance through the file +your current location is. +.DS I 1i +:\|\fBf +.R +"text" [Modified] line 3 of 4 --75%-- +.DE +.\"The expression ``[Edited]'' indicates that the buffer contains +.\"either the editor's copy of the existing file ``text'' +.\"or a file which you are just now creating. +If the contents of the buffer have changed +since the last time the file was written, +the editor will tell you that the file has been ``[Modified]''. +After you save the changes by writing onto a disk file, +the buffer will no longer be considered modified: +.DS I 1i +:\|\fBw +.R +"text" 4 lines, 88 characters +:\|\fBf +.R +"text" line 3 of 4 --75%-- +.DE +.SH +Reading additional files (r) +.PP +The +\f3read (r)\f1 command allows you to add the contents of a file +to the buffer +at a specified location, +essentially copying new lines +between two existing lines. +To use it, specify the line after which the new text will be placed, +the \f3read (r)\f1 command, +and then the name of the file. +If you have a file named ``example'', the command +.DS I 1i +:\|\fB$r example +.R +"example" 18 lines, 473 characters +.DE +reads the file ``example'' +and adds it to the buffer after the last line. +The current filename is not changed by the read command. +.SH +Writing parts of the buffer +.PP +The +.B +write (w) +.R +command can write all or part of the buffer +to a file you specify. +We are already familiar with +writing the entire contents of the +buffer to a disk file. +To write only part of the buffer onto a file, +indicate the beginning and ending lines before the write command, +for example +.DS I 1i +:\|\fB45,$w ending +.R +.DE +Here all lines from 45 through the end of the buffer +are written onto the file named +.I ending. +The lines remain in the buffer +as part of the document you are editing, +and you may continue to edit the entire buffer. +Your original file is unaffected +by your command to write part of the buffer +to another file. +Edit still remembers whether you have saved changes to the buffer +in your original file or not. +.SH +Recovering files +.PP +Although it does not happen very often, +there are times \s-2UNIX\s+2 stops working +because of some malfunction. +This situation is known as a \fIcrash\fR. +Under most circumstances, +edit's crash recovery feature +is able to save work to within a few lines of changes +before a crash (or an accidental phone hang up). +If you lose the contents of an editing buffer in a system crash, +you will normally receive mail when you login that gives +the name of the recovered file. +To recover the file, +enter the editor and type the command +.B recover +(\fBrec\fR), +followed by the name of the lost file. +For example, +to recover the buffer for an edit session +involving the file ``chap6'', the command is: +.DS I 1i +.R +:\|\fBrecover chap6 +.R +.DE +Recover is sometimes unable to save the entire buffer successfully, +so always check the contents of the saved buffer carefully +before writing it back onto the original file. +For best results, +write the buffer to a new file temporarily +so you can examine it without risk to the original file. +Unfortunately, +you cannot use the recover command +to retrieve a file you removed +using the shell command \f3rm\f1. +.SH +Other recovery techniques +.PP +If something goes wrong when you are using the editor, +it may be possible to save your work by using the command +.B preserve +(\fBpre\fR), +which saves the buffer as if the system had crashed. +If you are writing a file and you get the message +``Quota exceeded'', you have tried to use more disk storage +than is allotted to your account. +.I +Proceed with caution +.R +because it is likely that only a part +of the editor's buffer is now present in the file you tried to write. +In this case you should use the shell escape from the editor (!) +to remove some files you don't need and try to write +the file again. +If this is not possible and you cannot find someone to help you, +enter the command +.DS I 1i +:\|\fBpreserve +.R +.DE +and wait for the reply, +.DS I 1i +File preserved. +.DE +If you do not receive this reply, +seek help immediately. +Do not simply leave the editor. +If you do, the buffer will be lost, +and you may not be able to save your file. +If the reply is ``File preserved.'' +you can leave the editor +(or logout) +to remedy the situation. +After a preserve, you can use the recover command +once the problem has been corrected, +or the \fB\-r\fR option of the edit command +if you leave the editor and want to return. +.PP +If you make an undesirable change to the buffer +and type a write command before discovering your mistake, +the modified version will replace any previous version of the file. +Should you ever lose a good version of a document in this way, +do not panic and leave the editor. +As long as you stay in the editor, +the contents of the buffer remain accessible. +Depending on the nature of the problem, +it may be possible +to restore the buffer to a more complete +state with the undo command. +After fixing the damaged buffer, you can again write the file +to disk. +.SH +Further reading and other information +.PP +Edit is an editor designed for beginning and casual users. +It is actually a version of a more powerful editor called +.I ex. +These lessons are intended to introduce you to the editor +and its more commonly-used commands. +We have not covered all of the editor's commands, +but a selection of commands +that should be sufficient to accomplish most of your editing tasks. +You can find out more about the editor in the +.I +Ex Reference Manual, +.R +which is applicable to both +.I ex +and +.I edit. +One way to become familiar with the manual is to begin by reading +the description of commands that you already know. +.bd I 3 +.SH +Using +.I ex +.fl +.bd I +.PP +As you become more experienced with using the editor, +you may still find that edit continues to meet your needs. +However, should you become interested in using +.I ex, +it is easy to switch. +To begin an editing session with +.I ex, +use the name +.B ex +in your command instead of +.B edit. +.PP +Edit commands also work in +.I ex, +but the editing environment is somewhat different. +You should be aware of a few differences +between +.I ex +and +.I edit. +In edit, only the characters ``^'', ``$'', and ``\\'' have +special meanings in searching the buffer +or indicating characters to be changed by a substitute command. +Several additional characters have special +meanings in ex, as described in the +.I +Ex Reference Manual. +.R +Another feature of the edit environment prevents users from +accidently entering two alternative modes of editing, +.I open +and +.I visual, +in which +the editor behaves quite differently from normal command mode. +If you are using ex and you encounter strange behavior, +you may have accidently entered open mode by typing ``o''. +Type the \s-2ESC\s0 key and then a ``Q'' +to get out of open or visual mode and back into +the regular editor command mode. +The document +.I +An Introduction to Display Editing with Vi\|\| +.R +provide full details of visual mode. +.bp +.SH +.ce 1 +\s+2Index\s0 +.LP +.sp 2 +.2C +.nf +addressing, \fIsee\fR line numbers +ampersand, 20 +append mode, 6-7 +append (a) command, 6, 7, 9 +``At end of file'' (message), 18 +backslash (\\), 21 +buffer, 3 +caret (^), 10, 20 +change (c) command, 18 +command mode, 5-6 +``Command not found'' (message), 6 +context search, 10-12, 19-21 +control characters (``^'' notation), 10 +control-H, 7 +copy (co) command, 15 +corrections, 7, 16 +current filename, 21 +current line (\|.\|), 11, 17 +delete (d) command, 15-16 +dial-up, 5 +disk, 3 +documentation, 3, 23 +dollar ($), 10, 11, 17, 20-21 +dot (\f3\|.\|\f1) 11, 17 +edit (text editor), 3, 5, 23 +edit (e) command, 5, 9, 14 +editing commands: +.in +.25i +append (a), 6, 7, 9 +change (c), 18 +copy (co), 15 +delete (d), 15-16 +edit (text editor), 3, 5, 23 +edit (e), 5, 9, 14 +file (f), 21-22 +global (g), 19 +move (m), 14-15 +number (nu), 11 +preserve (pre), 22-23 +print (p), 10 +quit (q), 8, 13 +read (r), 22 +recover (rec), 22, 23 +substitute (s), 11-12, 19, 20 +undo (u), 16-17, 23 +write (w), 8, 13, 21, 22 +z, 12-13 +! (shell escape), 21 +$=, 17 ++, 17 +\-, 17 +//, 12, 20 +??, 20 +\&., 11, 17 +\&.=, 11, 17 +.in -.25i +entering text, 3, 6-7 +erasing +.in +.25i +characters (^H), 7 +lines (@), 7 +.in -.25i +error corrections, 7, 16 +ex (text editor), 23 +\fIEx Reference Manual\fR, 23 +exclamation (!), 21 +file, 3 +file (f) command, 21-22 +file recovery, 22-23 +filename, 3, 21 +global (g) command, 19 +input mode, 6-7 +Interrupt (message), 9 +line numbers, \fIsee also\fR current line +.in +.25i +dollar sign ($), 10, 11, 17 +dot (\|.\|), 11, 17 +relative (+ and \-), 17 +.in -.25i +list, 10 +logging in, 4-6 +logging out, 8 +``Login incorrect'' (message), 5 +minus (\-), 17 +move (m) command, 14-15 +``Negative address\(emfirst buffer line is 1'' (message), 18 +``No current filename'' (message), 8 +``No such file or directory'' (message), 5, 6 +``No write since last change'' (message), 21 +non-printing characters, 10 +``Nonzero address required'' (message), 18 +``Not an editor command'' (message), 6 +``Not that many lines in buffer'' (message), 18 +number (nu) command, 11 +password, 5 +period (\|.\|), 11, 17 +plus (+), 17 +preserve (pre) command, 22-23 +print (p) command, 10 +program, 3 +prompts +.in .25i +% (\s-2UNIX\s0), 5 +: (edit), 5, 6, 7 +\0 (append), 7 +.in -.25i +question (?), 20 +quit (q) command, 8, 13 +read (r) command, 22 +recover (rec) command, 22, 23 +recovery, \fIsee\fR\| file recovery +references, 3, 23 +remove (rm) command, 21, 22 +reverse command effects (undo), 16-17, 23 +searching, 10-12, 19-21 +shell, 21 +shell escape (!), 21 +slash (/), 11-12, 20 +special characters (^, $, \\), 10, 11, 17, 20-21 +substitute (s) command, 11-12, 19, 20 +terminals, 4-5 +text input mode, 7 +undo (u) command, 16-17, 23 +\s-1UNIX\s0, 3 +write (w) command, 8, 13, 21, 22 +z command, 12-13 + diff --git a/contrib/nvi/docs/USD.doc/exref/Makefile b/contrib/nvi/docs/USD.doc/exref/Makefile new file mode 100644 index 000000000000..11b5423607e7 --- /dev/null +++ b/contrib/nvi/docs/USD.doc/exref/Makefile @@ -0,0 +1,17 @@ +# @(#)Makefile 8.8 (Berkeley) 10/10/96 + +ROFF= groff +TBL= tbl + +all: exref.ps summary.ps + +exref.ps: ex.rm + ${TBL} ex.rm | ${ROFF} -ms > $@ + chmod 444 $@ + +summary.ps: ex.summary + ${TBL} ex.summary | ${ROFF} -ms > $@ + chmod 444 $@ + +clean: + rm -f exref.ps summary.ps diff --git a/contrib/nvi/docs/USD.doc/exref/ex.rm b/contrib/nvi/docs/USD.doc/exref/ex.rm new file mode 100644 index 000000000000..217bad46d277 --- /dev/null +++ b/contrib/nvi/docs/USD.doc/exref/ex.rm @@ -0,0 +1,2213 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)ex.rm 8.5 (Berkeley) 8/18/96 +.\" +.nr LL 6.5i +.nr FL 6.5i +.EH 'USD:12-%''Ex Reference Manual' +.OH 'Ex Reference Manual''USD:12-%' +.nr )P 0 +.de ZP +.nr pd \\n()P +.nr )P 0 +.if \\n(.$=0 .IP +.if \\n(.$=1 .IP "\\$1" +.if \\n(.$>=2 .IP "\\$1" "\\$2" +.nr )P \\n(pd +.rm pd +.. +.de LC +.br +.sp .1i +.ne 4 +.LP +.ta 4.0i +.. +.bd S B 3 +.\".RP +.TL +Ex Reference Manual +.br +Version 3.7 +.AU +William Joy +.AU +Mark Horton +.AI +Computer Science Division +Department of Electrical Engineering and Computer Science +University of California, Berkeley +Berkeley, Ca. 94720 +.AB +.I Ex +a line oriented text editor, which supports both command and display +oriented editing. +This reference manual describes the command oriented part of +.I ex; +the display editing features of +.I ex +are described in +.I "An Introduction to Display Editing with Vi." +Other documents about the editor include the introduction +.I "Edit: A tutorial", +the +.I "Ex/edit Command Summary", +and a +.I "Vi Quick Reference" +card. +.AE +.NH 1 +Starting ex +.PP +.FS +The financial support of an \s-2IBM\s0 Graduate Fellowship and the National +Science Foundation under grants MCS74-07644-A03 and MCS78-07291 is gratefully +acknowledged. +.FE +Each instance of the editor has a set of options, +which can be set to tailor it to your liking. +The command +.I edit +invokes a version of +.I ex +designed for more casual or beginning +users by changing the default settings of some of these options. +To simplify the description which follows we +assume the default settings of the options. +.PP +When invoked, +.I ex +determines the terminal type from the \s-2TERM\s0 variable in the environment. +It there is a \s-2TERMCAP\s0 variable in the environment, and the type +of the terminal described there matches the \s-2TERM\s0 variable, +then that description +is used. Also if the \s-2TERMCAP\s0 variable contains a pathname (beginning +with a \fB/\fR) then the editor will seek the description of the terminal +in that file (rather than the default /etc/termcap). +If there is a variable \s-2EXINIT\s0 in the environment, then the editor +will execute the commands in that variable, +otherwise if there is a file +.I \&.exrc +in your \s-2HOME\s0 directory +.I ex +reads commands from that file, simulating a +.I source +command. +Option setting commands placed in +\s-2EXINIT\s0 or +.I \&.exrc +will be executed before each editor session. +.PP +A command to enter +.I ex +has the following prototype:\(dg +.FS +\(dg Brackets `[' `]' surround optional parameters here. +.FE +.DS +\fBex\fP [ \fB\-\fP ] [ \fB\-v\fP ] [ \fB\-t\fP \fItag\fP ] [ \fB\-r\fP ] [ \fB\-l\fP ] [ \fB\-w\fP\fIn\fP ] [ \fB\-x\fP ] [ \fB\-R\fP ] [ \fB+\fP\fIcommand\fP ] name ... +.DE +The most common case edits a single file with no options, i.e.: +.DS +\fBex\fR name +.DE +The +.B \- +command line option +option suppresses all interactive-user feedback +and is useful in processing editor scripts in command files. +The +.B \-v +option is equivalent to using +.I vi +rather than +.I ex. +The +.B \-t +option is equivalent to an initial +.I tag +command, editing the file containing the +.I tag +and positioning the editor at its definition. +The +.B \-r +option is used in recovering after an editor or system crash, +retrieving the last saved version of the named file or, +if no file is specified, +typing a list of saved files. +The +.B \-l +option sets up for editing \s-2LISP\s0, setting the +.I showmatch +and +.I lisp +options. +The +.B \-w +option sets the default window size to +.I n, +and is useful on dialups to start in small windows. +The +.B \-x +option causes +.I ex +to prompt for a +.I key , +which is used to encrypt and decrypt the contents of the file, +which should already be encrypted using the same key, +see +.I crypt (1). +The +.B \-R +option sets the +.I readonly +option at the start. +.I Name +arguments indicate files to be edited. +An argument of the form +\fB+\fIcommand\fR +indicates that the editor should begin by executing the specified command. +If +.I command +is omitted, then it defaults to ``$'', positioning the editor at the last +line of the first file initially. Other useful commands here are scanning +patterns of the form ``/pat'' or line numbers, e.g. ``+100'' starting +at line 100. +.NH 1 +File manipulation +.NH 2 +Current file +.PP +.I Ex +is normally editing the contents of a single file, +whose name is recorded in the +.I current +file name. +.I Ex +performs all editing actions in a buffer +(actually a temporary file) +into which the text of the file is initially read. +Changes made to the buffer have no effect on the file being +edited unless and until the buffer contents are written out to the +file with a +.I write +command. +After the buffer contents are written, +the previous contents of the written file are no longer accessible. +When a file is edited, +its name becomes the current file name, +and its contents are read into the buffer. +.PP +The current file is almost always considered to be +.I edited. +This means that the contents of the buffer are logically +connected with the current file name, +so that writing the current buffer contents onto that file, +even if it exists, +is a reasonable action. +If the current file is not +.I edited +then +.I ex +will not normally write on it if it already exists.* +.FS +* The +.I file +command will say ``[Not edited]'' if the current file is not considered +edited. +.FE +.NH 2 +Alternate file +.PP +Each time a new value is given to the current file name, +the previous current file name is saved as the +.I alternate +file name. +Similarly if a file is mentioned but does not become the current file, +it is saved as the alternate file name. +.NH 2 +Filename expansion +.PP +Filenames within the editor may be specified using the normal +shell expansion conventions. +In addition, +the character `%' in filenames is replaced by the +.I current +file name and the character +`#' by the +.I alternate +file name.\(dg +.FS +\(dg This makes it easy to deal alternately with +two files and eliminates the need for retyping the +name supplied on an +.I edit +command after a +.I "No write since last change" +diagnostic is received. +.FE +.NH 2 +Multiple files and named buffers +.PP +If more than one file is given on the command line, +then the first file is edited as described above. +The remaining arguments are placed with the first file in the +.I "argument list." +The current argument list may be displayed with the +.I args +command. +The next file in the argument list may be edited with the +.I next +command. +The argument list may also be respecified by specifying +a list of names to the +.I next +command. +These names are expanded, +the resulting list of names becomes the new argument list, +and +.I ex +edits the first file on the list. +.PP +For saving blocks of text while editing, and especially when editing +more than one file, +.I ex +has a group of named buffers. +These are similar to the normal buffer, except that only a limited number +of operations are available on them. +The buffers have names +.I a +through +.I z.\(dd +.FS +\(dd It is also possible to refer to +.I A +through +.I Z; +the upper case buffers are the same as the lower but commands +append to named buffers rather than replacing +if upper case names are used. +.FE +.NH 2 +Read only +.PP +It is possible to use +.I ex +in +.I "read only" +mode to look at files that you have no intention of modifying. +This mode protects you from accidently overwriting the file. +Read only mode is on when the +.I readonly +option is set. +It can be turned on with the +.B \-R +command line option, +by the +.I view +command line invocation, +or by setting the +.I readonly +option. +It can be cleared by setting +.I noreadonly . +It is possible to write, even while in read only mode, by indicating +that you really know what you are doing. +You can write to a different file, or can use the ! form of write, +even while in read only mode. +.NH 1 +Exceptional Conditions +.NH 2 +Errors and interrupts +.PP +When errors occur +.I ex +(optionally) rings the terminal bell and, in any case, prints an error +diagnostic. If the primary input is from a file, editor processing +will terminate. If an interrupt signal is received, +.I ex +prints ``Interrupt'' and returns to its command level. If the primary +input is a file, then +.I ex +will exit when this occurs. +.NH 2 +Recovering from hangups and crashes +.PP +If a hangup signal is received and the buffer has been modified since +it was last written out, or if the system crashes, either the editor +(in the first case) or the system (after it reboots in the second) will +attempt to preserve the buffer. The next time you log in you should be +able to recover the work you were doing, losing at most a few lines of +changes from the last point before the hangup or editor crash. To +recover a file you can use the +.B \-r +option. If you were editing the file +.I resume, +then you should change +to the directory where you were when the crash occurred, giving the command +.DS +\fBex \-r\fP\fI resume\fP +.DE +After checking that the retrieved file is indeed ok, you can +.I write +it over the previous contents of that file. +.PP +You will normally get mail from the system telling you when a file has +been saved after a crash. The command +.DS +\fBex\fP \-\fBr\fP +.DE +will print a list of the files which have been saved for you. +(In the case of a hangup, +the file will not appear in the list, +although it can be recovered.) +.NH 1 +Editing modes +.PP +.I Ex +has five distinct modes. The primary mode is +.I command +mode. Commands are entered in command mode when a `:' prompt is +present, and are executed each time a complete line is sent. In +.I "text input" +mode +.I ex +gathers input lines and places them in the file. The +.I append, +.I insert, +and +.I change +commands use text input mode. +No prompt is printed when you are in text input mode. +This mode is left by typing a `.' alone at the beginning of a line, and +.I command +mode resumes. +.PP +The last three modes are +.I open +and +.I visual +modes, entered by the commands of the same name, and, within open and +visual modes +.I "text insertion" +mode. +.I Open +and +.I visual +modes allow local editing operations to be performed on the text in the +file. The +.I open +command displays one line at a time on any terminal while +.I visual +works on \s-2CRT\s0 terminals with random positioning cursors, using the +screen as a (single) window for file editing changes. +These modes are described (only) in +.I "An Introduction to Display Editing with Vi." +.NH +Command structure +.PP +Most command names are English words, +and initial prefixes of the words are acceptable abbreviations. +The ambiguity of abbreviations is resolved in favor of the more commonly +used commands.* +.FS +* As an example, the command +.I substitute +can be abbreviated `s' +while the shortest available abbreviation for the +.I set +command is `se'. +.FE +.NH 2 +Command parameters +.PP +Most commands accept prefix addresses specifying the lines in the file +upon which they are to have effect. +The forms of these addresses will be discussed below. +A number of commands also may take a trailing +.I count +specifying the number of lines to be involved in the command.\(dg +.FS +\(dg Counts are rounded down if necessary. +.FE +Thus the command ``10p'' will print the tenth line in the buffer while +``delete 5'' will delete five lines from the buffer, +starting with the current line. +.PP +Some commands take other information or parameters, +this information always being given after the command name.\(dd +.FS +\(dd Examples would be option names in a +.I set +command i.e. ``set number'', +a file name in an +.I edit +command, +a regular expression in a +.I substitute +command, +or a target address for a +.I copy +command, i.e. ``1,5 copy 25''. +.FE +.NH 2 +Command variants +.PP +A number of commands have two distinct variants. +The variant form of the command is invoked by placing an +`!' immediately after the command name. +Some of the default variants may be controlled by options; +in this case, the `!' serves to toggle the default. +.NH 2 +Flags after commands +.PP +The characters `#', `p' and `l' may be placed after many commands.** +.FS +** +A `p' or `l' must be preceded by a blank or tab +except in the single special case `dp'. +.FE +In this case, the command abbreviated by these characters +is executed after the command completes. +Since +.I ex +normally prints the new current line after each change, `p' is rarely necessary. +Any number of `+' or `\-' characters may also be given with these flags. +If they appear, the specified offset is applied to the current line +value before the printing command is executed. +.NH 2 +Comments +.PP +It is possible to give editor commands which are ignored. +This is useful when making complex editor scripts +for which comments are desired. +The comment character is the double quote: ". +Any command line beginning with " is ignored. +Comments beginning with " may also be placed at the ends +of commands, except in cases where they could be confused as part +of text (shell escapes and the substitute and map commands). +.NH 2 +Multiple commands per line +.PP +More than one command may be placed on a line by separating each pair +of commands by a `|' character. +However the +.I global +commands, +comments, +and the shell escape `!' +must be the last command on a line, as they are not terminated by a `|'. +.NH 2 +Reporting large changes +.PP +Most commands which change the contents of the editor buffer give +feedback if the scope of the change exceeds a threshold given by the +.I report +option. +This feedback helps to detect undesirably large changes so that they may +be quickly and easily reversed with an +.I undo. +After commands with more global effect such as +.I global +or +.I visual, +you will be informed if the net change in the number of lines +in the buffer during this command exceeds this threshold. +.NH 1 +Command addressing +.NH 2 +Addressing primitives +.IP \fB.\fR 20 +The current line. +Most commands leave the current line as the last line which they affect. +The default address for most commands is the current line, +thus `\fB.\fR' is rarely used alone as an address. +.IP \fIn\fR 20 +The \fIn\fRth line in the editor's buffer, lines being numbered +sequentially from 1. +.IP \fB$\fR 20 +The last line in the buffer. +.IP \fB%\fR 20 +An abbreviation for ``1,$'', the entire buffer. +.IP \fI+n\fR\ \fI\-n\fR 20 +An offset relative to the current buffer line.\(dg +.FS +\(dg +The forms `.+3' `+3' and `+++' are all equivalent; +if the current line is line 100 they all address line 103. +.FE +.IP \fB/\fIpat\fR\fB/\fR\ \fB?\fIpat\fR\fB?\fR 20 +Scan forward and backward respectively for a line containing \fIpat\fR, a +regular expression (as defined below). The scans normally wrap around the end +of the buffer. +If all that is desired is to print the next line containing \fIpat\fR, then +the trailing \fB/\fR or \fB?\fR may be omitted. +If \fIpat\fP is omitted or explicitly empty, then the last +regular expression specified is located.\(dd +.FS +\(dd The forms \fB\e/\fP and \fB\e?\fP scan +using the last regular expression used in a scan; after a substitute +\fB//\fP and \fB??\fP would scan using the substitute's regular expression. +.FE +.IP \fB\(aa\(aa\fP\ \fB\(aa\fP\fIx\fP 20 +Before each non-relative motion of the current line `\fB.\fP', +the previous current line is marked with a tag, subsequently referred to as +`\(aa\(aa'. +This makes it easy to refer or return to this previous context. +Marks may also be established by the +.I mark +command, using single lower case letters +.I x +and the marked lines referred to as +`\(aa\fIx\fR'. +.NH 2 +Combining addressing primitives +.PP +Addresses to commands consist of a series of addressing primitives, +separated by `,' or `;'. +Such address lists are evaluated left-to-right. +When addresses are separated by `;' the current line `\fB.\fR' +is set to the value of the previous addressing expression +before the next address is interpreted. +If more addresses are given than the command requires, +then all but the last one or two are ignored. +If the command takes two addresses, the first addressed line must +precede the second in the buffer.\(dg +.FS +\(dg Null address specifications are permitted in a list of addresses, +the default in this case is the current line `.'; +thus `,100' is equivalent to `\fB.\fR,100'. +It is an error to give a prefix address to a command which expects none. +.FE +.NH 1 +Command descriptions +.PP +The following form is a prototype for all +.I ex +commands: +.DS +\fIaddress\fR \fBcommand\fR \fI! parameters count flags\fR +.DE +All parts are optional; the degenerate case is the empty command which prints +the next line in the file. For sanity with use from within +.I visual +mode, +.I ex +ignores a ``:'' preceding any command. +.PP +In the following command descriptions, the +default addresses are shown in parentheses, +which are +.I not, +however, +part of the command. +.LC +\fBabbreviate\fR \fIword rhs\fP abbr: \fBab\fP +.ZP +Add the named abbreviation to the current list. +When in input mode in visual, if +.I word +is typed as a complete word, it will be changed to +.I rhs . +.LC +( \fB.\fR ) \fBappend\fR abbr: \fBa\fR +.br +\fItext\fR +.br +\&\fB.\fR +.ZP +Reads the input text and places it after the specified line. +After the command, `\fB.\fR' +addresses the last line input or the +specified line if no lines were input. +If address `0' is given, +text is placed at the beginning of the buffer. +.LC +\fBa!\fR +.br +\fItext\fR +.br +\&\fB.\fR +.ZP +The variant flag to +.I append +toggles the setting for the +.I autoindent +option during the input of +.I text. +.LC +\fBargs\fR +.ZP +The members of the argument list are printed, with the current argument +delimited by `[' and `]'. +.ig +.PP +\fBcd\fR \fIdirectory\fR +.ZP +The +.I cd +command is a synonym for +.I chdir. +.. +.LC +( \fB.\fP , \fB.\fP ) \fBchange\fP \fIcount\fP abbr: \fBc\fP +.br +\fItext\fP +.br +\&\fB.\fP +.ZP +Replaces the specified lines with the input \fItext\fP. +The current line becomes the last line input; +if no lines were input it is left as for a +\fIdelete\fP. +.LC +\fBc!\fP +.br +\fItext\fP +.br +\&\fB.\fP +.ZP +The variant toggles +.I autoindent +during the +.I change. +.ig +.LC +\fBchdir\fR \fIdirectory\fR +.ZP +The specified \fIdirectory\fR becomes the current directory. +If no directory is specified, the current value of the +.I home +option is used as the target directory. +After a +.I chdir +the current file is not considered to have been +edited so that write restrictions on pre-existing files apply. +.. +.LC +( \fB.\fP , \fB.\fP )\|\fBcopy\fP \fIaddr\fP \fIflags\fP abbr: \fBco\fP +.ZP +A +.I copy +of the specified lines is placed after +.I addr, +which may be `0'. +The current line +`\fB.\fR' +addresses the last line of the copy. +The command +.I t +is a synonym for +.I copy. +.LC +( \fB.\fR , \fB.\fR )\|\fBdelete\fR \fIbuffer\fR \fIcount\fR \fIflags\fR abbr: \fBd\fR +.ZP +Removes the specified lines from the buffer. +The line after the last line deleted becomes the current line; +if the lines deleted were originally at the end, +the new last line becomes the current line. +If a named +.I buffer +is specified by giving a letter, +then the specified lines are saved in that buffer, +or appended to it if an upper case letter is used. +.LC +\fBedit\fR \fIfile\fR abbr: \fBe\fR +.br +\fBex\fR \fIfile\fR +.ZP +Used to begin an editing session on a new file. +The editor +first checks to see if the buffer has been modified since the last +.I write +command was issued. +If it has been, +a warning is issued and the +command is aborted. +The +command otherwise deletes the entire contents of the editor buffer, +makes the named file the current file and prints the new filename. +After insuring that this file is sensible\(dg +.FS +\(dg I.e., that it is not a binary file such as a directory, +a block or character special file other than +.I /dev/tty, +a terminal, +or a binary or executable file +(as indicated by the first word). +.FE +the editor reads the file into its buffer. +.IP +If the read of the file completes without error, +the number of lines and characters read is typed. +If there were any non-\s-2ASCII\s0 characters +in the file they are stripped of their non-\s-2ASCII\s0 +high bits, +and any null characters in the file are discarded. +If none of these errors occurred, the file is considered +.I edited. +If the last line of the input file is missing the trailing +newline character, it will be supplied and a complaint will be issued. +This command leaves the current line `\fB.\fR' at the last line read.\(dd +.FS +\(dd If executed from within +.I open +or +.I visual, +the current line is initially the first line of the file. +.FE +.LC +\fBe!\fR \fIfile\fR +.ZP +The variant form suppresses the complaint about modifications having +been made and not written from the editor buffer, thus +discarding all changes which have been made before editing the new file. +.LC +\fBe\fR \fB+\fIn\fR \fIfile\fR +.ZP +Causes the editor to begin at line +.I n +rather than at the last line; +\fIn\fR may also be an editor command containing no spaces, e.g.: ``+/pat''. +.LC +\fBfile\fR abbr: \fBf\fR +.ZP +Prints the current file name, +whether it has been `[Modified]' since the last +.I write +command, +whether it is +.I "read only" , +the current line, +the number of lines in the buffer, +and the percentage of the way through the buffer of the current line.* +.FS +* In the rare case that the current file is `[Not edited]' this is +noted also; in this case you have to use the form \fBw!\fR to write to +the file, since the editor is not sure that a \fBwrite\fR will not +destroy a file unrelated to the current contents of the buffer. +.FE +.LC +\fBfile\fR \fIfile\fR +.ZP +The current file name is changed to +.I file +which is considered +`[Not edited]'. +.LC +( 1 , $ ) \fBglobal\fR /\fIpat\|\fR/ \fIcmds\fR abbr: \fBg\fR +.ZP +First marks each line among those specified which matches +the given regular expression. +Then the given command list is executed with `\fB.\fR' initially +set to each marked line. +.IP +The command list consists of the remaining commands on the current +input line and may continue to multiple lines by ending all but the +last such line with a `\e'. +If +.I cmds +(and possibly the trailing \fB/\fR delimiter) is omitted, each line matching +.I pat +is printed. +.I Append, +.I insert, +and +.I change +commands and associated input are permitted; +the `\fB.\fR' terminating input may be omitted if it would be on the +last line of the command list. +.I Open +and +.I visual +commands are permitted in the command list and take input from the terminal. +.IP +The +.I global +command itself may not appear in +.I cmds. +The +.I undo +command is also not permitted there, +as +.I undo +instead can be used to reverse the entire +.I global +command. +The options +.I autoprint +and +.I autoindent +are inhibited during a +.I global, +(and possibly the trailing \fB/\fR delimiter) and the value of the +.I report +option is temporarily infinite, +in deference to a \fIreport\fR for the entire global. +Finally, the context mark `\'\'' is set to the value of +`.' before the global command begins and is not changed during a global +command, +except perhaps by an +.I open +or +.I visual +within the +.I global. +.LC +\fBg!\fR \fB/\fIpat\fB/\fR \fIcmds\fR abbr: \fBv\fR +.IP +The variant form of \fIglobal\fR runs \fIcmds\fR at each line not matching +\fIpat\fR. +.LC +( \fB.\fR )\|\fBinsert\fR abbr: \fBi\fR +.br +\fItext\fR +.br +\&\fB.\fR +.ZP +Places the given text before the specified line. +The current line is left at the last line input; +if there were none input it is left at the line before the addressed line. +This command differs from +.I append +only in the placement of text. +.KS +.LC +\fBi!\fR +.br +\fItext\fR +.br +\&\fB.\fR +.ZP +The variant toggles +.I autoindent +during the +.I insert. +.KE +.LC +( \fB.\fR , \fB.\fR+1 ) \fBjoin\fR \fIcount\fR \fIflags\fR abbr: \fBj\fR +.ZP +Places the text from a specified range of lines +together on one line. +White space is adjusted at each junction to provide at least +one blank character, two if there was a `\fB.\fR' at the end of the line, +or none if the first following character is a `)'. +If there is already white space at the end of the line, +then the white space at the start of the next line will be discarded. +.LC +\fBj!\fR +.ZP +The variant causes a simpler +.I join +with no white space processing; the characters in the lines are simply +concatenated. +.LC +( \fB.\fR ) \fBk\fR \fIx\fR +.ZP +The +.I k +command is a synonym for +.I mark. +It does not require a blank or tab before the following letter. +.LC +( \fB.\fR , \fB.\fR ) \fBlist\fR \fIcount\fR \fIflags\fR +.ZP +Prints the specified lines in a more unambiguous way: +tabs are printed as `^I' +and the end of each line is marked with a trailing `$'. +The current line is left at the last line printed. +.LC +\fBmap\fR \fIlhs\fR \fIrhs\fR +.ZP +The +.I map +command is used to define macros for use in +.I visual +mode. +.I Lhs +should be a single character, or the sequence ``#n'', for n a digit, +referring to function key \fIn\fR. When this character or function key +is typed in +.I visual +mode, it will be as though the corresponding \fIrhs\fR had been typed. +On terminals without function keys, you can type ``#n''. +See section 6.9 of the ``Introduction to Display Editing with Vi'' +for more details. +.LC +( \fB.\fR ) \fBmark\fR \fIx\fR +.ZP +Gives the specified line mark +.I x, +a single lower case letter. +The +.I x +must be preceded by a blank or a tab. +The addressing form `\'x' then addresses this line. +The current line is not affected by this command. +.LC +( \fB.\fR , \fB.\fR ) \fBmove\fR \fIaddr\fR abbr: \fBm\fR +.ZP +The +.I move +command repositions the specified lines to be after +.I addr . +The first of the moved lines becomes the current line. +.LC +\fBnext\fR abbr: \fBn\fR +.ZP +The next file from the command line argument list is edited. +.LC +\fBn!\fR +.ZP +The variant suppresses warnings about the modifications to the buffer not +having been written out, discarding (irretrievably) any changes which may +have been made. +.LC +\fBn\fR \fIfilelist\fR +.br +\fBn\fR \fB+\fIcommand\fR \fIfilelist\fR +.ZP +The specified +.I filelist +is expanded and the resulting list replaces the +current argument list; +the first file in the new list is then edited. +If +.I command +is given (it must contain no spaces), then it is executed after editing the first such file. +.LC +( \fB.\fR , \fB.\fR ) \fBnumber\fR \fIcount\fR \fIflags\fR abbr: \fB#\fR or \fBnu\fR +.ZP +Prints each specified line preceded by its buffer line +number. +The current line is left at the last line printed. +.KS +.LC +( \fB.\fR ) \fBopen\fR \fIflags\fR abbr: \fBo\fR +.br +( \fB.\fR ) \fBopen\fR /\fIpat\|\fR/ \fIflags\fR +.ZP +Enters intraline editing \fIopen\fR mode at each addressed line. +If +.I pat +is given, +then the cursor will be placed initially at the beginning of the +string matched by the pattern. +To exit this mode use Q. +See +.I "An Introduction to Display Editing with Vi" +for more details. +.KE +.LC +\fBpreserve\fR +.ZP +The current editor buffer is saved as though the system had just crashed. +This command is for use only in emergencies when a +.I write +command has resulted in an error and you don't know how to save your work. +After a +.I preserve +you should seek help. +.LC +( \fB.\fR , \fB.\fR )\|\fBprint\fR \fIcount\fR abbr: \fBp\fR or \fBP\fR +.ZP +Prints the specified lines +with non-printing characters printed as control characters `^\fIx\fR\|'; +delete (octal 177) is represented as `^?'. +The current line is left at the last line printed. +.LC +( \fB.\fR )\|\fBput\fR \fIbuffer\fR abbr: \fBpu\fR +.ZP +Puts back +previously +.I deleted +or +.I yanked +lines. +Normally used with +.I delete +to effect movement of lines, +or with +.I yank +to effect duplication of lines. +If no +.I buffer +is specified, then the last +.I deleted +or +.I yanked +text is restored.* +.FS +* But no modifying commands may intervene between the +.I delete +or +.I yank +and the +.I put, +nor may lines be moved between files without using a named buffer. +.FE +By using a named buffer, text may be restored that was saved there at any +previous time. +.LC +\fBquit\fR abbr: \fBq\fR +.ZP +Causes +.I ex +to terminate. +No automatic write of the editor buffer to a file is performed. +However, +.I ex +issues a warning message if the file has changed +since the last +.I write +command was issued, and does not +.I quit.\(dg +.FS +\(dg \fIEx\fR +will also issue a diagnostic if there are more files in the argument +list. +.FE +Normally, you will wish to save your changes, and you +should give a \fIwrite\fR command; +if you wish to discard them, use the \fBq!\fR command variant. +.LC +\fBq!\fR +.ZP +Quits from the editor, discarding changes to the buffer without complaint. +.LC +( \fB.\fR ) \fBread\fR \fIfile\fR abbr: \fBr\fR +.ZP +Places a copy of the text of the given file in the +editing buffer after the specified line. +If no +.I file +is given the current file name is used. +The current file name is not changed unless there is none in which +case +.I file +becomes the current name. +The sensibility restrictions for the +.I edit +command apply here also. +If the file buffer is empty and there is no current name then +.I ex +treats this as an +.I edit +command. +.IP +Address `0' is legal for this command and causes the file to be read at +the beginning of the buffer. +Statistics are given as for the +.I edit +command when the +.I read +successfully terminates. +After a +.I read +the current line is the last line read.\(dd +.FS +\(dd Within +.I open +and +.I visual +the current line is set to the first line read rather than the last. +.FE +.LC +( \fB.\fR ) \fBread\fR \fB!\fR\fIcommand\fR +.ZP +Reads the output of the command +.I command +into the buffer after the specified line. +This is not a variant form of the command, rather a read +specifying a +.I command +rather than a +.I filename; +a blank or tab before the \fB!\fR is mandatory. +.LC +\fBrecover \fIfile\fR +.ZP +Recovers +.I file +from the system save area. +Used after a accidental hangup of the phone** +.FS +** The system saves a copy of the file you were editing only if you +have made changes to the file. +.FE +or a system crash** or +.I preserve +command. +Except when you use +.I preserve +you will be notified by mail when a file is saved. +.LC +\fBrewind\fR abbr: \fBrew\fR +.ZP +The argument list is rewound, and the first file in the list is edited. +.LC +\fBrew!\fR +.ZP +Rewinds the argument list discarding any changes made to the current buffer. +.LC +\fBset\fR \fIparameter\fR +.ZP +With no arguments, prints those options whose values have been +changed from their defaults; +with parameter +.I all +it prints all of the option values. +.IP +Giving an option name followed by a `?' +causes the current value of that option to be printed. +The `?' is unnecessary unless the option is Boolean valued. +Boolean options are given values either by the form +`set \fIoption\fR' to turn them on or +`set no\fIoption\fR' to turn them off; +string and numeric options are assigned via the form +`set \fIoption\fR=value'. +.IP +More than one parameter may be given to +.I set \|; +they are interpreted left-to-right. +.LC +\fBshell\fR abbr: \fBsh\fR +.IP +A new shell is created. +When it terminates, editing resumes. +.LC +\fBsource\fR \fIfile\fR abbr: \fBso\fR +.IP +Reads and executes commands from the specified file. +.I Source +commands may be nested. +.LC +( \fB.\fR , \fB.\fR ) \fBsubstitute\fR /\fIpat\fR\|/\fIrepl\fR\|/ \fIoptions\fR \fIcount\fR \fIflags\fR abbr: \fBs\fR +.IP +On each specified line, the first instance of pattern +.I pat +is replaced by replacement pattern +.I repl. +If the +.I global +indicator option character `g' +appears, then all instances are substituted; +if the +.I confirm +indication character `c' appears, +then before each substitution the line to be substituted +is typed with the string to be substituted marked +with `\(ua' characters. +By typing an `y' one can cause the substitution to be performed, +any other input causes no change to take place. +After a +.I substitute +the current line is the last line substituted. +.IP +Lines may be split by substituting +new-line characters into them. +The newline in +.I repl +must be escaped by preceding it with a `\e'. +Other metacharacters available in +.I pat +and +.I repl +are described below. +.LC +.B stop +.ZP +Suspends the editor, returning control to the top level shell. +If +.I autowrite +is set and there are unsaved changes, +a write is done first unless the form +.B stop ! +is used. +This commands is only available where supported by the teletype driver +and operating system. +.LC +( \fB.\fR , \fB.\fR ) \fBsubstitute\fR \fIoptions\fR \fIcount\fR \fIflags\fR abbr: \fBs\fR +.ZP +If +.I pat +and +.I repl +are omitted, then the last substitution is repeated. +This is a synonym for the +.B & +command. +.LC +( \fB.\fR , \fB.\fR ) \fBt\fR \fIaddr\fR \fIflags\fR +.ZP +The +.I t +command is a synonym for +.I copy . +.LC +\fBta\fR \fItag\fR +.ZP +The focus of editing switches to the location of +.I tag, +switching to a different line in the current file where it is defined, +or if necessary to another file.\(dd +.FS +\(dd If you have modified the current file before giving a +.I tag +command, you must write it out; giving another +.I tag +command, specifying no +.I tag +will reuse the previous tag. +.FE +.IP +The tags file is normally created by a program such as +.I ctags, +and consists of a number of lines with three fields separated by blanks +or tabs. The first field gives the name of the tag, +the second the name of the file where the tag resides, and the third +gives an addressing form which can be used by the editor to find the tag; +this field is usually a contextual scan using `/\fIpat\fR/' to be immune +to minor changes in the file. Such scans are always performed as if +.I nomagic +was set. +.PP +The tag names in the tags file must be sorted alphabetically. +.LC +\fBunabbreviate\fR \fIword\fP abbr: \fBuna\fP +.ZP +Delete +.I word +from the list of abbreviations. +.LC +\fBundo\fR abbr: \fBu\fR +.ZP +Reverses the changes made in the buffer by the last +buffer editing command. +Note that +.I global +commands are considered a single command for the purpose of +.I undo +(as are +.I open +and +.I visual.) +Also, the commands +.I write +and +.I edit +which interact with the +file system cannot be undone. +.I Undo +is its own inverse. +.IP +.I Undo +always marks the previous value of the current line `\fB.\fR' +as `\'\''. +After an +.I undo +the current line is the first line restored +or the line before the first line deleted if no lines were restored. +For commands with more global effect +such as +.I global +and +.I visual +the current line regains it's pre-command value after an +.I undo. +.LC +\fBunmap\fR \fIlhs\fR +.ZP +The macro expansion associated by +.I map +for +.I lhs +is removed. +.LC +( 1 , $ ) \fBv\fR /\fIpat\fR\|/ \fIcmds\fR +.ZP +A synonym for the +.I global +command variant \fBg!\fR, running the specified \fIcmds\fR on each +line which does not match \fIpat\fR. +.LC +\fBversion\fR abbr: \fBve\fR +.ZP +Prints the current version number of the editor +as well as the date the editor was last changed. +.LC +( \fB.\fR ) \fBvisual\fR \fItype\fR \fIcount\fR \fIflags\fR abbr: \fBvi\fR +.ZP +Enters visual mode at the specified line. +.I Type +is optional and may be `\-' , `\(ua' or `\fB.\fR' +as in the +.I z +command to specify the placement of the specified line on the screen. +By default, if +.I type +is omitted, the specified line is placed as the first on the screen. +A +.I count +specifies an initial window size; the default is the value of the option +.I window. +See the document +.I "An Introduction to Display Editing with Vi" +for more details. +To exit this mode, type Q. +.LC +\fBvisual\fP file +.br +\fBvisual\fP +\fIn\fP file +.ZP +From visual mode, +this command is the same as edit. +.LC +( 1 , $ ) \fBwrite\fR \fIfile\fR abbr: \fBw\fR +.ZP +Writes changes made back to \fIfile\fR, printing the number of lines and +characters written. +Normally \fIfile\fR is omitted and the text goes back where it came from. +If a \fIfile\fR is specified, then text will be written to that file.* +.FS +* The editor writes to a file only if it is +the current file and is +.I edited , +if the file does not exist, +or if the file is actually a teletype, +.I /dev/tty, +.I /dev/null. +Otherwise, you must give the variant form \fBw!\fR to force the write. +.FE +If the file does not exist it is created. +The current file name is changed only if there is no current file +name; the current line is never changed. +.IP +If an error occurs while writing the current and +.I edited +file, the editor +considers that there has been ``No write since last change'' +even if the buffer had not previously been modified. +.LC +( 1 , $ ) \fBwrite>>\fR \fIfile\fR abbr: \fBw>>\fR +.ZP +Writes the buffer contents at the end of +an existing file. +.IP +.LC +\fBw!\fR \fIname\fR +.ZP +Overrides the checking of the normal \fIwrite\fR command, +and will write to any file which the system permits. +.LC +( 1 , $ ) \fBw\fR \fB!\fR\fIcommand\fR +.ZP +Writes the specified lines into +.I command. +Note the difference between \fBw!\fR which overrides checks and +\fBw\ \ !\fR which writes to a command. +.LC +\fBwq\fR \fIname\fR +.ZP +Like a \fIwrite\fR and then a \fIquit\fR command. +.LC +\fBwq!\fR \fIname\fR +.ZP +The variant overrides checking on the sensibility of the +.I write +command, as \fBw!\fR does. +.LC +\fBxit\fP \fIname\fR +.ZP +If any changes have been made and not written, writes the buffer out. +Then, in any case, quits. +.LC +( \fB.\fR , \fB.\fR )\|\fByank\fR \fIbuffer\fR \fIcount\fR abbr: \fBya\fR +.ZP +Places the specified lines in the named +.I buffer, +for later retrieval via +.I put. +If no buffer name is specified, the lines go to a more volatile place; +see the \fIput\fR command description. +.LC +( \fB.+1\fR ) \fBz\fR \fIcount\fR +.ZP +Print the next \fIcount\fR lines, default \fIwindow\fR. +.LC +( \fB.\fR ) \fBz\fR \fItype\fR \fIcount\fR +.ZP +Prints a window of text with the specified line at the top. +If \fItype\fR is `\-' the line is placed at the bottom; a `\fB.\fR' causes +the line to be placed in the center.* +A count gives the number of lines to be displayed rather than +double the number specified by the \fIscroll\fR option. +On a \s-2CRT\s0 the screen is cleared before display begins unless a +count which is less than the screen size is given. +The current line is left at the last line printed. +.FS +* Forms `z=' and `z\(ua' also exist; `z=' places the current line in the +center, surrounds it with lines of `\-' characters and leaves the current +line at this line. The form `z\(ua' prints the window before `z\-' +would. The characters `+', `\(ua' and `\-' may be repeated for cumulative +effect. +On some v2 editors, no +.I type +may be given. +.FE +.LC +\fB!\fR \fIcommand\fR\fR +.ZP +The remainder of the line after the `!' character is sent to a shell +to be executed. +Within the text of +.I command +the characters +`%' and `#' are expanded as in filenames and the character +`!' is replaced with the text of the previous command. +Thus, in particular, +`!!' repeats the last such shell escape. +If any such expansion is performed, the expanded line will be echoed. +The current line is unchanged by this command. +.IP +If there has been ``[No\ write]'' of the buffer contents since the last +change to the editing buffer, then a diagnostic will be printed +before the command is executed as a warning. +A single `!' is printed when the command completes. +.LC +( \fIaddr\fR , \fIaddr\fR ) \fB!\fR \fIcommand\fR\fR +.ZP +Takes the specified address range and supplies it as +standard input to +.I command; +the resulting output then replaces the input lines. +.LC +( $ ) \fB=\fR +.ZP +Prints the line number of the +addressed line. +The current line is unchanged. +.KS +.LC +( \fB.\fR , \fB.\fR ) \fB>\fR \fIcount\fR \fIflags\fR +.br +( \fB.\fR , \fB.\fR ) \fB<\fR \fIcount\fR \fIflags\fR +.IP +Perform intelligent shifting on the specified lines; +\fB<\fR shifts left and \fB>\fR shift right. +The quantity of shift is determined by the +.I shiftwidth +option and the repetition of the specification character. +Only white space (blanks and tabs) is shifted; +no non-white characters are discarded in a left-shift. +The current line becomes the last line which changed due to the +shifting. +.KE +.LC +\fB^D\fR +.ZP +An end-of-file from a terminal input scrolls through the file. +The +.I scroll +option specifies the size of the scroll, normally a half screen of text. +.LC +( \fB.\fR+1 , \fB.\fR+1 ) +.br +( \fB.\fR+1 , \fB.\fR+1 ) | +.ZP +An address alone causes the addressed lines to be printed. +A blank line prints the next line in the file. +.LC +( \fB.\fR , \fB.\fR ) \fB&\fR \fIoptions\fR \fIcount\fR \fIflags\fR +.ZP +Repeats the previous +.I substitute +command. +.LC +( \fB.\fR , \fB.\fR ) \fB\s+2~\s0\fR \fIoptions\fR \fIcount\fR \fIflags\fR +.ZP +Replaces the previous regular expression with the previous +replacement pattern from a substitution. +.NH 1 +Regular expressions and substitute replacement patterns +.NH 2 +Regular expressions +.PP +A regular expression specifies a set of strings of characters. +A member of this set of strings is said to be +.I matched +by the regular expression. +.I Ex +remembers two previous regular expressions: +the previous regular expression used in a +.I substitute +command +and the previous regular expression used elsewhere +(referred to as the previous \fIscanning\fR regular expression.) +The previous regular expression +can always be referred to by a null \fIre\fR, e.g. `//' or `??'. +.NH 2 +Magic and nomagic +.PP +The regular expressions allowed by +.I ex +are constructed in one of two ways depending on the setting of +the +.I magic +option. +The +.I ex +and +.I vi +default setting of +.I magic +gives quick access to a powerful set of regular expression +metacharacters. +The disadvantage of +.I magic +is that the user must remember that these metacharacters are +.I magic +and precede them with the character `\e' +to use them as ``ordinary'' characters. +With +.I nomagic, +the default for +.I edit, +regular expressions are much simpler, +there being only two metacharacters. +The power of the other metacharacters is still available by preceding +the (now) ordinary character with a `\e'. +Note that `\e' is thus always a metacharacter. +.PP +The remainder of the discussion of regular expressions assumes +that +that the setting of this option is +.I magic.\(dg +.FS +\(dg To discern what is true with +.I nomagic +it suffices to remember that the only +special characters in this case will be `\(ua' at the beginning +of a regular expression, +`$' at the end of a regular expression, +and `\e'. +With +.I nomagic +the characters `\s+2~\s0' and `&' also lose their special meanings +related to the replacement pattern of a substitute. +.FE +.NH 2 +Basic regular expression summary +.PP +The following basic constructs are used to construct +.I magic +mode regular expressions. +.IP \fIchar\fR 15 +An ordinary character matches itself. +The characters `\(ua' at the beginning of a line, +`$' at the end of line, +`*' as any character other than the first, +`.', `\e', `[', and `\s+2~\s0' are not ordinary characters and +must be escaped (preceded) by `\e' to be treated as such. +.IP \fB\(ua\fR +At the beginning of a pattern +forces the match to succeed only at the beginning of a line. +.IP \fB$\fR +At the end of a regular expression forces the match to +succeed only at the end of the line. +.IP \&\fB.\fR +Matches any single character except +the new-line character. +.IP \fB\e<\fR +Forces the match +to occur only at the beginning of a ``variable'' or ``word''; +that is, either at the beginning of a line, or just before +a letter, digit, or underline and after a character not one of +these. +.IP \fB\e>\fR +Similar to `\e<', but matching the end of a ``variable'' +or ``word'', i.e. either the end of the line or before character +which is neither a letter, nor a digit, nor the underline character. +.IP \fB[\fIstring\fR]\fR +Matches any (single) character in the class defined by +.I string. +Most characters in +.I string +define themselves. +A pair of characters separated by `\-' in +.I string +defines the set of characters collating between the specified lower and upper +bounds, thus `[a\-z]' as a regular expression matches +any (single) lower-case letter. +If the first character of +.I string +is an `\(ua' then the construct +matches those characters which it otherwise would not; +thus `[\(uaa\-z]' matches anything but a lower-case letter (and of course a +newline). +To place any of the characters +`\(ua', `[', or `\-' in +.I string +you must escape them with a preceding `\e'. +.NH 2 +Combining regular expression primitives +.PP +The concatenation of two regular expressions matches the leftmost and +then longest string +which can be divided with the first piece matching the first regular +expression and the second piece matching the second. +Any of the (single character matching) regular expressions mentioned +above may be followed by the character `*' to form a regular expression +which matches any number of adjacent occurrences (including 0) of characters +matched by the regular expression it follows. +.PP +The character `\s+2~\s0' may be used in a regular expression, +and matches the text which defined the replacement part +of the last +.I substitute +command. +A regular expression may be enclosed between the sequences +`\e(' and `\e)' with side effects in the +.I substitute +replacement patterns. +.NH 2 +Substitute replacement patterns +.PP +The basic metacharacters for the replacement pattern are +`&' and `~'; these are +given as `\e&' and `\e~' when +.I nomagic +is set. +Each instance of `&' is replaced by the characters +which the regular expression matched. +The metacharacter `~' stands, in the replacement pattern, +for the defining text of the previous replacement pattern. +.PP +Other metasequences possible in the replacement pattern +are always introduced by the escaping character `\e'. +The sequence `\e\fIn\fR' is replaced by the text matched +by the \fIn\fR-th regular subexpression enclosed between +`\e(' and `\e)'.\(dg +.FS +\(dg When nested, parenthesized subexpressions are present, +\fIn\fR is determined by counting occurrences of `\e(' starting from the left. +.FE +The sequences `\eu' and `\el' cause the immediately following character in +the replacement to be converted to upper- or lower-case respectively +if this character is a letter. +The sequences `\eU' and `\eL' turn such conversion on, either until +`\eE' or `\ee' is encountered, or until the end of the replacement pattern. +.de LC +.br +.sp .1i +.ne 4 +.LP +.ta 3i +.. +.NH 1 +Option descriptions +.PP +.LC +\fBautoindent\fR, \fBai\fR default: noai +.ZP +Can be used to ease the preparation of structured program text. +At the beginning of each +.I append , +.I change +or +.I insert +command +or when a new line is +.I opened +or created by an +.I append , +.I change , +.I insert , +or +.I substitute +operation within +.I open +or +.I visual +mode, +.I ex +looks at the line being appended after, +the first line changed +or the line inserted before and calculates the amount of white space +at the start of the line. +It then aligns the cursor at the level of indentation so determined. +.IP +If the user then types lines of text in, +they will continue to be justified at the displayed indenting level. +If more white space is typed at the beginning of a line, +the following line will start aligned with the first non-white character +of the previous line. +To back the cursor up to the preceding tab stop one can hit +\fB^D\fR. +The tab stops going backwards are defined at multiples of the +.I shiftwidth +option. +You +.I cannot +backspace over the indent, +except by sending an end-of-file with a \fB^D\fR. +.IP +Specially processed in this mode is a line with no characters added +to it, which turns into a completely blank line (the white +space provided for the +.I autoindent +is discarded.) +Also specially processed in this mode are lines beginning with +an `\(ua' and immediately followed by a \fB^D\fR. +This causes the input to be repositioned at the beginning of the line, +but retaining the previous indent for the next line. +Similarly, a `0' followed by a \fB^D\fR +repositions at the beginning but without +retaining the previous indent. +.IP +.I Autoindent +doesn't happen in +.I global +commands or when the input is not a terminal. +.LC +\fBautoprint\fR, \fBap\fR default: ap +.ZP +Causes the current line to be printed after each +.I delete , +.I copy , +.I join , +.I move , +.I substitute , +.I t , +.I undo +or +shift command. +This has the same effect as supplying a trailing `p' +to each such command. +.I Autoprint +is suppressed in globals, +and only applies to the last of many commands on a line. +.LC +\fBautowrite\fR, \fBaw\fR default: noaw +.ZP +Causes the contents of the buffer to be written to the current file +if you have modified it and give a +.I next, +.I rewind, +.I stop, +.I tag, +or +.I ! +command, or a \fB^\(ua\fR (switch files) or \fB^]\fR (tag goto) command +in +.I visual. +Note, that the +.I edit +and +.I ex +commands do +.B not +autowrite. +In each case, there is an equivalent way of switching when autowrite +is set to avoid the +.I autowrite +(\fIedit\fR +for +.I next , +.I rewind! +for .I rewind , +.I stop! +for +.I stop , +.I tag! +for +.I tag , +.I shell +for +.I ! , +and +\fB:e\ #\fR and a \fB:ta!\fR command from within +.I visual). +.LC +\fBbeautify\fR, \fBbf\fR default: nobeautify +.ZP +Causes all control characters except tab, newline and form-feed +to be discarded from the input. +A complaint is registered the first time a +backspace character is discarded. +.I Beautify +does not apply to command input. +.LC +\fBdirectory\fR, \fBdir\fR default: dir=/tmp +.ZP +Specifies the directory in which +.I ex +places its buffer file. +If this directory in not +writable, then the editor will exit abruptly when it fails to be +able to create its buffer there. +.LC +\fBedcompatible\fR default: noedcompatible +.ZP +Causes the presence of absence of +.B g +and +.B c +suffixes on substitute commands to be remembered, and to be toggled +by repeating the suffices. The suffix +.B r +makes the substitution be as in the +.I ~ +command, instead of like +.I &. +.LC +\fBerrorbells\fR, \fBeb\fR default: noeb +.ZP +Error messages are preceded by a bell.* +.FS +* Bell ringing in +.I open +and +.I visual +on errors is not suppressed by setting +.I noeb. +.FE +If possible the editor always places the error message in a standout mode of the +terminal (such as inverse video) instead of ringing the bell. +.LC +\fBhardtabs\fR, \fBht\fR default: ht=8 +.ZP +Gives the boundaries on which terminal hardware tabs are set (or +on which the system expands tabs). +.LC +\fBignorecase\fR, \fBic\fR default: noic +.ZP +All upper case characters in the text are mapped to lower case in regular +expression matching. +In addition, all upper case characters in regular expressions are mapped +to lower case except in character class specifications. +.LC +\fBlisp\fR default: nolisp +.ZP +\fIAutoindent\fR indents appropriately for +.I lisp +code, and the \fB( ) { } [[\fR and \fB]]\fR commands in +.I open +and +.I visual +are modified to have meaning for \fIlisp\fR. +.LC +\fBlist\fR default: nolist +.ZP +All printed lines will be displayed (more) unambiguously, +showing tabs and end-of-lines as in the +.I list +command. +.LC +\fBmagic\fR default: magic for \fIex\fR and \fIvi\fR\(dg +.FS +\(dg \fINomagic\fR for \fIedit\fR. +.FE +.ZP +If +.I nomagic +is set, the number of regular expression metacharacters is greatly reduced, +with only `\(ua' and `$' having special effects. +In addition the metacharacters +`~' +and +`&' +of the replacement pattern are treated as normal characters. +All the normal metacharacters may be made +.I magic +when +.I nomagic +is set by preceding them with a `\e'. +.LC +\fBmesg\fR default: mesg +.ZP +Causes write permission to be turned off to the terminal +while you are in visual mode, if +.I nomesg +is set. +.LC +\fBmodeline\fR default: nomodeline +.ZP +If +.I modeline +is set, then the first 5 lines and the last five lines of the file +will be checked for ex command lines and the comands issued. +To be recognized as a command line, the line must have the string +.B ex: +or +.B vi: +preceeded by a tab or a space. This string may be anywhere in the +line and anything after the +.I : +is interpeted as editor commands. This option defaults to off because +of unexpected behavior when editting files such as +.I /etc/passwd. +.LC +\fBnumber, nu\fR default: nonumber +.ZP +Causes all output lines to be printed with their +line numbers. +In addition each input line will be prompted for by supplying the line number +it will have. +.LC +\fBopen\fR default: open +.ZP +If \fInoopen\fR, the commands +.I open +and +.I visual +are not permitted. +This is set for +.I edit +to prevent confusion resulting from accidental entry to +open or visual mode. +.LC +\fBoptimize, opt\fR default: optimize +.ZP +Throughput of text is expedited by setting the terminal +to not do automatic carriage returns +when printing more than one (logical) line of output, +greatly speeding output on terminals without addressable +cursors when text with leading white space is printed. +.LC +\fBparagraphs,\ para\fR default: para=IPLPPPQPP\0LIbp +.ZP +Specifies the paragraphs for the \fB{\fR and \fB}\fR operations in +.I open +and +.I visual. +The pairs of characters in the option's value are the names +of the macros which start paragraphs. +.LC +\fBprompt\fR default: prompt +.ZP +Command mode input is prompted for with a `:'. +.LC +\fBredraw\fR default: noredraw +.ZP +The editor simulates (using great amounts of output), an intelligent +terminal on a dumb terminal (e.g. during insertions in +.I visual +the characters to the right of the cursor position are refreshed +as each input character is typed.) +Useful only at very high speed. +.LC +\fBremap\fP default: remap +.ZP +If on, macros are repeatedly tried until they are unchanged. +For example, if +.B o +is mapped to +.B O , +and +.B O +is mapped to +.B I , +then if +.I remap +is set, +.B o +will map to +.B I , +but if +.I noremap +is set, it will map to +.B O . +.LC +\fBreport\fR default: report=5\(dg +.FS +\(dg 2 for \fIedit\fR. +.FE +.ZP +Specifies a threshold for feedback from commands. +Any command which modifies more than the specified number of lines +will provide feedback as to the scope of its changes. +For commands such as +.I global , +.I open , +.I undo , +and +.I visual +which have potentially more far reaching scope, +the net change in the number of lines in the buffer is +presented at the end of the command, subject to this same threshold. +Thus notification is suppressed during a +.I global +command on the individual commands performed. +.LC +\fBscroll\fR default: scroll=\(12 window +.ZP +Determines the number of logical lines scrolled when an end-of-file +is received from a terminal input in command mode, +and the number of lines printed by a command mode +.I z +command (double the value of +.I scroll ). +.LC +\fBsections\fR default: sections=SHNHH\0HU +.ZP +Specifies the section macros for the \fB[[\fR and \fB]]\fR operations +in +.I open +and +.I visual. +The pairs of characters in the options's value are the names +of the macros which start paragraphs. +.LC +\fBshell\fR, \fBsh\fR default: sh=/bin/sh +.ZP +Gives the path name of the shell forked for +the shell escape command `!', and by the +.I shell +command. +The default is taken from SHELL in the environment, if present. +.LC +\fBshiftwidth\fR, \fBsw\fR default: sw=8 +.ZP +Gives the width a software tab stop, +used in reverse tabbing with \fB^D\fR when using +.I autoindent +to append text, +and by the shift commands. +.LC +\fBshowmatch, sm\fR default: nosm +.ZP +In +.I open +and +.I visual +mode, when a \fB)\fR or \fB}\fR is typed, move the cursor to the matching +\fB(\fR or \fB{\fR for one second if this matching character is on the +screen. Extremely useful with +.I lisp. +.LC +\fBslowopen, slow\fR terminal dependent +.ZP +Affects the display algorithm used in +.I visual +mode, holding off display updating during input of new text to improve +throughput when the terminal in use is both slow and unintelligent. +See +.I "An Introduction to Display Editing with Vi" +for more details. +.LC +\fBtabstop,\ ts\fR default: ts=8 +.ZP +The editor expands tabs in the input file to be on +.I tabstop +boundaries for the purposes of display. +.LC +\fBtaglength,\ tl\fR default: tl=0 +.ZP +Tags are not significant beyond this many characters. +A value of zero (the default) means that all characters are significant. +.LC +\fBtags\fR default: tags=tags /usr/lib/tags +.ZP +A path of files to be used as tag files for the +.I tag +command. +A requested tag is searched for in the specified files, sequentially. +By default, files called +.B tags +are searched for in the current directory and in /usr/lib +(a master file for the entire system). +.LC +\fBterm\fR from environment TERM +.ZP +The terminal type of the output device. +.LC +\fBterse\fR default: noterse +.ZP +Shorter error diagnostics are produced for the experienced user. +.LC +\fBwarn\fR default: warn +.ZP +Warn if there has been `[No write since last change]' before a `!' +command escape. +.LC +\fBwindow\fR default: window=speed dependent +.ZP +The number of lines in a text window in the +.I visual +command. +The default is 8 at slow speeds (600 baud or less), +16 at medium speed (1200 baud), +and the full screen (minus one line) at higher speeds. +.LC +\fBw300,\ w1200\, w9600\fR +.ZP +These are not true options but set +.B window +only if the speed is slow (300), medium (1200), or high (9600), +respectively. +They are suitable for an EXINIT +and make it easy to change the 8/16/full screen rule. +.LC +\fBwrapscan\fR, \fBws\fR default: ws +.ZP +Searches using the regular expressions in addressing +will wrap around past the end of the file. +.LC +\fBwrapmargin\fR, \fBwm\fR default: wm=0 +.ZP +Defines a margin for automatic wrapover of text during input in +.I open +and +.I visual +modes. See +.I "An Introduction to Text Editing with Vi" +for details. +.LC +\fBwriteany\fR, \fBwa\fR default: nowa +.IP +Inhibit the checks normally made before +.I write +commands, allowing a write to any file which the system protection +mechanism will allow. +.NH 1 +Acknowledgements +.PP +Chuck Haley contributed greatly to the early development of +.I ex. +Bruce Englar encouraged the redesign which led to +.I ex +version 1. +Bill Joy wrote versions 1 and 2.0 through 2.7, +and created the framework that users see in the present editor. +Mark Horton added macros and other features and made the +editor work on a large number of terminals and Unix systems. diff --git a/contrib/nvi/docs/USD.doc/exref/ex.summary b/contrib/nvi/docs/USD.doc/exref/ex.summary new file mode 100644 index 000000000000..83084a368ed8 --- /dev/null +++ b/contrib/nvi/docs/USD.doc/exref/ex.summary @@ -0,0 +1,730 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)ex.summary 8.3 (Berkeley) 8/18/96 +.\" +.ds p \v'-0.2'.\v'+0.2' +.ds U \s-2UNIX\s+2 +.ds c \v'-0.2':\v'+0.2' +.nr LL 6.5i +.lt 6.5i +.ll 6.5i +.ds CH +.ds LF Computing Services, U.C. Berkeley +.ds RF April 3, 1979 +.de SP +.sp 1v +.. +.nr PI 3n +.nr PD 0 +.ND +.ps 12 +.ft B +.ce 1 +Ex/Edit Command Summary (Version 2.0) +.sp 1 +.ft R +.nr VS 11 +.nr PS 9 +.2C +.PP +.I Ex +and +.I edit +are text editors, used for creating +and modifying files of text on the \*U +computer system. +.I Edit +is a variant of +.I ex +with features designed to +make it less complicated +to learn and use. +In terms of command syntax and effect +the editors are essentially identical, +and this command summary applies to both. +.PP +The summary is meant as a quick reference +for users already acquainted +with +.I edit +or \fIex\fP. +Fuller explanations of the editors are available +in the documents +.I +Edit: A Tutorial +.R +(a self-teaching introduction) and the +.I +Ex Reference Manual +.R +(the comprehensive reference source for +both \fIedit\fP and \fIex\fP). +Both of these writeups are available in the +Computing Services Library. +.PP +In the examples included with the +summary, commands and text entered by +the user are printed in \fBboldface\fR to +distinguish them from responses printed +by the computer. +.sp 0.45v +.LP +.B +The Editor Buffer +.PP +In order to perform its tasks +the editor sets aside a temporary +work space, +called a \fIbuffer\fR, +separate from the user's permanent +file. +Before starting to work on an existing +file the editor makes a copy of it in the +buffer, leaving the original untouched. +All editing changes are made to the +buffer copy, which must then +be written back to the permanent +file in order to update the +old version. +The buffer disappears +at the end of the editing session. +.sp 0.45v +.LP +.B +Editing: Command and Text Input Modes +.PP +.R +During an editing session there are +two usual modes of operation: +\fIcommand\fP mode and \fItext input\fP +mode. +(This disregards, for the moment, +.I open +and +.I visual +modes, discussed below.) +In command mode, the editor issues a +colon prompt (:) +to show that it is ready to +accept and execute a command. +In text input mode, on the other hand, there is +no prompt and the editor merely accepts text to +be added to the buffer. +Text input mode is initiated by the commands +\fIappend\fP, \fIinsert\fP, and \fIchange\fP, +and is terminated by typing a period as the +first and only character on a line. +.sp 0.45v +.LP +.B +Line Numbers and Command Syntax +.PP +.R +The editor keeps track of lines of text +in the buffer by numbering them consecutively +starting with 1 and renumbering +as lines are added or deleted. +At any given time the editor is positioned +at one of these lines; this position is +called the \fIcurrent line\fP. +Generally, commands that change the +contents of the buffer print the +new current line at the end of their +execution. +.PP +Most commands can be preceded by one or two +line-number addresses which indicate the lines +to be affected. +If one number is given the command operates on +that line only; if two, on an inclusive range +of lines. +Commands that can take line-number prefixes also +assume default prefixes if none are given. +The default assumed by each command is designed +to make it convenient to use in many instances +without any line-number prefix. +For the most part, a command used without a +prefix operates on the current line, +though exceptions to this rule should be noted. +The \fIprint\fP command +by itself, for instance, causes +one line, the current line, to be +printed at the terminal. +.PP +The summary shows the number of line addresses +that can be +prefixed to each command as well as +the defaults assumed if they are omitted. +For example, +.I (.,.) +means that up to 2 line-numbers may be given, +and that if none is given the +command operates on the current line. +(In the address prefix notation, ``.'' stands +for the current line and ``$'' stands for +the last line of the buffer.) +If no such notation appears, no +line-number prefix may be used. +.PP +Some commands take trailing +information; +only +the more important instances of this +are mentioned in the summary. +.sp 0.25v +.LP +.B +Open and Visual Modes +.PP +.R +Besides command and text input modes, +.I ex +and +.I edit +provide on some CRT terminals other modes of editing, +.I open +and +.I visual . +In these modes the cursor can +be moved to individual words +or characters in a line. +The commands then given are very different +from the standard editor commands; most do not appear on the screen when +typed. +.I +An Introduction to Display Editing with Vi +.R +provides a full discussion. +.sp 0.25v +.LP +.B +Special Characters +.PP +.R +.fi +Some characters take on special meanings +when used in context searches +and in patterns given to the \fIsubstitute\fP command. +For \fIedit\fR, these are ``^'' and ``$'', +meaning the beginning and end of a line, +respectively. +.I Ex +has the following additional special characters: +.B +.ce 1 +\&. & * [ ] ~ +.R +To use one of the special characters as its +simple graphic representation +rather than with its special meaning, +precede it by a backslash (\\). +The backslash always has a special meaning. +.1C +.TS +cp10 cp10 cp10 cp10 +ltw(1.0i) lt2w(0.40i)fB ltw(3.0i) ltw(1.8i). +Name Abbr Description Examples +.sp 1.75 +(.)\fBappend a T{ +Begins text input mode, +adding lines to the buffer after +the line specified. Appending continues +until ``.'' is typed alone at the +beginning of a new line, followed by +a carriage return. \fI0a\fR places +lines at the beginning of the buffer. +T} T{ +.nf +\fR:\fBa +Three lines of text +are added to the buffer +after the current line. +\*p +.R +\*c +.fi +T} +.SP +\fR(.,.)\fBchange c T{ +Deletes indicated line(s) and +initiates text input mode to +replace them with new text which follows. +New text is terminated the same way +as with \fIappend\fR. +T} T{ +.nf +:\fB5,6c +Lines 5 and 6 are +deleted and replaced by +these three lines. +\*p +.R +\*c +.fi +T} +.SP +\fR(.,.)\fBcopy \fIaddr co T{ +Places a copy of the specified lines +after the line indicated by \fIaddr\fR. +The example places a copy of lines 8 through +12, inclusive, after line 25. +T} T{ +.nf +\fR:\fB8,12co 25 +\fRLast line copied is printed +\fR\*c +.fi +T} +.SP +\fR(.,.)\fBdelete d T{ +Removes lines from the buffer +and prints the current line after the deletion. +T} T{ +.nf +\fR:\fB13,15d +\fRNew current line is printed +\*c +.fi +T} +.TE +.sp 0.5v +.TS +ltw(1.0i) lt2w(0.40i)fB ltw(3.0i) ltw(1.8i). +T{ +\fBedit \fIfile\fP +.br +\fBedit! \fIfile\fP +T} T{ +e +.br +e! +T} T{ +.fi +\fRClears the editor buffer and then +copies into it the named \fIfile\fR, +which becomes the current file. +This is a way of shifting to a different +file +without leaving the editor. +The editor issues a warning +message if this command is used before +saving changes +made to the file already in the buffer; +using the form \fBe!\fR overrides this protective mechanism. +T} T{ +.nf +\fR:\fBe ch10\fR +No write since last change +:\fBe! ch10\fR +"ch10" 3 lines, 62 characters +\*c +.fi +T} +.SP +\fBfile \fIname\fR f T{ +\fRIf followed by a \fIname\fR, renames +the current file to \fIname\fR. +If used without \fIname\fR, prints +the name of the current file. +T} T{ +.nf +\fR:\fBf ch9 +\fR"ch9" [Modified] 3 lines ... +:\fBf +\fR"ch9" [Modified] 3 lines ... +\*c +.fi +T} +.SP +(1,$)\fBglobal g \fBglobal/\fIpattern\fB/\fIcommands T{ +.nf +:\fBg/nonsense/d +\fR\*c +.fi +T} +\fR(1,$)\fBglobal! g!\fR or \fBv T{ +Searches the entire buffer (unless a smaller +range is specified by line-number prefixes) and +executes \fIcommands\fR on every line with +an expression matching \fIpattern\fR. +The second form, abbreviated +either \fBg!\fR or \fBv\fR, +executes \fIcommands\fR on lines that \fIdo +not\fR contain the expression \fIpattern\fR. +T} \^ +.SP +\fR(.)\fBinsert i T{ +Inserts new lines of text immediately before the specified line. +Differs from +.I append +only in that text is placed before, rather than after, the indicated line. +In other words, \fB1i\fR has the same effect as \fB0a\fR. +T} T{ +.nf +:\fB1i +These lines of text will +be added prior to line 1. +\&. +\fR: +.fi +T} +.SP +\fR(.,.+1)\fBjoin j T{ +Join lines together, adjusting white space (spaces +and tabs) as necessary. +T} T{ +.nf +:\fB2,5j\fR +Resulting line is printed +: +.fi +T} +.TE +.bp +.TS +cp10 cp10 cp10 cp10 +ltw(1.0i) lt2w(0.40i)fB ltw(3.0i) ltw(1.8i). +Name Abbr Description Examples +.sp 1.75 +\fR(.,.)\fBlist l T{ +\fRPrints lines in a more +unambiguous way than the \fIprint\fR +command does. The end of a line, +for example, is marked with a ``$'', +and tabs printed as ``^I''. +T} T{ +.nf +:\fB9l +\fRThis is line 9$ +\*c +.fi +T} +.TE +.sp 0.5v +.TS +ltw(1.0i) lt2w(0.40i)fB ltw(3.0i) ltw(1.8i). +\fR(.,.)\fBmove \fIaddr\fB m T{ +\fRMoves the specified lines +to a position after the line +indicated by \fIaddr\fR. +T} T{ +.nf +\fR:\fB12,15m 25\fR +New current line is printed +\*c +.fi +T} +.SP +\fR(.,.)\fBnumber nu T{ +Prints each line preceded +by its buffer line number. +T} T{ +.nf +\fR:\fBnu +\0\0\fR10\0 This is line 10 +\*c +.fi +T} +.SP +\fR(.)\fBopen o T{ +Too involved to discuss here, +but if you enter open mode +accidentally, press +the \s-2ESC\s0 key followed by +\fBq\fR to +get back into normal editor +command mode. +\fIEdit\fP is designed to +prevent accidental use of +the open command. +T} +.SP +\fBpreserve pre T{ +Saves a copy of the current buffer contents as though the system had +just crashed. This is for use in an emergency when a +.I write +command has failed and you don't know how else to save your work.\(dg +T} T{ +.nf +:\fBpreserve\fR +File preserved. +: +.fi +T} +.SP +\fR(.,.)\fBprint p Prints the text of line(s). T{ +.nf +:\fB+2,+3p\fR +The second and third lines +after the current line +: +.fi +T} +.TE +.FS +.ll 6.5i +\(dg You should seek assistance from a system administrator as soon as +possible after saving a file with the +.I preserve +command, because the preserved copy of the file is saved in a +directory used to store temporary files, and thus, the preserved +copy may only be available for a short period of time. +.FE +.SP +.nf +.TS +ltw(1.0i) lt2w(0.40i)fB ltw(3.0i) ltw(1.8i). +T{ +.nf +\fBquit +quit! +.fi +T} T{ +.nf +q +q! +T} T{ +.fi +\fREnds the editing session. +You will receive a +warning if you have changed the buffer +since last writing its contents +to the file. In this event you +must either type \fBw\fR to write, +or type \fBq!\fR to exit from +the editor without saving your changes. +T} T{ +.nf +\fR:\fBq +\fRNo write since last change +:\fBq! +\fR% +.fi +T} +.SP +\fR(.)\fBread \fIfile\fP r T{ +.fi +\fRPlaces a copy of \fIfile\fR in the +buffer after the specified line. +Address 0 is permissible and causes +the copy of \fIfile\fR to be placed +at the beginning of the buffer. +The \fIread\fP command does not +erase any text already in the buffer. +If no line number is specified, +\fIfile\fR is placed after the +current line. +T} T{ +.nf +\fR:\fB0r newfile +\fR"newfile" 5 lines, 86 characters +\*c +.fi +T} +.SP +\fBrecover \fIfile\fP rec T{ +.fi +Retrieves a copy of the editor buffer +after a system crash, editor crash, +phone line disconnection, or +\fIpreserve\fR command. +T} +.SP +\fR(.,.)\fBsubstitute s T{ +.nf +\fBsubstitute/\fIpattern\fB/\fIreplacement\fB/ +substitute/\fIpattern\fB/\fIreplacement\fB/gc +.fi +\fRReplaces the first occurrence of \fIpattern\fR +on a line +with \fIreplacement\fP. +Including a \fBg\fR after the command +changes all occurrences of \fIpattern\fP +on the line. +The \fBc\fR option allows the user to +confirm each substitution before it is +made; see the manual for details. +T} T{ +.nf +:\fB3p +\fRLine 3 contains a misstake +:\fBs/misstake/mistake/ +\fRLine 3 contains a mistake +\*c +.fi +T} +.TE +.bp +.TS +cp10 cp10 cp10 cp10 +ltw(1.0i) lt2w(0.40i)fB ltw(3.0i) ltw(1.8i). +Name Abbr Description Examples +.sp 1.75 +\fBundo u T{ +.fi +\fRReverses the changes made in +the buffer by the last buffer-editing +command. +Note that this example contains +a notification about the number of +lines affected. +T} T{ +.nf +\fR:\fB1,15d +\fR15 lines deleted +new line number 1 is printed +:\fBu +\fR15 more lines in file ... +old line number 1 is printed +\*c +.fi +T} +.SP +\fR(1,$)\fBwrite \fIfile\fR w T{ +.fi +\fRCopies data from the buffer onto +a permanent file. If no \fIfile\fR +is named, the current filename +is used. +The file is automatically created +if it does not yet exist. +A response containing the number of +lines and characters in the file +indicates that the write +has been completed successfully. +The editor's built-in protections +against overwriting existing files +will in some circumstances +inhibit a write. +The form \fBw!\fR forces the +write, confirming that +an existing file is to be overwritten. +T} T{ +.nf +\fR:\fBw +\fR"file7" 64 lines, 1122 characters +:\fBw file8 +\fR"file8" File exists ... +:\fBw! file8 +\fR"file8" 64 lines, 1122 characters +\*c +.fi +T} +\fR(1,$)\fBwrite! \fIfile\fP w! \^ \^ +.TE +.sp 0.5v +.TS +ltw(1.0i) lt2w(0.40i)fB ltw(3.0i) ltw(1.8i). +\fR(.)\fBz \fIcount\fP z T{ +.fi +\fRPrints a screen full of text starting +with the line indicated; +or, if \fIcount\fR is specified, +prints that number of lines. +Variants of the \fIz\fR command +are described in the manual. +T} +.SP +\fB!\fIcommand T{ +.fi +Executes the remainder of the line +after \fB!\fR as a \*U command. +The buffer is unchanged by this, and +control is returned to the editor when +the execution of \fIcommand\fR is complete. +T} T{ +.nf +\fR:\fB!date +\fRFri Jun 9 12:15:11 PDT 1978 +! +\*c +.fi +T} +.SP +\fRcontrol-d T{ +.fi +Prints the next \fIscroll\fR of text, +normally half of a screen. See the +manual for details of the \fIscroll\fR +option. +T} +.SP +\fR(.+1)<cr> T{ +.fi +An address alone followed by a carriage +return causes the line to be printed. +A carriage return by itself prints the +line following the current line. +T} T{ +.nf +:\fR<cr> +the line after the current line +\*c +.fi +T} +.TE +.sp 0.5v +.TS +ltw(1.0i) lt2w(0.40i)fB ltw(3.0i) ltw(1.8i). +\fB/\fIpattern\fB/ T{ +.fi +\fRSearches for the next line in which +\fIpattern\fR occurs and prints it. +T} T{ +.nf +\fR:\fB/This pattern/ +\fRThis pattern next occurs here. +\*c +.fi +T} +.SP +\fB// T{ +Repeats the most recent search. +T} T{ +.nf +\fR:\fB// +\fRThis pattern also occurs here. +\*c +.fi +T} +.SP +\fB?\fIpattern\fB? T{ +Searches in the reverse direction +for \fIpattern\fP. +T} +.SP +\fB?? T{ +Repeats the most recent search, +moving in the reverse direction +through the buffer. +T} +.TE diff --git a/contrib/nvi/docs/USD.doc/vi.man/Makefile b/contrib/nvi/docs/USD.doc/vi.man/Makefile new file mode 100644 index 000000000000..54338646791f --- /dev/null +++ b/contrib/nvi/docs/USD.doc/vi.man/Makefile @@ -0,0 +1,16 @@ +# @(#)Makefile 8.7 (Berkeley) 8/18/96 + +ROFF= groff + +all: vi.0 vi.0.ps + +vi.0: vi.1 + ${ROFF} -man -Tascii < vi.1 > $@ + chmod 444 $@ + +vi.0.ps: vi.1 + ${ROFF} -man < vi.1 > $@ + chmod 444 $@ + +clean: + rm -f vi.0 vi.0.ps diff --git a/contrib/nvi/docs/USD.doc/vi.man/spell.ok b/contrib/nvi/docs/USD.doc/vi.man/spell.ok new file mode 100644 index 000000000000..80ebcaba829d --- /dev/null +++ b/contrib/nvi/docs/USD.doc/vi.man/spell.ok @@ -0,0 +1,179 @@ +Ar +Bostic +CDPATH +COLUMNSXX +Cscope +Ds +EXINIT +Ee +Ev +Fa +Ff +Fl +HUnhsh +IPLPPPQPP +LIpplpipbp +Li +Lite +NEXINIT +NHSHH +Nex +Nn +POSIX +Pp +QQ +SIGWINCHXX +Std +Sy +TMPDIR +Tt +USD +Unmap +VI +Vi +XXXX +ZZ +ags +ai +altwerase +ap +autoindent +autoprint +autowrite +aw +bf +bigwords +cd +cdpath +cedit +cmd +co +creens +cs +ctags +db +dbopen +dd +di +dir +dit +doc +docs +eFRrsv +eFRrv +eFlRrv +ead +eb +edcompatible +egrep +elete +errorbells +esc +exrc +exu +fg +filec +hange +hardtabs +ht +ic +iclower +ignorecase +ile +ind +ious +ist +ize +keytime +leftright +lhs +li +libc +lobal +lp +matchtime +mber +mesg +mk +modeful +modeline +modelines +nex +nexrc +nk +nonblank +nooption +noprint +nsert +nul +nvi +oin +onnections +ove +ppend +prev +pu +readonly +rec +recdir +redist +rhs +rint +rk +ro +rsion +sccs +scr +se +searchincr +sh +shareware +shellmeta +shiftwidth +showmatch +showmode +sidescroll +slowopen +sm +smd +sourceany +su +sual +sw +ta +tabstop +taglength +tagn +tagp +tagstring +th's +tildeop +tl +tmp +tr +ts +ttytype +ttywerase +ubstitute +uffers +uit +unm +urce +var +ve +vi +viu +wa +wi +windowname +wl +wm +wn +wq +wraplen +wrapmargin +wrapscan +writeany +ws +ya +yy diff --git a/contrib/nvi/docs/USD.doc/vi.man/vi.1 b/contrib/nvi/docs/USD.doc/vi.man/vi.1 new file mode 100644 index 000000000000..22aee3e7e952 --- /dev/null +++ b/contrib/nvi/docs/USD.doc/vi.man/vi.1 @@ -0,0 +1,1608 @@ +.\" Copyright (c) 1994 +.\" The Regents of the University of California. All rights reserved. +.\" Copyright (c) 1994, 1995, 1996 +.\" Keith Bostic. All rights reserved. +.\" +.\" This document may not be republished without written permission from +.\" Keith Bostic. +.\" +.\" See the LICENSE file for redistribution information. +.\" +.\" @(#)vi.1 8.51 (Berkeley) 10/10/96 +.\" +.TH VI 1 "October 10, 1996" +.UC +.SH NAME +ex, vi, view \- text editors +.SH SYNOPSIS +.B ex +[\c +.B -eFRrSsv\c +] [\c +.BI -c " cmd"\c +] [\c +.BI -t " tag"\c +] [\c +.BI -w " size"\c +] [file ...] +.br +.B vi +[\c +.B -eFlRrSv\c +] [\c +.BI -c " cmd"\c +] [\c +.BI -t " tag"\c +] [\c +.BI -w " size"\c +] [file ...] +.br +.B view +[\c +.B -eFRrSv\c +] [\c +.BI -c " cmd"\c +] [\c +.BI -t " tag"\c +] [\c +.BI -w " size"\c +] [file ...] +.SH LICENSE +The vi program is freely redistributable. You are welcome to copy, +modify and share it with others under the conditions listed in the +LICENSE file. If any company (not individual!) finds vi sufficiently +useful that you would have purchased it, or if any company wishes to +redistribute it, contributions to the authors would be appreciated. +.SH DESCRIPTION +.I \&Vi +is a screen oriented text editor. +.I \&Ex +is a line-oriented text editor. +.I \&Ex +and +.I \&vi +are different interfaces to the same program, +and it is possible to switch back and forth during an edit session. +.I View +is the equivalent of using the +.B \-R +(read-only) option of +.IR \&vi . +.PP +This manual page is the one provided with the +.I nex/nvi +versions of the +.I ex/vi +text editors. +.I Nex/nvi +are intended as bug-for-bug compatible replacements for the original +Fourth Berkeley Software Distribution (4BSD) +.I \&ex +and +.I \&vi +programs. +For the rest of this manual page, +.I nex/nvi +is used only when it's necessary to distinguish it from the historic +implementations of +.IR ex/vi . +.PP +This manual page is intended for users already familiar with +.IR ex/vi . +Anyone else should almost certainly read a good tutorial on the +editor before this manual page. +If you're in an unfamiliar environment, and you absolutely have to +get work done immediately, read the section after the options +description, entitled ``Fast Startup''. +It's probably enough to get you going. +.PP +The following options are available: +.TP +.B \-c +Execute +.B cmd +immediately after starting the edit session. +Particularly useful for initial positioning in the file, however +.B cmd +is not limited to positioning commands. +This is the POSIX 1003.2 interface for the historic ``+cmd'' syntax. +.I Nex/nvi +supports both the old and new syntax. +.TP +.B \-e +Start editing in ex mode, as if the command name were +.IR \&ex . +.TP +.B \-F +Don't copy the entire file when first starting to edit. +(The default is to make a copy in case someone else modifies +the file during your edit session.) +.TP +.B \-l +Start editing with the lisp and showmatch options set. +.TP +.B \-R +Start editing in read-only mode, as if the command name was +.IR view , +or the +.B readonly +option was set. +.TP +.B \-r +Recover the specified files, or, if no files are specified, +list the files that could be recovered. +If no recoverable files by the specified name exist, +the file is edited as if the +.B \-r +option had not been specified. +.TP +.B \-S +Run with the +.B secure +edit option set, disallowing all access to external programs. +.TP +.B \-s +Enter batch mode; applicable only to +.I \&ex +edit sessions. +Batch mode is useful when running +.I \&ex +scripts. +Prompts, informative messages and other user oriented message +are turned off, +and no startup files or environmental variables are read. +This is the POSIX 1003.2 interface for the historic ``\-'' argument. +.I \&Nex/nvi +supports both the old and new syntax. +.TP +.B \-t +Start editing at the specified tag. +(See +.IR ctags (1)). +.TP +.B \-w +Set the initial window size to the specified number of lines. +.TP +.B \-v +Start editing in vi mode, as if the command name was +.I \&vi +or +.IR view . +.PP +Command input for +.I ex/vi +is read from the standard input. +In the +.I \&vi +interface, it is an error if standard input is not a terminal. +In the +.I \&ex +interface, if standard input is not a terminal, +.I \&ex +will read commands from it regardless, however, the session will be a +batch mode session, exactly as if the +.B \-s +option had been specified. +.PP +.I Ex/vi +exits 0 on success, and greater than 0 if an error occurs. +.SH FAST STARTUP +This section will tell you the minimum amount that you need to +do simple editing tasks using +.IR \&vi . +If you've never used any screen editor before, you're likely to have +problems even with this simple introduction. +In that case you should find someone that already knows +.I \&vi +and have them walk you through this section. +.PP +.I \&Vi +is a screen editor. +This means that it takes up almost the entire screen, displaying part +of the file on each screen line, except for the last line of the screen. +The last line of the screen is used for you to give commands to +.IR \&vi , +and for +.I \&vi +to give information to you. +.PP +The other fact that you need to understand is that +.I \&vi +is a modeful editor, i.e. you are either entering text or you +are executing commands, and you have to be in the right mode +to do one or the other. +You will be in command mode when you first start editing a file. +There are commands that switch you into input mode. +There is only one key that takes you out of input mode, +and that is the <escape> key. +(Key names are written using less-than and greater-than signs, e.g. +<escape> means the ``escape'' key, usually labeled ``esc'' on your +terminal's keyboard.) +If you're ever confused as to which mode you're in, +keep entering the <escape> key until +.I \&vi +beeps at you. +(Generally, +.I \&vi +will beep at you if you try and do something that's not allowed. +It will also display error messages.) +.PP +To start editing a file, enter the command ``vi file_name<carriage-return>''. +The command you should enter as soon as you start editing is +``:set verbose showmode<carriage-return>''. +This will make the editor give you verbose error messages and display +the current mode at the bottom of the screen. +.PP +The commands to move around the file are: +.TP +.B h +Move the cursor left one character. +.TP +.B j +Move the cursor down one line. +.TP +.B k +Move the cursor up one line. +.TP +.B l +Move the cursor right one character. +.TP +.B <cursor-arrows> +The cursor arrow keys should work, too. +.TP +.B /text<carriage-return> +Search for the string ``text'' in the file, +and move the cursor to its first character. +.PP +The commands to enter new text are: +.TP +.B a +Append new text, +.I after +the cursor. +.TP +.B i +Insert new text, +.I before +the cursor. +.TP +.B o +Open a new line below the line the cursor is on, and start +entering text. +.TP +.B O +Open a new line above the line the cursor is on, and start +entering text. +.TP +.B <escape> +Once you've entered input mode using the one of the +.BR \&a , +.BR \&i , +.BR \&O +or +.B \&o +commands, use +.B <escape> +to quit entering text and return to command mode. +.PP +The commands to copy text are: +.TP +.B yy +Copy the line the cursor is on. +.TP +.B p +Append the copied line after the line the cursor is on. +.PP +The commands to delete text are: +.TP +.B dd +Delete the line the cursor is on. +.TP +.B x +Delete the character the cursor is on. +.PP +The commands to write the file are: +.TP +.B :w<carriage-return> +Write the file back to the file with the name that you originally used +as an argument on the +.I \&vi +command line. +.TP +.B ":w file_name<carriage-return>" +Write the file back to the file with the name ``file_name''. +.PP +The commands to quit editing and exit the editor are: +.TP +.B :q<carriage-return> +Quit editing and leave vi (if you've modified the file, but not +saved your changes, +.I \&vi +will refuse to quit). +.TP +.B :q!<carriage-return> +Quit, discarding any modifications that you may have made. +.PP +One final caution. +Unusual characters can take up more than one column on the screen, +and long lines can take up more than a single screen line. +The above commands work on ``physical'' characters and lines, +i.e. they affect the entire line no matter how many screen lines it +takes up and the entire character no matter how many screen columns +it takes up. +.SH VI COMMANDS +The following section describes the commands available in the command +mode of the +.I \&vi +editor. +In each entry below, the tag line is a usage synopsis for the command +character. +.PP +.TP +.B "[count] <control-A>" +Search forward +.I count +times for the current word. +.TP +.B "[count] <control-B>" +Page backwards +.I count +screens. +.TP +.B "[count] <control-D>" +Scroll forward +.I count +lines. +.TP +.B "[count] <control-E>" +Scroll forward +.I count +lines, leaving the current line and column as is, if possible. +.TP +.B "[count] <control-F>" +Page forward +.I count +screens. +.TP +.B "<control-G>" +Display the file information. +.TP +.B "<control-H>" +.TP +.B "[count] h" +Move the cursor back +.I count +characters in the current line. +.TP +.B "[count] <control-J>" +.TP +.B "[count] <control-N>" +.TP +.B "[count] j" +Move the cursor down +.I count +lines without changing the current column. +.TP +.B "<control-L>" +.TP +.B "<control-R>" +Repaint the screen. +.TP +.B "[count] <control-M>" +.TP +.B "[count] +" +Move the cursor down +.I count +lines to the first nonblank character of that line. +.TP +.B "[count] <control-P>" +.TP +.B "[count] k" +Move the cursor up +.I count +lines, without changing the current column. +.TP +.B "<control-T>" +Return to the most recent tag context. +.TP +.B "<control-U>" +Scroll backwards +.I count +lines. +.TP +.B "<control-W>" +Switch to the next lower screen in the window, or, to the first +screen if there are no lower screens in the window. +.TP +.B "<control-Y>" +Scroll backwards +.I count +lines, leaving the current line and column as is, if possible. +.TP +.B "<control-Z>" +Suspend the current editor session. +.TP +.B "<escape>" +Execute +.I \&ex +commands or cancel partial commands. +.TP +.B "<control-]>" +Push a tag reference onto the tag stack. +.TP +.B "<control-^>" +Switch to the most recently edited file. +.TP +.B "[count] <space>" +.TP +.B "[count] l" +Move the cursor forward +.I count +characters without changing the current line. +.TP +.B "[count] ! motion shell-argument(s)" +Replace text with results from a shell command. +.TP +.B "[count] # #|+|-" +Increment or decrement the cursor number. +.TP +.B "[count] $" +Move the cursor to the end of a line. +.TP +.B "%" +Move to the matching character. +.TP +.B "&" +Repeat the previous substitution command on the current line. +.TP +.B "'<character>" +.TP +.B "`<character>" +Return to a context marked by the character +.IR <character> . +.TP +.B "[count] (" +Back up +.I count +sentences. +.TP +.B "[count] )" +Move forward +.I count +sentences. +.TP +.B "[count] ," +Reverse find character +.I count +times. +.TP +.B "[count] -" +Move to first nonblank of the previous line, +.I count +times. +.TP +.B "[count] ." +Repeat the last +.I \&vi +command that modified text. +.TP +.B "/RE<carriage-return>" +.TP +.B "/RE/ [offset]<carriage-return>" +.TP +.B "?RE<carriage-return>" +.TP +.B "?RE? [offset]<carriage-return>" +.TP +.B "N" +.TP +.B "n" +Search forward or backward for a regular expression. +.TP +.B "0" +Move to the first character in the current line. +.TP +.B ":" +Execute an ex command. +.TP +.B "[count] ;" +Repeat the last character find +.I count +times. +.TP +.B "[count] < motion" +.TP +.B "[count] > motion" +Shift lines left or right. +.TP +.B "@ buffer" +Execute a named buffer. +.TP +.B "[count] A" +Enter input mode, appending the text after the end of the line. +.TP +.B "[count] B" +Move backwards +.I count +bigwords. +.TP +.B "[buffer] [count] C" +Change text from the current position to the end-of-line. +.TP +.B "[buffer] D" +Delete text from the current position to the end-of-line. +.TP +.B "[count] E" +Move forward +.I count +end-of-bigwords. +.TP +.B "[count] F <character>" +Search +.I count +times backward through the current line for +.IR <character> . +.TP +.B "[count] G" +Move to line +.IR count , +or the last line of the file if +.I count +not specified. +.TP +.B "[count] H" +Move to the screen line +.I "count - 1" +lines below the top of the screen. +.TP +.B "[count] I" +Enter input mode, inserting the text at the beginning of the line. +.TP +.B "[count] J" +Join lines. +.TP +.B "[count] L" +Move to the screen line +.I "count - 1" +lines above the bottom of the screen. +.TP +.B " M" +Move to the screen line in the middle of the screen. +.TP +.B "[count] O" +Enter input mode, appending text in a new line above the current line. +.TP +.B "[buffer] P" +Insert text from a buffer. +.TP +.B "Q" +Exit +.I \&vi +(or visual) mode and switch to +.I \&ex +mode. +.TP +.B "[count] R" +Enter input mode, replacing the characters in the current line. +.TP +.B "[buffer] [count] S" +Substitute +.I count +lines. +.TP +.B "[count] T <character>" +Search backwards, +.I count +times, +through the current line for the character +.I after +the specified +.IR <character> . +.TP +.B "U" +Restore the current line to its state before the cursor last +moved to it. +.TP +.B "[count] W" +Move forward +.I count +bigwords. +.TP +.B "[buffer] [count] X" +Delete +.I count +characters before the cursor. +.TP +.B "[buffer] [count] Y" +Copy (or ``yank'') +.I count +lines into the specified buffer. +.TP +.B "ZZ" +Write the file and exit +.IR \&vi . +.TP +.B "[count] [[" +Back up +.I count +section boundaries. +.TP +.B "[count] ]]" +Move forward +.I count +section boundaries. +.TP +.B "\&^" +Move to first nonblank character on the current line. +.TP +.B "[count] _" +Move down +.I "count - 1" +lines, to the first nonblank character. +.TP +.B "[count] a" +Enter input mode, appending the text after the cursor. +.TP +.B "[count] b" +Move backwards +.I count +words. +.TP +.B "[buffer] [count] c motion" +Change a region of text. +.TP +.B "[buffer] [count] d motion" +Delete a region of text. +.TP +.B "[count] e" +Move forward +.I count +end-of-words. +.TP +.B "[count] f<character>" +Search forward, +.I count +times, through the rest of the current line for +.IR <character> . +.TP +.B "[count] i" +Enter input mode, inserting the text before the cursor. +.TP +.B "m <character>" +Save the current context (line and column) as +.IR <character> . +.TP +.B "[count] o" +Enter input mode, appending text in a new line under the current line. +.TP +.B "[buffer] p" +Append text from a buffer. +.TP +.B "[count] r <character>" +Replace +.I count +characters. +.TP +.B "[buffer] [count] s" +Substitute +.I count +characters in the current line starting with the current character. +.TP +.B "[count] t <character>" +Search forward, +.I count +times, through the current line for the character immediately +.I before +.IR <character> . +.TP +.B "u" +Undo the last change made to the file. +.TP +.B "[count] w" +Move forward +.I count +words. +.TP +.B "[buffer] [count] x" +Delete +.I count +characters. +.TP +.B "[buffer] [count] y motion" +Copy (or ``yank'') +a text region specified by the +.I count +and motion into a buffer. +.TP +.B "[count1] z [count2] -|.|+|^|<carriage-return>" +Redraw, optionally repositioning and resizing the screen. +.TP +.B "[count] {" +Move backward +.I count +paragraphs. +.TP +.B "[count] |" +Move to a specific +.I column +position on the current line. +.TP +.B "[count] }" +Move forward +.I count +paragraphs. +.TP +.B "[count] ~" +Reverse the case of the next +.I count +character(s). +.TP +.B "[count] ~ motion" +Reverse the case of the characters in a text region specified by the +.I count +and +.IR motion . +.TP +.B "<interrupt>" +Interrupt the current operation. +.SH VI TEXT INPUT COMMANDS +The following section describes the commands available in the text +input mode of the +.I \&vi +editor. +.PP +.TP +.B "<nul>" +Replay the previous input. +.TP +.B "<control-D>" +Erase to the previous +.B shiftwidth +column boundary. +.TP +.B "^<control-D>" +Erase all of the autoindent characters, and reset the autoindent level. +.TP +.B "0<control-D>" +Erase all of the autoindent characters. +.TP +.B "<control-T>" +Insert sufficient +.I <tab> +and +.I <space> +characters to move forward to the next +.B shiftwidth +column boundary. +.TP +.B "<erase> +.TP +.B "<control-H>" +Erase the last character. +.TP +.B "<literal next>" +Quote the next character. +.TP +.B "<escape> +Resolve all text input into the file, and return to command mode. +.TP +.B "<line erase>" +Erase the current line. +.TP +.B "<control-W>" +.TP +.B "<word erase>" +Erase the last word. +The definition of word is dependent on the +.B altwerase +and +.B ttywerase +options. +.TP +.B "<control-X>[0-9A-Fa-f]+" +Insert a character with the specified hexadecimal value into the text. +.TP +.B "<interrupt>" +Interrupt text input mode, returning to command mode. +.SH EX COMMANDS +The following section describes the commands available in the +.I \&ex +editor. +In each entry below, the tag line is a usage synopsis for the command. +.PP +.TP +.B "<end-of-file>" +Scroll the screen. +.TP +.B "! argument(s)" +.TP +.B "[range]! argument(s)" +Execute a shell command, or filter lines through a shell command. +.TP +.B \&" +A comment. +.TP +.B "[range] nu[mber] [count] [flags]" +.TP +.B "[range] # [count] [flags]" +Display the selected lines, each preceded with its line number. +.TP +.B "@ buffer" +.TP +.B "* buffer" +Execute a buffer. +.TP +.B "[line] a[ppend][!]" +The input text is appended after the specified line. +.TP +.B "[range] c[hange][!] [count]" +The input text replaces the specified range. +.TP +.B "cs[cope] add | find | help | kill | reset" +Execute a Cscope command. +.TP +.B "[range] d[elete] [buffer] [count] [flags]" +Delete the lines from the file. +.TP +.B "di[splay] b[uffers] | c[onnections] | s[creens] | t[ags]" +Display buffers, Cscope connections, screens or tags. +.TP +.B "[Ee][dit][!] [+cmd] [file]" +.TP +.B "[Ee]x[!] [+cmd] [file]" +Edit a different file. +.TP +.B "exu[sage] [command]" +Display usage for an +.I \&ex +command. +.TP +.B "f[ile] [file]" +Display and optionally change the file name. +.TP +.B "[Ff]g [name]" +.I \&Vi +mode only. +Foreground the specified screen. +.TP +.B "[range] g[lobal] /pattern/ [commands]" +.TP +.B "[range] v /pattern/ [commands]" +Apply commands to lines matching (or not matching) a pattern. +.TP +.B "he[lp]" +Display a help message. +.TP +.B "[line] i[nsert][!]" +The input text is inserted before the specified line. +.TP +.B "[range] j[oin][!] [count] [flags]" +Join lines of text together. +.TP +.B "[range] l[ist] [count] [flags]" +Display the lines unambiguously. +.TP +.B "map[!] [lhs rhs]" +Define or display maps (for +.I \&vi +only). +.TP +.B "[line] ma[rk] <character>" +.TP +.B "[line] k <character>" +Mark the line with the mark +.IR <character> . +.TP +.B "[range] m[ove] line" +Move the specified lines after the target line. +.TP +.B "mk[exrc][!] file" +Write the abbreviations, editor options and maps to the specified +file. +.TP +.B "[Nn][ext][!] [file ...]" +Edit the next file from the argument list. +.TP +.B "[line] o[pen] /pattern/ [flags]" +Enter open mode. +.TP +.B "pre[serve]" +Save the file in a form that can later be recovered using the +.I \&ex +.B \-r +option. +.TP +.B "[Pp]rev[ious][!]" +Edit the previous file from the argument list. +.TP +.B "[range] p[rint] [count] [flags]" +Display the specified lines. +.TP +.B "[line] pu[t] [buffer]" +Append buffer contents to the current line. +.TP +.B "q[uit][!]" +End the editing session. +.TP +.B "[line] r[ead][!] [file]" +Read a file. +.TP +.B "rec[over] file" +Recover +.I file +if it was previously saved. +.TP +.B "res[ize] [+|-]size" +.I \&Vi +mode only. +Grow or shrink the current screen. +.TP +.B "rew[ind][!]" +Rewind the argument list. +.TP +.B "se[t] [option[=[value]] ...] [nooption ...] [option? ...] [all]" +Display or set editor options. +.TP +.B "sh[ell]" +Run a shell program. +.TP +.B "so[urce] file" +Read and execute +.I \&ex +commands from a file. +.TP +.B "[range] s[ubstitute] [/pattern/replace/] [options] [count] [flags]" +.TP +.B "[range] & [options] [count] [flags]" +.TP +.B "[range] ~ [options] [count] [flags]" +Make substitutions. +.TP +.B "su[spend][!]" +.TP +.B "st[op][!]" +.TP +.B <suspend> +Suspend the edit session. +.TP +.B "[Tt]a[g][!] tagstring" +Edit the file containing the specified tag. +.TP +.B "tagn[ext][!]" +Edit the file containing the next context for the current tag. +.TP +.B "tagp[op][!] [file | number]" +Pop to the specified tag in the tags stack. +.TP +.B "tagp[rev][!]" +Edit the file containing the previous context for the current tag. +.TP +.B "unm[ap][!] lhs" +Unmap a mapped string. +.TP +.B "ve[rsion]" +Display the version of the +.I \&ex/vi +editor. +.TP +.B "[line] vi[sual] [type] [count] [flags]" +.I \&Ex +mode only. +Enter +.IR \&vi . +.TP +.B "[Vi]i[sual][!] [+cmd] [file]" +.I \&Vi +mode only. +Edit a new file. +.TP +.B "viu[sage] [command]" +Display usage for a +.I \&vi +command. +.TP +.B "[range] w[rite][!] [>>] [file]" +.TP +.B "[range] w[rite] [!] [file]" +.TP +.B "[range] wn[!] [>>] [file]" +.TP +.B "[range] wq[!] [>>] [file]" +Write the file. +.TP +.B "[range] x[it][!] [file]" +Write the file if it has been modified. +.TP +.B "[range] ya[nk] [buffer] [count]" +Copy the specified lines to a buffer. +.TP +.B "[line] z [type] [count] [flags]" +Adjust the window. +.SH SET OPTIONS +There are a large number of options that may be set (or unset) to +change the editor's behavior. +This section describes the options, their abbreviations and their +default values. +.PP +In each entry below, the first part of the tag line is the full name +of the option, followed by any equivalent abbreviations. +The part in square brackets is the default value of the option. +Most of the options are boolean, i.e. they are either on or off, +and do not have an associated value. +.PP +Options apply to both +.I \&ex +and +.I \&vi +modes, unless otherwise specified. +.PP +.TP +.B "altwerase [off]" +.I \&Vi +only. +Select an alternate word erase algorithm. +.TP +.B "autoindent, ai [off]" +Automatically indent new lines. +.TP +.B "autoprint, ap [off]" +.I \&Ex +only. +Display the current line automatically. +.TP +.B "autowrite, aw [off]" +Write modified files automatically when changing files. +.\" I cannot get a double quote to print between the square brackets +.\" to save my life. The ONLY way I've been able to get this to work +.\" is with the .tr command. +.tr Q" +.ds ms backup [QQ] +.TP +.B "\*(ms" +.tr QQ +Backup files before they are overwritten. +.TP +.B "beautify, bf [off]" +Discard control characters. +.TP +.B "cdpath [environment variable CDPATH, or current directory]" +The directory paths used as path prefixes for the +.B cd +command. +.TP +.B "cedit [no default]" +Set the character to edit the colon command-line history. +.TP +.B "columns, co [80]" +Set the number of columns in the screen. +.TP +.B "comment [off]" +.I \&Vi +only. +Skip leading comments in shell, C and C++ language files. +.TP +.B "directory, dir [environment variable TMPDIR, or /tmp]" +The directory where temporary files are created. +.TP +.B "edcompatible, ed [off]" +Remember the values of the ``c'' and ``g'' suffices to the +.B substitute +commands, instead of initializing them as unset for each new +command. +.TP +.B "errorbells, eb [off]" +.I \&Ex +only. +Announce error messages with a bell. +.TP +.B "exrc, ex [off]" +Read the startup files in the local directory. +.TP +.B "extended [off]" +Regular expressions are extended (i.e. +.IR egrep (1)\-\c +style) expressions. +.TP +.B "filec [no default]" +Set the character to perform file path completion on the colon +command line. +.TP +.B "flash [on]" +Flash the screen instead of beeping the keyboard on error. +.TP +.B "hardtabs, ht [8]" +Set the spacing between hardware tab settings. +.TP +.B "iclower [off]" +Makes all Regular Expressions case-insensitive, +as long as an upper-case letter does not appear in the search string. +.TP +.B "ignorecase, ic [off]" +Ignore case differences in regular expressions. +.TP +.B "keytime [6]" +The 10th's of a second +.I ex/vi +waits for a subsequent key to complete a key mapping. +.TP +.B "leftright [off]" +.I \&Vi +only. +Do left-right scrolling. +.TP +.B "lines, li [24]" +.I \&Vi +only. +Set the number of lines in the screen. +.TP +.B "lisp [off]" +.I \&Vi +only. +Modify various search commands and options to work with Lisp. +.I "This option is not yet implemented." +.TP +.B "list [off]" +Display lines in an unambiguous fashion. +.TP +.B "lock [on]" +Attempt to get an exclusive lock on any file being edited, +read or written. +.TP +.B "magic [on]" +Treat certain characters specially in regular expressions. +.TP +.B "matchtime [7]" +.I \&Vi +only. +The 10th's of a second +.I ex/vi +pauses on the matching character when the +.B showmatch +option is set. +.TP +.B "mesg [on]" +Permit messages from other users. +.TP +.B "modelines, modeline [off]" +Read the first and last few lines of each file for +.I ex +commands. +.I "This option will never be implemented." +.\" I cannot get a double quote to print between the square brackets +.\" to save my life. The ONLY way I've been able to get this to work +.\" is with the .tr command. +.tr Q" +.ds ms noprint [QQ] +.TP +.B "\*(ms" +.tr QQ +Characters that are never handled as printable characters. +.TP +.B "number, nu [off]" +Precede each line displayed with its current line number. +.TP +.B "octal [off]" +Display unknown characters as octal numbers, instead of the default +hexadecimal. +.TP +.B "open [on]" +.I \&Ex +only. +If this option is not set, the +.B open +and +.B visual +commands are disallowed. +.TP +.B "optimize, opt [on]" +.I \&Vi +only. +Optimize text throughput to dumb terminals. +.I "This option is not yet implemented." +.TP +.B "paragraphs, para [IPLPPPQPP LIpplpipbp]" +.I \&Vi +only. +Define additional paragraph boundaries for the +.B \&{ +and +.B \&} +commands. +.TP +.B "path []" +Define additional directories to search for files being edited. +.\" I cannot get a double quote to print between the square brackets +.\" to save my life. The ONLY way I've been able to get this to work +.\" is with the .tr command. +.tr Q" +.ds ms print [QQ] +.TP +.B "\*(ms" +.tr QQ +Characters that are always handled as printable characters. +.TP +.B "prompt [on]" +.I \&Ex +only. +Display a command prompt. +.TP +.B "readonly, ro [off]" +Mark the file and session as read-only. +.TP +.B "recdir [/var/tmp/vi.recover]" +The directory where recovery files are stored. +.TP +.B "redraw, re [off]" +.I \&Vi +only. +Simulate an intelligent terminal on a dumb one. +.I "This option is not yet implemented." +.TP +.B "remap [on]" +Remap keys until resolved. +.TP +.B "report [5]" +Set the number of lines about which the editor reports changes +or yanks. +.TP +.B "ruler [off]" +.I \&Vi +only. +Display a row/column ruler on the colon command line. +.TP +.B "scroll, scr [window / 2]" +Set the number of lines scrolled. +.TP +.B "searchincr [off]" +Makes the +.B \&/ +and +.B \&? +commands incremental. +.TP +.B "sections, sect [NHSHH HUnhsh]" +.I \&Vi +only. +Define additional section boundaries for the +.B \&[[ +and +.B \&]] +commands. +.TP +.B "secure [off]" +Turns off all access to external programs. +.TP +.B "shell, sh [environment variable SHELL, or /bin/sh]" +Select the shell used by the editor. +.\" I cannot get a double quote to print between the square brackets +.\" to save my life. The ONLY way I've been able to get this to work +.\" is with the .tr command. +.tr Q" +.ds ms shellmeta [~{[*?$`'Q\e] +.TP +.B "\*(ms" +.tr QQ +Set the meta characters checked to determine if file name expansion +is necessary. +.TP +.B "shiftwidth, sw [8]" +Set the autoindent and shift command indentation width. +.TP +.B "showmatch, sm [off]" +.I \&Vi +only. +Note matching ``{'' and ``('' for ``}'' and ``)'' characters. +.TP +.B "showmode, smd [off]" +.I \&Vi +only. +Display the current editor mode and a ``modified'' flag. +.TP +.B "sidescroll [16]" +.I \&Vi +only. +Set the amount a left-right scroll will shift. +.TP +.B "slowopen, slow [off]" +Delay display updating during text input. +.I "This option is not yet implemented." +.TP +.B "sourceany [off]" +Read startup files not owned by the current user. +.I "This option will never be implemented." +.TP +.B "tabstop, ts [8]" +This option sets tab widths for the editor display. +.TP +.B "taglength, tl [0]" +Set the number of significant characters in tag names. +.TP +.B "tags, tag [tags /var/db/libc.tags /sys/kern/tags]" +Set the list of tags files. +.TP +.B "term, ttytype, tty [environment variable TERM]" +Set the terminal type. +.TP +.B "terse [off]" +This option has historically made editor messages less verbose. +It has no effect in this implementation. +.TP +.B "tildeop [off]" +Modify the +.B \&~ +command to take an associated motion. +.TP +.B "timeout, to [on]" +Time out on keys which may be mapped. +.TP +.B "ttywerase [off]" +.I \&Vi +only. +Select an alternate erase algorithm. +.TP +.B "verbose [off]" +.I \&Vi +only. +Display an error message for every error. +.TP +.B "w300 [no default]" +.I \&Vi +only. +Set the window size if the baud rate is less than 1200 baud. +.TP +.B "w1200 [no default]" +.I \&Vi +only. +Set the window size if the baud rate is equal to 1200 baud. +.TP +.B "w9600 [no default]" +.I \&Vi +only. +Set the window size if the baud rate is greater than 1200 baud. +.TP +.B "warn [on]" +.I \&Ex +only. +This option causes a warning message to the terminal if the file has +been modified, since it was last written, before a +.B \&! +command. +.TP +.B "window, w, wi [environment variable LINES]" +Set the window size for the screen. +.TP +.B "windowname [off]" +Change the icon/window name to the current file name even if it can't +be restored on editor exit. +.TP +.B "wraplen, wl [0]" +.I \&Vi +only. +Break lines automatically, the specified number of columns from the +left-hand margin. +If both the +.B wraplen +and +.B wrapmargin +edit options are set, the +.B wrapmargin +value is used. +.TP +.B "wrapmargin, wm [0]" +.I \&Vi +only. +Break lines automatically, the specified number of columns from the +right-hand margin. +If both the +.B wraplen +and +.B wrapmargin +edit options are set, the +.B wrapmargin +value is used. +.TP +.B "wrapscan, ws [on]" +Set searches to wrap around the end or beginning of the file. +.TP +.B "writeany, wa [off]" +Turn off file-overwriting checks. +.SH ENVIRONMENTAL VARIABLES +.TP +.I COLUMNS +The number of columns on the screen. +This value overrides any system or terminal specific values. +If the +.I COLUMNS +environmental variable is not set when +.I ex/vi +runs, or the +.B columns +option is explicitly reset by the user, +.I ex/vi +enters the value into the environment. +.TP +.I EXINIT +A list of +.I \&ex +startup commands, read if the variable +.I NEXINIT +is not set. +.TP +.I HOME +The user's home directory, used as the initial directory path +for the startup ``$\fIHOME\fP/.nexrc'' and ``$\fIHOME\fP/.exrc'' +files. +This value is also used as the default directory for the +.I \&vi +.B \&cd +command. +.TP +.I LINES +The number of rows on the screen. +This value overrides any system or terminal specific values. +If the +.I LINES +environmental variable is not set when +.I ex/vi +runs, or the +.B lines +option is explicitly reset by the user, +.I ex/vi +enters the value into the environment. +.TP +.I NEXINIT +A list of +.I \&ex +startup commands. +.TP +.I SHELL +The user's shell of choice (see also the +.B shell +option). +.TP +.I TERM +The user's terminal type. +The default is the type ``unknown''. +If the +.I TERM +environmental variable is not set when +.I ex/vi +runs, or the +.B term +option is explicitly reset by the user, +.I ex/vi +enters the value into the environment. +.TP +.I TMPDIR +The location used to stored temporary files (see also the +.B directory +edit option). +.SH ASYNCHRONOUS EVENTS +.TP +SIGALRM +.I \&Vi/ex +uses this signal for periodic backups of file modifications and to +display ``busy'' messages when operations are likely to take a long time. +.TP +SIGHUP +.TP +SIGTERM +If the current buffer has changed since it was last written in its +entirety, the editor attempts to save the modified file so it can +be later recovered. +See the +.I \&vi/ex +Reference manual section entitled ``Recovery'' for more information. +.TP +SIGINT +When an interrupt occurs, +the current operation is halted, +and the editor returns to the command level. +If interrupted during text input, +the text already input is resolved into the file as if the text +input had been normally terminated. +.TP +SIGWINCH +The screen is resized. +See the +.I \&vi/ex +Reference manual section entitled ``Sizing the Screen'' for more information. +.TP +SIGCONT +.TP +SIGQUIT +.TP +SIGTSTP +.I \&Vi/ex +ignores these signals. +.SH FILES +.TP +/bin/sh +The default user shell. +.TP +/etc/vi.exrc +System-wide vi startup file. +.TP +/tmp +Temporary file directory. +.TP +/var/tmp/vi.recover +The default recovery file directory. +.TP +$HOME/.nexrc +1st choice for user's home directory startup file. +.TP +$HOME/.exrc +2nd choice for user's home directory startup file. +.TP +\&.nexrc +1st choice for local directory startup file. +.TP +\&.exrc +2nd choice for local directory startup file. +.SH SEE ALSO +.IR ctags (1), +.IR more (3), +.IR curses (3), +.IR dbopen (3) +.sp +The ``Vi Quick Reference'' card. +.sp +``An Introduction to Display Editing with Vi'', found in the +``UNIX User's Manual Supplementary Documents'' +section of both the 4.3BSD and 4.4BSD manual sets. +This document is the closest thing available to an introduction to the +.I \&vi +screen editor. +.sp +``Ex Reference Manual (Version 3.7)'', +found in the +``UNIX User's Manual Supplementary Documents'' +section of both the 4.3BSD and 4.4BSD manual sets. +This document is the final reference for the +.I \&ex +editor, as distributed in most historic 4BSD and System V systems. +.sp +``Edit: A tutorial'', +found in the +``UNIX User's Manual Supplementary Documents'' +section of the 4.3BSD manual set. +This document is an introduction to a simple version of the +.I \&ex +screen editor. +.sp +``Ex/Vi Reference Manual'', +found in the +``UNIX User's Manual Supplementary Documents'' +section of the 4.4BSD manual set. +This document is the final reference for the +.I \&nex/nvi +text editors, as distributed in 4.4BSD and 4.4BSD-Lite. +.PP +.I Roff +source for all of these documents is distributed with +.I nex/nvi +in the +.I nvi/USD.doc +directory of the +.I nex/nvi +source code. +.sp +The files ``autowrite'', ``input'', ``quoting'' and ``structures'' +found in the +.I nvi/docs/internals +directory of the +.I nex/nvi +source code. +.SH HISTORY +The +.I nex/nvi +replacements for the +.I ex/vi +editor first appeared in 4.4BSD. +.SH STANDARDS +.I \&Nex/nvi +is close to IEEE Std1003.2 (``POSIX''). +That document differs from historical +.I ex/vi +practice in several places; there are changes to be made on both sides. diff --git a/contrib/nvi/docs/USD.doc/vi.ref/Makefile b/contrib/nvi/docs/USD.doc/vi.ref/Makefile new file mode 100644 index 000000000000..0e1b6343350d --- /dev/null +++ b/contrib/nvi/docs/USD.doc/vi.ref/Makefile @@ -0,0 +1,32 @@ +# @(#)Makefile 8.20 (Berkeley) 8/18/96 + +MACROS= -me +ROFF= groff +TBL= tbl + +all: vi.ref.txt vi.ref.ps + +vi.ref.txt: vi.ref index.so + soelim vi.ref | ${TBL} | groff ${MACROS} -Tascii > $@ + rm -f index + chmod 444 $@ + +vi.ref.ps: vi.ref index.so + soelim vi.ref | ${TBL} | ${ROFF} ${MACROS} > $@ + rm -f index + chmod 444 $@ + +index.so: vi.ref + # Build index.so, side-effect of building the paper. + soelim vi.ref | ${TBL} | ${ROFF} ${MACROS} > /dev/null + sed -e 's/MINUSSIGN/\\-/' \ + -e 's/DOUBLEQUOTE/""/' \ + -e "s/SQUOTE/'/" \ + -e 's/ /__SPACE/g' < index | \ + sort -u '-t ' +0 -1 +1n | awk -f merge.awk | \ + sed -e 's/__SPACE/ /g' > $@ + rm -f index + chmod 444 $@ + +clean: + rm -f vi.ref.ps vi.ref.txt index index.so diff --git a/contrib/nvi/docs/USD.doc/vi.ref/ex.cmd.roff b/contrib/nvi/docs/USD.doc/vi.ref/ex.cmd.roff new file mode 100644 index 000000000000..382e635a6fdd --- /dev/null +++ b/contrib/nvi/docs/USD.doc/vi.ref/ex.cmd.roff @@ -0,0 +1,1924 @@ +.\" Copyright (c) 1994 +.\" The Regents of the University of California. All rights reserved. +.\" Copyright (c) 1994, 1995, 1996 +.\" Keith Bostic. All rights reserved. +.\" +.\" See the LICENSE file for redistribution information. +.\" +.\" @(#)ex.cmd.roff 8.41 (Berkeley) 8/17/96 +.\" +.SH 1 "Ex Description" +.pp +The following words have special meanings for +.CO ex +commands. +.KY "<end-of-file>" +.IP "<end-of-file>" +The end-of-file character is used to scroll the screen in the +.CO ex +editor. +This character is normally +.LI <control-D> . +However, whatever character is set for the current terminal is supported +as well as +.LI <control-D> . +.KY "line" +.IP "line" +A single-line address, given in any of the forms described in the +section entitled +.QB "Ex Addressing" . +The default for +.LI line +is the current line. +.KY "range" +.IP "range" +A line, or a pair of line addresses, separated by a comma or semicolon. +(See the section entitled +.QB "Ex Addressing" +for more information.) +The default for range is the current line +.i only , +i.e. +.QT \&.,. . +A percent sign +.PQ % +stands for the range +.QT 1,$ . +The starting address must be less than, or equal to, the ending address. +.KY "count" +.IP "count" +A positive integer, specifying the number of lines to be affected by +the command; the default is 1. +Generally, a count past the end-of-file may be specified, e.g. the +command +.QT "p 3000" +in a 10 line file is acceptable, and will print from the current line +through the last line in the file. +.KY "flags" +.IP "flags" +One or more of the characters +.QQ # , +.QQ p , +and +.QQ l . +When a command that accepts these flags completes, the addressed line(s) +are written out as if by the corresponding +.CO # , +.CO l +or +.CO p +commands. +In addition, any number of +.QT + +or +.QT \- +characters can be specified before, after, or during the flags, in which +case the line written is not necessarily the one affected by the command, +but rather the line addressed by the offset address specified. +The default for +.LI flags +is none. +.KY "file" +.IP "file" +A pattern used to derive a pathname; the default is the current file. +File names are subjected to normal +.XR sh 1 +word expansions. +.pp +Anywhere a file name is specified, it is also possible to use +the special string +.QT /tmp . +This will be replaced with a temporary file name which can be used +for temporary work, e.g. +.QT ":e /tmp" +creates and edits a new file. +.pp +If both a count and a range are specified for commands that use either, +the starting line for the command is the +.i last +line addressed by the range, and +.LI count - 1 +subsequent lines are affected by the command, e.g. the command +.QT 2,3p4 +prints out lines 3, 4, 5 and 6. +.pp +When only a line or range is specified, with no command, the implied +command is either a +.CO list , +.CO number +or +.CO print +command. +The command used is the most recent of the three commands to have been +used (including any use as a flag). +If none of these commands have been used before, the +.CO print +command is the implied command. +When no range or count is specified and the command line is a blank line, +the current line is incremented by 1 and then the current line is displayed. +.pp +Zero or more whitespace characters may precede or follow the addresses, +count, flags, or command name. +Any object following a command name (such as buffer, file, etc.), +that begins with an alphabetic character, +should be separated from the command name by at least one whitespace +character. +.pp +Any character, including +.LI <carriage-return> , +.QT % +and +.QT # +retain their literal value when preceded by a backslash. +.SH 1 "Ex Commands" +.pp +The following section describes the commands available in the +.CO ex +editor. +In each entry below, the tag line is a usage synopsis for the command. +.pp +Each command can be entered as the abbreviation +(those characters in the synopsis command word preceding the +.QQ [ +character), +the full command (all characters shown for the command word, +omitting the +.QQ [ +and +.QQ ] +characters), +or any leading subset of the full command down to the abbreviation. +For example, the args command (shown as +.QT ar[gs] +in the synopsis) +can be entered as +.QT ar , +.QT arg +or +.QT args . +.pp +Each +.CO ex +command described below notes the new current line after it +is executed, as well as any options that affect the command. +.\" I cannot get a double quote to print to save my life. The ONLY way +.\" I've been able to get this to work is with the .tr command. +.tr Q" +.ds ms Q +.KY DOUBLEQUOTE +.IP "\*(ms" +.tr QQ +A comment. +Command lines beginning with the double-quote character +.PQ """" +are ignored. +This permits comments in editor scripts and startup files. +.KY "<control-D>" +.KY "<end-of-file>" +.IP "<control-D>" +.IP "<end-of-file>" +Scroll the screen. +Write the next N lines, where N is the value of the +.OP scroll +option. +The command is the end-of-file terminal character, which may be +different on different terminals. +Traditionally, it is the +.LI <control-D> +key. +.sp +Historically, the +.CO eof +command ignored any preceding count, and the +.LI <end-of-file> +character was ignored unless it was entered as the first character +of the command. +This implementation treats it as a command +.i only +if entered as the first character of the command line, and otherwise +treats it as any other character. +.SS +.SP Line: +Set to the last line written. +.SP Options: +Affected by the +.OP scroll +option. +.SE +.KY "!" +.IP "! argument(s)" +.Ip "[range]! argument(s)" +Execute a shell command, or filter lines through a shell command. +In the first synopsis, the remainder of the line after the +.QT ! +character is passed to the program named by the +.OP shell +option, as a single argument. +.sp +Within the rest of the line, +.QT % +and +.QT # +are expanded into the current and alternate pathnames, respectively. +The character +.QT ! +is expanded with the command text of the previous +.CO ! +command. +(Therefore, the command +.CO !! +repeats the previous +.CO ! +command.) +The special meanings of +.QT % , +.QT # , +and +.QT ! +can be overridden by escaping them with a backslash. +If no +.CO ! +or +.CO :! +command has yet been executed, it is an error to use an unescaped +.QT ! +character. +The +.CO ! +command does +.i not +do shell expansion on the strings provided as arguments. +If any of the above expansions change the command the user entered, +the command is redisplayed at the bottom of the screen. +.sp +.CO Ex +then executes the program named by the +.OP shell +option, with a +.b \-c +flag followed by the arguments (which are bundled into a single argument). +.sp +The +.CO ! +command is permitted in an empty file. +.sp +If the file has been modified since it was last completely written, +the +.Co ! +command will warn you. +.sp +A single +.QT ! +character is displayed when the command completes. +.sp +In the second form of the +.CO ! +command, the remainder of the line after the +.QT ! +is passed to the program named by the +.OP shell +option, as described above. +The specified lines are passed to the program as standard input, +and the standard and standard error output of the program replace +the original lines. +.SS +.SP Line: +Unchanged if no range was specified, otherwise set to the first +line of the range. +.SP Options: +Affected by the +.OP shell +and +.OP warn +options. +.SE +.KY "#" +.IP "[range] # [count] [flags]" +.KY "number" +.Ip "[range] nu[mber] [count] [flags]" +Display the selected lines, each preceded with its line number. +.sp +The line number format is +.QQ %6d , +followed by two spaces. +.SS +.SP Line: +Set to the last line displayed. +.SP Options: +Affected by the +.OP list +option. +.SE +.KY "@" +.IP "@ buffer" +.KY "*" +.Ip "* buffer" +Execute a buffer. +Each line in the named buffer is executed as an +.CO ex +command. +If no buffer is specified, or if the specified buffer is +.QT @ +or +.QT * , +the last buffer executed is used. +.KY < +.IP "[range] <[< ...] [count] [flags]" +Shift lines left or right. +The specified lines are shifted to the left (for the +.CO < +command) or right (for the +.CO > +command), by the number of columns specified by the +.OP shiftwidth +option. +Only leading whitespace characters are deleted when shifting left; +once the first column of the line contains a nonblank character, +the +.CO shift +command will succeed, but the line will not be modified. +.sp +If the command character +.CO < +or +.CO > +is repeated more than once, the command is repeated once for each +additional command character. +.SS +.SP Line: +If the current line is set to one of the lines that are affected +by the command, it is unchanged. +Otherwise, it is set to the first nonblank character of the lowest +numbered line shifted. +.SP Options: +Affected by the +.OP shiftwidth +option. +.SE +.KY = +.IP "[line] = [flags]" +Display the line number of +.LI line +(which defaults to the last line in the file). +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY > +.IP "[range] >[> ...] [count] [flags]" +Shift right. +The specified lines are shifted to the right by the number of columns +specified by the +.OP shiftwidth +option, by inserting tab and space characters. +Empty lines are not changed. +.sp +If the command character +.QT > +is repeated more than once, the command is repeated once for each +additional command character. +.SS +.SP Line: +Set to the last line modified by the command. +.SP Options: +Affected by the +.OP shiftwidth +option. +.SE +.KY abbrev +.IP "ab[brev] lhs rhs" +Add an abbreviation to the current abbreviation list. +When inserting text in +.CO vi , +each time a non-word character is entered after a word character, +a set of characters ending at the word character are checked for +a match with +.LI lhs . +If a match is found, they are replaced with +.LI rhs . +The set of characters that are checked for a match are defined as follows, +for inexplicable historical reasons. +If only one or two characters were entered before the non-word character +that triggered the check, +and after the beginning of the insertion, +or the beginning of the line or the file, +or the last +.LI <blank> +character that was entered, +then the one or the both characters are checked for a match. +Otherwise, the set includes both characters, +as well as the characters that precede them that are the same word +class (i.e. word or non-word) as the +.b second +to last character entered before the non-word character that triggered +the check, +back to the first +.LI <blank> character, +the beginning of the insertion, +or the beginning of the line or the file. +.sp +For example, the abbreviations: +.sp +.ne 3v +.ft C +.TS +r l l. +:abbreviate abc ABC +:abbreviate #i #include +:abbreviate /*#i /*#include +.TE +.ft R +will all work, while the abbreviations: +.sp +.ne 2v +.ft C +.TS +r l l. +:abbreviate a#i A#include +:abbreviate /* /******************** +.TE +.ft R +will not work, and are not permitted by +.CO nvi . +.sp +To keep the abbreviation expansion from happening, +the character immediately following the +.LI lhs +characters should be quoted with a +.LI <literal-next> +character. +.sp +The replacement +.LI rhs +is itself subject to both further abbreviation expansion and further +map expansion. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY append +.IP "[line] a[ppend][!]" +The input text is appended to the specified line. +If line 0 is specified, the text is inserted at the beginning of the file. +Set to the last line input. +If no lines are input, then set to +.LI line , +or to the first line of the file if a +.LI line +of 0 was specified. +Following the command name with a +.QT ! +character causes the +.OP autoindent +option to be toggled for the duration of the command. +.SS +.SP Line: +Unchanged. +.SP Options: +Affected by the +.OP autoindent +and +.OP number +options. +.SE +.KY args +.IP "ar[gs]" +Display the argument list. +The current argument is displayed inside of +.QT [ +and +.QT ] +characters. +The argument list is the list of operands specified on startup, +which can be replaced using the +.CO next +command. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY bg +.IP bg +.CO Vi +mode only. +Background the current screen. +The screen is unchanged, +but is no longer accessible and disappears from the display. +Use the +.CO fg +command to bring the screen back to the display foreground. +.SS +.SP Line: +Set to the current line when the screen was last edited. +.SP Options: +None. +.SE +.KY change +.IP "[range] c[hange][!] [count]" +Replace the lines with input text. +Following the command name with a +.QT ! +character causes the +.OP autoindent +option to be toggled for the duration of the command. +.SS +.SP Line: +Set to the last line input, or, if no lines were input, +set to the line before the target line, or to the first +line of the file if there are no lines preceding the target line. +.SP Options: +Affected by the +.OP autoindent +and +.OP number +options. +.SE +.KY cd +.KY chdir +.IP "chd[ir][!] [directory]" +.Ip "cd[!] [directory]" +Change the current working directory. +The +.LI directory +argument is subjected to +.XR sh 1 +word expansions. +When invoked with no directory argument and the +.LI HOME +environment variable is set, the directory named by the +.LI HOME +environment variable becomes the new current directory. +Otherwise, the new current directory becomes the directory returned +by the +.XR getpwent 3 +routine. +.sp +The +.CO chdir +command will fail if the file has been modified since the last complete +write of the file. +You can override this check by appending a +.QT ! +character to the command. +.SS +.SP Line: +Unchanged. +.SP Options: +Affected by the +.OP cdpath +option. +.SE +.KY copy +.KY t +.IP "[range] co[py] line [flags]" +.Ip "[range] t line [flags]" +Copy the specified lines (range) after the destination line. +Line 0 may be specified to insert the lines at the beginning of +the file. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY cscope +.IP "cs[cope] command [args]" +Execute a +.CO cscope +command. +For more information, see the section of the reference manual entitled +.QB "Tags, Tag Stacks, and Cscope" . +.KY delete +.IP "[range] d[elete] [buffer] [count] [flags]" +Delete the lines from the file. +The deleted text is saved in the specified buffer, or, if no buffer +is specified, in the unnamed buffer. +If the command name is followed by a letter that could be interpreted +as either a buffer name or a flag value (because neither a +.LI count +or +.LI flags +values were given), +.CO ex +treats the letter as a +.LI flags +value if the letter immediately follows the command name, +without any whitespace separation. +If the letter is preceded by whitespace characters, +it treats it as a buffer name. +.SS +.SP Line: +Set to the line following the deleted lines, +or to the last line if the deleted lines were at the end. +.SP Options: +None. +.SE +.KY display +.IP "di[splay] b[uffers] | c[onnections] | s[creens] | t[ags]" +Display buffers, +.CO cscope +connections, screens or tags. +The +.CO display +command takes one of three additional arguments, which are as follows: +.SS +.SP b[uffers] +Display all buffers (including named, unnamed, and numeric) +that contain text. +.SP c[onnections] +Display the source directories for all attached +.CO cscope +databases. +.SP s[creens] +Display the file names of all background screens. +.SP t[ags] +Display the tags stack. +.SE +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY edit +.IP "e[dit][!] [+cmd] [file]" +.Ip "ex[!] [+cmd] [file]" +Edit a different file. +If the current buffer has been modified since the last complete write, +the command will fail. +You can override this by appending a +.QT ! +character to the command name. +.sp +If the +.QT +cmd +option is specified, that +.CO ex +command will be executed in the new file. +Any +.CO ex +command may be used, although the most common use of this feature is +to specify a line number or search pattern to set the initial location +in the new file. +.sp +Capitalizing the first letter of the command, i.e. +.CO Edit +or +.CO Ex , +while in +.CO vi +mode, will edit the file in a new screen. +In this case, any modifications to the current file are ignored. +.SS +.SP Line: +If you have previously edited the file, the current line will be set +to your last position in the file. +If that position does not exist, or you have not previously edited the +file, the current line will be set to the first line of the file if +you are in +.CO vi +mode, and the last line of the file if you are in +.CO ex . +.SP Options: +None. +.SE +.KY exusage +.IP "exu[sage] [command]" +Display usage for an +.CO ex +command. +If +.LI command +is specified, a usage statement for that command is displayed. +Otherwise, usage statements for all +.CO ex +commands are displayed. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY file +.IP "f[ile] [file]" +Display and optionally change the file name. +If a file name is specified, the current pathname is changed to the +specified name. +The current pathname, the number of lines, and the current position +in the file are displayed. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY fg +.IP "fg [name]" +.CO Vi +mode only. +Foreground the specified screen. +If the argument name doesn't exactly match the name of a file displayed +by a background screen, +it is compared against the last component of each of the file names. +If no background screen is specified, +the first background screen is foregrounded. +.sp +By default, +foregrounding causes the current screen to be swapped with the backgrounded +screen. +Capitalizing the first letter of the command, i.e. +.CO Fg , +will foreground the backgrounded screen in a new screen instead of +swapping it with the current screen. +.SS +.SP Line: +Set to the current line when the screen was last edited. +.SP Options: +None. +.SE +.KY global +.IP "[range] g[lobal] /pattern/ [commands]" +.KY v +.Ip "[range] v /pattern/ [commands]" +Apply commands to lines matching (or not matching) a pattern. +The lines within the given range that match +.PQ g[lobal] , +or do not match +.PQ v +the given pattern are selected. +Then, the specified +.CO ex +command(s) are executed with the current line +.PQ \&. +set to each selected line. +If no range is specified, the entire file is searched for matching, +or not matching, lines. +.sp +Multiple commands can be specified, one per line, by escaping each +.LI <newline> +character with a backslash, or by separating commands with a +.QT | +character. +If no commands are specified, the command defaults to the +.CO print +command. +.sp +For the +.CO append , +.CO change +and +.CO insert +commands, the input text must be part of the global command line. +In this case, the terminating period can be omitted if it ends the commands. +.sp +The +.CO visual +command may also be specified as one of the +.CO ex +commands. +In this mode, input is taken from the terminal. +Entering a +.CO Q +command in +.CO vi +mode causes the next line matching the pattern to be selected and +.CO vi +to be reentered, until the list is exhausted. +.sp +The +.CO global , +.CO v +and +.CO undo +commands cannot be used as part of these commands. +.sp +The editor options +.OP autoindent , +.OP autoprint +and +.OP report +are turned off for the duration of the +.CO global +and +.CO v +commands. +.SS +.SP Line: +The last line modified. +.SP Options: +Affected by the +.OP ignorecase +and +.OP magic +options. +Turns off the +.OP autoindent , +.OP autoprint +and +.OP report +options. +.SE +.KY help +.IP "he[lp]" +Display a help message. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY insert +.IP "[line] i[nsert][!]" +The input text is inserted before the specified line. +Following the command name with a +.QT ! +character causes the +.OP autoindent +option setting to be toggled for the duration of this command. +.SS +.SP Line: +Set to the last line input; if no lines were input, +set to the line before the target line, or to the first line +of the file if there are no lines preceding the target line. +Affected by the +.OP autoindent +and +.OP number +options. +.SE +.KY join +.IP "[range] j[oin][!] [count] [flags]" +Join lines of text together. +.sp +A +.LI count +specified to the +.Sy join +command specifies that the last line of the +.LI range +plus +.LI count +subsequent lines will be joined. +(Note, this differs by one from the general rule where only +.LI count - 1 +subsequent lines are affected.) +.sp +If the current line ends with a whitespace character, all whitespace +is stripped from the next line. +Otherwise, if the next line starts with a open parenthesis +.PQ ( , +do nothing. +Otherwise, if the current line ends with a question mark +.PQ ? , +period +.PQ \&. +or exclamation point +.PQ ! , +insert two spaces. +Otherwise, insert a single space. +.sp +Appending a +.QT ! +character to the command name causes a simpler join with no +white-space processing. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY list +.IP "[range] l[ist] [count] [flags]" +Display the lines unambiguously. +Tabs are displayed as +.QT ^I , +and the end of the line is marked with a +.QT $ +character. +.SS +.SP Line: +Set to the last line displayed. +.SP Options: +Affected by the +.OP number +option. +.SE +.KY map +.IP "map[!] [lhs rhs]" +Define or display maps (for +.CO vi +only). +.sp +If +.QT lhs +and +.QT rhs +are not specified, the current set of command mode maps are displayed. +If a +.QT ! +character is appended to to the command, +the text input mode maps are displayed. +.sp +Otherwise, when the +.QT lhs +character sequence is entered in +.CO vi , +the action is as if the corresponding +.QT rhs +had been entered. +If a +.QT ! +character is appended to the command name, +the mapping is effective during text input mode, +otherwise, it is effective during command mode. +This allows +.QT lhs +to have two different macro definitions at the same time: one for command +mode and one for input mode. +.sp +Whitespace characters require escaping with a +.LI <literal-next> +character to be entered in the +.LI lhs +string in visual mode. +.sp +Normally, keys in the +.LI rhs +string are remapped (see the +.OP remap +option), +and it is possible to create infinite loops. +However, keys which map to themselves are not further remapped, +regardless of the setting of the +.OP remap +option. +For example, the command +.QT ":map n nz." +maps the +.QT n +key to the +.CO n +and +.CO z +commands. +.sp +To exit an infinitely looping map, use the terminal +.LI <interrupt> +character. +.SS +.SP Line: +Unchanged. +.SP Options: +Affected by the +.OP remap +option. +.SE +.KY mark +.KY k +.IP "[line] ma[rk] <character>" +.Ip "[line] k <character>" +Mark the line with the mark +.LI <character> . +The expressions +.QT '<character> +and +.QT `<character> +can then be used as an address in any command that uses one. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY move +.IP "[range] m[ove] line" +Move the specified lines after the target line. +A target line of 0 places the lines at the beginning of the file. +.SS +.SP Line: +Set to the first of the moved lines. +.SP Options: +None. +.SE +.KY mkexrc +.IP "mk[exrc][!] file" +Write the abbreviations, editor options and maps to the specified +file. +Information is written in a form which can later be read back in +using the +.CO ex +.CO source +command. +If +.LI file +already exists, the +.CO mkexrc +command will fail. +This check can be overridden by appending a +.QT ! +character to the command. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY next +.IP "n[ext][!] [file ...]" +Edit the next file from the argument list. +The +.CO next +command will fail if the file has been modified since the last complete +write. +This check can be overridden by appending the +.QT ! +character to the command name. +The argument list can optionally be replaced by specifying a new one +as arguments to this command. +In this case, editing starts with the first file on the new list. +.sp +Capitalizing the first letter of the command, i.e. +.CO Next , +while in +.CO vi +mode, will set the argument list and edit the file in a new screen. +In this case, any modifications to the current file are ignored. +.SS +.SP Line: +Set as described for the +.CO edit +command. +.SP Options: +Affected by the options +.OP autowrite +and +.OP writeany . +.SE +.KY open +.IP "[line] o[pen] /pattern/ [flags]" +Enter open mode. +Open mode is the same as being in +.CO vi , +but with a one-line window. +All the standard +.CO vi +commands are available. +If a match is found for the optional RE argument, +the cursor is set to the start of the matching pattern. +.sp +.i "This command is not yet implemented." +.SS +.SP Line: +Unchanged, unless the optional RE is specified, in which case it is +set to the line where the matching pattern is found. +.SP Options: +Affected by the +.OP open +option. +.SE +.KY preserve +.IP "pre[serve]" +Save the file in a form that can later be recovered using the +.CO ex +.b \-r +option. +When the file is preserved, an email message is sent to the user. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY previous +.IP "prev[ious][!]" +Edit the previous file from the argument list. +The +.CO previous +command will fail if the file has been modified since the last complete +write. +This check can be overridden by appending the +.QT ! +character to the command name. +.sp +Capitalizing the first letter of the command, i.e. +.CO Previous , +while in +.CO vi +mode, will edit the file in a new screen. +In this case, any modifications to the current file are ignored. +.SS +.SP Line: +Set as described for the +.CO edit +command. +.SP Options: +Affected by the options +.OP autowrite +and +.OP writeany . +None. +.SE +.KY print +.IP "[range] p[rint] [count] [flags]" +Display the specified lines. +.SS +.SP Line: +Set to the last line displayed. +.SP Options: +Affected by the +.OP list +and +.OP number +option. +.SE +.KY put +.IP "[line] pu[t] [buffer]" +Append buffer contents to the current line. +If a buffer is specified, its contents are appended to the line, +otherwise, the contents of the unnamed buffer are used. +.SS +.SP Line: +Set to the line after the current line. +.SP Options: +None. +.SE +.KY quit +.IP "q[uit][!]" +End the editing session. +If the file has been modified since the last complete write, the +.CO quit +command will fail. +This check may be overridden by appending a +.QT ! +character to the command. +.sp +If there are more files to edit, the +.CO quit +command will fail. +Appending a +.QT ! +character to the command name or entering two +.CO quit +commands (i.e. +.CO wq , +.CO quit , +.CO xit +or +.CO ZZ ) +in a row) will override this check and the editor will exit. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY read +.IP "[line] r[ead][!] [file]" +Read a file. +A copy of the specified file is appended to the line. +If +.LI line +is 0, the copy is inserted at the beginning of the file. +If no file is specified, the current file is read; if there is no +current file, then +.LI file +becomes the current file. +If there is no current file and no +.LI file +is specified, then the +.CO read +command will fail. +.sp +If +.LI file +is preceded by a +.QT ! +character, +.LI file +is treated as if it were a shell command, and passed to the program +named by the +.OP shell +edit option. +The standard and standard error outputs of that command are read into +the file after the specified line. +The special meaning of the +.QT ! +character can be overridden by escaping it with a backslash +.PQ \e +character. +.SS +.SP Line: +When executed from +.CO ex , +the current line is set to the last line read. +When executed from +.CO vi , +the current line is set to the first line read. +.SP Options: +None. +.SE +.KY recover +.IP "rec[over] file" +Recover +.LI file +if it was previously saved. +If no saved file by that name exists, the +.CO recover +command behaves equivalently to the +.CO edit +command. +.SS +.SP Line: +Set as described for the +.CO edit +command. +.SP Options: +None. +.SE +.KY resize +.IP "res[ize] [+|-]size" +.CO Vi +mode only. +Grow or shrink the current screen. +If +.LI size +is a positive, signed number, the current screen is grown by that many lines. +If +.LI size +is a negative, signed number, the current screen is shrunk by that many lines. +If +.LI size +is not signed, the current screen is set to the specified +.LI size . +Applicable only to split screens. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY rewind +.IP "rew[ind][!]" +Rewind the argument list. +If the current file has been modified since the last complete write, +the +.CO rewind +command will fail. +This check may be overridden by appending the +.QT ! +character to the command. +.sp +Otherwise, the current file is set to the first file in the argument +list. +.SS +.SP Line: +Set as described for the +.CO edit +command. +.SP Options: +Affected by the +.OP autowrite +and +.OP writeany +options. +.SE +.KY set +.IP "se[t] [option[=[value]] ...] [nooption ...] [option? ...] [all]" +Display or set editor options. +When no arguments are specified, the editor option +.OP term , +and any editor options whose values have been changed from the +default settings are displayed. +If the argument +.LI all +is specified, the values of all of editor options are displayed. +.sp +Specifying an option name followed by the character +.QT ? +causes the current value of that option to be displayed. +The +.QT ? +can be separated from the option name by whitespace characters. +The +.QT ? +is necessary only for Boolean valued options. +Boolean options can be given values by the form +.QT "set option" +to turn them on, or +.QT "set nooption" +to turn them off. +String and numeric options can be assigned by the form +.QT "set option=value" . +Any whitespace characters in strings can be included literally by preceding +each with a backslash. +More than one option can be set or listed by a single set command, +by specifying multiple arguments, each separated from the next by +whitespace characters. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY shell +.IP "sh[ell]" +Run the shell program. +The program named by the +.OP shell +option is run with a +.b \-i +(for interactive) flag. +Editing is resumed when that program exits. +.SS +.SP Line: +Unchanged. +.SP Options: +Affected by the +.OP shell +option. +.SE +.KY source +.IP "so[urce] file" +Read and execute +.CO ex +commands from a file. +.CO Source +commands may be nested. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY substitute +.IP "[range] s[ubstitute] [/pattern/replace/] [options] [count] [flags]" +.KY & +.Ip "[range] & [options] [count] [flags]" +.KY ~ +.Ip "[range] ~ [options] [count] [flags]" +Make substitutions. +Replace the first instance of +.LI pattern +with the string +.LI replace +on the specified line(s). +If the +.QT /pattern/repl/ +argument is not specified, the +.QT /pattern/repl/ +from the previous +.CO substitute +command is used. +Any character other than an alphabetic, numeric, <blank> or backslash +character may be used as the delimiter. +.sp +If +.LI options +includes the letter +.QT c +(confirm), you will be prompted for confirmation before each replacement +is done. +An affirmative response (in English, a +.QT y +character) causes the replacement to be made. +A quit response (in English, a +.QT q +character) causes the +.CO substitute +command to be terminated. +Any other response causes the replacement not to be made, and the +.CO substitute +command continues. +If +.LI options +includes the letter +.QT g +(global), all nonoverlapping instances of +.LI pattern +in the line are replaced. +.sp +The +.CO & +version of the command is the same as not specifying a pattern +or replacement string to the +.CO substitute +command, and the +.QT & +is replaced by the pattern and replacement information from the +previous substitute command. +.sp +The +.CO ~ +version of the command is the same as +.CO & +and +.CO s , +except that the search pattern used is the last RE used in +.i any +command, not necessarily the one used in the last +.CO substitute +command. +.sp +For example, in the sequence +.ft C +.(b +s/red/blue/ +/green +~ +.)b +.ft R +the +.QT ~ +is equivalent to +.QT s/green/blue/ . +.sp +The +.CO substitute +command may be interrupted, using the terminal interrupt character. +All substitutions completed before the interrupt are retained. +.SS +.SP Line: +Set to the last line upon which a substitution was made. +.SP Options: +Affected by the +.OP ignorecase +and +.OP magic +option. +.SE +.KY suspend +.IP "su[spend][!]" +.KY stop +.Ip "st[op][!]" +.KY <control-Z> +.Ip <control-Z> +Suspend the edit session. +Appending a +.QT ! +character to these commands turns off the +.OP autowrite +option for the command. +.SS +.SP Line: +Unchanged. +.SP Options: +Affected by the +.OP autowrite +and +.OP writeany +options. +.SE +.KY tag +.IP "ta[g][!] tagstring" +Edit the file containing the specified tag. +If the tag is in a different file, then the new file is edited. +If the current file has been modified since the last complete write, +the +.CO tag +command will fail. +This check can be overridden by appending the +.QT ! +character to the command name. +.sp +The +.CO tag +command searches for +.LI tagstring +in the tags file(s) specified by the +.Op tags +option. +(See +.XR ctags 1 +for more information on tags files.) +.sp +Capitalizing the first letter of the command, i.e. +.CO Tag , +while in +.CO vi +mode, will edit the file in a new screen. +In this case, any modifications to the current file are ignored. +.SS +.SP Line: +Set to the line indicated by the tag. +.SP Options: +Affected by the +.OP autowrite , +.OP taglength , +.OP tags +and +.OP writeany +options. +.SE +.KY tagnext +.IP "tagn[ext][!]" +Edit the file containing the next context for the current tag. +If the context is in a different file, then the new file is edited. +If the current file has been modified since the last complete write, +the +.CO tagnext +command will fail. +This check can be overridden by appending the +.QT ! +character to the command name. +.sp +Capitalizing the first letter of the command, i.e. +.CO Tagnext , +while in +.CO vi +mode, will edit the file in a new screen. +In this case, any modifications to the current file are ignored. +.SS +.SP Line: +Set to the line indicated by the tag. +.SP Options: +Affected by the +.OP autowrite +and +.OP writeany +options. +.SE +.KY tagpop +.IP "tagp[op][!] [file | number]" +Pop to the specified tag in the tags stack. +If neither +.LI file +or +.LI number +is specified, the +.CO tagpop +command pops to the most recent entry on the tags stack. +If +.LI file +or +.LI number +is specified, the +.CO tagpop +command pops to the most recent entry in the tags stack for that file, +or numbered entry in the tags stack, respectively. +(See the +.CO display +command for information on displaying the tags stack.) +.sp +If the file has been modified since the last complete write, the +.CO tagpop +command will fail. +This check may be overridden by appending a +.QT ! +character to the command name. +.SS +.SP Line: +Set to the line indicated by the tag. +.SP Options: +Affected by the +.OP autowrite +and +.OP writeany +options. +.SE +.KY tagprev +.IP "tagp[rev][!]" +Edit the file containing the previous context for the current tag. +If the context is in a different file, then the new file is edited. +If the current file has been modified since the last complete write, +the +.CO tagprev +command will fail. +This check can be overridden by appending the +.QT ! +character to the command name. +.sp +Capitalizing the first letter of the command, i.e. +.CO Tagprev , +while in +.CO vi +mode, will edit the file in a new screen. +In this case, any modifications to the current file are ignored. +.SS +.SP Line: +Set to the line indicated by the tag. +.SP Options: +Affected by the +.OP autowrite +and +.OP writeany +options. +.SE +.KY tagtop +.IP "tagt[op][!]" +Pop to the least recent tag on the tags stack, clearing the tags stack. +.sp +If the file has been modified since the last complete write, the +.CO tagtop +command will fail. +This check may be overridden by appending a +.QT ! +character to the command name. +.SS +.SP Line: +Set to the line indicated by the tag. +.SP Options: +Affected by the +.OP autowrite +and +.OP writeany +options. +.SE +.KY unabbrev +.IP "una[bbrev] lhs" +Delete an abbreviation. +Delete +.LI lhs +from the current list of abbreviations. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY undo +.IP "u[ndo]" +Undo the last change made to the file. +Changes made by +.CO global , +.CO v , +.CO visual +and map sequences are considered a single command. +If repeated, the +.CO u +command alternates between these two states, and is its own inverse. +.SS +.SP Line: +Set to the last line modified by the command. +.SP Options: +None. +.SE +.KY unmap +.IP "unm[ap][!] lhs" +Unmap a mapped string. +Delete the command mode map definition for +.LI lhs . +If a +.QT ! +character is appended to the command name, delete the text input mode +map definition instead. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY version +.IP "ve[rsion]" +Display the version of the +.CO ex/vi +editor. +.KY visual +.IP "[line] vi[sual] [type] [count] [flags]" +.CO Ex +mode only. +Enter +.CO vi . +The +.LI type +is optional, and can be +.QT \- , +.QT + +or +.QT ^ , +as in the +.CO ex +.CO z +command, to specify the position of the specified line in the screen +window. +(The default is to place the line at the top of the screen window.) +A +.LI count +specifies the number of lines that will initially be displayed. +(The default is the value of the +.OP window +editor option.) +.SS +.SP Line: +Unchanged unless +.LI line +is specified, in which case it is set to that line. +.SP Options: +None. +.SE +.KY visual +.IP "vi[sual][!] [+cmd] [file]" +.CO Vi +mode only. +Edit a new file. +Identical to the +.QT "edit[!] [+cmd] [file]" +command. +.sp +Capitalizing the first letter of the command, i.e. +.CO Visual , +will edit the file in a new screen. +In this case, any modifications to the current file are ignored. +.KY viusage +.IP "viu[sage] [command]" +Display usage for a +.CO vi +command. +If +.LI command +is specified, a usage statement for that command is displayed. +Otherwise, usage statements for all +.CO vi +commands are displayed. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY write +.IP "[range] w[rite][!] [>>] [file]" +.Ip "[range] w[rite] [!] [file]" +.KY wn +.Ip "[range] wn[!] [>>] [file]" +.KY wq +.Ip "[range] wq[!] [>>] [file]" +Write the file. +The specified lines (the entire file, if no range is given) is written +to +.LI file . +If +.LI file +is not specified, the current pathname is used. +If +.LI file +is specified, and it exists, or if the current pathname was set using the +.CO file +command, and the file already exists, these commands will fail. +Appending a +.QT ! +character to the command name will override this check and the write +will be attempted, regardless. +.sp +Specifying the optional +.QT >> +string will cause the write to be appended to the file, in which case +no tests are made for the file already existing. +.sp +If the file is preceded by a +.QT ! +character, the program named by the shell edit option is +invoked with file as its second argument, and the specified +lines are passed as standard input to that command. +The +.QT ! +in this usage must be separated from command name by at least one +whitespace character. +The special meaning of the +.QT ! +may be overridden by escaping it with a backslash +.PQ \e +character. +.sp +The +.CO wq +version of the write command will exit the editor after writing the file, +if there are no further files to edit. +Appending a +.QT ! +character to the command name or entering two +.QQ quit +commands (i.e. +.CO wq , +.CO quit , +.CO xit +or +.CO ZZ ) +in a row) will override this check and the editor will exit, +ignoring any files that have not yet been edited. +.sp +The +.CO wn +version of the write command will move to the next file after writing +the file, unless the write fails. +.SS +.SP Line: +Unchanged. +.SP Options: +Affected by the +.OP readonly +and +.OP writeany +options. +.SE +.KY xit +.IP "[range] x[it][!] [file]" +Write the file if it has been modified. +The specified lines are written to +.LI file , +if the file has been modified since the last complete write to any +file. +If no +.LI range +is specified, the entire file is written. +.sp +The +.CO xit +command will exit the editor after writing the file, +if there are no further files to edit. +Appending a +.QT ! +character to the command name or entering two +.QQ quit +commands (i.e. +.CO wq , +.CO quit , +.CO xit +or +.CO ZZ ) +in a row) will override this check and the editor will exit, +ignoring any files that have not yet been edited. +.SS +.SP Line: +Unchanged. +.SP Options: +Affected by the +.OP readonly +and +.OP writeany +options. +.SE +.KY yank +.IP "[range] ya[nk] [buffer] [count]" +Copy the specified lines to a buffer. +If no buffer is specified, the unnamed buffer is used. +.SS +.SP Line: +Unchanged. +.SP Options: +None. +.SE +.KY z +.IP "[line] z [type] [count] [flags]" +Adjust the window. +If no +.LI type +is specified, then +.LI count +lines following the specified line are displayed. +The default +.LI count +is the value of the +.OP window +option. +The +.LI type +argument changes the position at which +.LI line +is displayed on the screen by changing the number of lines +displayed before and after +.LI line . +The following +.LI type +characters may be used: +.SS +.SP \- +Place the line at the bottom of the screen. +.SP + +Place the line at the top of the screen. +.SP \&. +Place the line in the middle of the screen. +.SP ^ +Write out count lines starting +.LI "count * 2" +lines before +.LI line ; +the net effect of this is that a +.QT z^ +command following a +.CO z +command writes the previous page. +.SP = +Center +.LI line +on the screen with a line of hyphens displayed immediately before and +after it. +The number of preceding and following lines of text displayed are +reduced to account for those lines. +.SE +.SS +.SP Line: +Set to the last line displayed, with the exception of the +.Dq Li \&= +.LI type , +where the current line is set to the line specified by the command. +.SP Options: +Affected by the +.OP scroll +option. +.SE diff --git a/contrib/nvi/docs/USD.doc/vi.ref/index.so b/contrib/nvi/docs/USD.doc/vi.ref/index.so new file mode 100644 index 000000000000..4c3acb6e4f04 --- /dev/null +++ b/contrib/nvi/docs/USD.doc/vi.ref/index.so @@ -0,0 +1,260 @@ +! 21, 42 +"" 42 +# 22, 43 +$ 22 +% 22 +& 23, 51 +'<character> 23 +( 23 +) 24 +* 43 ++ 19 +, 24 +. 24 +/RE/ 25 +0 25 +0<control-D> 38 +: 26 +; 26 +< 26, 43 +<carriage-return> 14 +<control-A> 17 +<control-B> 17 +<control-D> 17, 38, 42 +<control-E> 18 +<control-F> 18 +<control-G> 18 +<control-H> 18, 39 +<control-J> 19 +<control-L> 19 +<control-M> 19 +<control-N> 19 +<control-P> 19 +<control-R> 19 +<control-T> 19, 38 +<control-U> 20 +<control-W> 20, 39 +<control-X> 39 +<control-Y> 20 +<control-Z> 20, 52 +<control-]> 20 +<control-^> 21 +<end-of-file> 40, 42 +<erase> 39 +<escape> 20, 39 +<interrupt> 12, 37, 39 +<line erase> 39 +<literal-next> 12, 39 +<newline> 14 +<nul> 38 +<space> 21 +<word erase> 39 += 43 +> 26, 43 +?RE? 25 +@ 26, 43 +A 27 +B 27 +C 27 +D 27 +E 28 +F 28 +G 28 +H 28 +I 28 +J 29 +L 29 +M 29 +N 25 +O 29 +P 29 +Q 30 +R 30 +S 30 +T 30 +U 30 +W 31 +X 31 +Y 31 +ZZ 31 +[[ 31 +\- 24 +]] 32 +^ 32 +^<control-D> 38 +_ 32 +`<character> 23 +a 32 +abbrev 43 +alternate pathname 13 +altwerase 56 +append 44 +args 44 +autoindent 56 +autoprint 56 +autowrite 57 +b 32 +backup 57 +beautify 57 +bg 44 +bigword 16 +buffer 13 +c 33 +cd 45 +cdpath 57 +cedit 57 +change 45 +chdir 45 +columns 58 +comment 58 +copy 45 +count 16, 41 +cscope 45 +current pathname 12 +d 33 +delete 45 +directory 58 +display 45 +e 33 +edcompatible 58 +edit 46 +errorbells 58 +escapetime 58 +exrc 58 +extended 58 +exusage 46 +f 33 +fg 46 +file 41, 46 +filec 58 +flags 41 +flash 59 +global 47 +hardtabs 59 +help 47 +i 33 +iclower 59 +ignorecase 59 +insert 47 +j 19 +join 47 +k 19, 48 +keytime 59 +l 21 +leftright 59 +line 41 +lines 59 +lisp 59 +list 48, 59 +lock 59 +m 34 +magic 60 +map 48 +mark 48 +matchtime 60 +mesg 60 +mkexrc 49 +modelines 60 +motion 15 +move 48 +msgcat 60 +n 25 +next 49 +noprint 60 +number 43, 61 +o 34 +octal 61 +open 49, 61 +optimize 61 +p 34 +paragraph 16 +paragraphs 61 +path 61 +preserve 49 +previous 49 +previous context 15 +print 50, 61 +prompt 61 +put 50 +quit 50 +r 34 +range 41 +read 50 +readonly 61 +recdir 62 +recover 50 +redraw 62 +remap 62 +report 62 +resize 50 +rewind 51 +ruler 62 +s 34 +scroll 62 +searchincr 62 +section 17 +sections 63 +secure 63 +sentence 17 +set 51 +shell 51, 63 +shellmeta 63 +shiftwidth 63 +showmatch 63 +showmode 63 +sidescroll 63 +slowopen 63 +source 51 +sourceany 64 +stop 52 +substitute 51 +suspend 52 +t 35, 45 +tabstop 64 +tag 52 +taglength 64 +tagnext 52 +tagpop 53 +tagprev 53 +tags 64 +tagtop 53 +term 64 +terse 64 +tildeop 64 +timeout 64 +ttywerase 64 +u 35 +unabbrev 53 +undo 53 +unmap 54 +unnamed buffer 14 +v 47 +verbose 64 +version 54 +visual 54 +viusage 54 +w 35 +w1200 64 +w300 64 +w9600 64 +warn 65 +whitespace 14 +window 65 +windowname 65 +wn 54 +word 16 +wq 54 +wraplen 65 +wrapmargin 65 +wrapscan 65 +write 54 +writeany 66 +x 35 +xit 55 +y 35 +yank 55 +z 36, 55 +{ 36 +| 36 +} 37 +~ 37, 51 diff --git a/contrib/nvi/docs/USD.doc/vi.ref/merge.awk b/contrib/nvi/docs/USD.doc/vi.ref/merge.awk new file mode 100644 index 000000000000..c65207c106a7 --- /dev/null +++ b/contrib/nvi/docs/USD.doc/vi.ref/merge.awk @@ -0,0 +1,16 @@ +# @(#)merge.awk 8.3 (Berkeley) 5/25/94 +# +# merge index entries into one line per label +$1 == prev { + printf ", %s", $2; + next; +} +{ + if (NR != 1) + printf "\n"; + printf "%s \t%s", $1, $2; + prev = $1; +} +END { + printf "\n" +} diff --git a/contrib/nvi/docs/USD.doc/vi.ref/ref.so b/contrib/nvi/docs/USD.doc/vi.ref/ref.so new file mode 100644 index 000000000000..a82c79258bb1 --- /dev/null +++ b/contrib/nvi/docs/USD.doc/vi.ref/ref.so @@ -0,0 +1,103 @@ +.\" Copyright (c) 1994 +.\" The Regents of the University of California. All rights reserved. +.\" Copyright (c) 1994, 1995, 1996 +.\" Keith Bostic. All rights reserved. +.\" +.\" See the LICENSE file for redistribution information. +.\" +.\" @(#)ref.so 8.9 (Berkeley) 8/17/96 +.\" +.\" +.\" indented paragraph, with spaces between the items, bold font +.de IP +.\".tm arg 1 \\$1 arg 2 \\$2 arg 3 \\$3 +.sp 1 +.nr PS \\n(ps +.nr ps 0 +.ip "\fB\\$1\fP" \\$2 +.nr ps \\n(PS +.br +.. +.\" indented paragraph, no spaces between the items, bold font +.de Ip +.\".tm arg 1 \\$1 arg 2 \\$2 arg 3 \\$3 +.nr PS \\n(ps +.nr ps 0 +.ns +.ip "\fB\\$1\fP" \\$2 +.nr ps \\n(PS +.br +.. +.\" start nested .IP +.de SS +.sp +.ba +5n +.. +.\" end nested .IP +.de SE +.ba -5n +.. +.\" nested .IP, no spaces, normal font +.de SP +.\".tm arg 1 \\$1 arg 2 \\$2 arg 3 \\$3 +.nr PS \\n(ps +.nr ps 0 +.ns +.ip "\\$1" 9n +.nr ps \\n(PS +.. +.\" typewriter font +.de LI +\&\fC\\$1\fP\\$2 +.. +.\" ex/vi names in command font +.de EV +\&\fB\\$1\fP/\fB\\$2\fP\\$3 +.. +.\" command names +.de CO +\&\fB\\$1\fP\\$2 +.. +.\" key words for index +.de KY +.sy echo >>index '\\$1 \\n%' +.. +.\" option names +.de OP +\&\fB\\$1\fP\\$2 +.. +.\" paren quoted (typewriter font) +.de PQ +(\*(lq\fC\\$1\fP\*(rq)\\$2 +.. +.\" quoted bold +.de QB +\*(lq\fB\\$1\fP\*(rq\\$2 +.. +.\" quoted command +.de QC +\*(lq\fB\\$1\fP\*(rq\\$2 +.. +.\" quoted option +.de QO +\*(lq\fB\\$1\fP\*(rq\\$2 +.. +.\" quoted (no font change) +.de QQ +\*(lq\\$1\*(rq\\$2 +.. +.\" quoted (typewriter font) +.de QT +\*(lq\fC\\$1\fP\*(rq\\$2 +.. +.\" section macro to build TOC +.de SH +.(x +\\$2 +.)x +.sh \\$1 "\\$2" +.. +.\" manual section +.de XR +\&\fI\\$1\fP(\\$2)\\$3 +.. diff --git a/contrib/nvi/docs/USD.doc/vi.ref/set.opt.roff b/contrib/nvi/docs/USD.doc/vi.ref/set.opt.roff new file mode 100644 index 000000000000..838412897ab0 --- /dev/null +++ b/contrib/nvi/docs/USD.doc/vi.ref/set.opt.roff @@ -0,0 +1,1303 @@ +.\" Copyright (c) 1994 +.\" The Regents of the University of California. All rights reserved. +.\" Copyright (c) 1994, 1995, 1996 +.\" Keith Bostic. All rights reserved. +.\" +.\" See the LICENSE file for redistribution information. +.\" +.\" @(#)set.opt.roff 8.66 (Berkeley) 10/10/96 +.\" +.SH 1 "Set Options" +.pp +There are a large number of options that may be set (or unset) to +change the editor's behavior. +This section describes the options, their abbreviations and their +default values. +.pp +In each entry below, the first part of the tag line is the full name +of the option, followed by any equivalent abbreviations. +(Regardless of the abbreviations, it is only necessary to use the +minimum number of characters necessary to distinguish an abbreviation +from all other commands for it to be accepted, in +.EV nex nvi . +Historically, only the full name and the official abbreviations +were accepted by +.EV ex vi . +Using full names in your startup files and environmental variables will +probably make them more portable.) +The part in square brackets is the default value of the option. +Most of the options are boolean, i.e. they are either on or off, +and do not have an associated value. +.pp +Options apply to both +.CO ex +and +.CO vi +modes, unless otherwise specified. +.pp +With a few exceptions, +all options are settable per screen, i.e. the +.OP tags +option can be set differently in each screen. +The exceptions are the +.OP columns , +.OP lines , +.OP secure +and +.OP term +options. +Changing these options modifies the respective information for all screens. +.pp +For information on modifying the options or to display the options and +their current values, see the +.QQ set +command in the section entitled +.QB "Ex Commands" . +.KY altwerase +.IP "altwerase [off]" +.CO Vi +only. +Change how +.CO vi +does word erase during text input. +When this option is set, text is broken up into three classes: +alphabetic, numeric and underscore characters, other nonblank +characters, and blank characters. +Changing from one class to another marks the end of a word. +In addition, the class of the first character erased is ignored +(which is exactly what you want when erasing pathname components). +.KY autoindent +.IP "autoindent, ai [off]" +If this option is set, whenever you create a new line (using the +.CO vi +.CO A , +.CO a , +.CO C , +.CO c , +.CO I , +.CO i , +.CO O , +.CO o , +.CO R , +.CO r , +.CO S , +and +.CO s +commands, or the +.CO ex +.CO append , +.CO change , +and +.CO insert +commands) the new line is automatically indented to align the cursor with +the first nonblank character of the line from which you created it. +Lines are indented using tab characters to the extent possible (based on +the value of the +.OP tabstop +option) and then using space characters as necessary. +For commands inserting text into the middle of a line, any blank characters +to the right of the cursor are discarded, and the first nonblank character +to the right of the cursor is aligned as described above. +.sp +The indent characters are themselves somewhat special. +If you do not enter more characters on the new line before moving to +another line, or entering +.LI <escape> , +the indent character will be deleted and the line will be empty. +For example, if you enter +.LI <carriage-return> +twice in succession, +the line created by the first +.LI <carriage-return> +will not have any characters in it, +regardless of the indentation of the previous or subsequent line. +.sp +Indent characters also require that you enter additional erase characters +to delete them. +For example, +if you have an indented line, containing only blanks, the first +.LI <word-erase> +character you enter will erase up to end of the indent characters, +and the second will erase back to the beginning of the line. +(Historically, only the +.LI <control-D> +key would erase the indent characters. +Both the +.LI <control-D> +key and the usual erase keys work in +.CO nvi .) +In addition, if the cursor is positioned at the end of the indent +characters, the keys +.QT 0<control-D> +will erase all of the indent characters for the current line, +resetting the indentation level to 0. +Similarly, the keys +.QT ^<control-D> +will erase all of the indent characters for the current line, +leaving the indentation level for future created lines unaffected. +.sp +Finally, if the +.OP autoindent +option is set, the +.CO S +and +.CO cc +commands change from the first nonblank of the line to the end of the +line, instead of from the beginning of the line to the end of the line. +.KY autoprint +.IP "autoprint, ap [off]" +.CO Ex +only. +Cause the current line to be automatically displayed after the +.CO ex +commands +.CO < , +.CO > , +.CO copy , +.CO delete , +.CO join , +.CO move , +.CO put , +.CO t , +.CO Undo , +and +.CO undo . +This automatic display is suppressed during +.CO global +and +.CO v +commands, and for any command where optional flags are used to explicitly +display the line. +.KY autowrite +.IP "autowrite, aw [off]" +If this option is set, the +.CO vi +.CO ! , +.CO ^^ , +.CO ^] +and +.CO <control-Z> +commands, and the +.CO ex +.CO edit , +.CO next , +.CO rewind , +.CO stop , +.CO suspend , +.CO tag , +.CO tagpop , +and +.CO tagtop +commands automatically write the current file back to the current file name +if it has been modified since it was last written. +If the write fails, the command fails and goes no further. +.sp +Appending the optional force flag character +.QT ! +to the +.CO ex +commands +.CO next , +.CO rewind , +.CO stop , +.CO suspend , +.CO tag , +.CO tagpop , +and +.CO tagtop +stops the automatic write from being attempted. +.sp +(Historically, the +.CO next +command ignored the optional force flag.) +Note, the +.CO ex +commands +.CO edit , +.CO quit , +.CO shell , +and +.CO xit +are +.i not +affected by the +.OP autowrite +option. +.sp +The +.OP autowrite +option is ignored if the file is considered read-only for any reason. +.\" I cannot get a double quote to print between the square brackets +.\" to save my life. The ONLY way I've been able to get this to work +.\" is with the .tr command. +.tr Q" +.ds ms backup [QQ] +.KY backup +.IP "\*(ms" +.tr QQ +If this option is set, it specifies a pathname used as a backup file, +and, whenever a file is written, the file's current contents are copied +to it. +The pathname is +.QT \&# , +.QT \&% +and +.QT \&! +expanded. +.sp +If the first character of the pathname is +.QT \&N , +a version number is appended to the pathname (and the +.QT \&N +character is then discarded). +Version numbers are always incremented, and each backup file will have +a version number one greater than the highest version number currently +found in the directory. +.sp +Backup files must be regular files, owned by the real user ID of the +user running the editor, and not accessible by any other user. +.KY beautify +.IP "beautify, bf [off]" +If this option is set, all control characters that are not currently being +specially interpreted, other than +.LI <tab> , +.LI <newline> , +and +.LI <form-feed> , +are +discarded from commands read in by +.CO ex +from command files, and from input text entered to +.CO vi +(either into the file or to the colon command line). +Text files read by +.EV ex vi +are +.i not +affected by the +.OP beautify +option. +.KY cdpath +.IP "cdpath [environment variable CDPATH, or current directory]" +This option is used to specify a colon separated list of directories +which are used as path prefixes for any relative path names used as +arguments for the +.CO cd +command. +The value of this option defaults to the value of the environmental +variable +.LI CDPATH +if it is set, otherwise to the current directory. +For compatibility with the POSIX 1003.2 shell, the +.CO cd +command does +.i not +check the current directory as a path prefix for relative path names +unless it is explicitly specified. +It may be so specified by entering an empty string or a +.QT \&. +character into the +.LI CDPATH +variable or the option value. +.KY cedit +.IP "cedit [no default]" +This option adds the ability to edit the colon command-line history. +This option is set to a string. +Whenever the first character of that string is entered on the colon +command line, +you will enter a normal editing window on the collected commands that +you've entered on the +.CO vi +colon command-line. +You may then modify and/or execute the commands. +All normal text editing is available, +except that you cannot use +.CO <control-W> +to switch to an alternate screen. +Entering a +.CO <carriage-return> +will execute the current line of the screen window as an ex command in +the context of the screen from which you created the colon command-line +screen, +and you will then return to that screen. +.sp +Because of +.CO vi \&'s +parsing rules, it can be difficult to set the colon command-line edit +character to the +.LI <escape> +character. +To set it to +.LI <escape> , +use +.QT "set cedit=<literal-next><escape>" . +.sp +If the +.OP cedit +edit option is set to the same character as the +.OP filec +edit option, +.CO vi +will perform colon command-line editing if the character is entered as +the first character of the line, +otherwise, +.CO vi +will perform file name expansion. +.KY columns +.IP "columns, co [80]" +The number of columns in the screen. +Setting this option causes +.EV ex vi +to set (or reset) the environmental variable +.LI COLUMNS . +See the section entitled +.QB "Sizing the Screen" +more information. +.KY comment +.IP "comment [off]" +.CO Vi +only. +If the first non-empty line of the file begins with the string +.QT # , +.QT /\&* +or +.QT // , +this option causes +.CO vi +to skip to the end of that shell, C or C++ comment (probably a +terribly boring legal notice) before displaying the file. +.KY directory +.IP "directory, dir [environment variable TMPDIR, or /tmp]" +The directory where temporary files are created. +The environmental variable +.LI TMPDIR +is used as the default value if it exists, otherwise +.LI /tmp +is used. +.KY edcompatible +.IP "edcompatible, ed [off]" +Remember the values of the +.QQ c +and +.QQ g +suffixes to the +.CO substitute +commands, instead of initializing them as unset for each new +command. +Specifying pattern and replacement strings to the +.CO substitute +command unsets the +.QQ c +and +.QQ g +suffixes as well. +.KY escapetime +.IP "escapetime [1]" +The 10th's of a second +.EV ex vi +waits for a subsequent key to complete an +.LI <escape> +key mapping. +.KY errorbells +.IP "errorbells, eb [off]" +.CO Ex +only. +.CO Ex +error messages are normally presented in inverse video. +If that is not possible for the terminal, setting this option causes +error messages to be announced by ringing the terminal bell. +.KY exrc +.IP "exrc, ex [off]" +If this option is turned on in the EXINIT environment variables, +or the system or $HOME startup files, +the local startup files are read, +unless they are the same as the system or $HOME startup files or +fail to pass the standard permission checks. +See the section entitled +.QB "Startup Information" +for more information. +.KY extended +.IP "extended [off]" +This option causes all regular expressions to be treated as POSIX +1003.2 Extended Regular Expressions (which are similar to historic +.XR egrep 1 +style expressions). +.KY filec +.IP "filec [no default]" +This option adds the ability to do shell expansion when entering input +on the colon command line. +This option is set to a string. +Whenever the first character of that string is entered on the colon +command line, +the <blank> delimited string immediately before the cursor is expanded +as if it were followed by a +.LI \&* +character, and file name expansion for the +.CO ex +edit command was done. +If no match is found, the screen is flashed and text input resumed. +If a single match results, that match replaces the expanded text. +In addition, if the single match is for a directory, a +.LI \&/ +character is appended and file completion is repeated. +If more than a single match results, +any unique prefix shared by the matches replaces the expanded text, +the matches are displayed, +and text input resumed. +.sp +Because of +.CO vi \&'s +parsing rules, it can be difficult to set the path completion character +to two command values, +.LI <escape> +and +.LI <tab> . +To set it to +.LI <escape> , +use +.QT "set filec=<literal-next><escape>" . +To set it to +.LI <tab> , +use +.QT "set filec=\e<tab>" . +.sp +If the +.OP cedit +edit option is set to the same character as the +.OP filec +edit option, +.CO vi +will perform colon command-line editing if the character is entered as +the first character of the line, +otherwise, +.CO vi +will perform file name expansion. +.KY flash +.IP "flash [on]" +This option causes the screen to flash instead of beeping the keyboard, +on error, if the terminal has the capability. +.KY hardtabs +.IP "hardtabs, ht [8]" +This option defines the spacing between hardware tab settings, i.e. +the tab expansion done by the operating system and/or the terminal +itself. +As +.EV nex nvi +never writes +.LI <tab> +characters to the terminal, unlike historic versions of +.EV ex vi , +this option does not currently have any affect. +.KY iclower +.IP "iclower [off]" +The +.OP iclower +edit option makes all Regular Expressions case-insensitive, +as long as an upper-case letter does not appear in the search string. +.KY ignorecase +.IP "ignorecase, ic [off]" +This option causes regular expressions, both in +.CO ex +commands and in searches, +to be evaluated in a case-insensitive manner. +.KY keytime +.IP "keytime [6]" +The 10th's of a second +.EV ex vi +waits for a subsequent key to complete a key mapping. +.KY leftright +.IP "leftright [off]" +.CO Vi +only. +This option causes the screen to be scrolled left-right to view +lines longer than the screen, instead of the traditional +.CO vi +screen interface which folds long lines at the right-hand margin +of the terminal. +.KY lines +.IP "lines, li [24]" +.CO Vi +only. +The number of lines in the screen. +Setting this option causes +.EV ex vi +to set (or reset) the environmental variable +.LI LINES . +See the section entitled +.QB "Sizing the Screen" +for more information. +.KY lisp +.IP "lisp [off]" +.CO Vi +only. +This option changes the behavior of the +.CO vi +.CO ( , +.CO ) , +.CO { , +.CO } , +.CO [[ +and +.CO ]] +commands to match the Lisp language. +Also, the +.OP autoindent +option's behavior is changed to be appropriate for Lisp. +.sp +.i "This option is not yet implemented." +.KY list +.IP "list [off]" +This option causes lines to be displayed in an unambiguous fashion. +Specifically, tabs are displayed as control characters, i.e. +.QT ^I , +and the ends of lines are marked with a +.QT $ +character. +.KY lock +.IP "lock [on]" +This option causes the editor to attempt to get an exclusive lock on +any file being edited, read or written. +Reading or writing a file that cannot be locked produces a warning +message, but no other effect. +Editing a file that cannot be locked results in a read only edit session, +as if the +.OP readonly +edit option were set. +.KY magic +.IP "magic [on]" +This option is on by default. +Turning the +.OP magic +option off causes all regular expression characters except for +.QT ^ +and +.QT $ , +to be treated as ordinary characters. +To re-enable characters individually, when the +.OP magic +option is off, +precede them with a backslash +.QT \e +character. +See the section entitled +.QB "Regular Expressions and Replacement Strings" +for more information. +.KY matchtime +.IP "matchtime [7]" +.CO Vi +only. +The 10th's of a second +.CO vi +pauses on the matching character when the +.OP showmatch +option is set. +.KY mesg +.IP "mesg [on]" +This option allows other users to contact you using the +.XR talk 1 +and +.XR write 1 +utilities, while you are editing. +.EV Ex vi +does not turn message on, i.e. if messages were turned off when the +editor was invoked, they will stay turned off. +This option only permits you to disallow messages for the edit session. +See the +.XR mesg 1 +utility for more information. +.KY msgcat +.IP "msgcat [./]" +This option selects a message catalog to be used to display error and +informational messages in a specified language. +If the value of this option ends with a '/', it is treated as the name +of a directory that contains a message catalog +.QT "vi_XXXX" , +where +.QT XXXX +is the value of the +.LI LANG +environmental variable, if it's set, or the value of the +.LI LC_MESSAGES +environmental variable if it's not. +If neither of those environmental variables are set, +or if the option doesn't end in a '/', +the option is treated as the full path name of the message catalog to use. +.sp +If any messages are missing from the catalog, +the backup text (English) is used instead. +.sp +See the distribution file +.LI catalog/README +for additional information on building and installing message catalogs. +.KY modelines +.IP "modelines, modeline [off]" +If the +.OP modelines +option is set, +.EV ex vi +has historically scanned the first and last five lines of each file as +it is read for editing, looking for any +.CO ex +commands that have been placed in those lines. +After the startup information has been processed, and before the user +starts editing the file, any commands embedded in the file are executed. +.sp +Commands were recognized by the letters +.QQ e +or +.QQ v +followed by +.QQ x +or +.QQ i , +at the beginning of a line or following a tab or space character, +and followed by a +.QQ : , +an +.CO ex +command, and another +.QQ : . +.sp +This option is a security problem of immense proportions, +and should not be used under any circumstances. +.sp +.i "This option will never be implemented." +.\" I cannot get a double quote to print between the square brackets +.\" to save my life. The ONLY way I've been able to get this to work +.\" is with the .tr command. +.tr Q" +.ds ms noprint [QQ] +.KY noprint +.IP "\*(ms" +.tr QQ +Characters that are never handled as printable characters. +By default, the C library function +.XR isprint 3 +is used to determine if a character is printable or not. +This edit option overrides that decision. +.KY number +.IP "number, nu [off]" +Precede each line displayed with its current line number. +.KY octal +.IP "octal [off]" +Display unknown characters as octal numbers +.PQ "\e###" , +instead of the default +hexadecimal +.PQ "\ex##" . +.KY open +.IP "open [on]" +.CO Ex +only. +If this option is not set, the +.CO open +and +.CO visual +commands are disallowed. +.KY optimize +.IP "optimize, opt [on]" +.CO Vi +only. +Throughput of text is expedited by setting the terminal not to do automatic +carriage returns when printing more than one (logical) line of output, +greatly speeding output on terminals without addressable cursors when text +with leading white space is printed. +.sp +.i "This option is not yet implemented." +.KY paragraphs +.IP "paragraphs, para [IPLPPPQPP LIpplpipbp]" +.CO Vi +only. +Define additional paragraph boundaries for the +.CO { +and +.CO } +commands. +The value of this option must be a character string consisting +of zero or more character pairs. +.sp +In the text to be edited, the character string +.LI "<newline>.<char-pair>" , +(where +.LI <char-pair> +is one of the character pairs in the option's value) +defines a paragraph boundary. +For example, if the option were set to +.LI "LaA<space>##" , +then all of the following additional paragraph boundaries would be +recognized: +.sp +.(l +<newline>.La +<newline>.A<space> +<newline>.## +.)l +.KY path +.IP "path []" +The path option can be used to specify a <colon>-separated list of +paths, similar to the +.LI PATH +environment variable in the shells. +If this option is set, +the name of the file to be edited is not an absolute pathname, +the first component of the filename is not +.QT \&. +or +.QT \&.. , +and the file to be edited doesn't exist in the current directory, +the elements of the +.OP path +option are sequentially searched for a file of the specified name. +If such a file is found, it is edited. +.\" I cannot get a double quote to print between the square brackets +.\" to save my life. The ONLY way I've been able to get this to work +.\" is with the .tr command. +.tr Q" +.ds ms print [QQ] +.KY print +.IP "\*(ms" +.tr QQ +Characters that are always handled as printable characters. +By default, the C library function +.XR isprint 3 +is used to determine if a character is printable or not. +This edit option overrides that decision. +.KY prompt +.IP "prompt [on]" +.CO Ex +only. +This option causes +.CO ex +to prompt for command input with a +.QT : +character; when it is not set, no prompt is displayed. +.KY readonly +.IP "readonly, ro [off]" +This option causes a force flag to be required to attempt to write the file. +Setting this option is equivalent to using the +.b \-R +command line option, +or executing the +.CO vi +program using the name +.CO view . +.sp +The +.OP readonly +edit option is not usually persistent, like other edit options. +If the +.b \-R +command line option is set, +.CO vi +is executed as +.CO view , +or the +.OP readonly +edit option is explicitly set, +all files edited in the screen will be marked readonly, +and the force flag will be required to write them. +However, if none of these conditions are true, +or the +.OP readonly +edit option is explicitly unset, +then the +.OP readonly +edit option will toggle based on the write permissions of the file currently +being edited as of when it is loaded into the edit buffer. +In other words, the +.OP readonly +edit option will be set if the current file lacks write permissions, +and will not be set if the user has write permissions for the file. +.KY recdir +.IP "recdir [/var/tmp/vi.recover]" +The directory where recovery files are stored. +.sp +If you change the value of +.OP recdir , +be careful to choose a directory whose contents are not regularly +deleted. +Bad choices include directories in memory based filesystems, +or +.LI /tmp , +on most systems, +as their contents are removed when the machine is rebooted. +.sp +Public directories like +.LI /usr/tmp +and +.LI /var/tmp +are usually safe, although some sites periodically prune old files +from them. +There is no requirement that you use a public directory, +e.g. a sub-directory of your home directory will work fine. +.sp +Finally, if you change the value of +.OP recdir , +you must modify the recovery script to operate in your chosen recovery +area. +.sp +See the section entitled +.QB "Recovery" +for further information. +.KY redraw +.IP "redraw, re [off]" +.CO Vi +only. +The editor simulates (using great amounts of output), an intelligent +terminal on a dumb terminal (e.g. during insertions in +.CO vi +the characters to the right of the cursor are refreshed as each input +character is typed). +.sp +.i "This option is not yet implemented." +.KY remap +.IP "remap [on]" +If this option is set, +it is possible to define macros in terms of other macros. +Otherwise, each key is only remapped up to one time. +For example, if +.QT A +is mapped to +.QT B , +and +.QT B +is mapped to +.QT C , +The keystroke +.QT A +will be mapped to +.QT C +if the +.OP remap +option is set, and to +.QT B +if it is not set. +.KY report +.IP "report [5]" +Set the threshold of the number of lines that need to be changed or +yanked before a message will be displayed to the user. +For everything but the yank command, the value is the largest value +about which the editor is silent, i.e. by default, 6 lines must be +deleted before the user is notified. +However, if the number of lines yanked is greater than +.i "or equal to" +the set value, it is reported to the user. +.KY ruler +.IP "ruler [off]" +.CO Vi +only. +Display a row/column ruler on the colon command line. +.KY scroll +.IP "scroll, scr [(environment variable LINES - 1) / 2]" +Set the number of lines scrolled by the +.CO ex +.CO <control-D> +and +.CO <end-of-file> +commands. +.sp +Historically, the +.CO ex +.CO z +command, when specified without a count, used two times the size of the +scroll value; the POSIX 1003.2 standard specified the window size, which +is a better choice. +.KY searchincr +.IP "searchincr [off]" +The +.OP searchincr +edit option makes the search commands +.CO \&/ +and +.CO \&? +incremental, i.e. the screen is updated and the cursor moves to the matching +text as the search pattern is entered. +If the search pattern is not found, +the screen is beeped and the cursor remains on the colon-command line. +Erasing characters from the search pattern backs the cursor up to the +previous matching text. +.KY sections +.IP "sections, sect [NHSHH HUnhsh]" +.CO Vi +only. +Define additional section boundaries for the +.CO [[ +and +.CO ]] +commands. +The +.OP sections +option should be set to a character string consisting of zero or +more character pairs. +In the text to be edited, the character string +.LI "<newline>.<char-pair>" , +(where +.LI <char-pair> +is one of the character pairs in the option's value), +defines a section boundary in the same manner that +.OP paragraphs +option boundaries are defined. +.KY secure +.IP "secure [off]" +The +.OP secure +edit option turns off all access to external programs. +This means that the versions of the +.CO read +and +.CO write +commands that filter text through other programs, +the +.CO vi +.CO \&! +and +.CO <control-Z> +commands, +the +.CO ex +.CO \&! , +.CO script , +.CO shell , +.CO stop +and +.CO suspend +commands and file name expansion will not be permitted. +Once set, +the +.OP secure +edit option may not be unset. +.KY shell +.IP "shell, sh [environment variable SHELL, or /bin/sh]" +Select the shell used by the editor. +The specified path is the pathname of the shell invoked by the +.CO vi +.CO ! +shell escape command and by the +.CO ex +.CO shell +command. +This program is also used to resolve any shell meta-characters in +.CO ex +commands. +.\" I cannot get a double quote to print between the square brackets +.\" to save my life. The ONLY way I've been able to get this to work +.\" is with the .tr command. +.tr Q" +.ds ms shellmeta [~{[*?$`'Q\e] +.KY shellmeta +.IP "\*(ms" +.tr QQ +The set of characters that +.CO ex +checks for when doing file name expansion. +If any of the specified characters are found in the file name arguments +to the +.CO ex +commands, +the arguments are expanded using the program defined by the +.OP shell +option. +The default set of characters is a union of meta characters +from the Version 7 and the Berkeley C shell. +.KY shiftwidth +.IP "shiftwidth, sw [8]" +Set the autoindent and shift command indentation width. +This width is used by the +.OP autoindent +option and by the +.CO < , +.CO > , +and +.CO shift +commands. +.KY showmatch +.IP "showmatch, sm [off]" +.CO Vi +only. +This option causes +.CO vi , +when a +.QT } +or +.QT ) +is entered, to briefly move the cursor the matching +.QT { +or +.QT ( . +See the +.OP matchtime +option for more information. +.KY showmode +.IP "showmode, smd [off]" +.CO Vi +only. +This option causes +.CO vi +to display a string identifying the current editor mode on the colon +command line. +The string is preceded by an asterisk (``*'') if the file has been +modified since it was last completely written, +.KY sidescroll +.IP "sidescroll [16]" +.CO Vi +only. +Sets the number of columns that are shifted to the left or right, +when +.CO vi +is doing left-right scrolling and the left or right margin is +crossed. +See the +.OP leftright +option for more information. +.KY slowopen +.IP "slowopen, slow [off]" +This option affects the display algorithm used by +.CO vi , +holding off display updating during input of new text to improve +throughput when the terminal in use is slow and unintelligent. +.sp +.i "This option is not yet implemented." +.KY sourceany +.IP "sourceany [off]" +If this option is turned on, +.CO vi +historically read startup files that were owned by someone other than +the editor user. +See the section entitled +.QB "Startup Information" +for more information. +This option is a security problem of immense proportions, +and should not be used under any circumstances. +.sp +.i "This option will never be implemented." +.KY tabstop +.IP "tabstop, ts [8]" +This option sets tab widths for the editor display. +.KY taglength +.IP "taglength, tl [0]" +This option sets the maximum number of characters that are considered +significant in a tag name. +Setting the value to 0 makes all of the characters in the tag name +significant. +.KY tags +.IP "tags, tag [tags /var/db/libc.tags /sys/kern/tags]" +Sets the list of tags files, in search order, +which are used when the editor searches for a tag. +.KY term +.IP "term, ttytype, tty [environment variable TERM]" +Set the terminal type. +Setting this option causes +.EV ex vi +to set (or reset) the environmental variable +.LI TERM . +.KY terse +.IP "terse [off]" +This option has historically made editor messages less verbose. +It has no effect in this implementation. +See the +.OP verbose +option for more information. +.KY tildeop +.IP "tildeop [off]" +Modify the +.CO ~ +command to take an associated motion. +.KY timeout +.IP "timeout, to [on]" +If this option is set, +.EV ex vi +waits for a specific period for a subsequent key to complete a key +mapping (see the +.OP keytime +option). +If the option is not set, the editor waits until enough keys are +entered to resolve the ambiguity, regardless of how long it takes. +.KY ttywerase +.IP "ttywerase [off]" +.CO Vi +only. +This option changes how +.CO vi +does word erase during text input. +If this option is set, text is broken up into two classes, +blank characters and nonblank characters. +Changing from one class to another marks the end of a word. +.KY verbose +.IP "verbose [off]" +.CO Vi +only. +.CO Vi +historically bells the terminal for many obvious mistakes, e.g. trying +to move past the left-hand margin, or past the end of the file. +If this option is set, an error message is displayed for all errors. +.KY w300 +.IP "w300 [no default]" +.CO Vi +only. +Set the window size if the baud rate is less than 1200 baud. +See the +.OP window +option for more information. +.KY w1200 +.IP "w1200 [no default]" +.CO Vi +only. +Set the window size if the baud rate is equal to 1200 baud. +See the +.OP window +option for more information. +.KY w9600 +.IP "w9600 [no default]" +.CO Vi +only. +Set the window size if the baud rate is greater than 1200 baud. +See the +.OP window +option for more information. +.KY warn +.IP "warn [on]" +.CO Ex +only. +This option causes a warning message to the terminal if the file has +been modified, since it was last written, before a +.CO ! +command. +.KY window +.IP "window, w, wi [environment variable LINES - 1]" +This option determines the default number of lines in a screenful, +as displayed by the +.CO z +command. +It also determines the number of lines scrolled by the +.CO vi +commands +.CO <control-B> +and +.CO <control-F> , +and the default number of lines scrolled by the +.CO vi +commands +.CO <control-D> +and +.CO <control-U> . +The value of window can be unrelated to the real screen size, +although it starts out as the number of lines on the screen. +See the section entitled +.QB "Sizing the Screen" +for more information. +Setting the value of the +.OP window +option is the same as using the +.b \-w +command line option. +.sp +If the value of the +.OP window +option (as set by the +.OP window , +.OP w300 , +.OP w1200 +or +.OP w9600 +options) is smaller than the actual size of the screen, +large screen movements will result in displaying only that smaller +number of lines on the screen. +(Further movements in that same area will result in the screen being +filled.) +This can provide a performance improvement when viewing different +places in one or more files over a slow link. +.sp +Resetting the window size does not reset the default number of lines +scrolled by the +.CO <control-D> +and +.CO <control-U> +commands. +.KY windowname +.IP "windowname [off]" +.CO Vi +changes the name of the editor's icon/window to the current file name +when it's possible and not destructive, i.e., +when the editor can restore it to its original value on exit or when +the icon/window will be discarded as the editor exits. +If the +.OP windowname +edit option is set, +.CO vi +will change the icon/window name even when it's destructive and the +icon/window name will remain after the editor exits. +(This is the case for +.XR xterm 1 ). +.KY wraplen +.IP "wraplen, wl [0]" +This option is identical to the +.OP wrapmargin +option, with the exception that it specifies the number of columns +from the +.i left +margin before the line splits, not the right margin. +.sp +If both +.OP wraplen +and +.OP wrapmargin +are set, the +.OP wrapmargin +value is used. +.KY wrapmargin +.IP "wrapmargin, wm [0]" +.CO Vi +only. +If the value of the +.OP wrapmargin +option is non-zero, +.CO vi +will split lines so that they end at least that number of columns +before the right-hand margin of the screen. +(Note, the value of +.OP wrapmargin +is +.i not +a text length. +In a screen that is 80 columns wide, the command +.QT ":set wrapmargin=8" +attempts to keep the lines less than or equal to 72 columns wide.) +.sp +Lines are split at the previous whitespace character closest to the +number. +Any trailing whitespace characters before that character are deleted. +If the line is split because of an inserted +.LI <space> +or +.LI <tab> +character, and you then enter another +.LI <space> +character, it is discarded. +.sp +If wrapmargin is set to 0, +or if there is no blank character upon which to split the line, +the line is not broken. +.sp +If both +.OP wraplen +and +.OP wrapmargin +are set, the +.OP wrapmargin +value is used. +.KY wrapscan +.IP "wrapscan, ws [on]" +This option causes searches to wrap around the end or the beginning +of the file, and back to the starting point. +Otherwise, the end or beginning of the file terminates the search. +.KY writeany +.IP "writeany, wa [off]" +If this option is set, file-overwriting checks that would usually be +made before the +.CO write +and +.CO xit +commands, or before an automatic write (see the +.OP autowrite +option), are not made. +This allows a write to any file, provided the file permissions allow it. diff --git a/contrib/nvi/docs/USD.doc/vi.ref/spell.ok b/contrib/nvi/docs/USD.doc/vi.ref/spell.ok new file mode 100644 index 000000000000..a7d95e35d03a --- /dev/null +++ b/contrib/nvi/docs/USD.doc/vi.ref/spell.ok @@ -0,0 +1,414 @@ +ABC +Amir +Autoindent +Autoprint +BRE's +Bostic +Bourne +CDPATH +CSCOPE +Cscope +DIRS +DOUBLEQUOTE +Dq +Ds +ERE's +EXINIT +Englar +Ev +FF +Fa +Fg +FindScreen +Fl +Foregrounding +HUnhsh +IPLPPPQPP +Kirkendall +Korn +LC +LIpplpipbp +LaA +Li +Lowercase +MINUSSIGN +Makefiles +Mayoff +NEX +NEXINIT +NHSHH +NVI +Neville +Nex +Nvi +OS +POSIX +Perl +PostScript +QQ +RE's +README +RECDIR +Reference''USD:13 +SENDMAIL +SIGHUP +SIGWINCH +SQUOTE +Se +Std +Std1003.2 +Sven +Sy +TANDARDS +TIOCGWINSZ +TMPDIR +TOC +Tagnext +Tagprev +Tcl +Tk +Todo +USD +USD.doc +USD:13 +UUNET +Unmap +VI +Verdoolaege +Vi +Vx +Whitespace +XOFF +XON +XOptions +XXCOLUMNS +XXXX +XXXXXX +XXb +ZZ +ab +abbrev +abc +ags +ai +al +altwerase +ap +api +ar +arg +args +att +autoindent +autoprint +autowrite +aw +backgrounded +backgrounding +bbrev +berkeley +bf +bg +bigword +bigwords +bostic +bp +brev +bsd +bugs.current +c2w +carat +cd +cdpath +cdy +cedit +changelog +chd +chdir +cmd +co +count1 +count2 +creens +cs +cs.berkeley.edu +cscope +ctags +cw +db +dbopen +dd +def +di +dir +dit +docs +eE +eFlRsv +eFlRv +eL +eU +ead +eb +edcompatible +edu +ee +egrep +elete +elp +elvis +email +enum +eof +errorbells +esc +escapetime +eset +eu +ex.cmd.roff +exrc +ext +exu +exusage +fcntl +fg +fi +filec +filesystem +filesystems +foo +foregrounded +foregrounding +ftp.cs.berkeley.edu +ftp.uu.net +gdb +gdb.script +getpwent +gs +gzip'd +halfbyte +hange +hangup +hardtabs +ht +html +http +ic +iclower +ifdef +ignorecase +ile +ind +initially +ious +ir +iscntrl +isprint +ist +ize +keystroke +keystrokes +keytime +leftright +lhs +li +lib +libc +libc.tags +lineNum +lineNumber +lobal +lowercase +lp +luR +matchtime +mber +mesg +meta +mk +mkexrc +modeful +modeline +modelines +ms +msgcat +ndo +nex +nexrc +nk +nomagic +nonblank +nonoverlapping +nooption +noprint +nsert +nul +nvi +nvi.tar.Z +nvi.tar.z +nz +oin +onnections +op +ove +para +pathname +pathnames +pe +perl +perld +ppend +prev +pu +py +rc +rc.local +readonly +rec +recdir +recfile +recover.XXXX +recover.XXXXXX +recover.c +recover.script +redist +redistributable +reimplementations +remapmax +remapped +repl +res +rew +rhs +rint +ript +rk +rl +ro +roff +rsion +sc +sccs +scr +screeen +screenId +se +searchincr +sendmail +set.opt.roff +settable +setuid +sh +shareware +shellmeta +shiftwidth +showmatch +showmode +sidescroll +slowopen +sm +smd +sourceany +sp +spell.ok +ssg +st +su +sual +svi +sw +ta +tabstop +taglength +tagn +tagnext +tagp +tagpop +tagprev +tagstring +tagt +tagtop +tc +tcl +tclproc +terminfo +th +th's +tildeop +tl +tmp +toolchest +tpath +tr +ts +ttytype +ttywerase +uR +ubstitute +ucb +uffers +uit +una +unabbrev +unescaped +unm +unmap +unsets +uppercase +urce +usr +uunet +v +var +ve +vi +vi.0.ps +vi.0.txt +vi.1 +vi.XXXX +vi.XXXXXX +vi.cmd.roff +vi.exrc +vi.recover +viAppendLine +viDelLine +viEndScreen +viFindScreen +viGetCursor +viGetLine +viGetMark +viGetOpt +viInsertLine +viLastLine +viMapKey +viMsg +viNewScreen +viSetCursor +viSetLine +viSetMark +viSetOpt +viSwitchScreen +viUnmMapKey +vibackup +virecovery +viu +viusage +wa +whitespace +wi +windowname +wl +wm +wn +wq +wraplen +wrapmargin +wrapscan +writeany +ws +www +xaw +xit +xterm +ya +yy diff --git a/contrib/nvi/docs/USD.doc/vi.ref/vi.cmd.roff b/contrib/nvi/docs/USD.doc/vi.ref/vi.cmd.roff new file mode 100644 index 000000000000..12030cd52b08 --- /dev/null +++ b/contrib/nvi/docs/USD.doc/vi.ref/vi.cmd.roff @@ -0,0 +1,3085 @@ +.\" Copyright (c) 1994 +.\" The Regents of the University of California. All rights reserved. +.\" Copyright (c) 1994, 1995, 1996 +.\" Keith Bostic. All rights reserved. +.\" +.\" See the LICENSE file for redistribution information. +.\" +.\" @(#)vi.cmd.roff 8.49 (Berkeley) 8/17/96 +.\" +.SH 1 "Vi Description" +.pp +.CO Vi +takes up the entire screen to display the edited file, +except for the bottom line of the screen. +The bottom line of the screen is used to enter +.CO ex +commands, and for +.CO vi +error and informational messages. +If no other information is being displayed, +the default display can show the current cursor row and cursor column, +an indication of whether the file has been modified, +and the current mode of the editor. +See the +.OP ruler +and +.OP showmode +options for more information. +.pp +Empty lines do not have any special representation on the screen, +but lines on the screen that would logically come after the end of +the file are displayed as a single tilde +.PQ ~ +character. +To differentiate between empty lines and lines consisting of only +whitespace characters, use the +.OP list +option. +Historically, implementations of +.CO vi +have also displayed some lines as single asterisk +.PQ @ +characters. +These were lines that were not correctly displayed, i.e. lines on the +screen that did not correspond to lines in the file, or lines that did +not fit on the current screen. +.CO Nvi +never displays lines in this fashion. +.pp +.CO Vi +is a modeful editor, i.e. it has two modes, +.QQ command +mode and +.QQ "text input" +mode. +When +.CO vi +first starts, it is in command mode. +There are several commands that change +.CO vi +into text input mode. +The +.LI <escape> +character is used to resolve the text input into the file, +and exit back into command mode. +In +.CO vi +command mode, the cursor is always positioned on the last column of +characters which take up more than one column on the screen. +In +.CO vi +text insert mode, the cursor is positioned on the first column of +characters which take up more than one column on the screen. +.pp +When positioning the cursor to a new line and column, +the type of movement is defined by the distance to the new cursor position. +If the new position is close, +the screen is scrolled to the new location. +If the new position is far away, +the screen is repainted so that the new position is on the screen. +If the screen is scrolled, +it is moved a minimal amount, +and the cursor line will usually appear at the top or bottom of the screen. +If the screen is repainted, +the cursor line will appear in the center of the screen, +unless the cursor is sufficiently close to the beginning or end of the file +that this isn't possible. +If the +.OP leftright +option is set, the screen may be scrolled or repainted in a horizontal +direction as well as in a vertical one. +.pp +A major difference between the historical +.CO vi +presentation and +.CO nvi +is in the scrolling and screen oriented position commands, +.CO <control-B> , +.CO <control-D> , +.CO <control-E> , +.CO <control-F> , +.CO <control-U> , +.CO <control-Y> , +.CO H , +.CO L +and +.CO M . +In historical implementations of +.CO vi , +these commands acted on physical (as opposed to logical, or screen) +lines. +For lines that were sufficiently long in relation to the size of the +screen, this meant that single line scroll commands might repaint the +entire screen, scrolling or screen positioning commands might not change +the screen or move the cursor at all, and some lines simply could not +be displayed, even though +.CO vi +would edit the file that contained them. +In +.CO nvi , +these commands act on logical, i.e. screen lines. +You are unlikely to notice any difference unless you are editing files +with lines significantly longer than a screen width. +.pp +.CO Vi +keeps track of the currently +.QQ "most attractive" +cursor position. +Each command description (for commands that alter the current cursor +position), +specifies if the cursor is set to a specific location in the line, +or if it is moved to the +.QQ "most attractive cursor position" . +The latter means that the cursor is moved to the cursor position that +is horizontally as close as possible to the current cursor position. +If the current line is shorter than the cursor position +.CO vi +would select, the cursor is positioned on the last character in the line. +(If the line is empty, the cursor is positioned on the first column +of the line.) +If a command moves the cursor to the most attractive position, +it does not alter the current cursor position, and a subsequent +movement will again attempt to move the cursor to that position. +Therefore, although a movement to a line shorter than the currently +most attractive position will cause the cursor to move to the end of +that line, a subsequent movement to a longer line will cause the +cursor to move back to the most attractive position. +.pp +In addition, the +.CO $ +command makes the end of each line the most attractive cursor position +rather than a specific column. +.pp +Each +.CO vi +command described below notes where the cursor ends up after it is +executed. +This position is described in terms of characters on the line, i.e. +.QQ "the previous character" , +or, +.QQ "the last character in the line" . +This is to avoid needing to continually refer to on what part of the +character the cursor rests. +.pp +The following words have special meaning for +.CO vi +commands. +.KY "previous context" +.IP "previous context" +The position of the cursor before the command which caused the +last absolute movement was executed. +Each +.CO vi +command described in the next section that is considered an +absolute movement is so noted. +In addition, specifying +.i any +address to an +.CO ex +command is considered an absolute movement. +.KY "motion" +.IP "motion" +A second +.CO vi +command can be used as an optional trailing argument to the +.CO vi +.CO \&< , +.CO \&> , +.CO \&! , +.CO \&c , +.CO \&d , +.CO \&y , +and (depending on the +.OP tildeop +option) +.CO \&~ +commands. +This command indicates the end of the region of text that's affected by +the command. +The motion command may be either the command character repeated (in +which case it means the current line) or a cursor movement command. +In the latter case, the region affected by the command is from the +starting or stopping cursor position which comes first in the file, +to immediately before the starting or stopping cursor position which +comes later in the file. +Commands that operate on lines instead of using beginning and ending +cursor positions operate on all of the lines that are wholly or +partially in the region. +In addition, some other commands become line oriented depending on +where in the text they are used. +The command descriptions below note these special cases. +.sp +The following commands may all be used as motion components for +.CO vi +commands: +.sp +.ne 12v +.ft C +.TS +r r r r. +<control-A> <control-H> <control-J> <control-M> +<control-N> <control-P> <space> $ +% '<character> ( ) ++ , - / +0 ; ? B +E F G H +L M N T +W [[ ]] ^ +\&_ `<character> b e +f h j k +l n t w +{ | } +.TE +.ft R +.sp +The optional count prefix available for some of the +.CO vi +commands that take motion commands, +or the count prefix available for the +.CO vi +commands that are used as motion components, +may be included and is +.i always +considered part of the motion argument. +For example, the commands +.QT c2w +and +.QT 2cw +are equivalent, and the region affected by the +.CO c +command is two words of text. +In addition, +if the optional count prefix is specified for both the +.CO vi +command and its motion component, +the effect is multiplicative and is considered part of the motion argument. +For example, the commands +.QT 4cw +and +.QT 2c2w +are equivalent, and the region affected by the +.CO c +command is four words of text. +.KY "count" +.IP "count" +A positive number used as an optional argument to most commands, +either to give a size or a position (for display or movement commands), +or as a repeat count (for commands that modify text). +The count argument is always optional and defaults to 1 unless otherwise +noted in the command description. +.sp +When a +.CO vi +command synopsis shows both a +.LI [buffer] +and +.LI [count] , +they may be presented in any order. +.KY word +.IP word +Generally, in languages where it is applicable, +.CO vi +recognizes two kinds of words. +First, a sequence of letters, digits and underscores, +delimited at both ends by: +characters other than letters, digits, or underscores, +the beginning or end of a line, and the beginning or end of the file. +Second, a sequence of characters other than letters, digits, underscores, +or whitespace characters, delimited at both ends by: a letter, digit, +underscore, or whitespace character, +the beginning or end of a line, and the beginning or end of the file. +For example, the characters +.QT " !@#abc$%^ " +contain three words: +.QT "!@#" , +.QT "abc" +and +.QT "$%^" . +.sp +Groups of empty lines (or lines containing only whitespace characters) +are treated as a single word. +.KY "bigword" +.IP "bigword" +A set of non-whitespace characters preceded and followed by whitespace +characters or the beginning or end of the file or line. +For example, the characters +.QT " !@#abc$%^ " +contain one bigword: +.QT "!@#abc$%^" . +.sp +Groups of empty lines (or lines containing only whitespace characters) +are treated as a single bigword. +.KY "paragraph" +.IP "paragraph" +An area of text that begins with either the beginning of a file, +an empty line, or a section boundary, and continues until either +an empty line, section boundary, or the end of the file. +.sp +Groups of empty lines (or lines containing only whitespace characters) +are treated as a single paragraph. +.sp +Additional paragraph boundaries can be defined using the +.OP paragraphs +option. +.KY "section" +.IP "section" +An area of text that starts with the beginning of the file or a line +whose first character is an open brace +.PQ { +and continues until the next section or the end of the file. +.sp +Additional section boundaries can be defined using the +.OP sections +option. +.KY "sentence" +.IP "sentence" +An area of text that begins with either the beginning of the file or the +first nonblank character following the previous sentence, paragraph, or +section boundary and continues until the end of the file or a period +.PQ \&. +exclamation point +.PQ ! +or question mark +.PQ ? +character, +followed by either an end-of-line or two whitespace characters. +Any number of closing parentheses +.PQ ) , +brackets +.PQ ] , +double-quote +.PQ """" +or single quote +.PQ ' +characters can appear between the period, exclamation point, +or question mark and the whitespace characters or end-of-line. +.sp +Groups of empty lines (or lines containing only whitespace characters) +are treated as a single sentence. +.SH 1 "Vi Commands" +.pp +The following section describes the commands available in the command +mode of the +.CO vi +editor. +In each entry below, the tag line is a usage synopsis for the command +character. +In addition, the final line and column the cursor rests upon, +and any options which affect the command are noted. +.KY <control-A> +.IP "[count] <control-A>" +Search forward +.LI count +times for the current word. +The current word begins at the first non-whitespace character on or +after the current cursor position, +and extends up to the next non-word character or the end of the line. +The search is literal, i.e. no characters in the word have any special +meaning in terms of Regular Expressions. +It is an error if no matching pattern is found between the starting position +and the end of the file. +.sp +The +.CO <control-A> +command is an absolute movement. +The +.CO <control-A> +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +.SS +.SP Line: +Set to the line where the word is found. +.SP Column: +Set to the first character of the word. +.SP Options: +Affected by the +.OP ignorecase +and +.OP wrapscan +options. +.SE +.KY <control-B> +.IP "[count] <control-B>" +Page backward +.LI count +screens. +Two lines of overlap are maintained, if possible, +by displaying the window starting at line +.LI "(top_line - count * window_size) + 2" , +where +.LI window_size +is the value of the +.OP window +option. +(In the case of split screens, this size is corrected to the +current screen size.) +It is an error if the movement is past the beginning of the file. +.SS +.SP Line: +Set to the last line of text displayed on the screen. +.SP Column: +Set to the first nonblank character of the line. +.SP Options: +Affected by the +.OP window +option. +.SE +.KY <control-D> +.IP "[count] <control-D>" +Scroll forward +.LI count +lines. +If +.LI count +is not specified, scroll forward the number of lines specified by the last +.CO <control-D> +or +.CO <control-U> +command. +If this is the first +.CO <control-D> +or +.CO <control-U> +command, +scroll forward half the number of lines in the screen. +(In the case of split screens, the default scrolling distance is +corrected to half the current screen size.) +It is an error if the movement is past the end of the file. +.SS +.SP Line: +Set to the current line plus the number of lines scrolled. +.SP Column: +Set to the first nonblank character of the line. +.SP Options: +None. +.SE +.KY <control-E> +.IP "[count] <control-E>" +Scroll forward +.LI count +lines, leaving the cursor on the current line and column, if possible. +It is an error if the movement is past the end of the file. +.SS +.SP Line: +Unchanged unless the current line scrolls off the screen, +in which case it is set to the first line on the screen. +.SP Column: +Unchanged unless the current line scrolls off the screen, +in which case it is set to the most attractive cursor position. +.SP Options: +None. +.SE +.KY <control-F> +.IP "[count] <control-F>" +Page forward +.LI count +screens. +Two lines of overlap are maintained, if possible, +by displaying the window starting at line +.LI "top_line + count * window_size - 2" , +where +.LI window_size +is the value of the +.OP window +option. +(In the case of split screens, this size is corrected to the +current screen size.) +It is an error if the movement is past the end of the file. +.SS +.SP Line: +Set to the first line on the screen. +.SP Column: +Set to the first nonblank character of the current line. +.SP Options: +Affected by the +.OP window +option. +.SE +.KY <control-G> +.IP "<control-G>" +Display the file information. +The information includes the current pathname, the current line, +the number of total lines in the file, the current line as a percentage +of the total lines in the file, if the file has been modified, +was able to be locked, if the file's name has been changed, +and if the edit session is read-only. +.SS +.SP Line: +Unchanged. +.SP Column: +Unchanged. +.SP Options: +None. +.SE +.KY <control-H> +.IP "[count] <control-H>" +.Ip "[count] h" +Move the cursor back +.LI count +characters in the current line. +It is an error if the cursor is on the first character in the line. +.sp +The +.CO <control-H> +and +.CO h +commands may be used as the motion component of other +.CO vi +commands, +in which case any text copied into a buffer is character oriented. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the +.LI "current - count" +character, or, the first character in the line if +.LI count +is greater than or equal to the number of characters in the line +before the cursor. +.SP Options: +None. +.SE +.KY <control-J> +.IP "[count] <control-J>" +.KY <control-N> +.Ip "[count] <control-N>" +.KY j +.Ip "[count] j" +Move the cursor down +.LI count +lines without changing the current column. +It is an error if the movement is past the end of the file. +.sp +The +.CO <control-J> , +.CO <control-N> +and +.CO j +commands may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +line oriented. +.SS +.SP Line: +Set to the current line plus +.LI count . +.SP Column: +The most attractive cursor position. +.SP Options: +None. +.SE +.KY <control-L> +.IP "<control-L>" +.KY <control-R> +.Ip "<control-R>" +Repaint the screen. +.SS +.SP Line: +Unchanged. +.SP Column: +Unchanged. +.SP Options: +None. +.SE +.KY <control-M> +.IP "[count] <control-M>" +.KY + +.Ip "[count] +" +Move the cursor down +.LI count +lines to the first nonblank character of that line. +It is an error if the movement is past the end of the file. +.sp +The +.CO <control-M> +and +.CO + +commands may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +line oriented. +.SS +.SP Line: +Set to the current line plus +.LI count . +.SP Column: +Set to the first nonblank character in the line. +.SP Options: +None. +.SE +.KY <control-P> +.IP "[count] <control-P>" +.KY k +.Ip "[count] k" +Move the cursor up +.LI count +lines, without changing the current column. +It is an error if the movement is past the beginning of the file. +.sp +The +.CO <control-P> +and +.CO k +commands may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +line oriented. +.SS +.SP Line: +Set to the current line minus +.LI count . +.SP Column: +The most attractive cursor position. +.SP Options: +None. +.SE +.KY <control-T> +.IP "<control-T>" +Return to the most recent tag context. +The +.CO <control-T> +command is an absolute movement. +.SS +.SP Line: +Set to the context of the previous tag command. +.SP Column: +Set to the context of the previous tag command. +.SP Options: +None. +.SE +.KY <control-U> +.IP "[count] <control-U>" +Scroll backward +.LI count +lines. +If +.LI count +is not specified, scroll backward the number of lines specified by the +last +.CO <control-D> +or +.CO <control-U> +command. +If this is the first +.CO <control-D> +or +.CO <control-U> +command, +scroll backward half the number of lines in the screen. +(In the case of split screens, the default scrolling distance is +corrected to half the current screen size.) +It is an error if the movement is past the beginning of the file. +.SS +.SP Line: +Set to the current line minus the amount scrolled. +.SP Column: +Set to the first nonblank character in the line. +.SP Options: +None. +.SE +.KY <control-W> +.IP "<control-W>" +Switch to the next lower screen in the window, or, to the first +screen if there are no lower screens in the window. +.SS +.SP Line: +Set to the previous cursor position in the window. +.SP Column: +Set to the previous cursor position in the window. +.SP Options: +None. +.SE +.KY <control-Y> +.IP "[count] <control-Y>" +Scroll backward +.LI count +lines, leaving the current line and column as is, if possible. +It is an error if the movement is past the beginning of the file. +.SS +.SP Line: +Unchanged unless the current line scrolls off the screen, +in which case it is set to the last line of text displayed +on the screen. +.SP Column: +Unchanged unless the current line scrolls off the screen, +in which case it is the most attractive cursor position. +.SP Options: +None. +.SE +.KY <control-Z> +.IP "<control-Z>" +Suspend the current editor session. +If the file has been modified since it was last completely written, +and the +.OP autowrite +option is set, the file is written before the editor session is +suspended. +If this write fails, the editor session is not suspended. +.SS +.SP Line: +Unchanged. +.SP Column: +Unchanged. +.SP Options: +Affected by the +.OP autowrite +option. +.SE +.KY <escape> +.IP "<escape>" +Execute +.CO ex +commands or cancel partial commands. +If an +.CO ex +command is being entered (e.g. +.CO / , +.CO ? , +.CO : +or +.CO ! ), +the command is executed. +If a partial command has been entered, e.g. +.QT "[0-9]*" , +or +.QT "[0-9]*[!<>cdy]" , +the command is cancelled. +Otherwise, it is an error. +.SS +.SP Line: +When an +.CO ex +command is being executed, the current line is set as described for +that command. +Otherwise, unchanged. +.SP Column: +When an +.CO ex +command is being executed, the current column is set as described for +that command. +Otherwise, unchanged. +.SP Options: +None. +.SE +.KY <control-]> +.IP "<control-]>" +Push a tag reference onto the tag stack. +The tags files (see the +.OP tags +option for more information) are searched for a tag matching the +current word. +The current word begins at the first non-whitespace character on or +after the current cursor position, +and extends up to the next non-word character or the end of the line. +If a matching tag is found, the current file is discarded and the +file containing the tag reference is edited. +.sp +If the current file has been modified since it was last completely +written, the command will fail. +The +.CO <control-]> +command is an absolute movement. +.SS +.SP Line: +Set to the line containing the matching tag string. +.SP Column: +Set to the start of the matching tag string. +.SP Options: +Affected by the +.OP tags +and +.OP taglength +options. +.SE +.KY <control-^> +.IP "<control-^>" +Switch to the most recently edited file. +.sp +If the file has been modified since it was last completely written, +and the +.OP autowrite +option is set, the file is written out. +If this write fails, the command will fail. +Otherwise, if the current file has been modified since it was last +completely written, the command will fail. +.SS +.SP Line: +Set to the line the cursor was on when the file was last edited. +.SP Column: +Set to the column the cursor was on when the file was last edited. +.SP Options: +Affected by the +.OP autowrite +option. +.SE +.KY <space> +.IP "[count] <space>" +.KY l +.Ip "[count] l" +Move the cursor forward +.LI count +characters without changing the current line. +It is an error if the cursor is on the last character in the line. +.sp +The +.CO <space> +and +.CO \&l +commands may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +In addition, these commands may be used as the motion components +of other commands when the cursor is on the last character in the +line, without error. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the current character plus the next +.LI count +characters, or to the last character on the line if +.LI count +is greater than the number of characters in the line after the +current character. +.SP Options: +None. +.SE +.KY ! +.IP "[count] ! motion shell-argument(s)<carriage-return>" +Replace text with results from a shell command. +Pass the lines specified by the +.LI count +and +.LI motion +arguments as standard input to the program named by the +.OP shell +option, and replace those lines with the output (both +standard error and standard output) of that command. +.sp +After the motion is entered, +.CO vi +prompts for arguments to the shell command. +.sp +Within those arguments, +.QT % +and +.QT # +characters are expanded to the current and alternate pathnames, +respectively. +The +.QT ! +character is expanded with the command text of the previous +.CO ! +or +.CO :! +commands. +(Therefore, the command +.CO !<motion>! +repeats the previous +.CO ! +command.) +The special meanings of +.QT % , +.QT # +and +.QT ! +can be overridden by escaping them with a backslash. +If no +.CO ! +or +.CO :! +command has yet been executed, +it is an error to use an unescaped +.QT ! +character as a shell argument. +The +.CO ! +command does +.i not +do shell expansion on the strings provided as arguments. +If any of the above expansions change the arguments the user entered, +the command is redisplayed at the bottom of the screen. +.sp +.CO Vi +then executes the program named by the +.OP shell +option, with a +.b \-c +flag followed by the arguments (which are bundled into a single argument). +.sp +The +.CO ! +command is permitted in an empty file. +.sp +If the file has been modified since it was last completely written, +the +.CO ! +command will warn you. +.SS +.SP Line: +The first line of the replaced text. +.SP Column: +The first column of the replaced text. +.SP Options: +Affected by the +.OP shell +option. +.SE +.KY # +.IP "[count] # #|+|-" +Increment or decrement the number referenced by the cursor. +If the trailing character is a +.LI \&+ +or +.LI \&# , +the number is incremented by +.LI count . +If the trailing character is a +.LI \&- , +the number is decremented by +.LI count . +.sp +A leading +.QT \&0X +or +.QT \&0x +causes the number to be interpreted as a hexadecimal number. +Otherwise, a leading +.QT \&0 +causes the number to be interpreted as an octal number, unless a non-octal +digit is found as part of the number. +Otherwise, the number is interpreted as a decimal number, and may +have a leading +.LI \&+ +or +.LI \&- +sign. +The current number begins at the first non-blank character at or after +the current cursor position, and extends up to the end of the line or +the first character that isn't a possible character for the numeric type. +The format of the number (e.g. leading 0's, signs) is retained unless +the new value cannot be represented in the previous format. +.sp +Octal and hexadecimal numbers, and the result of the operation, must fit +into an +.QT "unsigned long" . +Similarly, decimal numbers and their result must fit into a +.QT "signed long" . +It is an error to use this command when the cursor is not positioned at +a number. +.sp +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the first character in the cursor number. +.SP Options: +None. +.SE +.KY $ +.IP "[count] $" +Move the cursor to the end of a line. +If +.LI count +is specified, the cursor moves down +.LI "count - 1" +lines. +.sp +It is not an error to use the +.CO $ +command when the cursor is on the last character in the line or +when the line is empty. +.sp +The +.CO $ +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented, unless the cursor is at, or before the first +nonblank character in the line, in which case it is line oriented. +It is not an error to use the +.CO $ +command as a motion component when the cursor is on the last character +in the line, although it is an error when the line is empty. +.SS +.SP Line: +Set to the current line plus +.LI count +minus 1. +.SP Column: +Set to the last character in the line. +.SP Options: +None. +.SE +.KY % +.IP % +Move to the matching character. +The cursor moves to the parenthesis or curly brace which +.i matches +the parenthesis or curly brace found at the current cursor position +or which is the closest one to the right of the cursor on the line. +It is an error to execute the +.CO % +command on a line without a parenthesis or curly brace. +Historically, any +.LI count +specified to the +.CO % +command was ignored. +.sp +The +.CO % +command is an absolute movement. +The +.CO % +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented, unless the starting point of the region is at +or before the first nonblank character on its line, and the ending +point is at or after the last nonblank character on its line, in +which case it is line oriented. +.SS +.SP Line: +Set to the line containing the matching character. +.SP Column: +Set to the matching character. +.SP Options: +None. +.SE +.KY & +.IP "&" +Repeat the previous substitution command on the current line. +.sp +Historically, any +.LI count +specified to the +.CO & +command was ignored. +.SS +.SP Line: +Unchanged. +.SP Column: +Unchanged if the cursor was on the last character in the line, +otherwise, set to the first nonblank character in the line. +.SP Options: +Affected by the +.OP edcompatible , +.OP extended , +.OP ignorecase +and +.OP magic +options. +.SE +.KY SQUOTE<character> +.IP \'<character> +.KY `<character> +.Ip `<character> +Return to a context marked by the character +.LI <character> . +If +.LI <character> +is the +.QT ' +or +.QT ` +character, return to the previous context. +If +.LI <character> +is any other character, +return to the context marked by that character (see the +.CO m +command for more information). +If the command is the +.CO \' +command, only the line value is restored, +and the cursor is placed on the first nonblank character of that line. +If the command is the +.CO ` +command, both the line and column values are restored. +.sp +It is an error if the context no longer exists because of +line deletion. +(Contexts follow lines that are moved, or which are deleted +and then restored.) +.sp +The +.CO \' +and +.CO ` +commands are both absolute movements. +They may be used as a motion component for other +.CO vi +commands. +For the +.CO \' +command, any text copied into a buffer is line oriented. +For the +.CO ` +command, +any text copied into a buffer is character oriented, +unless it both starts and stops at the first character in the line, +in which case it is line oriented. +In addition, when using the +.CO ` +command as a motion component, +commands which move backward and started at the first character in the line, +or move forward and ended at the first character in the line, +are corrected to the last character of the line preceding the starting and +ending lines, respectively. +.SS +.SP Line: +Set to the line from the context. +.SP Column: +Set to the first nonblank character in the line, for the +.CO \' +command, and set to the context's column for the +.CO ` +command. +.SP Options: +None. +.SE +.KY ( +.IP "[count] (" +Back up +.LI count +sentences. +.sp +The +.CO ( +command is an absolute movement. +The +.CO ( +command may be used as the motion component of other +.CO vi +commands, +in which case any text copied into a buffer is character oriented, +unless the starting and stopping points of the region are the first +character in the line, +in which case it is line oriented. +If it is line oriented, +the starting point of the region is adjusted to be the end of the line +immediately before the starting cursor position. +.SS +.SP Line: +Set to the line containing the beginning of the sentence. +.SP Column: +Set to the first nonblank character of the sentence. +.SP Options: +Affected by the +.OP lisp +option. +.SE +.KY ) +.IP "[count] )" +Move forward +.LI count +sentences. +.sp +The +.CO ) +command is an absolute movement. +The +.CO ) +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented, unless the starting point of the region is the +first character in the line, in which case it is line oriented. +In the latter case, if the stopping point of the region is also +the first character in the line, it is adjusted to be the end of the +line immediately before it. +.SS +.SP Line: +Set to the line containing the beginning of the sentence. +.SP Column: +Set to the first nonblank character of the sentence. +.SP Options: +Affected by the +.OP lisp +option. +.SE +.KY , +.IP "[count] ," +Reverse find character +.LI count +times. +Reverse the last +.CO F , +.CO f , +.CO T +or +.CO t +command, searching the other way in the line, +.LI count +times. +It is an error if a +.CO F , +.CO f , +.CO T +or +.CO t +command has not been performed yet. +.sp +The +.CO , +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the searched-for character for the +.CO F +and +.CO f +commands, +before the character for the +.CO t +command +and after the character for the +.CO T +command. +.SP Options: +None. +.SE +.KY MINUSSIGN +.IP "[count] \-" +Move to the first nonblank of the previous line, +.LI count +times. +.sp +It is an error if the movement is past the beginning of the file. +.sp +The +.CO - +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +line oriented. +.SS +.SP Line: +Set to the current line minus +.LI count . +.SP Column: +Set to the first nonblank character in the line. +.SP Options: +None. +.SE +.KY \&. +.IP "[count] \&." +Repeat the last +.CO vi +command that modified text. +The repeated command may be a command and motion component combination. +If +.LI count +is specified, it replaces +.i both +the count specified for the repeated command, and, if applicable, for +the repeated motion component. +If +.LI count +is not specified, the counts originally specified to the command being +repeated are used again. +.sp +As a special case, if the +.CO \. +command is executed immediately after the +.CO u +command, the change log is rolled forward or backward, depending on +the action of the +.CO u +command. +.SS +.SP Line: +Set as described for the repeated command. +.SP Column: +Set as described for the repeated command. +.SP Options: +None. +.SE +.KY /RE/ +.IP "/RE<carriage-return>" +.Ip "/RE/ [offset]<carriage-return>" +.KY ?RE? +.Ip "?RE<carriage-return>" +.Ip "?RE? [offset]<carriage-return>" +.KY N +.Ip "N" +.KY n +.Ip "n" +Search forward or backward for a regular expression. +The commands beginning with a slash +.PQ / +character are forward searches, the commands beginning with a +question mark +.PQ ? +are backward searches. +.CO Vi +prompts with the leading character on the last line of the screen +for a string. +It then searches forward or backward in the file for the next +occurrence of the string, which is interpreted as a Basic Regular +Expression. +.sp +The +.CO / +and +.CO ? +commands are absolute movements. +They may be used as the motion components of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented, unless the search started and ended on +the first column of a line, in which case it is line oriented. +In addition, forward searches ending at the first character of a line, +and backward searches beginning at the first character in the line, +are corrected to begin or end at the last character of the previous line. +(Note, forward and backward searches can occur for both +.CO / +and +.CO ? +commands, if the +.OP wrapscan +option is set.) +.sp +If an offset from the matched line is specified (i.e. a trailing +.QT / +or +.QT ? +character is followed by a signed offset), the buffer will always +be line oriented (e.g. +.QT /string/+0 +will always guarantee a line orientation). +.sp +The +.CO N +command repeats the previous search, but in the reverse direction. +The +.CO n +command repeats the previous search. +If either the +.CO N +or +.CO n +commands are used as motion components for the +.CO ! +command, you will not be prompted for the text of the bang command, +instead the previous bang command will be executed. +.sp +Missing RE's (e.g. +.QT //<carriage-return> , +.QT /<carriage-return> , +.QT ??<carriage-return> , +or +.QT ?<carriage-return> +search for the last search RE, in the indicated direction. +.sp +Searches may be interrupted using the +.LI <interrupt> +character. +.sp +Multiple search patterns may be grouped together by delimiting +them with semicolons and zero or more whitespace characters, e.g. +.LI "/foo/ ; ?bar?" +searches forward for +.LI foo +and then, from that location, backwards for +.LI bar . +When search patterns are grouped together in this manner, +the search patterns are evaluated left to right with the +final cursor position determined by the last search pattern. +.sp +It is also permissible to append a +.CO z +command to the search strings, e.g. +.LI "/foo/ z." +searches forward for the next occurrence of +.LI foo , +and then positions that line in the middle of screen. +.SS +.SP Line: +Set to the line in which the match occurred. +.SP Column: +Set to the first character of the matched string. +.SP Options: +Affected by the +.OP edcompatible , +.OP extended , +.OP ignorecase , +.OP magic , +and +.OP wrapscan +options. +.SE +.KY 0 +.IP "0" +Move to the first character in the current line. +It is not an error to use the +.CO 0 +command when the cursor is on the first character in the line, +.sp +The +.CO 0 +command may be used as the motion component of other +.CO vi +commands, +in which case it is an error if the cursor is on the first character +in the line, +and any text copied into a buffer is character oriented. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the first character in the line. +.SP Options: +None. +.SE +.KY : +.IP ":" +Execute an +.CO ex +command. +.CO Vi +prompts for an +.CO ex +command on the last line of the screen, using a colon +.PQ : +character. +The command is terminated by a +.LI <carriage-return> , +.LI <newline> +or +.LI <escape> +character; all of these characters may be escaped by using a +.LI "<literal-next>" +character. +The command is then executed. +.sp +If the +.CO ex +command writes to the screen, +.CO vi +will prompt the user for a +.LI <carriage-return> +before continuing +when the +.CO ex +command finishes. +Large amounts of output from the +.CO ex +command will be paged for the user, and the user prompted for a +.LI <carriage-return> +or +.LI <space> +key to continue. +In some cases, a quit (normally a +.QQ q +character) or +.LI <interrupt> +may be entered to interrupt the +.CO ex +command. +.sp +When the +.CO ex +command finishes, and the user is prompted to resume visual mode, +it is also possible to enter another +.QT : +character followed by another +.CO ex +command. +.SS +.SP Line: +The current line is set as described for the +.CO ex +command. +.SP Column: +The current column is set as described for the +.CO ex +command. +.SP Options: +Affected as described for the +.CO ex +command. +.SE +.KY ; +.IP "[count] ;" +Repeat the last character find +.LI count +times. +The last character find is one of the +.CO F , +.CO f , +.CO T +or +.CO t +commands. +It is an error if a +.CO F , +.CO f , +.CO T +or +.CO t +command has not been performed yet. +.sp +The +.CO ; +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the searched-for character for the +.CO F +and +.CO f +commands, +before the character for the +.CO t +command +and after the character for the +.CO T +command. +.SP Options: +None. +.SE +.KY < +.IP "[count] < motion" +.KY > +.Ip "[count] > motion" +Shift lines left or right. +Shift the number of lines in the region specified by the +.LI count +and +.LI motion +left (for the +.CO < +command) or right (for the +.CO > +command) by the number of columns specified by the +.OP shiftwidth +option. +Only whitespace characters are deleted when shifting left. +Once the first character in the line no longer contains a whitespace +character, the command will succeed, +but the line will not be modified. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the first nonblank character in the line. +.SP Options: +Affected by the +.OP shiftwidth +option. +.SE +.KY @ +.IP "@ buffer" +Execute a named buffer. +Execute the named buffer as +.CO vi +commands. +The buffer may include +.CO ex +commands, too, but they must be expressed as a +.CO : +command. +If the buffer is line oriented, +.LI <newline> +characters are logically appended to each line of the buffer. +If the buffer is character oriented, +.LI <newline> +characters are logically appended to all but the last line in the buffer. +.sp +If the buffer name is +.QT @ , +or +.QT * , +then the last buffer executed shall be used. +It is an error to specify +.QT @@ +or +.QT @* +if there were no previous buffer executions. +The text of a buffer may contain a +.CO @ +command, +and it is possible to create infinite loops in this manner. +(The +.LI <interrupt> +character may be used to interrupt the loop.) +.SS +.SP Line: +The current line is set as described for the command(s). +.SP Column: +The current column is set as described for the command(s). +.SP Options: +None. +.SE +.KY A +.IP "[count] A" +Enter input mode, appending the text after the end of the line. +If +.LI count +is specified, the text is repeatedly input +.LI "count - 1" +more times after input mode is exited. +.SS +.SP Line: +Set to the last line upon which characters were entered. +.SP Column: +Set to the last character entered. +.SP Options: +Affected by the +.OP altwerase , +.OP autoindent , +.OP beautify , +.OP showmatch , +.OP ttywerase +and +.OP wrapmargin +options. +.SE +.KY B +.IP "[count] B" +Move backward +.LI count +bigwords. +Move the cursor backward to the beginning of a bigword by repeating the +following algorithm: if the current position is at the beginning of a +bigword or the character at the current position cannot be part of a bigword, +move to the first character of the preceding bigword. +Otherwise, move to the first character of the bigword at the current position. +If no preceding bigword exists on the current line, move to the first +character of the last bigword on the first preceding line that contains a +bigword. +.sp +The +.CO B +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +.SS +.SP Line: +Set to the line containing the word selected. +.SP Column: +Set to the first character of the word selected. +.SP Options: +None. +.SE +.KY C +.IP "[buffer] [count] C" +Change text from the current position to the end-of-line. +If +.LI count +is specified, the input text replaces from the current position to +the end-of-line, plus +.LI "count - 1" +subsequent lines. +.SS +.SP Line: +Set to the last line upon which characters were entered. +.SP Column: +Set to the last character entered. +.SP Options: +Affected by the +.OP altwerase , +.OP autoindent , +.OP beautify , +.OP showmatch , +.OP ttywerase +and +.OP wrapmargin +options. +.SE +.KY D +.IP "[buffer] D" +Delete text from the current position to the end-of-line. +.sp +It is not an error to execute the +.CO D +command on an empty line. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the character before the current character, or, column 1 if +the cursor was on column 1. +.SP Options: +None. +.SE +.KY E +.IP "[count] E" +Move forward +.LI count +end-of-bigwords. +Move the cursor forward to the end of a bigword by repeating the +following algorithm: if the current position is the end of a +bigword or the character at that position cannot be part of a bigword, +move to the last character of the following bigword. +Otherwise, move to the last character of the bigword at the current +position. +If no succeeding bigword exists on the current line, +move to the last character of the first bigword on the next following +line that contains a bigword. +.sp +The +.CO E +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +.SS +.SP Line: +Set to the line containing the word selected. +.SP Column: +Set to the last character of the word selected. +.SP Options: +None. +.SE +.KY F +.IP "[count] F <character>" +Search +.LI count +times backward through the current line for +.LI <character> . +.sp +The +.CO F +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the searched-for character. +.SP Options: +None. +.SE +.KY G +.IP "[count] G" +Move to line +.LI count , +or the last line of the file if +.LI count +not specified. +.sp +The +.CO G +command is an absolute movement. +The +.CO \&G +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +line oriented. +.SS +.SP Line: +Set to +.LI count , +if specified, otherwise, the last line. +.SP Column: +Set to the first nonblank character in the line. +.SP Options: +None. +.SE +.KY H +.IP "[count] H" +Move to the screen line +.LI "count - 1" +lines below the top of the screen. +.sp +The +.CO H +command is an absolute movement. +The +.CO H +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +line oriented. +.SS +.SP Line: +Set to the line +.LI "count - 1" +lines below the top of the screen. +.SP Column: +Set to the first nonblank character of the +.i screen +line. +.SP Options: +None. +.SE +.KY I +.IP "[count] I" +Enter input mode, inserting the text at the beginning of the line. +If +.LI count +is specified, the text input is repeatedly input +.LI "count - 1" +more times. +.SS +.SP Line: +Set to the last line upon which characters were entered. +.SP Column: +Set to the last character entered. +.SP Options: +None. +.SE +.KY J +.IP "[count] J" +Join lines. +If +.LI count +is specified, +.LI count +lines are joined; a minimum of two lines are always joined, +regardless of the value of +.LI count . +.sp +If the current line ends with a whitespace character, all whitespace +is stripped from the next line. +Otherwise, if the next line starts with a open parenthesis +.PQ ( +do nothing. +Otherwise, if the current line ends with a question mark +.PQ ? , +period +.PQ \&. +or exclamation point +.PQ ! , +insert two spaces. +Otherwise, insert a single space. +.sp +It is not an error to join lines past the end of the file, +i.e. lines that do not exist. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the character after the last character of the next-to-last +joined line. +.SP Options: +None. +.SE +.KY L +.IP "[count] L" +Move to the screen line +.LI "count - 1" +lines above the bottom of the screen. +.sp +The +.CO L +command is an absolute movement. +The +.CO L +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +line oriented. +.SS +.SP Line: +Set to the line +.LI "count - 1" +lines above the bottom of the screen. +.SP Column: +Set to the first nonblank character of the +.i screen +line. +.SP Options: +None. +.SE +.KY M +.IP " M" +Move to the screen line in the middle of the screen. +.sp +The +.CO M +command is an absolute movement. +The +.CO M +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +line oriented. +.sp +Historically, any +.LI count +specified to the +.CO M +command was ignored. +.SS +.SP Line: +Set to the line in the middle of the screen. +.SP Column: +Set to the first nonblank character of the +.i screen +line. +.SP Options: +None. +.SE +.KY O +.IP "[count] O" +Enter input mode, appending text in a new line above the current line. +If +.LI count +is specified, the text input is repeatedly input +.LI "count - 1" +more times. +.sp +Historically, any +.LI count +specified to the +.CO O +command was ignored. +.SS +.SP Line: +Set to the last line upon which characters were entered. +.SP Column: +Set to the last character entered. +.SP Options: +Affected by the +.OP altwerase , +.OP autoindent , +.OP beautify , +.OP showmatch , +.OP ttywerase +and +.OP wrapmargin +options. +.SE +.KY P +.IP "[buffer] P" +Insert text from a buffer. +Text from the buffer (the unnamed buffer by default) is inserted +before the current column or, if the buffer is line oriented, +before the current line. +.SS +.SP Line: +Set to the lowest numbered line insert, +if the buffer is line oriented, otherwise unchanged. +.SP Column: +Set to the first nonblank character of the appended text, +if the buffer is line oriented, otherwise, the last character +of the appended text. +.SP Options: +None. +.SE +.KY Q +.IP "Q" +Exit +.CO vi +(or visual) mode and switch to +.CO ex +mode. +.SS +.SP Line: +Unchanged. +.SP Column: +No longer relevant. +.SP Options: +None. +.SE +.KY R +.IP "[count] R" +Enter input mode, replacing the characters in the current line. +If +.LI count +is specified, the text input is repeatedly input +.LI "count - 1" +more times. +.sp +If the end of the current line is reached, no more characters are +replaced and any further characters input are appended to the line. +.SS +.SP Line: +Set to the last line upon which characters were entered. +.SP Column: +Set to the last character entered. +.SP Options: +Affected by the +.OP altwerase , +.OP autoindent , +.OP beautify , +.OP showmatch , +.OP ttywerase +and +.OP wrapmargin +options. +.SE +.KY S +.IP "[buffer] [count] S" +Substitute +.LI count +lines. +.SS +.SP Line: +Set to the last line upon which characters were entered. +.SP Column: +Set to the last character entered. +.SP Options: +Affected by the +.OP altwerase , +.OP autoindent , +.OP beautify , +.OP showmatch , +.OP ttywerase +and +.OP wrapmargin +options. +.SE +.KY T +.IP "[count] T <character>" +Search backward, +.LI count +times, +through the current line for the character +.i after +the specified +.LI <character> . +.sp +The +.CO T +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the character +.i after +the searched-for character. +.SP Options: +None. +.SE +.KY U +.IP "U" +Restore the current line to its state before the cursor last +moved to it. +.SS +.SP Line: +Unchanged. +.SP Column: +The first character in the line. +.SP Options: +None. +.SE +.KY W +.IP "[count] W" +Move forward +.LI count +bigwords. +Move the cursor forward to the beginning of a bigword by repeating the +following algorithm: if the current position is within a bigword or the +character at that position cannot be part of a bigword, move to the first +character of the next bigword. +If no subsequent bigword exists on the current line, +move to the first character of the first bigword on the first following +line that contains a bigword. +.sp +The +.CO W +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +.SS +.SP Line: +The line containing the word selected. +.SP Column: +The first character of the word selected. +.SP Options: +None. +.SE +.KY X +.IP "[buffer] [count] X" +Delete +.LI count +characters before the cursor. +If the number of characters to be deleted is greater than or equal to +the number of characters to the beginning of the line, all of the +characters before the current cursor position, to the beginning of the +line, are deleted. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the current character minus +.LI count , +or the first character if count is greater than the number of +characters in the line before the cursor. +.SP Options: +None. +.SE +.KY Y +.IP "[buffer] [count] Y" +Copy (or +.QQ yank ) +.LI count +lines into the specified buffer. +.SS +.SP Line: +Unchanged. +.SP Column: +Unchanged. +.SP Options: +None. +.SE +.KY ZZ +.IP "ZZ" +Write the file and exit +.CO vi . +The file is only written if it has been modified since the last +complete write of the file to any file. +.sp +The +.CO ZZ +command will exit the editor after writing the file, +if there are no further files to edit. +Entering two +.QQ quit +commands (i.e. +.CO wq , +.CO quit , +.CO xit +or +.CO ZZ ) +in a row will override this check and the editor will exit, +ignoring any files that have not yet been edited. +.SS +.SP Line: +Unchanged. +.SP Column: +Unchanged. +.SP Options: +None. +.SE +.KY [[ +.IP "[count] [[" +Back up +.LI count +section boundaries. +.sp +The +.CO [[ +command is an absolute movement. +The +.CO [[ +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented, unless the starting position is column 0, +in which case it is line oriented. +.sp +It is an error if the movement is past the beginning of the file. +.SS +.SP Line: +Set to the previous line that is +.LI count +section boundaries back, +or the first line of the file if no more section boundaries exist +preceding the current line. +.SP Column: +Set to the first nonblank character in the line. +.SP Options: +Affected by the +.OP sections +option. +.SE +.KY ]] +.IP "[count] ]]" +Move forward +.LI count +section boundaries. +.sp +The +.CO ]] +command is an absolute movement. +The +.CO ]] +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented, unless the starting position is column 0, +in which case it is line oriented. +.sp +It is an error if the movement is past the end of the file. +.SS +.SP Line: +Set to the line that is +.LI count +section boundaries forward, +or to the last line of the file if no more section +boundaries exist following the current line. +.SP Column: +Set to the first nonblank character in the line. +.SP Options: +Affected by the +.OP sections +option. +.SE +.KY ^ +.IP "\&^" +Move to first nonblank character on the current line. +.sp +The +.CO ^ +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the first nonblank character of the current line. +.SP Options: +None. +.SE +.KY _ +.IP "[count] _" +Move down +.LI "count - 1" +lines, to the first nonblank character. +The +.CO _ +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +line oriented. +.sp +It is not an error to execute the +.CO _ +command when the cursor is on the first character in the line. +.SS +.SP Line: +The current line plus +.LI "count - 1" . +.SP Column: +The first nonblank character in the line. +.SP Options: +None. +.SE +.KY a +.IP "[count] a" +Enter input mode, appending the text after the cursor. +If +.LI count +is specified, the text input is repeatedly input +.LI "count - 1" +more times. +.SS +.SP Line: +Set to the last line upon which characters were entered. +.SP Column: +Set to the last character entered. +.SP Options: +Affected by the +.OP altwerase , +.OP autoindent , +.OP beautify , +.OP showmatch , +.OP ttywerase +and +.OP wrapmargin +options. +.SE +.KY b +.IP "[count] b" +Move backward +.LI count +words. +Move the cursor backward to the beginning of a word by repeating the +following algorithm: if the current position is at the beginning of a word, +move to the first character of the preceding word. +Otherwise, the current position moves to the first character of the word +at the current position. +If no preceding word exists on the current line, move to the first +character of the last word on the first preceding line that contains +a word. +.sp +The +.CO b +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +.SS +.SP Line: +Set to the line containing the word selected. +.SP Column: +Set to the first character of the word selected. +.SP Options: +None. +.SE +.KY c +.IP "[buffer] [count] c motion" +Change the region of text specified by the +.LI count +and +.LI motion . +If only part of a single line is affected, then the last character +being changed is marked with a +.QT $ . +Otherwise, the region of text is deleted, and input mode is entered. +.SS +.SP Line: +Set to the last line upon which characters were entered. +.SP Column: +Set to the last character entered. +.SP Options: +Affected by the +.OP altwerase , +.OP autoindent , +.OP beautify , +.OP showmatch , +.OP ttywerase +and +.OP wrapmargin +options. +.SE +.KY d +.IP "[buffer] [count] d motion" +Delete the region of text specified by the +.LI count +and +.LI motion . +.SS +.SP Line: +Set to the line where the region starts. +.SP Column: +Set to the first character in the line after the last character in the +region. +If no such character exists, set to the last character before the region. +.SP Options: +None. +.SE +.KY e +.IP "[count] e" +Move forward +.LI count +end-of-words. +Move the cursor forward to the end of a word by repeating the following +algorithm: if the current position is the end of a word, +move to the last character of the following word. +Otherwise, move to the last character of the word at the current position. +If no succeeding word exists on the current line, move to the last character +of the first word on the next following line that contains a word. +.sp +The +.CO e +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +.SS +.SP Line: +Set to the line containing the word selected. +.SP Column: +Set to the last character of the word selected. +.SP Options: +None. +.SE +.KY f +.IP "[count] f <character>" +Search forward, +.LI count +times, through the rest of the current line for +.LI <character> . +.sp +The +.CO f +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the searched-for character. +.SP Options: +None. +.SE +.KY i +.IP "[count] i" +Enter input mode, inserting the text before the cursor. +If +.LI count +is specified, the text input is repeatedly input +.LI "count - 1" +more times. +.SS +.SP Line: +Set to the last line upon which characters were entered. +.SP Column: +Set to the last character entered. +.SP Options: +Affected by the +.OP altwerase , +.OP autoindent , +.OP beautify , +.OP showmatch , +.OP ttywerase +and +.OP wrapmargin +options. +.SE +.KY m +.IP "m <character>" +Save the current context (line and column) as +.LI <character> . +The exact position is referred to by +.QT `<character> . +The line is referred to by +.QT '<character> . +.sp +Historically, +.LI <character> +was restricted to lower-case letters. +.CO Nvi +permits the use of any character. +.SS +.SP Line: +Unchanged. +.SP Column: +Unchanged. +.SP Options: +None. +.SE +.KY o +.IP "[count] o" +Enter input mode, appending text in a new line under the current line. +If +.LI count +is specified, the text input is repeatedly input +.LI "count - 1" +more times. +.sp +Historically, any +.LI count +specified to the +.CO o +command was ignored. +.SS +.SP Line: +Set to the last line upon which characters were entered. +.SP Column: +Set to the last character entered. +.SP Options: +Affected by the +.OP altwerase , +.OP autoindent , +.OP beautify , +.OP showmatch , +.OP ttywerase +and +.OP wrapmargin +options. +.SE +.KY p +.IP "[buffer] p" +Append text from a buffer. +Text from the buffer (the unnamed buffer by default) is appended +after the current column or, if the buffer is line oriented, +after the current line. +.SS +.SP Line: +Set to the first line appended, if the buffer is line oriented, +otherwise unchanged. +.SP Column: +Set to the first nonblank character of the appended text if the buffer +is line oriented, otherwise, the last character of the appended text. +.SP Options: +None. +.SE +.KY r +.IP "[count] r <character>" +Replace characters. +The next +.LI count +characters in the line are replaced with +.LI <character> . +Replacing characters with +.LI <newline> +characters results in creating new, empty lines into the file. +.sp +If +.LI <character> +is +.LI <escape> , +the command is cancelled. +.SS +.SP Line: +Unchanged unless the replacement character is a +.LI <newline> , +in which case it is set to the current line plus +.LI "count - 1" . +.SP Column: +Set to the last character replaced, +unless the replacement character is a +.LI <newline> , +in which case the cursor is in column 1 of the last line inserted. +.SP Options: +None. +.SE +.KY s +.IP "[buffer] [count] s" +Substitute +.LI count +characters in the current line starting with the current character. +.SS +.SP Line: +Set to the last line upon which characters were entered. +.SP Column: +Set to the last character entered. +.SP Options: +Affected by the +.OP altwerase , +.OP autoindent , +.OP beautify , +.OP showmatch , +.OP ttywerase +and +.OP wrapmargin +options. +.SE +.KY t +.IP "[count] t <character>" +Search forward, +.LI count +times, through the current line for the character immediately +.i before +.LI <character> . +.sp +The +.CO t +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the character +.i before +the searched-for character. +.SP Options: +None. +.SE +.KY u +.IP "u" +Undo the last change made to the file. +If repeated, the +.CO u +command alternates between these two states, and is its own inverse. +When used after an insert that inserted text on more than one line, +the lines are saved in the numeric buffers. +.sp +The +.CO \&. +command, when used immediately after the +.CO u +command, causes the change log to be rolled forward or backward, +depending on the action of the +.CO u +command. +.SS +.SP Line: +Set to the position of the first line changed, if the reversal affects +only one line or represents an addition or change; otherwise, the line +preceding the deleted text. +.SP Column: +Set to the cursor position before the change was made. +.SP Options: +None. +.SE +.KY w +.IP "[count] w" +Move forward +.LI count +words. +Move the cursor forward to the beginning of a word by repeating the +following algorithm: if the current position is at the +beginning of a word, move to the first character of the next word. +If no subsequent word exists on the current line, move to the first +character of the first word on the first following line that contains +a word. +.sp +The +.CO w +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +.SS +.SP Line: +Set to the line containing the word selected. +.SP Column: +Set to the first character of the word selected. +.SP Options: +None. +.SE +.KY x +.IP "[buffer] [count] x" +Delete +.LI count +characters. +The deletion is at the current character position. +If the number of characters to be deleted is greater than or equal to +the number of characters to the end of the line, all of the characters +from the current cursor position to the end of the line are deleted. +.SS +.SP Line: +Unchanged. +.SP Column: +Unchanged unless the last character in the line is deleted and the cursor +is not already on the first character in the line, in which case it is +set to the previous character. +.SP Options: +None. +.SE +.KY y +.IP "[buffer] [count] y motion" +Copy (or +.QQ yank ) +the text region specified by the +.LI count +and +.LI motion , +into a buffer. +.SS +.SP Line: +Unchanged, unless the region covers more than a single line, +in which case it is set to the line where the region starts. +.SP Column: +Unchanged, unless the region covers more than a single line, +in which case it is set to the character were the region starts. +.SP Options: +None. +.SE +.KY z +.IP "[count1] z [count2] type" +Redraw the screen with a window +.LI count2 +lines long, with line +.LI count1 +placed as specified by the +.LI type +character. +If +.LI count1 +is not specified, it defaults to the current line. +If +.LI count2 +is not specified, it defaults to the current window size. +.sp +The following +.LI type +characters may be used: +.SS +.SP + +If +.LI count1 +is specified, place the line +.LI count1 +at the top of the screen. +Otherwise, display the screen after the current screen, similarly to the +.CO <control-F> +command. +.SP <carriage-return> +Place the line +.LI count1 +at the top of the screen. +.SP \&. +Place the line +.LI count1 +in the center of the screen. +.SP \- +Place the line +.LI count1 +at the bottom of the screen. +.SP ^ +If +.LI count1 +is specified, place the line that is at the top of the screen +when +.LI count1 +is at the bottom of the screen, at the bottom of the screen, +i.e. display the screen before the screen before +.LI count1 . +Otherwise, display the screen before the current screen, similarly to the +.CO <control-B> +command. +.SE +.SS +.SP Line: +Set to +.LI count1 +unless +.LI count1 +is not specified and the +.LI type +character was either +.QT ^ +or +.QT + , +in which case it is set to the line before the first line on the +previous screen or the line after the last line on the previous +screen, respectively. +.SP Column: +Set to the first nonblank character in the line. +.SP Options: +None. +.SE +.KY { +.IP "[count] {" +Move backward +.LI count +paragraphs. +.sp +The +.CO { +command is an absolute movement. +The +.CO { +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented, unless the starting character is the first +character on its line, in which case it is line oriented. +.SS +.SP Line: +Set to the line containing the beginning of the previous paragraph. +.SP Column: +Set to the first nonblank character in the line. +.SP Options: +Affected by the +.OP paragraph +option. +.SE +.KY | +.IP "[count] |" +Move to a specific +.i column +position on the current line. +.sp +The +.CO | +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented. +It is an error to use the +.CO | +command as a motion component and for the cursor not to move. +.SS +.SP Line: +Unchanged. +.SP Column: +Set to the character occupying the column position identified by +.LI count , +if the position exists in the line. +If the column length of the current line is less than +.LI count , +the cursor is moved to the last character in the line. +.SP Options: +None. +.SE +.KY } +.IP "[count] }" +Move forward +.LI count +paragraphs. +.sp +The +.CO } +command is an absolute movement. +The +.CO } +command may be used as the motion component of other +.CO vi +commands, in which case any text copied into a buffer is +character oriented, unless the starting character is at or +before any nonblank characters in its line, +in which case it is line oriented. +.SS +.SP Line: +Set to the line containing the beginning of the next paragraph. +.SP Column: +Set to the first nonblank character in the line. +.SP Options: +Affected by the +.OP paragraph +option. +.SE +.KY ~ +.IP "[count] ~" +Reverse the case of the next +.LI count +character(s). +This is the historic semantic for the +.CO ~ +command and it is only in effect if the +.OP tildeop +option is not set. +.sp +Lowercase alphabetic characters are changed to uppercase, +and uppercase characters are changed to lowercase. +No other characters are affected. +.sp +Historically, the +.CO ~ +command did not take an associated count, nor did it move past the +end of the current line. +As it had no associated motion it was difficult to change the case +of large blocks of text. +In +.CO nvi , +if the cursor is on the last character of a line, and there are +more lines in the file, the cursor moves to the next line. +.sp +It is not an error to specify a count larger than the number of +characters between the cursor and the end of the file. +.SS +.SP Line: +Set to the line of the character after +.LI count +characters, or, end of file. +.SP Column: +Set to the character after +.LI count +characters, or, end-of-file. +.SP Options: +Affected by the +.OP tildeop +option. +.SE +.KY ~ +.IP "[count] ~ motion" +Reverse the case of the characters in a text region specified by the +.LI count +and +.LI motion . +Only in effect if the +.OP tildeop +option is set. +.sp +Lowercase characters are changed to uppercase, +and uppercase characters are changed to lowercase. +No other characters are affected. +.SS +.SP Line: +Set to the line of the character after the last character in the region. +.SP Column: +Set to the character after the last character in the region. +.SP Options: +Affected by the +.OP tildeop +option. +.SE +.KY <interrupt> +.IP "<interrupt>" +Interrupt the current operation. +Many of the potentially long-running +.CO vi +commands may be interrupted using the terminal interrupt character. +These operations include searches, file reading and writing, filter +operations and map character expansion. +Interrupts are also enabled when running commands outside of +.CO vi . +.sp +If the +.LI <interrupt> +character is used to interrupt while entering an +.CO ex +command, the command is aborted, the cursor returns to its previous +position, and +.CO vi +remains in command mode. +.sp +Generally, if the +.LI <interrupt> +character is used to interrupt any +operation, any changes made before the interrupt are left in place. +.SS +.SP Line: +Dependent on the operation being interrupted. +.SP Column: +Dependent on the operation being interrupted. +.SP Options: +None. +.SH 1 "Vi Text Input Commands" +.pp +The following section describes the commands available in the text +input mode of the +.CO vi +editor. +.pp +Historically, +.CO vi +implementations only permitted the characters inserted on the current +line to be erased. +In addition, only the +.LI <control-D> +erase character and the +.QT 0<control-D> +and +.QT ^<control-D> +erase strings could erase autoindent characters. +(Autoindent characters include both the characters inserted automatically +at the beginning of an input line as well as characters inserted using the +.LI <control-T> +command.) +This implementation permits erasure to continue past the beginning +of the current line, and back to where text input mode was entered. +In addition, autoindent characters may be erased using the standard +erase characters. +For the line and word erase characters, reaching the autoindent +characters forms a +.QQ soft +boundary, denoting the end of the current word or line erase. +Repeating the word or line erase key will erase the autoindent characters. +.pp +Historically, +.CO vi +always used +.LI <control-H> +and +.LI <control-W> +as character and word erase characters, respectively, regardless of +the current terminal settings. +This implementation accepts, in addition to these two characters, +the current terminal characters for those operations. +.KY <nul> +.IP "<nul>" +If the first character of the input is a +.LI <nul> , +the previous input is replayed, as if just entered. +.KY <control-D> +.IP "<control-D>" +If the previous character on the line was an autoindent character, +erase characters to move the cursor back to the column immediately +after the previous (1-based) column which is a multiple of the +.OP shiftwidth +edit option. +This may result in any number of +.LI <tab> +and +.LI <space> +characters preceding the cursor being changed. +.sp +Otherwise, if the +.OP autoindent +option is set and the user is entering the first character in the line, +.LI <control-D> +is ignored. +Otherwise, a literal +.LI <control-D> +character is entered. +.KY ^<control-D> +.IP "^<control-D>" +If the previous character on the line was an autoindent character, +erase all of the autoindent characters on the line. +In addition, the autoindent level is reset to 0. +.KY 0<control-D> +.IP "0<control-D>" +If the previous character on the line was an autoindent character, +erase all of the autoindent characters on the line. +The autoindent level is not altered. +.KY <control-T> +.IP "<control-T>" +Insert sufficient +.LI <tab> +and +.LI <space> +characters to move the cursor forward to the column immediately +after the next (1-based) column which is a multiple of the +.OP shiftwidth +edit option. +This may result in any number of +.LI <tab> +and +.LI <space> +characters preceding the cursor being changed. +.sp +Historically, +.CO vi +did not permit the +.LI <control-T> +command to be used unless the cursor was at the first column of a new +line or it was preceded only by autoindent characters. +.CO Nvi +permits it to be used at any time during insert mode. +.KY <erase> +.IP <erase> +.KY <control-H> +.Ip <control-H> +Erase the last character. +.KY "<literal-next>" +.IP "<literal-next>" +Quote the next character. +The next character will not be mapped (see the +.CO map +command for more information) +or interpreted specially. +A carat +.PQ ^ +character will be displayed immediately as a placeholder, +but will be replaced by the next character. +.KY <escape> +.IP <escape> +If on the colon command line, and the +.OP filec +edit option is set, behave as described for that option. +Otherwise, if on the colon command line, +execute the command. +Otherwise, if not on the colon command line, +resolve all text input into the file, and return to command mode. +.KY "<line erase>" +.IP "<line erase>" +Erase the current line. +.KY "<control-W>" +.IP "<control-W>" +.KY "<word erase>" +.Ip "<word erase>" +Erase the last word. +The definition of word is dependent on the +.OP altwerase +and +.OP ttywerase +options. +.KY "<control-X>" +.IP "<control-X>[0-9A-Fa-f]+" +Insert a character with the specified hexadecimal value into the text. +The value is delimited by any non-hexadecimal character or the input +of the maximum number of characters that can be translated into a single +character value. +.KY <interrupt> +.IP "<interrupt>" +Interrupt text input mode, returning to command mode. +If the +.LI <interrupt> +character is used to interrupt inserting text into the file, +it is as if the +.LI <escape> +character was used; all text input up to the interruption is +resolved into the file. diff --git a/contrib/nvi/docs/USD.doc/vi.ref/vi.ref b/contrib/nvi/docs/USD.doc/vi.ref/vi.ref new file mode 100644 index 000000000000..a880c1659e11 --- /dev/null +++ b/contrib/nvi/docs/USD.doc/vi.ref/vi.ref @@ -0,0 +1,1840 @@ +.\" Copyright (c) 1994 +.\" The Regents of the University of California. All rights reserved. +.\" Copyright (c) 1994, 1995, 1996 +.\" Keith Bostic. All rights reserved. +.\" +.\" This document may not be republished without written permission from +.\" Keith Bostic. +.\" +.\" See the LICENSE file for redistribution information. +.\" +.\" @(#)vi.ref 8.88 (Berkeley) 10/19/96 +.\" +.\" +.so ref.so +.tp +.(l C +.ps 12 +.ft B +Vi/Ex Reference Manual +.ft +.ps +.sp +.i "Keith Bostic" +.sp +Computer Science Division +Department of Electrical Engineering and Computer Science +University of California, Berkeley +Berkeley, California 94720 +.sp 1 +\*(td +.)l +.sp 3 +.(l C +.i Abstract +.)l +.(q +.pp +This document is the reference guide for the 4.4BSD +implementations of +.EV nex nvi , +which are implementations of the historic Berkeley +.EV ex vi +editors. +.)q +.sp 3 +.(l C +.i Licensing +.)l +.sp +.lp +Copyright (c) 1991, 1992, 1993, 1994 +.ti +5 +The Regents of the University of California. All Rights Reserved. +.lp +Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996 +.ti +5 +Keith Bostic. All Rights Reserved. +.sp +.pp +The vi program is freely redistributable. You are welcome to copy, +modify and share it with others under the conditions listed in the +LICENSE file. If any company (not individual!) finds vi sufficiently +useful that you would have purchased it, or if any company wishes to +redistribute it, contributions to the authors would be appreciated. +.bp 2 +.(l C +.i Acknowledgements +.)l +.sp +.(q +.pp +Bruce Englar encouraged the early development of the historic +.EV ex vi +editor. +Peter Kessler helped bring sanity to version 2's command layout. +Bill Joy wrote versions 1 and 2.0 through 2.7, +and created the framework that users see in the present editor. +Mark Horton added macros and other features and made +.EV ex vi +work on a large number of terminals and Unix systems. +.pp +.CO Nvi +is originally derived from software contributed to the University of +California, Berkeley by Steve Kirkendall, the author of the +.CO vi +clone +.CO elvis . +.pp +IEEE Standard Portable Operating System Interface for Computer +Environments (POSIX) 1003.2 style Regular Expression support was +done by Henry Spencer. +.pp +The curses library was originally done by Ken Arnold. +Scrolling and reworking for +.CO nvi +was done by Elan Amir. +.pp +George Neville-Neil added the Tcl interpreter, +and Sven Verdoolaege added the Perl interpreter. +.pp +Rob Mayoff added Cscope support. +.pp +The Institute of Electrical and Electronics Engineers has +given us permission to reprint portions of their documentation. +Portions of this document are reprinted and reproduced from +IEEE Std 1003.2-1992, IEEE Standard Portable Operating +System Interface for Computer Environments (POSIX), +copyright 1992 by the Institute of Electrical and Electronics +Engineers, Inc. +.pp +The financial support of UUNET Communications Services is gratefully +acknowledged. +.)q +.sy echo -n >index +.oh 'Vi/Ex Reference''USD:13-%' +.eh 'USD:13-%''Vi/Ex Reference' +.bp 4 +.SH 1 Description +.pp +.CO Vi +is a screen oriented text editor. +.CO Ex +is a line-oriented text editor. +.CO Ex +and +.CO vi +are different interfaces to the same program, +and it is possible to switch back and forth during an edit session. +.CO View +is the equivalent of using the +.b \-R +(read-only) option of +.CO vi . +.pp +This reference manual is the one provided with the +.EV nex nvi +versions of the +.EV ex vi +text editors. +.EV Nex nvi +are intended as bug-for-bug compatible replacements for the original +Fourth Berkeley Software Distribution (4BSD) +.EV ex vi +programs. +This reference manual is accompanied by a traditional-style manual page. +That manual page describes the functionality found in +.EV ex vi +in far less detail than the description here. +In addition, it describes the system interface to +.EV ex vi , +e.g. command line options, session recovery, signals, +environmental variables, and similar things. +.pp +This reference is intended for users already familiar with +.EV ex vi . +Anyone else should almost certainly read a good tutorial on the +editor first. +If you are in an unfamiliar environment, +and you absolutely have to get work done immediately, +see the section entitled +.QB "Fast Startup" +in the manual page. +It is probably enough to get you started. +.pp +There are a few features in +.EV nex nvi +that are not found in historic versions of +.EV ex vi . +Some of the more interesting of those features are briefly described +in the next section, entitled +.QB "Additional Features" . +For the rest of this document, +.EV nex nvi +is used only when it is necessary to distinguish it from the historic +implementations of +.EV ex vi . +.pp +Future versions of this software will be periodically made available +by anonymous ftp, and can be retrieved from +.LI ftp.cs.berkeley.edu , +in the directory +.LI ucb/4bsd . +.SH 1 "Additional Features in Nex/Nvi" +.pp +There are a few features in +.EV nex nvi +that are not found in historic versions of +.EV ex vi . +Some of the more interesting of these are as follows: +.IP "8-bit clean data, large lines, files" +.EV Nex nvi +will edit any format file. +Line lengths are limited by available memory, +and file sizes are limited by available disk space. +The +.CO vi +text input mode command +.CO <control-X> +can insert any possible character value into the text. +.IP "Background and foreground screens" +The +.CO bg +command backgrounds the current screen, and the +.CO fg +command foregrounds backgrounded screens. +The +.CO display +command can be used to list the background screens. +.IP "Command Editing" +You can enter a normal editing window on the collected commands that +you've entered on the +.CO vi +colon command-line, +and then modify and/or execute the commands. +See the +.OP cedit +edit option for more information. +.IP "Displays" +The +.CO display +command can be used to display the current buffers, the backgrounded +screens, and the tags stack. +.IP "Extended Regular Expressions" +The +.CO extended +option causes Regular Expressions to be interpreted as as Extended +Regular Expressions, (i.e. \fIegrep\fP(1) style Regular Expressions). +.IP "File Name Completion" +It is possible to do file name completion and file name displays when +entering commands on the +.CO vi +colon command-line. +See the +.OP filec +option for more information. +.IP "Infinite undo" +Changes made during an edit session may be rolled backward and forward. +A +.CO \&. +command immediately after a +.CO u +command continues either forward or backward depending on whether the +.CO u +command was an undo or a redo. +.IP "Left-right scrolling" +The +.CO leftright +option causes +.CO nvi +to do left-right screen scrolling, instead of the traditional +.CO vi +line wrapping. +.IP "Message Catalogs" +It is possible to display informational and error messages in different +languages by providing a catalog of messages. +See the +.OP msgcat +option and the file +.LI "catalog/README" +for more information. +.IP "Incrementing numbers" +The +.CO \&# +command increments or decrements the number referenced by the cursor. +.IP "Previous file" +The +.CO previous +command edits the previous file from the argument list. +.IP "Scripting languages" +The +.CO ":pe[rl] cmd" , +.CO ":perld[o] cmd" +and +.CO ":tc[l] cmd" +commands execute Perl and Tcl/Tk commands, respectively, +on lines from the edit buffer. +See the +.QB "Scripting Languages" +section and the specific commands for more information. +.\".IP "Shell screens" +.\"The +.\".CO ":sc[ript] [file ...]" +.\"command runs a shell in the screen. +.\"Editing is unchanged, with the exception that a \fC<carriage-return>\fP +.\"enters the current line (stripped of any prompt) as input to the +.\"shell. +.IP "Split screens" +The +.CO Edit , +.CO Ex , +.CO Next , +.CO Previous , +.CO Tag +and +.CO Visual +(in +.CO vi +mode) commands divide the screen into multiple editing regions and +then perform their normal function in a new screen area. +The +.CO <control-W> +command rotates between the foreground screens. +The +.CO resize +command can be used to grow or shrink a particular screen. +.IP "Tag stacks" +Tags are now maintained in a stack. +The +.CO <control-T> +command returns to the previous tag location. +The +.CO tagpop +command returns to the most recent tag location by default, or, +optionally to a specific tag number in the tag stack, +or the most recent tag from a specified file. +The +.CO display +command can be used to list the tags stack. +The +.CO tagtop +command returns to the top of the tag stack. +.IP "Usage information" +The +.CO exusage +and +.CO viusage +commands provide usage information for all of the +.CO ex +and +.CO vi +commands by default, or, optionally, for a specific command or key. +.IP "Word search" +The +.CO <control-A> +command searches for the word referenced by the cursor. +.SH 1 "Startup Information" +.pp +.EV Ex vi +interprets one of two possible environmental variables and reads up to +three of five possible files during startup. +The variables and files are expected to contain +.CO ex +commands, not +.CO vi +commands. +In addition, they are interpreted +.i before +the file to be edited is read, and therefore many +.CO ex +commands may not be used. +Generally, any command that requires output to the screen or that +needs a file upon which to operate, will cause an error if included +in a startup file or environmental variable. +.pp +Because the +.CO ex +command set supported by +.EV nex nvi +is a superset of the command set supported by historical implementations of +.CO ex , +.EV nex nvi +can use the startup files created for the historical implementations, +but the converse may not be true. +.pp +If the +.b \-s +(the historic \- option) +is specified, or if standard input is redirected from a file, +all environmental variables and startup files are ignored. +.pp +Otherwise, startup files and environmental variables are handled +in the following order: +.np +The file +.LI /etc/vi.exrc +is read, +as long as it is owned by root or the effective user ID of the user. +.np +The environmental variable +.LI NEXINIT +(or the variable +.LI EXINIT , +if +.LI NEXINIT +is not set) is interpreted. +.np +If neither +.LI NEXINIT +or +.LI EXINIT +was set, and the +.LI HOME +environmental variable is set, the file +.LI $HOME/.nexrc +(or the file +.LI $HOME/.exrc , +if +.LI $HOME/.nexrc +does not exist) is read, +as long as the effective user ID of the user is root or is the same as +the owner of the file. +.sp +When the $HOME directory is being used for both +.EV nex nvi +and an historic implementation of +.EV ex vi , +a possible solution is to put +.EV nex nvi +specific commands in the +.LI \&.nexrc +file, along with a +.CO ":source $HOME/.exrc" +command to read in the commands common to both implementations. +.np +If the +.OP exrc +option was turned on by one of the previous startup information +sources, the file +.LI \&.nexrc +(or the file +.LI \&.exrc , +if +.LI \&.nexrc +does not exist) is read, as long as the effective user ID of the user +is the same as the owner of the file. +.pp +No startup file is read if it is writable by anyone other than its owner. +.pp +It is not an error for any of the startup environmental variables or files +not to exist. +.pp +Once all environmental variables are interpreted, +and all startup files are read, +the first file to be edited is read in (or a temporary file is created). +Then, any commands specified using the +.b \-c +option are executed, in the context of that file. +.SH 1 "Recovery" +.pp +There is no recovery program for +.EV nex nvi , +nor does +.EV nex nvi +run setuid. +Recovery files are created readable and writable by the owner only. +Users may recover any file which they can read, +and the superuser may recover any edit session. +.pp +Edit sessions are backed by files in the directory named by the +.OP recdir +option (the directory +.LI /var/tmp/vi.recover +by default), and are named +.QC vi.XXXXXX , +where +.QC XXXXXX +is a number related to the process ID. +When a file is first modified, +a second recovery file containing an email message for the user is created, +and is named +.QC recover.XXXXXX , +where, again, +.QC XXXXXX +is associated with the process ID. +Both files are removed at the end of a normal edit session, +but will remain if the edit session is abnormally terminated +or the user runs the +.CO ex +.CO preserve +command. +.pp +The +.OP recdir +option may be set in either the user's or system's startup information, +changing the recovery directory. +(Note, however, that if a memory based file system is used as the backup +directory, each system reboot will delete all of the recovery files! +The same caution applies to directories such as +.LI /tmp +which are cleared of their contents by a system reboot, or +.LI /usr/tmp +which is periodically cleared of old files on many systems.) +.pp +The recovery directory should be owned by root, or at least by a pseudo-user. +In addition, if directory +.QQ sticky-bit +semantics are available, the directory should have the sticky-bit +set so that files may only be removed by their owners. +The recovery directory must be read, write, and executable by any user, +i.e. mode 1777. +.pp +If the recovery directory does not exist, +.EV ex vi +will attempt to create it. +This can result in the recovery directory being owned by a normal user, +which means that that user will be able to remove other user's recovery +and backup files. +This is annoying, but is not a security issue as the user cannot +otherwise access or modify the files. +.pp +The recovery file has all of the necessary information in it to enable the +user to recover the edit session. +In addition, it has all of the necessary email headers for +.XR sendmail 8 . +When the system is rebooted, all of the files in +.LI /var/tmp/vi.recover +named +.QC recover.XXXXXX +should be sent to their owners, by email, using the +.b \-t +option of +.CO sendmail +(or a similar mechanism in other mailers). +If +.EV ex vi +receives a hangup (SIGHUP) signal, or the user executes the +.CO ex +.CO preserve +command, +.EV ex vi +will automatically email the recovery information to the user. +.pp +If your system does not have the +.CO sendmail +utility (or a mailer program which supports its interface) +the source file +.LI nvi/common/recover.c +will have to be modified to use your local mail delivery programs. +Note, if +.EV nex nvi +is changed to use another mailer, +it is important to remember that the owner of the file given to +the mailer is the +.EV nex nvi +user, so nothing in the file should be trusted as it may have been +modified in an effort to compromise the system. +.pp +Finally, the owner execute bit is set on backup files when they are +created, and unset when they are first modified, e.g. backup files +that have no associated email recovery file will have this bit set. +(There is also a small window where empty files can be created and +not yet have this bit set. +This is due to the method in which the files are created.) +Such files should be deleted when the system reboots. +.pp +A simple way to do this cleanup is to run the Bourne shell script +.CO recover , +from your +.LI /etc/rc.local +(or other system startup) file. +The script should work with the historic Bourne shell, +a POSIX 1003.2 shell or the Korn shell. +The +.CO recover +script is installed as part of the +.EV nex nvi +installation process. +.pp +Consult the manual page for details on recovering preserved or +aborted editing sessions. +.SH 1 "Sizing the Screen" +.pp +The size of the screen can be set in a number of ways. +.EV Ex vi +takes the following steps until values are obtained for both the +number of rows and number of columns in the screen. +.np +If the environmental variable +.LI LINES +exists, +it is used to specify the number of rows in the screen. +.np +If the environmental variable +.LI COLUMNS +exists, +it is used to specify the number of columns in the screen. +.np +The TIOCGWINSZ +.XR ioctl 2 +is attempted on the standard error file descriptor. +.np +The termcap entry (or terminfo entry on System V machines) +is checked for the +.QQ li +entry (rows) and the +.QQ co +entry (columns). +.np +The number of rows is set to 24, and the number of columns is set to 80. +.pp +If a window change size signal (SIGWINCH) is received, +the new window size is retrieved using the TIOCGWINSZ +.XR ioctl 2 +call, and all other information is ignored. +.SH 1 "Character Display" +.pp +In both +.CO ex +and +.CO vi +printable characters as defined by +.XR isprint 3 +are displayed using the local character set. +.pp +Non-printable characters, for which +.XR iscntrl 3 +returns true, and which are less than octal \e040, +are displayed as the string +.QT ^<character> , +where +.LI <character> +is the character that is the original character's value offset from the +.QT @ +character. +For example, the octal character \e001 is displayed as +.QT ^A . +If +.XR iscntrl 3 +returns true for the octal character \e177, +it is displayed as the string +.QT ^? . +All other characters are displayed as either hexadecimal values, +in the form +.QT "0x<high-halfbyte> ... 0x<low-halfbyte>" , +or as octal values, in the form +.QT "\e<high-one-or-two-bits> ... \e<low-three-bits>" . +The display of unknown characters is based on the value of the +.OP octal +option. +.pp +In +.CO vi +command mode, the cursor is always positioned on the last column of +characters which take up more than one column on the screen. +In +.CO vi +text input mode, the cursor is positioned on the first column of +characters which take up more than one column on the screen. +.SH 1 "Multiple Screens" +.pp +.CO Nvi +supports multiple screens by dividing the window into regions. +It also supports stacks of screens by permitting the user to change +the set of screens that are currently displayed. +.pp +The +.CO Edit , +.CO Ex , +.CO Fg , +.CO Next , +.CO Previous , +.CO Tag +and +.CO Visual +(in +.CO vi +mode) +commands divide the current screen into two regions of approximately +equal size and then perform their usual action in a new screen area. +If the cursor is in the lower half of the screen, the screen will split +up, i.e. the new screen will be above the old one. +If the cursor is in the upper half of the screen, the new screen will be +below the old one. +.pp +When more than one screen is editing a file, changes in any screen are +reflected in all other screens editing the same file. +Exiting a screen without saving any changes (or explicitly discarding +them) is permitted until the last screen editing the file is exited, +at which time the changes must be saved or discarded. +.pp +The +.CO resize +command permits resizing of individual screens. +Screens may be grown, shrunk or set to an absolute number of rows. +.pp +The +.CO ^W +command is used to switch between screens. +Each +.CO ^W +moves to the next lower screen in the window, or to the first screen +in the window if there are no lower screens. +.pp +The +.CO bg +command +.QQ backgrounds +the current screen. +The screen disappears from the window, +and the rows it occupied are taken over by a neighboring screen. +It is an error to attempt to background the only screen in the window. +.pp +The +.CO "display screens" +command displays the names of the files associated with the current +backgrounded screens in the window. +.pp +The +.CO "fg [file]" +command moves the specified screen from the list of backgrounded screens +to the foreground. +If no file argument is specified, the first screen on the list is +foregrounded. +By default, +foregrounding consists of backgrounding the current screen, +and replacing its space in the window with the foregrounded screen. +.pp +Capitalizing the first letter of the command, i.e. +.CO Fg , +will foreground the backgrounded screen in a new screen instead of +swapping it with the current screen. +.pp +If the last foregrounded screen in the window is exited, +and there are backgrounded screens, +the first screen on the list of backgrounded screens takes over the window. +.SH 1 "Tags, Tag Stacks, and Cscope" +.pp +.CO Nvi +supports the historic +.CO vi +tag command +.CO <control-]> , +and the historic +.CO ex +tag command +.CO tag . +These commands change the current file context to a new location, +based on information found in the +.LI tags +files. +If you are unfamiliar with these commands, +you should review their description in the +.CO ex +and +.CO vi +commands section of this manual. +For additional information on tags files, +see the discussion of the +.OP tags +edit option and the system +.XR ctags 1 +manual page. +.pp +In addition, +.CO nvi +supports the notion of +.QQ "tags stacks" , +using the +.CO <control-T> +command. +The +.CO <control-T> +command returns the user to the previous context, i.e., +the last place from which a +.CO <control-]> +or +.CO "tag" +command was entered. +These three commands provide the basic functionality which allows you +to use +.CO vi +to review source code in a structured manner. +.pp +.CO Nvi +also provides two other basic +.CO ex +commands for tag support: +.CO tagpop +and +.CO tagtop . +The +.CO tagpop +command is identical to the +.CO <control-T> +command, +with the additional functionality that you may specify that modifications +to the current file are to be discarded. +This cannot be done using the +.CO <control-T> +command. +The +.CO tagtop +command discards all of the contexts that have been pushed onto the tag +stack, returning to the context from which the first +.CO <control-]> +or +.CO tag +command was entered. +.pp +The historic +.XR ctags 1 +tags file format supports only a single location per tag, +normally the function declaration or structure or string definition. +More sophisticated source code tools often provide multiple locations +per tag, e.g., +a list of the places from which a function is called or a string +definition is used. +An example of this functionality is the System V source code tool, +.CO cscope . +.sp +.CO Cscope +creates a database of information on source code files, +and supports a query language for that information as described in the +.XR cscope 1 +manual page. +.CO Nvi +contains an interface to the +.CO cscope +query language which permits you to query +.CO cscope +and then sequentially step through the locations in the sources files which +.CO cscope +returns. +There are two +.CO nvi +commands which support this ability to step through multiple locations. +They are the +.CO ex +commands +.CO tagnext +and +.CO tagprev . +The +.CO tagnext +command moves to the next location for the current tag. +The +.CO tagprev +command moves to the previous location for the current tag. +(See the +.CO tagnext +and +.CO tagprev +command discussion in the +.CO ex +commands section of this manual for more information.) +At any time during this sequential walk, +you may use the +.CO <control-]> , +.CO tag +or +.CO cscope +commands to move to a new tag context, and then use the +.CO <control-T> +or +.CO tagpop +commands to return and continue stepping through the locations for this +tag. +This is similar to the previous model of a simple tag stack, +except that each entry in the tag stack may have more than one file context +that is of interest. +.pp +Although there is no widely distributed version of +.XR ctags 1 +that creates tags files with multiple locations per tag, +.CO nvi +has been written to understand the obvious extension to the historic +tags file format, i.e., more than a single line in the tags file with +the same initial tag name. +If you wish to extend your +.CO ctags +implementation or other tool with which you build tags files, +this extension should be simple and will require no changes to +.CO nvi . +.pp +The +.CO nvi +and +.CO cscope +interface is based on the new +.CO ex +command +.CO cscope , +which has five subcommands: +.CO add , +.CO find , +.CO help , +.CO kill +and +.CO reset . +The subcommand +.CO find +itself has eight subcommands: +.CO \&c , +.CO \&d , +.CO \&e , +.CO \&f , +.CO \&g , +.CO \&i , +.CO \&s +and +.CO \&t . +.pp +.IP "cs[cope] a[dd] file" +The +.CO add +command attaches to the specified +.CO cscope +database. +The file name is expanded using the standard filename expansions. +If +.CO file +is a directory, the file +.QQ cscope.out +in that directory is used as the database. +.pp +After +.CO nvi +attaches to a new database, +all subsequent +.CO cscope +queries will be asked of that database. +The result of any single query is the collection of response to the query +from all of the attached databases. +.sp +If the +.QQ CSCOPE_DIRS +environmental variable is set when +.CO nvi +is run, +it is expected to be a <colon> or <blank>-separated list of +.CO cscope +databases or directories containing +.CO cscope +databases, to which the user wishes to attach. +.IP ":cs[cope] f[ind] c|d|e|f|g|i|s|t buffer|pattern" +The +.CO find +command is the +.CO cscope +query command for +.CO nvi . +For this command, +.CO nvi +queries all attached +.CO cscope +databases for the pattern. +If the pattern is a double-quote character followed by a valid buffer +name (e.g., +.LI """<character>" ), +then the contents of the named buffer are used as the pattern. +Otherwise, the pattern is a Regular Expression. +.sp +The +.CO find +command pushes the current location onto the tags stack, +and switches to the first location resulting from the query, +if the query returned at least one result. +.sp +File names returned by the +.CO cscope +query, if not absolute paths, are searched for relative to the directory +where the +.CO cscope +database is located. +In addition, if the file +.QQ cscope.tpath +appears in the same directory as the +.CO cscope +database, +it is expected to contain a colon-separated list of directory names +where files referenced by its associated +.CO cscope +database may be found. +.sp +The +.CO find +subcommand is one of the following: +.SS +.SP \&c +Find callers of the name. +.SP \&d +Find all function calls made from name. +.SP \&e +Find pattern. +.SP \&f +Find files with name as substring. +.SP \&g +Find definition of name. +.SP \&i +Find files #including name. +.SP \&s +Find all uses of name. +.SP \&t +Find assignments to name. +.SE +.IP ":cs[cope] h[elp] [command]" +List the +.CO cscope +commands, +or optionally list usage help for any single +.CO cscope +command. +.IP ":display c[onnections]" +Display the list of +.CO cscope +databases to which +.CO nvi +is currently connected. +.IP ":cs[cope] k[ill] #" +Disconnect from a specific +.CO cscope +database. +The connection number is the one displayed by the +.CO ex +.CO "display connections" +command. +.IP ":cs[cope] r[eset]" +Disconnect from all attached +.CO cscope +databases. +.pp +Cscope is not freely redistributable software, +but is fairly inexpensive and easily available. +To purchase a copy of +.CO cscope , +see http://www.att.com/ssg/products/toolchest.html. +.SH 1 "Regular Expressions and Replacement Strings" +.pp +Regular expressions are used in line addresses, +as the first part of the +.CO ex +.CO substitute , +.CO global , +and +.CO v +commands, and in search patterns. +.pp +The regular expressions supported by +.EV ex vi +are, by default, the Basic Regular Expressions (BRE's) described in the +IEEE POSIX Standard 1003.2. +The +.OP extended +option causes all regular expressions to be interpreted as the Extended +Regular Expressions (ERE's) described by the same standard. +(See +.XR re_format 7 +for more information.) +Generally speaking, BRE's are the Regular Expressions found in +.XR ed 1 +and +.XR grep 1 , +and ERE's are the Regular Expressions found in +.XR egrep 1 . +.pp +The following is not intended to provide a description of Regular +Expressions. +The information here only describes strings and characters which +have special meanings in the +.EV ex vi +version of RE's, +or options which change the meanings of characters that normally +have special meanings in RE's. +.np +An empty RE (e.g. +.QT // +or +.QT ?? +is equivalent to the last RE used. +.np +The construct +.QT \e< +matches the beginning of a word. +.np +The construct +.QT \e> +matches the end of a word. +.np +The character +.QT ~ +matches the replacement part of the last +.CO substitute +command. +.pp +When the +.OP magic +option is +.i not +set, the only characters with special meanings are a +.QT ^ +character at the beginning of an RE, a +.QT $ +character at the end of an RE, and the escaping character +.QT \e . +The characters +.QT \&. , +.QT * , +.QT [ +and +.QT ~ +are treated as ordinary characters unless preceded by a +.QT \e ; +when preceded by a +.QT \e +they regain their special meaning. +.pp +Replacement strings are the second part of a +.CO substitute +command. +.pp +The character +.QT & +(or +.QT \e& +if the +.OP magic +option is +.i not +set) in the replacement string stands for the text matched by the RE +that is being replaced. +The character +.QT ~ +(or +.QT \e~ +if the +.OP magic +option is +.i not +set) stands for the replacement part of the previous +.CO substitute +command. +It is only valid after a +.CO substitute +command has been performed. +.pp +The string +.QT \e# , +where +.QT # +is an integer value from 1 to 9, stands for the text matched by +the portion of the RE enclosed in the +.QT # 'th +set of escaped parentheses, e.g. +.QT \e( +and +.QT \e) . +For example, +.QT "s/abc\e(.*\e)def/\e1/" +deletes the strings +.QT abc +and +.QT def +from the matched pattern. +.pp +The strings +.QT \el , +.QT \eu , +.QT \eL +and +.QT \eU +can be used to modify the case of elements in the replacement string. +The string +.QT \el +causes the next character to be converted to lowercase; +the string +.QT \eu +behaves similarly, but converts to uppercase +(e.g. +.LI s/abc/\eU&/ +replaces the string +.LI abc +with +.LI ABC ). +The string +.QT \eL +causes characters up to the end of the string or the next occurrence +of the strings +.QT \ee +or +.QT \eE +to be converted to lowercase; +the string +.QT \eU +behaves similarly, but converts to uppercase. +.pp +If the entire replacement pattern is +.QT % , +then the last replacement pattern is used again. +.pp +In +.CO vi , +inserting a +.LI <control-M> +into the replacement string will cause +the matched line to be split into two lines at that point. +(The +.LI <control-M> +will be discarded.) +.SH 1 "Scripting Languages" +.pp +The +.CO nvi +editor currently supports two scripting languages, Tcl/Tk and Perl. +(Note that Perl4 isn't sufficient, and that the Perl5 used must be +version 5.002 or later. +See the +.QB "Building Nvi" +section for more information. +.pp +The scripting language interface is still being worked on, +therefore the following information is probably incomplete, +probably wrong in cases, and likely to change. +See the +.LI perl_api +and +.LI tcl_api +source directories for more information. +As a quick reference, the following function calls are provided for +both the Perl and Tcl interfaces. +The Perl interface uses a slightly different naming convention, +e.g. ``viFindScreen'' is named ``VI::FindScreen''. +.IP "viFindScreen file" +Return the +.LI "screenId" associated with +.LI file . +.IP "viAppendLine screenId lineNumber text" +Append +.LI text +as a new line after line number +.LI lineNumber , +in the screen +.LI screenId . +.IP "viDelLine screenId lineNum" +Delete the line +.LI lineNumber +from the screen +.LI screenId . +.IP "viGetLine screenId lineNumber" +Return the line +.LI lineNumber +from the screen +.LI screenId . +.IP "viInsertLine screenId lineNumber text" +Insert +.LI text +as a new line before line number +.LI lineNumber +in the screen +.LI screenId . +.IP "viLastLine screenId" +Return the line number of the last line in the screen +.LI screenId . +.IP "viSetLine screenId lineNumber text" +Change the line +.LI lineNumber +in the screen +.LI screenId +to match the specified +.LI text . +.IP "viGetMark screenId mark" +Return the current line and column for the specified +.LI mark +from the screen +.LI screenId . +.IP "viSetMark screenId mark line column" +Set the specified +.LI mark +to be at line +.LI line , +column +.LI column , +in the screen +.LI screenId . +.IP "viGetCursor screenId" +Return the current line and column for the cursor in the screen +.LI screenId . +.IP "viSetCursor screenId line column" +Set the cursor in the screen +.LI screenId +to the specified +.LI line +and +.LI column . +.IP "viMsg screenId text" +Display the specified +.LI text +as a vi message in the screen +.LI screenId . +.IP "viNewScreen screenId [file]" +Create a new screen. +.IP "viEndScreen screenId" +Exit the screen +.LI screenId . +.IP "viSwitchScreen screenId screenId" +Switch from the screen +.LI screenId +to the screen +.LI screenId . +.IP "viMapKey screenId key tclproc" +Map the specified +.LI key +in the screen +.LI screenId +to the Tcl procedure +.LI tclproc . +.IP "viUnmMapKey screenId key" +Unmap the specified +.LI key +in the screen +.LI screenId +.IP "viGetOpt screenId option" +Return the value of the specified +.LI option +from the screen +.LI screenId . +.IP "viSetOpt screenId command" +Set one or more options in the screen +.LI screenId . +.SH 1 "General Editor Description" +.pp +When +.CO ex +or +.CO vi +are executed, +the text of a file is read (or a temporary file is created), +and then all editing changes happen within the context of the +copy of the file. +.i "No changes affect the actual file until the file is written out" , +either using a write command or another command which is affected by the +.OP autowrite +option. +.pp +All files are locked (using the +.XR flock 2 +or +.XR fcntl 2 +interfaces) during the edit session, +to avoid inadvertently making modifications to multiple copies of the file. +If a lock cannot be obtained for a file because it is locked by another +process, the edit session is read-only (as if the +.OP readonly +option or the +.b \-R +flag had been specified). +If a lock cannot be obtained for other reasons, the edit session will +continue, but the file status information +(see the +.CO <control-G> +command) will reflect this fact. +.pp +Both +.CO ex +and +.CO vi +are modeful editors, i.e. they have two modes, +.QQ command +mode and +.QQ "text input" +mode. +The former is intended to permit you to enter commands which modifies +already existing text. +The latter is intended to permit you to enter new text. +When +.CO ex +first starts running, it is in command mode, and usually displays a prompt +(see the +.OP prompt +option for more information). +The prompt is a single colon +.PQ : +character. +There are three commands that switch +.CO ex +into text input mode: +.CO append , +.CO change +and +.CO insert . +Once in input mode, entering a line containing only a single period +.PQ \&. +ends text input mode and returns to command mode, +where the prompt is redisplayed. +.pp +When +.CO vi +first starts running, it is in command mode as well. +There are eleven commands that switch +.CO vi +into text input mode: +.CO A , +.CO a , +.CO C , +.CO c , +.CO I , +.CO i , +.CO O , +.CO o , +.CO R , +.CO S +and +.CO s . +Once in input mode, entering an +.LI <escape> +character ends text input mode and returns to command mode. +.pp +.EV Ex vi +present three different interfaces to editing a file. +.CO Ex +presents a line oriented interface. +.CO Vi +presents a full screen display oriented interface, +also known as +.QQ "visual mode" . +In addition, there is a third mode, +.QQ "open mode" , +which is line oriented, +but supports cursor movement and editing within the displayed line, +similarly to visual mode. +Open mode is not yet implemented in +.CO nvi . +.pp +The following words have special meanings in both the +.CO ex +and +.CO vi +command descriptions: +.KY <interrupt> +.IP <interrupt> +The interrupt character is used to interrupt the current operation. +Normally +.LI <control-C> , +whatever character is set for the current terminal is used. +.KY "<literal-next>" +.IP "<literal-next>" +The literal next character is used to escape the subsequent character +from any special meaning. +This character is always +.LI <control-V> . +If the terminal is not set up to do XON/XOFF flow control, +then +.LI <control-Q> +is used to mean literal next as well. +.KY "current pathname" +.IP "current pathname" +The pathname of the file currently being edited by vi. +When the percent character +.PQ % +appears in a file name entered as part of an +.CO ex +command argument, it is replaced by the current pathname. +(The +.QT % +character can be escaped by preceding it with a backslash.) +.KY "alternate pathname" +.IP "alternate pathname" +The name of the last file name mentioned in an +.CO ex +command, or, +the previous current pathname if the last file mentioned +becomes the current file. +When the hash mark character +.PQ # +appears in a file name entered as part of an +.CO ex +command argument, it is replaced by the alternate pathname. +(The +.QT # +character can be escaped by preceding it with a backslash.) +.KY buffer +.IP buffer +One of a number of named areas for saving copies of text. +Commands that change or delete text can save the changed or deleted +text into a specific buffer, for later use, if the command allows +it (i.e. the +.CO ex +.CO change +command cannot save the changed text in a named buffer). +Buffers are named with a single character, preceded by a double quote, +e.g. +.LI """<character>" +in +.CO vi +and +without the double quote, e.g. +.LI <character> , +in +.CO ex . +(The double quote isn't necessary for +.CO ex +because buffers names are denoted by their position in the command line.) +Historic implementations of +.EV ex vi +limited +.LI <character> +to the alphanumeric characters; +.EV nex nvi +permits the use of any character without another meaning in the position +where a buffer name is expected. +.sp +Buffers named by uppercase characters are the same as buffers +named by lowercase characters, e.g. the buffer named by the +English character +.QT A +is the same as the buffer named by the character +.QT a , +with the exception that, if the buffer contents are being changed (as +with a text deletion or +.CO vi +.CO change +command), the text is +.i appended +to the buffer, instead of replacing the current contents. +.sp +The buffers named by the numeric characters (in English, +.QT 1 +through +.QT 9 ), +are special. +If a region of text including characters from more than one line, +or a single line of text specified by using a line-oriented motion, +is changed or deleted in the file using the +.CO vi +.CO change +or +.CO delete +commands, a copy of the text is placed into the numeric buffer +.QT 1 , +regardless of the user specifying another buffer in which to save it. +In addition, there are a few commands which, when used as a +.LI motion +with the +.CO vi +.CO change +and +.CO delete +commands, +.i always +copy the specified region of text into the numeric buffers regardless +of the region including characters from more than one line. +These commands are: +.sp +.ne 3v +.ft C +.TS +r r r r. +<control-A> % ( ) +`<character> / ? N +n { } +.TE +.ft R +.sp +Before this copy is done, the previous contents of buffer +.QT 1 +are moved into buffer +.QT 2 , +.QT 2 +into buffer +.QT 3 , +and so on. +The contents of buffer +.QT 9 +are discarded. +In +.CO vi , +text may be explicitly stored into the numeric buffers. +In this case, the buffer rotation described above occurs before the +replacement of the buffer's contents. +The numeric buffers are only available in +.LI visual +and +.LI open +modes, +and are not accessible by +.CO ex +in any way, although changed and deleted text is still stored there +while in +.CO ex +mode. +.sp +When a +.CO vi +command synopsis shows both a +.LI [buffer] +and a +.LI [count] , +they may be presented in any order. +.sp +Finally, all buffers are either +.QQ line +or +.QQ character +oriented. +All +.CO ex +commands which store text into buffers are line oriented. +Some +.CO vi +commands which store text into buffers are line oriented, +and some are character oriented; the description for each applicable +.CO vi +command notes whether text copied into buffers using the command +is line or character oriented. +In addition, the +.CO vi +command +.CO "display buffers" +displays the current orientation for each buffer. +Generally, the only importance attached to this orientation is that +if the buffer is subsequently inserted into the text, line oriented +buffers create new lines for each of the lines they contain, and +character oriented buffers create new lines for any lines +.i other +than the first and last lines they contain. +The first and last lines are inserted into the text at the current +cursor position, becoming part of the current line. +If there is more than one line in the buffer, however, the current +line itself will be split. +.KY "unnamed buffer" +.IP "unnamed buffer" +The unnamed buffer is a text storage area which is used by commands +that use or operate on a buffer when no buffer is specified by the user. +If the command stores text into a buffer, +the text is stored into the unnamed buffer even if a buffer is also +specified by the user. +It is not possible to append text to the unnamed buffer. +If text is appended to a named buffer, +the named buffer contains both the old and new text, +while the unnamed buffer contains only the new text. +There is no way to explicitly reference the unnamed buffer. +.sp +Historically, the contents of the unnamed buffer were discarded by many +different commands, even ones that didn't store text into it. +.EV Nex nvi +never discards the contents of the unnamed buffer until new text +replaces them. +.KY whitespace +.IP whitespace +The characters <tab> and <space>. +.KY "<carriage-return>" +.IP "<carriage-return>" +The character represented by an ASCII +.LI <control-M> . +This character is almost always treated identically to a +.LI <newline> +character, but differs in that it can be escaped into the file text or +into a command. +.KY <newline> +.IP <newline> +The character represented by an ASCII +.LI <control-J> . +This character is almost always treated identically to a +.LI <control-M> +character, but differs in that it cannot be escaped into the file text or +into a command. +.oh 'Vi/Ex Reference (Vi Commands)''USD:13-%' +.eh 'USD:13-%''Vi/Ex Reference (Vi Commands)' +.so vi.cmd.roff +.oh 'Vi/Ex Reference''USD:13-%' +.eh 'USD:13-%''Vi/Ex Reference' +.SH 1 "Ex Addressing" +.pp +Addressing in +.CO ex +(and when +.CO ex +commands are executed from +.CO vi ) +relates to the current line. +In general, the current line is the last line affected by a command. +The exact effect on the current line is discussed under the description +of each command. +When the file contains no lines, the current line is zero. +.pp +Addresses are constructed by one or more of the following methods: +.np +The address +.QT \&. +refers to the current line. +.np +The address +.QT $ +refers to the last line of the file. +.np +The address +.QT N , +where +.LI N +is a positive number, refers to the N-th line of the file. +.np +The address +.QT '<character> +or +.QT `<character> +refers to the line marked with the name +.LI <character> . +(See the +.CO k +or +.CO m +commands for more information on how to mark lines.) +.np +A regular expression (RE) enclosed by slashes +.PQ / +is an address, +and it refers to the first line found by searching forward from the line +.i after +the current line toward the end of the file, and stopping at the +first line containing a string matching the RE. +(The trailing slash can be omitted at the end of the command line.) +.sp +If no RE is specified, i.e. the pattern is +.QT // , +the last RE used in any command is used in the search. +.sp +If the +.OP extended +option is set, the RE is handled as an extended RE, not a basic RE. +If the +.OP wrapscan +option is set, the search wraps around to the beginning of the file +and continues up to and including the current line, so that the entire +file is searched. +.sp +The form +.QT \e/ +is accepted for historic reasons, +and is identical to +.QT // . +.np +An RE enclosed in question marks +.PQ ? +addresses the first line found by searching backward from the line +.i preceding +the current line, toward the beginning of the file and stopping at the +first line containing a string matching the RE. +(The trailing question mark can be omitted at the end of a command line.) +.sp +If no RE is specified, i.e. the pattern is +.QT ?? , +the last RE used in any command is used in the search. +.sp +If the +.OP extended +option is set, the RE is handled as an extended RE, not a basic RE. +If the +.OP wrapscan +option is set, the search wraps around from the beginning of the file to +the end of the file and continues up to and including the current line, +so that the entire file is searched. +.sp +The form +.QT \e? +is accepted for historic reasons, and is identical to +.QT ?? . +.np +An address followed by a plus sign +.PQ + +or a minus sign +.PQ - +followed by a number is an offset address and refers to the address +plus (or minus) the indicated number of lines. +If the address is omitted, the addition or subtraction is done with +respect to the current line. +.np +An address of +.QT + +or +.QT \- +followed by a number is an offset from the current line. +For example, +.QT \-5 +is the same as +.QT \&.\-5 . +.np +An address ending with +.QT + +or +.QT - +has 1 added to or subtracted from the address, respectively. +As a consequence of this rule and of the previous rule, the address +.QT \- +refers to the line preceding the current line. +Moreover, trailing +.QT + +and +.QT \- +characters have a cumulative effect. +For example, +.QT ++\-++ +refers to the current line plus 3. +.np +A percent sign +.PQ % +is equivalent to the address range +.QT 1,$ . +.pp +.CO Ex +commands require zero, one, or two addresses. +It is an error to specify an address to a command which requires zero +addresses. +.pp +If the user provides more than the expected number of addresses to any +.CO ex +command, the first addresses specified are discarded. +For example, +.QT 1,2,3,5 print +prints lines 3 through 5, because the +.CO print +command only takes two addresses. +.pp +The addresses in a range are separated from each other by a comma +.PQ , +or a semicolon +.PQ ; . +In the latter case, the current line +.PQ \&. +is set to the first address, and only then is the second address calculated. +This feature can be used to determine the starting line for forward and +backward searches (see rules (5) and (6) above). +The second address of any two-address sequence corresponds to a line that +follows, in the file, the line corresponding to the first address. +The first address must be less than or equal to the second address. +The first address must be greater than or equal to the first line of the +file, and the last address must be less than or equal to the last line +of the file. +.oh 'Vi/Ex Reference (Ex Commands)''USD:13-%' +.eh 'USD:13-%''Vi/Ex Reference (Ex Commands)' +.so ex.cmd.roff +.oh 'Vi/Ex Reference (Options)''USD:13-%' +.eh 'USD:13-%''Vi/Ex Reference (Options)' +.so set.opt.roff +.oh 'Vi/Ex Reference''USD:13-%' +.eh 'USD:13-%''Vi/Ex Reference' +.bp +.SH 1 Index +.lp +.2c +0.5i 3 +.ta \n($luR +.nf +.so index.so +.fi +.\" Force the TOC to an odd page, in case it's a duplex printer. +.if o .bp +.bp 3 +.1c +.ce 1 +\fB\s+2Table of Contents\s0\fP +.sp +.xp diff --git a/contrib/nvi/docs/USD.doc/vitut/Makefile b/contrib/nvi/docs/USD.doc/vitut/Makefile new file mode 100644 index 000000000000..3d4aca0a64e6 --- /dev/null +++ b/contrib/nvi/docs/USD.doc/vitut/Makefile @@ -0,0 +1,22 @@ +# @(#)Makefile 8.7 (Berkeley) 8/18/96 + +MACROS= -ms +ROFF= groff +TBL= tbl + +all: vitut.ps summary.ps viapwh.ps + +vitut.ps: vi.in vi.chars + ${TBL} vi.in vi.chars | ${ROFF} ${MACROS} > $@ + chmod 444 $@ + +summary.ps: vi.summary + ${TBL} vi.summary | ${ROFF} ${MACROS} > $@ + chmod 444 $@ + +viapwh.ps: vi.apwh.ms + ${TBL} vi.apwh.ms | ${ROFF} ${MACROS} > $@ + chmod 444 $@ + +clean: + rm -f vitut.ps summary.ps viapwh.ps diff --git a/contrib/nvi/docs/USD.doc/vitut/vi.apwh.ms b/contrib/nvi/docs/USD.doc/vitut/vi.apwh.ms new file mode 100644 index 000000000000..6b0763055ca9 --- /dev/null +++ b/contrib/nvi/docs/USD.doc/vitut/vi.apwh.ms @@ -0,0 +1,1081 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)vi.apwh.ms 8.2 (Berkeley) 8/18/96 +.\" +.nr LL 6.5i +.nr FL 6.5i +.TL +Vi Command & Function Reference +.AU CB 2675 +Alan P.W. Hewett +.sp +Revised for version 2.12 by Mark Horton +.CB +.NH 1 +Author's Disclaimer +.LP +This document does not claim to be 100% complete. There are a +few commands listed in the original document that I was unable +to test either because I do not speak \fBlisp\fR, because they +required programs we don't have, or because I wasn't able to make +them work. In these cases I left the command out. The commands +listed in this document have been tried and are known to work. +It is expected that prospective users of this document will read +it once to get the flavor of everything that \fBvi\fR can do +and then use it as a reference document. Experimentation is +recommended. If you don't understand a command, try it and +see what happens. +.LP +[Note: In revising this document, I have attempted to make it +completely reflect version 2.12 of +.B vi . +It does not attempt to document the VAX version (version 3), +but with one or two exceptions (wrapmargin, arrow keys) +everything said about 2.12 should apply to 3.1. +.I "Mark Horton" ] +.NH 1 +Notation +.LP +\fB[option]\fR is used to denote optional parts of a command. +Many \fBvi\fR commands have an optional count. \fB[cnt]\fR +means that an optional number may precede the command to +multiply or iterate the command. +\fB{variable item}\fR is used to denote parts of the command +which must appear, but can take a number of different values. +\fB<character [-character]>\fR means that the character or +one of the characters in the range described between the +two angle brackets is to be typed. +For example \fB<esc>\fR means +the \fBescape\fR key is to be typed. \fB<a-z>\fR means that a +lower case letter is to be typed. \fB^<character>\fR means that +the character is to be typed as a \fBcontrol\fR character, that is, +with the \fB<cntl>\fR key held down while simultaneously typing +the specified character. In this document control characters will +be denoted using the \fIupper case\fR character, but +^<uppercase chr> and ^<lowercase chr> are equivalent. That is, for +example, \fB<^D>\fR is equal to \fB<^d>\fR. +The most common character abbreviations +used in this list are as follows: +.VL 8 +.IP <esc> 8 +escape, octal 033 +.IP <cr> 8 +carriage return, ^M, octal 015 +.IP <lf> 8 +linefeed ^J, octal 012 +.IP <nl> 8 +newline, ^J, octal 012 (same as linefeed) +.IP <bs> 8 +backspace, ^H, octal 010 +.IP <tab> 8 +tab, ^I, octal 011 +.IP <bell> 8 +bell, ^G, octal 07 +.IP <ff> 8 +formfeed, ^L, octal 014 +.IP <sp> 8 +space, octal 040 +.IP <del> 8 +delete, octal 0177 +.LE +.sp 1 +.NH 1 +Basics +.LP +To run \fBvi\fR the shell variable \fBTERM\fR must be defined and +exported to your environment. +How you do this depends on which shell you are using. +You can tell which shell you have by the character it +prompts you for commands with. +The Bourne shell prompts with `$', and the C shell prompts with `%'. +For these examples, we will suppose +that you are using an HP 2621 terminal, whose termcap name is ``2621''. +.NH 2 +Bourne Shell +.LP +To manually set your terminal type to 2621 you would type: +.DS +TERM=2621 +export TERM +.DE +.PP +There are various ways of having this automatically or +semi-automatically done when you log in. +Suppose you usually dial in on a 2621. +You want to tell this to the machine, but still have it +work when you use a hardwired terminal. +The recommended way, if you have the +.B tset +program, is to use the sequence +.DS +tset \-s \-d 2621 > tset$$ +\&. tset$$ +rm tset$$ +.DE +in your .login (for csh) or the same thing using `.' instead of `source' +in your .profile (for sh). +The above line says that if you are dialing in you are on a 2621, +but if you are on a hardwired terminal it figures out your terminal +type from an on-line list. +.NH 2 +The C Shell +.LP +To manually set your terminal type to 2621 you would type: +.DS +setenv TERM 2621 +.DE +.PP +There are various ways of having this automatically or +semi-automatically done when you log in. +Suppose you usually dial in on a 2621. +You want to tell this to the machine, but still have it +work when you use a hardwired terminal. +The recommended way, if you have the +.B tset +program, is to use the sequence +.DS +tset \-s \-d 2621 > tset$$ +source tset$$ +rm tset$$ +.DE +in your .login.* +.FS +* On a version 6 system +without environments, the invocation of tset +is simpler, just add the line ``tset \-d 2621'' +to your .login or .profile. +.FE +The above line says that if you are dialing in you are on a 2621, +but if you are on a hardwired terminal it figures out your terminal +type from an on-line list. +.NH 1 +Normal Commands +.LP +\fBVi\fR is a visual editor with a window on the file. What +you see on the screen is \fBvi\fR's current notion of +what your file will contain, +(at this point in the file), +when it is written out. +Most commands do not cause any change in the screen until the +complete command is typed. Should you get confused while +typing a command, you can abort the command by typing an +<del> character. You will know you are back to command level +when you hear a <bell>. Usually typing an <esc> will produce the +same result. When \fBvi\fR gets an improperly formatted command +it rings the <bell>. +Following are the \fBvi\fR commands broken down by function. +.NH 2 +Entry and Exit +.LP +To enter +.B vi +on a particular +.I file , +type +.DS +\fBvi\fP \fIfile\fP +.DE +The file will be read in and the cursor will be placed at the beginning +of the first line. +The first screenfull of the file will be displayed on the terminal. +.PP +To get out of the editor, type +.DS +ZZ +.DE +If you are in some special mode, such as input mode +or the middle of a multi-keystroke command, it may +be necessary to type <esc> first. +.NH 2 +Cursor and Page Motion +.LP +.VL 16 +.B NOTE: +The arrow keys (see the next four commands) +on certain kinds of terminals will not work with the +PDP-11 version of vi. The control versions or the hjkl versions will +work on any terminal. Experienced users prefer the hjkl keys because +they are always right under their fingers. Beginners often prefer +the arrow keys, since they do not require memorization of which hjkl +key is which. +The mnemonic value of hjkl is clear from looking at the keyboard of an adm3a. +.sp +.IP "[cnt]<bs> or [cnt]h or [cnt]\(<-" 16 +.br +Move the cursor to the left one character. Cursor stops at the left +margin of the page. +If cnt is given, these commands move that many spaces. +.IP "[cnt]^N or [cnt]j or [cnt]\(da or [cnt]<lf>" 16 +.br +Move down one line. +Moving off the screen scrolls the window to force a new line +onto the screen. +Mnemonic: \fBN\fRext +.IP "[cnt]^P or [cnt]k or [cnt]\(ua" 16 +.br +Move up one line. +Moving off the top of the screen forces new text onto the screen. +Mnemonic: \fBP\fRrevious +.IP "[cnt]<sp> or [cnt]l or [cnt]\(->" 16 +.br +Move to the right one character. +Cursor will not go beyond the end of the line. +.IP [cnt]- 16 +Move the cursor up the screen to the beginning of the next line. +Scroll if necessary. +.IP "[cnt]+ or [cnt]<cr>" 16 +.sp 1 +Move the cursor down the screen to the beginning of the next line. +Scroll up if necessary. +.IP "[cnt]$" 16 +Move the cursor to the end of the line. +If there is a count, move to the end of the line "cnt" lines +forward in the file. +.IP "^" 16 +Move the cursor to the beginning of the first word on the line. +.IP "0" 16 +Move the cursor to the left margin of the current line. +.IP "[cnt]|" 16 +Move the cursor to the column specified by the count. The default is +column zero. +.IP "[cnt]w" 16 +Move the cursor to the beginning of the next word. If there +is a count, then move forward that many words and +position the cursor at the beginning of the word. +Mnemonic: next-\fBw\fRord +.IP "[cnt]W" 16 +Move the cursor to the beginning of the next word which follows +a "white space" (<sp>,<tab>, or <nl>). Ignore other punctuation. +.IP "[cnt]b" 16 +Move the cursor to the preceding word. Mnemonic: \fBb\fRackup-word +.IP "[cnt]B" 16 +Move the cursor to the preceding word that is separated from the +current word by a "white space" (<sp>,<tab>, or <nl>). +.IP "[cnt]e" 16 +Move the cursor to the end of the current word or the end of the +"cnt"'th word hence. Mnemonic: \fBe\fRnd-of-word +.IP "[cnt]E" 16 +Move the cursor to the end of the current word which is delimited by +"white space" (<sp>,<tab>, or <nl>). +.IP "[line number]G" 16 +.br +Move the cursor to the line specified. Of particular use are the +sequences "1G" and "G", which move the cursor to the beginning and +the end of the file respectively. Mnemonic: \fBG\fRo-to +.LP +.B NOTE: +The next four commands (^D, ^U, ^F, ^B) +are not true motion commands, in that they +cannot be used as the object of commands such as delete or change. +.IP "[cnt]^D" 16 +Move the cursor down in the file by "cnt" lines (or the last "cnt" +if a new count isn't given. The initial default is half a page.) The +screen is simultaneously scrolled up. Mnemonic: \fBD\fRown +.IP "[cnt]^U" 16 +Move the cursor up in the file by "cnt" lines. The screen is simultaneously +scrolled down. Mnemonic: \fBU\fRp +.IP "[cnt]^F" 16 +Move the cursor to the next page. A count moves that many pages. +Two lines of the previous page are kept on the screen for continuity if +possible. Mnemonic: \fBF\fRorward-a-page +.IP "[cnt]^B" 16 +Move the cursor to the previous page. Two lines of the current page +are kept if possible. Mnemonic: \fBB\fRackup-a-page +.IP "[cnt](" 16 +Move the cursor to the beginning of the next sentence. +A sentence is defined as ending with a ".", "!", or "?" +followed by two spaces or a <nl>. +.IP "[cnt])" 16 +Move the cursor backwards to the beginning of a sentence. +.IP "[cnt]}" 16 +Move the cursor to the beginning of the next paragraph. This command +works best inside \fBnroff\fR documents. It understands two sets of +\fBnroff\fR macros, \fB\-ms\fR and \fB\-mm\fR, for which the +commands ".IP", ".LP", ".PP", ".QP", "P", as well as the nroff command ".bp" +are considered to be paragraph delimiters. +A blank line also delimits a paragraph. +The \fBnroff\fR macros that it accepts as paragraph delimiters is +adjustable. See \fBparagraphs\fR under the \fBSet Commands\fR section. +.IP "[cnt]{" 16 +Move the cursor backwards to the beginning of a paragraph. +.IP "]]" 16 +Move the cursor to the next "section", where a section is defined by +two sets of \fBnroff\fR macros, \fB\-ms\fR and \fB\-mm\fR, in which +".NH", ".SH", and ".H" delimit a section. A line beginning with a <ff><nl> +sequence, or a line beginning with a "{" are also considered to +be section delimiters. The last option makes it +useful for finding the beginnings of C functions. +The \fBnroff\fR macros that are used for section delimiters can be adjusted. +See \fBsections\fR under the \fBSet Commands\fR section. +.IP "[[" 16 +Move the cursor backwards to the beginning of a section. +.IP "%" 16 +Move the cursor to the matching parenthesis +or brace. This is very useful in C or lisp code. If the +cursor is sitting on a \fB( ) {\fR or \fB}\fR the cursor +is moved to the matching character at the other end of the +section. If the cursor is not sitting on a brace or a +parenthesis, \fBvi\fR searches forward until it finds one +and then jumps to the match mate. +.IP "[cnt]H" 16 +If there is no count move the cursor to the top left position on the screen. +If there is a count, then move the cursor to the beginning of the line +"cnt" lines from the top of the screen. Mnemonic: \fBH\fRome +.IP "[cnt]L" 16 +If there is no count move the cursor to the beginning +of the last line on the screen. +If there is a count, then move the cursor to the beginning of the line +"cnt" lines from the bottom of the screen. Mnemonic: \fBL\fRast +.IP "M" 16 +Move the cursor to the beginning of the middle line on the screen. +Mnemonic: \fBM\fRiddle +.IP "m<a-z>" 16 +This command does not move the cursor, but it \fBmarks\fR the place +in the file and the character "<a-z>" becomes the label for referring +to this location in the file. See the next two commands. Mnemonic: +\fBm\fRark +.B NOTE: +The mark command is not a motion, and cannot be used as the target +of commands such as delete. +.IP "\(aa<a-z>" 16 +Move the cursor to the beginning of the line that is marked with the label +"<a-z>". +.IP "\(ga<a-z>" 16 +Move the cursor to the exact position on the line that was marked with +with the label "<a-z>". +.IP "\(aa\(aa" 16 +Move the cursor back to the beginning of the line where it was before the +last "non-relative" move. A "non-relative" move is something such as a +search or a jump to a specific line in the file, rather than moving the +cursor or scrolling the screen. +.IP "\(ga\(ga" 16 +Move the cursor back to the exact spot on the line where it was located +before the last "non-relative" move. +.LE +.NH 2 +Searches +.LP +The following commands allow you to search for items in a file. +.VL 16 +.IP [cnt]f{chr} 16 +.sp 1 +Search forward on the line for the next or "cnt"'th occurrence of +the character "chr". The cursor is placed \fBat\fR the character +of interest. Mnemonic: \fBf\fRind character +.IP [cnt]F{chr} 16 +.sp 1 +Search backwards on the line for the next or "cnt"'th occurrence of +the character "chr". The cursor is placed \fBat\fR the character +of interest. +.IP [cnt]t{chr} 16 +.sp 1 +Search forward on the line for the next or "cnt"'th occurrence of +the character "chr". The cursor is placed \fBjust preceding\fR +the character of interest. Mnemonic: move cursor up \fBt\fRo character +.IP [cnt]T{chr} 16 +.sp 1 +Search backwards on the line for the next or "cnt"'th occurrence of +the character "chr". The cursor is placed \fBjust preceding\fR +the character of interest. +.IP "[cnt];" 16 +Repeat the last "f", "F", "t" or "T" command. +.IP "[cnt]," 16 +Repeat the last "f", "F", "t" or "T" command, but in the opposite +search direction. This is useful if you overshoot. +.IP "[cnt]/[string]/<nl>" 16 +.br +Search forward for the next occurrence of "string". +Wrap around at the end of the file +does occur. +The final \fB</>\fR is not required. +.IP "[cnt]?[string]?<nl>" 16 +.br +Search backwards for the next occurrence of "string". If a count is +specified, the count becomes the new window size. Wrap around at the beginning +of the file does occur. +The final \fB<?>\fR is not required. +.IP n 16 +Repeat the last /[string]/ or ?[string]? search. Mnemonic: \fBn\fRext +occurrence. +.IP N 16 +Repeat the last /[string]/ or ?[string]? search, but in the reverse +direction. +.IP ":g/[string]/[editor command]<nl>" 16 +.sp 1 +Using the \fB:\fR syntax it is possible to do global searches ala the +standard UNIX "ed" editor. +.LE +.NH 2 +Text Insertion +.LP +The following commands allow for the insertion of text. All multicharacter +text insertions are terminated with an <esc> character. +The last change +can always be \fBundone\fR by typing a \fBu\fR. +The text insert in insertion mode can contain newlines. +.VL 16 +.IP a{text}<esc> 16 +Insert text immediately following the cursor position. +Mnemonic: \fBa\fRppend +.IP A{text}<esc> 16 +Insert text at the end of the current line. +Mnemonic: \fBA\fRppend +.IP i{text}<esc> 16 +Insert text immediately preceding the cursor position. +Mnemonic: \fBi\fRnsert +.IP I{text}<esc> 16 +Insert text at the beginning of the current line. +.IP o{text}<esc> 16 +Insert a new line after the line on which the cursor appears and +insert text there. Mnemonic: \fBo\fRpen new line +.IP O{text}<esc> 16 +Insert a new line preceding the line on which the cursor appears +and insert text there. +.LE +.NH 2 +Text Deletion +.LP +The following commands allow the user to delete text in various ways. +All changes can always be \fBundone\fR by typing the \fBu\fR command. +.VL 16 +.IP "[cnt]x" 16 +Delete the character or characters starting at the cursor position. +.IP "[cnt]X" 16 +Delete the character or characters starting at the character preceding +the cursor position. +.IP "D" 16 +Deletes the remainder of the line starting at the cursor. +Mnemonic: \fBD\fRelete the rest of line +.IP "[cnt]d{motion}" 16 +.br +Deletes one or more occurrences of the specified motion. +Any motion from sections 4.1 and 4.2 can be used here. +The d can be stuttered (e.g. [cnt]dd) to delete cnt lines. +.LE +.NH 2 +Text Replacement +.LP +The following commands allow the user to simultaneously delete and +insert new text. All such actions can be \fBundone\fR by typing +\fBu\fR following the command. +.VL 16 +.IP "r<chr>" 16 +Replaces the character at the current cursor position with <chr>. This +is a one character replacement. No <esc> is required for termination. +Mnemonic: \fBr\fReplace character +.IP "R{text}<esc>" 16 +Starts overlaying the characters on the screen with whatever you type. +It does not stop until an <esc> is typed. +.IP "[cnt]s{text}<esc>" 16 +Substitute for "cnt" characters beginning at the current cursor +position. A "$" will appear at the position in the text where the +"cnt"'th character appears so you will know how much you are erasing. +Mnemonic: \fBs\fRubstitute +.IP "[cnt]S{text}<esc>" 16 +Substitute for the entire current line (or lines). If no count is given, +a "$" appears at the end of the current line. If a count of more than +1 is given, all the lines to be replaced are deleted before the insertion +begins. +.IP "[cnt]c{motion}{text}<esc>" 16 +.br +Change the specified "motion" by replacing it with the +insertion text. A "$" will appear at the end of the last item +that is being deleted unless the deletion involves whole lines. +Motion's can be any motion from sections 4.1 or 4.2. +Stuttering the c (e.g. [cnt]cc) changes cnt lines. +.LE +.NH 2 +Moving Text +.LP +\fBVi\fR provides a number of ways of moving chunks of text around. +There are nine buffers into which each piece of text which is deleted +or "yanked" is put in addition to the "undo" buffer. +The most recent deletion or yank is in the "undo" buffer and also +usually in buffer +1, the next most recent in buffer 2, and so forth. Each new deletion +pushes down all the older deletions. Deletions older than 9 +disappear. There is also +a set of named registers, a-z, into which text can optionally +be placed. If any delete or replacement type command is preceded +by \fB"<a-z>\fR, that named buffer will contain the text deleted +after the command is executed. For example, \fB"a3dd\fR will delete +three lines starting at the current line and put them in buffer \fB"a\fR.* +.FS +* Referring to an upper case letter as a buffer name (A-Z) is the +same as referring to the lower case letter, except that text placed +in such a buffer is appended to it instead of replacing it. +.FE +There are two more basic commands and +some variations useful in getting and putting text into a file. +.VL 16 +.IP ["<a-z>][cnt]y{motion} 16 +.sp 1 +Yank the specified item or "cnt" items and put in the "undo" buffer or +the specified buffer. The variety of "items" that can be yanked +is the same as those that can be deleted with the "d" command or +changed with the "c" command. In the same way that "dd" means +delete the current line and "cc" means replace the current line, +"yy" means yank the current line. +.IP ["<a-z>][cnt]Y 16 +Yank the current line or the "cnt" lines starting from the current +line. If no buffer is specified, they will go into the "undo" buffer, +like any delete would. It is equivalent to "yy". +Mnemonic: \fBY\fRank +.IP ["<a-z>]p 16 +Put "undo" buffer or the specified buffer down \fBafter\fR the cursor. +If whole lines were yanked or deleted into the buffer, then they will be +put down on the line following the line the cursor is on. If +something else was deleted, like a word or sentence, then it will +be inserted immediately following the cursor. +Mnemonic: \fBp\fRut buffer +.IP +It should be noted that text in the named buffers remains there when you +start editing a new file with the \fB:e file<esc>\fR command. Since +this is so, it is possible to copy or delete text from one file and +carry it over to another file in the buffers. +However, the undo buffer and the ability to undo are lost when +changing files. +.IP ["<a-z>]P 16 +Put "undo" buffer or the specified buffer down \fBbefore\fR the cursor. +If whole lines where yanked or deleted into the buffer, then they will be +put down on the line preceding the line the cursor is on. If +something else was deleted, like a word or sentence, then it will +be inserted immediately preceding the cursor. +.IP [cnt]>{motion} 16 +The shift operator will right shift all the text from the line on which +the cursor is located to the line where the \fBmotion\fR is located. +The text is shifted by one \fBshiftwidth\fR. (See section 6.) +\fB>>\fR means right shift the current line or lines. +.IP [cnt]<{motion} 16 +The shift operator will left shift all the text from the line on which +the cursor is located to the line where the \fBitem\fR is located. +The text is shifted by one \fBshiftwidth\fR. (See section 6.) +\fB<<\fR means left shift the current line or lines. +Once the line has reached the left margin it is not further affected. +.IP [cnt]={motion} 16 +Prettyprints the indicated area according to +.B lisp +conventions. +The area should be a lisp s-expression. +.LE +.NH 2 +Miscellaneous Commands +.LP +\fBVi\fR has a number of miscellaneous commands that are very +useful. They are: +.VL 16 +.IP ZZ 16 +This is the normal way to exit from vi. +If any changes have been made, the file is written out. +Then you are returned to the shell. +.IP ^L 16 +Redraw the current screen. This is useful if someone "write"s you +while you are in "vi" or if for any reason garbage gets onto the +screen. +.IP ^R 16 +On dumb terminals, those not having the "delete line" function +(the vt100 is such a terminal), \fBvi\fR saves redrawing the +screen when you delete a line by just marking the line with an +"@" at the beginning and blanking the line. If you want to +actually get rid of the lines marked with "@" and see what the +page looks like, typing a ^R will do this. +.IP \s+4.\s0 16 +"Dot" is a particularly useful command. It repeats the last +text modifying command. Therefore you can type a command once and +then to another place and repeat it by just typing ".". +.IP u 16 +Perhaps the most important command in the editor, +u undoes the last command that changed the buffer. +Mnemonic: \fBu\fRndo +.IP U 16 +Undo all the text modifying commands performed on the current line +since the last time you moved onto it. +.IP [cnt]J 16 +Join the current line and the following line. The <nl> is deleted +and the two lines joined, usually with a space between the +end of the first line and the beginning of what was the second +line. If the first line ended with a "period", then two spaces +are inserted. +A count joins the next cnt lines. +Mnemonic: \fBJ\fRoin lines +.IP Q 16 +Switch to \fBex\fR editing mode. +In this mode \fBvi\fR will behave very much like \fBed\fR. +The editor in this mode will operate on single lines normally and +will not attempt to keep the "window" up to date. +Once in this mode it is also possible to switch to the \fBopen\fR +mode of editing. By entering the command \fB[line number]open<nl>\fR +you enter this mode. It is similar to the normal visual mode +except the window is only \fBone\fR line long. +Mnemonic: \fBQ\fRuit visual mode +.IP ^] 16 +An abbreviation for a tag command. +The cursor should be positioned at the beginning of a word. +That word is taken as a tag name, and the tag with that +name is found as if it had been typed in a :tag command. +.IP [cnt]!{motion}{UNIX\ cmd}<nl> 16 +.br +Any UNIX filter +(e.g. command that reads the standard input and outputs something +to the standard output) can be sent a section of the current file and +have the output of the command replace the original text. Useful +examples are programs like \fBcb\fR, \fBsort\fR, and +\fBnroff\fR. For instance, using \fBsort\fR it would be possible to +sort a section of the current file into a new list. +Using \fB!!\fR means take a line or lines starting at the line the +cursor is currently on and pass them to the UNIX command. +.B NOTE: +To just escape to the shell for one command, +use :!{cmd}<nl>, see section 5. +.IP z{cnt}<nl> 16 +This resets the current window size to "cnt" lines and redraws the screen. +.LE +.NH 2 +Special Insert Characters +.LP +There are some characters that have special meanings during +insert modes. They are: +.VL 16 +.IP ^V 16 +During inserts, typing a ^V allows you to quote control characters +into the file. Any character typed after the ^V will be inserted +into the file. +.IP [^]^D\ or\ [0]^D 16 +<^D> without any argument backs up one \fBshiftwidth\fR. This is necessary +to remove indentation that was inserted by the \fBautoindent\fR feature. +^<^D> temporarily removes all the autoindentation, thus placing the cursor +at the left margin. On the next line, the previous indent level will be +restored. This is useful for putting "labels" at the left margin. +0<^D> says remove all autoindents and stay that way. Thus the cursor +moves to the left margin and stays there on successive lines until +<tab>'s are typed. As with the <tab>, the <^D> is only effective before +any other "non-autoindent" controlling characters are typed. +Mnemonic: \fBD\fRelete a shiftwidth +.IP ^W 16 +If the cursor is sitting on a word, <^W> moves the cursor back to the beginning +of the word, thus erasing the word from the insert. +Mnemonic: erase \fBW\fRord +.IP <bs> 16 +The backspace always serves as an erase during insert modes in addition +to your normal "erase" character. To insert a <bs> into your file, use +the <^V> to quote it. +.LE +.NH 1 +\fB:\fR Commands +.LP +Typing a ":" during command mode causes \fBvi\fR to put the cursor at +the bottom on the screen in preparation for a command. In the +":" mode, \fBvi\fR can be given most \fBed\fR commands. It is +also from this mode that you exit from \fBvi\fR or switch to different +files. All commands of this variety are terminated by a <nl>, <cr>, +or <esc>. +.VL 16 +.IP ":w[!] [file]" 16 +Causes \fBvi\fR to write out the current text to the disk. It is +written to the file you are editing unless "file" is supplied. If +"file" is supplied, the write is directed to that file instead. If +that file already exists, \fBvi\fR will not perform the write unless +the "!" is supplied indicating you +.I really +want to destroy the older copy of the file. +.IP :q[!] 16 +Causes \fBvi\fR to exit. If you have modified the file you are +looking at currently and haven't written it out, \fBvi\fR will +refuse to exit unless the "!" is supplied. +.IP ":e[!] [+[cmd]] [file]" 16 +.sp 1 +Start editing a new file called "file" or start editing the current +file over again. The command ":e!" says "ignore the changes I've made +to this file and start over from the beginning". It is useful if +you really mess up the file. The optional "+" says instead of starting +at the beginning, start at the "end", or, +if "cmd" is supplied, execute "cmd" first. +Useful cases of this are where cmd is "n" (any integer) which starts +at line number n, +and "/text", which searches for "text" and starts at the line where +it is found. +.IP "^^" 16 +Switch back to the place you were before your last tag command. +If your last tag command stayed within the file, ^^ returns to that tag. +If you have no recent tag command, it will return to the +same place in the previous file that it was showing when you switched +to the current file. +.IP ":n[!]" 16 +Start editing the next file in the argument list. Since \fBvi\fR +can be called with multiple file names, the ":n" command tells it to +stop work on the current file and switch to the next file. If the +current file was modifies, it has to be written out before the ":n" +will work or else the "!" must be supplied, which says discard the +changes I made to the current file. +.IP ":n[!] file [file file ...]" 16 +.sp +Replace the current argument list with a new list of files and start +editing the first file in this new list. +.IP ":r file" 16 +Read in a copy of "file" on the line after the cursor. +.IP ":r !cmd" 16 +Execute the "cmd" and take its output and put it into the file after +the current line. +.IP ":!cmd" 16 +Execute any UNIX shell command. +.IP ":ta[!] tag" 16 +.B Vi +looks in the file named +.B tags +in the current directory. +.B Tags +is a file of lines in the format: +.sp 1 +.ti +8 +tag filename \fBvi\fR-search-command +.sp 1 +If \fBvi\fR finds the tag you specified in the \fB:ta\fR command, +it stops editing the current file if necessary and if the current file is +up to date on the disk and switches to the file specified and uses the +search pattern specified to find the "tagged" item of interest. This +is particularly useful when editing multi-file C programs such as the +operating system. There is a program called \fBctags\fR which will +generate an appropriate \fBtags\fR file for C and f77 +programs so that by saying +\fB:ta function<nl>\fR you will be switched to that function. +It could also be useful when editing multi-file documents, though the +\fBtags\fR file would have to be generated manually. +.LE +.NH 1 +Special Arrangements for Startup +.PP +\fBVi\fR takes the value of \fB$TERM\fR and looks up the characteristics +of that terminal in the file \fB/etc/termcap\fR. +If you don't know \fBvi\fR's name for the terminal you are working +on, look in \fB/etc/termcap\fR. +.PP +When \fBvi\fR starts, it attempts to read the variable EXINIT +from your environment.* +If that exists, it takes the values in it as the default values +for certain of its internal constants. See the section on "Set Values" +for further details. +If EXINIT doesn't exist you will get all the normal defaults. +.FS +* On version 6 systems +Instead of EXINIT, put the startup commands in the file .exrc +in your home directory. +.FE +.PP +Should you inadvertently hang up the phone while inside +.B vi , +or should the computer crash, +all may not be lost. +Upon returning to the system, type: +.DS +vi \-r file +.DE +This will normally recover the file. If there is more than one +temporary file for a specific file name, \fBvi\fR recovers the +newest one. You can get an older version by recovering the +file more than once. +The command "vi -r" without a file name gives you the list of files +that were saved in the last system crash +(but +.I not +the file just saved when the phone was hung up). +.NH 1 +Set Commands +.LP +\fBVi\fR has a number of internal variables and switches which can be +set to achieve special affects. +These options come in three forms, those that are switches, which toggle +from off to on and back, those that require a numeric value, and those +that require an alphanumeric string value. +The toggle options are set by a command of the form: +.DS +:set option<nl> +.DE +and turned off with the command: +.DS +:set nooption<nl> +.DE +Commands requiring a value are set with a command of the form: +.DS +:set option=value<nl> +.DE +To display the value of a specific option type: +.DS +:set option?<nl> +.DE +To display only those that you have changed type: +.DS +:set<nl> +.DE +and to display the long table of all the settable parameters and +their current values type: +.DS +:set all<nl> +.DE +.PP +Most of the options have a long form and an abbreviation. Both are +listed in the following table as well as the normal default value. +.PP +To arrange to have values other than the default used every time you +enter +.B vi , +place the appropriate +.B set +command in EXINIT in your environment, e.g. +.DS +EXINIT='set ai aw terse sh=/bin/csh' +export EXINIT +.DE +or +.DS +setenv EXINIT 'set ai aw terse sh=/bin/csh' +.DE +for +.B sh +and +.B csh , +respectively. +These are usually placed in your .profile or .login. +If you are running a system without environments (such as version 6) +you can place the set command in the file .exrc in your home +directory. +.VL 16 +.IP autoindent\ ai 16 +Default: noai Type: toggle +.br +When in autoindent mode, vi helps you indent code by starting each +line in the same column as the preceding line. +Tabbing to the right with <tab> or <^T> will move this boundary to +the right, and it can be moved to the left with <^D>. +.IP autoprint\ ap 16 +Default: ap Type: toggle +.br +Causes the current line to be printed after each ex text modifying command. +This is not of much interest in the normal \fBvi\fR visual mode. +.IP autowrite\ aw 16 +Default: noaw type: toggle +.br +Autowrite causes an automatic write to be done if there are unsaved +changes before certain commands which change files or otherwise +interact with the outside world. +These commands are :!, :tag, :next, :rewind, ^^, and ^]. +.IP beautify\ bf 16 +Default: nobf Type: toggle +.br +Causes all control characters except <tab>, <nl>, and <ff> to be discarded. +.IP directory\ dir 16 +Default: dir=/tmp Type: string +.br +This is the directory in which \fBvi\fR puts its temporary file. +.IP errorbells\ eb 16 +Default: noeb Type: toggle +.br +Error messages are preceded by a <bell>. +.IP hardtabs\ ht 16 +Default: hardtabs=8 Type: numeric +.br +This option contains the value of hardware tabs in your terminal, or +of software tabs expanded by the Unix system. +.IP ignorecase\ ic 16 +Default: noic Type: toggle +.br +All upper case characters are mapped to lower case in regular expression +matching. +.IP lisp 16 +Default: nolisp Type: toggle +.br +Autoindent for \fBlisp\fR code. The commands \fB( ) [[\fR and \fB]]\fR +are modified appropriately to affect s-expressions and functions. +.IP list 16 +Default: nolist Type: toggle +.br +All printed lines have the <tab> and <nl> characters displayed visually. +.IP magic 16 +Default: magic Type: toggle +.br +Enable the metacharacters for matching. These include \fB. * < > [string] +[^string]\fR and \fB[<chr>-<chr>]\fR. +.IP number\ nu 16 +Default: nonu Type: toggle +.br +Each line is displayed with its line number. +.IP open 16 +Default: open Type: toggle +.br +When set, prevents entering open or visual modes from ex or edit. +Not of interest from vi. +.IP optimize\ opt 16 +Default: opt Type: toggle +.br +Basically of use only when using the \fBex\fR capabilities. This +option prevents automatic <cr>s from taking place, +and speeds up output of indented lines, +at the expense of losing typeahead on some versions of UNIX. +.IP paragraphs\ para 16 +Default: para=IPLPPPQPP\ bp Type: string +.br +Each pair of characters in the string indicate \fBnroff\fR macros +which are to be treated as the beginning of a paragraph for the +\fB{\fR and \fB}\fR commands. The default string is for the \fB-ms\fR +and \fB-mm\fR macros. +To indicate one letter \fBnroff\fR macros, such as \fB.P\fR or \fB.H\fR, +quote a space in for the second character position. For example: +.sp 1 +.ti +8 +:set paragraphs=P\e bp<nl> +.sp 1 +would cause \fBvi\fR to consider \fB.P\fR and \fB.bp\fR as paragraph +delimiters. +.IP prompt 16 +Default: prompt Type: toggle +.br +In +.B ex +command mode the prompt character \fB:\fR will be printed when +\fBex\fR is waiting for a command. This is not of interest from vi. +.IP redraw 16 +Default: noredraw Type: toggle +.br +On dumb terminals, force the screen to always be up to date, +by sending great amounts of output. Useful only at high speeds. +.IP report 16 +Default: report=5 Type: numeric +.br +This sets the threshold for the number of lines modified. When +more than this number of lines are modified, removed, or yanked, +\fBvi\fR will report the number of lines changed at the bottom of +the screen. +.IP scroll 16 +Default: scroll={1/2 window} Type: numeric +.br +This is the number of lines that the screen scrolls up or down when +using the <^U> and <^D> commands. +.IP sections 16 +Default: sections=SHNHH HU Type: string +.br +Each two character pair of this string specify \fBnroff\fR macro names +which are to be treated as the beginning of a section by the +\fB]]\fR and \fB[[\fR commands. The default string is for the \fB-ms\fR +and \fB-mm\fR macros. +To enter one letter \fBnroff\fR macros, use a quoted space as the +second character. +See \fBparagraphs\fR for a fuller explanation. +.IP shell\ sh 16 +Default: sh=from environment SHELL or /bin/sh Type: string +.br +This is the name of the \fBsh\fR to be used for "escaped" commands. +.IP shiftwidth\ sw 16 +Default: sw=8 Type: numeric +.br +This is the number of spaces that a <^T> or <^D> will move over for +indenting, and the amount < and > shift by. +.IP showmatch\ sm 16 +Default: nosm Type: toggle +.br +When a \fB)\fR or \fB}\fR is typed, show the matching \fB(\fR or \fB{\fR +by moving the cursor to it for one second if it is on the current screen. +.IP slowopen\ slow 16 +Default: terminal dependent Type: toggle +.br +On terminals that are slow and unintelligent, this option prevents the +updating of the screen some of the time to improve speed. +.IP tabstop\ ts 16 +Default: ts=8 Type: numeric +.br +<tab>s are expanded to boundaries that are multiples of this value. +.IP taglength\ tl 16 +Default: tl=0 Type: numeric +.br +If nonzero, tag names are only significant to this many characters. +.IP term 16 +Default: (from environment \fBTERM\fP, else dumb) Type: string +.br +This is the terminal and controls the visual displays. It cannot be +changed when in "visual" mode, +you have to Q to command mode, type a +set term command, and do ``vi.'' to get back into visual. +Or exit vi, fix $TERM, and reenter. +The definitions that drive a particular +terminal type are found in the file \fB/etc/termcap\fR. +.IP terse 16 +Default: terse Type: toggle +.br +When set, the error diagnostics are short. +.IP warn 16 +Default: warn Type: toggle +.br +The user is warned if she/he tries to escape to +the shell without writing out the current changes. +.IP window 16 +Default: window={8 at 600 baud or less, 16 at 1200 baud, and screen +size \- 1 at 2400 baud or more} Type: numeric +.br +This is the number of lines in the window whenever \fBvi\fR must redraw +an entire screen. It is useful to make this size smaller if you are +on a slow line. +.IP w300,\ w1200,\ w9600 +.br +These set window, but only within the corresponding speed ranges. +They are useful in an EXINIT to fine tune window sizes. +For example, +.DS +set w300=4 w1200=12 +.DE +causes a 4 lines window at speed up to 600 baud, a 12 line window at 1200 +baud, and a full screen (the default) at over 1200 baud. +.IP wrapscan\ ws 16 +Default: ws Type: toggle +.br +Searches will wrap around the end of the file when is option is set. When +it is off, the search will terminate when it reaches the end or the +beginning of the file. +.IP wrapmargin\ wm 16 +Default: wm=0 Type: numeric +.br +\fBVi\fR will automatically insert a <nl> when it finds a natural +break point (usually a <sp> between words) that occurs within +"wm" spaces of the right margin. +Therefore with "wm=0" the option is off. Setting it to 10 would +mean that any time you are within 10 spaces of the right margin +\fBvi\fR would be looking for a <sp> or <tab> which it could +replace with a <nl>. This is convenient for people who forget +to look at the screen while they type. +(In version 3, wrapmargin behaves more like nroff, in that the +boundary specified by the distance from the right edge of the screen +is taken as the rightmost edge of the area where a break is allowed, +instead of the leftmost edge.) +.IP writeany\ wa 16 +Default: nowa Type: toggle +.br +\fBVi\fR normally makes a number of checks before it writes out a file. +This prevents the user from inadvertently destroying a file. When the +"writeany" option is enabled, \fBvi\fR no longer makes these checks. +.LE diff --git a/contrib/nvi/docs/USD.doc/vitut/vi.chars b/contrib/nvi/docs/USD.doc/vitut/vi.chars new file mode 100644 index 000000000000..7941065d1d0f --- /dev/null +++ b/contrib/nvi/docs/USD.doc/vitut/vi.chars @@ -0,0 +1,645 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)vi.chars 8.3 (Berkeley) 6/27/96 +.\" +.bd S 3 +.pn 21 +.de iP +.IP "\fB\\$1\fR" \\$2 +.. +.SH +Appendix: character functions +.PP +This appendix gives the uses the editor makes of each character. The +characters are presented in their order in the \s-2ASCII\s0 character +set: Control characters come first, then most special characters, then +the digits, upper and then lower case characters. +.PP +For each character we tell a meaning it has as a command and any meaning it +has during an insert. +If it has only meaning as a command, then only this is discussed. +Section numbers in parentheses indicate where the character is discussed; +a `f' after the section number means that the character is mentioned +in a footnote. +.iP "^@" 15 +Not a command character. +If typed as the first character of an insertion it is replaced with the +last text inserted, and the insert terminates. Only 128 characters are +saved from the last insert; if more characters were inserted the mechanism +is not available. +A \fB^@\fR cannot be part of the file due to the editor implementation +(7.5f). +.iP "^A" 15 +Unused. +.iP "^B" 15 +Backward window. +A count specifies repetition. +Two lines of continuity are kept if possible (2.1, 6.1, 7.2). +.iP "^C" 15 +Unused. +.iP "^D" 15 +As a command, scrolls down a half-window of text. +A count gives the number of (logical) lines to scroll, and is remembered +for future \fB^D\fR and \fB^U\fR commands (2.1, 7.2). +During an insert, backtabs over \fIautoindent\fR white space at the beginning +of a line (6.6, 7.5); this white space cannot be backspaced over. +.iP "^E" 15 +Exposes one more line below the current screen in the file, leaving +the cursor where it is if possible. +(Version 3 only.) +.iP "^F" 15 +Forward window. A count specifies repetition. +Two lines of continuity are kept if possible (2.1, 6.1, 7.2). +.iP "^G" 15 +Equivalent to \fB:f\fR\s-2CR\s0, printing the current file, whether +it has been modified, the current line number and the number of lines +in the file, and the percentage of the way through the file that you +are. +.iP "^H (\fR\s-2BS\s0\fP)" 15 +Same as +.B "left arrow" . +(See +.B h ). +During an insert, eliminates the last input character, backing over it +but not erasing it; it remains so you can see what you typed if you +wish to type something only slightly different (3.1, 7.5). +.iP "^I\ (\fR\s-2TAB\s0\fP)" 15 +Not a command character. +When inserted it prints as some +number of spaces. +When the cursor is at a tab character it rests at the last of the spaces +which represent the tab. +The spacing of tabstops is controlled by the \fItabstop\fR option (4.1, 6.6). +.iP "^J\ (\fR\s-2LF\s0\fP)" 15 +Same as +.B "down arrow" +(see +.B j ). +.iP "^K" 15 +Unused. +.iP "^L" 15 +The \s-2ASCII\s0 formfeed character, this causes the screen to be cleared +and redrawn. This is useful after a transmission error, if characters +typed by a program other than the editor scramble the screen, +or after output is stopped by an interrupt (5.4, 7.2f). +.ne 1i +.iP "^M\ (\fR\s-2CR\s0\fP)" 15 +A carriage return advances to the next line, at the first non-white position +in the line. Given a count, it advances that many lines (2.3). +During an insert, a \s-2CR\s0 causes the insert to continue onto +another line (3.1). +.iP "^N" 15 +Same as +.B "down arrow" +(see +.B j ). +.iP "^O" 15 +Unused. +.iP "^P" 15 +Same as +.B "up arrow" +(see +.B k ). +.iP "^Q" 15 +Not a command character. +In input mode, +.B ^Q +quotes the next character, the same as +.B ^V , +except that some teletype drivers will eat the +.B ^Q +so that the editor never sees it. +.iP "^R" 15 +Redraws the current screen, eliminating logical lines not corresponding +to physical lines (lines with only a single @ character on them). +On hardcopy terminals in \fIopen\fR mode, retypes the current line +(5.4, 7.2, 7.8). +.iP "^S" 15 +Unused. Some teletype drivers use +.B ^S +to suspend output until +.B ^Q is pressed. +.iP "^T" 15 +Not a command character. +During an insert, with \fIautoindent\fR set and at the beginning of the +line, inserts \fIshiftwidth\fR white space. +.iP "^U" 15 +Scrolls the screen up, inverting \fB^D\fR which scrolls down. Counts work as +they do for \fB^D\fR, and the previous scroll amount is common to both. +On a dumb terminal, \fB^U\fR will often necessitate clearing and redrawing +the screen further back in the file (2.1, 7.2). +.iP "^V" 15 +Not a command character. +In input mode, quotes the next character so that it is possible +to insert non-printing and special characters into the file (4.2, 7.5). +.iP "^W" 15 +Not a command character. +During an insert, backs up as \fBb\fR would in command mode; the deleted +characters remain on the display (see \fB^H\fR) (7.5). +.iP "^X" 15 +Unused. +.iP "^Y" 15 +Exposes one more line above the current screen, leaving the cursor where +it is if possible. (No mnemonic value for this key; however, it is next +to \fB^U\fR which scrolls up a bunch.) +(Version 3 only.) +.iP "^Z" 15 +If supported by the Unix system, +stops the editor, exiting to the top level shell. +Same as \fB:stop\fP\s-2CR\s0. +Otherwise, unused. +.iP "^[\ (\fR\s-2ESC\s0\fP)" 15 +Cancels a partially formed command, such as a \fBz\fR when no following +character has yet been given; terminates inputs on the last line (read +by commands such as \fB: /\fR and \fB?\fR); ends insertions of new text +into the buffer. +If an \s-2ESC\s0 is given when quiescent in command state, the editor +rings the bell or flashes the screen. You can thus hit \s-2ESC\s0 if +you don't know what is happening till the editor rings the bell. +If you don't know if you are in insert mode you can type \s-2ESC\s0\fBa\fR, +and then material to be input; the material will be inserted correctly +whether or not you were in insert mode when you started (1.5, 3.1, 7.5). +.iP "^\e" 15 +Unused. +.iP "^]" 15 +Searches for the word which is after the cursor as a tag. Equivalent +to typing \fB:ta\fR, this word, and then a \s-2CR\s0. +Mnemonically, this command is ``go right to'' (7.3). +.iP "^\(ua" 15 +Equivalent to \fB:e #\fR\s-2CR\s0, returning to the previous position +in the last edited file, or editing a file which you specified if you +got a `No write since last change diagnostic' and do not want to have +to type the file name again (7.3). +(You have to do a \fB:w\fR before \fB^\(ua\fR +will work in this case. If you do not wish to write the file you should +do \fB:e!\ #\fR\s-2CR\s0 instead.) +.iP "^_" 15 +Unused. +Reserved as the command character for the +Tektronix 4025 and 4027 terminal. +.iP "\fR\s-2SPACE\s0\fP" 15 +Same as +.B "right arrow" +(see +.B l ). +.iP "!" 15 +An operator, which processes lines from the buffer with reformatting commands. +Follow \fB!\fR with the object to be processed, and then the command name +terminated by \s-2CR\s0. Doubling \fB!\fR and preceding it by a count +causes count lines to be filtered; otherwise the count +is passed on to the object after the \fB!\fR. Thus \fB2!}\fR\fIfmt\fR\s-2CR\s0 +reformats the next two paragraphs by running them through the program +\fIfmt\fR. If you are working on \s-2LISP\s0, +the command \fB!%\fR\fIgrind\fR\s-2CR\s0,* +.FS +*Both +.I fmt +and +.I grind +are Berkeley programs and may not be present at all installations. +.FE +given at the beginning of a +function, will run the text of the function through the \s-2LISP\s0 grinder +(6.7, 7.3). +To read a file or the output of a command into the buffer use \fB:r\fR (7.3). +To simply execute a command use \fB:!\fR (7.3). +.tr " +.iP 15 +Precedes a named buffer specification. There are named buffers \fB1\-9\fR +used for saving deleted text and named buffers \fBa\-z\fR into which you can +place text (4.3, 6.3) +.tr +.iP "#" 15 +The macro character which, when followed by a number, will substitute +for a function key on terminals without function keys (6.9). +In input mode, +if this is your erase character, it will delete the last character +you typed in input mode, and must be preceded with a \fB\e\fR to insert +it, since it normally backs over the last input character you gave. +.iP "$" 15 +Moves to the end of the current line. If you \fB:se list\fR\s-2CR\s0, +then the end of each line will be shown by printing a \fB$\fR after the +end of the displayed text in the line. Given a count, advances to the +count'th following end of line; thus \fB2$\fR advances to the end of the +following line. +.iP "%" 15 +Moves to the parenthesis or brace \fB{ }\fR which balances the parenthesis +or brace at the current cursor position. +.iP "&" 15 +A synonym for \fB:&\fR\s-2CR\s0, by analogy with the +.I ex +.B & +command. +.iP "\(aa" 15 +When followed by a \fB\(aa\fR returns to the previous context at the +beginning of a line. The previous context is set whenever the current +line is moved in a non-relative way. +When followed by a letter \fBa\fR\-\fBz\fR, returns to the line which +was marked with this letter with a \fBm\fR command, at the first non-white +character in the line. (2.2, 5.3). +When used with an operator such as \fBd\fR, the operation takes place +over complete lines; if you use \fB\(ga\fR, the operation takes place +from the exact marked place to the current cursor position within the +line. +.iP "(" 15 +Retreats to the beginning of a +sentence, or to the beginning of a \s-2LISP\s0 s-expression +if the \fIlisp\fR option is set. +A sentence ends at a \fB. !\fR or \fB?\fR which is followed by either +the end of a line or by two spaces. Any number of closing \fB) ] "\fR +and \fB\(aa\fR characters may appear after the \fB. !\fR or \fB?\fR, +and before the spaces or end of line. Sentences also begin +at paragraph and section boundaries +(see \fB{\fR and \fB[[\fR below). +A count advances that many sentences (4.2, 6.8). +.iP ")" 15 +Advances to the beginning of a sentence. +A count repeats the effect. +See \fB(\fR above for the definition of a sentence (4.2, 6.8). +.iP "*" 15 +Unused. +.iP "+" 15 +Same as \s-2CR\s0 when used as a command. +.iP "," 15 +Reverse of the last \fBf F t\fR or \fBT\fR command, looking the other way +in the current line. Especially useful after hitting too many \fB;\fR +characters. A count repeats the search. +.iP "\-" 15 +Retreats to the previous line at the first non-white character. +This is the inverse of \fB+\fR and \s-2RETURN\s0. +If the line moved to is not on the screen, the screen is scrolled, or +cleared and redrawn if this is not possible. +If a large amount of scrolling would be required the screen is also cleared +and redrawn, with the current line at the center (2.3). +.iP "\&." 15 +Repeats the last command which changed the buffer. Especially useful +when deleting words or lines; you can delete some words/lines and then +hit \fB.\fR to delete more and more words/lines. +Given a count, it passes it on to the command being repeated. Thus after +a \fB2dw\fR, \fB3.\fR deletes three words (3.3, 6.3, 7.2, 7.4). +.iP "/" 15 +Reads a string from the last line on the screen, and scans forward for +the next occurrence of this string. The normal input editing sequences may +be used during the input on the bottom line; an returns to command state +without ever searching. +The search begins when you hit \s-2CR\s0 to terminate the pattern; +the cursor moves to the beginning of the last line to indicate that the search +is in progress; the search may then +be terminated with a \s-2DEL\s0 or \s-2RUB\s0, or by backspacing when +at the beginning of the bottom line, returning the cursor to +its initial position. +Searches normally wrap end-around to find a string +anywhere in the buffer. +.IP +When used with an operator the enclosed region is normally affected. +By mentioning an +offset from the line matched by the pattern you can force whole lines +to be affected. To do this give a pattern with a closing +a closing \fB/\fR and then an offset \fB+\fR\fIn\fR or \fB\-\fR\fIn\fR. +.IP +To include the character \fB/\fR in the search string, you must escape +it with a preceding \fB\e\fR. +A \fB\(ua\fR at the beginning of the pattern forces the match to occur +at the beginning of a line only; this speeds the search. A \fB$\fR at +the end of the pattern forces the match to occur at the end of a line +only. +More extended pattern matching is available, see section 7.4; +unless you set \fBnomagic\fR in your \fI\&.exrc\fR file you will have +to preceed the characters \fB. [ *\fR and \fB~\fR in the search pattern +with a \fB\e\fR to get them to work as you would naively expect (1.5, 2,2, +6.1, 7.2, 7.4). +.iP "0" 15 +Moves to the first character on the current line. +Also used, in forming numbers, after an initial \fB1\fR\-\fB9\fR. +.iP "1\-9" 15 +Used to form numeric arguments to commands (2.3, 7.2). +.iP ":" 15 +A prefix to a set of commands for file and option manipulation and escapes +to the system. Input is given on the bottom line and terminated with +an \s-2CR\s0, and the command then executed. You can return to where +you were by hitting \s-2DEL\s0 or \s-2RUB\s0 if you hit \fB:\fR accidentally +(see primarily 6.2 and 7.3). +.iP ";" 15 +Repeats the last single character find which used \fBf F t\fR or \fBT\fR. +A count iterates the basic scan (4.1). +.iP "<" 15 +An operator which shifts lines left one \fIshiftwidth\fR, normally 8 +spaces. Like all operators, affects lines when repeated, as in +\fB<<\fR. Counts are passed through to the basic object, thus \fB3<<\fR +shifts three lines (6.6, 7.2). +.iP "=" 15 +Reindents line for \s-2LISP\s0, as though they were typed in with \fIlisp\fR +and \fIautoindent\fR set (6.8). +.iP ">" 15 +An operator which shifts lines right one \fIshiftwidth\fR, normally 8 +spaces. Affects lines when repeated as in \fB>>\fR. Counts repeat the +basic object (6.6, 7.2). +.iP "?" 15 +Scans backwards, the opposite of \fB/\fR. See the \fB/\fR description +above for details on scanning (2.2, 6.1, 7.4). +.iP "@" 15 +A macro character (6.9). If this is your kill character, you must escape it with a \e +to type it in during input mode, as it normally backs over the input you +have given on the current line (3.1, 3.4, 7.5). +.iP "A" 15 +Appends at the end of line, a synonym for \fB$a\fR (7.2). +.iP "B" 15 +Backs up a word, where words are composed of non-blank sequences, placing +the cursor at the beginning of the word. A count repeats the effect +(2.4). +.iP "C" 15 +Changes the rest of the text on the current line; a synonym for \fBc$\fR. +.iP "D" 15 +Deletes the rest of the text on the current line; a synonym for \fBd$\fR. +.iP "E" 15 +Moves forward to the end of a word, defined as blanks and non-blanks, +like \fBB\fR and \fBW\fR. A count repeats the effect. +.iP "F" 15 +Finds a single following character, backwards in the current line. +A count repeats this search that many times (4.1). +.iP "G" 15 +Goes to the line number given as preceding argument, or the end of the +file if no preceding count is given. The screen is redrawn with the +new current line in the center if necessary (7.2). +.iP "H" 15 +.B "Home arrow" . +Homes the cursor to the top line on the screen. If a count is given, +then the cursor is moved to the count'th line on the screen. +In any case the cursor is moved to the first non-white character on the +line. If used as the target of an operator, full lines are affected +(2.3, 3.2). +.iP "I" 15 +Inserts at the beginning of a line; a synonym for \fB\(uai\fR. +.iP "J" 15 +Joins together lines, supplying appropriate white space: one space between +words, two spaces after a \fB.\fR, and no spaces at all if the first +character of the joined on line is \fB)\fR. A count causes that many +lines to be joined rather than the default two (6.5, 7.1f). +.iP "K" 15 +Unused. +.iP "L" 15 +Moves the cursor to the first non-white character of the last line on +the screen. With a count, to the first non-white of the count'th line +from the bottom. Operators affect whole lines when used with \fBL\fR +(2.3). +.iP "M" 15 +Moves the cursor to the middle line on the screen, at the first non-white +position on the line (2.3). +.iP "N" 15 +Scans for the next match of the last pattern given to +\fB/\fR or \fB?\fR, but in the reverse direction; this is the reverse +of \fBn\fR. +.iP "O" 15 +Opens a new line above the current line and inputs text there up to an +\s-2ESC\s0. A count can be used on dumb terminals to specify a number +of lines to be opened; this is generally obsolete, as the \fIslowopen\fR +option works better (3.1). +.iP "P" 15 +Puts the last deleted text back before/above the cursor. The text goes +back as whole lines above the cursor if it was deleted as whole lines. +Otherwise the text is inserted between the characters before and at the +cursor. May be preceded by a named buffer specification \fB"\fR\fIx\fR +to retrieve the contents of the buffer; buffers \fB1\fR\-\fB9\fR contain +deleted material, buffers \fBa\fR\-\fBz\fR are available for general +use (6.3). +.iP "Q" 15 +Quits from \fIvi\fR to \fIex\fR command mode. In this mode, whole lines +form commands, ending with a \s-2RETURN\s0. You can give all the \fB:\fR +commands; the editor supplies the \fB:\fR as a prompt (7.7). +.iP "R" 15 +Replaces characters on the screen with characters you type (overlay fashion). +Terminates with an \s-2ESC\s0. +.iP "S" 15 +Changes whole lines, a synonym for \fBcc\fR. A count substitutes for +that many lines. The lines are saved in the numeric buffers, and erased +on the screen before the substitution begins. +.iP "T" 15 +Takes a single following character, locates the character before the +cursor in the current line, and places the cursor just after that character. +A count repeats the effect. Most useful with operators such as \fBd\fR +(4.1). +.iP "U" 15 +Restores the current line to its state before you started changing it +(3.5). +.iP "V" 15 +Unused. +.iP "W" 15 +Moves forward to the beginning of a word in the current line, +where words are defined as sequences of blank/non-blank characters. +A count repeats the effect (2.4). +.iP "X" 15 +Deletes the character before the cursor. A count repeats the effect, +but only characters on the current line are deleted. +.iP "Y" 15 +Yanks a copy of the current line into the unnamed buffer, to be put back +by a later \fBp\fR or \fBP\fR; a very useful synonym for \fByy\fR. +A count yanks that many lines. May be preceded by a buffer name to put +lines in that buffer (7.4). +.iP "ZZ" 15 +Exits the editor. +(Same as \fB:x\fP\s-2CR\s0.) +If any changes have been made, the buffer is written out to the current file. +Then the editor quits. +.iP "[[" 15 +Backs up to the previous section boundary. A section begins at each +macro in the \fIsections\fR option, +normally a `.NH' or `.SH' and also at lines which which start +with a formfeed \fB^L\fR. Lines beginning with \fB{\fR also stop \fB[[\fR; +this makes it useful for looking backwards, a function at a time, in C +programs. If the option \fIlisp\fR is set, stops at each \fB(\fR at the +beginning of a line, and is thus useful for moving backwards at the top +level \s-2LISP\s0 objects. (4.2, 6.1, 6.6, 7.2). +.iP "\e" 15 +Unused. +.iP "]]" 15 +Forward to a section boundary, see \fB[[\fR for a definition (4.2, 6.1, +6.6, 7.2). +.iP "\(ua" 15 +Moves to the first non-white position on the current line (4.4). +.iP "_" 15 +Unused. +.iP "\(ga" 15 +When followed by a \fB\(ga\fR returns to the previous context. +The previous context is set whenever the current +line is moved in a non-relative way. +When followed by a letter \fBa\fR\-\fBz\fR, returns to the position which +was marked with this letter with a \fBm\fR command. +When used with an operator such as \fBd\fR, the operation takes place +from the exact marked place to the current position within the line; +if you use \fB\(aa\fR, the operation takes place over complete lines +(2.2, 5.3). +.iP "a" 15 +Appends arbitrary text after the current cursor position; the insert +can continue onto multiple lines by using \s-2RETURN\s0 within the insert. +A count causes the inserted text to be replicated, but only if the inserted +text is all on one line. +The insertion terminates with an \s-2ESC\s0 (3.1, 7.2). +.iP "b" 15 +Backs up to the beginning of a word in the current line. A word is a +sequence of alphanumerics, or a sequence of special characters. +A count repeats the effect (2.4). +.iP "c" 15 +An operator which changes the following object, replacing it with the +following input text up to an \s-2ESC\s0. If more than part of a single +line is affected, the text which is changed away is saved in the numeric named +buffers. If only part of the current line is affected, then the last +character to be changed away is marked with a \fB$\fR. +A count causes that many objects to be affected, thus both +\fB3c)\fR and \fBc3)\fR change the following three sentences (7.4). +.iP "d" 15 +An operator which deletes the following object. If more than part of +a line is affected, the text is saved in the numeric buffers. +A count causes that many objects to be affected; thus \fB3dw\fR is the +same as \fBd3w\fR (3.3, 3.4, 4.1, 7.4). +.iP "e" 15 +Advances to the end of the next word, defined as for \fBb\fR and \fBw\fR. +A count repeats the effect (2.4, 3.1). +.iP "f" 15 +Finds the first instance of the next character following the cursor on +the current line. A count repeats the find (4.1). +.iP "g" 15 +Unused. +.sp +Arrow keys +.B h , +.B j , +.B k , +.B l , +and +.B H . +.iP "h" 15 +.B "Left arrow" . +Moves the cursor one character to the left. +Like the other arrow keys, either +.B h , +the +.B "left arrow" +key, or one of the synonyms (\fB^H\fP) has the same effect. +On v2 editors, arrow keys on certain kinds of terminals +(those which send escape sequences, such as vt52, c100, or hp) +cannot be used. +A count repeats the effect (3.1, 7.5). +.iP "i" 15 +Inserts text before the cursor, otherwise like \fBa\fR (7.2). +.iP "j" 15 +.B "Down arrow" . +Moves the cursor one line down in the same column. +If the position does not exist, +.I vi +comes as close as possible to the same column. +Synonyms include +.B ^J +(linefeed) and +.B ^N . +.iP "k" 15 +.B "Up arrow" . +Moves the cursor one line up. +.B ^P +is a synonym. +.iP "l" 15 +.B "Right arrow" . +Moves the cursor one character to the right. +\s-2SPACE\s0 is a synonym. +.iP "m" 15 +Marks the current position of the cursor in the mark register which is +specified by the next character \fBa\fR\-\fBz\fR. Return to this position +or use with an operator using \fB\(ga\fR or \fB\(aa\fR (5.3). +.iP "n" 15 +Repeats the last \fB/\fR or \fB?\fR scanning commands (2.2). +.iP "o" 15 +Opens new lines below the current line; otherwise like \fBO\fR (3.1). +.iP "p" 15 +Puts text after/below the cursor; otherwise like \fBP\fR (6.3). +.iP "q" 15 +Unused. +.iP "r" 15 +Replaces the single character at the cursor with a single character you +type. The new character may be a \s-2RETURN\s0; this is the easiest +way to split lines. A count replaces each of the following count characters +with the single character given; see \fBR\fR above which is the more +usually useful iteration of \fBr\fR (3.2). +.iP "s" 15 +Changes the single character under the cursor to the text which follows +up to an \s-2ESC\s0; given a count, that many characters from the current +line are changed. The last character to be changed is marked with \fB$\fR +as in \fBc\fR (3.2). +.iP "t" 15 +Advances the cursor upto the character before the next character typed. +Most useful with operators such as \fBd\fR and \fBc\fR to delete the +characters up to a following character. You can use \fB.\fR to delete +more if this doesn't delete enough the first time (4.1). +.iP "u" 15 +Undoes the last change made to the current buffer. If repeated, will +alternate between these two states, thus is its own inverse. When used +after an insert which inserted text on more than one line, the lines are +saved in the numeric named buffers (3.5). +.iP "v" 15 +Unused. +.iP "w" 15 +Advances to the beginning of the next word, as defined by \fBb\fR (2.4). +.iP "x" 15 +Deletes the single character under the cursor. With a count deletes +deletes that many characters forward from the cursor position, but only +on the current line (6.5). +.iP "y" 15 +An operator, yanks the following object into the unnamed temporary buffer. +If preceded by a named buffer specification, \fB"\fR\fIx\fR, the text +is placed in that buffer also. Text can be recovered by a later \fBp\fR +or \fBP\fR (7.4). +.iP "z" 15 +Redraws the screen with the current line placed as specified by the following +character: \s-2RETURN\s0 specifies the top of the screen, \fB.\fR the +center of the screen, and \fB\-\fR at the bottom of the screen. +A count may be given after the \fBz\fR and before the following character +to specify the new screen size for the redraw. +A count before the \fBz\fR gives the number of the line to place in the +center of the screen instead of the default current line. (5.4) +.iP "{" 15 +Retreats to the beginning of the beginning of the preceding paragraph. +A paragraph begins at each macro in the \fIparagraphs\fR option, normally +`.IP', `.LP', `.PP', `.QP' and `.bp'. +A paragraph also begins after a completely +empty line, and at each section boundary (see \fB[[\fR above) (4.2, 6.8, +7.6). +.iP "|" 15 +Places the cursor on the character in the column specified +by the count (7.1, 7.2). +.iP "}" 15 +Advances to the beginning of the next paragraph. See \fB{\fR for the +definition of paragraph (4.2, 6.8, 7.6). +.iP "~" 15 +Unused. +.iP "^?\ (\s-2\fRDEL\fP\s0)" 15 +Interrupts the editor, returning it to command accepting state (1.5, +7.5) +.bp +\&. diff --git a/contrib/nvi/docs/USD.doc/vitut/vi.in b/contrib/nvi/docs/USD.doc/vitut/vi.in new file mode 100644 index 000000000000..c36ebe41743e --- /dev/null +++ b/contrib/nvi/docs/USD.doc/vitut/vi.in @@ -0,0 +1,2074 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)vi.in 8.5 (Berkeley) 8/18/96 +.\" +.nr LL 6.5i +.nr FL 6.5i +.EH 'USD:11-%''An Introduction to Display Editing with Vi' +.OH 'An Introduction to Display Editing with Vi''USD:11-%' +.bd S 3 +.if t .ds dg \(dg +.if n .ds dg + +.if t .ds dd \(dd +.if n .ds dd ++ +.\".RP +.TL +An Introduction to Display Editing with Vi +.AU +William Joy +.AU +Mark Horton +.AI +Computer Science Division +Department of Electrical Engineering and Computer Science +University of California, Berkeley +Berkeley, Ca. 94720 +.AB +.PP +.I Vi +(visual) is a display oriented interactive text editor. +When using +.I vi +the screen of your terminal acts as a window into the file which you +are editing. Changes which you make to the file are reflected +in what you see. +.PP +Using +.I vi +you can insert new text any place in the file quite easily. +Most of the commands to +.I vi +move the cursor around in the file. +There are commands to move the cursor +forward and backward in units of characters, words, +sentences and paragraphs. +A small set of operators, like +.B d +for delete and +.B c +for change, are combined with the motion commands to form operations +such as delete word or change paragraph, in a simple and natural way. +This regularity and the mnemonic assignment of commands to keys makes the +editor command set easy to remember and to use. +.PP +.I Vi +will work on a large number of display terminals, +and new terminals are easily driven after editing a terminal description file. +While it is advantageous to have an intelligent terminal which can locally +insert and delete lines and characters from the display, the editor will +function quite well on dumb terminals over slow phone lines. +The editor makes allowance for the low bandwidth in these situations +and uses smaller window sizes and +different display updating algorithms to make best use of the +limited speed available. +.PP +It is also possible to use the command set of +.I vi +on hardcopy terminals, storage tubes and ``glass tty's'' using a one line +editing window; thus +.I vi's +command set is available on all terminals. +The full command set of the more traditional, line +oriented editor +.I ex +is available within +.I vi; +it is quite simple to switch between the two modes of editing. +.AE +.NH 1 +Getting started +.PP +.FS +The financial support of an \s-2IBM\s0 Graduate Fellowship and the +National Science Foundation under grants MCS74-07644-A03 and MCS78-07291 +is gratefully acknowledged. +.FE +This document provides a quick introduction to +.I vi. +(Pronounced \fIvee-eye\fP.) +You should be running +.I vi +on a file you are familiar with while you are reading this. +The first part of this document (sections 1 through 5) +describes the basics of using +.I vi. +Some topics of special interest are presented in section 6, and +some nitty-gritty details of how the editor functions are saved for section +7 to avoid cluttering the presentation here. +.PP +There is also a short appendix here, which gives for each character the +special meanings which this character has in \fIvi\fR. Attached to +this document should be a quick reference card. +This card summarizes the commands of +.I vi +in a very compact format. You should have the card handy while you are +learning +.I vi. +.NH 2 +Specifying terminal type +.PP +Before you can start +.I vi +you must tell the system what kind of terminal you are using. +Here is a (necessarily incomplete) list of terminal type codes. +If your terminal does not appear here, you should consult with one of +the staff members on your system to find out the code for your terminal. +If your terminal does not have a code, one can be assigned and a description +for the terminal can be created. +.LP +.TS +center; +ab ab ab +a a a. +Code Full name Type +_ +2621 Hewlett-Packard 2621A/P Intelligent +2645 Hewlett-Packard 264x Intelligent +act4 Microterm ACT-IV Dumb +act5 Microterm ACT-V Dumb +adm3a Lear Siegler ADM-3a Dumb +adm31 Lear Siegler ADM-31 Intelligent +c100 Human Design Concept 100 Intelligent +dm1520 Datamedia 1520 Dumb +dm2500 Datamedia 2500 Intelligent +dm3025 Datamedia 3025 Intelligent +fox Perkin-Elmer Fox Dumb +h1500 Hazeltine 1500 Intelligent +h19 Heathkit h19 Intelligent +i100 Infoton 100 Intelligent +mime Imitating a smart act4 Intelligent +t1061 Teleray 1061 Intelligent +vt52 Dec VT-52 Dumb +.TE +.PP +Suppose for example that you have a Hewlett-Packard HP2621A +terminal. The code used by the system for this terminal is `2621'. +In this case you can use one of the following commands to tell the system +the type of your terminal: +.DS +% \fBsetenv TERM\fP 2621 +.DE +This command works with the +.I csh +shell. +If you are using the standard Bourne shell +.I sh +then you should give the commands +.DS +$ \fBTERM=\fP2621 +$ \fBexport TERM\fP +.DE +.PP +If you want to arrange to have your terminal type set up automatically +when you log in, you can use the +.I tset +program. +If you dial in on a +.I mime , +but often use hardwired ports, a typical line for your +.I .login +file (if you use csh) would be +.DS +\fBsetenv TERM \(gatset\fP \- \-d mime\(ga +.DE +or for your +.I .profile +file (if you use sh) +.DS +\fBTERM=\(gatse\fPt \- \-d mime\(ga +.DE +.I Tset +knows which terminals are hardwired to each port +and needs only to be told that when you dial in you +are probably on a +.I mime . +.I Tset +is usually used to change the erase and kill characters, too. +.NH 2 +Editing a file +.PP +After telling the system which kind of terminal you have, you should +make a copy of a file you are familiar with, and run +.I vi +on this file, giving the command +.DS +% \fBvi\fR \fIname\fR +.DE +replacing \fIname\fR with the name of the copy file you just created. +The screen should clear and the text of your file should appear on the +screen. If something else happens refer to the footnote.\*(dd +.FS +\*(dd If you gave the system an incorrect terminal type code then the +editor may have just made a mess out of your screen. This happens when +it sends control codes for one kind of terminal to some other +kind of terminal. In this case hit +the keys \fB:q\fR (colon and the q key) and then hit the \s-2RETURN\s0 key. +This should get you back to the command level interpreter. +Figure out what you did wrong (ask someone else if necessary) and try again. + Another thing which can go wrong is that you typed the wrong file name and +the editor just printed an error diagnostic. In this case you should +follow the above procedure for getting out of the editor, and try again +this time spelling the file name correctly. + If the editor doesn't seem to respond to the commands which you type +here, try sending an interrupt to it by hitting the \s-2DEL\s0 or \s-2RUB\s0 +key on your terminal, and then hitting the \fB:q\fR command again followed +by a carriage return. +.sp +.FE +.NH 2 +The editor's copy: the buffer +.PP +The editor does not directly modify the file which you are editing. +Rather, the editor makes a copy of this file, in a place called the +.I buffer, +and remembers the file's +name. You do not affect the contents of the file unless and until you +write the changes you make back into the original file. +.NH 2 +Notational conventions +.PP +In our examples, input which must be typed as is will be presented in +\fBbold face\fR. Text which should be replaced with appropriate input +will be given in \fIitalics\fR. We will represent special characters +in \s-2SMALL CAPITALS\s0. +.NH 2 +Arrow keys +.PP +The editor command set is independent of the terminal +you are using. On most terminals with cursor positioning keys, these keys +will also work within the editor. +If you don't have cursor positioning keys, or even if you do, you can use +the \fBh j k\fR and \fBl\fR keys as cursor positioning +keys (these are labelled with arrows on an +.I adm3a).* +.PP +(Particular note for the HP2621: on this terminal the function keys +must be \fIshifted\fR (ick) to send to the machine, otherwise they +only act locally. Unshifted use will leave the cursor positioned +incorrectly.) +.FS +* As we will see later, +.I h +moves back to the left (like control-h which is a backspace), +.I j +moves down (in the same column), +.I k +moves up (in the same column), +and +.I l +moves to the right. +.FE +.NH 2 +Special characters: \s-2ESC\s0, \s-2CR\s0 and \s-2DEL\s0 +.PP +Several of these special characters are very important, so be sure to +find them right now. Look on your keyboard for a key labelled \s-2ESC\s0 +or \s-2ALT\s0. It should be near the upper left corner of your terminal. +Try hitting this key a few times. The editor will ring the bell +to indicate that it is in a quiescent state.\*(dd +.FS +\*(dd On smart terminals where it is possible, the editor will quietly +flash the screen rather than ringing the bell. +.FE +Partially formed commands are cancelled by \s-2ESC\s0, and when you insert +text in the file you end the text insertion +with \s-2ESC\s0. This key is a fairly +harmless one to hit, so you can just hit it if you don't know +what is going on until the editor rings the bell. +.PP +The \s-2CR\s0 or \s-2RETURN\s0 key is important because it is used +to terminate certain commands. +It is usually at the right side of the keyboard, +and is the same command used at the end of each shell command. +.PP +Another very useful key is the \s-2DEL\s0 or \s-2RUB\s0 key, which generates +an interrupt, telling the editor to stop what it is doing. +It is a forceful way of making the editor listen +to you, or to return it to the quiescent state if you don't know or don't +like what is going on. Try hitting the `/' key on your terminal. This +key is used when you want to specify a string to be searched for. The +cursor should now be positioned at the bottom line of the terminal after +a `/' printed as a prompt. You can get the cursor back to the current +position by hitting the \s-2DEL\s0 or \s-2RUB\s0 key; try this now.* +.FS +* Backspacing over the `/' will also cancel the search. +.FE +From now on we will simply refer to hitting the \s-2DEL\s0 or \s-2RUB\s0 +key as ``sending an interrupt.''** +.FS +** On some systems, this interruptibility comes at a price: you cannot type +ahead when the editor is computing with the cursor on the bottom line. +.FE +.PP +The editor often echoes your commands on the last line of the terminal. +If the cursor is on the first position of this last line, then the editor +is performing a computation, such as computing a new position in the +file after a search or running a command to reformat part of the buffer. +When this is happening you can stop the editor by +sending an interrupt. +.NH 2 +Getting out of the editor +.PP +After you have worked with this introduction for a while, and you wish +to do something else, you can give the command \fBZZ\fP +to the editor. +This will write the contents of the editor's buffer back into +the file you are editing, if you made any changes, and then quit from +the editor. You can also end an editor +session by giving the command \fB:q!\fR\s-2CR\s0;\*(dg +.FS +\*(dg All commands which read from the last display line can also be +terminated with a \s-2ESC\s0 as well as an \s-2CR\s0. +.FE +this is a dangerous but occasionally essential +command which ends the editor session and discards all your changes. +You need to know about this command in case you change the editor's +copy of a file you wish only to look at. Be very careful +not to give this command when you really want to save +the changes you have made. +.NH 1 +Moving around in the file +.NH 2 +Scrolling and paging +.PP +The editor has a number of commands for moving around in the file. +The most useful of these is generated by hitting the control and D keys +at the same time, a control-D or `^D'. We will use this two character +notation for referring to these control keys from now on. You may have +a key labelled `^' on your terminal. This key will be represented as `\(ua' +in this document; `^' is exclusively used as part of the `^x' notation +for control characters.\*(dd +.FS +\*(dd If you don't have a `^' key on your terminal +then there is probably a key labelled `\(ua'; in any case these characters +are one and the same. +.FE +.PP +As you know now if you tried hitting \fB^D\fR, this command scrolls down in +the file. The \fBD\fR thus stands for down. Many editor commands are mnemonic +and this makes them much easier to remember. For instance the command +to scroll up is \fB^U\fR. Many dumb terminals can't scroll up at all, in which +case hitting \fB^U\fR clears the screen and refreshes it +with a line which is farther back in the file at the top. +.PP +If you want to see more of the file below where you are, you can +hit \fB^E\fR to expose one more line at the bottom of the screen, +leaving the cursor where it is. +The command \fB^Y\fR (which is hopelessly non-mnemonic, but next to \fB^U\fR +on the keyboard) exposes one more line at the top of the screen. +.PP +There are other ways to move around in the file; the keys \fB^F\fR and \fB^B\fR +move forward and backward a page, +keeping a couple of lines of continuity between screens +so that it is possible to read through a file using these rather than +\fB^D\fR and \fB^U\fR if you wish. +.PP +Notice the difference between scrolling and paging. If you are trying +to read the text in a file, hitting \fB^F\fR to move forward a page +will leave you only a little context to look back at. Scrolling on the +other hand leaves more context, and happens more smoothly. You can continue +to read the text as scrolling is taking place. +.NH 2 +Searching, goto, and previous context +.PP +Another way to position yourself in the file is by giving the editor a string +to search for. Type the character \fB/\fR followed by a string of characters +terminated by \s-2CR\s0. The editor will position the cursor +at the next occurrence of this string. +Try hitting \fBn\fR to then go to the next occurrence of this string. +The character \fB?\fR will search backwards from where you are, and is +otherwise like \fB/\fR.\*(dg +.FS +\*(dg These searches will normally wrap around the end of the file, and thus +find the string even if it is not on a line in the direction you search +provided it is anywhere else in the file. You can disable this wraparound +in scans by giving the command \fB:se nowrapscan\fR\s-2CR\s0, +or more briefly \fB:se nows\fR\s-2CR\s0. +.FE +.PP +If the search string you give the editor is not present in the +file the editor will print +a diagnostic on the last line of the screen, and the cursor will be returned +to its initial position. +.PP +If you wish the search to match only at the beginning of a line, begin +the search string with an \fB\(ua\fR. To match only at the end of +a line, end the search string with a \fB$\fR. +Thus \fB/\(uasearch\fR\s-2CR\s0 will search for the word `search' at +the beginning of a line, and \fB/last$\fR\s-2CR\s0 searches for the +word `last' at the end of a line.* +.FS +*Actually, the string you give to search for here can be a +.I "regular expression" +in the sense of the editors +.I ex (1) +and +.I ed (1). +If you don't wish to learn about this yet, you can disable this more +general facility by doing +\fB:se\ nomagic\fR\s-2CR\s0; +by putting this command in +EXINIT +in your environment, you can have this always be in effect (more +about +.I EXINIT +later.) +.FE +.PP +The command \fBG\fR, when preceded by a number will position the cursor +at that line in the file. +Thus \fB1G\fR will move the cursor to +the first line of the file. If you give \fBG\fR no count, then it moves +to the end of the file. +.PP +If you are near the end of the file, and the last line is not at the bottom +of the screen, the editor will place only the character `~' on each remaining +line. This indicates that the last line in the file is on the screen; +that is, the `~' lines are past the end of the file. +.PP +You can find out the state of the file you are editing by typing a \fB^G\fR. +The editor will show you the name of the file you are editing, the number +of the current line, the number of lines in the buffer, and the percentage +of the way through the buffer which you are. +Try doing this now, and remember the number of the line you are on. +Give a \fBG\fR command to get to the end and then another \fBG\fR command +to get back where you were. +.PP +You can also get back to a previous position by using the command +\fB\(ga\(ga\fR (two back quotes). +This is often more convenient than \fBG\fR because it requires no advance +preparation. +Try giving a \fBG\fR or a search with \fB/\fR or \fB?\fR and then a +\fB\(ga\(ga\fR to get back to where you were. If you accidentally hit +\fBn\fR or any command which moves you far away from a context of interest, you +can quickly get back by hitting \fB\(ga\(ga\fR. +.NH 2 +Moving around on the screen +.PP +Now try just moving the cursor around on the screen. +If your terminal has arrow keys (4 or 5 keys with arrows +going in each direction) try them and convince yourself +that they work. +If you don't have working arrow keys, you can always use +.B h , +.B j , +.B k , +and +.B l . +Experienced users of +.I vi +prefer these keys to arrow keys, +because they are usually right underneath their fingers. +.PP +Hit the \fB+\fR key. Each time you do, notice that the cursor +advances to the next line in the file, at the first non-white position +on the line. The \fB\-\fR key is like \fB+\fR but goes the other way. +.PP +These are very common keys for moving up and down lines in the file. +Notice that if you go off the bottom or top with these keys then the +screen will scroll down (and up if possible) to bring a line at a time +into view. The \s-2RETURN\s0 key has the same effect as the \fB+\fR +key. +.PP +.I Vi +also has commands to take you to the top, middle and bottom of the screen. +\fBH\fR will take you to the top (home) line on the screen. +Try preceding it with a +number as in \fB3H\fR. +This will take you to the third line on the screen. +Many +.I vi +commands take preceding numbers and do interesting things with them. +Try \fBM\fR, +which takes you to the middle line on the screen, +and \fBL\fR, +which takes you to the last line on the screen. +\fBL\fR also takes counts, thus +\fB5L\fR will take you to the fifth line from the bottom. +.NH 2 +Moving within a line +.PP +Now try picking a word on some line on the screen, not the +first word on the line. +move the cursor using \s-2RETURN\s0 and \fB\-\fR to be on the line where +the word is. +Try hitting the \fBw\fR key. This will advance the cursor to the +next word on the line. +Try hitting the \fBb\fR key to back up words +in the line. +Also try the \fBe\fR key which advances you to the end of the current +word rather than to the beginning of the next word. +Also try \s-2SPACE\s0 (the space bar) which moves right one character +and the \s-2BS\s0 (backspace or \fB^H\fR) key which moves left one character. +The key \fBh\fR works as \fB^H\fR does and is useful if you don't have +a \s-2BS\s0 key. +(Also, as noted just above, \fBl\fR will move to the right.) +.PP +If the line had punctuation in it you may have noticed that +that the \fBw\fR and \fBb\fR +keys stopped at each group of punctuation. You can also go back and +forwards words without stopping at punctuation by using \fBW\fR and \fBB\fR +rather than the lower case equivalents. Think of these as bigger words. +Try these on a few lines with punctuation to see how they differ from +the lower case \fBw\fR and \fBb\fR. +.PP +The word keys wrap around the end of line, +rather than stopping at the end. Try moving to a word on a line below +where you are by repeatedly hitting \fBw\fR. +.NH 2 +Summary +.IP +.TS +lw(.50i)b a. +\fR\s-2SPACE\s0\fP advance the cursor one position +^B backwards to previous page +^D scrolls down in the file +^E exposes another line at the bottom +^F forward to next page +^G tell what is going on +^H backspace the cursor +^N next line, same column +^P previous line, same column +^U scrolls up in the file +^Y exposes another line at the top ++ next line, at the beginning +\- previous line, at the beginning +/ scan for a following string forwards +? scan backwards +B back a word, ignoring punctuation +G go to specified line, last default +H home screen line +M middle screen line +L last screen line +W forward a word, ignoring punctuation +b back a word +e end of current word +n scan for next instance of \fB/\fR or \fB?\fR pattern +w word after this word +.TE +.NH 2 +View +.PP +If you want to use the editor to look at a file, +rather than to make changes, +invoke it as +.I view +instead of +.I vi . +This will set the +.I readonly +option which will prevent you from +accidently overwriting the file. +.sp +.NH 1 +Making simple changes +.NH 2 +Inserting +.PP +One of the most useful commands is the +\fBi\fR (insert) command. +After you type \fBi\fR, everything you type until you hit \s-2ESC\s0 +is inserted into the file. +Try this now; position yourself to some word in the file and try inserting +text before this word. +If you are on an dumb terminal it will seem, for a minute, +that some of the characters in your line have been overwritten, but they will +reappear when you hit \s-2ESC\s0. +.PP +Now try finding a word which can, but does not, end in an `s'. +Position yourself at this word and type \fBe\fR (move to end of word), then +\fBa\fR for append and then `s\s-2ESC\s0' to terminate the textual insert. +This sequence of commands can be used to easily pluralize a word. +.PP +Try inserting and appending a few times to make sure you understand how +this works; \fBi\fR placing text to the left of the cursor, \fBa\fR to +the right. +.PP +It is often the case that you want to add new lines to the file you are +editing, before or after some specific line in the file. Find a line +where this makes sense and then give the command \fBo\fR to create a +new line after the line you are on, or the command \fBO\fR to create +a new line before the line you are on. After you create a new line in +this way, text you type up to an \s-2ESC\s0 is inserted on the new line. +.PP +Many related editor commands +are invoked by the same letter key and differ only in that one is given +by a lower +case key and the other is given by +an upper case key. In these cases, the +upper case key often differs from the lower case key in its sense of +direction, with +the upper case key working backward and/or up, while the lower case +key moves forward and/or down. +.PP +Whenever you are typing in text, you can give many lines of input or +just a few characters. +To type in more than one line of text, +hit a \s-2RETURN\s0 at the middle of your input. A new line will be created +for text, and you can continue to type. If you are on a slow +and dumb terminal the editor may choose to wait to redraw the +tail of the screen, and will let you type over the existing screen lines. +This avoids the lengthy delay which would occur if the editor attempted +to keep the tail of the screen always up to date. The tail of the screen will +be fixed up, and the missing lines will reappear, when you hit \s-2ESC\s0. +.PP +While you are inserting new text, you can use the characters you normally use +at the system command level (usually \fB^H\fR or \fB#\fR) to backspace +over the last +character which you typed, and the character which you use to kill input lines +(usually \fB@\fR, \fB^X\fR, or \fB^U\fR) +to erase the input you have typed on the current line.\*(dg +.FS +\*(dg In fact, the character \fB^H\fR (backspace) always works to erase the +last input character here, regardless of what your erase character is. +.FE +The character \fB^W\fR +will erase a whole word and leave you after the space after the previous +word; it is useful for quickly backing up in an insert. +.PP +Notice that when you backspace during an insertion the characters you +backspace over are not erased; the cursor moves backwards, and the characters +remain on the display. This is often useful if you are planning to type +in something similar. In any case the characters disappear when when +you hit \s-2ESC\s0; if you want to get rid of them immediately, hit an +\s-2ESC\s0 and then \fBa\fR again. +.PP +Notice also that you can't erase characters which you didn't insert, and that +you can't backspace around the end of a line. If you need to back up +to the previous line to make a correction, just hit \s-2ESC\s0 and move +the cursor back to the previous line. After making the correction you +can return to where you were and use the insert or append command again. +.sp .5 +.NH 2 +Making small corrections +.PP +You can make small corrections in existing text quite easily. +Find a single character which is wrong or just pick any character. +Use the arrow keys to find the character, or +get near the character with the word motion keys and then either +backspace (hit the \s-2BS\s0 key or \fB^H\fR or even just \fBh\fR) or +\s-2SPACE\s0 (using the space bar) +until the cursor is on the character which is wrong. +If the character is not needed then hit the \fBx\fP key; this deletes +the character from the file. It is analogous to the way you \fBx\fP +out characters when you make mistakes on a typewriter (except it's not +as messy). +.PP +If the character +is incorrect, you can replace it with the correct character by giving +the command \fBr\fR\fIc\fR, +where \fIc\fR is replaced by the correct character. +Finally if the character which is incorrect should be replaced +by more than one character, give the command \fBs\fR which substitutes +a string of characters, ending with \s-2ESC\s0, for it. +If there are a small number of characters +which are wrong you can precede \fBs\fR with a count of the number of +characters to be replaced. Counts are also useful with \fBx\fR to specify +the number of characters to be deleted. +.NH 2 +More corrections: operators +.PP +You already know almost enough to make changes at a higher level. +All you need to know now is that the +.B d +key acts as a delete operator. Try the command +.B dw +to delete a word. +Try hitting \fB.\fR a few times. Notice that this repeats the effect +of the \fBdw\fR. The command \fB.\fR repeats the last command which +made a change. You can remember it by analogy with an ellipsis `\fB...\fR'. +.PP +Now try +\fBdb\fR. +This deletes a word backwards, namely the preceding word. +Try +\fBd\fR\s-2SPACE\s0. This deletes a single character, and is equivalent +to the \fBx\fR command. +.PP +Another very useful operator is +.B c +or change. The command +.B cw +thus changes the text of a single word. +You follow it by the replacement text ending with an \s-2ESC\s0. +Find a word which you can change to another, and try this +now. +Notice that the end of the text to be changed was marked with the character +`$' so that you can see this as you are typing in the new material. +.sp .5 +.NH 2 +Operating on lines +.PP +It is often the case that you want to operate on lines. +Find a line which you want to delete, and type +\fBdd\fR, +the +.B d +operator twice. This will delete the line. +If you are on a dumb terminal, the editor may just erase the line on +the screen, replacing it with a line with only an @ on it. This line +does not correspond to any line in your file, but only acts as a place +holder. It helps to avoid a lengthy redraw of the rest of the screen +which would be necessary to close up the hole created by the deletion +on a terminal without a delete line capability. +.PP +Try repeating the +.B c +operator twice; this will change a whole line, erasing its previous contents and +replacing them with text you type up to an \s-2ESC\s0.\*(dg +.FS +\*(dg The command \fBS\fR is a convenient synonym for for \fBcc\fR, by +analogy with \fBs\fR. Think of \fBS\fR as a substitute on lines, while +\fBs\fR is a substitute on characters. +.FE +.PP +You can delete or change more than one line by preceding the +.B dd +or +.B cc +with a count, i.e. \fB5dd\fR deletes 5 lines. +You can also give a command like \fBdL\fR to delete all the lines up to +and including +the last line on the screen, or \fBd3L\fR to delete through the third from +the bottom line. Try some commands like this now.* +.FS +* One subtle point here involves using the \fB/\fR search after a \fBd\fR. +This will normally delete characters from the current position to the +point of the match. If what is desired is to delete whole lines +including the two points, give the pattern as \fB/pat/+0\fR, a line address. +.FE +Notice that the editor lets you know when you change a large number of +lines so that you can see the extent of the change. +The editor will also always tell you when a change you make affects text which +you cannot see. +.NH 2 +Undoing +.PP +Now suppose that the last change which you made was incorrect; +you could use the insert, delete and append commands to put the correct +material back. However, since it is often the case that we regret a +change or make a change incorrectly, the editor provides a +.B u +(undo) command to reverse the last change which you made. +Try this a few times, and give it twice in a row to notice that an +.B u +also undoes a +.B u. +.PP +The undo command lets you reverse only a single change. After you make +a number of changes to a line, you may decide that you would rather have +the original state of the line back. The +.B U +command restores the current line to the state before you started changing +it. +.PP +You can recover text which you delete, even if +undo will not bring it back; see the section on recovering lost text +below. +.NH 2 +Summary +.IP +.TS +lw(.50i)b a. +\fR\s-2SPACE\s0\fP advance the cursor one position +^H backspace the cursor +^W erase a word during an insert +\fRerase\fP your erase (usually ^H or #), erases a character during an insert +\fRkill\fP your kill (usually @, ^X, or ^U), kills the insert on this line +\&\fB.\fP repeats the changing command +O opens and inputs new lines, above the current +U undoes the changes you made to the current line +a appends text after the cursor +c changes the object you specify to the following text +d deletes the object you specify +i inserts text before the cursor +o opens and inputs new lines, below the current +u undoes the last change +.TE +.NH 1 +Moving about; rearranging and duplicating text +.NH 2 +Low level character motions +.PP +Now move the cursor to a line where there is a punctuation or a bracketing +character such as a parenthesis or a comma or period. Try the command +\fBf\fR\fIx\fR where \fIx\fR is this character. This command finds +the next \fIx\fR character to the right of the cursor in the current +line. Try then hitting a \fB;\fR, which finds the next instance of the +same character. By using the \fBf\fR command and then a sequence of +\fB;\fR's you can often +get to a particular place in a line much faster than with a sequence +of word motions or \s-2SPACE\s0s. +There is also a \fBF\fR command, which is like \fBf\fR, but searches +backward. The \fB;\fR command repeats \fBF\fR also. +.PP +When you are operating on the text in a line it is often desirable to +deal with the characters up to, but not including, the first instance of +a character. Try \fBdf\fR\fIx\fR for some \fIx\fR now and +notice that the \fIx\fR character is deleted. Undo this with \fBu\fR +and then try \fBdt\fR\fIx\fR; the \fBt\fR here stands for to, i.e. +delete up to the next \fIx\fR, but not the \fIx\fR. The command \fBT\fR +is the reverse of \fBt\fR. +.PP +When working with the text of a single line, an \fB\(ua\fR moves the +cursor to the first non-white position on the line, and a +\fB$\fR moves it to the end of the line. Thus \fB$a\fR will append new +text at the end of the current line. +.PP +Your file may have tab (\fB^I\fR) characters in it. These +characters are represented as a number of spaces expanding to a tab stop, +where tab stops are every 8 positions.* +.FS +* This is settable by a command of the form \fB:se ts=\fR\fIx\fR\s-2CR\s0, +where \fIx\fR is 4 to set tabstops every four columns. This has +effect on the screen representation within the editor. +.FE +When the cursor is at a tab, it sits on the last of the several spaces +which represent that tab. Try moving the cursor back and forth over +tabs so you understand how this works. +.PP +On rare occasions, your file may have nonprinting characters in it. +These characters are displayed in the same way they are represented in +this document, that is with a two character code, the first character +of which is `^'. On the screen non-printing characters resemble a `^' +character adjacent to another, but spacing or backspacing over the character +will reveal that the two characters are, like the spaces representing +a tab character, a single character. +.PP +The editor sometimes discards control characters, +depending on the character and the setting of the +.I beautify +option, +if you attempt to insert them in your file. +You can get a control character in the file by beginning +an insert and then typing a \fB^V\fR before the control +character. The +\fB^V\fR quotes the following character, causing it to be +inserted directly into the file. +.PP +.NH 2 +Higher level text objects +.PP +In working with a document it is often advantageous to work in terms +of sentences, paragraphs, and sections. The operations \fB(\fR and \fB)\fR +move to the beginning of the previous and next sentences respectively. +Thus the command \fBd)\fR will delete the rest of the current sentence; +likewise \fBd(\fR will delete the previous sentence if you are at the +beginning of the current sentence, or the current sentence up to where +you are if you are not at the beginning of the current sentence. +.PP +A sentence is defined to end at a `.', `!' or `?' which is followed by +either the end of a line, or by two spaces. Any number of closing `)', +`]', `"' and `\(aa' characters may appear after the `.', `!' or `?' before +the spaces or end of line. +.PP +The operations \fB{\fR and \fB}\fR move over paragraphs and the operations +\fB[[\fR and \fB]]\fR move over sections.\*(dg +.FS +\*(dg The \fB[[\fR and \fB]]\fR operations +require the operation character to be doubled because they can move the +cursor far from where it currently is. While it is easy to get back +with the command \fB\(ga\(ga\fP, +these commands would still be frustrating +if they were easy to hit accidentally. +.FE +.PP +A paragraph begins after each empty line, and also +at each of a set of paragraph macros, specified by the pairs of characters +in the definition of the string valued option \fIparagraphs\fR. +The default setting for this option defines the paragraph macros of the +\fI\-ms\fR and \fI\-mm\fR macro packages, i.e. the `.IP', `.LP', `.PP' +and `.QP', `.P' and `.LI' macros.\*(dd +.FS +\*(dd You can easily change or extend this set of macros by assigning a +different string to the \fIparagraphs\fR option in your EXINIT. +See section 6.2 for details. +The `.bp' directive is also considered to start a paragraph. +.FE +Each paragraph boundary is also a sentence boundary. The sentence +and paragraph commands can +be given counts to operate over groups of sentences and paragraphs. +.PP +Sections in the editor begin after each macro in the \fIsections\fR option, +normally `.NH', `.SH', `.H' and `.HU', and each line with a formfeed \fB^L\fR +in the first column. +Section boundaries are always line and paragraph boundaries also. +.PP +Try experimenting with the sentence and paragraph commands until you are +sure how they work. If you have a large document, try looking through +it using the section commands. +The section commands interpret a preceding count as a different window size in +which to redraw the screen at the new location, and this window size +is the base size for newly drawn windows until another size is specified. +This is very useful +if you are on a slow terminal and are looking for a particular section. +You can give the first section command a small count to then see each successive +section heading in a small window. +.NH 2 +Rearranging and duplicating text +.PP +The editor has a single unnamed buffer where the last deleted or +changed away text is saved, and a set of named buffers \fBa\fR\-\fBz\fR +which you can use to save copies of text and to move text around in +your file and between files. +.PP +The operator +.B y +yanks a copy of the object which follows into the unnamed buffer. +If preceded by a buffer name, \fB"\fR\fIx\fR\|\fBy\fR, where +\fIx\fR here is replaced by a letter \fBa\-z\fR, it places the text in the named +buffer. The text can then be put back in the file with the commands +.B p +and +.B P; +\fBp\fR puts the text after or below the cursor, while \fBP\fR puts the text +before or above the cursor. +.PP +If the text which you +yank forms a part of a line, or is an object such as a sentence which +partially spans more than one line, then when you put the text back, +it will be placed after the cursor (or before if you +use \fBP\fR). If the yanked text forms whole lines, they will be put +back as whole lines, without changing the current line. In this case, +the put acts much like a \fBo\fR or \fBO\fR command. +.PP +Try the command \fBYP\fR. This makes a copy of the current line and +leaves you on this copy, which is placed before the current line. +The command \fBY\fR is a convenient abbreviation for \fByy\fR. +The command \fBYp\fR will also make a copy of the current line, and place +it after the current line. You can give \fBY\fR a count of lines to +yank, and thus duplicate several lines; try \fB3YP\fR. +.PP +To move text within the buffer, you need to delete it in one place, and +put it back in another. You can precede a delete operation by the +name of a buffer in which the text is to be stored as in \fB"a5dd\fR +deleting 5 lines into the named buffer \fIa\fR. You can then move the +cursor to the eventual resting place of the these lines and do a \fB"ap\fR +or \fB"aP\fR to put them back. +In fact, you can switch and edit another file before you put the lines +back, by giving a command of the form \fB:e \fR\fIname\fR\s-2CR\s0 where +\fIname\fR is the name of the other file you want to edit. You will +have to write back the contents of the current editor buffer (or discard +them) if you have made changes before the editor will let you switch +to the other file. +An ordinary delete command saves the text in the unnamed buffer, +so that an ordinary put can move it elsewhere. +However, the unnamed buffer is lost when you change files, +so to move text from one file to another you should use an unnamed buffer. +.NH 2 +Summary. +.IP +.TS +lw(.50i)b a. +\(ua first non-white on line +$ end of line +) forward sentence +} forward paragraph +]] forward section +( backward sentence +{ backward paragraph +[[ backward section +f\fIx\fR find \fIx\fR forward in line +p put text back, after cursor or below current line +y yank operator, for copies and moves +t\fIx\fR up to \fIx\fR forward, for operators +F\fIx\fR f backward in line +P put text back, before cursor or above current line +T\fIx\fR t backward in line +.TE +.ne 1i +.NH 1 +High level commands +.NH 2 +Writing, quitting, editing new files +.PP +So far we have seen how to enter +.I vi +and to write out our file using either +\fBZZ\fR or \fB:w\fR\s-2CR\s0. The first exits from +the editor, +(writing if changes were made), +the second writes and stays in the editor. +.PP +If you have changed the editor's copy of the file but do not wish to +save your changes, either because you messed up the file or decided that the +changes are not an improvement to the file, then you can give the command +\fB:q!\fR\s-2CR\s0 to quit from the editor without writing the changes. +You can also reedit the same file (starting over) by giving the command +\fB:e!\fR\s-2CR\s0. These commands should be used only rarely, and with +caution, as it is not possible to recover the changes you have made after +you discard them in this manner. +.PP +You can edit a different file without leaving the editor by giving the +command \fB:e\fR\ \fIname\fR\s-2CR\s0. If you have not written out +your file before you try to do this, then the editor will tell you this, +and delay editing the other file. You can then give the command +\fB:w\fR\s-2CR\s0 to save your work and then the \fB:e\fR\ \fIname\fR\s-2CR\s0 +command again, or carefully give the command \fB:e!\fR\ \fIname\fR\s-2CR\s0, +which edits the other file discarding the changes you have made to the +current file. +To have the editor automatically save changes, +include +.I "set autowrite" +in your EXINIT, +and use \fB:n\fP instead of \fB:e\fP. +.NH 2 +Escaping to a shell +.PP +You can get to a shell to execute a single command by giving a +.I vi +command of the form \fB:!\fIcmd\fR\s-2CR\s0. +The system will run the single command +.I cmd +and when the command finishes, the editor will ask you to hit a \s-2RETURN\s0 +to continue. When you have finished looking at the output on the screen, +you should hit \s-2RETURN\s0 and the editor will clear the screen and +redraw it. You can then continue editing. +You can also give another \fB:\fR command when it asks you for a \s-2RETURN\s0; +in this case the screen will not be redrawn. +.PP +If you wish to execute more than one command in the shell, then you can +give the command \fB:sh\fR\s-2CR\s0. +This will give you a new shell, and when you finish with the shell, ending +it by typing a \fB^D\fR, the editor will clear the screen and continue. +.PP +On systems which support it, \fB^Z\fP will suspend the editor +and return to the (top level) shell. +When the editor is resumed, the screen will be redrawn. +.NH 2 +Marking and returning +.PP +The command \fB\(ga\(ga\fR returned to the previous place +after a motion of the cursor by a command such as \fB/\fR, \fB?\fR or +\fBG\fR. You can also mark lines in the file with single letter tags +and return to these marks later by naming the tags. Try marking the +current line with the command \fBm\fR\fIx\fR, where you should pick some +letter for \fIx\fR, say `a'. Then move the cursor to a different line +(any way you like) and hit \fB\(gaa\fR. The cursor will return to the +place which you marked. +Marks last only until you edit another file. +.PP +When using operators such as +.B d +and referring to marked lines, it is often desirable to delete whole lines +rather than deleting to the exact position in the line marked by \fBm\fR. +In this case you can use the form \fB\(aa\fR\fIx\fR rather than +\fB\(ga\fR\fIx\fR. Used without an operator, \fB\(aa\fR\fIx\fR will move to +the first non-white character of the marked line; similarly \fB\(aa\(aa\fR +moves to the first non-white character of the line containing the previous +context mark \fB\(ga\(ga\fR. +.NH 2 +Adjusting the screen +.PP +If the screen image is messed up because of a transmission error to your +terminal, or because some program other than the editor wrote output +to your terminal, you can hit a \fB^L\fR, the \s-2ASCII\s0 form-feed +character, to cause the screen to be refreshed. +.PP +On a dumb terminal, if there are @ lines in the middle of the screen +as a result of line deletion, you may get rid of these lines by typing +\fB^R\fR to cause the editor to retype the screen, closing up these holes. +.PP +Finally, if you wish to place a certain line on the screen at the top +middle or bottom of the screen, you can position the cursor to that line, +and then give a \fBz\fR command. +You should follow the \fBz\fR command with a \s-2RETURN\s0 if you want +the line to appear at the top of the window, a \fB.\fR if you want it +at the center, or a \fB\-\fR if you want it at the bottom. +.NH 1 +Special topics +.NH 2 +Editing on slow terminals +.PP +When you are on a slow terminal, it is important to limit the amount +of output which is generated to your screen so that you will not suffer +long delays, waiting for the screen to be refreshed. We have already +pointed out how the editor optimizes the updating of the screen during +insertions on dumb terminals to limit the delays, and how the editor erases +lines to @ when they are deleted on dumb terminals. +.PP +The use of the slow terminal insertion mode is controlled by the +.I slowopen +option. You can force the editor to use this mode even on faster terminals +by giving the command \fB:se slow\fR\s-2CR\s0. If your system is sluggish +this helps lessen the amount of output coming to your terminal. +You can disable this option by \fB:se noslow\fR\s-2CR\s0. +.PP +The editor can simulate an intelligent terminal on a dumb one. Try +giving the command \fB:se redraw\fR\s-2CR\s0. This simulation generates +a great deal of output and is generally tolerable only on lightly loaded +systems and fast terminals. You can disable this by giving the command + \fB:se noredraw\fR\s-2CR\s0. +.PP +The editor also makes editing more pleasant at low speed by starting +editing in a small window, and letting the window expand as you edit. +This works particularly well on intelligent terminals. The editor can +expand the window easily when you insert in the middle of the screen +on these terminals. If possible, try the editor on an intelligent terminal +to see how this works. +.PP +You can control the size of the window which is redrawn each time the +screen is cleared by giving window sizes as argument to the commands +which cause large screen motions: +.DS +.B ": / ? [[ ]] \(ga \(aa" +.DE +Thus if you are searching for a particular instance of a common string +in a file you can precede the first search command by a small number, +say 3, and the editor will draw three line windows around each instance +of the string which it locates. +.PP +You can easily expand or contract the window, placing the current line +as you choose, by giving a number on a \fBz\fR command, after the \fBz\fR +and before the following \s-2RETURN\s0, \fB.\fR or \fB\-\fR. Thus the +command \fBz5.\fR redraws the screen with the current line in the center +of a five line window.\*(dg +.FS +\*(dg Note that the command \fB5z.\fR has an entirely different effect, +placing line 5 in the center of a new window. +.FE +.PP +If the editor is redrawing or otherwise updating large portions of the +display, you can interrupt this updating by hitting a \s-2DEL\s0 or \s-2RUB\s0 +as usual. If you do this you may partially confuse the editor about +what is displayed on the screen. You can still edit the text on +the screen if you wish; clear up the confusion +by hitting a \fB^L\fR; or move or search again, ignoring the +current state of the display. +.PP +See section 7.8 on \fIopen\fR mode for another way to use the +.I vi +command set on slow terminals. +.NH 2 +Options, set, and editor startup files +.PP +The editor has a set of options, some of which have been mentioned above. +The most useful options are given in the following table. +.PP +The options are of three kinds: numeric options, string options, and +toggle options. You can set numeric and string options by a statement +of the form +.DS +\fBset\fR \fIopt\fR\fB=\fR\fIval\fR +.DE +and toggle options can be set or unset by statements of one of the forms +.DS +\fBset\fR \fIopt\fR +\fBset\fR \fBno\fR\fIopt\fR +.DE +.KF +.TS +lb lb lb lb +l l l a. +Name Default Description +_ +autoindent noai Supply indentation automatically +autowrite noaw Automatic write before \fB:n\fR, \fB:ta\fR, \fB^\(ua\fR, \fB!\fR +ignorecase noic Ignore case in searching +lisp nolisp \fB( { ) }\fR commands deal with S-expressions +list nolist Tabs print as ^I; end of lines marked with $ +magic nomagic The characters . [ and * are special in scans +number nonu Lines are displayed prefixed with line numbers +paragraphs para=IPLPPPQPbpP LI Macro names which start paragraphs +redraw nore Simulate a smart terminal on a dumb one +sections sect=NHSHH HU Macro names which start new sections +shiftwidth sw=8 Shift distance for <, > and input \fB^D\fP and \fB^T\fR +showmatch nosm Show matching \fB(\fP or \fB{\fP as \fB)\fP or \fB}\fR is typed +slowopen slow Postpone display updates during inserts +term dumb The kind of terminal you are using. +.TE +.KE +These statements can be placed in your EXINIT in your environment, +or given while you are running +.I vi +by preceding them with a \fB:\fR and following them with a \s-2CR\s0. +.PP +You can get a list of all options which you have changed by the +command \fB:set\fR\s-2CR\s0, or the value of a single option by the +command \fB:set\fR \fIopt\fR\fB?\fR\s-2CR\s0. +A list of all possible options and their values is generated by +\fB:set all\fP\s-2CR\s0. +Set can be abbreviated \fBse\fP. +Multiple options can be placed on one line, e.g. +\fB:se ai aw nu\fP\s-2CR\s0. +.PP +Options set by the \fBset\fP command only last +while you stay in the editor. +It is common to want to have certain options set whenever you +use the editor. +This can be accomplished by creating a list of \fIex\fP commands\*(dg +.FS +\*(dg +All commands which start with +.B : +are \fIex\fP commands. +.FE +which are to be run every time you start up \fIex\fP, \fIedit\fP, +or \fIvi\fP. +A typical list includes a \fBset\fP command, and possibly a few +\fBmap\fP commands. +Since it is advisable to get these commands on one line, they can +be separated with the | character, for example: +.DS +\fBset\fP ai aw terse|\fBmap\fP @ dd|\fBmap\fP # x +.DE +which sets the options \fIautoindent\fP, \fIautowrite\fP, \fIterse\fP, +(the +.B set +command), +makes @ delete a line, +(the first +.B map ), +and makes # delete a character, +(the second +.B map ). +(See section 6.9 for a description of the \fBmap\fP command) +This string should be placed in the variable EXINIT in your environment. +If you use the shell \fIcsh\fP, +put this line in the file +.I .login +in your home directory: +.DS +setenv EXINIT \(aa\fBset\fP ai aw terse|\fBmap\fP @ dd|\fBmap\fP # x\(aa +.DE +If you use the standard shell \fIsh\fP, +put these lines in the file +.I .profile +in your home directory: +.DS +EXINIT=\(aa\fBset\fP ai aw terse|\fBmap\fP @ dd|\fBmap\fP # x\(aa +export EXINIT +.DE +Of course, the particulars of the line would depend on which options +you wanted to set. +.NH 2 +Recovering lost lines +.PP +You might have a serious problem if you delete a number of lines and then +regret that they were deleted. Despair not, the editor saves the last +9 deleted blocks of text in a set of numbered registers 1\-9. +You can get the \fIn\fR'th previous deleted text back in your file by +the command +"\fR\fIn\fR\|\fBp\fR. +The "\fR here says that a buffer name is to follow, +\fIn\fR is the number of the buffer you wish to try +(use the number 1 for now), +and +.B p +is the put command, which puts text in the buffer after the cursor. +If this doesn't bring back the text you wanted, hit +.B u +to undo this and then +\fB\&.\fR +(period) +to repeat the put command. +In general the +\fB\&.\fR +command will repeat the last change you made. +As a special case, when the last command refers to a numbered text buffer, +the \fB.\fR command increments the number of the buffer before repeating +the command. Thus a sequence of the form +.DS +\fB"1pu.u.u.\fR +.DE +will, if repeated long enough, show you all the deleted text which has +been saved for you. +You can omit the +.B u +commands here to gather up all this text in the buffer, or stop after any +\fB\&.\fR command to keep just the then recovered text. +The command +.B P +can also be used rather than +.B p +to put the recovered text before rather than after the cursor. +.NH 2 +Recovering lost files +.PP +If the system crashes, you can recover the work you were doing +to within a few changes. You will normally receive mail when you next +login giving you the name of the file which has been saved for you. +You should then change to the directory where you were when the system +crashed and give a command of the form: +.DS +% \fBvi \-r\fR \fIname\fR +.DE +replacing \fIname\fR with the name of the file which you were editing. +This will recover your work to a point near where you left off.\*(dg +.FS +\*(dg In rare cases, some of the lines of the file may be lost. The +editor will give you the numbers of these lines and the text of the lines +will be replaced by the string `LOST'. These lines will almost always +be among the last few which you changed. You can either choose to discard +the changes which you made (if they are easy to remake) or to replace +the few lost lines by hand. +.FE +.PP +You can get a listing of the files which are saved for you by giving +the command: +.DS +% \fBvi \-r\fR +.DE +If there is more than one instance of a particular file saved, the editor +gives you the newest instance each time you recover it. You can thus +get an older saved copy back by first recovering the newer copies. +.PP +For this feature to work, +.I vi +must be correctly installed by a super user on your system, +and the +.I mail +program must exist to receive mail. +The invocation ``\fIvi -r\fP'' will not always list all saved files, +but they can be recovered even if they are not listed. +.NH 2 +Continuous text input +.PP +When you are typing in large amounts of text it is convenient to have +lines broken near the right margin automatically. You can cause this +to happen by giving the command +\fB:se wm=10\fR\s-2CR\s0. +This causes all lines to be broken at a space at least 10 columns +from the right hand edge of the screen. +.PP +If the editor breaks an input line and you wish to put it back together +you can tell it to join the lines with \fBJ\fR. You can give \fBJ\fR +a count of the number of lines to be joined as in \fB3J\fR to join 3 +lines. The editor supplies white space, if appropriate, +at the juncture of the joined +lines, and leaves the cursor at this white space. +You can kill the white space with \fBx\fR if you don't want it. +.NH 2 +Features for editing programs +.PP +The editor has a number of commands for editing programs. +The thing that most distinguishes editing of programs from editing of text +is the desirability of maintaining an indented structure to the body of +the program. The editor has a +.I autoindent +facility for helping you generate correctly indented programs. +.PP +To enable this facility you can give the command \fB:se ai\fR\s-2CR\s0. +Now try opening a new line with \fBo\fR and type some characters on the +line after a few tabs. If you now start another line, notice that the +editor supplies white space at the beginning of the line to line it up +with the previous line. You cannot backspace over this indentation, +but you can use \fB^D\fR key to backtab over the supplied indentation. +.PP +Each time you type \fB^D\fR you back up one position, normally to an +8 column boundary. This amount is settable; the editor has an option +called +.I shiftwidth +which you can set to change this value. +Try giving the command \fB:se sw=4\fR\s-2CR\s0 +and then experimenting with autoindent again. +.PP +For shifting lines in the program left and right, there are operators +.B < +and +.B >. +These shift the lines you specify right or left by one +.I shiftwidth. +Try +.B << +and +.B >> +which shift one line left or right, and +.B <L +and +.B >L +shifting the rest of the display left and right. +.PP +If you have a complicated expression and wish to see how the parentheses +match, put the cursor at a left or right parenthesis and hit \fB%\fR. +This will show you the matching parenthesis. +This works also for braces { and }, and brackets [ and ]. +.PP +If you are editing C programs, you can use the \fB[[\fR and \fB]]\fR keys +to advance or retreat to a line starting with a \fB{\fR, i.e. a function +declaration at a time. When \fB]]\fR is used with an operator it stops +after a line which starts with \fB}\fR; this is sometimes useful with +\fBy]]\fR. +.NH 2 +Filtering portions of the buffer +.PP +You can run system commands over portions of the buffer using the operator +\fB!\fR. +You can use this to sort lines in the buffer, or to reformat portions +of the buffer with a pretty-printer. +Try typing in a list of random words, one per line and ending them +with a blank line. Back up to the beginning of the list, and then give +the command \fB!}sort\fR\s-2CR\s0. This says to sort the next paragraph +of material, and the blank line ends a paragraph. +.NH 2 +Commands for editing \s-2LISP\s0 +.PP +If you are editing a \s-2LISP\s0 program you should set the option +.I lisp +by doing +\fB:se\ lisp\fR\s-2CR\s0. +This changes the \fB(\fR and \fB)\fR commands to move backward and forward +over s-expressions. +The \fB{\fR and \fB}\fR commands are like \fB(\fR and \fB)\fR but don't +stop at atoms. These can be used to skip to the next list, or through +a comment quickly. +.PP +The +.I autoindent +option works differently for \s-2LISP\s0, supplying indent to align at +the first argument to the last open list. If there is no such argument +then the indent is two spaces more than the last level. +.PP +There is another option which is useful for typing in \s-2LISP\s0, the +.I showmatch +option. +Try setting it with +\fB:se sm\fR\s-2CR\s0 +and then try typing a `(' some words and then a `)'. Notice that the +cursor shows the position of the `(' which matches the `)' briefly. +This happens only if the matching `(' is on the screen, and the cursor +stays there for at most one second. +.PP +The editor also has an operator to realign existing lines as though they +had been typed in with +.I lisp +and +.I autoindent +set. This is the \fB=\fR operator. +Try the command \fB=%\fR at the beginning of a function. This will realign +all the lines of the function declaration. +.PP +When you are editing \s-2LISP\s0,, the \fB[[\fR and \fR]]\fR advance +and retreat to lines beginning with a \fB(\fR, and are useful for dealing +with entire function definitions. +.NH 2 +Macros +.PP +.I Vi +has a parameterless macro facility, which lets you set it up so that +when you hit a single keystroke, the editor will act as though +you had hit some longer sequence of keys. You can set this up if +you find yourself typing the same sequence of commands repeatedly. +.PP +Briefly, there are two flavors of macros: +.IP a) +Ones where you put the macro body in a buffer register, say \fIx\fR. +You can then type \fB@x\fR to invoke the macro. The \fB@\fR may be followed +by another \fB@\fR to repeat the last macro. +.IP b) +You can use the +.I map +command from +.I vi +(typically in your +.I EXINIT ) +with a command of the form: +.DS +:map \fIlhs\fR \fIrhs\fR\s-2CR +.DE +mapping +.I lhs +into +.I rhs. +There are restrictions: +.I lhs +should be one keystroke (either 1 character or one function key) +since it must be entered within one second +(unless +.I notimeout +is set, in which case you can type it as slowly as you wish, +and +.I vi +will wait for you to finish it before it echoes anything). +The +.I lhs +can be no longer than 10 characters, the +.I rhs +no longer than 100. +To get a space, tab or newline into +.I lhs +or +.I rhs +you should escape them with a \fB^V\fR. +(It may be necessary to double the \fB^V\fR if the map +command is given inside +.I vi, +rather than in +.I ex.) +Spaces and tabs inside the +.I rhs +need not be escaped. +.PP +Thus to make the \fBq\fR key write and exit the editor, you can give +the command +.DS +:map q :wq\fB^V^V\fP\s-2CR CR\s0 +.DE +which means that whenever you type \fBq\fR, it will be as though you +had typed the four characters \fB:wq\fR\s-2CR\s0. +A \fB^V\fR's is needed because without it the \s-2CR\s0 would end the +\fB:\fR command, rather than becoming part of the +.I map +definition. +There are two +.B ^V 's +because from within +.I vi , +two +.B ^V 's +must be typed to get one. +The first \s-2CR\s0 is part of the +.I rhs , +the second terminates the : command. +.PP +Macros can be deleted with +.DS +unmap lhs +.DE +.PP +If the +.I lhs +of a macro is ``#0'' through ``#9'', this maps the particular function key +instead of the 2 character ``#'' sequence. So that terminals without +function keys can access such definitions, the form ``#x'' will mean function +key +.I x +on all terminals (and need not be typed within one second.) +The character ``#'' can be changed by using a macro in the usual way: +.DS +:map \fB^V^V^I\fP # +.DE +to use tab, for example. (This won't affect the +.I map +command, which still uses +.B #, +but just the invocation from visual mode. +.PP +The undo command reverses an entire macro call as a unit, +if it made any changes. +.PP +Placing a `!' after the word +.B map +causes the mapping to apply +to input mode, rather than command mode. +Thus, to arrange for \fB^T\fP to be the same as 4 spaces in input mode, +you can type: +.DS +:map \fB^T\fP \fB^V\fP\o'b/'\o'b/'\o'b/'\o'b/' +.DE +where +.B \o'b/' +is a blank. +The \fB^V\fP is necessary to prevent the blanks from being taken as +white space between the +.I lhs +and +.I rhs . +.NH +Word Abbreviations +.PP +A feature similar to macros in input mode is word abbreviation. +This allows you to type a short word and have it expanded into +a longer word or words. +The commands are +.B :abbreviate +and +.B :unabbreviate +(\fB:ab\fP +and +.B :una ) +and have the same syntax as +.B :map . +For example: +.DS +:ab eecs Electrical Engineering and Computer Sciences +.DE +causes the word `eecs' to always be changed into the +phrase `Electrical Engineering and Computer Sciences'. +Word abbreviation is different from macros in that +only whole words are affected. +If `eecs' were typed as part of a larger word, it would +be left alone. +Also, the partial word is echoed as it is typed. +There is no need for an abbreviation to be a single keystroke, +as it should be with a macro. +.NH 2 +Abbreviations +.PP +The editor has a number of short +commands which abbreviate longer commands which we +have introduced here. You can find these commands easily +on the quick reference card. +They often save a bit of typing and you can learn them as convenient. +.NH 1 +Nitty-gritty details +.NH 2 +Line representation in the display +.PP +The editor folds long logical lines onto many physical lines in the display. +Commands which advance lines advance logical lines and will skip +over all the segments of a line in one motion. The command \fB|\fR moves +the cursor to a specific column, and may be useful for getting near the +middle of a long line to split it in half. Try \fB80|\fR on a line which +is more than 80 columns long.\*(dg +.FS +\*(dg You can make long lines very easily by using \fBJ\fR to join together +short lines. +.FE +.PP +The editor only puts full lines on the display; if there is not enough +room on the display to fit a logical line, the editor leaves the physical +line empty, placing only an @ on the line as a place holder. When you +delete lines on a dumb terminal, the editor will often just clear the +lines to @ to save time (rather than rewriting the rest of the screen.) +You can always maximize the information on the screen by giving the \fB^R\fR +command. +.PP +If you wish, you can have the editor place line numbers before each line +on the display. Give the command \fB:se nu\fR\s-2CR\s0 to enable +this, and the command \fB:se nonu\fR\s-2CR\s0 to turn it off. +You can have tabs represented as \fB^I\fR and the ends of lines indicated +with `$' by giving the command \fB:se list\fR\s-2CR\s0; +\fB:se nolist\fR\s-2CR\s0 turns this off. +.PP +Finally, lines consisting of only the character `~' are displayed when +the last line in the file is in the middle of the screen. These represent +physical lines which are past the logical end of file. +.NH 2 +Counts +.PP +Most +.I vi +commands will use a preceding count to affect their behavior in some way. +The following table gives the common ways in which the counts are used: +.DS +.TS +l lb. +new window size : / ? [[ ]] \` \' +scroll amount ^D ^U +line/column number z G | +repeat effect \fRmost of the rest\fP +.TE +.DE +.PP +The editor maintains a notion of the current default window size. +On terminals which run at speeds greater than 1200 baud +the editor uses the full terminal screen. +On terminals which are slower than 1200 baud +(most dialup lines are in this group) +the editor uses 8 lines as the default window size. +At 1200 baud the default is 16 lines. +.PP +This size is the size used when the editor clears and refills the screen +after a search or other motion moves far from the edge of the current window. +The commands which take a new window size as count all often cause the +screen to be redrawn. If you anticipate this, but do not need as large +a window as you are currently using, you may wish to change the screen +size by specifying the new size before these commands. +In any case, the number of lines used on the screen will expand if you +move off the top with a \fB\-\fR or similar command or off the bottom +with a command such as \s-2RETURN\s0 or \fB^D\fR. +The window will revert to the last specified size the next time it is +cleared and refilled.\*(dg +.FS +\*(dg But not by a \fB^L\fR which just redraws the screen as it is. +.FE +.PP +The scroll commands \fB^D\fR and \fB^U\fR likewise remember the amount +of scroll last specified, using half the basic window size initially. +The simple insert commands use a count to specify a repetition of the +inserted text. Thus \fB10a+\-\-\-\-\fR\s-2ESC\s0 will insert a grid-like +string of text. +A few commands also use a preceding count as a line or column number. +.PP +Except for a few commands which ignore any counts (such as \fB^R\fR), +the rest of the editor commands use a count to indicate a simple repetition +of their effect. Thus \fB5w\fR advances five words on the current line, +while \fB5\fR\s-2RETURN\s0 advances five lines. A very useful instance +of a count as a repetition is a count given to the \fB.\fR command, which +repeats the last changing command. If you do \fBdw\fR and then \fB3.\fR, +you will delete first one and then three words. You can then delete +two more words with \fB2.\fR. +.NH 2 +More file manipulation commands +.PP +The following table lists the file manipulation commands which you can +use when you are in +.I vi. +.KF +.DS +.TS +lb l. +:w write back changes +:wq write and quit +:x write (if necessary) and quit (same as ZZ). +:e \fIname\fP edit file \fIname\fR +:e! reedit, discarding changes +:e + \fIname\fP edit, starting at end +:e +\fIn\fP edit, starting at line \fIn\fP +:e # edit alternate file +:w \fIname\fP write file \fIname\fP +:w! \fIname\fP overwrite file \fIname\fP +:\fIx,y\fPw \fIname\fP write lines \fIx\fP through \fIy\fP to \fIname\fP +:r \fIname\fP read file \fIname\fP into buffer +:r !\fIcmd\fP read output of \fIcmd\fP into buffer +:n edit next file in argument list +:n! edit next file, discarding changes to current +:n \fIargs\fP specify new argument list +:ta \fItag\fP edit file containing tag \fItag\fP, at \fItag\fP +.TE +.DE +.KE +All of these commands are followed by a \s-2CR\s0 or \s-2ESC\s0. +The most basic commands are \fB:w\fR and \fB:e\fR. +A normal editing session on a single file will end with a \fBZZ\fR command. +If you are editing for a long period of time you can give \fB:w\fR commands +occasionally after major amounts of editing, and then finish +with a \fBZZ\fR. When you edit more than one file, you can finish +with one with a \fB:w\fR and start editing a new file by giving a \fB:e\fR +command, +or set +.I autowrite +and use \fB:n\fP <file>. +.PP +If you make changes to the editor's copy of a file, but do not wish to +write them back, then you must give an \fB!\fR after the command you +would otherwise use; this forces the editor to discard any changes +you have made. Use this carefully. +.ne 1i +.PP +The \fB:e\fR command can be given a \fB+\fR argument to start at the +end of the file, or a \fB+\fR\fIn\fR argument to start at line \fIn\fR\^. +In actuality, \fIn\fR may be any editor command not containing a space, +usefully a scan like \fB+/\fIpat\fR or \fB+?\fIpat\fR. +In forming new names to the \fBe\fR command, you can use the character +\fB%\fR which is replaced by the current file name, or the character +\fB#\fR which is replaced by the alternate file name. +The alternate file name is generally the last name you typed other than +the current file. Thus if you try to do a \fB:e\fR and get a diagnostic +that you haven't written the file, you can give a \fB:w\fR command and +then a \fB:e #\fR command to redo the previous \fB:e\fR. +.PP +You can write part of the buffer to a file by finding out the lines +that bound the range to be written using \fB^G\fR, and giving these +numbers after the \fB:\fR +and before the \fBw\fP, separated by \fB,\fR's. +You can also mark these lines with \fBm\fR and +then use an address of the form \fB\(aa\fR\fIx\fR\fB,\fB\(aa\fR\fIy\fR +on the \fBw\fR command here. +.PP +You can read another file into the buffer after the current line by using +the \fB:r\fR command. +You can similarly read in the output from a command, just use \fB!\fR\fIcmd\fR +instead of a file name. +.PP +If you wish to edit a set of files in succession, you can give all the +names on the command line, and then edit each one in turn using the command +\fB:n\fR. It is also possible to respecify the list of files to be edited +by giving the \fB:n\fR command a list of file names, or a pattern to +be expanded as you would have given it on the initial +.I vi +command. +.PP +If you are editing large programs, you will find the \fB:ta\fR command +very useful. It utilizes a data base of function names and their locations, +which can be created by programs such as +.I ctags, +to quickly find a function whose name you give. +If the \fB:ta\fR command will require the editor to switch files, then +you must \fB:w\fR or abandon any changes before switching. You can repeat +the \fB:ta\fR command without any arguments to look for the same tag +again. +.NH 2 +More about searching for strings +.PP +When you are searching for strings in the file with \fB/\fR and \fB?\fR, +the editor normally places you at the next or previous occurrence +of the string. If you are using an operator such as \fBd\fR, +\fBc\fR or \fBy\fR, then you may well wish to affect lines up to the +line before the line containing the pattern. You can give a search of +the form \fB/\fR\fIpat\fR\fB/\-\fR\fIn\fR to refer to the \fIn\fR'th line +before the next line containing \fIpat\fR, or you can use \fB+\fR instead +of \fB\-\fR to refer to the lines after the one containing \fIpat\fR. +If you don't give a line offset, then the editor will affect characters +up to the match place, rather than whole lines; thus use ``+0'' to affect +to the line which matches. +.PP +You can have the editor ignore the case of words in the searches it does +by giving the command \fB:se ic\fR\s-2CR\s0. +The command \fB:se noic\fR\s-2CR\s0 turns this off. +.ne 1i +.PP +Strings given to searches may actually be regular expressions. +If you do not want or need this facility, you should +.DS +set nomagic +.DE +in your EXINIT. +In this case, +only the characters \fB\(ua\fR and \fB$\fR are special in patterns. +The character \fB\e\fR is also then special (as it is most everywhere in +the system), and may be used to get at the +an extended pattern matching facility. +It is also necessary to use a \e before a +\fB/\fR in a forward scan or a \fB?\fR in a backward scan, in any case. +The following table gives the extended forms when \fBmagic\fR is set. +.DS +.TS +lb l. +\(ua at beginning of pattern, matches beginning of line +$ at end of pattern, matches end of line +\fB\&.\fR matches any character +\e< matches the beginning of a word +\e> matches the end of a word +[\fIstr\fP] matches any single character in \fIstr\fP +[\(ua\fIstr\fP] matches any single character not in \fIstr\fP +[\fIx\fP\-\fIy\fP] matches any character between \fIx\fP and \fIy\fP +* matches any number of the preceding pattern +.TE +.DE +If you use \fBnomagic\fR mode, then +the \fB. [\fR and \fB*\fR primitives are given with a preceding +\e. +.NH 2 +More about input mode +.PP +There are a number of characters which you can use to make corrections +during input mode. These are summarized in the following table. +.sp .5 +.DS +.TS +lb l. +^H deletes the last input character +^W deletes the last input word, defined as by \fBb\fR +erase your erase character, same as \fB^H\fP +kill your kill character, deletes the input on this line +\e escapes a following \fB^H\fP and your erase and kill +\s-2ESC\s0 ends an insertion +\s-2DEL\s0 interrupts an insertion, terminating it abnormally +\s-2CR\s0 starts a new line +^D backtabs over \fIautoindent\fP +0^D kills all the \fIautoindent\fP +\(ua^D same as \fB0^D\fP, but restores indent next line +^V quotes the next non-printing character into the file +.TE +.DE +.sp .5 +.PP +The most usual way of making corrections to input is by typing \fB^H\fR +to correct a single character, or by typing one or more \fB^W\fR's to +back over incorrect words. If you use \fB#\fR as your erase character +in the normal system, it will work like \fB^H\fR. +.PP +Your system kill character, normally \fB@\fR, \fB^X\fP or \fB^U\fR, +will erase all +the input you have given on the current line. +In general, you can neither +erase input back around a line boundary nor can you erase characters +which you did not insert with this insertion command. To make corrections +on the previous line after a new line has been started you can hit \s-2ESC\s0 +to end the insertion, move over and make the correction, and then return +to where you were to continue. The command \fBA\fR which appends at the +end of the current line is often useful for continuing. +.PP +If you wish to type in your erase or kill character (say # or @) then +you must precede it with a \fB\e\fR, just as you would do at the normal +system command level. A more general way of typing non-printing characters +into the file is to precede them with a \fB^V\fR. The \fB^V\fR echoes +as a \fB\(ua\fR character on which the cursor rests. This indicates that +the editor expects you to type a control character. In fact you may +type any character and it will be inserted into the file at that point.* +.FS +* This is not quite true. The implementation of the editor does +not allow the \s-2NULL\s0 (\fB^@\fR) character to appear in files. Also +the \s-2LF\s0 (linefeed or \fB^J\fR) character is used by the editor +to separate lines in the file, so it cannot appear in the middle of a +line. You can insert any other character, however, if you wait for the +editor to echo the \fB\(ua\fR before you type the character. In fact, +the editor will treat a following letter as a request for the corresponding +control character. This is the only way to type \fB^S\fR or \fB^Q\fP, +since the system normally uses them to suspend and resume output +and never gives them to the editor to process. +.FE +.PP +If you are using \fIautoindent\fR you can backtab over the indent which +it supplies by typing a \fB^D\fR. This backs up to a \fIshiftwidth\fR +boundary. +This only works immediately after the supplied \fIautoindent\fR. +.PP +When you are using \fIautoindent\fR you may wish to place a label at +the left margin of a line. The way to do this easily is to type \fB\(ua\fR +and then \fB^D\fR. The editor will move the cursor to the left margin +for one line, and restore the previous indent on the next. You can also +type a \fB0\fR followed immediately by a \fB^D\fR if you wish to kill +all the indent and not have it come back on the next line. +.NH 2 +Upper case only terminals +.PP +If your terminal has only upper case, you can still use +.I vi +by using the normal +system convention for typing on such a terminal. +Characters which you normally type are converted to lower case, and you +can type upper case letters by preceding them with a \e. +The characters { ~ } | \(ga are not available on such terminals, but you +can escape them as \e( \e\(ua \e) \e! \e\(aa. +These characters are represented on the display in the same way they +are typed.\*(dd +.FS +\*(dd The \e character you give will not echo until you type another +key. +.FE +.NH 2 +Vi and ex +.PP +.I Vi +is actually one mode of editing within the editor +.I ex. +When you are running +.I vi +you can escape to the line oriented editor of +.I ex +by giving the command +\fBQ\fR. +All of the +.B : +commands which were introduced above are available in +.I ex. +Likewise, most +.I ex +commands can be invoked from +.I vi +using :. +Just give them without the \fB:\fR and follow them with a \s-2CR\s0. +.PP +In rare instances, an internal error may occur in +.I vi. +In this case you will get a diagnostic and be left in the command mode of +.I ex. +You can then save your work and quit if you wish by giving a command +\fBx\fR after the \fB:\fR which \fIex\fR prompts you with, or you can +reenter \fIvi\fR by giving +.I ex +a +.I vi +command. +.PP +There are a number of things which you can do more easily in +.I ex +than in +.I vi. +Systematic changes in line oriented material are particularly easy. +You can read the advanced editing documents for the editor +.I ed +to find out a lot more about this style of editing. +Experienced +users often mix their use of +.I ex +command mode and +.I vi +command mode to speed the work they are doing. +.NH 2 +Open mode: vi on hardcopy terminals and ``glass tty's'' +\(dd +.PP +If you are on a hardcopy terminal or a terminal which does not have a cursor +which can move off the bottom line, you can still use the command set of +.I vi, +but in a different mode. +When you give a +.I vi +command, the editor will tell you that it is using +.I open +mode. +This name comes from the +.I open +command in +.I ex, +which is used to get into the same mode. +.PP +The only difference between +.I visual +mode +and +.I open +mode is the way in which the text is displayed. +.PP +In +.I open +mode the editor uses a single line window into the file, and moving backward +and forward in the file causes new lines to be displayed, always below the +current line. +Two commands of +.I vi +work differently in +.I open: +.B z +and +\fB^R\fR. +The +.B z +command does not take parameters, but rather draws a window of context around +the current line and then returns you to the current line. +.PP +If you are on a hardcopy terminal, +the +.B ^R +command will retype the current line. +On such terminals, the editor normally uses two lines to represent the +current line. +The first line is a copy of the line as you started to edit it, and you work +on the line below this line. +When you delete characters, the editor types a number of \e's to show +you the characters which are deleted. The editor also reprints the current +line soon after such changes so that you can see what the line looks +like again. +.PP +It is sometimes useful to use this mode on very slow terminals which +can support +.I vi +in the full screen mode. +You can do this by entering +.I ex +and using an +.I open +command. +.LP +.SH +Acknowledgements +.PP +Bruce Englar encouraged the early development of this display editor. +Peter Kessler helped bring sanity to version 2's command layout. +Bill Joy wrote versions 1 and 2.0 through 2.7, +and created the framework that users see in the present editor. +Mark Horton added macros and other features and made the +editor work on a large number of terminals and Unix systems. diff --git a/contrib/nvi/docs/USD.doc/vitut/vi.summary b/contrib/nvi/docs/USD.doc/vitut/vi.summary new file mode 100644 index 000000000000..8a09ce944407 --- /dev/null +++ b/contrib/nvi/docs/USD.doc/vitut/vi.summary @@ -0,0 +1,468 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)vi.summary 8.3 (Berkeley) 8/18/96 +.\" +.ds CH +.ds CF +.de TS +.br +.if !\\n(1T .RT +.ul 0 +.ti \\n(.iu +.if t .sp 0.25 +.if n .sp +.if \\$1H .TQ +.nr IX 1 +.. +.nr PS 9 +.ps 9 +.nr VS 11 +.vs 11 +.nr HM .50i +.nr FM .25i +.nr PO 1.0i +.po 1.0i +.nr LL 4.5i +.ll 4.5i +.de nc +.bp +.. +.de h +.LG +.B +\\$1 +.R +.NL +.. +.LG +.LG +.B +.ce +Ex Quick Reference +.R +.NL +.LP +.LP +.h "Entering/leaving ex" +.TS +aw(1.4i)b aw(1.8i). +% ex \fIname\fP edit \fIname\fP, start at end +% ex +\fIn\fP \fIname\fP ... at line \fIn\fP +% ex \-t \fItag\fP start at \fItag\fP +% ex \-r list saved files +% ex \-r \fIname\fP recover file \fIname\fP +% ex \fIname\fP ... edit first; rest via \fB:n\fP +% ex \-R \fIname\fP read only mode +: x exit, saving changes +: q! exit, discarding changes +.TE +.h "Ex states" +.TS +lw(1i) lw(2.0i). +Command T{ +Normal and initial state. Input prompted for by \fB:\fP. +Your kill character cancels partial command. +T} +Insert T{ +Entered by \fBa\fP \fBi\fP and \fBc\fP. +Arbitrary text then terminates with line having only \fB.\fP +character on it or abnormally with interrupt. +T} +Open/visual T{ +Entered by \fBopen\fP or \fBvi\fP, terminates with \fBQ\fP +or ^\e. +T} +.TE +.h "Ex commands" +.TS +lw(.45i) lw(.08i)b lw(.45i) lw(.08i)b lw(.45i) lw(.08i)b. +abbrev ab next n unabbrev una +append a number nu undo u +args ar open o unmap unm +change c preserve pre version ve +copy co print p visual vi +delete d put pu write w +edit e quit q xit x +file f read re yank ya +global g recover rec \fIwindow\fP z +insert i rewind rew \fIescape\fP ! +join j set se \fIlshift\fP < +list l shell sh \fIprint next\fP \fRCR\fP +map source so \fIresubst\fP & +mark ma stop st \fIrshift\fP > +move m substitute s \fIscroll\fP ^D +.TE +.h "Ex command addresses" +.TS +lw(.3i)b lw(0.8i) lw(.3i)b lw(0.8i). +\fIn\fP line \fIn\fP /\fIpat\fP next with \fIpat\fP +\&. current ?\fIpat\fP previous with \fIpat\fP +$ last \fIx\fP-\fIn\fP \fIn\fP before \fIx\fP ++ next \fIx\fP,\fIy\fP \fIx\fP through \fIy\fP +\- previous \(aa\fIx\fP marked with \fIx\fP ++\fIn\fP \fIn\fP forward \(aa\(aa previous context +% 1,$ +.TE +.nc +.h "Specifying terminal type" +.TS +aw(1.7i)b aw(1.5i). +% setenv TERM \fItype\fP \fIcsh\fP and all version 6 +$ TERM=\fItype\fP; export TERM \fIsh\fP in Version 7 +See also \fItset\fR(1) +.TE +.h "Some terminal types" +.TS +lw(.4i) lw(.4i) lw(.4i) lw(.4i) lw(.4i). +2621 43 adm31 dw1 h19 +2645 733 adm3a dw2 i100 +300s 745 c100 gt40 mime +33 act4 dm1520 gt42 owl +37 act5 dm2500 h1500 t1061 +4014 adm3 dm3025 h1510 vt52 +.TE +.h "Initializing options" +.TS +lw(.9i)b aw(1.5i). +EXINIT place \fBset\fP's here in environment var. +set \fIx\fP enable option +set no\fIx\fP disable option +set \fIx\fP=\fIval\fP give value \fIval\fP +set show changed options +set all show all options +set \fIx\fP? show value of option \fIx\fP +.TE +.h "Useful options" +.TS +lw(.9i)b lw(.3i) lw(1.0i). +autoindent ai supply indent +autowrite aw write before changing files +ignorecase ic in scanning +lisp \fB( ) { }\fP are s-exp's +list print ^I for tab, $ at end +magic \fB. [ *\fP special in patterns +number nu number lines +paragraphs para macro names which start ... +redraw simulate smart terminal +scroll command mode lines +sections sect macro names ... +shiftwidth sw for \fB< >\fP, and input \fB^D\fP +showmatch sm to \fB)\fP and \fB}\fP as typed +slowopen slow choke updates during insert +window visual mode lines +wrapscan ws around end of buffer? +wrapmargin wm automatic line splitting +.TE +.LP +.h "Scanning pattern formation" +.TS +aw(.9i)b aw(1.0i). +\(ua beginning of line +$ end of line +\fB.\fR any character +\e< beginning of word +\e> end of word +[\fIstr\fP] any char in \fIstr\fP +[\(ua\fIstr\fP] ... not in \fIstr\fP +[\fIx\-y\fP] ... between \fIx\fP and \fIy\fP +* any number of preceding +.TE +.nc +.LP +.LG +.LG +.B +.ce +Vi Quick Reference +.NL +.R +.LP +.LP +.h "Entering/leaving vi" +.TS +aw(1.4i)b aw(1.8i). +% vi \fIname\fP edit \fIname\fP at top +% vi +\fIn\fP \fIname\fP ... at line \fIn\fP +% vi + \fIname\fP ... at end +% vi \-r list saved files +% vi \-r \fIname\fP recover file \fIname\fP +% vi \fIname\fP ... edit first; rest via \fB:n\fP +% vi \-t \fItag\fP start at \fItag\fP +% vi +/\fIpat\fP \fIname\fP search for \fIpat\fP +% view \fIname\fP read only mode +ZZ exit from vi, saving changes +^Z stop vi for later resumption +.TE +.h "The display" +.TS +lw(.75i) lw(2.2i). +Last line T{ +Error messages, echoing input to \fB: / ?\fP and \fB!\fR, +feedback about i/o and large changes. +T} +@ lines On screen only, not in file. +~ lines Lines past end of file. +^\fIx\fP Control characters, ^? is delete. +tabs Expand to spaces, cursor at last. +.TE +.LP +.h "Vi states" +.TS +lw(.75i) lw(2.2i). +Command T{ +Normal and initial state. Others return here. +ESC (escape) cancels partial command. +T} +Insert T{ +Entered by \fBa i A I o O c C s S\fP \fBR\fP. +Arbitrary text then terminates with ESC character, +or abnormally with interrupt. +T} +Last line T{ +Reading input for \fB: / ?\fP or \fB!\fP; terminate +with ESC or CR to execute, interrupt to cancel. +T} +.TE +.h "Counts before vi commands" +.TS +lw(1.5i) lw(1.7i)b. +line/column number z G | +scroll amount ^D ^U +replicate insert a i A I +repeat effect \fRmost rest\fP +.TE +.h "Simple commands" +.TS +lw(1.5i)b lw(1.7i). +dw delete a word +de ... leaving punctuation +dd delete a line +3dd ... 3 lines +i\fItext\fP\fRESC\fP insert text \fIabc\fP +cw\fInew\fP\fRESC\fP change word to \fInew\fP +ea\fIs\fP\fRESC\fP pluralize word +xp transpose characters +.TE +.nc +.h "Interrupting, cancelling" +.TS +aw(0.75i)b aw(1.6i). +ESC end insert or incomplete cmd +^? (delete or rubout) interrupts +^L reprint screen if \fB^?\fR scrambles it +.TE +.h "File manipulation" +.TS +aw(0.75i)b aw(1.6i). +:w write back changes +:wq write and quit +:q quit +:q! quit, discard changes +:e \fIname\fP edit file \fIname\fP +:e! reedit, discard changes +:e + \fIname\fP edit, starting at end +:e +\fIn\fR edit starting at line \fIn\fR +:e # edit alternate file +^\(ua synonym for \fB:e #\fP +:w \fIname\fP write file \fIname\fP +:w! \fIname\fP overwrite file \fIname\fP +:sh run shell, then return +:!\fIcmd\fP run \fIcmd\fR, then return +:n edit next file in arglist +:n \fIargs\fP specify new arglist +:f show current file and line +^G synonym for \fB:f\fP +:ta \fItag\fP to tag file entry \fItag\fP +^] \fB:ta\fP, following word is \fItag\fP +.TE +.h "Positioning within file" +.TS +aw(0.75i)b aw(1.6i). +^F forward screenfull +^B backward screenfull +^D scroll down half screen +^U scroll up half screen +G goto line (end default) +/\fIpat\fR next line matching \fIpat\fR +?\fIpat\fR prev line matching \fIpat\fR +n repeat last \fB/\fR or \fB?\fR +N reverse last \fB/\fR or \fB?\fR +/\fIpat\fP/+\fIn\fP n'th line after \fIpat\fR +?\fIpat\fP?\-\fIn\fP n'th line before \fIpat\fR +]] next section/function +[[ previous section/function +% find matching \fB( ) {\fP or \fB}\fP +.TE +.h "Adjusting the screen" +.TS +aw(0.75i)b aw(1.6i). +^L clear and redraw +^R retype, eliminate @ lines +z\fRCR\fP redraw, current at window top +z\- ... at bottom +z\|. ... at center +/\fIpat\fP/z\- \fIpat\fP line at bottom +z\fIn\fP\|. use \fIn\fP line window +^E scroll window down 1 line +^Y scroll window up 1 line +.TE +.nc +.h "Marking and returning +.TS +aw(0.5i)b aw(2.0i). +\(ga\(ga previous context +\(aa\(aa ... at first non-white in line +m\fIx\fP mark position with letter \fIx\fP +\(ga\fIx\fP to mark \fIx\fP +\(aa\fIx\fP ... at first non-white in line +.TE +.h "Line positioning" +.TS +aw(0.5i)b aw(2.0i). +H home window line +L last window line +M middle window line ++ next line, at first non-white +\- previous line, at first non-white +\fRCR\fP return, same as + +\(da \fRor\fP j next line, same column +\(ua \fRor\fP k previous line, same column +.TE +.h "Character positioning" +.TS +aw(0.5i)b aw(2.0i). +\(ua first non white +0 beginning of line +$ end of line +h \fRor\fP \(-> forward +l \fRor\fP \(<- backwards +^H same as \fB\(<-\fP +\fRspace\fP same as \fB\(->\fP +f\fIx\fP find \fIx\fP forward +F\fIx\fP \fBf\fR backward +t\fIx\fP upto \fIx\fP forward +T\fIx\fP back upto \fIx\fP +; repeat last \fBf F t\fP or \fBT\fP +, inverse of \fB;\fP +| to specified column +% find matching \fB( { )\fP or \fB}\fR +.TE +.h "Words, sentences, paragraphs" +.TS +aw(0.5i)b aw(2.0i). +w word forward +b back word +e end of word +) to next sentence +} to next paragraph +( back sentence +{ back paragraph +W blank delimited word +B back \fBW\fP +E to end of \fBW\fP +.TE +.h "Commands for \s-2LISP\s0" +.TS +aw(0.5i)b aw(2.0i). +) Forward s-expression +} ... but don't stop at atoms +( Back s-expression +{ ... but don't stop at atoms +.TE +.nc +.h "Corrections during insert" +.TS +aw(.5i)b aw(2.0i). +^H erase last character +^W erases last word +\fRerase\fP your erase, same as \fB^H\fP +\fRkill\fP your kill, erase input this line +\e escapes \fB^H\fR, your erase and kill +\fRESC\fP ends insertion, back to command +^? interrupt, terminates insert +^D backtab over \fIautoindent\fP +\(ua^D kill \fIautoindent\fP, save for next +0^D ... but at margin next also +^V quote non-printing character +.TE +.h "Insert and replace" +.TS +aw(.5i)b aw(2.0i). +a append after cursor +i insert before +A append at end of line +I insert before first non-blank +o open line below +O open above +r\fIx\fP replace single char with \fIx\fP +R replace characters +.TE +.h "Operators (double to affect lines)" +.TS +aw(0.5i)b aw(2.0i). +d delete +c change +< left shift +> right shift +! filter through command +\&= indent for \s-2LISP\s0 +y yank lines to buffer +.TE +.h "Miscellaneous operations" +.TS +aw(0.5i)b aw(2.0i). +C change rest of line +D delete rest of line +s substitute chars +S substitute lines +J join lines +x delete characters +X ... before cursor +Y yank lines +.TE +.h "Yank and put" +.TS +aw(0.5i)b aw(2.0i). +p put back lines +P put before +"\fIx\fPp put from buffer \fIx\fP +"\fIx\fPy yank to buffer \fIx\fP +"\fIx\fPd delete into buffer \fIx\fP +.TE +.h "Undo, redo, retrieve" +.TS +aw(0.5i)b aw(2.0i). +u undo last change +U restore current line +\fB.\fP repeat last change +"\fId\fP\|p retrieve \fId\fP'th last delete +.TE diff --git a/contrib/nvi/docs/changelog b/contrib/nvi/docs/changelog new file mode 100644 index 000000000000..1f2a8c67b478 --- /dev/null +++ b/contrib/nvi/docs/changelog @@ -0,0 +1,1102 @@ +1.78 -> 1.79 (10/23/96) + + Rename delete() to del(), for C++. + + Add Spanish to the list of translations. + + Update to Perl 5.003_06, and other Perl interpreter updates. + + Update the set-edit-option interface for the scripting languages. + + Rework ex command parsing to match historic practice for backslash + escaped <newline> characters inside of global commands. + + Enhance the comment edit option to skip C++ comments. + + Change installation to configure the recovery shell script to match + the system pathnames and to install it into the vi data directory. + Move the recover script into the build directory, and delete the + recover directory. + + Enhance LynxOS support. +1.76 -> 1.78 (10/01/96) + + Fix bugs when both the leftright scrolling and number edit options + were on. + + Fix bug where splitting in the middle of the screen could repaint + incorrectly. + + Fix first-nul in input bug, where random garbage was inserted. + + Correct search and mark-as-motion-command bug, it's a line mode + action if the search starts at or before the first non<blank>. + + Fix bug autoindent bug, where ^D could shift too far in the line. + + Fix core dump where ! command called from the .exrc file. + + Add the -S command-line option, which initializes vi to have the + secure edit option preset. +1.75 -> 1.76 (09/15/96) + + Fix bug where ^V didn't keep input mapping from happening. + + Fix a core dump bug in the R command. + + Give up on licensing: no more shareware, adware, whatever. + + Fix cursor positioning bug for C, S and c$ in an empty file. +1.74 -> 1.75 (08/22/96) + + Add French to the error message translations. + + Move the UNLICENSED message to the end of the message line. + + Fix bug where wide characters in a file name weren't calculated + correctly in the status message. + + Fix bug where cl_rename was called directly, by the ex shell code. + + Fix bug where splitting a screen resulting in a new screen at the + top of the display resulted in badly displayed status messages. +1.73 -> 1.74 (08/18/96) + + Fix bug where the status line wasn't redisplayed if the user ran + an ex command that trashed the screen. + + Fix bug where the long version of the status line wasn't displayed + when switching screens. + + Rework fast-path filename completion code to sort the entries, and + strip out . and .. by default. + + Fix bug where ex went to the first line instead of the last one when + reading in a file. +1.72 -> 1.73 (08/12/96) + + Do filename completion and some file expansion internally for speed. + + Fix CSCOPE_DIRS environmental variable support. + + Ex parser fix for global commands in script files. + + Add the O_PATH option, so you can specify a directory search path + for files. + + Make it possible to specify the database file to cscope, allowing + multiple databases in a single directory. + + Fix incremental search to overwrite erased characters so the user + can tell where they are on the colon-command line. + + Fix incremental search to restart the search if the user enters an + unescaped shell meta character. +1.71 -> 1.72 (07/12/96) + + Cscope fix: test for files newer than the database was reversed. + + Display "files to edit" message for rewind, next and initial screen. + + Fix a bug in the R command where it could fail if the user extended + the file. + + Fix a bug where text abbreviations could corrupt the line. + + Fix a bug where the windowname edit option couldn't be set before a + file was loaded into the edit buffer. + + Fix a bug where the system .exrc values weren't being overridden by + the user's $HOME .exrc values. + + Fix a bug in the filename completion code, where garbage characters + could be added to the colon command line. + + Fix bug where multiple edit sessions on a non-existent file could + all write the file without warning. + + Fix bug where screen update was incorrect if a character triggered + both a wrapmargin and showmatch condition. + + Fix bug in leftright scrolling where <CR> during text input didn't + return the cursor to the left margin. + + Rev the Perl interpreter code, new version from Sven Verdoolaege, + based on Perl 5.003.01. + + Fix bug in tags file pattern search introduced in 1.71. +1.70 -> 1.71 (07/01/96) + + Don't include <term.h> -- neither HPUX or Solaris can cope with it. + + Fix bug where ^M's in the original pattern were converted into new + lines in the file during substitution commands. + + Make window resize events separate from interrupts -- too many users + complained. + + Fix bug in first-character-is-null text input semantic. + + Rework search routines to take a length instead of a nul-terminated + string for a pattern. This fixes a couple of bugs in searching, but + probably introduces new ones. + + Fix prompting the user after a write filter command, the way I did + it in 1.70 broke the display. + + Don't switch to the alternate xterm screen when entering the ex + text input commands from vi mode. + + Implement the Fg command, so can foreground a background screen into + a split screen. + + Change the fg command to match screen names using the last component + of the filename the full filename fails. +1.69 -> 1.70 (06/28/96) + + Change the ex read command to support named pipes. + + Copy the EXINIT/NEXINIT strings before executing their commands so + we don't step on the process environment. + + Don't do "line modification" reports for intermediate commands + executed from the vi colon command line, it screws up filter + reads, causing nvi to prompt for the user to continue. + + Add "smd" as an abbreviation for showmode: HP, ICL and SCO have it. + + Change nvi to always prompt the user after a write filter command. + This matches historic practice. + + Fix recovery information mailed to the user to reflect the program's + installed name. + + Change configuration script to not cache option information, e.g., + --disable-curses. + + Fix a bug where the second character of the vi [[, ]] and ZZ + commands could start a command mapped sequence. + + Fix 3 write bugs: partial writes (3,$write), were clearing the + modified flag, full writes using line numbers (1,$write) were + not, and append historically never cleared the modified flag, and + we didn't get that right. + + Shorten the "more files to edit" message so it can gang on a single + line, lots of people have complained. Add the number of files that + are left to edit, it's historic practice. + + Fix core dump where message catalogs collided with truncating the + write path. Add a new write message so the string "appended" is + taken from a message catalog. + + Fix bug where an undo followed by '.' to repeat it wouldn't work + if no other repeatable commands had been entered. + + Fix core dump when resolution of input lines' autoindent characters + invalidated cached display information. + + Set the name of the X11 xterm icon/window to "xterm" when exiting, + if modified based on the windowname option. + + Include <term.h> if it exists, fixes portability problems on IRIX + systems. +1.68 -> 1.69 (06/17/96) + + Add the windowname edit option and code to change the icon/window + name for xterm's. + + Enhance the comment edit option to skip shell comments. + + Add conditional prototypes to replacement C library functions. + + Minor enhancements/reworking to Makefile.in, other build files. + + Fix bug in vi text input ^D processing, could result in cursor + warp to the beginning of the line. + + Fix leftright screen bug where the screen wasn't repainted when + being repainted from scratch. + + Update the Swedish and Dutch catalogs. + + Truncate paths in write commands if they don't fit on one line. + + Fix alternate screen bug where the screen flashed and output lost + when switching to/from the X11 xterm alternate screen. Fix bug + where nvi switched into the alternate screen during filter-read + commands, which doesn't match historic practice. + + Minor relative cursor positioning change, make cursor position + changes from ex real and permanent. +1.67 -> 1.68 (06/09/96) + + Fix core dump when tagging out of a modified file. +1.66 -> 1.67 (06/09/96) + + Convert the license to adware. + + Leftright scrolling tweak, don't repaint the screen as often. + + Change so that search warning/error messages don't appear during an + incremental search. + + Cscope fix: test for files newer than the database was reversed. + + Don't display ex `welcome message' if in ex batch mode. + + Test for vsnprintf and snprintf separately, HP 10.10 has snprintf + but not vsnprintf. + + Reverse lookup order between LC_MESSAGES and LANG. + + Fix Tcl/Perl core dumps in common API code to get/set options. + + Fix R command -- it used a DB pinned page after discarding it. + + Minor fixes in multiple edit buffer message handling code. + + Fix yk command moving to shorter line core dump. + + Rework message handling to try and gang more messages onto a single + line. +1.65 -> 1.66 (05/18/96) + + Convert vi man page to historic -man macro package, and install it. + + Fix bug were !! on an empty line with a nonexistent command left the + cursor on the second character, not the first. + + Fix bug where line redisplay was wrong when a <tab> replaced a + previous <tab> in the line. + + Fix bug where D (d$) didn't reset the relative cursor position. + + Fix bug where yG incorrectly reset the relative cursor position. + + Fix bug where the window size couldn't be grown once it was shrunk. + + Fix bug where the extended edit option caused tag searches to fail. + + If multiple lines in the tags file with the same leading tag, build + a tags stack like the Cscope stack. This is the obvious extension, + and the way that Larry McVoy's ctags program works. + + Send the appropriate TI/TE sequence in the curses screen whenever + entering ex/vi mode. This means that :shell now shows the correct + screen when using xterm alternate screens. + + Rework the options display code to get five columns in an 80 column + screen. + + Interactive Unix V3.0 port -- mostly file name shortening, other + minor changes. Only preliminary, more work will be necessary. + + Add debugging option to not read EXINIT/.exrc information. + + Fix bug where re_compile printed an error message to the screen + when the user entered [ to an incremental search. + + Turn off screen beeps when incremental search is failing. + + Fix bug where the iclower option didn't trigger an RE recompilation. + + Fix bug where -t into an already locked file forced the user to wait + as if a startup command had failed. + + LynxOS port -- mostly adding <sys/types.h> even though <sys/param.h> + was already included. + + Fix ex output bug, where it appeared as if an ex command was skipped + due to flags not being cleared in the vs_msg() routine. + + Fix core dump when global command tried to switch screens. +1.64 -> 1.65 (05/13/96) + + Fix cscope <blank>-matching pattern to use extended RE's, and bug + that kept cscope from finding patterns containing <blank>s. + + Fix core dumps in both leftright and folded screens when tabstops + edit option value was large, and tab characters occurred as the last + character in the logical screen. + + Fix core dump where the second screen of a folded line wasn't + displayed correctly. + + Fix incremental search to match the current location for strings + starting with \< patterns. + + Fix bug where margins were ignored during replay of text input. + + Fix bug where motion components to shorter lines could lose because + the relative motion flags weren't ever set. This has been broken + forever, but the change almost certainly breaks something else -- I + have no idea what. + + Tags display: don't print the current entry separately, display + them all and add a trailing asterisk for the current one. + + Change the cscope add command to put the directory name through + standard file name expansion. + + Fix cscope use of buffers -- search commands weren't nul-terminated. +1.63 -> 1.64 (05/08/96) + + Add installation target to the Makefile. + + Add documentation on the new tags commands to the Vi Reference + Manual. + + Make the sidescroll edit option work again. + + Fix bug where messages output during startup by ex could be lost. + + Change ex/vi commands errors into beeps, unless the verbose edit + option is set -- there are too many macros that are expected to + eventually fail. This matches historic practice. + + Truncate paths in initial vi screen if they won't fit on one line. + + Make cursor position after filter write match historic practice. + + Force the user to wait if there is output and the user is leaving + the screen for any reason -- don't permit further ex commands. + + Don't use a <newline> character to scroll the screen when exiting, + scroll in the vi screen before endwin() is called. + + Fix bug where the column number could be incorrect because the old + screen wasn't updated after a screen split. + + Fix ex print routine to correctly specify print flags. + + Make -g/-O a separate make/configuration option. + + Fix bug where ex/vi messages weren't being joined. + + Fix bug where termcap strings were free'd twice. + + Fix bug where TI/TE still weren't working -- I didn't put in the + translation strings for BSD style curses. + + Fix bug where I misspelled the iclower edit option as icloser. +1.62 -> 1.63 (04/29/96) + + Robustness and type/lint fixes for the Tcl interface code. + + Fix core dump if TERM wasn't set or terminal type was unknown. + + Fix bug where combining ex commands that did/did not require an + ex screen would overwrite the command with the want-to-continue + messsage. + + Fix bug where the screen was never resolved if the user continued + entering ex commands using the : character, but then backspaced + over the prompt to quit or tried to edit their colon command-line + history. + + Fix bug where cursor wasn't placed over the ^ placeholder character + when quoting using the literal-next character. + + Fix bug where nvi under BSD style curses wasn't sending TI/TE termcap + strings when suspending the process. + + Rename mic again, to iclower. + + Fix bug where 'z' commands trailing / or ? commands weren't being + executed. + + Change incremental search to leave the cursor at its last position + when searching for something that was never found. + + Fix bug where search-with-confirmation from vi mode didn't position + the cursor correctly after displaying the confirm message. + + Fix bug where the "search wrapped" message was dependent on the + verbose edit option, which doesn't match historic practice. Change + search messages to be in inverse video. + + Fix bug where matched showmatch character wasn't being displayed + before the matching character was displayed. + + Another cursor update bug required a change to vs_paint(). + + Fix bug were initial line offset was wrong for the first split screen + (symptom is very strange column numbers and blank first line). + + Create filename "argument" lists when creating new screens. + + Fix bug where globals with associated commands that included both + buffer execution and other commands could fail to execute the latter. +1.61 -> 1.62 (04/22/96) + + Rename the "searchci" edit option to be "mic". + + Fix memory corruption in global commands ending in searches. + + Fix text resolution bug, corrected the cursor based on the + first line input, not the last. + + Rework the readonly edit option to match historic practice. + + Fix several minor incremental search bugs; make incremental + searches work in maps. + + Fix long-line core dump, where an incorrect screen map could be + used. +1.60 -> 1.61 (04/12/96) + + The cursor now ends up on the FIRST character of the put text for + all versions of the vi put commands, regardless of the source + of the text. This matches System III/V behavior and POSIX 1003.2. + + Fixed bug where showmatch messages were getting discarded. + + Minor Perl integration fixes. + + Integrate Cscope into the tags stack code -- major change. + + Fixed bug where ^T would drop core if returning to a temporary file. + + Changed vs_ routine to display ex output to replace tab characters + with spaces. + + Fix autoindent code to not back up past beginning of line when ^T + inserted into the middle of a line, i.e. offset != 0. + + Fix "notimeout" option, was being ignored, by a coding error. + + Fix showmatch code to never flash on a match if keys are waiting. + + Change the vi 'D' command to ignore any supplied count, matching + historic practice. + + Fix viusage for D, S, C and Y (the aliased vi commands). + + Fix the Perl5 configuration bug in the configuration script. + + Make file completion commands in empty lines work. + + Fix where the change to let vi use the default ex command structure + broke the ex specification of the script or source file name. + + Fix to free saved RE structures when screens exit. This is a major + RE change, which fixed several bugs in the handling of saved/subst + RE's. It's likely to have added new bugs, however. + + Add case-independent searching (the searchci edit option). + + Add incremental search (the searchincr edit option). + + Home the cursor when executing ex commands from vi. +1.59 -> 1.60 (03/29/96) + + Fix ":w >>" core dump, make that command match historic practice. + + Fix autoindent bug where the length of the line was incorrectly + calculated. + + Fix cursor bug where cursor could end up at the wrong place if the + movement keys were entered quickly enough. + + Change the read/write whirling indicator to appear only every 1/4 + second, clean up the appearance. + + Don't change the options real values until underlying functions + have returned OK -- fix "set tabstop=0" core dump. + + Fix resizing on Sun's: use SA_INTERRUPT to interrupt read calls. + + Fix two forward mark command bugs: one where it wasn't setting the + "favorite cursor" position because of the refresh optimization, + and one where it didn't have VM_RCM_SET set in the command flags + for some reason. + + Fix a bug were the 's' command on top of a <tab> didn't correctly + copy the buffer. + + Make :exusage command work for commands having optional leading + capital letters, e.g. Next. + + Previous changes broke the inital-matching-prefix code in the key + mapping part of v_event_get -- fix it, and fix the infinite macro + interrupt code at the same time. + + Add "cedit" edit option, so colon command-line editing is optional. + Change filec/cedit so that you can set them to the same character, + and they do cedit if in column 1, and filec otherwise. + + Fix "source of non-existent file" core dump. + + Fix bug where functions keys specified in startup information were + never resolved/activated. + + Fix v_txt bug where could infinitely loop if <escape> triggered an + abbreviation expansion. + + Move version string into VERSION file, out of ex_version.c +1.58 -> 1.59 + + Configuration changes, several minor bug fixes, including a few + core dumps. No functional changes. +1.57 -> 1.58 + + Fix the problem where colon command-line temporary files were + getting left in /tmp. + + Fix the configuration scripts to quit immediately if the Perl + or Tk/Tcl libraries are specified but not found. + + Several screen fixes -- the changes in 1.57 weren't as safe as + I thought. More specifically, the refresh-only-if-waiting change + caused a lot of problems. In general, fixing them should provide + even more speedup, but I'm nervous. + + Lots of changes in the configuration scripts, hopefully this is + just a first-round ordeal. + + Several other minor bug fixes. +1.56 -> 1.57 + + Add <esc> hook to colon commands, so you can edit colon commands. + + Add Perl5 interpreter. + + Change shell expansion code to fail if it doesn't read at least + one non-blank character from the shell. If the shell expansion + process fails, or if not at least one non-blank character, it + now displays an error message to the user. + + Rework the screen display so that it matches the historic vi screen + refreshes. + + Rework options processing: print/noprint are no longer cumulative, + provide more information to underlying edit options modules, move + O_MESG information into the screen specific code. + + Make file completion character settable. + + Rework terminal restart -- you can now use ":set term" to switch + terminal types. This cleaned up screen resizing considerably. + + Character display fix, display \177 as ^?, not in hex/octal. + + Tag search bug fix, don't repeat search if successful. + + Replace sys_siglist[] use with private sigmsg() routine. + + Fix core dump if illegal screenId specified to Tcl routine. + + Add get/set mark interface to Tcl Interpreter interface. + + Fix core dump if file expansion code stressed (re: filec edit option) + + Fix bug where filter commands in empty files couldn't find line 0. + + Switch to GNU autoconf 2.7 for configuration, delete nvi/PORT. + Many random portability fixes. +1.55 -> 1.56 (11/26/95) + + Bug fix release -- generally available beta release. +1.54 -> 1.55 (11/18/95) + + Bug fix release. + + Integrate Tcl interpreter. +1.53 -> 1.54 (11/11/95) + + Bug fix release. A major change in reworking the ex commands, when + called from the colon command line, to match historic practice, and + permit them to be entered repeatedly after ex has trashed the screen. + + Use restartable endwin() from System V curses to implement screen + + suspend. +1.52 -> 1.53 (10/29/95) + + Switch to using vendor's curses library for all ports. + + Back out the event driven version, leaving screen separation. + + User configuration of <escape> timeout (the escapetime edit option). + + Add Tcl/Tk screen support. + + Add file name completion (the filec edit option). + + Disallow access to outside applications (the secure edit option). +1.51 -> 1.52 (7/26/95) + + Minor cleanups, snapshotted for SMI. +1.50 -> 1.51 (7/05/95) + + Lots and lots of changes for event driven model, largely in moving + the boundary between the screen code and the editor up and down. + Private release for Rob Zimmermann @ Tartan and Bill Shannon @ SMI. +1.49 -> 1.50 Fri Jun 9 13:56:17 1995 + + Minor bug fixes for stability. + + Convert to an event driven model, with the usual Nachos Supreme + layering that results. This is a completely new version, nothing + done previously matters any more. +1.48 -> 1.49 Wed Mar 8 10:42:17 1995 + + Changes in 1.46 broke ^A processing. + + Add :previous to split screen commands. + + Lots o' random bug fixes -- passes purify testing again. +1.47 -> 1.48 Thu Feb 9 18:13:29 1995 + + Random bug fixes for 1.47. + + Move the FREF (file structure) list out of the screen and into + the global area. + + Change semantics to :E to more closely match :e -- ":E" joins + the current file, so ":E /tmp" is now the command to match the + historic ":split". +1.46 -> 1.47 Wed Feb 8 19:43:41 1995 + + All ex commands (including visual and excluding global and v) + are now supported inside ex global commands. + + Rework the append/change/insert commands to match historic + practice for text appended to the ex command line, and inside + of ex global commands. + + Restructure to make single-line screens work. + + Restructure to create curses independent screen routines. + + Restructure to permit Edit, Next, and Tag routines to create new + screens on the fly. + + Change hexadecimal output to be \x## instead of 0x##. + + Change ex commands run from vi to stay in vi mode for as long as + possible, i.e. until ex modifies the screen outside of the editor. +1.45 -> 1.46 Tue Jan 24 10:22:27 1995 + + Restructure to build as a library. +1.44 -> 1.45 Thu Jan 12 21:33:06 1995 + + Fix relative cursor motion to handle folded lines. + + Recompile the search pattern if applicable edit options change. + + Change +/-c command ordering to match historic practice. + + Rework autoindent code to always resolve preceeding <blank> + characters when a ^T or ^D are entered. + + Add the print/noprint edit options, so can now specify if + a character is printable. + + Change ex to run in canonical mode. + + Fix ex text input to support the number edit option. + + Vi text input fix for the R command to correctly restore + characters entered and then backspaced over. + + Several vi increment command fixes. +1.43 -> 1.44 + + Bug fix, vi was printing the last line number on the status line + at startup. Change to execute commands at first line set, i.e. + "vi -t tag -c cmd" executes cmd at the tag line, not EOF. +1.42 -> 1.43 Sat Dec 3 13:11:32 1994 + + Marks, SunOS signed comparison fix for 1.42. +1.41 -> 1.42 Fri Dec 2 20:08:16 1994 + + Make autowrite require the file not be read-only. + + Make the ex insert command work in empty files. + + Tab expansion is no longer limited to values < 20 (which matches + historical practice). + + Simplify (and fix limit detection for) the # command. It's no + longer possible to use the # command itself to repeat or modify + a previous # command, '.' is the only possibility. + + Lots more reworking of the ex addresses, putting ? and / into + the ex addressing code broke the world. + + Make the Put, Preserve and Print commands work (don't ask). + + Split stdout/stderr from shell expansions; stdout is expansion + text, stderr is entered on the message queue. +1.40 -> 1.41 Fri Nov 18 16:13:52 1994 + + Addition of a port for AUX 3.1 + + Addition of a message catalog for Russian. + + Make vi ? and / commands be true ex addresses (historic practice). + + Display the date first in vi -r recovery list. +1.39 -> 1.40 Mon Nov 14 10:46:56 1994 + + Two bug fixes for 1.39; -r option and v_change core dump. +1.38 -> 1.39 Sun Nov 13 18:04:08 1994 + + Ex substitution with confirmation now matches historic practice + (except that it still runs in raw mode, not cooked). + + Nvi now clears the screen before painting, if repainting the + entire screen. + + Fix final cursor position for put command entering text in a + single line. + + Change to break error message lines on the last <blank> in the + line. + + Always center the current line when returning to a previously + edited file or moving to a tag line that's not visible on the + screen. + + Change write of the current file using an explicit name or % to + match the semantics of :w<CR>, not :w file<CR>. + + Add command aliases to vi, and remap 6 historic commands to their + historic counterparts: D->d$, Y->y_, S->c_, C->c$, A->$a, I->^i. + + Match option display to historic practice; if boolean or numeric + options changed to default values, not displayed by default. + Nvi treats string options the same way, vi always displayed any + string option that was changed. + + Added lock edit option, if not set, no file locking is done. + + Rework ex to permit any ex command in the EXINIT variable or + exrc startup files. This fixes the bug were `vi +100 file' + painted the screen and then moved to line 100 and repainted. + (Yanked to SCCS ID 9.1.) + + Bug fix: could report file modified more recently than it was + written, incorrectly. + + Search fix: historically, motions with deltas were not corrected + to the previous/next line based on the starting/stopping column. + + Addressing fixes: make trailing non-existent addresses work, change + % to be text substitution, not a unique address (to follow future + POSIX). +1.37 -> 1.38 Mon Oct 24 12:51:58 1994 + + Scrolling fix; ^B can move to nonexistent lines. + + Fix to vi mapped commands; <escape> characters while already in + command mode did not historically cause the mapped characters to + be flushed. + + Add the backup edit option, automatically version edit files. + + Make it possible to edit files that db can't read, i.e. edit a + temporary file, with the correct file name. + + Only anchor the last line of the file to the bottom line of the + screen if there's half or less of a screen between the target + line and the end of the file. + + Fix wrapmargin text allocation bug. + + Fix ex put command to work in any empty file. + + Fix global command to handle move's to line 0 correctly. + + Regularize the yank cursor motions, several bug fixes for historic + practice. + + Fix N and n, when used as a motion command for the ! command, + repeat the last bang command instead of prompting for a new + one. + + Timeout maps beginning with <escape> quickly, instead of based + on the keytime option. + + Bug fix for wraplen option, wasn't triggered for input commands. +1.36 -> 1.37 Sun Oct 9 19:02:53 1994 + + Change PORT directories to install patches before distribution. + + Fix ^A to set search direction and pattern for consistency. + + Fold the showdirty option into the showmode option. + + Ex addressing fix: change search offset and line arguments (e.g. + the copy command) to be ex addressing offsets, matching historic + practice. + + Ex addressing fix: support ^ as an offset/flag equivalent to -. + + Ex addressing fix: historically, any missing address defaulted to + dot, e.g. "4,,," was the same as ".,.". + + Ex addressing fix: historically, <blank> separated numbers were + additive, e.g. "3 5p" displayed line 8. + + Ex addressing fix: make ';' as a range delimiter match historic + practice. + + Change nvi to exit immediately if stdout isn't a terminal. + + Change alternate file name behavior to match historic practice, + make the :write command set the current file name. + + Text input fix; input keys from a map, with an associated count, + weren't historically affected by the wrapmargin value. + + Add wraplen option, same as wrapmargin, but from the left-hand + column, not the right. + + Make ex address .<number> be equivalent to .+<number>, i.e. the + '+' is understood; matches historic practice, and it's widely + documented for ed(1). + + Input mode ^V^J historically mapped into a single ^J. + + Minor catalog changes, fixes; don't use 's' to pluralize words. +1.35 -> 1.36 Thu Sep 8 08:40:25 1994 + + Don't overwrite user's maps with standard (termcap) mappings. + + Make \ escape kill and erase characters in vi text input mode. + + Fix ^D autoindent bug by resolving leading <blank>s at ^D. + + Rework abbreviation tests (again!) to match historic practice. + + Change ^D/^U default scrolling value to be based on window option + value, not screen lines, correct scrolling option value, both to + match historic practice. NOTE: System V does this differently! +1.34 -> 1.35 Wed Aug 31 19:20:15 1994 + + Add the historic -l option. + + Message catalogs. + + Display global messages at each flush, just in case some are there. + + Fix global substitute code, `\\' wasn't handled correctly. + + Fix abbreviation code to use <blank>s as the preceding character. + + Fix ruler to display logical column, not physical column. + + Block signals when user issues :preserve command, so no race caused + by SIGHUP/SIGTERM. +1.33 -> 1.34 Wed Aug 17 14:37:32 1994 (PUBLICLY AVAILABLE VERSION) + + Back out sccsid string fix, it won't work on SunOS 4.1. +1.32 -> 1.33 Wed Aug 17 09:31:41 1994 (PUBLICLY AVAILABLE VERSION) + + Get back 5K of data space for the sccsid strings. + + Fix bug where cG fix in version 1.31 broke cw cursor positioning + when the change command extended the line. + + Fix core dump in map/seq code if character larger than 7 bits. + + Block signals when manipulating the SCR chains. + + Fix memory allocation for machines with multiple pointer sizes. +1.31 -> 1.32 Mon Aug 15 14:27:49 1994 + + Turn off recno mmap call for Solaris 2.4/SunOS 5.4. +1.30 -> 1.31 Sun Aug 14 13:13:35 1994 + + Fix bug were cG on the last line of a file wasn't done in line mode, + and where the cursor wasn't positioned correctly after exiting text + insert mode. + + Add termcap workaround to make function keys greater than 9 work + correctly (or fail if old-style termcap support). + + Change ex/vi to not flush mapped keys on error -- this is historic + practice, and people depended on it. + + Rework vi parser so that no command including a mapped key ever + becomes the '.' command, matching historic practice. + + Make <escape> cancellation in the vi parser match POSIX 1003.2. + + Fix curses bug where standout string was written for each standout + character, and where standout mode was never exited explicitly. + Fix bugs in curses SF/sf and SR/sr scrolling, as seen on Sun and + x86 consoles. + + The v/global commands execute the print command by default. + + The number option historically applies to ex as well as vi. +1.29 -> 1.30 Mon Aug 8 10:30:42 1994 + + Make first read into a temporary set the file's name. + + Permit any key to continue scrolling or ex commands -- this + allows stacked colon commands, and matches historic practice. + + Don't output normal ! command commentary in ex silent mode. + + Allow +/- flags after substitute commands, make line (flag) + offsets from vi mode match historic practice. + + Return <eof> to ex immediately, even if preceded by spaces. Rework + ex parser to do erase the prompt instead of depending on the print + routines to do it. Minor fixes to the ex parser for display of + default and scrolling commands. MORE EX PARSER CHANGES. +1.28 -> 1.29 Fri Aug 5 10:18:07 1994 + + Make the abbreviated ex delete command work (:dele---###lll for + example, is historically legal. + + When autoprint fires, multiple flags may be set, use ex_print + directly instead of the stub routines. + + Change v/global commands to turn off autoprint while running. + + Minor changes to make the ! command display match historic output. + + Rework the ex parser to permit multiple command separators without + commands -- MAJOR CHANGE, likely to introduce all sorts of new bugs. + + Fix cd command to expand argument in the context of each element + of the cdpath option, make relative paths always relative to the + current directory. + + Rework write/quit cases for temporary files, so that user's don't + discard them accidentally. + + Check for window size changes when continuing after a suspend. + + Fix memory problem in svi_screen, used free'd memory. + + Change the ex change, insert, append commands to match historic + cursor positions if no data entered by the user. + + Change ex format flags (#, l, p) to affect future commands, not + just the current one, to match historic practice. + + Make the user's EOF character an additional scroll character in ex. + + Fix ex ^D scrolling to be the value of the scroll option, not half + the screen. + + Fix buffer execution to match historic practice -- bugs where the + '*' command didn't work, and @<carriage-return> didn't work. + + Fix doubled reporting of deleted lines in filters. + + Rework the % ` / ? ( ) N n { and ^A commands to always cut into + numeric buffers regardless of the location or length of the cut. + This matches historic practice. + + Fix the { command to check the current line if the cursor doesn't + start on the first character of the line. + + Do '!' expansion in the ex read command arguments, it's historic + practice. In addition, it sets the last '!' command. +1.27 -> 1.28 Wed Jul 27 21:29:18 1994 + + Add support for scrolling using the CS and SF/sf/SR/sr termcap + strings to the 4BSD curses. + + Rework of getkey() introduced a bug where command interrupt put + nvi into an infinite loop. + + Piping through a filter historically cut the replaced lines into + the default buffer, although not the numeric ones. + + Read of a filter and !! historically moved to the first nonblank + of the resulting cursor line (most of the time). + + Rework cursor motion flags, to support '!' as a motion command. +1.26 -> 1.27 Tue Jul 26 10:27:58 1994 + + Add the meta option, to specify characters the shell will expand. + + Fix the read command to match historic practice, the white space + and bang characters weren't getting parsed correctly. + + Change SIGALRM handler to save and restore errno. + + Change SunOS include/compat.h to include <vfork.h> so that the + ex/filter.c code works again. + + Don't put lines deleted by the ex delete command into the numeric + buffers, matching historic practice. + + Fix; if appending to a buffer, default buffer historically only + references the appended text, not the resulting text. + + Support multiple, semi-colon separated search strings, and 'z' + commands after search strings. + + Make previous context mark setting match historic practice (see + docs/internals/context). + + Fix the set command to permit whitespace between the option and + the question mark, fix question marks in general. + + Fix bug where ex error messages could be accidentally preceded + by a single space. + + Fix bug where curses reorganization could lose screen specific + mappings as soon as any screen exited. + + Fix bug in paragraph code where invalid macros could be matched. + Make paragraph motions stop at formfeed (^L) characters. + + Change 'c' to match historic practice, it cut text into numeric + buffers. +1.25 -> 1.26 Tue Jul 19 17:46:24 1994 + + Ignore SIGWINCH if the screen size is unchanged; SunOS systems + deliver one when a screen is uncovered. + + Fix: don't permit a command with a motion component to wrap due + to wrapscan and return to the original cursor position. + + Fix: ^E wasn't beeping when reaching the bottom of the file. + + Fix bg/fg bug where tmp file exiting caused a NULL dereference. + + Rework file locking code to use fcntl(2) explicitly. + + Fix bug in section code where invalid macros could be matched. + + Fix bug where line number reset by vi's Q command. + + Add explicit character mode designation to character mode buffers. + + Add <sys/ioctl.h> include to sex/sex_window.c, needed by NET/2 + vintage systems. + + Change to always flush a character during suspend, 4BSD curses + has the optimization where it doesn't flush after a standend(). + + Fix bug on OSF1 where <curses.h> changes the values of VERASE, + VKILL and VWERASE to incorrect ones. + + Fix bug where optarg used incorrectly in main.c. + + Block all signals when acting on a signal delivery. + + Fix recovery bug where RCV_EMAIL could fire even if there wasn't + a backing file; format recovery message. +1.24 -> 1.25 Sun Jul 17 14:33:38 1994 + + Stop allowing keyboard suspends (^Z) in insert mode, it's hard + to get autowrite correct, and it's not historic practice. + + Fix z^, z+ to match historic practice. + + Bug in message handling, "vi +35 non-existent_file" lost the + status message because the "+35" pushed onto the stack erased + it. For now, change so that messages aren't displayed if there + are keys waiting -- may need to add a "don't-erase" bit to the + character in the stack instead. + + Bug in svi_msgflush(), where error messages could come out in + normal video. +1.23 -> 1.24 Sat Jul 16 18:30:18 1994 + + Fix core dump in exf.c, where editing a non-existent file and + exiting could cause already free'd memory to be free'd. + + Clean up numerous memory errors, courtesy of Purify. + + Change process wait code to fail if wait fails, and not attempt + to interpret the wait return information. + + Open recovery and DB files for writing as well as reading, System + V (fcntl) won't let you acquire LOCK_EX locks otherwise. + + Fix substitute bug where could malloc 0 bytes (AIX breaks). + + Permit the mapping of <carriage-return>, it's historic practice. + + Historic vi didn't eat <blank> characters before the force + flag, match historic practice. + + Bug in ex argument parsing, corrected for literal characters + twice. + + Delete screen specific maps when the screen closes. + + Move to the first non-<blank> in the line on startup; historic + practice. + + Change the ex visual command to move directly to a line if no + trailing 'z' command. + + Fix "[[" and "]]" to match historic practice (yet again...). + + Fix "yb" and "y{" commands to update the cursor correctly. + + Change "~<motion>" to match the yank cursor movement semantics + exactly. + + Move all of the curses related code into sex/svi -- major rework, + but should help in future ports. + + Fix bug in split code caused by new file naming code, where would + drop core when a split screen exited. + + Change svi_ex_write to do character display translation, so that + messages with file names in them are displayed correctly. + + Display the file name on split screens instead of a divider line. + + Fix move bug, wasn't copying lines before putting them. + + Fix bug were :n dropped core if no arguments supplied. + + Don't quote characters in executed buffer: "ifoo<esc>" should leave + insert mode after the buffer is executed. + + Tagpop and tagpush should set the absolute mark in case only moving + within a file. + + Skip leading whitespace characters before tags and cursor word + searches. + + Fix bug in ex_global where re_conv() was allocating the temporary + buffer and not freeing it. +1.22 -> 1.23: Wed Jun 29 19:22:33 1994 + + New <sys/cdefs.h> required "inline" to change to "__inline" + + Fix System V curses code for new ^Z support. + + Fix off-by-one in the move code, avoid ":1,$mo$" with only one + line in the buffer. + + Line orientation of motion commands was remembered too long, + i.e. '.' command could be incorrectly marked as line oriented. + + Move file modification time into EXF, so it's shared across + split screens. + + Put the prev[ious] command back in, people complained. + + Random fixes to next/prev semantics changed in 1.22. + + Historically vi doesn't only move to the last address if there's + ANYTHING after the addresses, e.g. ":3" moves to line 3, ":3|" + prints line 3. +1.21 -> 1.22: Mon Jun 27 11:01:41 1994 + + Make the line between split screens inverse video again. + + Delete the prev[ious] command, it's not useful enough to keep. + + Rework :args/file name handling from scratch -- MAJOR CHANGE, + likely to introduce all sorts of new bugs. + + Fix RE bug where no subexpressions in the pattern but there were + subexpressions referenced in the replacement, e.g. "s/XXX/\1/g". + + Change recovery to not leave unmodified files around after a + crash, by using the owner 'x' bit on unmodified backup files. + MAJOR CHANGE, the system recovery script has to change! + + Change -r option to delete recovery.* files that reference non- + existent vi.* files. + + Rework recovery locking so that fcntl(2) locking will work. + + Fix append (upper-case) buffers, broken by cut fixes. + + Fix | to not set the absolute motion mark. + + Read $HOME/.exrc file on startup if the effective user ID is + root. This makes running vi while su(1)'d work correctly. + + Use the full pathname of the file as the recovery name, not + just the last component. Matches historic practice. + + Keep marks in empty files from being destroyed. + + Block all caught signals before calling the DB routines. + + Make the line change report match historic practice (yanked + lines were different than everything else). + + Add section on multiple screens to the reference manual. + + Display all messages at once, combine onto a single line if + possible. Delete the trailing period from all messages. +1.20 -> 1.21: Thu May 19 12:21:58 1994 + + Delete the -l flag from the recover mail. + + Send the user email if ex command :preserve executed, this matches + historic practice. Lots of changes to the preserve and recovery + code, change preserve to snapshot files (again, historic practice). + + Make buffers match historic practice: "add logically stores text + into buffer a, buffer 1, and the unnamed buffer. + + Print <tab> characters as ^I on the colon command line if the + list option set. + + Adjust ^F and ^B scroll values in the presence of split screens + and small windows. + + Break msg* routines out from util.c into msg.c, start thinking + about message catalogs. + + Add tildeop set option, based on stevie's option of the same name. + Changes the ~ command into "[count] ~ motion", i.e. ~ takes a + trailing motion. + + Chose NOT to match historic practice on cursor positioning after + consecutive undo commands on a single line; see vi/v_undo.c for + the comment. + + Add a one line cache so that multiple changes to the same line + are only counted once (e.g. "dl35p" changes one line, not 35). + + Rework signals some more. Block file sync signals in vi routines + that interface to DB, so can sync the files at interrupt time. + Write up all of the signal handling arguments, see signal.c. +1.19 -> 1.20: Thu May 5 19:24:57 1994 + + Return ^Z to synchronous handling. See the dicussion in signal.c + and svi_screen.c:svi_curses_init(). + + Fix bug where line change report was wrong in util.c:msg_rpt(). +1.18 -> 1.19: Thu May 5 12:59:51 1994 + + Block DSUSP so that ^Y isn't delivered at SIGTSTP. + + Fix bug -- put into an empty file leaves the cursor at 1,0, + not the first nonblank. + + Fix bug were number of lines reported for the 'P' command was + off-by-one. + + Fix bug were 0^D wasn't being handled correctly. + + Delete remnants of ^Z as a raw character. + + Fix bug where if a map was an entire colon command, it may never + have been displayed. + + Final cursor position fixes for the vi T and t commands. + + The ex :next command took an optional ex command as it's first + argument similar to the :edit commands. Match historic practice. +1.17 -> 1.18: Wed May 4 13:57:10 1994 + + Rework curses information in the PORT/Makefile's. + + Minor fixes to ^Z asynchronous code. +1.16 -> 1.17: Wed May 4 11:15:56 1994 + + Make ex comment handling match historic practice. + + Make ^Z work asynchronously, we can no longer use the SIGTSTP + handler in the curses library. +1.15 -> 1.16: Mon May 2 19:42:07 1994 + + Make the 'p' and 'P' commands support counts, i.e. "Y10p" works. + + Make characters that map to themselves as the first part of the + mapping work, it's historic practice. + + Fix bug where "s/./\& /" discarded the space in the replacement + string. + + Add support for up/down cursor arrows in text input mode, rework + left/right support to match industry practice. + + Fix bug were enough character remapping could corrupt memory. + + Delete O_REMAPMAX in favor of setting interrupts after N mapped + characters without a read, delete the map counter per character. + MAJOR CHANGE. All of the interrupt signal handling has been + reworked so that interrupts are always turned on instead of + being turned on periodically, when an interruptible operation is + pending. + + Fix bug where vi wait() was interrupted by the recovery alarm. + + Make +cmd's and initial commands execute with the current line + set to the last line of the file. This is historic practice. + + Change "lock failed" error message to a file status message. + It always fails over NFS, and making all NFS files readonly + isn't going to fly. + + Use the historic line number format, but check for overflow. + + Fix bug where vi command parser ignored buffers specified as + part of the motion command. + + Make [@*]buffer commands on character mode buffers match historic + practice. + + Fix bug where the cmap/chf entries of the tty structure weren't + being cleared when new characters were read. + + Fix bug where the default command motion flags were being set + when the command was a motion component. + + Fix wrapmargin bug; if appending characters, and wrapmargin breaks + the line, an additional space is eaten. +1.14 -> 1.15: Fri Apr 29 07:44:57 1994 + + Make the ex delete command work in any empty file. + + Fix bug where 't' command placed the cursor on the character + instead of to its left. + + ^D and ^U didn't set the scroll option value historically. + Note, this change means that any user set value (e.g. 15^D) + will be lost when splitting the screen, since the split code + now resets the scroll value regardless. + + Fix the ( command to set the absolute movement mark. + + Only use TIOCGWINSZ for window information if SIGWINCH signal + caught. + + Delete the -l flag, and make -r work for multiple arguments. + Add the ex "recover[!] file" command. + + Switch into ex terminal mode and use the sex routines when + append/change/insert called from vi mode. + + Make ^F and ^B match historic practice. This required a fairly + extensive rework of the svi scrolling code. + + Cursor positioning in H, M, L, G (first non-blank for 1G) wasn't + being done correctly. Delete the SETLFNB flag. H, M, and L stay + logical movements (SETNNB) and G always moves to the first nonblank. + + System V uses "lines" and "cols", not "li" and "co", change as + necessary. Check termcap function returns for errors. + + Fix `<character> command to do start/end of line correction, + and to set line mode if starting and stopping at column 0. + + Fix bug in delete code where dropped core if deleted in character + mode to an empty line. (Rework the delete code for efficiency.) + + Give up on SunOS 4.1.X, and use "cc" instead of /usr/5bin/cc. + + Protect ex_getline routine from interrupted system calls (if + possible, set SA_RESTART on SIGALRM, too). + + Fix leftright scrolling bug, when moving to a shorter line. + + Do validity checking on the copy, move, t command target line + numbers. + + Change for System V % pattern broke trailing flags for empty + replacement strings. + + Fix bug when RCM flags retained in the saved dot structure. + + Make the ex '=' command work for empty files. + + Fix bug where special_key array was being free'd (it's no longer + allocated). + + Matches cut in line mode only if the starting cursor is at or + before the first nonblank in its line, and the ending cursor is + at or after the last nonblank in its line. + + Add the :wn command, so you can write a file and switch to a new + file in one command. + + Allow only a single key as an argument to :viusage. + + New movement code broke filter/paragraph operations in empty + files ("!}date" in an empty file was dropping core). +1.12 -> 1.14: Mon Apr 18 11:05:10 1994 (PUBLICLY AVAILABLE VERSION, 4.4BSD) + + Fix FILE structure leakage in the ex filter code. + + Rework suspend code for System V curses. Nvi has to do the + the work, there's no way to get curses to do it right. + + Revert SunOS 4.1.X ports to the distributed curses. There's + a bug in Sun's implementation that we can't live with. + + Quit immediately if row/column values are unreasonable. + + Fix the function keys to match vi historic behavior. + + Replace the echo/awk magic in the Makefile's with awk scripts. +1.11 -> 1.12: Thu Apr 14 11:10:19 1994 + + Fix bug where only the first vi key was checked for validity. + + Make 'R' continue to overwrite after a <carriage-return>. + + Only display the "no recovery" message once. + + Rework line backup code to restore the line to its previous + condition. + + Don't permit :q in a .exrc file or EXINIT variable. + + Fix wrapscan option bug where forward searches become backward + searches and do cursor correction accordingly. + + Change "dd" to move the cursor to the first non-blank on the line. + + Delete cursor attraction to the first non-blank, change non-blank + motions to set the most attractive cursor position instead. + + Fix 'r' substitute option to set the RE to the last RE, not the + last substitute RE. + + Fix 'c' and 'g' substitute options to always toggle, and fix + edcompatible option to not reset them. + + Display ex error messages in inverse video. + + Fix errorbells option to match historic practice. + + Delete fixed character display table in favor of table built based + on the current locale. + + Add ":set octal" option, that displays unknown characters as octal + values instead of the default hexadecimal. + + Make all command and text input modes interruptible. + + Fix ex input mode to display error messages immediately, instead + of waiting for the lines to be resolved. + + Fix bug where vi calling append could overwrite the command. + + Fix off-by-one in the ex print routine tab code. + + Fix incorrect ^D test in vi text input routines. + + Add autoindent support for ex text insert routines. + + Add System V substitute command replacement pattern semantics, + where '%' means the last replacement pattern. + + Fix bug that \ didn't escape newlines in ex commands. + + Regularize the names of special characters to CH_*. + + Change hex insert character from ^Vx<hex_char> to ^X<hex_char> + + Integrate System V style curses, so SunOS and Solaris ports can + use the native curses implementation. +1.10 -> 1.11: Thu Mar 24 16:07:45 EST 1994 (PUBLICLY AVAILABLE VERSION) + + Change H, M, and L to set the absolute mark, historical practice. + + Fix bug in stepping through multiple tags files. + + Add "remapmax" option that turns off map counts so you can remap + infinitely. If it's off, term_key() can be interrupted from the + keyboard, which will cause the buffers to flush. I also dropped + the default max number of remaps to 50. (Only Dave Hitz's TM + macros and maze appear to go over that limit.) + + Change :mkexrc to not dump w{300,1200,9600}, lisp options. + + Fix backward search within a line bug. + + Change all the includes of "pathnames.h" to use <>'s so that the + PORT versions can use -I. to replace it with their own versions. + + Make reads and writes interruptible. Rework code that enters and + leaves ex for '!' and filter commands, rework all interrupt and + timer code. + + Fix core dump when user displayed option in .exrc file. + + Fix bug where writing empty files didn't update the saved + modification time. + + Fix bug where /pattern/ addressing was always a backward search. + + Fix bug triggered by autoindent of more than 32 characters, where + nvi wasn't checking the right TEXT length. + + Fix bug where joining only empty lines caused a core dump. +1.09 -> 1.10: Sat Mar 19 15:40:29 EST 1994 + + Fix "set all" core dump. +1.08 -> 1.09: Sat Mar 19 10:11:14 EST 1994 + + If the tag's file path is relative, and it doesn't exist, check + relative to the tag file location. + + Fix ~ command to free temporary buffer on error return. + + Create vi.ref, a first cut at a reference document for vi. + The manual page and the reference document only document the + set options, so far. + + Fix 1G bug not always going to the first non-blank. + + Upgrade PORT/regex to release alpha3.4, from Henry Spencer. + + Add MKS vi's "cdpath" option, supporting a cd search path. + + Handle if search as a motion was discarded, i.e. "d/<erase>". + + Change nvi to not create multiple recovery files if modifying + a recovered file. + + Decide to ignore that the cursor is before the '$' when inserting + in list mode. It's too hard to fix. +1.07 -> 1.08: Wed Mar 16 07:37:36 EST 1994 + + Leftright and big line scrolling fixes. This meant more changes + to the screen display code, so there may be new problems. + + Don't permit search-style addresses until a file has been read. + + "c[Ww]" command incorrectly handled the "in whitespace" case. + + Fix key space allocation bug triggered by cut/paste under SunOS. + + Ex move command got the final cursor position wrong. + + Delete "optimize option not implemented" message. + + Make the literal-next character turn off mapping for the next + character in text input mode. +1.06 -> 1.07: Mon Mar 14 11:10:33 EST 1994 + + The "wire down" change in 1.05 broke ex command parsing, there + wasn't a corresponding change to handle multiple K_VLNEXT chars. + + Fix final position for vi's 't' command. +1.05 -> 1.06: Sun Mar 13 16:12:52 EST 1994 + + Wire down ^D, ^H, ^W, and ^V, regardless of the user's termios + values. + + Add ^D as the ex scroll command. + + Support ^Q as a literal-next character. + + Rework abbreviations to be delimited by any !inword() character. + + Add options description to the manual page. + + Minor screen cache fix for svi_get.c. + + Rework beautify option support to match historical practice. + + Exit immediately if not reading from a tty and a command fails. + + Default the SunOS 4.* ports to the distributed curses, not SMI's. +1.04 -> 1.05: Thu Mar 24 16:07:45 EST 1994 + + Make cursor keys work in input mode. + + Rework screen column code in vi curses screen. MAJOR CHANGE -- + after this, we'll be debugging curses screen presentation from + scratch. + + Explode include files in vi.h into the source files. +1.03 -> 1.04: Sun Mar 6 14:14:16 EST 1994 + + Make the ex move command keep the marks on the moved lines. + + Change resize semantics so you can set the screen size to a + specific value. A couple of screen fixes for the resize code. + + Fixes for foreground/background due to SIGWINCH. + + Complete rework of all of vi's cursor movements. The underlying + assumption in the old code was that the starting cursor position + was part of the range of lines cut or deleted. The command + "d[[" is an example where this isn't true. Change it so that all + motion component commands set the final cursor position separately + from the range, as it can't be done correctly later. This is a + MAJOR CHANGE -- after this change, we'll be debugging the cursor + positioning from scratch. + + Rewrite the B, b, E, e commands to use vi's getc() interface + instead of rolling their own. + + Add a second MARK structure, LMARK, which is the larger mark + needed by the logging and mark queue code. Everything else uses + the reworked MARK structure, which is simply a line/column pair. + + Rework cut/delete to not expect 1-past-the-end in the range, but + to act on text to the end of the range, inclusive. + + Sync on write's, to force NFS to flush. +1.01 -> 1.03: Sun Jan 23 17:50:35 EST 1994 (PUBLICLY AVAILABLE VERSION) + + Tag stack fixes, was returning to the tag, not the position from + which the user tagged. + + Only use from the cursor to the end of the word in cursor word + searches and tags. (Matches historical vi behavior.) + + Fix delete-last-line bug when line number option set. + + Fix usage line for :split command. + + If O_NUMBER set, long input lines would eventually fail, the column + count for the second screen of long lines wasn't set correctly. + + Fix for [[ reaching SOF with a column longer than the first line. + + Fix for multiple error messages if no screen displayed. + + Fix :read to set alternate file name as in historical practice. + + Fix cut to rotate the numeric buffers if line mode flag set. +1.00 -> 1.01: Wed Jan 12 13:37:18 EST 1994 + + Don't put cut items into numeric buffers if cutting less than + parts of two lines. +0.94 -> 1.00: Mon Jan 10 02:27:27 EST 1994 + + Read-ahead not there; BSD tty driver problem, SunOS curses + problem. + + Global command could error if it deleted the last line of + the file. + + Change '.' to only apply to the 'u' if entered immediately + after the 'u' command. "1pu.u.u. is still broken, but I + expect that it's going to be sacrificed for multiple undo. + + If backward motion on a command, now move to the point; get + yank cursor positioning correct. + + Rework cut buffers to match historic practice -- yank/delete + numeric buffers redone sensibly, ignoring historic practice. +0.92 -> 0.93: Mon Dec 20 19:52:14 EST 1993 + + Christos Zoulas reimplemented the script windows using pty's, + which means that they now work reasonably. The down side of + this is that almost all ports other than 4.4BSD need to include + two new files, login_tty.c and pty.c from the PORT/clib directory. + I've added them to the Makefiles. + + All calloc/malloc/realloc functions now cast their pointers, for + SunOS -- there should be far fewer warning messages, during the + build. The remaining messages are where CHAR_T's meet char *'s, + i.e. where 8-bit clean meets strcmp. + + The user's argument list handling has been reworked so that there + is always a single consistent position for use by :next, :prev and + :rewind. + + All of the historical options are now at least accepted, although + not all of them are implemented. (Edcompatible, hardtabs, lisp, + optimize, redraw, and slowopen aren't implemented.) + + The RE's have been reworked so that matches of length 0 are handled + in the same way as vi used to handle them. + + Several more mapping fixes and ex parser addressing fixes. diff --git a/contrib/nvi/docs/ev b/contrib/nvi/docs/ev new file mode 100644 index 000000000000..144295a319f2 --- /dev/null +++ b/contrib/nvi/docs/ev @@ -0,0 +1,55 @@ +# @(#)ev 8.4 (Berkeley) 4/29/94 + +Ev: Vi: Result: +<CK> <CK> (Cursor keys). Move around the file. + +Meta key commands: +^A<#> <#>G Goto line #. +^A$ G Goto the end of the file. +^A/ / Prompt and execute a forward search. +^A: : Prompt and execute an ex command. +^A? ? Prompt and execute a backward search. +^Ac y'<c> Copy to mark in line mode (or copy the current line). +^AC y`<c> Copy to mark in character mode. +^Ad d'<c> Delete to mark in line mode (or delete the current line). +^AD d`<c> Delete to mark in character mode. +^Aj J Join lines. +^Am m<c> Mark the current cursor position. +^AN N Repeat search in the reverse direction. +^An ^A Search for the word under the cursor. +^Ar u Redo a command. +^Au u Undo a command. + +Single key commands: +^B ^B Page up a screen. +^C ^C Interrupt long-running commands. +^D ^D Page down a half-screen. +^E $ End of line. +^F ^F Page down a screen. +^G ^G File status/information. +^H X Delete the character to the left of the cursor. +^I (TAB) +^J j Cursor down one line. +^K k Cursor up one line. +^L ^L Redraw the screen. +^M (CR) ^M In insert mode, split the line at the current cursor, + creating a new line. + In overwrite mode, cursor down one line. +^N n Repeat previous search, in previous direction. +^O (UNUSED) +^P p Paste the cut text at the cursor position. +^Q (XON/XOFF) +^R (UNUSED) +^S (XON/XOFF) +^T D Truncate the line at the cursor position. +^U ^U Page up a half-screen. +^V<c> ^V<c> Insert/overwrite with a literal next character. +^W w Move forward one whitespace separated word. +^X x Delete the current character. +^Y (UNUSED) +^Z ^Z Suspend. + +New ex mode commands: + +^A:set ov[erwrite] Toggle "insert" mode, so that input keys overwrite + the existing characters. diff --git a/contrib/nvi/docs/features b/contrib/nvi/docs/features new file mode 100644 index 000000000000..51650f949efc --- /dev/null +++ b/contrib/nvi/docs/features @@ -0,0 +1,83 @@ +List of things that should be added: +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= + ++ X11 (Tk, Motif, Xaw) interface. ++ Interpreted language (Perl, Scheme, Tcl/Rush, Python) ++ Additional ports: Windows, Windows NT, MSDOS ++ Forms editing package; use RE's to verify field contents. ++ Internationalization, including wide character and multibyte support. ++ Support for single line window editing, including full editing + capability on the vi colon command line. ++ Rob Pike's sam style RE's. ++ Right-to-left and bottom to top text support. ++ Quitall command, to leave all windows. A ! will force the quit. + +List of suggested features: +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= ++ It would be nice to have the completion mechanism found in tcsh versions + >= 6.03. For instance, the completion for the `:cd' command will be + directories only. The completion for the `:set' command will be all + options not set at that moment, and for `:set un' will be all options + that are set at that moment. The completion for `:< count' will be the + flags. + ++ Add an command-line option to initially split the screen based on the + number of file arguments, e.g., "nvi -a file1 file2" would initialize + a two edit-buffer display. + ++ Add a "push" command that would push a file on the tags stack. + (Essentially make tags a special case of the stack, and make + the stack more general purpose.) + ++ Make :script just run a command and edit the output, and :interactive, + which allows interactive shell session, instead of just the current + :script. + ++ Add tagging information to the man page so that users can display + the part of the man page that discusses the command in which they're + interested. + ++ Add a zone option so that you can declare that top/bottom few lines + of the screen aren't filled except by accident, so that the text + you ask for is always concentrated in the center of the screen. + ++ Change + :di[splay] tags -> :tags + :di[splay] screens -> :screens + :di[splay] buffers -> :buffers + ++ A macro record function. Add the ability to record a sequence + of keystrokes into a named buffer for later use. Handy when + you're trying to build a semi-complex macro. + ++ The semantics of :split, :bg, and :fg aren't right. Someone needs to + rethink how they should interact. The main problem arises when users + want to get a window into a new file. Currently, the necessary sequence + is ":split newfile|^W|:bg". It would be nice if you could simply + background the current screen and edit a new one. + ++ An option to turn on a ``quarter plane'' model so that you can + go as far to the right or down as you wish. The File or the + current line is only extended if you actually put down a char at + the new location. Very handy for ascii graphics and tables. + ++ Some way of replacing the command bindings. For this to work + cleanly the notion of a command must be separate from that of a + key. (Simulate the Rand editor?) + ++ Vertical splitting, so you can see files side by side. + ++ Tracking. Two or more files are associated so that when one file + is scrolled up/down/left/right other files track by the same amount. + Tracking may be constrained such that two files only track vertically + or horizontally. This is relatively easy to implement. + ++ A status file so that the next time invocation of the editor returns + to the same place, with the same number of windows etc. In case of + change of the screen size, reasonable defaults are used. For each + window size and location of the window, name of the file and position + in it, any tab settings, any other settings for the window (such as + insert/overwrite mode, auto indent etc). Last search RE and maybe + direction. If a file does not exist the next time you invoke the + editor, its window is left in the same place but with some default + message. diff --git a/contrib/nvi/docs/help b/contrib/nvi/docs/help new file mode 100644 index 000000000000..81df84aa1353 --- /dev/null +++ b/contrib/nvi/docs/help @@ -0,0 +1,229 @@ +MOVING THE CURSOR: + k - cursor up ^F - page forward /<pattern><CR> - search forward + j - cursor down ^B - page backward ?<pattern><CR> - search backward + h - cursor left w - move forward a "word" n - repeat the last search + l - cursor right b - move backward a "word" + +ENTERING TEXT: +a - append after the cursor. Use the <escape> key to return to +i - insert before the cursor. command mode. +o - open a new line below the cursor. +O - open new line above the cursor. + +WRITING AND EXITING: +:w<Enter> - write the file +:q<Enter> - exit the file +:q!<Enter> - exit without writing the file +:#<Enter> - move to a line (e.g., :35<Enter> moves to line 35) + +MISCELLANEOUS: +^G - display the file name + J - join two lines (use i<Enter><escape> to split a line) + u - undo the last change (enter . after a 'u' to undo more than one change) + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +VI COMMANDS: + ^A search forward for cursor word + ^B scroll up by screens + ^C interrupt an operation (e.g. read, write, search) + ^D scroll down by half screens (setting count) + ^E scroll down by lines + ^F scroll down by screens + ^G file status + ^H move left by characters + ^J move down by lines + ^L redraw screen + ^M move down by lines (to first non-blank) + ^N move down by lines + ^P move up by lines + ^R redraw screen + ^T tag pop + ^U half page up (set count) + ^V input a literal character + ^W move to next screen + ^Y page up by lines + ^Z suspend editor + ^[ <escape> exit input mode, cancel partial commands + ^\ switch to ex mode + ^] tag push cursor word + ^^ switch to previous file + <space> move right by columns + ! filter through command(s) to motion + # number increment/decrement + $ move to last column + % move to match + & repeat substitution + ' move to mark (to first non-blank) + ( move back sentence + ) move forward sentence + + move down by lines (to first non-blank) + , reverse last F, f, T or t search + - move up by lines (to first non-blank) + . repeat the last command + / search forward + 0 move to first character + : ex command + ; repeat last F, f, T or t search + < shift lines left to motion + > shift lines right to motion + ? search backward + @ execute buffer + A append to the line + B move back bigword + C change to end-of-line + D delete to end-of-line + E move to end of bigword + F character in line backward search + G move to line + H move to count lines from screen top + I insert before first nonblank + J join lines + L move to screen bottom + M move to screen middle + N reverse last search + O insert above line + P insert before cursor from buffer + Q switch to ex mode + R replace characters + S substitute for the line(s) + T before character in line backward search + U Restore the current line + W move to next bigword + X delete character before cursor + Y copy line + ZZ save file and exit + [[ move back section + ]] move forward section + ^ move to first non-blank + _ move to first non-blank + ` move to mark + a append after cursor + b move back word + c change to motion + d delete to motion + e move to end of word + f character in line forward search + h move left by columns + i insert before cursor + j move down by lines + k move up by lines + l move right by columns + m set mark + n repeat last search + o append after line + p insert after cursor from buffer + r replace character + s substitute character + t before character in line forward search + u undo last change + w move to next word + x delete character + y copy text to motion into a cut buffer + z reposition the screen + { move back paragraph + | move to column + } move forward paragraph + ~ reverse case +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +EX COMMANDS: + ^D: scroll lines + !: filter lines through commands or run commands + #: display numbered lines + &: repeat the last subsitution + *: execute a buffer + <: shift lines left + =: display line number + >: shift lines right + @: execute a buffer + append: append input to a line + abbreviate: specify an input abbreviation + args: display file argument list + bg: background the current screen + change: change lines to input + cd: change the current directory + chdir: change the current directory + copy: copy lines elsewhere in the file + cscope: create a set of tags using a cscope command + delete: delete lines from the file + display: display buffers, screens or tags + [Ee]dit: begin editing another file + [Ee]x: begin editing another file + exusage: display ex command usage statement + file: display (and optionally set) file name + fg: switch the current screen and a backgrounded screen + global: execute a global command on lines matching an RE + help: display help statement + insert: insert input before a line + join: join lines into a single line + k: mark a line position + list: display lines in an unambiguous form + move: move lines elsewhere in the file + mark: mark a line position + map: map input or commands to one or more keys + mkexrc: write a .exrc file + [Nn]ext: edit (and optionally specify) the next file + number: change display to number lines + open: enter "open" mode (not implemented) + print: display lines + perl: run the perl interpreter with the command + perldo: run the perl interpreter with the command, on each line + preserve: preserve an edit session for recovery + [Pp]revious: edit the previous file in the file argument list + put: append a cut buffer to the line + quit: exit ex/vi + read: append input from a command or file to the line + recover: recover a saved file + resize: grow or shrink the current screen + rewind: re-edit all the files in the file argument list + s: substitute on lines matching an RE + script: run a shell in a screen + set: set options (use ":set all" to see all options) + shell: suspend editing and run a shell + source: read a file of ex commands + stop: suspend the edit session + suspend: suspend the edit session + t: copy lines elsewhere in the file + [Tt]ag: edit the file containing the tag + tagnext: move to the next tag + tagpop: return to the previous group of tags + tagprev: move to the previous tag + tagtop: discard all tags + tcl: run the tcl interpreter with the command + undo: undo the most recent change +unabbreviate: delete an abbreviation + unmap: delete an input or command map + v: execute a global command on lines NOT matching an RE + version: display the program version information + visual: enter visual (vi) mode from ex mode + [Vv]isual: edit another file (from vi mode only) + viusage: display vi key usage statement + write: write the file + wn: write the file and switch to the next file + wq: write the file and exit + xit: exit + yank: copy lines to a cut buffer + z: display different screens of the file + ~: replace previous RE with previous replacement string, +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +Edit options: +noaltwerase filec="" nomodeline scroll=17 notildeop +autoindent flash msgcat="./" nosearchincr timeout +autoprint hardtabs=0 noprint="" nosecure nottywerase +noautowrite noiclower nonumber shiftwidth=8 noverbose +backup="" noignorecase nooctal noshowmatch warn +nobeautify keytime=6 open noshowmode window=35 +cedit="" noleftright optimize sidescroll=16 nowindowname +columns=80 lines=36 print="" noslowopen wraplen=0 +comment nolisp prompt nosourceany wrapmargin=0 +noedcompatible nolist readonly tabstop=8 wrapscan +escapetime=1 lock noredraw taglength=0 nowriteany +noerrorbells magic remap tags="tags" +exrc matchtime=7 report=5 term="xterm" +noextended mesg ruler noterse +cdpath="/usr/src/local/nvi:/tmp" +directory="/tmp" +paragraphs="IPLPPPQPP LIpplpipbp" +recdir="/var/tmp/vi.recover" +sections="NHSHH HUnhsh" +shell="/bin/csh" +shellmeta="~{[*?$`'"\" diff --git a/contrib/nvi/docs/internals/autowrite b/contrib/nvi/docs/internals/autowrite new file mode 100644 index 000000000000..dbad6c8bae8a --- /dev/null +++ b/contrib/nvi/docs/internals/autowrite @@ -0,0 +1,88 @@ +# @(#)autowrite 8.3 (Berkeley) 2/17/95 + +Vi autowrite behavior, the fields with *'s are "don't cares". + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +Commands that are affected only by autowrite: + +Command File Autowrite? Action: + modified? +----------------------------------------------- +^Z Y Y Write file and suspend. +^Z Y N Suspend. +^Z N * Suspend. + +# This behavior is NOT identical to :edit. +^^ Y Y Write file and jump. +^^ Y N Error. +^^ N * Jump. + +# The new nvi command ^T (:tagpop) behaves identically to ^]. +# This behavior is identical to :tag, :tagpop, and :tagpush with +# force always set to N. +^] Y Y Write file and jump. +^] Y N Error. +^] N * Jump. + +# There's no way to specify a force flag to the '!' command. +:! Y Y Write file and execute. +:! Y N Warn (if warn option) and execute. +:! N * Execute. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +Commands that are affected by both autowrite and force: + +NOTE: the "force" flag is never passed on, i.e. the write +to the file caused by the autowrite flag is never forced. + +Command File Autowrite? Force? Action: + modified? (!) +------------------------------------------------------- +# The first rule (YYY) is historic practice, but seems wrong. +# In nvi, :next and :prev commands behave identically to :rewind. +:next Y Y Y Write changes and jump. +:next Y Y N Write changes and jump. +:next Y N Y Abandon changes and jump. +:next Y N N Error. +:next N * * Jump. + +:rewind Y Y Y Abandon changes and jump. +:rewind Y Y N Write changes and jump. +:rewind Y N Y Abandon changes and jump. +:rewind Y N N Error. +:rewind N * * Jump. + +# The new nvi commands, :tagpop and :tagtop, behave identically to :tag. +# Note, this behavior is the same as :rewind and friends, as well. +:tag Y Y Y Abandon changes and jump. +:tag Y Y N Write changes and jump. +:tag Y N Y Abandon changes and jump. +:tag Y N N Error. +:tag N * * Jump. + +# The command :suspend behaves identically to :stop. +:stop Y Y Y Suspend. +:stop Y Y N Write changes and suspend. +:stop Y N Y Suspend. +:stop Y N N Suspend. +:stop N * * Suspend. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +Commands that might be affected by autowrite, but aren't: + +Command File Autowrite? Force? Action: + modified? (!) +------------------------------------------------------- +#:ex, and :vi (executed while in vi mode) behave identically to :edit. +:edit Y * Y Abandon changes and jump. +:edit Y * N Error. +:edit N * * Jump. + +:quit Y * Y Quit. +:quit Y * N Error. +:quit N * * Quit. + +:shell * * * Execute shell. + +:xit Y * * Write changes and exit. +:xit N * * Exit. diff --git a/contrib/nvi/docs/internals/context b/contrib/nvi/docs/internals/context new file mode 100644 index 000000000000..8b1db32768b7 --- /dev/null +++ b/contrib/nvi/docs/internals/context @@ -0,0 +1,32 @@ +# @(#)context 8.6 (Berkeley) 10/14/94 + +In historic vi, the previous context mark was always set: + +ex address: + any number, <question-mark>, <slash>, <dollar-sign>, + <single-quote>, <backslash> + +ex commands: undo, "z.", global, v + +vi commands: (, ), {, }, %, [[, ]], ^] + +nvi adds the vi command ^T to this list. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +In historic vi, the previous context mark was set if the +line changed: + +vi commands: '<mark>, G, H, L, M, z + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +In historic vi, the previous context mark was set if the +line or column changed: + +vi commands: `<mark>, /, ?, N, n + +nvi adds the vi command ^A to this list. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +In historic vi, the previous context mark was set in non-visual +mode for ^R and ^L if the line changed, but I have yet to figure +out how the line could change. diff --git a/contrib/nvi/docs/internals/cscope.NOTES b/contrib/nvi/docs/internals/cscope.NOTES new file mode 100644 index 000000000000..e0e3483d26ed --- /dev/null +++ b/contrib/nvi/docs/internals/cscope.NOTES @@ -0,0 +1,142 @@ +Cscope Notes: + +The nvi tags structure has been reworked to handle the notion of multiple +locations per tag. This supports cscope, which returns multiple locations +per query. It will hopefully support ctags programs that create databases +with multiple locations per tag as well. + +There is now a list of "tag queues" chained from each screen. Each tag +queue has one or more "tag locations". + + +----+ +----+ +----+ +----+ + | EP | -> | Q1 | <-- | T1 | <-- | T2 | + +----+ +----+ --> +----+ --> +----+ + | + +----+ +----+ + | Q2 | <-- | T1 | + +----+ --> +----+ + | + +----+ +----+ + | Q3 | <-- | T1 | + +----+ --> +----+ + +In the above diagram, each "Q" is a "tag queue", and each "T" is a +tag location. Generally, the commands: + + :tag create a new Q + ^[ create a new Q + :cscope find create a new Q + :tagnext move to the next T + :tagprev move to the previous T + :tagpop discard one or more Q's + ^T discard the most recent Q + :tagtop discard all Q's + +More specifically: + +:cs[cope] a[dd] cscope-dir + + Attach to the cscope database in cscope-dir. + +:cs[cope] f[ind] c|d|e|f|g|i|s|t buffer|pattern + + Query all attached cscopes for the pattern. The pattern is a + regular expression. If the pattern is a double-quote character + followed by a valid buffer name (e.g., "t), then the contents + of the named buffer are used as the pattern. + + c: find callers of name + d: find all function calls made from name + e: find pattern + f: find files with name as substring + g: find definition of name + i: find files #including name + s: find all uses of name + t: find assignments to name + + The find command pushes the current location onto the tags stack, + and switches to the first location resulting from the query, if + the query returned at least one result. + +:cs[cope] h[elp] [command] + + List the cscope commands, or usage help on one command. + +:display c[onnections] + + Display the list of cscope connections + +:display t[ags] + + The tags display has been enhanced to display multiple tag + locations per tag query. + +:cs[cope] k[ill] # + + Kill cscope connection number #. + +:cs[cope] r[eset] + Kill all attached cscopes. Useful if one got hung but you don't + know which one. + +:tagn[ext][!] + + Move to the next tag resulting from a query. + +:tagpr[ev][!] + + Return to the previous tag resulting from a query. + +:tagp[op], ^T + + Return to the previous tag group (no change). + +:tagt[op] + + Discard all tag groups (no change). + +Suggested maps: + + " ^N: move to the next tag + map ^N :tagnext^M + " ^P: move to the previous tag + map ^P :tagprev^M + + " Tab+letter performs a C-Scope query on the current word. + " C-Scope 12.9 has a text-string query (type t). + " C-Scope 13.3 replaces it with an assignment query; hence a==t. + map <tab>a "tye:csc find t"t
+ map <tab>c "tye:csc find c"t
+ map <tab>d "tye:csc find d"t
+ map <tab>e "tye:csc find e"t
+ map <tab>f "tye:csc find f"t
+ map <tab>g "tye:csc find g"t
+ map <tab>i "tye:csc find i"t
+ map <tab>s "tye:csc find s"t
+ map <tab>t "tye:csc find t"t
+ +To start nvi with an initial set of cscope directories, use the environment +variable CSCOPE_DIRS. This variable should contain a <blank>-separated +list of directories containing cscope databases. (This MAY be changed to +be an edit option, I haven't really decided, yet.) + +Each cscope directory must contain a file named "cscope.out" which is the +main cscope database, or nvi will not attempt to connect to a cscope to +handle requests for that database. + +The file "cscope.tpath" may contain a colon-separated directory search +path which will be used to find the files reported by cscope. If this +cscope.tpath does not exist, then the paths are assumed to be relative to +the cscope directory itself. This is an extension to the standard cscope, +but seems important enough to keep. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +Cscope Availability: + +UNIXWare System V Release 4.0 variants such as Sun Solaris 2.x +(/opt/SUNWspro/bin) have version 11.5, and UNIXWare System V +Release 4.1 has version 12.10 with an option for much faster +searching. + +You can buy version 13.3 source with an unrestricted license +for $400 from AT&T Software Solutions by calling +1-800-462-8146. diff --git a/contrib/nvi/docs/internals/gdb.script b/contrib/nvi/docs/internals/gdb.script new file mode 100644 index 000000000000..a1122343c162 --- /dev/null +++ b/contrib/nvi/docs/internals/gdb.script @@ -0,0 +1,76 @@ +# @(#)gdb.script 8.5 (Berkeley) 5/4/96 + +# display the VI screen map +# usage dmap(sp) +define dmap + set $h = ((VI_PRIVATE *)$arg0->vi_private)->h_smap + set $t = ((VI_PRIVATE *)$arg0->vi_private)->t_smap + while ($h <= $t) + printf "lno: %2d; soff %d coff %d ", \ + (int)$h->lno, (int)$h->soff, (int)$h->coff + if ($h->c_ecsize == 0) + printf "flushed\n" + else + printf "\n\tsboff %d; scoff %d\n", \ + (int)$h->c_sboff, (int)$h->c_scoff + printf "\teboff %d; eclen %d; ecsize %d\n", \ + (int)$h->c_eboff, (int)$h->c_eclen, \ + (int)$h->c_ecsize + end + set $h = $h + 1 + end +end + +# display the tail of the VI screen map +define tmap + set $h = ((VI_PRIVATE *)$arg0->vi_private)->h_smap + set $t = ((VI_PRIVATE *)$arg0->vi_private)->t_smap + while ($t >= $h) + printf "lno: %2d; soff %d coff %d ", \ + (int)$t->lno, (int)$t->soff, (int)$t->coff + if ($t->c_ecsize == 0) + printf "flushed\n" + else + printf "\n\tsboff %d; scoff %d\n", \ + (int)$t->c_sboff, (int)$t->c_scoff + printf "\teboff %d; eclen %d; ecsize %d\n", \ + (int)$t->c_eboff, (int)$t->c_eclen, \ + (int)$t->c_ecsize + end + set $t = $t - 1 + end +end + +# display the private structures +define clp + print *((CL_PRIVATE *)sp->gp->cl_private) +end +define vip + print *((VI_PRIVATE *)sp->vi_private) +end +define exp + print *((EX_PRIVATE *)sp->ex_private) +end + +# display the marks +define markp + set $h = sp->ep->marks.next + set $t = &sp->ep->marks + while ($h != 0 && $h != $t) + printf "key %c lno: %d cno: %d flags: %x\n", \ + ((MARK *)$h)->name, ((MARK *)$h)->lno, \ + ((MARK *)$h)->cno, ((MARK *)$h)->flags + set $h = ((MARK *)$h)->next + end +end + +# display the tags +define tagp + set $h = sp->taghdr.next + set $t = &sp->taghdr + while ($h != 0 && $h != $t) + printf "tag: %s lno %d cno %d\n", ((TAG *)$h)->frp->fname, \ + ((TAG *)$h)->lno, ((TAG *)$h)->cno + set $h= ((TAG *)$h)->next + end +end diff --git a/contrib/nvi/docs/internals/input b/contrib/nvi/docs/internals/input new file mode 100644 index 000000000000..9a7506ee2337 --- /dev/null +++ b/contrib/nvi/docs/internals/input @@ -0,0 +1,350 @@ +# @(#)input 5.5 (Berkeley) 7/2/94 + +MAPS, EXECUTABLE BUFFERS AND INPUT IN EX/VI: + +The basic rule is that input in ex/vi is a stack. Every time a key which +gets expanded is encountered, it is expanded and the expansion is treated +as if it were input from the user. So, maps and executable buffers are +simply pushed onto the stack from which keys are returned. The exception +is that if the "remap" option is turned off, only a single map expansion +is done. I intend to be fully backward compatible with this. + +Historically, if the mode of the editor changed (ex to vi or vice versa), +any queued input was silently discarded. I don't see any reason to either +support or not support this semantic. I intend to retain the queued input, +mostly because it's simpler than throwing it away. + +Historically, neither the initial command on the command line (the + flag) +or the +cmd associated with the ex and edit commands was subject to mapping. +Also, while the +cmd appears to be subject to "@buffer" expansion, once +expanded it doesn't appear to work correctly. I don't see any reason to +either support or not support these semantics, so, for consistency, I intend +to pass both the initial command and the command associated with ex and edit +commands through the standard mapping and @ buffer expansion. + +One other difference between the historic ex/vi and nex/nvi is that nex +displays the executed buffers as it executes them. This means that if +the file is: + + set term=xterm + set term=yterm + set term=yterm + +the user will see the following during a typical edit session: + + nex testfile + testfile: unmodified: line 3 + :1,$yank a + :@a + :set term=zterm + :set term=yterm + :set term=xterm + :q! + +This seems like a feature and unlikely to break anything, so I don't +intend to match historic practice in this area. + +The rest of this document is a set of conclusions as to how I believe +the historic maps and @ buffers work. The summary is as follows: + +1: For buffers that are cut in "line mode", or buffers that are not cut + in line mode but which contain portions of more than a single line, a + trailing <newline> character appears in the input for each line in the + buffer when it is executed. For buffers not cut in line mode and which + contain portions of only a single line, no additional characters + appear in the input. +2: Executable buffers that execute other buffers don't load their + contents until they execute them. +3: Maps and executable buffers are copied when they are executed -- + they can be modified by the command but that does not change their + actions. +4: Historically, executable buffers are discarded if the editor + switches between ex and vi modes. +5: Executable buffers inside of map commands are expanded normally. + Maps inside of executable buffers are expanded normally. +6: If an error is encountered while executing a mapped command or buffer, + the rest of the mapped command/buffer is discarded. No user input + characters are discarded. +7: Characters in executable buffers are remapped. +8: Characters in executable buffers are not quoted. + +Individual test cases follow. Note, in the test cases, control characters +are not literal and will have to be replaced to make the test cases work. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +1: For buffers that are cut in "line mode", or buffers that are not cut + in line mode but which contain portions of more than a single line, a + trailing <newline> character appears in the input for each line in the + buffer when it is executed. For buffers not cut in line mode and which + contain portions of only a single line, no additional characters + appear in the input. + +=== test file === +3Gw +w +line 1 foo bar baz +line 2 foo bar baz +line 3 foo bar baz +=== end test file === + + If the first line is loaded into 'a' and executed: + +1G"ayy@a + + The cursor ends up on the '2', a result of pushing "3Gw^J" onto + the stack. + + If the first two lines are loaded into 'a' and executed: + +1G2"ayy@a + + The cursor ends up on the 'f' in "foo" in the fifth line of the + file, a result of pushing "3Gw^Jw^J" onto the stack. + + If the first line is loaded into 'a', but not using line mode, + and executed: + +1G"ay$@a + + The cursor ends up on the '1', a result of pushing "3Gw" onto + the stack + + If the first two lines are loaded into 'a', but not using line mode, + and executed: + +1G2"ay$@a + + The cursor ends up on the 'f' in "foo" in the fifth line of the + file, a result of pushing "3Gw^Jw^J" onto the stack. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +2: Executable buffers that execute other buffers don't load their + contents until they execute them. + +=== test file === +cwLOAD B^[ +line 1 foo bar baz +line 2 foo bar baz +line 3 foo bar baz +@a@b +"byy +=== end test file === + + The command is loaded into 'e', and then executed. 'e' executes + 'a', which loads 'b', then 'e' executes 'b'. + +5G"eyy6G"ayy1G@e + + The output should be: + +=== output file === +cwLOAD B^[ +LOAD B 1 foo bar baz +line 2 foo bar baz +line 3 foo bar baz +@a@b +"byy +=== end output file === + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +3: Maps and executable buffers are copied when they are executed -- + they can be modified by the command but that does not change their + actions. + + Executable buffers: + +=== test file === +line 1 foo bar baz +line 2 foo bar baz +line 3 foo bar baz +@a@b +"eyy +cwEXECUTE B^[ +=== end test file === + +4G"eyy5G"ayy6G"byy1G@eG"ep + + The command is loaded into 'e', and then executed. 'e' executes + 'a', which loads 'e', then 'e' executes 'b' anyway. + + The output should be: + +=== output file === +line 1 foo bar baz +EXECUTE B 2 foo bar baz +line 3 foo bar baz +@a@b +"eyy +cwEXECUTE B^[ +line 1 foo bar baz +=== end output file === + + Maps: + +=== test file === +Cine 1 foo bar baz +line 2 foo bar baz +line 3 foo bar baz +=== end test file === + + Entering the command ':map = :map = rB^V^MrA^M1G==' shows that + the first time the '=' is entered the '=' map is set and the + character is changed to 'A', the second time the character is + changed to 'B'. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +4: Historically, executable buffers are discarded if the editor + switches between ex and vi modes. + +=== test file === +line 1 foo bar baz +line 2 foo bar baz +line 3 foo bar baz +cwCHANGE^[Q:set +set|visual|1Gwww +=== end test file === + +vi testfile +4G"ayy@a + +ex testfile +$p +yank a +@a + + In vi, the command is loaded into 'a' and then executed. The command + subsequent to the 'Q' is (historically, silently) discarded. + + In ex, the command is loaded into 'a' and then executed. The command + subsequent to the 'visual' is (historically, silently) discarded. The + first set command is output by ex, although refreshing the screen usually + causes it not to be seen. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +5: Executable buffers inside of map commands are expanded normally. + Maps inside of executable buffers are expanded normally. + + Buffers inside of map commands: + +=== test file === +line 1 foo bar baz +line 2 foo bar baz +line 3 foo bar baz +cwREPLACE BY A^[ +=== end test file === + +4G"ay$:map x @a +1Gx + + The output should be: + +=== output file === +REPLACE BY A 1 foo bar baz +line 2 foo bar baz +line 3 foo bar baz +cwREPLACE BY A^[ +=== end output file === + + Maps commands inside of executable buffers: + +=== test file === +line 1 foo bar baz +line 2 foo bar baz +line 3 foo bar baz +X +=== end test file === + +:map X cwREPLACE BY XMAP^[ +4G"ay$1G@a + + The output should be: + +=== output file === +REPLACE BY XMAP 1 foo bar baz +line 2 foo bar baz +line 3 foo bar baz +X +=== end output file === + + Here's a test that does both, repeatedly. + +=== test file === +line 1 foo bar baz +line 2 foo bar baz +line 3 foo bar baz +X +Y +cwREPLACED BY C^[ +blank line +=== end test file === + +:map x @a +4G"ay$ +:map X @b +5G"by$ +:map Y @c +6G"cy$ +1Gx + + The output should be: + +=== output file === +REPLACED BY C 1 foo bar baz +line 2 foo bar baz +line 3 foo bar baz +X +Y +cwREPLACED BY C^[ +blank line +=== end output file === + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +6: If an error is encountered while executing a mapped command or + a buffer, the rest of the mapped command/buffer is discarded. No + user input characters are discarded. + +=== test file === +line 1 foo bar baz +line 2 foo bar baz +line 3 foo bar baz +:map = 10GcwREPLACMENT^V^[^[ +=== end test file === + + The above mapping fails, however, if the 10G is changed to 1, 2, + or 3G, it will succeed. + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +7: Characters in executable buffers are remapped. + +=== test file === +abcdefghijklmnnop +ggg +=== end test file === + +:map g x +2G"ay$1G@a + + The output should be: + +=== output file === +defghijklmnnop +ggg +=== end output file === + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +8: Characters in executable buffers are not quoted. + +=== test file === +iFOO^[ + +=== end test file === + +1G"ay$2G@a + + The output should be: + +=== output file === +iFOO^[ +FOO +=== end output file === +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= diff --git a/contrib/nvi/docs/internals/openmode b/contrib/nvi/docs/internals/openmode new file mode 100644 index 000000000000..c64b76774b3e --- /dev/null +++ b/contrib/nvi/docs/internals/openmode @@ -0,0 +1,36 @@ + @(#)openmode 8.1 (Berkeley) 10/29/94 + +Open mode has the following special behaviors: + +z, ^F, ^B: + If count is not specified, it shall default to the window + edit option - 2. + + Write lines from the edit buffer starting at: + + (the current line) - ((count - 2) / 2) + + until: + + (((count + 1) / 2) * 2) - 1 + + lines, or the last line in the edit buffer has been written. A + line consisting of the smaller of the number of columns in the + display divided by two or 40 ``-'' characters shall be written + immediately before and after the specified is written. These two + lines shall count against the total number of lines to be written. + A blank line shall be written after the last line is written. + + z, ^F and ^B all behave identically. + +^D: Display the next scroll value lines, change the current line. + +^U: Change the current line, do nothing else. + +^E, ^Y: Do nothing. + +^L: Clear the screen and redisplay the current line. + +H, L, M: + Move to the first nonblank of the current line and do nothing + else. diff --git a/contrib/nvi/docs/internals/quoting b/contrib/nvi/docs/internals/quoting new file mode 100644 index 000000000000..a5fb8926a33c --- /dev/null +++ b/contrib/nvi/docs/internals/quoting @@ -0,0 +1,208 @@ +# @(#)quoting 5.5 (Berkeley) 11/12/94 + +QUOTING IN EX/VI: + +There are four escape characters in historic ex/vi: + + \ (backslashes) + ^V + ^Q (assuming it wasn't used for IXON/IXOFF) + The terminal literal next character. + +Vi did not use the lnext character, it always used ^V (or ^Q). +^V and ^Q were equivalent in all cases for vi. + +There are four different areas in ex/vi where escaping characters +is interesting: + + 1: In vi text input mode. + 2: In vi command mode. + 3: In ex command and text input modes. + 4: In the ex commands themselves. + +1: Vi text input mode (a, i, o, :colon commands, etc.): + + The set of characters that users might want to escape are as follows. + As ^L and ^Z were not special in input mode, they are not listed. + + carriage return (^M) + escape (^[) + autoindents (^D, 0, ^, ^T) + erase (^H) + word erase (^W) + line erase (^U) + newline (^J) (not historic practice) + + Historic practice was that ^V was the only way to escape any + of these characters, and that whatever character followed + the ^V was taken literally, e.g. ^V^V is a single ^V. I + don't see any strong reason to make it possible to escape + ^J, so I'm going to leave that alone. + + One comment regarding the autoindent characters. In historic + vi, if you entered "^V0^D" autoindent erasure was still + triggered, although it wasn't if you entered "0^V^D". In + nvi, if you escape either character, autoindent erasure is + not triggered. + + Abbreviations were not performed if the non-word character + that triggered the abbreviation was escaped by a ^V. Input + maps were not triggered if any part of the map was escaped + by a ^V. + + The historic vi implementation for the 'r' command requires + two leading ^V's to replace a character with a literal + character. This is obviously a bug, and should be fixed. + +2: Vi command mode + + Command maps were not triggered if the second or later + character of a map was escaped by a ^V. + + The obvious extension is that ^V should keep the next command + character from being mapped, so you can do ":map x xxx" and + then enter ^Vx to delete a single character. + +3: Ex command and text input modes. + + As ex ran in canonical mode, there was little work that it + needed to do for quoting. The notable differences between + ex and vi are that it was possible to escape a <newline> in + the ex command and text input modes, and ex used the "literal + next" character, not control-V/control-Q. + +4: The ex commands: + + Ex commands are delimited by '|' or newline characters. + Within the commands, whitespace characters delimit the + arguments. Backslash will generally escape any following + character. In the abbreviate, unabbreviate, map and unmap + commands, control-V escapes the next character, instead. + + This is historic behavior in vi, although there are special + cases where it's impossible to escape a character, generally + a whitespace character. + + Escaping characters in file names in ex commands: + + :cd [directory] (directory) + :chdir [directory] (directory) + :edit [+cmd] [file] (file) + :ex [+cmd] [file] (file) + :file [file] (file) + :next [file ...] (file ...) + :read [!cmd | file] (file) + :source [file] (file) + :write [!cmd | file] (file) + :wq [file] (file) + :xit [file] (file) + + Since file names are also subject to word expansion, the + underlying shell had better be doing the correct backslash + escaping. This is NOT historic behavior in vi, making it + impossible to insert a whitespace, newline or carriage return + character into a file name. + +4: Escaping characters in non-file arguments in ex commands: + + :abbreviate word string (word, string) +* :edit [+cmd] [file] (+cmd) +* :ex [+cmd] [file] (+cmd) + :map word string (word, string) +* :set [option ...] (option) +* :tag string (string) + :unabbreviate word (word) + :unmap word (word) + + These commands use whitespace to delimit their arguments, and use + ^V to escape those characters. The exceptions are starred in the + above list, and are discussed below. + + In general, I intend to treat a ^V in any argument, followed by + any character, as that literal character. This will permit + editing of files name "foo|", for example, by using the string + "foo\^V|", where the literal next character protects the pipe + from the ex command parser and the backslash protects it from the + shell expansion. + + This is backward compatible with historical vi, although there + were a number of special cases where vi wasn't consistent. + +4.1: The edit/ex commands: + + The edit/ex commands are a special case because | symbols may + occur in the "+cmd" field, for example: + + :edit +10|s/abc/ABC/ file.c + + In addition, the edit and ex commands have historically + ignored literal next characters in the +cmd string, so that + the following command won't work. + + :edit +10|s/X/^V / file.c + + I intend to handle the literal next character in edit/ex consistently + with how it is handled in other commands. + + More fun facts to know and tell: + The acid test for the ex/edit commands: + + date > file1; date > file2 + vi + :edit +1|s/./XXX/|w file1| e file2|1 | s/./XXX/|wq + + No version of vi, of which I'm aware, handles it. + +4.2: The set command: + + The set command treats ^V's as literal characters, so the + following command won't work. Backslashes do work in this + case, though, so the second version of the command does work. + + set tags=tags_file1^V tags_file2 + set tags=tags_file1\ tags_file2 + + I intend to continue permitting backslashes in set commands, + but to also permit literal next characters to work as well. + This is backward compatible, but will also make set + consistent with the other commands. I think it's unlikely + to break any historic .exrc's, given that there are probably + very few files with ^V's in their name. + +4.3: The tag command: + + The tag command ignores ^V's and backslashes; there's no way to + get a space into a tag name. + + I think this is a don't care, and I don't intend to fix it. + +5: Regular expressions: + + :global /pattern/ command + :substitute /pattern/replace/ + :vglobal /pattern/ command + + I intend to treat a backslash in the pattern, followed by the + delimiter character or a backslash, as that literal character. + + This is historic behavior in vi. It would get rid of a fairly + hard-to-explain special case if we could just use the character + immediately following the backslash in all cases, or, if we + changed nvi to permit using the literal next character as a + pattern escape character, but that would probably break historic + scripts. + + There is an additional escaping issue for regular expressions. + Within the pattern and replacement, the '|' character did not + delimit ex commands. For example, the following is legal. + + :substitute /|/PIPE/|s/P/XXX/ + + This is a special case that I will support. + +6: Ending anything with an escape character: + + In all of the above rules, an escape character (either ^V or a + backslash) at the end of an argument or file name is not handled + specially, but used as a literal character. + diff --git a/contrib/nvi/docs/internals/structures b/contrib/nvi/docs/internals/structures new file mode 100644 index 000000000000..a25c780c8e63 --- /dev/null +++ b/contrib/nvi/docs/internals/structures @@ -0,0 +1,68 @@ +# @(#)structures 5.4 (Berkeley) 10/4/95 + +There are three major data structures in this package, plus a single data +structure per screen type. The first is a single global structure (GS) +which contains information common to all files and screens. It hold +global things like the input key queues, and functions as a single place +to hang things. For example, interrupt routines have to be able to find +screen structures, and they can only do this if they have a starting +point. The number of globals in nvi is dependent on the screen type, but +every screen type will have at least one global, __global_list, which +references the GS structure. + +The GS structure contains linked lists of screen (SCR) structures. +Each SCR structure normally references a file (EXF) structure. + +The GS structure has a set of functions which update the screen and/or +return information about the screen from the underlying screen package. +The GS structure never goes away. The SCR structure persists over +instances of screens, and the EXF structure persists over references to +files. + +File names have different properties than files themselves, so the name +information for a file is held in an FREF structure which is chained from +the SCR structure. + +In general, functions are always passed an SCR structure, which usually +references an underlying EXF structure. The SCR structure is necessary +for any routine that wishes to talk to the screen, the EXF structure is +necessary for any routine that wants to modify the file. The relationship +between an SCR structure and its underlying EXF structure is not fixed, +and various ex commands will substitute a new EXF in place of the current +one, and there's no way to detect this. + +The naming of the structures is consistent across the program. (Macros +even depend on it, so don't try and change it!) The global structure is +"gp", the screen structure is "sp", and the file structure is "ep". + +A few other data structures: + +TEXT In nvi/cut.h. This structure describes a portion of a line, + and is used by the input routines and as the "line" part of a + cut buffer. + +CB In nvi/cut.h. A cut buffer. A cut buffer is a place to + hang a list of TEXT structures. + +CL The curses screen private data structure. Everything to + do standalone curses screens. + +MARK In nvi/mark.h. A cursor position, consisting of a line number + and a column number. + +MSG In nvi/msg.h. A chain of messages for the user. + +SEQ In nvi/seq.h. An abbreviation or a map entry. + +TK The Tcl/Tk screen private data structure. Everything to + do standalone Tcl/Tk screens. + +EXCMD In nvi/ex/ex.h. The structure that gets passed around to the + functions that implement the ex commands. (The main ex command + loop (see nvi/ex/ex.c) builds this up and then passes it to the + ex functions.) + +VICMD In nvi/vi/vi.h. The structure that gets passed around to the + functions that implement the vi commands. (The main vi command + loop (see nvi/vi/vi.c) builds this up and then passes it to the + vi functions.) diff --git a/contrib/nvi/docs/interp/interp b/contrib/nvi/docs/interp/interp new file mode 100644 index 000000000000..3da5a8f656dc --- /dev/null +++ b/contrib/nvi/docs/interp/interp @@ -0,0 +1,190 @@ +# @(#)interp 8.5 (Berkeley) 10/19/96 + Nvi Interpreter API + +Introduction: + The intention is to provide a way to graft a fairly generic extension + language into nvi. I think that the obvious candidates are Tcl/Rush, + Scheme, Python and Perl. Since the interpretation language chosen + is often a religious issue, the method should be as flexible as + possible. I don't expect to rewrite the editor in the interpreted + language, so that isn't a consideration. + + Q: Is there any reason for nvi to support multiple interpreters in + a single executable? + +Interpreter functions in nvi: + + 1: Function to get the current screen pointer. + + SCR *inter_screen(); + + Return a pointer to the current screen. + + 2: Functions to execute both ex and vi commands. The return value of the + function will be success/failure. The editor itself will continue to + handle the display of all messages and text for the foreseeable future. + + int inter_vicmd(SCR *, char *cmds, size_t len); + int inter_excmd(SCR *, char *cmds, size_t len); + + The byte string cmds, of length len, is entered into the standard + vi or ex parser, as if typed by the user. The characters are not + mapped in any way, i.e. the user's vi mappings don't apply. If + any error occurs, an error value is returned, and the rest of the + characters are discarded. + + 3: Functions to handle lines of text in the file. + + int inter_gline(SCR *, recno_t lno, char **lp, size_t *lenp); + + Return a pointer to the text of the line lno, into the location + referenced by lp, and its length into the location referenced by + lenp. + + int inter_dline(SCR *, recno_t lno); + + Delete the line lno from the file. + + int inter_aline(SCR *, recno_t lno, char *lp, size_t len); + + Append a line consisting of the len bytes of text referenced by + lp to the line lno. + + int inter_iline(SCR *, recno_t lno, char *lp, size_t len); + + Insert a line consisting of the len bytes of text referenced by + lp before the line lno. + + int inter_sline(SCR *, recno_t lno, char *lp, size_t len); + + Replace line lno with the len bytes of text referenced by lp. + + int inter_lline(SCR *, recno_t *lnop); + + Return the number of the last line in the file in the location + referenced by lnop. + + 4: Function to post an error message to the user. + + int inter_msgq(SCR *, enum msgtype, char *fmt, ...); + + Display the message for the user. Valid message types are: + + M_BERR Error: M_ERR if verbose, else bell. + M_ERR Error: Display in inverse video. + M_INFO Info: Display in normal video. + M_SYSERR Error: M_ERR, using strerror(3) message. + M_VINFO Info: M_INFO if verbose, else ignore. + + 5: Function to manipulate cut buffers. + + int inter_setbuf(SCR *, CHAR_T buffer); + + Create the specified buffer if it does not exist (the + buffer will have no contents). + + int inter_getbuf(SCR *, CHAR_T buffer, TEXT **textp); + + Return a pointer to the specified buffer in the location + referenced by textp. (Since a pointer to the real item + is being returned, it can be manipulated in any way the + interpreter chooses.) + + 6: Functions to manipulate marks. + + int inter_setmark(SCR *, CHAR_T name); + + Create the specified mark if it does not exist (the + mark will have no contents). + + int inter_getmark(SCR *, CHAR_T name, MARK **markp); + + Return a pointer to the specified mark in the location + referenced by markp. (Since a pointer to the real item + is being returned, it can be manipulated in any way the + interpreter chooses.) + + 7: Function to manipulate screens. + + SCR *inter_iscreen(); + + Create a new screen, and return a pointer to it. + + int inter_escreen(SCR *); + + End a screen. + + 8: Functions to get input from the user. + + int inter_getchar(CHAR_T *chp, + enum maptype {NONE, INPUT, COMMAND} mapt); + + Return a character from the keyboard into the location referenced + by chp. Mapt can be set to INPUT, COMMAND or NONE, depending on + what vi mappings should be applied to the character. + + int inter_getline(SCR *, char *prompt, CHAR_T **linep, + size_t *lenp, enum maptype {NONE, INPUT, COMMAND} mapt); + + Return a pointer to a line entered by the user, and its length, + into the locations linep and lenp. A prompt may be specified + by prompt, and mappings by mapt. + + int inter_freeline(CHAR_T *linep); + + Free the memory that was allocated by inter_getline(); + + 9: Function to retrieve and set the cursor. + + int inter_getcursor(SCR *, MARK *mark); + + Store the current cursor position in mark. + + int inter_setcursor(SCR *, MARK *mark); + + Set the current cursor position to mark. + +10: Function to return a motion command from the user. + + int inter_getmotion(SCR *, + MARK *start, MARK *end, enum movetype {LINE, CHAR} *mt); + + Nvi gets a motion command from the user and returns the starting + and stopping points of the movement, reordered from the beginning + to the end of the file. The standard rules for line/character + motions are applied, and returned to the interpreter through the + mt argument. + +11: Functions to return pathnames. + +12: Functions to return edit options. + +13: Nvi commands which will send text to the interpreter. + + Nvi will have a new ex command "inter", which will pipe the rest of + the line up to the first unescaped <newline> to the interpreter, of + the following form: + + :[address[,address]] inter [count] command + + The interface from the ex command to the interpreter is a function: + + int inter_ex( + SCR *, /* Current screen. */ + char *cmd; /* The command. */ + size_t len; /* The command length. */ + MARK *start, /* Starting address for INTER_EX */ + MARK *end, /* Ending address for INTER_EX */ + int count); /* Count. */ + + Nvi will have a new vi command "*<buffer>" which will pipe the contents + of the named buffer to the interpreter, of the following form: + + [count]*<buffer> + + The interface from the vi command to the interpreter is a function: + + int inter_vi( + SCR *, /* Current screen. */ + CHAR_T buffer, /* Buffer. */ + int count); /* Count. */ diff --git a/contrib/nvi/docs/interp/spell.ok b/contrib/nvi/docs/interp/spell.ok new file mode 100644 index 000000000000..4ca990c21720 --- /dev/null +++ b/contrib/nvi/docs/interp/spell.ok @@ -0,0 +1,46 @@ +API +BERR +Mapt +Nvi +Perl +SCR +SYSERR +Tcl +VINFO +aline +callback +chp +cmd +cmds +dline +enum +escreen +excmd +freeline +getbuf +getcursor +getline +getmotion +gline +iline +int +interp +iscreen +lenp +linep +lline +lno +lnop +lp +mapt +maptype +movetype +msgq +msgtype +nvi +recno +setcursor +sline +strerror +textp +vicmd diff --git a/contrib/nvi/docs/spell.ok b/contrib/nvi/docs/spell.ok new file mode 100644 index 000000000000..ec854ffa41b4 --- /dev/null +++ b/contrib/nvi/docs/spell.ok @@ -0,0 +1,173 @@ +API's +Amiga +Amir +Bostic +CFLAGS +CR +CTYPE +Cscope +Ctags +DB +DPURIFY +Darren +Ds +Dw +EXINIT +Englar +FreeBSD +GDB +Hiebert +Kirkendall +LC +LN +Linux +Lite +MSDOS +Makefile +Mayoff +NEXINIT +NVI +NetBSD +Neville +Nvi +Nvi's +OS +POSIX +POSIX.2 +Perl +PostScript +README +Roff +Solaris +SunOS +Sven +Tcl +Tk +Todo +USD +USD.doc +USD:14 +USD:15 +USD:16 +UUNET +UX +Verdoolaege +Vi +Vi's +WindowsNT +ags +al +american +api +autowrite +berkeley +bitstring +bitstring.h +bostic +bsd +bugs.current +ccil +changelog +cl +clib +cont +cs +cs.berkeley.edu +cscope +csh +cshrc +ctags +darren +db +dbopen +devel +doc +docs +edu +elvis +email +enum +escapetime +esr +execl +exrc +exref +fcntl +filesystem +free's +ftp.cs.berkeley.edu +gdb +gdb.script +gvr +gz +gzip'd +hardtabs +hiwaay +html +http +ic +iclower +ignorecase +il +init +init.tcl +iso +isprint +kB +keystrokes +ksh +lang +ld +lt +lu +mmap +ncurses +nex +nexrc +nul's +nvi +nvi's +nvi.ALPHA.tar.gz +nvi.tar.Z +nvi.tar.gz +openmode +org +perl +preformatted +ps +queue.h +readonly +recover.script +redistributable +regex +remapped +setenv +settable +shiftwidth +sirsi +slowopen +sourced +struct +sunsite +svi +tcl +tclapi +terminfo +tk +tknvi +txt +ucb +unc +uunet +version's +vi +vi's +vi.man +vi.ref +vi.ref.ps +vi.ref.txt +vitut +writeable +www +xaw +ynq diff --git a/contrib/nvi/docs/tutorial/vi.advanced b/contrib/nvi/docs/tutorial/vi.advanced new file mode 100644 index 000000000000..f757ad19c44a --- /dev/null +++ b/contrib/nvi/docs/tutorial/vi.advanced @@ -0,0 +1,1458 @@ +Section 26: Index to the rest of the tutorial + +The remainder of the tutorial can be perused at your leisure. Simply find the +topic of interest in the following list, and {/Section xx:/^M} to get to the +appropriate section. (Remember that ^M means the return key) + +The material in the following sections is not necessarily in a bottom up +order. It should be fairly obvious that if a section mentions something with +which you are not familiar, say, buffers, you might {/buffer/^M} followed by +several {n} to do a keyword search of the file for more details on that item. +Another point to remember is that commands are surrounded by curly-braces and +can therefore be found rather easily. To see where, say, the X command is +used try {/{X}/^M}. Subsequent {n} will show you other places the command was +used. We have tried to maintain the convention of placing the command letter +surrounded by curly-braces on the section line where that command is +mentioned. + +Finally, you should have enough 'savvy' at this point to be able to do your +own experimentation with commands without too much hand-holding on the part of +the tutorial. Experimentation is the best way to learn the effects of the +commands. + + Section Topic - description + ------- ------------------- +(Sections 1 through 25 are located in the file vi.beginner.) + 1 introduction: {^F} {ZZ} + 2 introduction (con't) and positioning: {^F} {^B} + 3 introduction (con't) and positioning: {^F} {^B} + 4 positioning: {^F} {^B} ^M (return key) + 5 quitting: {:q!} ^M key + 6 marking, cursor and screen positioning: {m} {G} {'} {z} + 7 marking, cursor and screen positioning: {m} {G} {'} {z} + 8 marking, cursor and screen positioning: {z} {m} {'} + 9 marking and positioning: {m} {''} + 10 line positioning: {^M} {-} + 11 scrolling with {^M} + 12 scrolling with {-} and screen adjustment {z} + 13 notes on use of tutorial + 14 other scrolling and postioning commands: {^E} {^Y} {^D} {^U} + 15 searching: {/ .. /^M} + 16 searching: {? .. ?^M} {n} (in search strings ^ $) + 17 searching: \ and magic-characters in search strings + 18 colon commands, exiting: {:} {ZZ} + 19 screen positioning: {H} {M} {L} + 20 character positioning: {w} {b} {0} {W} {B} {e} {E} {'} {`} + 21 cursor positioning: {l} {k} {j} {h} + 22 adding text: {i} {a} {I} {A} {o} {O} ^[ (escape key) + 23 character manipulation: {f} {x} {X} {w} {l} {r} {R} {s} {S} {J} + 24 undo: {u} {U} + 25 review +(The following sections are in this file.) + 26 Index to the rest of the tutorial ******** YOU ARE HERE ******* + 27 discussion of repeat counts and the repeat command: {.} + 28 more on low-level character motions: {t} {T} {|} + 29 advanced correction operators: {d} {c} + 30 updating the screen: {^R} + 31 text buffers: {"} + 32 rearranging and duplicating text: {p} {P} {y} {Y} + 33 recovering lost lines + 34 advanced file manipulation with vi + 34.1 more than one file at a time: {:n} + 34.2 reading files and command output: {:r} + 34.3 invoking vi from within vi: {:e} {:vi} + 34.4 escaping to a shell: {:sh} {:!} + 34.5 writing parts of a file: {:w} + 34.6 filtering portions of text: {!} + 35 advanced searching: magic patterns + 36 advanced substitution: {:s} + 37 advanced line addressing: {:p} {:g} {:v} + 38 higher level text objects and nroff: ( ) { } [[ ]] + 39 more about inserting text + 40 more on operators: {d} {c} {<} {>} {!} {=} {y} + 41 abbreviations: {:ab} + 42 vi's relationship with the ex editor: {:} + 43 vi on hardcopy terminals and dumb terminals: open mode + 44 options: {:set} {setenv EXINIT} + 44.1 autoindent + 44.2 autoprint + 44.3 autowrite + 44.4 beautify + 44.5 directory + 44.6 edcompatible + 44.7 errorbells + 44.8 hardtabs + 44.9 ignorecase + 44.10 lisp + 44.11 list + 44.12 magic + 44.13 mesg + 44.14 number + 44.15 open + 44.16 optimize + 44.17 paragraphs + 44.18 prompt + 44.19 readonly + 44.20 redraw + 44.21 remap + 44.22 report + 44.23 scroll + 44.24 sections + 44.25 shell + 44.26 shiftwidth + 44.27 showmatch + 44.28 slowopen + 44.29 tabstop + 44.30 tags + 44.31 taglength + 44.32 term + 44.33 terse + 44.34 timeout + 44.35 ttytype + 44.36 warn + 44.37 window + 44.38 wrapscan + 44.39 wrapmargin + 44.40 writeany + 44.41 w300, w1200, w9600 + +Section 27: repetition counts and the repeat command {.} + +Most vi commands will use a preceding count to affect their behavior in some +way. We have already seen how {3x} deletes three characters, and {22G} moves +us to line 22 of the file. For almost all of the commands, one can survive by +thinking of these leading numbers as a 'repeat count' specifying that the +command is to be repeated so many number of times. + +Other commands use the repeat count slightly differently, like the {G} command +which use it as a line number. + +For example: + +{3^D} means scroll down in the file three lines. Subsequent {^D} OR {^U} will +scroll only three lines in their respective directions! + +{3z^M} says put line three of the file at the top of the screen, while {3z.} +says put line three as close to the middle of the screen as possible. + +{50|} moves the cursor to column fifty in the current line. + +{3^F} says move forward 3 screenfulls. This is a repetition count. The +documents advertise that {3^B} should move BACK three screenfulls, but I +can't get it to work. + +Position the cursor on some text and try {3r.}. This replaces three characters +with '...'. However, {3s.....^[} is the same as {3xi.....^[}. + +Try {10a+----^[}. + +A very useful instance of a repetition count is one given to the '.' command, +which repeats the last 'change' command. If you {dw} and then {3.}, you will +delete first one and then three words. You can then delete two more words with +{2.}. If you {3dw}, you will delete three words. A subsequent {.} will delete +three more words. But a subsequent {2.} will delete only two words, not three +times two words. + +Caveat: The author has noticed that any repetition count with {^B} will NOT +work: indeed, if you are at the end of your file and try {3^B} sufficiently +often, the editor will hang you in an infinite loop. Please don't try it: +take my word for it. + +Section 28: {t} {T} {|} + +Position the cursor on line 13 below: + +Line 13: Four score and seven years ago, our forefathers brought ... + +Note that {fv} moves the cursor on/over the 'v' in 'seven'. Do a {0} to return +to the beginning of the line and try a {tv}. The cursor is now on/over the +first 'e' in 'seven'. The {f} command finds the next occurrence of the +specified letter and moves the cursor to it. The {t} command finds the +specified letter and moves the cursor to the character immediately preceding +it. {T} searches backwards, as does {F}. + +Now try {60|}: the cursor is now on the 'o' in 'brought', which is the +sixtieth character on the line. + +Section 29: {d} {c} + +Due to their complexity we have delayed discussion of two of the most powerful +operators in vi until now. Effective use of these operators requires more +explanation than was deemed appropriate for the first half of the tutorial. + +{d} and {c} are called operators instead of commands because they consist of +three parts: a count specification or a buffer specification (see section +#BUFFERS), the {d} or {c}, and the object or range description. We will not +discuss buffers at this stage, but will limit ourselves to count +specifications. Examples speak louder than words: position the cursor at the +beginning of line 14: + +Line 14: Euclid alone has looked on beauty bear. + +Obviously, there is something wrong with this quotation. Type {2fb} to +position the cursor on the 'b' of 'bear'. Now, type {cwbare^[} +and observe the results. The {cw} specifies that the change command {c} is to +operate on a word object. More accurately, it specifies that the range of the +change command includes the next word. + +Position the cursor on the period in Line 14. (one way is to use {f.}) +Now, type {cbbeast^[}. This specifies the range of the change command to be the +previous word (the 'b' reminiscent of the {b} command). If we had wished to +delete the word rather than change it, we would have used the {d} operator, +rather than the {c} operator. + +Position the cursor at the beginning of the line with {0}. Type +{d/look/^M}. The search string specified the range of the delete. +Everything UP TO the word 'looking' was deleted from the line. + +In general, almost any command that would move the cursor will specify a range +for these commands. The most confusing exception to this rule is when {dd} or +{cc} is entered: they refer to the whole line. Following is a summary of the +suffixes (suffices? suffici?) and the ranges they specify: + + suffix will delete{d}/change{c} + ------ ------------------------ + ^[ cancels the command + w the word to the right of the cursor + W ditto, but ignoring punctuation + b the word to the left of the cursor + B ditto, but ignoring punctuation + e see below. + E ditto + (space) a character + $ to the end of the line + ^ to the beginning of the line + / .. / up to, but not including, the string + ? .. ? back to and including the string + fc up to and including the occurrence of c + Fc back to and including the occurrence of c + tc up to but not including the occurrence of c + Tc back to but not including the occurrence of c + ^M TWO lines (that's right: two) + (number)^M that many lines plus one + (number)G up to and including line (number) + ( the previous sentence if you are at the beginning of + the current sentence, or the current sentence up to where + you are if you are not at the beginning of the current + sentence. Here, 'sentence' refers to the intuitive + notion of an English sentence, ending with '!', '?', + or '.' and followed by an end of line or two spaces. + ) the rest of the current sentence + { analogous to '(', but in reference to paragraphs: + sections of text surrounded by blank lines + } analogous to ')', but in reference to paragraphs + [[ analogous to '(', but in reference to sections + ]] analogous to ')', but in reference to sections + H the first line on the screen + M the middle line on the screen + L the last line on the screen + 3L through the third line from the bottom of the screen + ^F forward a screenful + ^B backward a screenful + : + : etc. etc. etc. + +This list is not exhaustive, but it should be sufficient to get the idea +across: after the {c} or {d} operator, you can specify a range with another +move-the-cursor command, and that is the region of text over which the command +will be effective. + +Section 30: updating the screen {^R} + +Vi tries to be very intelligent about the type of terminal you are working on +and tries to use the in-terminal computing power (if any) of your terminal. +Also if the terminal is running at a low baud rate (say 1200 or below), vi sets +various parameters to make things easier for you. For example, if you were +running on a 300 baud terminal (that's 30 characters per second transmission +rate) not all 24 lines of the screen would be used by vi. In addition, there +is a large portion of the editor keeping track of what your screen currently +looks like, and what it would look like after a command has been executed. Vi +then compares the two, and updates only those portions of the screen that have +changed. + +Furthermore, some of you may have noticed (it depends on your terminal) that +deleting lines or changing large portions of text may leave some lines on the +screen looking like: +@ +meaning that this line of the screen does not correspond to any line in your +file. It would cost more to update the line than to leave it blank for the +moment. If you would like to see your screen fully up-to-date with the +contents of your file, type {^R}. + +To see it in action, delete several lines with {5dd}, type {^R}, and then type +{u} to get the lines back. + +Here is as good a place as any to mention that if the editor is displaying the +end of your file, there may be lines on the screen that look like: +~ +indicating that that screen line would not be affected by {^R}. These lines +simply indicate the end of the file. + +Section 31: text buffers {"} + +Vi gives you the ability to store text away in "buffers". This feature is very +convenient for moving text around in your file. There are a total of thirty- +five buffers available in vi. There is the "unnamed" buffer that is used by all +commands that delete text, including the change operator {c}, the substitute +and replace commands {s} and {r}, as well as the delete operator {d} and delete +commands {x} and {X}. This buffer is filled each time any of these commands +are used. However, the undo command {u} has no effect on the unnamed buffer. + +There are twenty-six buffers named 'a' through 'z' which are available for the +user. If the name of the buffer is capitalized, then the buffer is not +overwritten but appended to. For example, the command {"qdd} will delete one +line and store that line in the 'q' buffer, destroying the previous contents of +the buffer. However, {"Qdd} will delete one line of text and append that line +to the current contents of the 'q' buffer. + +Finally, there are nine buffers named '1' through '9' in which the last nine +deletes are stored. Buffer 1 is the default buffer for the modify commands and +is sometimes called the unnamed buffer. + +To reference a specific buffer, use the double-quote command {"} followed by +the name of the buffer. The next two sections show how buffers can be used to +advantage. + +Section 32: rearranging and duplicating text: {y} {Y} {p} {P} + +Position yourself on line 15 below and {z^M}: + +Line 15: A tree as lovely as a poem ... +Line 16: I think that I shall never see + +Type {dd}. Line 15 has disappeared and been replaced with the empty line (one +with the single character @ on it) or (again depending on your terminal) Line +16 has moved up and taken its place. We could recover Line 15 with an undo +{u} but that would simply return it to its original location. Obviously, the +two lines are reversed, so we want to put line 15 AFTER line 16. This is +simply done with the put command {p}, which you should type now. What has +happened is that {dd} put Line 15 into the unnamed buffer, and the {p} command +retrieved the line from the unnamed buffer. + +Now type {u} and observe that Line 15 disappears again (the put was undone +without affecting the unnamed buffer). Type {P} and see that the capital {P} +puts the line BEFORE the cursor. + +To get Line 15 where it belongs again type {dd}{p}. + +Also in Line 15 note that the words 'tree' and 'poem' are reversed. Using the +unnamed buffer again: {ft}{dw}{ma}{fp}{P}{w}{dw}{`aP} will set things aright +(note the use of the reverse quote). + +The put commands {p} and {P} do not affect the contents of the buffer. +Therefore, multiple {p} or {P} will put multiple copies of the unnamed buffer +into your file. + +Experiment with {d} and {p} on words, paragraphs, etc. Whatever {d} +deletes, {p} can put. + +Position the cursor on Line 17 and {z^M}: + +Line 17: interest apple cat elephant boy dog girl hay farmer + +Our task is to alphabetize the words on line 17. With the named buffers (and a +contrived example) it is quite easy: + +{"idw}{"adw}{"cdw}{"edw}{"bdw}{"ddw}{"gdw}{"hdw}{"fdw} + +stores each of the words in the named buffer corresponding to the first letter +of each of the words ('interest' goes in buffer "i, 'apple' goes in buffer "a, +etc.). Now to put the words in order type: + +{"ap$}{"bp$}{"cp$}{"dp$}{"ep$}{"fp$}{"gp$}{"hp$}{"ip$} + +Notice that, because 'farmer' was at the end of the line, {dw} did not include +a space after it, and that, therefore, there is no space between 'farmer' and +'girl'. This is corrected with {Fg}{i ^[}. + +This example could have been done just as easily with lines as with +words. + +You do not have to delete the text in order to put it into a buffer. If all +you wish to do is to copy the text somewhere else, don't use {d}, rather use +the yank commands {y} or {Y}. {y} is like {d} and {c} - an operator rather +than a command. It, too, takes a buffer specification and a range +specification. Therefore, instead of {dw}{P} to load the unnamed buffer with a +word without deleting the word, use {yw} (yank a word). + +{Y} is designed yank lines, and not arbitrary ranges. That is, {Y} is +equivalent to {yy} (remember that operators doubled means the current line), +and {3Y} is equivalent to {3yy}. + +If the text you yank or modify forms a part of a line, or is an object such as +a sentence which partially spans more than one line, then when you put the text +back, it will be placed after the cursor (or before if you use {P}). If the +yanked text forms whole lines, they will be put back as whole lines, without +changing the current line. In this case, the put acts much like the {o} or {O} +command. + +The named buffers "a through "z are not affected by changing edit files. +However, the unnamed buffer is lost when you change files, so to move text from +one file to another you should use a named buffer. + +Section 33: recovering lost lines + +Vi also keeps track of the last nine deletes, whether you ask for it or not. +This is very convenient if you would like to recover some text that was +accidentally deleted or modified. Position the cursor on line 18 following, +and {z^M}. + + +Line 18: line 1 +Line 19: line 2 +Line 20: line 3 +Line 21: line 4 +Line 22: line 5 +Line 23: line 6 +Line 24: line 7 +Line 25: line 8 +Line 26: line 9 +Type {dd} nine times: now don't cheat with {9dd}! That is totally different. + +The command {"1p} will retrieve the last delete. Furthermore, when the +numbered buffers are used, the repeat-command command {.} will increment the +buffer numbers before executing, so that subsequent {.} will recover all nine +of the deleted lines, albeit in reverse order. If you would like to review the +last nine deletes without affecting the buffers or your file, do an undo {u} +after each put {p} and {.}: + +{"1p}{u}{.}{u}{.}{u}{.}{u}{.}{u}{.}{u}{.}{u}{.}{u}{.} + +will show you all the buffers and leave them and your file intact. + +If you had cheated above and deleted the nine lines with {9dd}, all nine lines +would have been stored in both the unnamed buffer and in buffer number 1. +(Obviously, buffer number 1 IS the unnamed buffer and is just the default +buffer for the modify commands.) + +Section 34: advanced file manipulation: {:r} {:e} {:n} {:w} {!} {:!} + +We've already looked at writing out the file you are editing with the +{:w} command. Now let's look at some other vi commands to make editing +more efficient. + +Section 34.1: more than one file at a time {:n} {:args} + +Many times you will want to edit more than one file in an editing session. +Instead of entering vi and editing the first file, exiting, entering vi and +editing the second, etc., vi will allow you to specify ALL files that you wish +to edit on the invocation line. Therefore, if you wanted to edit file1 and +file2: + +% vi file1 file2 + +will set up file1 for editing. When you are done editing file one, write it +out {:w^M} and then type {:n^M} to get the next file on the list. On large +programming projects with many source files, it is often convenient just to +specify all source files with, say: + +% vi *.c + +If {:n^M} brings in a file that does not need any editing, another {:n^M} +will bring in the next file. + +If you have made changes to the first file, but decide to discard these changes +and proceed to the next file, {:n!^M} forces the editor to discard the current +contents of the editor. + +You can specify a new list of files after {:n}; e.g., {:n f1 f2 f3^M}. This +will replace the current list of files (if any). + +You can see the current list of files being edited with {:args^M}. + +Section 34.2: reading files and command output: {:r} + +Typing {:r fname^M} will read the contents of file fname into the editor and +put the contents AFTER the cursor line. + +Typing {:r !cmd^M} will read the output of the command cmd and place that +output after the cursor line. + +Section 34.3: invoking vi from within vi: {:e} {:vi} + +To edit another file not mentioned on the invocation line, type {:e filename^M} +or {:vi filename^M}. If you wish to discard the changes to the current file, +use the exclamation point after the command, e.g. {:e! filename^M}. + +Section 34.4: escaping to a shell: {:sh} {:!} {^Z} + +Occasionally, it is useful to interrupt the current editing session to perform +a UNIX task. However, there is no need to write the current file out, exit +the editor, perform the task, and then reinvoke the editor on the same file. +One thing to do is to spin off another process. If there are several UNIX +commands you will need to execute, simply create another shell with {:sh^M}. +At this point, the editor is put to sleep and will be reawakened when you log +out of the shell. + +If it is a single command that you want to execute, type {:!cmd^M}, where cmd +is the command that you wish to run. The output of the command will come to +the terminal as normal, and will not be made part of your file. The message +"[Hit return to continue]" will be displayed by vi after the command is +finished. Hitting return will then repaint the screen. Typing another +{:!cmd^M} at this point is also acceptable. + +However, there is a quicker, easier way: type {^Z}. Now this is a little +tricky, but hang in there. When you logged into UNIX, the first program you +began communicating with was a program that is called a "shell" (i.e. it 'lays +over' the operating system protecting you from it, sort of like a considerate +porcupine). When you got your first prompt on the terminal (probably a '%' +character) this was the shell telling you to type your first command. When +you typed {vi filename} for some file, the shell did not go away, it just went +to sleep. The shell is now the parent of vi. When you type {^Z} the editor +goes to sleep, the shell wakes up and says "you rang?" in the form of another +prompt (probably '%'). At this point you are talking to the shell again and +you can do anything that you could before including edit another file! (The +only thing you can't do is log out: you will get the message "There are +stopped jobs.") + +When your business with the shell is done, type {fg} for 'foreground' and the +last process which you ^Z'd out of will be reawakened and the shell will go +back to sleep. I will refer you to the documentation for the Berkeley shell +'csh' for more information on this useful capability. + +Section 34.5: writing parts of a file: {:w} + +The {:w} command will accept a range specifier that will then write only a +selected range of lines to a file. To write this section to a file, position +the cursor on the section line (e.g. {/^Section 34.5:/^M}) and {z^M}. Now type +{^G} to find out the line number (it will be something like "line 513"). Now +{/^Section 34.6:/-1^M} to find the last line of this section, and {^G} to find +its line number (it will be something like 542). To write out this section of +text by itself to a separate file which we will call "sepfile", type +{:510,542w sepfile^M}. If sepfile already exists, you will have to use the +exclamation point: {:1147,1168w! sepfile^M} or write to a different, non- +existent file. + +{:!cat sepfile^M} will display the file just written, and it should be the +contents of this section. + +There is an alternate method of determining the line numbers for the write. +{:set number^M} will repaint the screen with each line numbered. When the file +is written and the numbers no longer needed, {:set nonumber^M} will remove the +numbers, and {^R} will adjust the screen. + +Or, if you remember your earlier lessons about marking lines of text, +mark the beginning and ending lines. Suppose we had used {ma} to mark the +first line of the section and {mb} to mark the last. Then the command +{:'a,'bw sepfile^M} will write the section into "sepfile". In general, +you can replace a line number with the 'name' of a marked line (a single-quote +followed by the letter used to mark the line) + + +Section 34.6: filtering portions of text: {!} + +{!} is an operator like {c} and {d}. That is, it consists of a repetition +count, {!}, and a range specifier. Once the {!} operator is entered in its +entirety, a prompt will be given at the bottom of the screen for a UNIX +command. The text specified by the {!} operator is then deleted and +passed/filtered/piped to the UNIX command you type. The output of the UNIX +command is then placed in your file. For example, place the cursor at the +beginning of the following line and {z^M}: + +ls -l vi.tutorial +********* marks the bottom of the output from the ls command ********** + +Now type {!!csh^M}. The line will be replaced with the output from the ls +command. The {u} command works on {!}, also. + +Here is an extended exercise to display some of these capabilities. When this +tutorial was prepared, certain auxiliary programs were created to aid in its +development. Of major concern was the formatting of sections of the tutorial +to fit on a single screen, particularly the first few sections. What was +needed was a vi command that would 'format' a paragraph; that is, fill out +lines with as many words as would fit in eighty columns. There is no such vi +command. Therefore, another method had to be found. + +Of course, nroff was designed to do text formatting. However, it produces a +'page'; meaning that there may be many blank lines at the end of a formatted +paragraph from nroff. The awk program was used to strip these blank lines from +the output from nroff. Below are the two files used for this purpose: I refer +you to documentation on nroff and awk for a full explanation of their function. +Position the cursor on the next line and {z^M}. + +******** contents of file f ********** +# +nroff -i form.mac | awk "length != 0 { print }" +***** contents of file form.mac ****** +.na +.nh +.ll 79 +.ec +.c2 +.cc +************************************** + +Determine the line numbers of the two lines of file f. They should be +something like 574 and 575, although you better double check: this file is +under constant revision and the line numbers may change inadvertently. Then +{:574,575w f^M}. Do the same for the lines of file form.mac. They will be +approximately 577 and 582. Then {:577,582w form.mac^M}. File f must have +execute privileges as a shell file: {:!chmod 744 f^M}. + +Observe that this paragraph is +rather ratty in appearance. With our newly created files we can +clean it up dramatically. Position the cursor at the beginning +of this paragraph and type the following sequence of +characters +(note that we must abandon temporarily our convention +of curly braces since the command itself contains a curly brace - we +will use square brackets for the nonce): [!}f^M]. + +Here is a brief explanation of what has happened. By typing [!}f^M] we +specified that the paragraph (all text between the cursor and the first blank +line) will be removed from the edit file and piped to a UNIX program called +"f". This is a shell command file that we have created. This shell file runs +nroff, pipes its output to awk to remove blank lines, and the output from awk +is then read back into our file in the place of the old, ratty paragraph. The +file form.mac is a list of commands to nroff to get it to produce paragraphs +to our taste (the right margin is not justified, the line is 79 characters +long, words are not hyphenated, and three nroff characters are renamed to +avoid conflict: note that in this file, the {^G} you see there is vi's display +of the control-G character, and not the two separate characters ^ up-arrow and +G upper-case g). + +This example was created before the existence of the fmt program. I now type +[!}fmt^M] to get the same effect much faster. Actually, I don't type those +six keys each time: I have an abbreviation (which see). + +Section 35: searching with magic patterns + +The documentation available for "magic patterns" (i.e. regular expressions) is +very scanty. The following should explain this possibly very confusing feature +of the editor. This section assumes that the magic option is on. To make +sure, you might want to type {:set magic^M}. + +By "magic pattern" we mean a general description of a piece of text that the +editor attempts to find during a search. Most search patterns consist of +strings of characters that must be matched exactly, e.g. {/card/^M} searches +for a specific string of four characters. Let us suppose that you have +discovered that you consistently have mistyped this simple word as either ccrd +or czrd (this is not so far-fetched for touch typists). You could {/ccrd/^M} +and {n} until there are no more of this spelling, followed by {/czrd/^M} and +{n} until there are no more of these. Or you could {/c.rd/^M} and catch all of +them on the first pass. Try typing {/c.rd/^M} followed by several {n} and +observe the effect. + +Line 27: card cord curd ceard + +When '.' is used in a search string, it has the effect of matching any single +character. + +The character '^' (up-arrow) used at the beginning of a search string means +the beginning of the line. {/^Line 27/^M} will find the example line above, +while {/Line 27/^M} will find an occurrence of this string anywhere in the +line. + +Similarly, {/ the$/^M} will find all occurrences of the word 'the' occurring +at the end of a line. There are several of them in this file. + +Note that {:set nomagic^M} will turn off the special meaning of these magic +characters EXCEPT for '^' and '$' which retain their special meanings at the +beginning and end of a search string. Within the search string they hold no +special meaning. Try {/\/ the$\//^M} and note that the dollar-sign is not the +last character in the search string. Let the dollar-sign be the last +character in the search string, as in {/\/ the$/^M} and observe the result. + +Observe the result of {/back.*file/^M}. This command, followed by sufficient +{n}, will show you all lines in the file that contain both the words 'back' +and 'file' on the same line. The '*' magic character specifies that the +previous regular expression (the '.' in our example) is to be repeatedly +matched zero or more times. In our example we specified that the words 'back' +and 'file' must appear on the same line (they may be parts of words such as +'backwards' or 'workfile') separated by any number (including zero) of +characters. + +We could have specified that 'back' and 'file' are to be words by themselves by +using the magic sequences '\<' or '\>'. E.g. {/\<back\>.*\<file\>/^M}. The +sequence '\<' specifies that this point of the search string must match the +beginning of a word, while '\>' specifies a match at the end of a word. By +surrounding a string with these characters we have specified that they must be +words. + +To find all words that begin with an 'l' or a 'w', followed by an 'a' or an +'e', and ending in 'ing', try {/\<[lw][ea][a-z]*ing\>/^M}. This will match +words like 'learning', 'warning', and 'leading'. The '[..]' notation matches +exactly ONE character. The character matched will be one of the characters +enclosed in the square brackets. The characters may be specified individually +as in [abcd] or a '-' may be used to specify a range of characters as in [a-d]. +That is, [az] will match the letter 'a' OR the letter 'z', while [a-z] will +match any of the lower case letters from 'a' through 'z'. If you would like to +match either an 'a', a '-', or a 'z', then the '-' must be escaped: [a\-z] will +match ONE of the three characters 'a', '-', or 'z'. + +If you wish to find all Capitalized words, try {/\<[A-Z][a-z]*\>/^M}. The +following will find all character sequences that do NOT begin with an +uncapitalized letter by applying a special meaning to the '^' character in +square brackets: {/\<[^a-z][a-z]*\>/^M}. When '^' is the first character of a +square-bracket expression, it specifies "all but these characters". (No +one claimed vi was consistent.) + +To find all variable names (the first character is alphabetic, the remaining +characters are alphanumeric): try {/\<[A-Za-z][A-Za-z0-9]*\>/^M}. + +In summary, here are the primitives for building regular expressions: + + ^ at beginning of pattern, matches beginning of line + $ at end of pattern, matches end of line + . matches any single character + \< matches the beginning of a word + \> matches the end of a word + [str] matches any single character in str + [^str] matches any single character NOT in str + [x-y] matches any character in the ASCII range between x and y + * matches any number (including zero) of the preceding pattern + +Section 36: advanced substitution: {:s} + +The straightforward colon-substitute command looks like the substitute +command of most line-oriented editors. Indeed, vi is nothing more than a +superstructure on the line-oriented editor ex and the colon commands are +simply a way of accessing commands within ex (see section #EX). This gives us +a lot of global file processing not usually found in visual oriented editors. + +The colon-substitute command looks like: {:s/ .. / .. /^M} and will find the +pattern specified after the first slash (this is called the search pattern), +and replace it with the pattern specified after the second slash (called, +obviously enough, the replacement pattern). E.g. position the cursor on line +28 below and {:s/esample/example/^M}: + +Line 28: This is an esample. + +The {u} and {U} commands work for {:s}. The first pattern (the search pattern) +may be a regular expression just as for the search command (after all, it IS a +search, albeit limited to the current line). Do an {u} on the above line, and +try the following substitute, which will do almost the same thing: +{:s/s[^ ]/x/^M}. +Better undo it with {u}. The first pattern {s[^ ]} matches an 's' +NOT followed by a blank: the search therefore ignores the 's'es in 'This' and +'is'. However, the character matched by {[^ ]} must appear in the replacement +pattern. But, in general, we do not know what that character is! (In this +particular example we obviously do, but more complicated examples will follow.) +Therefore, vi (really ex) has a duplication mechanism to copy patterns matched +in the search string into the replacement string. Line 29 below is a copy of +line 28 above so you can adjust your screen. + +Line 29: This is an esample. + +In general, you can nest parts of the search pattern in \( .. \) and refer to +it in the replacement pattern as \n, where n is a digit. The problem outlined +in the previous paragraph is solved with {:s/s\([^ ]\)/x\1/^M}: try it. Here +\1 refers to the first pattern grouping \( .. \) in the search string. + +Obviously, for a single line, this is rather tedious. Where it becomes +powerful, if not necessary, is in colon-substitutes that cover a range of +lines. (See the next section for a particularly comprehensive example.) + +If the entire character sequence matched by the search pattern is needed in +the replacement pattern, then the unescaped character '&' can be used. On +Line 29 above, try {:s/an e.ample/not &/^M}. If another line is to have the +word 'not' prepended to a pattern, then '~' can save you from re-typing the +replacement pattern. E.g. {:s/some pattern/~/^M} after the previous example +would be equivalent to {:s/some pattern/not &/^M}. + +One other useful replacement pattern allows you to change the case of +individual letters. The sequences {\u} and {\l} cause the immediately +following character in the replacement to be converted to upper- or lower-case, +respectively, if this character is a letter. The sequences {\U} and {\L} turn +such conversion on, either until {\E} or {\e} is encountered, or until the end +of the replacement pattern. + +For example, position the cursor on a line: pick a line, any line. Type +{:s/.*/\U&/^M} and observe the result. You can undo it with {u}. + +The search pattern may actually match more than once on a single line. +However, only the first pattern is substituted. If you would like ALL +patterns matched on the line to be substituted, append a 'g' after the +replacement pattern: {:s/123/456/g^M} will substitute EVERY occurrence +on the line of 123 with 456. + +Section 37: advanced line addressing: {:p} {:g} {:v} + +Ex (available through the colon command in vi) offers several methods for +specifying the lines on which a set of commands will act. For example, if you +would like to see lines 50 through 100 of your file: {:50,100p^M} will display +them, wait for you to [Hit return to continue], and leave you on line 100. +Obviously, it would be easier just to do {100G} from within vi. But +what if you would like to make changes to just those lines? Then the +addressing is important and powerful. + +Line 30: This is a text. +Line 31: Here is another text. +Line 32: One more text line. + +The lines above contain a typing error that the author of this tutorial tends +to make every time he attempts to type the word 'test'. To change all of these +'text's into 'test's, try the following: +{:/^Line 30/,/^Line 32/s/text/test/^M}. This finds the beginning and end of +the portion of text to be changed, and limits the substitution to each of the +lines in that range. The {u} command applies to ALL of the substitutions as +a group. + +This provides a mechanism for powerful text manipulations. +And very complicated examples. + +Line 33: This test is a. +Line 34: Here test is another. +Line 35: One line more test. + +The above three lines have the second word out of order. The following command +string will put things right. Be very careful when typing this: it is very +long, full of special characters, and easy to mess up. You may want to +consider reading the following section to understand it before trying the +experiment. Don't worry about messing up the rest of the file, though: the +address range is specified. + +{:/^Line 33/,/^Line 35/s/\([^:]*\): \([^ ]*\) \([^ ]*\) \([^.]*\)/\1: \2 \4 \3/^M} + +There are several things to note about this command string. First of all, the +range of the substitute was limited by the address specification {/^Line +33/,/^Line 35/^M}. It might have been simpler to do {:set number^M} to see the +line numbers directly, and then, in place of the two searches, typed +the line numbers, e.g. {1396,1398}. Or to mark the lines with {ma} and {mb} +and use {'a,'b}. + +Then follows the substitute pattern itself. To make it easier to understand +what the substitute is doing, the command is duplicated below with the various +patterns named for easier reference: + + s/\([^:]*\): \([^ ]*\) \([^ ]*\) \([^.]*\)/\1: \2 \4 \3/ + |--\1---| |--\2---| |--\3---| |--\4---| + |--------search pattern------------------|-replacement| + |--pattern---| + +In overview, the substitute looks for a particular pattern made up of +sub-patterns, which are named \1, \2, \3, and \4. These patterns are specified +by stating what they are NOT. Pattern \1 is the sequence of characters that +are NOT colons: in the search string, {[^:]} will match exactly one character +that is not a colon, while appending the asterisk {[^:]*} specifies that the +'not a colon' pattern is to be repeated until no longer satisfied, and +{\([^:]*\)} then gives the pattern its name, in this case \1. Outside of the +specification of \1 comes {: }, specifying that the next two characters must be +a colon followed by a blank. + +Patterns \2 and \3 are similar, specifying character sequences that are +not blanks. Pattern \4 matches up to the period at the end of the line. + +The replacement pattern then consists of specifying the new order of the +patterns. + +This is a particularly complicated example, perhaps the most complicated +in this tutorial/reference. For our small examples, it is obviously +tedious and error prone. For large files, however, it may be the most +efficient way to make the desired modifications. + +(The reader is advised to look at the documentation for awk. This tool is very +powerful and slightly simpler to use than vi for this kind of file +manipulation. But, it is another command language to learn.) + +Many times, you will not want to operate on every line in a certain +range. Rather you will want to make changes on lines that satisfy +certain patterns; e.g. for every line that has the string 'NPS' on it, +change 'NPS' to 'Naval Postgraduate School'. The {:g} addressing +command was designed for this purpose. The example of this paragraph +could be typed as {:g/NPS/s//Naval Postgraduate School/^M}. + +The general format of the command is {:g/(pattern)/cmds^M} and it +works in the following way: all lines that match the pattern +following the {:g} are 'tagged' in a special way. Then each of these +lines have the commands following the pattern executed over them. + +Line 36: ABC rhino george farmer Dick jester lest +Line 37: george farmer rhino lest jester ABC +Line 38: rhino lest george Dick farmer ABC jester + +Type: + +{:g/^Line.*ABC/s/Dick/Harry Binswanger/|s/george farmer/gentleman george/p^M} + +There are several things of note here. First, lines 36, 37, and 38 above are +tagged by the {:g}. Type {:g/^Line.*ABC/p^M} to verify this. Second, there +are two substitutes on the same line separated by '|'. In general, any colon +commands can be strung together with '|'. Third, both substitutes operate on +all three lines, even though the first stubstitute works on only two of the +lines (36 and 38). Fourth, the second substitute works on only two lines (36 +and 37) and those are the two lines printed by the trailing 'p'. + +The {:v} command works similarly to the {:g} command, except that the sense of +the test for 'tagging' the lines is reversed: all lines NOT matching the search +pattern are tagged and operated on by the commands. + +Using {^V} to quote carriage return (see section 39) can be used in global +substitutions to split two lines. For example, the command +{:g/\. /s//.^V^M/g^M} will change your file so that each sentence is on a +separate line. (Note that we have to 'escape' the '.', because '.' by itself +matches any character. Our command says to find any line which contains a +period followed by 2 spaces, and inserts a carriage return after the period.) + +Caveat: In some of the documentation for ex and vi you may find the +comment to the effect that {\^M} can be used between commands following +{:g}. The author of this tutorial has never gotten this to work and has +crashed the editor trying. + +Section 38: higher level text objects and nroff: {(} {)} [{] [}] {[[} {]]} + +(Note: this section may be a little confusing because of our command +notation. Using curly braces to surround command strings works fine as +long as the command string does not contain any curly braces itself. +However, the curly braces are legitimate commands in vi. Therefore, for +any command sequence that contains curly braces, we will surround that +sequence with SQUARE braces, as on the previous Section line.) + +In working with a document, particularly if using the text formatting +programs nroff or troff, it is often advantageous to work in terms of +sentences, paragraphs, and sections. The operations {(} and {)} move to +the beginning of the previous and next sentences, respectively. Thus +the command {d)} will delete the rest of the current sentence; likewise +{d(} will delete the previous sentence if you are at the beginning of +the current sentence, or, if you are not at the beginning of a sentence, +it will delete the current sentence from the beginning +up to where you are. + +A sentence is defined to end at a '.', '!', or '?' which is followed +by either the end of a line, or by two spaces. Any number of closing +')', ']', '"', and ''' characters may appear after the '.', '!', or '?' +before the spaces or end of line. Therefore, the {(} and {)} commands +would recognize only one sentence in the following line, but two +sentences on the second following line. + +Line 39: This is one sentence. Even though it looks like two. +Line 40: This is two sentences. Because it has two spaces after the '.'. + +The operations [{] and [}] move over paragraphs and the operations {[[} +and {]]} move over sections. + +A paragraph begins after each empty line, and also at each of a set of nroff +paragraph macros. A section begins after each line with a form-feed ^L in the +first column, and at each of a set of nroff section macros. When preparing a +text file as input to nroff, you will probably be using a set of nroff macros +to make the formatting specifications easier, or more to your taste. These +macros are invoked by beginning a line with a period followed by the one or two +letter macro name. Vi has been programmed to recognize these nroff macros, and +if it doesn't recognize your particular macro you can use the {:set paragraphs} +or {:set sections} commands so that it will. + +Section 39: more about inserting text + +There are a number of characters which you can use to make correnctions +during input mode. These are summarized in the following table. + + ^H deletes the last input character + ^W deletes the last input word + (erase) same as ^H; each terminal can define its own erase character; + for some it is ^H, for others it is the DELETE key, and for + others it is '@'. + (kill) deletes the input on this line; each terminal can define its + own line-kill character; for some it is ^U, for others it is + '@'; you will need to experiment on your terminal to find + out what your line-kill and erase characters are. + \ escapes a following ^H, (kill), and (erase) characters: i.e. + this is how to put these characters in your file. + ^[ escape key; ends insertion mode + ^? the delete key; interrupts an insertion, terminating it + abnormally. + ^M the return key; starts a new line. + ^D backtabs over the indentation set by the autoindent option + 0^D backtabs over all indentation back to the beginning of the line + ^^D (up-arrow followed by control-d)same as 0^D, except the indentation + will be restored at the beginning of the next line. + ^V quotes the next non-printing character into the file + +If you wish to type in your erase or kill character (say # or @ or ^U) then you +must precede it with a \, just as you would do at the normal system command +level. A more general way of typing non-printing characters into the file is +to precede them with a ^V. The ^V echoes as a ^ character on which the cursor +rests. This indicates that the editor expects you to type a control character +and it will be inserted into the file at that point. There are a few +exceptions to note. The implementation of the editor does not allow the null +character ^@ to appear in files. Also the linefeed character ^J is used by the +editor to separate lines in the file, so it cannot appear in the middle of a +line. (Trying to insert a ^M into a file, or putting it in the replacement +part of a substitution string will result in the matched line being split in +two. This, in effect, is how to split lines by using a substitution.) You can +insert any other character, however, if you wait for the editor to echo the ^ +before you type the character. In fact, the editor will treat a following +letter as a request for the corresponding control character. This is the only +way to type ^S or ^Q, since the system normally uses them to suspend and resume +output and never gives them to the editor to process. + +If you are using the autoindent option you can backtab over the indent which it +supplies by typing a ^D. This backs up to the boundary specified by the +shiftwidth option. This only works immediately after the supplied autoindent. + +When you are using the autoindent option you may wish to place a label at the +left margin of a line. The way to do this easily is to type ^ (up-arrow) and +then ^D. The editor will move the cursor to the left margin for one line, and +restore the previous indent on the next. You can also type a 0 followed +immediately by a ^D if you wish to kill all indentation and not have it resume +on the next line. + +Section 40: more on operators: {d} {c} {<} {>} {!} {=} {y} + +Below is a non-exhaustive list of commands that can follow the operators +to affect the range over which the operators will work. However, note +that the operators {<}, {>}, {!}, and {=} do not operate on any object +less than a line. Try {!w} and you will get a beep. To get the +operator to work on just the current line, double it. E.g. {<<}. + + suffix will operate on + ------ ------------------------ + ^[ cancels the command + w the word to the right of the cursor + W ditto, but ignoring punctuation + b the word to the left of the cursor + B ditto, but ignoring punctuation + e see below. + E ditto + (space) a character + $ to the end of the line + ^ to the beginning of the line + / .. / up to, but not including, the string + ? .. ? back to and including the string + fc up to and including the occurrence of c + Fc back to and including the occurrence of c + tc up to but not including the occurrence of c + Tc back to but not including the occurrence of c + ^M TWO lines (that's right: two) + (number)^M that many lines plus one + (number)G up to and including line (number) + ( the previous sentence if you are at the beginning of + the current sentence, or the current sentence up to where + you are if you are not at the beginning of the current + sentence. Here, 'sentence' refers to the intuitive + notion of an English sentence, ending with '!', '?', + or '.' and followed by an end of line or two spaces. + ) the rest of the current sentence + { analogous to '(', but in reference to paragraphs: + sections of text surrounded by blank lines + } analogous to ')', but in reference to paragraphs + [[ analogous to '(', but in reference to sections + ]] analogous to ')', but in reference to sections + H the first line on the screen + M the middle line on the screen + L the last line on the screen + 3L through the third line from the bottom of the screen + ^F forward a screenful + ^B backward a screenful + : + : etc. etc. etc. + +This list is not exhaustive, but it should be sufficient to get the idea +across: after the operator, you can specify a range with a move-the-cursor +command, and that is the region of text over which the operator will be +effective. + +Section 41: abbreviations: {:ab} + +When typing large documents you may find yourself typing a large phrase +over and over. Vi gives you the ability to specify an abbreviation for +a long string such that typing the abbreviation will automatically +expand into the longer phrase. + +Type {:ab nps Naval Postgraduate School^M}. Now type: + +{iThis is to show off the nps's UNIX editor.^M^[} + +Section 42: vi's relationship with the ex editor: {:} + +Vi is actually one mode of editing within the editor ex. When you are +running vi you can escape to the line oriented editor of ex by giving +the command {Q}. All of the colon-commands which were introduced above +are available in ex. Likewise, most ex commands can be invoked from vi +using {:}. + +In rare instances, an internal error may occur in vi. In this case you +will get a diagnostic and will be left in the command mode of ex. You can +then save your work and quit if you wish by giving the command {x} after +the colon prompt of ex. Or you can reenter vi (if you are brave) by +giving ex the command {vi}. + +Section 43: vi on hardcopy terminals and dumb terminals: open mode + +(The author has not checked the following documentation for accuracy. It is +abstracted from the Introduction to Vi Editing document.) + +If you are on a hardcopy terminal or a terminal which does not have a cursor +which can move off the bottom line, you can still use the command set of vi, +but in a different mode. When you give the vi command to UNIX, the editor will +tell you that it is using open mode. This name comes from the open command in +ex, which is used to get into the same mode. + +The only difference between visual mode (normal vi) and open mode is the way in +which the text is displayed. + +In open mode the editor uses a single line window into the file, and moving +backward and forward in the file causes new lines to be displayed, always below +the current line. Two commands of vi work differently in open: {z} and {^R}. +The {z} command does not take parameters, but rather draws a window of context +around the current line and then returns you to the current line. + +If you are on a hardcopy terminal, the {^R} command will retype the current +line. On such terminals, the editor normally uses two lines to represent the +current line. The first line is a copy of the line as you started to edit it, +and you work on the line below this line. When you delete characters, the +editor types a number of \'s to show you the characters which are deleted. The +editor also reprints the current line soon after such changes so that you can +see what the line looks like again. + +It is sometimes useful to use this mode on very slow terminals which can +support vi in the full screen mode. You can do this by entering ex and using +an {open} command. + +********************************************************************* +Section 44: options: {:set} {setenv EXINIT} + +You will discover options as you need them. Do not worry about them very much +on the first pass through this document. My advice is to glance through them, +noting the ones that look interesting, ignoring the ones you don't understand, +and try re-scanning them in a couple of weeks. + +If you decide that you have a favorite set of options and would like to change +the default values for the editor, place a {setenv EXINIT} command in your +.login file. When you are given an account under UNIX your directory has +placed in it a file that is executed each time you log in. If one of the +commands in this file sets the environment variable EXINIT to a string of vi +commands, you can have many things done for you each time you invoke vi. For +example, if you decide that you don't like tabstops placed every eight columns +but prefer every four columns, and that you wish the editor to insert linefeeds +for you when your typing gets you close to column 72, and you want +autoindentation, then include the following line in your .login file: + +setenv EXINIT='set tabstop=4 wrapmargin=8 autoindent' + +or equivalently + +setenv EXINIT='se ts=4 wm=8 ai' + +Each time you bring up vi, this command will be executed and the options set. + +There are forty options in the vi/ex editor that the user can set for his/her +own convenience. They are described in more detail in individual sections +below. The section line will show the full spelling of the option name, the +abbreviation, and the default value of the option. The text itself +comes from the ex reference manual and is not the epitome of clarity. + +Section 44.1: {autoindent}, {ai} default: noai + +Can be used to ease the preparation of structured program text. At the +beginning of each append, change or insert command or when a new line is opened +or created by an append, change, insert, or substitute operation within open or +visual mode, ex looks at the line being appended after, the first line changed +or the line inserted before and calculates the amount of white space at the +start of the line. It then aligns the cursor at the level of indentation so +determined. + +If the user then types lines of text in, they will continue to be justified at +the displayed indenting level. If more white space is typed at the beginning +of a line, the following line will start aligned with the first non-white +character of the previous line. To back the cursor up to the preceding tab +stop one can hit {^D}. The tab stops going backwards are defined at multiples +of the shiftwidth option. You cannot backspace over the indent, except by +sending an end-of-file with a {^D}. A line with no characters added to it +turns into a completely blank line (the white space provided for the autoindent +is discarded). Also specially processed in this mode are lines beginning with +an up-arrow `^' and immediately followed by a {^D}. This causes the input to +be repositioned at the beginning of the line, but retaining the previous indent +for the next line. Similarly, a `0' followed by a {^D} repositions at the +beginning but without retaining the previous indent. Autoindent doesn't happen +in global commands or when the input is not a terminal. + +Section 44.2: {autoprint}, {ap} default: ap + +Causes the current line to be printed after each delete, copy, join, move, +substitute, t, undo or shift command. This has the same effect as supplying a +trailing `p' to each such command. Autoprint is suppressed in globals, and +only applies to the last of many commands on a line. + +Section 44.3: {autowrite}, {aw} default: noaw + +Causes the contents of the buffer to be written to the current file if you have +modified it and give a next, rewind, stop, tag, or {!} command, or a control- +up-arrow {^^} (switch files) or {^]} (tag goto) command in visual. Note, that +the edit and ex commands do not autowrite. In each case, there is an +equivalent way of switching when autowrite is set to avoid the autowrite +({edit} for next, rewind! for rewind, stop! for stop, tag! for tag, shell +for {!}, and {:e #} and a {:ta!} command from within visual). + +Section 44.4: {beautify}, {bf} default: nobeautify + +Causes all control characters except tab ^I, newline ^M and form-feed ^L to be +discarded from the input. A complaint is registered the first time a backspace +character is discarded. Beautify does not apply to command input. + +Section 44.5: {directory}, {dir} default: dir=/tmp + +Specifies the directory in which ex places its buffer file. If this directory +in not writable, then the editor will exit abruptly when it fails to be able to +create its buffer there. + +Section 44.6: {edcompatible} default: noedcompatible + +Causes the presence or absence of g and c suffixes on substitute commands to be +remembered, and to be toggled by repeating the suffices. The suffix r makes +the substitution be as in the {~} command, instead of like {&}. + +[Author's note: this should not concern users of vi.] + +Section 44.7: {errorbells}, {eb} default: noeb + +Error messages are preceded by a bell. However, bell ringing in open and +visual modes on errors is not suppressed by setting noeb. If possible the +editor always places the error message in a standout mode of the terminal (such +as inverse video) instead of ringing the bell. + +Section 44.8: {hardtabs}, {ht} default: ht=8 + +Gives the boundaries on which terminal hardware tabs are set (or on which the +system expands tabs). + +Section 44.9: {ignorecase}, {ic} default: noic + +All upper case characters in the text are mapped to lower case in regular +expression matching. In addition, all upper case characters in regular +expressions are mapped to lower case except in character class specifications +(that is, character in square brackets). + +Section 44.10: {lisp} default: nolisp + +Autoindent indents appropriately for lisp code, and the {(}, {)}, [{], [}], +{[[}, and {]]} commands in open and visual modes are modified in a +striaghtforward, intuitive fashion to have meaning for lisp. + +[Author's note: but don't ask me to define them precisely.] + +Section 44.11: {list} default: nolist + +All printed lines will be displayed (more) unambiguously, showing tabs as ^I +and end-of-lines with `$'. This is the same as in the ex command {list}. + +Section 44.12: {magic} default: magic for {ex} and {vi}, nomagic for edit. + +If nomagic is set, the number of regular expression metacharacters is greatly +reduced, with only up-arrow `^' and `$' having special effects. In addition +the metacharacters `~' and `&' of the replacement pattern are treated as normal +characters. All the normal metacharacters may be made magic when nomagic is +set by preceding them with a `\'. + +[Author's note: In other words, if magic is set a back-slant turns the magic +off for the following character, and if nomagic is set a back-slant turns the +magic ON for the following character. And, no, we are not playing Dungeons and +Dragons, although I think the writers of these option notes must have played it +all the time.] + +Section 44.13: {mesg} default: mesg + +Causes write permission to be turned off to the terminal while you are in +visual mode, if nomesg is set. + +[Author's note: I don't know if anyone could have made any one sentence +paragraph more confusing than this one. What it says is: mesg allows people to +write to you even if you are in visual or open mode; nomesg locks your terminal +so they can't write to you and mess up your screen.] + +Section 44.14: {number, nu} default: nonumber + +Causes all output lines to be printed with their line numbers. In addition +each input line will be prompted with its line number. + +Section 44.15: {open} default: open + +If {noopen}, the commands open and visual are not permitted. This is set for +edit to prevent confusion resulting from accidental entry to open or visual +mode. + +[Author's note: As you may have guessed by now, there are actually three +editors available under Berkeley UNIX that are in reality the same +program, ex, with different options set: ex itself, vi, and edit.] + +Section 44.16: {optimize, opt} default: optimize + +Throughput of text is expedited by setting the terminal to not do automatic +carriage returns when printing more than one (logical) line of output, greatly +speeding output on terminals without addressable cursors when text with leading +white space is printed. + +[Author's note: I still don't know what this option does.] + +Section 44.17: {paragraphs, para} default: para=IPLPPPQPP LIbp + +Specifies the paragraphs for the [{] and [}] operations in open and visual. +The pairs of characters in the option's value are the names of the nroff macros +which start paragraphs. + +Section 44.18: {prompt} default: prompt + +Command mode input is prompted for with a `:'. + +[Author's note: Doesn't seem to have any effect on vi.] + +Section 44.19: {readonly}, {ro} default: noro, unless invoked with -R + or insufficient privileges on file + +This option allows you to guarantee that you won't clobber your file by +accident. You can set the option and writes will fail unless you use an `!' +after the write. Commands such as {x}, {ZZ}, the autowrite option, and in +general anything that writes is affected. This option is turned on if you +invoke the editor with the -R flag. + +Section 44.20: {redraw} default: noredraw + +The editor simulates (using great amounts of output), an intelligent terminal +on a dumb terminal (e.g. during insertions in visual the characters to the +right of the cursor position are refreshed as each input character is typed). +Useful only at very high baud rates, and should be used only if the system is +not heavily loaded: you will notice the performance degradation yourself. + +Section 44.21: {remap} default: remap + +If on, macros are repeatedly tried until they are unchanged. For example, if o +is mapped to O, and O is mapped to I, then if remap is set, o will map to I, +but if noremap is set, it will map to O . + +Section 44.22: {report} default: report=5 for ex and vi, 2 for edit + +Specifies a threshold for feedback from commands. Any command which modifies +more than the specified number of lines will provide feedback as to the scope +of its changes. For commands such as global, open, undo, and visual which have +potentially more far reaching scope, the net change in the number of lines in +the buffer is presented at the end of the command, subject to this same +threshold. Thus notification is suppressed during a global command on the +individual commands performed. + +Section 44.23: {scroll} default: scroll=1/2 window + +Determines the number of logical lines scrolled when a {^D} is received from a +terminal in command mode, and determines the number of lines printed by a +command mode z command (double the value of scroll). + +[Author's note: Doesn't seem to affect {^D} and {z} in visual (vi) mode.] + +Section 44.24: sections {sections} default: sections=SHNHH HU + +Specifies the section macros from nroff for the {[[} and {]]} operations in +open and visual. The pairs of characters in the options's value are the names +of the macros which start paragraphs. + +Section 44.25: {shell}, {sh} default: sh=/bin/sh + +Gives the path name of the shell forked for the shell escape command `!', and +by the shell command. The default is taken from SHELL in the environment, if +present. + +[Editor's note: I would suggest that you place the following line in +your .login file: +setenv SHELL '/bin/csh' +] + +Section 44.26: {shiftwidth}, {sw} default: sw=8 + +Used in reverse tabbing with {^D} when using autoindent to append text, and +used by the shift commands. Should probably be the same value as the tabstop +option. + +Section 44.27: {showmatch}, {sm} default: nosm + +In open and visual mode, when a `)' or `}' is typed, if the matching `(' or `{' +is on the screen, move the cursor to it for one second. Extremely useful with +complicated nested expressions, or with lisp. + +Section 44.28: {slowopen}, {slow} default: terminal dependent + +Affects the display algorithm used in visual mode, holding off display updating +during input of new text to improve throughput when the terminal in use is both +slow and unintelligent. See "An Introduction to Display Editing with Vi" for +more details. + +Section 44.29: {tabstop}, {ts} default: ts=8 + +The editor expands tabs ^I to tabstop boundaries in the display. + +Section 44.30: {taglength}, {tl} default: tl=0 + +Tags are not significant beyond this many characters. +A value of zero (the default) means that all characters are significant. + +Section 44.31: {tags} default: tags=tags /usr/lib/tags + +A path of files to be used as tag files for the tag command. A requested tag +is searched for in the specified files, sequentially. By default files called +tags are searched for in the current directory and in /usr/lib (a master file +for the entire system). + +[Author's note: The author of this tutorial has never used this option, nor +seen it used. I'm not even sure I know what they are talking about.] + +Section 44.32: {term} default: from environment variable TERM + +The terminal type of the output device. + +Section 44.33: {terse} default: noterse + +Shorter error diagnostics are produced for the experienced user. + +Section 44.34: {timeout} default: timeout + +Causes macros to time out after one second. Turn it off and they will +wait forever. This is useful if you want multi-character macros, but if +your terminal sends escape sequences for arrow keys, it will be +necessary to hit escape twice to get a beep. + +[Editor's note: Another paragraph which requires a cryptographer.] + +Section 44.35: ttytype + +[Editor's note: I have found no documentation for this option at all.] + +Section 44.36: {warn} default: warn + +Warn if there has been `[No write since last change]' before a `!' command +escape. + +Section 44.37: {window} default: window=speed dependent + +The number of lines in a text window in the visual command. The default is 8 +at slow speeds (600 baud or less), 16 at medium speed (1200 baud), and the full +screen (minus one line) at higher speeds. + +Section 44.38: {wrapscan}, {ws} default: ws + +Searches using the regular expressions in addressing will wrap around past the +end of the file. + +Section 44.39: {wrapmargin}, {wm} default: wm=0 + +Defines a margin for automatic wrapover of text during input in open and visual +modes. The numeric value is the number of columns from the right edge of the +screen around which vi looks for a convenient place to insert a new-line +character (wm=0 is OFF). This is very convenient for touch typists. +Wrapmargin behaves much like fill/nojustify mode does in nroff. + +Section 44.40: {writeany}, {wa} default: nowa + +Inhibit the checks normally made before write commands, allowing a write to any +file which the system protection mechanism will allow. + +Section 44.41: {w300}, {w1200}, {w9600} defaults: w300=8 + w1200=16 + w9600=full screen minus one + +These are not true options but set the default size of the window for when the +speed is slow (300), medium (1200), or high (9600), respectively. They are +suitable for an EXINIT and make it easy to change the 8/16/full screen rule. + +Section 45: Limitations + +Here are some editor limits that the user is likely to encounter: + 1024 characters per line + 256 characters per global command list + 128 characters per file name + 128 characters in the previous inserted and deleted text in open or + visual + 100 characters in a shell escape command + 63 characters in a string valued option + 30 characters in a tag name + 250000 lines in the file (this is silently enforced). + +The visual implementation limits the number of macros defined with map to 32, +and the total number of characters in macros to be less than 512. + +[Editor's note: these limits may not apply to versions after 4.1BSD.] diff --git a/contrib/nvi/docs/tutorial/vi.beginner b/contrib/nvi/docs/tutorial/vi.beginner new file mode 100644 index 000000000000..3bf35ac939f8 --- /dev/null +++ b/contrib/nvi/docs/tutorial/vi.beginner @@ -0,0 +1,741 @@ +Section 1: {^F} {ZZ} + +To get out of this tutorial, type: ZZ (two capital Z's). + +Learning a new computer system implies learning a new text editor. These +tutorial lessons were created by Dain Samples to help you come to grips with +UC Berkeley's screen oriented editor called vi (for VIsual). This tutorial +uses the vi editor itself as the means of presentation. + +For best use of this tutorial, read all of a screen before performing any of +the indicated actions. This tutorial (or, at least, the first half of it) has +been designed to systematically present the vi commands IF THE INSTRUCTIONS +ARE FOLLOWED! If you are too adventuresome, you may find yourself lost. If +you ever find yourself stuck, remember the first line of this section. + +OK, now find the control key on your keyboard; it usually has CTL or CTRL +written on its upper surface. Your first assignment is to hold the control +key down while you press the 'F' key on your keyboard. Please do so now. + + + +Section 2: {^F} {^B} +Many of vi's commands use the control key and some other key in combination, +as with the control and the 'F' key above. This is abbreviated CTL-F, or ^F. + +As you have probably guessed by now, ^F (CTL-F) moves you forward a fixed +number of lines in the file. Throughout the remainder of the tutorial when +you are ready to advance to the next section of text, hit ^F. + +The opposite command is ^B. Just for fun, you might want to try a ^B to see +the previous section again. Be sure to do a ^F to return you here. + +Determine what the cursor looks like on your screen. Whatever it is (a box, +an underscore, blinking, flashing, inverse, etc.) it should now be positioned +in the upper left-hand corner of your screen under or on the S of Section. +Become familiar with your cursor: to use vi correctly it is important to +always know where the cursor is. + +Did you notice that when you do a ^F the cursor is left at the top of the +screen, and a ^B leaves the cursor near the bottom of the screen? Try the two +commands ^B^F again. And now do another ^F to see the next section. + +Section 3: {^F} {^B} +You now have two basic commands for examining a file, both forwards (^F) and +backwards (^B). + +Note that these are vi text editing commands: they are not commands for the +tutorial. Indeed, this tutorial is nothing but a text file which you are now +editing. Everything you do and learn in this tutorial will be applicable to +editing text files. + +Therefore, when you are editing a file and are ready to see more of the text, +entering ^F will get you to the next section of the file. Entering ^B will +show you the previous section. + +Time for you to do another ^F. + + + + + + + +Section 4: {^F} {^B} {^M} (return key) +We will adopt the notation of putting commands in curly braces so we can write +them unambiguously. For example, if you are to type the command sequence +"control B control F" (as we asked you to do above) it would appear as {^B^F}. +This allows clear delineation of the command strings from the text. Remember +that the curly braces are NOT part of the command string you are to type. Do +NOT type the curly braces. + +Sometimes, the command string in the curly braces will be rather long, and may +be such that the first couple of characters of the command will erase from +the screen the string you are trying to read and type. It is suggested that +you write down the longer commands BEFORE you type them so you won't forget +them once they disappear. + +Now locate the return key on your keyboard: it is usually marked 'RETURN', +indicate hitting the return key. In fact, the control-M key sequence is +exactly the same as if you hit the return key, and vice versa. + +Now type {^F}. + + +Section 5: {:q!} {ZZ} {^M} (return key) +Recognize that this tutorial is nothing more than a text file that you +are editing. This means that if you do something wrong, it is possible +for you to destroy the information in this file. Don't worry. If this +happens, type {ZZ} (two capital Z's) or {:q!^M} to leave the tutorial. +Restart the tutorial. Once in the tutorial, you can then page forward +with {^F} until you are back to where you want to be. (There are +easier ways to do this, some of which will be discussed later, but this +is the most straightforward.) + +You may want to write these commands down in a convenient place for quick +reference: {:q!^M} and {ZZ} + +We will assume that you now know to do a {^F} to advance the file + + + + + + + +Section 6: {m} {G} {'} {z} +Now that you know how to get around in the file via ^F and ^B let's look at +other ways of examining a text file. Sometimes it is necessary, in the midst +of editing a file, to examine another part of the file. You are then faced +with the problem of remembering your place in the file, looking at the other +text, and then getting back to your original location. Vi has a 'mark' +command, m. Type {mp}. You have just 'marked' your current location in the +file and given it the name 'p'. The command string below will do three +things: position you at the beginning of the file (line 1), then return you to +the location 'p' that you just marked with the 'm' command, and, since the +screen will not look exactly the same as it does right now, the 'z' command +will reposition the screen. (You may want to write the string down before +typing it: once you type {1G} it will no longer be on the screen.) + +So now type {1G'pz^M} - a one followed by a capital G, followed by the quote +mark, followed by a lower case 'p', then a lower case 'z', then a return +(which is the same as a ^M). The {1G} moves you to line 1, i.e. the beginning +of the file. The {'p} moves you to the location you marked with {mp}. The +{z^M} command will repaint the screen putting the cursor at the top of the +screen. (Now {^F}.) + +Section 7: {m} {G} {'} {z} +Let's look at some variations on those commands. If you wanted to look at +line 22 in the file and return to this location you could type {mp22G'p}. Do +so now, observing that {22G} puts your cursor at the beginning of section 2 in +the middle of the screen. + +Also note that, without the {z^M} command, the line with 'Section 7' on it is +now in the MIDDLE of the screen, and not at the top. Our cursor is on the +correct line (where we did the {mp} command) but the line is not where we +might like it to be on the screen. That is the function of the {z^M} command. +(Remember, ^M is the same as the 'return' key on your keyboard.) Type {z^M} +now and observe the effect. + +As you can see, the 'Section 7' line is now at the top of the screen with the +cursor happily under the capital S. If you would like the cursor line (i.e. +the line which the cursor is on) in the middle of the screen again, you would +type {z.}. If you wanted the cursor line to be at the BOTTOM of the screen, +type {z-}. Try typing {z-z.z^M} and watch what happens. + +{^F} + +Section 8: {z} {m} {'} + +Note that the z command does not change the position of our cursor in the file +itself, it simply moves the cursor around on the screen by moving the contents +of the file around on the screen. The cursor stays on the same line of the +file when using the z command. + +This brings up an important point. There are two questions that the users of +vi continually need to know the answer to: "Where am I in the file?" and +"Where am I on the screen?" The cursor on your terminal shows the answer to +both questions. Some commands will move you around in the file, usually +changing the location of the cursor on the screen as well. Other commands +move the cursor around on the screen without changing your location in the +file. + +Now type {ma}. Your location in the file has been given the name 'a'. If you +type {'p'a} you will see the previous location we marked in section 7, and +then will be returned to the current location. (You will want to do a {z^M} +to repaint the screen afterwards.) Try it. +{^F} + +Section 9: {m} {''} +Now we can move about in our file pretty freely. By using the {m} command we +can give the current cursor position a lower-case-character name, like 'p', +'a', 'e', 'm', or 'b'. Using the {G} command preceded by a line number we can +look at any line in the file we like. Using the single quote command {'} +followed by a character used in an {m} command, we can return to any location +in the file we have marked. + +However, try {m3}, or {mM}. You should hear a beep, or bell. Only lower-case +letters are acceptable to the {m} and {'} commands: numbers, upper-case +letters, and special characters are not acceptable. + +If you type the {'} command with a character that is lower-case alphabetic but +that has not been used in an {m} command, or for which the 'marked' text has +been deleted, you will also get a beep. Try {'i}. You should get a beep +because the command {mi} has never been issued. (Unless you've been +experimenting.) + +The command {''} attempts to return you to the location at which you last +modified some part of your file. However, my experience has been that it is +difficult to predict exactly where you will end up. +Section 10: {^M} {-} +Now do {ma}, marking your position at the top of the screen. Now hit {^M} (or +return) until the cursor is right ... +* <- here, over/under the asterisk. Now +type {mb'a'b} and watch the cursor move from the asterisk to the top of the +screen and back again. + +The {^M} command moves the cursor to the beginning of the next line. Now type +{^M} until the cursor is right ... +* <- here. The command to move the cursor to the beginning of the +previous line is {-}. Practice moving the cursor around on the screen by using +{^M} and {-}. BE CAREFUL to not move the cursor OFF the screen just yet. If +you do, type {'az^M}. + +Now we can move to any line within the screen. Practice moving around in the +file using the {^F}, {^B}, {-}, {^M}, {z}, and {'} commands. When you are +fairly confident that you can get to where you need to be in the file, and +position the cursor on the screen where you want it type {'az^M^F} (which, of +course, moves you back to the beginning of this section, repositions the +cursor at the top of the screen, and advances you to the next section). + +Section 11: scrolling: {^M} +The cursor should now be on the S of 'Section 11', and this should be on the +first line of the screen. If it is not, do {^M} or {-} as appropriate to put +the cursor on the section line, and type {z^M}. + +Type {mc} to mark your place. + +Now type {^M} until the cursor is on the last line of this screen. Now do one +more {^M} and observe the result. This is called scrolling. When you +attempted to move to a line not displayed on the screen, the line at the top of +the screen was 'scrolled off', and a line at the bottom of the screen was +'scrolled on'. The top line with 'Section 11' should no longer be visible. + +Now type {'cz^M} to reset the screen and type {^F} for the next section. + + + + + + + +Section 12: {-} {z} + +The {-} command moves the cursor to the previous line in the file. Now type +{-}, which attempts to move the cursor to the previous line in this file. +However, that line is not on the screen. The resulting action will depend on +your terminal. (Do a {^Mz^M} to reposition the file). On intelligent +terminals (e.g. VT100s, Z19s, Concept 100s), a top line is 'scrolled on' and +the bottom line is 'scrolled off'. Other terminals, however, may not have +this 'reverse scrolling' feature. They will simply repaint the screen with +the cursor line in the middle of the screen. On such terminals it is +necessary to type {z^M} to get the cursor line back to the top of the screen. + + + + + + + + + + +Section 13: +Up until this point, the tutorial has always tried to make sure that the first +line of each screen has on it the section number and a list of the commands +covered in that section. This will no longer be strictly maintained. If you +want the section line at the top of the screen, you now know enough commands to +do it easily: do {^M} or {-} until the cursor is on the section line and +then {z^M}. Also, from this point on, it may not be the case that a {^F} will +put you at the beginning of the next section. Therefore, be aware of where you +are in the file as we look at other commands. You may have to find your way +back to a particular section without any help from the tutorial. If you do not +feel comfortable with this, then it is suggested that you practice moving from +section 1 to section 13, back and forth, using {^M}, {-}, {^F}, and {^B} +commands for a while. + +Also make liberal use of the mark command {m}: if, for example, you make a +habit of using {mz} to mark your current location in the file, then you will +always be able to return to that location with {'z} if the editor does +something strange and you have no idea where you are or what happened. + +And finally, the proscription against experimentation is hereby lifted: play +with the editor. Feel free to try out variations on the commands and move +around in the file. By this time you should be able to recover from any gross +errors. + +Section 14: {^E} {^Y} {^D} {^U} +Let us now look at a few other commands for moving around in the file, and +moving the file around on the screen. Note that the commands we have already +looked at are sufficient: you really don't need any more commands for looking +in a file. The following commands are not absolutely necessary. However, +they can make editing more convenient, and you should take note of their +existence. But it would be perfectly valid to decide to ignore them on this +first pass: you can learn them later when you see a need for them, if you ever +do. + +First, let's clear up some potentially confusing language. In at least one +place in the official document ('An Introduction to Display Editing with Vi' +by William Joy, and Mark Horton, September 1980), the expression "to scroll +down text" means that the cursor is moved down in your file. However, note +that this may result in the text on the screen moving UP. This use of the +word 'scroll' refers to the action of the cursor within the file. However, +another legitimate use of the word refers to the action of the text on the +screen. That is, if the lines on your screen move up toward the top of the +screen, this would be 'scrolling the screen up'. If the lines move down +toward the bottom of the screen, this would be refered to as scrolling down. + +I have tried to maintain the following jargon: 'scrolling' refers to what the +text does on the screen, not to what the cursor does within the file. For the +latter I will refer to the cursor 'moving', or to 'moving the cursor'. I +realize that this is not necessarily consistent with Joy and Horton, but they +were wrong. + +{^E} scrolls the whole screen up one line, keeping the cursor on the same line, +if possible. However, if the cursor line is the first line on the screen, then +the cursor is moved to the next line in the file. Try typing {^E}. + +{^Y} scrolls the screen down one line, keeping the cursor on the same line, if +possible. However, if the cursor line is the last line on the screen, then the +cursor is moved to the previous line in the file. Try it. + +{^D} moves the cursor down into the file, scrolling the screen up. + +{^U} moves the cursor up into the file, also scrolling the screen if the +terminal you are on has the reverse scroll capability. Otherwise the +screen is repainted. + +Note that {^E} and {^Y} move the cursor on the screen while trying to keep the +cursor at the same place in the file (if possible: however, the cursor can +never move off screen), while {^D} and {^U} keep the cursor at the same place +on the screen while moving the cursor within the file. + +Section 15: {/ .. /^M} + +Another way to position yourself in the file is by giving the editor a string +to search for. Type the following: {/Here 1/^M} and the cursor should end up +right ...........................here ^. Now type {/Section 15:/^M} and the +cursor will end up over/on .....................here ^. Now type {//^M} and +observe that the cursor is now over the capital S five lines above this line. +Typing {//^M} several more times will bounce the cursor back and forth between +the two occurrences of the string. In other words, when you type a string +between the two slashes, it is searched for. Typing the slashes with nothing +between them acts as if you had typed the previous string again. + +Observe that the string you type between the two slashes is entered on the +bottom line of the screen. Now type {/Search for x /^M} except replace the 'x' +in the string with some other character, say 'b'. The message "Pattern not +found" should appear on the bottom of the screen. If you hadn't replaced the +'x', then you would have found the string. Try it. + +Section 16: {? .. ?^M} {n} (search strings: ^ $) + +When you surround the sought-for string with slashes as in {/Search/}, the +file is searched beginning from your current position in the file. If the +string is not found by the end of the file, searching is restarted at the +beginning of the file. However, if you do want the search to find the +PREVIOUS rather than the NEXT occurrence of the string, surround the string +with question marks instead of slash marks. + +Below are several occurrences of the same string. +Here 2 Here 2 Here 2 + Here 2 Here 2. +Observe the effect of the following search commands (try them in the +sequence shown): +{/Here 2/^M} {//^M} {??^M} +{/^Here 2/^M} {//^M} {??^M} +{/Here 2$/^M} {//^M} {??^M} + +The first command looks for the next occurrence of the string 'Here 2'. +However the second line of commands looks for an occurrence of 'Here 2' that +is at the beginning of the line. When the up-arrow is the first character of +a search string it stands for the beginning of the line. When the dollar-sign +is the last character of the search string it stands for the end of the line. +Therefore, the third line of commands searches for the string only when it is +at the end of the line. Since there is only one place the string begins a +line, and only one place the string ends the line, subsequent {//^M} and +{??^M} will find those same strings over and over. + +The {n} command will find the next occurrence of the / or ? search +string. Try {/Here 2/^M} followed by several {n} and observe the +effect. Then try {??^M} followed by several {n}. The {n} command +remembers the direction of the last search. It is just a way to save a +few keystrokes. + +Section 17: \ and magic-characters in search strings + +Now type {/Here 3$/^M}. You might expect the cursor to end up +right......^ here. However, you will get "Pattern not found" at the bottom of +the screen. Remember that the dollar-sign stands for the end of the line. +Somehow, you must tell vi that you do not want the end of the line, but a +dollar-sign. In other words, you must take away the special meaning that the +dollar-sign has for the search mechanism. You do this (for any special +character, including the up-arrow ^) by putting a back-slash ('\', not '/') in +front of the character. + +Now try {/Here 3\$/^M} and you should end up nine lines above this one. Try +{//^M} and note that it returns you to the same place, and not to the first +line of this paragraph: the back-slash character is not part of the search +string and will not be found. To find the string in the first line of this +paragraph, type {/Here 3\\\$/^M}. There are three back-slashes: the first takes +away the special meaning from the second, and the third takes away the special +meaning from the dollar-sign. + +Following is a list of the characters that have special meanings in search +strings. If you wish to find a string containing one of these characters, you +will have to be precede the character with a backslash. These characters are +called magic characters because of the fun and games you can have with them +and they can have with you, if you aren't aware of what they do. + + ^ - (up-arrow) beginning of a line + $ - (dollar-sign) end of a line + . - (period) matches any character + \ - (backslant) the escape character itself + [ - (square bracket) for finding patterns (see section #SEARCH) + ] - (square bracket) ditto + * - (asterisk) ditto + +Without trying to explain it here, note that {:set nomagic^M} turns off the +special meanings of all but the ^ up-arrow, $ dollar-sign, and backslash +characters. + +Section 18: {: (colon commands)} {ZZ} + +In this section we will discuss getting into and out of the editor in more +detail. If you are editing a file and wish to save the results the command +sequence {:w^M} writes the current contents of the file out to disk, using the +file name you used when you invoked the editor. That is, if you are at the +command level in Unix, and you invoke vi with {vi foo} where foo is the name +of the file you wish to edit, then foo is the name of the file used by the +{:w^M} command. + +If you are done, the write and quit commands can be combined into a single +command {:wq^M}. An even simpler way is the command {ZZ} (two capital Z's). + +If, for some reason, you wish to exit without saving any changes you have made, +{:q!^M} does the trick. If you have not made any changes, the exclamation +point is not necessary: {:q^M}. Vi is pretty good about not letting you +get out without warning you that you haven't saved your file. + +We have mentioned before that you are currently in the vi editor, editing a +file. If you wish to start the tutorial over from the very beginning, you +could {ZZ}, and then type {vi.tut beginner} in response to the Unix prompt. +This will create a fresh copy of this file for you, which might be necessary +if you accidentally destroyed the copy you were working with. Just do a +search for the last section you were in: e.g. {/Section 18:/^Mz^M}. + +Section 19: {H} {M} {L} + +Here are a few more commands that will move you around on the screen. Again, +they are not absolutely necessary, but they can make screen positioning easier: + +{H} - puts the cursor at the top of the screen (the 'home' position) + +{M} - puts the cursor in the middle of the screen + +{L} - puts the cursor at the bottom of the screen. + +Try typing {HML} and watch the cursor. + +Try typing {5HM5L} and note that 5H puts you five lines from the top of the +screen, and 5L puts you five lines from the bottom of the screen. + +Section 20: {w} {b} {0} {W} {B} {e} {E} {'} {`} + +Up to this point we have concentrated on positioning in the file, and +positioning on the screen. Now let's look at positioning in a line. Put the +cursor at the beginning of the following line and type {z^M}: + +This is a test line: your cursor should initially be at its beginning. + +The test line should now be at the top of your screen. Type {w} several times. +Note that it moves you forward to the beginning of the next word. Now type +{b} (back to the beginning of the word) several times till you are at the +beginning of the line. (If you accidentally type too many {b}, type {w} until +you are on the beginning of the line again.) Type {wwwww} (five w's) and note +that the cursor is now on the colon in the sentence. The lower-case w command +moves you forward one word, paying attention to certain characters such as +colon and period as delimiters and counting them as words themselves. Now +type {0} (zero, not o 'oh'): this moves you to the beginning of the current +line. Now type {5w} and notice that this has the effect of repeating {w} five +times and that you are now back on the colon. Type {0} (zero) again. To +ignore the delimiters and to move to the beginning of the next word using only +blanks, tabs and carriage-returns (these are called white-space characters) to +delimit the words, use the {W} command: upper-case W. {B} takes you back a +word using white-space characters as word delimiters. + +Note that the commands {wbWB} do not stop at the beginning or end of a line: +they will continue to the next word on the next line in the direction specified +(a blank line counts as a word). + +If you are interested in the END of the word, and not the BEGINNING, then use +the {e} and {E} commands. These commands only move forward and there are no +corresponding 'reverse search' commands for the end of a word. + +Also, we have been using the {'} command to move the cursor to a position that +we have previously marked with the {m} command. However, position the cursor +in the middle of a line (any line, just pick one) and type {mk}, marking that +position with the letter k. Now type a few returns {^M} and type {'k}. +Observe that the cursor is now at the beginning of the line that you marked. +Now try {`k}: note that this is the reverse apostrophe, or back-quote, or grave +accent, or whatever you want to call it. Also note that it moves you to the +character that was marked, not just to the line that was marked. + +In addition, the {``} command works just like the {''} command except that you +are taken to the exact character, not just to the line. (I'm still not +sure which exact character, just as I'm still not sure which line.) + +Section 21: {l} {k} {j} {h} + +There are several commands to move around on the screen on a character by +character basis: + +l - moves the cursor one character to the RIGHT +k - moves the cursor UP one line +j - moves the cursor DOWN one line +h - moves the cursor one character to the LEFT + +Section 22: {i} {a} {I} {A} {o} {O} ^[ (escape key) + +For this and following sections you will need to use the ESCAPE key on your +terminal. It is usually marked ESC. Since the escape key is the same as +typing {^[} we will use ^[ for the escape key. + +Probably the most often used command in an editor is the insert command. Below +are two lines of text, the first correct, the second incorrect. Position your +cursor at the beginning of Line 1 and type {z^M}. + +Line 1: This is an example of the insert command. +Line 2: This is an of the insert command. + +To make line 2 look like line 1, we are going to insert the characters +'example ' before the word 'of'. So, now move the cursor so that it is +positioned on the 'o' of 'of'. (You can do this by typing {^M} to move +to the beginning of line 2, followed by {6w} or {wwwwww} to position the cursor +on the word 'of'.) + +Now carefully type the following string and observe the effects: + {iexample ^[} (remember: ^[ is the escape key)} +The {i} begins the insert mode, and 'example ' is inserted into the line: +be sure to notice the blank in 'example '. The ^[ ends insertion mode, +and the line is updated to include the new string. Line 1 should look exactly +like Line 2. + +Move the cursor to the beginning of Line 3 below and type {z^M}: + +Line 3: These lines are examples for the 'a' command. +Line 4: These line are examples for the ' + +We will change line four to look like line three by using the append command. +We need to append an 's' to the word 'line'. Position the cursor on the 'e' +of 'line'. You can do this in several ways, one way is the following: +First, type {/line /^M}. This puts us on the word 'line' in Line 4 +(the blank in the search string is important!). Next, type {e}. The 'e' puts +us at the end of the word. Now, type {as^[ (^[ is the escape character)}. +The 'a' puts us in insert mode, AFTER the current character. We appended the +'s', and the escape ^[ ended the insert mode. + +The difference between {i} (insert) and {a} (append) is that {i} begins +inserting text BEFORE the cursor, and {a} begins inserting AFTER the cursor. + +Now type {Aa' command.^[}. The cursor is moved to the end of the line and the +string following {A} is inserted into the text. Line 4 should now look like +line 3. + +Just as {A} moves you to the end of the line to begin inserting, {I} would +begin inserting at the FRONT of the line. + +To begin the insertion of a line after the cursor line, type {o}. To insert a +line before the cursor line, type {O}. In other words {o123^[} is equivalent +to {A^M123^[}, and {O123^[} is equivalent to {I123^M^[}. The text after the +{o} or {O} is ended with an escape ^[. + +This paragraph contains information that is terminal dependent: you will just +have to experiment to discover what your terminal does. Once in the insert +mode, if you make a mistake in the typing, ^H will delete the previous +character up to the beginning of the current insertion. ^W will delete the +previous word, and one of ^U, @, or ^X will delete the current line (up to the +beginning of the current insertion). You will need to experiment with ^U, @, +and ^X to determine which works for your terminal. + +Section 23: {f} {x} {X} {w} {l} {r} {R} {s} {S} {J} + +Position the cursor at the beginning of line 5 and {z^M}: + +Line 5: The line as it should be. +Line 6: The line as it shouldn't be. + +To make Line 6 like Line 5, we have to delete the 'n', the apostrophe, and the +'t'. There are several ways to position ourselves at the 'n'. Choose +whichever one suits your fancy: + +{/n't/^M} +{^M7w6l} or {^M7w6 } (note the space) +{^M3fn} (finds the 3rd 'n' on the line) + +Now {xxx} will delete the three characters, as will {3x}. + +Note that {X} deletes the character just BEFORE the cursor, as opposed +to the character AT the cursor. + +Position the cursor at line 7 and {z^M}: + +Line 7: The line as it would be. +Line 8: The line as it could be. + +To change line 8 into line 7 we need to change the 'c' in 'could' into a 'w'. +The 'r' (replace) command was designed for this. Typing {rc} is the same as +typing {xic^[} (i.e. delete the 'bad' character and insert the correct +new character). Therefore, assuming that you have positioned the cursor on the +'c' of 'could', the easiest way to change 'could' into 'would' is {rw}. + +If you would like to now change the 'would' into 'should', use the substitute +command, 's': {ssh^[}. The difference between 'r' and 's' is that 'r' +(replace) replaces the current character with another character, while 's' +(substitute) substitutes the current character with a string, ended with an +escape. + +The capital letter version of replace {R} replaces each character by a +character one at a time until you type an escape, ^[. The 'S' command +substitutes the whole line. + +Position your cursor at the beginning of line 9 and {z^M}. + +Line 9: Love is a many splendored thing. +Line 10: Love is a most splendored thing. + +To change line 10 into line 9, position the cursor at the beginning of 'most', +and type {Rmany^[}. + +You may have noticed that, when inserting text, a new line is formed by typing +{^M}. When changing, replacing, or substituting text you can make a new line +by typing {^M}. However, neither {x} nor {X} will remove ^M to make two lines +into one line. To do this, position the cursor on the first of the two lines +you wish to make into a single line and type {J} (uppercase J for 'Join'). + +Section 24: {u} {U} + +Finally, before we review, let's look at the undo command. Position +your cursor on line 11 below and {z^M}. + +Line 11: The quick brown fox jumped over the lazy hound dog. +Line 12: the qwick black dog dumped over the laxy poune fox. + +Type the following set of commands, and observe carefully the effect of each +of the commands: + +{/^Line 12:/^M} {ft} {rT} {fw} {ru} {w} {Rbrown fox^[} {w} {rj} +{fx} {rz} {w} {Rhound dog^[} + +Line 12 now matches line 11. Now type {U} - capital 'U'. And line 12 now +looks like it did before you typed in the command strings. Now type: + +{ft} {rT} {fw} {ru} {^M} {^M} + +and then type {u}: the cursor jumps back to the line containing the second +change you made and 'undoes' it. That is, {U} 'undoes' all the changes on the +line, and {u} 'undoes' only the last change. Type {u} several times and +observe what happens: {u} can undo a previous {u}! + +Caveat: {U} only works as long as the cursor is still on the line. Move the +cursor off the line and {U} will have no effect, except to possibly beep at +you. However, {u} will undo the last change, no matter where it occurred. + +Section 25: review + +At this point, you have all the commands you need in order to make use of vi. +The remainder of this tutorial will discuss variations on these commands as +well as introduce new commands that make the job of editing more efficient. +Here is a brief review of the basic commands we have covered. They are listed +in the order of increasing complexity and/or decreasing necessity (to say that +a command is less necessary is not to say that it is less useful!). These +commands allow you to comfortably edit any text file. There are other +commands that will make life easier but will require extra time to learn, +obviously. You may want to consider setting this tutorial aside for several +weeks and returning to it later after gaining experience with vi and getting +comfortable with it. The convenience of some of the more exotic commands may +then be apparent and worth the extra investment of time and effort +required to master them. + +to get into the editor from Unix: {vi filename} +to exit the editor + saving all changes {ZZ} or {:wq^M} + throwing away all changes {:q!^M} + when no changes have been made {:q^M} +save a file without exiting the editor {:w^M} +write the file into another file {:w filename^M} +insert text + before the cursor {i ...text... ^[} + at the beginning of the line {I ...text... ^[} + after the cursor (append) {a ...text... ^[} + at the end of the line {A ...text... ^[} + after the current line {o ...text... ^[} + before the current line {O ...text... ^[} +delete the character ... + under the cursor {x} + to the left of the cursor {X} +delete n characters {nx} or {nX} (for n a number) +make two lines into one line (Join) {J} +find a string in the file ... + searching forward {/ ...string... /^M} + searching backwards {? ...string... ?^M} +repeat the last search command {n} +repeat the last search command in the + opposite direction {N} +find the character c on this line ... + searching forward {fc} + searching backward {Fc} +repeat the last 'find character' command {;} +replace a character with character x {rx} +substitute a single character with text {s ...text... ^[} +substitute n characters with text {ns ...text... ^[} +replace characters one-by-one with text {R ...text... ^[} +undo all changes to the current line {U} +undo the last single change {u} +move forward in the file a "screenful" {^F} +move back in the file a "screenful" {^B} +move forward in the file one line {^M} or {+} +move backward in the file one line {-} +move to the beginning of the line {0} +move to the end of the line {$} +move forward one word {w} +move forward one word, ignoring punctuation {W} +move forward to the end of the next word {e} +to the end of the word, ignoring punctuation{E} +move backward one word {b} +move back one word, ignoring punctuation {B} +return to the last line modified {''} +scroll a line onto the top of the screen {^Y} +scroll a line onto the bottom of the screen {^E} +move "up" in the file a half-screen {^U} +move "down" in the file a half-screen {^D} +move the cursor to the top screen line {H} +move the cursor to the bottom screen line {L} +move the cursor to the middle line {M} +move LEFT one character position {h} or {^H} +move RIGHT one character position {l} or { } +move UP in the same column {k} or {^P} +move DOWN in the same column {j} or {^N} +mark the current position, name it x {mx} +move to the line marked/named x {'x} +move to the character position named x {`x} +move to the beginning of the file {1G} +move to the end of the file {G} +move to line 23 in the file {23G} +repaint the screen with the cursor line + at the top of the screen {z^M} + in the middle of the screen {z.} + at the bottom of the screen {z-} + +More information on vi can be found in the file vi.advanced, which you can +peruse at your leisure. From UNIX, type {vi.tut advanced^M}. diff --git a/contrib/nvi/docs/tutorial/vi.tut.csh b/contrib/nvi/docs/tutorial/vi.tut.csh new file mode 100755 index 000000000000..01554bc4e5fd --- /dev/null +++ b/contrib/nvi/docs/tutorial/vi.tut.csh @@ -0,0 +1,24 @@ +#!/bin/csh -f +# +# This makes the user's EXINIT variable set to the 'correct' things. +# I don't know what will happen if they also have a .exrc file! +# +# XXX +# Make sure that user is using a 24 line window!!! +# +if ($1 != "beginner" && $1 != "advanced") then + echo Usage: $0 beginner or $0 advanced + exit +endif + +if ($?EXINIT) then + set oexinit="$EXINIT" + setenv EXINIT 'se ts=4 wm=8 sw=4' +endif + +vi vi.{$1} + +onintr: + if ($?oexinit) then + setenv EXINIT "$oexinit" +endif |