.\" $Header: /r3/tony/src/stevie/src/RCS/stevie.mm,v 3.72 90/01/22 19:11:56 tony Exp $
.\"
.\" Documentation for STEVIE. Process with nroff using the mm macros.
.\"
.nr Hu 1
.SA 1
.TL
STEVIE - An Aspiring VI Clone
.sp
User Reference - 3.71
.AU "Tony Andrews"
.AF ""
.MT 4
.PH "'STEVIE''User Reference'"
.PF "''- \\\\n% -''"
.H 1 "Overview"
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.
.P
This program is the result of many late nights of hacking over the last
couple of years.
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.
.P
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.
.P
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.
.P
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 I'd like to
see as many people have access to the source as possible.
.P
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.
.H 1 "Starting the Editor"
The following command line forms are supported:
.VL 20
.LI "stevie [file ...]"
Edit the specified file(s)
.LI "stevie -t tag"
Start at the location of the given tag
.LI "stevie + file"
Edit file starting at end
.LI "stevie +n file"
Edit file starting a line number 'n'
.LI "stevie +/pat file"
Edit file starting at pattern 'pat'
.LE
.P
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.
.H 1 "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:
.sp
.ti +5
set showmatch
.sp
or cleared by:
.sp
.ti +5
set noshowmatch
.sp
Numeric parameters are set as in:
.sp
.ti +5
set scroll=5
.sp
Several parameters may be set with a single command:
.sp
.ti +5
set novb sm report=1
.P
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:
.VL 12
.LI autoindent
Short: ai, Default: noai, Type: Boolean
.br
When in insert mode, start new lines at the same column as the prior
line. Unlike vi, you can backspace over the indentation.
.LI backup
Short: bk, Default: nobk, Type: Boolean
.br
Leave a backup on file writes.
.LI errorbells
Short: eb, Default: noeb, Type: Boolean
.br
Ring bell when error messages are shown.
.LI ignorecase
Short: ic, Default: noic, Type: Boolean
.br
Ignore case in string searches.
.LI lines
Short: lines, Default: lines=25, Type: Numeric
.br
Number of physical lines on the screen. The default value actually
depends on the host machine, but is generally 25.
.LI list
Short: list, Default: nolist, Type: Boolean
.br
Show tabs and newlines graphically.
.LI modelines
Short: ml, Default: noml, Type: Boolean
.br
Enable processing of modelines in files.
.LI number
Short: nu, Default: nonu, Type: Boolean
.br
Display lines on the screen with their line numbers.
.LI report
Short: report, Default: report=5, Type: Numeric
.br
Minimum number of lines to report operations on.
.LI return
Short: cr, Default: cr, Type: Boolean
.br
End lines with cr-lf when writing files.
.LI scroll
Short: scroll, Default: scroll=12, Type: Numeric
.br
Number of lines to scroll for ^D & ^U.
.LI showmatch
Short: sm, Default: nosm, Type: Boolean
.br
When a ), }, or ] is typed, show the matching (, {, or [ if
it's on the current screen by moving the cursor there briefly.
.LI showmode
Short: mo, Default: nomo, Type: Boolean
.br
Show on status line when in insert mode.
.LI tabstop
Short: ts, Default: ts=8, Type: Numeric
.br
Number of spaces in a tab.
.LI terse
Short: terse, Default: noterse, Type: Boolean
.br
This option is currently ignored.
It is provided only for compatibility with vi.
.LI tildeop
Short: to, Default: noto, Type: Boolean
.br
If set, tilde is an operator. Otherwise, tilde acts as normal.
.LI wrapscan
Short: ws, Default: ws, Type: Boolean
.br
String searches wrap around the ends of the file.
.LI vbell
Short: vb, Default: vb, Type: Boolean
.br
Use a visual bell, if possible. (novb for audible bell)
.LE
.P
The EXINIT environment variable can be used to modify the default values
on startup as in:
.sp
.ti +5
setenv EXINIT="set sm ts=4"
.P
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.
.P
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.
.P
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.
.H 1 "Colon Commands"
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:
.DS 1
addr
addr + number
addr - number
.DE
where 'addr' may be one of the following:
.DS 1
a line number
a mark (as in 'a or 'b)
\'.' (the current line)
\'$' (the last line)
.DE
.P
An address range of "%" is accepted as an abbreviation of "1,$".
.H 2 "Mode Lines"
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:
.DS 1
vi:set ts=4 noai:
ex:45:
.DE
.P
Mode lines are characterized by the string "vi" or "ex" followed
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.
.P
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.
.H 2 "The Global Command"
A limited form of the global command is supported, accepting the
following command form:
.DS 1
g/pattern/X
.DE
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.
.P
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.
.H 2 "The Substitute Command"
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:
.DS 1
s/pattern/replacement/g
.DE
Each line in the given range (or the current line, if no range was
given) is scanned for the given regular expression.
When found, the string that matched the pattern is replaced with
the given replacement string.
If the replacement string is null, each matching pattern string is
deleted.
.P
The trailing 'g' is optional and, if present, indicates that multiple
occurrences of 'pattern' on a line should all be replaced.
.P
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 command could be used to put all occurrences
of 'foo' or 'bar' within double quotes:
.DS 1
1,$s/foo|bar/"&"/g
.DE
.P
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 command could be used to swap the first two
parameters in calls to the C function "foo":
.DS 1
1,$s/foo\\\\(([^,]*),([^,]*),/foo(\\\\2,\\\\1,/g
.DE
.P
Like the global command, substitutions can't be undone with this
version of the editor.
.H 2 "File Manipulation Commands"
The following table shows the supported file manipulation commands as
well as some other 'ex' commands that aren't described elsewhere:
.DS
:w		write the current file
:wq		write and quit
:x		write (if necessary) and quit
ZZ		same as ":x"

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

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

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

:f		show the current file name
:f name		change the current file name
:x=		show the line number of address 'x'

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

:help		display a command summary
:ve		show the version number

:sh		run an interactive shell
:!cmd		run a command
.DE
.P
The ":help" command can also be invoked with the <HELP> key on the Atari
ST. This actually displays a pretty complete summary of the real vi with
unsupported features indicated appropriately.
.P
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.
.H 1 "String Searches"
String searches are supported, as in vi, accepting the usual regular
expression syntax. This was done using a modified form of
Henry Spencer's regular expression
library. I added code outside the library to support