home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 5 Edit
/
05-Edit.zip
/
elvos221.zip
/
lib
/
elvis.INF
(
.txt
)
< prev
next >
Wrap
OS/2 Help File
|
1998-12-10
|
339KB
|
10,480 lines
ΓòÉΓòÉΓòÉ 1. Elvis 2.1 Documentation ΓòÉΓòÉΓòÉ
TABLE OF CONTENTS
1. What is elvis?
2. Visual command mode (by function or name)
3. Input mode
4. EX command mode (by function or name)
5. Regular expressions (searches and substitutions)
6. Options (by function or name)
7. Display modes
8. User interfaces
9. Operating systems
10. Sessions, initialization, and recovery
11. Cut buffers
12. Messages
13. Arithmetic expressions (arithmetic, tests, and functions)
14. Tags
15. The Internet
16. Tips
A. List of terse messages (not in here, see elvistrs.msg)
B. Quick Reference
C. How To...
elvis(1) Man-page for elvis (not in here, see elvis.man)
ctags(1) Man-page for ctags (not in here, see ctags.man)
ref(1) Man-page for ref (not in here, see ref.man)
fmt(1) Man-page for fmt (not in here, see fmt.man)
HINT: If you're reading this via elvis' built-in :help command, then you
should probably begin by reading about :help itself. To do that, move the
cursor onto the word ":help" and press the Enter key.
.--------------------------------------------------------------.
| Copyright (C) 1995 by Steve Kirkendall. Permission is granted |
| to use and distribute this software in either source code |
| form, or executable form, under the terms described in the |
| license. The license is in the file "lib/license". This |
| software is provided with no warranty of any kind. The |
| author is not liable for any consequences arising from the |
| use of this software. |
^--------------------------------------------------------------^
You can contact the author via e-mail at kirkenda@cs.pdx.edu, or via postal
mail at:
Steve Kirkendall
1500 SW Park Avenue, #326
Portland OR 97201
USA
ΓòÉΓòÉΓòÉ 1.1. What is elvis? ΓòÉΓòÉΓòÉ
1. WHAT IS ELVIS?
Elvis is a clone of vi/ex, the standard UNIX editor. Elvis supports nearly all
of the vi/ex commands, in both visual mode and ex mode. Elvis adds support for
multiple files, multiple windows, a variety of display modes, on-line help, and
other miscellaneous extensions.
Like vi/ex, Elvis stores most of the text in a temporary file, instead of RAM.
This allows it to edit files that are too large to fit in a single process'
data space. Also, the edit buffer can survive a power failure or crash.
Elvis 2.1 runs under the following operating systems:
UNIX. If you have X-windows, elvis can use a graphical interface, in
addition to the traditional text-based interface.
MS-Windows/95 and Windows/NT. Both a console (text-based) and a graphical
version are available.
MS-DOS. It can also run in a DOS window under Windows 3.1. However, there
is no graphic 16-bit version of elvis.
OS/2. The basic OS/2 port only supports a text-mode interface using VIO
calls; it acts exactly like the termcap interface. There is also a real
port of the termcap version which requires the EMX library, and a version
which uses the graphical "x11" interface which requires XFree86.
Elvis is freely redistributable, in either source form or executable form.
There are very few restrictions on how you may use it.
1.1 About this manual
This document is written in HTML. You should be able to view it with any Web
browser, such as Mosaic or Netscape. These browsers also allow you to print
the manual, if you prefer.
You can also use elvis to view it or print it; elvis has a built-in HTML
display mode. To print this document using elvis, you must first set some
printer options. After that, you can just load any of these files, maybe set
the display mode to HTML via the command ":display html" (if elvis doesn't set
the display mode automatically), and then give the command ":lp".
Each chapter is stored in a separate file; you'll need to print each one
separately. A shell script/batch file named printdoc.bat is provided to help
you do this.
1.2 Overview of Elvis
The user interface of Elvis/vi/ex is weird. There are two major command modes
in Elvis, and a few text input modes as well. Each command mode has a command
which allows you to switch to the other mode.
You will probably use the visual command mode most of the time. This is the
mode that Elvis normally starts up in.
In visual command mode, the entire screen is filled with lines of text from
your file. Each keystroke is interpreted as part of a visual command. If you
start typing text, it will not be inserted, it will be treated as part of a
command. To insert text, you must first give an "insert text" command, such as
i. This will take some getting used to. (An alternative exists. Look up the
initialstate option.)
The ex mode is quite different. Elvis displays a ":" character on the bottom
line of the screen, as a prompt. You are then expected to type in a command
line and hit the Enter key. The set of commands recognized in the ex mode is
different from visual mode's.
1.3 Special features of Elvis
Compared to the traditional ex/vi, elvis supports the following major new
features:
Multiple edit buffers
You can edit several files at the same time. The :buffer ex command
lists the current edit buffers. You can switch to a different buffer
by typing :(buffername or :buffer buffername.
Multiple windows
The :split ex command or ^Ws visual command will create a new window
showing the same edit buffer. You can use :split filename to edit a
different file in a new window. Related commands allow you to do
things like search for a tag and display it in a new window, or move
among windows.
Multiple user interfaces
In addition to the traditional termcap user interface, elvis also
supports graphical interfaces for X11 and Windows95, plus some other
stripped-down interfaces.
A variety of display modes
The :display command lists the available display modes, and can set
the display to a particular mode. The ^Wd visual command toggles
between display modes.
Online help
This uses elvis' built-in "html" display mode to display the manual,
which uses multiple fonts and hypertext links to improve
readability. To access it, give the command :help. (But you already
figured that out, didn't you?)
Highly configurable
Elvis has a set of configuration scripts, each of which is run at a
specific time. For example, elvis.ini is run when elvis starts up,
and elvis.arf is run after reading a file. See the chapter on
sessions for a discussion of these.
There is also an elvis.msg file which can be used to translate the
built-in messages into another language.
The X11 interface has a fully configurable toolbar.
The elvis.syn file contains descriptions of various languages, for
use with the syntax-coloring display mode.
Enhanced tags
The tags feature has been extended to support overloaded tags, which
C++ tends to use a lot. See the tags chapter.
Macro debugger
To help you develop keyboard macros (and also report
incompatibilities between elvis and vi), elvis has a built-in macro
debugger. The the article in the Tips chapter.
Network support
Elvis can read via the http protocol, and read/write via the ftp
protocol. See the Internet chapter.
Aliases
You can construct csh-style aliases for the ex commands, via the
:alias command. See the article in the Tips chapter.
New options
Elvis has roughly 200 different options. See the Options chapter
for a list.
Built-in calculator
Elvis has a : calc command which evaluates C-like expressions.
These expressions are also used for some other commands, such as :if
and :eval, among other things. See the Arithmetic expressions
chapter.
ΓòÉΓòÉΓòÉ 1.2. Elvis 2.1 Visual Command Mode ΓòÉΓòÉΓòÉ
2. VISUAL COMMAND MODE
Most visual mode commands are one keystroke long. The following tables list the
operation performed by each keystroke, and also denotes any options or
arguments that it accepts.
In addition to the keys listed here, your keyboard's "arrow" keys will be
interpreted as the appropriate cursor movement commands. The same goes for
(PgUp) and (PgDn), if your keyboard has them. The (Insert) key will toggle
between insert mode and replace mode. There is a colon mode command (":map", to
be described later) which will allow you to define other keys, such as function
keys.
A tip: visual command mode looks a lot like text input mode. If you forget
which mode you're in, just hit the (Esc) key. If Elvis beeps, then you're in
visual command mode. If Elvis does not beep, then you were in input mode, but
by hitting (Esc) you will have switched to visual command mode. So, one way or
another, after (Esc) Elvis will be ready for a command.
2.1 Notation
The following notation is used in the tables that follow...
count
Many commands may be preceded by a count. This is a sequence of
digits representing a decimal number. For most commands that use a
count, the command is repeated count times, but a few commands use
the count value for some completely different purpose. The count is
always optional, and usually defaults to 1.
key
Some commands require two keystrokes. The first key always
determines which command is to be executed. The second key is used
as a parameter to the command.
mv
Some commands (! < > = c d y) operate on text between the cursor and
some other position. Usually, the other position is specified by
typing a movement command after the operator command, but there are
other options. See the section on operators for more information.
inp
Many commands allow the user to interactively enter text. See the
discussion of "input mode" in the following chapter.
2.2 Visual Commands, Grouped by Function
2.2.1 Edit commands
2.2.2 Edit commands which are operators
2.2.3 Edit commands which are shortcuts for operators
2.2.4 Movement commands which move by a line or column
2.2.5 Movement commands which are window-relative
2.2.6 Movement commands which search for strings
2.2.7 Movement commands which search for characters
2.2.8 Movement commands which move by words
2.2.9 Movement commands which move by sentences or sections
2.2.10 Movement/mark commands
2.2.11 Scrolling commands
2.2.12 Window commands
2.2.13 Other commands
2.2.1 Edit commands
.--------------.------------------------------------------------------.
| COMMAND | DESCRIPTION |
|--------------|------------------------------------------------------|
| P | Paste text before the cursor |
| p | Paste text after the cursor |
| count J | Join lines, to form one big line |
| count X | Delete the character(s) to the left of the cursor |
| count x | Delete the character that the cursor's on |
| count ~ | Switch a character between uppercase & lowercase |
| count r key | Replace "count" chars by a given character |
| R inp | Overtype |
| count a inp | Insert text after the cursor |
| count A inp | Append at end of the line |
| count i inp | Insert text at the cursor |
| count I inp | Insert at the front of the line (after indents) |
| count o inp | Open a new line below the current line |
| count O inp | Open up a new line above the current line |
| count . | Repeat the previous "edit" command |
| count u | Undo the previous edit command |
| count ^R | Redo commands which were undone by the u command |
| U | Undo all recent changes to the current line |
^--------------^------------------------------------------------------^
P
p
The P and p commands paste text from a cut buffer. The difference
between them is that p pastes after the cursor, and P pastes before
it. See the section on cut buffers for more information.
count J
The J command joins the current line with the following line. If you
supply a count argument, then it will joint that many lines
together, starting at the current line.
count X
count x
The X and x commands delete characters. The difference between them
is that x deletes the character at the cursor, and X deletes the
character before the cursor. If you supply a count, then it will
delete that many characters. The deleted characters are copied into
a cut buffer. The X and x commands never delete newline characters.
count ~
The ~ command changes uppercase letters to lowercase, or vice versa,
and moves the cursor forward. Non-letters are unaffected, but the
cursor will still be moved forward.
count r key
The r command replaces a single character in the edit buffer with a
single character read from the keyboard. If you supply a count, then
it will replace that many characters in the edit buffer with
multiple copies of a single character from the keyboard.
R inp
The R command switches the window to "replace mode" which is a
variation of input mode.
count a inp
The a command switches to input mode with the cursor starting
immediately after its previous position. If a count is supplied,
then after you manually insert the first copy of the new text, elvis
will automatically insert count-1 additional copies.
count A inp
The A command switches to input mode with the cursor starting at the
end of the current line. If a count is supplied, then after you
manually insert the first copy of the new text, elvis will
automatically insert count-1 additional copies.
count i inp
The i command switches to input mode with the cursor starting at its
current position. If a count is supplied, then after you manually
insert the first copy of the new text, elvis will automatically
insert count-1 additional copies.
count I inp
The I command switches to input mode with the cursor starting at the
beginning of the current line. If a count is supplied, then after
you manually insert the first copy of the new text, elvis will
automatically insert count-1 additional copies.
count o inp
The o command switches to input mode. A new, blank line is created
after the current line, and the cursor starts at the beginning of
that new line. If a count is supplied, then after you manually
insert the first copy of the new text, elvis will automatically
insert count-1 additional copies.
count O inp
The O command switches to input mode. A new, blank line is created
before the current line, and the cursor starts at the beginning of
that new line. If a count is supplied, then after you manually
insert the first copy of the new text, elvis will automatically
insert count-1 additional copies.
count .
The . command repeats the previous command which changed text. If a
count is supplied, it overrides count of the original command.
count u
The u command undoes the previous edit command. If a count is
supplied, then it will undo that many changes, within the limit
defined by the undolevels option.
count ^R
The ^R command redoes commands which were undone by the u command.
Essentially it undoes the "undo".
U
The U command undoes all changes which were made to the current line
since the cursor was moved onto it.
2.2.2 Edit commands which are operators
.--------------.------------------------------------------------------.
| COMMAND | DESCRIPTION |
|--------------|------------------------------------------------------|
| < mv | Shift text left |
| > mv | Shift text right |
| ! mv text| Run selected lines thru an external filter program |
| = mv | Reformat |
| c mv inp | Change text |
| d mv | Delete text |
| y mv | Yank text (copy it into a cut buffer) |
^--------------^------------------------------------------------------^
These commands all affect text between the cursor's current position and some
other position. There are three ways that you can specify that other position:
Follow the command keystroke with a movement command. For example, dw
deletes a single word. d3w and 3dw both delete three words.
Type the command keystroke twice. This causes whole lines to be acted
upon. For example, >> indents the current line. 3>> indents the current
line and the following two lines.
Move the cursor to one end of the text, type v, V, or ^V to start
marking, move the cursor to the other end, and then type the desired
command key.
< mv
> mv
These commands adjust the indentation of lines. The < command
reduces indentation by shiftwidth columns, and the > command
increases indentation by the same amount. The type of whitespace
used for the new indentation is determined by the autotab option.
The doubled-up << and >> commands reduce or increase the indentation
for the current line, respectively.
! mv text
This command prompts you to enter a shell command line at the bottom
of the window. When you've entered the command line, that command is
executed and the selected text is piped through it. The resulting
text replaces the original selected text. For example, 10!!sort will
send 10 lines through the sort program.
= mv
When applied to lines, this command resembles the ! command, except
that instead of prompting for a command line, the = command will
always execute the program specified via the equalprg option. If you
expect to be running the same filter program over and over again,
then = is more convenient.
When applied to characters selected via the v command, the = command
uses elvis' built-in calculator to evaluate the characters, and then
replaces the original text with the result of that evaluation. For
example, if you move the cursor to the start of a parenthesized
arithmetic expression and hit v%= then the expression will be
simplified.
c mv inp
This command puts you in input mode so you can replace the selected
text with new, manually-entered text. The doubled-up cc command
changes the current line.
d mv
y mv
These commands copy the selected text into a cut buffer. The d
command then deletes the text from the edit buffer, but y leaves the
original text intact. The doubled-up dd and yy commands delete or
yank the current line, respectively.
2.2.3 Edit commands which are shortcuts for operators
.--------------.------------------------------------------------------.
| COMMAND | DESCRIPTION |
|--------------|------------------------------------------------------|
| C inp | Change text from the cursor to the end of the line |
| D | Delete text from the cursor to the end of the line |
| count S inp | Change lines, like "count" cc |
| count s inp | Replace characters, like "count" cl |
| count Y | Yank text line(s) (copy them into a cut buffer) |
^--------------^------------------------------------------------------^
C inp
D
count S inp
count s int
count Y
All of these commands are shortcuts for particular operator/movement
command combinations. C is short for c$, D is short for d$,
uppercase S is short for cc, lowercase s is short for cl, and Y is
short for yy.
2.2.4 Movement commands which move by a line or column
.--------------.------------------------------------------------------.
| COMMAND | DESCRIPTION |
|--------------|------------------------------------------------------|
| 0 | If not part of count, move to 1st char of this line |
| ^ | Move to the front of the current line (after indent) |
| $ | Move to the rear of the current line |
| count | | Move to column "count" (defaulting to column 1) |
| count ^X | Move to column "count" (defaulting to the right edge)|
| count ^M | Move to the front of the next line |
| count + | Move to the front of the next line |
| count - | Move to the front of the preceding line |
| count G | Move to line #"count" (default is the bottom line) |
| count h | Move left |
| count ^H | Move left |
| count l | Move right |
| count Space | Move right |
| count j | Move down |
| count ^J | Move down |
| count ^N | Move down |
| count k | Move up |
| count ^P | Move up |
| count _ | Move to the current line |
^--------------^------------------------------------------------------^
0
The 0 command moves the cursor to the first character in the current
line.
^
The ^ command moves the cursor to the first non-whitespace character
in the current line. If the current line doesn't contain any
non-whitespace characters, then the cursor is moved to the end of
the line.
$
The $ command moves the cursor to the last character in the line.
count |
count ^X
These commands move the cursor to a given column. The leftmost
column is designated "column 1." If the cursor can't be moved to the
exact column number requested (e.g., because the line isn't that
long, or the requested column falls in the middle of a tab
character), then elvis will move the cursor as close as possible. If
no count is given, then the | command moves the cursor to column 1
and the ^X move the cursor to the rightmost visible column (taking
side scrolling into account).
count ^M
count +
The ^M and + commands move the cursor down count lines (or 1 line if
no count is given), and then to the first non-whitespace character
in that destination line. It is equivalent to a j command followed
by a ^ command.
count -
The - command moves the cursor up count lines (or 1 line if no count
is given), and then to the first non-whitespace character in that
destination line. It is equivalent to a k command followed by a ^
command.
count G
The G command moves the cursor directly to the start of a given
line, or to the last line if no count is given.
For the purposes of this command, the "line number" of the cursor
position is defined to be one plus the number of newline characters
which precede it in the buffer. This definition is used regardless
of what display mode you happen to be using. The number and ruler
options use the same definition.
count h
count ^H
The h and ^H commands move the cursor count characters to the left,
or 1 character leftward if no count is given. They won't move the
cursor past the beginning of the line.
count l
count Space
The h and Space commands move the cursor count characters to the
right, or 1 character rightward if no count is given. They won't
move the cursor past the end of the line.
count j
count ^J
count ^N
These commands all move the cursor down count lines (or 1 line if no
count is given), without changing the column of the cursor if
possible.
count k
count ^P
These commands all move the cursor up count lines (or 1 line if no
count is given), without changing the column of the cursor if
possible.
count _
The _ command moves the cursor down count-1 lines. This command is
used internally to implement the double-operators; for example, <<
is interpreted as <_. By itself the _ command is pretty useless.
2.2.5 Movement commands which are window-relative
.--------------.------------------------------------------------------.
| COMMAND | DESCRIPTION |
|--------------|------------------------------------------------------|
| count H | Move to home row (the line at the top of the screen) |
| M | Move to middle row |
| count L | Move to last row (i.e., line at bottom of window) |
^--------------^------------------------------------------------------^
count H
The H command moves the cursor to the front of the first line that
is currently visible in the window. If a count is given, then it
will move down count-1 lines from the top of the window.
M
The M command moves the cursor to the front of the line in the
middle of the window.
count L
The L command moves the cursor to the front of the line line that is
currently visible in the window. If a count is given, then it will
move up count-1 lines from the bottom of the window.
2.2.6 Movement commands which search for strings
.--------------.------------------------------------------------------.
| COMMAND | DESCRIPTION |
|--------------|------------------------------------------------------|
| / text | Search forward for a given regular expression |
| ? text | Search backward for a given regular expression |
| ^A | Search for next occurrence of word at cursor |
| n | Repeat the previous search |
| N | Repeat previous search, but in the opposite direction|
^--------------^------------------------------------------------------^
All of these search commands are affected by the magic, ignorecase, wrapscan,
and autoselect options.
/ text
? text
These commands prompt you to enter a regular expression at the
bottom of the window. When you have entered it, elvis will search
forward (for /) or backward (for ?) for text which matches the
regular expression. Normally the cursor is positioned at the start
of the matching text. If you want to include a / or ? character in
the regular expression, you must precede it with a backslash;
otherwise it will be interpreted as a closing delimiter.
When entering the regular expression, you can append a closing
delimiter (/ or ?, as appropriate) followed by a line delta (+ or -
followed by a line number) to move the cursor to the start of a line
after or before the matching text. You can also use v or n flags to
temporarily force the autoselect option on or off for that one
search.
^A
This command searches forward for the next instance of the word
under the cursor. It is a shortcut for the /\<\@\> Enter command.
n
N
These commands repeat the previous /, ?, or ^A command. The n
command repeats it in the same direction as the original search, and
N repeats it in the opposite direction.
2.2.7 Movement commands which search for characters
.--------------.------------------------------------------------------.
| COMMAND | DESCRIPTION |
|--------------|------------------------------------------------------|
| count % | Move to matching (){}[] or to a given % of file |
| count F key | Move leftward to a given character |
| count f key | Move rightward to a given character |
| count T key | Move leftward *almost* to a given character |
| count t key | Move rightward *almost* to a given character |
| count , | Repeat the previous [fFtT] but in the other direction|
| count ; | Repeat the previous [fFtT] cmd |
^--------------^------------------------------------------------------^
count %
This command actually performs one of two totally separate
movements, depending on whether a count was supplied. With no count,
if the cursor is on a parenthesis character from the matchchar list,
then it moves the cursor to the opposite parenthesis. If the cursor
isn't on a parenthesis to begin with, then elvis will scan forward
on the current line until it finds one, and then move to its
opposite. It can also show matching preprocessor directives, if the
window is in the syntax display mode for a language which has a
preprocessor.
However, if a count is supplied, then it is used as a percentage
from 1 to 100, and the cursor is moved to that percentage of the way
into the buffer. For example, typing 50% will move the cursor to the
middle of the buffer.
count F key
count f key
These commands search for the character key in the current line,
starting from the cursor position. For example, fk searches forward
for the next "k". F4 searches backward for the previous "4". If the
end of line is reached without finding the character, then the
command fails.
count T key
count t key
These commands move almost, but not quite, to the next instance of
key. The t and T commands stop one character short of where f and F
would stop, respectively.
count ,
count ;
The ; command repeats the previous f, F, t, or T command. You don't
need to type a key because elvis automatically uses whatever key you
looked for last time. The , command also repeats the previous f, F,
t, or T command, but in the reverse direction.
2.2.8 Movement commands which move by words
.--------------.------------------------------------------------------.
| COMMAND | DESCRIPTION |
|--------------|------------------------------------------------------|
| count w | Move forward "count" words |
| count e | Move forward to the end of the current word |
| count b | Move back "count" words |
| count W | Move forward "count" Words |
| count E | Move end of Word |
| count B | Move back Word |
^--------------^------------------------------------------------------^
The uppercase and lowercase versions of these commands differ only in their
definition of a "word." The uppercase commands consider a word to be any
sequence of non-whitespace characters, bound by whitespace characters or the
ends of the buffer.
The lowercase commands define a word as either a sequence of alphanumeric
characters, or a sequence of punctuation characters, but not a mixture of the
two; these words can be bound by whitespace, the ends of the buffer, or by
characters from the other class of lowercase word. (I.e, an alphanumeric word
can be bound by punctuation characters, and a punctuation word can be bound by
alphanumeric characters.) The underscore character is considered to be
alphanumeric.
count w
count W
The w and W commands move the cursor forward to the start of the
next word. If a count is given, the cursor will move forward count
words.
count e
count E
The e and E commands move the cursor forward to the end of the
current word, or if it is already at the end of the word then it'll
move to the end of the following word. If a count is given, the
cursor will move forward count word ends.
NOTE: These commands are often used as the targets of the operator
commands, as in dw or de. When used this way, the difference between
them is that dw includes any whitespace after the word, but de does
not.
count b
count B
The b and B commands move the cursor backward to the start of the
current word, or if it is already at the start of the word then
it'll move to the start of the preceding word. If a count is given,
the cursor will move backward count word starts.
2.2.9 Movement commands which move by sentences or sections
.--------------.------------------------------------------------------.
| COMMAND | DESCRIPTION |
|--------------|------------------------------------------------------|
| count ( | Move backward "count" sentences |
| count ) | Move forward "count" sentences |
| count { | Move back "count" paragraphs |
| count } | Move forward "count" paragraphs |
| [ [ | Move back 1 section |
| ] ] | Move forward 1 section |
^--------------^------------------------------------------------------^
count (
count )
These commands move backward or forward to the start of a sentence.
The start of a sentence is defined to be the first non-whitespace
character in the file, or the first non-whitespace character after
the end of a sentence.
The exact definition of the end of a sentence depends on the values
of the sentenceend, sentencegap, and sentencequote options. The
default values of those options define a sentence end to be a
period, question mark, or exclamation mark, followed by either a
newline character, or two or more space characters. Any number of
double-quote characters or closing parentheses may appear between
the punctuation and the whitespace.
count {
count }
These commands move backward or forward to the start of a paragraph.
The start of a paragraph is defined to be the first blank line
encountered after a non-blank line; or a line which contains a troff
paragraph command listed in the paragraphs option's value; or the
start of a section as described below.
[[
]]
These commands move backward or forward to the start of a section.
The start of a section is defined to be '{' character in column 1 of
a line; or a troff section command listed in the value of the
sections option.
Note: There are also [key and ]key commands for recording
keystrokes. Those commands are not related to the [[ and ]] movement
commands.
2.2.10 Movement/mark commands
.--------------.------------------------------------------------------.
| COMMAND | DESCRIPTION |
|--------------|------------------------------------------------------|
| m key | Mark a line or character |
| ' key | Move to a marked line |
| ` key | Move to a marked character |
| V | Start marking lines for c d y < > or ! |
| v | Start marking characters for c d y < > or ! |
| ^V | Start marking a rectangle for c d y < > or ! |
^--------------^------------------------------------------------------^
m key
The mkey command stores the current cursor position in mark named
key, where key is any letter. The mark is not visible.
' key
` key
These commands move the cursor back to a position which was stored
via the mkey command. The `key (grave) command is a
character-movement command which positions the cursor exactly on the
marked character. The 'key (apostrophe) command is a line-movement
command which positions the cursor at the front of the line
containing the mark.
The distinction between character-movement and line-movement becomes
more significant when you're using the movement command as the
target of an operator command. For example, after an ma command and
some cursor movement, the command d'a would delete whole lines, but
the command d`a would delete only the text between the cursor and
the "a" mark.
v
V
^V
These commands start visually selecting text for use by an operator
command. The lowercase v command starts selecting characters,
uppercase V starts selecting lines, and ^V starts selecting a
rectangular area.
2.2.11 Scrolling commands
.--------------.------------------------------------------------------.
| COMMAND | DESCRIPTION |
|--------------|------------------------------------------------------|
| ^F | Move toward the bottom of the file by 1 screen full |
| ^B | Move toward the top of the file by 1 screen full |
| z key | Scroll current line to window's +top -bottom .middle |
| count ^D | Scroll forward "count" lines (default 1/2 screen) |
| count ^E | Scroll forward "count" lines (default 1 line) |
| count ^U | Scroll backward "count" lines (default 1/2 screen) |
| count ^Y | Scroll backward "count" lines (default 1 line) |
^--------------^------------------------------------------------------^
^F
This command moves forward one screen. Specifically, it locates the
line at the bottom of the window and moves it to the top of the
window. This means that for a 24-row window, ^F will generally move
forward 22 lines. The cursor is moved if necessary to keep it on the
screen.
^B
This command moves backward one screen, by moving the line at the
top of the window to the bottom. It is the opposite of the ^F
command.
z key
This command scrolls the current line to either the top (if key is
"+"), middle (if key is "." or "z"), or bottom (if key is "-") of
the window.
count ^D
count ^E
These commands scroll the window forward by count lines. If no count
is given, then ^E defaults to 1 line, and ^D defaults to the value
of the scroll option. Supplying a count to the ^D option has the
side-effect of setting the scroll option to count.
count ^U
count ^Y
These commands scroll the window backward by count lines. If no
count is given, then ^Y defaults to 1 line, and ^U defaults to the
value of the scroll option. Supplying a count to the ^U option has
the side-effect of setting the scroll option to count.
2.2.12 Window commands
.--------------.------------------------------------------------------.
| COMMAND | DESCRIPTION |
|--------------|------------------------------------------------------|
| ^W s | Split current window |
| ^W ] | Split window, then look up tag at cursor |
| ^W n | Split window, and create a new buffer |
| ^W q | Save buffer & close window, like ZZ |
| ^W c | Hide buffer & close window |
| ^W d | Toggle the display mode |
| ^W S | Toggle the sidescroll option |
| ^W j | Move down to next window |
| ^W k | Move up to previous window |
| count ^W ^W | Move to next window, or to the "count" window |
^--------------^------------------------------------------------------^
^W s
This creates a new window, showing the same buffer as the current
window. It is equivalent to the ex :split command with no arguments.
^W ]
This performs tag lookup on the word at the cursor, and then creates
a new window to show the tag definition. It is similar to the ex
:stag command.
^W n
This creates a new buffer, and then creates a new window to show
that buffer. It is similar to the ex :snew command.
^W q
This saves the buffer if it has changed, and then closes the window.
It is identical to the visual ZZ command, and similar to the ex :xit
command.
^W c
This closes the window, but it neither saves nor discards the
current buffer. The buffer continues to exist. This command is like
the ex :close command.
^W d
This toggles the windows display mode between two different modes.
If the buffer's bufdisplay option is set to "html", "man", or "tex",
then it will toggle between that mode and the syntax coloring mode.
If bufdisplay is set to a syntax-coloring mode or "hex" then it
toggles between that mode and "normal". If bufdisplay is "normal",
then this command toggles between that mode and the "hex" mode.
^W S
This toggles the wrap option off or on, causing sideways scrolling
to be alternately disabled and enabled.
^W j
^W k
count ^W ^W
These commands make other windows be current. This is the only
possible way to switch windows for some user interfaces such as the
termcap interface.
NOTE: In addition to the commands shown here, some user interfaces may support
extensions to these commands. For example, the termcap interface uses ^W+ to
increase the size of the current window, ^W- to reduce the size of the current
window, and ^W\ to make the current window as large as possible.
2.2.13 Other commands
.--------------.------------------------------------------------------.
| COMMAND | DESCRIPTION |
|--------------|------------------------------------------------------|
| " key | Select which cut buffer to use next |
| @ key | Execute the contents of a cut-buffer as VI commands |
| [ key | Start recording keystrokes into a cut-buffer |
| ] key | Stop recording keystrokes into a cut-buffer |
| : text | Run single EX cmd |
| Q | Quit to EX mode |
| K | Run keywordprg on the word at the cursor |
| Z Z | Save the file & exit |
| ^Z | Either suspend elvis, or fork a shell |
| ^G | Show file status, and the current line # |
| ^L | Redraw the screen |
| * | Go to the next error in the errlist |
| ^I | In HTML mode, move forward to next link |
| ^T | Return to source of previous :tag or ^] command. |
| ^] | If the cursor is on a tag name, go to that tag |
| ^^ | Switch to the previous file, like ":e #" |
| count # key | Increment a number |
| count & | Repeat the previous ":s//" command here |
^--------------^------------------------------------------------------^
" key
This command determines which cut buffer the next command will use.
If the next command doesn't involve a cut buffer, then this command
has no effect. If you don't use this command, then the following
command will use the anonymous cut buffer.
@ key
The @ command executes the contents of a cut buffer as a series of
vi command keystrokes. The key after the @ is the name of the cut
buffer to be executed.
[ key
] key
These commands are used for recording keystrokes into a cut-buffer.
The key is the name of the cut buffer; it must be a letter. Later,
you can replay the keystrokes via the @key command.
Note: There are also [[ and ]] commands for moving the cursor to the
start of a section. Those movement commands are unrelated to these
[key and ]key keystroke recording commands.
:
Q
This : command allows you to enter a single ex command, and then
immediately return to visual command. The Q command is similar,
except that it causes you to remain in ex mode until you give the ex
:vi command.
K
This command executes the program named in the keywordprg option,
passing it the word at the cursor. This is intended to provide an
easy way to run on-line manuals and the like.
ZZ
The ZZ command writes the current file if it has changed, and then
exits. It is equivalent to the ex :xit command.
^Z
This command will either suspend elvis, or fork a shell program.
Either way, you'll get a shell prompt. ^Z is equivalent to the :stop
ex command.
^G
The ^G command displays the status of the current file. It is
equivalent to the ex :file command with no arguments.
^L
The ^L command causes the current window to be redrawn from scratch.
This is handy when another program or line noise changes the screen
in a way that elvis can't detect & correct automatically.
*
The * command moves the cursor to the next error reported by the
compiler. It is equivalent to the ex :errlist command.
^I
The ^I command (the Tab key) moves the cursor forward to the next
hypertext link, if you're in the "html" display mode.
^]
^T
The ^] command performs tag lookup on the word at the cursor
position, and moves the cursor to the file/line where the tag is
defined. It resembles the ex :tag command. The ^T command returns
the cursor to the previous position, like :pop.
^^
After you've switched edit buffers in a window, the ^^
(Control-Carat) command switches back to the previous buffer, and
moves the cursor to its previous position within that buffer. It is
like the ex :e# command.
count # key
This command allows you add or subtract count to the number at the
cursor. If the cursor isn't on a word that looks like a number, then
the command fails. If no count is given, then 1 is assumed. If the
key is "-" then count is subtracted from the number. If the key is
"+" or "#" then count is added to the number. If the key is "=" then
the word is changed to count. Any other key causes the command to
fail.
count &
Repeat the previous :s/re/new/ command on the current line. If count
is given, then also apply it to each of the count-1 following lines
as well.
2.3 Visual Commands, sorted by their ASCII code
.--------------.------------------------------------------------------.
| COMMAND | DESCRIPTION |
|--------------|------------------------------------------------------|
| NUL | (undefined) |
| ^A | Search for next occurrence of word at cursor |
| ^B | Move toward the top of the file by 1 screen full |
| ^C | (undefined; may abort a time-consuming command) |
| count ^D | Scroll forward "count" lines (default 1/2 screen) |
| count ^E | Scroll forward "count" lines (default 1 line) |
| ^F | Move toward the bottom of the file by 1 screen full |
| ^G | Show file status, and the current line # |
| count ^H | Move left |
| ^I | (Tab) In "html" display mode, move to next hyperlink |
| count ^J | Move down |
| ^K | (undefined) |
| ^L | Redraw the screen |
| count ^M | Move to the front of the next line |
| count ^N | Move down |
| ^O | ignored, to simplify implementation of "visual" map |
| count ^P | Move up |
| ^Q | (undefined; may resume stopped output) |
| count ^R | Redo commands which were undone by the u command |
| ^S | (undefined; may stop output) |
| ^T | Return to source of previous :tag or ^] command. |
| count ^U | Scroll backward "count" lines (default 1/2 screen) |
| ^V | Start marking a rectangle for c d y < > or ! |
| count ^W ^W | Move to next window, or to the "count" window |
| ^W S | Toggle the sidescroll option |
| ^W ] | Split window, then look up tag at cursor |
| ^W c | Hide buffer & close window |
| ^W d | Toggle the display mode |
| ^W j | Move down to next window |
| ^W k | Move up to previous window |
| ^W n | Split window, and create a new buffer |
| ^W q | Save buffer & close window, like ZZ |
| ^W s | Split current window |
| count ^X | Move to column "count" (defaulting to the right edge)|
| count ^Y | Scroll backward "count" lines (default 1 line) |
| ^Z | Either suspend elvis, or fork a shell |
| ^[ | (Escape) Cancels a partially-entered command |
| ^\ | (undefined; may cause core dump) |
| ^] | If the cursor is on a tag name, go to that tag |
| ^^ | Switch to the previous file, like ":e #" |
| ^_ | (undefined) |
| count Space | Move right |
| ! mv | Run selected lines thru an external filter program |
| " key | Select which cut buffer to use next |
| count # key | Increment a number |
| $ | Move to the rear of the current line |
| count % | Move to matching (){}[] or to a given % of file |
| count & | Repeat the previous ":s//" command here |
| ' key | Move to a marked line |
| count ( | Move backward "count" sentences |
| count ) | Move forward "count" sentences |
| * | Go to the next error in the errlist |
| count + | Move to the front of the next line |
| count , | Repeat the previous [fFtT] but in the other direction|
| count - | Move to the front of the preceding line |
| count . | Repeat the previous "edit" command |
| / text | Search forward for a given regular expression |
| 0 | If not part of count, move to 1st char of this line |
| 1 | Part of a count argument |
| 2 | Part of a count argument |
| 3 | Part of a count argument |
| 4 | Part of a count argument |
| 5 | Part of a count argument |
| 6 | Part of a count argument |
| 7 | Part of a count argument |
| 8 | Part of a count argument |
| 9 | Part of a count argument |
| : text | Run single EX cmd |
| count ; | Repeat the previous [fFtT] cmd |
| < mv | Shift text left |
| = mv | Reformat |
| > mv | Shift text right |
| ? text | Search backward for a given regular expression |
| @ key | Execute the contents of a cut-buffer as VI commands |
| count A inp | Append at end of the line |
| count B | Move back Word |
| C inp | Change text from the cursor to the end of the line |
| D | Delete text from the cursor to the end of the line |
| count E | Move end of Word |
| count F key | Move leftward to a given character |
| count G | Move to line #"count" (default is the bottom line) |
| count H | Move to home row (the line at the top of the screen) |
| count I inp | Insert at the front of the line (after indents) |
| count J | Join lines, to form one big line |
| K | Run keywordprg on the word at the cursor |
| count L | Move to last row (i.e., line at bottom of window) |
| M | Move to middle row |
| N | Repeat previous search, but in the opposite direction|
| count O inp | Open up a new line above the current line |
| P | Paste text before the cursor |
| Q | Quit to EX mode |
| R inp | Overtype |
| count S inp | Change lines, like "count" cc |
| count T key | Move leftward *almost* to a given character |
| U | Undo all recent changes to the current line |
| V | Start marking lines for c d y < > or ! |
| count W | Move forward "count" Words |
| count X | Delete the character(s) to the left of the cursor |
| count Y | Yank text line(s) (copy them into a cut buffer) |
| Z Z | Save the file & exit |
| [ [ | Move back 1 section |
| [ key | Start recording keystrokes into a cut-buffer |
| \ | (undefined) |
| ] ] | Move forward 1 section |
| ] key | Stop recording keystrokes into a cut-buffer |
| ^ | Move to the front of the current line (after indent) |
| count _ | (the underscore character) Move to the current line |
| ` key | Move to a marked character |
| count a inp | Insert text after the cursor |
| count b | Move back "count" words |
| c mv | Change text |
| d mv | Delete text |
| count e | Move forward to the end of the current word |
| count f key | Move rightward to a given character |
| g | (undefined) |
| count h | Move left |
| count i inp | Insert text at the cursor |
| count j | Move down |
| count k | Move up |
| count l | Move right |
| m key | Mark a line or character |
| n | Repeat the previous search |
| count o inp | Open a new line below the current line |
| p | Paste text after the cursor |
| q | (undefined) |
| count r key | Replace "count" chars by a given character |
| count s inp | Replace characters, like "count" cl |
| count t key | Move rightward *almost* to a given character |
| count u | Undo the previous edit command |
| v | Start marking characters for c d y < > or ! |
| count w | Move forward "count" words |
| count x | Delete the character that the cursor's on |
| y mv | Yank text (copy it into a cut buffer) |
| z key | Scroll current line to window's +top -bottom .middle |
| count { | Move back "count" paragraphs |
| count | | Move to column "count" (defaulting to column 1) |
| count } | Move forward "count" paragraphs |
| count ~ | Switch a character between uppercase & lowercase |
| DEL | (undefined) |
^--------------^------------------------------------------------------^
ΓòÉΓòÉΓòÉ 1.3. Elvis 2.1 Input Mode ΓòÉΓòÉΓòÉ
3. INPUT MODE
You can't type text into your file directly from visual command mode. Instead,
you must first give a command which will put you into input mode. The commands
to do this are A, C, I, O, R, S, a, i, o, and s.
The S, s, C, and c commands temporarily place a $ at the end of the text that
they are going to change.
In input mode, all keystrokes are inserted into the text at the cursor's
position, except for the following:
.-----.-----------------------------------------------------.
| KEY | FUNCTION |
|-----|-----------------------------------------------------|
| ^@ | (Nul) Insert a copy of last input text, then exit |
| ^A | Insert a copy of the last input text |
| ^D | Delete one indent character |
| ^H | (Backspace) Erase the character before the cursor |
| ^I | (Tab) Depends on the inputtab option |
| ^K | Compose the next two characters as a digraph |
| ^M | (Enter) Insert a newline (^J, linefeed) |
| ^O | Read & run a single vi command, then resume input |
| ^P | Insert the contents of the cut buffer |
| ^R | Redraw the window, like ^L |
| ^T | Insert an indent character |
| ^U | Backspace to the beginning of the line |
| ^V | Insert the following keystroke, even if special |
| ^W | Backspace to the beginning of the current word |
| ^X | Use the next two keystrokes as hex digits of 1 byte |
| ^[ | (ESCape) Exit from input mode, back to command mode |
^-----^-----------------------------------------------------^
Also, on some systems, ^S may stop output, ^Q may restart output, and ^C may
interrupt execution.
The R visual command puts you in overtype mode, which is a slightly different
form of input mode. In overtype mode, each time you insert a character, one of
the old characters is deleted from the file.
3.1 Arrow keys in Input Mode
The arrow keys can be used to move the cursor in input mode. (This is an
extension; the real Vi doesn't support arrow keys in input mode.) The PgUp,
PgDn, Home, and End keys work in input mode, too. The Delete key deletes a
single character in input mode. The Insert key toggles between input mode and
replace mode.
3.2 Digraphs
Elvis supports digraphs as a way to enter non-ASCII characters. A digraph is a
character which is composed of two other characters. For example, an apostrophe
and the letter i could be defined as a digraph which is to be stored and
displayed as an accented i.
There is no single standard for extended ASCII character sets, so elvis uses a
configurable digraph table. You can view or edit the digraph table via the
:digraph! ex command.
When inputting text, there are two ways you can type in a digraph. The first
way is to type the first character, then hit backspace, and then type the
second character. Elvis will then substitute the non-ASCII character in their
place. Digraphs entered this way will not be recognized unless you've turned on
the digraph option.
The other way is to type ^K followed by the two characters, without a
backspace. This method works regardless of the value of the digraph option.
3.2.1 Latin-1 digraphs
The most common standard for non-ASCII symbol sets is called Latin-1 (or ISO
8859/1, or ECMA-94 -- these are all the same). This symbol set is used by
X-windows and graphical Windows95 programs, but not MS-DOS.
Elvis is distributed with a file named lib/elvis.lat which contains the
:digraph commands necessary to set up the digraph table appropriately for
Latin-1. Most of these digraphs are fairly straight-forward. For example, to
generate an accented "i", type ^K, i, and an apostrophe character. You can list
all of the digraphs via the command ":dig!"
The default lib/elvis.ini file reads the lib/elvis.lat file automatically. This
is very handy if your system really does use Latin-1, but if it doesn't then
you'll probably want to disable the automatic loading. You can disable it by
editing the lib/elvis.ini file, searching for the "source!
(elvispath("elvis.lat"))" line, and inserting a double-quote character at the
start of that line.
3.2.2 PC-8 digraphs
MS-DOS doesn't use Latin-1, and neither do OS/2 or Win32 console applications,
such as elvis. So for Microsoft operating systems, elvis loads its digraph
table via a file named lib/elvis.pc8. This sets up the digraph table
appropriately for the 437 code page, which is Microsoft's default. If you use a
different code page, you may wish to edit lib/elvis.pc8.
3.3 Abbreviations
Elvis can expand abbreviations for you. You define an abbreviation with the
:abbr command, and then whenever you type in the abbreviated form while in
input mode, Elvis will immediately replace it with the long form. COBOL
programmers should find this useful. :-)
Elvis doesn't perform the substitution until you type a non-alphanumeric
character to mark the end of the word. If you type a control-V before that
non-alphanumeric character, then Elvis will not perform the substitution.
Elvis also requires the abbreviated text to either appear at the start of a
line, or immediately after a non-alphanumeric character. This prevents elvis
from trying to treat the ends of words as abbreviations. This is necessary so
that if you set up an abbreviation which maps "ed" to "editor", elvis won't
mangle "confused" into "confuseditor".
Abbreviations are allowed to contain punctuation characters. For example, TeX
users might find it useful to map "\b" to "\begin".
3.4 Auto-Indent
With the autoindent option turned on, Elvis will automatically insert leading
whitespace at the beginning of each new line that you type in. The leading
whitespace is copied from the preceding line.
To add more leading whitespace, type control-T. To remove some whitespace, type
control-D.
If you ":set noautotab", then the whitespace generated by control-T will always
consist of spaces -- never tabs. Some people seem to prefer this.
Elvis' autoindent mode isn't 100% compatible with vi's. In Elvis, 0^D and ^^D
don't work, ^U can wipe out all indentation, and sometimes Elvis will use a
different amount of indentation than vi would.
ΓòÉΓòÉΓòÉ 1.4. Elvis 2.1 Ex Mode ΓòÉΓòÉΓòÉ
4. EX COMMAND MODE
Ex is an editing mode in which elvis acts like a line editor. This means that
you type in a command line, and when the line is complete elvis executes it on
the current text buffer. I.e., in ex each line (or group of lines) is a
command, as opposed to vi where each character (or group of characters) is a
command.
Typically, ex commands are used to do perform complex actions such as global
search & replace, or actions which require an argument such as writing the edit
buffer out to a different file.
Ex is also used as the configuration language for elvis; configuration scripts
such as elvis.ini, .exrc (or elvis.rc), and elvis.arf contain a series of ex
commands.
You can switch freely between vi and ex. If you're in vi mode, you can enter a
single ex command line via the visual : command, or more permanently switch via
the visual Q command. If you're in ex mode, you can switch to vi mode via ex's
:vi command.
Normally elvis will start in vi mode, but you can force it to start in ex mode
by supplying a -e command line flag. On UNIX systems, you can link elvis to a
name which ends with "x" to achieve the same effect.
The remainder of this section discusses how to enter lines, the general syntax
of an ex command line, and the specific commands which elvis supports.
4.1 Entering lines
In elvis, when you're typing in an ex command line you're really inputting text
into a buffer named "Elvis ex history". All of the usual input mode commands
are available, including Backspace to erase the previous character, Control-W
to erase the previous word, and so on.
Any previously entered lines will still be in the "Elvis ex history" buffer,
and you can use the arrow keys to move back and edit earlier commands. You can
even use the Control-O input-mode command with the ?regexp visual command, to
search for an earlier command line.
When you hit the Enter key on a line in the "Elvis ex history" buffer, elvis
sends that line to the ex command parser, which is described in the next
section.
4.1.1 An example
Suppose you enter the command...
:e ~/proj1/src/header.h
...and then realize that you really wanted "header2.h" instead of "header.h".
You simplest way to get "header2.h" is to...
1. Hit the : key to start a new ex command line.
2. Hit the Up arrow key, or ^O k to move back to the preceding command
line (which was ":e ~/proj1/src/header.h"). ^O k works because ^O reads
and executes one vi command, and the k vi command moves the cursor back
one line. The Up arrow key works because it is mapped to "visual k",
which does exactly the same thing as ^O k.
3. Hit the Left arrow key twice, or ^O 2 h, to move the cursor back to the
'.' character in "header.h".
4. Hit 2 to insert a '2' before the '.' character. At this point, the
line should look like ":e ~/proj1/src/header2.h".
5. Hit Enter to submit the revised command line.
Or suppose you really wanted "footer2.h" instead of "header2.h". This is a
little trickier because you want to delete characters in the middle of the
command line, before inserting the correct text. The simplest way to do this
is move the cursor to a point just after the last character that you want to
delete, and then backspace over them. The steps are:
1. Hit the : key to start a new ex command line.
2. Hit the Up arrow key or ^O k repeatedly to move back to the ":e
~/proj1/src/header2.h"command line.
3. Hit the Left arrow key five times, or ^O 5 h, to move the cursor back
to the last 'e' character in "header2.h".
4. Hit the Backspace key four times to delete the word "head". It will
still show on the screen, but elvis will know that it has been deleted.
This is the same sort of behavior that elvis (and vi) exhibits when you
backspace over newly entered text in input mode.
5. Type f o o t to insert "foot" where "head" used to be. At this point,
the line should look like ":e ~/proj1/src/footer2.h".
6. Hit Enter to submit the revised command line.
4.1.2 The TAB key
The Tab key has a special function when you're inputting text into the "Elvis
ex history" buffer. It is used for name completion. (Exception: Under MS-DOS,
this feature is disabled in order to reduce the size of the program, so it
will fit in the lower 640K.)
Name completion works like this: The preceding word is assumed to be a partial
name for an ex command, an option, a tag, or a file. The type of name is
determined by the context in which it appears -- commands appear at the start
of an ex command line, and the others can only occur after certain, specific
command names. Elvis searches for all matches of the appropriate type.
If there are multiple matches, then elvis fills in as many characters of the
name as possible, and then stops; or, if no additional characters are implied
by the matching names, then elvis lists all matching names and redisplays the
command line. If there is a single match, then elvis completes the name and
appends a tab character or some other appropriate character. If there are no
matches, then elvis simply inserts a tab character.
Also, if while entering a :set command you hit the Tab key immediately after
"option=" then elvis will insert the current value of the option. You can then
edit that value before submitting the command line.
I tried to make elvis smart enough that the Tab key will only attempt
file/command/option completion in contexts where it makes sense to do so, but
that code might not be 100% correct. You can bypass the completion by typing a
Control-V before the Tab key. You can also disable name completion altogether
by setting the "Elvis ex history" buffer's inputtab option to "tab", via the
following command:
:(Elvis ex history)set inputtab=tab
By default, elvis ignores binary files when performing filename completion.
The completebinary option can be used to make elvis include binary files.
That's a global option (unlike inputtab which is associated with a specific
buffer), so you don't need to specify the buffer name; a simple :set
completebinary will set it.
4.2 Syntax and Addressing
In general, ex command lines can begin with an optional window id. This may be
followed by an optional buffer id, and then 0, 1, or 2 line addresses,
followed by a command name, and perhaps some arguments after that (depending
on the command name).
A window ID is typed in as a decimal number followed by a colon character. If
you don't supply a window ID (and you almost never will) then it defaults to
the window where you typed in the command line. The :buffer command lists the
buffers, and shows which one is being edited in which window. Also, the
windowid option indicates the ID of the current window.
A buffer ID is given by typing an opening parenthesis, the name of the buffer,
and a closing parenthesis. For user buffers, the name of the buffer is usually
identical to the name of the file that it corresponds to. For example, a file
named ~/.Xdefaults would be loaded into a buffer which could be addressed as
(~/.Xdefaults). Elvis also assigns numbers to user buffers, which may be more
convenient to type since numbers are generally shorter than names. If
~/.Xdefaults is the first file you've edited since starting elvis, then its
buffer could be addressed as (1). The :buffer command shows the number for
each user buffer.
Elvis also has several internal buffers, all of which have names that start
with "Elvis ", such as (Elvis cut buffer x) and (Elvis error list). The
:buffer! command (with a ! suffix) will list them all. For the sake of
brevity, elvis allows you to refer to cut buffers as ("x). Similarly, the
other internal buffers can be referred to via a " character and the initial
letter in each word of the full name, such as ("Eel) for (Elvis error list).
Commands which don't access the text, such as ":quit", don't allow any line
addresses. Other commands, such as ":mark", only allow a single line address.
Most commands, though, allow two line addresses; the command is applied to all
lines between the two specified lines, inclusively. The tables below indicate
how many line addresses each command allows.
Line addresses are always optional. The first line address of most commands
usually defaults to the current line. The second line address usually defaults
to be the same as the first line address. Exceptions are :write, :lpr,
:global, and :vglobal, which act on all lines of the file by default, and
:!, which acts on no lines by default.
If you use the visual V command to mark a range of lines, and then use the
visual : command to execute a single ex command, then the default range
affected by the ex command will be the visibly marked text.
Line addresses consist of an absolute part and a relative part. The absolute
part of a line specifier may be either an explicit line number, a mark, a dot
to denote the current line, a dollar sign to denote the last line of the file,
or a forward or backward search. An explicit line number is simply a decimal
number, expressed as a string of digits. A mark is typed in as an apostrophe
followed by a letter. Marks must be set before they can be used. You can set a
mark in visual command mode by typing "m" and a letter, or you can set it in
ex command mode via the "mark" command. A forward search is typed in as a
regular expression surrounded by slash characters; searching begins at the
default line. A backward search is typed in as a regular expression
surrounded by question marks; searching begins at the line before the default
line.
If you omit the absolute part, then the default line is used.
The relative part of a line specifier is typed as a + or - character followed
by a decimal number. The number is added to or subtracted from the absolute
part of the line specifier to produce the final line number.
As a special case, the % character may be used to specify all lines of the
file. It is roughly equivalent to saying 1,$. This can be a handy shortcut.
Here are some addressing examples, using the :p command:
COMMAND | ACTION
-------------|-------------------------------------------
:p | print the current line
:37p | print line 37
:'gp | print the line which contains mark g
:/foo/p | print the next line that contains "foo"
:$p | print the last line of the buffer
:20,30p | print lines 20 through 30
:1,$p | print all lines of the buffer
:%p | print all lines of the buffer
:(zot)%p | print all lines of the "zot" buffer
:/foo/-2,+4p | print 5 lines around the next "foo"
The optional addresses are followed by the command name. Command names may be
abbreviated. In the sections that follow, the command's full name is given
with the optional part enclosed in square brackets.
Some commands allow a '!' character to appear immediately after the command
name. The significance of the '!' varies from one command to another, but
typically it forces the command to do something dangerous that it would
ordinarily refuse to do. For example, :w file refuses to overwrite an existing
file, but :w! file will do it.
Many commands allow (or even require) additional arguments. The descriptions
below list which arguments each command accepts with optional commands denoted
by square brackets. The most common argument types are:
/regexp/
This is a regular expression. You can use any punctuation character
to delimit it, but the '/' character is the most commonly used.
/regexp/newtext/
This is a regular expression followed by replacement text.
count
This is a number - a string of digits. Generally, it is used as the
repeat count for certain commands.
cutbuf
This is the name of a cut buffer - a single letter. Elvis also
allows (but does not require) a quote character before the letter.
excmds
This is another ex command, or list of ex commands. Traditionally,
the whole list of commands had to appear on the same line, delimited
by '|' characters. Elvis has the added versatility of allowing a '{'
character on the first line, each command on a separate following
line, and then '}' on a line by itself to mark the end of the ex
command list.
lhs
This is string of characters. If whitespace characters are to be
included in it, then they must be quoted by embedding a ^V character
before them.
line
This is a line address, as described earlier.
mark
This is the name of a mark - a single lowercase letter. Elvis allows
(but does not require) an apostrophe before the letter.
rhs
This is a string of characters. If it begins with a whitespace
character, then that character must be quoted by embedding a ^V
character in the command line before it. Other whitespace characters
in the string do not need to be quoted.
expr
This is an arithmetic expression using the normal syntax.
shellcmd
This is a command line which is passed to the system's command
interpreter. Within the command line, the following character
substitutions take place, unless preceded by a backslash:
.-----------.----------------------------.
| CHARACTER | REPLACED BY |
|-----------|----------------------------|
| % | Name of current file |
| # | Name of alternate file |
| #n | Name of file whose bufid=n |
| ! | Previous command line |
| \@ | Word at cursor location |
^-----------^----------------------------^
Note that the \@ substitution requires a backslash. This quirk
exists for the sake of backward compatibility - the real vi doesn't
perform any substitutions for just plain @.
file or files
This is one or more file name, or a "wildcard" pattern which matches
the names of zero or more files. File names are subjected to three
levels of processing. First, leading ~ characters and certain other
characters are replaced with text, as follows:
.---------.------------------------------------------------.
| SYMBOL | REPLACED BY |
|---------|------------------------------------------------|
| ~user | (Unix only) Replaced by home directory of user |
| ~+ | Replaced by current working directory |
| ~- | Replaced by previous directory (previousdir) |
| ~ | Replaced by home directory (home) |
| % | Replaced by the name of the current file |
| # | Replaced by the name of the alternate file |
| #n | Replaced by the filename of buffer with bufid=n|
| (space) | Delimits one file name from another |
^---------^------------------------------------------------^
The second stage of processing evaluates each name using the simpler
expression syntax. This basically means that expressions of the form
$NAME will be replaced with the value of the environment variable
named NAME. Also, you can use parentheses around option names or
more complex expressions. For example, if the user option f contains
the name of a file, then you could say ":e (f)" to edit that file.
In either of the first two stages, backslashes may be used to
prevent the special symbols from having their usual meaning; they'll
be treated as normal text instead. In particular, a backslash-space
sequence can be used to give a filename which includes spaces; e.g.,
to edit "C:\Program Files\foo" you would type ":e C:\Program\
Files\foo". Note that backslashes which are followed by a normal
character are simply retained as normal characters, so you rarely
need to type a double-backslash when your file name needs only a
single backslash.
The third stage of processing checks for "wildcard" characters in
the name, and if there are any then the whole name is replaced by
the name of each matching file. The exact list of supported
wildcards will vary from one operating system to another, but the
following are typical:
.--------.----------------------------------------------.
| SYMBOL | MATCHES |
|--------|----------------------------------------------|
| * | Any string of characters, of any length |
| ? | Any single character |
| [a-z] | (Unix only) Any single character from A to Z |
^--------^----------------------------------------------^
In most operating systems, wildcards are only recognized when they
occur in the last file name part of a longer pathname. In other
words, you can use wildcards for file names, but not in directory
names leading up to file names.
Traditionally, vi has used the Unix shell to expand wildcards.
However, this interferes with the use of spaces in file names, isn't
easily portable to non-Unix operating systems, and is a potential
security hole. So elvis performs all wildcard expansion itself. The
only disadvantage of this is that you loose other shell notations
such as `command` and {alt1,alt2}.
Most commands can be followed by a '|' character and another ex command.
Others can't. In particular, any command which takes a excmd or shellcmd
argument doesn't treat '|' as a command delimiter.
If a command does treat '|' as a delimiter, and you want '|' to be treated as
part of a command argument, then you'll need to quote the '|' character by
preceding it with a backslash or ^V, depending on the command. (Sadly,
different commands require different quote characters.)
4.3 Ex Commands, Grouped by Function
4.3.1 The help command itself
4.3.2 Editing commands
4.3.3 Global edit commands
4.3.4 Displaying text
4.3.5 Tags
4.3.6 File I/O commands
4.3.7 The args list, and selecting a file to edit
4.3.8 Quitting
4.3.9 Scripts and macros
4.3.10 Working with a compiler
4.3.11 Built-in calculator
4.3.12 Buffer commands
4.3.13 Window commands
4.3.14 Configuration
4.3.15 Miscellaneous
4.3.1 The help command itself
.-------.-------------------.-----------------------------------.
|ADDRESS| COMMAND | ARGUMENTS |
|-------|-------------------|-----------------------------------|
| | h[elp] | topic |
^-------^-------------------^-----------------------------------^
The :help command loads and displays a help file for a given topic. There are
several help files, covering a wide variety of topics.
Elvis looks at the topic you supply, and tries to determine whether it is an
ex command name, vi keystroke, option name, or something else. Based on this,
it generates a hypertext link to the topic in the appropriate help file, and
shows the topic in a separate window. Elvis uses the following rules to
convert your requested topic into a hypertext reference:
.---------------.-------------------------------------------.
| COMMAND | ELVIS' INTERPRETATION |
|---------------|-------------------------------------------|
| :help | With no topic, elvis loads the table of |
| | contents. This has hypertext links that |
| | can lead you to any other topic. |
| :help ex | Elvis loads the chapter describing ex |
| | commands. |
| :help vi | Elvis loads the chapter describing vi |
| | commands. |
| :help set XXX | If XXX is an option name, elvis will show |
| | the description of that option; else it |
| | will list groups of all options. |
| :help :XXX | If XXX is an ex command name, elvis will |
| | show its description; else elvis will |
| | list groups of all ex commands. |
| :help XXX | If XXX appears to be a keystroke then |
| | elvis will assume it is meant to be a |
| | vi command and will show the command's |
| | description. Else if it is an option |
| | name elvis will show that. Else if it |
| | is an ex command, elvis will show that. |
| | Else elvis will show this description |
| | of the :help command itself. |
^---------------^-------------------------------------------^
Although this chart only mentions sections on ex commands, vi commands, and
options, there are many others which are only accessible via the table of
contents shown by ":help" with no arguments.
All of these help files are HTML documents. Elvis' standard HTML editing
facilities are available while you're viewing the help text. Some of the
highlights of this are:
To close this help window, type ZQ. Actually, this works for all
windows. (You must hold the Shift key as you type ZQ, because
lowercase zq does something else entirely: nothing!)
Any underlined text is a hypertext reference. This means that you
can move the cursor onto it, and hit the Enter key, and the cursor
will move to a topic describing the underlined text.
To return to your original position after following a hypertext
reference, hit ^T (Control-T).
The Tab key moves the cursor forward to the next hypertext reference.
You can use elvis to print the document via the :lpr command. This assumes
you have set the printing options correctly.
4.3.2 Editing commands
.-------.-------------------.-----------------------------------.
|ADDRESS| COMMAND | ARGUMENTS |
|-------|-------------------|-----------------------------------|
| line | a[ppend][!] | [text] |
| line | i[nsert][!] | [text] |
| range | c[hange][!] | [count] [text] |
| range | d[elete] | [cutbuf] [count] |
| range | y[ank] | [cutbuf] [count] |
| line | pu[t] | [cutbuf] |
| range | co[py] | line |
| range | m[ove] | line |
| range | t[o] | line |
| range | ! | shellcmd |
| range | > | |
| range | < | |
| range | j[oin][!] | |
| | u[ndo] | [count] |
| | red[o] | [count] |
^-------^-------------------^-----------------------------------^
The :append command inserts text after the current line. If no new text is
supplied on the command line, then elvis will wait for you to type in text;
you can then mark the end of the new text by typing a "." (period) on a line
by itself. In the real vi, adding a '!' suffix temporarily toggles the
autoindent option, but elvis just ignores the '!'.
The :insert command inserts text before the current line. Other than that, it
is identical to the :append command. In the real vi, adding a '!' suffix
temporarily toggles the autoindent option, but elvis just ignores the '!'.
The :change command deletes old text lines (copying them into the anonymous
cut buffer) and then waits for you to enter new text to replace it. You can
then mark the end of the new text by typing a "." (period) on a line by
itself. In the real vi, adding a '!' suffix temporarily toggles the autoindent
option, but elvis just ignores the '!'.
The :delete command copies text into a cut buffer, and then deletes it from
the edit buffer. The :yank command copies text into a cut buffer but leaves
the edit buffer unchanged.
The :put command "pastes" text from a cut buffer back into the edit buffer.
The cut buffer's contents are inserted after the addressed line. If you want
to insert before the first line, you can use address 0 like this:
:0put
The :copy and :to commands are identical. They both make a copy of a portion
of an edit buffer, and insert that copy at a specific point. The destination
line can be specified with an optional buffer name and the full address syntax
as described in section 4.2. Consequently, you can use this command to copy
part of one edit buffer into another edit buffer. The following example copies
an 11-line window from the current buffer onto the end of a buffer named
"otherbuf"
:-5,+5t(otherbuf)$
The :move command resembles :copy except that :move deletes the original text.
The :! command allows you to send parts of your edit buffer though some
external "filter" program. The output of the program then replaces the
original text. For example, this following will sort lines 1 through 10 using
the "sort" program.
:1,10!sort
If you use the :! command without any line addresses, then elvis will simply
execute the program and display its output. This is only guaranteed to work
correctly for non-interactive programs; to execute an interactive program you
should use the :shell command.
The :< and :> commands adjust the indentation on the addressed lines. The :<
command decreases the leading whitespace by the number of spaces indicated in
the shiftwidth option, and :> does the reverse. You can use multiple < or >
characters in a single command to increase the shift amount; for example, :>>>
shifts text by triple the shiftwidth amount. Normally elvis' versions of these
commands will leave blank lines unchanged, but if you append a '!' (as in :>!)
then the command will affect blank lines in addition to other lines.
The :join command joins multiple lines together so they form one long line.
Normally it will intelligently decide how much whitespace it should place
between lines, depending on the sentenceend, sentencegap, and sentencequote
options. When invoked with a '!' suffix (as in :join!), it joins the lines
without doing fancy things to whitespace.
The :undo command undoes recent changes. The number of undoable changes is
controllable on a buffer-by-buffer basis, via the undolevels option. The :redo
command undoes an undo.
4.3.3 Global edit commands
.-------.-------------------.-----------------------------------.
|ADDRESS| COMMAND | ARGUMENTS |
|-------|-------------------|-----------------------------------|
| range | g[lobal][!] | /regexp/ excmds |
| range | v[global][!] | /regexp/ excmds |
| range | s[ubstitute] | /regexp/text/[g|.n][x][c][p|l|#] |
| range | & | [g|.n][p|l|#][x][c] |
| range | ~ | [g|.n][p|l|#][x][c] |
^-------^-------------------^-----------------------------------^
The :global command searches for lines which contain the /regexp/ and
executes the given excmds for each matching line. The :vglobal command
executes the excmds for each line which does not match the /regexp/.
In script files, you can supply multiple command lines to a single :global or
:vglobal by placing a '{' character on the :global/:vglobal line, following
that with any number of command lines, and then finally a '}' character on a
line by itself to mark the end. This notation doesn't allow nesting; you can't
use {...} inside a larger {...} command list. (Hopefully this limitation will
be lifted soon.)
The :substitute command searches for the /regexp/ in each line, and replaces
the matching text with newtext. The interpretation of newtext is described in
section 5.2
The newtext can be followed by a g flag to replace all instances in each line.
Without the g flag, only the first match within each line is changed (unless
the gdefault option is set). To replace some other instance in each line, give
a decimal point followed by the instance number, such as .3 to replace the
third instance of matching text in each line.
You can also supply a p flag. This causes each affected line to be printed
(like :p), after all substitutions have been made to that line. Similarly, l
lists it (like :l), and #prints it with a line number (like :nu or :#).
You can also make elvis ask for confirmation before each substitution by
appending a c flag. The :s command will locate the first match and then exit
immediately, but it will leave the window in an unusual input state in which y
performs a substitution and then moves on to the next match, n does not
perform the substitution but still moves to the next match, and Esc cancels
the operation. Most other keys act like y in this mode.
Elvis supports a special x flag. Instead of performing each substitution,
elvis will execute the final replacement text as an ex command line. This is
used in the implementation of modelines, like this:
1,5 s/ex:\(.*\):/\1/x
$-4,$ s/ex:\(.*\):/\1/x
The :& and :~ commands both repeat the previous :substitute command,
discarding any previous flags. The difference between them is that :& uses the
regular expression from the previous :s command, but :~ uses the most recent
regular expression from any context.
4.3.4 Displaying text
.-------.-------------------.-----------------------------------.
|ADDRESS| COMMAND | ARGUMENTS |
|-------|-------------------|-----------------------------------|
| range | p[rint] | [count] |
| range | l[ist] | [count] |
| range | nu[mber] | [count] |
| range | # | [count] |
| line | z | [spec] |
| range | = | |
^-------^-------------------^-----------------------------------^
The :print command displays lines from the edit buffer. It displays them the
normal way -- with tabs expanded and so on.
The :list command also displays lines, but it tries to make all non-printing
characters visible, and it marks the end of each line with a '$' character.
The :number and :# commands are identical to each other. They both display
lines the normal way except that each line is preceded by its line number.
The :z command shows a "window" of lines surrounding the current line. The
default size of the "window" is taken from the window option. If a line
address is supplied, then it becomes the current line before this command is
executed. The spec can be one of the following characters; the default is z+.
.------.-----------------------------------------------------.
| SPEC | OUTPUT STYLE |
|------|-----------------------------------------------------|
| - | Place the current line at the bottom of the window. |
|------|-----------------------------------------------------|
| + | Place the current line at the top of the window. |
| | Upon completion of this command, the last line |
| | output will become the current line. |
|------|-----------------------------------------------------|
| ^ | Jump back 2 windows' worth of lines, and then do |
| | the equivalent of z+. Note that z+ is like paging |
| | forward and z^ is like paging backward. |
|------|-----------------------------------------------------|
| . | Place the current line in the middle of the window. |
| | Upon completion of this command, the last line |
| | output will become the current line. |
|------|-----------------------------------------------------|
| = | Place the current line in the middle of the window, |
| | and surround it with lines containing hyphens. |
^------^-----------------------------------------------------^
The := command displays the line number of the current line, or the addressed
line if given one address. If given a range of addresses, it tells you the
line numbers of the two endpoints and the total number of lines in the range.
4.3.5 Tags
.-------.-------------------.-----------------------------------.
|ADDRESS| COMMAND | ARGUMENTS |
|-------|-------------------|-----------------------------------|
| | ta[g][!] | [tag] |
| | stac[k] | |
| | po[p][!] | |
| | br[owse][!] | restrictions |
^-------^-------------------^-----------------------------------^
Tags provide a way to associate names with certain places within certain
files. Typically, you will run the ctags program to create a file named "tags"
which describes the location of each function and macro used in the source
code for your project. The tag names are the same as the function names, in
this case.
In HTML mode, elvis uses the tags commands to follow hypertext links, but
we'll generally ignore that in the following discussions.
The :tag command performs tag lookup. It reads the "tags" file to locate the
named tag. It then loads the source file where that tag is defined, and moves
the cursor to the specific point within that buffer where the tag is defined.
Elvis' implementation of :tag also allows you to give extra restrictions and
hints. There is also a :stag command which creates a new window and moves its
cursor to the tag's definition point.
The :browse command extracts selected tags from the tags file, constructs an
HTML document listing those tags (with hypertext links to their definition
points inside your source code) and displays it in the current window. There
is also a :sbrowse command which displays the same list in a new window. If
invoked with no args, they browse all tags in the current file. If invoked
with a '!' suffix, they browse all tags. See chapter 14. Tags for a full
description of restrictions and hints, and browsing.
Before moving the cursor, elvis will save the old cursor position on a stack.
You can use the :stack command to display the contents of that stack. Each
window has an independent stack.
The :pop command pops a cursor position off the stack, restoring the cursor to
its previous position. When you're browsing though source code, you will
typically use :tag to go deeper into the call tree, and :pop to come back out
again.
In HTML mode, these all work the same except that :tag expects to be given an
URL instead of a tag name. URLs don't depend on having a "tags" file, so the
"tags" file is ignored when in HTML mode. Elvis doesn't support any network
protocols, so its URLs can only consist of a file name and/or a #label. The
following example would move the cursor to the start of this section:
:tag elvisopt.html#TAGS
4.3.6 File I/O commands
.-------.-------------------.-----------------------------------.
|ADDRESS| COMMAND | ARGUMENTS |
|-------|-------------------|-----------------------------------|
| line | r[ead] | file | !shellcmd |
| range | w[rite][!] | [file | >>file | !shellcmd] |
| range | lp[r][!] | [file | >>file | !shellcmd] |
^-------^-------------------^-----------------------------------^
The :read command reads a file or external program, and inserts the new text
into the edit buffer after the addressed line. If you don't explicitly give a
line address, then the text will be inserted after the current line. To insert
the file's contents into the top of the buffer ( before line 1), you should
specify line 0. For example, to insert the contents of "foo.txt" before line
1, you would give the command...
:0 read foo.txt
The :write command writes either the entire edit buffer (if no address range
is given) or a part of it (if a range is given) out to either a file or an
external filter program. If you don't specify the output file or external
command, then elvis will assume it should write to the file that the buffer
was originally loaded from.
Elvis will normally prevent you from overwriting existing files. (The exact
details of this protection depend on the edited, filename, newfile, readonly,
and writeany options.) If you want to force elvis to overwrite an existing
file, you can append a "!" to the end of the command name, but before the file
name. In order to avoid ambiguity, there must not be any whitespace between
the "write" command name and the "!" character when you want to overwrite an
existing file. Conversely, when writing to an external program there should be
whitespace before the "!" that marks the start of the program's command line.
The ">>file" notation tells elvis to append to "file" instead of overwriting
it.
The :lpr command sends text to the printer. It is similar to :write except
that :lpr formats the buffer contents as defined by the bufdisplay option and
the printing options. If no output file or external program is specified, then
the printer output is sent to the file or external program specified by the
lpout option.
4.3.7 The args list, and selecting a file to edit
.-------.-------------------.-----------------------------------.
|ADDRESS| COMMAND | ARGUMENTS |
|-------|-------------------|-----------------------------------|
| | ar[gs] | [file...] |
| | n[ext][!] | [file...] |
| | N[ext][!] | |
| | pre[vious][!] | |
| | rew[ind][!] | |
| | la[st] | |
| | wn[ext][!] | |
| | f[ile] | [file] |
| | e[dit][!] | [+line] [file] |
| | ex[!] | [+line] [file] |
| | vi[sual][!] | [+line] [file] |
| | o[pen][!] | [+line] [file] |
^-------^-------------------^-----------------------------------^
The "args list" is a list of file names. It provides an easy way to edit a
whole series of files, one at a time. Initially, it contains any file names
that you named on the command line when you invoked elvis.
The :args command displays the args list, with the current file name enclosed
in brackets. You can also use :args to replace the args list with a new set of
files; this has no effect on whatever file you're editing at that time, but it
will affect any :next commands that you give later.
The :next command switches to the next file in the args list. This means it
loads the next file from the args list into an edit buffer, and makes that
edit buffer be the current buffer for this window. You can also give a new
args list on the :next command line; this acts like a :args command to set the
args list, followed by an argumentless :next command to load the next (first)
file in that list.
The :Next (with a capital "N") and :previous commands are identical to each
other. They both move backwards through the args list.
The :rewind and :last commands switch to the first and last files in the args
list, respectively.
The :wnext command is like a :write command followed by a :next command. It
saves any changes made to the current file before switching to the next file.
(The autowrite option offers a better alternative.)
The :file command displays information about the current buffer. It can also
be used to change the filename associated with this buffer.
The :edit and :ex commands are identical to each other. They both switch to a
new file, or if no file is named then they reread the current file. This has
no effect on the args list.
The :visual and :open commands switch to a new file if one is named; otherwise
they continue to use the current buffer without reloading it from the original
file. These commands have the side-effect of switching the window mode from ex
mode to either the normal visual mode or the uglier "open" mode, respectively.
"Open" mode allows you to use all of the visual commands, but it only displays
a single line (the line that the cursor is on) at the bottom of the screen.
The sole advantage that "open" mode has over "visual" mode is that "open" mode
doesn't need to know what kind of terminal you're using.
4.3.8 Quitting
.-------.-------------------.-----------------------------------.
|ADDRESS| COMMAND | ARGUMENTS |
|-------|-------------------|-----------------------------------|
| | cl[ose][!] | |
| | q[uit][!] | |
| | wq[uit][!] | [file] |
| | x[it][!] | [file] |
| | qa[ll][!] | |
| | pres[erve] | |
^-------^-------------------^-----------------------------------^
Except for :qall, all of these commands attempt to close the current window
without losing any changes. When the last window is closed, elvis exits. The
differences between these commands concern how modified buffers are handled.
In the discussions below, it is assumed that tempsession is True and the
buffer's retain option is False, which is usually the case.
The :close command is the simplest. If the current window is the only window
and one or more buffers have been modified but not yet saved, then :close will
fail; otherwise the current window will be closed. The visual ^Wq command uses
this command internally. If the window's buffer was modified, then elvis will
just have a modified buffer lying around, which may or may not be visible in
some other window. That's okay. The other quitting commands won't allow you to
lose that buffer accidentally. You can make some other window view that buffer
by giving that buffer's name in parentheses on an ex command line in that
other window.
The :quit command fails if the current buffer has been modified. If you wish
to abandon the changes made to the current buffer, you can add a "!" to the
end of the command name; this has the effect of turning off the buffer's
modified flag.
The :xit command saves the file if it has been modified, and then closes the
window. The visual ZZ command uses this command internally.
The :wquit command saves the file regardless of whether it has been modified,
and then closes the window.
The :qall command tries to close all of the windows at once. It is equivalent
to giving the :quit command in each window.
The :preserve command closes all windows and exits, but it doesn't delete the
session file. You can restart the same edit session later by giving the
command...
elvis -ssessionfile
...where sessionfile is the name of the session file, usually
"/var/tmp/elvis1.ses". You may want to check the value of the session option
first, just to make sure.
4.3.9 Scripts and macros
.-------.-------------------.-----------------------------------.
|ADDRESS| COMMAND | ARGUMENTS |
|-------|-------------------|-----------------------------------|
| | @ | cutbuf |
| | so[urce][!] | file |
| | saf[er][!] | file |
| | al[ias] | [name [excmds]] |
| | unal[ias][!] | name |
^-------^-------------------^-----------------------------------^
The :@ command executes the contents of a cut buffer as a series of ex
command lines.
The :source command reads a file, and executes its contents as a series of ex
commands. Normally, elvis would issue an error message if the requested file
didn't exist but when a "!" is appended to the command name, elvis will
silently ignore the command if it doesn't exist.
The :safer command is exactly like :source, except that :safer will
temporarily set the safer option while it is executing the commands. You
should use :safer instead of :source when it is possible that the file to be
executed could contain potentially harmful commands. For example, the default
"elvis.ini" file uses :source to execute the ".exrc" file in your home
directory since it is presumably secure, but :safer is used to execute the
".exrc" file in the current directory since it could have been created by
anybody. As with :source!, invoking :safer! (with a '!' suffix) prevents elvis
from complaining about nonexistent script files.
The :alias and :unalias commands manipulate the alias list. (See the Tips
section of the manual for a discussion of aliases.) With no arguments, :alias
displays all aliases. When given a name but no commands, :alias displays the
complete definition of the named alias. When given a name and commands, :alias
defines (or redefines) an alias. The :unalias command deletes the alias with a
given name.
4.3.10 Working with a compiler
.-------.-------------------.-----------------------------------.
|ADDRESS| COMMAND | ARGUMENTS |
|-------|-------------------|-----------------------------------|
| | cc[!] | [args] |
| | mak[e][!] | [args] |
| | er[rlist][!] | [file] |
^-------^-------------------^-----------------------------------^
If you use elvis to edit source code for programs, then you can have elvis
read the output of your compiler and parse that output for error messages.
When elvis finds an error message, it can move the cursor to the file and line
number where the error was reported.
To parse the compiler output, elvis first breaks the output into lines. Each
line is then broken into words. If a word looks like a number, then it is
assumed to be a line number. If a word looks like the name of an existing
file, then it is assumed to be a file name. Any line which contains both a
line number and a file name is treated as an error report (with the remainder
of the line serving as a description of the error); lines which don't have
both of these are simply ignored.
The :cc and :make commands use the ccprg and makeprg options, respectively, to
run your compiler or "make" utility, and collect the output. Elvis will then
move the cursor to where the first error was detected. (If there were no
errors, elvis will say so and leave the cursor unchanged.)
After that, the :errlist command can be used repeatedly to move to each
successive error. You can also use the :errlist command with a file name
argument to load a new batch of error messages from a file; the cursor is then
moved to the first error in that batch.
4.3.11 Built-in calculator
.-------.-------------------.-----------------------------------.
|ADDRESS| COMMAND | ARGUMENTS |
|-------|-------------------|-----------------------------------|
| | ca[lculate] | expr |
| | ev[al] | expr |
^-------^-------------------^-----------------------------------^
Elvis has a built-in calculator which uses a C-like syntax. It is described
in section 12: Arithmetic Expressions. The :if and :let commands also use the
calculator.
The :calculate command evaluates an expression and displays the result.
The :eval command evaluates an expression using the simpler syntax (which
basically means that text outside of parentheses is left alone), and then
executes the result as an ex command line. This provides a way to use
expressions with commands which would not ordinarily use expressions. For
example, the following command line inserts the value the elvispath option
into the current edit buffer.
:eval insert elvispath=(elvispath)
Note: There is a hardcoded limit of (normally) 1023 characters for the result
of any expression. This limit will sometimes impact the use of :eval. For
example, if your $EXINIT environment variable is longer than 1023 characters
then elvis will be unable to interpret it during initialization.
4.3.12 Buffer commands
.-------.-------------------.-----------------------------------.
|ADDRESS| COMMAND | ARGUMENTS |
|-------|-------------------|-----------------------------------|
| | al[l][!] | excmds |
| | b[uffer][!] | [buffer] |
| | ( | buffer |
| | bb[rowse][!] | |
| | sbb[rowse][!] | |
^-------^-------------------^-----------------------------------^
The :all command applies a given ex command line to each edit buffer in turn.
Normally the command is applied just to the user edit buffers, but if you
append a "!" to the command name, then the ex command line is applied to
internal buffers as well. For example, the following sets the "bufdisplay"
option of all user edit buffers:
:all set bufdisplay=normal
In script files, you can supply multiple command lines to a single :all
commands by placing a '{' character on the :all line, following that with any
number of command lines, and then finally a '}' character on a line by itself
to mark the end. This notation doesn't allow nesting; you can't use {...}
inside a larger {...} command list. (Hopefully this limitation will be lifted
soon.)
The :buffer command lists either all user edit buffers, or (when "!" is
appended to the command name) all buffers including internal ones. If the
buffer is being edited in one or more windows, then the window ID is also
displayed. Buffers which have been modified will be marked with an asterisk.
You can also use the :buffer command to make the current window display a
different buffer.
The :(buffer notation causes the current window to display the named buffer,
instead of the current buffer. This isn't really a command; it is part of an
address. Whenever you give an address without specifying a command, elvis
moves the cursor to the addressed line. In this particular case, we're
addressing the most recently changed line of a given buffer, so that's where
the cursor is moved to. For more information, see the discussion of Buffer IDs
earlier in this chapter (in the discussion of addresses).
The :bbrowse and :sbbrowse commands create an HTML document which lists the
names of all user buffers (or, when a '!' is appended to the command name, all
buffers including internal buffers). You can then go to one of the buffers
just by following the hypertext link. The difference between these two
commands is that :bbrowse displays the list in the current window, but
:sbbrowse creates a new window to display it.
4.3.13 Window commands
.-------.-------------------.-----------------------------------.
|ADDRESS| COMMAND | ARGUMENTS |
|-------|-------------------|-----------------------------------|
| | sp[lit] | [+line] [file | !shellcmd] |
| | new | |
| | sne[w] | |
| | sn[ext] | [file...] |
| | sN[ext] | |
| | sre[wind] | |
| | sl[ast] | |
| | sta[g] | [tag] |
| | sb[rowse] | restrictions |
| | sa[ll] | |
| | wi[ndow] | [ +[+] | -[-] | number | buffer] |
| | di[splay] | [modename [language]] |
| | no[rmal] | |
^-------^-------------------^-----------------------------------^
The :split command creates a new window. If you supply a file name, then it
will load that file into an edit buffer and the new window will show that
buffer. If you supply a shell command line preceded by a '!' character, then
it will create an untitled buffer, and read the output of that command line
into the buffer. Otherwise, the new window will show the same buffer as the
current window.
The :new and :snew commands are identical to each other. They both create a
new empty buffer, and then create a new window to show that buffer.
The :snext, :sNext, :srewind, :slast, :stag, and :sbrowse commands resemble
the :next, :Next, :rewind, :last, :tag, and :browse commands, respectively,
except that these "s" versions create a new window for the newly loaded file,
and leave the current window unchanged.
The :sall command creates a new window for any files named in the args list,
which don't already have a window. (See section 4.3.7: The args list... for a
discussion of the args list.)
The :window command either lists all windows (when invoked with no arguments)
or switches to a given window. You can specify which to switch to by giving
one of the following arguments.
.----------.-----------------------------------------------.
| ARGUMENT | MEANING |
|----------|-----------------------------------------------|
| + | Switch to the next window, like ^Wk |
| ++ | Switch to the next window, wrapping like ^W^W |
| - | Switch to the previous window, like ^Wj |
| -- | Switch to the previous window, wrapping |
| number | Switch to the window whose windowid=number |
| buffer | Switch to the window editing the named buffer |
^----------^-----------------------------------------------^
The :display command switches the window to a new display mode, overriding the
value of the bufdisplay option. The display option indicates the current
display mode. If you omit the new modename, then the :display command will
list all supported display modes, with an asterisk next to the current mode.
The "syntax" mode allows you to specify which language's syntax it is supposed
to use; if you don't specify a language, elvis will guess the language from
the file name's extension.
The :normal command is equivalent to ":display normal". It can be abbreviated
to ":no", which is certainly easier to type than ":dis normal".
4.3.14 Configuration
.-------.-------------------.-----------------------------------.
|ADDRESS| COMMAND | ARGUMENTS |
|-------|-------------------|-----------------------------------|
| | ab[breviate][!] | [lhs rhs] |
| | una[bbreviate][!] | lhs |
| | map[!] | [lhs rhs] |
| | unm[ap][!] | lhs |
| | bre[ak][!] | lhs |
| | unb[reak][!] | lhs |
| | dig[raph][!] | [lhs [rhs]] |
| | col[or] | [font color ["on" color]] |
| | gu[i] | text |
| | se[t][!] | [option=value | option? | all] |
| | lo[cal][!] | [option=value | option ] |
| | le[t][!] | option=expr |
| | if | expr |
| | th[en] | excmds |
| | el[se] | excmds |
| | try | excmds |
| | wh[ile] | expr |
| | do | excmds |
| | mk[exrc][!] | [file] |
^-------^-------------------^-----------------------------------^
The :abbreviate and :unabbreviate commands add and remove entries to the
abbreviation table, respectively. Also, the :abbreviate command can be used
with no arguments to list the current contents of the abbreviation table. For
a discussion of abbreviations, see section 3.3: Abbreviations. Normal
abbreviations are only active while you're typing in a normal text buffer;
adding a '!' suffix to the command name causes the macro to be active while
you're entering ex command lines.
The :map and :unmap commands add and remove entries to the map tables,
respectively. When the :map command is given without any arguments, it lists
the contents of a map table.
There are two map tables. When a "!" is appended to the command name, these
commands use the table that applies to input mode; without the "!" these
commands use the table that applied to visual command mode.
The primary purpose of map tables is to assign actions to the cursor keypad
and the function keys. Each of these keys sends an arbitrary but distinctive
sequence of characters when pressed. The map tables are used to convert these
arbitrary character sequences into command keystrokes that elvis can do
something useful with. For example, arrow keys are normally mapped to the h,
j, k, and l commands.
The first argument to :map is the raw character sequence sent by a key, and
the remaining arguments are the characters that elvis should pretend you
pressed. This can be either a literal sequence of characters, or a
gui-dependent symbol representing a particular keystroke. See the User
Interfaces chapter for lists of keystrokes. Also, function keys can usually be
denoted by #1 for the <F1> key, #2 for the <F2> key, and so on.
The second argument is character sequence that elvis should pretend you typed
whenever the raw characters are received. This may be preceded by the word
"visual" which causes the remaining argument characters to be processed as
visual commands, even if the key is pressed in input mode. This trick is used
to allow the cursor to be moved via the arrow keys when in input mode.
The :break and :unbreak commands set and reset the breakpoint flag for a given
macro, respectively. Using a '!' suffix causes the breakpoint to be set for an
input-mode map. This is used for debugging macros, as described in section
16.3: How to debug macros. If a macro has its breakpoint flag set, and the
maptrace option is set to run, then when that map is encountered elvis will
automatically switch maptrace to step mode.
The :digraph command manipulates the digraph table. (See section 3.2: Digraphs
for a discussion on digraphs.) With no arguments, it lists the digraph table.
With one argument, it removes the given digraph from the table. With two
arguments, it adds the given digraph to the table, or if the same two ASCII
characters are already in the table then it alters the existing entry.
Normally, the :digraph command sets the most significant bit in the last
argument's character. That way you don't need to be able to type a non-ASCII
character on your keyboard in order to enter it into the table; you can type
the ASCII equivalent and allow elvis to convert it to non-ASCII before storing
the digraph. If you don't want elvis to set the most significant bit, then
append a "!" to the end of the command name.
The :color command allows you to choose a color to use for displaying each
font. Some user interfaces don't support this. The ones that do will vary in
the color names that they support. The termcap interface supports black,
white, gray, red, green, blue, brown, yellow, magenta, and cyan, plus light or
bright versions of most of those. The windows interface supports the same
colors, except that it is pickier: it doesn't allow spaces, and only "light"
is accepted, such as "lightblue". The x11 interface supports all standard X
color names.
The first argument should be the name of the font to change. This can be
"normal", "bold", "emphasized", "italic", "underlined", or "fixed". Some user
interfaces may also support "standout", "cursor", "scrollbar", and/or
"toolbar". All of these can be either spelled out completely, or abbreviated
to the first letter. (Currently no user interface supports both "standout" and
"scrollbar" so there is no ambiguity.) If you omit the font name, then
"normal" is assumed. The termcap interface requires you to assign a "normal"
color before any of the other fonts.
You can specify an optional background color. The word "on" is used to delimit
the foreground color name from the background color name. For example, the
command ":color yellow on blue" causes normal text to be displayed as yellow
characters on a blue background.
The x11 user interface allows you to specify both the foreground and
background color for the cursor. The cursor is drawn in the foreground color
normally, but the background color if elvis own the current X selection.
The :gui command provides a way to pass unusual commands to the user
interface. Currently, the only user interface which uses this is the "x11"
interface, which uses it to configure the toolbar.
The :set command allows you to examine or change the values of options. Using
:set! (with a "!" at the end of the command name) causes it to include the
group name of any option that is output. In addition, "!" inhibits the setting
of any option's "modified" flag, which will then prevent it from being output
by a later argumentless :set command.
With no arguments, :set lists the names and values of any options that have
been altered or are of frequent interest. If given the argument "all" it will
list the names and values of most (but not really all) options. If given the
name of an option followed by a "?" character, :set will output the option's
name and value. If given the name of a group of options, followed by a "?"
character, :set will output the names and values of all options in that group.
To turn a Boolean option on, just give the name of the option. You can turn it
off by adding the prefix "no" to the option name, and you can negate it by
adding the "neg" prefix to its name.
To change the value of a non-Boolean option, give the name followed
immediately by an "=" and the new value. If the new value contains whitespace,
you should either enclose the entire value in quotes, or precede each
whitespace character with a backslash.
If you give the name of a non-Boolean option, without either "=value" or "?",
then elvis will display its value.
.-----------.--------------------------------------------------------.
| EXAMPLE | WHAT IT DOES |
|-----------|--------------------------------------------------------|
| :set | display names & values of changed/interesting options |
| :set all | display names & values of most POSIX-compliant options |
| :set ts? | display name & value of the tabstop option |
| :set lp? | display names & values of all printing options |
| :set ts=4 | set value of the tabstop option to 4 |
| :set ai | turn on the autoindent option |
| :set noai | turn off the autoindent option |
| :set negai| toggle the autoindent option |
^-----------^--------------------------------------------------------^
The :local command is similar to :set, and is intended to be used in aliases
and scripts. In addition to setting options' values, it also pushes the old
values onto a stack; the old values are automatically restored at the end of
the alias or script. Another difference is that where :set would output an
option, :local merely pushes its old value, without outputting or changing the
option's value. This means that you can save a non-Boolean option simply by
mentioning its name on a :local command line; Boolean options can also be
saved without altering them, but you must put a question mark after the
option's name.
Here's a simple alias which uses :local. It totals the numbers in all lines
from the current line forward to the next line which contains the "total:",
and stores the total in the "total:" line.
:alias total {
local nowrapscan ignorecase t=0
.,/total:/-1 s/\d\+/let t=t+&/x
eval /total/ s/:.*/: (t)/
}
The :let command computes a new value for an option. The :let command should
be followed by the name of an option, then an "=" sign, and then an expression
that produces the new value. Note that even Boolean options use the "="
notation here. When invoked as :let! (with a '!' suffix), elvis won't set the
option's "changed" flag so it won't be output by an argumentless :set command.
The :if command evaluates an expression, and sets an internal variable
according to whether the result was true or false. Later, the :then and :else
commands can be used to test that variable, and conditionally execute other ex
commands.
Note that after an :if command, any other ex commands which don't start with
:then or :else will be executed unconditionally.
In aliases or script files, you can supply multiple command lines to a single
:then or :else by placing a '{' character on the :then/:else line, following
that with any number of command lines, and then finally a '}' character on a
line by itself to mark the end. The following example demonstrates this
syntax, and also shows that you can safely use :if inside a :then or :else
command:
:if i <= 0
:then {
if i == 0
then echo zero
else echo negative
}
:else echo positive
The :try command executes its argument text as an ex command line. Regardless
of whether that command line succeeds or fails, the :try command itself always
succeeds. That's significant because a command fails, all pending aliases,
macros, and scripts are cancelled; :try prevents that. Error messages and
warning messages are disabled while the command line runs. Afterward, the
then/else is set to indicate whether the command line succeeded. This command
is useful for implementing specialized error handing in an alias or script.
The following example will search for "foo"; if there is no "foo" then it will
search for "bar":
:try /foo
:else /bar
The :while command stores an expression. It should be followed by a :do
command; the :do command repeatedly evaluates the expression, and as long as
the result is true it executes the commands which follow the :do. The
following example counts from 1 to 10:
:let i=1
:while i <= 10
:do {
calc i
let i=i+1
}
Both the :if/:then/:else and :while/:do command structures permit nesting.
I.e., the commands in a :then command can't affect the "if" variable to cause
the :else command to also be executed.
The :mkexrc command creates a file containing ex commands which recreate the
current map, abbreviation, and digraph tables, and also sets any options which
have been changed. Basically it stores your current configuration in a file
which you can later :source to restore your configuration. If you don't
specify a filename, then it will write to ".exrc" or "elvis.rc" in the current
directory.
NOTE: The :mkexrc command does not store information for :alias or :gui
commands. This is expected to be added in a later version of elvis.
4.3.15 Miscellaneous
.-------.-------------------.-----------------------------------.
|ADDRESS| COMMAND | ARGUMENTS |
|-------|-------------------|-----------------------------------|
| | " | text |
| | cd[!] | [directory] |
| | chd[ir][!] | [directory] |
| | ec[ho] | text |
| | me[ssage] | text |
| | wa[rning] | text |
| | erro[r] | text |
| | sh[ell] | |
| | st[op][!] | |
| | sus[pend][!] | |
| | ve[rsion] | |
| line | go[to] | |
| line | ma[rk] | mark |
| line | k | mark |
| | { | |
^-------^-------------------^-----------------------------------^
The " command causes the remainder of the line to be ignored. It is used for
inserting comments into ex scripts.
The :cd and :chdir commands are identical. They both change the current
working directory for elvis and all its windows. If you don't specify a new
directory name then elvis will switch to your home directory.
The :echo command displays its arguments as a message. This may be useful in
ex scripts.
The :message, :warning, and :error commands all output their arguments as a
message. The command name indicates the importance of the message. This is
diffs from :echo as follows: the messages are translated via the elvis.msg
file, then evaluated using the simpler syntax, and finally stuffed into the
message queue. The message queue collects all messages, and outputs them
immediately before waiting for the next keystroke. Also, the :error command
has the side-effect of terminating any macros, aliases, or scripts.
The :shell command starts up an interactive shell (command-line interpreter).
Elvis will be suspended while the shell executes. (Exception: the "x11" GUI
runs the shell in a separate xterm window. The elvis and the shell can then
run simultaneously.)
The :stop and :suspend commands are identical to each other. If the operating
system and user interface support it, they will suspend elvis and resume the
shell that started elvis. (This is like hitting ^Z on many UNIX systems.) If
the OS or GUI don't support it, then elvis will generally treat these commands
as synonyms for the :shell command.
The :version command identifies this version number of elvis, and displays
credits.
The :goto moves the cursor to the addressed line. This is the only command
which can be abbreviated down to zero characters, so if you type in a line
containing just a line address, then elvis will treat that as a :goto command.
The :mark and :k commands are identical to each other. They set a named mark
to equal the addressed line, or the current line if no address was given.
The { commands } notation isn't really a command; it is a feature of elvis'
syntax which allows you to pass several command lines to a command which
normally expects a single command line as its argument. It is supported by the
:global, :vglobal, :all, :then, and :else commands. Instead of placing the
argument command at the end of one of those command lines, you can place a
single '{' character there. That should be followed by one or more command
lines, and terminated by a '}' on a line by itself.
4.4 Alphabetical list of ex commands
.-------.-------------------.-----------------------------------.
|ADDRESS| COMMAND | ARGUMENTS |
|-------|-------------------|-----------------------------------|
| | ab[breviate][!] | [lhs rhs] |
| | al[l][!] | excmds |
| line | a[ppend][!] | [text] |
| | ar[gs] | [file...] |
| | bb[rowse] | |
| | bre[ak][!] | lhs |
| | br[owse][!] | restrictions |
| | b[uffer][!] | [buffer] |
| | ca[lculate] | expr |
| | cc[!] | [args] |
| | cd[!] | [directory] |
| range | c[hange][!] | [count] [text] |
| | chd[ir][!] | [directory] |
| | cl[ose][!] | |
| | col[or] | [font color ["on" color]] |
| range | co[py] | line |
| range | d[elete] | [cutbuf] [count] |
| | dig[raph][!] | [lhs [rhs]] |
| | di[splay] | [modename [language]] |
| | do | excmds |
| | ec[ho] | text |
| | e[dit][!] | [+line] [file] |
| | el[se] | excmds |
| | er[rlist][!] | [file] |
| | erro[r] | text |
| | ev[al] | expr |
| | ex[!] | [+line] [file] |
| | f[ile] | [file] |
| range | g[lobal][!] | /regexp/ excmds |
| line | go[to] | |
| | gu[i] | text |
| | h[elp] | topic |
| | if | expr |
| line | i[nsert][!] | [text] |
| range | j[oin][!] | |
| line | k | mark |
| | la[st] | |
| | le[t][!] | option=expr |
| range | l[ist] | [count] |
| | lo[cal][!] | [option=value | option ] |
| range | lp[r][!] | [ file | >>file | !shellcmd ] |
| | mak[e][!] | [args] |
| | map[!] | [lhs rhs] |
| line | ma[rk] | mark |
| | me[ssage] | text |
| | mk[exrc][!] | [file] |
| range | m[ove] | line |
| | new | |
| | n[ext][!] | [file...] |
| | N[ext][!] | |
| | no[rmal] | |
| range | nu[mber] | [count] |
| | o[pen][!] | [+line] [file] |
| | po[p][!] | |
| | pre[vious][!] | |
| range | p[rint] | [count] |
| line | pu[t] | [cutbuf] |
| | qa[ll][!] | |
| | q[uit][!] | |
| line | r[ead] | file | !shellcmd |
| | red[o] | [count] |
| | rew[ind][!] | |
| | sN[ext] | |
| | saf[er][!] | file |
| | sa[ll] | |
| | sbb[rowse] | |
| | sb[rowse] | restrictions |
| | se[t][!] | [option=value | option? | all] |
| | sh[ell] | |
| | sl[ast] | |
| | sne[w] | |
| | sn[ext] | [file...] |
| | so[urce][!] | file |
| | sp[lit] | [file | !shellcmd] |
| | sre[wind][!] | |
| | stac[k] | |
| | sta[g] | [tag] |
| | st[op][!] | |
| range | s[ubstitute] | /regexp/newtext/[g][p][x][count] |
| | sus[pend][!] | |
| | ta[g][!] | [tag] |
| | th[en] | excmds |
| range | t[o] | line |
| | try | excmds |
| | una[bbreviate][!] | lhs |
| | unb[reak][!] | lhs |
| | u[ndo] | [count] |
| | unm[ap][!] | lhs |
| | ve[rsion] | |
| range | v[global][!] | /regexp/ excmds |
| | vi[sual][!] | [+line] [file] |
| | wa[rning] | text |
| | wh[ile] | expr |
| | wi[ndow] | [+ | - | number | buffer ] |
| | wn[ext][!] | |
| | wq[uit][!] | [file] |
| range | w[rite][!] | [file | >>file | !shellcmd] |
| | x[it][!] | [file] |
| range | y[ank] | [cutbuf] [count] |
| line | z | [spec] |
| range | ! | shellcmd |
| | " | text |
| range | # | [count] |
| range | & | |
| | ( | buffer |
| range | < | |
| range | = | |
| range | > | |
| | @ | cutbuf |
| | { | |
| range | ~ | |
^-------^-------------------^-----------------------------------^
ΓòÉΓòÉΓòÉ 1.5. Elvis 2.1 Regular Expressions ΓòÉΓòÉΓòÉ
5. REGULAR EXPRESSIONS
Elvis uses regular expressions for searching and substitutions. A regular
expression is a text string in which some characters have special meanings.
This is much more powerful than simple text matching.
5.1 Syntax
Elvis' regexp package treats the following one- or two-character strings
(called meta-characters) in special ways:
\(subexpression\)
The \( and \) metacharacters are used to delimit subexpressions.
When the regular expression matches a particular chunk of text,
Elvis will remember which portion of that chunk matched the
subexpression. The :s/regexp/newtext/ command makes use of this
feature.
^
The ^ metacharacter matches the beginning of a line. If, for
example, you wanted to find "foo" at the beginning of a line, you
would use a regular expression such as /^foo/. Note that ^ is only a
metacharacter if it occurs at the beginning of a regular expression;
practically anyplace else, it is treated as a normal character.
(Exception: It also has a special meaning inside a [character-list]
metacharacter, as described below.)
$
The $ metacharacter matches the end of a line. It is only a
metacharacter when it occurs at the end of a regular expression;
elsewhere, it is treated as a normal character. For example, the
regular expression /$$/ will search for a dollar sign at the end of
a line.
\<
The \< metacharacter matches a zero-length string at the beginning
of a word. A word is considered to be a string of 1 or more letters,
digits, or underscores. A word can begin at the beginning of a line
or after 1 or more non-alphanumeric characters.
\>
The \> metacharacter matches a zero-length string at the end of a
word. A word can end at the end of the line or before 1 or more
non-alphanumeric characters. For example, /\<end\>/ would find any
instance of the word "end", but would ignore any instances of e-n-d
inside another word such as "calendar".
\@
When you're performing a search in visual mode, and the cursor is on
a word before you start typing the search command, then \@ matches
the word at the cursor.
\=
Ordinarily, the visual mode search command leaves the cursor on the
first character of the matching text that it finds. If your regular
expression includes a \= metacharacter, then it will leave the
cursor at the position that matched the \=. For example, if you
place \= at the end of your regular expression, then the cursor will
be left after the matching text instead of at the start of it.
.
The . metacharacter matches any single character.
NOTE: If the magic option is turned off, then . is treated as an
ordinary, literal character. You should use \. to get the
meta-character version in this case.
[character-list]
This matches any single character from the character-list. Inside
the character-list, you can denote a span of characters by writing
only the first and last characters, with a hyphen between them. If
the character-list is preceded by a ^ character, then the list is
inverted -- it will match any character that isn't mentioned in the
list. For example, /[a-zA-Z]/ matches any ASCII letter, and /[^ ]/
matches anything other than a blank.
There is no way to quote the ']' or '-' characters, which means that
if you want to include those characters as members of the list, you
must place them in positions where they couldn't be mistaken for the
end of the list or a range. Specifically, ']' can appear only as the
first character in the list (immediately after the "[" or "[^" that
starts the list) or as the last character in a range. '-' can appear
there too, or immediately after the last character of a range. For
example, [])}] matches a closing bracket, parentheses, or curly
brace. [^-+] matches any character except '+' or '-'. Probably the
trickiest example, []-]-] matches a closing bracket or a '-'. (Note
that the range "]-]" matches a single bracket; we wrote it this way
so that the following "-" would be in a context where it couldn't be
mistaken for a range and so must be a literal '-' character.)
There are also special cases for some common character lists. When
one of the following special symbols appears in a character list,
the list will include all appropriate characters for that symbol
including the non-ascii characters as indicated by the digraph
table. Note that he brackets around these symbols are in addition to
the brackets around the whole class. For example, /[[:alpha:]]/
matches any single letter, and /[[:alpha:]_][[:alnum:]_]*/ matches
any C identfier.
.----------------.-------------------------------------------.
| SPECIAL SYMBOL | INCLUDED CHARACTERS |
|----------------|-------------------------------------------|
| [:alnum:] | all letters and digits |
| [:alpha:] | all letters |
| [:ascii:] | all ASCII characters |
| [:blank:] | the space and tab characters |
| [:cntrl:] | ASCII control characters |
| [:digit:] | all digits |
| [:graph:] | all printable characters excluding space |
| [:lower:] | all lowercase letters |
| [:print:] | all printable characters including space |
| [:punct:] | all punctuation characters |
| [:space:] | all whitespace characters except linefeed |
| [:upper:] | all uppercase characters |
| [:xdigit:] | all hexadecimal digits |
^----------------^-------------------------------------------^
NOTE: If the magic option is turned off, then the opening [ is
treated as an ordinary, literal character. To get the meta-character
behavior, you should use \[character-list] in this case.
\s, \S, \d, \D, \w, \W, \p, and \P
These are all shortcuts for certain character lists. The lowercase
\s, \d, \w, and \p symbols match (respectively) any whitespace
character, digit, alphanumeric character, or any printable
character. The uppercase versions are the opposites; they match any
single character that the lowercase versions don't match.
\0, \a, \b, \f, \r, and \t
These are control characters, just as they would be in C strings.
Note that there is no \n.
\{n\} or \{n}
This is a closure operator, which means that it can only be placed
after something that matches a single character. It controls the
number of times that the single-character expression should be
repeated. The \{n\} or \{n} operator, in particular, means that the
preceding expression should be repeated exactly n times. For
example, /^-\{80\}$/ matches a line of eighty hyphens, and
/\<[[:alpha:]]\{4}\>/ matches any four-letter word.
\{n,m\} or \{n,m}
This is a closure operator which means that the preceding
single-character expression should be repeated between n and m
times, inclusive. If the m is omitted (but the comma is present)
then m is taken to be infinity. For example, /"[^"]\{3,5\}"/ matches
any pair of quotes which contains three, four, or five non-quote
characters. /.\{81,}/ matches any line which contains more than 80
characters.
*
The * metacharacter is a closure operator which means that the
preceding single-character expression can be repeated zero or more
times. It is equivalent to \{0,\}. For example, /.*/ matches a whole
line.
NOTE: If the magic option is turned off, then * is treated as an
ordinary, literal character. You should use \* to get the
meta-character version in this case.
\+
The \+ metacharacter is a closure operator which means that the
preceding single-character expression can be repeated one or more
times. It is equivalent to \{1,\}. For example, /.\+/ matches a
whole line, but only if the line contains at least one character. It
doesn't match empty lines.
\?
The \? metacharacter is a closure operator which indicates that the
preceding single-character expression is optional -- that is, that
it can occur 0 or 1 times. It is equivalent to \{0,1\}. For example,
/no[ -]\?one/ matches "no one", "no-one", or "noone".
Anything else is treated as a normal character which must exactly match a
character from the scanned text. The special strings may all be preceded by a
backslash to force them to be treated normally.
5.2 Substitutions
The :s command has at least two arguments: a regular expression, and a
substitution string. The text that matched the regular expression is replaced
by text which is derived from the substitution string.
You can use any punctuation character to delimit the regular expression and
the replacement text. The first character after the command name is used as
the delimiter. Most folks prefer to use a slash character most of the time,
but if either the regular expression or the replacement text uses a lot of
slashes, then some other punctuation character may be more convenient.
Most other characters in the substitution string are copied into the text
literally but a few have special meaning:
.-------.----------------------------------------------------------.
|SYMBOL | MEANING |
|-------|----------------------------------------------------------|
| ^M | Insert a newline (instead of a carriage-return) |
| & | Insert a copy of the original text |
| ~ | Insert a copy of the previous replacement text |
| \1 | Insert a copy of that portion of the original text which |
| | matched the first set of \( \) parentheses |
| \2-\9 | Do the same for the second (etc.) pair of \( \) |
| \U | Convert following characters to uppercase |
| \L | Convert following characters to lowercase |
| \E | End the effect of \U or \L |
| \u | Convert the next character to uppercase |
| \l | Convert the next character to lowercase |
| \# | Insert the line number, as a string of digits |
| \0 | Insert a nul character |
| \a | Insert a bell character |
| \b | Insert a backspace character |
| \f | Insert a form-feed character |
| \n | Insert a line-feed character |
| \r | Insert a carriage-return character |
| \t | Insert a tab character |
^-------^----------------------------------------------------------^
These may be preceded by a backslash to force them to be treated normally. The
delimiting character can also be preceeded by a backslash to include it in
either the regular expression or the substitution string.
Traditionally \0 was a synonym for the & symbol -- they both inserted a copy
of the matching text. Elvis breaks from tradition here to make \0 insert a NUL
character because there would otherwise be no way to have a substitution
insert a NUL character.
5.3 Options
Elvis has two options which affect the way regular expressions are used. These
options may be examined or set via the :set command.
The first option is called "[no]magic". This is a boolean option, and it is
"magic" (TRUE) by default. While in magic mode, all of the meta-characters
behave as described above. In nomagic mode, the ., [...], and * characters
loose their special meaning unless preceeded by a backslash. Also, in
substitution text the & and ~ characters are treated literally unless
preceeded by a backslash.
The second option is called "[no]ignorecase". This is a boolean option, and it
is "noignorecase" (FALSE) by default. While in ignorecase mode, the searching
mechanism will not distinguish between an uppercase letter and its lowercase
form, except in a character list metacharacter. In noignorecase mode,
uppercase and lowercase are treated as being different.
Also, the "[no]wrapscan" and "[no]autoselect" options affect searches.
5.4 Examples
This example changes every occurrence of "utilize" to "use":
:%s/utilize/use/g
This example deletes all whitespace that occurs at the end of a line anywhere
in the file.
:%s/\s\+$//
This example converts the current line to uppercase:
:s/.*/\U&/
This example underlines each letter in the current line, by changing it into
an "underscore backspace letter" sequence. (The ^H is entered as "control-V
backspace".):
:s/[a-zA-Z]/_^H&/g
This example locates the last colon in a line, and swaps the text before the
colon with the text after the colon. The first \( \) pair is used to delimit
the stuff before the colon, and the second pair delimit the stuff after. In
the substitution text, \1 and \2 are given in reverse order to perform the
swap:
:s/\(.*\):\(.*\)/\2:\1/
ΓòÉΓòÉΓòÉ 1.6. Elvis 2.1 Options ΓòÉΓòÉΓòÉ
6. OPTIONS
Options are a primary means of configuring the appearance and behavior of
elvis. They are set via the :set command, or the :let command. The options'
values are examined directly by elvis internally, and can also be displayed via
:set, or in an expression. The following tables list the names, type, group,
and description of each option. One table lists all options alphabetically, and
the other breaks list down into groups of related options. I recommend the
latter, since there are a lot of options.
Most options have two names -- a short name that is easy to type in, and a
longer descriptive name. You can type in either name; they work equivalently.
Elvis always outputs the longer name when it is listing values.
Each option accepts a specific type of value. The most common types are
boolean, number, string, and one-of, but some options have weird types.
Each option serves as an attribute of something. The group of an option
designates what it is an attribute of. For example, the "filename" option is an
attribute of buffers; when you switch to a different buffer, it will have a
different value for the "filename" option. Other options are attributes of
windows, or display modes, etc. Here's a complete list:
.---------.-------------------------------------------------------.
| GROUP | DESCRIPTION |
|---------|-------------------------------------------------------|
| buf | Attributes of buffers |
| win | Attributes of windows |
| syntax | Attributes of the "syntax" display mode |
| x11 | Attributes of the "x11" user interface |
| tcap | Attributes of the "termcap" user interface |
| windows | Attributes of the "windows" user interface |
| win32 | User interface attributes for the Win32 port |
| global | Global options |
| lp | Printing options |
| user | User variables a - z (Global, useful in ex scripts) |
^---------^-------------------------------------------------------^
You don't need to know an option's group to set that option. You can output the
values of all options in a group by passing the group name followed by a
question mark to the :set command. The following example outputs all of the
attributes of the current buffer:
:set buf?
6.1 Options, grouped by function
6.1.1 Options that relate the buffer to a file
6.1.2 Statistics about a buffer
6.1.3 Options that affect movement commands
6.1.4 Options that affect input mode
6.1.5 Ex options
6.1.6 Window statistics
6.1.7 Options affecting the appearance of text
6.1.8 Options for a particular display mode
6.1.9 Messages
6.1.10 Words
6.1.11 Options for a particular user interface
6.1.12 Regular expression options
6.1.13 Tag options
6.1.14 Window update parameters
6.1.15 Cache options
6.1.16 Options that describe the system
6.1.17 External programs
6.1.18 Directory names
6.1.19 Initialization options
6.1.20 Keyboard map options
6.1.21 Printing options
6.1.22 Previous arguments
6.1.23 Unsupported options
6.1.24 User variables
6.1.1 Options that relate the buffer to a file
.---------------------.---------.--------.-----------------------------.
| OPTION NAMES | TYPE | GROUP | DESCRIPTION |
|---------------------|---------|--------|-----------------------------|
| filename, file | String | buf | name of file in buffer |
| bufname, buffer | String | buf | name of buffer |
| bufid, bufferid | Number | buf | ID number of user buffer |
| retain, ret | Boolean | buf | keep buffer in session file |
| modified, mod | Boolean | buf | buffer differs from file |
| edited, samename | Boolean | buf | buffer loaded from filename |
| newfile, new | Boolean | buf | filename doesn't exist yet |
| readonly, ro | Boolean | buf | don't overwrite filename |
| defaultreadonly, dro| Boolean | global | assume all files readonly |
| locked, lock | Boolean | win | prevent any alterations |
| autowrite, aw | Boolean | global | save file before switching |
| writeany, wa | Boolean | global | don't warn of existing file |
| backup, bk | Boolean | global | make *.bak file before write|
| undolevels, ul | Number | buf | number of undoable commands |
| beautify, bf | Boolean | global | strip ctrl chars from files |
^---------------------^---------^--------^-----------------------------^
The filename option stores the name of the text file whose text was initially
loaded into the buffer. If no file name is known (e.g., for an internal buffer
or a new, untitled buffer) then this will be an empty string. The :file
command can be used to change the filename. Also, the filename is set
automatically when you write the buffer out, if it had no filename before.
The bufname option stores the name of the buffer. Usually this will be the
same as the filename, but it can be different. Every buffer has a bufname,
even if it doesn't have a filename. The name of a buffer can be changed via
the :buffer command.
For user buffers, the bufid option stores a unique id number for each buffer.
Anyplace where you can use the (name) notation to specify a buffer, you can
also use (n) as an abbreviation for the buffer whose bufid=n. Also, for
filenames you can use #n for the filename of the buffer whose bufid=n.
The retain option indicates whether the buffer is intended to survive past the
end of this elvis process. If this option is true and the tempsession option
is false (":set retain notempsession") then elvis will allow you to exit even
if this buffer hasn't been saved since its last change. When you restart the
session, the buffer will still exist with all its changed text intact. By
default, the retain option is false (":set noretain") because that mimics
traditional vi behavior.
The modified option indicates whether the buffer has been modified since the
last time it was written out completely.
The edited option indicates whether the filename option has been modified
since the last time it was written out. If this option is false, elvis will be
more cautious about writing the file out.
The newfile option indicates that when the buffer was created it tried to load
the file identified by the filename option, but that file did not exist at
that time.
The readonly option indicates that when the buffer was loaded, the original
file was marked as being unwritable. Either that, or the defaultreadonly
option was set to true (probably via the -R command line flag). This option
has two purposes: it gives you a way to detect that you can't write the file
out, and it protects you from writing out a file that you meant to just look
at without modifying.
The locked option prevents you from modifying the buffer. Nearly any command
which would modify the buffer will fail. The only exceptions are "undo"
commands, and commands such as :e which merely reload the buffer from its
original file.
Setting the autowrite option allows elvis to automatically write the current
buffer out to a file if it has been modified, before switching to another
buffer. By default this option is off, so if you try to switch away from a
modified buffer, elvis will just give an error message and refuse to switch
until you manually write the file out.
Elvis tries to save you from accidentally clobbering existing files. Setting
the writeany option disables this protection; elvis will allow you to
overwrite any file that the operating system will allow, without giving any
warnings.
The backup option isn't used internally by elvis, but the default elvis.bwf
file checks this flag to determine whether it should attempt to make a backup
of a file it is about to overwrite. By default, this option is false, so
backups will not be made.
For each buffer, the undolevels option indicates the number of "undo" versions
elvis will maintain. Each undo level requires at least three blocks of the
session file (typically 2K bytes each, 6K total) so you probably don't want to
set this higher than 100 or so, and you probably want to keep it much lower.
The default is 0, which is a special case that mimics vi's traditional
behavior.
If the beautify option is true, then whenever elvis reads text from a file or
external program, it will strip any control characters other than tab,
linefeed or formfeed. This is false by default.
6.1.2 Statistics about a buffer
.---------------------.---------.--------.-----------------------------.
| OPTION NAMES | TYPE | GROUP | DESCRIPTION |
|---------------------|---------|--------|-----------------------------|
| readeol, reol | One of | buf | newline mode when reading |
| writeeol, weol | One of | global | newline mode when writing |
| bufchars, bc | Number | buf | number of characters |
| buflines, bl | Number | buf | number of lines |
| partiallastline, pll| Boolean | buf | file didn't end with newline|
| errlines | Number | buf | buflines when :make was run |
| internal | Boolean | buf | elvis requires this buffer |
| putstyle, ps | One of | buf | type of text in a cut buffer|
^---------------------^---------^--------^-----------------------------^
The readeol option determines how elvis reads the file into a buffer. It can
be one of the following:
"unix" The file is opened in binary mode, and any Line Feed characters in
the file are converted to newline characters in the buffer.
"dos" The file is opened in binary mode, and any Carriage Return/Line
Feed pairs from the file are converted to newline characters in the
buffer.
"mac" The file is opened in binary mode, and any Carriage Return
characters from the file are converted to newline characters in the
buffer.
"text" The file is opened in text mode, and no other conversion takes
place.
"binary" The file is opened in binary mode, and no conversion takes
place.
The compiled-in default is "text", but the standard elvis.brf file sets it
to a file-dependent value via the fileeol() function.
The writeeol option influences how elvis writes buffers out to a file. If a
buffer's readeol option is set to "binary", then the value of writeeol is
ignored for that buffer; the file will be written in binary. Otherwise it can
be one of the following to determine the output format:
"unix" The file is opened in binary mode, and newlines are written out as
Line Feed characters.
"dos" The file is opened in binary mode, and newlines are written out as
Carriage Return/Line Feed pairs.
"mac" The file is opened in binary mode, and newlines are written out as
Carriage Return characters.
"text" The file is opened in text mode, and no conversion takes place.
"binary" The file is opened in binary mode, and no conversion takes
place.
"same" The value of the readeol option is used to control the output
format.
The default value is "same". You might want to change that to some other mode
to force the file to be written in a specific format; for example, setting it
to "text" will cause a non-binary file to be written in the local text format.
The bufchars and buflines options indicate the number of characters and lines
in the buffer, respectively. The buflines option works by counting newline
characters; it is unaffected by vagaries of the display mode. These options
can't be set.
The partiallastline option indicates whether the file's last line ended with a
newline. Text files should always end with a newline. Traditionally, when vi
loaded a file that contained a partial last line, it would append a newline to
the edit buffer to complete that last line. The extra newline would be written
out when the buffer was saved to a file. That's great for vi, but elvis can
edit binary files as well as text, and appending newlines onto binary files
could cause some problems. So elvis appends a newline just like vi, but also
sets the partiallastline option to remind itself that when the buffer is saved
in binary mode, the last newline should be omitted. Also, the hex display mode
is smart enough to hide the added newline when this option is set.
The errlines option is used to store the number of lines that were in the
buffer when the last :make or :cc command was run. Any difference between
buflines and errlines is used to adjust the line numbers reported in any error
messages, to compensate for lines which have been inserted or deleted since
then.
The internal option indicates that elvis uses the buffer internally. Such
buffers can't be deleted.
The putstyle option is only relevant for cut buffers. It indicates whether the
cut buffer contains characters, whole lines, or a rectangular area. It is set
automatically whenever you yank or cut text into a cut buffer; when you put
(paste) the contents of that buffer, elvis checks the value of this option to
determine how the text should be inserted into your edit buffer.
6.1.3 Options that affect movement commands
.---------------------.---------.--------.-----------------------------.
| OPTION NAMES | TYPE | GROUP | DESCRIPTION |
|---------------------|---------|--------|-----------------------------|
| matchchar, mc | String | global | characters matched by % |
| paragraphs, para | String | buf | nroff paragraph commands |
| sections, sect | String | buf | nroff section commands |
| sentenceend, se | String | global | punct at end of sentence |
| sentencequote, sq | String | global | punct allowed after se |
| sentencegap, sg | Number | global | spaces required after sq |
| scroll, scr | Number | win | scroll amount for ^D/^U |
^---------------------^---------^--------^-----------------------------^
The matchchar option stores a list of matching character pairs, for use by
the % visual command. In each pair, the first character should be an opening
parenthesis (or whatever) and the second character should be the corresponding
closing parenthesis. If both characters are identical, then the % command will
try to guess whether it should search forward or backward. The default value
is mc=[]{}(), but you may wish to add :set mc=[]{}()<>\"\" to your ~/.exrc (or
~/elvis.rc) file.
The paragraphs option stores a list of two-letter nroff paragraph commands.
This list is used by the { and } movement commands. Similarly, the sections
option stores a list of section commands, affecting the [[ and ]] commands.
Their defaults are paragraphs="PPppIPLPQP" and sections="NHSHSSSEse".
The sentenceend, sentencequote, and sentencegap options all affect the ( and )
sentence motion commands. The sentenceend option is a list of punctuation
characters which can appear at the end of a sentence. The sentencegap option
is the number spaces that must follow a sentenceend character in order for it
to count as the end of a sentence. The sentencequote option is a list of
punctuation characters that can appear between the sentenceend character and
the spaces. Their defaults are sentenceend="?!.", sentencequote=")\"", and
sentencegap=2, which meets the proposed POSIX specifications.
The scroll option indicates the number of lines that the ^U and ^D commands
should scroll the screen by. Its default value is 12.
6.1.4 Options that affect input mode
.---------------------.---------.--------.-----------------------------.
| OPTION NAMES | TYPE | GROUP | DESCRIPTION |
|---------------------|---------|--------|-----------------------------|
| autoindent, ai | Boolean | buf | auto-indent new text |
| inputtab, it | One-Of | buf | input mode's (Tab) key |
| completebinary, cob | Boolean | global | complete names of binaries? |
| autotab, at | Boolean | buf | allow autoindent to use '\t'|
| tabstop, ts | Number | buf | width of tabstop columns |
| shiftwidth, sw | Number | buf | width used by < and > |
| textwidth, tw | Number | buf | width for word-wrap, or 0 |
| wrapmargin, wm | (weird) | win | set textwidth from right |
| digraph, dig | Boolean | global | allow X-backspace-Y entry |
^---------------------^---------^--------^-----------------------------^
Setting the autoindent option causes elvis to automatically insert whitespace
at the start of each line, to make it line up with the preceding line. This is
convenient when you're editing C source code. It is off by default.
The inputtab option controls the behavior of the Tab key. It can be set to
one of the following values:
tab - insert an actual tab character. This is the traditional vi
behavior, and the default for user buffers.
spaces - insert enough space characters to look like a tab character.
filename - attempt filename completion on the preceding word.
identifier - attempt tag name completion on the preceeding word. If
the word is already comlete, or if cursor isn't at the end of a word,
then it inserts a plain tab character. This can be handy when you're
editing source code.
ex - a smarter version of filename completion, it knows enough about ex
command line syntax to avoid some tabbing mistakes that the filename
setting can make. It can also complete ex command names, tag names,
option names, and option values. This is the default for the (Elvis
ex history) buffer, which is used for entering in ex commands.
The completebinary option controls whether binary files are included in the
list of possible filename completions. The default setting is
nocompletebinary, so binary files are omitted. This is handy when you're
editing source code -- if your directory contains "foo.c" and "foo.o" (or
"FOO.OBJ" in the Land of the Lost), then typing f-o-o-TAB will complete the
"foo.c" name.
The autotab option affects the behavior of the < and > operator commands, and
the ^D and ^T input mode keystrokes. If autotab is true then elvis will
include tab characters in the indentation whitespace; if it is false then the
indentation whitespace will consist entirely of space characters. By default,
it is true.
Note that if you start with a buffer which contains no tabs, and do a ":set
inputtab=spaces noautotab" then no amount of editing will result in the buffer
containing tabs... unless you get tricky with ^V or something.
The tabstop option affects the way tab characters are displayed, by specifying
how far apart the tab stops should be located. When elvis displays a file with
tabs, it displays the tabs as a variable number of spaces. You should probably
leave this option at its default value (8) since changing this will make your
file look strange in any other context. If you want to use indentation levels
of less than 8 characters, you're better off changing shiftwidth.
The shiftwidth option indicates how far left or right the < and > operator
commands (and the ^D and ^T input mode keystrokes) should shift the line of
text. This is used for adjusting the indentation of lines.
When editing a text file in "normal" display mode, the textwidth option can be
used to cause word-wrap to occur when a line gets too long. The default value
of textwidth is 0, which disables automatic word-wrap. Setting it to any
larger value causes word-wrap to occur when text is inserted into a line,
causing that line to become wider than textwidth columns. (Note that this has
nothing to do with the display formatting of the "html" and "man" display
modes.)
The wrapmargin option is provided for backwards compatibility. It allows you
to set the textwidth relative to the right edge of the window, instead of the
left edge. This option's value is actually derived from the textwidth option's
value and the window's width, so if you resize a window this option's value
will appear to change to correspond to the new width; textwidth will not
change.
Digraphs allow you to enter non-ASCII characters as a combination of two ASCII
characters. There are two ways to enter digraphs: ^K X Y and X backspace Y.
The second form can cause some confusion if you're not expecting it, so the
digraph option was created as a way to disable that second form. The first
form of digraphs is always available. This option is false by default, to
avoid the confusion.
6.1.5 Ex options
.---------------------.---------.--------.-----------------------------.
| OPTION NAMES | TYPE | GROUP | DESCRIPTION |
|---------------------|---------|--------|-----------------------------|
| prompt | Boolean | global | issue ":" prompt in ex mode |
| autoprint, ap | Boolean | global | print current line in ex |
| report | Number | global | minimum # lines to report |
| optionwidth, ow | Number | global | widths of ":set all" values |
^---------------------^---------^--------^-----------------------------^
The prompt option controls whether a ":" prompt is issued before reading each
command line in EX mode. It is true by default, and should usually be left
that way.
The autoprint option causes elvis to display the current line of the edit
buffer in certain circumstances, while you're in EX mode. It is true by
default.
The report option determines the minimum number of lines that must change in a
file, before elvis will bother to display a count of the changed lines. As a
special case, if report=0 then it won't report any changes, or failed
:s/old/new/ commands. Its default value is 5, so small changes won't be
reported but big ones will.
optionwidth sets a limit on how wide a single option can be when output by a
":set" or ":set all" command. Limiting the widths is a good idea, because
otherwise a single option that has a long value could force the output to use
fewer columns, forcing some options scrolling off the top of the screen before
you can read them. The ":set" command likes to leave at least two spaces after
each column. The default value is optionwidth=24, which guarantees that at
least 3 columns can fit on an 80-character terminal, since 80/(24+2)=3. Note
that optionwidth has no effect on options that you explicitly name in a ":set"
command; for example, ":set tags?" will show you the entire tag path
regardless of the value of optionwidth.
6.1.6 Window statistics
.---------------------.---------.--------.-----------------------------.
| OPTION NAMES | TYPE | GROUP | DESCRIPTION |
|---------------------|---------|--------|-----------------------------|
| windowid, id | Number | win | ID number of current window |
| columns, cols | Number | win | width of window |
| lines, rows | Number | win | height of window |
^---------------------^---------^--------^-----------------------------^
The windowid option stores the ID number of the current window. These window
IDs are listed by the :buffer command. Some GUIs may also display the window
ID as part of the window's title. This value is set to a unique value
automatically when the window is created. You can't change it.
The columns and lines options indicate the size of the window.
6.1.7 Options affecting the appearance of text
.---------------------.---------.--------.-----------------------------.
| OPTION NAMES | TYPE | GROUP | DESCRIPTION |
|---------------------|---------|--------|-----------------------------|
| list, li | Boolean | win | show markups, newlines, etc.|
| showmarkups, smu | Boolean | global | show markup at cursor |
| bufdisplay, bd | String | buf | default display mode |
| display, mode | String | win | name of current display mode|
| number, nu | Boolean | win | display line numbers |
| ruler, ru | Boolean | win | display cursor's line/column|
| showcmd, sc | Boolean | win | display command characters |
| showmatch, sm | Boolean | win | highlight matching parens |
| showmode, smd | Boolean | win | display the command state |
| showname, snm | Boolean | global | display the buffer name |
| showtag, st | Boolean | global | display tag on status line |
| nonascii, asc | One-Of | global | how to display non-ascii |
| showstack, sstk | Boolean | win | display some debugging info |
^---------------------^---------^--------^-----------------------------^
In the "normal" or "syntax" display modes, the list option causes tab
characters to be shown as ^I instead of being expanded to the appropriate
amount of whitespace, and it causes the end of each line to be marked with a $
character. In "html" or "man" mode, it causes all of the markups to be
displayed.
In "html" or "man" mode, the showmarkups option causes the markup at the
cursor to be displayed, but leaves other markups hidden. It has no effect in
other display modes. This option is off by default, so markups won't suddenly
become visible as you move the cursor around.
Each buffer has a bufdisplay option, which indicates that buffer's preferred
display mode. Whenever a window starts to show a buffer, it switches its
display mode to that buffer's bufdisplay mode. You should set bufdisplay to
the name of a supported display mode: normal, syntax, html, man, tex, or hex.
The compiled-in default is normal but the standard elvis.arf file tries to
choose a more clever default, based on the extension of the buffer's filename.
The display option indicates which display mode the window is currently in.
You can't set this option directly; you must use the :display command instead.
The number option causes a line number to be prepended to the start of each
line. The line numbers are defined as "one plus the number of newlines
preceding the start of the line," which is not necessarily how the current
display mode defines lines. Consequently, the line numbers may not increment
by 1 every time. These line numbers do correspond to the ruler and the visual
G command, though. This option is false by default.
The ruler option causes the current line number and column number to be
displayed at the bottom of the screen. This uses the same definition of "line
number" as the number option, above. This option is false by default.
When entering multi-character commands, the showcmd option causes the
preceding characters of the command to be displayed at the bottom of the
window.
The showmatch option helps you locate matching parentheses. When you're in
input mode, and you type a ), ], or } character, elvis will cause the matching
(, [, or { character to be highlighted on the screen. This option is false by
default.
The showmode option causes elvis to display a one-word label for its current
parse state in the lower right-hand corner of the window. Usually, this will
be either "Command" or "Input". This option is false by default, but I suggest
you make it true because it really is handy.
The showname option causes elvis to display the buffer name on the bottom row
of each window, unless it has something else to show there such as an error
message.
The showtag option causes elvis to display (on the bottom row of each window)
the name of the tag being defined at the cursor's position. Usually, this
means it tells you the name of the function you're editing. When this option
is true, each time you load a text file into an edit buffer elvis will scan
the "tags" file for any tags which are defined in the text file. Elvis builds
a table of those tags, and stores it in RAM for the sake of speed. Then, each
time the window is updated, elvis will compare the cursor position to the
definition lines of each tag, and display the name of the last tag it found
which is defined at or before the cursor position. By default, this option is
false because the tag loading can be slow.
The version of ctags distributed with elvis has a "-l" flag which causes it to
generate "ln" hints, which give the line number where the tag is defined.
Elvis can use these hints to greatly accelerate the loading of tags when you
switch files. The "-l" option is enabled by default if you don't give any
flags, so you don't need to give it explicitly unless you're also giving some
other flags.
NOTE: The MS-DOS version of elvis is normally configured to omit the showtag
option, because memory is tight in the lower 640K.
The nonascii option tells elvis how to display characters 0x80 through 0xff.
It can have one of the following values:
.-------.------------------------------------------------.
| VALUE | MEANING |
|-------|------------------------------------------------|
| all | All characters 0x80-0xff are visible |
| most | Chars 0xa0-0xff are visible, but not 0x80-0x9f |
| none | Chars 0x80-0xff are not visible |
| strip | Convert 0xa0-0xfe to ASCII; others not visible |
^-------^------------------------------------------------^
Any characters which aren't visible will be displayed as '.' characters. Note
that this only affects the way the characters are displayed; they are actually
stored with their true 8-bit value. The default value of nonascii is "most",
because that is the correct value for the Latin-1 symbol set.
The showstack option causes some debugging output to appear on the bottom row
of the window. It is false by default, and you should leave it that way.
6.1.8 Options for a particular display mode
.---------------------.---------.--------.-----------------------------.
| OPTION NAMES | TYPE | GROUP | DESCRIPTION |
|---------------------|---------|--------|-----------------------------|
| commentfont, cfont | One-Of | syntax | font used for comments |
| stringfont, sfont | One-Of | syntax | font used for strings |
| keywordfont, kfont | One-Of | syntax | font used for reserved words|
| functionfont, ffont | One-Of | syntax | font used for function names|
| variablefont, vfont | One-Of | syntax | font used for variables |
| prepfont, pfont | One-Of | syntax | font used for preprocessor |
| otherfont, ofont | One-Of | syntax | font used for other symbols |
| includepath, inc | String | syntax | where to find #include files|
^---------------------^---------^--------^-----------------------------^
In the syntax display mode, the commentfont, stringfont, keywordfont,
functionfont, variablefont, prepfont and otherfont options specify which font
is to be used for different parts of the source code. Each option can be set
to normal, bold, emphasized, italic, underlined, or fixed. The prepfont is
used for preprocessor directives. The keywordfont is used for reserved words
such as "int" and "return". The functionfont is used for any other word which
is followed by an opening parenthesis character. The otherfont is used for any
other word which matches some language-dependent criteria; for C, the word
must either contain no lowercase letters or end with a "_t" (probably a
constant or a user-defined type). The variablefont is used for all other
words. Punctuation is always in the normal font; you can't control that.
You can set these variables during initialization, in the .exrc or elvis.rc
file. After that, your window must actually be in the "syntax" mode for these
to be accessible.
As a separate step, some user interfaces allow you to specify a color to be
used for each font, via the :color command.
The includepath option contains a list of directory names where elvis should
look for #include files. When you look up a tag whose name begins with a quote
character, elvis searches through those directories for a file with the same
name as the tag (with the quotes stripped off). This means that you can move
the cursor onto a #include file name, hit ^], and have elvis load the
indicated header file.
6.1.9 Messages
.---------------------.---------.--------.-----------------------------.
| OPTION NAMES | TYPE | GROUP | DESCRIPTION |
|---------------------|---------|--------|-----------------------------|
| terse, te | Boolean | global | don't translate messages |
| verbose | Numeric | global | give more status messages |
| errorbells, eb | Boolean | global | ring bell for error message |
| warningbells, wb | Boolean | global | ring bell for warning msg |
| flash, vbell | Boolean | global | substitute flash for bell |
^---------------------^---------^--------^-----------------------------^
The terse option indicates whether elvis should attempt to translate messages
via the elvis.msg file. If terse is true, then no such translation takes
place; the built-in messages are used. If terse is false, then elvis will
search through the file (actually the "Elvis messages" buffer) for a line
which looks like "terse:verbose" and if found it'll use the verbose version
instead. By default, terse is false.
The verbose option has nothing to do with the terse option. Instead, it
indicates the number of -V flags given when elvis was invoked. Larger values
indicate that the user wants more status messages to be generated. This is
handy when elvis isn't initializing itself the way you expected it to; elvis'
initialization code frequently tests the value of verbose and automatically
writes status messages when verbose is set to a high enough level.
The errorbells and warningbells options cause the terminal's bell to ring when
an error message or warning message is generated, respectively. By default the
errorbells option is true, and the warningbells option is false.
Setting the flash option causes elvis to use a visible alternative to the
bell, if one exists. This is nice in a crowded terminal room. By default this
option is false.
6.1.10 Words
.---------------------.---------.--------.-----------------------------.
| OPTION NAMES | TYPE | GROUP | DESCRIPTION |
|---------------------|---------|--------|-----------------------------|
| true, True | String | global | locale's True value |
| false, False | String | global | locale's False value |
| submit, Submit | String | x11 | locale's Submit label |
| cancel, Cancel | String | x11 | locale's Cancel label |
| help, Help | String | x11 | locale's Help label |
^---------------------^---------^--------^-----------------------------^
These options store words, which are translated via the elvis.msg file when
elvis starts up. The default versions of all of them are their capitalized
English names.
The true and false options exist primarily to allow the english words true and
false to be used in expressions to represent Boolean literals. Also, the
value of false is used as an alternative false string, in addition to "", "0",
or "false". (In a Boolean context, any string that isn't false is considered
to be true, so elvis never compares a string to the true option's value.) A
Boolean option will return the value of either the true or false option, as
appropriate.
If you're using the "x11" user interface, then values of the submit and cancel
options are used as the labels for the [Submit] and [Cancel] buttons in a
dialog. Also, if the dialog contains any Boolean options, the value will be
displayed using values of the true and false options.
Currently the help option does nothing. Eventually I expect to add pull-down
menus to the "x11" interface, though, and in Motif menu bars the "Help" menu
traditionally appears on the far right edge. The value of the help option
will allow elvis to recognize the "Help" menu.
6.1.10 Options for a particular user interface
.---------------------.---------.--------.-----------------------------.
| OPTION NAMES | TYPE | GROUP | DESCRIPTION |
|---------------------|---------|--------|-----------------------------|
| term, ttytype | String | tcap | terminal's termcap entry |
| ttyrows, ttylines | Number | tcap | height of screen |
| ttycolumns, ttycols | Number | tcap | width of screen |
| ttyunderline, ttyu | Boolean | tcap | okay to mix color & underln |
| codepage, cp | Number | win32 | console character set |
|---------------------|---------|--------|-----------------------------|
| scrollbar, sb | Boolean | (gui) | enable the scrollbar |
| toolbar, tb | Boolean | (gui) | enable the toolbar |
| statusbar, stb | Boolean | (gui) | enable the statusbar |
|---------------------|---------|--------|-----------------------------|
| menubar, mb | Boolean | windows| enable the menubar |
| font, fnt | String | windows| base font |
| normalstyle, nfn | String | windows| n or combination of b/i/u |
| boldstyle, bfn | String | windows| n or combination of b/i/u |
| italicstyle, ifn | String | windows| n or combination of b/i/u |
| fixedstyle, ffn | String | windows| n or combination of b/i/u |
| emphasizedstyle, efn| String | windows| n or combination of b/i/u |
| underlinedstyle, nfn| String | windows| n or combination of b/i/u |
|---------------------|---------|--------|-----------------------------|
| normalfont, xfn | String | x11 | name of normal font |
| boldfont, xfb | String | x11 | name of bold font |
| italicfont, xfi | String | x11 | name of italic font |
| controlfont, xfc | String | x11 | name of toolbar font |
| underline, uln | Boolean | x11 | enables underlining |
| toolbar, xtb | Boolean | x11 | enables the toolbar |
| scrollbarleft, xsl | Boolean | x11 | enable scrollbar on side |
| scrollbarwidth, xsw | Number | x11 | size of scrollbar, in pixels|
| scrollbartime, xst | Number | x11 | delay for scrollbar repeat |
| borderwidth, xbw | Number | x11 | size of text area's border |
| dblclicktime, xdct | Number | x11 | double-click speed, 1/10 Sec|
| blinktime, xbt | Number | x11 | cursor blink rate, 1/10 Sec |
| textcursor, tc | Number | x11 | one of hollow, opaque, xor |
| xrows, xlines | Number | x11 | height of new windows |
| xcolumns, xcols | Number | x11 | width of new windows |
| firstx, xpos | Number | x11 | horiz. position of first win|
| firsty, ypos | Number | x11 | vert. position of first win |
| stagger | Number | x11 | offset for next new window |
| icon | Boolean | x11 | use the built-in icon? |
| stopshell, ssh | String | x11 | interactive shell command |
| autoiconify, aic | Boolean | x11 | iconify old window |
| altkey, metakey | One of | x11 | effect of the Alt key |
| focusnew, fn | Boolean | x11 | force focus into new window |
| warpto, wt | One of | x11 | ^W^W forces pointer movement|
| warpback, xwb | Boolean | x11 | upon exit, point to xterm |
| outlinemono, om | Number | x11 | char outlining for X11-mono |
^---------------------^---------^--------^-----------------------------^
6.1.10.1 Termcap options
The term, ttyrows, ttycolumns, and ttyunderline options are only present if
you're using the termcap user interface. They indicate the name of the termcap
entry being used (normally taken from the TERM environment variable), the size
of the screen, and whether it is safe to try underlining text when colors have
been assigned to fonts. The ttyunderline option is true by default, but it
should be made false on the Linux console, because the console driver has a
bug which prevents underlined text from being shown in color.
The codepage option only exists in the Win32 version with the termcap
interface (WindowsNT or Windows95, in console mode). It indicates which code
page (character map) the console is using. Its value is persistent; if you
change it in elvis, the console will remain changed even after you exit elvis.
Changing the code page has no effect on the digraph table, or elvis' idea of
which non-ASCII characters are printable or should be treated as letters; it
only reconfigures the console driver. Typical values are 437 for the standard
IBM PC character set, and 850 for extra European characters.
6.1.10.2 Options common to Windows and X11
The scrollbar, toolbar, and statusbar options indicate whether the scrollbar,
toolbar, and statusbar should be visible, respectively. By default, all are
are visible.
6.1.10.2 Windows options
The menubar option indicates whether the menu bar should be visible. By
default, it is visible.
The font option stores the name of the base font. The easiest way to set it is
via the "Options->Font" menu item.
The normalstyle, boldstyle, italicstyle, fixedstyle, emphasizedstyle, and
underlinedstyle options determine how elvis will derive each of its fonts from
the base font. The values of these options are strings. If the string is "n"
then the base font is used unmodified. Other possibilities are any
combination of "b" for bold, "i" for italic (slanted), and "u" for underlined.
For example, ":set ufn=bu" causes elvis' underlined font to be drawn in bold
with an underline.
6.1.10.3 X11 options
The other options all apply to the x11 interface. The normalfont, boldfont,
and italicfont options control the X fonts used for displaying text.
Typically, the elvis.ini or ".exrc" file will set these. If you do choose to
set them in one of these files, be sure to have your initialization script
check which interface is being used because if elvis is using the termcap
interface then these x11 options won't exist. These options all default to an
empty string; this is a special case which causes elvis to use the "fixed"
font for normal text, and to derive the bold and italic fonts from the normal
font.
The controlfont option determines which font is used for displaying the labels
of toolbar buttons, and also the statusbar. Unlike the other fonts, this one
is permitted to have a variable pitch. If it is unset, then elvis will use the
font named "variable" by default.
The underline option determines whether characters in the "underlined" font
should be displayed as underlined. Normally, underline is true, so they are
underlined. Setting nounderline will cause them to be displayed as normal
characters, but in the color of underlined text.
The toolbar option controls whether the toolbar is visible or not. It is
normally true, which makes the toolbar visible. The toolbar can be configured
via the :gui command.
The statusbar option controls the visibility of the statusbar. It is true by
default, which makes the statusbar is visible. The statusbar always displays
the information which would otherwise be shown on the bottom row of the text
area only when the ruler and showmode options were true. When you press a
toolbar button, the button's one-line description is shown on the statusbar.
The scrollbarleft option deterimines which side of the window the scrollbar
will be drawn on. This option is false by default, so the scrollbar appears on
the right side of the window. Making it true will cause the scrollbar to be
drawn on the left.
The scrollbarwidth option controls the size of the x11 scrollbar. The default
value is 14 pixels, and the allowed range is 5 to 40 pixels.
The scrollbar buttons automatically repeat if you hold a mouse button down
scrollbartime tenths of a second. The default is 4 tenths of a second.
The main text area of a window looks better when the characters aren't drawn
immediately adjacent to the edge. The borderwidth option allows you to specify
how many pixels should be left blank between a character and any edge of the
text area. The default is 1 pixel.
The dblclicktime option allows you to adjust the speed of mouse double-clicks
to match your own clicking habits. The default is 3 tenths of a second.
The blinktime option controls the cursor blink rate. If set to 0, the cursor
will not blink. If set to a value from 1 to 10, then the cursor will first be
visible for that many tenths of a second, and then invisible for the same
amount of time. The cursor will only blink in the window which currently has
keyboard focus.
The textcursor option controls the way the block text cursor is drawn. It can
be xor, hollow, or opaque. The default is xor, which causes the cursor to be
drawn as a filled rectangle with the XOR bitblt function. This converts the
background color to the cursor color, and the foreground color to an
unpredictable color; hopefully the foreground color will contrast with the
cursor color well enough to allow you to discern what the underlying character
is. The hollow cursor style causes the cursor to be drawn as an unfilled
rectangle. This allows you to easily see the underlying character, and detect
whether it is highlighted or not. The opaque cursor style draws a filled
rectangle, which is easier to locate but you can only see the underlying
character between blinks.
The xrows and xcolumns options control the initial size of windows. They
default to 34 and 80, respectively, and can also be set via the -geometry
command-line flag. After a window has been created, you can use your window
manager to resize the window.
The firstx and firsty options, if set, control the position of the first
window that elvis creates. If they are unset, then elvis doesn't specify a
position for the window. The -geometry command-line flag can be used to set
these options. After the first window has been created, if the stagger option
is set to a non-zero value then any new windows are created that many pixels
down and to the right of the current window. If stagger is zero, then elvis
won't specify a position for the new windows, so the window manager can choose
the location itself.
The icon option can only be set in an initialization file such as elvis.ini or
".exrc"; once the first window has been created it is too late to change it.
This option controls whether the window will be given the default, built-in
icon. It is true by default, so windows will get the icon. This is usually a
good thing. Some window managers don't allow you to override built-in icons,
though, so if you want your window manager to use a different icon for elvis
then you'll need to have a "set noicon" in your elvis.ini file.
The stopshell option stores a command which runs an interactive shell. It is
used for the :shell and :stop ex commands, and the ^Z visual command.
Normally, this is set to "xterm &" so you get a shell in a window. The "&" at
the end of the command allows elvis to continue responding to user input while
the shell is running.
When the ^W^W visual command switches keyboard control to an X11 window which
as been iconified, elvis automatically deiconifies it. When it does this, if
the autoiconify option is set then elvis will iconify the previous window, so
the number of iconified elvis windows remains constant. By default, this
option is false. Regardless of whether autoiconify is set, you can always use
your window manager to iconify or deiconify windows manually.
The altkey option controls the effect of the Alt or Meta keys. It can be set
to either control-O, setbit, or ignore. The ignore value is self explanatory.
If the option is set to control-O then the x11 interface will simulate a ^O
keystroke before each actual keystroke. This is handy because if you're in
input mode you can just hold down Alt/Meta to perform a series of visual
commands. If the option is set to setbit then the x11 interface will set the
most significant bit of each ASCII character while the Alt/Meta key is held
down. Some other programs use this trick as a means of entering non-ASCII
characters. (Elvis has a better way though; check out the :digraph command.)
The default is setbit.
The focusnew option causes elvis to force input focus to switch to any newly
created window, or to one which has been deiconified. It is true by default;
making it false (":set nofocusnew") prevents elvis from forcing a change of
input focus in those two situations. Note that elvis always forces a change of
input focus when you give a command which switches windows, such as ^W^W.
The warpto option can cause elvis to force the mouse pointer to move whenever
you use keyboard commands such as ^W^W to switch from one elvis window to
another. There are two reasons you may wish to do this: either your window
manager requires the pointer to be in a window for that window to receive
keystrokes, or you want to have your X server automatically pan the screen to
bring the next window into view.
You can set the warpto option to any one of the following values: don't,
scrollbar, origin, or corners. The default is don't which prevents any
automatic pointer movement. The scrollbar value causes the pointer to move to
the scrollbar, and origin moves it to the upper-left corner. The corners value
causes the pointer to move first to the corner furthest from the window's text
cursor, and then to the nearest corner; this will cause the X server to pan
(if necessary) to bring the entire window into view.
The warpback option, if set, causes the X terminal's graphic cursor to be
moved back to the window which held keyboard focus at the time when elvis was
started. Usually this will be the xterm where you typed in the "elvis
files..." command line. Just as the firstx, firsty, and stagger options are
intended to allow mouseless positioning of elvis windows, the warpback option
is intended to serve as a mouseless way to switch keyboard focus back to the
original xterm, so that mouse haters will find elvis' x11 interface as
convenient to use as the termcap interface. By default, warpback is false.
The outlinemono option affects the way that text is drawn against a stippled
background when elvis is run on monochrome X terminals (or with the -mono
command-line flag). It has no effect on color systems. Because characters
drawn on a stippled background can be hard to read, elvis can draw a white
outline around the black characters. The value of outlinemono is a number
that indicates how thick the outline should be. 3 is the thickest supported
outline, and 0 is no outline at all. The default is 2.
6.1.11 Regular expression options
.---------------------.---------.--------.-----------------------------.
| OPTION NAMES | TYPE | GROUP | DESCRIPTION |
|---------------------|---------|--------|-----------------------------|
| ignorecase, ic | Boolean | global | regexp uppercase=lowercase |
| magic, ma | Boolean | global | use normal regexp syntax |
| autoselect, as | Boolean | global | visibly mark searched text |
| wrapscan, ws | Boolean | global | searching wraps at EOF<->BOF|
| gdefault, gd | Boolean | global | default change all instances|
| edcompatible, ed | Boolean | global | remember regsub flags |
| saveregexp, sre | Boolean | global | remember regexp to use as //|
^---------------------^---------^--------^-----------------------------^
Setting the ignorecase option to true will cause elvis to treat uppercase and
lowercase letters as being equal, except in character list metacharacters.
When ignorecase is false (the default), they are treated as different.
The magic option selects one of two different syntaxes for regular
expressions. When magic is true, it uses the normal syntax in which * and .
are special characters. When magic is false, it uses a simplified syntax.
The autoselect option, when true, causes a successful visual search command
such as /regexp to visibly mark the matching text just like the v command
does. This is intended to compensate for elvis 2.1's lack of a "c" option in
the :s/old/new/ command. By default, autoselect is false.
The wrapscan option determines what happens when a search command bumps into
the top or bottom of a buffer. If wrapscan is true, then the search will wrap
around to the other end of the buffer, so if there's a match anywhere in the
buffer, the search will find it. If wrapscan is false, then searches fail when
they hit the end of the buffer. By default, wrapscan is true.
The gdefault option affects the default behavior of the :s/old/new/ command.
It is false by default, which causes :s/old/new/ to assume a count of 1 so
only the first instance in each line is changed. Making gdefault true will
cause it change all instances in each line, as though the "g" flag had
been given. If you give an explicit count or "g" flag, then the value of
gdefault is ignored.
The edcompatible option causes elvis to remember any flags that are passed
into the :s/old/new/flags command, and use them as the default for the next
such command. Explicitly naming a flag will toggle that flag's value. This is
not the way the old ed editor worked, but this option's name and behavior are
traditional in vi. This option is false by default.
The saveregexp option is normally true, which causes elvis to remember each
regular expression. If, in a latter command, you give an empty regular
expression, then elvis will recall the saved regular expression instead. This
also affects the n and N commands. You may wish to turn this option off
temporarily in a the lib/elvis.arf file if you're using any regular
expressions there, so that loading a file doesn't interfere with n and N.
6.1.12 Tag options
.---------------------.---------.--------.-----------------------------.
| OPTION NAMES | TYPE | GROUP | DESCRIPTION |
|---------------------|---------|--------|-----------------------------|
| taglength, tl | Number | global | significant length of tags |
| tags, tagpath | String | global | list of possible tag files |
| tagstack, tsk | Boolean | global | remember origin of tag srch |
| tagprg, tp | String | global | external tag search program |
| tagprgonce, tpo | String | global | like tagprg, but auto-resets|
^---------------------^---------^--------^-----------------------------^
These options control how elvis performs tag lookup, as for the :tag ex
command or the ^] visual command. You should also check out the previoustag
and showtag options.
The taglength option defines how many characters are significant in a tag
name. By default this option is set to 0, which is a special value indicating
that all characters are significant. If you have a lot of long names, you
might want to set this to some other value so that you could type in
abbreviated names.
The tags option stores a list of filenames or directory names where tags are
stored. (For directory names, it looks for a file named "tags" in that
directory.) When performing tag lookup, elvis will begin by looking for it in
the first directory/file mentioned in the list; if it doesn't find it there,
then it moves on to the next one, and so on. By default, it just looks in a
file named "tags" in the current directory.
In a path, names which start with "./" (or ".\" in MS-Windows) are assumed to
be relative to the directory of the current file. This means that ":set
tags=./tags:tags" will cause elvis to first check the "tags" file in the
directory of the current text file, and then the "tags" file in the current
directory.
NOTE: Traditionally, this elements in this path have been space-delimited.
Since every other path in any other context is either colon-delimited (for
Unix) or semicolon-delimited (for Microsoft), and it is becoming more common
for filenames to contain spaces, elvis uses colons or semicolons for the tag
path too. This makes elvis' "tags" settings incompatible with other versions
of vi, though.
If the tagstack option is true, then before switching to the file and location
of a looked-up tag, elvis will store the original file and position on a
stack. Later, you can use the :pop or visual ^T commands to return to your
original position. If tagstack is false, then the tag stack is unaffected by
tag look-up. It is true by default.
If the tagprg option is set to any value other than "", then whenever you try
to do a tag search via :tag or :browse, elvis will execute tagprg's value as a
shell command and interpret its stdout as a list of matching tags. Before the
command is run, it is evaluated using the simpler expression syntax with $1
indicating where the arguments should go. The default value of tagprg is ""
which causes elvis to use the internal tag search algorithm.
The tagprgonce options acts just like the tagprg option, except that
tagprgonce automatically reverts to "" the first time it is used. If tagprg
and tagprgonce are both set, then tagprgonce is used. It exists mostly so you
can easily write aliases which perform specialized searches, without
interfering with normal tag searches. The following example creates a new
:text command which finds instances of a given text string in any *.c or *.h
files. (Note that the "set tagprgonce..." command should be entered on one
line; it is shown here on three lines simply as a typographical convenience.)
:alias text {
set tagprgonce="grep -nsw '(quote(\"'\",$1))' *.[ch] /dev/null \|
sed 's/^\\\\\\(.*\\\\\\):\\\\\\(.*\\\\\\):.*/!^ \\1 \\2/'"
tag!? !*
}
NOTE: You might also consider using the ccprg option for this sort of thing,
since the :cc command has a smarter line parser than the :tag command.
6.1.13 Window update parameters
.---------------------.---------.--------.-----------------------------.
| OPTION NAMES | TYPE | GROUP | DESCRIPTION |
|---------------------|---------|--------|-----------------------------|
| exrefresh, er | Boolean | global | redraw scrn after each line |
| nearscroll, ns | Number | global | scroll vs. jump¢er param|
| wrap | Boolean | win | how long lines are displayed|
| sidescroll, ss | Number | win | sideways scrolling amount |
| optimize, op | Boolean | global | run faster |
| animation, anim | Number | global | animation macro speed |
| window, wi | Number | global | lines to show for :z command|
| pollfrequency, pf | Number | global | rate of testing for ^C |
| maptrace, mt | One of | global | debugger: off, run, or step |
| maplog, mlog | One of | global | logging: off, reset, append |
^---------------------^---------^--------^-----------------------------^
The exrefresh option affects the frequency of window updates when in EX mode.
It is normally false, which causes the window to be refreshed at the end of
each EX command. If you set exrefresh to true, then elvis will update the
window's image every time an output line is generated; this makes the command
run much slower, but gives you more feedback.
The nearscroll option controls elvis' behavior when the cursor is moved off
the top or bottom of the window. If the new cursor position is within
nearscroll lines of the window, then the window is scrolled to bring the new
line into view. If the new cursor position is outside that range, then elvis
uses a "jump and center" approach, in which the window's image is drawn from
scratch with the new cursor line shown in the center of the window. Its
default value is 5.
The wrap option determines how elvis will display lines which are too long to
fit on a single row of the display. It is true by default, which causes long
lines to be wrapped onto multiple rows of the display. This is the traditional
vi behavior. Changing it to false will cause long lines to be partially
displayed on a single row of the display; you can scroll sideways to reveal
the rest of the line my moving the cursor onto it, and then off the edge.
If the wrap option is false (indicating that long lines should be displayed
via side-scrolling) then the sidescroll option controls the scrolling
increment. The default is 8, so the display will scroll sideways in chunks of
8 characters at a time.
The optimize option affects the efficiency of screen updates. It is normally
true, which tells elvis to update the screen image only when it must wait for
user input. If you make it false, then elvis will update the screen after
every command; among other things, this allows you to see intermediate effects
of macros.
The animation option is similar. When the optimize option is true, elvis still
refreshes the screen periodically while executing a large macro so that
animation macros can be seen in all their glory. Elvis attempts to figure out
which macros are loops, and when one of those macros is invoked elvis
considers updating the screen. If animation=1 then elvis updates the screen
every time; when animation=2 it updates the screen an alternate invocations of
those macros, and so on. The default, chosen simply through experimentation,
is 3.
Sometimes elvis will choose the wrong macros to refresh. If that happens, then
try running the macro with optimize option turned off. For example, the
bouncing ball macros look better with optimize turned off.
The window option stores the default number of lines to be displayed by the :z
command. Historically it has also been used for forcing vi to update only a
portion of the screen, but elvis doesn't use it for that.
When elvis is performing some time-consuming operations, such as a global
substitution, it will periodically check to see if the user is trying to
cancel the operation. For some user interfaces, this inspection takes a
significant amount of time so elvis allows the pollfrequency option to reduce
the frequency of these checks. The default is 20. Larger values of
pollfrequency will make global substitutions run faster; smaller values make
elvis respond to ^C sooner.
The maptrace option controls elvis' built-in macro debugger. It can be off,
run or step. The default is off, which causes macros to run normally. If you
change it to run then elvis will display the contents of the mapping queue at
the bottom of the screen while running any macro. The step value also displays
the mapping queue, but then waits for a keystroke before proceeding. If the
keystroke is ^C then the macro is terminated. If the keystroke is r then
maptrace is set to run. Any other keystroke causes elvis to pause again after
processing the macro's next character. See section 16.3 How to debug macros
for more suggestions for debugging macros.
The maplog option can be used to log the information displayed by the maptrace
option. It also logs any ex commands that are executed, other than those that
you enter manually. It is off by default. Setting it to append causes the map
trace information to be appended to an internal edit buffer named "Elvis map
log". Setting it to reset causes that buffer to be clobbered before the next
map trace; when that happens, maplog will be automatically switched to append.
You can view the logged data via the command...
:("Eml)sp
or the long version, ":(Elvis map log)split".
6.1.14 Cache options
.---------------------.---------.--------.-----------------------------.
| OPTION NAMES | TYPE | GROUP | DESCRIPTION |
|---------------------|---------|--------|-----------------------------|
| blkcache, cache | Number | global | number of blocks in cache |
| blksize, bsz | Number | global | size of cache block |
| blkfill, bfill | Number | global | initial chars per text block|
| blkhash, hash | Number | global | size of cache hash table |
| blkgrow, bgr | Number | global | allocation table parameter |
| blkhit, bh | Number | global | # of block requests in cache|
| blkmiss, bm | Number | global | # of block req. not in cache|
| blkwrite, bw | Number | global | # of blocks written |
| sync | Boolean | global | force changes to disk |
^---------------------^---------^--------^-----------------------------^
You probably don't need to know about the "blk" options. The blkcache option
indicates how many blocks from the session file elvis should keep in its own
internal cache, and blkhit and blkmiss can be used to gauge the efficiency of
the cache. blkwrite indicates how many blocks have been written to the session
file. The blksize option indicates the size of each block, blkfill indicates
how many characters should be stuffed into each block initially (leaving room
for more text that the user may insert later), and blkhash and blkgrow affect
a couple of internal tables.
Note that the value of blksize can only be set via the -bblksize command line
flag, and its value must be a power of 2 in the range [512, 8192]. You can't
change blksize after elvis has started (not even in configuration scripts),
because by then the session file has already been created with the other block
size.
If the sync option is true, then elvis will flush all dirty blocks from its
cache at the end of each edit command. Doing this will just about guarantee
that you can recover your changes after a crash, but it can slow down the
computer tremendously. The sync option is false by default, and on multi-user
systems it should be left that way. On a single-user system, you might
consider setting the sync option.
6.1.15 Options that describe the system
.---------------------.---------.--------.-----------------------------.
| OPTION NAMES | TYPE | GROUP | DESCRIPTION |
|---------------------|---------|--------|-----------------------------|
| version, ver | String | global | elvis version number (2.1) |
| bitsperchar, bits | Number | global | character size (always 8) |
| gui | String | global | name of user interface |
| os | String | global | name of operating system |
| program, argv0 | String | global | invocation name of elvis |
| session, ses | String | global | name of session file |
| tempsession, temp | Boolean | global | delete session file on exit |
| newsession, newses | Boolean | global | session file is new |
| recovering, rflag | Boolean | global | recovering after a crash |
| exitcode, exit | Number | global | exit code of elvis process |
^---------------------^---------^--------^-----------------------------^
The version option stores the version number of elvis -- currently "2.1". If
later versions of elvis have features which are incompatible with this
version, your script files can use this to check the version number, and skip
the uncompatible commands.
The bitsperchar option indicates the size of characters that elvis uses
internally. Currently this is always 8, but I expect to support 16-bit
characters eventually.
The gui option indicates which user interface is being used. This can be handy
in your initialization files. For example, you might prefer white characters
on a blue background when using the "termcap" interface, and black characters
on a white background when using the "x11" interface.
The os option allows elvis' initialization files to act differently on
different operating systems. Its value indicates the name of the local
operating system.
The program option stores the name by which elvis was invoked; i.e., the value
of argv[0]. Typical values would be "elvis" under UNIX, "elvis.exe" under
Win32, or "C:\BIN\ELVIS.EXE" under MS-DOS. The default elvis.ini file
evaluates tolower(basename(program)) and compares the result to "ex" and
"view", to set the initialstate and defaultreadonly options, respectively.
The session option stores the name of the current session file. There is
rarely any need to check this, but I had to store it someplace and it might as
well be accessible, I figured.
The tempsession, newsession, and recovering options describe different aspects
of the session file. If tempsession is true, then elvis will delete the
session file when it exits. If newsession is true, then elvis has just created
the file so there may be extra initialization that needs to take place in
elvis.ini or someplace. If recovering is true, then the session file may be
damaged, so it may be a good idea to skip some initialization steps, or
automatically write out all user buffers.
The exitcode is the value that elvis will return to its parent process when
the elvis process exits. Initially this is 0, which is the conventional
indication of a normal, successful exit. You can explicitly set it to other
values to indicate special situations. Also, if elvis outputs an error message
and exitcode has not been explicitly set, then elvis changes exitcode to 1, so
the parent process can know that elvis had an error.
6.1.16 External programs
.---------------------.---------.--------.-----------------------------.
| OPTION NAMES | TYPE | GROUP | DESCRIPTION |
|---------------------|---------|--------|-----------------------------|
| ccprg, cp | String | buf | shell command for :cc |
| makeprg, mp | String | buf | shell command for :make |
| anyerror, ae | Boolean | global | allow :errlist if readonly |
| equalprg, ep | String | buf | shell command for = operator|
| keywordprg, kp | String | buf | shell command for K command |
| shell, sh | String | global | name of shell program |
| warn | Boolean | global | warn if file not saved |
^---------------------^---------^--------^-----------------------------^
The ccprg and makeprg are the programs used by the :cc and :make commands.
Before the program strings are executed, they are subjected to the same sort
of expression evaluation as the :eval command, with $1 representing any extra
arguments from the ex command line, and $2 representing the name of the
current file. Their defaults are cc="cc ($1?$1:$2)" and make="make $1".
When searching for error messages after a :cc or :make command, elvis will
normally ignore errors about files that you don't have write access to.
Usually this is convenient, because it prevents elvis from reading header
files that you've misused. However, setting anyerror to true will make it read
any file that generates a complaint, even if you can't write to it.
The equalprg option stores the name of a program to be executed for the visual
= operator command. Its default value is "fmt", which is a simple text
formatting program.
The keywordprg option stores the name of the program used by the visual K
command. This string is evaluated with $1 being replaced with the word under
the cursor at that time, and $2 the name of the current file. The default
value is "ref $1 file:$2"; the ref program looks up a tag and displays it. If
you're using the x11 user interface, then you might want try the following,
which causes the function's header to be displayed in a separate pop-up
window:
set kp="ref $1 file:$2 2>&1 \| xmessage -file - >/dev/null 2>&1 &"
The shell option stores the name of the system's command-line interpreter. It
is used when executing all of the above programs, as well as commands entered
for the EX :! and visual ! commands. Its default value is system-dependent;
typically it will be "/bin/sh" for UNIX, and "C:\COMMAND.COM" for MS-DOS.
When any external program is executed, if the current buffer has been changed
but not written out to the file, then elvis will normally give a warning
message. Setting the warn option to false disables this message.
6.1.17 Directory names
.---------------------.---------.--------.-----------------------------.
| OPTION NAMES | TYPE | GROUP | DESCRIPTION |
|---------------------|---------|--------|-----------------------------|
| home | String | global | home directory |
| elvispath, epath | String | global | list of possible config dirs|
| sessionpath, spath | String | global | list of possible session dir|
| directory, dir | String | global | where to store temp files |
^---------------------^---------^--------^-----------------------------^
The home option is the name of your home directory. The value of this option
is used for replacing the ~ character at the start of a full pathname. If an
environment variable named HOME exists, then home is initialized from its
value. Otherwise, its default value is set as follows:
For UNIX:
The default is "/".
For Win32:
The default is derived from environment variables named HOMEDRIVE
and HOMEPATH, which will normally always be defined. Their default
value is usually "C:\users\default". If either of those environment
variables is undefined, then elvis will attempt to find the pathname
of the program, and use its directory. As a last resort, elvis will
use "C:\" as the default home directory.
For OS/2:
The default home directory is the one containing ELVIS.EXE, or if
that can't be found then it will use "C:\" as the default home
directory.
For MS-DOS:
The default home directory is the one containing ELVIS.EXE.
The elvispath option stores a list of directory names where elvis might find
its configuration files. If there is an ELVISPATH environment variable, then
the elvispath option is initialized from the value of ELVISPATH. Otherwise it
is set to a value such as "~/.elvislib:/usr/local/lib/elvis" so that elvis
will search first in a subdirectory of the user's home directory, and then in
the directory where the standard versions of those files were installed. A
path like this allows users to override elvis' behavior if they want. The
default value depends the operating system, as follows:
For UNIX:
The default contains ~/.elvislib and the directory that you
specified as the data directory when you ran the configure script.
(E.g, "configure --datadir=/usr/lib/elvis") The default data
directory is /usr/local/lib/elvis, so usually elvispath will default
to "~/.elvislib:/usr/local/lib/elvis".
For Win32, OS/2, or MS-DOS:
The default contains ~\elvislib, and the directory where elvis.exe
resides, and a subdirectory under that named "lib". For example, if
elvis is installed as C:\elvis\elvis.exe then elvispath would be
~\elvislib;C:\elvis;C:\elvis\lib.
The sessionpath option gives elvis a list of possible directories where
session files might be placed. Elvis uses the first writable directory in that
list, and ignores all of the others. The default value depends on the
operating system, and can be overridden by the SESSIONPATH environment
variable. You can't change the sessionpath option after elvis has started,
because the session file has already been created by then.
The directory option gives the name of the directory where elvis will store
its temporary files. The default value is system-dependent. Note that this is
not where the session file is stored; the session option gives the name of the
session file.
6.1.18 Initialization options
.---------------------.---------.--------.-----------------------------.
| OPTION NAMES | TYPE | GROUP | DESCRIPTION |
|---------------------|---------|--------|-----------------------------|
| exrc, ex | Boolean | global | interpret ./.exrc file |
| modeline, ml | Boolean | global | interpret modelines |
| modelines, mls | Number | global | positions of modelines |
| safer, trapunsafe | Boolean | global | be paranoid |
| initialstate, is | One-Of | global | command mode of new windows |
^---------------------^---------^--------^-----------------------------^
The exrc option has no built-in meaning to elvis, however the default
elvis.ini file uses this option to determine whether it should look for a
".exrc" file in the current directory.
The modeline option controls whether elvis will look for modelines in each
buffer after it has been loaded from a file. If modelines is true, then elvis
will search through the first and last modelines lines of the buffer for
something that looks like "ex:commands:" or "vi:commands:" and if found, it
executes the commands as an ex command line. This is typically used for
changing tabstops and the like. The modeline option is false by default, and
modelines is 5.
The safer option closes some security holes. It is intended to make modelines
and a .exrc file in the current directory safe to use, but I'm not making any
promises. When the "safer" option is true, certain commands are disabled,
wildcard expansion in filenames is disabled, and certain options are locked
(including the safer option itself). Typically you will use the ex command
:safer to execute an untrusted file, and :source to execute a trusted one,
rather than futz with the value of the safer option directly.
The initialstate option determines what command mode new windows will start
in. It can be one of input, replace, vi, or ex. The default is vi, the visual
command mode.
6.1.19 Keyboard map options
.---------------------.---------.--------.-----------------------------.
| OPTION NAMES | TYPE | GROUP | DESCRIPTION |
|---------------------|---------|--------|-----------------------------|
| remap | Boolean | global | allow key maps to use maps |
| keytime, kt | Number | global | timeout for function keys |
| usertime, ut | Number | global | timeout for multi-key maps |
^---------------------^---------^--------^-----------------------------^
Elvis allows keystrokes to be mapped via the :map command. Once a map has
been defined, these options control how and when those maps are recognized.
The remap option controls how many times elvis will attempt to reapply key
maps. If the remap option is true (the default), then elvis will repeatedly
attempt to reapply maps as long as there are any that match. This means that
maps can be written to use other maps, allowing some very complex behavior. If
remap is false, then it will attempt to apply maps only once, so the result of
any map is not altered any further. By default, remap is true.
The keytime and usertime options come into play when characters are received
which partially match one or more maps. For example, suppose the arrow keys
are mapped to h, j, k, and l, those arrow keys send escape sequences when
pressed, and elvis has just received an escape character. How can it tell
whether the user hit the Esc key or an arrow key?
In this situation, elvis must perform a read-keystrokes-with-timeout operation
to determine which map applies, if any. If all of the partially matching maps
are for special keys such as function keys, then elvis will use the keytime
value. If at least one of them is for a user map, then elvis will use the
usertime value. Either way, the values indicate the time, in tenths of a
second, that elvis should allow for the rest of the map characters to arrive.
If they don't arrive, then none of the partially matching maps is used.
Typically, the usertime value will be much longer than the keytime value,
because the user must hit a series of keys for a user map. For example, many
people like to create maps consisting of a semicolon and one or two following
letters. (If you're a touch typist, then your right-hand pinky normally rests
on the semicolon key, so this is convenient.) By distinguishing between key
maps and user maps, elvis can give quick response to the Esc while still
allowing users to key in their own keymaps at a leisurely pace. Their default
values are keytime=3 and usertime=15.
6.1.20 Printing options
.---------------------.---------.--------.-----------------------------.
| OPTION NAMES | TYPE | GROUP | DESCRIPTION |
|---------------------|---------|--------|-----------------------------|
| lptype, lpt | String | lp | printer type |
| lpconvert, lpcvt | Boolean | lp | convert Latin-1 to PC-8 |
| lpcrlf, lpc | Boolean | lp | printer needs CR-LF newline |
| lpout, lpo | String | lp | printer file or filter |
| lpcolumns, lpcols | Number | lp | width of printer page |
| lpwrap, lpw | Boolean | lp | simulate line-wrap |
| lplines, lprows | Number | lp | length of printer page |
| lpnumber, lpn | Boolean | lp | print line numbers in margin|
| lpheader, lph | Boolean | lp | print header at top of page |
| lpformfeed, lpff | Boolean | lp | send form-feed after last pg|
| lppaper, lpp | String | lp | paper size (letter, a4, ...)|
| lpcolor, lpcl | Boolean | lp | use colors when printing |
^---------------------^---------^--------^-----------------------------^
These options all affect hardcopy output, done via the :lpr command. Note
that these options are in a separate group, so you can display all of them by
giving the command "se lp?".
The lptype option lets elvis know what type of printer you're using, so it can
use the correct escape codes (or whatever) to switch fonts. The default is
"dumb" because it is the most conservative value, but it is also the least
expressive. (Exception: When using the Win32 user interface, the default is
"windows".) You should set lptype to one of the following values:
.---------.---------------------------------------------.
| VALUE | PRINTER DESCRIPTION |
|---------|---------------------------------------------|
| ps | PostScript, one logical page per sheet |
| ps2 | PostScript, two logical pages per sheet |
| epson | Most dot-matrix printers, no graphic chars |
| pana | Panasonic dot-matrix printers |
| ibm | Dot-matrix printers with IBM graphic chars |
| hp | HP printers, and most non-PostScript lasers |
| cr | Line printers, overtypes via carriage-return|
| bs | Overtypes via backspace, like nroff |
| dumb | Plain ASCII, no font control |
|-- --- --|-- --- --- --- --- --- --- --- --- --- --- --|
| windows | The Win32 print facility (in WinElvis only) |
^---------^---------------------------------------------^
The lpconvert option, when set, causes some printer types to convert
non-ASCII Latin-1 characters to PC-8 characters. Most computers use Latin-1
internally for storing text, but many printers use PC-8; hence the need for
conversion. This option has no effect on ASCII characters because they never
need conversion. This option is ignored if your computer doesn't appear to be
using Latin-1 (or, more precisely, if there is no digraph which maps AE to
0xc6, the Latin-1 code for the Γò₧ ligature.) This option is false by default.
NOTE: Not all printer types obey the lpconvert option. Postscript printers
don't do conversion because they use Latin-1 themselves. The "cr", "bs", and
"dumb" printer types ignore it simply because they are typically used for
writing to files, not actual printers, and as long as the text remains in the
computer no conversion is necessary. Only the "epson", "pana", "ibm", and "hp"
printers will obey the lpconvert option.
The lpcrlf option forces elvis to convert each newline character to a CR/LF
pair. Some printers, on some systems, require this. Most don't, so this
option is false by default. If you attempt to print something and only the
first line is visible, or the text is badly jumbled, then try ":set lpcrlf"
and maybe that'll fix it.
The lpout option should be either the name of a file or device (such as "prn"
or "/dev/lp0") to which the printer output should be sent, or ! character
followed by a shell command (such as "!lp -s") which reads printer text from
stdin and submits it to the printer spooler. The default is system dependent.
The lpcolumns option tells elvis how wide the printer page is. The default is
80 columns. If you have a wide-carriage printer, you may wish to set
lpcolumns=132. If you have a postscript printer and set lpcolumns to a value
greater than 80, elvis will compress the characters to make the longer lines
fit.
The lpwrap option tells elvis how to handle lines that are wider than
lpcolumns. If this options is true (the default) then long lines will wrap
onto multiple printed lines. If lpwrap is false, then it will clip long lines.
The lplines option tells elvis how long the usable portion of each page is;
i.e., how many lines it should print on each page. The default is 60. Some
display modes ("html" and "man") print headers at the top of each page; those
lines are included in the lplines count. Setting lplines=0 causes elvis to
assume that pages are infinitely long, which sounds about right for fan-fold
printer paper. If you have a PostScript printer and set lplines to a value
greater than 60, then the page will be compressed vertically to make it fit.
The lpnumber option does to printouts what the number option does for a window
-- it causes the line number to be output in the left margin. If the buffer's
bufdisplay option is "normal" or "syntax", then it also causes a header to be
printed at the top of each page, showing the file name, page number, and
date/time when the printout was created.
The lpheader option controls whether printouts will have a line at the top of
each page showing the file name, date, and page number. It only affects the
normal, syntax, and hex display modes; the others always have a header.
The lpformfeed option controls whether elvis will send a form-feed control
character after the last page of any print job. This should generally be false
if you're printing through a print spooler program, because print spoolers
usually add the final formfeed themselves. Under MS-DOS, elvis is normally
configured to send the text directly to the printer device, prn, and you may
wish to set the lpformfeed option there.
The lppaper option is only significant for PostScript printers. The value of
lppaper is inserted into the PostScript output before the contents of the
elvis.ps file. elvis.ps contains code which scales the output to fit on the
paper. The default version supports letter, legal, executive, a4 and a3 paper
sizes. Adding new paper sizes to that file is fairly easy. You should be
careful when setting lppaper because elvis won't prevent you from setting it
to an unsupported value. The default value is letter.
The lpcolor option is currently only supported for the "windows" printer type
under Microsoft Windows95/98/NT. When true, it allows printouts to use color
for the foreground. (The background is always white.) Normally it is false
(nolpcolor), which forces all printouts to use black since that usually prints
faster and looks better, and is always less expensive.
6.1.21 Previous arguments
.---------------------.---------.--------.-----------------------------.
| OPTION NAMES | TYPE | GROUP | DESCRIPTION |
|---------------------|---------|--------|-----------------------------|
| previousdir, pdir | String | global | previous directory name |
| previousfile | String | global | name of alternate file |
| previousfileline | Number | global | line# from previousfile |
| previouscommand | String | global | previous shell command line |
| previoustag, ptag | String | global | previous search tag |
^---------------------^---------^--------^-----------------------------^
These options all store the previous value of some type of input, so that the
same value can be used again later. You can set these options, but there
really isn't much point to it, usually.
The previousdir option stores the name of the previous working directory.
Initially it is set from the value of the $OLDPWD environment variable. After
that, each :cd command will store the old current working directory into this
option before switching to the new working directory. If you give elvis a
file name which begins with "~-", elvis will replace the "~-" with the value
of this option.
The previousfile option stores the name of an alternate file. Usually this is
the name of the last file you mentioned, other than that of the current file.
When you switch from one file to another, the name of the previous file is
stored here, along with the line number (in previousfileline), so you can
easily bounce between this file and the previous one. Whenever you type in a
filename as an argument to an ex command, any instances of the # character are
replaced by the value of previousfile.
The previouscommand option stores the last shell command you typed in. When
you enter the next shell command line, any instances of the ! character will
be replaced by the value of previouscommand.
The previoustag option stores the name of the last tag you looked up. This
value is also stored on the tagstack in the hope that it may help you remember
where you were when you performed all of your recent tag lookups.
6.1.22 Unsupported options
.---------------------.---------.--------.-----------------------------.
| OPTION NAMES | TYPE | GROUP | DESCRIPTION |
|---------------------|---------|--------|-----------------------------|
| hardtabs, ht | Number | global | width of terminal's tabs |
| mesg | Boolean | global | disable SysAdmin messages |
| more, mo | Boolean | global | allow "Hit <Enter>" prompt |
| novice | Boolean | global | beginner mode |
| redraw | Boolean | global | redraw screen during input |
^---------------------^---------^--------^-----------------------------^
The hardtabs, mesg, more, novice, and redraw options exist in elvis, but
they don't do anything. Perhaps some day...
6.1.23 User variables
.---------------------.---------.--------.-----------------------------.
| OPTION NAMES | TYPE | GROUP | DESCRIPTION |
|---------------------|---------|--------|-----------------------------|
| a | String | user | user variable |
| b | String | user | user variable |
| c | String | user | user variable |
| d | String | user | user variable |
| e | String | user | user variable |
| f | String | user | user variable |
| g | String | user | user variable |
| h | String | user | user variable |
| i | String | user | user variable |
| j | String | user | user variable |
| k | String | user | user variable |
| l | String | user | user variable |
| m | String | user | user variable |
| n | String | user | user variable |
| o | String | user | user variable |
| p | String | user | user variable |
| q | String | user | user variable |
| r | String | user | user variable |
| s | String | user | user variable |
| t | String | user | user variable |
| u | String | user | user variable |
| v | String | user | user variable |
| w | String | user | user variable |
| x | String | user | user variable |
| y | String | user | user variable |
| z | String | user | user variable |
^---------------------^---------^--------^-----------------------------^
These one-letter options have no preset purpose. They are useful
for holding temporary values which you expect to use in an expression later.
These are all string values, but because the expression evaluator doesn't
distinguish between a number and a string which happens to look like number,
you can also use these as numbers. For example, the command...
:let i=i+1
...does exactly what you would expect.
6.2 Alphabetical list of options
.---------------------.---------.--------.-----------------------------.
| OPTION NAMES | TYPE | GROUP | DESCRIPTION |
|---------------------|---------|--------|-----------------------------|
| a | String | user | user variable |
| altkey, metakey | One of | x11 | effect of the Alt key |
| animation, anim | Number | global | animation macro speed |
| anyerror, ae | Boolean | global | allow :errlist if readonly |
| autoiconify, aic | Boolean | x11 | iconify old window |
| autoindent, ai | Boolean | buf | auto-indent new text |
| autoprint, ap | Boolean | global | print current line in ex |
| autoselect, as | Boolean | global | visibly mark searched text |
| autotab, at | Boolean | buf | allow autoindent to use '\t'|
| autowrite, aw | Boolean | global | save file before switching |
| b | String | user | user variable |
| backup, bk | Boolean | global | make *.bak file before write|
| beautify, bf | Boolean | global | strip ctrl chars from files |
| bitsperchar, bits | Number | global | character size (always 8) |
| blkcache, cache | Number | global | number of blocks in cache |
| blkfill, bfill | Number | global | initial chars per text block|
| blkgrow, bgr | Number | global | allocation table parameter |
| blkhash, hash | Number | global | size of cache hash table |
| blkhit, bh | Number | global | # of block requests in cache|
| blkmiss, bm | Number | global | # of block req. not in cache|
| blksize, bsz | Number | global | size of cache block |
| boldstyle, bfn | String | windows| n or combination of b/i/u |
| boldfont, xfb | String | x11 | name of bold font |
| borderwidth, xbw | Number | x11 | size of text area's border |
| bufchars, bc | Number | buf | number of characters |
| bufdisplay, bd | String | buf | default display mode |
| bufid, bufferid | Number | buf | ID number of user buffer |
| buflines, bl | Number | buf | number of lines |
| bufname, buffer | String | buf | name of buffer |
| c | String | user | user variable |
| ccprg, cp | String | buf | shell command for :cc |
| codepage, cpg | Number | win32 | console character set |
| columns, cols | Number | win | width of window |
| commentfont, cfont | One-Of | syntax | font used for comments |
| d | String | user | user variable |
| dblclicktime, xdct | Number | x11 | double-click milliseconds |
| defaultreadonly, dro| Boolean | global | assume all files readonly |
| digraph, dig | Boolean | global | allow X-backspace-Y entry |
| directory, dir | String | global | where to store temp files |
| display, mode | String | win | name of current display mode|
| e | String | user | user variable |
| edcompatible, ed | Boolean | global | remember regsub flags |
| edited, samename | Boolean | buf | buffer loaded from filename |
| elvispath, epath | String | global | list of possible config dirs|
| emphasizedstyle, efn| String | windows| n or combination of b/i/u |
| equalprg, ep | String | buf | shell command for = operator|
| errlines | Number | buf | buflines when :make was run |
| errorbells, eb | Boolean | global | ring bell for error message |
| exitcode, exit | Number | global | exit code of elvis process |
| completebinary, cob | Boolean | global | complete names of binaries? |
| exrc, ex | Boolean | global | interpret ./.exrc file |
| exrefresh, er | Boolean | global | redraw scrn after each line |
| f | String | user | user variable |
| filename, file | String | buf | name of file in buffer |
| firstx, xpos | Number | x11 | horiz. position of first win|
| firsty, ypos | Number | x11 | vert. position of first win |
| fixedstyle, ffn | String | windows| n or combination of b/i/u |
| flash, vbell | Boolean | global | substitute flash for bell |
| focusnew, fn | Boolean | x11 | force focus into new window |
| font, fnt | String | windows| base font |
| functionfont, ffont | One-Of | syntax | font used for function names|
| g | String | user | user variable |
| gdefault, gd | Boolean | global | default change all instances|
| gui | String | global | name of user interface |
| h | String | user | user variable |
| hardtabs, ht | Number | global | width of terminal's tabs |
| home | String | global | home directory |
| i | String | user | user variable |
| icon | Boolean | x11 | use the built-in icon? |
| ignorecase, ic | Boolean | global | regexp uppercase=lowercase |
| initialstate, is | One-Of | global | command mode of new windows |
| inputtab, itab | One-Of | buf | input mode's (Tab) key |
| internal | Boolean | buf | elvis requires this buffer |
| italicstyle, ifn | String | windows| n or combination of b/i/u |
| italicfont, xfi | String | x11 | name of italic font |
| j | String | user | user variable |
| k | String | user | user variable |
| keytime, kt | Number | global | timeout for function keys |
| keywordfont, kfont | One-Of | syntax | font used for reserved words|
| keywordprg, kp | String | buf | shell command for K command |
| l | String | user | user variable |
| lines, rows | Number | win | height of window |
| list, li | Boolean | win | show markups, newlines, etc.|
| locked, lock | Boolean | win | prevent any alterations |
| lpcolor, lpcl | Boolean | lp | use colors when printing |
| lpcolumns, lpcols | Number | lp | width of printer page |
| lpcrlf, lpc | Boolean | lp | printer needs CR-LF newline |
| lpformfeed, lpff | Boolean | lp | send form-feed after last pg|
| lpheader, lph | Boolean | lp | print header at top of page |
| lplines, lprows | Number | lp | length of printer page |
| lpnumber, lpn | Boolean | lp | print line numbers in margin|
| lpout, lpo | String | lp | printer file or filter |
| lppaper, lpp | String | lp | paper size (letter, a4, ...)|
| lptype, lpt | String | lp | printer type |
| lpwrap, lpw | Boolean | lp | simulate line-wrap |
| m | String | user | user variable |
| magic, ma | Boolean | global | use normal regexp syntax |
| makeprg, mp | String | buf | shell command for :make |
| maplog, mlog | One of | global | logging: off, reset, append |
| maptrace, mt | One of | global | debugger: off, run, or step |
| mesg | Boolean | global | disable SysAdmin messages |
| modeline, ml | Boolean | global | interpret modelines |
| modelines, mls | Number | global | positions of modelines |
| modified, mod | Boolean | buf | buffer differs from file |
| n | String | user | user variable |
| nearscroll, ns | Number | global | scroll vs. jump¢er param|
| newfile, new | Boolean | buf | filename doesn't exist yet |
| newsession, newses | Boolean | global | session file is new |
| nonascii, asc | One-Of | global | how to display non-ascii |
| normalstyle, nfn | String | windows| n or combination of b/i/u |
| normalfont, xfn | String | x11 | name of normal font |
| novice | Boolean | global | beginner mode |
| number, nu | Boolean | win | display line numbers |
| o | String | user | user variable |
| optimize, opt | Boolean | global | run faster |
| optionwidth, ow | Number | global | widths of ":set all" values |
| os | String | global | name of operating system |
| otherfont, ofont | One-Of | syntax | font used for other symbols |
| outlinemono, om | Number | x11 | char outlining for X11-mono |
| p | String | user | user variable |
| paragraphs, para | String | buf | nroff paragraph commands |
| partiallastline, pll| Boolean | buf | file didn't end with newline|
| pollfrequency, pf | Number | global | rate of testing for ^C |
| prepfont, pfont | One-Of | syntax | font used for preprocessor |
| previouscommand | String | global | previous shell command line |
| previousdir, pdir | String | global | previous directory name |
| previousfile | String | global | name of alternate file |
| previousfileline | Number | global | line# from previousfile |
| previoustag, ptag | String | global | previous search tag |
| program, argv0 | String | global | invocation name of elvis |
| prompt | Boolean | global | issue ":" prompt in ex mode |
| putstyle, ps | One of | buf | type of text in a cut buffer|
| q | String | user | user variable |
| r | String | user | user variable |
| readeol, reol | One of | buf | newline mode when reading |
| readonly, ro | Boolean | buf | don't overwrite filename |
| recovering, rflag | Boolean | global | recovering after a crash |
| redraw | Boolean | global | redraw screen during input |
| remap | Boolean | global | allow key maps to use maps |
| report | Number | global | minimum # lines to report |
| retain, ret | Boolean | buf | keep buffer in session file |
| ruler, ru | Boolean | win | display cursor's line/column|
| s | String | user | user variable |
| safer, trapunsafe | Boolean | global | be paranoid |
| saveregexp, sre | Boolean | global | remember regexp to use as //|
| scroll, scr | Number | win | scroll amount for ^D/^U |
| scrollbar, sb | Boolean | (gui) | enable the scrollbar |
| scrollbarleft, xsl | Boolean | x11 | draw scrollbar on left side |
| scrollbartime, xst | Number | x11 | delay for scrollbar repeat |
| scrollbarwidth, xsw | Number | x11 | size of scrollbar, in pixels|
| sections, sect | String | buf | nroff section commands |
| sentenceend, se | String | global | punct at end of sentence |
| sentencegap, sg | Number | global | spaces required after sq |
| sentencequote, sq | String | global | punct allowed after se |
| session, ses | String | global | name of session file |
| sessionpath, spath | String | global | list of possible session dir|
| shell, sh | String | global | name of shell program |
| shiftwidth, sw | Number | buf | width used by < and > |
| showcmd, sc | Boolean | win | display command characters |
| showmarkups, smu | Boolean | global | show markup at cursor |
| showmatch, sm | Boolean | win | highlight matching parens |
| showmode, smd | Boolean | win | display the command state |
| showname, snm | Boolean | global | display the buffer name |
| showstack, sstk | Boolean | win | display some debugging info |
| showtag, st | Boolean | global | display tag on status line |
| sidescroll, ss | Number | win | sideways scrolling amount |
| stagger | Number | x11 | offset for next new window |
| statusbar, xstat | Boolean | x11 | enables the statusbar |
| stringfont, sfont | One-Of | syntax | font used for strings |
| sync | Boolean | global | force changes to disk |
| t | String | user | user variable |
| tabstop, ts | Number | buf | width of tabstop columns |
| taglength, tl | Number | global | significant length of tags |
| tagprg, tp | String | global | external tag search program |
| tagprgonce, tpo | String | global | like tagprg, but auto-resets|
| tags, tagpath | String | global | list of possible tag files |
| tagstack, tsk | Boolean | global | remember origin of tag srch |
| tempsession, temp | Boolean | global | delete session file on exit |
| term, ttytype | String | tcap | terminal's termcap entry |
| terse, te | Boolean | global | don't translate messages |
| textcursor, tc | Number | x11 | one of hollow, opaque, xor |
| textwidth, tw | Number | buf | width for word-wrap, or 0 |
| toolbar, tb | Boolean | (gui) | enable the toolbar |
| ttycolumns, ttycols | Number | tcap | width of screen |
| ttyrows, ttylines | Number | tcap | height of screen |
| ttyunderline, ttyu | Boolean | tcap | okay to mix color & underln |
| u | String | user | user variable |
| underline, uln | Boolean | x11 | enables underlining |
| underlinedstyle, nfn| String | windows| n or combination of b/i/u |
| undolevels, ul | Number | buf | number of undoable commands |
| usertime, ut | Number | global | timeout for multi-key maps |
| v | String | user | user variable |
| variablefont, vfont | One-Of | syntax | font used for variables |
| verbose | Boolean | global | give more status messages |
| w | String | user | user variable |
| warn | Boolean | global | warn if file not saved |
| warningbells, wb | Boolean | global | ring bell for warning msg |
| warpback, xwb | Boolean | x11 | upon exit, point to xterm |
| warpto, wt | One of | x11 | ^W^W forces pointer movement|
| window, wi | Number | global | lines to show for :z command|
| windowid, id | Number | win | ID number of current window |
| wrap | Boolean | win | how long lines are displayed|
| wrapmargin, wm | Boolean | win | set textwidth from right |
| wrapscan, ws | Boolean | global | searching wraps at EOF<->BOF|
| writeany, wa | Boolean | global | don't warn of existing file |
| writeeol, weol | One of | buf | newline mode when writing |
| x | String | user | user variable |
| xcolumns, xcols | Number | x11 | width of new windows |
| xrows, xlines | Number | x11 | height of new windows |
| y | String | user | user variable |
| z | String | user | user variable |
^---------------------^---------^--------^-----------------------------^
ΓòÉΓòÉΓòÉ 1.7. Elvis 2.1 Display Modes ΓòÉΓòÉΓòÉ
7. DISPLAY MODES
A "display mode" consists primarily of an algorithm that elvis uses internally
to convert the bytes in a buffer into an image in a window. The same algorithm
is also used for printing via the ":lpr" command.
The display mode also affects tag lookup, and image-dependent operations such
as determining the column number of the cursor's location, and moving the
cursor vertically.
You can list the supported display modes by giving the ":display" command
without any arguments. Typically, the supported modes will include the
following:
.--------.----------------------------------------------.
| MODE | DESCRIPTION |
|--------|----------------------------------------------|
| normal | Traditional vi, displays plain ASCII |
| syntax | Like "normal" but does syntax coloring |
| hex | Interactive hex dump, good for binary files |
| html | Simple Web page formatter |
| man | Simple Man page formatter, like "nroff -man" |
| tex | Simple subset of the TeX formatter |
^--------^----------------------------------------------^
Elvis 2.1 allows each window to be in a different display mode. You can
manually change a window's display mode via the ":display mode" command, where
mode is the name of a supported display mode. There is also a ":no" command,
which is short for ":display normal".
7.1 Options
There are two options which pertain to display modes: display and bufdisplay.
The display option is associated with a window. It always contains the name of
the window's current display mode. You aren't allowed to change the value of
this option directly; you must use the ":display mode" command to change the
display mode. This option exists solely so that you can write EX scripts which
behave differently, depending on the display mode.
The bufdisplay option is associated with a buffer. It should be set to the name
of the usual display mode for that buffer. Typically this option will be set
from the elvis.arf initialization file, based on the name of the file like
this:
let e=tolower(dirext(filename))
if knownsyntax(filename)
then set! bufdisplay=syntax
else if os=="unix" && buflines >= 1
then 1s/^#! *[^ ]*\/\([^ ]\+\).*/set! bufdisplay="syntax \1"/x
if e<<4==".htm"
then set! bufdisplay=html
if e==".man" || e==".1"
then set! bufdisplay=man
if binary
then set! bufdisplay=hex
When a new window is created for that buffer, or an existing window switches to
that buffer, that window's display mode will automatically be switched to the
bufdisplay mode.
The bufdisplay mode also affects the ^Wd visual command. This command toggles
the window between the normal mode and the bufdisplay mode. If bufdisplay is
also set to "normal", then ^Wd will toggle between the normal and hex display
modes.
7.2 Normal mode
The "normal" display mode looks like a traditional vi screen. All characters
are displayed literally except for the following...
Tab
The tab character is displayed as a variable number of spaces --
however many are needed to move to the next tabstop position.
Newline
The newline character (linefeed) marks the end of a line.
Other control characters
Control characters other than tab and newline are displayed as a
caret and a printable ASCII character. For example Control-A is
displayed as ^A, and NUL is displayed as ^@. The delete character is
displayed as ^?.
Non-ASCII characters
The appearance of non-ASCII characters (i.e., characters 128-255) is
controlled by the nonascii option. By default, most non-ASCII
characters are assumed to be ordinary printable characters.
7.3 Syntax mode
The "syntax" display mode acts exactly like the normal mode, except that this
mode automatically uses different fonts for various types of tokens in any
supported programming language. You can then use the :color command to assign
colors for each font.
7.3.1 Options
The following options determine which font is used for each type of token:
.---------------------.----------^-------------------------------------.
| OPTION NAMES | DEFAULT | AFFECTED TOKEN TYPE |
|---------------------|----------^-------------------------------------|
| commentfont, cfont | italic | comments |
| stringfont, sfont | fixed | string, character, & regexp literals|
| prepfont, pfont |emphasized| preprocessor directives |
| keywordfont, kfont | bold | keywords |
| functionfont, ffont | normal | identifier followed by function char|
| otherfont, ofont | bold | other special words |
| variablefont, vfont | normal | variables, fields, etc. |
^---------------------^----------^-------------------------------------^
Each of those options can be set to one of normal, bold, italic, underlined,
emphasized, or fixed. When typing these values into a :set command line, you
are only required to type the initial letter (n, b, i, u, e or f).
Any text that doesn't fall into one of the above groups (punctuation, mostly)
is displayed in the normal font. There is no option that controls this; it is
hard coded.
You can use the :color command to choose a color for each font, if you wish.
Not all user interfaces support color, but the "x11" and "termcap" interfaces
do.
7.3.2 Language specification
All supported languages are described in a file named "elvis.syn". Each time
a window switches to the "syntax" display mode, elvis scans this file for a
description of the language. If it can't find a description of the language,
then nothing will be displayed in a different font; "syntax" mode will look
exactly like "normal" mode.
The "elvis.syn" file is a text file. In it, blank lines and lines which start
with a '#' are ignored. Other lines begin with the name of an attribute; the
remaining words in the line are values for that attribute. Each language's
description begins with an attribute named "language". The following lines (up
to the next "language" line or the end of the file) describe that language.
The attributes names are:
language
This word is followed by a whitespace-delimited list of language
names. The names are case-sensitive, so you should probably give all
names in lowercase so they're easier for the user to type in. The
user can indicate which language to use by appending its name to the
name of the "syntax" display mode. For example, ":display syntax
c++" causes elvis to highlight the text appropriately for C++.
extension
This word is followed by the filename extensions which are commonly
used for this language. If the user doesn't specify which language
to load, then elvis scans through "elvis.syn" for an extension line
which matches the current file name. The extension lines must come
immediately after the language line.
NOTE: This is case sensitive! If the file name extension will often
be used on case-insensitive file systems (e.g., most Microsoft) then
you'll probably want to give both uppercase and lowercase versions
of the extension. For example, the description of Microsoft batch
file syntax includes "extension .bat .BAT".
keyword
This word is followed by a list of words which should be shown in
the keywordfont font. If omitted, then no words are shown in the
keywordfont. Long lists can be split into several keyword lines, if
you wish. Elvis doesn't care about the order of the words, but the
list will be easier to maintain if you keep it alphabetized.
Elvis supports three forms of keywords...
Most keywords begin with an alphanumeric character or a
character in the startword list, and continue with zero or more
characters which are alphanumeric or in the inword list.
The same startword/inword type of keywords can be made somewhat
context sensitive by appending a single character which does
not appear in the inword. The keyword will only be recognized
when it is immediately followed by that character. The HTML
syntax highlighting uses this feature to display parameters in
a distinctive font.
Rarely, you may find it convenient to have keywords which
consist of one or two punctuation characters, but which don't
match the first form of keywords. This is mostly so that Perl's
$# variable won't be displayed as a simple dollar sign followed
by a comment.
You can list the same keyword in multiple lines (once each in a
keyword line, a font line, an anchor line, and a comment line) to
specify the various attributes of each keyword. You don't need to
list it in a keyword line first; you can introduce new keywords in
any of these four line types.
font
This word can be used to cause certain keywords to be displayed in
some font other than the keywordfont. The first word after font
should be the name of the font (normal, fixed, bold, emphasized,
italic, or underlined) or a one-letter abbreviation of a font name.
The line's remaining words are keywords which will be displayed in
that font.
anchor
This offers a way to restrict certain keywords, so they will only be
recognized as such if they occur in a particular column. The first
word after "anchor" is a column number -- 1 for the leftmost column,
9 for the first tabstop, and so on. You can also use ^ instead of a
number to indicate that the keyword can only appear after whitespace
at the front of a line. The remainder of the "anchor" line is the
list of keywords which are only special when they occur in that
column.
comment
This word is followed by a keyword which marks the beginning of a
comment. The comment is assumed to end at the end of the line.
Comments are normally shown in the commentfont font, but if you've
overridden the keyword's font via a font line in elvis.syn, then the
whole comment will be displayed in that font instead. You can define
multiple comment keywords, and assign different fonts to them if you
wish.
The comment word can also be followed by a pair of one- or
two-character sequences which mark the beginning and end of comments
which can include newlines. Elvis only supports one multi-line
comment style for each language, and it will always be displayed in
the commentfont font.
operator
This word is followed by a keyword which the language uses as a
prefix for operators, and then by a list of characters which can
appear in the operator itself. This affects the ^] visual command
for tag searches. As far as I know, the only language that uses
this is C++, where it is specified like this:
operator operator ~!%^&*+|-=[]<>/
preprocessor
This word is followed by a single character which, when used at the
beginning of a line, marks the start of a preprocessor directive.
For C, this is the # character. All preprocessor directives will
then be shown in the prepfont font. If omitted, nothing is displayed
in the prepfont.
prepquote
This word is followed by a single character, or a pair of single
characters, which are used as the quote characters surrounding a
file name in a preprocessor directive. For C, this is the < and >
characters. The name of the included file will then be displayed
using the stringfont font. If omitted, then preprocessor file names
will be highlighted as though they were arithmetic expressions.
function
This word is followed by a single character which, if it appears
after a word, indicates that the word should be displayed in the
functionfont font. For most languages, this will be a ( character.
If omitted, nothing is displayed in the functionfont.
startword
inword
These can be followed by a list of punctuation characters which may
appear at the start of a word, or in the remainder of the word,
respectively. Letters and digits are always legal in words; you
don't need to list them.
other
This word indicates which types of words should be displayed in the
otherfont font. If omitted, nothing is displayed in the otherfont.
It can be any combination of the following symbols:
.-------------.-------------------------------------------------.
| SYMBOL | HOW TO RECOGNIZE "OTHER" WORDS |
|-------------|-------------------------------------------------|
| allcaps | length >= 2 chars, no lowercase characters |
| initialcaps | 1st character is uppercase, some are lowercase |
| initialpunct| 1st character is punctuation, from "startword" |
| mixedcaps | 1st character is lowercase, some are uppercase |
| final_t | length >= 3 chars, ends with "_t" |
^-------------^-------------------------------------------------^
string
This word is followed by a single character, or a pair of single
characters, which are used as the quote characters surrounding
string literals. For C, this is the " character. String literals
will then be displayed using the stringfont font. If omitted, then
strings will not be recognized.
strnewline
This is followed by backslash, allowed, indent, or empty to indicate
how strings can be continued across lines. The default is backslash
which indicates a C-style backslash is required to quote the newline
characters (which C will then exclude from the string, but elvis
doesn't care about that). The other values all indicate that a
backslash is not needed, and also give some hints that help elvis
detect whether the top of the screen is inside a multi-line string.
Specifically, the indent value means that indented lines are rarely
a continuation of a string, empty means that empty lines are
probably not part of a string, and allowed makes no promises.
The allowed value would be too slow if strings' opening and closing
quotes are identical (e.g., if the " character appears at both ends
of a string); in this situation, elvis uses empty instead.
Note that the hints are only used for detecting whether the first
line starts in a multi-line string. When drawing text after that,
elvis treats all non-backslash values identically.
character
This word is followed by a single character, or a pair of single
characters, which are used as the quote characters surrounding
character literals. For C, this is the ' character. This is shown
using the stringfont font, like strings. When parsing, the only
difference between the two is that characters can't span lines, but
strings can.
regexp
This word is followed by a list of characters which can be used for
delimiting a regular expression, which some languages support as a
means for specifying strings with metacharacters. (See Section 5 of
this manual for a description of elvis' own implementation of
regular expressions, which is a typical example.) Regular
expressions are displayed using the stringfont font.
Note that regexp accepts a list of characters, while string and
character support only a single character. This is because many
programming languages allow the programmer to choose from a variety
of delimiting characters.
useregexp
The most commonly used delimiter for regular expressions is '/',
which many languages also use as the division operator. To avoid
mistakenly displaying the division operator as the start of a
regular expression, elvis must be sensitive to the context in which
it is used. That's what this word is for. The useregexp word is
followed by a list of keywords and/or punctuation characters which
allow the next character to be recognized as a regular expression.
Additionally, regular expressions are allowed at the start of a
line.
useregsub
This is used for listing keywords and punctuation characters which
may be followed by a regular expression and then substitution text.
ignorecase
This word should be followed by true or false. If true, then elvis
won't distinguish between uppercase and lowercase letters when
testing whether a word is a keyword (except that in the elvis.syn
file, the keywords should be listed in lowercase). If omitted, elvis
assumes it should be false.
7.3.3 Example
The elvis.syn file shipped with elvis contains some good examples of language
descriptions. Here's an excerpt from it, describing the Java language.
language java
extension .java .jav
keyword abstract boolean break byte byvalue case cast catch char
keyword class const continue default do double else extends false
keyword final finally float for future generic goto if implements
keyword import inner instanceof int interface long native new null
keyword operator outer package private protected public rest return
keyword short static super switch synchronized this throw throws
keyword transient true try var void volatile while
comment //
comment /* */
function (
string "
character '
startword _
inword _
other allcaps initialcaps
There is no preprocessor line, because java doesn't use a preprocessor. The
"allcaps" and "initialcaps" symbols are given so that constants and class
names will be shown in the otherfont.
7.4 Hex mode
The "hex" display mode is an interactive hex dump of the buffer. This is good
for examining or editing binary files.
One handy feature is the ability to enter characters in hex (either in input
mode or as the argument to an r visual command) by typing ^X followed by two
hex digits. This feature is always available regardless of the display mode...
but this is where is it most useful.
7.5 HTML mode
HTML is the language used for constructing pages on the World Wide Web.
Elvis' "html" display mode supports a subset of HTML, which it uses for
displaying the online help documentation (including this very document).
HTML is a markup language. This means that documents contain a mixture of text
and formatting instructions. In HTML there are two types of instructions,
called tags and entities. When the document is processed by a program such as
Netscape or elvis (in html mode), the tags are stripped out, the entities are
converted to a kind of text, and the text is formatted and presented to the
user. Ordinarily the user will never see the tags.
Since elvis is primarily an editor, not a viewer, it has two options which
allow the tags to become visible: the showmarkups option causes a tag to
become visible if the cursor is moved onto it, and the list option makes all
tags visible regardless of the cursor position.
There are a lot of good "How To Use HTML" documents on the Net. This is not
one of them! I don't intend to do much more than describe the quirks of elvis'
implementation of HTML here.
I added HTML support to elvis mostly to support the online help. Consequently,
if a feature is hard to implement and the online documentation doesn't use it,
then I didn't implement that feature.
If you intend to use elvis as a browser, then I suggest you read the
approriate section in the Tip chapter.
7.5.1 Formatting tags
Elvis supports the following HTML tags. Unsupported tags are silently
ignored. Newline characters aren't supported within tags; each tag must fit on
a single line.
<html> ... </html>
The entire document should be enclosed in these tags. They don't
actually do anything to help format the document, but they may help
programs recognize that the document is, in fact, written in HTML.
<head> ... </head>
These should be used to bracket the document's header, if it has
one.
<title> ... </title>
These tags are only legal in the document's header. Any text between
the <title> and </title> tags will be stored internally as the title
of the document. If you print the document, elvis will display the
title at the top of each page.
<body> ... </body>
These should be used to bracket the body of the document. They don't
actually do anything in elvis, but real Web browsers such as
Netscape allow you to specify backgrounds and patterns via
BGCOLOR=... and BACKGROUND=... arguments, respectively.
<h1> ... </h1>
These tags bracket the most visible type of section header. Elvis
displays <h1> ... </h1> headers in boldface, flush against the left
edge of the page. When printing, these headers cause a page break.
<h2> ... </h2>
These bracket the second most visible type of section header. Elvis
displays <h2> ... </h2> headers in boldface, indented slightly from
the left edge. When printing, these may cause a page break if they
would otherwise appear near the bottom of a page.
<h3> ... </h3>
These bracket the third most visible type of section header. Elvis
displays them in boldface, indented fully from the left edge so that
it lines up with normal text.
<h4>...</h4>
<h5>...</h5>
<h6>...</h6>
These are very minor section headers. Conventional wisdom says that
if you're using this many section headers then you would probably do
better to split your document into several smaller documents. Elvis
displays these headers in an italic font.
<p>
This tag should be placed at the start of each normal paragraph,
with the possible exception of the first paragraph after a section
header. It causes a blank line to be generated, and any later text
to appear starting on a new line.
<br>
This causes any later text to appear starting on a new line. It
differs from <p> in that <br> doesn't output a blank line.
<hr>
This outputs a "horizontal rule" -- a line all the way across the
page.
<img alt=... src=...>
Elvis can't display graphics, but if it encounters an <img> tag
which has an alternate text form (as denoted by an img="text"
parameter) then it'll display the alternate text. Otherwise elvis
will display "src" URL. Also, if the image isn't already part of a
hypertext link, then elvis will treat it as a link to the image's
binary data; this offers you a way to fetch images, even though
elvis can't display them. The supported URL formats are described in
the discussion of the <a> tag, below.
<frame name=... src=...>
Elvis can't display frames either, but it will display the frame's
name, and treat that name as a hypertext link to the frame's
document. This offers a simple work-around for elvis' lack of real
frame support. The supported URL formats are described in the
discussion of the <a> tag, below.
<blockquote> ... </blockquote>
This is used to mark a large chunk text which is quoted from another
source. Elvis will indent the enclosed text.
<pre> ... </pre>
This brackets text which has already been preformatted by the
document's author. Elvis will treat tabs and newlines literally.
(Outside of <pre> ... </pre>, they would normally be treated like
spaces.) This has been used for presenting tables, poetry, and
source code examples.
In fact, elvis has an extension that is useful for tables: If you
start with <pre graphic> then elvis will convert certain characters
into graphic line-drawing characters. When adjacent to a hyphen
character, the hyphen, period, caret are converted into appropriate
graphic characters. Additionally, the vertical bar character is
always converted to a graphic character. The following was done with
a plain <pre>...
.--.--.
|--|--|
| | |
^--^--^
... and this was done with <pre graphic>...
.--.--.
|--|--|
| | |
^--^--^
<table>...</table>
<tr>...</tr>
<th>...</th>
<td>...</td>
These are used for implementing tables in HTML 3.0. Each table
should be enclosed in a <table>...</table> pair. Within the table,
each row should be delimited with a <tr>...</tr> pair. Within each
row, the information for each column should be enclosed in either a
<th>...</th> pair for headers, or a <td>...</td> pair for data.
Elvis doesn't really support these tags very well. Only the bare
essentials of these commands have been implemented. They are
intended to make tables recognizable as being tables, but not
necessarily make them easy to read.
<dir>...</dir>
<xmp>...</xmp>
These are treated almost exactly like <pre> ... </pre>. There are
supposed to be some differences, but elvis doesn't support those
differences.
<dl> ... </dl>
These are used to bracket a list of definitions. The definitions
themselves are marked with the <dt> and <dd> tags, described below.
<dt>
The text after this tag is used as a term to be defined. Elvis
displays this text in bold face, indented by the same amount as
normal text. This is only legal in a <dl>...</dl> pair.
<dd>
The text after this tag is used as the definition of a term. Elvis
displays it in the normal font, indented somewhat more than normal
text or the <dt> text. This is only legal in a <dl>...</dl> pair.
<ol> ... </ol>
These are used to enclose an ordered list. The official
specifications say that lists may be nested inside one another, but
elvis doesn't allow ordered lists to appear inside any other type of
list. If a document uses <ol> ... </ol> inside another list, then
elvis will act as though <ul> ... </ul> had been used instead. This
means that the list items will be marked with bullets instead of
numbers. Within the list, <li> tags are used to mark the items.
<ul> ... </ul>
These enclose an unordered list. Each item in the list should be
marked with a <li> tag.
<menu> ... </menu>
These enclose an unordered list, like <ul> ... </ul>, but other Web
browsers may display <menu> ... </menu> lists in a more compact
manner.
<li>
This is used to mark the start of a new item in a list.
<input type=... size=... value=...>
<textarea cols=...>
Elvis can display a mockup of a form, so you can have some idea of
how the form would look on a real browser. The forms won't really
work in elvis! Elvis displays forms for the sole purpose of helping
you define the form layout. Buttons are displayed as reverse-video
characters, and text input areas are displayed as underlined spaces.
The <textarea> image is always 3 rows high, regardless of any
rows=... value you supply.
<a> ... </a>
There are two forms of this tag: <a href=URL>...</a> to mark the
source of a hypertext link, and <a name=anchor></a> to mark the
destination of a hypertext link.
Elvis doesn't support as many URL protocols as a real browser. It
only supports the pseudo-protocol "buffer:", and the real protocols
"file:" and (on some platforms) "http:" and "ftp:". Only the
following URL formats are supported:
buffer:bufname
Switch to the buffer named bufname. Within that
buffer, the cursor will be moved to the position
of the most recent activity to that buffer. This
is an elvis-only extension!
[protocol:]filename.ext
Load the named file, and move the cursor to the
top of that file's buffer.
[protocol:]filename.html#anchor
Load the named file, and move the cursor to the
first visible character after an <a name=anchor>
tag. This is only useful for HTML files.
[protocol:]filename.ext?data
For the "file:" protocol, the data can be any valid
ex line address, including a "nomagic" regular
expression or a line number. Elvis loads the file
and moves the cursor to the address. This is an
elvis-only extension!
For the "http:" protocol, the data is passed to the
HTTP server; it's interpretation is handled by the
HTTP server (or more likely a CGI script).
Either way, the data should be URL-encoded,
which means...
* + represents a space character
* %2B represents a '+' character
* %25 represents a '%' character
* %22 represents a '"' character
* %3C represents a '<' character
* %3E represents a '>' character
* Other printable ASCII characters can be
given literally
* Anything else (non-ASCII characters or
ASCII control characters) should be given
as a '%' followed by two hex digits for
its ordinal value.
<cite> ... </cite>
These enclose a citation. Elvis displays the citation in italics.
<dfn> ... </dfn>
These enclose a term that is being defined. Elvis displays the term
in italics. Netscape doesn't support this tag, so you should
probably avoid it. Use <em> ... </em> instead.
<em> ... </em>
These enclose text which should be emphasized some way. Elvis
displays the text in (you guessed it) italics.
<kbd> ... </kbd>
These enclose text which the user might want to type into the
computer some day. Generally, each word of the text will be the
legend from a keytop on the user's keyboard, such as Esc or Tab.
Elvis displays this text in boldface.
<strong> ... </strong>
These enclose text which should be emphasized a heck of a lot. Elvis
displays this text in boldface.
<var> ... </var>
These enclose text which indicates where some variable argument is
to be placed. Elvis displays this text in italics.
<address> ... </address>
These enclose an address. Elvis displays the address in italics.
Note that this is typically used for e-mail addresses and Web URLs,
not postal addresses.
<code> ... </code>
These enclose example code which is included in the body of a
paragraph. Elvis displays the text in the fixed font -- which,
unfortunately, looks exactly like the normal font on most printers.
<b> ... </b>
The enclosed text is displayed in bold. The <strong> ... </strong>
tags are preferred, if you really want to emphasize text.
<i> ... </i>
The enclosed text is displayed in italics. The <em> ... </em> tags
are preferred, if you really want to emphasize text.
<u> ... </u>
The enclosed text is displayed underlined. You should avoid using
this tag, because underlining is also used to indicate hypertext
links. The <u> ... </u> text would look like a hypertext link but
wouldn't work like one.
<tt> ... </tt>
The enclosed text is displayed in the fixed font. The <code> ...
</code> tags are preferred, if you really want to embed code
examples in the body of a paragraph.
Note that most of these tags come in pairs, and the ending tag's name includes
a '/' character. Elvis doesn't verify that the pairs match up correctly.
Because of this, I strongly suggest that you preview your document using a
more powerful HTML viewer such as Netscape before sharing it with the world.
7.5.2 Character entities
Most text characters can be given literally in an HTML file, but some need
special treatment. The most notable are <, >, &, and non-ASCII characters.
HTML uses "character entities" to represent them.
Many of the entities are automatically derived from the digraph table. If you
don't know about digraphs, you should look up the :digraph command, and the
discussion on how to use them in input mode.
All of these must begin with an '&' character and end with a ';' character. In
the earliest HTML standard, the ';' was optional, but elvis requires it. If
you omit the ';' from an entity, then elvis will display it literally (not
translate it to a single character).
Elvis supports the following character entities:
< or <
> or >
The less-than and greater-than symbols (< and >).
& or &
The ampersand character character (&).
" or "
“
”
The double-quote character (").
‘
’
The left and right single quote characters (‘ and ’).
«
»
The left and right angle quote characters (« and Γòù). These are
formed from digraphs which combine two < characters or two >
characters, respectively.
or &NBSP;
A non-breaking space. This is displayed as a space character. It
differs from plain old whitespace in that can't be converted
into a line break.
© or ©
The copyright symbol ((C)). Elvis looks for a digraph which combines
a lowercase c and uppercase O. If there is no such digraph, then
elvis displays c.
® or ®
The registered trademark symbol (╨╛). Elvis looks for a digraph which
combines a lowercase r and uppercase O. If there is no such digraph,
then elvis displays r.
£
¢
¥
¤
Currency symbols (╨│, ╨▓, ╨╡, and ╨┤). These are formed from digraphs
combining the letter L, C, Y or X (respectively) with the $
character.
°
The degree symbol (Γûæ). This is formed from a digraph combining two *
characters.
& iexcl;
¿
Inverted exclamation mark and inverted question mark (╨▒ and ΓöÉ).
These are formed from digraphs combining the ! or ? character
(respectively) with the ~ character. If no such digraph exists,
then the non-inverted version of that character is shown.
A small hyphen (╨╜).
Æ
A digraph combining the letters A and E (Γò₧). If no such digraph has
been defined, then elvis will display E.
æ
A digraph combining the letters a and e (Γò₧). If no such digraph has
been defined, then elvis will display e.
Ð
A digraph combining a hyphen and the letter D (Γò¿).
ð
A digraph combining a hyphen and the letter d (Γò¿).
Þ
A digraph combining the letters T and P (ΓûÉ), or just plain P if
there is no such digraph.
þ
A digraph combining the letters t and p (ΓûÉ), or just plain p if
there is no such digraph.
ß
A digraph combining the letters s and z (ΓûÇ), or just plain z if
there is no such digraph.
&lettergrave;
A digraph combining the ` and letter, such as à (Γöö).
&letteracute;
A digraph combining the ' and letter, such as á (Γö┤).
&lettercirc;
A digraph combining the ^ and letter, such as â (Γö¼).
&lettertilde;
A digraph combining the ~ and letter, such as ã (Γö£).
&letteruml;
A digraph combining the " and letter, such as ä (ΓöÇ).
&letterring;
A digraph combining the * and letter, such as å (Γö╝).
&lettercedil;
A digraph combining the , and letter, such as ç (Γòƒ).
&letterslash;
A digraph combining the / and letter, such as ø (Γò¬).
&#number;
The character whose ordinal value is number. This should be avoided,
because you can't be sure which symbol set will be used when
somebody else views the document. Some documents use which is
a "hard" space in the ISO Latin-1 symbol set, but they should really
use .
If your document uses a character entity which elvis doesn't support, then
elvis will not convert that entity into a single character; instead, it will
be displayed literally.
If elvis looks for a digraph containing a punctuation character and a letter,
and no such digraph has been defined, then elvis will use the plain ASCII
letter.
7.5.3 Using hypertext
The HTML hypertext has been implemented as a variation on the standard vi :tag
command. Consequently, all of the wonderful commands that elvis offers for
browsing C source code can also be used for browsing HTML documents.
In EX mode, you can use :tag URL to pursue a hypertext reference, and :pop to
come back afterward.
In VI mode, you can move the cursor onto the underlined text which denotes a
hypertext reference, and hit ^] to pursue the reference, and ^T to come back
afterward. Also, when in html mode the Tab key searches forward for the next
hypertext reference, and the Enter key performs tag lookup just like the ^]
key.
If elvis' user interface supports a mouse, then you can double-click the left
button to follow a hypertext reference, and double-click the right button to
come back afterward.
7.6 Man mode
The man display mode uses a markup language, as does the html display mode.
The difference is that the man display mode's markup language resembles that
of "troff -man". It is used for formatting entries in the UNIX user manuals.
Elvis supports only a tiny subset of the troff commands and -man macros. It is
adequate for a surprising number of man pages, though. The most notable
failing is the lack of number/string registers.
Commands which start with a "." are only recognized at the start of a line.
The remainder of the line is used as arguments to the command. Commands which
start with a "\" are recognized anywhere.
.\" comment
Elvis ignores any text on a .\" command line.
.TH name section
This command should appear at the top of the man page. It declares
the name of the program to be described, and the section of the
manual where it should appear. User programs are usually documented
in section 1.
.SH name
The name is displayed as a section header. If name contains
whitespace, then it should be enclosed in quotes. Man pages usually
have sections named NAME, SYNOPSIS, DESCRIPTION, OPTIONS, FILES,
ENVIRONMENT, "SEE ALSO", BUGS, and AUTHOR, in that order. The
"elvis.man" file is a typical example.
.SS name
The name is displayed as a subsection header. If name contains
whitespace, then it should be enclosed in quotes. Man pages rarely
use subsections.
.B text
The text is displayed in boldface.
.I text
The text is displayed in italics.
.SM text
Troff would display the text in a slightly smaller font. Elvis
doesn't support multiple font sizes, though, so it simply outputs
the text.
.RB text1 text2 ...
.BR text1 text2 ...
.RI text1 text2 ...
.IR text1 text2 ...
.BS text1 text2 ...
.SB text1 text2 ...
These output the argument text, alternating between two fonts. For
example, .BR outputs the first argument word in boldface, the second
in normal (a.k.a. Roman), the third in boldface again, and so on.
The "S" font is supposed to be small, but elvis uses the normal font
for that. All whitespace is removed from between the argument words.
.IP label
This starts an indented paragraph. The label, if given, is output
before the paragraph, and without indentation. This is typically
used for presenting a term (the label) and its definition (the
paragraph).
.TP
This starts a hanging paragraph. That's like a .IP indented
paragraph, except the label is declared on the line following the
command, instead of on the command line itself. The body of the
paragraph starts on the second line after the command line.
.P
.LP
.HP
Any of these will start a regular paragraph. In addition, a series
of one or more blank lines will also start a paragraph.
.RS
.RE
These start and end a relative indentation, respectively. In other
words, .RS increases the indentation of any subsequent text, and .RE
reduces indentation.
.br
This causes a line break.
.sp
This causes a line break, and then leaves a blank line.
.nf
.fi
These turn "fill mode" off and on, respectively. When fill mode is
turned off, elvis will perform much less formatting. It is similar
to the <pre>...</pre> tags in HTML.
.TS
.TE
In the real troff, these mark the start and end of a table, and the
line after the .TS indicates the format of the table. For elvis,
these are just like .nf and .fi, respectively, except that .TS hides
the line that follows it (so the table format is hidden).
.DS
.DE
These mark the beginning and end of a "display." Inside the display,
"fill mode" is turned off, just as it is for the .fi and .nf
markups. The real troff tries to avoid page-breaks inside a display,
but elvis isn't that smart.
\e
This is replaced by the backslash character.
\|
\&
\^
These are deleted. If you ever feel a need to put a period at the
start of a line, and don't want it to be treated like a command
line, then put \&. in your file. The \& will prevent the period from
being interpreted as the start of a command line, but will not show
in the output.
\fB
\f1
Switch to boldface.
\fI
\f2
Switch to italics.
\fR
\f0
Switch to the normal font.
\fP
Switch to the default font for this context. That's boldface in
headings, and normal the rest of the time. Actually, \fP is supposed
to switch to the "previous" font, whatever that was, but elvis
doesn't do it that way.
\*
\n
In the real troff, these are used for accessing the value of a
string or numeric register, respectively. Elvis doesn't support
registers; it'll just display the \* or \n expression literally.
\character
When character is something other than one of the above, output the
character. In particular, \\ outputs a single backslash.
Troff source was never designed to be interactively edited, and although I did
the best I could, attempting to edit in "man" mode is still a disorienting
experience. I suggest you get in the habit of using "normal" mode when making
changes, and "man" mode to preview the effect of those changes. The ^Wd
command makes switching between modes a pretty easy thing to do.
Unrecognized commands which start with "." are silently ignored.
Unrecognized commands which start with "\" will be output without the initial
"\" character. This falls far short of the ideal, but there are just too many
weird escapes to bother implementing in something that isn't being advertised
as a troff clone. (NOTE: Elvis is not a troff clone.)
A tip: If your document contains sequences which look like \*X or \*(XY (for
any characters X and Y), then it is trying to use defined strings. Look for a
".ds X foo" command near the top of the document to find out what that string
is supposed to look like. The string \*(bu is a bullet character.
7.7 TeX mode
Don't get excited, this isn't that good. I spent two days adding a quick hack
to the html/man display code to allow it to almost format some TeX documents.
But the semantics of TeX are sufficiently different from HTML or nroff -man
that a truly satisfying TeX formatter would need totally separate formatting
code, which would require a couple of weeks to implement and would add about
25k bytes to the elvis executable. Since I don't use TeX myself, my priorities
don't justify that. They justify a two-day hack and about 3k bytes of extra
code.
7.7.1 Supported TeX markups
The following describes the subset of TeX that elvis now supports. It also
describes the quirks of elvis' implementation.
%comment
Anything between a % and the end of the line is ignored.
(blank lines)
\p
Two or more consecutive newlines (i.e., one or more blank lines)
indicate a paragraph break. You can also use \p to start a new
paragraph; in fact, that's how all paragraph breaks are displayed if
you set the list or showmarkups options.
{ ... }
The { character causes the current font to be stored in a hidden
memory location, and } resets the current font to the stored value.
A few other markups, described below, use the { ... } notation for
their arguments.
This differs from TeX in two major ways:
In addition to the font, TeX stores other attributes such as
the indentation level. Elvis only stores the font.
Elvis has only a single location for storing fonts, but TeX
uses a stack, which allows you to nest { ... } pairs to good
effect. Elvis will become confused by nested { ... } pairs.
\mathrelpunctuation
\charpunctuation
\punctuation
These output the punctuation character literally. In the real TeX,
\mathrel is more subtle than that.
\title{text}
Display the text as a title: Centered, in the "bold" font.
\author{text}
Display the text as an author name: Centered, in the "italic" font.
\section{text}
Display the text as a section title: Starting at the leftmost
column, in the "bold" font. Also, if it would be printed near the
end of a page then it will be moved to the start of the next page
instead.
\subsection{text}
Display the text as a subsection title: Indented slightly from the
left edge, and in the "bold" font.
\hline
Draw a horizonal line across the page. Unfortunately, elvis'
implementation tends to leave a blank line above the horizontal
line.
\begin{table}
\hfil or \hfill or & ;
\cr or \\
\end{table}
These are used to present tables. \cr or \\ marks the end of each
row, and \hfil, \hfill, or & mark the end of a column's data within
a row. TeX actually offers other commands to control the shape of
the table, but elvis doesn't support those commands.
\begin{quote}
\end{quote}
These are used to enclose a quoted paragraph. Elvis uses extra
indentation while displaying the paragraph.
\begin{verbatim}
\end{verbatim}
These are used to enclose text which should be subjected to less
processing; in particular, indentation and line breaks are
preserved.
$$
A $$ pair toggles between the "normal" font with standard text
filling, and the "fixed" font with lines displayed verbatim. This is
typically used for presenting longer command-line examples on lines
by themselves between paragraphs.
\begin{description}
\item[term]
\end{description}
This is used for presenting a series of terms followed by their
definitions.
\begin{enumerate}
\item
\end{enumerate}
This is used for presenting a numbered list of items. Each item
should be preceeded by \item.
\begin{itemize}
\item
\item[bullet]
\end{itemize}
This is used for presenting a list of items. Each item should be
preceded either by \item to mark it with an asterisk, or by
\item[bullet] to mark it with something other than an asterisk.
\tt
Switch to the "fixed" font. Generally, all of these font-switching
commands will be used with { ... }, like this:
Normal text {\tt Fixed-font text} Normal again.
\bf
Switch to the "bold" font.
\em
\it
Switch to the "italic" font.
\fo
This is a common macro which indicates the following text is in a
foreign language. Elvis supports it; it switches to the "italic"
font.
$
A single $ character toggles between the "normal" font and the
"fixed" font. This is often used for marking computer commands in
the body of a paragraph.
7.7.2 Unsupported TeX markups
The following describes how elvis deals with certain unsupported features of
TeX.
\vspace{value}
This is treated like a paragraph break.
\footnote{text}
The footnote is completely hidden, including its text.
\halign...
\begin{tabular}...
\multicolumn...
\set...
\def...
\new...
\catcode...
\document...
\other=...
Everything up to the end of the line is skipped. Other than that,
the markup has no effect.
\other{text}
The markup and its text are ignored.
\other
Unrecognized markups are generally ignored. The single big exception
is that if the markup is followed by punctuation or a
backslash-space pair, then elvis assumes the markup is probably just
an abbreviation for some word or phrase which is supposed to be
displayed in a special font; so elvis displays the markup's name
(without the leading backslash) in the "bold" font.
ΓòÉΓòÉΓòÉ 1.8. Elvis 2.1 User Interfaces ΓòÉΓòÉΓòÉ
8. USER INTERFACES
A single elvis binary can be compiled to support multiple user interfaces. For
example, under UNIX elvis can be compiled to have a graphical user interface
when run under X-windows, a termcap interface for use on most text terminals,
an "open" interface for use on any terminal, and a "quit" interface for running
scripts. Here's a comprehensive list of the user interfaces which may be
available in your copy of elvis:
x11 - a graphical interface under Unix and OS/2.
windows - a graphical interface under Win32.
termcap - a full-screen text-based interface.
vio - OS/2-specific version of the termcap interface.
open - a simpler text-based interface.
quit - a pseudo-interface for non-interactive editing.
The exact list of available user interfaces will vary from one system to
another. You can make elvis output a list of available interfaces by running
"elvis -G?". This will also show you which interface elvis will use by
default.
Elvis chooses the default user interface at run time by testing each user
interface in turn, starting with the most desirable, and working its way down
the list until it finds one that appears to be supported in the current
environment. For example, if you're using elvis on a text terminal under UNIX,
then elvis will bypass the "x11" interface because X-windows doesn't work on
text terminals, and then elvis will find that the "termcap" interface would
work, so that'll be the default.
If you don't want to use the default user interface, you can specify which
interface to use via the -G gui command-line flag.
8.1 X11 Interface
The x11 interface is used under X-Windows on UNIX or OS/2 systems. (See the
OS/2 section of the OS chapter for a description of what you need to run X11
under OS/2.) Subsections here are command line flags, the mouse, the toolbar,
resources, keys, and icons.
The x11 interface provides a scrollbar and mouse support, and allows you to
select which fonts to use. Fonts are specified via command-line flags; there
is no way to change fonts after elvis has created the first window.
The x11 interface reads app-defaults (as listed below) but those are only used
to provided default values for options and colors. You can override them with
:set and :color commands. The x11-specific options are described in the
options chapter.
8.1.1 X11 Command-line Flags
To specify a normal font, use -font fontname or -fn fontname. Proportional
fonts are not supported. If you don't specify a normal font, then elvis will
use a font named "fixed" by default.
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.
The -fc fontname flag can be used to specify the font to be used for controls
-- currently just the toolbar, but eventually elvis will offer a scrollbar and
maybe a statusbar. If you don't specify a control font, then elvis will use
the "variable" font by default.
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 also specify the foreground and background colors with -fg color and
-bg color, respectively. All standard X color names are supported.
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.
Elvis also supports the -geometry WxH+X+Y flag for specifying the size and/or
position of the first window.
The -fork option causes elvis to fork a new process, so you get a new shell
prompt 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. If there is
no elvis process already running, then -client will act like -fork so that
either way, you get a new shell prompt immediately.
You can change elvis' defaults by editing the elvis.ini or ~/.exrc file. You
can use the :color command to assign colors to various fonts, and the cursor
and scrollbar/toolbar. Most other aspects are controlled via options.
8.1.2 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 cancelling
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.
8.1.3 Toolbar
The X11 interface supports a user-configurable toolbar. The toolbar is
enabled by default; you can disable it in your ~/.exrc file by adding a "set
notoolbar" command.
If enabled, you will find that the default toolbar already has some buttons
defined. You can use the :gui command to reconfigure the toolbar. The
following commands are supported:
:gui
This displays the :gui commands which were used to set up all
toolbar buttons.
:gui label
This displays the :gui commands which were used to set up the
toolbar button that has the given label.
:gui newtoolbar
This deletes all buttons from the toolbar.
:gui ~label
This deletes a single, specific button from the toolbar.
:gui gap
This leaves a small gap between the previous button and the
following button.
:gui label : excommand
This creates a button named label. Whenever you click the button,
the excommand will be interpreted as an ex command line. The label
can begin with any non-whitespace character. The remaining
characters can be letters, digits, or another instance of the
initial character.
:gui Help:help
NOTE: If you want to have more than one line's worth of ex commands
associated with a toolbar button, then you might consider defining
an alias.
:gui label = condition
Normally buttons are drawn as though sticking out; this command
gives you a way to make them selectively appear to be stuck in. The
condition is a C-like expression. When it is true, the button will
be drawn "sticking in". When it is false, the button will be drawn
"sticking out". The button behaves exactly the same either way.
:gui List:set neglist
:gui List=list
:gui label ? condition
This gives you a way to selectively disable the button. The
condition is a C-like expression. When it is true, the button
behaves as normal; when it is false, the button ignores any mouse
clicks. Also, buttons which are disabled this way are displayed as
being "flat", instead of the normal 3D shading that makes them
appear to stick out or in.
:gui Quit:q
:gui Quit?!modified
NOTE: The condition expressions are re-evaluated after nearly every
input event. If you have many complex expressions, this may take a
noticeable amount of time. With the default toolbar, elvis seems to
slow down by about 20%. Toolbar buttons which don't use condition
expressions have no such overhead.
:gui label " description
Add a one-line description to the button. The description is shown
on the status line when the button is pressed. It is also displayed
on pop-up dialogs, as described below.
:gui Quit"Close this window, and maybe exit elvis
:gui label ; ;
:gui label ; option ; ...
:gui label ; "prompt" (type) option = value ; ...
This allows you to define a pop-up dialog for a given toolbar
button. When you click on the toolbar button, the dialog appears
immediately. You can then edit some values, and then hit the
[Submit] button to store the edited values into options and run the
toolbar button's ex command (if any), or hit the [Cancel] button to
do nothing.
The simplest dialog is specified by giving just a pair of semicolons
after the label. This dialog will have no editable fields, but it
still shows the [Submit] and [Cancel] buttons, so it is a handy way
to ask for confirmation before doing something.
But usually you'll give a semicolon-delimited list of options after
the toolbar button's label. The dialog will then allow you to edit
those options. When you hit the [Submit] button on that dialog
window, elvis will store the values into the options before running
the ex command.
The default prompt for each option is its name. If you precede the
option name with a quoted string, then the string is used for the
prompt instead.
You can also override the option's data type. The default type for
each option is the same type used by the :set command. You can
override that by placing one of the following before the option
name:
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéTYPE ΓöéMEANING Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé(oneof list) ΓöéAllow any single value from the Γöé
Γöé Γöéspace-delimited list Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé(boolean) ΓöéSame as (oneof true false) Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé(number) ΓöéAllow any number Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé(number m:n) ΓöéAllow number between m and n, Γöé
Γöé Γöéinclusive Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé(string) ΓöéAllow any string Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé(file) ΓöéAllow any string, but use the Tab key Γöé
Γöé Γöéfor file name completion Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
Γöé(locked) ΓöéDisplay it, but don't allow any Γöé
Γöé Γöéediting Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
The default value for each option is the option's actual value at
the time the dialog pops up. You can override that by appending an
'=' followed by an expression for some other value. Note that the
option itself isn't changed unless/until you hit the [Submit]
button.
NOTE: The user options "a" through "z" are useful for inputting (via
the dialog) and storing temporary values. You'll almost certainly
want to override the prompt and type of those options.
NOTE: Because the edited option values are stored before the toolbar
button's ex command is executed, the ex command can access the
options' values via commands such as :eval. Also, since elvis
always subjects file names to evaluation via the simpler expression
syntax, you can don't need to use :eval to expand file names. The
following shows one useful example of this:
:gui Split;"File to load:" (file) f = filename
:gui Split:split (f)
NOTE: If you just want to use the dialog for adjusting options, and
don't need to run an ex command afterward, then you can simply omit
the ex command definition for that toolbar button. For example, the
following is sufficient for editing the display options:
:gui Display Options; list; number; wrap; sidescroll
NOTE: You can display a non-editable line of text in the dialog by
using ="string" without giving any option name. Here's an example:
:gui Save;"Save as:"(file)f=basename(file);="In current directory!"
:gui Save:w (f)
8.1.4 Resources
Elvis uses the following X resources. The resource values can be overridden
by command-line flags, or by explicit :set or :color commands in the
initialization scripts.
.----------------------------.---------.----------.--------------------.
| RESOURCE CLASS | | DEFAULT | |
|(name is lowercase of class)| TYPE | VALUE | PARTIAL EX COMMAND |
|----------------------------|---------|----------|--------------------|
| Elvis.Toolbar | Boolean | True | set toolbar |
| Elvis.Statusbar | Boolean | True | set statusbar |
| Elvis.Font | Font | fixed | set normalfont= |
| Elvis.Geometry | Geometry| 80x34 | set firstx= xrows= |
| Elvis.Foreground | Color | black | color normal |
| Elvis.Background | Color | gray90 | color normal |
| Elvis.MultiClickTimeout | Timeout | 3 | set dblclicktime= |
| Elvis.Control.Font | Font | variable | set controlfont= |
| Elvis.Cursor.Foreground | Color | red | color cursor |
| Elvis.Cursor.Selected | Color | red | color cursor |
| Elvis.Cursor.BlinkTime | Timeout | 3 | set blinktime= |
| Elvis.Tool.Foreground | Color | black | color tool |
| Elvis.Tool.Background | Color | gray75 | color tool |
| Elvis.Scrollbar.Foreground | Color | gray75 | color scrollbar |
| Elvis.Scrollbar.Background | Color | gray60 | color scrollbar |
| Elvis.Scrollbar.Width | Number | 11 | set scrollbarwidth=|
| Elvis.Scrollbar.Repeat | Timeout | 4 | set scrollbartime= |
| Elvis.Scrollbar.Enabled | Boolean | True | set scrollbar |
^----------------------------^---------^----------^--------------------^
The "Timeout" type gives a time value, in tenths of a second.
For example, if your X resources database contains the line "elvis.font:
10x20" then the default text font would be "10x20". This value would therefore
be used if the normalfont option was unset.
8.1.5 X11 Keys
If there is a standard way to map a Keysym value into a text string, then
elvis will use it. This means that when you hit the <m> key, you get an "m"
character. Function keys and cursor keys have no standard translation, so
elvis converts them to a ^K character followed the Keysym binary value,
expressed as four hex digits.
You can use the "^Kxxxx" character sequences as the first argument to a :map
command. In the interest of readability and portability, though, elvis also
allows you to use the symbolic name of a key in that context, instead of the
raw characters. These are the same key names that are used by (among other
things) the xmodmap command. Here are some of the more important names: Begin,
End, Home, Print, Menu, Insert, Undo, Redo, Help, Break, Multi_key, Kanji, and
Mode_switch.
8.1.6 X11 Icons
Elvis has a 48x32 monochrome icon compiled into it. This icon is stored in
the file guix11/elvis.xbm. It is a standard X11 bitmap file.
There are also a variety of colored icons in that directory, in standard X11
pixmap files. These are not compiled into elvis. If you want to use one of
these, you'll need to configure your window manager to substitute the colored
icon for the compiled-in monochrome icon. Each window manager is configured
in a different way, and I can't tell you about every single one out there.
But I use FVWM2, and I can tell you how to configure that: In your ~/.fvwm2rc
file, add a line which reads...
Style "elvis" Icon /usr/include/X11/pixmaps/elvis.xpm
Note that this expects the elvis.xpm file to be copied into
/usr/include/X11/pixmaps/. When you install elvis by running make install,
the insticon.sh shell script is run; this checks for a whole series of likely
places to copy icons of various sizes, and copies them there.
The following color icons are available:
.------------.------------------------------------------------.
| NAME | DESCRIPTION |
|------------|------------------------------------------------|
| elvis.xpm | 48x32, 4 colors, same as the monochrome icon |
| mini.xpm | 16x14, 6 colors, for fvwm95 taskbar |
| normal.xpm | 56x46, on a shaded button for NextStep-ish WMs |
| small.xpm | 21x18, on a shaded button for NextStep-ish WMs |
^------------^------------------------------------------------^
The last two use many colors, but most of those colors are for the shaded
button background, not the icon itself. Other shaded-button icons use the
exact same colors for the shading, so the overall impact on your color table
isn't too bad. But if you don't normally use icons on shaded buttons, then
you should probably use only the first two icons.
8.2 Windows Interface
The windows interface works under Microsoft's Windows95, Windows98, or
WindowsNT (version 3.51 or later) operating systems. It offers a full
graphical interface with all the usual bells and whistles. Subsections here
discuss the mouse, keys, colors, printing, and fonts.
Because Microsoft doesn't allow a single .EXE file to contain both a Windows
interface and a text-based interface, the Windows version resides in a
separate file named WinElvis.exe. (The text-based version is named elvis.exe,
and it uses the termcap interface.)
8.2.1 Windows Mouse
In addition to all the usual mouse actions in the menubar, toolbar, and
scrollbar, you can use the mouse in elvis' main text area as follows.
Dragging the mouse with the left button pressed causes elvis to select
characters, like the lowercase v command. Dragging with the right button
pressed causes it to select a rectangular area, like the ^V command. Dragging
in the left margin (where the mouse cursor changes to up-and-right-arrow)
causes whole lines to be selected.
Clicking with either the left or right mouse button will move the cursor to
the clicked-on character. When you click with the left button, if a selection
is highlighted then elvis will cancel the selection; clicking with the right
extends the selection to include the clicked-on character.
Double-clicking on a word with the left button causes elvis to perform a tag
search, like the ^] command. Double-clicking with the right button pops back
to the previous position via the tag stack, like the ^T command.
8.2.2 Windows Keys
In addition to all the ASCII keys, WinElvis allows you to :map any cursor
keys or function keys. In fact, the cursor keys all have rather convenient
maps built-in; you can see them by running ":map" with no arguments.
All of the cursor keys and function keys send multi-character sequences to
WinElvis. WinElvis then uses its standard mapping facilities to convert those
sequences into something that it can recognize and act on. Since the
multi-character sequences aren't standardized, and are usually hard to guess
or remember, WinElvis allows you to refer to them symbolically. The following
symbols are used for referring to the cursor keys:
.--------------------.----------.-----------.
| KEY | SYMBOL | MAPPED TO |
|--------------------|----------|-----------|
| up arrow | <Up> | k |
| down arrow | <Down> | j |
| left arrow | <Left> | h |
| right arrow | <Right> | l |
| Page Up | <PgUp> | ^B |
| Page Down | <PgDn> | ^F |
| Home | <Home> | ^ |
| End | <End> | $ |
| Ctrl + left arrow | <CLeft> | B |
| Ctrl + right arrow | <CRight> | W |
| Ctrl + Page Up | <CPgUp> | 1G |
| Ctrl + Page Down | <CPgDn> | G |
| Ctrl + Home | <CHome> | 1G |
| Ctrl + End | <CEnd> | G |
| Ctrl + Insert | <Insert> | i |
| Ctrl + Delete | <Delete> | x |
^--------------------^----------^-----------^
The function keys are a different story. Vi has a traditional way to access
function keys in a terminal-independent manner, so WinElvis starts with that
and extends it just slightly. The benefit of this is that you can use the
same function key maps in other versions of elvis, or even in other
implementations of vi.
The basic function key symbols are #1 for the F1 key, #2 for the F2 key, and
so on through #12 for the F12 key. Combinations involving the Shift, Ctrl,
and Alt keys are specified by appending "s", "c", or "a" onto the symbol. For
example, Ctrl-F1 is mapped using the symbol #1c.
8.2.3 Windows colors
WinElvis allows you use the :color command to change the colors used for the
different fonts. The color names that it supports are: black, blue, cyan,
green, red, magenta, brown, gray, darkgray, lightblue, lightcyan, lightgreen,
lightred, lightgray, yellow, and white.
8.2.4 Windows Printing
The default value of the lptype option is "windows". This uses the standard
Windows graphical print spooler and should be able to print on any printer
that Windows supports. The lpout option is ignored when lptype=windows.
However you still have the option of changing lptype to one of its other
values. The other values will generally print faster, and may even look
slightly better, but that isn't much of a motivation. A more common reason for
changing lptype would be to print into a file in a specified format.
8.2.5 Windows Fonts
WinElvis allows you to specify one base font for each window, via the font
option. You can set this to the name of any fixed-pitch font, such as
"courier*12".
Conceptually elvis supports six different fonts: normal, bold, italic, fixed,
emphasized, and underlined. WinElvis derives these six fonts from the base
font, via options named normalstyle, boldstyle, italicstyle, fixedstyle,
emphasizedstyle, and underlinedstyle, respectively.
Each of these options may be "n" to use the base font without any changes, or
any combination of "b" for bolding, "i" for italicizing, or "u" for
underlining. By default, boldstyle and emphasizedstyle use "b", italicstyle
uses "i", and underlinedstyle uses "u". You can override these via :set, and
make them be different colors via the :color command.
However, when printing WinElvis will always make them all black, and always
uses the default derived fonts.
8.3 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.)
Subsections here discuss terminal databases, termcap fields, keys, and graphic
characters.
If your terminal supports ANSI color escape sequences, then you can use the
:color command to assign different colors to the six basic fonts: normal,
bold, italic, underlined, emphasized, and fixed. You must assign a normal
color first, e.g., ":color normal yellow".
There are three additional options when using the termcap interface: term,
ttyrows,and ttycolumns. The term option contains the name of the termcap entry
being used; it should correspond to the type of terminal you're using. The
ttyrows and ttycolumns options give the size of the screen.
Under Win32, there is also a codepage option for detecting or changing the
current code page. Win32's termcap interface also supports the mouse, using
basically the same rules as the x11 interface. The only differences are that
it doesn't cut & paste via the clipboard, and pressing both buttons of a
two-button mouse will simulate pressing the missing middle button.
8.3.1 Termcap, Terminfo, and tinytcap
Termcap is a database of terminal characteristics, and a library of C
functions for accessing that database. It was created at Berkeley to allow the
original vi editor to be terminal-independent. Elvis' termcap user interface
was written to use this.
AT&T created the terminfo database and library, adding a few minor features.
Most modern UNIX systems use terminfo instead of termcap. Fortunately,
terminfo's library contains functions which emulate the termcap functions, so
the termcap interface can be compiled to work with the terminfo library.
The tinytcap.c file contains a simple reimplementation of the termcap library,
for those systems (such as MS-DOS) which don't have either a real termcap, or
terminfo. Tinytcap's database is hard-coded into it; to add or modify a
terminal description, you need to edit tinytcap.c and recompile elvis.
8.3.2 Common termcap values
This section describes most of the termcap values used by elvis. The values
which deal with cursor keys and graphic characters will be described in the
following sections.
Termcap field names are two characters long. Some names supply Boolean values,
and others supply numeric or string values. A Boolean value is made true by
giving the name; the absence of its name in a terminal's entry indicates a
false value for that field, for that terminal. For numeric fields, the name is
followed by a '#' character and then decimal digits specifying the value. For
string fields, the name is followed by a '=' character and then a string.
Fields are delimited by ':' characters.
.-------.----------------------------------------------------.
|TERMCAP| |
| FIELD | DESCRIPTION |
|-------|----------------------------------------------------|
| :AL=: | Insert a given number of lines before current line |
| :al=: | Insert one line before the current line |
| :am: | Automargin - cursor wraps at end-of-line |
| :bc=: | Move the cursor back one character |
| :cI=: | Set cursor shape to "insert" shape |
| :cQ=: | Set cursor shape to "quit" shape |
| :cR=: | Set cursor shape to "replace" shape |
| :cV=: | Set cursor shape to "vi command" shape |
| :cX=: | Set cursor shape to "ex command" shape |
| :ce=: | Clear from cursor to end-of-line |
| :cm=: | Move cursor to a given row/column |
| :co#: | Width of screen, in columns |
| :DC=: | Delete a given number of character at the cursor |
| :dc=: | Delete one character at the cursor position |
| :DL=: | Delete a given number of lines at the cursor |
| :dl=: | Delete one line at the cursor position |
| :IC=: | Insert a given number of characters at the cursor |
| :ic=: | Insert one character at the cursor position |
| :ke=: | Disable the cursor keypad |
| :ks=: | Enable the cursor keypad |
| :li#: | Height of screen, in lines |
| :md=: | Start bold text |
| :me=: | End bold or half-bright text |
| :mh=: | Start half-bright text (used for italic text) |
| :pt: | Terminal supports physical tabs |
| :se=: | End standout text |
| :sg#: | Width of gap required by the :so=:se=: strings |
| :so=: | Start standout text |
| :sr=: | Reverse scroll one line (limited form of :ic=:) |
| :te=: | String that elvis sends upon exiting |
| :ti=: | String that elvis sends when starting |
| :us=: | End underlined text |
| :ug#: | Width of gap required by the :us:ue:md:me: strings |
| :up=: | move cursor up one line |
| :us=: | Start underlined text |
| :vb=: | Visible alternative to the bell |
| :ve=: | Set cursor shape to "quit" shape |
| :vs=: | Set cursor shape to "vi command" shape |
| :xn: | Brain-damaged newline; ignore the :am: flag |
^-------^----------------------------------------------------^
8.3.3 Cursor Keys and Function Keys
Cursor keys and function keys generally send escape sequences when struck.
Elvis needs to know what those escape sequences are, so it can recognize the
keystroke and act accordingly.
The names of the fields for the arrows are pretty well standardized in
termcap, but the other cursor keys are still rather unsettled. Different UNIX
variants use different names for the same key. Elvis supports all common names
for each key.
Function keys are even more challenging. Originally termcap only had strings
which described the first 4 function keys. This was easy to extend to 9 keys,
but starting with the 10th function key things get strange because termcap
field names must be two characters long. Also, there was no way to describe
shift-function keys, control-function keys, or alt-function keys, so I
invented by own fields for them.
The following table lists all of the key field names, and the keys they refer
to. For keys which may be described via more than one field name, the
preferred field name is listed first. It also lists the key's label, as
reported by :map and what (if anything) that key is normally mapped to.
.-----------.---------------.-----------------------------------.
| KEY LABEL | TERMCAP NAMES | DESCRIPTION |
|-----------|---------------|-----------------------------------|
| <Up> | :ku=: | Up arrow, mapped to "k" |
| <Down> | :kd=: | Down arrow, mapped to "j" |
| <Left> | :kl=: | Left arrow, mapped to "h" |
| <Right> | :kr=: | Right arrow, mapped to "l" |
| <PgUp> | :kP=:PU=:K2=: | Previous Page, mapped to "^B" |
| <PgDn> | :kN=:PD=:K5=: | Next Page, mapped to "^F" |
| <Home> | :kh=:HM=:K1=: | Home, mapped to "^" |
| <End> | :kH=:EN=:K4=: | End, mapped to "$" |
| <Insert> | :kI=: | Insert key, mapped to "i" |
| <Delete> | :kD=: | Delete key, mapped to "x" |
| <CLeft> | :#4=:KL=: | Ctrl + Left arrow, mapped to "B" |
| <CRight> | :%i=:KR=: | Ctrl + Right arrow, mapped to "W" |
| #1 | :k1=: | F1 key |
| #2 | :k2=: | F2 key |
| #3 | :k3=: | F3 key |
| #4 | :k4=: | F4 key |
| #5 | :k5=: | F5 key |
| #6 | :k6=: | F6 key |
| #7 | :k7=: | F7 key |
| #8 | :k8=: | F8 key |
| #9 | :k9=: | F9 key |
| #10 | :k0=:ka=:k;=: | F10 key |
| #1s | :s1=: | Shift-F1 key |
| #2s | :s2=: | Shift-F2 key |
| #3s | :s3=: | Shift-F3 key |
| #4s | :s4=: | Shift-F4 key |
| #5s | :s5=: | Shift-F5 key |
| #6s | :s6=: | Shift-F6 key |
| #7s | :s7=: | Shift-F7 key |
| #8s | :s8=: | Shift-F8 key |
| #9s | :s9=: | Shift-F9 key |
| #10s | :s0=: | Shift-F10 key |
| #1c | :c1=: | Control-F1 key |
| #2c | :c2=: | Control-F2 key |
| #3c | :c3=: | Control-F3 key |
| #4c | :c4=: | Control-F4 key |
| #5c | :c5=: | Control-F5 key |
| #6c | :c6=: | Control-F6 key |
| #7c | :c7=: | Control-F7 key |
| #8c | :c8=: | Control-F8 key |
| #9c | :c9=: | Control-F9 key |
| #10c | :c0=: | Control-F10 key |
| #1a | :a1=: | Alt-F1 key |
| #2a | :a2=: | Alt-F2 key |
| #3a | :a3=: | Alt-F3 key |
| #4a | :a4=: | Alt-F4 key |
| #5a | :a5=: | Alt-F5 key |
| #6a | :a6=: | Alt-F6 key |
| #7a | :a7=: | Alt-F7 key |
| #8a | :a8=: | Alt-F8 key |
| #9a | :a9=: | Alt-F9 key |
| #10a | :a0=: | Alt-F10 key |
^-----------^---------------^-----------------------------------^
8.3.4 Graphic characters
Elvis uses graphic characters for HTML mode's <pre graphic> and <hr> tags.
Originally termcap didn't support a way to access the terminal's graphic
characters. A standard of sorts was eventually developed under the XENIX
variant of UNIX. Later, the terminfo library adopted a different way to access
the graphic characters, and this was worked back into the termcap standard,
displacing the XENIX standard. The terminfo method is preferred, these days.
Elvis supports both.
Terminfo Strings
.-------.---------------------------------------------------.
|TERMCAP| |
| FIELD | DESCRIPTION |
|-------|---------------------------------------------------|
| :as=: |Start graphic text |
| :ae=: |End graphic text |
| :ac=: |Maps VT100 graphic chars to this terminal's chars |
^-------^---------------------------------------------------^
The terminfo method uses the :as=:ae=: strings for turning the graphical
character attribute on and off. While in graphic mode, the value of the :ac=:
string is interpreted as a list of character pairs; the first character is a
VT-100 graphic character, and the following character is this terminal's
corresponding graphic character. The following table lists the (text versions
of) VT-100 graphic characters, and descriptions of them. It also includes IBM
PC characters.
.--------.--------.--------------------------------------.
| VT-100 | IBM PC | DESCRIPTION |
|--------|--------|--------------------------------------|
| 'q' | '\304' | horizontal line |
| 'x' | '\263' | vertical line |
| 'm' | '\300' | lower left corner (third quadrant) |
| 'v' | '\301' | horizontal line with up-tick |
| 'j' | '\331' | lower right corner (fourth quadrant) |
| 't' | '\303' | vertical line with right-tick |
| 'n' | '\305' | four-way intersection, like '+' sign |
| 'u' | '\264' | vertical line with left-tick |
| 'l' | '\332' | upper left corner (second quadrant) |
| 'w' | '\302' | horizontal line with down-tick |
| 'k' | '\277' | upper right corner (first quadrant) |
^--------^--------^--------------------------------------^
So, for example, an entry describing the IBM PC would contain the following:
:ac=q\304x\263m\300v\301j\331t\303n\305u\264l\332w\302k\277:
XENIX Termcap Strings
.-------.---------------------------------------------------.
|TERMCAP| |
| FIELD | DESCRIPTION |
|-------|---------------------------------------------------|
| :GS=: |Start graphic text |
| :GE=: |End graphic text |
| :GH=: |Horizontal bar |
| :GV=: |Vertical bar |
| :G3=: |Lower-left corner (i.e., third quadrant) |
| :GU=: |Horizontal bar with up-tick |
| :G4=: |Lower-right corner (i.e., fourth quadrant) |
| :GR=: |Vertical bar with right-tick |
| :GC=: |Center crosspiece (i.e., a big '+' sign) |
| :GL=: |Vertical bar with a left-tick |
| :G2=: |Upper-left corner (i.e., second quadrant) |
| :GD=: |Horizontal bar with a down-tick |
| :G1=: |Upper-right corner (i.e., first quadrant) |
^-------^---------------------------------------------------^
In Xenix, a separate string is used for each line-drawing graphic character.
There are also optional :GS=:GE=: strings for starting and ending graphic
mode. If the :GS=:GE=: strings aren't specified, then termcap is expected to
set the MSB of each character in the graphic character strings.
8.4 VIO Interface for OS/2
The vio interface is an OS/2-specific text-mode interface. It should behave
almost exactly like the termcap interface in all respects: same options, same
colors, same windowing features, etc. Unlike the termcap interface, the vio
interface must be run locally. It can't run over a network via telnet, but the
termcap interface can.
8.5 Open Interface
The open interface was created for use on terminals which lack some necessary
capability (such as the :cm=: cursor movement command), or terminals of an
unknown type. The open interface is ugly; if you have a choice, you should
always use the termcap interface instead.
The open interface works on all text terminals because the only control codes
it uses are backspace, carriage return, and line feed.
It only allows you to edit one line at a time. When you move to a new line
(e.g., by using the j or k commands), the screen scrolls up and the new line
is displayed at the bottom of the screen. This is true even when you're moving
the cursor back towards the beginning of the edit buffer; the lines of the
buffer will appear on the screen in reverse order! The open interface can be
very confusing.
However, practically all of the normal visual commands are available. The only
ones missing are those that specifically affect a whole window.
8.6 Quit Interface
The quit interface is intended to be used for executing scripts of ex
commands. It performs all of the usual initialization, and then quits. It is
normally used in conjunction with the -c command flag.
For example, you can have elvis load a file, print it, and then exit via the
following command line...
elvis -G quit -c lp somefile
Because the usual initialization guesses a file's display mode automatically,
this one command can be used to format and print HTML documents, man pages, C
code, and possibly hex dumps of binary files.
ΓòÉΓòÉΓòÉ 1.9. Elvis 2.1 Operating System Notes ΓòÉΓòÉΓòÉ
9. Operating System Notes
Elvis 2.1 currently runs under MS-DOS, MS-WindowsNT/MS-Winsdows95, OS/2, and
many versions of UNIX. This chapter describes the quirks of each
implementation.
In addition, elvis has been reported to work under a few other operating
systems. It isn't officially supported under these yet.
9.1 MS-DOS
Elvis 2.1 was ported to MS-DOS by Steve Kirkendall, using code from Guntram
Blohm and Martin Patzel's MS-DOS port elvis 1.X. It also uses Thomas Wagner's
"exec" function to swap elvis out to EMS/XMS memory or disk, while running
another program.
The "os" option
Under MS-DOS, the os option's value is "msdos".
The "shell" option
The default value of shell is "C:\COMMAND.COM". This can be
overridden by the value of the COMSPEC environment variable.
The "lpout" option
The default value of the lpout option is "prn", which causes the
:lpr command to write its output directly to the printer.
I tried to make it use the spooler program, PRINT, but failed. The
first problem I ran into was the fact that PRINT can't read data
from stdin; it must be given the name of a file. To work around this
problem, I modified the osmsdos/osprg.c file to allow $1 in the
command line to be replaced by the name of elvis' temporary file
that contains the print data.
This lead to the the second problem: PRINT doesn't make a copy of
the file, and elvis deletes the temporary file as soon as PRINT
exits. Since PRINT exits before the file has been printed
completely, this means that the file is deleted before PRINT is
through reading it. The print job is truncated. I was unable to find
a way around this problem, so I gave up and just set lpout=prn.
The "ccprg" option
The default value of the ccprg option is "cl /c ($1?$1:$2)", which
is appropriate for MSVC++ 1.5. This way, you can run :cc without
arguments to compile (but not link) the current source file. If you
supply arguments, they'll be used instead of the filename.
The "makeprg" option
The default value of the makeprg option is "make". You might
consider changing it to "nmake -f ($1?$1:basename($2)".mak")", would
allow MSVC++ 1.5 to compile "foo.c" via the "foo.mak" makefile,
unless you invoke :make with command-line arguments naming a
different makefile.
The "elvispath" option
The default value of the elvispath option is
"~\elvislib;BIN\lib;BIN", where BIN is the directory where elvis.exe
resides. Note that elements of the path are separated with
semicolons. The ~ character is replaced by the value of the home
option, which is also usually the name of the directory where
elvis.exe resides.
The "blksize" option
The blksize option controls the size of elvis' data blocks. Under
other operating systems this is usually 2048, but for MS-DOS is it
reduced to 1024 because memory is tight.
If you're going to be editing a large file, you may want to increase
the block size. The only way to do that is to invoke elvis with a
"-b2048" argument. You can't change it via ":set blksize=..."
because by then the session file would have already been created
with the old block size. Once elvis starts, you should probably
ensure that the blkcache is no more than 6 or so, or else elvis may
run out of memory unexpectedly.
The "TERM" environment variable
The TERM environment variable tells elvis how to access the screen.
If it is undefined, or set to "pcbios", then elvis will use BIOS
calls to access the screen. This should work on all MS-DOS systems,
but it isn't very fast.
If TERM is set to "dosansi" then elvis will output escape sequences
which are supported by the ANSI.SYS driver. This isn't recommended;
ANSI.SYS is just as slow as the BIOS, and it isn't as powerful so
elvis is forced to redraw the screen instead of scrolling it, in
some circumstances.
If TERM is set to "nansi" then elvis will output escape sequences
which are supported by more capable drivers, such as NANSI.SYS and
FANSI.SYS. These drivers usually bypass the BIOS, so they are very
fast. If you're looking for a way to speed up elvis, this is
probably your best bet. The Web URL for these drivers is listed in
the Tips chapter.
Elvis also supports "vt220" which use DEC VT-220 escape codes, and
"ansi" which uses true ANSI escape codes for both input and output.
"ansi" doesn't work with ANSI.SYS!
The "termcap" user interface
Under MS-DOS, elvis normally uses the termcap user interface. It
supports the :color command, and the mouse.
Missing features
Because elvis must run in the lower 640k, it is normally compiled
with certain features disabled. If you want to enable these, or
disable more of them, you'll need to edit the config.h file and
recompile elvis. Normally the missing features are:
PROTOCOL_HTTP and PROTOCOL_FTP - These two must remain
disabled, because no source code is provided for supporting
these features under MS-DOS. You can't enable them unless you
write the necessary WinSock code. (And if you do write that
code, please share it with me!)
FEATURE_SHOWTAG - The showtag option, which attempts to
continually display the name of the function you're editing.
FEATURE_COMPLETE - The <Tab> key in ex command lines normally
attempts to complete a file name or other word.
FEATURE_RAM - This would allow elvis to store its edit buffers
in EMS/XMS memory instead of a session file, by specifying "-f
ram" on the command line. This makes elvis run much faster,
but you can't recover the contents of the edit buffers after a
crash. Also, the Microsoft functions for accessing EMS/XMS
memory are bulky and require a fairly large buffer space, so if
you #define FEATURE_RAM then you must #undef every other
FEATURE_XXXXX, and even then you may run out of memory
occasionally.
9.2 MS-Windows95/MS-WindowsNT
Elvis 2.1 was ported to Windows95/WindowsNT as a text application by Steve
Kirkendall. The graphical user interface was written by Serge Pirotte.
Windows doesn't allow a single program to have both a text-mode interface and
a graphical interface, so we include two separate versions of elvis. ELVIS.EXE
is the text-mode version, and WINELVIS.EXE is the graphical version. Run
"elvis -G?" for a list of the text-mode user interfaces supported; you will
generally want to use the "termcap" interface. The graphical version, of
course, is unable to output such a list. It supports two user interfaces,
named "windows" and "quit".
The "os" option
Under Windows95/WindowsNT, the os option's value is "win32".
The "shell" option
The default value of shell is "cmd". If the COMSPEC environment
variable is set (and it normally is), then its value will be used
instead of "cmd". This is important, because Windows95 uses
"COMMAND.COM" instead of "CMD.EXE".
The "lpout" option
The default value of the lpout option is "prn", which causes the
:lpr command to send text directly to the printer.
The "lptype" option
The default value of the lptype option is "dumb" in elvis.exe, or
"windows" in WinElvis.exe.
The "windows" printer type is only available in WinElvis; it causes
elvis to use the standard Windows graphics-oriented print spooler.
This is a very slow way to print, but it is portable and produces
good-looking output.
The "ccprg" option
The default value of the ccprg option is "cl /c ($1?$1:$2)", which
is appropriate for MSVC++ 2.0 or later. This way, you can run :cc
without arguments to compile (but not link) the current source file.
If you supply arguments, they'll be used instead of the filename.
The "makeprg" option
The default value of the makeprg option is "make". You might
consider changing it to "nmake -f ($1?$1:basename($2)".mak")", would
allow MSVC++ 2.0 (or later) to compile "foo.c" via the "foo.mak"
makefile, unless you invoke :make with command-line arguments naming
a different makefile.
The "elvispath" option
The default value of elvispath is "~\elvislib;BIN;BIN\lib", where
BIN is the name of the directory where ELVIS.EXE resides. Note that
elements of the path are separated with semicolons. The ~ character
is replaced by the value of the home option, which is usually
C:\users\default for WindowsNT.
Unlike MS-DOS, Win32 doesn't pass the full pathname of the .EXE file
as an argument to the program. So the when the Win32 version of
elvis starts up, the first thing it does is search for ELVIS.EXE in
your execution path. It must do this in order to find the value to
use as BIN.
The "TERM" environment variable
The TERM environment variable tells elvis how to access the screen.
It should probably be left undefined, or set to "console". Other
values have not been tested, but the following should work via
terminal emulators or whatever: dosansi, nansi, vt100, vt100w, and
vt52.
Console size
Win32 distinguishes between a console's buffer size and its window
size. Many users like to set the buffer to a huge size (e.g., 100
lines) but leave the window set at 25 lines. They do this so they
can scroll back and review earlier programs' output.
When elvis starts, it creates a separate buffer which is the same
size as the window (except under Windows95 which has bugs in this
area). Elvis does this mostly so the scrollbar will go away. If you
change the buffer size while elvis is running, elvis will adjust the
size of the window to match the new buffer size, and then redraw the
text to take advantage of the new screen size.
You can change the console buffer's size by setting the ttyrows and
ttycolumns options. In WindowsNT, you can also change the size via
the console's Properties dialog.
When you exit elvis, the console will revert to its original buffer
and original window size.
Mouse
In WinElvis (graphical mode), the mouse works about like you'd
expect. You can select character spans by dragging the mouse through
the text while holding the left button down. You can select a
rectangular area by dragging with the right button down. To select
whole lines, move the mouse to the left margin, where the cursor
shape changes to an up-and-right arrow, and start dragging with the
left button there. Double-clicking on a word with the left button
will do a tag search on that word; double-clicking the right button
pops returns to the original position. At present, there is no way
to bring up a menu with the right button.
In elvis (text mode), the mouse should work both in full-screen mode
and in a window. Dragging with the left, right, or both buttons
pressed is will select characters, whole lines, or a rectangular
block, respectively. If you have a three-button mouse and the
appropriate driver, dragging with the middle button pressed will
also select a rectangular block. Clicking the left button will
cancel a pending text selection, and move the cursor. Clicking the
right button will move the cursor; if a text selection is pending,
it will be extended to the new cursor position. Double-clicking the
left or right button will follow a hypertext reference or return
from one, respectively.
There is a weird bug in WindowsNT's text-mode mouse support. If,
when the console is shown in a window, part of that console is
located off-screen, then the mouse won't be able to move there, even
if you're currently in full-screen mode! Since WindowsNT will
sometimes resize your console when you switch between full-screen
and windowed modes, this might not be obvious. But if the mouse
refuses to move onto part of your full-screen console, I suggest you
switch back to windowed mode and reduce the size of your font there.
When you switch back to full-screen mode again it will look exactly
the same, but the mouse should be able to go where no mouse has gone
before.
9.3 OS/2
Elvis 2.0 was ported to OS/2 by Lee Johnson, but that port was too late to be
included in the standard distribution of elvis 2.0. After that, Martin
"Herbert" Dietze took over the job, and brought it up to date for elvis 2.1.
OS/2-specific bug reports or comments should be sent to
herbert@paulina.shnet.org.
The basic OS/2 version uses the vio user interface, and doesn't require any
special libraries.
There is also a version which supports the termcap user interface in addition
to the standard VIO interface. This should allow you to run elvis over a
telnet connection. However, it requires the EMX.DLL library.
Another supports the x11 graphical interface in addition to VIO and the
termcap interface. It requires the X11.DLL library from XFree86, and the
EMX.DLL library. The X11 version can run under PMX provided you have XFree86's
X11.DLL file, but if you want to recompile elvis from scratch you'll need the
whole XFree86 package.
There are two separate VIO versions: a full-featured version named elvis.exe,
and version which lacks Internet support, named elvis-no-tcp.exe. The latter
version is required if your OS/2 system doesn't have TCP/IP software
installed; otherwise you should use the full-featured version. The termcap and
x11 versions both require TCP/IP.
The "os" option
Under OS/2, the os option's value is "os2".
The "shell" option
The default value of shell is "cmd.exe".
The "lpout" option
The default value of the lpout option is "prn", which causes the
:lpr command to send text directly to the printer.
The "ccprg" option
The default value of the ccprg option is "gcc -c ($1?$1:$2)". You
may want to change it. This way, you can run :cc without arguments
to compile (but not link) the current source file. If you supply
arguments, they'll be used instead of the filename.
The "makeprg" option
The default value of the makeprg option is "make $1".
The "elvispath" option
The default value of elvispath is "~\elvislib;BIN;BIN\lib", where
BIN is the name of the directory where elvis.exe resides. Note that
elements of the path are separated with semicolons. The ~ character
is replaced by the value of the home option.
The "TERM" environment variable
Although the OS/2 version of elvis does support the "termcap"
interface, it usually uses its own "vio" interface for text console
I/O. The "vio" interface ignores TERM completely.
But the termcap interface is still supported, if compiled using
emx/gcc and linked against emx.dll both the usual "vio" and a
termcap based interface are available.
The mouse
Elvis ignores the mouse, under OS/2.
9.4 UNIX
Elvis was originally written under UNIX, so it seems strange to say I ported
it to UNIX, but I'll say it anyway: Elvis 2.1 was ported to UNIX by Steve
Kirkendall, with a lot of feedback from many people on the net.
Since elvis (and vi, for that matter) were originally designed and written for
UNIX, there aren't many quirks that show up for generic UNIX. Most of this
section will describe the quirks of individual UNIX versions.
The "os" option
Under all versions of UNIX, the os option's value is "unix".
The "lpout" option
The default value of the lpout option is either "!lp -s" or "!lpr".
The choice is made by the configure script; if /usr/bin/lp exists
then it will use "!lp -s", else it will use "!lpr".
The "elvispath" option
The default value of elvispath is usually
~/.elvislib:/usr/local/lib/elvis. The /usr/local/lib/elvis member of
that path can be set via the --datadir=directory flag to the
configure script.
Missing functions
If your linker reports an undefined function, such as strdup(), then
you should check the need.h and need.c files; they contain
implementations of many such functions. To use elvis' version of the
missing function, edit the config.h file and change "#undef
NEED_XXX" to "#define NEED_XXX".
In all of the officially supported Unix variants listed below, the
configure script automatically selects any necessary NEED_XXX
macros.
9.4.1 UNIX versions
The configure script works around most of the quirks of individual UNIX
versions. Here, I will describe what configure does, or fails to do, for each
type of UNIX.
SunOS and Solaris
SunOS and Solaris2 both claim to be SunOS, according to the uname
command. However, their configuration is quite different, so the
configure script distinguishes between them by looking at the
revision number output by "uname -r".
The SunOS port uses BSD's sgtty ioctl calls, instead of the POSIX
calls, even though SunOS supports the POSIX calls. This choice was
made because differences in signal handling were preventing the
SunOS port from responding to window resize signals.
Solaris2 seems to have a bad implementation of rlogin, at least on
the system where I tested it. It couldn't handle 2000-character
write() calls. Because this is a communication issue, and not purely
a Solaris issue, I decided to reduce the size of the output buffer
for all systems to 1500 bytes.
The SunOS port uses termcap because I prefer it. The Solaris port
uses terminfo because Solaris doesn't seem to have a termcap
library.
Sun's normal C compiler, "cc", only supports the old K&R syntax, not
ANSI syntax. Some of your standard (non-elvis) header files may
include a "const" declaration which K&R doesn't understand, so if
you aren't using GCC then the configure script will append
"-Dconst=" to the value of the CC macro in your Makefile, so the
"const" keyword will be ignored.
If you configure elvis to support X-windows, and your
LD_LIBRARY_PATH environment variable doesn't contain an X11 library
directory, then the configure script will output a warning message
telling you how to set that variable. However, you might not need to
set it; try running elvis without setting it first.
OSF-1
This configuration is rather weird. I don't have access to an OSF-1
system myself, so it's hard for me to make it less weird.
The primary weirdness is that it uses tinytcap.c (by defining
NEED_TGETENT in the config.h file) instead of the real terminfo
functions. I suggest you try compiling without NEED_TGETENT.
BSD
For BSD, configure will try to use the shlicc2 compiler if it is
available, so elvis can use shared libraries.
Interestingly, the BSD port is configured to use POSIX ioctl calls
instead of BSD's own sgtty calls. This may be a mistake. If elvis
fails to adjust when you resize your xterm, then I suggest you run
"configure --ioctl=sgtty", and recompile.
SCO
SCO likes to change the operating system name (as reported by the
"uname" command) to match the network node name. If uname reports a
brand of Unix that configure doesn't recognize, then configure will
inspect the files on your system for evidence that you're running
SCO Unix/ODT or SCO Xenix. If that test fails, you'll need to give
the OS name on the the command line when invoking configure (e.g.,
"configure sco" or "configure xenix").
When using an ANSI compiler, SCO seems to require extern
declarations of the termcap functions. I added those declarations to
the end of the "osunix/osdef.h" file.
Linux
Newer versions of Linux seem to have moved the definition of the
speed_t data type from its tradional location, <sys/types.h>. The
new location is <termios.h>, which makes sense since that's where
the legal values of speed_t are defined... but because it is
non-standard, I had to add a little extra code to the
"osunix/osdef.h" file to include <termios.h> for Linux.
9.5 Other operating systems
Elvis has been reported to work without modification on Atari ST/TT systems
with MiNT. The only special trick is that you must configure it with
"configure --ioctl=sgtty". Without the "--ioctl=sgtty", elvis would be
configured to use the POSIX termios ioctl() calls, which don't work quite
right under MiNT.
If you would like to port elvis to another operating system, please contact me
first. I can send you some notes I have about how the OS-dependent functions
in the os*/*.c files should behave, and also how the GUI functions should
behave. That's normally all you need to write in order to port elvis to a new
operating system.
A Macintosh port is currently underway. I still need volunteers to port it to
VMS and OS-9. I would also welcome a port for any other popular system.
ΓòÉΓòÉΓòÉ 1.10. Elvis 2.1 Sessions ΓòÉΓòÉΓòÉ
10. SESSIONS, INITIALIZATION, AND RECOVERY
This section of the manual describes the life-cycle of an edit session. We
begin with the definition of an edit session and what that means to elvis. This
is followed by sections discussing initialization and recovery after a crash.
10.1 Sessions
Elvis is eventually expected to meet the COSE standards, which require (among
other things) that programs be able to save their state so that they can be
restarted later. It isn't required to restart in exactly the same state, but it
should come as close as possible.
For elvis, this means that edit sessions should be restartable. It is possible
to begin an edit session with one elvis process, exit that process, and then
later start a new elvis process which resumes the previous edit session.
To accomplish this, elvis stores its state in a file, called the session file.
For all practical purposes, the session file is the session.
The name of the session file is stored in the session option. By default, this
will be a file in your home directory, named "elvis*.ses", where "*" represents
a number chosen at run-time to make the file name unique. You can specify some
other name for the session file via the -ssession command-line flag.
If the session file doesn't already exist when elvis starts running, then elvis
will create it.
When elvis exits, it will normally delete the session file if this is the elvis
process that created it. If the session file was left over from some other
elvis process, then elvis will not delete it upon exiting. This is controlled
by the tempsession option; if you don't like elvis' default behavior then you
can change it.
10.2 Initialization
Before discussing elvis' initialization, let me just say that if you're having
trouble configuring elvis, you might want to try invoking elvis with the
command line flag -VVV, which causes elvis to write status information to
stdout/stderr so you can see what it is doing. The flag -ologfile will redirect
this information to a file named logfile. Windows programs such as WinElvis.exe
aren't allowed to write anything to stdout, so you must use -ologfile any time
you use -VVV. Now, back to the topic at hand...
Elvis begins by initializing some options to hardcoded values.
Elvis then chooses which user interface it should use. Elvis does this by
scanning the command line arguments for a -Ggui flag; if there is no such flag,
then elvis tests each user interface and uses the best one that is expected to
work. (For example, the "x11" interface is expected to work if there is a
DISPLAY environment variable and the X server is accessible. If not, then the
"x11" interface is rejected and some other interface is used.)
The session file is then opened or created. For preexisting session files,
elvis scans the session file for any buffers in it, and adds them to its
internal list. Elvis can even reload the "undo" versions of some buffers.
Elvis searches through the directories named in the elvispath option for a file
named "elvis.ini". If it finds that file, then it loads it into a buffer named
"Elvis initialization" and executes its contents as a series of ex commands.
See section 10.2.1 for description of the default contents of this file.
After that, it attempts to similarly load some other files, but they aren't
executed. Some of them will be executed later. These files are:
.-----------.----------------------.------------------------------.
| FILE NAME | BUFFER NAME | PURPOSE |
|-----------|----------------------|------------------------------|
| elvis.msg | Elvis messages | used to translate messages |
| elvis.brf | Elvis before reading | executed before loading file |
| elvis.arf | Elvis after reading | executed after loading file |
| elvis.bwf | Elvis before writing | executed before saving file |
| elvis.awf | Elvis after writing | executed after saving file |
^-----------^----------------------^------------------------------^
The "elvis.msg" file is described in section 11: Messages. The other files are
described later in this section.
The next step in initialization is to load the first file and display it in a
window. To do this, it first creates an empty buffer with the same name as the
file. It then executes the "Elvis before reading" buffer (if it exists) on the
empty buffer. The file's contents are then read into the buffer. Then the
"Elvis after reading" buffer (if it exists) is executed on the new buffer.
Finally, elvis creates a new window that shows the new buffer.
If the -a flag was given on the command line, then elvis will repeat the above
steps for each file named on the command line. On the other hand, if no
filenames were given on the command line then elvis will simply create a single
untitled buffer and a window that shows it.
10.2.1 The "elvis.ini" file
The "elvis.ini" file is loaded into a buffer named "Elvis initialization".
That buffer is then executed before any other initialization files are loaded.
If the session file is later restarted, this script will be executed again at
that time. Here's a line-by-line analysis of the default "elvis.ini" file...
" DEFINE SOME DIGRAPHS
if os=="msdos" || os=="os2" || (os=="win32" && gui!="windows")
then source! (elvispath("elvis.pc8"))
else source! (elvispath("elvis.lat"))
This attempts to locate the "elvis.lat" or "elvis.pc8" file and execute it.
Those files contain ex scripts, consisting of a bunch of :digraph commands that
set up the digraph table appropriately for the Latin-1 symbol set. The "!" at
the end of the :source command name causes :source to silently ignore errors.
" CHOOSE SOME DEFAULT OPTION VALUES BASED ON THE INVOCATION NAME
let p=tolower(basename(program))
if p == "ex" || p == "edit"
then set! initialstate=ex
if p == "view"
then set! defaultreadonly
if p == "edit" || p == "vedit"
then set! novice
if home == ""
then let home=dirdir(program)
These lines initialize certain options according to the name by which elvis was
invoked. Traditionally, invoking vi by the name "ex" causes it to start up in
ex mode instead of vi mode, and "view" causes the files to be treated as
readonly.
" SYSTEM TWEAKS GO HERE
"
" The Linux console can't handle colors and underlining.
if gui=="termcap"
then {
if term=="linux"
then set! nottyunderline
}
This is an attempt to work around a bug in the Linux console driver. The Linux
console can't mix color attributes with the underline attribute.
" WINDOWS DEFAULT COLORS GO HERE (may be overridden in elvis.rc file)
if gui=="windows"
then {
color e green
color i magenta
color u blue
color f red
}
" X11 DEFAULT COLORS AND TOOLBAR GO HERE (may be overridden in .exrc file)
if gui=="x11"
then so! (elvispath("elvis.x11"))
These lines set the defaults for the "windows" and "x11" user interfaces.
Note that "x11" configuration commands are actually stored in a separate file.
This is because there are large number of commands for setting up the toolbar,
and I didn't want to force other GUIs to read them just to ignore them. You
should set the defaults in "elvis.x11", and not in an app-defaults file. If you
aren't using the "x11" user interface, then these lines have no effect.
" EXECUTE THE STANDARD CUSTOMIZATION SCRIPTS
let f=(os=="unix" ? ".elvisrc" : "elvis.rc")
if $EXINIT
then eval $EXINIT
else source! (exists("~"/f) ? "~"/f : "~/.exrc")
if exrc && getcwd()!=home
then safer! (exists(f) ? f : ".exrc")
set f=""
;
These lines set the f option to either ".elvisrc" or "elvis.rc", whichever is
appropriate for your operating system. They then check whether an environment
variable named "EXINIT" is set to a non-empty value. If so, then the value of
EXINIT is executed as an ex command line; otherwise the ".elvisrc" or
"elvis.rc" file in your home directory is executed, if it exists. If that file
doesn't exist, then it tries ".exrc"... which probably only makes sense for
Unix, but it is quicker to try & fail then to test before trying. The "~"
notation is UNIX's conventional alias for referring to files in your home
directory; elvis handles it correctly on non-UNIX systems too.
Note: There is a hardcoded limit of (normally) 1023 characters for the result
of an expression. If your EXINIT environment variable's value is longer than
that, elvis won't be able to execute it.
If EXINIT or .elvisrc/elvis.rc/.exrc (whichever was executed) has set the exrc
option then elvis will execute ".elvisrc" or "elvis.rc" in the current
directory, if it exists; if not, then it tries ".exrc". Elvis uses :safer
instead of :source to execute the file for security reasons.
" X11 INTERFACE DEFAULT FONTS GO HERE
if gui == "x11"
then if normalfont == ""
then {
set! normalfont="*-courier-medium-r-*-18-*"
set! boldfont="*-courier-bold-r-*-18-*"
set! italicfont="*-courier-medium-o-*-18-*"
}
These cause the x11 interface to use 18-point courier fonts, if you don't
explicitly name some other font on the command line (-font fontname) or by
setting the normalfont option in your .exrc file.
10.2.2 The "elvis.brf" file
The "elvis.brf" file is loaded into a buffer named "Elvis before reading".
That buffer is executed immediately before loading any user file into a user
buffer.
" TAKE A GUESS AT THE BUFFER'S TYPE
let! readeol=fileeol(filename)
This line tries to guess whether the file is binary or not. This must be done
before the file is loaded because for non-binary files elvis converts newlines
to linefeeds as it reads the file.
10.2.3 The "elvis.arf" file
The "elvis.arf" file is loaded into a buffer named "Elvis after reading". That
buffer is automatically executed immediately after a user file has been loaded
into a user buffer.
" TAKE A GUESS AT THE BUFFER'S PREFERRED DISPLAY MODE
let e=tolower(dirext(filename))
if knownsyntax(filename)
then set! bufdisplay=syntax
if os=="unix" && buflines >= 1
then 1s/^#! *[^ ]*\/\([^ ]\+\).*/set! bufdisplay="syntax \1"/x
if !newfile
then {
if readeol=="binary" && bufdisplay=="normal"
then set! bufdisplay=hex
if e==".man"
then set! bufdisplay=man
if strlen(e)==2 && isnumber(e>>1) && buflines>=1
then 1s/^\./set! bufdisplay=man/x
if e==".tex"
then set! bufdisplay=tex
if e<<4==".htm"
then set! bufdisplay=html
if buflines >= 1 && bufdisplay=="hex"
then 1s/^<[HIThit!]/set! bufdisplay=html/x
if (filename<<5=="http:" || filename<<4=="ftp:")
&& strlen(e)<4 && bd=="hex"
then set! bufdisplay=normal
if bufdisplay=="normal" && buflines >= 1
then 1s/^From .*/set! bufdisplay="syntax email"/x
if dirdir(filename)=="/tmp" || dirdir(filename)=="/var/tmp"
then set! bufdisplay="syntax email"
}
These lines try to guess the preferred display mode for the file. First it
checks to see if the filename's extension is listed in the elvis.syn file; if
so, then the buffer is shown in the syntax display mode. Then, for UNIX, if the
first line of the file starts with "#!shell", elvis will use the syntax display
mode for that named shell. This is followed by many special cases.
" EXECUTE MODELINES, IF "modelines" OPTION IS SET
if modelines && buflines >= 1 && buflines <= modelines * 2
then %s/ex:\(.*\):/\1/x
if modelines && buflines > modelines * 2
then {
eval 1,(modelines)s/[ev][xi]:\\\(.*\\\):/\1/x
eval (buflines - modelines + 1),(buflines)
s/[ev][xi]:\\\(.*\\\):/\1/x
}
These commands search for modelines in the newly loaded file, if the modelines
option is set. The modelines are executed via the new "x" option to the :s
command.
Note: The second "eval" line is split above merely as a typographical
convenience. In the real "elvis.arf" file, the "eval" line and "s" line are
actually a single line.
10.2.4 The "elvis.bwf" file
The "elvis.bwf" file is loaded into a buffer named "Elvis before writing".
That buffer is executed as a series of ex commands immediately before writing
the entire contents of a buffer out over its original file.
if backup && !newfile
then {
if os=="unix"
then eval ! cp (filename) (filename).bak
else eval ! copy (filename) (basename(filename)).bak >NUL
}
These lines copy the original version of the file to a "*.bak" file. Note that
we implement separate Unix and non-Unix versions of the copy command here.
10.2.5 The "elvis.awf" file
The "elvis.awf" file is loaded into a buffer named "Elvis after writing". That
buffer is executed as a series of ex commands immediately after writing the
entire contents of a buffer out over its original file.
There is no default "elvis.awf" file, because I haven't found any need for one
yet.
10.3 Recovery
If elvis ever dies an unnatural death, the session file will be left behind.
This session file contains all of the changes you've made during your edit
session, so you should be able to start a new elvis process on the old session
file and recover all of your changes.
Only one elvis process at a time is allowed to use a given session file. To
enforce this, when elvis starts up it sets an "in use" flag in the session
file's header. Any later elvis process will test that flag, and refuse to use a
session file which is already in use.
When elvis crashes, it leaves the "in use" flag set, even though the process
that was using it has died. You must restart your edit session via "elvis -r".
The -r flag tells elvis to ignore the "in use" flag. If you aren't using the
default session file, then you'll need to add a "-f sessionfile" flag to tell
elvis which session file it should recover from.
If you always use the default session file, and allow several old files to
accumulate after crashes, then "elvis -r" will always recover from the
lowest-numbered one. The command "elvis -r -Gquit" will tell you its name. If
you prefer to recover form a different session file, you can either delete the
lower-numbered session files, or use the "-f sessionfile" flag to make elvis
use a different one.
When this new elvis process starts up, it will be displaying a new, empty
buffer. Don't panic! Your edit buffers are still intact; they just don't happen
to be displayed in the initial window.
After a crash, the session file might not be entirely self-consistent. Because
of this, it is dangerous to edit the file using this session file. You should
save your old buffer to a file immediately, and then exit elvis. To save your
old buffer give elvis the command ":(buffer)w filename" where buffer is the
name of your buffer (usually the same as the original file name) and filename
is the name of a new file where you wish to store the text. Note that the
buffer name should be in parentheses! And for safety's sake, you should not
write the salvaged buffer out over the top of the original text file.
Under normal circumstances elvis automatically deletes the session file when it
exits, but when recovering after a crash elvis is more cautious. It never
deletes a recovered session file itself. After recovering your text and exiting
elvis, you should manually delete the session file via "rm
/var/tmp/elvis*.ses", or whatever the session file's name is. For DOS/Windows
users, the command would be "DEL \TEMP\ELVIS*.SES".
If you can figure out how to reproduce the problem, please let me know! My
email address is kirkenda@cs.pdx.edu
10.4 Other files
The following configuration files aren't necessarily related to initialization
or sessions, but since we've discussed so many configuration files in this
chapter already, we might as well finish it off.
*.man
These files are Unix-style "man pages" describing each of the
programs. You can view them with elvis' "man" display mode, or you
can print them via " troff -man ..." or the local equivalent.
elvis.ftp or ~/.netrc
This file stores account names and passwords to be used when
contacting certain FTP sites. It is described in Chapter 15: The
Internet.
elvis*.html
These files store the on-line interactive manual for elvis. When you
use the :help command, elvis locates the necessary file and loads
it. These files are written in HTML so you can also view/print them
using a Web browser such as Netscape.
howto.html
This file contains a lot of "How To" discussions for various
features. It is meant to be searched via the ":howto" alias defined
in exalias.eg. Most of the discussions contain links into the
manual, so it is important for this file to be located in the same
directory as all of the elvis*.html files.
elvis.lat
This file contains a bunch of :digraph commands for setting up the
digraph table for the Latin-1 symbol set. The default elvis.ini file
interprets this file's contents automatically.
elvis.pc8
This file contains a bunch of :digraph commands for setting up the
digraph table for the PC-8 symbol set (which corresponds to IBM Code
Page 437). The default elvis.ini file interprets this file's
contents automatically for MS-DOS, OS/2 and text-mode Win32.
elvis.msg
This file stores a translation table, which allows you to customize
elvis' messages. This file is described in the Messages chapter.
elvistrs.msg
This contains a rough list of nearly all of elvis' terse messages.
You can use this as a resource when constructing an elvis.msg file.
elvis.net
This tells elvis which sites can be accessed directly, and which can
only be accessed via proxy servers. It is described in Chapter 15:
The Internet.
elvis.ps
The PostScript printer drivers (lptype=ps or ps2) include this
file's contents in the printer output. This file should contain
PostScript code which defines the symbols ElvisN, ElvisB, and ElvisI
as 12-point monospaced fonts to be used for normal text, bold text,
and italic text, respectively. It also defines ElvisPage,
ElvisLeftPage, and ElvisRightPage procedures for setting the size
and position of a page's text on the paper. If this file doesn't
exist or is unreadable, elvis will use the following definitions:
/ElvisN /Courier findfont 12 scalefont def
/ElvisB /Courier-Bold findfont 12 scalefont def
/ElvisI /Courier-Oblique findfont 12 scalefont def
/ElvisPage { 12 36 translate } def
/ElvisLeftPage { 12 750 translate -90 rotate 0.58 0.75 scale } def
/ElvisRightPage { newpath 12 394 moveto 576 0 rlineto stroke
12 366 translate -90 rotate 0.58 0.75 scale } def
elvis.syn
This contains descriptions of all languages supported by the syntax
display mode. For a full description of this file, see the Language
Specification section in the Display Modes chapter.
elvis.xbm
This stores a two-color Elvis icon, in the X-Windows XBM format.
elvis.xpm
This stores a four-color Elvis icon, in the X-Windows XPM format.
printdoc.bat
This contains a series of program invocations for printing all of
the elvis documentation in the correct sequence. This file should be
executable under MS-DOS, Win32, and Unix. You must install elvis
before this will work!
ΓòÉΓòÉΓòÉ 1.11. Elvis 2.1 Cut Buffers ΓòÉΓòÉΓòÉ
11. CUT BUFFERS
When Elvis deletes text, it stores that text in a cut buffer. This happens in
both visual mode and EX mode. There are 36 cut buffers: 26 named buffers ("a
through "z), 9 anonymous buffers ("1 through "9), and 1 extra cut buffer (".).
There is no practical limit to how much text a cut buffer can hold.
11.1 Putting text into a Cut Buffer
In visual mode, text is copied into a cut buffer when you use the d, y, c, C,
s, or x commands. There are also a few others.
By default, the text goes into the "1 buffer. The text that used to be in "1
gets shifted into "2, "2 gets shifted into "3, and so on. The text that used to
be in "9 is lost. This way, the last 9 things you deleted are still accessible.
You can also put the text into a named buffer -- "a through "z. To do this, you
should type the buffer's name (two keystrokes: a double-quote and a lowercase
letter) before the command that will cut the text. When you do this, "1 through
"9 are not affected by the cut.
You can append text to one of the named buffers. To do this, type the buffer's
name in uppercase (a double-quote and an uppercase letter) before the
d/y/c/C/s/x command.
The ". buffer is special. It isn't affected by the d/y/c/C/s/x command.
Instead, it stores the text that you typed in the last time you were in input
mode. It is used to implement the . visual command, and ^A in input mode.
In EX mode, the :delete, :change, and :yank commands all copy text into a cut
buffer. Like the visual commands, these EX commands normally use the "1 buffer,
but you can use one of the named buffers by giving its name after the command.
For example...
:20,30y a
... will copy lines 20 through 30 into cut buffer "a.
You can't directly put text into the ". buffer, or the "2 through "9 buffers.
11.2 Pasting from a Cut Buffer
There are two main styles of pasting: line-mode and character-mode. If a cut
buffer contains whole lines (from a command like "dd") then line-mode pasting
is used; if it contains partial lines (from a command like "dw") then
character-mode pasting is used. The EX commands always cut whole lines.
Elvis also supports a limited form of rectangular cut and paste. This is handy,
for example, when you want to swap two columns in a table. The only way to put
a rectangular area into a cut buffer is to select it via the visual ^V command,
and then yank or delete it with a y or d command, respectively. When a cut
buffer has been filled this way, it will be pasted using rectangle-mode
pasting.
Character-mode pasting causes the text to be inserted into the line that the
cursor is on.
Line-mode pasting inserts the text on a new line above or below the line that
the cursor is on. It doesn't affect the cursor's line at all.
In visual mode, the p and P commands insert text from a cut buffer. Uppercase P
will insert it before the cursor, and lowercase p will insert it after the
cursor. Normally, these commands will paste from the "1 buffer, but you can
specify any other buffer to paste from. Just type its name (a double-quote and
another character) before you type the P or p.
In EX mode, the :put command pastes text after a given line. To paste from a
buffer other that "1, enter its name after the command.
11.3 Macros
The contents of a named cut buffer can be executed as a series of ex/vi
commands.
To put the instructions into the cut buffer, you must first insert them into
the file, and then delete them into a named cut buffer.
To execute a cut buffer's contents as EX commands, you should give the EX
command :@ and the name of the buffer. For example, :@z will execute "z as a
series of EX commands.
To execute a cut buffer's contents as visual commands, you should give the
visual command @ and the letter of the buffer's name. The visual @ command is
different from the EX :@ command. They interpret the cut buffer's contents
differently.
The visual @ command can be rather finicky. Each character in the buffer is
interpreted as a keystroke. If you load the instructions into the cut buffer
via a "zdd command, then the newline character at the end of the line will be
executed just like any other character, so the cursor would be moved down 1
line. If you don't want the cursor to move down 1 line at the end of each @z
command, then you should load the cut buffer by saying 0"zD instead.
One way to store keystrokes into a buffer for use with the visual @ command is
via the [key and ]key commands. They record keystrokes into a cut buffer as
you type them.
11.4 The Effect of Switching Files
Elvis 2.1 retains the contents of all cut buffers when you switch files, e.g.
via a :next or :edit command. This differs from the traditional behavior of vi.
In the real vi and in elvis 1.X, the anonymous buffers ("1 through "9) were
clobbered and the named buffers ("a through "z) were left intact. This made
sense then, but since elvis 2.1 allows you to edit several files at the same
time, the rules changed.
11.5 Cut & Paste Between Applications
There is a special cut buffer named "^ (doublequote-carat) which accesses the
GUI's cut&paste feature. Each time you yank text into the "^ cut buffer, it is
copied to the GUI's clipboard. Each time you paste text from the "^ cut
buffer, elvis reads from the GUI's clipboard.
Not all GUIs have clipboards. For example, the plain old termcap interface
doesn't have one. The "^ cut buffer still exists, but it resides inside elvis,
just like any other cut buffer. (Exception: The Windows version of the termcap
interface has been patched to access the Windows clipboard.)
Elvis' X11 interface does use X's clipboard. Clicking the middle mouse button
causes the clipboard's contents to be inserted at the cursor position. When
you select text via the mouse, the text is immediately copied to the clipboard.
Text that you select via keyboard commands is not automatically copied because
elvis has no way of knowing when you're through selecting it.
The Win32 version of elvis has the usual Cut/Copy/Paste toolbar buttons and
menu items.
ΓòÉΓòÉΓòÉ 1.12. Elvis 2.1 Messages ΓòÉΓòÉΓòÉ
12. MESSAGES
Elvis has an extremely versatile method for handling messages. You can change
the wording, or even the language, of any message. You can make any message
ring the terminal's bell. You can hide certain messages.
This section of the manual describes how messages are generated, and how you
can customize them. A list of the individual messages can be found in the file
elvistrs.msg.
12.1 The msg() function.
Every message begins with a call to the msg() function. The message function
is passed at least two arguments: the message's importance, and the text of the
message. Some messages also have other arguments.
The importance of a message is a symbol which describes what type of message it
is. The symbol can be any of the following: MSG_STATUS, MSG_INFO, MSG_WARNING,
MSG_ERROR, or MSG_FATAL. This affects the way that the message is displayed.
For example, MSG_STATUS messages are always displayed immediately, and can be
overwritten by later messages; this is used for messages like "Reading
foo.c..." MSG_ERROR messages cause the exitcode option to be set to 1.
MSG_FATAL messages cause elvis to exit immediately after displaying the
message. You can't alter a message's importance without editing elvis' source
code and recompiling; each message's importance is hardcoded.
The text of the message is a string. If there are other arguments, then the
text of the message will be preceded by a bracketed list of letters which help
the msg() function convert the arguments to strings. Although this bracketed
list is part of the string, it is not considered to be part of the message's
text.
Each letter in the bracketed list describes how one argument is to be
displayed. d indicates that a long int argument is to be converted into a
decimal number string. c and C indicate that a char or CHAR is to be converted
into a string of length 1. s and S indicate that the argument is already a
string of chars or CHARs. (The CHAR data type could be either an 8-bit
character or a 16-bit character, depending on the compile-time configuration of
elvis. The bitsperchar option indicates which.)
12.2 Translation
All of the messages built into elvis are terse. If the terse option is turned
off, then elvis will attempt to translate each terse message into a verbose
one. Although the terse messages are written in English, the verbose messages
can be in any language.
When elvis first creates a new edit session, it attempts to locate a file named
"elvis.msg" and load it into a buffer named "Elvis messages". To find the
"elvis.msg" file, elvis searches through all of the directories named in the
elvispath option.
Each line of the "Elvis messages" buffer describes how a single message should
be translated. To translate a message, elvis scans through the "Elvis messages"
buffer for a line which begins with the terse message text followed immediately
by a ':' character. If it finds one, then it skips any whitespace after the ':'
and uses the remainder of the line as the message text. If it doesn't find any
matching line, then the terse text is used.
This is primarily intended to be used for translating the messages into your
native language.
The file elvistrs.msg is a handy resource when you're constructing your
"elvis.msg" file. It contains the terse forms of almost all messages. You can
yank a line from Appendix A, paste it into your "elvis.msg" file, and add a
colon and verbose message to the end of the message.
By the way, Appendix A is created automatically via the command "make
lib/elvistrs.msg". This just searches for all messages in any source file,
sorts them, and discards any duplicates. I intend to add another appendix some
day which describes some of the more subtle messages in detail.
12.3 Argument substitution
After translation, the message text is evaluated using the simpler syntax of
the built-in calculator. This basically means that you can use $1 in the
message text to indicate where the first argument should appear, $2 for the
second argument, and so on.
It also means that anything inside of parentheses is evaluated using the full
power of the calculator, which has a C-like syntax. The message output by the
:file command uses this to calculate the percentage of the way through the
file.
If you want to output a literal '$', '(', ')', or '\' character as part of the
message, you'll need to precede it with a '\' character.
12.4 Bell control
You can force any individual messages to ring the bell by using the "Elvis
messages" buffer to translate them into a message which begins with a ^G
character.
There are also two options which allow you to force the bell to ring for
certain message types. If elvis is outputting a MSG_ERROR message, and the
errorbells option is set, then elvis will ring the terminal's bell. It will
also ring the bell for MSG_WARNING messages if the warningbells option is set.
Note that there is also a flash option which instructs elvis to use a visible
alternative to the bell, if one is available.
12.5 Displaying the message
Messages are normally displayed at the bottom of the current window. Usually
this is exactly what you would expect, but it can be a little counterintuitive
when you're creating or closing windows.
When you're creating a window, the "current window" is the window where you
gave the command which caused the window to be created. So if you're editing
"foo.c" and give the command :split bar.c then the information about the
"bar.c" file will show up in the window where you're editing "foo.c". The
bottom line of the "bar.c" window will be blank.
When you're closing a window, elvis chooses some other window to become the new
"current window" so that it'll have a place where it can display the messages.
You can't always predict which window it will choose.
When you close the last window and exit elvis, any messages that elvis wants to
output will simply be written to stdout or stderr. Typically, the only message
that elvis wants to output when closing will be "wrote foo.c, 1234 lines, 56789
characters".
ΓòÉΓòÉΓòÉ 1.13. Elvis 2.1 Arithmetic Expressions ΓòÉΓòÉΓòÉ
13. ARITHMETIC EXPRESSIONS
13.1 Normal (C-like) Syntax
13.2 Simpler Syntax
13.3 Functions
13.4 EX Commands Which Use Expressions
13.5 VI Commands Which Use Expressions
13.6 Other Uses of Expressions
Elvis can evaluate expressions involving numbers, strings, and boolean values,
using a C-like syntax. These are used in several EX commands, one VI command,
and a couple of other situations.
There are two syntaxes. The normal syntax is extremely similar to C, and is
used in circumstances where you probably would never use a literal value, such
as for the :if command. The simpler syntax makes literal values easier to
enter, while still making the full power of the expression evaluator available
if you need it.
13.1 Normal (C-like) Syntax
The :calculate command uses the normal syntax and displays the results. We'll
use it for most of the examples in this section.
The normal syntax is intended to resemble the syntax of the C programming
language very closely. You can't define your own functions or use flow-control
constructs though; you can only use expressions. In traditional C
documentation, these would be called "rvalues." Basically that means you can
use literal values, option names, operators, parentheses, and some built-in
functions.
13.1.1 Primary expressions
Literals can be given in any of the following formats:
"text"
Any text in double-quotes is taken literally. The usual C escapes
are supported: \b, \E (uppercase, representing the Esc character),
\f, \n, \r, and \t. Also, you can use \\ for a literal backslash
character, or \" for a literal double-quote character within a
string.
\$
\(
\)
\\
You can use a backslash to quote a single dollar sign, parenthesis,
or backslash as though it was a string of length 1. This was done
mostly for the benefit of the simpler syntax, where these four
character are normally the only ones which have any special
interpretation.
digits
Any word which contains only digits will be taken as a literal
value. Generally this value will be interpreted as a number, but
internally the expression evaluator always stores values as strings.
Some operators look at their arguments and act differently depending
on whether those strings happen to look like numbers or Boolean
values.
0octaldigits
0xhexdigits
'character'
Octal, hex, and character constants can be used in expressions.
These are converted to decimal when they are parsed, before they are
passed to any operator or function. Passing an octal, hex, or
character constant therefore is exactly like passing the equivalent
decimal number. Elvis supports escapes as character constants: '\0',
'\b', '\E', '\f', '\n', '\r', and '\t'.
true
false
These can be used as Boolean literals. Technically, they are
implemented via options (as described below) named true and false.
All of the boolean operators accept "false", "0", "", or the value
of the false option as Boolean false values, and anything else as a
Boolean true value.
The following examples produce exactly identical results.
:calc "8"
8
:calc 8
8
:calc 010
8
:calc 0x8
8
:calc '\b'
8
You can also use option names in elvis the same way you would use variable
names in C.
:calc list
false
:calc scroll
12
:calc display
normal
Additionally, a dollar sign followed by the name of an environment variable is
replaced by the value of that environment variable. If there is no such
environment variable, then elvis will act as though it exists and has a null
value.
In some circumstances, you can use a dollar sign followed by a digit to access
special arguments. This is used in error messages and also in the values of a
few options, as described in section 13.6. These special arguments can only be
supplied by elvis' internal code, and it only supplies them in a few special
circumstances so you can't use them in :calculate, for example.
13.1.2 Operators
The following operators are available. When passed integer values, these
operators act like their C counterparts. When passed string values, most of
them concatenate their arguments with the operator name in between, but some
of them do something that is useful for strings, as described below. Items at
the top of this list have a higher precedence than those lower down.
(no operator)
Any two expressions placed side-by-side with no operator between
them will be concatenated as strings. C does this for literal
strings, but elvis does it for anything.
~
Perform a bitwise NOT operation on the argument, if it is a number.
!
Return true if the argument is false and vice versa.
* / %
The usual arithmetic operators. (% is the modulo operator.)
Also, the / operator can be used to combine a directory name and a
file name, to form an absolute pathname. Here are some examples
showing how this works in DOS:
:set dir home
directory=C:\temp home=C:\
:calc dir/"tempfile"
C:\temp\tempfile
:calc home/"elvis.rc"
C:\elvis.rc
+ -
The usual arithmetic operators. Note that there is no special unary
- sign; the minus sign serves double-duty. Because C normally gives
the unary - sign a higher precedence than other operators and elvis
doesn't, you may occasionally need to enclose negated values in
parentheses to achieve the same effect.
<< >>
For integers these operators perform bitwise shifting, exactly like
C. However, if the left argument is a string and the right argument
is a number then elvis will pad or truncate the string to make its
length match the number argument. << pads/truncates on the right,
and >> pads/truncates on the left.
:calc \[("port" << 6)\]
[port ]
:calc \[("starboard" >> 6)\]
[rboard]
< <= > >= == !=
Compare the arguments and return true if the comparison holds, and
false otherwise. If both arguments look like numbers, then they will
be compared as numbers; otherwise they will be compared as strings.
&
Bitwise AND of the arguments, if they're numbers.
^
Bitwise XOR of the arguments, if they're numbers.
|
Bitwise OR of the arguments, if they're numbers.
&&
Returns false if either argument is one of the four false string
values, and true otherwise.
||
Returns false if both arguments are one of the four false string
values, and true otherwise.
?:
This one is tricky because internally elvis always uses binary (two
operand) operators. In C this is a ternary operator but in elvis it
is implemented as two binary operators which cooperate in a subtle
way so they seem like a single ternary operator. You probably don't
need to know the details, but the upshot of it all is that 1) It
associates left-to-right (instead of right-to-left as in C), and 2)
The : and third argument are optional; if omitted, then elvis
mentally sticks :"" on the end of the expression.
,
Concatenates two strings, with a comma inserted between them. This
can be handy when you're passing arguments to the quote() and
unquote() functions.
;
Concatenates two strings without inserting any extra characters. The
result is exactly like (no operator), except that (no operator) has
an extremely high precedence, and ; has an extremely low precedence.
:calc 1+2 3*4
93
:calc 1+2;3*4
312
13.2 Simpler Syntax
In comparison to the normal expression syntax, the simpler syntax makes it
easier to enter literal strings because outside of parentheses the only
special characters are the backslash, dollar sign, and parentheses. (These may
be escaped by preceding them with a backslash.) Inside parentheses, the normal
syntax is used.
The :eval command uses the simpler syntax, and the :echo command displays its
arguments. These commands can be used together to experiment with the simpler
syntax, the same way we used :calculate to experiment with the normal syntax.
:eval echo TERM=$TERM
TERM=xterm
:eval echo home=(home)
home=/home/steve
:eval echo 2+2=(2+2)
2+2=4
13.3 Functions
There are several built-in functions. When you call one of these functions,
there must not be any whitespace between the function name and the following
parenthesis. The built-in functions are:
.------------------.--------------------------------------------.
| FUNCTION(ARG) | RETURN VALUE |
|------------------|--------------------------------------------|
| strlen(string) | number of characters in the string |
| toupper(string) | uppercase version of string |
| tolower(string) | lowercase version of string |
| isnumber(string) | "true" iff string is a decimal number |
| htmlsafe(string) | convert characters from ASCII to HTML |
| hex(number) | string of hex digits representing number |
| octal(number) | string of octal digits representing number |
| char(number) | convert number to 1 ASCII char, as a string|
| quote(list,str) | insert backslashes before chars in list |
| unquote(list,str)| remove backslashes before chars in list |
| exists(file) | "true" iff file exists |
| dirperm(file) | string indicating file attributes |
| dirfile(file) | filename.ext part of a path |
| dirname(file) | directory part of a pathname |
| dirdir(file) | directory, like dirname(file) |
| dirext(file) | extension (including the . ) |
| basename(file) | filename without extension |
| fileeol(file) | newline style of the file |
| absolute(file) | return a full path-name for a given file |
| getcwd() | return the current working directory name |
| elvispath(file) | locate a file in elvis' configuration path |
| knownsyntax(file)| language of a file if in elvis.syn, else ""|
| buffer(bufname) | "true" iff buffer exists |
| alias(name) | "true" iff an alias exists with that name |
| current(item) | value indicating an aspect of elvis' state |
| feature(name) | "true" iff a given feature is supported |
^------------------^--------------------------------------------^
(Note: "iff" is short for "if and only if")
Some of these deserve further comment.
The isnumber() function uses the same test that the operators use when
deciding whether to use the string version or the number version of their
behavior. You can use isnumber() to predict how operators will behave.
The hex() and octal() functions return strings which look like C-style hex or
octal constants, respectively. The isnumber() function will return false when
passed one of these strings; they are no longer considered to be numbers. In
fact, the only reason you can use hex and octal literals is because they are
converted into decimal strings by the parser, before evaluation even begins.
The following example demonstrates that hex literals are converted to decimal,
and that the value returned by hex() is something else.
:calc strlen(0xff)
3
:calc strlen(hex(255))
4
The char() function returns a one-character string; that character's decimal
value will be the argument number. For example, "char(65)" returns "A". Note
that the returned value does not look quite like a character constant.
The quote() and unquote() functions add and remove backslashes before special
characters. The backslash character itself is always considered to be
"special," so backslashes are converted to double-backslashes and vice versa.
In the argument, any characters which precede the first comma are used as a
list of other special characters, and the remainder of the argument is the
string to be quoted/unquoted. For example...
:set t="/* regexp */"
:set r="*^$/.["
:eval /(quote(r, t))/
... will search for the next instance of of the literal string "/* regexp */".
The '/' and '*' characters won't be treated as metacharacters in the regular
expression, because the quote() function inserts backslashes before them.
Also, notice that the comma operator concatenates two strings and inserts a
comma between them. That's handy!
The dirperm() function returns one of the following strings to indicate the
file's type and permissions:
"invalid"
The argument is malformed; it could not possibly be a valid file
name.
"badpath"
The argument is a pathname, and one or more of the directories named
in that pathname either doesn't exist or is something other than a
directory.
"notfile"
The argument is the name of something other than a file; for
example, it may be a directory.
"new"
There is no file, directory, or anything else with the given name.
"unreadable"
The file exists but you don't have permission to read it.
"readonly"
The file exists and you can read it, but you don't have permission
to write to it.
"readwrite"
The file exists and you can read or write it.
The fileeol() function opens the file in binary mode, reads the first hundred
bytes, and inspects those bytes to make a guess about the file's newline
format. It is commonly used for setting the readeol option. fileeol() returns
one of the following strings:
"unix"
It appears to be a text file which uses Line Feed characters for
newlines.
"dos"
It appears to be a text file which uses Carriage Return/Line Feed
pairs for newlines.
"mac"
It appears to be a text file which uses Carriage Return characters
for newlines.
"binary"
It appears to be a binary file.
"text"
Anything else; e.g., a non-existent file or empty file.
The elvispath() function searches through the directories listed in the
elvispath option's value, looking for the argument file name. If it is found,
then the full pathname of the file is returned; otherwise it returns a null
string.
The absolute() function attempts to construct a full pathname for a given file
name. If the given file name is actually a URL, or if it is already a full
pathname, then this function returns it unchanged. Otherwise it combines the
getcwd() value with the given name.
The knownsyntax() function determines whether the given file can be displayed
in the syntax display mode. It does this by looking for the file name
extension in the elvis.syn configuration file. If the file's extension is
listed there, then this function returns the name of the language. Otherwise,
it just returns an empty string.
The current() function examines elvis' internal variables, and returns a
string indicating the value of one of them. The argument determines which
variable is examined, as follows:
current("line")
Current line number.
current("column")
Current column number.
current("word")
The word at the cursor location. If the cursor isn't on a word, then
this returns an empty string.
current("tag")
If the showtag option is true, then this returns the name of the tag
that is defined at the cursor location, or the nearest one before
it. If the showtag option is false, or the cursor is located above
the first tag defined in this file, then current("tag") will return
an empty string.
current("mode")
Current key parsing mode. This returns the same string that the
showmode option displays, except that this function converts it to
all lowercase, and strips out whitespace. The usual return values
are "command", "input", and "replace". If the window isn't editing
the its main buffer (i.e., if you're entering an ex command line,
regular expression, or filter command) then this function will
return an empty string.
current("selection")
Visible selection type. This returns one of "character",
"rectangle", or "line" to indicate the type of visible selection
which is currently marked in the window, or an empty string if no
visible selection is marked.
current("next")
Next file. This returns the name of the file that the :next command
would load, or an empty string if you're at the end of the args
list.
current("previous")
Previous file. This returns the name of the file that the :previous
command would load, or an empty string if you're at the start of the
args list.
current("tagstack")
If the window's tag stack is empty, this returns "". Otherwise it
returns the name of the buffer to which :pop would move the cursor.
The feature() function is intended to allow you to write EX scripts which work
with different configurations of elvis. For example, you can compile elvis
without support for the hex display mode; if you do that, then feature("hex")
will return false. Currently feature() returns true for all supported display
modes, network protocols, and maybe "showtag" and "lpr"; it returns false for
anything else. As new features are added to future versions of elvis, I expect
to add them to feature()'s list.
13.4 EX Commands Which Use Expressions
The :calculate command evaluates its argument using the normal syntax, and
displays the result.
The :if command evaluates its argument using the normal syntax. If the
resulting value is any Boolean true value then a flag is set; otherwise the
flag is reset. After that, you can use :then and :else commands to
conditionally execute some commands, depending on the state of that flag.
The :eval command evaluates its arguments using the simpler syntax. The
resulting string value is then interpreted as an EX command line. This gives
you a way to use the expression evaluator with commands which otherwise
wouldn't evaluate expressions.
The :let command allows you to change the values of options. Its syntax is
":let option=expression", where expression is any expression using the normal
syntax. You can use this to change the value of any unlocked option, similarly
to :set.
:set i=14
:calc i
14
:let i=i+1
:set i?
i=15
:eval set i=(i*2)
:calc i
30
:let elvispath="."
:let list="false"
:let sidescroll=0x10
13.5 VI Commands Which Use Expressions
There is only one way to use expressions in a visual command: Move the cursor
to the start of some expression in your edit buffer, hit the lowercase v key,
move to the other end, and then hit the = key. Elvis will then evaluate the
highlighted expression, and replace the original expression with the result.
Note that the = operator only works this way when used with the v command for
marking characters. If you visibly mark lines, or use the traditional
=movement syntax, then elvis will send the selected lines though the external
filter program named in the equalprg option.
The # command doesn't use expressions, but it does perform some simple math.
13.6 Other Uses of Expressions
13.6.1 Messages
All of elvis' warning and error messages are actually expressions, using the
simpler syntax. When outputting a message, elvis may supply other parameters
which are accessible as $1 through $9. See the Messages chapter for a longer
description of how elvis handles messages.
13.6.2 Options
The ccprg and makeprg options' values are expressions, using the simpler
syntax. When evaluating these expressions, $1 is replaced by whatever
arguments are supplied on the ex command line, and $2 is replaced by the the
name of the file being edited.
13.6.3 File Names
File names are evaluated as expressions (using the simpler syntax), primarily
as a means for expanding environment variable names. This is done prior to
wildcard expansion.
The full power of the expression evaluator is available; you can use it to do
more than just expand environment variable names. For example, you could store
the name of a file in one of the user options, and then later use that option
name in parentheses wherever a filename was expected.
:set f=myfile.txt
:w (f)
wrote myfile.txt, ...
If you use this trick, remember that it only works when elvis is expecting a
file name. It won't work when invoking external programs, because elvis
doesn't know which program arguments are supposed to be file names. Elvis
always passes program arguments literally.
Recall that when a backslash character is followed by an alphanumeric
character, both the backslash and the alphanumeric character become part of
the resulting value. This was done mostly for the benefit of file names. If
the backslash was always dropped then MS-DOS users would have a heck of a time
entering pathnames of files! By making the backslash a little smarter, we
avoid that problem.
:eval echo c:\tmp \(notice the backslashes\)
c:\tmp (notice the backslashes)
To simplify the task of writing portable ex scripts, the behavior of the /
operator has been extended. When one or both of its arguments are strings, it
concatenates them as a directory name and a file name, yielding a full
pathname.
ΓòÉΓòÉΓòÉ 1.14. Elvis 2.1 Tags ΓòÉΓòÉΓòÉ
14. Tags
Tags provide a fast way to locate specific points in a collection of files.
This is done by storing a list of tag names, and their corresponding locations,
in a file named "tags". This is particularly handy for programmers who are
working on large projects.
Traditionally, each tag has three attributes: its name (generally the name of a
function, or some other symbol from your program), the name of the source code
file in which that function is defined, and the address of its line within that
file. The tag name is used for selecting a particular tag.
Elvis supports more a more sophisticated model. The extensions are intended to
allow elvis to handle C++, and similar languages, which allow different
functions to have the same name. Since tag names are derived from function
names, the tag name alone isn't sufficient to select a single tag. Elvis
permits tags to have other attributes, which help it select the correct tag.
All of this is described in more detail below, in the following sections:
14.1 The tags file
14.2 Creating a tags file
14.3 Reading the tags file
14.4 Using tags with elvis
14.5 The TAGPATH
14.6 Enhanced tags
14.5 Restrictions and hints
14.6 History
14.7 Browsing
14.8 The tagprg and tagprgonce options
14.1 The tags file
Tags are stored in a file named "tags". It is a plain ASCII text file. Each
line of the file contains the attributes of a single tag. A tab character is
used to delimit the attributes. The traditional tags file contains three
attributes for each tag.
The first attribute is the tag's name. It is typically the name of a function,
variable, or data type -- a name that you could guess by looking at the
source code of your project. Traditionally, this attribute has been the sole
means for selecting a tag, so tag names should ideally be unique. The lines of
the tags file are sorted by this attribute.
The second attribute is the name of source code file in which the
corresponding function (or whatever) is defined. If it isn't an absolute file
name (relative to the root directory) then it should be relative to the
directory where the tags file resides -- which isn't necessarily the current
working directory.
The third attribute is the address of the line within that file, where the
function (or whatever) is defined. This address can either be a line number,
or a nomagic style of regular expression. If it is a regular expression, it
must be bound by '/' or '?' characters, and it may contain tab characters.
Typically, the entire source line is encoded as a regular expression by
inserting "/^" onto the front, appending "$/" onto the end, and inserting a
backslash character before each / or \ character within the line.
Elvis actually supports a superset of this format (by permitting extra
attributes) but we'll start with the basics.
14.2 Creating a tags file
Usually the tags file is created automatically by a program such as ctags. It
reads a collection of C or C++ source files, and generates tags for each
global function. It can also generate tags for global types and variables, or
for static instances of any of these.
You will usually invoke ctags on all source files in the current directory via
a command similar to this:
ctags *.c *.h
The ctags program can also generate other types of output. Be sure to look at
its manual page to see the options.
14.3 Reading the tags file
Tags exist mostly for use with elvis, but for the sake of simplicity we'll
start with the ref program.
ref selects tags just like elvis, and then displays information about them.
The simplest way to use it is to pass it the name of the tag you're interested
in. The following example would display the definition of the "main" function:
ref main
There are some other options. One of the most useful is -a which instructs ref
to display all selected tags. (Without -a it just displays one of the selected
tags.) For example, if your current directory contains many programs, each
with its own "main" function, then this would display the headers for all of
them:
ref -a main
You can also use ref to generate an HTML document listing all tags, or just
the ones that match some criteria. Here's an example which lists all tags as
an HTML document:
ref -ha >tags.html
ref uses the same syntax for restrictions and sorting hints as elvis' :tag
command. This syntax will be described later. You should check the manual page
for a list of options.
14.4 Using tags with elvis
When starting elvis, you can use the -ttagname flag to start with the cursor
at the definition point of a given function in your program's source code. It
automatically performs the following steps:
1. Scan the tags file for a tag named tagname.
2. Load the file indicated by the tag's second attribute.
3. Search for the line indicated by the tag's third attribute.
4. Within that line, search for the tag name.
5. Move the cursor there.
Once elvis is running, there are many commands available which deal with tags.
The most essential is :tag tagname. It does all the same steps as the
-ttagname command-line flag, plus it saves the cursor's original position on a
stack. Later, you can use :pop to bring the cursor back to its original
position.
When elvis is in visual command mode, you can move the cursor onto a word and
hit ^] to perform a :tag search on that current word, or ^T to perform a :pop
command.
If you have a mouse, then you can use the left button to double-click on a
word in the text, to have elvis perform a :tag search on that word.
Double-clicking the right button anywhere in the text will perform a :pop
command.
The uppercase K command runs program on the word at the cursor position. The
program is chosen by setting the keywordprg option. By default, it runs the
ref program, so the word's definition is displayed temporarily at the bottom
of the screen.
14.5 The TAGPATH
You can have tags files in several directories, and configure ref and elvis
to search the appropriate ones by setting the TAGPATH environment variable.
The value of TAGPATH is a list of directories or tags files, delimited by
either a ':' character (for UNIX) or a ';' character (for most other operating
systems, including Microsoft's).
In a typical large project, you will have some directories which contain
library functions, and some which contain the code for specific programs. With
this arrangement, you would set TAGPATH to search the current directory
followed by each of the library directories. Something like this...
setenv TAGPATH=tags:/usr/src/libproj/tags:/usr/src/libio/tags
The exact syntax depends on your command interpreter. And of course the exact
directory names will depend on your project.
When your current directory is one which contains the source code for some
program, and you do a search for (as an example) "showitem", elvis would look
for it first in that program's tags file, and if it isn't found there then
it'll look in each library's tags files until it does find it. The ref program
searches the same way.
Actually, elvis uses an option named tags to store the search path. The
default value of that option is taken from the TAGPATH environment variable,
though. If you don't set TAGPATH (or the tags option), then elvis will search
only in the current directory.
The default path for ref is a little more sophisticated. That's because ref is
intended to be general reference utility for all library functions, while
elvis' tags facility is mostly intended for navigating through the source code
of a single program.
Note to system administrators: ref can be so handy that I suggest you make a
tags file for the functions in your system's standard libraries. If licensing
restrictions prevent you from making the library source code available to all
users, then you should use ctags -r to generate a "refs" file. If you don't
have access to the library source code yourself, then perhaps you can make
something useful from the lint libraries.
14.6 Enhanced tags
The C++ programming language supports "overloading," which means that
different functions can have the same name. Since tag names are derived from
function names, different tags will have the same name. This creates a problem
because the tag name has traditionally been the only way to select a tag, so
you could easily get the wrong one. Elvis' implementation of tags has some
extra features to solve this problem.
There are two tactics for solving the problem. The first tactic is to be more
selective; i.e., use information other than just the tag name to select tags.
This definitely helps, but it is an absolute impossibility to resolve all such
ambiguities prior to run-time, so we also need a second tactic: collect all
possible tags into a list, and use heuristics or explicit hints from the user
to sort the list so the most likely alternative is tried first, the second
most likely if the first was rejected, and so on down the list. Elvis uses
both tactics.
In the tags file, elvis permits tags to have extra attributes. Each attribute
has a name and a value. The first three fields are named tagname, tagfile and
tagaddress. Those names are implicit; the names don't appear in the tags file,
only the values do.
If a tag has any extra attributes, they will be appended to the tag line. In
order to allow the original vi/ex to read tags files which have additional
attributes, a semicolon-doublequote character pair is appended to the
tagaddress, before the first extra attribute. Due to an undocumented quirk of
the original vi/ex, this will cause vi/ex to ignore the remainder of the line.
The extra attributes will not adversely affect the behavior of the original
vi/ex.
The extra attributes have explicit names. In the tags file, the extra
attributes are generally given in the form <TAB>name:value. Different tags may
have different extra attributes; many will have no extra attributes at all.
The attributes may appear in a different sequence for each tag.
In a single tags file, elvis supports up to 10 distinct attribute names -- the
3 implicit names for the standard fields, plus up to 7 explicit names for
extra attributes. (This is a limitation of elvis, not the enhanced tag
format.)
The name can be any series of letters or digits. Lowercase letters are
preferred.
The value can contain any character except NUL. Any backslash, tab, or newline
characters should be stored as \\, \t, or \n, respectively.
If an extra attribute has a value but no name or colon, then the name is
understood to be "kind".
The extra attributes are intended to describe the contexts in which the
corresponding program symbol can appear. Typically the name is a type of
lexical scope, and the value is the name of that scope; e.g., "function:init"
for a tag which is only defined inside the init() function. Elvis can use
these as hints to figure out which tags might make sense in the current
context, and ignore those that don't. Although the extra attributes have no
preset names, the following names are recommended:
kind
The value is a single letter which indicates the lexical type of the
tag. It can be "f" for a function, "v" for a variable, and so on.
Note that since the default attribute name is kind, a solitary
letter can denote the tag's type (e.g, "f" for a function).
file
For tags which are "static", i.e., local to the file. The value
should be the name of the file.
If the value is given as an empty string (just "file:"), then it is
understood to be the same as the tagfile field; this special case
was added partly for the sake of compactness, and partly to provide
an easy way handle tags files that aren't in the current directory.
The value of the tagfile field always relative to the directory in
which the tags file itself resides.
function
For local variables. The value is the name of function in which
they're defined.
struct
For fields in a struct. The value is the name of the struc. If it
has no name (not even a typedef) then struct:struct is better than
nothing.
enum
For values in an enum data type. The value is the name of the enum
type. If it has no name (not even a typedef) then enum:enum is
better than nothing.
class
For member functions and variables. The value is the name of the
class.
scope
Intended mostly for class member functions. It will usually be
"private" for private members, or omitted for public members, so
users can restrict tag searches to only public members.
arity
For functions. The number of arguments.
The ctags program has been hacked slightly to support some of these, but not
all. Its new -h flag enables generation of the extra hint attributes; if you
invoke ctags without any flags, then -h is one of the flags that it uses by
default. For example, the usual command for generating tags for all source
files in the current directory is...
ctags *.c *.cpp *.h
The current hacked-up ctags distributed with elvis will only generate file and
class hints, and even class isn't as effective as one might hope.
Some pseudo-tags may be inserted at the top of the tags file, to describe the
characteristics of that particular tags file. These tags all begin with a "!_"
so that even if the tags are sorted, the pseudo-tags will always appear at the
top of the file. The pseudo-tags all use the old tags format, so they can be
parsed (and then ignored) by older tag reading programs.
!_TAG_FILE_FORMAT 2 /supported features/
!_TAG_FILE_SORTED 1 /0=unsorted, 1=sorted/
The !_TAG_FILE_FORMAT pseudo-tag's tagfile field is 2 for new-style tags, or 1
for old-style tags. The !_TAG_FILE_SORTED pseudo-tag's tagfile field is 1 if
sorted, or 0 if unsorted. The tagaddress field is used simply as a comment in
both tags. If these tags are missing from a tags file, then the file is
assumed to be in the new format (which is still backwards compatible with the
old format), and sorted. If a tags file is unsorted then it must contain a
!_TAG_FILE_SORTED field indicating that.
These may be followed by more pseudo-tags describing the ctags program itself.
Elvis' version of ctags produces the following information:
!_TAG_PROGRAM_AUTHOR Steve Kirkendall /kirkenda@cs.pdx.edu/
!_TAG_PROGRAM_NAME Elvis Ctags //
!_TAG_PROGRAM_URL ftp://ftp.cs.pdx.edu/pub/elvis/README.html //
!_TAG_PROGRAM_VERSION 2.1 //
The new tags file format also addresses another limitation of the old format:
the old format allows fields to be delimited with any whitespace. This is a
problem because space characters are becoming more common in file names these
days, so we occasionally need to put spaces into the tagfile field. To support
this, the new format dictates that fields must be delimited by a single tab
character, not spaces. This shouldn't cause any backward compatibility
problems because traditionally ctags has always used tab as the delimiter.
Also, the interpretation of the tagaddress field has been refined.
Traditionally, it has been defined as either a line number or a nomagic
regular expression, but it has actually been implemented in vi/ex to support
any ex command there. Supporting any command could produce a security hole, so
the new format only supports addresses. It supports more complex addresses
though, because they can be useful in some circumstances. For example, the tag
line for a "val" field in a struct named "item_s" could look like...
val file.h /^struct item_s {$/;/^ int val;$/ struct:item_s
... which would allow the editor to skip past any "int val;" definitions in
other structs, to find the correct "int val;" in the item_s struct.
This form of tags file is also supported by Darren Hiebert's Exuberant ctags
and by Vim, in addition to elvis.
If you ever need to convert a new-style tags file back to the old style, you
can do so via the ref utility. Run it like this:
ref -ta >oldtags
14.5 Restrictions and hints
The syntax of the :tag command has been extended. Previously you could only
supply a single tagname value to search for. Now you can supply multiple
acceptable values for any attribute, and control what happens when a given tag
lacks a given attribute.
The arguments of the :tag command are now whitespace-delimited expressions of
the following forms, to define a set of restrictions that possible tags must
meet to be selected:
name:value
Reject tags which have an attribute named "name", but that
attribute's value isn't in the list of acceptable values. E.g.,
"file:foo.c" accepts global tags, or tags which are static to the
file "foo.c", but rejects tags which are static to other files.
name:=value
Reject tags which have an attribute named "name" attribute, but that
attribute's value isn't in the list of acceptable values. Also
reject tags which don't have a "name" attribute. E.g., "class:=Foo"
only accepts tags which have class "Foo".
name:/value
Like name:value except that when a tag has no attribute named name
then the tagaddress attribute's value is required to contain value
as a substring. "class:/Foo" would find tags in class "Foo" PLUS
global tags whose address mentions "Foo" -- probably friends of the
Foo class.
value
Short for tagname:value.
The parser also allows you to add some sorting hints to the command line.
These hints are added to the history that elvis uses to guess which overloaded
tag to list first.
name:+value
If a tag has an attribute with the given name and value, then cause
it to appear near the beginning of the sorted list. I.e., tags with
this name and value are more likely to be the intended tag, but you
can't be certain.
name:-value
If a tag has an attribute with the given name and value, then cause
it to appear near the end of the sorted list. I.e., tags with this
name and value are less likely to be the intended tag, but you can't
be certain.
All of these restriction expressions and the sorting hint expressions allow
you to give multiple acceptable values. You can either give each value in a
separate expression, or give a comma-delimited list of values to a single
expression.
A nul value string matches anything. So "struct:=" would accept any tag with a
"struct" attribute, and reject those without it. This would be handy when
you're trying to do tag lookup for a word which follows a '.' character -- you
know it is a field name, but you don't know which struct type.
The :tag command automatically adds a file:filename restriction (where
filename is the name of the file being edited in the current window) to any
tag search you request. This causes it to ignore tags which are static to
other files. The :browse command doesn't do that. See the Browsing section,
below.
14.6 History
The sorting hints are persistent. They aren't forgotten immediately after a
tag search; a hint from one search will influence the sorting order for
following searches. The degree of influence is weighted, so more recent hints
will have more influence than older hints. Eventually, each hint's weighting
factor drops to zero, and the hint is forgotten only then. The history uses
two lists of name/value pairs: one for storing recent successes, and one for
recent failures.
While searching for a tag, elvis builds a list of tags which matched the
restrictions. That list is sorted primarily by the tagname attribute's value,
but when multiple tags have the same name, elvis looks for the attributes of
those tags in the lists of successes and failures, and uses the weights of any
matches to compute the likelyhood that a particular tag is the one that the
user really wants. The more likely tags are inserted into the list before any
less likely tags with the same name.
Expressions of the form name:+value add a name/value pair to the success list,
and expressions of the form name:-value add a name/value to the failure list.
Name/value pairs are also added automatically in the following circumstances:
If you perform a tag search on the same name twice in a row, then elvis
assumes you're rejecting the first tag that it found. The attributes of
that tag are added to the failure list.
If you perform a tag search on a different name, then elvis assumes that
the previous tag must have been the right one, so its attributes are
added to the success list.
It should be stressed that the tag history has no effect on which tags are
selected from the tags file. It only affects the order in which they're
presented, if more than one tag meets your restrictions.
14.7 Browsing
The result of any tag search is always a list of matching tags. The :tag
command keeps this list hidden, and moves the cursor to the single most likely
member of that list. This is not always the best way to select a tag.
Elvis has a :browse command which performs a tag search, and then builds an
HTML document from the list. The document shows all tags which matched your
search criteria; the current window will then switch to this document. There
is also a :sbrowse command which displays the same document in a new window.
The arguments to :browse differ from :tag in the following ways:
:browse does not automatically add any restrictions. (:tag adds
file:filename to each search.)
If you invoke :browse with no arguments, then it will assume you wanted
tagfile:filename, where filename is the name of the file being edited in
the current window.
If you invoke :browse with a single argument, elvis first tries to
interpret it as a restriction or sorting hint in the normal way. But that
search yields no tags, elvis may retry the search using your argument as
a file name (tagfile:argument), or as a class name (class:/argument).
By default, :browse only searches through the "tags" file in the current
directory. When invoked as :browse! (with a "!" suffix) it collects matching
tags from all "tags" files as specified by the tags option.
Here are some examples of :browse commands.
:browse term
Show all tags named "term"
:browse
Show all tags defined in the current file.
:browse foo.c
Show all tags defined in the file "foo.c".
:browse tagname:=
Show all tags which have a tagname attribute. Since all tags have a
tagname attribute, this shows every tag in the tags file.
:browse class:/DbItem
Show all tags in the DbItem class, or friend functions of that
class. It may also include some non-friend functions which merely
use DbItem, but there's no easy way to avoid that.
:browse DbItem
If there is a tag named DbItem, then show it. Otherwise this is the
same as :browse class:/DbItem
Each matching tag in the generated document has a hypertext link to the point
in your source where the corresponding symbol is defined. By following the
hypertext link, you can go directly to the appropriate point in your source
code. As usual, the tag stack can be used to :pop back to the same browser
document, from which you may then proceed to a different tag, or :pop back one
more level to wherever the cursor was located before you gave the :browse
command.
If you wish, you can define your own format for the browser document. Elvis
searches through the elvispath for a file named "elvis.bro". If found, then
blank lines in it will be used to delimit it into three sections:
Everything before the first blank line is the header. It is copied into
the start of each browser document. $1 is replaced by the command line
arguments, and $2 is replaced by the number of matching tags found. This
is a straight-forward text substitution, not an evaluation like the
following section...
Everything between the first blank line and the last blank line is
repeated for each tag. For each tag, it is evaluated using the simpler
syntax, with $1 being replaced by the tagname, $2 by the tagfile, $3 by
the line text extracted from the tagaddress, and $4 by a URL combining
the tagfile and tagaddress attributes. You can also use parentheses to
enclose more complex expressions.
Everything after the last blank line is the trailer. It it copied into
the browser document literally.
The ref -ha restrictions... program generates a similar HTML document. It
always interprets its arguments as restrictions, and the format of the HTML
document can't be reconfigured. Those are the only differences.
14.8 The tagprg and tagprgonce options
As an alternative to elvis' "restrictions" method for finding tags, you can
set the tagprg option to a shell command line which locates the tags.
When you give a :tag command, elvis evaluates the tagprg option's value using
the simpler expression syntax. Any instance of $1 in the value will be
replaced with the command-line arguments. Also, any text inside parentheses
will be evaluated; this gives you a way to access other options' values, so
you can do things like pass the value of the tags option to the program so it
knows which tags files to search through.
The resulting string is then executed, and its output is parsed as though it
was a tags file. All of the tags that it outputs are considered to be
matches, since using tagprg disables the use of restrictions.
Elvis builds a list of the matches, and sorts them using the same history
mechanism that is uses with restrictions. However, the "name:+value" and
"name:-value" sorting hints are not detected in the arguments.
Once the list has been built, elvis moves the cursor to the first match. You
can step through all matches in the list by hitting ^] or by giving the :ta
command with no arguments, as usual.
Note that the program's output should be in the standard tags file format. At
a minimum, this means "tagname TAB filename TAB address". If you want to use a
function searching program that uses a different format, you'll need to pipe
its output through a custom-made filter that converts its output to the
standard tags format.
There is also a tagprgonce option. It is exactly like tagprg except that
tagprgonce is automatically reset to "" after it is used. This is handy when
you're writing aliases that use perform specialized searches.
ΓòÉΓòÉΓòÉ 1.15. Elvis and the Internet ΓòÉΓòÉΓòÉ
15. THE INTERNET
This chapter describes elvis' ability to read and write data via the internet.
The topics discussed here are:
15.1 URLs
15.2 FTP
15.2.1 elvis.ftp or ~/.netrc
15.3 HTTP
15.3.1 Proxy Servers
15.3.2 elvis.net
In addition, you should probably read the Information via the Web and Using
elvis as a Web browser sections of the Tips chapter. You may also wish to read
the "html" section of the Display Modes chapter.
15.1 URLs
Wherever the traditional vi expects a filename, elvis expects a Universal
Resource Locator, or URL. The names of local files are one type of URL; other
types give the names of resources available from servers on other machines,
accessible via the Internet.
URLs have the form protocol://server.domain.name:port/directory/file where the
components of the URL have the following meanings:
protocol
This tells elvis how to read the URL. It can be one of the
following:
file: for local files.
buffer: for already-loaded edit buffers.
http: for the HTTP Internet protocol
ftp: for the FTP Internet protocol
Anything else isn't directly supported by elvis, but may be
accessible via a proxy server.
server.domain.name
For the http: and ftp: protocols, this tells elvis which machine to
contact on the Internet.
port
Both http: and ftp: have default port numbers (80 and 21
respectively), but if a given machine's server is listening at a
non-standard port, you would give the port number here.
directory
This tells the server which directory contains the file.
file
This is the file to be loaded.
You can append a "#name" to the end of the URL. After loading the URL, elvis
searches through its text for a <a name=name> tag -- even if the file isn't an
HTML file.
You can also append a "?expression" to the end of an URL. The expression's
meaning depends on the protocol. For "file:" and ":buffer", it is used as an
ex line address (usually a line number or a regular expression), and the
cursor will be moved to that line. This is used by the :browse command. For
"http:", it is passed to the server and usually interpreted by a program
residing there. For other protocols it has no meaning, and should not be used.
While in the "html" display mode, tag names are assumed to be URLs too.
However, if a tag name lacks the protocol, site, port, or directory name then
it inherits those properties from the current document. This is true only for
tags, and only if you're in the "html" display mode. For example, if you're
viewing "ftp://ftp.cs.pdx.edu/pub/elvis/README.html", and then give the
command ":ta Announce.21d", then elvis will load the URL
"ftp://ftp.cs.pdx.edu/pub/elvis/Announce.21d".
15.2 FTP
The name "FTP" stands for "File Transfer Protocol". It is a robust and
versatile protocol for transferring data between different types of computers
over the Internet, providing support for various formats or text or paged
data.
Elvis always uses FTP's non-paged binary data format. Many files require this,
and most other files will can be converted manually later if necessary.
If possible, when elvis is downloading a file via FTP it will display the
file's size along with the number of bytes downloaded so far, so you can gauge
how much longer the download will take. However, not all FTP servers support
the "SIZE" command that elvis uses to learn the file's size, so sometimes
elvis can't display the file's size while downloading. Also, elvis never
displays the size of a directory while downloading.
Elvis converts FTP directory listings into HTML documents. For each file or
subdirectory, elvis constructs a hypertext link from the directory to the
file/subdirectory, so you can browse through an FTP file system using elvis'
"html" display mode.
In addition to reading, elvis allows you to write via FTP. You can even append
to a remote file via FTP, with a command such as...
:w >>ftp://ftp.somesite.com/incoming/filename
Unfortunately, the FTP protocol doesn't have a well-defined means for testing
the attributes of a file. I tried to make elvis clever enough to infer the
file type from the limited information that the FTP server can provide, but in
some cases it may fail.
15.2.1 elvis.ftp or ~/.netrc
When using the World Wide Web, FTP accesses are normally anonymous. This
allows you to read public files, which is all that a Web browser is expected
to do anyway. On some sites, anonymous FTP may also allow you to write into a
directory named "/incoming" but Web browsers don't use that facility.
Since elvis is an editor (not merely a browser), it has different
requirements. You may wish to fetch a private file from your own account at
some FTP site, modify it, and write it back again. You can't do that with
anonymous FTP; elvis must therefore support user-specific FTP in addition to
anonymous FTP.
To remain compatible with the Web, elvis normally uses anonymous FTP. If you
want to access an FTP server using your own account, elvis requires you to
give a directory name which begins with a "~". For example,
"ftp://localhost/pub/myfile" refers to "pub/myfile" in the anonymous directory
hierarchy, but "ftp://localhost/~/myfile" refers to "myfile" in your home
directory using your own account's privileges.
Elvis doesn't prompt for your password when you access an FTP site using your
own account, though. Instead, it searches for account information in the
".netrc" file in your home directory, or if that doesn't exist then it
searches for "elvis.ftp" anywhere in your elvispath. Regardless of the name,
the file has the exact same format.
The file is divided into words. Some of these are keywords; others are data
associated with the preceding keywords. Line breaks are no more significant
than any other whitespace, but for the sake of readability it is a good idea
to keep all data for a particular FTP site on a single line.
A typical line, then, will have a format like this...
machine server.domain.name login yourlogin password yourpass
...where server.domain.name is the name of an FTP server, yourlogin is your
login name there, and yourpass is your unencrypted password.
Warning! Because this file contains unencrypted passwords, you must be very
careful to make this file unreadable by other users.
For more information about the ~/.netrc file, look in the Unix manual at the
ftp(1) and netrc(5) man-pages. Elvis' use of the ~/.netrc file is intended to
be compatible with ftp's use of the that file.
15.3 HTTP
The name "HTTP" stands for "HyperText Transfer Protocol". It is a
light-weight protocol which is used mostly for fetching Web pages.
"Light-weight" means that it handles small transfers efficiently, with very
little overhead for initialization.
Elvis supports HTTP. In fact, elvis requires you to configure HTTP support if
you want FTP support; you can't have FTP without HTTP.
Elvis doesn't support authentication or security. Authentication would embed
your user name and password into each request you make; this would be useful
for accessing subscription sites for things like stock market information, or
an online encyclopedia. Security would encrypt each request; this would be
useful when the request contains sensitive information such as your credit
card number. Since elvis doesn't support these features, it can't replace a
real Web browser.
HTTP is a read-only protocol. Consequently, you can't write to an "http:" URL.
15.3.1 Proxy Server
A proxy server is an HTTP server which allows you to send it a request for an
URL which resides on a totally separate system. There are two reasons why you
might want to do this.
The first reason is to get around a firewall. For security reasons, many Local
Area Networks are configured to severely restrict the flow of data between the
LAN and the Internet. This prevents you from accessing an Internet site
directly. A proxy server may straddle that firewall, so it can receive
requests from computers on the LAN, and send requests to Internet sites.
The second reason is that the URL you send to an HTTP proxy doesn't
necessarily have to be an "http:" URL. It could use Gopher, WAIS, or whatever.
Elvis can thus use its built-in HTTP support, and the services of an HTTP
proxy, to support any protocol which the proxy supports.
15.3.2 elvis.net
The elvis.net configuration file tells elvis which requests must go through a
proxy, and which can be sent directly. When a proxy is needed, it also gives
the name of the proxy.
The file is divided into words. The word "direct" means that following words
are domain names which can be accessed directly (without a proxy). The word
"proxy" is followed by the name of an HTTP proxy server, and then by the names
of domains which must use that proxy.
The domain names in this file can either be the complete names of servers
("www.othersite.com"), or a partial name which starts with a dot
(".othersite.com") which matches all sites whose name has the same ending.
When elvis wants to read from a URL, it scans through the file and uses the
first "proxy" or "direct" list which mentions the URL's domain. If the domain
doesn't appear in any of list, then the last "proxy" or "direct" list is used;
i.e., the last "proxy" or "direct" command is used as the default. As a simple
example, if all requests must go through a proxy, then elvis.net would
contain:
proxy www.myproxy.com
When elvis is given a URL that uses any protocol other than "ftp:" or "http:"
it searches through the elvis.net file for a proxy using the usual rules,
except that if the URL's domain isn't mentioned in any list, then elvis will
use the last proxy mentioned in the file (even if there is a "direct" list
after that). If there is no proxy, then elvis gives an error message. For
example, if you can access all sites directly, but also have access to a proxy
which can fetch non-ftp/http URLs for you, then elvis.net should look like
this:
proxy www.myproxy.com
direct
As a final example, here's a file which causes all accesses to sites whose
domain name ends with ".mylan.com" to be accessed directly, but all other
sites accessed via a proxy. This is a typical set-up for a proxy which is used
to reach out through a firewall.
direct .mylan.com
proxy www.myproxy.com
Note that all proxy accesses use the HTTP protocol, even if they are to FTP
sites. This means that you can only read through a proxy; you can't write
through a proxy because HTTP is a read-only protocol.
The proxy accesses work by sending an HTTP "GET" request to the HTTP server,
passing it the whole URL rather than just the directory and filename. The
server must then be clever enough to parse the URL, and fetch the requested
document from the proper site, using the proper protocol. Not all servers are
that smart, so don't be surprised if your closest server can't handle proxy
requests.
If elvis.net doesn't exist, then all FTP or HTTP accesses will be direct, and
other protocols will generate an error. The same behavior can also be
generated by creating an elvis.net file containing only the word "direct".
ΓòÉΓòÉΓòÉ 1.16. Elvis Tips ΓòÉΓòÉΓòÉ
16. TIPS
This section of the manual explains some of the more complex, obscure, and
useful features of elvis (or larger subjects). The following subjects are
discussed:
16.1 Information via the Web
16.2 Using elvis as a Web browser
16.3 How to debug macros
16.4 Running your compiler from within elvis
16.5 Internationalization
16.6 Aliases
- 16.6.1 Some example aliases
16.7 How to make elvis run faster
16.1 Information via the Web
Here are some URLs (World Wide Web links to other documents) which are
relevant to vi. Each of these, in turn, has links to other sites. Directly or
indirectly, these links will lead you to a huge amount of information about
vi.
I've tried to limit this list to advertized sites; there are others that I run
across from time to time, but their URLs tend to vary over time, so it isn't a
good idea to place them in a static document such as this one. It makes for a
short list, though.
ftp://ftp.cs.pdx.edu/pub/elvis/README.html
The "home" site of elvis. This is where you can find the latest
official release.
ftp://ftp.cs.pdx.edu/pub/elvis/unreleased/README.html
Prerelease versions of elvis can often be found here. Prerelease
versions are identified by a letter appended to the version number
they they're expected to be released as. For example, 2.1a is a
prerelease version of what will eventually be released as version
2.1. Also, I append "-alpha" in the early stages when new features
are still being added, or "-beta" if no new features are expected
before the release. Typically, new versions are uploaded once a
month or so; watch for announcements on the comp.editors newsgroup.
http://www.fh-wedel.de/elvis/index.html
This where Herbert (a.k.a. Martin Dietze, who ported elvis to OS/2)
is putting an Elvis home page. It is expected to have links to all
relevent web pages, archives, and people's email addresses. The
manual will also be available here. He is also considering adding a
searchable online database of aliases and how-to articles. This may
also become the preferred way to submit bug reports, suggestions, or
any other contribution to the project.
http://greens.ml.org/about/elvis/online-help/elvis.html
This is one location on the web where elvis' manual is available
online. Be sure to check the version number!
http://www.phys.columbia.edu/~flame/vi.htm
This is a Web page for elvis, maintained by JaeSub Hong. It has some
screen shots, macros, and syntax-coloring definitions. It also has
the online manual.
http://www.cs.vu.nl/~tmgil/vi.html
"The VI lover's home page." This contains links to a wide variety of
vi documentation, and practically all vi clones. A very good
resource!
http://www.math.fu-berlin.de/~guckes/vi/features.html
Feature comparison between different VI implementations, plus a few
other editors. Originally it just listed which options are supported
by which clones, but it has matured a bit since then. The maintainer
is fond of VIM, so there is a bias towards that.
http://www.bsyse.wsu.edu/~rnelson/editors/editors.htm
A compendium of text editors. It describes all kinds of text
editors, not just vi clones. It lists the features and supported
platforms for each editor.
http://home.hiwaay.net/~darren/ctags/
Home page for Darren Hiebert's exuberant ctags program. It supports
all features of elvis' ctags, except for the "-r" flag for
generating a "refs" file. Exuberant ctags has a smarter parsing
algorithm, which causes it to generate fewer bogus tags (i.e., tags
for things that really shouldn't have tags). It also adds the
ability to generate tags for "enum" values and a few other useful
things.
http://wafu.netgate.net/tama/unix/global.html
Home page for Shigio Yamaguchi's global function reference utility.
You can make elvis use it instead of the normal built-in tag
searcher by giving elvis the following command:
:se tagprg="global -t $1"
Once you have run global's gtags utility, you can do some powerful
things such as search for each place where a function (e.g.,
m_front()) is called, like this:
:ta -r m_front
http://www.cs.berkeley.edu/~amc/Par/
Home page for Adam Costello's par program, which is a much more
sophisticated text formatter than the fmt program distributed with
elvis. It even does a very good job of reformatting comments! Sadly,
it is one of those rare programs that doesn't handle tab characters
correctly.
ftp://alf.uib.no/pub/vi
An archive site containing many macro packages and other information
about vi. Nearly all of it should apply equally well to elvis.
ftp://ftp.oce.nl/pub/vim
http://www.clark.net/pub/dickey/vile/vile.html
http://www.sleepycat.com/vi/
http://www.snafu.de/~ramo/WinViEn.htm
http://ourworld.compuserve.com/homepages/fwiarda/software.htm
These are the home pages for some other vi clones: vim, vile, nvi,
WinVi, and pvic respectively.
ftp://ftp.funet.fi/pub/doc/posix/p1003.2a/d8/5.10
ftp://ftp.funet.fi/pub/doc/posix/p1003.2a/d8/5.35
These are old drafts of the POSIX standards for ex and vi,
respectively. These URLs might not be valid very long.
http://www.de.freebsd.org/de/doc/usd/12.vi/paper.html
This is the official BSD documentation for vi.
http://alumni.caltech.edu/~dank/nansi/
This is a home page for the NANSI.SYS and NNANSI.SYS drivers, which
accelerate the screen updates under MS-DOS.
16.2 Using elvis as a Web browser
NOTE: The following information doesn't apply to the MS-DOS version of elvis,
because that version doesn't support the ftp and http protocols. But for
Win32, Unix, and OS/2...
You can use elvis as a light-weight Web browser. Surfing with elvis isn't as
much fun as surfing with a multimedia-capable browser such as Netscape or
MSIE, but elvis does have some advantages: it starts up much faster, it feels
like vi, and you can edit whatever you download.
There's no special trick to loading a Web page. Just give a URL where elvis
expects a filename, and elvis will read the Web page via the Internet. You can
follow links in Web pages just as you do in elvis' online manual. HTML pages
are displayed in the "html" display mode, and anything else uses the "hex" or
"normal" display mode by default. All data is fetched in binary so data files
aren't mangled; however, this also means that newlines aren't converted, which
may make non-HTML text files look ugly.
Elvis has built-in support for the HTTP and FTP protocols. Other protocols may
be indirectly supported, via an HTTP proxy as indicated by the elvis.net
configuration file.
By default, FTP access is anonymous. However, if you give a file name which
starts with "/~/" then elvis will attept to login to the FTP server using you
own account, as described in the elvis.ftp or ~/.netrc configuration file. For
example, "ftp://localhost/directory/file" uses anonymous FTP, but
"ftp://localhost/~/directory/file" uses your own account.
Elvis can write via FTP as well as read; see the Internet chapter.
Elvis also doesn't support inline graphic images, but that isn't as big of a
problem as you might think. If you download an image, elvis will simply load
it into a buffer and then display that buffer in the "hex" display mode. You
can then write that buffer's contents to a file, or in Unix you can send it
directly to an image viewer via a command such as ":w !xv -".
The easiest way to save an image (or any other buffer) to a local file is via
the command ":w (dirfile(filename))". In fact, you might want to add the
following lines to your ~/.exrc file to make the (F2) key save the current
buffer to a file, and the (F3) key send it to the xv image viewer:
map #2 :w (dirfile(filename))^M
map #3 :w !xv -^M
To make images easier to fetch, any <IMG SRC=url> tag which isn't already part
of a hypertext link will be interpreted as a link to the SRC url. This allows
you to download an image by moving the cursor onto it and hitting the (Enter)
key.
Elvis doesn't support frames either, so a similar trick was used for <FRAME
SRC=url> tags. Elvis displays the name of each frame; those names serve as
links to the contents of the frame.
Because elvis is primarily an editor, not a Web browser, I deliberately made
the "html" display mode rather picky, so that any questionable entities in
your own HTML documents will call attention to themselves. When you're using
elvis to browse other peoples' documents, though, this can be annoying, so I
modified it slightly to be more forgiving when you're viewing read-only
documents. (All Web pages are read-only.)
And you already know that elvis' support for the <TABLE> macros is very poor,
right? If you encounter a Web page which looks really ugly in elvis, you can
bet it uses tables.
Elvis doesn't support forms, or secure connections. Well, elvis can display
mock-ups of forms; they just don't work. They probably never will. You have to
draw the line somewhere.
Elvis doesn't always choose the best display mode for HTML pages. It uses
"html" if the file name ends with ".html" or ".htm", or if the document's text
begins with "<!", "<H", or "<h". For all other documents, it uses the "normal"
or "hex" display mode by default. If elvis chooses the wrong display mode, you
can use the :display command to switch to a different display mode.
The command ":e foo" will always load the local file "foo" from your current
directory. This is true of all commands which normally act on files -- unless
you give a complete URL, elvis assumes it should work with local files.
However, while in the "html" display mode, the command ":ta foo" will use the
same protocol, site, and directory as the page you're already viewing, because
that's how the "html" display mode interprets tags.
16.3 How to debug macros
There are two ways to create a macro in elvis: You can either assign a series
of commands to a keystroke (or series of keystrokes) via the :map command, or
you can store a series of commands in a cut buffer and execute them via the
visual @x command. You will often use a combination of techniques, in which
:map macro constructs a customized @x macro and runs it.
Elvis has several features that make debugging macros much easier. For
example, you can create a window which continuously displays the contents of a
given cut buffer, such as "m, via the command:
:(Elvis cut buffer m)split
or, more concisely:
:("m)sp
Note: The cut buffer must exist before you can display it. Cut buffers are
created the first time anything is yanked into them.
The maptrace option allows you to trace the execution of macros. You can
either allow it to run through the macro, or wait for a keypress before each
mapped command character. You can also use the :break and :unbreak commands to
set or clear a breakpoint on a given :map macro. Breakpoints cause the
maptrace option to switch from "run" to "step" when that macro is expanded.
The maplog option can be used to log the trace information to a buffer named
"Elvis map log". The idea here is that you will give the command...
:se mt=r mlog=r
... (or its full-length form, :set maptrace=run maplog=reset) before starting
the macro, and then when the macro fails you can give the command...
:(Elvis map log)split
... to see what it was doing shortly before the failure. Note that the maplog
option has no effect if maptrace is "off".
Warning: Elvis has a single keystroke queue which is shared by all windows.
Because of this, while elvis is running a macro in one window you can't switch
to another window and type in commands. Even if the GUI allows you to switch
windows without using the keyboard, doing so will simply force the macro to
continue execution in the new window. So don't switch windows while a macro is
running!
Here's a debugging methodology that works for me:
1. Begin by loading the macro package and a test file.
2. Give the command ":se mt=r mlog=r", and run the macro.
3. If the macro fails, give the command ":(Elvis map log)split" to find
out what commands executed immediately before the failure. In
particular look for a :map macro that was expanded shortly before the
failure.
4. Set a breakpoint on that macro with ":break macrokey".
5. Turn off logging, via ":se mlog=o".
6. Reload the test file.
7. Execute the macro again. When the macro with the breakpoint is
encountered, elvis will switch to single-step mode. Step slowly
through the next few instructions, looking for one which does something
unexpected.
If your macro reveals a bug in elvis, please let me know! My email address is
kirkenda@cs.pdx.edu. Please tell me which version of elvis you're using, as
reported by the :version command.
16.4 Running your compiler from within elvis
Elvis can parse most compilers' error messages. When it parses an error
message, elvis loads the faulty file, moves the cursor to the line where the
error was reported, and shows the descriptive portion of the error message on
the bottom row of the window. You can step through all reported errors very
quickly, making changes along the way.
Usually, you will invoke your compiler or "make" utility via the :cc or :make
commands. The only difference between these commands is that :cc invokes the
program named by the ccprg option, and :make uses the makeprg option.
Both of those options' values are evaluated using the simpler expression
syntax, with $1 set to any extra command-line parameters, and $2 set to the
current file name.
You can also read error messages from some other program with the command
":errlist !program", or read them from a file with the command ":errlist
filename".
I often invoke elvis via the command "elvis +make" so elvis will attempt to
compile the program, and move the cursor to the first error (if there are any
errors).
All of the compiler's output text is collected into a buffer named "Elvis
error list". If you wish, you can view this list in a separate window via this
command:
:(Elvis error list)split
Here's how elvis parses each line of compiler output: Starting from the left,
it divides the line into "words", which are defined as a series of letters,
digits, and/or certain punctuation characters.
If the word is the name of an existing directory, then elvis remembers that
directory name. In later lines, elvis will allow file names to be given
relative to that directory, in addition to the current directory. This
particular feature is intended to work with the directory lines generated by
the GNU version of the "make" program.
If the word looks like a number, and no line number has been seen yet, then
the word is taken to be a line number. If the word is the name of an existing,
writable file (or any existing file if the anyerror option is set) in either
the current directory or the directory remembered from a previous line as
described above, then the word is taken to be a file name. Other words are
ignored.
When elvis has found both a file name and a line number, then it skips over
any whitespace or punctuation immediately following them, and uses the
remainder of the line as the error's description.
If elvis fails to find a file name/line number pair, then it skips that whole
line of compiler output.
Immediately after collecting compiler output, elvis moves the cursor to the
source of the first error. After that, you can use :errlist (with no
arguments) or the visual * command to step through each following error.
Each time elvis collects a new set of error messages, it remembers how many
lines are in each buffer. Later, when you insert or delete lines to correct an
error, elvis can compare the current number of lines to original number of
lines, and adjust the reported line numbers accordingly.
Here's something that may be useful for PERL programmers. PERL's error
messages follow two distinct formats, neither of which looks like any compiler
error message format; consequently, elvis can't parse PERL's error messages
directly. The following PERL program is a filter that reformats PERL's error
messages to look more like normal compiler error messages.
#!/usr/bin/perl
$\ = "\n";
while (<>) {
chop;
s/(.*) in file ([^ ]*) at line (\d*).*/$2($3): $1/;
s/(.*) at ([^ ]*) line (\d*)\.$/$2($3): $1/;
print;
}
To use this script, store it in a file named "perlerr" and turn on the file's
"execute" flag, and then set elvis' ccprg option as follows:
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéFor CSH: Γöé:set ccprg="perl -c ($1?$1:$2) |& Γöé
Γöé Γöéperlerr" Γöé
Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
ΓöéOther shells: Γöé:set ccprg="perl -c ($1?$1:$2) 2>&1 | Γöé
Γöé Γöéperlerr" Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
16.5 Internationalization
Elvis can be configured to translate its messages into different languages,
and to use different symbol sets. These things are accomplished via the
elvis.msg file and :digraph command, respectively.
Elvis locates the elvis.msg file during initialization. Ordinarily it searches
through each directory named in the ELVISPATH environment variable. However,
if there is an environment variable named LC_ALL, LC_MESSAGES, or LANG (listed
in order or precedence) which is set to a non-null value, then elvis will look
for elvis.msg first in a subdirectory whose name matches the environment
variable's value. For example, if ELVISPATH=~/.elvis:/usr/local/lib/elvis,
LC_ALL is unset, and LC_MESSAGES=german, then elvis would try to load its
messages from...
1. ~/.elvis/german/elvis.msg
2. ~/.elvis/elvis.msg
3. /usr/local/lib/elvis/german/elvis.msg
4. /usr/local/lib/elvis/elvis.msg
The digraph table affects more than just keyboard input. It also affects
"html" mode, and character type classifications.
Digraphs are used by the "html" display mode to translate character entities
into characters. For example, when elvis encounters & ntilde; in an HTML
document, it tries to find a digraph which combines 'n' with '~'. If there is
such a digraph, elvis will use it to display an 'Γòñ'; if not, then elvis will
display a plain 'n' character.
The digraph table affects the character classes, too. This, in turn, affects
the definition of a "word", as used by the visual w command, among others. A
non-ascii character is treated as an uppercase letter if, according to the
digraph table, it is the result of combining an ASCII uppercase letter with
either a punctuation character or a second uppercase letter. A similar rule
holds for lowercase letters.
Also, elvis tries to find uppercase/lowercase pairs through the digraph table.
This is used for case conversions, as performed by the visual ~ command, or
the \U metacharacter in the :s/old/new command.
There is no way to specify a sorting order. This means, in particular, that
the regular expression /[a-z]/ will only match the ASCII lowercase letters,
not the non-ASCII ones. However, the regular expression /[:lower:]/ will
match all lowercase letters including the non-ASCII ones.
The default elvis.ini file tries to load digraphs by executing either
elvis.pc8 for MS-DOS, OS/2, or text-mode Win32, or elvis.lat for any other
operating system.
The "win32" version of the "termcap" user interface has a codepage option
which determines which symbol set is used for console output. If you change
codepage, you should also adjust your digraph table.
16.6 Aliases
Aliases provide a simple way to add a new name for an existing ex command, or
series of ex commands.
The syntax of elvis' :alias command is intended to resemble that of the csh
Unix shell. The simplest example of an alias is...
:alias save w
... which would allow you to write your file out by running ":save", as an
alternative to the standard ":w". If you pass any arguments to ":save" then
they'll be appended to the ":w" command. For example, ":save foo" would be
interpreted as ":w foo".
Here's another example. On Unix systems, this will make ":ls" display a
directory listing.
:alias ls !!ls -C
Note that the above example requires two exclamation marks. This is because
the "!" character is special in aliases -- elvis' aliases allow you to use
special symbols to indicate where arguments belong in the command text, and
all of those symbols begin with a "!" character. When you invoke the alias,
all of the symbols are replaced by argument values before the command text is
executed. Here is a complete list of the replacement symbols:
.--------.-------------------------------------------------.
| SYMBOL | REPLACED BY |
|--------|-------------------------------------------------|
| !< | first address line, if any addresses given |
| !> | last address line, if any addresses given |
| !% | address range, if any addresses given |
| !? | "!" if the alias is invoked with a "!" suffix |
| !* | the entire argument string except for "!" suffix|
| !^ | the first word from the argument string |
| !$ | the last word from the argument string |
| !n | the nth word (where n is a single digit) |
| !! | a single, literal "!" character |
^--------^-------------------------------------------------^
Using any of the !*, !^, !$, or !1 through !9 symbols in the command string
has the side-effect of disabling the normal behavior of appending the
arguments to the command. Or to phrase that another way: If the command text
doesn't explicitly say what to do with arguments, then elvis will assume it
should simply append them.
The other symbols, such as !% and !?, have no such default behavior. If your
macro is going to use addresses or a "!" suffix, then you must explicitly
include !% or !? (respectively) in the command string.
Here's a simple alias for playing around with these:
:alias show echo !!<=!< !!%=!% !!?=!? !!*=!* !!^=!^ !!2=!2 !!$=!$
Here's a more sophisticated version of the ":save" alias. This version allows
you to use ":save!" as an alias for ":w!".
:alias save w!?
Here's a macro that converts a range of lines to uppercase. If invoked
without any addresses, it will change only the current line, because that's
the default for the :s command.
:alias upper !%s/.*/\U&/
You can define multi-line aliases by enclosing the lines in curly braces. The
following example uses this technique to make a slightly smarter version of
the "save" alias:
:alias save {
"Write a file, but only if it has been modified
if modified
then w!? !*
}
Note that the first line of the alias's body is a comment. (Comments start
with a " character.) This is a good idea because with the :alias command is
invoked with no arguments, it lists the names and first lines of all aliases.
Putting a descriptive comment in the first line allows you to see what each
alias does simply by examining that list.
If a multi-line alias is going to use arguments, then it must include !*, !^,
!$, or !n symbols. Elvis does not, by default, append arguments to the end of
a multi-line alias; it only does that for single-line aliases.
An alias can have the same name as a built-in command, but aliases can't be
recursive. Together, these two rules mean that you can use an alias to change
the behavior of a built-in command. For example, the following alias makes
the :w command perform an RCS checkout operation if you don't already have
write permission for a file. The "w" command inside the command text refers to
the normal :write command since it isn't allowed to be a recursive call to the
"w" alias.
:alias w {
"Write a file, checking it out first if necessary
if readonly && "!%!?!*" == ""
then !!co -l %
then w!!
else !%w!? !*
}
You can optionally insert a ':' character between the '!' and the second
character of any of these symbols. This has no effect; it is allowed simply to
remain a little closer to CSH's alias syntax.
You can also optionally insert a '\' character between the '!' and the second
character. This does have an effect: It causes a backslash to be inserted
before any characters which would otherwise receive special treatment if they
appeared in a regular expression. Specifically, it will always insert a
backslash before '\', '/', '^', '$', '.', '[', or '*'. Note that this is not
sensitive to the magic option; in effect, it assumes that magic is always set.
Also, it never inserts a backslash before a '?' character even if it is used
in a regular expression which is delimited by '?' characters. The following
"find" alias will search for literal text:
:alias find /!\*
In addition, you can optionally specify a default value for an argument, by
placing the value in parentheses between the '!' and the second character.
Here's an example which acts like echo, except that if you don't tell it what
to echo then it will echo "Howdy!":
:alias greet !(Howdy!)*
If necessary, you can insert both a backslash and a parenthesized default
value. The backslash quoting will be applied to the given argument value, but
bot the parenthesized default value. Here's a variation of the "find" alias
which searches for literal text, or if you don't specify any text to find then
it searches for a { character at the front of a line.
:alias find /!(^{)\*
Some vi commands are implemented via ex commands. If you create an alias
with the same name as a built-in ex command, then the corresponding visual
command will be affected. For example, the ZZ visual command runs :x, so the
following alias would break the ZZ command...
:alias x echo Winners never quit, and quitters never win
16.6.1 Some example aliases
The distribution comes with some handy aliases in a file named lib/exalias.eg.
I suggest you look at them. The simple ones should give you some ideas of how
to structure your own aliases, and the complex examples will give you a feel
of what can be accomplished.
These examples are intended to be useful as well as instructive. The aliases
in that file include:
:save [filename]
Write this file, but only if it has been modified.
:[range]w[! ] [filename]
Like the normal :w command, except that if you try to write a whole
file back over itself, and that file is readonly, then the :w alias
will attempt to perform an RCS "checkout" operation on that file.
:man [section] topic
Unix only. Read a man-page and display it in a new window.
:courier [size]
X11 only. Select the courier fonts of the given size. If no size is
specified, then it uses the default size, which is 18-point.
:copying
Display the license
:howto[!] word [word2 ]
Load the "How To" appendix in a separate window, and search for a
topic containing the given word or words. The words should be typed
in lowercase. If you want to search all lines (not just topic lines)
then run :howto! (with a ! suffix).
:cbsave filename
:cbload filename
Save the cut buffers ("a through "z) to a file, or load them from
that file.
:config
Report the configuration of your copy of elvis. I.e., list the
features which were enabled at when elvis was compiled.
:[range]left
:[range]right
:[range]center
For each line in the given range (or only the current line if no
addresses are given), adjust the indentation so that its text is
moved to the left, right, or center of the line.
:[range]rot13
Peform ROT13 encryption/decryption on the given range of lines, or
only the current line if no addresses are given. ROT13 is a simple
character-substitution code in which characters from the front half
of the alphabet are exchanged with the corresponding characters from
the back half of the alphabet. It is sometimes used as a courtesy
when posting offensive jokes to the rec.humor newsgroup, along with
an unencrypted warning such as "The following may be offensive to
whomever. Decode using ROT13 at your own risk."
:[range]cfmt
Adjust the line breaks in a C or C++ comment block.
:[range]align
Align any = signs (or other given text) in range of lines. This is
useful for making macro definitions in a Makefile look pretty. This
is the most complex example.
:match
If the cursor (in visual mode) is on an "if", "while", or "for"
keyword then this moves the cursor to the matching "endif",
"endwhile", or "endfor" keyword, respectively. It can also do the
reverse.
16.7 How to make elvis run faster
This section describes some ways you can "tune" elvis to run faster. None of
these suggestions require recompiling elvis.
For example, my computer (AMD K6-200) can run 10 generations of the "life"
macros in 41 seconds with the default configuration. If I invoke elvis with a
reduced block size (-b1024 on the command line) and an increased cache (:set
blkcache=200 blkhash=300), it can run 10 generations in just 24 seconds.
The blksize option
Elvis uses fixed-size blocks to store buffers. The block size is chosen when
the session file is created. The default is 2048 bytes (or 1024 bytes for
MS-DOS), but you can override that by invoking elvis with a -bblksize flag.
The size must be a power of two, between 512 and 8192.
The blksize option indicates the current block size. This is a read-only
option; once elvis has started, (and hence has already created the session
file) it is too late to request a different block size.
Generally, smaller blocks are better if your CPU is slow or you're only
editing small files. Larger blocks are better if your disk is slow (e.g., the
temporary file is stored on a remote disk, accessed via a network) or you're
editing large files.
The block cache
In the interest of speed, elvis has its own cache of blocks from the session
file. The blkcache option tells elvis how many blocks to store in the cache.
You can change this value at any time. If elvis requires more cached blocks
for a given editing operation than the blkcache allows, then elvis ignores
blkcache and loads the required blocks into the expanded cache; you can't make
blkcache too small. The default blkcache is 20 (except for MS-DOS, where it is
10), and the upper bound is 200 blocks. In MS-DOS, setting blkcache too high
can cause elvis to crash.
The blkhit and blkmiss options count the number of cache hits and misses, so
you can compute the efficiency of the cache as follows:
:calc (bh*100/(bh+bm))"%"
You'll probably find that 98% or more of the block requests are being
satisfied from the cache. However, since each miss takes thousands of times
longer to complete than a hit, each fraction of a percent means a lot.
In addition to the blocks themselves, the cache contains a hash table which
allows elvis to quickly determine whether a block is in the cache or not. If
you increase the size of the cache, then you'll probably want to increase the
size of the table as well. The table size is controlled by the blkhash
option. Ideally, it should be set to a prime number somewhat larger than
blkcache... or simply the largest possible value, since hash table entries are
small. The default is 61, and the upper bound is 300.
Syncing
Elvis has a sync option which, if set, causes elvis to force all dirty blocks
out to disk occasionally. This is a very slow operation, so the sync option
is normally turned off. If elvis seems to be running exceptionally slowly,
then you might want to verify that sync is off. You can check it by giving the
command ":set sync?".
Temporary files
The session file, and any other temporary files, should be stored on a local
hard disk. Storing them on a network drive will slow elvis down a lot.
The session option indicates where the current session file is stored, and the
sessionpath option indicates which directories elvis looked through when
deciding where to put the session file. These are read-only options, since it
is too late to choose a new location for the session file after the session
file is already created. If you need to force elvis to store its session files
in a different directory, you should set the SESSIONPATH environment variable
to a list of acceptable directories. Elvis will use the first directory from
that list which exists and is writable.
The directory option tells elvis where to store other temporary files, such as
those used for piping text through external programs. You can change its
value at any time. (Note: the real vi also has a directory option, but only
allows you to change it during initialization.)
Screen updates
Options which add information to the bottom row of the window, such as ruler
and showmode, can slow down screen updates. If speed is critical, you should
turn those options off.
The optimize option attempts to eliminate superfluous screen updates while a
macro is executing. It is normally on, but you may want to verify that. Some
animation macros force it off.
Elvis also has an animation option which, if optimize is on, causes elvis to
bypass some of the animation steps. The default value is 3. If animations
look choppy then try reducing it to 1. Or set it to 10 or so for faster
animation.
The exrefresh option controls whether elvis should refresh the screen after
each line output by an ex command, or wait until the command completes and
then update the screen once. It is normally off, so the screen is only updated
once.
Interestingly, the syntax-coloring display mode seems to run about as fast as
the normal display mode. One possible exception would be if you're running
elvis over a slow modem connection then the extra escape sequences required
for sending color information may slow down screen updates.
If you have long lines, then elvis may run somewhat faster when the wrap
option is set. This is because elvis always formats entire lines, even if
only part of the line is visible on the screen, and the "nowrap" display style
shows more long lines (one per row) than the "wrap" display style.
Input
The pollfrequency option indicates how often elvis checks for an abort request
from the user. (Abort requests are usually given by typing ^C or by clicking
on a window while a macro or other time-consuming command is running).
Smaller numbers give a quicker response to an abort request, but will cause
the command itself to run slower.
The keytime option indicates how long elvis should wait after receiving an Esc
character to distinguish between the <Esc> key, and some other function key
which begins with an Esc. Longer times are more reliable, especially when
you're running over a network. But shorter times allow a quicker response to
the <Esc> key.
MS-DOS-specific tips
The single biggest improvement you can make is to switch from the 16-bit
MS-DOS version to the 32-bit text-mode Win32 version. It only runs under
Windows95 or WindowsNT, not MS-DOS, but you can make it run in full-screen
mode which feels like MS-DOS. And it is *much* faster, because I really had
to mangle the MS-DOS version of elvis to make it fit in the lower 640k.
The fancier ANSI drivers such as NANSI.SYS also help. They allow elvis to
redraw the screen very quickly. The URLS section of this chapter tells you
where you can find NANSI.SYS on the Internet.
Installing smartdrv.exe can be a big help. Storing temporary files on a RAM
disk (in extended/expanded memory please!) can also help.
Elvis also has a compile-time option, controlled by the FEATURE_RAM
declaration in config.h, which allows elvis to store its buffers in EMS/XMS
memory instead of a file. This makes elvis run much faster, but it has some
disadvantages. If elvis crashes, there will be no way to recover the contents
of the edit buffers. Also the Microsoft functions for accessing EMS/XMS
memory are very bulky, and also require a fairly large buffer; so if you
enable FEATURE_RAM, then you must disable most of the other FEATURE_XXXX
features in config.h, and even then elvis may run out of memory occasionally.
If you enable FEATURE_RAM, then to actually use that feature, you must invoke
elvis with "-f ram" on the command line.
If you often use "-b 2048" or "-f ram", then you might consider setting up a
batch file which runs them. For example, you could create a elvis.bat file
containing...
elvis.exe -b 2048 -f ram %1 %2 %3 %4 %5 %6 %7 %8 %9
ΓòÉΓòÉΓòÉ 1.17. Elvis 2.1 Quick Reference ΓòÉΓòÉΓòÉ
.----------------------.-----------------------.-----------------------------.
| VISUAL MOVEMENT CMDS | VISUAL EDIT CMDS | EX COMMANDS [2] |
| h Move left | i Insert | :q! QUIT, NO SAVE |
| j Move down | a Append | :x SAVE & QUIT |
| k Move up | o Open line after | :qa Quit all windows |
| l Move right | O Open line before | :h topic Help |
| xxxG Go to line xxx | R Replace | :w file Write this file |
| /xxx Search forward | x Delete char | :n Edit next file |
| ?xxx Search backward | X Delete prev char | :e file Edit other file |
| n Repeat search | p Paste after [3] | :se ... Set/show options |
|----------------------| P Paste before [3] | :lp Print |
| VISUAL WINDOW CMDS | u Undo | :ta name Look up a tag |
| ^Ws Split window |-----------------------| :mak Compile, find error|
| ^W^W Go to next win | VISUAL OPERATORS [4] | :er Find next error |
| ^Wq SAVE & QUIT | < Shift left |-----------------------------|
| ^Wd Toggle display | > Shift right | OPTIONS [6] |
|----------------------| = Adjust via ep [5]| readeol File type |
|VISUAL MISCELLANY | !xxx Filter thru xxx | bufdisplay How to display |
| ZZ SAVE & QUIT | c Change | tabstop Width of tab char|
| ^L Refresh screen | d Delete | shiftwidth For < > operators|
| : Run 1 ex command| y Yank | inputtab Role of <tab> key|
| Q Run many ex cmds|-----------------------| magic Searching syntax |
| K Look up word [7]| VISUAL SELECTIONS [8] | ruler Show line/columns|
| Esc Cancel command | v Select chars | showmode Show input state |
| ^G Show fil info | V Select lines | lptype Printer type |
| . Repeat change | ^V Select rectangle | lpout Printer port |
^----------------------^-----------------------^-----------------------------^
NOTES:
1. This is not a complete list of commands and options. I just tried to fit
the most interesting and useful items in the smallest possible space.
Control characters are represented as a caret and a letter; e.g., ^X
means <Control-X>.
2. All ex command begin with a ':' keystroke, and end with a carriage
return. Try :help ex for more information.
3. Most commands which delete or change text will save the old text in a cut
buffer before making the change. The p and P commands copy text from the
cut buffer back into the file.
4. Operator commands are normally followed by a movement command; the
operator then acts on the text between the cursor's original position,
and the position that the movement command would move it to. For example,
"d24G" deletes all lines between the current line and line 24.
Alternatively, you could use a VISUAL SELECTION command and some movement
commands to highlight text, and then hit the operator to act on that
text.
5. The = operator sends text through an external filter program, named by
the equalprg option.
6. Options are accessed via the :set command.
7. The K command runs the program named by the keywordprg option; as an
argument, it passes whatever word the cursor is on. This can provide
convenient access to an on-line manual.
8. The visual selection commands can be by hitting the <Esc> key.
ΓòÉΓòÉΓòÉ 1.18. Elvis 2.1 How To ΓòÉΓòÉΓòÉ
C. How to...
This is a collection of "How to" topics, each with short discussion. The
following catagories of topics are available:
Initialization - Change the default behavior of elvis
Word Completion - Alter word completion via the Tab key
Whitespace - The relationship between tabs and spaces
Buffers - Cut buffers and edit buffers
X-Windows - The "x11" user interface
Windows95/98/NT - The "windows" user interface
Miscellany - Things that didn't fit anywhere else
If you're using elvis to view this file, you can search for a topic simply by
using the / command. To limit the search to topic lines only, begin the
regular expression with "^<dt>.*". For example you could search for "spaces"
in a topic line via the following:
/^<dt>.*spaces
Sometimes there are multiple topics that use the same word or phrase. If the
first one that it finds isn't the one you want, then you can use the n command
to find the next one.
In addition, the lib/exalias.eg script distributed with elvis contains a
"howto" alias which loads this file and searches for a given topic. If you've
loaded the aliases from that file, you display any topic in a a separate
window with via a command such as this:
:howto spaces
C.1 Initialization
Initialization for each file
The lib/elvis.arf file is executed after a file has been read; you
can put file initialization commands there.
Make file initialization be language-sensitive
If the filename extension indicates the file's language, and the
language is described in the lib/elvis.syn file, then you can use
the knownsyntax() function to check the language, like this:
:if knownsyntax(filename) == "perl"
:then set ccprg="perl -c ($1?$1:$2) 2>&1 | perlerr"
(The perlerr perl script converts perl's error messages into a form
that elvis can parse. It is given in the Tips chapter.)
You could also use the extension() function instead of
knownsyntax(); it doesn't depend on the lib/elvis.syn file. As a
last resort, you might consider using the x flag of the :s command.
Change the default settings
Before the first buffer is loaded or the first window is created,
and buffer/window options you set will be used as the defaults for
the buffers/windows that are created later. In other words, although
setting a buffer-specific option like equalprg or a window-specific
option like ruler interactively will only affect that buffer or
window, setting the same option in the lib/elvis.ini or ~/.exrc file
changes the default for all buffers/windows.
However, the lib/elvis.brf and lib/elvis.arf files typically change
some of those options, so the defaults might not be used very long
before they're changed.
Have a separate ~/.exrc and ~/.elvisrc file under Unix
This is easy. The lib/elvis.ini file controls this, and the default
version does it in a very convenient way: It looks first for
.elvisrc and runs it if it exists; else it looks for .exrc and runs
that.
If you want elvis to run both of them, then add the following line
to your .elvisrc file:
:source ~/.exrc
C.2 Word Completion
Disable word completion on the ex command line
You need to set the inputtab option for the (Elvis ex history)
buffer to "tab". You can do that via the following command:
:(Elvis ex history)set inputtab=tab
Disable identifier completion on the regular expression prompt line
This is similar to word completion on the ex command line. To
disable it, you need to set the inputtab option for the (Elvis
regexp history) buffer, like this:
:(Elvis regexp history)set inputtab=tab
Enable identifier completion in normal edit buffers
Set the buffer's inputtab option to "identifier". To make this the
default, set it in the .exrc file (or elvis.rc for non-Unix
systems). The command is:
:set inputtab=identifier
After that, each time you hit the <Tab> key elvis will search
through the tags file for any matching tags, and add as many
characters as possible. If it completes the entire tag name, it does
not append a space or other character, which is a little different
from other types of name completion. Also, in the syntax display
mode it will not attempt completion if the partial word happens to
be a complete keyword or otherword.
C.3 Whitespace
Use spaces instead of tabs
In the traditional vi, the only way to make elvis use spaces instead
of tabs was to set the tabstop option to the largest possible value,
and then :map ^I to ^T. This made existing tabbed files look bad,
and it didn't work well for tabs embedded in a line (instead of just
in the line's indentation whitespace). Elvis has a better way.
In elvis, you can set the inputtab option to "spaces" to make the
<Tab> key insert the appropriate number of spaces into a line. This
works even if the cursor isn't in the line's indentation whitespace.
In addition, the autotab option controls the shifting commands (the
:< and :> commands in ex, and the < and > operators in visual mode).
To make those commands use only spaces, autotab should be off.
:set inputtab=spaces noautotab
To convert existing files to use only spaces, you should use an
external program such as "col -bx" under Unix.
Change the tabstops
Many people don't like the fact that the <Tab> key indents text by 8
columns. That's so wide that it quickly pushes the writer's source
code off the right edge of the screen.
However, you almost certainly do not want to change the tabstop
option because most other software, and most printers and terminals,
also assume that tabs are 8 characters wide. If you edit files with
tabstop set to 4 or 5, then your files will look very strange when
viewed with anything other than elvis, or by anyone other than you.
So leave tabstop=8.
Instead, set the shiftwidth option to the desired indentation
amount, and either get in the habit of typing ^T to increase
indentation, or :map! the <Tab> key to ^T in input mode.
:set shiftwidth=5
:map! ^V^I ^V^T
Note that when you're typing in the above :map command, you'll need
to type an extra ^V before each ^V or ^T.
Also, this map has the unfortunate side-effect of making the <Tab>
increase indentation even if the cursor is somewhere later in the
line (unless you type ^V before it). This is one good reason to skip
the map, and get in the habit of using ^T to increase indentation.
The autotab option helps here, too.
C.4 Buffers
Switch to a different buffer in the same window
This is easier that you might think. On an ex command line, if you
give an address but no command then elvis will move the cursor to
there. So to switch buffers all you need to do is give an address
that's in a different buffer. In elvis, you do this by giving the
buffer's name (or number) in parentheses (and the closing
parenthesis is optional). For example, to switch to buffer #1 all
you need to do is...
:(1
Or you can switch to "main.c" like this:
:(main.c
Of course, the buffer must exist before you can switch to it.
Another thing to keep in mind is, switching buffers doesn't
necessarily force you to save the old buffer first. Any changes you
made to the old buffer are not lost -- you can switch back to the
original buffer again if you wish.
Display an edit buffer (or cut buffer) in a separate window
This is similar to switching edit buffers (the previous topic). The
main difference is that instead of giving no command, you should
give the :split command. In this context, the closing parenthesis is
required.
:(1)split
Or, create a window showing the "main.c" buffer:
:(main.c)split
Edit a cut buffer
Editing a cut buffer can be handy when you're trying to fix a
defective macro. This is possible in elvis, because elvis uses an
ordinary edit buffer to store the contents of a cut buffer. The
names of the cut buffers are of the form (Elvis cut buffer X), where
X is the name of the cut buffer (a single letter or digit).
Consequently, you could create a window showing cut buffer "a like
this:
:(Elvis cut buffer a)split
Of course, the "a cut buffer must exist for this to work.
Since the name is so long, elvis supports a special short-hand
notation for cut buffer names. In parentheses, if the first
character is " and the remainder of the buffer name is a single
letter, then elvis uses the buffer which contains that cut buffer's
contents. The following command also creates a window showing the "a
cut buffer:
:("a)sp
Elvis doesn't store "undo" versions for cut buffers, and you can't
yank a buffer into itself. Other than that, editing should be pretty
normal. The type of data in the buffer (characters, lines, or
rectangle) is stored in an option named putstyle.
Free an edit buffer
Elvis has no command for discarding old edit buffers. Under some
circumstances it will free them automatically, if they aren't being
used. It rarely matters, though.
C.5 X-Windows
Run elvis in an xterm instead of creating a new window
You can force elvis to use the termcap interface by adding a
-Gtermcap flag. If you do this often, you may wish to create a shell
script, alias, or shell function which runs elvis with -Gtermcap.
Here's an example of shell script:
#!/bin/sh
exec elvis -Gtermcap "$@"
If you never want to use the "x11" user interface, then you should
probably reconfigure elvis to leave it it out. This will make elvis
considerably smaller. To do this, go into the directory where elvis'
source code resides and execute the following shell commands:
make clean
configure --with-x=no
make
Make the text cursor more visible under X11
For a notebook computer, the normal blinking cursor may be hard to
see. You can make it stop blinking by adding the following command
to your .exrc file:
:set blinktime=0
Indicate when elvis owns the current X11 selection
The cursor can be configured to have a special color whenever elvis
owns the current selection. To do this, use the :color command to
set both the foreground and background color of the cursor. The
"background" color will be used when elvis owns the selection, and
the "foreground" color will be used otherwise. Here's an example
which turns the cursor green when elvis owns the selection:
:color cursor red on green
Change the default font size
In your .exrc file, you can set the normalfont, boldfont, and
italicfont options to anything you want. These settings will
override the defaults. If you set only the normalfont and leave the
others unset, then elvis will derive the others from the normal
font.
:set normalfont=7x14
If you just want to use a smaller size of the Courier font, you can
use the :courier alias. It takes a single parameter: the point size
of the font to use. The default font is 18-point Courier, and most
systems also have 14-point Courier fonts which works well.
:courier 14
Run a program from within elvis, in parallel, under X11
The tricky part here is that elvis tries to read the program's
stdout and stderr, so the output can be displayed in elvis' window.
Elvis must wait until after all text has been read from
stdout/stderr. So to run in parallel, you must redirect the
program's stdout/stderr to /dev/null, like this:
:!xeyes >/dev/null 2>&1 &
If you want to write data out to the program (:w !program) then it
becomes even more complex. This is because pipes can only contain a
finite amount of data, so when elvis is redirecting stdin as well as
stdout/stderr, it uses a temporary file for stdin. Elvis deletes
that file as soon as the program returns -- which, for a program run
in parallel, happens immediately even though the program hasn't had
a chance to read the data from that file yet. The solution is to
write the data into a temporary file sequentially, and then start a
parallel command line which runs the program and then deletes the
temporary file, like this:
:w !cat >$$; (xv $$; rm $$) >/dev/null 2>&1 &
Yes, that's nasty. I plan to clean that up some day, by making elvis
smart enough to avoid reading stdout/stderr when the command line
ends with a '&' character.
C.6 Windows95/98/NT
Set the initial working directory
Create a shortcut to WinElvis, and then edit the shortcut's
properties. The "Start in" property gives the program's initial
working directory.
Change the working directory each time a file is loaded
First, let me say that I don't recommend this because the real vi
doesn't behave like this, so it is likely to confuse some people.
But it you really want to do this, then you should add the following
line to the end of your lib/elvis.arf file:
try cd (dirdir(filename))
Select whole lines in WinElvis
To select whole lines in WinElvis, move the mouse pointer to the
window's left margin. The mouse pointer should change shape when
you're in the margin. Click the left mouse button there to begin
marking lines; hold the button as you move the mouse to the other
end of the range of lines and then release it.
C.7 Miscellany
Test for certain text within a file
This is sometimes handy in scripts and aliases. For example, the
elvis.arf script uses this to detect mode lines and the "hash pling"
header on other types of scripts, such as shell scripts which start
with "#!/bin/sh".
One nice trick is to use the x flag of elvis' :s command. It not
only detects text, but can incorporate that text into the commands.
For example, to compute the total of all numbers in all lines, you
could...
:set t=0
:%s/\<[[:digit:]]\+\>/let t = t + &/gx
:set t?
Note that this series of commands does not affect the edit buffer.
The x flag prevents the substitution from taking place; the
replacement text is executed instead.
You can also use the :try command to run a search command, and then
use :then and :else to act differently depending on whether the
search succeeded or not.
:try /Yow!
:then echo Zippy was here
:else echo Where in the world is Zippy the Pinhead?
You can also use the current("word") function to find the word at
the cursor location.
:let w=current("word")
Find the short name (or group name) of an option
Finding the long name of an option is easy, thanks to name
completion. To find the short name of an option, or the name of its
group, run the :set! command (with a !) and the long option name,
followed by a ? character. (For non-Boolean options, the ? is
optional.)
:set! wrapmargin?
This will produce output like "win.wm=0", indicating that the short
name is "wm", the group name is "win" (so each window has its own
margin), and the value is 0.
ΓòÉΓòÉΓòÉ 1.19. printdoc.bat ΓòÉΓòÉΓòÉ
REM () { :; }
REM This little script will print the documentation. It does this by invoking
REM elvis on each documentation file in turn, telling elvis to print the file
REM via its :lpr command and then quit. The complete manual should be about
REM 200 pages long.
REM
REM THIS ASSUMES YOU HAVE ALREADY SET UP THE PRINTING OPTIONS!
REM
REM This script should work under DOS, Windows/NT, and the UNIX "ksh" shell or
REM clones such as "bash". The first line of this file allows "sh" to accept
REM these REM lines without complaint, by defining it as a do-nothing function.
elvis -Gquit -clp elvis.html
elvis -Gquit -clp elvisvi.html
elvis -Gquit -clp elvisinp.html
elvis -Gquit -clp elvisex.html
elvis -Gquit -clp elvisre.html
elvis -Gquit -clp elvisopt.html
elvis -Gquit -clp elvisdm.html
elvis -Gquit -clp elvisgui.html
elvis -Gquit -clp elvisos.html
elvis -Gquit -clp elvisses.html
elvis -Gquit -clp elviscut.html
elvis -Gquit -clp elvismsg.html
elvis -Gquit -clp elvisexp.html
elvis -Gquit -clp elvistag.html
elvis -Gquit -clp elvisnet.html
elvis -Gquit -clp elvistip.html
elvis -Gquit -clp elvistrs.msg
elvis -Gquit -clp elvisqr.html
elvis -Gquit -clp elvis.man
elvis -Gquit -clp ctags.man
elvis -Gquit -clp ref.man
elvis -Gquit -clp fmt.man
ΓòÉΓòÉΓòÉ 2. External links ΓòÉΓòÉΓòÉ
This chapter contains all external links referenced in this book - either link
is an Unified Resource Locator (URL) or simply to a local file which is not a
part of this book.
ΓòÉΓòÉΓòÉ 2.1. mailto:herbert@paulina.shnet.org ΓòÉΓòÉΓòÉ
The link you selected points to an external resource. Click the URL below to launch IBM Web Explorer
mailto:herbert@paulina.shnet.org
ΓòÉΓòÉΓòÉ 2.2. http://fly.hiwaay.net/~darren/ctags.html ΓòÉΓòÉΓòÉ
The link you selected points to an external resource. Click the URL below to launch IBM Web Explorer
http://fly.hiwaay.net/~darren/ctags.html
ΓòÉΓòÉΓòÉ 2.3. ftp://ftp.oce.nl/pub/misc/vim ΓòÉΓòÉΓòÉ
The link you selected points to an external resource. Click the URL below to launch IBM Web Explorer
ftp://ftp.oce.nl/pub/misc/vim
ΓòÉΓòÉΓòÉ 2.4. ftp://ftp.cs.pdx.edu/pub/elvis/README.html ΓòÉΓòÉΓòÉ
The link you selected points to an external resource. Click the URL below to launch IBM Web Explorer
ftp://ftp.cs.pdx.edu/pub/elvis/README.html
ΓòÉΓòÉΓòÉ 2.5. ftp://ftp.cs.pdx.edu/pub/elvis/unreleased/README.html ΓòÉΓòÉΓòÉ
The link you selected points to an external resource. Click the URL below to launch IBM Web Explorer
ftp://ftp.cs.pdx.edu/pub/elvis/unreleased/README.html
ΓòÉΓòÉΓòÉ 2.6. news:comp.editors ΓòÉΓòÉΓòÉ
The link you selected points to an external resource. Click the URL below to launch IBM Web Explorer
news:comp.editors
ΓòÉΓòÉΓòÉ 2.7. http://www.fh-wedel.de/elvis/index.html ΓòÉΓòÉΓòÉ
The link you selected points to an external resource. Click the URL below to launch IBM Web Explorer
http://www.fh-wedel.de/elvis/index.html
ΓòÉΓòÉΓòÉ 2.8. http://www.phys.columbia.edu/~flame/vi.htm ΓòÉΓòÉΓòÉ
The link you selected points to an external resource. Click the URL below to launch IBM Web Explorer
http://www.phys.columbia.edu/~flame/vi.htm
ΓòÉΓòÉΓòÉ 2.9. http://www.cs.vu.nl/~tmgil/vi.html ΓòÉΓòÉΓòÉ
The link you selected points to an external resource. Click the URL below to launch IBM Web Explorer
http://www.cs.vu.nl/~tmgil/vi.html
ΓòÉΓòÉΓòÉ 2.10. http://www.math.fu-berlin.de/~guckes/vi/features.html ΓòÉΓòÉΓòÉ
The link you selected points to an external resource. Click the URL below to launch IBM Web Explorer
http://www.math.fu-berlin.de/~guckes/vi/features.html
ΓòÉΓòÉΓòÉ 2.11. http://www.bsyse.wsu.edu/~rnelson/editors/editors.htm ΓòÉΓòÉΓòÉ
The link you selected points to an external resource. Click the URL below to launch IBM Web Explorer
http://www.bsyse.wsu.edu/~rnelson/editors/editors.htm
ΓòÉΓòÉΓòÉ 2.12. http://home.hiwaay.net/~darren/ctags/ ΓòÉΓòÉΓòÉ
The link you selected points to an external resource. Click the URL below to launch IBM Web Explorer
http://home.hiwaay.net/~darren/ctags/
ΓòÉΓòÉΓòÉ 2.13. http://wafu.netgate.net/tama/unix/global.html ΓòÉΓòÉΓòÉ
The link you selected points to an external resource. Click the URL below to launch IBM Web Explorer
http://wafu.netgate.net/tama/unix/global.html
ΓòÉΓòÉΓòÉ 2.14. http://www.cs.berkeley.edu/~amc/Par/ ΓòÉΓòÉΓòÉ
The link you selected points to an external resource. Click the URL below to launch IBM Web Explorer
http://www.cs.berkeley.edu/~amc/Par/
ΓòÉΓòÉΓòÉ 2.15. ftp://alf.uib.no/pub/vi ΓòÉΓòÉΓòÉ
The link you selected points to an external resource. Click the URL below to launch IBM Web Explorer
ftp://alf.uib.no/pub/vi
ΓòÉΓòÉΓòÉ 2.16. ftp://ftp.oce.nl/pub/vim ΓòÉΓòÉΓòÉ
The link you selected points to an external resource. Click the URL below to launch IBM Web Explorer
ftp://ftp.oce.nl/pub/vim
ΓòÉΓòÉΓòÉ 2.17. http://www.clark.net/pub/dickey/vile/vile.html ΓòÉΓòÉΓòÉ
The link you selected points to an external resource. Click the URL below to launch IBM Web Explorer
http://www.clark.net/pub/dickey/vile/vile.html
ΓòÉΓòÉΓòÉ 2.18. http://www.sleepycat.com/vi/ ΓòÉΓòÉΓòÉ
The link you selected points to an external resource. Click the URL below to launch IBM Web Explorer
http://www.sleepycat.com/vi/
ΓòÉΓòÉΓòÉ 2.19. http://www.snafu.de/~ramo/WinViEn.htm ΓòÉΓòÉΓòÉ
The link you selected points to an external resource. Click the URL below to launch IBM Web Explorer
http://www.snafu.de/~ramo/WinViEn.htm
ΓòÉΓòÉΓòÉ 2.20. http://ourworld.compuserve.com/homepages/fwiarda/software.htm ΓòÉΓòÉΓòÉ
The link you selected points to an external resource. Click the URL below to launch IBM Web Explorer
http://ourworld.compuserve.com/homepages/fwiarda/software.htm
ΓòÉΓòÉΓòÉ 2.21. ftp://ftp.funet.fi/pub/doc/posix/p1003.2a/d8/5.10 ΓòÉΓòÉΓòÉ
The link you selected points to an external resource. Click the URL below to launch IBM Web Explorer
ftp://ftp.funet.fi/pub/doc/posix/p1003.2a/d8/5.10
ΓòÉΓòÉΓòÉ 2.22. ftp://ftp.funet.fi/pub/doc/posix/p1003.2a/d8/5.35 ΓòÉΓòÉΓòÉ
The link you selected points to an external resource. Click the URL below to launch IBM Web Explorer
ftp://ftp.funet.fi/pub/doc/posix/p1003.2a/d8/5.35
ΓòÉΓòÉΓòÉ 2.23. http://www.de.freebsd.org/de/doc/usd/12.vi/paper.html ΓòÉΓòÉΓòÉ
The link you selected points to an external resource. Click the URL below to launch IBM Web Explorer
http://www.de.freebsd.org/de/doc/usd/12.vi/paper.html
ΓòÉΓòÉΓòÉ 2.24. http://alumni.caltech.edu/~dank/nansi/ ΓòÉΓòÉΓòÉ
The link you selected points to an external resource. Click the URL below to launch IBM Web Explorer
http://alumni.caltech.edu/~dank/nansi/
ΓòÉΓòÉΓòÉ 2.25. mailto:kirkenda@cs.pdx.edu ΓòÉΓòÉΓòÉ
The link you selected points to an external resource. Click the URL below to launch IBM Web Explorer
mailto:kirkenda@cs.pdx.edu
ΓòÉΓòÉΓòÉ 2.26. news:rec.humor ΓòÉΓòÉΓòÉ
The link you selected points to an external resource. Click the URL below to launch IBM Web Explorer
news:rec.humor
(.txt)
(.txt)