GEMini Atari/GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso/files/editors/elv1beta/elvisman.txt

Text File | 1993-08-08 | 158KB | 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]










              08/18/92











             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.







              08/18/92








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.



              08/18/92








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



              08/18/92





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



              08/18/92





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



              08/18/92





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



              08/18/92





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



              08/18/92





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.



















              08/18/92








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



              08/18/92





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



              08/18/92





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.



              08/18/92





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



              08/18/92





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



              08/18/92





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



              08/18/92





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.



              08/18/92





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




              08/18/92





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



              08/18/92





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.


















































              08/18/92








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]



              08/18/92





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.




              08/18/92





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



              08/18/92





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/

































              08/18/92








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



              08/18/92





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



              08/18/92





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.




              08/18/92





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



              08/18/92





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



              08/18/92





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.



              08/18/92





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



              08/18/92





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



              08/18/92





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.



              08/18/92





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



              08/18/92





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



              08/18/92





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.





















              08/18/92








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.



              08/18/92





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



              08/18/92





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.




































              08/18/92








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.



              08/18/92





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.




              08/18/92





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



              08/18/92





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.














              08/18/92








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)



              08/18/92





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



              08/18/92





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




              08/18/92





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



              08/18/92





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.































              08/18/92








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.




              08/18/92





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



              08/18/92





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.




              08/18/92





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



              08/18/92





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.



              08/18/92





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



              08/18/92





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.


















              08/18/92








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




              08/18/92





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



              08/18/92





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:




































              08/18/92








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.






              08/18/92





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.
































              08/18/92








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



              08/18/92





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



              08/18/92





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



              08/18/92





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



              08/18/92





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.



              08/18/92





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.






              08/18/92





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.



              08/18/92





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.




































              08/18/92








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.



              08/18/92





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?



              08/18/92





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.



              08/18/92





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.






































              08/18/92





     CTAGS(1)                              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
      function becomes the name of a tag.  For each    tag, a line is
      added    to the "tags" file which contains:
              -    the name of the    tag
              -    a tab character
              -    the name of the    file containing    the tag
              -    a tab character
              -    a way to find the particular line within the file.

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



     Page 1                         (printed 8/18/92)






     CTAGS(1)                              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
           everybody to know what arguments    the library functions
           need.

     BUGS
      ctags    is sensitive to    indenting and line breaks.
      Consequently,    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]



























     Page 2                         (printed 8/18/92)






     ELVIS(1)                              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
      command.

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

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




     Page 1                         (printed 8/18/92)






     ELVIS(1)                              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)
           program.

      .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
           usually 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
      missing, 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]



     Page 2                         (printed 8/18/92)






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



















































     Page 3                         (printed 8/18/92)






     ELVPRSV(1)                            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,
      system 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".




     Page 1                         (printed 8/18/92)






     ELVPRSV(1)                            ELVPRSV(1)



     AUTHOR
      Steve    Kirkendall
      [e-mail]




















































     Page 2                         (printed 8/18/92)






     ELVREC(1)                             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]




     Page 1                         (printed 8/18/92)






     FMT(1)                            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
      newlines, 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]
































     Page 1                         (printed 8/18/92)






     REF(1)                            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
      global 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.




     Page 1                         (printed 8/18/92)






     REF(1)                            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
      system.  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]









     Page 2                         (printed 8/18/92)