The C Users' Group Library 1994 August/wc-cdrom-cusersgrouplibrary-1994-08.iso/vol_300/365_03/elvisman.txt

Text File | 1992-04-06 | 197KB | 5,413 lines

                  #######
                  #        #       #    #     #     ####
                  #        #       #    #     #    #
                  #####    #       #    #     #     ####
                  #        #       #    #     #         #
                  #        #        #  #      #    #    #
                  #######  ######    ##       #     ####

                            - a clone of vi/ex -
                                version 1.5






























  Author:  Steve Kirkendall
           14407 SW Teal Blvd., Apt C
           Beaverton, OR 97005

  E-Mail:  [e-mail]

  Phone:   [phone]










                               March 23, 1992











                             Table of Contents




        INTRODUCTION What ELVIS does, Copyright, How to com-
        pile ELVIS, Overview ..................................    1

        VISUAL MODE COMMANDS Normal interactive editing,
        Input mode, Arrow keys, Digraphs, Abbreviations,
        Auto-indentation ......................................    2

        COLON MODE COMMANDS Line specifiers, Text entry, Cut
        & paste, Display text, Global operations, Line edit-
        ing, Undo, Configuration & status, Multiple files,
        Switching files, Working with a compiler, Exiting,
        File I/O, Directory & shell, Debugging ................    3

        REGULAR EXPRESSIONS Syntax, Options, Substitutions,
        Examples ..............................................    4

        OPTIONS Autoindent, Autoprint, etc.  ..................    5

        CUT BUFFERS Putting text into a cut buffer, Pasting
        from a cut buffer, Macros, The effect of switching
        files .................................................    6

        DIFFERENCES BETWEEN ELVIS AND THE REAL VI/EX Exten-
        sions, Omissions ......................................    7

        INTERNAL For programmers only, The temporary file,
        Implementation of editing, Marks and the cursor,
        Colon command interpretation, Screen control, Porta-
        bility ................................................    8

        CFLAGS ................................................    9

        TERMCAP ...............................................   10

        ENVIRONMENT VARIABLES .................................   11

        VERSIONS ..............................................   12

        QUESTIONS & ANSWERS ...................................   13


          UNIX-style "man" pages appear at the end of this manual.







                               March 23, 1992








        1.  INTRODUCTION

             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  tem-
        porary  file,  instead of RAM.  This allows it to edit files
        that are too large to fit in a single process'  data  space.
        Also, the edit buffer can survive a power failure or crash.

             Elvis runs under BSD UNIX, AT&T SysV UNIX,  Minix,  MS-
        DOS,  Atari TOS, Coherent, OS9/68000, VMS and AmigaDos.  The
        next version is also expected to add  MS-Windows,  OS/2  and
        MacOS.  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.   There are no restrictions on how you
        may use it.

        1.1.  Compiling

             See the "Versions" section of this manual for  instruc-
        tions on how to compile Elvis.

             If you want to port Elvis to another O.S. or  compiler,
        then  you  should start by reading the "Portability" part of
        the "Internal" section.

        1.2.  Overview of Elvis

             The user interface of Elvis/vi/ex is weird.  There  are
        two major command 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 visual command mode  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 inter-
        pretted as part of a visual command.  If  you  start  typing
        text, it will not 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 colon mode 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.



                               March 23, 1992








        2.  VISUAL MODE COMMANDS

             Most visual mode commands are one keystroke long.   The
        following  table lists the operation performed by each keys-
        troke, and also denotes any options  or  arguments  that  it
        accepts.   Notes  at the end of the table describe the nota-
        tion 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.   The  <Insert>  key  will toggle
        between insert mode and replace mode.  There is a colon mode
        command (":map", 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  com-
        mand  mode.   So, one way or another, after <Esc> Elvis will
        be ready for a command.

        COMMAND      DESCRIPTION
               ^A    Search for next occurence of word at cursor (MOVE)(EXT)
               ^B    Move toward the top of the file by 1 screenful
               ^C    --- (usually sends SIGINT, to interupt a command)
        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    --- (typically XON, which restarts screen updates)
               ^R    Redraw the screen
               ^S    --- (typically XOFF, which stops screen updates)
               ^T    ---
        count  ^U    Scroll up <count> lines (default 1/2 screen)
               ^V    ---
               ^W    ---
        count  ^X    Move to a physical column number on the screen (MOVE) (EXT)
        count  ^Y    Scroll down <count> lines
               ^Z    --- (sometimes sends SIGSUSP, to suspend execution)
               ESC   ---
               ^\    --- (usually sends SIGQUIT, which is ignored)
               ^]    If the cursor is on a tag name, go to that tag



                               March 23, 1992





        2-2                 VISUAL MODE COMMANDS                 2-2


               ^^    Switch to the previous file, like ":e #"
               ^_    ---
        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
        count  # +   Increment a number (EDIT) (EXT)
               $     Move to the rear of the current line (MOVE)
        count  %     Move to matching (){}[] or to a given % of file (MOVE)(EXT)
        count  &     Repeat the previous ":s//" command here (EDIT)
               ' key Move to a marked line (MOVE)
        count  (     Move backward <count> sentences (MOVE)
        count  )     Move forward <count> sentences (MOVE)
               *     Go to the next error in the errlist (EXT)
        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
               / textSearch 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
               : textRun single EX cmd
        count  ;     Repeat the previous [fFtT] cmd (MOVE)
               < mv  Shift text left (EDIT)
               = mv  Reformat
               > mv  Shift text right (EDIT)
               ? textSearch backward for a given regular expression (MOVE)
               @ key Execute the contents of a cut-buffer as VI commands
        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-line (EDIT)
               D     Delete text from the cursor through the end-of-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 (EXT)
        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 (EDIT)
               Q     Quit to EX mode
               R inp Overtype (EDIT)
        count  S inp Change lines, like <count>cc



                               March 23, 1992





        2-3                 VISUAL MODE COMMANDS                 2-3


        count  T key Move leftward *almost* to a given character (MOVE)
               U     Undo all recent changes to the current line
               V     Start marking lines for c/d/y/</>/!/\ (EXT)
        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
               [ [   Move back 1 section (MOVE)
               \ mv  Pop-up menu for modifying text (EXT)
               ] ]   Move forward 1 section (MOVE)
               ^     Move to the front of the current line (after indent) (MOVE)
        count  _     Move to the current line
               ` 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 (EDIT)
               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     Start marking characters for c/d/y/</>/!/\ (EXT)
        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)
        count  ~     Switch a character between uppercase & lowercase (EDIT)
               DEL   --- (usually mapped to shift-X, so it deletes 1 character)


        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 usu-
             ally defaults to 1.

        key  Some commands require two keystrokes.   The  first  key



                               March 23, 1992





        2-4                 VISUAL MODE COMMANDS                 2-4


             always determines which command is to be executed.  The
             second key is used as a parameter to the command.

        mv   Some commands (! < > c d y \ =) operate on text between
             the  cursor  and  some other position.  There are three
             ways that you can specifify that other position.

             The first way is to follow the command keystroke with a
             movement  command.   For example, "dw" deletes a single
             word.  "d3w" and "3dw" both delete three words.

             The second way is to type the command keystroke  twice.
             This causes whole lines to be acted upon.  For example,
             ">>" indents  the  current  line.   "3>>"  indents  the
             current line and the following two lines.

             The last way is to move the cursor to one  end  of  the
             text, type 'v' or 'V' to start marking, move the cursor
             to the other end, and then  type  the  desired  command
             key.

        inp  Many commands allow the  user  to  interactively  enter
             text.   See  the discussion of "input mode" in the fol-
             lowing section.

        (EXT)
             These commands are extensions -- the  real  vi  doesn't
             have them.

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

        2.1.  Input Mode

             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



                               March 23, 1992





        2-5                 VISUAL MODE COMMANDS                 2-5


                ^L      redraw the screen
                ^M      (carriage return) insert a newline (^J, linefeed)
                ^O      execute next key as a visual command (limited!)
                ^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  res-
        tart  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 char-
        acters is deleted from the file.

        2.2.  Arrow keys in Input Mode

             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 <Insert>  key
        toggles between input mode and replace 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.

        2.3.  Digraphs

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

             There is no single standard for extended ASCII  charac-
        ter  sets.   Elvis  can be compiled to fill the digraph with
        values appropriate for either the IBM PC character  set,  or
        the  LATIN-1  character  set  used by X windows, or neither.
        (See the discussions of -DCS_IBMPC and  -DCS_LATIN1  in  the



                               March 23, 1992





        2-6                 VISUAL MODE COMMANDS                 2-6


        CFLAGS  section  of  this  manual.) You can view or edit the
        digraph table via the ":digraph" colon command.

             Digraphs will not be recognized  until  you've  entered
        ":set digraph".

             To actually use a digraph  type  the  first  character,
        then  hit  <Backspace>,  and then type the second character.
        Elvis will then substitute the non-ASCII character in  their
        place.

        2.4.  Abbreviations

             Elvis can expand abbreviations for you.  You define  an
        abbreviation  with  the :abbr command, and then whenever you
        type in the abbreviated form while in input mode, Elvis will
        immediately  replace  it with the long form.  COBOL program-
        mers should find this useful. :-)

             Elvis doesn't perform the substitution until you type a
        non-alphanumeric  character to mark the end of the word.  If
        you type a control-V before that non-alphanumeric character,
        then Elvis will not perform the substitution.

        2.5.  Auto-Indent

             With the ":set autoindent" option turned on, Elvis will
        automatically  insert leading whitespace at the beginning of
        each new line that you type in.  The leading  whitespace  is
        copied from the preceding line.

             To add more leading  whitespace,  type  control-T.   To
        remove some whitespace, type control-D.

             If you ":set noautotab", then the whitespace  generated
        by  control-T  will  always consist of spaces -- never tabs.
        Some people seem to prefer this.

             Elvis' autoindent mode isn't 100% compatible with vi's.
        In  Elvis, 0^D and ^^D don't work, ^U can wipeout all inden-
        tation, and sometimes Elvis will use a different  amount  of
        indentation than vi would.















                               March 23, 1992








        3.  COLON MODE COMMANDS

                LINES               COMMAND   ARGUMENTS
                                    ab[br]    [short] [expanded form]
                [line]              a[ppend][!]
                                    ar[gs]    [files]
                                    cc        [files]
                                    cd[!]     [directory]
                [line][,line]       c[hange]
                                    chd[ir][!][directory]
                [line][,line]       co[py]    line
                                    col[or]   [when] [[light] color] [on color]
                [line][,line]       d[elete]  [x]
                                    dig[raph][!][XX [Y]]
                                    e[dit][!] [file]
                                    er[rlist][!][errlist]
                                    f[ile]    [file]
                [line][,line]       g[lobal]  /regexp/ command
                [line]              i[nsert]
                [line][,line]       j[oin][!]
                [line][,line]       l[ist]
                                    mak[e]    [target]
                                    map[!]    key mapped_to
                [line]              ma[rk]    x
                                    mk[exrc]
                [line][,line]       m[ove]    line
                                    n[ext][!] [files]
                                    N[ext][!]
                [line][,line]       nu[mber]
                [line][,line]       p[rint]
                [line]              pu[t]     [x]
                                    q[uit][!]
                [line]              r[ead]    file
                                    rew[ind][!]
                                    se[t]     [options]
                                    so[urce]  file
                [line][,line]       s[ubstitute]/regexp/replacement/[p][g][c]
                                    ta[g][!]  tagname
                                    una[bbr]  [short]
                                    u[ndo]
                                    unm[ap][!]key
                                    ve[rsion]
                [line][,line]       v[global] /regexp/ command
                                    vi[sual]  [filename]
                                    wq
                [line][,line]       w[rite][!][[>>]file]
                                    x[it][!]
                [line][,line]       y[ank]    [x]
                [line][,line]       !         command
                [line][,line]       <
                [line][,line]       =
                [line][,line]       >
                [line][,line]       &
                                    @          x



                               March 23, 1992





        3-2                 COLON MODE COMMANDS                  3-2


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

        3.1.  Line Specifiers

             Line specifiers are always optional.   The  first  line
        specifier  of  most commands usually defaults to the current
        line.  The second line specifier 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 rela-
        tive  part.   The  absolute  part of a line specifier 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 specifier 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



                               March 23, 1992





        3-3                 COLON MODE COMMANDS                  3-3


             :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"


        3.2.  Text Entry Commands

                [line] append
                [line][,line] change ["x]
                [line] insert


             The append command inserts  text  after  the  specified
        line.

             The insert command inserts text  before  the  specified
        line.

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

        3.3.  Cut & Paste Commands

                [line][,line] delete ["x]
                [line][,line] yank ["x]
                [line] put ["x]
                [line][,line] copy line
                [line][,line] to line
                [line][,line] move line


             The delete command copies the specified range of  lines
        into a cut buffer, and then deletes them.

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

             The put command inserts text from a  cut  buffer  after
        the specified line.

             The copy and to commands yank the  specified  range  of
        lines and then immediately paste them after some other line.

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



                               March 23, 1992





        3-4                 COLON MODE COMMANDS                  3-4


        3.4.  Display Text Commands

                [line][,line] print
                [line][,line] list
                [line][,line] number


             The print  command  displays  the  specified  range  of
        lines.

             The  number  command  displays  the  lines,  with  line
        numbers.

             The list command also displays them, but it is  careful
        to make control characters visible.

        3.5.  Global Operations Commands

                [line][,line] global /regexp/ command
                [line][,line] vglobal /regexp/ command


             The global 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  expres-
        sion.   It  then moves the cursor to each of these lines and
        runs some other command on them.

             The vglobal command is similar,  but  it  searches  for
        lines that don't contain the regular expression.

        3.6.  Line Editing Commands

                [line][,line] join[!]
                [line][,line] ! program
                [line][,line] <
                [line][,line] >
                [line][,line] substitute /regexp/replacement/[p][g][c]
                [line][,line] &


             The join 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  normal  ":join"  inserts  one or two spaces between the
        lines; the ":join!" variation (with a  '!')  doesn't  insert
        spaces.

             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



                               March 23, 1992





        3-5                 COLON MODE COMMANDS                  3-5


        left  or  right,  normally  by the width of 1 tab character.
        The "shiftwidth" option determines the shifting amount.

             The substitute 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.  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.) The "c" option asks for confirma-
        tion before each substitution.

             The & command repeats the  previous  substitution  com-
        mand.   Actually, "&" is equivelent to "s//~/" with the same
        options as last time.  It  searches  for  the  last  regular
        expression  that you specified for any purpose, and replaces
        it with the the same text that was used in the previous sub-
        stitution.

        3.7.  Undo Command

                undo


             The undo command restores the file to the state it  was
        in before your most recent command which changed text.

        3.8.  Configuration & Status Commands

                map[!] [key mapped_to]
                unmap[!] key
                abbr [word expanded_form_of_word]
                unabbr word
                digraph[!] [XX [Y]]
                set [options]
                mkexrc
                [line] mark "x
                visual
                version
                [line][,line] =
                file [file]
                source file
                @ "x
                color [when] [["light"] color] ["on" color]


             The map command allows you to configure Elvis to recog-
        nize  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  input  and
        replace  modes  as well.  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



                               March 23, 1992





        3-6                 COLON MODE COMMANDS                  3-6


        is  the  sequence  that you want Elvis to treat it as having
        sent.  As a special case, if the first argument is a  number
        then  Elvis  will  map  the  corresponding function key; for
        example, ":map 7 dd" will cause the <F7>  key  to  delete  a
        line.

             The unmap command removes  key  definitions  that  were
        made via the map command.

             The abbr command is used  to  define/list  a  table  of
        abbreviations.  The table contains both the abbreviated form
        and the fully spelled-out form.  When you're in visual input
        mode,  and  you  type  in  the  abbreviated form, Elvis will
        replace the abbreviated  form  with  the  fully  spelled-out
        form.   When  this  command  is called without arguments, it
        lists the table; with two or more arguments, the first argu-
        ment  is  taken as the abbreviated form, and the rest of the
        command line is the fully-spelled out form.

             The unabbr command deletes entries from the abbr table.

             The digraph 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 set 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 mkexrc command saves the current configuration to a
        file called ".exrc" in the current directory.

             The mark 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 visual command puts the editor  into  visual  mode.
        Instead of emulating ex, Elvis will start emulating vi.

             The version command tells  you  that  what  version  of
        Elvis this is.

             The = command tells you what line you specified, or, if



                               March 23, 1992





        3-7                 COLON MODE COMMANDS                  3-7


        you  specified  a range of lines, it will tell you both end-
        points and the number of lines included in the range.

             The file 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.  You can also use  it  to
        change the name of the current file.

             The source command reads a sequence of colon mode  com-
        mands from a file, and interprets them.

             The @ command executes the contents of a cut-buffer  as
        EX commands.

             The color command only works under MS-DOS,  or  if  you
        have  an  ANSI-compatible  color terminal.  It allows you to
        set the foreground and background colors for different types
        of  text: normal, bold, italic, underlined, standout, pop-up
        menu, and visible selection.  By  default,  it  changes  the
        "normal"  colors; to change other colors, the first argument
        to the :color command should be the first letter of the type
        of  text  you want.  The syntax for the colors themselves is
        fairly intuitive.  For example, ":color light cyan on  blue"
        causes  normal  text to be displayed in light cyan on a blue
        background, and ":color b bright white" causes bold text  to
        be  displayed  in  bright  white  on a blue background.  The
        background color always defaults to the  current  background
        color  of  normal  text.   Your  first  :color  command must
        specify both the foreground and background for normal text.

        3.9.  Multiple File Commands

                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 args command will display this  list,
        or define a new one.

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

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

             The rewind command switches from the  current  file  to
        the first file in the args list.



                               March 23, 1992





        3-8                 COLON MODE COMMANDS                  3-8


        3.10.  Switching Files

                edit[!] [file]
                tag[!] tagname


             The edit 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 tag 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.

        3.11.  Working with a Compiler

                cc [files]
                make [target]
                errlist[!] [errlist]


             The cc and  make  commands  execute  your  compiler  or
        "make"  utility  and redirect any error messages into a file
        called "errlist".  By default, cc  is  run  on  the  current
        file.  (You should write it before running cc.) The contents
        of the "errlist" file are then scanned for  error  messages.
        If  an  error  message is found, then the cursor is moved to
        the line where the error was detected, and  the  description
        of the error is displayed on the status line.

             After you've fixed one error, the errlist command  will
        move  the cursor to the next error.  In visual command mode,
        hitting `*' will do this, too.

             You can also create an "errlist" file from  outside  of
        Elvis, and use "Elvis -m" to start elvis and have the cursor
        moved to the first error.  Note that you don't need to  sup-
        ply  a  filename  with "Elvis -m" because the error messages
        always say which source file an error is in.

             Note: When you use errlist repeatedly  to  fix  several
        errors  in  a  single  file,  it  will attempt to adjust the
        reported line numbers to  allow  for  lines  that  you  have
        inserted  or  deleted.   These adjustments are made with the
        assumption that you will  work  though  the  file  from  the
        beginning to the end.

        3.12.  Exit Commands

                quit[!]
                wq
                xit




                               March 23, 1992





        3-9                 COLON MODE COMMANDS                  3-9


             The quit command exits from the editor  without  saving
        your file.

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

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

        3.13.  File I/O Commands

                [line] read file
                [line][,line] write[!] [[>>]file]


             The read  command  gets  text  from  another  file  and
        inserts  it  after the specified line.  It can also read the
        output of a program; simply precede the program  name  by  a
        '!' and use it in place of the file name.

             The write 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.  You can send the lines to the
        standard input of a program by replacing the filename with a
        '!' followed by the command and its arguments.

             Note: Be careful not to confuse ":w!filename"  and  ":w
        !command".   To  write  to a program, you must have at least
        one blank before the '!'.

        3.14.  Directory Commands

                cd [directory]
                chdir [directory]
                shell


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

             The shell command starts an interactive shell.

        3.15.  Debugging Commands

                [line][,line] debug[!]
                validate[!]


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

             The debug command lists statistics for the blocks which



                               March 23, 1992





        3-10                COLON MODE COMMANDS                 3-10


        contain  the specified range of lines.  If the ! is present,
        then the contents of those blocks is displayed, too.

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


















































                               March 23, 1992








        4.  REGULAR EXPRESSIONS


             Elvis uses regular expressions for searching  and  sub-
        stututions.   A regular expression is a text string in which
        some characters have special meanings.  This  is  much  more
        powerful than simple text matching.

        Syntax

             Elvis' regexp package  treats  the  following  one-  or
        two-character  strings  (called  meta-characters) in special
        ways:

        \(subexpression\)
                The \( and \) metacharacters  are  used  to  delimit
                subexpressions.  When the regular expression matches
                a particular chunk  of  text,  Elvis  will  remember
                which  portion  of that chunk matched the subexpres-
                sion.  The :s/regexp/newtext/ command makes  use  of
                this feature.

        ^       The ^ metacharacter matches the beginning of a line.
                If,  for  example,  you  wanted to find "foo" at the
                beginning of a line, you would use a regular expres-
                sion  such  as  /^foo/.  Note that ^ is only a meta-
                character if it occurs at the beginning of a regular
                expression; anyplace else, it is treated as a normal
                character.

        $       The $ metacharacter matches the end of a  line.   It
                is only a metacharacter when it occurs at the end of
                a regular expression; elsewhere, it is treated as  a
                normal  character.  For example, the regular expres-
                sion /$$/ will search for a dollar sign at  the  end
                of a line.

        \<      The \< metacharacter matches a zero-length string at
                the beginning of a word.  A word is considered to be
                a string of 1 or more letters and  digits.   A  word
                can  begin  at the beginning of a line or after 1 or
                more non-alphanumeric characters.

        \>      The \> metacharacter matches a zero-length string at
                the end of a word.  A word can end at the end of the
                line or before 1 or  more  non-alphanumeric  charac-
                ters.    For   example,  /\<end\>/  would  find  any
                instance of the word "end",  but  would  ignore  any
                instances  of  e-n-d  inside  another  word  such as
                "calendar".

        .       The . metacharacter matches any single character.

        [character-list]



                               March 23, 1992





        4-2                 REGULAR EXPRESSIONS                  4-2


                This  matches  any   single   character   from   the
                character-list.   Inside the character-list, you can
                denote a span of  characters  by  writing  only  the
                first  and  last  characters,  with a hyphen between
                them.  If the character-list  is  preceded  by  a  ^
                character,  then  the  list  is  inverted -- it will
                match character that isn't mentioned  in  the  list.
                For  example, /[a-zA-Z]/ matches any letter, and /[^
                ]/ matches anything other than a blank.

        \{n\}   This is a closure operator, which means that it  can
                only be placed after something that matches a single
                character.  It controls the number of times that the
                single-character expression should be repeated.

                The \{n\} operator, in particular,  means  that  the
                preceding  expression  should  be repeated exactly n
                times.  For example, /^-\{80\}$/ matches a  line  of
                eighty  hyphens, and /\<[a-zA-Z]\{4\}\>/ matches any
                four-letter word.

        \{n,m\} This is a closure  operator  which  means  that  the
                preceding   single-character  expression  should  be
                repeated between n and m times, inclusive.  If the m
                is  omitted  (but  the  comma  is present) then m is
                taken to be inifinity.  For example, /"[^"]\{3,5\}"/
                matches  any  pair  of  quotes which contains three,
                four, or five non-quote characters.

        *       The * metacharacter  is  a  closure  operator  which
                means that the preceding single-character expression
                can  be  repeated  zero  or  more  times.    It   is
                equivelent  to  \{0,\}.  For example, /.*/ matches a
                whole line.

        \+      The \+ metacharacter is  a  closure  operator  which
                means that the preceding single-character expression
                can be repeated one or more times.  It is equivelent
                to \{1,\}.  For example, /.\+/ matches a whole line,
                but only if the line contains at least  one  charac-
                ter.  It doesn't match empty lines.

        \?      The \? metacharacter is  a  closure  operator  which
                indicates   that   the   preceding  single-character
                expression is optional -- that is, that it can occur
                0  or  1  times.   It is equivelent to \{0,1\}.  For
                example, /no[ -]\?one/ matches "no  one",  "no-one",
                or "noone".

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




                               March 23, 1992





        4-3                 REGULAR EXPRESSIONS                  4-3


        Substitutions

             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:

               &     Insert a copy of the original text
               ~     Insert a copy of the previous replacement text
               \1    Insert a copy of that portion of the original text which
                     matched the first set of \( \) parentheses
               \2-\9 Do the same for the second (etc.) pair of \( \)
               \U    Convert all chars of any later & or \# to uppercase
               \L    Convert all chars of any later & or \# to lowercase
               \E    End the effect of \U or \L
               \u    Convert the first char of the next & or \# to uppercase
               \l    Convert the first char of the next & or \# to lowercase


             These may be preceded by a backslash to force  them  to
        be treated normally.  If "nomagic" mode is in effect, then &
        and ~ will be treated normally, and you must write  them  as
        \& and \~ for them to have special meaning.

        Options

             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  lower-
        case are treated as being different.

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

        Examples

             This example changes every occurence  of  "utilize"  to
        "use":

                  :%s/utilize/use/g



                               March 23, 1992





        4-4                 REGULAR EXPRESSIONS                  4-4


             This example deletes all whitespace that occurs at  the
        end of a line anywhere in the file.  (The brackets contain a
        single space and a single tab.):

                  :%s/[   ]\+$//

             This example converts the current line to uppercase:

                  :s/.*/\U&/

             This example underlines  each  letter  in  the  current
        line,  by  changing it into an "underscore backspace letter"
        sequence.  (The ^H is entered as "control-V backspace".):

                  :s/[a-zA-Z]/_^H&/g

             This example locates the last  colon  in  a  line,  and
        swaps  the  text  before  the  colon with the text after the
        colon.  The first \( \) pair is used to  delimit  the  stuff
        before  the  colon,  and  the  second pair delimit the stuff
        after.  In the substitution text, \1 and  \2  are  given  in
        reverse order to perform the swap:

                  :s/\(.*\):\(.*\)/\2:\1/

































                               March 23, 1992








        5.  OPTIONS

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

             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.

             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.   Elvis also allows boolean
        options to be toggled by prefixing the name with "neg".  So,
        ":map  g  :set  neglist^M"  will cause the <g> key to alter-
        nately toggle the "list" option on and off.  (The "neg" pre-
        fix is an extension; the real vi doesn't support it.)

             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.

        NAMES              TYPE DEFAULT       MEANING
        autoindent, ai     Bool noai          auto-indent during input
        autoprint, ap      Bool ap            in EX, print the current line
        autotab, at        Bool at            auto-indent allowed to use tabs?
        autowrite, aw      Bool noaw          auto-write when switching files
        beautify,  bf      Bool nobf          strip control chars from file?
        charattr, ca       Bool noca          interpret \fX sequences?
        cc, cc             Str  cc="cc -c"    name of the C compiler
        columns, co        Num  co=80         width of the screen
        digraph, dig       Bool nodig         recognize digraphs?
        directory, dir     Str  dir="/usr/tmp"where tmp files are kept
        edcompatible, ed   Bool noed          remember ":s//" options
        equalprg, ep       Bool ep="fmt"      program to run for = operator
        errorbells, eb     Bool eb            ring bell on error
        exrc, exrc         Bool noexrc        read "./.exrc" file?
        exrefresh, er      Bool er            write lines indiviually in EX
        flash, vbell       Bool flash         use visible alternative to bell
        flipcase, fc       Str  fc=""         non-ASCII chars flipped by ~
        hideformat, hf     Bool hf            hide text formatter commands
        ignorecase, ic     Bool noic          upper/lowercase match in search
        inputmode, im      Bool noim          start vi in insert mode?
        keytime, kt        Num  kt=2          timeout for mapped key entry
        keywordprg, kp     Str  kp="ref"      full pathname of shift-K prog
        lines, ln          Num  ln=25         number of lines on the screen
        list, li           Bool noli          display lines in "list" mode
        magic, ma          Bool ma            use regular expression in search
        make, mk           Str  mk="make"     name of the "make" program



                               March 23, 1992





        5-2                       OPTIONS                        5-2


        mesg, ms           Bool ms            allow messages from other users?
        modelines, ml      Bool noml          are modelines processed?
        more, more         Bool more          pause between messages?
        novice, nov        Bool nonovice      set options for ease of use
        paragraphs, para   Str  para="PPppIPLPQP"names of "paragraph" nroff cmd
        prompt, pr         Bool pr            show ':' prompt in ex mode
        readonly, ro       Bool noro          prevent overwriting of orig file
        remap, rem         Bool remap         allow key maps to call key maps
        report, re         Num  re=5          report when 5 or more changes
        ruler, ru          Bool noru          display line/column numbers
        scroll, sc         Num  sc=12         scroll amount for ^U and ^D
        sections, sect     Str  sect="NHSHSSSEse"names of "section" nroff cmd
        shell, sh          Str  sh="/bin/sh"  full pathname of the shell
        showmatch, sm      Bool nosm          show matching ()[]{}
        showmode, smd      Bool nosmd         say when we're in input mode
        shiftwidth, sw     Num  sw=8          shift amount for < and >
        sidescroll, ss     Num  ss=8          amount of sideways scrolling
        sync, sy           Bool nosy          call sync() often
        tabstop, ts        Num  ts=8          width of tab characters
        taglength, tl      Num  tl=0          significant chars in tag name
        term, te           Str  te="$TERM"    name of the termcap entry
        terse, tr          Bool notr          give shorter error messages
        timeout, to        Bool to            distinguish <esc> from <arrow>?
        warn, wa           Bool wa            warn for ! if file modified
        window, wi         Num  wi=24         lines to redraw after long move
        wrapmargin, wm     Num  wm=0          wrap long lines in input mode
        wrapscan, ws       Bool ws            at EOF, searches wrap to line 1
        writeany, wr       Bool nowr          allow :w to clobber files


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

        autoprint, ap
             This option only affects EX  mode.   If  the  autoprint
             option  on,  and  either the cursor has moved to a dif-
             ferent line or the previous command modified the  file,
             then Elvis will print the current line.

        autotab, at
             This option affects the  behaviour  of  the  autoindent
             mode.  If autoindent is turned off, then autotab has no
             effect.

             When autotab is turned on, elvis will use a mixture  of
             spaces and tabs to create the proper amount of indenta-
             tion.  This is the default.

             When autotab is turned off, elvis will only use  spaces
             for  auto-indent.   Elvis  will still insert a real tab
             character when you  hit  the  <Tab>  key,  though;  the



                               March 23, 1992





        5-3                       OPTIONS                        5-3


             autotab option only affects automatic indentation.

        autowrite, aw
             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 suc-
             cessfully switch to the new file.

        beautify, bf
             This option causes all control characters to be deleted
             from  the text file, at the time when you start editing
             it.  If you're already editing a file when you turn  on
             the beautify option, then that file won't be affected.

        cc   The :cc command  runs  the  C  compiler.   This  option
             should be set to the name of your compiler.

        charattr, ca
             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 \fP 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 under-
             lined and boldface, and if the TERMCAP entry  says  how
             to do it.)

        columns, co
             This option shows how wide your screen is.

        digraph, dig
             This option is used to  enable/disable  recognition  of
             digraphs.   The default value is nodigraph, which means
             that digraphs will not be recognized.

        directory, dir
             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



                               March 23, 1992





        5-4                       OPTIONS                        5-4


             files in some other directory, so it would be too late.

        edcompatible, ed
             This   option   affects   the    behaviour    of    the
             ":s/regexp/text/options"  command.   It is normally off
             (:se noed) which causes all of the substitution options
             to be off unless explicitly given.

             However, with edcompatible on (:se ed),  the  substitu-
             tion  command  remembers  which  options  you used last
             time.  Those same options  will  continue  to  be  used
             until  you change them.  In edcompatible mode, when you
             explicitly give the name of a substitution option,  you
             will toggle the state of that option.

             This all seems very strange to me, but its  implementa-
             tion  was  almost free when I added the ":&" command to
             repeat the previous substitution, so there it is.

        equalprg, ep
             This holds the name & arguments of the external  filter
             program  used  the  the visual = operator.  The defualt
             value is "fmt", so the  =  operator  will  adjust  line
             breaks in text.

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

        exrc This option specifies  whether  a  .exrc  file  in  the
             current directory should be executed.  By default, this
             option is off (":set noexrc") which prevents elvis from
             executing .exrc in the current directory.  If the .exrc
             file in your home directory turns this option on (":set
             exrc") then the Elvis will attempt to execute the .exrc
             file in the current directory.

             This option  exist  mainly  for  security  reasons.   A
             mean-spirited person could do something like
                  echo >/tmp/.exrc '!rm -rf $HOME'
             and then anybody who attempted to edit or view  a  file
             in  the  /tmp directory would lose most of their files.
             With the exrc option turned off, this  couldn't  happen
             to you.

        exrefresh, er
             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.




                               March 23, 1992





        5-5                       OPTIONS                        5-5


             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.

        flash, vbell
             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.  Nor-
             mally it will be.

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

        flipcase, fc
             The flipcase option allows you to control how the  non-
             ASCII characters are altered by the "~" command.

             The string is divided into pairs of  characters.   When
             "~" is applied to a non-ASCII character, Elvis looks up
             the character in the flipcase string to see which  pair
             it's  in, and replaces it by the other character of the
             pair.

        hideformat, hf
             Many text formatters require you to embed  format  com-
             mands  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.

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

             When the ignorecase option is on, uppercase and  lower-
             case are treated as equal.

        inputmode, im
             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.

        keytime, kt
             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



                               March 23, 1992





        5-6                       OPTIONS                        5-6


             allows  you  to  control  the maximum amount of time to
             allow for an arrow key (or  other  mapped  key)  to  be
             received in full.

             On most systems, the setting is the number of tenths of
             a  second  to  allow between characters.  On some other
             systems, the setting is in whole seconds.

             Try to avoid  setting  keytime=1.   Most  systems  just
             count  clock beats, so if you tried to read a character
             shortly before a clock beat, you could allow almost  no
             time  at  all  for  reading the characters.  For higher
             keytime settings, the difference is less critical.

             If your system's response time is poor, you might  want
             to  increase  the  keytime.   In particular, I've found
             that when keystrokes must be  sent  through  a  network
             (via  X  windows,  rlogin,  or telnet, for example) the
             keytime should be set to at least 1 second.

             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.

        keywordprg, kp
             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  infor-
             mation about it.

             This option says which program gets run.

             The default value of this option is "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 >>>".

        lines, ln
             This option says how many lines you screen has.

        list, li



                               March 23, 1992





        5-7                       OPTIONS                        5-7


             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.

        magic, ma
             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  set-
             ting of magic.

        make, mk
             The :make  command  runs  your  "make"  program.   This
             option defines the name of your "make" program.

        mesg With the  real  vi,  running  under  real  UNIX,  ":set
             nomesg" would prevent other users from sending you mes-
             sages.  Elvis ignores it, though.

        modelines, ml
             Elvis supports modelines.  Modelines are lines near the
             beginning  or  end  of  your  text  file  which contain
             "ex:yowza:", where "yowza" is any EX command.  A  typi-
             cal  "yowza"  would  be  something  like  "set  ts=5 ca
             kp=spell wm=15".  Other text may also appear on a mode-
             line, so you can place the "ex:yowza:" in a comment:

                     /* ex:set sw=4 ai: */


             Normally these lines are ignored, for security reasons,
             but if you have "set modelines" in your .exrc file then
             "yowza" is executed.

        novice, nov
             The  command  ":set  novice"  is  equivelent  to  ":set
             nomagic report=1 showmode".

        paragraphs, pa
             The { and } commands move the cursor forward  or  back-
             ward 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



                               March 23, 1992





        5-8                       OPTIONS                        5-8


             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.

        more When Elvis must display a sequence of messages  at  the
             bottom  line  of the screen in visual mode, it normally
             pauses after all but the last one, so you have time  to
             read them all.

             If you turn off the "more" option, then Elvis will  not
             pause.   This means you can only read the last message,
             but it is usually the most important one anyway.

        prompt, pr
             If you ":set noprompt", then Elvis will no longer  emit
             a  ':'  when  it  expects you to type in an ex command.
             This is slightly useful if you're  using  an  astonish-
             ingly  slow  UNIX  machine, but the rest of us can just
             ignore this one.

        readonly, ro
             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 different file.

             If you set the readonly option, then Elvis will pretend
             you  don't  have write permission to any 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.

        remap
             The ":map"  command  allows  you  to  convert  one  key
             sequence  into another.  The remap option allows you to
             specify what should happen if portions  of  that  other
             sequence  are  also  in the map table.  If remap is on,
             then those portions will also be  mapped,  just  as  if
             they  had been typed on the keyboard.  If remap is off,
             then the matching portions will not be mapped.

             For example, if you enter the commands ":map A  B"  and
             ":map  B C", then when remap is on, A will be converted



                               March 23, 1992





        5-9                       OPTIONS                        5-9


             to C.  But when remap is off, A will be converted  only
             to B.

        report, re
             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.

        ruler, ru
             This option is normally off.  If you turn it  on,  then
             Elvis  will  constantly display the line/column numbers
             of the cursor, at the bottom of the screen.

        scroll, sc
             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.   If you invoke ^U or ^D with a count argu-
             ment (for example, "33^D") then this option's value  is
             set to the count.

        sections, se
             The [[ and ]] commands move the cursor backward or for-
             ward  in increments of 1 section.  Sections may be del-
             imited 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.

        shell, sh
             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.

        shiftwidth, sw
             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.

        showmatch, sm
             With showmatch set, in input mode every  time  you  hit
             one  of  )}], Elvis will momentarily move the cursor to
             the matching ({[.




                               March 23, 1992





        5-10                      OPTIONS                       5-10


        showmode, smd
             In visual mode, it is easy to forget whether you're  in
             the  visual  command  mode or input/replace mode.  Nor-
             mally, 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.

        sidescroll, ss
             For long lines, Elvis scrolls sideways.  (This is  dif-
             ferent 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.

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

        sync, sy
             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
             the  OS  will not copy changes to the hard disk immedi-
             ately, so recovery might not be possible.  The [no]sync
             option lets you control this.

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

             In sync mode (which is the default for  MS-DOS,  Amiga-
             Dos,  and  Atari  TOS), Elvis forces all changes out to
             disk every time you make a change.  This  is  generally
             safer,  but slower.  It can also be a rather rude thing
             to do on a multi-user system.

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

        taglength, tl
             This option allows you to specify how  many  characters
             of  a tag's name must match when performing tag lookup.
             As a special case, ":set taglength=0"  means  that  all
             characters of a tag's name must match.

             Note: some configurations of Elvis don't  support  this
             option.





                               March 23, 1992





        5-11                      OPTIONS                       5-11

        term, te
             This read-only option shows the  name  of  the  termcap
             entry that Elvis is using for your terminal.

        terse, tr
             The real vi uses  this  option  to  select  longer  vs.
             shorter  error  messages.   Elvis  has  only one set of
             error messages, though, so this option has no effect.

        timeout, to
             The command ":set notimeout"  is  equivelent  to  ":set
             keytime=0",  and  ":set timeout" is equivelent to ":set
             keytime=1".  This affects the behaviour  of  the  <Esc>
             key.   See  the  discussion of the "keytime" option for
             more information.

        warn, wa
             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.

        window, wi
             This option controls how many lines are redrawn after a
             long move.

             On fast terminals, this is usually set to the number of
             rows  that  the  terminal can display, minus one.  This
             causes the entire screen to be filled with text  around
             the cursor.

             On slow terminals, you may wish to reduce this value to
             about  7  or  so.   That way, if you're doing something
             like  repeatedly  hitting  'n'  to  search   for   each
             occurrence of some string and trying to find a particu-
             lar occurrence, then you don't need to wait as long for
             Elvis to redraw the screen after each search.

        wrapmargin, wm
             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
             come  too close to the right-hand margin.  For example:
             On an 80-column screen, ":set wm=10" will  cause  lines
             to wrap when their length exceeds 70 columns.

        wrapscan, ws
             Normally, when you search  for  something,  Elvis  will



                               March 23, 1992





        5-12                      OPTIONS                       5-12


             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.

        writeany, wr
             With "writeany" turned off, elvis will prevent you from
             accidentally overwriting a file.  For example, if "foo"
             exists then ":w foo" will fail.  If  you  turn  on  the
             "writeany" option, then ":w foo" will work.

             Regardless of the setting of "writeany",  though,  ":w!
             foo"  will  work.   The  '!' forces the ":w" command to
             write the file unless the operating system won't  allow
             it.







































                               March 23, 1992








        6.  CUT BUFFERS

             When Elvis deletes text, it stores that text in  a  cut
        buffer.   This  happens  in  both  visual  mode and EX mode.
        There is no practical limit to how much text  a  cut  buffer
        can hold.

             There are 36 cut buffers: 26 named buffers ("a  through
        "z),  9  anonymous  buffers ("1 through "9), and 1 extra cut
        buffer (".).

             In EX mode, the :move and  :copy  commands  use  a  cut
        buffer to temporarily hold the text to be moved/copied.

        6.1.  Putting text into a Cut Buffer

             In visual mode, text is copied into a cut  buffer  when
        you  use the d, y, c, C, s, or x commands.  There are also a
        few others.

             By default, the text goes into the "1 buffer.  The text
        that  used to be in "1 gets shifted into "2, "2 gets shifted
        into "3, and so on.  The text that used to be in "9 is lost.
        This  way,  the last 9 things you deleted are still accessi-
        ble.

             You can also put the text into a  named  buffer  --  "a
        through  "z.   To do this, you should type the buffer's name
        (two keystrokes: a  double-quote  and  a  lowercase  letter)
        before  the  command  that  will  cut the text.  When you do
        this, "1 through "9 are not affected by the cut.

             You can append text to one of the named buffers.  To do
        this,  type  the  buffer's name in uppercase (a double-quote
        and an uppercase letter) before the d/y/c/C/s/x command.

             The ". buffer is special.  It  isn't  affected  by  the
        d/y/c/C/s/x  command.   Instead, it stores the text that you
        typed in the last time you were in input mode.  It  is  used
        to implement the . visual command, and ^A in input mode.

             In EX mode (also known as  colon  mode),  the  :delete,
        :change, and :yank commands all copy text into a cut buffer.
        Like the visual commands, these EX commands normally use the
        "1  buffer, but you can use one of the named buffers by giv-
        ing its name after the command.  For example,

             :20,30y a


        will copy lines 20 through 30 into cut buffer "a.

             You can't directly put text into the ". buffer, or  the
        "2 through "9 buffers.



                               March 23, 1992





        6-2                     CUT BUFFERS                      6-2


        6.2.  Pasting from a Cut Buffer

             There  are  two  styles  of  pasting:   line-mode   and
        character-mode.   If a cut buffer contains whole lines (from
        a command like "dd") then line-mode pasting is used;  if  it
        contains  partial  lines  (from  a  command  like "dw") then
        character-mode pasting is used.  The EX commands always  cut
        whole lines.

             Character-mode pasting causes the text to  be  inserted
        into the line that the cursor is on.

             Line-mode pasting inserts the text on a new line  above
        or  below the line that the cursor is on.  It doesn't affect
        the cursor's line at all.

             In visual mode, the p and P commands insert text from a
        cut  buffer.   Uppercase P will insert it before the cursor,
        and lowercase p will insert it after the cursor.   Normally,
        these  commands  will  paste from the "1 buffer, but you can
        specify any other buffer to paste from.  Just type its  name
        (a double-quote and another character) before you type the P
        or p.

             In EX mode, the (pu)t command pastes text after a given
        line.   To paste from a buffer other that "1, enter its name
        after the command.

        6.3.  Macros

             The contents of a named cut buffer can be executed as a
        series of ex/vi commands.

             To put the instructions into the cut buffer,  you  must
        first insert them into the file, and then delete them into a
        named cut buffer.

             To execute a cut buffer's contents as EX commands,  you
        should  give  the EX command "@" and the name of the buffer.
        For example, :@z will execute "z as a series of EX commands.

             To execute a cut buffer's contents as visual  commands,
        you should give the visual command "@" and the letter of the
        buffer's name.  The visual "@" command is different from the
        EX  "@"  command.   They interpret the cut buffer's contents
        differently.

             The visual @ command can be rather finicky.  Each char-
        acter  in the buffer is interpretted as a keystroke.  If you
        load the instructions into the cut buffer via  a  "zdd  com-
        mand, then the newline character at the end of the line will
        be executed just like any other  character,  so  the  cursor
        would be moved down 1 line.  If you don't want the cursor to
        move down 1 line at the end of each  @z  command,  then  you



                               March 23, 1992





        6-3                     CUT BUFFERS                      6-3


        should load the cut buffer by saying 0"zD instead.

             Although cut buffers can hold any amount of text, Elvis
        can  only  execute small buffers.  The size limit is roughly
        1000 characters, for either EX macros or VI  macros.   If  a
        buffer  is  too  large  to  execute,  an  error  message  is
        displayed.

             You can't nest :@ commands.  You can't run :@  commands
        from  your  .exrc  file,  or  any other :source file either.
        Similarly, you can't run a :source command from within an  @
        command.   Hopefully, these restrictions will be lifted in a
        later version.

        6.4.  The Effect of Switching Files

             When Elvis first starts up, all cut buffers are  empty.
        When  you  switch to a different file (via the :n or :e com-
        mands perhaps) the  9  anonymous  cut  buffers  are  emptied
        again,  but  the  other  27  buffers ("a through "z, and ".)
        retain their text.




































                               March 23, 1992








        7.  DIFFERENCES BETWEEN Elvis & BSD VI/EX

             Elvis is not  100%  compatible  with  the  real  vi/ex.
        Elvis  has  many small extensions, some omissions, and a few
        features which  are  implemented  in  a  slightly  different
        manner.

        7.1.  Extensions

        Save Configuration
                  The :mkexrc command saves  the  current  :set  and
                  :map  configurations  in  the ".exrc" file in your
                  current directory.

        Previous File
                  The :N or :prev command  moves  backwards  through
                  the args list.

        Center Current Row
                  In visual command mode, the (lowercase) "zz"  com-
                  mand  will  center the current line on the screen,
                  like "z=".

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

        Previous Text
                  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).

        Keyword Lookup
                  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 com-
                  mand  alone  is worth the price of admission!  See
                  the ctags and ref programs.

        Increment/Decrement
                  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 Mode
                  You can backspace past the beginning of the line.




                               March 23, 1992





        7-2        DIFFERENCES BETWEEN Elvis & BSD VI/EX         7-2


                  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.

        Start in Input Mode
                  If you ":set inputmode" in your .exrc  file,  then
                  Elvis  will  start  up  in  input  mode instead of
                  visual command mode.

        Visible Fonts
                  With   ":set   charattr",   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.

        File Syncing
                  After a crash, you can usually recover the altered
                  form  of  the  file  from  the temporary file that
                  Elvis uses -- unless the temporary file  was  cor-
                  rupted.

                  UNIX systems  use  a  delayed-write  cache,  which
                  means  that  when Elvis tries to write to the tem-
                  porary file, the information might still be in RAM
                  instead  of  on the disk.  A power failure at that
                  time would cause  the  in-RAM  information  to  be
                  lost.   UNIX's  sync()  call  will  force all such



                               March 23, 1992





        7-3        DIFFERENCES BETWEEN Elvis & BSD VI/EX         7-3


                  information to disk.

                  MS-DOS and Atari TOS don't write a  file's  length
                  to  disk until that file is closed.  Consequently,
                  the temporary file would appear to be 0 bytes long
                  if  power  failed  when we were editing.  To avoid
                  this problem, a sync() function has  been  written
                  which  will  close  the  temporary  file  and then
                  immediately reopen it.

        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.

        Hide nroff Lines
                  Th ":set hideformat"  option  hides  nroff  format
                  control  lines.  (They are displayed on the screen
                  as blank lines.)

        Compiler Interface
                  Elvis is clever enough to parse the error messages
                  emitted  by  many compilers.  To use this feature,
                  you should collect your compiler's error  messages
                  into a file called "errlist"; Elvis will read this
                  file, determine which source file caused the error
                  messages, start editing that file, move the cursor
                  to the line where  the  error  was  detected,  and
                  display  the  error  message  on  the status line.
                  Nifty!

        Visible Text Selection
                  In visual command mode, 'v' starts visibly select-
                  ing  characters  and  'V' starts visibly selecting
                  whole lines.  The character or line where the cur-
                  sor  is located becomes one endpoint of the selec-
                  tion.  You can then use the standard cursor  move-
                  ment commands to move the cursor to the other end-
                  point, and then press one of the operator commands
                  (c/d/y/</>/!/=/\).  The operator will then immedi-
                  ately be applied to the selected text.

        Pop-up Menu Operator
                  The '\' key is a new operator, similar  in  opera-
                  tion to the c/d/y/</>/! operators It conjures up a
                  menu, from which you can select any of  the  other
                  operators plus a few other common commands.

        Preset Filter Operator
                  The '=' key is another new operator.  It is  simi-
                  lar  to  the  '!'  operator, except that while '!'
                  asks you to type in a filter  command  each  time,
                  '='  assumes  it  should  always  run  the command
                  stored in the equalprg option.



                               March 23, 1992





        7-4        DIFFERENCES BETWEEN Elvis & BSD VI/EX         7-4


        Move to a Given Percentage
                  The '%' movement key can now  accept  an  optional
                  count.   Without  a count, the '%' key still moves
                  to a matching  parenthesis  like  it  always  did.
                  With  a count somewhere between 1 and 100, though,
                  it moves the cursor to approximately a given  per-
                  centage of the way through the file.  For example,
                  typing "50%" will move the cursor to the middle of
                  the file.

        Regular Expressions
                  In regular expressions, several new forms of  clo-
                  sure  operators  are  supported: \{n}, \{n,m}, \+,
                  and \?.

        7.2.  Omissions

             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.
        So  is  the  -r  flag.   I've never had a good reason to use
        ":preserve", and  since  ":recover"  is  used  so  rarely  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, I figured.

             LISP support is missing.  However, the = key  is  still
        an  operator  that  reformats lines of text.  By default, it
        reformats lines by sending them through the fmt filter,  but
        you could write your own LISP beautifier and configure elvis
        to use it.  Key mappings  could  take  care  of  most  other
        differences.  Auto-indent is the only thing that is irrecov-
        erably lost.

             Autoindent mode acts a little different from  the  real
        vi, anyway.  It doesn't handle ^^D or 0^D correctly.  On the
        other hand, it does allow ^D and ^T to be used  anywhere  in
        the line, to adjust the indentation for the whole line.













                               March 23, 1992








        8.  INTERNAL

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

             You should also check out the CFLAGS, TERMCAP, ENVIRON-
        MENT  VARIABLES, VERSIONS, and QUIESTIONS & ANSWERS sections
        of this manual.

        8.1.  The temporary file

             The temporary file is divided into blocks of 1024 bytes
        each.  The functions in "blk.c" maintain a cache of the five
        most recently used blocks, to minimize file I/O.

             When Elvis starts up, the file is copied into the  tem-
        porary  file  by  the function tmpstart() in "tmp.c".  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 characters.  the input file
        must not contain any NULs, to avoid  confusion.   This  also
        limits lines to a length of 1023 characters or less.

             The data blocks aren't necessarily stored in  sequence.
        For  example,  it  is  entirely possible that the data block
        containing the first lines of text will be stored after  the
        block containing the last lines of text.

             In RAM, Elvis maintains two lists: one  that  describes
        the  "proper"  order  of  the  disk blocks, and another that
        records the line number of the  last  line  in  each  block.
        When  Elvis  needs  to  fetch  a given line of text, it uses
        these tables to locate the data block  which  contains  that
        line.

             Before each change is made to the file, these lists are
        copied.  The copies can be used to "undo" the change.  Also,
        the first list -- the one that  lists  the  data  blocks  in
        their  proper order -- is written to the first data block of
        the temp file.  This list can be used during file recovery.

             When blocks are altered, they are rewritten to  a  dif-
        ferent  block  in  the  file,  and the order list is updated
        accordingly.  The original block is  left  intact,  so  that
        "undo"  can  be  performed  easily.   Elvis  will eventually
        reclaim the original block, when it is no longer needed.

        8.2.  Implementation of Editing

             There are three basic operations which affect text:

                + delete text   - delete(from, to)
                + add text      - add(at, text)



                               March 23, 1992





        8-2                       INTERNAL                       8-2


                + 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".)
        Yanking is implemented in the function cut(), and pasting is
        implemented  in  the  function paste().  These functions are
        defined in "cut.c".

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

             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 sim-
        ple as modifying a single block.  This is implemented in the
        function add().

             There is also a change() function, which generally just
        calls delete() and add().  For the special case where a sin-
        gle character is being replaced by another single character,
        though,  change() will optimize things somewhat.  The add(),
        delete(),  and  change()  functions  are  all   defined   in
        "modify.c".

             The input() function reads text from a user and inserts
        it  into  the  file.   It  makes  heavy  use  of  the add(),
        delete(), and change() functions.  It inserts characters one
        at a time, as they are typed.

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

        8.3.  Marks and the Cursor

             Marks are places within the text.  They are represented
        internally  as  32-bit  values which are split into two bit-
        fields: a line number and a character index.   Line  numbers
        start with 1, and character indexes start with 0.  Lines can
        be up to 1023 characters long, so the character index is  10



                               March 23, 1992





        8-3                       INTERNAL                       8-3


        bits wide and the line number fills the remaining 22 bits in
        the long int.

             Since line numbers start with 1, it is impossible for a
        valid  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.   Marks  are
        adjusted similarly after new text is inserted.

             The cursor is represented as a mark.

        8.4.  Colon Command Interpretation

             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.

        8.5.  Screen Control

             In input mode or visual command  mode,  the  screen  is
        redrawn  by  a  function  called redraw().  This function is
        called in the getkey() function  before  each  keystroke  is
        read in, if necessary.

             Redraw() write to the screen 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.

             (Note: Under MS-DOS, the pseudo-curses macros check  to
        see  whether you're using the pcbios interface.  If you are,
        then the macros call functions in "pc.c" to implement screen
        updates.)

             The  low-level  functions  which  modify  text  (namely
        add(), delete(), and change()) supply redraw() with clues to
        help redraw() decide which  parts  of  the  screen  must  be
        redrawn.    The  clues  are  given  via  a  function  called
        redrawrange().

             Most EX commands use the pseudo-curses package to  per-
        form their output, like redraw().




                               March 23, 1992





        8-4                       INTERNAL                       8-4


             There is also a function called msg()  which  uses  the
        same  syntax  as printf().  In EX mode, msg() writes message
        to the screen and automatically adds a newline.  In VI mode,
        msg()  writes  the  message on the bottom line of the screen
        with the "standout" character attribute turned on.

        8.6.  Options

             For each option available through the  ":set"  command,
        Elvis contains a character array variable, named "o_option".
        For example, the  "lines"  option  uses  a  variable  called
        "o_lines".

             For boolean options, the array has a  dimension  of  1.
        The  first  (and only) character of the array will be NUL if
        the variable's value is FALSE, and some other value if it is
        TRUE.   To  check  the  value, just by dereference the array
        name, as in "if (*o_autoindent)".

             For number options, the array has  a  dimension  of  3.
        The  array  is  treated as three unsigned one-byte integers.
        The first byte is the current  value  of  the  option.   The
        second  and  third  bytes  are the lower and upper bounds of
        that option.

             For string options, the array usually has  a  dimension
        of about 60 but this may vary.  The option's value is stored
        as a normal NUL-terminated string.

             All of the options are declared in "opts.c".  Most  are
        initialized to their default values; the initopts() function
        is used to perform any environment-specific initialization.

        8.7.  Portability

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

             One of the more significant macros is ttyread().   This
        macro is used to read raw characters from the keyboard, pos-
        sibly with timeout.  For UNIX systems, this basically  reads
        bytes  from  stdin.  For MSDOS, TOS, and OS9, 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



                               March 23, 1992





        8-5                       INTERNAL                       8-5


        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.

             The file "tinytcap.c" contains a set of functions  that
        emulate  the  termcap  library  for  a small set of terminal
        types.  The terminal-specific info is hard-coded  into  this
        file.   It  is only used for systems that don't support real
        termcap.  Another alternative for screen control can be seen
        in  the  "curses.h"  and  "pc.c"  files.  Here, macros named
        VOIDBIOS and CHECKBIOS are used to indirectly call functions
        which perform low-level screen manipulation via BIOS calls.

             The stat() function must be able to come up with  UNIX-
        style  major/minor/inode  numbers  that  uniquely identify a
        file or directory.

             Please try to keep you changes localized, and wrap them
        in  #if/#endif pairs, so that Elvis can still be compiled on
        other systems.  And PLEASE let me know about it,  so  I  can
        incorporate your changes into my latest-and-greatest version
        of Elvis.































                               March 23, 1992








        9.  CFLAGS

             Elvis uses many preprocessor symbols to control  compi-
        lation.   Some  of  these  control  the sizes of buffers and
        such.  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 some sets because otherwise  Elvis  would  be  too
        bulky  to  compile.   The "asld" phase of the compiler craps
        out.

        -DM_SYSV, -Dbsd, -DTOS, -DCOHERENT, -Damiga
             These flags tell the compiler that Elvis is being  com-
             piled for System-V UNIX, BSD UNIX, Atari TOS, Coherent,
             or AmigaDos,  respectively.   For  other  systems,  the
             config.h  file  can  generally  figure it out automati-
             cally.

        -DRAINBOW
             For MS-DOS systems, this causes  support  for  the  DEC
             Rainbow to be compiled into Elvis.

        -DS5WINSIZE
             Some versions of SysV UNIX don't  support  support  the
             "winsize"   style  of  screen-size  testing,  so  elvis
             ignores window size changes by default.

             However, many of the newer SysV systems  defines  "win-
             size"  in  the file "/usr/include/sys/ptem.h".  If your
             SysV  system  has  "winsize"  then   you   should   add
             -DS5SWINSIZE to the CFLAGS setting.

        -DTERMIOS
             POSIX is a SysV-derived specification which uses a ter-
             minal  control  package  called  "termios",  instead of
             "termio".  Some other SysV systems may  also  use  ter-
             mios.   You  can make elvis uses termios instead of the
             more common  termio  by  adding  -DTERMIOS  to  CFLAGS.
             (Note: This hasn't been tested very well.)

        -DNBUFS=number
             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 5 blocks, and the
             minimum is 3 blocks.  (See the -DBLKSIZE flag, below.)

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




                               March 23, 1992





        9-2                        CFLAGS                        9-2


        -DBLKSIZE=number
             This controls the size of blocks that Elvis uses inter-
             nally.   The  value  of BLKSIZE must be a power of two.
             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.   For  MS-DOS,
             Coherent,  and  Minix-PC,  the  default  value is 1024,
             which allows you to edit files up to almost 512K  bytes
             long.   For  all  other  systems,  the default value is
             2048, which allows you to edit files that are nearly  2
             megabytes long.

             The BLKSIZE also determines the  maximum  line  length,
             and  a few other limits.  BLKSIZE should be either 256,
             512, 1024, or 2048.  Values other than these  can  lead
             to strange behaviour.

        -DTMPDIR=string
             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.

        -DEXRC=str, -DHMEXRC=str, -DSYSEXRC=str, -DEXINIT=str
             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.   Since  that
             isn't  a  legal  DOS filename, under DOS the default is
             "elvis.rc".  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, in quotes.

             EXINIT is the name of an environment variable that  can
             contain  initialization  commands.  Normally, its value
             is "EXINIT".

        -DKEYWORDPRG=string
             This  flag  determines  the  default   value   of   the



                               March 23, 1992





        9-3                        CFLAGS                        9-3


             "keywordprg" option.  Its value must be a string, so be
             careful about quoting.  The default value of this  flag
             is "ref", which is a C reference program.

        -DCC_COMMAND=string -DMAKE_COMMAND=string -DERRLIST=string
             These control the names of the C compiler,  the  "make"
             utility, and the error output file, respectively.  They
             are only used if -DNO_ERRLIST is not given.

             The default value of CC_COMMAND depends on the  Operat-
             ing  System and compiler that you use to compile elvis;
             for UNIX, the default is "cc".  The default  values  of
             MAKE_COMMAND  and  ERRLIST  are  "make"  and "errlist",
             respectively.

        -DMAXRCLEN=number
             This determines how large a :@  macro  command  can  be
             (measured  in  bytes).   The default is 1000 bytes.  If
             you increase this value  significantly,  then  you  may
             need  to  allocate extra memory for the stack.  See the
             "CHMEM" setting in the Makefile.

        -DSHELL=string
             This is the default value of the  "shell"  option,  and
             hence  the  default shell used from within Elvis.  This
             only controls the default; the value you give here  may
             be  overridden  at  run-time  by setting an environment
             variable named SHELL  (or  COMSPEC  for  MS-DOS).   Its
             value  must  be  a string constant, so be careful about
             quoting.

        -DTAGS=string
             This sets the name of the "tags" file, which is used by
             the :tag command.  Its value must be a string constant,
             so be careful about quoting.

        -DCS_IBMPC -DCS_LATIN1 -DCS_SPECIAL
             The digraph table and  flipcase  option  will  normally
             start  out  empty.   However,  if you add -DCS_IBMPC or
             -DCS_LATIN1 to your CFLAGS, then they  will  start  out
             filled  with values that are appropriate for the IBM PC
             character set or the ISO Latin-1 character set, respec-
             tively.

             You can also use -DCS_IBMPC and  -DCS_SPECIAL  together
             to  get  digraphs that produce the PC's graphic charac-
             ters.

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

             -DDEBUG2 causes a line to be appended to a file  called



                               March 23, 1992





        9-4                        CFLAGS                        9-4


             "debug.out"  everytime  any  change is made to the edit
             buffer.

        -DCRUNCH
             This flag removes some non-critical code, so that Elvis
             is  smaller.   For example, it removes a short-cut from
             the regexp package, so that text searches  are  slower.
             Also, screen updates are not as efficient.  A couple of
             obscure features are disabled by this, too.

        -DNO_MKEXRC
             This removes the ":mkexrc"  command,  so  you  have  to
             create any .exrc files manually.  The size of the .text
             segment will be reduced by about 600 bytes.

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

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

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

             Interestingly, the real vi never  recycles  space  from
             its temporary file.

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

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

        -DNO_EXTENSIONS



                               March 23, 1992





        9-5                        CFLAGS                        9-5


             Leaves out the "K" and "#" visual commands.  Also,  the
             arrow  keys will no longer work in input mode.  Regular
             expressions will no longer recognize the \{\} operator.
             (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 250
             bytes.

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

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

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

        -DNO_DIGRAPH
             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 char-
             acters, 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.

        -DNO_ERRLIST
             Elvis adds a ":errlist" command,  which  is  useful  to
             programmers.   If  you don't need this feature, you can
             disable it via the -DNO_ERRLIST flag.  This will reduce
             the .text segment by about 900 bytes, and the .bss seg-
             ment by about 300 bytes.

        -DNO_ABBR
             The -DNO_ABBR flag disables the  ":abbr"  command,  and
             reduces the size of Elvis by about 250 bytes.

        -DNO_OPTCOLS
             When Elvis displays the current  options  settings  via
             the  ":set"  command,  the  options are normally sorted
             into columns.  The -DNO_OPTCOLS flag causes the options
             to be sorted across the rows, which is much simpler for
             the computer.  The -DNO_OPTCOLS flag  will  reduce  the
             size of your .text segment by about 500 bytes.

        -DNO_MODELINES



                               March 23, 1992





        9-6                        CFLAGS                        9-6


             This removes all support for modelines.

        -DNO_TAG
             This disables tag lookup.  It reduces the size  of  the
             .text segment by about 750 bytes.

        -DNO_ALT_FKEY -DNO_CTRL_FKEY -DNO_SHIFT_FKEY -DNO_FKEY
             These remove explicit  support  of  function  keys.   -
             DNO_ALT_FKEY  removes  support for the <alternate> ver-
             sions function keys.   -DNO_CTRL_FKEY  removes  support
             for  the  <control>  and  <alternate> versions function
             keys.  -DNO_SHIFT_FKEY removes support for the <shift>,
             <control>,  and  <alternate> versions function keys.  -
             DNO_FKEY removes all support of function keys.

             Elvis's ":map" command normally allows you to  use  the
             special  sequence  "#<n>" to map function key <n>.  For
             example, ":map #1 {!}fmt^M" will cause the <F1> key  to
             reformat  a paragraph.  Elvis checks the :k1=: field in
             the termcap description of your terminal to figure  out
             what  code  is  sent  by  the  <F1> key.  This is handy
             because it allows you to create a .exrc file which maps
             function  keys  the same way regardless of what type of
             terminal you use.

             That behaviour is standard; most implementations of the
             real  vi  supports it too.  Elvis extends this to allow
             you to use "#1s" to refer  to  <shift>+<F1>,  "#1c"  to
             refer   to   <control>+<F1>,  and  "#1a"  to  refer  to
             <alt>+<F1>.  The termcap description for  the  terminal
             should have fields named :s1=:c1=:a1=: respectively, to
             define the code sent by these key  conbinations.   (You
             should  also  have  :k2=:s2=:c2=:a2=: for the <F2> key,
             and so on.)

             But there  may  be  problems.   The  terminfo  database
             doesn't  support :s1=:c1=:a1=:, so no terminfo terminal
             description could ever support shift/control/alt  func-
             tion  keys; so you might as well add -DNO_SHIFT_FKEY to
             CFLAGS if you're using terminfo.

             Note that, even if you have -DNO_FKEYS, you  can  still
             configure  Elvis  to  use your function keys my mapping
             the literal character codes sent by the key.  You  just
             couldn't do it in a terminal-independent way.  TERM_925

        -DTERM_AMIGA -DTERM_VT100 -DTERM_VT52 etc.
             The tinytcap.c file contains  descriptions  of  several
             terminal  types.  For each system that uses tinytcap, a
             reasonable subset  of  the  available  descriptions  is
             actually  compiled  into Elvis.  If you wish to enlarge
             this  subset,  then  you  can   add   the   appropriate
             -DTERM_XXX flag to your CFLAGS settings.




                               March 23, 1992





        9-7                        CFLAGS                        9-7


             For a list of the available terminal types,  check  the
             tinytcap.c file.

        -DINTERNAL_TAGS
             Normally, Elvis uses the "ref" program to  perform  tag
             lookup.   This  is more powerful than the real vi's tag
             lookup, but it can be much slower.

             If you add -DINTERNAL_TAGS to your CFLAGS setting, then
             will  use  its  own  internal tag lookup code, which is
             faster.

        -DPRSVDIR=directory
             This controls where preserved files will be placed.  An
             appropriate  default has been chosen for each Operating
             System, so you probably don't need to worry about it.

        -DFILEPERMS=number
             This affects the attributes of files that  are  created
             by  Elvis;  it  is  used  as the second argument to the
             creat() function.  The default is 0666 which  (on  UNIX
             systems  at least) means that anybody can read or write
             the new file, but nobody can execute it.  On UNIX  sys-
             tems, the creat() call modifies this via the umask set-
             ting.

        -DKEYBUFSIZE=number
             This determines the size of the type-ahead buffer  that
             elvis uses.  It also limits the size of keymaps that it
             can handle.  The  default  is  1000  characters,  which
             should be plenty.


























                               March 23, 1992








        10.  TERMCAP

             Elvis uses fairly  standard  termcap  fields  for  most
        things.   I  invented  the cursor shape names but other than
        that there should be few surprises.

        Required numeric fields

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


        Required string fields

            :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


        Boolean fields

            :am:    auto margins - wrap when char is written in last column?
            :xn:    brain-damaged auto margins - newline ignored after wrap
            :pt:    physical tabs?


        Optional string fields

            :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 row at top of screen)
            :vb=:   visible bell
            :ti=:   terminal initialization string, to start full-screen mode
            :te=:   terminal termination, to end full-screen mode
            :ks=:   enables the cursor keypad
            :ke=:   disables the cursor keypad


        Optional strings received from the keyboard

            :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
            :kP=:   sequence sent by the <PgUp> key
            :kN=:   sequence sent by the <PgDn> key
            :kh=:   sequence sent by the <Home> key
            :kH=:   sequence sent by the <End> key
            :kI=:   sequence sent by the <Insert> key


                           March 23, 1992





        10-2                      TERMCAP                       10-2



             Originally, termcap  didn't  have  any  names  for  the
        <PgUp>,  <PgDn>, <Home>, and <End> keys.  Although the capa-
        bility names shown in the table above are the  most  common,
        they  are  not  universal.  SCO Xenix uses :PU=:PD=:HM=:EN=:
        for those keys.  Also, if the four arrow keys happen  to  be
        part  of  a  3x3 keypad, then the five non-arrow keys may be
        named :K1=: through :K5=:, so an  IBM  PC  keyboard  may  be
        described  using those names instead.  Elvis can find any of
        these names.

        Optional strings sent by function keys

            :k1=:...:k9=:k0=:       codes sent by <F1> through <F10> keys
            :s1=:...:s9=:s0=:       codes sent by <Shift F1> ... <Shift F10>
            :c1=:...:c9=:c0=:       codes sent by <Ctrl F1> ... <Ctrl F10>
            :a1=:...:a9=:a0=:       codes sent by <Alt F1> ... <Alt F10>


             Note that :k0=: is used  to  describe  the  <F10>  key.
        Some  termcap  documents  recommend  :ka=: or even :k;=: for
        describing the <F10> key, but Elvis doesn't support that.

             Also, the :s1=:..., :c1=:..., and  :a1=:...  codes  are
        very  non-standard.   The  terminfo  library doesn't support
        them.

        Optional fields that describe character attributes

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


        Optional fields that affect the cursor's shape

             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 used for reading EX command
            :cV=:   cursor used for reading VI commands
            :cI=:   cursor used during VI input mode
            :cR=:   cursor used during VI replace mode


             If the capabilities above aren't given, then Elvis will
        try to use the following values instead.

            :ve=:   normal cursor, used as :cQ=:cX=:cI=:cR=:
            :vs=:   gaudy cursor, used as :cV=:


                           March 23, 1992





        10-3                      TERMCAP                       10-3




        An example

             Here's the termcap entry I use on my  Minix-ST  system.
        Some  of  the  fields  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:\
            :is=\E[0~: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:\
            :md=\E[1m:me=\E[m:as=\E[1;3m:ae=\E[m:\
            :ku=\E[A:kd=\E[B:kr=\E[C:kl=\E[D:\
            :k1=\E[1~:k2=\E[2~:k3=\E[3~:k4=\E[4~:k5=\E[5~:\
            :k6=\E[6~:k7=\E[17~:k8=\E[18~:k9=\E[19~:k0=\E[20~:\
            :kU=\E[36~:kQ=\E[32~:kH=\E[28~:\
            :GV=3:GH=D:G1=?:G2=Z:G3=@:G4=Y:GC=E:GL=4:GR=C:GU=A:GD=B:\
            :cQ=\E[k:cX=\E[2;0k:cV=\E[16;0k:cI=\E[k:cR=\E[16;20k:


































                               March 23, 1992








        11.  ENVIRONMENT VARIABLES

             Elvis examines several environment  variables  when  it
        starts  up.   The  values of these variables are used inter-
        nally 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 AmigaDOS, MS-DOS or TOS systems,  even  that
        is optional.

        TERM, TERMCAP

             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.

             If your version of Elvis is using tinytcap  instead  of
        the  full  termcap library, then the value of TERMCAP cannot
        contain any  backslash  escapes  (\E,  \r,  etc.)  or  carat
        escapes  (^[, ^M, etc.), because tinytcap doesn't understand
        them.  Instead, you should embed the actual control  charac-
        ter into the string.

        TMP, TEMP

             These only work for AmigaDOS,  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.

        LINES, COLUMNS

             The termcap entry for your terminal should specify  the
        size of your screen.  If you're using a windowing interface,
        then there is an ioctl() call which will provide the size of
        the  window;  the ioctl() values will override the values in
        the termcap entry.  The LINES and COLUMNS environment  vari-
        ables  (if  defined)  will override either of these sources.
        They, in turn, can be overridden by a ":set" command.

             Normally, the LINES  and  COLUMNS  variables  shouldn't
        need to be defined.

        EXINIT

             This variable's value may contain one  or  more  colon-
        mode  commands,  which  will  be  executed  after all of the
        ".exrc" files but before interactive editing begins.

             To put  more  than  one  command  in  EXINIT,  you  can
        separate the commands with either a newline or a '|' charac-
        ter.






                               March 23, 1992





        11-2               ENVIRONMENT VARIABLES                11-2


        SHELL, COMSPEC

             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.

        HOME

             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.

        TAGPATH

             This variable is used by the "ref"  program.   It  con-
        tains  a  list  of directories that might contain a relevent
        "tags" file.  Under AmigaDOS, MS-DOS or Atari TOS, the names
        of  the directories should be separated by semicolons (";").
        Under other operating systems, the names should be separated
        by colons (":").

             If you don't define TAGPATH,  then  "ref"  will  use  a
        default  list which includes the current directory and a few
        other likely places.  See the definition  of  DEFTAGPATH  at
        the start of ref.c for an accurate list.
































                               March 23, 1992








        12.  VERSIONS

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

             For all versions except MS-DOS, the file "Makefile.mix"
        should  be  copied  to "Makefile", and then edited to select
        the correct set of options for your system.  There  is  more
        information about this embedded in the file itself.

        12.1.  BSD UNIX

             Temporary files are stored in /tmp.

             You should modify /etc/rc so that the  temp  files  are
        preserved  when  the  system  is  rebooted.   Find a line in
        /etc/rc which reads
             ex4.3preserve /tmp

             or something like that, and append the  following  line
        after it:
             elvprsv /tmp/elv*

             If you do not have permission to modify /etc/rc,  don't
        fret.  The above modification is only needed to allow you to
        recover your changes after a system crash.   You  can  still
        run  Elvis  without  that  modification,  and  you can still
        recover your changes when Elvis crashes or when your  dialup
        modem  looses  the  carrier  signal, or something like that.
        Only a system crash or power failure could hurt you.

             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=man"  will  work  for Elvis, but Vi will complain
        because it doesn't have a "keywordprg" option.  If the warn-
        ing  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".

             If you use X windows, you may wish to add "-DCS_LATIN1"
        to  CFLAGS.  This will cause the digraph table and the flip-
        case option to have default values that are appropriate  for
        the  LATIN-1  character  set.  That's the standard character
        set for X.

             The default keyboard macro time-out value is larger for
        BSD  than  it  is  for  some other systems, because I've had
        trouble running Elvis via rlogin or Xterm.  I guess it takes
        a while for those keystokes to squirt through the net.




                               March 23, 1992





        12-2                      VERSIONS                      12-2


        12.2.  System-V UNIX

             Most SysV UNIX systems use terminfo instead of termcap,
        but  the  terminfo  library  doesn't seem to have a standard
        name.  As shipped, Elvis' Makefile.mix  is  configured  with
        "LIBS=-lterm". You may need to change it to "LIBS=-ltermcap"
        or "LIBS=-lterminfo" or even "LIBS=-lcurses".

             The /etc/rc file should be modified  as  described  for
        BSD  systems,  above.  The only difference is that SysV sys-
        tems tend to have directories for initialization, instead of
        a  single  large  /etc/rc  file.  Editor recovery is usually
        done somewhere in the /etc/rc2.d directory.

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

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

        12.3.  SCO Xenix

             For Xenix-386, you can use the  generic  System-V  set-
        tings.   You may wish to add "-DCS_IBMPC" to CFLAGS, to have
        the digraph table and flipcase option start  up  in  a  mode
        that is appropriate for the console.

        There is a separate group of settings for  use  with  Xenix-
        286.  It already has "-DCS_IBMPC" in CFLAGS.

             Because Xenix is so similar to System-V,  everything  I
        said  earlier  about  System-V  applies to the Xenix version
        too, except that  editor  recovery  probably  belongs  in  a
        directory called /etc/rc.d/8.

        12.4.  Minix

             There are separate settings in Makefile.mix for  Minix-
        PC  and  Minix-68k.   The  differences between these two are
        that the 68k version uses ".o" for the object file extension
        where  the PC version uses ".s", and the PC version has some
        extra flags in CFLAGS to reduce the size of Elvis.   The  PC
        version  also uses tinytcap (instead of the full termcap) to
        make it smaller.

             Minix-PC users should read the CFLAGS section  of  this
        manual very carefully.  You have some choices to make...

             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.   We  use  /usr/tmp
        instead  of  /tmp  because  after  a  system  crash or power
        failure, you can recover the altered version of a file  from
        the  temporary  file in /usr/tmp.  If it was stored in /tmp,
        though, then it would  be  lost  because  /tmp  is  normally



                               March 23, 1992





        12-3                      VERSIONS                      12-3


        located on the RAM disk.

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

        12.5.  Coherent

             Elvis was ported to Coherent by Esa Ahola.

             Elvis is too large to run  under  Coherent  unless  you
        eliminate  some features via the CFLAGS setting.  The recom-
        mended settings, in Makefile.mix, produce a working  version
        of Elvis which emulates Vi faithfully, but lacks most of the
        extensions.  You should read  the  CFLAGS  section  of  this
        manual carefully.

             You can probably reduce the  size  of  Elvis  by  using
        tinytcap.c  instead of -lterm.  This would allow you to keep
        most features of Elvis, at the expense of terminal  indepen-
        dence.   (Tinytcap.c  has  ANSI  escape sequences hard-coded
        into it.) To use tinytcap,  just  add  "tinytcap.o"  to  the
        "EXTRA="  line in the Makefile, and remove "-lterm" from the
        "LIBS=" line.

             The temporary files are stored  in  /tmp.   You  should
        modify your /etc/rc file as described for BSD earlier.

        12.6.  MS-DOS

             Elvis was ported to MS-DOS by Guntram Blohm and  Martin
        Patzel.  Willett Kempton added support for the DEC Rainbow.

             Ideally, Elvis should be compiled with Microsoft C 5.10
        and  the  standard  Microsoft  Make utility, via the command
        "make elvis.mak".  This will compile Elvis and  all  related
        utilities.

             With Microsoft C 6.00, use Makefile.mix  with  "NDMAKE"
        settings.  You  may  have trouble compiling regexp.c; if so,
        try compiling it without optimization.

             The "Makefile.mix" file contains  a  set  of  suggested
        settings for compiling elvis with Turbo-C or Borland C.  (If
        you have Turbo-C, but not the Make  utility,  then  you  can
        almost  use  the  "Elvis.prj" file to compile Elvis, but you
        must  explicitly  force  Turbo-C  to  compile  it  with  the
        "medium" memory model.  Most of the related programs [ctags,
        ref, virec, refont, and wildcard] are only one file long, so
        you  should  have  no trouble compiling them.) The "alias.c"
        file is meant to be compiled once into an  executable  named
        "ex.exe".   You  should  then  copy "ex.exe" to "vi.exe" and
        "view.exe".

             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  TMPDIR  to  something  else  before


                               March 23, 1992





        12-4                      VERSIONS                      12-4


        compiling.  You can also control the name of the temp direc-
        tory via an environment variable named  TMP  or  TEMP.   The
        directory must exist before you can run Elvis.

             The TERM environment variable determines how elvis will
        write  to  the screen.  It can be set to any one of the fol-
        lowing values:

                       pcbios    Use BIOS calls on an IBM-PC clone.
                       rainbow   Use DEC Rainbow interface.
                       ansi      Use ANSI.SYS driver.
                       nansi     User faster NANSI.SYS driver.


             If  the  TERM  variable  isn't  set,  then  elvis  will
        automatically  select  either  the "rainbow" interface (when
        run on a Rainbow) or "pcbios" (on an IBM clone).

             You may prefer to use NANSI.SYS for speed; or  you  may
        NEED to use ANSI.SYS for a non-clone, such as a lap-top.  If
        so, you should  install  one  of  these  drivers  by  adding
        "driver  = nansi.sys" (or whatever) to your CONFIG.SYS file,
        and then you should define TERM to be "nansi" (or  whatever)
        by  adding  "set TERM=nansi" 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.

             Since ".exrc" is not a valid DOS filename, the name  of
        the  initialization  file  has  been  changed to "elvis.rc".
        Elvis will look for an "elvis.rc" file first  in  your  home
        directory, and then in the current directory.  Note that you
        must set an environment variable named "HOME"  to  the  full
        pathname  of  your home directory, for Elvis to check there;
        if "HOME" isn't set,  then  Elvis  will  only  look  in  the
        current  directory.   To set "HOME", you would typically add
        the following line to your AUTOEXEC.BAT file:
             set HOME c:\

             An extra program, called "wildcard", is needed for  MS-
        DOS.   It  expands  wildcard  characters  in file names.  If
        Elvis flashes a "Bad command or filename"  message  when  it
        starts,  then  you've probably lost the WILDCARD.EXE program
        somehow.

             Elvis can run under Windows, but  only  in  full-screen
        mode.   Also,  Windows  uses  an environment variable called
        TEMP which interferes with elvis' usage  of  TEMP;  to  work
        around  this,  you  can  simply  set an environment variable
        named TMP (with no 'E') to  the  name  of  elvis'  temporary
        directory.   When  TEMP and TMP are both set, Elvis uses TMP
        and ignored TEMP.





                               March 23, 1992





        12-5                      VERSIONS                      12-5


        12.7.  Atari TOS

             Elvis was ported to Atari TOS by Guntram Blohm and Mar-
        tin  Patzel.   It is very similar to the MS-DOS version.  It
        has been tested with the Mark Williams C compiler  and  also
        GNU-C.

             The TERM environment variable is ignored; the  ST  port
        always  assumes  that  TERM=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".
        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.)

             Currently, character attributes cannot be displayed  on
        the screen.

             Elvis runs under MiNT (a free  multi-tasking  extension
        to  TOS)  but  it  can  be a CPU hog because of the way that
        Elvis reads from the keyboard  with  timeout.   Also,  Elvis
        doesn't  use  any  of  the special features of MiNT.  I have
        received a set of patches that optimize Elvis for MiNT,  but
        they arrived too late to integrate into this release.

        12.8.  OS9/68k

             Elvis was ported to OS9/68k by Peter Reinig.

             The Makefile is currently configured to  install  Elvis
        and  the  related  programs  in /dd/usr/cmds If this this is
        unacceptable, then you should change the BIN setting to some
        other  directory.   Similarly, it expects the source code to
        reside in /dd/usr/src/elvis; the ODIR  setting  is  used  to
        control this.

             Temporary files are stored in  the  /dd/tmp  directory.
        Your  /dd/startup file may need to be modified to prevent it
        from deleting Elvis' temporary files; make  /dd/startup  run
        the elvprsv program before it wipes out /dd/tmp.

             The program in alias.c is linked repeatedly to  produce
        the "vi", "view", and "input" aliases for Elvis.  Sadly, the
        "ex" alias is impossible to implement under OS9 because  the
        shell has a built-in command by that name.

             For some  purposes,  you  must  give  `make'  the  "-b"
        option.  Specifically, you need this for "make -b clean" and
        "make -b install".


                               March 23, 1992





        12-6                      VERSIONS                      12-6




        12.9.  VAX/VMS

             John Campbell ported Elvis to VAX/VMS.

             A heavily laden VAX can take half an  hour  to  compile
        elvis.  This is normal.  Don't panic.

             While running, elvis will  create  temporary  files  in
        SYS$SCRATCH.   Enter  SHOW  LOGICAL  SYS$SCRATCH to see what
        actual directory you are using.  Many sites have SYS$SCRATCH
        equivalenced  to  SYS$LOGIN.  The elvis temporary files look
        like the following on VMS while elvis is running:
               ELV_1123A.1;1       ELV_1123A.2;1       SO070202.;1

             Also, filtering commands (like !!dir and !}fmt)  should
        work  on  VMS.   This  assumes, however, that you can create
        temporary mailboxes and that your mailbox  quota  (a  sysgen
        parameter)  is  at least 256 bytes for a single write to the
        mailbox.  This is the default  sysgen  parameter,  so  there
        should be few people who experience filter problems.

             Additionally, an attempt was made to support the  stan-
        dard  terminals  on  VMS: "vt52", "vt100", "vt200", "vt300",
        "vt101", "vt102".  Non-standard terminals could be supported
        by  setting  your  terminal type to UNKNOWN (by entering SET
        TERM/UNKNOWN) and  defining  the  logical  name  ELVIS_TERM.
        Whatever  ELVIS_TERM translates to, however, will have to be
        included in tinytcap.c.  Note that the upper/lowercase  dis-
        tinctions are significant, and that DCL will upshift charac-
        ters that are not quoted strings, so enter DEFINE ELVIS_TERM
        "hp2621a".   As distributed, it would probably not be a good
        idea to have more than the standard terminals in  tinytcap.c
        (else  it  wouldn't  be  tiny, would it?).  Changes here, of
        course, would require a recompilation to take effect.

             If you have a version  of  the  "termcap"  library  and
        database  on  your  system,  then  you  may  wish to replace
        tinytcap with the real termcap.

        12.10.  AmigaDOS

             Mike Rieser and Dale Rahn ported Elvis to AmigaDOS.

             The port was done using  Manx  Aztec  C  version  5.2b.
        Elvis  uses about as much space as it can and still be small
        code and data.  Elvis should also compile under DICE, though
        there  may  be  a little trouble with signed versus unsigned
        chars.

             The port has been done so  the  same  binary  will  run
        under both versions of AmigaDOS.  Under AmigaDOS 2.04, Elvis
        supports all the  documented  features.   It  also  uses  an



                               March 23, 1992





        12-7                      VERSIONS                      12-7


        external program ref to do tag lookup.  So, the accompanying
        programs: ref and ctags  are  recommended.   Under  AmigaDOS
        1.2/1.3 Elvis works, buts lacks the more advanced features.

             For the port to AmigaDOS 2.04, we tried to use as  many
        Native  AmigaDOS  calls  as  we could.  This should increase
        Elvis's chances at  being  compiled  with  other  compilers.
        DICE  seems  to have a different default char type.  You may
        need to use the UCHAR() macro in tio.c.  To test it, try the
        :map command; if it looks right, things are cool.

             For the port to AmigaDOS 1.3, we tried to make sure the
        program  was  at  least  usable.  Many features are missing,
        most notably running commands in subshells.  Also,  what  we
        could  get working, we used Aztec functions to support them,
        so this part is little more compiler dependent.

             Aztec is compatible with the SAS  libcall  #pragma.   I
        personally  prefer  using the includes that come from Commo-
        dore over the ones supplied with Aztec, but for people  with
        a straight Aztec installation, I went with the default names
        for the Aztec pragmas.

             One include you'll need is <sys/types.h>.  Its a common
        include when porting software just make yourself one.  Its a
        two line file that saves a lot of hassle especially  in  the
        elvis  source.  So, make a directory where your includes are
        located called `sys' and in a file below that type:

                /* sys/types.h */
                #include <exec/types.h>

             When setting environment  variables  (either  local  or
        global)  for  variables  that specify a directory, make sure
        the variable ends in `:' or `/'.  This saved from having  to
        change  much  of the way elvis works.  The default temporary
        directory (if TEMP and TMP aren't specified) is  "T:".   The
        default  if  HOME directory (if no HOME environment variable
        is set) is "S:".

             To avoid conlict with other uses, Elvis  uses  elvis.rc
        instead of .exrc or where it looks for macros.

        12.11.  Other Systems

             For Sun workstations, use the BSD configuration.   Ear-
        lier  versions of elvis didn't link correctly due to a quirk
        in Sun's version of the "make" utility, but this version  of
        elvis has a work-around for that quirk so you should have no
        trouble at all.

             For Linux, use the SysV  settings.   You  can  probably
        just remove the "-lterm" from the "LIBS= -lterm" line, since
        linux keeps the termcap functions in the standard C library.



                               March 23, 1992





        12-8                      VERSIONS                      12-8


             For other UNIXoid systems, I suggest you start with the
        Minix-68k settings and then grow from that.  Minix is a nice
        starting point because it is a  clone  of  Version  7  UNIX,
        which  was  the  last  common  ancestor of BSD UNIX and SysV
        UNIX.  Any Operating System which claims any  UNIX  compati-
        bility  what  so  ever will therefore support V7/Minix code.
        You may need to fiddle with  #include  directives  or  some-
        thing,  though.   Minix-68k  is a better starting point than
        Minix-PC because the PC compiler has some severe quirks.
















































                               March 23, 1992








        13.  QUESTIONS & ANSWERS


        1) How can I make elvis run faster under DOS?

               There are several things you can do.  The first thing
               to  do is get a good screen driver such as NANSI.SYS.
               This can speed up screen redrawing by as  much  as  a
               factor of eight!  The DOS-specific part of section 12
               tells you how to do this.

               You might also consider  reducing  the  size  of  the
               blocks  that  elvis  uses.   You'll need to recompile
               Elvis to do this.  The default BLKSIZE is  1024  byte
               for  the  DOS  version of Elvis, which means that for
               each keystroke that you insert, elvis must  shift  an
               average of about 500 bytes.  That's a lot to ask from
               a little old 5MHz 8088.  A BLKSIZE of 512 bytes might
               be more appropriate.

               If you're really desperate for more speed, you  might
               want to make Elvis store its temporary files on a RAM
               disk.  However, this limits the size of the file  you
               can  edit,  and it eliminates any chance you may have
               had to recover your work after  a  power  failure  or
               system  crash,  but it might be worth it; you decide.
               To do this, add ":set dir=R:\" (or whatever your  RAM
               disk's name is) to the elvis.rc file.

               Next, consider turning off the "sync"  option.   When
               the  sync  option  is turned on, Elvis will close the
               temporary file and reopen it after every  change,  in
               order  to  force  DOS  to update the file's directory
               entry.  If you put ":set nosync"  into  the  elvis.rc
               file,  then  elvis  will only close the file when you
               start editing a different text file, or  when  you're
               exiting Elvis.  Consequently, there is no chance that
               you'll be able to recover your changes after a  power
               failure... so if you're going to this, then you might
               as well store the temp files on the RAM disk, too.


        2) Where's the <Esc> key on a DEC keyboard?

               I don't know.  Maybe the <F11> key?  You could always
               use ":map!" to make some other key act like the <Esc>
               key.  If all else fails, use <Control><[>.


        3) Is there a way to show which keys do what?

               Yes.  The command ":map" will show what each key does
               in  command  mode,  and  ":map!" (with an exclamation
               mark) shows what each key does in input mode.



                               March 23, 1992





        13-2                QUESTIONS & ANSWERS                 13-2


               The table is divided into three  columns:  the  key's
               label,  the characters that it sends, and the charac-
               ters that Elvis pretends you typed.


        4) How can I make Elvis display long lines like the real vi?

               You can't yet.  The next version of Elvis  shouldsup-
               port this, though.


        5) I can't recover my text  [under  MS-DOS  or  Atari  TOS].
           According to the directory listing, the temporary file is
           0 bytes long.  What went wrong?

               MS-DOS and TOS only update a file's  directory  entry
               when the file is closed.  If the system crashes while
               the file is still open, then  the  file's  length  is
               stored  as  0  bytes.  The ":set sync" option is sup-
               posed to prevent this; you probably turned it off  in
               the interest of speed, right?

               Under MS-DOS [I don't know  about  TOS],  you  should
               delete   the  empty  temporary  file,  and  then  run
               CHKDSK/F.  This might find the data that belonged  in
               the  empty  file,  and  place it in a new file with a
               name like "000001.CHK" -- something like  that.   You
               can  then try to extract the text from that temporary
               file by giving the  command  "elvprsv  -R  000001.chk
               >goodnews.txt".   If  you're  lucky,  then  your text
               might be in GOODNEWS.TXT.


        6) What is the most current version of Elvis?

               Each version of Elvis that is released to the  public
               has  a  version  number  of  the  form  "number point
               number".  As I write this, the most  current  version
               of elvis is 1.5.

               The intermediate steps between one  release  and  the
               next are labeled with the next version number, with a
               letter  appended.   For  example,   after   1.4   was
               released,  I started working on 1.5a.  I am currently
               working on 2.0a.  When Elvis reaches a stable  state,
               I'll call it 2.0 and release it.

               Sometimes a beta-test version of elvis will be avail-
               able  via  anonymous FTP from m2xenix.psg.com, in the
               directory "pub/elvis/beta".


        7) I only got executables, but now I want the  source  code.
           Where can I get it?



                               March 23, 1992





        13-3                QUESTIONS & ANSWERS                 13-3


               If you have access to the Internet, then  you  should
               be  able  to fetch it from one of the public archives
               such  as  plains.nodak.edu.   It  is  accessible  via
               anonymous   FTP,   or   via  an  email  server  named
               "[e-mail]".  Elvis is  located
               in the directory "/pub/Minix/all.contrib".

               I will also offer it to the C Users' Group. They sell
               C source code for us$8 per diskette (or slightly more
               outside  North  America).    Their  phone  number  is
               [phone], and their address is:

                        The C Users' Group
                        PO Box 3127
                        Lawrence KS 66046-0127

        8) Is this shareware, or public domain, or what?

               It is not public domain; it  is  copyrighted  by  me,
               Steve  Kirkendall.   However, this particular version
               is freely redistributable, in either source  form  or
               executable  form.   (I  would  prefer  that  you give
               copies away for free, complete with the  full  source
               code... but I'm not going to force you.)

               It is not shareware; you aren't expected to  send  me
               anything.  You can use it without guilt.

               It is not  "copylefted."  I  hold  a  copyright,  but
               currently  I have not added any of the usual restric-
               tions that you would find on copylefted software.  If
               people  start doing really obnoxious things to Elvis,
               then I will start adding restrictions  to  subsequent
               versions,  but  earlier  versions  won't be affected.
               (So far, everybody has been pretty good about this so
               no restrictions have been necessary.)


        9) Can I reuse parts of your source code?

               Yes.  Please be careful, though, to  make  sure  that
               the  code  really is mine.  Some of the code was con-
               tributed by  other  people,  and  I  don't  have  the
               authority  to  give  you  permission  to use it.  The
               author's name can be  found  near  the  top  of  each
               source  file.  If it says "Steve Kirkendall" then you
               may use  it;  otherwise,  you'd  better  contact  the
               author first.

               Please don't remove my name from the source code.  If
               you  modify  the  source,  please make a note of that
               fact in a comment near the top of  the  source  code.
               And, finally, please mention my name in your documen-
               tation.



                               March 23, 1992





        13-4                QUESTIONS & ANSWERS                 13-4


        10) Can Elvis work with non-ASCII files?

               Elvis can't edit binary files because it can't handle
               the NUL character, and because of line-length limita-
               tions.  However, it is 8-bit clean so you  should  be
               able to edit any European extended ASCII file without
               any surprises.

               Elvis has also been  modified  to  work  with  16-bit
               character  sets.  Yongguang Zhang ([e-mail])
               has created a Chinese  version  of  Elvis  that  uses
               16-bit  characters  and  runs  under  cxterm (Chinese
               X-term)  on  X-windows   systems.    Junichiro   Itoh
               ([e-mail])  has  modified  Elvis to edit
               Japanese text under MS-DOS.










































                               March 23, 1992





        CTAGS(1)            UNIX Programmer's Manual             CTAGS(1)



        NAME
             ctags - Generates "tags" and (optionally) "refs" files

        SYNOPSIS
             ctags [-stvra] filesnames...

        DESCRIPTION
             ctags generates the "tags" and "refs" files from a group of
             C source files.  The "tags" file is used by Elvis' ":tag"
             command, control-] command, and -t option.  The "refs" file
             is sometimes used by the ref(1) program.

             Each C source file is scanned for #define statements and
             global function definitions.  The name of the macro or func-
             tion 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 filenames list will typically be the names of all C
             source files in the current directory, like this:
                  $ ctags -stv *.[ch]

        OPTIONS
             -t   Include typedefs.  A tag will be generated for each
                  user-defined type.  Also tags will be generated for
                  struct and enum names.  Types are considered to be glo-
                  bal if they are defined in a header file, and static if
                  they are defined in a C source file.

             -v   Include variable declarations.  A tag will be generated
                  for each variable, except for those that are declared
                  inside the body of a function.

             -s   Include static tags.  Ctags will normally put global
                  tags in the "tags" file, and silently ignore the static
                  tags.  This flag causes both global and static tags to
                  be added.  The name of a static tag is generated by
                  prefixing the name of the declared item with the name
                  of the file where it is defined, with a colon in
                  between.  For example, "static foo(){}" in "bar.c"
                  results in a tag named "bar.c:foo".

             -r   This causes ctags to generate both "tags" and "refs".
                  Without -r, it would only generate "tags".

             -a   Append to "tags", and maybe "refs".  Normally, ctags
                  overwrites these files each time it is invoked.  This
                  flag is useful when you have to many files in the



        Printed 3/23/92                                                 1






        CTAGS(1)            UNIX Programmer's Manual             CTAGS(1)



                  current directory for you to list them on a single
                  command-line; it allows you to split the arguments
                  among several invocations.

        FILES
             tags A cross-reference that lists each tag name, the name of
                  the source file that contains it, and a way to locate a
                  particular line in the source file.

             refs The "refs" file contains the definitions for each tag
                  in the "tags" file, and very little else.  This file
                  can be useful, for example, when licensing restrictions
                  prevent you from making the source code to the standard
                  C library readable by everybody, but you still every-
                  body to know what arguments the library functions need.

        BUGS
             ctags is sensitive to indenting and line breaks.  Conse-
             quently, it might not discover all of the tags in a file
             that is formatted in an unusual way.

        SEE ALSO
             elvis(1), refs(1)

        AUTHOR
             Steve Kirkendall
             [e-mail]




























        Printed 3/23/92                                                 2






        ELVIS(1)            UNIX Programmer's Manual             ELVIS(1)



        NAME
             elvis, ex, vi, view, input - The editor

        SYNOPSIS
             elvis [flags] [+cmd] [files...]

        DESCRIPTION
             Elvis is a text editor which emulates vi/ex.

             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", "view", and "input".  These extra names
             would normally be links to elvis; see the "ln" shell com-
             mand.

             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.

        OPTIONS
             -r   To the real vi, this flag means that a previous edit
                  should be recovered.  Elvis, though, has a separate
                  program, called elvrec(1), for recovering files.  When
                  you invoke elvis with -r, elvis will tell you to run
                  elvrec.

             -R   This sets the "readonly" option, so you won't acciden-
                  tally overwrite a file.

             -t tag
                  This causes elvis to start editing at the given tag.

             -m [file]
                  Elvis will search through file for something that looks
                  like an error message from a compiler.  It will then
                  begin editing the source file that caused the error,
                  with the cursor sitting on the line where the error was
                  detected.  If you don't explicitly name a file, then
                  "errlist" is assumed.

             -e   Elvis will start up in colon command mode.

             -v   Elvis will start up in visual command mode.

             -i   Elvis will start up in input mode.




        Printed 3/23/92                                                 1






        ELVIS(1)            UNIX Programmer's Manual             ELVIS(1)



             -w winsize
                  Sets the "window" option's value to winsize.

             +command or -c command
                  If you use the +command parameter, then after the first
                  file is loaded command is executed as an EX command.  A
                  typical example would be "elvis +237 foo", which would
                  cause elvis to start editing foo and then move directly
                  to line 237.  The "-c command" variant was added for
                  UNIX SysV compatibility.

        FILES
             /tmp/elv*
                  During editing, elvis stores text in a temporary file.
                  For UNIX, this file will usually be stored in the /tmp
                  directory, and the first three characters will be
                  "elv".  For other systems, the temporary files may be
                  stored someplace else; see the version-specific section
                  of the documentation.

             tags This is the database used by the :tags command and the
                  -t option.  It is usually created by the ctags(1) pro-
                  gram.

             .exrc or elvis.rc
                  On UNIX-like systems, a file called ".exrc" in your
                  home directory is executed as a series of ex commands.
                  A file by the same name may be executed in the current
                  directory, too.  On non-UNIX systems, ".exrc" is usu-
                  ally an invalid file name; there, the initialization
                  file is called "elvis.rc" instead.

        SEE ALSO
             ctags(1), ref(1), virec(1)

             Elvis - A Clone of Vi/Ex, the complete elvis documentation.

        BUGS
             There is no LISP support.  Certain other features are miss-
             ing, too.

             Auto-indent mode is not quite compatible with the real vi.
             Among other things, 0^D and ^^D don't do what you might
             expect.

             Long lines are displayed differently.  The real vi wraps
             long lines onto multiple rows of the screen, but elvis
             scrolls sideways.

        AUTHOR
             Steve Kirkendall
             [e-mail]



        Printed 3/23/92                                                 2






        ELVIS(1)            UNIX Programmer's Manual             ELVIS(1)



             Many other people have worked to port elvis to various
             operating systems.  To see who deserves credit, run the
             :version command from within elvis, or look in the system-
             specific section of the complete documentation.



















































        Printed 3/23/92                                                 3






        ELVPRSV(1)          UNIX Programmer's Manual           ELVPRSV(1)



        NAME
             elvprsv - Preserve the the modified version of a file after
             a crash.

        SYNOPSIS
             elvprsv ["-why elvis died"] /tmp/filename...
             elvprsv -R /tmp/filename...

        DESCRIPTION
             elvprsv preserves your edited text after elvis dies.  The
             text can be recovered later, via the elvprsv program.

             For UNIX-like systems, you should never need to run this
             program from the command line.  It is run automatically when
             elvis is about to die, and it should be run (via /etc/rc)
             when the computer is booted.  THAT'S ALL!

             For non-UNIX systems such as MS-DOS, you can either use
             elvprsv the same way as under UNIX systems (by running it
             from your AUTOEXEC.BAT file), or you can run it separately
             with the "-R" flag to recover the files in one step.

             If you're editing a file when elvis dies (due to a bug, sys-
             tem crash, power failure, etc.) then elvprsv will preserve
             the most recent version of your text.  The preserved text is
             stored in a special directory; it does NOT overwrite your
             text file automatically.

             elvprsv will send mail to any user whose work it preserves,
             if your operating system normally supports mail.

        FILES
             /tmp/elv*
                  The temporary file that elvis was using when it died.

             /usr/preserve/p*
                  The text that is preserved by elvprsv.

             /usr/preserve/Index
                  A text file which lists the names of all preserved
                  files, and the names of the /usr/preserve/p* files
                  which contain their preserved text.

        BUGS
             Due to the permissions on the /usr/preserve directory, on
             UNIX systems elvprsv must be run as superuser.  This is
             accomplished by making the elvprsv executable be owned by
             "root" and turning on its "set user id" bit.

             If you're editing a nameless buffer when elvis dies, then
             elvprsv will pretend that the file was named "foo".




        Printed 3/23/92                                                 1






        ELVPRSV(1)          UNIX Programmer's Manual           ELVPRSV(1)



        AUTHOR
             Steve Kirkendall
             [e-mail]




















































        Printed 3/23/92                                                 2






        ELVREC(1)           UNIX Programmer's Manual            ELVREC(1)



        NAME
             elvrec - Recover the modified version of a file after a
             crash

        SYNOPSIS
             elvrec [preservedfile [newfile]]

        DESCRIPTION
             If you're editing a file when elvis dies, the system
             crashes, or power fails, the most recent version of your
             text will be preserved.  The preserved text is stored in a
             special directory; it does NOT overwrite your text file
             automatically.

             The elvrec program locates the preserved version of a given
             file, and writes it over the top of your text file -- or to
             a new file, if you prefer.  The recovered file will have
             nearly all of your changes.

             To see a list of all recoverable files, run elvrec with no
             arguments.

        FILES
             /usr/preserve/p*
                  The text that was preserved when elvis died.

             /usr/preserve/Index
                  A text file which lists the names of all preserved
                  files, and the names of the /usr/preserve/p* files
                  which contain their preserved text.

        BUGS
             elvrec is very picky about filenames.  You must tell it to
             recover the file using exactly the same pathname as when you
             were editing it.  The simplest way to do this is to go into
             the same directory that you were editing, and invoke elvrec
             with the same filename as elvis.  If that doesn't work, then
             try running elvrec with no arguments, to see exactly which
             pathname it is using for the desired file.

             Due to the permissions on the /usr/preserve directory, on
             UNIX systems elvrec must be run as superuser.  This is
             accomplished by making the elvrec executable be owned by
             "root" and setting its "set user id" bit.

             If you're editing a nameless buffer when elvis dies, then
             elvrec will pretend that the file was named "foo".

        AUTHOR
             Steve Kirkendall
             [e-mail]




        Printed 3/23/92                                                 1






        FMT(1)              UNIX Programmer's Manual               FMT(1)



        NAME
             fmt - adjust line-length for paragraphs of text

        SYNOPSIS
             fmt [-width] [files]...

        DESCRIPTION
             fmt is a simple text formatter.  It inserts or deletes new-
             lines, as necessary, to make all lines in a paragraph be
             approximately the same width.  It preserves indentation and
             word spacing.

             The default line width is 72 characters.  You can override
             this with the -width flag.  If you don't name any files on
             the command line, then fmt will read from stdin.

             It is typically used from within vi to adjust the line
             breaks in a single paragraph.  To do this, move the cursor
             to the top of the paragraph, type "!}fmt", and hit <Return>.

        AUTHOR
             Steve Kirkendall
             [e-mail]
































        Printed 3/23/92                                                 1






        REF(1)              UNIX Programmer's Manual               REF(1)



        NAME
             ref - Display a C function header

        SYNOPSIS
             ref [-t] [-c class]... [-f file]... tag

        DESCRIPTION
             ref quickly locates and displays the header of a function.
             To do this, ref looks in the "tags" file for the line that
             describes the function, and then scans the source file for
             the function.  When it locates the function, it displays an
             introductory comment (if there is one), the function's
             declaration, and the declarations of all arguments.

        SEARCH METHOD
             ref uses a fairly sophisticated tag look-up algorithm.  If
             you supply a filename via -f file, then elvis first scans
             the tags file for a static tag from that file.  This search
             is limited to the tags file in the current directory.

             If you supply a classname via -c class, then elvis searches
             for a tag from that class.  This search is not limited to
             the current directory; You can supply a list of directories
             in the environment variable TAGPATH, and ref will search
             through the "tags" file in each directory until it finds a
             tag in the desired class.

             If that fails, ref will then try to look up an ordinary glo-
             bal tag.  This search checks all of the directories listed
             in TAGPATH, too.

             If you've given the -t flag, then ref will simply output the
             tag line that it found, and then exit.  Without -t, though,
             ref will search for the tag line.  It will try to open the
             source file, which should be in the same directory as the
             tags file where the tag was discovered.  If the source file
             doesn't exist, or is unreadable, then ref will try to open a
             file called "refs" in that directory.  Either way, ref will
             try to locate the tag, and display whatever it finds.

        INTERACTION WITH ELVIS
             ref is used by elvis' shift-K command.  If the cursor is
             located on a word such as "splat", in the file "foo.c", then
             elvis will invoke ref with the command "ref -f foo.c splat".

             If elvis has been compiled with the -DEXTERNAL_TAGS flag,
             then elvis will use ref to scan the tags files.  This is
             slower than the built-in tag searching, but it allows elvis
             to access the more sophisticated tag lookup provided by ref.
             Other than that, external tags should act exactly like
             internal tags.




        Printed 3/23/92                                                 1






        REF(1)              UNIX Programmer's Manual               REF(1)



        OPTIONS
             -t   Output tag info, instead of the function header.

             -f file
                  The tag might be a static function in file.  You can
                  use several -f flags to have ref consider static tags
                  from more than one file.

             -c class
                  The tag might be a member of class class.  You can use
                  several -c flags to have ref consider tags from more
                  than one class.

        FILES
             tags List of function names and their locations, generated
                  by ctags.

             refs Function headers extracted from source files
                  (optional).

        ENVIRONMENT
             TAGPATH
                  List of directories to be searched.  The elements in
                  the list are separated by either semicolons (for MS-
                  DOS, Atari TOS, and AmigaDos), or by colons (every
                  other operating system).  For each operating system,
                  ref has a built-in default which is probably adequate.

        NOTES
             You might want to generate a "tags" file the directory that
             contains the source code for standard C library on your sys-
             tem.  If licensing restrictions prevent you from making the
             library source readable by everybody, then you can have
             ctags generate a "refs" file, and make "refs" readable by
             everybody.

             If your system doesn't come with the library source code,
             then perhaps you can produce something workable from the
             lint libraries.

        SEE ALSO
             elvis(1), ctags(1)

        AUTHOR
             Steve Kirkendall
             [e-mail]









        Printed 3/23/92                                                 2