Category : Word Processors
Archive   : STEVIE.ZIP
Filename : STEVIE.DOC

 
Output of file : STEVIE.DOC contained in archive : STEVIE.ZIP

STEVIE - An Aspiring VI Clone

User Reference

Tony Andrews

3/6/88


Overview
--------

STEVIE is an editor designed to mimic the interface of the UNIX editor
'vi'. The name (ST Editor for VI Enthusiasts) is due to the fact that
the editor was first written for the Atari ST. The current version has
been ported to UNIX and OS/2, but I've left the name intact for now.

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. Almost
all of the visual mode commands are supported. The biggest failing at the
moment is that the undo command is currently in a state of disrepair.
Recent enhancements in other areas have required the undo command to be
mostly disabled until it can catch up with the other changes. But don't be
discouraged. I've tried very 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 real pain, but do much to make the editor feel right.

This program is the result of many late nights of hacking over the last
several months. The first version was written 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.

STEVIE may be freely distributed. The source isn't copyrighted or
restricted in any way. If you pass the program along, please include all
the documentation and, if practical, the source as well. I'm not fanatical
about this, but I tried to make STEVIE fairly portable and that doesn't
do any good if the source isn't available.

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.


Starting the Editor
-------------------

The following command line forms are supported:

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

vi -t tag Start at location of the given tag

vi + file Edit file starting at end

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

vi +/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, ":p" goes backward in the list,
and ":rew" can be used to rewind back to the start of the file list.


Set Command Options
-------------------

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, defaults, and descriptions are
shown below:

Full Name Short Default Description
------------------------------------------------------------------------------
vbell vb vb Use visual bell (novb for audible bell)
showmatch sm nosm Showmatch mode
wrapscan ws ws Wrapscan (searches cross file start/end)
errorbells eb noeb Ring bell when error messages are shown
showmode mo nomo Show on status line when in insert mode
backup bk nobk Leave backup in *.bak on file writes
return cr cr End lines with cr-lf when writing
list list nolist Show tabs and newlines graphically

scroll scroll 12 Number of lines to scroll for ^D and ^U
tabstop ts 8 Number of spaces in a tab
report report 5 Min # of lines to report operations on
lines lines 25 Number of lines on the screen


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

The 'lines' parameter tells the editor how many lines there are on the screen.
This is useful on systems like the ST where various screen resolutions may be
used. By using the 'lines' parameter, different screen sizes can be easily
handled.


File Manipulation Commands
--------------------------

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

:w write the current file
:wq write and quit
😡 write (if necessary) and quit
ZZ same as ":x"

:e file edit the named file
:e! re-edit the current file, discarding any changes
:e # edit the alternate file

:w file write the buffer to the named file
:x,y w file write lines x through y to the named file
:r file read the named file into the buffer

:n edit the next file
:p edit the previous file
:rew rewind the file list

:f show the current file name
:f name change the current file name

:ta tag go to the named tag
^] like ":ta" using the current word as the tag

:help display a command summary

The ":help" command can also be invoke with the key on the Atari
ST. This actually displays a pretty complete summary of the real vi with
unsupported features indicated appropriately.

The commands above work pretty much like they do in 'vi'. Most of the
commands support a '!' suffix (if appropriate) to discard any pending
changes.

When writing just part of the buffer, the following address forms are
supported:

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)


String Searches
---------------

String searches are supported, as in vi, accepting the usual regular
expression syntax. This was done using Henry Spencer's regular expression
library without modification. I added code outside the library to support
the '\<' and '\>' extensions. This actually turned out to be pretty easy.


Operators
---------

The vi operators (d, c, y, <, and >) work as true operators. The only
exception is that the change operator works only for character-oriented
changes (like cw or c%) and not for line-oriented changes (like cL or c3j).


Tags
----

Tags are implemented and a fairly simple version of 'ctags' is supplied
with the editor. The current version of ctags will find functions and
macros following a specific (but common) form. See 'ctags.doc' for a
complete discussion. [The full Ctags program is in the public domain;
contact your nearest comp.sources.unix archive site; the primitive
tags has been taken out of this c.s.u distribution.]


System-Specific Comments
------------------------

The following sections provide additional relevant information for the
systems to which STEVIE has been ported.


Atari ST
--------

The editor has been tested in all three resolutions, although low and
high res. are less tested than medium. The 50-line high res. mode can
be used by setting the 'lines' parameter to 50. Alternatively, the
environment variable 'LINES' can be set. The editor doesn't actively
set the number of lines on the screen. It just operates using the number
of lines it was told.

The arrow keys, as well as the , , and keys are
all mapped appropriately.


UNIX
----

The editor has been ported to UNIX System V release 3. This was done
mainly to get some profiling data so I haven't put much effort into
doing the UNIX version right. It's hard-coded for ansi-style escape
sequences and doesn't use the termcap/terminfo routines at all.


OS/2
----

This port was done because the editor that comes with the OS/2 developer's
kit really sucks. Make sure 'ansi' mode is on (using the 'ansi' command).
The OS/2 ansi driver doesn't support insert/delete line, so the display
updates are a little rough, but the editor is fast enough that it isn't
too bothersome. The arrow keys are NOT mapped, so they don't currently do
anything reasonable.


Missing Features
----------------

1. Counts aren't yet supported everywhere that they should be.

2. Macros with support for the ST function keys.

3. More "set" options.

4. Auto-indent.

5. Many others...



Known Bugs and Problems
-----------------------

1. Undo is partially disabled until I can re-work some of the code for
undoing certain edit operations. Undo is enabled for those operations
where I've specifically checked out the code. All other cases print
an apologetic message for the time being. Recent changes to the editor
broke some of the old 'undo' code. This is a temporary hack until I
can check out all the undo code.

2. The change operator is only half-way implemented. It works for character
motions but not line motions. This isn't so bad since most change
operations are character oriented anyway.

3. The yank buffer uses statically allocated memory, so yanks of more than
1K of text will fail. If a delete spans more than 1K, the program asks
for confirmation before proceeding. That way, if you were moving text,
you don't get screwed by the limited yank buffer. You just have to move
smaller chunks at a time. All the internal buffers (yank, redo, etc.)
need to be reworked to allocate memory dynamically.

4. If you stay in insert mode for a long time, the insert buffer can overflow.
The editor will print a message and dump you back into command mode.

5. Puts are very slow.

6. Several other less bothersome glitches...


Conclusion
----------

I'm still working on the program pretty actively, although the farther I
get with it, the harder it is to get motivated to work on it. I've been
using it as my standard editor for a long time, and I suppose I'm coming
to accept its deficiencies more than I should. Fortunately, I use the
real vi every day at work, so I'm constantly reminded of the work that
remains to be done.

I'd like to thank Tim Thompson for writing the original version of the
editor. His program was well structured and quite readable. Thanks for
giving me a good base to work with.

If you're reading this file, but didn't get the source code for STEVIE,
it can be had by sending a disk with return postage to the address given
below. I can write disks for the Atari ST (SS or DS) or MSDOS (360K or
1.2M). Please be sure to include the return postage. I don't intend to
make money from this program, but I don't want to lose any either.

I'm not planning to try to coordinate the various ports of STEVIE that
may occur. I just don't have the time. But if you do port it, I'd be
interested in hearing about it. I will be doing a port for Minix on the
ST when that becomes available later this year. So if anyone does a
Minix port on the PC, I'd be especially interested.


Tony Andrews UUCP: onecom!wldrdg!tony
5902E Gunbarrel Ave.
Boulder, CO 80301


Character Function Summary
--------------------------

The following list describes the meaning of each character that's used
by the editor. In some cases characters have meaning in both command and
insert mode; these are all described.

^@ The null character. Not used in any mode. This character may not
be present in the file, as is the case with vi.

^B Backward one screen.

^D Scroll the window down one half screen.

^E Scroll the screen up one line.

^F Forward one screen.

^G Same as ":f" command. Displays file information.

^H (BS) Moves cursor left one space in command mode. In insert mode, erases
the last character typed.

^J Move the cursor down one line.

^L Clear and redraw the screen.

^M (CR) Move to the first non-white character in the next line. In insert
mode, a carriage return opens a new line for input.

^N Move the cursor down a line.

^P Move the cursor up a line.

^U Scroll the window up one half screen.

^Y Scroll the screen down one line.

^[ Escape cancels a pending command in command mode, and is used to
terminate insert mode.

^] Moves to the tag whose name is given by the word in which the cursor
resides.

^` Same as ":e #" if supported (system-dependent).

SPACE Move the cursor right on column.

$ Move to the end of the current line.

% If the cursor rests on a paren '()', brace '{}', or bracket '[]',
move to the matching one.

' Used to move the cursor to a previously marked position, as in
'a or 'b. The cursor moves to the start of the marked line. The
special mark '' refers to the "previous context".

+ Same as carriage return, in command mode.

, Reverse of the last t, T, f, or F command.

- Move to the first non-white character in the previous line.

. Repeat the last edit command.

/ Start of a forward string search command. String searches may be
optionally terminated with a closing slash. To search for a slash
use '\/' in the search string.

0 Move to the start of the current line. Also used within counts.

1-9 Used to add 'count' prefixes to commands.

: Prefix character for "ex" commands.

; Repeat last t, T, f, or F command.

< The 'left shift' operator.

> The 'right shift' operator.

? Same as '/', but search backward.

A Append at the end of the current line.

B Backward one blank-delimited word.

C Change the rest of the current line.

D Delete the rest of the current line.

E End of the end of a blank-delimited word.

F Find a character backward on the current line.

G Go to the given line number (end of file, by default).

H Move to the first non-white char. on the top screen line.

I Insert before the first non-white char. on the current line.

J Join two lines.

L Move to the first non-white char. on the bottom screen line.

M Move to the first non-white char. on the middle screen line.

N Reverse the last string search.

O Open a new line above the current line, and start inserting.

P Put the yank/delete buffer before the current cursor position.

T Reverse search 'upto' the given character.

W Move forward one blank-delimited word.

X Delete one character before the cursor.

Y Yank the current line. Same as 'yy'.

ZZ Exit from the editor, saving changes if necessary.

[[ Move backward one C function.

]] Move forward one C function.

^ Move to the first non-white on the current line.

` Move to the given mark, as with '. The distinction between the two
commands is important when used with operators. I support the
difference correctly. If you don't know what I'm talking about,
don't worry, it won't matter to you.

a Append text after the cursor.

b Back one word.

c The change operator.

d The delete operator.

e Move to the end of a word.

f Find a character on the current line.

h Move left one column.

i Insert text before the cursor.

j Move down one line.

k Move up one line.

l Move right one column.

m Set a mark at the current position (e.g. ma or mb).

n Repeat the last string search.

o Open a new line and start inserting text.

p Put the yank/delete buffer after the cursor.

r Replace a character.

s Replace characters.

t Move forward 'upto' the given character on the current line.

u Undo the last edit. This isn't currently supported very well.

w Move forward one word.

x Delete the character under the cursor.

y The yank operator.

z Redraw the screen with the current line at the top (zRETURN),
the middle (z.), or the bottom (z-).

| Move to the column given by the preceding count.



  3 Responses to “Category : Word Processors
Archive   : STEVIE.ZIP
Filename : STEVIE.DOC

  1. Very nice! Thank you for this wonderful archive. I wonder why I found it only now. Long live the BBS file archives!

  2. This is so awesome! 😀 I’d be cool if you could download an entire archive of this at once, though.

  3. But one thing that puzzles me is the “mtswslnkmcjklsdlsbdmMICROSOFT” string. There is an article about it here. It is definitely worth a read: http://www.os2museum.com/wp/mtswslnk/