Programmer 7500/MAX_PROGRAMMERS.iso/CLIPPER/MISC/ELV15.ZIP/ELVISMAN.TXT

Text File | 1992-06-20 | 163.6 KB | 5,413 lines

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

                    - a clone of vi/ex -
                        version 1.6






























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

E-Mail:  [e-mail]

Phone:   [phone]










                       June 13, 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.







                       June 13, 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 be 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.



                       June 13, 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



                       June 13, 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 the line (EDIT)
       D     Delete text from the cursor through the end of the line (EDIT)
count  E     Move end of Word (MOVE)
count  F key Move leftward to a given character (MOVE)
count  G     Move to line #<count> (default is the bottom line) (MOVE)
count  H     Move to home row (the line at the top of the screen)
count  I inp Insert at the front of the line (after indents) (EDIT)
count  J     Join lines, to form one big line (EDIT)
       K     Look up keyword (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



                       June 13, 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 one character)


countMany 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
     always determines which command is to be executed.  The



                       June 13, 1992





2-4                 VISUAL MODE COMMANDS                 2-4


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



                       June 13, 1992





2-5                 VISUAL MODE COMMANDS                 2-5


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



                       June 13, 1992





2-6                 VISUAL MODE COMMANDS                 2-6


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



















                       June 13, 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



                       June 13, 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



                       June 13, 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.



                       June 13, 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



                       June 13, 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 confir-
mation 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



                       June 13, 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



                       June 13, 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.



                       June 13, 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 con-
tents of the "errlist" file are then scanned for error  mes-
sages.   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




                       June 13, 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



                       June 13, 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.


















































                       June 13, 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]



                       June 13, 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.




                       June 13, 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



                       June 13, 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/

































                       June 13, 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



                       June 13, 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?
nearscroll, ns     Num  ns=15         when to scroll vs. redraw
novice, nov        Bool nonovice      set options for ease of use
number, nu         Bool nonumber      show line numbers
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



                       June 13, 1992





5-3                       OPTIONS                        5-3


     for  auto-indent.   Elvis  will still insert a real tab
     character when you hit the <Tab> key, though; the auto-
     tab 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.




                       June 13, 1992





5-4                       OPTIONS                        5-4


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

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



                       June 13, 1992





5-5                       OPTIONS                        5-5


     written to the screen separately.

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

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

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



                       June 13, 1992





5-6                       OPTIONS                        5-6


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

     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.



                       June 13, 1992





5-7                       OPTIONS                        5-7


list, li
     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.

nearscroll, ns
     The line that contains the cursor will always be on the
     screen.  If you move the cursor to a line that isn't on
     the screen, then  elvis  will  either  scroll  (if  the
     cursor's  line  is  nearly  on  the  screen already) or
     redraw the screen completely  with  the  cursor's  line
     centered  (if  the  cursor  line is not near the screen
     already).



                       June 13, 1992





5-8                       OPTIONS                        5-8


     This option  allows  you  to  control  elvis'  idea  of
     "near".   A value of 15 is typical.  A value of 1 would
     cause elvis to scroll no more that one line.   A  value
     of 0 disables scrolling.

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

number, nu
     The  "number"  option  causes  Elvis  to  display  line
     numbers at the start of each line.  The numbers are not
     actually part of the text; when  the  file  is  written
     out, it will be written without line numbers.

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 dif-
     ferent "dot" commands.  This option allows you to  con-
     figure 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



                       June 13, 1992





5-9                       OPTIONS                        5-9


     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.

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



                       June 13, 1992





5-10                      OPTIONS                       5-10


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

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



                       June 13, 1992





5-11                      OPTIONS                       5-11


     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.

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



                       June 13, 1992





5-12                      OPTIONS                       5-12


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





















                       June 13, 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.



                       June 13, 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



                       June 13, 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.




































                       June 13, 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 ModeYou can backspace past the beginning of the line.

          The arrow keys work in input mode.



                       June 13, 1992





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


          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
          information to disk.




                       June 13, 1992





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


          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.

Move to a Given Percentage



                       June 13, 1992





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


          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.














                       June 13, 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:

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



                       June 13, 1992





8-2                       INTERNAL                       8-2


        o 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



                       June 13, 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().




                       June 13, 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



                       June 13, 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.































                       June 13, 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.




                       June 13, 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



                       June 13, 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.

-DMAILER=string
     This is the name of the program that Elvis uses to send
     mail  to  a  user  whose  text has just been preserved.
     (See the manual page for the elvprsv program.)  If your
     system doesn't use electronic mail, then this option is
     irrelevent.  For UNIX and  OS-9  systems,  though,  the
     value  should be a quoted string.  The default value is
     "mail", but SysV users may prefer to use  "mailx",  and
     BSD users may prefer "Mail".

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




                       June 13, 1992





9-4                        CFLAGS                        9-4


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



                       June 13, 1992





9-5                        CFLAGS                        9-5


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



                       June 13, 1992





9-6                        CFLAGS                        9-6


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



                       June 13, 1992





9-7                        CFLAGS                        9-7


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

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


















                       June 13, 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


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




                       June 13, 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=:



                       June 13, 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:




































                       June 13, 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.






                       June 13, 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.
































                       June 13, 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  and  VMS,  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:

     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 mailer  used  notify  users  when  text  is
preserver  is "mail".  You may wish to change this to "Mail"
(with an uppercase 'M').  See the description of "MAILER" in



                       June 13, 1992





12-2                      VERSIONS                      12-2


the CFLAGS section of this manual.

     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.

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.

     The default mailer  used  notify  users  when  text  is
preserver  is  "mail".   You  may  wish  to  change  this to
"mailx".  See the description of "MAILER" in the CFLAGS sec-
tion of this manual.

     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



                       June 13, 1992





12-3                      VERSIONS                      12-3


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



                       June 13, 1992





12-4                      VERSIONS                      12-4


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 com-
piling.  You can also control the name of the temp directory
via an environment variable named TMP or TEMP.   The  direc-
tory 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 won't look  for  "elvis.rc".
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



                       June 13, 1992





12-5                      VERSIONS                      12-5


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.

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.



                       June 13, 1992





12-6                      VERSIONS                      12-6


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

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.






                       June 13, 1992





12-7                      VERSIONS                      12-7


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



                       June 13, 1992





12-8                      VERSIONS                      12-8


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.

     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.




































                       June 13, 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.



                       June 13, 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.6.

       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?



                       June 13, 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.



                       June 13, 1992





13-4                QUESTIONS & ANSWERS                 13-4


       And, finally, please mention my name in your documen-
       tation.


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.






































                       June 13, 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 6/13/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 6/13/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 6/13/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 6/13/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 6/13/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 6/13/92                                                 1






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



AUTHOR
     Steve Kirkendall
     [e-mail]




















































Printed 6/13/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 6/13/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 6/13/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 6/13/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 6/13/92                                                 2