1.  Getting started

      This document provides a quick introduction to vi. (Pronounced vee-eye.) You should be running 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 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.

      There is also a short appendix here, which gives for each character the special meanings which this character has in vi. Attached to this document should be a quick reference card. This card summarizes the commands of vi in a very compact format. You should have the card handy while you are learning vi.

1.1.  Specifying terminal type

      Before you can start 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.

       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

      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:

% setenv TERM 2621
This command works with the csh shell. If you are using the standard Bourne shell sh then you should give the commands
$ TERM=2621
$ export TERM

      If you want to arrange to have your terminal type set up automatically when you log in, you can use the tset program. If you dial in on a mime, but often use hardwired ports, a typical line for your .login file (if you use csh) would be

setenv TERM `tset - -d mime`
or for your .profile file (if you use sh)
TERM=`tset - -d mime`
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 mime. Tset is usually used to change the erase and kill characters, too.

1.2.  Editing a file

      After telling the system which kind of terminal you have, you should make a copy of a file you are familiar with, and run vi on this file, giving the command

% vi name
replacing name 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.***

1.3.  The editor's copy: the buffer

      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 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.

1.4.  Notational conventions

      In our examples, input which must be typed as is will be presented in bold face. Text which should be replaced with appropriate input will be given in italics. We will represent special characters in SMALL CAPITALS.

1.5.  Arrow keys

      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 h j k and l keys as cursor positioning keys (these are labelled with arrows on an adm3a).*

      (Particular note for the HP2621: on this terminal the function keys must be shifted (ick) to send to the machine, otherwise they only act locally. Unshifted use will leave the cursor positioned incorrectly.)

1.6.  Special characters: ESC, CR and DEL

      Several of these special characters are very important, so be sure to find them right now. Look on your keyboard for a key labelled ESC or ALT. 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.*** Partially formed commands are cancelled by ESC, and when you insert text in the file you end the text insertion with ESC. 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.

      The CR or RETURN 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.

      Another very useful key is the DEL or RUB 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 DEL or RUB key; try this now.* From now on we will simply refer to hitting the DEL or RUB key as ``sending an interrupt.''**

      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.

1.7.  Getting out of the editor

      After you have worked with this introduction for a while, and you wish to do something else, you can give the command ZZ 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 :q!CR;** 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.