




_I_n_t_r_o_d_u_c_t_i_o_n

        Elvis is a clone of vi/ex, the standard UNIX editor. Elvis supports
     nearly all of the vi/ex commands, in both visual mode and colon mode.

        Like vi/ex, elvis stores most of the  text  in  a  temporary  file,
     instead of RAM. This allows it to edit files that are too large to fit
     in a single process' data space.

        Elvis runs under BSD UNIX, AT&T SysV UNIX, Minix, MS-DOS, and Atari
     TOS.  Ports to other operating systems are being worked on; contact me
     before you start porting it to some other OS,  because  somebody  else
     may have already done it for you.

        Elvis   is   freely  redistributable,  in  either  source  form  or
     executable form.


  _O_v_e_r_v_i_e_w _o_f _E_l_v_i_s

        The user interface of elvis/vi/ex is weird.  There  are  two  major
     comand  modes  in  Elvis,  and  a  few  text input modes as well. Each
     command mode has a command which allows you to  switch  to  the  other
     mode.

        You  will  probably  use  the _v_i_s_u_a_l _c_o_m_m_a_n_d _m_o_d_e most of the time.
     This is the mode that elvis normally starts up in.

        In visual command mode, the entire screen is filled with  lines  of
     text  from  your  file.  Each  keystroke  is interpretted as part of a
     visual command. If you start typing text, it will _n_o_t be inserted,  it
     will  be  treated as part of a command. To insert text, you must first
     give an "insert text" command. This will take some  getting  used  to.
     (An alternative exists. Lookup the "inputmode" option.)

        The  _c_o_l_o_n  _m_o_d_e is quite different. Elvis displays a ":" character
     on the bottom line of the screen, as a prompt. You are  then  expected
     to  type  in  a  command  line  and  hit  the <Return> key. The set of
     commands recognized in the colon mode is different from visual mode's.


















                                    - 1 -








_V_i_s_u_a_l _M_o_d_e _C_o_m_m_a_n_d_s

        Most visual mode commands are one  keystroke  long.  The  following
     table  lists  the  operation  performed  by  each  keystroke, and also
     denotes any options or arguments that it accepts. Notes at the end  of
     the table describe the notation used in this table.

        In  addition  to the keys listed here, your keyboard's "arrow" keys
     will be interpretted as the appropriate cursor movement commands.  The
     same goes for <PgUp> and <PgDn>, if your keyboard has them. There is a
     colon mode command (to be described later) which  will  allow  you  to
     define other keys, such as function keys.

        A tip: visual command mode looks a lot like text input mode. If you
     forget which mode you're in, just hit the <Esc> key. If  elvis  beeps,
     then  you're  in visual command mode. If elvis does not beep, then you
     were in input mode, but by hitting <Esc> you  will  have  switched  to
     visual command mode. So, one way or another, after <Esc> elvis will be
     ready for a command.

command         description                                             type
---------------+-------------------------------------------------------+--------
        ^A      ---
        ^B      Move toward the top of the file by 1 screenful
        ^C      ---
count   ^D      scroll down <count> lines (default 1/2 screen)
count   ^E      scroll up <count> lines
        ^F      move toward the bottom of the file by 1 screenful
        ^G      show file status, and the current line #
count   ^H      move left, like h                                       MOVE
        ^I      ---
count   ^J      move down                                               MOVE
        ^K      ---
        ^L      redraw the screen
count   ^M      move to the front of the next line                      MOVE
count   ^N      move down                                               MOVE
        ^O      ---
count   ^P      move up                                                 MOVE
        ^Q      ---
        ^R      redraw the screen
        ^S      ---
        ^T      ---
count   ^U      scroll up <count> lines (default 1/2 screen)
        ^V      ---
        ^W      ---
        ^X      ---
count   ^Y      scroll down <count> lines
        ^Z      ---
        ESC     ---
        ^\      ---
        ^]      if the cursor is on a tag name, go to that tag
        ^^      ---
        ^_      ---
count   SPC     move right,like l                                       MOVE
         ! mv   run the selected lines thru an external filter program
         " key  select which cut buffer to use next

                                    - 2 -








count    # +    increment a number                                      EDIT
         $      move to the rear of the current line                    MOVE
         %      move to the matching (){}[] character                   MOVE
         &      ---
         ' key  move to a marked line                                   MOVE
count    (      move backward <count> sentences                         MOVE
count    )      move forward <count> sentences                          MOVE
         *      ---
count    +      move to the front of the next line                      MOVE
count    ,      repeat the previous [fFtT] but in the other direction   MOVE
count    -      move to the front of the preceding line                 MOVE
count    .      repeat the previous "edit" command
         / text search forward for a given regular expression           MOVE
         0      if not part of count, move to 1st char of this line     MOVE
         1      part of count
         2      part of count
         3      part of count
         4      part of count
         5      part of count
         6      part of count
         7      part of count
         8      part of count
         9      part of count
         : text run single EX cmd
count    ;      repeat the previous [fFtT] cmd                          MOVE
         < mv   shift text left                                         EDIT
         =      ---
         > mv   shift text right                                        EDIT
         ? text search backward for a given regular expression          MOVE
         @      ---
count    A inp  append at end of the line                               EDIT
count    B      move back Word                                          MOVE
         C inp  change text from the cursor through the end of the line EDIT
         D      delete text from the cursor through the end of the line EDIT
count    E      move end of Word                                        MOVE
count    F key  move leftward to a given character                      MOVE
count    G      move to line #<count> (default is the bottom line)      MOVE
count    H      move to home row (the line at the top of the screen)
count    I inp  insert at the front of the line (after indents)         EDIT
count    J      join lines, to form one big line                        EDIT
         K      look up keyword
count    L      move to last row (the line at the bottom of the screen)
         M      move to middle row
         N      repeat previous search, but in the opposite direction   MOVE
count    O inp  open up a new line above the current line               EDIT
         P      paste text before the cursor
         Q      quit to EX mode
         R inp  overtype                                                EDIT
count    S inp  change lines, like <count>cc
count    T key  move leftward *almost* to a given character             MOVE
         U      Undo all recent changes to the current line
         V      ---
count    W      move forward <count> Words                              MOVE
count    X      delete the character(s) to the left of the cursor       EDIT
count    Y      yank text line(s) (copy them into a cut buffer)
         Z Z    save the file & exit

                                    - 3 -








         [ [    move back 1 section                                     MOVE
         \      ---
         ] ]    move forward 1 section                                  MOVE
         ^      move to the front of the current line (after indent)    MOVE
         _      ---
         ` key  move to a marked character                              MOVE
count    a inp  insert text after the cursor                            EDIT
count    b      move back <count> words                                 MOVE
         c mv   change text                                             EDIT
         d mv   delete text                                             EDIT
count    e      move forward to the end of the current word             MOVE
count    f key  move rightward to a given character                     MOVE
         g      ---
count    h      move left                                               MOVE
count    i inp  insert text at the cursor                               EDIT
count    j      move down                                               MOVE
count    k      move up                                                 MOVE
count    l      move right                                              MOVE
         m key  mark a line or character
         n      repeat the previous search                              MOVE
count    o inp  open a new line below the current line                  EDIT
         p      paste text after the cursor
         q      ---
count    r key  replace <count> chars by a given character              EDIT
count    s inp  replace <count> chars with text from the user           EDIT
count    t key  move rightward *almost* to a given character            MOVE
         u      undo the previous edit command
         v      ---
count    w      move forward <count> words                              MOVE
count    x      delete the character that the cursor's on               EDIT
         y mv   yank text (copy it into a cut buffer)
         z key  scroll current line to the screen's +=top -=bottom .=middle
count    {      move back <count> paragraphs                            MOVE
count    |      move to column <count> (the leftmost column is 1)
count    }      move forward <count> paragraphs                         MOVE
         ~      switch a character between uppercase & lowercase        EDIT
        DEL     ---
--------------------------------------------------------------------------------

count   Many commands may be preceded by a count.  This is a sequence of digits
        representing a decimal number.  For most commands that use a count,
        the command is repeated <count> times.  The count is always optional,
        and usually defaults to 1.

key     Some commands require two keystrokes.  The first key always determines
        which command is to be executed.  The second key is used as a parameter
        to the command.

mv      Six commands (! < > c d y) operate on text between the cursor and some
        other position.  To specify that other position, you are expected to
        follow the command keystroke with a movement command.  Also, you may
        have the command operate on the whole line that the cursor is on by
        typing the command key a second time.

inp     Many commands allow the user to interactively enter text.


                                    - 4 -








EDIT    These commands affect text, and may be repeated by the "." command.

MOVE    These commands move the cursor, and may be used to specify the extent
        of a member of the "mv" class of commands.


  _I_n_p_u_t _M_o_d_e

        You can't type text into your file  directly  from  visual  command
     mode.  Instead,  you must first give a command which will put you into
     input mode. The commands to do this are A/C/I/O/R/S/a/i/o/s.

        The S/s/C/c commands temporarily place a $ at the end of  the  text
     that they are going to change.

        In  input  mode,  all  keystrokes are inserted into the text at the
     cursor's position, except for the following:
            ^A      insert a copy of the last input text
            ^D      delete one indent character
            ^H      (backspace) erase the character before the cursor
            ^L      redraw the screen
            ^M      (carriage return) insert a newline (^J, linefeed)
            ^P      insert the contents of the cut buffer
            ^R      redraw the screen, like ^L
            ^T      insert an indent character
            ^U      backspace to the beginning of the line
            ^V      insert the following keystroke, even if special
            ^W      backspace to the beginning of the current word
            ^Z ^Z   write the file & exit elvis
            ^[      (ESCape) exit from input mode, back to command mode

        Also, on some systems, ^S may stop output, ^Q may  restart  output,
     and  ^C  may  interupt  execution.  ^@  (the  NUL character) cannot be
     inserted.

        The R visual command puts you in overtype mode, which is a slightly
     different form of input mode. In overtype mode, each time you insert a
     character, one of the old characters is deleted from the file.


  _A_r_r_o_w _k_e_y_s _i_n _I_n_p_u_t _M_o_d_e

        The arrow keys can be used to move the cursor in input mode.  (This
     is  an  extension;  the  real  Vi  doesn't support arrow keys in input
     mode.) The <PgUp>, <PgDn>, <Home>, and <End> keys work in input  mode,
     too. The <Delete> key deletes a single character in input mode.

        The  best  thing about allowing arrow keys to work in input mode is
     that as long as you're in input mode, Elvis seems  to  have  a  fairly
     ordinary  user interface. With most other text editors, you are always
     in either insert mode or replace mode, and you can use the arrow  keys
     at  any time to move the cursor. Now, Elvis can act like that, too. In
     fact, with the new "inputmode" option and  the  "control-Z  control-Z"
     input  command,  you may never have to go into visual command mode for
     simple edit sessions.


                                    - 5 -








  _D_i_g_r_a_p_h_s



        Elvis supports digraphs as a way to enter non-ASCII  characters.  A
     digraph  is a character which is composed of two other characters. For
     Elvis, the first character must be an ASCII punctuation character, and
     the  second  can  be  any  other  ASCII  character.  For  example,  an
     apostrophe and the letter i could be defined as a digraph which is  to
     be stored & displayed as an accented i.

        Elvis  has  no built-in digraphs, since there is no single standard
     for extended ASCII character sets. You must explicitly define a custom
     set  of  digraphs  for the non-ASCII characters that your computer (or
     terminal) uses. Digraphs are defined via the ":digraph" command.

        To actually use a digraph, you must first be in  input  mode.  Type
     the  punctuation  character,  then  hit <Backspace>, and then type the
     other character. Elvis will then substitute the non-ASCII character in
     their place.





































                                    - 6 -








_C_o_l_o_n _M_o_d_e _C_o_m_m_a_n_d_s

        To  use  colon  mode  commands, you must switch from visual command
     mode to colon command mode. The visual mode commands to  do  this  are
     ":" for a single colon command, or "Q" for many colon mode commands.

        Lines           command         arguments
        ---------------+---------------+-------------------------------
        [line]          append
                        args            [files]
                        cd              [directory]
                        chdir           [directory]
        [line][,line]   change
        [line][,line]   copy            line
        [line][,line]   debug[!]
        [line][,line]   delete          ["x]
                        digraph[!]      [XX [Y]]
                        edit[!]         [file]
                        ex[!]           [file]
                        file
        [line][,line]   global          /regexp/ command
        [line]          insert
        [line][,line]   join
        [line][,line]   list
                        map[!]          key mapped_to
        [line]          mark            x
                        mkexrc
        [line][,line]   move            line
                        next[!]         [files]
                        Next[!]
                        previous[!]
        [line][,line]   print
        [line]          put             ["x]
                        quit[!]
        [line]          read            file
                        rewind[!]
                        set             [options]
                        source          file
        [line][,line]   substitute      /regexp/replacement/[p][g]
                        tag[!]          tagname
        [line][,line]   to              line
                        undo
                        unmap[!]        key
                        validate[!]
                        version
        [line][,line]   vglobal         /regexp/ command
                        visual
                        wq
        [line][,line]   write[!]        [[>>]file]
                        xit[!]
        [line][,line]   yank            ["x]
        [line][,line]   !               command
        [line][,line]   <
        [line][,line]   =
        [line][,line]   >


                                    - 7 -








  _L_i_n_e _S_p_e_c_i_f_i_e_r_s



        Line  specifiers  are  always  optional. The first line specifer of
     most commands usually defaults to the current line.  The  second  line
     specifer  usually defaults to be the same as the first line specifier.
     Exceptions are :write, :global, and :vglobal, which act on  all  lines
     of the file by default, and :!, which acts on no lines by default.

        Line  specifiers  consist  of an absolute part and a relative part.
     The absolute part of a line specifer may be either  an  explicit  line
     number,  a  mark,  a  dot to denote the current line, a dollar sign to
     denote the last line of the file, or a forward or backward search.

        An explicit line number is simply a decimal number, expressed as  a
     string of digits.

        A  mark  is  typed  in as an apostrophe followed by a letter. Marks
     must be set before they can be used. You can  set  a  mark  in  visual
     command  mode  by  typing "m" and a letter, or you can set it in colon
     command mode via the "mark" command.

        A forward search is typed in as a regular expression surrounded  by
     slash  characters;  searching  begins  at the default line. A backward
     search is typed in as a  regular  expression  surrounded  by  question
     marks; searching begins at the line before the default line.

        If you omit the absolute part, then the default line is used.

        The  relative  part  of  a  line  specifer is typed as a "+" or "-"
     character followed by a decimal number. The  number  is  added  to  or
     subtracted from the absolute part of the line specifier to produce the
     final line number.

        As a special case, the % character may be used to specify all lines
     of  the  file.  It  is roughly equivelent to saying 1,$. This can be a
     handy shortcut.

        Some examples:
            :p              print the current line
            :37p            print line 37
            :'gp            print the line which contains mark g
            :/foo/p         print the next line that contains "foo"
            :$p             print the last line of the file
            :20,30p         print lines 20 through 30
            :1,$p           print all lines of the file
            :%p             print all lines of the file
            :/foo/-2,+4p    print 5 lines around the next "foo"








                                    - 8 -








  _T_e_x_t _E_n_t_r_y _C_o_m_m_a_n_d_s
            [line] append
            [line][,line] change ["x]
            [line] insert

        The (a)ppend command inserts text after the specified line.

        The (i)nsert command inserts text before the specified line.

        The (c)hange command copies the range of lines into a  cut  buffer,
     deletes them, and inserts new text where the old text used to be.

        For  all of these commands, you indicate the end of the text you're
     inserting by hitting ^D or by entering a line which  contains  only  a
     period.


  _C_u_t & _P_a_s_t_e _C_o_m_m_a_n_d_s
            [line][,line] delete ["x]
            [line][,line] yank ["x]
            [line] put[!] ["x]
            [line][,line] copy line
            [line][,line] to line
            [line][,line] move line

        The (d)elete command copies the specified range of lines into a cut
     buffer, and then deletes them.

        The (y)ank command copies the specified range of lines into  a  cut
     buffer, but does *not* delete them.

        The  (pu)t  command  inserts  text  from  a  cut  buffer  after the
     specified line -- or before it if the ! is present.

        The (co)py and (t)o commands yank the specified range of lines  and
     then immediately paste them after some other line.

        The  (m)ove  command  deletes the specified range of lines and then
     immediately pastes them after some other line. If the destination line
     comes  after  the deleted text, then it will be adjusted automatically
     to account for the deleted lines.


  _D_i_s_p_l_a_y _T_e_x_t _C_o_m_m_a_n_d_s
            [line][,line] print
            [line][,line] list

        The (p)rint command displays the specified range of lines.

        The (l)ist command also displays them, but it is  careful  to  make
     control characters visible.






                                    - 9 -








  _G_l_o_b_a_l _O_p_e_r_a_t_i_o_n_s _C_o_m_m_a_n_d_s
            [line][,line] global /regexp/ command
            [line][,line] vglobal /regexp/ command

        The  (g)lobal  command  searches through the lines of the specified
     range (or through the whole file if no range is specified)  for  lines
     that  contain  a given regular expression. It then moves the cursor to
     each of these lines and runs some other command on them.

        The (v)global command is similar, but it searches  for  lines  that
     _d_o_n'_t contain the regular expression.


  _L_i_n_e _E_d_i_t_i_n_g _C_o_m_m_a_n_d_s
            [line][,line] join
            [line][,line] ! program
            [line][,line] <
            [line][,line] >
            [line][,line] substitute /regexp/replacement/[p][g]

        The  (j)oin  command  catenates  all  lines  in the specified range
     together to form one big line. If only a  single  line  is  specified,
     then the following line is catenated onto it.

        The  !  command  runs  an  external  filter  program, and feeds the
     specified range of lines to it's stdin. The lines are then replaced by
     the  output of the filter. A typical example would be ":'a,'z!sort" to
     sort the lines 'a,'z.

        The < and > commands shift the specified range  of  lines  left  or
     right,  normally  by  the  width  of 1 tab character. The "shiftwidth"
     option determines the shifting amount.

        The (s)ubstitute command finds the regular expression in each line,
     and  replaces  it with the replacement text. The "p" option causes the
     altered lines to be printed, and the "g" option permits all  instances
     of  the  regular expression to be found & replaced. (Without "g", only
     the first occurrence in each line is replaced.)


  _U_n_d_o _C_o_m_m_a_n_d
            undo

        The (u)ndo command restores the file to the state it was in  before
     your most recent command which changed text.


  _C_o_n_f_i_g_u_r_a_t_i_o_n & _S_t_a_t_u_s _C_o_m_m_a_n_d_s
            map[!] [key mapped_to]
            unmap[!] key
            digraph[!] [XX [Y]]
            set [options]
            mkexrc
            [line] mark x
            visual
            version

                                    - 10 -








            [line][,line] =
            file
            source file

        The  (ma)p  command allows you to configure Elvis to recognize your
     function keys, and treat them as though they  transmitted  some  other
     sequence of characters. Normally this mapping is done only when in the
     visual command mode, but with the [!] present it will map  keys  under
     all  contexts. When this command is given with no arguments, it prints
     a table showing all mappings currently in effect. When called with two
     arguments,  the  first  is  the sequence that your function key really
     sends, and the second is the sequence that you want Elvis to treat  it
     as having sent.

        The  (unm)ap command removes key definitions that were made via the
     map command.

        The (di)graph command allows you to display  the  set  of  digraphs
     that  Elvis  is  using,  or  add/remove  a digraph. To list the set of
     digraphs, use the digraph command with no arguments. To add a digraph,
     you  should give the digraph command two arguments. The first argument
     is the two ASCII characters that are to be combined; the second is the
     non-ASCII  character  that  they  represent. The non-ASCII character's
     most significant bit is automatically  set  by  the  digraph  command,
     unless  to  append  a  !  to the command name. Removal of a digraph is
     similar to adding a digraph, except that  you  should  leave  off  the
     second argument.

        The  (se)t  command allows you examine or set various options. With
     no arguments, it  displays  the  values  of  options  that  have  been
     changed.  With the single argument "all" it displays the values of all
     options, regardless of whether they've been  explicitly  set  or  not.
     Otherwise, the arguments are treated as options to be set.

        The  (mk)exrc  command  saves  the  current configuration to a file
     called ".exrc" in the current directory.

        The mar(k) command defines a named mark  to  refer  to  a  specific
     place  in  the  file. This mark may be used later to specify lines for
     other commands.

        The (vi)sual command puts the editor into visual mode.  Instead  of
     emulating ex, Elvis will start emulating vi.

        The (ve)rsion command tells you that what version of Elvis this is.

        The  =  command  tells  you  what  line  you  specified, or, if you
     specified a range of lines, it will tell you both  endpoints  and  the
     number of lines included in the range.

        The  (f)ile  command tells you the name of the file, whether it has
     been modified, the number of lines in the file, and the  current  line
     number.




                                    - 11 -








        The (so)urce command reads a sequence of colon mode commands from a
     file, and interprets them.


  _M_u_l_t_i_p_l_e _F_i_l_e _C_o_m_m_a_n_d_s
            args [files]
            next[!] [files]
            Next[!]
            previous[!]
            rewind[!]

        When you invoke Elvis from your shell's command line, any filenames
     that  you  give to Elvis as arguments are stored in the args list. The
     (ar)gs command will display this list, or define a new one.

        The (n)ext command switches from the current file to the  next  one
     in the args list. You may specify a new args list here, too.

        The  (N)ext and (pre)vious commands (they're really aliases for the
     same command) switch from the current file to the  preceding  file  in
     the args list.

        The  (rew)ind  command  switches from the current file to the first
     file in the args list.


  _S_w_i_t_c_h_i_n_g _F_i_l_e_s _C_o_m_m_a_n_d_s
            edit[!] [file]
            tag[!] tagname

        The (e)dit command allows to switch from the current file  to  some
     other file. This has nothing to do with the args list, by the way.

        The (ta)g command looks up a given tagname in a file called "tags".
     This tells it which file the tag is in, and how to  find  it  in  that
     file. Elvis then switches to the tag's file and finds the tag.


  _E_x_i_t _C_o_m_m_a_n_d_s
            quit[!]
            wq
            xit

        The (q)uit command exits from the editor without saving your file.

        The (wq) command writes your file out, then then exits.

        The (x)it command is similar to the (wq) command, except that (x)it
     won't bother to write your file if you haven't modified it.








                                    - 12 -








  _F_i_l_e _I/_O _C_o_m_m_a_n_d_s
            [line] read file
            [line][,line] write[!][[>>]file]

        The (r)ead command gets text from another file and inserts it after
     the specified line.

        The  (w)rite  command writes the whole file, or just part of it, to
     some other file. The !, if  present,  will  permit  the  lines  to  be
     written  even  if  you've  set the readonly option. If you precede the
     filename by >> then the lines will be appended to the file.


  _D_i_r_e_c_t_o_r_y _C_o_m_m_a_n_d_s
            cd [directory]
            chdir [directory]
            shell

        The (cd) and (chd)ir commands (really two names  for  one  command)
     switch the current working directory.

        The (sh)ell command starts an interactive shell.


  _D_e_b_u_g_g_i_n_g _C_o_m_m_a_n_d_s
            [line][,line] debug[!]
            validate[!]

        These  commands  are  only  available if you compile Elvis with the
     -DDEBUG flag.

        The de(b)ug command lists stats for the blocks  which  contain  the
     specified  range  of  lines. If the ! is present, then the contents of
     those blocks is displayed, too.

        The  (va)lidate  command  checks  certain  variables  for  internal
     consistency.  Normally  it doesn't output anything unless it detects a
     problem. With the !, though, it will always produce *some* output.



















                                    - 13 -








_R_e_g_u_l_a_r _E_x_p_r_e_s_s_i_o_n_s

        Elvis uses regular expressions for searching and substututions.


  _S_y_n_t_a_x

        The code for handling regular expressions  is  derived  from  Henry
     Spencer's  regexp  package.  However,  I  have  modified the syntax to
     resemble that of the real vi.

        Elvis' regexp package treats the following  one-  or  two-character
     strings (called meta-characters) in special ways:
            \( \)    Used to control grouping
            ^        Matches the beginning of a line
            $        Matches the end of a line
            \<       Matches the beginning of a word
            \>       Matches the end of a word
            [ ]      Matches any single character inside the brackets
            *        The preceding may be repeated 0 or more times
            +        The preceding may be repeated 1 or more times
            ?        The preceding is optional
            \|       Separates two alternatives

        Anything  else  is  treated  as a normal character which must match
     exactly. The special strings may all be preceded  by  a  backslash  to
     force them to be treated normally.

        For example, "\(for\|back\)ward" will find "forward" or "backward",
     and "\<text\>" will find "text" but not "context".


  _O_p_t_i_o_n_s

        Elvis has two options which affect the way regular expressions  are
     used. These options may be examined or set via the :set command.

        The  first  option is called "[no]magic". This is a boolean option,
     and it is "magic" (TRUE) by default. While in magic mode, all  of  the
     meta-characters behave as described above. In nomagic mode, only ^ and
     $ retain their special meaning.

        The second option is called "[no]ignorecase".  This  is  a  boolean
     option,  and  it  is  "noignorecase"  (FALSE)  by  default.  While  in
     ignorecase mode, the searching mechanism will not distinguish  between
     an  uppercase  letter  and  its  lowercase form. In noignorecase mode,
     uppercase and lowercase are treated as being different.

        Also, the "[no]wrapscan" option affects searches.








                                    - 14 -








  _S_u_b_s_t_i_t_u_t_i_o_n_s

        The :s command has at least two arguments:  a  regular  expression,
     and   a  substitution  string.  The  text  that  matched  the  regular
     expression is replaced by text which is derived from the  substitution
     string.

        Most characters in the substitution string are copied into the text
     literally but a few have special meaning:
            &        Causes a copy of the original text to be inserted
            \1       Inserts a copy of that portion of the original text which
                     matched the first set of \( \) parentheses.
            \2 - \9  Does the same for the second (etc.) pair of \( \).

        These may be preceded by a backslash to force them  to  be  treated
     normally.









































                                    - 15 -








_O_p_t_i_o_n_s

        Options  may  be  set  or examined via the colon command "set". The
     values of options will affect the operation of later commands.

        There are three types of options:  Boolean,  string,  and  numeric.
     Boolean  options  are made TRUE by giving the name of the option as an
     argument to the "set" command; they are made FALSE  by  prefixing  the
     name  with  "no".  For  example, "set autoindent" makes the autoindent
     option TRUE, and "set noautoindent" makes it FALSE.

        To change the value of a string or numeric option, pass  the  "set"
     command  the  name  of  the  option,  followed  by an "=" sign and the
     option's new value. For example, "set tabstop=8" will give the tabstop
     option a value of 8. For string options, you may enclose the new value
     in quotes.

        For convenience, options have both a long descriptive  name  and  a
     short   name   which  is  easy  to  type.  You  may  use  either  name
     interchangably. I like the short names, myself.

Names           Type        Default             Meaning
---------------+-----------+-------------------+--------------------------------
ai, autoindent  Boolean     noai                auto-indent during input
aw, autowrite   Boolean     noaw                auto-write when switching files
ca, charattr    Boolean     noca                interpret \fX sequences
co, columns     Numeric     co=80               width of the screen
dir, directory  String      dir="/usr/tmp"      where tmp files are kept
eb, errorbells  Boolean     eb                  ring bell on error
er, exrefresh   Boolean     er                  write lines indiviually in EX
hf, hideformat  Boolean     hf                  hide text formatter comamnds
ic, ignorecase  Boolean     noic                upper/lowercase match in search
im, inputmode   Boolean     noim                start vi in insert mode?
kt, keytime     Numeric     kt=2                timeout for mapped key entry
kp, keywordprg  String      kp="/usr/bin/ref"   full pathname of shift-K prog
ln, lines       Numeric     ln=25               number of lines on the screen
li, list        Boolean     noli                display lines in "list" mode
ma, magic       Boolean     ma                  use regular expression in search
pa, paragraphs  String      pa="PPppPApa"       names of "paragraph" nroff cmd
ro, readonly    Boolean     noro                prevent overwriting of orig file
re, report      Numeric     re=5                report when 5 or more changes
sc, scroll      Numeric     sc=12               scroll amount for ^U and ^D
se, sections    String      se="SEseSHsh"       names of "section" nroff cmd
sh, shell       String      sh="/bin/sh"        full pathname of the shell
sho, showmode   Boolean     noshowmode          say when we're in input mode
sw, shiftwidth  Numeric     sw=8                shift amount for < and >
ss, sidescroll  Numeric     ss=8                amount of sideways scrolling
sy, sync        Boolean     nosy                call sync() often
ts, tabstop     Numeric     ts=8                width of tab characters
te, term        String      te="?"              name of the termcap entry
vb, vbell       Boolean     vb                  use visible alternative to bell
wa, warn        Boolean     wa                  warn for ! if file modified
wm, wrapmargin  Numeric     wm=0                wrap long lines in input mode
ws, wrapscan    Boolean     ws                  at EOF, searches wrap to line 1



                                    - 16 -








  _a_u_t_o_i_n_d_e_n_t

        During input mode, the autoindent option will cause each added line
     to  begin with the same amount of leading whitespace as the line above
     it. Without autoindent, added lines are initially empty.


  _a_u_t_o_w_r_i_t_e

        When you're editing one file and decide to switch to another -- via
     the  :tag  command,  or :next command, perhaps -- if your current file
     has been modified, then Elvis will normally print an error message and
     refuse to switch.

        However,  if  the autowrite option is on, then Elvis will write the
     modified version of the current file and successfully  switch  to  the
     new file.


  _c_h_a_r_a_t_t_r

        Many  text  formatting  programs allow you to designate portions of
     your text to be underlined, italicized, or boldface by  embedding  the
     special strings \fU, \fI, and \fB in your text. The special string \fR
     marks the end of underlined or boldface text.

        Elvis normally treats those special strings  just  like  any  other
     text.

        However,  if  the  charattr option is on, then Elvis will interpret
     those special strings correctly, to  display  underlined  or  boldface
     text  on the screen. (This only works, of course, if your terminal can
     display underlined and boldface, and if the TERMCAP entry says how  to
     do it.)


  _c_o_l_u_m_n_s

        This  is  a "read only" option. You can't change its value, but you
     can have Elvis print it. It shows how wide your screen is.


  _d_i_r_e_c_t_o_r_y

        Elvis stores text in temporary files. This  option  allows  you  to
     control  which  directory  those  temporary  files will appear in. The
     default is /usr/tmp.

        This option can only be set in a .exrc file; after that, elvis will
     have  already  started making temporary files in some other directory,
     so it would be too late.






                                    - 17 -








  _e_r_r_o_r_b_e_l_l_s

        Elvis normally rings a bell  when  you  do  something  wrong.  This
     option lets you disable the bell.


  _e_x_r_e_f_r_e_s_h

        The  EX mode of Elvis writes many lines to the screen. You can make
     Elvis either write each line to the screen separately, or save up many
     lines and write them all at once.

        The exrefresh option is normally on, so each line is written to the
     screen separately.

        You may wish to turn the exrefresh option off  (:se  noer)  if  the
     "write"  system  call  is costly on your machine, or if you're using a
     windowing environment.  (Windowing  environments  scroll  text  a  lot
     faster when you write many lines at once.)

        This option has no effect in visual command mode or input mode.


  _h_i_d_e_f_o_r_m_a_t

        Many  text  formatters require you to embed format commands in your
     text, on lines  that  start  with  a  "."  character.  Elvis  normally
     displays these lines like any other text, but if the hideformat option
     is on, then format lines are displayed as blank lines.


  _i_g_n_o_r_e_c_a_s_e

        Normally, when Elvis searches for text, it treats uppercase letters
     as being different for lowercase letters.

        When  the  ignorecase  option  is  on,  uppercase and lowercase are
     treated as equal.


  _i_n_p_u_t_m_o_d_e

        This option allows you to have Elvis start up in insert  mode.  You
     can  still  exit  insert  mode  at any time by hitting the ESC key, as
     usual. Usually, this option would be set in your ".exrc" file.


  _k_e_y_t_i_m_e

        The arrow keys of most terminals send a  multi-character  sequence.
     It  takes  a  measurable  amount  of  time  for  these sequences to be
     transmitted. The keytime option allows  you  to  control  the  maximum
     amount  of  time to allow for an arrow key (or other mapped key) to be
     received in full.



                                    - 18 -








        The default keytime value is 2. Because of the way UNIX timekeeping
     works,  the  actual  amount of time allowed will vary slightly, but it
     will always be between 1 and 2 seconds.

        If you set keytime to 1, then the actual  amount  of  time  allowed
     will  be  between  0  and  1  second.  This  will  generally  make the
     keyboard's response be a little faster (mostly for the ESC  key),  but
     on  those  occasions  where the time allowed happens to be closer to 0
     than 1 second, Elvis may fail to allow enough time for an arrow  key's
     sequence to be received fully. Ugh.

        As  a  special  case, you can set keytime to 0 to disable this time
     limit stuff altogether. The big problem here is: If your  arrow  keys'
     sequences  start  with  an  ESC,  then every time you hit your ESC key
     Elvis will wait... and wait... to see if maybe that ESC was part of an
     arrow key's sequence.

        NOTE:  this option is a generalization of the timeout option of the
     real vi.


  _k_e_y_w_o_r_d_p_r_g

        Elvis has a special keyword lookup feature.  You  move  the  cursor
     onto  a  word, and hit shift-K, and Elvis uses another program to look
     up the word and display information about it.

        This option says which program gets run. It should contain the full
     pathname of the program; your whole execution path is _n_o_t checked.

        The  default  value  of  this  option is "/usr/bin/ref", which is a
     program that looks up the definition of a function in C. It  looks  up
     the function name in a file called "refs" which is created by ctags.

        You  can  subtitute  other  programs, such as an English dictionary
     program or the online  manual.  Elvis  runs  the  program,  using  the
     keyword  as its only argument. The program should write information to
     stdout. The program's exit status should be 0, unless you  want  Elvis
     to print "<<< failed >>>".


  _l_i_n_e_s

        This "read only" option shows how many lines you screen has.


  _l_i_s_t

        In  nolist  mode  (the  default), elvis displays text in a "normal"
     manner -- with tabs expanded to an appropriate number of spaces, etc.

        However, sometimes it is useful to have  tab  characters  displayed
     differently.  In  list  mode, tabs are displayed as "^I", and a "$" is
     displayed at the end of each line.



                                    - 19 -








  _m_a_g_i_c

        The search mechanism in Elvis can accept "regular  expressions"  --
     strings in which certain characters have special meaning.

        The  magic  option is normally on, which causes these characters to
     be treated specially.

        If you turn the magic option off (:se noma),  then  all  characters
     except  ^  and  $  are treated literally. ^ and $ retain their special
     meanings regardless of the setting of magic.


  _p_a_r_a_g_r_a_p_h_s

        The { and }  commands  move  the  cursor  forward  or  backward  in
     increments  of  one  paragraph.  Paragraphs  may be separated by blank
     lines, or by a "dot" command  of  a  text  formatter.  Different  text
     formatters  use  different  "dot"  commands. This option allows you to
     configure Elvis to work with your text formatter.

        It is assumed that your formatter uses commands that start  with  a
     "."  character  at  the  front  of  a  line,  and  then have a one- or
     two-character command name.

        The value of the paragraphs option is a string in which  each  pair
     of  characters is one possible form of your text formatter's paragraph
     command.


  _r_e_a_d_o_n_l_y

        Normally, Elvis will let you write back any file to which you  have
     write  permission.  If  you  don't have write permission, then you can
     only write the changed version of the file to a _d_i_f_f_e_r_e_n_t file.

        If you set the readonly option, then Elvis will pretend  you  don't
     have  write  permission  to  _a_n_y  file you edit. It is useful when you
     really only mean to use Elvis to look at a file,  not  to  change  it.
     This way you can't change it accidentally.

        This  option  is  normally  off, unless you use the "view" alias of
     Elvis. "View" is like "vi" except that the readonly option is on.


  _r_e_p_o_r_t

        Commands in Elvis may affect many lines. For commands that affect a
     lot of lines, Elvis will output a message saying what was done and how
     many lines were affected. This option allows you to define what "a lot
     of  lines"  means. The default is 5, so any command which affects 5 or
     more lines will cause a message to be shown.





                                    - 20 -








  _s_c_r_o_l_l

        The ^U and ^D keys normally scroll backward or forward  by  half  a
     screenful,  but  this is adjustable. The value of this option says how
     many lines those keys should scroll by.


  _s_e_c_t_i_o_n_s

        The [[ and ]] commands move  the  cursor  backward  or  forward  in
     increments of 1 section. Sections may be delimited by a { character in
     column 1 (which is useful for C source code) or by  means  of  a  text
     formatter's "dot" commands.

        This  option  allows  you to configure Elvis to work with your text
     formatter's "section" command,  in  exectly  the  same  way  that  the
     paragraphs  option  makes  it  work  with the formatter's "paragraphs"
     command.


  _s_h_e_l_l

        When Elvis forks a shell (perhaps for the :!  or  :shell  commands)
     this  is  the  program  that  is uses as a shell. This is "/bin/sh" by
     default, unless you have  set  the  SHELL  (or  COMSPEC,  for  MS-DOS)
     environment  variable,  it which case the default value is copied from
     the environment.


  _s_h_i_f_t_w_i_d_t_h

        The < and > commands shift text  left  or  right  by  some  uniform
     number  of  columns.  The  shiftwidth  option  defines  that  "uniform
     number". The default is 8.


  _s_h_o_w_m_o_d_e

        In visual mode, it is easy to forget whether you're in  the  visual
     command  mode  or input/replace mode. Normally, the showmode option is
     off, and you haven't a clue as to which mode you're in.  If  you  turn
     the  showmode  option  on, though, a little message will appear in the
     lower right-hand corner of your screen, telling you which mode  you're
     in.


  _s_i_d_e_s_c_r_o_l_l

        For long lines, Elvis scrolls sideways. (This is different from the
     real vi, which wraps a single long  line  onto  several  rows  of  the
     screen.)

        To  minimize  the  number of scrolls needed, Elvis moves the screen
     sideways by several characters at a time. The  value  of  this  option
     says how many characters' widths to scroll at a time.


                                    - 21 -








        Generally,  the  faster  your  screen can be redrawn, the lower the
     value you will want in this option.


  _s_y_n_c

        If the system crashes during an edit session,  then  most  of  your
     work can be recovered from the temporary file that elvis uses to store
     changes. However, sometimes UNIX/Minix will not copy  changes  to  the
     hard disk immediately, so recovery might not be possible. The [no]sync
     option lets you control this.

        In nosync mode (which is the default),  elvis  lets  the  operating
     system  control  when  data  is written to the disk. This is generally
     faster.

        In sync mode, elvis forces all changes out to disk every  time  you
     make a change. This is generally safer, but slower.


  _t_a_b_s_t_o_p

        Tab  characters  are normally 8 characters wide, but you can change
     their widths by means of this option.


  _t_e_r_m

        This "read only" option shows the name of the  termcap  entry  that
     Elvis is using for your terminal.


  _v_b_e_l_l

        If  your  termcap  entry describes a visible alternative to ringing
     your terminal's bell, then this option will say  whether  the  visible
     version gets used or not. Normally it will be.

        If  your  termcap  does NOT include a visible bell capability, then
     the vbell option will be off, and you can't turn it on.


  _w_a_r_n

        If you have modified a file but not yet written it  back  to  disk,
     then  Elvis  will  normally print a warning before executing a ":!cmd"
     command. However, in nowarn mode, this warning is not given.

        Elvis also normally prints a message after a successful search that
     wrapped at EOF. The [no]warn option can also disable this warning.







                                    - 22 -








  _w_r_a_p_m_a_r_g_i_n

        Normally  (with  wrapmargin=0) Elvis will let you type in extremely
     long lines, if you wish.

        However,  with  warpmargin  set   to   something   other   that   0
     (wrapmargin=10  is nice), Elvis will automatically cause long lines to
     be "wrapped" on a  word  break  for  lines  longer  than  wrapmargin's
     setting.


  _w_r_a_p_s_c_a_n

        Normally,  when  you  search  for  something, Elvis will find it no
     matter where it is in the file. Elvis starts at the  cursor  position,
     and  searches  forward.  If Elvis hits EOF without finding what you're
     looking for, then it wraps around to continue searching from line 1.

        If you turn off the wrapscan option (:se  nows),  then  when  Elvis
     hits EOF during a search, it will stop and say so.





































                                    - 23 -








_P_r_o_g_r_a_m_s


  _e_l_v_i_s, _e_x, _v_i, _v_i_e_w, _i_n_p_u_t - _T_h_e _e_d_i_t_o_r
            elvis [flags] [+cmd] [files...]
            -r      tell the user to use "virec" instead
            -R      set the "readonly" option to TRUE
            -t tag  search for a tag
            -e      start up in colon command mode
            -v      start up in visual command mode
            -i  start up in input mode

        The editor itself is called elvis, of course. On systems which pass
     the program name as an argument, such as Unix and Minix, you may  also
     install  elvis  under  the  names  "ex", "vi", and "view". These extra
     names would normally be links to elvis; see the "ln" shell command.

        When elvis is invoked as "vi", it behaves exactly as though it  was
     invoked  as  "elvis". However, if you invoke elvis as "view", then the
     readonly option is set as though you had given it the  "-R"  flag.  If
     you  invoke  elvis  as  "ex",  then  elvis  will start up in the colon
     command mode instead of the visual command mode,  as  though  you  had
     given it the "-e" flag. If you invoke elvis as "input" or "edit", then
     elvis will start up in input mode, as though the "-i" flag was given.

        If you use the "+cmd" parameter,  then  after  the  first  file  is
     loaded  "cmd" is treated like a colon command. A typical example would
     be "elvis +237 foo", which would cause elvis to start editing foo  and
     then move directly to line 237.


  _c_t_a_g_s - _G_e_n_e_r_a_t_e_s "_t_a_g_s" _a_n_d (_o_p_t_i_o_n_a_l_l_y) "_r_e_f_s" _f_i_l_e_s
            ctags [-r] files...
            -r      generate a "refs" file, too

        The  "tags"  file  is  used  by  Elvis'  ":tag"  command, control-]
     command, and -t option. Each C source  file  is  scanned  for  #define
     statements  and  global function definitions. The name of the macro or
     function becomes the name of a tag. For each tag, a line is  added  to
     the "tags" file which contains:
                   - the name of the tag
                   - a tab character
                   - the name of the file containing the tag
                   - a tab character
                   - a way to find the particular line within the file.

        The  "refs" file is used by the "ref" program, which can be invoked
     via Elvis' K command. When ctags finds a global  function  definition,
     it  copies the function header into the "refs" file. The first line is
     flush against the right  margin,  but  the  argument  definitions  are
     indented.  The ref program can search the "refs" file _m_u_c_h faster than
     it could search all of the C source files.





                                    - 24 -








        The filenames list will typically be the  names  of  all  C  source
     files in the current directory, like this:
            $ ctags -r *.[ch]


  _r_e_f - _D_i_s_p_l_a_y _a _C _f_u_n_c_t_i_o_n _h_e_a_d_e_r
            ref function_name

        Ref is a program which looks up the function header of a particular
     function in any of a series of reference files. These reference  files
     are produced by the ctags program.

        Ref is used by vi's shift-K command.

        The list of files checked includes "refs" in the current directory,
     and possibly others. See the source code for an accurate list.


  _v_i_r_e_c - _R_e_c_o_v_e_r _t_h_e _m_o_d_i_f_i_e_d _v_e_r_s_i_o_n _o_f _a _f_i_l_e _a_f_t_e_r _a _c_r_a_s_h
            virec [-d tmpdir] textfilename...
            virec [-d tmpdir] </usr/tmp/viname

        Virec is a program which extracts the most recent version of a text
     file from a temporary file in /usr/tmp.

        When  you  edit  a file with Elvis, only about 5K bytes of the file
     are stored in RAM; the rest is stored in  a  file  in  /usr/tmp.  This
     allows  you  to  edit files larger than a process' data space. It also
     plays a big part in the way that "undo" and "paste" were implemented.

        The virec program basically extracts the "undo"  version  from  the
     file.  This  is  most useful when the system (or Elvis) crashes in the
     middle of a long edit session, because the "undo" version of the  file
     contains  everything  except your last change. Nearly all of your work
     can be salvaged.

        The most common way to invoke virec is this: You  just  give  virec
     the  name of the file you were editing, and it finds the matching file
     in /usr/tmp and writes the newest available version of the  file  over
     the existing version. It then deletes the /usr/tmp file.

        The  other  way,  where  you  redirect  its  stdin  to  come from a
     particular /usr/tmp file, is used when you have either forgotten which
     file  that  is  and  you want to see its contents, or when you want to
     recover the file without  losing  either  the  /usr/tmp  file  or  the
     current version of the text file.











                                    - 25 -








_D_i_f_f_e_r_e_n_c_e_s _b_e_t_w_e_e_n _e_l_v_i_s _a_n_d _t_h_e _r_e_a_l _v_i/_e_x


  _E_x_t_e_n_s_i_o_n_s

   :mkexrc
   :mk

        This  EX  command saves the current :set and :map configurations in
     the ".exrc" file in your current directory.

   :args
   :ar

        You can use the :args command to define a new args list, as in:
            :args *.h

        After you have defined a new args list, the next time you  issue  a
     :next command Elvis will switch to the first file of the new list.

   :Next
   :previous
   :N
   :pre

        These commands move backwards through the args list.

   zz

        In  visual  command  mode, the (lowercase) "zz" command will center
     the current line on the screen, like "z=".

   .

        The default count value for . is the same as the  previous  command
     which . is meant to repeat. However, you can supply a new count if you
     wish. For example, after "3dw", "." will delete 3 words, but "5." will
     delete 5 words.

   ".

        The  text  which  was  most  recently input (via a "cw" command, or
     something similar) is saved in a cut buffer  called  ".  (which  is  a
     pretty hard name to write in an English sentence).

   K

        In  visual  command  mode,  you can move the cursor onto a word and
     press shift-K to have Elvis run a reference program to look that  word
     up.  This command alone is worth the price of admission! See the ctags
     and ref programs.






                                    - 26 -








   #


        In visual command mode, you can move the cursor onto a  number  and
     then  hit ## or #+ to increment that number by 1. To increment it by a
     larger amount, type in the increment value before hitting the  initial
     #.  The  number  can  also  be decremented or set by hitting #- or #=,
     respectively.

   input

        You can backspace past the beginning of the line.

        The arrow keys work in input mode.

        If you type control-A, then the text that you input  last  time  is
     inserted.  You  will  remain  in input mode, so you can backspace over
     part of it, or add more to it. (This is sort of like control-@ on  the
     real vi, except that control-A really works.)

        Control-P will insert the contents of the cut buffer.

        Real  vi can only remember up to 128 characters of input, but Elvis
     can remember any amount.

        The ^T and ^D keys can adjust the indent of a line no matter  where
     the cursor happens to be in that line.

        You  can  save your file and exit Elvis directly from input mode by
     hitting control-Z twice.

        Elvis supports digraphs as a way to enter non-ASCII characters.

   :set inputmode
   :se im

        If you set this flag in your .exrc file, then elvis will  start  up
     in input mode instead of visual command mode.

   :set charattr
   :se ca

        Elvis  can  display "backslash-f" style character attributes on the
     screen as  you  edit.  The  following  example  shows  the  recognized
     atributes:
            normal \fBboldface\fR \fIitalics\fR \fUunderlined\fR normal

        NOTE:  you  must  compile  elvis without the -DNO_CHARATTR flag for
     this to work.

   :set noexrefresh
   :se noer





                                    - 27 -








        Elvis gives you a little more control over how EX mode writes lines
     to the terminal. In exrefresh mode, each line is individually written;
     in noexrefresh mode, Elvis writes several lines at  once.  The  latter
     mode works better on windowing systems.

   :set sync
   :se sy

        After a crash, you can usually recover the altered form of the file
     from the temporary file that Elvis uses. With the sync  option  turned
     on,  the  odds  are  shifted a little more in your favor because Elvis
     will perform a sync() call after each change has been written  to  the
     temporary file.

   cursor shape

        Elvis changes the shape of the cursor to indicate which mode you're
     in,  if  your  terminal's  termcap  entry   includes   the   necessary
     capabilities.

   :set hideformat
   :se hf

        This  option hides format control lines. (They are displayed on the
     screen as blank lines.)


  _O_m_i_s_s_i_o_n_s

        The replace mode is a hack.  It  doesn't  save  the  text  that  it
     overwrites.

        Long  lines  are  displayed  differently -- where the real vi would
     wrap a long line  onto  several  rows  of  the  screen,  Elvis  simply
     displays  part  of  the  line,  and  allows  you  to scroll the screen
     sideways to see the rest of it.

        The ":preserve" and ":recover" commands are missing, as is  the  -r
     flag.  I've  never had a good reason to use ":preserve", and since use
     of ":recover" is so rare, I decided to  implement  it  as  a  separate
     program.  There's  no need to load the recovery code into memory every
     time you edit a file.

        LISP support is missing.

        The "@" and ":@" commands are missing.

        You can't APPEND to a cut buffer. The following DOES NOT WORK:
            "Ayy

        Due to naming conventions used for the temporary files,  Elvis  can
     be creating no more that one new file per directory at any given time.
     Any number of existing files  can  be  edited  at  the  same  time  on
     multitasking  computer  systems,  but only one new file can be created
     simultaneously per directory. To relieve this problem, you would  have
     to edit tmp.c and virec.c

                                    - 28 -








_I_n_t_e_r_n_a_l

        You  don't  need to know the material in this section to use elvis.
     You only need it if you intend to modify elvis.


  _T_h_e _t_e_m_p_o_r_a_r_y _f_i_l_e

        The temporary file is divided into blocks of 1024 bytes each.

        When elvis starts up, the file is copied into the  temporary  file.
     Small  amounts  of extra space are inserted into the temporary file to
     insure that no text lines  cross  block  boundaries;  this  speeds  up
     processing  and  simplifies  storage  management. The "extra space" is
     filled with NUL charcters; the input file must not contain  any  NULs,
     to avoid confusion.

        The  first  block of the temporary file is an array of shorts which
     describe the order of the blocks; i.e. header[1] is the  block  number
     of  the  first block, and so on. This limits the temporary file to 512
     active blocks, so the largest file you can edit is  about  400K  bytes
     long. I hope that's enough!

        When blocks are altered, they are rewritten to a _d_i_f_f_e_r_e_n_t block in
     the file, and the in-core version  of  the  header  block  is  updated
     accordingly.  The in-core header block will be copied to the temp file
     immediately before the next change... or, to undo  this  change,  swap
     the old header (from the temp file) with the new (in-core) header.

        Elvis   maintains   another   in-core   array  which  contains  the
     line-number of the last line in every block. This  allows  you  to  go
     directly to a line, given its line number.


  _I_m_p_l_e_m_e_n_t_a_t_i_o_n _o_f _E_d_i_t_i_n_g

        There are three basic operations which affect text:
            * delete text   - delete(from, to)
            * add text      - add(at, text)
            * yank text     - cut(from, to)

        To  yank text, all text between two text positions is copied into a
     cut buffer. The original text is not changed. To copy the text into  a
     cut  buffer, you need only remember which physical blocks that contain
     the cut text, the offset into the first block of the start of the cut,
     the offset into the last block of the end of the cut, and what kind of
     cut it was. (Cuts may be either character cuts or line cuts; the  kind
     of  a  cut  affects the way it is later "put".) This is implemented in
     the function cut().

        To delete text, you must modify the  first  and  last  blocks,  and
     remove  any  reference to the intervening blocks in the header's list.
     The text to be deleted is specified by two marks. This is  implemented
     in the function delete().



                                    - 29 -








        To   add   text,  you  must  specify  the  text  to  insert  (as  a
     NUL-terminated string) and the place to insert it  (as  a  mark).  The
     block  into which the text is to be inserted may need to be split into
     as many as four blocks, with new intervening blocks needed as  well...
     or  it  could  be  as  simple  as  modifying  a  single block. This is
     implemented in the function add().

        Other interesting functions are paste() (to copy text  from  a  cut
     buffer  into  the file), modify() (for an efficient way to implement a
     combined delete/add sequence), and input() (to get text from the  user
     & insert it into the file).

        When  text  is  modified, an internal file-revision counter, called
     "changes", is incremented. This counter is used to detect when certain
     caches  are  out  of  date. (The "changes" counter is also incremented
     when we switch to a different file, and also in  one  or  two  similar
     situations -- all related to invalidating caches.)


  _M_a_r_k_s _a_n_d _t_h_e _C_u_r_s_o_r

        Marks  are  places within the text. They are represented internally
     as a long variable which is split into two bitfields:  a  line  number
     and  a  character  index.  Line  numbers  start  with 1, and character
     indexes start with 0.

        Since line numbers start with 1, it is impossible for a set mark to
     have a value of 0L. 0L is therefore used to represent unset marks.

        When  you  do the "delete text" change, any marks that were part of
     the deleted text are unset, and any marks  that  were  set  to  points
     after it are adjusted. Similarly, marks are adjusted after new text is
     inserted.

        The cursor is represented as a mark.


  _C_o_l_o_n _C_o_m_m_a_n_d _I_n_t_e_r_p_r_e_t_a_t_i_o_n

        Colon commands are parsed, and the command name is looked up in  an
     array  of structures which also contain a pointer to the function that
     implements the command, and a description of the  arguments  that  the
     command  can  take. If the command is recognized and its arguments are
     legal, then the function is called.

        Each function performs its task; this may cause the  cursor  to  be
     moved to a different line, or whatever.










                                    - 30 -








  _S_c_r_e_e_n _C_o_n_t_r_o_l

        The  screen  is updated via a package which looks like the "curses"
     library,  but  isn't.  It  is  actually  much  simpler.  Most   curses
     operations  are  implemented  as  macros  which copy characters into a
     large I/O buffer, which is then written with a  single  large  write()
     call as part of the refresh() operation.

        The  functions  which  modify  text  remember  where  text has been
     modified;  the  screen  redrawing  function,  redraw(),   needs   this
     information  to help it reduce the amount of text that is redrawn each
     time.


  _P_o_r_t_a_b_i_l_i_t_y

        To improve portability, Elvis  collects  as  much  system-dependent
     definitions  as  possible  in the config.h file. This file begins with
     some  preprocessor  instructions  which  attempt  to  determine  which
     compiler  and  operating system you have. After that, it conditionally
     defines some macros and constants for your system.

        One of the more significant macros is ttyread(buf,n). This macro is
     used  to  read  characters  from  the keyboard. For UNIX systems, this
     simply reads bytes from stdin. For MS-DOS and Atari-TOS, ttyread()  is
     a function defined in curses.c. There is also a ttywrite macro.

        The  tread() and twrite() macros are versions of read() and write()
     that are used for text files. On UNIX systems, these are equivelent to
     read() and write(). On MS-DOS, these are also equivelent to read() and
     write(), since DOS libraries are generally clever  enough  to  convert
     newline  characters  automatically.  For  Atari  TOS,  though, the MWC
     library is too stupid to do this, so  we  had  to  do  the  conversion
     explicitly.

        Other  macros  may  substitute index() for strchr(), or bcopy() for
     memcpy(), or map the (void) data type to (int), or whatever.




















                                    - 31 -








_C_F_L_A_G_S

        Elvis uses many preprocessor symbols to control  compilation.  Some
     of  these  control  the sizes of buffers and such, but the "-DNO_XXXX"
     options remove small sets of related features.

        Most Elvis users will probably want to keep all features available.
     Minix-PC users, though, will have to sacrifice one or two feature sets
     because otherwise Elvis would be too  bulky  to  compile.  The  "asld"
     phase  of  the compiler craps out. Interestingly, the full Elvis would
     probably be able to run under Minix-PC if you could cross-compile  it;
     under  SCO Xenix the ".text" segment is only about 59k bytes long, and
     I would expect the Minix-PC version to be about the same.


  -_D_M__S_Y_S_V, -_D_T_O_S, -_D_O_S_9

        These flags  tell  the  compiler  that  Elvis  is  being  compliled
     System-V  UNIX,  ot  Atari TOS, or OS-9/68000, respectively. For other
     systems, the config.h file can figure it out automatically.


  -_D_D_A_T_E=\'\"`_d_a_t_e`\"\'

        DATE should be defined to be a string constant. It  is  printed  by
     the :version command as the compilation date of the program.

        It  is  only  used  in  cmd1.c,  and  even  there  you may leave it
     undefined without causing an urp.

        The form shown  above  only  works  if  you  use  "eval".  See  the
     Makefile.


  -_D_N_B_U_F_S=_1_0

        Elvis  keeps  most  of  your text in a temporary file; only a small
     amount is actually stored in RAM. This flag allows you to control  how
     much  of  the file can be in RAM at any time. The default is 5k bytes;
     the example above changes that to 10k bytes.

        More RAM allows global changes to happen a little faster. If you're
     just making many small changes in one section of a file, though, extra
     RAM won't help much.


  -_D_B_L_K_S_I_Z_E=_2_0_4_8

        This controls the size of blocks that Elvis  uses  internally.  The
     value  of  BLKSIZE  must be a power of two. The default value is 1024,
     which allows you to edit files up to almost  512K  bytes  long.  Every
     time  you  double  BLKSIZE, you quadruple the size of a text file that
     Elvis can handle, but you  also  cause  the  temporary  file  to  grow
     faster.



                                    - 32 -








  -_D_T_M_P_D_I_R=\"/_t_m_p\"

        This  sets  the  default  value  of  the  "directory" option, which
     specifies where the temporary files should reside. The value of TMPDIR
     must  be a string, so be sure your value includes the quote characters
     on each end.


  -_D_E_X_R_C=\"._e_l_v_i_s_r_c\" -_D_H_M_E_X_R_C=\"_e_l_v_i_s._i_n_i\" -_D_S_Y_S_E_X_R_C=\"/_e_t_c/_e_l_v_i_s_r_c\"

        This lets you control the names of the initialization files.  Their
     values must be strings, so be careful about quoting.

        EXRC  is  the  name  of  the  initialization  file  in  the current
     directory. Its default value is ".exrc" on UNIX systems -- the same as
     the real vi. For other systems, check the config.h file.

        HMEXRC  is  the  name  of  the  initialization  file  in  your home
     directory.  By  default,  it  is  the  same  as   EXRC.   Elvis   will
     automatically prepend the name of your home directory to HMEXRC at run
     time, so don't give a full path name.

        SYSEXRC is the name of a system-wide initialization file. It has no
     default  value; if you don't define a value for it, then the code that
     supports SYSEXRC just isn't compiled. The value of SYSEXRC should be a
     full pathname.


  -_D_K_E_Y_W_O_R_D_P_R_G=\"/_u_s_r/_l_o_c_a_l/_r_e_f\"

        This  flag determines the default value of the "keywordprg" option.
     Its value must be a string, so be careful about quoting.  The  default
     value of this flag is "/usr/bin/ref" on UNIX systems.


  -_D_D_E_B_U_G

        This adds the ":debug" and ":validate" commands, and also adds many
     internal consistency checks. It increases  the  size  of  the  ".text"
     segment by about 5K.


  -_D_N_O__C_H_A_R_A_T_T_R

        Permanently  disables the charattr option. This reduces the size of
     your ".text" segment by about 850 bytes.


  -_D_N_O__R_E_C_Y_C_L_E

        Normally, Elvis will  recycle  space  (from  the  tmp  file)  which
     contains  totally  obsolete  text.  This flag disables this recycling.
     Without recycling, the ".text" segment is about  1K  smaller  than  it
     would  otherwise be, but the tmp file grows much faster. If you have a
     lot of free space on your harddisk, but Elvis is too bulky to run with
     recycling, then try it without recycling.

                                    - 33 -








        When  using  a  version  of  Elvis  that  has  been  compiled  with
     -DNO_RECYCLE, you should be careful to avoid making many small changes
     to  a  file  because each individual change will cause the tmp file to
     grow by at least  1k.  Hitting  "x"  thirty  times  counts  as  thirty
     changes,  but  hitting  "30x"  counts  as one change. Also, you should
     occasionally do a ":w" followed by a ":e" to start with  a  fresh  tmp
     file.


  -_D_N_O__S_E_N_T_E_N_C_E

        Leaves  out  the  "(" and ")" visual mode commands. Also, the "[[",
     "]]", "{", and "}" commands  will  not  recognize  *roff  macros.  The
     sections and paragraphs options go away. This saves about 650 bytes in
     the ".text" segment.


  -_D_N_O__C_H_A_R_S_E_A_R_C_H

        Leaves out the visual commands which locate a  given  character  in
     the  current  line:  "f", "t", "F", "T", "," and ";". This saves about
     900 bytes.


  -_D_N_O__E_X_T_E_N_S_I_O_N_S

        Leaves out  the  :mkexrc  command,  and  the  "K"  and  "#"  visual
     commands.  Also,  the  arrow  keys  will no longer work in input mode.
     (Other extensions are either inherent in the design of elvis,  or  are
     controlled  by  more  specific  flags,  or  are  too  tiny to be worth
     removing.) This saves about 500 bytes.


  -_D_N_O__M_A_G_I_C

        Permanently   disables   the   "magic"   option,   so   that   most
     meta-characters  in  a  regular  expression are *NOT* recognized. This
     saves about 3k of space in the ".text" segment,  because  the  complex
     regular expression code can be replaced by much simpler code.


  -_D_N_O__S_H_O_W_M_O_D_E

        Permanently disables the "showmode" option, saving about 250 bytes.


  -_D_N_O__C_U_R_S_O_R_S_H_A_P_E

        Normally,  Elvis  tries  to  adjust  the  shape  of the cursor as a
     reminder of which mode you're in. The -DNO_CURSORSHAPE  flag  disables
     this, saving about 150 bytes.






                                    - 34 -








  -_D_N_O__D_I_G_R_A_P_H

        To  allow entry of non-ASCII characters, Elvis supports digraphs. A
     digraph is a single  (non-ASCII)  character  which  is  entered  as  a
     combination  of  two  other  (ASCII)  characters. If you don't need to
     input non-ASCII characters, or if your keyboard supports a better  way
     of  entering  non-ASCII  characters,  then you can disable the digraph
     code and save about 450 bytes.

















































                                    - 35 -








_T_e_r_m_c_a_p

        Elvis uses fairly standard termcap capabilities  for  most  things.
     Some  of  the  keyboard  sequences were borrowed from SCO Xenix, and I
     invented some of the character attribute names and all of  the  cursor
     shape names, but other than that there should be no surprises.


  _R_e_q_u_i_r_e_d _n_u_m_e_r_i_c _c_a_p_a_b_i_l_i_t_i_e_s

        :co#:   number of columns on the screen (characters per line)
        :li#:   number of lines on the screen


  _R_e_q_u_i_r_e_d _s_t_r_i_n_g _c_a_p_a_b_i_l_i_t_i_e_s

        :ce=:   clear to end-of-line
        :cl=:   home the cursor & clear the screen
        :cm=:   move the cursor to a given row/column
        :up=:   move the cursor up one line


  _B_o_o_l_e_a_n _c_a_p_a_b_i_l_i_t_i_e_s

        :am:    auto margins - wrap when a char is written to the last column?
        :pt:    physical tabs?


  _O_p_t_i_o_n_a_l _s_t_r_i_n_g _c_a_p_a_b_i_l_i_t_i_e_s

        :al=:   insert a blank row on the screen
        :dl=:   delete a row from the screen
        :cd=:   clear to end of display
        :ei=:   end insert mode
        :ic=:   insert a blank character
        :im=:   start insert mode
        :dc=:   delete a character
        :sr=:   scroll reverse (insert a row at the top of the screen)
        :vb=:   visible bell
        :ti=:   terminal initialization string, to start full-screen mode
        :te=:   terminal termination, to end full-screen mode


  _O_p_t_i_o_n_a_l _s_t_r_i_n_g_s _r_e_c_e_i_v_e_d _f_r_o_m _t_h_e _k_e_y_b_o_a_r_d

        :kd=:   sequence sent by the <down arrow> key
        :kl=:   sequence sent by the <left arrow> key
        :kr=:   sequence sent by the <right arrow> key
        :ku=:   sequence sent by the <up arrow> key
        :PU=:   sequence sent by the <PgUp> key
        :PD=:   sequence sent by the <PgDn> key
        :HM=:   sequence sent by the <Home> key
        :EN=:   sequence sent by the <End> key




                                    - 36 -








  _O_p_t_i_o_n_a_l _c_a_p_a_b_i_l_i_t_i_e_s _t_h_a_t _d_e_s_c_r_i_b_e _c_h_a_r_a_c_t_e_r _a_t_t_r_i_b_u_t_e_s

        :so=: :se=:     start/end standout mode (We don't care about :sg#:)
        :us=: :ue=:     start/end underlined mode
        :VB=: :Vb=:     start/end boldface mode
        :as=: :ae=:     start/end alternate character set (italics)
        :ug#:           visible gap left by :us=:, :ue=:, :VB=:, or :Vb=:


  _O_p_t_i_o_n_a_l _c_a_p_a_b_i_l_i_t_i_e_s _t_h_a_t _a_f_f_e_c_t _t_h_e _s_h_a_p_e _o_f _t_h_e _c_u_r_s_o_r

        The  :cQ=:  string  is  used by elvis immediately before exiting to
     undo the effects of the other cursor shape strings. If  :cQ=:  is  not
     given, then all other cursor shape strings are ignored.

        :cQ=:   normal cursor
        :cX=:   cursor shape used for reading EX command -- steady underline
        :cV=:   cursor shape used for reading VI commands -- steady block
        :cI=:   cursor shape used during VI input mode -- blinking underline
        :cR=:   cursor shape used during VI replace mode -- blinking block


  _A_n _e_x_a_m_p_l_e

        Here's  the  termcap entry I use on my Minix-ST system. Some of the
     capabilities in it have nothing to do with Elvis. Some can  only  work
     on my system; I have modified my kernel's screen driver.

            mx|minix|minixst|ansi:\
                :co#80:li#25:bs:pt:\
                :cm=\E[%i%d;%dH:up=\E[A:do=^J:nd=\E[C:sr=\EM:\
                :cd=\E[J:ce=\E[K:cl=\E[H\E[J:\
                :al=\E[L:dl=\E[M:ic=\E[@:dc=\E[P:im=:ei=:\
                :so=\E[7m:se=\E[m:us=\E[4m:ue=\E[m:\
                :VB=\E[1m:Vb=\E[m:as=\E[1;3m:ae=\E[m:\
                :rs=\E[?5l:\
                :ku=\E[A:kd=\E[B:kr=\E[C:kl=\E[D:kb=^H:\
                :k1=\EOP:k2=\EOQ:k3=\EOR:k4=\EOS:k5=\EOT:\
                :k6=\EOU:k7=\EOV:k8=\EOW:k9=\EOX:k0=\EOY:\
                :kH=\E[V:kU=\E[U:\
                :cQ=\E[k:cX=\E[2;0k:cV=\E[16;0k:cI=\E[2;20k:cR=\E[16;20k:\
                :G3=%:GU=&:G4=':GR=(:GC=):GL=*:G2=+:GD=,:G1=-:GH=.:GV=/:















                                    - 37 -








_E_n_v_i_r_o_n_m_e_n_t _V_a_r_i_a_b_l_e_s

        Elvis examines several environment variables when it starts up. The
     values of these  variables  are  used  internally  for  a  variety  of
     purposes.  You  don't  need  to  define all of these; on most systems,
     Elvis only requires TERM to be defined. On MS-DOS systems,  even  that
     is optional.


  _T_E_R_M, _T_E_R_M_C_A_P

        TERM  tells Elvis the name of the termcap entry to use. TERMCAP may
     contain either the entire termcap entry, or the full pathname  of  the
     termcap file to search through.


  _T_M_P, _T_E_M_P

        These only work for MS-DOS and Atari TOS. Either of these variables
     may be used to  set  the  "directory"  option,  which  controls  where
     temporary files are stored. If you define them both, then TMP is used,
     and TEMP is ignored.


  _E_X_I_N_I_T

        This variable may contain  a  colon-mode  command,  which  will  be
     executed after all of the ".exrc" files but before interactive editing
     begins. NOTE: the real vi allows you to put  multiple  commands  here,
     separated  by  |  characters.  Elvis doesn't, yet, but you can place a
     "source" command there to get the same effect.


  _S_H_E_L_L, _C_O_M_S_P_E_C

        You can use COMSPEC in MS-DOS, or SHELL in  any  other  system,  to
     specify  which  shell  should  be  used  for  executing  commands  and
     expanding wildcards.


  _H_O_M_E

        This variable should give the full pathname of your home directory.
     Elvis  needs  to know the name of your home directory so it can locate
     the ".exrc" file there.












                                    - 38 -








_V_e_r_s_i_o_n_s

        Elvis currently works under  BSD  UNIX,  AT&T  System-V  UNIX,  SCO
     XENIX,  Minix,  MS-DOS,  and  Atari  TOS.  This  section of the manual
     provides special information that applies to each  particular  version
     of Elvis.


  _B_S_D _U_N_I_X

        Use "Makefile.bsd" to make Elvis.

        The  only  problem  you're  like to have is that both Elvis and the
     real Vi read initialization commands from a file called  ".exrc",  but
     the  commands  in  that  file might work on one but not the other. For
     example, "set keywordprg=/usr/myself/bin/ref" will work for Elvis, but
     Vi will complain because it doesn't have a "keywordprg" option. If the
     warning messages annoy you, then you can edit  the  config.h  file  to
     change  the name of the initialization file ".exrc" to something else,
     such as ".elvisrc".


  _S_y_s_t_e_m-_V _U_N_I_X

        Use "Makefile.s5" to make  Elvis.  If  your  system  uses  terminfo
     instead  of  termcap,  then  you  will have to edit the Makefile. More
     detailed instructions are embedded in the Makefile itself.

        The potential trouble with ".exrc" described  above  for  BSD  UNIX
     applies to System-V UNIX as well.

        If  your  system  uses  terminfo, you may have trouble with some of
     Elvis' extensions because  terminfo  can  only  emulate  the  standard
     termcap  capabilites  and  some  of  the  extensions  use  nonstandard
     capabilites. In particular, you can expect the "charattr" option to be
     almost useless, and the cursor's shape won't change.

        Elvis uses control-C as the interrupt key, not Delete.


  _S_C_O _X_e_n_i_x

        Use  "Makefile.s5" to make Elvis. On '286 systems, you will have to
     edit the Makefile so that the compiler generates  code  with  separate
     instruction  &  data segments. More detailed instructions are embedded
     in the Makefile itself.

        Other than that,  the  Xenix  version  behaves  like  the  System-V
     version, so everything mentioned in the System-V section above applies
     to SCO Xenix.







                                    - 39 -








  _M_i_n_i_x

        Use  "Makefile.st"  on  Minix-ST  systems,  and  "Makefile.pc"   on
     Minix-PC systems. The differences between these two Makefiles are that
     the ST version uses "*.o" files where the PC version uses "*.s" files,
     and  the  PC version has some extra flags in CFLAGS to reduce the size
     of Elvis.

        Minix-PC users should read the CFLAGS section of this  manual  very
     carefully.

        The  temporary files are stored in /usr/tmp. The /usr/tmp directory
     must exist before you run Elvis, and it must be  readable/writable  by
     everybody.

        Elvis uses control-C as the interrupt key, not Delete.


  _M_S-_D_O_S

        Elvis was ported to MS-DOS by Guntram Blohm and Martin Patzel.

        There   are   two  different  Makefiles  for  Elvis  under  MS-DOS.
     "Elvis.prj" should be used with Turbo-C,  and  "Elvis.mak"  should  be
     used  with  MSC and Microsoft MAKE. The "Elvis.mak" file may work with
     MS Quick-C if you change the definition of CC to "CC=  qcl".  I  don't
     know for sure; I haven't tried it.

        Elvis  stores  its  temporary  files  in  C:\tmp.  If  this  is not
     satisfactory, then you should edit the CFLAGS line of your Makefile to
     change it to something else before compiling. The directory must exist
     before you can run Elvis.

        Normally, the TERM environment variable should not be set, or  else
     it  should be set to "pcbios". This way, Elvis will make calls to BIOS
     to update the screen. This is the fastest & prettiest  way  to  update
     the screen.

        However,  if  your  system is not quite compatible enough, then you
     can still run Elvis via the ANSI.SYS or NANSI.SYS drivers. Install one
     of  these  drivers  by  adding  "driver = ansi.sys" to your CONFIG.SYS
     file, and then define TERM to be either "ansi" or "nansi" by adding  a
     line  such as "set TERM=ansi" to your AUTOEXEC.BAT file. You must then
     reboot for these changes to take effect. After that, Elvis will notice
     the "TERM" setting and use the driver.

        Under  MS-DOS,  Elvis  has  an  extra ":set" option called "pcbios"
     which indicates whether the BIOS is being used  directly.  This  is  a
     "read only" option; you can't use it to switch your interface style in
     the middle of an edit session.

        An extra program, called  "wildcard",  is  needed  for  MS-DOS.  It
     expands wildcard characters in file names.




                                    - 40 -








  _A_t_a_r_i _T_O_S

        Elvis  was  ported to Atari TOS by Guntram Blohm and Martin Patzel.
     It is very similar to the MS-DOS version.

        The Makefile.tos file should be used for TOS. It is intended to  be
     used with the Mark Williams C compiler.

        The  TERM  environment  variable should be set to "vt52". The SHELL
     (not COMSPEC!) variable should be set to the name of  a  line-oriented
     shell.

        A  simple shell in included with elvis. Its source is in "shell.c",
     and the name of the executable  is  "shell.ttp".  This  was  necessary
     because  the  standard  Atari  software  doesn't  offer any way to set
     environment variables. The file "profile.sh" should contain a  set  of
     instructions to be executed when the shell first starts up. An example
     of this file is included, but you will almost certainly want  to  edit
     it right away to match your configuration.

        If you already have a command-line shell, then you'll probably want
     to continue using it. The shell that comes with elvis is very limited.



































                                    - 41 -



