NAME
elvis - a clone of the ex/vi text editor
SYNOPSIS
elvis [-V...] [-a] [-r] [-e] [-i] [-s|-] [-b] [-R] [-S|-SS] [-f
session] [-o logfile] [-G gui] [-c command|+command] [-t tag] [-w
scroll] [-B blksize] [file]...
VERSION
Elvis 2.2_0
DESCRIPTION
Elvis is a text editor. It is intended to be a modern replacement for
the classic ex/vi editor of UNIX fame. Elvis supports many new
features, including multiple edit buffers, multiple windows, multiple
user interfaces (including an X11 interface), and a variety of display
modes.
To exit Elvis, you can give the command ":q" in each of its windows.
If you’ve modified the buffer in a window, and you want to abandon
those changes, then give the command ":q!" instead.
HELP PAGES
For more information please take a look at Elvis’ help pages. These
pages should have been installed together with Elvis. To view the help
pages, start Elvis and give the command ":help".
If this does not show you the main help file then something is wrong.
Perhaps the help pages were installed in the wrong place. In that
case, search for a file named "elvis.html" using either GNU’s locate(1)
or the standard find(1) program. Hopefully this will show you where
the file is located. You can then view it with...
:sp /directory/elvis.html
If the help pages aren’t installed on your system but you have access
to the Internet, then you can view the help pages via HTTP by
running...
:sp http://elvis.vi-editor.org/elvisman/elvis.html
OPTIONS
-V "Verbose" mode, causes Elvis to output more status messages.
You can use multiple -V flags to get even more detailed
information. -VVV can be handy when Elvis isn’t initializing
itself quite the way you expected. See also the -ologfile
option, described below.
-a Instructs Elvis to load all files named on the command line
simultaneously with a separate window for each.
-r This is used for recovering an edit session after a crash. Each
Elvis process uses a single "session file" to store the contents
of all edit buffers. While Elvis is running, a flag is set near
the beginning of the session file so that other Elvis processes
won’t try to use it at the same time. If an Elvis process dies
abnormally, though, it will leave the session file lying around
with that flag set; the -r flag allows Elvis to open a session
file even if it is marked as being in use.
-e Causes Elvis to start each window in ex mode, instead of visual
command mode. Invoking Elvis as "ex" implies this.
-i Causes Elvis to start each window in input mode, instead of
visual command mode. Novice users may prefer this.
-b This sets the "binary" option, which causes new buffers to be
marked as "readeol=binary". Without -b, Elvis will try to guess
the format by examining the first hundred bytes or so of the
file.
-R This sets the "defaultreadonly" option, which causes all new
buffers to be marked as "readonly" so you won’t accidentally
overwrite the original file.
-S Sets security=safer, making Elvis paranoid about certain
potentially harmful commands. The intent is to protect the user
against writing by malicious scripts. The ./.exrc file and
modelines are executed with security=safer temporarily
regardless of whether -S was given. The -S flag is just used to
make Elvis permanently paranoid, for the duration of this
process.
-SS Sets security=restricted. This is more extreme security than
"-S". The intent is to protect the system against reading by
malicious users.
-f session
Makes Elvis use the session file named "session" instead of the
default file. Session files are discussed in the description of
the -r flag, above.
-o logfile
Redirects messages and trace information out to logfile instead
of going to stdout/stderr as usual. This is useful under
Windows95, where stdout/stderr don’t show anywhere. If you’re
having trouble configuring WinElvis, try running "WinElvis -VVV
-o log" and then you can find the trace and error messages in
the file "log".
-G gui Makes Elvis use the named gui user interface instead of the
default. To see a list of supported user interfaces, give the
command "elvis -?".
-c command
After loading the first file, interpret command as an ex command
line. Several ex command lines can be sent in one line,
separated by "|". This is good to know, because only a single
-ccommand or +command flag can be used.
-s Read an ex script from stdin, and execute it. This is similar
to the -Gscript flag, except that -s has the additional side-
effect of bypassing all initialization scripts.
-t tag Causes editing to begin at the location where the given tag is
defined. See the ctags(1) command for more information about
tags.
-w scroll
This sets the "window" option, which has very little effect in
Elvis.
-B blksize
If a new session file is created, this causes it to use blocks
of size blksize.
In addition, the following options are also supported to maintain
backward compatibility, although their future use is discouraged.
+command
Like -c command, this causes the ex command to be executed after
the first file is loaded. If the command is omitted, it is
understood to be "$", which causes the cursor to move to the
last line of the file.
- Like -s, this causes Elvis to read a script from stdin and
execute it.
TERMCAP INTERFACE
The termcap interface is the one you’ll use most often on non-graphic
terminals. It looks and acts a heck of a lot like the traditional vi.
The biggest addition is the support for multiple windows. For more
information on how to use multiple windows, start Elvis and give the
command ":help ^W". The short form of that help is: ^Ws splits the
screen to form an additional window, ^Wq closes the window, and ^W^W
switches the cursor from one window to another.
If your terminal supports ANSI color escape sequences, then you can use
the ":color" command to assign different colors to various fonts. You
must assign a "normal" color first, e.g., ":color normal yellow on
blue".
The DOS and (text mode) Win32 version of the termcap interface support
the mouse. The mouse behaves almost exactly like the X11 mouse,
described below. The only differences are that the mouse can’t be used
to cut & paste to the clipboard, and on a two-button mouse you can
simulate a middle button by simultaneously pressing the left and right
buttons.
X11 INTERFACE
The x11 interface is used under X-Windows on UNIX systems. It provides
a scrollbar and mouse support, and allows you to select which fonts to
use.
X11 Options
To specify a normal font, use -font fontname or -fn fontname.
Proportional fonts are not properly supported, but they aren’t rejected
with an error message either. If you don’t specify a normal font, then
Elvis will use a font named "fixed" by default. (This default can be
overridden by a "set font=..." command in the elvis.ini file. The
default elvis.ini file does this, making the new default font be
18-point Courier.)
To specify a bold font, use -fb fontname. The specified font should
have the same size character cell as the normal font, but Elvis does
not verify this. If you don’t specify a bold font, then Elvis will
fake it by smearing the normal font rightward one pixel.
To specify an italic font, use -fi fontname. The specified font should
have the same size character cell as the normal font, but Elvis does
not verify this. If you don’t specify an italic font, then Elvis will
fake it by sliding the top half of the normal font rightward one pixel.
If you want to use Courier fonts, there is a shortcut: -courier size
will use the normal, bold, and italic versions of the Courier font in
the requested size.
You can force Elvis to use only black and white with the -mono flag;
this is the default if your display only has one bitplane. For color
displays, -fg color and -bg color can be used to set the normal text
color and the background color, respectively.
Elvis has a built-in icon, which is generally a good thing. Some
window managers won’t allow you to assign a new icon to a program that
has a built-in one, so Elvis has a -noicon flag which disables the
built-in icon.
The -fork client causes Elvis to run in the background, so that your
shell prompt returns immediately.
The -client option causes Elvis to look for an already-running Elvis
process on the same X server and, if there is one, send the new
arguments to it. This causes the old Elvis process to create new
windows for file arguments. The new Elvis process then exits, leaving
the old one to do the real work and allowing your shell program to
prompt for a new command immediately. For the sake of uniformity, if
-client fails to find an existing Elvis process, then a new Elvis
process starts up as though you had used the -fork argument instead.
The -client option is implemented in an interesting way: the client
Elvis simply sends a series of ex commands to an existing window of the
server Elvis. For each file name argument, the client Elvis sends a
":split file" command. For -ttag, the client Elvis sends a ":stag tag"
command. For -ccommand, the client Elvis simply sends the command, and
this results in some quirks. First, the server Elvis temporarily sets
security=safer while the command is executed, for security reasons.
Second, the command is executed by the server’s existing window, not
the new one, so (for example) "elvis -client -c 20 foo" creates a new
window for the file "foo", and then moves the OLD WINDOW’s cursor to
line 20 of whatever file it was showing.
X11 Mouse
I’ve tried to reach a balance between the mouse behavior of xterm(1)
and what makes sense for an editor. To do this right, Elvis has to
distinguish between clicking and dragging.
Dragging the mouse always selects text. Dragging with button 1 pressed
(usually the left button) selects characters, dragging with button 2
(the middle button) selects a rectangular area, and dragging with
button 3 (usually the right button) selects whole lines. These
operations correspond to Elvis’ v, ^V, and V commands, respectively.
When you release the button at the end of the drag, the selected text
is immediately copied into an X11 cut buffer, so you can paste it into
another application such as xterm. The text remains selected, so you
can apply an operator command to it.
Clicking button 1 cancels any pending selection, and moves the cursor
to the clicked-on character. Clicking button 3 moves the cursor
without canceling the pending selection; you can use this to extend a
pending selection.
Clicking button 2 "pastes" text from the X11 cut butter. If you’re
entering an ex command line, the text will be pasted into the command
line as though you had typed it. If you’re in visual command mode or
input mode, the text will be pasted into your edit buffer. When
pasting, it doesn’t matter where you click in the window; Elvis always
inserts the text at the position of the text cursor.
Double-clicking button 1 simulates a ^] keystroke, causing Elvis to
perform tag lookup on the clicked-on word. If Elvis happens to be
displaying an HTML document, then tag lookup pursues hypertext links so
you can double-click on any underlined text to view the topic that
describes that text. Double-clicking button 3 simulates a ^T
keystroke, taking you back to where you did the last tag lookup.
If your mouse has a scroll wheel, then Elvis can be configured to use
it. For instructions on doing this, start Elvis and give the command
":howto scrollwheel".
ENVIRONMENT VARIABLES
Elvis has commands which can examine any environment variable. Because
of this, a comprehensive list of environment variables isn’t possible.
The following list contains the environment variables which have
hardcoded meaning in Elvis.
BASH or BASH_VERSION
Under Unix/Linux, Elvis tests for the presence of these
variables to decide whether or not the /bin/sh shell supports
process control, especially the ^Z key. The values of these
variables doesn’t matter, only the fact that they exist.
COLUMNS
For the "termcap" user interface, this overrides the number of
columns specified in the termcap/terminfo entry.
DISPLAY
For the "x11" user interface, this indicates which display it
should run on.
ELVISBG
If set to "light" or "dark", its value is used as the default
value for the background option.
ELVISGUI
If set, its value is used to select the default user interface.
You can still override it by using the -Ggui command line flag.
ELVISPATH
If ELVISPATH is defined in the environment, then its value is
copied into the elvispath option, which is a list of directories
that Elvis should search through when looking for its support
files. If ELVISPATH is undefined, Elvis will use a default list
which usually includes the your home directory, and maybe a
system-wide default location.
EXINIT If defined, the value of this option is typically interpreted as
a series of EX commands when Elvis starts up. This behavior
isn’t built into Elvis though; it is handled by the standard
elvis.ini file.
HOME This is your home directory. Its value is used as the default
value for the home option, which is used in ~ substitution in
file names.
HOMEDRIVE and HOMEPATH
For Windows, if HOME is unset then HOMEDRIVE and HOMEPATH are
checked; if they’re set then they’re concatenated to form the
default value of the home option.
INCLUDE
The "syntax" display mode uses this as a list of directories to
search through when looking for a header file such as <stdio.h>.
LC_ALL, LC_MESSAGES, and LANG
If LANG is defined, then Elvis will look for its message
translations in $LANG/elvis.msg, and only use just plain
elvis.msg if it can’t find $LANG/elvis.msg. The LC_MESSAGES and
LC_ALL environment variables work similarly, and take precedence
over LANG.
LINES For the "termcap" user interface, this overrides the number of
lines specified in the termcap/terminfo entry.
LOGNAME
This stores your login name. It is used when reading via the
FTP protocol, to choose the default login information.
OLDPWD This stores the name of the previous directory you were in. Its
value is stored in the prevdir option, which is used for ~-
substitution in file names.
PATH The usual search path for programs.
SESSIONPATH
This is a list of directories where Elvis might be able to
create the session file. Elvis uses the first writable
directory from the list, and ignores all others.
SHELL or COMSPEC
This is the name of your command-line interpreter. Elvis needs
to know this so you can run programs from inside Elvis. SHELL
is used in Unix/Linux, and COMSPEC is used in MS-DOS.
TAGPATH
This is a path for tags files, used by the :tag command. For
Microsoft it is semicolon-delimited; for all others it is colon-
delimited. Each entry in the path can be either a filename, or
the name of a directory containing a file named tags.
TERM For the termcap interface, this is the name of the terminal’s
termcap/terminfo entry. Also, if its value is "kvt" or ends
with "-r" or "-rv", then the background option will be "light"
by default; else it will be "dark".
TERMCAP
For the termcap interface, this can either store the name of a
termcap file or the actual contents of a termcap entry.
TMP This is where Elvis stores its temporary files other than
session files.
WINDOWID
Elvis uses this when choosing the default value of the
background option. If the WINDOWID environment variable exists,
then Elvis assumes it is running in an xterm-like terminal
emulator, and those emulators usually have a light background.
XENVIRONMENT, XFILESEARCHPATH, and XUSERFILESEARCHPATH
These are used by the "x11" user interface, when loading Elvis’
resources.
FILES
~ This is your home directory. Whenever Elvis sees a ~ at the
start of a pathname, it replaces the ~ with the value of the
"home" option. The "home" option is initialized from the HOME
environment variable; if HOME is unset then some operating
systems will set "home" to the the directory where the Elvis
program resides.
lib In this man-page, "lib" is a placeholder for the name of a
directory in which Elvis’ configuration files reside. The
"elvispath" option’s value is a list of directories that Elvis
will check for each configuration file.
elvis*.ses
These are the default names for sessions files. Session files
store the contents of all edit buffers for a given edit session.
You can instruct Elvis to use a specific session file via the
-fsession command-line flag. Note that sessions specified via
-fsession normally reside in the current directory, but when
Elvis chooses its own session file name, it will place it in the
first writable directory named in the SESSIONPATH environment
variable.
tags This file stores the tags for the files in a directory. It is
used by the :tag command, among others.
lib/elvis.ini
This file contains EX commands which are executed whenever Elvis
starts up. Elvis searches through the ELVISPATH for the file.
~/.exrc, ~/.elvisrc, or ~\elvis.rc
The .exrc or .elvisrc (for UNIX) or elvis.rc (for non-UNIX) file
in your home directory will generally be executed as a series of
EX commands, unless the EXINIT environment variable is defined.
This behavior isn’t built into Elvis though; it is handled by
the standard elvis.ini file.
.exrc, .elvisrc, or elvis.rc
The .exrc or .elvisrc (for UNIX) or elvis.rc (for non-UNIX) file
in the current directory is interpreted as a series of EX
commands, but only if the exrc option has been set. This
behavior isn’t built into Elvis; it is handled by the standard
elvis.ini file.
lib/elvis.brf
This file contains EX commands which are executed Before Reading
a File. Typically this is used to distinguish a binary file
from a text file by examining the file name extension of the
file. The "readeol" option is then set accordingly.
lib/elvis.arf
This file contains EX commands which are executed After Reading
a File. If the current directory doesn’t contain an elvis.arf
file, then Elvis searches through the ELVISPATH for the file.
Typically, this is used to set the bufdisplay option for a
buffer, based on the file name extension of the file.
lib/elvis.bwf
This file contains EX commands which are executed Before Writing
a File. Typically, lib/elvis.bwf is used to perform an RCS
"checkout" command before writing a file.
lib/elvis.lat
This contains a series of ":digraph" commands which set up the
digraph table appropriately for the ISO Latin-1 symbol set. The
lib/elvis.ini file executes this script during initialization,
except under OS/2, MS-DOS, or text-mode Win32.
lib/elvis.pc8
This contains a series of ":digraph" commands which set up the
digraph table appropriately for the PC-8 symbol set. This is
the normal symbol set for MS-DOS, OS/2, and text-mode Win32
(although the graphical Win32 uses lib/elvis.lat). The
lib/elvis.ini file executes this script during initialization
under MS-DOS.
lib/elvis.msg
This file’s data is used for mapping the Elvis’ terse error
messages into verbose messages.
lib/elvistrs.msg
Elvis doesn’t use this file directly; it is simply meant to
serve as a resource from which you can extract the terse form of
one of elvis’ messages; you can then add the terse form and your
own custom verbose form to the lib/elvis.msg file.
lib/elvis.syn
This file controls how Elvis’ "syntax" display mode highlights
the text for a given language.
lib/elvis.x11
This file contains a series of ex command. This file is sourced
by lib/elvis.ini if Elvis is using its X11 user interface. It
configures up the toolbar and default colors.
lib/elvis.ali
This contains a set of aliases. If your copy of Elvis is
configured to support aliases (i.e., if it isn’t the MS-DOS
version) then these aliases will be loaded automatically. They
are partly intended to serve as examples of what aliases can do
and how to write them, but mostly these aliases are intended to
be truly useful. To see a list of the aliases, give the command
":alias".
lib/elvis*.html
These files contain the online documentation.
lib/*.man
These contain the man pages -- shorter summaries of the
programs, with descriptions of the command-line flags.
guix11/*.xpm and guix11/elvis.xbm
These contain icon images for use with X-windows. The
"elvis.xbm" image is a 2-color bitmap, and it is compiled into
Elvis. The other files, such as "elvis.xpm," contain color
images. The "insticon.sh" shell script (which is invoked as
part of the "make install" operation) tries to copy these into
appropriate directories.
SEE ALSO
ex(1), vi(1), ctags(1)
You should also view the on-line documentation, via ":help".
AUTHOR
Steve Kirkendall
kirkenda@cs.pdx.edu
elvis(1)