elvis - a clone of the ex/vi text editor

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

Elvis 2.2_0

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.

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

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

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.

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

X11 Mouse

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.

~

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.

ex(1), vi(1), ctags(1)

You should also view the on-line documentation, via ":help".

Steve Kirkendall

kirkenda@cs.pdx.edu