STEVIE - An Aspiring VI Clone

                          User Reference - 3.71

                               Tony Andrews



       1.  _O_v_e_r_v_i_e_w

       STEVIE is an editor designed to mimic the interface  of  the
       UNIX  editor  'vi'.  The name (ST Editor for VI Enthusiasts)
       comes from the fact that the editor was  first  written  for
       the  Atari ST. The current version also supports UNIX, Minix
       (ST), MS-DOS, and OS/2, but I've left the  name  intact  for
       now.

       This program is the result of many late  nights  of  hacking
       over  the last couple of years.  The first version was writ-
       ten by Tim Thompson and posted  to  USENET.  From  there,  I
       reworked  the  data  structures  completely,  added  LOTS of
       features, and generally improved the overall performance  in
       the process.

       I've labelled STEVIE an 'aspiring' vi clone as a warning  to
       those  who  may expect too much. On the whole, the editor is
       pretty complete.  Nearly all of the visual mode commands are
       supported.   And several of the more important 'ex' commands
       are supported as well.  I've tried hard to capture the  feel
       of vi by getting the little things right.  Making lines wrap
       correctly, supporting true operators, and even  getting  the
       cursor  to  land on the right place for tabs are all a pain,
       but really help make the editor feel right.  I've  tried  to
       resist  the  temptation  to deviate from the behavior of vi,
       even where I disagree with the original design.

       The biggest problem remaining has to do with the  fact  that
       the  edit  buffer is maintained entirely in memory, limiting
       the size of files that can be edited in  some  environments.
       Other  missing  features  include  named buffers and macros.
       Performance is generally  reasonable,  although  the  screen
       update code could be more efficient.  This is generally only
       visible on fairly slow systems.

       STEVIE may be freely distributed.  The  source  isn't  copy-
       righted  or  restricted  in any way. If you pass the program
       along, please include all the documentation and, if  practi-
       cal, the source as well. I'm not fanatical about this, but I
       tried to make STEVIE fairly portable and I'd like to see  as
       many people have access to the source as possible.

       The remainder of this document describes  the  operation  of
       the  editor.   This  is  intended  as  a reference for users
       already familiar with the real vi editor.




                                  - 1 -







       STEVIE                                        User Reference



       2.  _S_t_a_r_t_i_n_g__t_h_e__E_d_i_t_o_r

       The following command line forms are supported:

       stevie [file ...]   Edit the specified file(s)

       stevie -t tag       Start at the location of the given tag

       stevie + file       Edit file starting at end

       stevie +n file      Edit file starting a line number 'n'

       stevie +/pat file   Edit file starting at pattern 'pat'

       If multiple files are given on the command line  (using  the
       first  form),  the  ":n" command goes to the next file, ":N"
       goes backward in the list, and ":rew" can be used to  rewind
       back to the start of the file list.


       3.  _S_e_t__C_o_m_m_a_n_d__O_p_t_i_o_n_s

       The ":set" command works as usual to  set  parameters.  Each
       parameter  has  a  long  and  an abbreviated name, either of
       which may be used. Boolean parameters are set as in:

            set showmatch

       or cleared by:

            set noshowmatch

       Numeric parameters are set as in:

            set scroll=5

       Several parameters may be set with a single command:

            set novb sm report=1

       To see the status of all parameters use ":set  all".  Typing
       ":set"  with  no  arguments  will show only those parameters
       that have been changed.   The  supported  parameters,  their
       names,  abbreviations,  defaults, and descriptions are shown
       below:

       autoindent  Short: ai, Default: noai, Type: Boolean
                   When in insert mode, start new lines at the same
                   column  as  the  prior  line. Unlike vi, you can
                   backspace over the indentation.




                                  - 2 -







       STEVIE                                        User Reference



       backup      Short: bk, Default: nobk, Type: Boolean
                   Leave a backup on file writes.

       errorbells  Short: eb, Default: noeb, Type: Boolean
                   Ring bell when error messages are shown.

       ignorecase  Short: ic, Default: noic, Type: Boolean
                   Ignore case in string searches.

       lines       Short: lines, Default: lines=25, Type: Numeric
                   Number of physical  lines  on  the  screen.  The
                   default  value  actually  depends  on  the  host
                   machine, but is generally 25.

       list        Short: list, Default: nolist, Type: Boolean
                   Show tabs and newlines graphically.

       modelines   Short: ml, Default: noml, Type: Boolean
                   Enable processing of modelines in files.

       number      Short: nu, Default: nonu, Type: Boolean
                   Display lines on  the  screen  with  their  line
                   numbers.

       report      Short: report, Default: report=5, Type: Numeric
                   Minimum number of lines to report operations on.

       return      Short: cr, Default: cr, Type: Boolean
                   End lines with cr-lf when writing files.

       scroll      Short: scroll, Default: scroll=12, Type: Numeric
                   Number of lines to scroll for ^D & ^U.

       showmatch   Short: sm, Default: nosm, Type: Boolean
                   When a ), }, or ] is typed, show the matching (,
                   {,  or [ if it's on the current screen by moving
                   the cursor there briefly.

       showmode    Short: mo, Default: nomo, Type: Boolean
                   Show on status line when in insert mode.

       tabstop     Short: ts, Default: ts=8, Type: Numeric
                   Number of spaces in a tab.

       terse       Short: terse, Default: noterse, Type: Boolean
                   This option is currently ignored.   It  is  pro-
                   vided only for compatibility with vi.

       tildeop     Short: to, Default: noto, Type: Boolean
                   If set, tilde is an operator.  Otherwise,  tilde
                   acts as normal.



                                  - 3 -







       STEVIE                                        User Reference



       wrapscan    Short: ws, Default: ws, Type: Boolean
                   String searches wrap  around  the  ends  of  the
                   file.

       vbell       Short: vb, Default: vb, Type: Boolean
                   Use a visual bell, if possible. (novb for  audi-
                   ble bell)

       The EXINIT environment variable can be used  to  modify  the
       default values on startup as in:

            setenv EXINIT="set sm ts=4"

       The 'backup' parameter, if set, causes the editor to  retain
       a  backup of any files that are written. During file writes,
       a backup is always kept for safety until the write  is  com-
       pleted.  At  that  point,  the 'backup' parameter determines
       whether the backup file is deleted.

       In environments (e.g. OS/2 or TOS) where lines are  normally
       terminated  by CR-LF, the 'return' parameter allows files to
       be written with only a LF terminator (if  the  parameter  is
       cleared).  This parameter is ignored on UNIX systems.

       The 'lines' parameter tells the editor how many lines  there
       are  on  the  screen.  This is useful on systems like the ST
       (or OS/2 machines with an EGA adapter) where various  screen
       resolutions  may  be  used.  By using the 'lines' parameter,
       different screen sizes can be easily handled.


       4.  _C_o_l_o_n__C_o_m_m_a_n_d_s

       Several of the normal 'vi' colon commands are  supported  by
       STEVIE.   Some  commands  may  be  preceded  by a line range
       specification.  For commands that accept a range  of  lines,
       the following address forms are supported:

            addr
            addr + number
            addr - number

       where 'addr' may be one of the following:

            a line number
            a mark (as in 'a or 'b)
            '.' (the current line)
            '$' (the last line)

       An address range of "%" is accepted as  an  abbreviation  of
       "1,$".



                                  - 4 -







       STEVIE                                        User Reference



       4.1  _M_o_d_e__L_i_n_e_s

       Mode lines are a little-known, but often useful, feature  of
       vi.   To use this feature, special strings are placed in the
       first or last five lines  in  a  file.   When  the  file  is
       edited,  these  strings are detected and processed as though
       typed as a colon command.  One instance where  this  can  be
       useful  is  to  set  the  "tabstop"  parameter on a per-file
       basis.  The following are examples of mode lines:

            vi:set ts=4 noai:
            ex:45:

       Mode lines are characterized by the string "vi" or "ex" fol-
       lowed  by  a  command  surrounded  by colons. Other text may
       appear on the line, and multiple mode lines may be  present.
       No  guarantee  is made regarding the order in which multiple
       mode lines will be processed.

       The processing of mode lines is enabled by setting the  "ml"
       parameter.  This  should be done in the "EXINIT" environment
       variable, so that mode line processing is enabled as soon as
       the  editor begins.  By default, mode lines are disabled for
       security reasons.

       4.2  _T_h_e__G_l_o_b_a_l__C_o_m_m_a_n_d

       A limited form of the global command is supported, accepting
       the following command form:

            g/pattern/X

       where X may be either 'd' or 'p' to delete  or  print  lines
       that  match  the  given  pattern.  If a line range is given,
       only those lines are checked for a match with  the  pattern.
       If no range is given, all lines are checked.

       If  the  trailing  command  character  is  omitted,  'p'  is
       assumed.  In this case, the trailing slash is also optional.
       The current version of the editor does not support the  undo
       operation  following  the  deletion of lines with the global
       command.

       4.3  _T_h_e__S_u_b_s_t_i_t_u_t_e__C_o_m_m_a_n_d

       The substitute command provides  a  powerful  mechanism  for
       making  more complex substitutions than can be done directly
       from visual mode.  The general form of the command is:

            s/pattern/replacement/g




                                  - 5 -







       STEVIE                                        User Reference



       Each line in the given range (or the  current  line,  if  no
       range  was  given)  is scanned for the given regular expres-
       sion.  When found, the string that matched  the  pattern  is
       replaced with the given replacement string.  If the replace-
       ment  string  is  null,  each  matching  pattern  string  is
       deleted.

       The trailing 'g' is optional and, if present, indicates that
       multiple  occurrences  of  'pattern' on a line should all be
       replaced.

       Some special sequences are  recognized  in  the  replacement
       string.  The  ampersand  character is replaced by the entire
       pattern that was matched.  For example, the  following  com-
       mand  could be used to put all occurrences of 'foo' or 'bar'
       within double quotes:

            1,$s/foo|bar/"&"/g

       The special sequence "\n" where 'n' is a digit from 1 to  9,
       is  replaced  by  the  string  the matched the corresponding
       parenthesized expression in the pattern. The following  com-
       mand could be used to swap the first two parameters in calls
       to the C function "foo":

            1,$s/foo\(([^,]*),([^,]*),/foo(\2,\1,/g

       Like the global command, substitutions can't be undone  with
       this version of the editor.

       4.4  _F_i_l_e__M_a_n_i_p_u_l_a_t_i_o_n__C_o_m_m_a_n_d_s

       The following table shows the  supported  file  manipulation
       commands  as  well  as  some other 'ex' commands that aren't
       described elsewhere: