Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
tree: 076cf4ad5c
Fetching contributors…

Cannot retrieve contributors at this time

4001 lines (3619 sloc) 219.763 kb
<title>Elvis-2.2_1 Options</title>
<h1>6. OPTIONS</h1>
Options are a primary means of configuring the appearance and behavior of Elvis.
They are set via the <a href="elvisex.html#set">:set</a> command, or the
<a href="elvisex.html#let">:let</a> command.
The options' values are examined directly by Elvis internally, and can also
be displayed via <a href="elvisex.html#set">:set</a>, or in an expression.
The following tables list the names, type, group, and description of each
One table lists <a href="#INDEX">all options alphabetically,</a> and the other
breaks list down into <a href="#GROUP">groups of related options.</a>
I recommend the latter, since there are <em>a lot</em> of options.
<p>Most options have two <em>names</em> -- 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.
<p>Each option accepts a specific <em>type</em> of value.
The most common types are <strong>boolean, number, string, one-of,</strong> and
<strong>tab-list,</strong> but some options have weird types.
<code>String</code> options can be set to any value (although not all possible values
make sense).
<code>One-of</code> options can only be set a single value from a specific list of legal values.
(The list varies from one option to another.)
<code>Boolean</code> options are either true or false;
see the <a href="elvisex.html#set">:set</a> and
<a href="elvisex.html#let">:let</a> commands for a description of how to
set their values.
<code>Number</code> options can only be set to a numeric value, often only within a limited range.
<code>Tab-list</code> options can be set to a comma-delimited list of numbers, in which each
number represents the width of a column; for long lines, Elvis assumes the
last number should be repeated.
<p>Each option serves as an attribute of something.
The <a name="GRP"><em>group</em></a> 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:
<pre graphic>
| global | Global options |
| user | <a href="#USER">User variables a - z</a> (Global, useful in ex scripts) |
| lp | <a href="#LPR">Printing options</a> |
| buf | Attributes of each buffer |
| win | Attributes of each window |
| syntax | Attributes of the "syntax" display mode |
| x11 | Attributes of the "<a href="elvisgui.html#x11">x11</a>" user interface |
| windows | Attributes of the "<a href="elvisgui.html#windows">windows</a>" user interface |
| termcap | Attributes of the "<a href="elvisgui.html#termcap">termcap</a>" user interface |
| vio | Attributes of the "<a href="elvisgui.html#vio">vio</a>" user interface (OS/2 console) |
| win32 | Attributes of the text-mode Win32 port |
| au | Used only when executing an autocmd |
| bang | Used only when writing a file |
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
<a href="elvisex.html#set">:set</a> command.
The following example outputs all of the attributes of the current buffer:
:set buf?
<h2><a name="GROUP">6.1 Options, grouped by function</a></h2>
<li><a href="#FILESAVE">6.2 Options that relate the buffer to a file</a>
<li><a href="#BUFFER">6.3 Statistics about a buffer</a>
<li><a href="#MOVE">6.4 Options that affect movement commands</a>
<li><a href="#INPUT">6.5 Options that affect input mode</a>
<li><a href="#EXOPTS">6.6 Ex options</a>
<li><a href="#WINDOW">6.7 Window statistics</a>
<li><a href="#VIEW">6.8 Options affecting the appearance of text</a>
<li><a href="#MODE">6.9 Options for a particular display mode</a>
<li><a href="#SPELL">6.10 Spelling options</a>
<li><a href="#MSG">6.11 Messages</a>
<li><a href="#WORDS">6.12 Words</a>
<li><a href="#GUI">6.13 Options for a particular user interface</a>
<li><a href="#REGEXP">6.14 Regular expression options</a>
<li><a href="#TAG">6.15 Tag options</a>
<li><a href="#DRAW">6.16 Window update parameters</a>
<li><a href="#CACHE">6.17 Cache options</a>
<li><a href="#SYSTEM">6.18 Options that describe the system</a>
<li><a href="#EXTERNAL">6.19 External programs</a>
<li><a href="#DIR">6.20 Directory names</a>
<li><a href="#INIT">6.21 Initialization options</a>
<li><a href="#MAP">6.22 Keyboard map options</a>
<li><a href="#AUTOCMD">6.23 Auto command options</a>
<li><a href="#LPR">6.24 Printing options</a>
<li><a href="#PREVIOUS">6.25 Previous arguments</a>
<li><a href="#UNSUP">6.26 Unsupported options</a>
<li><a href="#USER">6.27 User variables</a>
<h2><a name="FILESAVE">6.2 Options that relate the buffer to a file</a></h2>
<pre graphic>.---------------------.---------.--------.-----------------------------.
| <a href="#filename">filename, file</a> | String | buf | name of file in buffer |
| <a href="#bufname">bufname, buffer</a> | String | buf | name of buffer |
| <a href="#bufid">bufid, bufferid</a> | Number | buf | ID number of user buffer |
| <a href="#retain">retain, ret</a> | Boolean | buf | keep buffer in session file |
| <a href="#modified">modified, mod</a> | Boolean | buf | buffer differs from file |
| <a href="#edited">edited, samename</a> | Boolean | buf | buffer loaded from filename |
| <a href="#newfile">newfile, new</a> | Boolean | buf | filename doesn't exist yet |
| <a href="#readonly">readonly, ro</a> | Boolean | buf | don't overwrite filename |
| <a href="#defaultreadonly">defaultreadonly, dro</a>| Boolean | global | assume all files readonly |
| <a href="#locked">locked, lock</a> | Boolean | win | prevent any alterations |
| <a href="#autowrite">autowrite, aw</a> | Boolean | global | save file before switching |
| <a href="#writeany">writeany, wa</a> | Boolean | global | don't warn of existing file |
| <a href="#timestamp">timestamp, time</a> | String | buf | time when file was modified |
| <a href="#backup">backup, bk</a> | Boolean | global | make *.bak file before write|
| <a href="#undolevels">undolevels, ul</a> | Number | buf | number of undoable commands |
| <a href="#beautify">beautify, bf</a> | Boolean | global | strip ctrl chars from files |
| <a href="#bang">bang</a> | Boolean | bang | writing with a '!' ? |
| <a href="#userprotocol">userprotocol, up</a> | Boolean | buf | URL, user-defined protocol |
<dt><a name="filename">filename, file <em>(String, buf)</em></a>
<dd>The <em>filename</em> 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 <a href="elvisex.html#file">:file</a> 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.
<dt><a name="bufname">bufname, buffer <em>(String, buf)</em></a>
<dd>The <em>bufname</em> 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 <a href="elvisex.html#buffer">:buffer</a> command.
<dt><a name="bufid">bufid, bufferid <em>(Number, buf)</em></a>
<dd>For user buffers, the <em>bufid</em> option stores
a unique id number for each buffer.
Anyplace where you can use the <code>(</code><var>name</var><code>)</code> notation
to specify a buffer, you can also use <code>(</code><var>n</var><code>)</code>
as an abbreviation for the buffer whose bufid=<var>n</var>.
Also, for filenames you can use <code>#</code><var>n</var> for the filename of
the buffer whose bufid=<var>n</var>.
<dt><a name="retain">retain, ret <em>(Boolean, buf)</em></a>
<dd>The <em>retain</em> option indicates whether the buffer
is intended to survive past the end of this Elvis process.
If this option is true and the <a href="#tempsession">tempsession</a> 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.
<p>It also prevents Elvis from destoying the buffer during an edit session.
Normally, Elvis will destroy buffers if they aren't shown in any window, and
their contents haven't been modified since they were loaded or written.
<dt><a name="modified">modified, mod <em>(Boolean, buf)</em></a>
<dd>The <em>modified</em> option indicates whether the
buffer has been modified since the last time it was written out completely.
<dt><a name="edited">edited, samename <em>(Boolean, buf)</em></a>
<dd>The <em>edited</em> 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
<dt><a name="newfile">newfile, new <em>(Boolean, buf)</em></a>
<dd>The <em>newfile</em> 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.
<dt><a name="readonly">readonly, ro <em>(Boolean, buf)</em></a>
<br><a name="defaultreadonly">defaultreadonly, dro <em>(Boolean, global)</em></a>
<dd>The <em>readonly</em> option indicates that when the buffer was loaded,
the original file was marked as being unwritable. Either that, or the
<em>defaultreadonly</em> option was set to true
(probably via the <kbd>-R</kbd> 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.
<dt><a name="locked">locked, lock <em>(Boolean, win)</em></a>
<dd>The <em>locked</em> 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
<a href="elvisex.html#edit">:e</a> which merely reload the buffer from
its original file.
<dt><a name="autowrite">autowrite, aw <em>(Boolean, global)</em></a>
<dd>Setting the <em>autowrite</em> 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.
<dt><a name="writeany">writeany, wa <em>(Boolean, global)</em></a>
<dd>Elvis tries to save you from accidentally
clobbering existing files. Setting the <em>writeany</em> option disables this
protection; Elvis will allow you to overwrite any file that the operating
system will allow, without giving any warnings.
<dt><a name="timestamp">timestamp, time <em>(String, buf)</em></a>
<dd>This option has no hardcoded purpose, but the default
<a href="elvisses.html#elvis.arf">elvis.arf</a>,
<a href="elvisses.html#elvis.bwf">elvis.bwf</a>, and
<a href="elvisses.html#elvis.awf">elvis.awf</a> scripts use it
store the modification time of a file
(as detected by the <a href="elvisexp.html#time">time()</a> function),
and detect whether the file has been modified by some other program
while you were editing it in Elvis.
<dt><a name="backup">backup, bk <em>(Boolean, global)</em></a>
<dd>The <em>backup</em> option isn't used internally
by Elvis, but the default <a href="elvisses.html#elvis.bwf">elvis.bwf</a> 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.
<dt><a name="undolevels">undolevels, ul <em>(Number, buf)</em></a>
<dd>For each buffer, the <em>undolevels</em> 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.
<dt><a name="beautify">beautify, bf <em>(Boolean, global)</em></a>
<dd>If the <em>beautify</em> 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.
<dt><a name="bang">bang <em>(Boolean, bang)</em></a>
<dd>The <em>bang</em> option only exists while executing
the <a href="elvisini.html#elvis.bwf">elvis.bwf</a> and
<a href="elvisini.html#elvis.awf">elvis.awf</a> scripts, when writing a file.
It indicates whether the write was forced (<a href="elvisex.html#write">:w!</a>)
or normal (<a href="elvisex.html#write">:w</a> or
<a href="elvisvi.html#ZZ">ZZ</a>).
Those scripts can check the value of <code>bang</code> and skip some tests if
it is set.
For example, the default version of <code>elvis.bwf</code> checks the
<a href="#timestamp">timestamp</a> before writing the file,
unless the bang option is set.
<dt><a name="userprotocol">userprotocol, up <em>(Boolean, buf)</em></a>
<dd>The <em>userprotocol</em> option indicates whether the buffer was loaded
via a <a href="elvistip.html#PROTO">user-defined protocol</a>.
It can be handy in automatically executed scripts.
<p>Initially, all buffers are created with <code>userprotocol</code> turned off.
It remains off while the <code>elvis.brf</code> is executed, and then turned
on immediately before the <code>read<var>PROTOCOL</var></code> alias is
The default <code>elvis.arf</code> script is sensitive to this value;
it skips some setup steps when <code>userprotocol</code> is set, on the
theory that if you really needed those options to be set then you would
have either set them in the <code>read<var>PROTOCOL</var></code> alias,
or you would have at least turned off <code>userprotocol</code> there.
<h2><a name="BUFFER">6.3 Statistics about a buffer</a></h2>
<pre graphic>.---------------------.---------.--------.-----------------------------.
| <a href="#binary">binary, bin</a> | Boolean | global | -b flag for binary files |
| <a href="#readeol">readeol, reol</a> | One of | buf | newline mode when reading |
| <a href="#writeeol">writeeol, weol</a> | One of | global | newline mode when writing |
| <a href="#bufchars">bufchars, bc</a> | Number | buf | number of characters |
| <a href="#buflines">buflines, bl</a> | Number | buf | number of lines |
| <a href="#partiallastline">partiallastline, pll</a>| Boolean | buf | file didn't end with newline|
| <a href="#errlines">errlines</a> | Number | buf | buflines when :make was run |
| <a href="#internal">internal</a> | Boolean | buf | Elvis requires this buffer |
| <a href="#putstyle">putstyle, ps</a> | One of | buf | type of text in a cut buffer|
<dt><a name="binary">binary, bin <em>(Boolean, global)</em></a>
<dd>The <em>binary</em> option indicates whether Elvis was invoked with the
"-b" flag for working with binary files.
It affects the way the default <a href="#readeol">readeol</a> value is chosen
for new buffers.
If <code>binary</code>, then readeol=binary.
If <code>nobinary</code> readeol=text except that the default
<a href="elvisses.html#elvis.brf">elvis.brf</a> file will
try to guess a better value .
the default is <code>nobinary</code>.
<dt><a name="readeol">readeol, reol <em>(One of, buf)</em></a>
<dd>The <em>readeol</em> option determines how Elvis reads the file into a buffer.
It can be one of the following:
<li><strong>unix</strong> -
The file is opened in binary mode, and any Line Feed characters in the
file are converted to newline characters in the buffer.
<li><strong>dos</strong> -
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.
<li><strong>mac</strong> -
The file is opened in binary mode, and any Carriage Return characters from
the file are converted to newline characters in the buffer.
<li><strong>text</strong> -
The file is opened in text mode, and no other conversion takes place.
<li><strong>binary</strong> -
The file is opened in binary mode, and no conversion takes place.
The compiled-in default is "binary" or "text", depending on the
<a href="#binary">binary</a> option, but the standard
<a href="elvisses.html#elvis.brf">elvis.brf</a> file may change "text" to a
file-dependent value via the <a href="elvisexp.html#fileeol">fileeol()</a>
<dt><a name="writeeol">writeeol, weol <em>(One of, buf)</em></a>
<dd>The <em>writeeol</em> option influences how Elvis writes buffers out to a
If a buffer's <code>readeol</code> option is set to "binary", then the value of
<code>writeeol</code> 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:
<li><strong>unix</strong> -
The file is opened in binary mode, and newlines are written out as Line Feed
<li><strong>dos</strong> -
The file is opened in binary mode, and newlines are written out as Carriage
Return/Line Feed pairs.
<li><strong>mac</strong> -
The file is opened in binary mode, and newlines are written out as
Carriage Return characters.
<li><strong>text</strong> -
The file is opened in text mode, and no conversion takes place.
<li><strong>binary</strong> -
The file is opened in binary mode, and no conversion takes place.
<li><strong>same</strong> -
The value of the <code>readeol</code> 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.
<dt><a name="bufchars">bufchars, bc <em>(Number, buf)</em></a>
<br><a name="buflines">buflines, bl <em>(Number, buf)</em></a>
<dd>The <em>bufchars</em> and <em>buflines</em> 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.
<dt><a name="partiallastline">partiallastline, pll <em>(Boolean, buf)</em></a>
<dd>The <em>partiallastline</em> 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
<code>partiallastline</code> option to remind itself that when the buffer
is saved in binary mode, the last newline should be omitted.
Also, the <a href="elvisdm.html#hex">hex display mode</a> is smart enough
to hide the added newline when this option is set.
<dt><a name="errlines">errlines <em>(Number, buf)</em></a>
<dd>The <em>errlines</em> option is used to store the
number of lines that were in the buffer when the last
<a href="elvisex.html#make">:make</a> or <a href="elvisex.html#cc">:cc</a>
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.
<dt><a name="internal">internal <em>(Boolean, buf)</em></a>
<dd>The <em>internal</em> option indicates that Elvis
uses the buffer internally. Such buffers can't be deleted.
<dt><a name="putstyle">putstyle, ps <em>(One of, buf)</em></a>
<dd>The <em>putstyle</em> 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
<h2><a name="MOVE">6.4 Options that affect movement commands</a></h2>
<pre graphic>.---------------------.---------.--------.-----------------------------.
| <a href="#matchchar">matchchar, mc</a> | String | global | characters matched by % |
| <a href="#paragraphs">paragraphs, para</a> | String | buf | nroff paragraph commands |
| <a href="#sections">sections, sect</a> | String | buf | nroff section commands |
| <a href="#tweaksection">tweaksection, twks</a> | Boolean | global | allow text before { section?|
| <a href="#sentenceend">sentenceend, se</a> | String | global | punct at end of sentence |
| <a href="#sentencequote">sentencequote, sq</a> | String | global | punct allowed after se |
| <a href="#sentencegap">sentencegap, sg</a> | Number | global | spaces required after sq |
| <a href="#scroll">scroll, scr</a> | Number | win | scroll amount for ^D/^U |
<dt><a name="matchchar">matchchar, mc <em>(String, global)</em></a>
<dd>The <em>matchchar</em> option stores a list of matching character pairs,
for use by the <a href="elvisvi.html#pct">%</a> 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 <a href="elvisvi.html#pct">%</a>
command will try to guess whether it should search forward or backward.
The default value is <code>mc=[]{}()</code>, but you may wish to add
<code>:set mc=[]{}()&lt;&gt;\"\"</code> to your ~/.exrc (or ~/elvis.rc) file.
<p>If your copy of Elvis was compiled with text objects enabled
(i.e., if <a href="elvisex.html#calculate">:calc</a> <a href="elvisexp.html#feature">feature("textobj")</a> returns <code>true</code>)
then the <code>matchchar</code> option may also contain the names of
text objects.
The most useful example of this is probably <code>:set mc=[]{}()ax</code>
which allows the <a href="elvisvi.html#pct">%</a> command to bounce between
the endpoints of an XML tag pair.
<dt><a name="paragraphs">paragraphs, para <em>(String, buf)</em></a>
<br><a name="sections">sections, sect <em>(String, buf)</em></a>
<dd>The <em>paragraphs</em> option stores a list of
two-letter nroff paragraph commands. This list is used by the
<a href="elvisvi.html#ocur">{</a>
and <a href="elvisvi.html#ccur">}</a> movement commands.
Similarly, the <em>sections</em> option stores a list
of section commands, affecting the <a href="elvisvi.html#obra">[[</a> and
<a href="elvisvi.html#cbra">]]</a> commands.
Their defaults are <code>paragraphs="PPppIPLPQP"</code> and
<dt><a name="tweaksection">tweaksection, twks <em>(Boolean, global)</em></a>
<dd>In addition to the <a href="#sections">sections</a> option described above,
the <a href="elvisvi.html#obra">[[</a>, <a href="elvisvi.html#cbra">]]</a>,
and <a href="elvisvi.html#gd">gd</a> commands
also allow sections to start on a '{' line.
This is handy when editing C/C++/Java code.
Traditionally, the '{' had to be the first character on the line, but that
can be a problem because Perl and some C/C++/Java coding styles
like to put the '{' on the end of the function header line.
Even Elvis' own <a href="elvisex.html#alias">:alias</a> syntax uses this style.
To support this style, Elvis normally tweaks the definition of a section to
allow any <em>unindented</em> text to appear before the '{' character.
<p>The <code>tweaksection</code> option is normally on, so Elvis allows
unindented text before the '{'.
Turning it off will cause Elvis to use the traditional definition of sections.
<dt><a name="sentenceend">sentenceend, se <em>(String, global)</em></a>
<br><a name="sentencequote">sentencequote, sq <em>(String, global)</em></a>
<br><a name="sentencegap">sentencegap, sg <em>(Number, global)</em></a>
<dd>The <em>sentenceend, sentencequote,</em> and <em>sentencegap</em> options
all affect the <a href="elvisvi.html#open">(</a> and
<a href="elvisvi.html#close">)</a> 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 <code>sentenceend="?!.", sentencequote=")\"",</code>
and <code>sentencegap=2,</code> which meets the proposed POSIX specifications.
<dt><a name="scroll">scroll, scr <em>(Number, win)</em></a>
<dd>The <em>scroll</em> option indicates the number of
lines that the <a href="elvisvi.html#^U">^U</a> and
<a href="elvisvi.html#^D">^D</a> commands should scroll the screen by.
Its default value is 12.
<h2><a name="INPUT">6.5 Options that affect input mode</a></h2>
<pre graphic>.---------------------.---------.--------.-----------------------------.
| <a href="#autoindent">autoindent, ai</a> | Boolean | buf | auto-indent new text |
| <a href="#inputtab">inputtab, it</a> | One-Of | buf | input mode's (Tab) key |
| <a href="#smarttab">smarttab, sta</a> | Boolean | global | if indenting, (Tab) shifts |
| <a href="#completebinary">completebinary, cob</a> | Boolean | global | complete names of binaries? |
| <a href="#autotab">autotab, at</a> | Boolean | buf | allow autoindent to use '\t'|
| <a href="#tabstop">tabstop, ts</a> | Tab-List| buf | widths of tabstop columns |
| <a href="#shiftwidth">shiftwidth, sw</a> | Tab-List| buf | width used by &lt; and &gt; |
| <a href="#textwidth">textwidth, tw</a> | Number | buf | width for word-wrap, or 0 |
| <a href="#wrapmargin">wrapmargin, wm</a> | (weird) | win | set textwidth from right |
| <a href="#digraph">digraph, dig</a> | Boolean | global | allow X-backspace-Y entry |
| <a href="#cleantext">cleantext, ct</a> | Packed | global | Rules for erasing old text |
<dt><a name="autoindent">autoindent, ai <em>(Boolean, buf)</em></a>
<dd>Setting the <em>autoindent</em> 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.
<dt><a name="inputtab">inputtab, itab <em>(One-Of, buf)</em></a>
<dd>The <em>inputtab</em> option controls the behavior
of the <kbd>Tab</kbd> key. It can be set to one of the following values:
<li><strong>tab</strong> - insert an actual tab character. This is the
traditional vi behavior, and the default for user buffers.
<li><strong>spaces</strong> - insert enough space characters to look like a
tab character.
<li><strong>filename</strong> - attempt filename completion on the preceding
word. Normally this only completes the names of text files, but you can
set the <a href="#completebinary">completebinary</a> option to allow
binary file names to be completed too.
<li><strong>identifier</strong> - attempt tag name completion on the
preceding word. If the word is already complete, 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.
<li><strong>ex</strong> - a smarter version of filename completion,
it knows enough about ex command line syntax to avoid some tabbing
mistakes that the <code>filename</code> setting can make.
It can also complete ex command names, tag names, option names,
and option values.
This is the default for the <code>(Elvis ex history)</code> buffer,
which is used for entering in ex commands.
<dt><a name="smarttab">smarttab, sta <em>(Boolean, global)</em></a>
<dd>The <em>smarttab</em> option only affects the
behavior of the <kbd>Tab</kbd> key in input mode,
when the cursor is in the indentation portion of a line
-- before the first non-whitespace character.
If this option is true, then <kbd>Tab</kbd> is treated like <kbd>^T</kbd>,
so the line is shifted rightward by one shiftwidth.
By default this option is false, so the <kbd>Tab</kbd> key is treated normally
(in accordance with the <a href="#inputtab">inputtab</a> option).
<dt><a name="completebinary">completebinary, cob <em>(Boolean, global)</em></a>
<dd>The <em>completebinary</em> option controls
whether binary files are included in the list of possible filename completions.
The default setting is <code>nocompletebinary</code>, so binary files are
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
<code>f-o-o-TAB</code> will complete the "foo.c" name.
<dt><a name="autotab">autotab, at <em>(Boolean, buf)</em></a>
<dd>The <em>autotab</em> option affects the behavior of
the <a href="elvisvi.html#lt">&lt;</a> and <a href="elvisvi.html#gt">&gt;</a>
operator commands, and the <kbd>^D</kbd> and <kbd>^T</kbd> input mode
If autotab is true then Elvis will include tab characters in the indentation
if it is false then the indentation whitespace will consist entirely of space
By default, it is true.
<p>Note that if you start with a buffer which contains no tabs, and do a
"<code>:set inputtab=spaces noautotab</code>" then no amount of editing will
result in the buffer containing tabs... unless you get tricky with
<kbd>^V</kbd> or something.
<dt><a name="tabstop">tabstop, ts <em>(Tab-List, buf)</em></a>
<dd>The <em>tabstop</em> 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.
The value of this option is a list of tabstop widths, in which the last
number is repeated for longer lines.
(E.g., "2,6,8" would create tabstops at columns 3, 9, 17, 25, 33, etc.)
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 <a href="#shiftwidth">shiftwidth</a> and maybe
setting <a href="#inputtab">inputtab</a><code>=spaces</code> and
<a href="#smarttab">smarttab</a>.
<dt><a name="shiftwidth">shiftwidth, sw <em>(Tab-List, buf)</em></a>
<dd>The <em>shiftwidth</em> option indicates how far
left or right the <a href="elvisvi.html#lt">&lt;</a> and
<a href="elvisvi.html#gt">&gt;</a> operator commands
(and the <kbd>^D</kbd> and <kbd>^T</kbd> input mode keystrokes)
should shift the line of text.
This is used for adjusting the indentation of lines.
The value of this option is a list of tabstop widths, in which the last
number is repeated for longer lines.
For example, "2,6,8" would create shifting zones that start at columns
3, 9, 17, 25, 33, etc.
If a line is indented 3 spaces before a <kbd>&lt;</kbd> command (that's
1 space into the second shift zone), then it be indented 1 space after it
(1 space into the second shift zone); or after <kbd>&gt;</kbd> it would
be indented 9 spaces (1 space into the third shift zone).
The default value is "8".
<dt><a name="textwidth">textwidth, tw <em>(Number, buf)</em></a>
<dd>When editing a text file in "normal" display mode,
the <em>textwidth</em> 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.)
<dt><a name="wrapmargin">wrapmargin, wm <em>(Boolean, win)</em></a>
<dd>The <em>wrapmargin</em> option is provided for
backwards compatibility.
It allows you to set the <a href="#textwidth">textwidth</a> relative to the right edge of the window,
instead of the left edge.
This option's value is actually derived from the <code>textwidth</code> option's value
and the window's width (the <a href="#columns">columns</a> option),
so if you resize a window this option's value will appear to change to
correspond to the new width; textwidth will not change.
<dt><a name="digraph">digraph, dig <em>(Boolean, global)</em></a>
<dd><a href="elvisinp.html#DIG">Digraphs</a> allow
you to enter non-ASCII characters via a combination of two ASCII characters.
There are two ways to enter digraphs:
<kbd>^K&nbsp;X&nbsp;Y</kbd> and <kbd>X&nbsp;backspace&nbsp;Y</kbd>.
The second form can cause some confusion if you're not expecting it, so the
<em>digraph</em> 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.
<dt><a name="cleantext">cleantext, ct <em>(Packed, global)</em></a>
<dd>The <em>cleantext</em> option tells Elvis when it should remove old text.
All old text goes away when you exit <a href="elvisinp.html">input mode</a>,
but Elvis normally tries to keep old text until then, so you can see what
you've backspaced over.
Some people like that, and some don't.
If you prefer to have Elvis erase old text sooner,
then you'll want to change this option.
The value of <code>cleantext</code> is a comma-delimited list of rule names,
taken from the following table.
For example, "<code>:se cleantext=long,bs,ex</code>" causes backspaced-over characters
to be erased immediately, or at the start of a long change.
The default value is simply "long".
<td>Erase text when <kbd>&lt;Backspace&gt;</kbd>, <kbd>^H</kbd>, or
<kbd>^U</kbd> is pressed.
<td>Erase old text at the start of a short change
(the <a href="elvisvi.html#c">c</a> operator, or related commands).
A short change is one in which the old text doesn't contain any
<td>Erase old text at the start of a long change.
A long change is one in which the old text contains at least one
<td>Erase old text whenever a new keystroke is inserted into the text.
<td>Erase text when <kbd>&lt;Backspace&gt;</kbd>, <kbd>^H</kbd>, or
<kbd>^U</kbd> is pressed while entering a command line or
regular expression.
This is similar to <strong>bs</strong> but for command lines instead
of the main buffer.
<h2><a name="EXOPTS">6.6 Ex options</a></h2>
<pre graphic>.---------------------.---------.--------.-----------------------------.
| <a href="#prompt">prompt</a> | Boolean | global | issue ":" prompt in ex mode |
| <a href="#autoprint">autoprint, ap</a> | Boolean | global | print current line in ex |
| <a href="#report">report</a> | Number | global | minimum # lines to report |
| <a href="#optionwidth">optionwidth, ow</a> | Number | global | widths of ":set all" values |
| <a href="#filenamerules">filenamerules, fnr</a> | Packed | global | how to parse file names |
<dt><a name="prompt">prompt <em>(Boolean, global)</em></a>
<dd>The <em>prompt</em> 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.
<dt><a name="autoprint">autoprint, ap <em>(Boolean, global)</em></a>
<dd>The <em>autoprint</em> 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.
<dt><a name="report">report <em>(Number, global)</em></a>
<dd>The <em>report</em> 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 <code>report=0</code> then it won't report any changes,
or failed <a href="elvisex.html#:substitute">:s/old/new/</a> commands.
Its default value is 5, so small changes won't be reported but big ones will.
<dt><a name="optionwidth">optionwidth, ow <em>(Number, global)</em></a>
<dd><em>optionwidth</em> 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 <code>optionwidth=24</code>,
which guarantees that at least 3 columns can fit on an 80-character terminal, since 80/(24+2)=3.
Note that <code>optionwidth</code> has no effect on options that you explicitly
name in a ":set" command; for example, ":set <a href="#tags">tags</a>?" will
show you the entire tag path regardless of the value of
<dt><a name="filenamerules">filenamerules, fnr <em>(Packed, global)</em></a>
<dd>The <em>filenamerules</em> option controls the way file names are parsed
and processed.
Its value is a comma-delimited list of keywords, taken from the following
<pre graphic>
| dollar | $<var>VARIABLE</var> for environment vars |
| paren | (<var>expression</var>) evaluation |
| space | &lt;space&gt; acts as a file name delimiter |
| special | % for current file, and # for alternate file |
| tilde | ~ at the start of a file name |
| wildcard | wildcard matching |
The default value includes all of these keywords.
Users of Microsoft Windows may want to remove "space" from the value,
so that spaces can be used in filenames more easily.
You can still give multiple file names by separating them with &lt;Tab&gt;.
<h2><a name="WINDOW">6.7 Window statistics</a></h2>
<pre graphic>.---------------------.---------.--------.-----------------------------.
| <a href="#windowid">windowid, id</a> | Number | win | ID number of current window |
| <a href="#columns">columns, cols</a> | Number | win | width of window |
| <a href="#lines">lines, rows</a> | Number | win | height of window |
| <a href="#eventcounter">eventcounter, evct</a> | Number | win | when window was last used |
<dt><a name="windowid">windowid, id <em>(Number, win)</em></a>
<dd>The <em>windowid</em> option stores the ID number of
the current window.
These window IDs are listed by the <a href="elvisex.html#buffer">:buffer</a>
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
You can't change it.
<dt><a name="columns">columns, cols <em>(Number, win)</em></a>
<br><a name="lines">lines, rows <em>(Number, win)</em></a>
<dd>The <em>columns</em> and
<em>lines</em> options indicate the size of the window.
<dt><a name="eventcounter">eventcounter, evct <em>(Number, win)</em></a>
<dd>Internally, Elvis counts the number of events from the GUI.
If it is an input event (mouse click or key press), then the count value
is copied into the <em>eventcounter</em> option of the current window.
The <a href="elvisvi.html#^W^W">^W^W</a> command uses this option to
determine which two windows are the "most recently used", so it can toggle
between them.
<h2><a name="VIEW">6.8 Options affecting the appearance of text</a></h2>
<pre graphic>.---------------------.---------.--------.-----------------------------.
| <a href="#list">list, li</a> | Boolean | win | show markups, newlines, etc.|
| <a href="#listchars">listchars, lcs</a> | Packed | global | controls the "list" option |
| <a href="#showmarkups">showmarkups, smu</a> | Boolean | global | show markup at cursor |
| <a href="#bufdisplay">bufdisplay, bd</a> | String | buf | default display mode |
| <a href="#initialsyntax">initialsyntax, isyn</a> | Boolean | buf | start in "syntax" mode? |
| <a href="#prefersyntax">prefersyntax, psyn</a> | String | global | when to set initialsyntax |
| <a href="#display">display, mode</a> | String | win | name of current display mode|
| <a href="#number">number, nu</a> | Boolean | win | display line numbers |
| <a href="#ruler">ruler, ru</a> | Boolean | win | display cursor's line/column|
| <a href="#guidewidth">guidewidth, gw</a> | Tab-list| buf | draw vertical guide lines |
| <a href="#hlobject">hlobject, hlo</a> | String | buf | type of object to highlight |
| <a href="#hllayers">hllayers, hll</a> | Number | win | how many layers to highlight|
| <a href="#background">background, bg</a> | One-of | global | assumed background color |
| <a href="#folding">folding, fold</a> | Boolean | win | enable folding |
| <a href="#show">show</a> | String | global | what to show on bottom row |
| <a href="#state">state</a> | String | global | may be shown via <a href="#show">show</a> option|
| <a href="#showmatch">showmatch, sm</a> | Boolean | win | highlight matching parens |
| <a href="#showmode">showmode, smd</a> | Boolean | win | display the command state |
| <a href="#nonascii">nonascii, asc</a> | One-Of | global | how to display non-ascii |
| <a href="#showstack">showstack, sstk</a> | Boolean | win | display some debugging info |
<dt><a name="list">list, li <em>(Boolean, win)</em></a>
<dd>In the "normal" or "syntax" display modes, the <em>list</em>
option causes tabs and newlines to be visible, under the influence of
the <a href="#listchars">listchars</a> option.
In "html", "man", or "tex" mode, it causes all of the markups to be displayed.
<dt><a name="listchars">listchars, lcs <em>(Packed, global)</em></a>
<dd>This option is only effective if <code>feature("listchars")</code>
returns <code>true</code>.
It alters the effect of the <a href="#list">list</a> option, and can also
cause markers to be shown when sidescrolling is active if the
<a href="#wrap">wrap</a> option is off.
The value is a comma-delimited list of "<var>name</var>:<var>value</var>"
pairs, as follows:
<th align=left>NAME</th>
<th align=left>HOW THE VALUE IS USED</th>
<td valign=top>eol</td>
<td>Marks the end of the line.
If omitted, then there is no mark at the end of the line.
<td valign=top>tab</td>
<td>Alternate form of the tab character.
When used, tabs are expanded to their usual width.
If the tabstop is narrower than the value, then the value is truncated.
If the tabstop is wider, then the last character of the value is
repeated to fill the tabstop.
If omitted then tabs are shown as <code>^I</code>, and do not fill
the tabstop.
<tr valign=top>
<td>Appearance of trailing spaces at the end of the line.
Like <code>tab</code>,
this is truncated or stretched to be as wide as the spaces.
If omitted, then trailing spaces will simply be displayed as spaces.
<tr valign=top>
<td>Alternate form of the FormFeed character.
If omitted, FormFeed will be displayed as <code>^L</code>.
<tr valign=top>
<td>Altername form of the CarriageReturn character.
If omitted, CarriageReturn will be displayed as <code>^M</code>.
<tr valign=top>
<td>Alternate form of the Escape character.
If omitted, Escape will be displayed as <code>^[</code>.
<tr valign=top>
<td>Alternate form of the Backspace character.
If omitted, Backspace will be displayed as <code>^H</code>.
<tr valign=top>
<td>Alternate form of the Delete character.
If omitted, Delete will be displayed as <code>^?</code>.
<tr valign=top>
<td>Alternate form of the Null character.
If omitted, Null will be displayed as <code>^@</code>.
<tr valign=top>
<td>When <a href="#wrap">wrap</a> is off and you've scrolled horizontally,
this marker is displayed at the left edge of non-empty lines.
<tr valign=top>
<td>When <a href="#wrap">wrap</a> is off,
this marker is displayed at the right edge of lines that extend past
the edge of the window.
<tr valign=top>
<td>In the <a href="elvisdm.html#html">html</a>,
<a href="elvisdm.html#man">man</a>, and
<a href="elvisdm.html#tex">tex</a> display modes,
the <a href="#list">list</a> option will cause all markups to be
displayed if the <code>listchars</code> contains "markup".
This field has no ":<var>value</var>" component.
<p>A typical example is "<code>:set lcs=eol:[EOL],tab:[TAB]-</code>",
which makes the newline marker look like "[EOL]", and tabs look like "[TAB]---".
The default value is "eol:$" which makes the <code>list</code> option look
exactly like it does in the traditional vi.
<p>In the <a href="elvisdm.html#normal">normal</a> and
<a href="elvisdm.html#syntax">syntax</a> display modes, the <code>eol</code>
marker is displayed in the "<code>nontext</code>" typeface,
the <code>precedes</code> and <code>extends</code> markers are displayed in the
"<code>extends</code>" typeface, and
all others are displayed in the "<code>specialkey</code>" face.
In the <a href="elvisdm.html#html">html</a>, <a href="elvisdm.html#man">man</a>,
and <a href="elvisdm.html#tex">tex</a> display modes, markups are displayed
in the "<code>markup</code>" face.
You can adjust the appearance of these faces via the
<a href="elvisex.html#color">:color</a> command.
<p><strong>NOTE:</strong> You can scroll sideways by clicking on the
<code>precedes</code> and <code>extends</code> arrows,
but if you click too quickly then Elvis will see that as a double-click, and
try to perform a tag search on the name at the arrow location.
So if you click, click slowly.
<dt><a name="showmarkups">showmarkups, smu <em>(Boolean, global)</em></a>
<dd>In "html" or "man" mode, the <em>showmarkups</em>
option causes the markup at the cursor to be displayed, but leaves other markups
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.
<dt><a name="bufdisplay">bufdisplay, bd <em>(String, buf)</em></a>
<dd>Each buffer has a <em>bufdisplay</em> option,
which indicates that buffer's preferred display mode.
You should set bufdisplay to the name of a supported display mode:
<b>normal, syntax, html, man, tex,</b> or <b>hex.</b>
The compiled-in default is <b>normal</b> but the standard
<a href="elvisses.html#elvis.arf">elvis.arf</a> file tries to choose a
more clever default, based on the extension of the buffer's filename.
<p>For <b>syntax</b>, the exact syntax used normally depends on the filename's
You may also append a syntax name to explicitly select a syntax.
For example, the following will cause the buffer to be displayed using
C++ syntax:
<dt><a name="initialsyntax">initialsyntax, isyn <em>(Boolean, buf)</em></a>
<dd>Whenever a new window is created, or an existing window switches buffers,
its display mode is set to either "syntax" if <em>initialsyntax</em> is true,
or to the value of the <a href="#bufdisplay">bufdisplay</a> option otherwise.
This option is normally false, so that HTML documents are shown formatted,
but the default <a href="elvisses.html#elvis.arf">elvis.arf</a> file tries to
choose a better value, using the <a href="#prefersyntax">prefersyntax</a>
option for guidance.
The <a href="elvisex.html#mkexrc">:mkexrc</a> command never stores the value
of this option permanently.
This is intentional; you may want different buffers to have their
<code>initialsyntax</code> option set or cleared, depending on the type of
text in it, but the initialization file created by <code>:mkexrc</code>
only stores one value for each option.
You should set the <a href="#prefersyntax">prefersyntax</a> option instead.
<dt><a name="prefersyntax">prefersyntax, psyn <em>(String, global)</em></a>
<dd>The <em>prefersyntax</em> option has no hardcoded meaning,
but the default <a href="elvisses.html#elvis.arf">elvis.arf</a> file uses it
to turn <a href="#initialsyntax">initialsyntax</a> on or off.
You can set <code>prefersyntax</code> to one of the following:
<pre graphic>
| never | Never set; always start with formatted display modes |
| writable | Set for writable files |
| local | Set for writable files in the current directory |
| always | Always set; never start with formatted display modes |
<dt><a name="display">display, mode <em>(String, win)</em></a>
<dd>The <em>display</em> option indicates which display
mode the window is currently in.
You can't set this option directly;
you must use the <a href="elvisex.html#display">:display</a> command instead.
<dt><a name="number">number, nu <em>(Boolean, win)</em></a>
<dd>The <em>number</em> 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 <em>do</em> correspond to the <a href="#ruler">ruler</a>
and the visual <a href="elvisvi.html#G">G</a> command, though.
This option is false by default.
<dt><a name="ruler">ruler, ru <em>(Boolean, win)</em></a>
<dd>The <em>ruler</em> 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.
<dt><a name="guidewidth">guidewidth, gw <em>(Tab-list, buf)</em></a>
<dd>The <em>guidewidth</em> option causes vertical
lines to be added to the screen at specific tab positions.
Its value is a list of tab widths, similar to the <a href="#tabstop">tabstop</a>
and <a href="#shiftwidth">shiftwidth</a> options.
The lines can be hidden again by setting guidewidth to an empty list.
This option is only effective in the <a href="elvisdm.html#normal">normal</a>
and <a href="elvisdm.html#syntax">syntax</a> display modes.
In graphical user interfaces, the color of the guide lines can be set by
"<a href="elvisex.html#color">:color</a> <code>guide</code> <var>colorname</var>".
The following map causes the <kbd>&lt;F4&gt;</kbd> key to display a guide line
at the cursor column:
:map #4 :let gw=current("column")-1,columns^M</pre>
<dt><a name="hlobject">hlobject, hlo <em>(String, buf)</em></a>
<dd>The <em>hlobject</em> option allows you to specify the type of object
that you want Elvis to highlight around the cursor.
Its value will usually be the two-character name of a single type of
<a href="elvisvi.html#textobject">text object</a>, but you can also
set it to a whole list of objects
(optionally delimited via whitespace or commas)
to use for different layers of highlighting.
To highlight whole lines, instead of the exact extent of the text object,
you can put a "V" before the text object's name.
If you set <a href="#hllayers">hllayers</a> to more layers than you've defined
in this option, then the last object type will be repeated with increasing
The default value is "" which inhibits highlighting.
For highlighting to occur, you must set both <code>hlobject</code> to a valid
object name, and <a href="#hllayers">hllayers</a> to a non-zero value.
<pre graphic>
| Object list | What it highlights |
| hll=1 hlo="al" | the line containing the cursor |
| hll=1 hlo="Va{" | whole lines via brace-delimited blocks|
| hll=2 hlo="ix,ax" | XML tags and their contents |
(Larger values of <a href="#hllayers">hll (hllayers)</a> will do interesting
and useful things.)
I recommend that you get in the habit of enclosing the value in quotes.
Some characters used in text object names can have special meaning to Elvis.
One surprising example of this is "a{", which could otherwise confuse Elvis'
attempt to parse {...} blocks in ex scripts.
<dt><a name="hllayers">hllayers, hll <em>(Number, win)</em></a>
<dd>The <em>hllayers</em> option specifies how many objects (as defined by the
<a href="#hlobject">hlobject</a> option) should be highlighted around the
The default value is 0, which disables highlighting.
Changing it to 1 (and setting <a href="#hlobject">hlobject</a> to the name of
a text object) will cause the object containing the cursor to be highlighted.
Larger values will cause more objects around the cursor to be highlighted.
The outermost layer will use the highlighting defined by the font "hlobject1",
the next layer will use "hlobject2", and so on; you can use the
<a href="elvisex.html#color">:color</a> command to set these up.
Also, for the <a href="elvisgui.html#x11">x11</a> and
<a href="elvisgui.html#windows">windows</a> user interfaces you can run
"<a href="elvistip.html#load">:load</a> <tt>shade</tt>"
to set up all of the "hlobject<var>n</var>" faces with
shades of gray background.
<dt><a name="background">background, bg <em>(One of, global)</em></a>
<dd>The <em>background</em> option does not change the background color!
It may affect the choices that Elvis makes for foreground colors though,
if <strong>all</strong> of the following are true:
<li>You're using a non-graphical user interface such as the
the <a href="elvisgui.html#termcap">termcap</a> interface.
For graphical interfaces, Elvis knows the real background color and makes
its choices from that.
<li>You have not explicitly set the normal background color.
In other words, your background should be the terminal's default background
<li>You have configured extra possible foreground colors by using the
"<code>or</code> <var>color</var>" clause in a
<a href="elvisex.html#color">:color</a> command.
If you haven't given Elvis a list of foreground colors to choose from,
then there is no choice to be made.
The legal values are "light" and "dark".
The default value is taken from the $ELVISBG environment variable.
If you haven't set that variable, then Elvis will try to guess the appropriate
default for your type of terminal.
In <a href="elvisexp.html">expressions</a>, you can use
<a href="elvisexp.html#current">current("background")</a> to obtain a
"light" or "dark" judgement for the actual normal background.
This works by examining the color table so it is reliable, unlike the
<code>background</code> option.
<dt><a name="folding">folding, fold <em>(Boolean, win)</em></a>
<dd><a href="elvisex.html#FOLD">Folded regions</a> are associated with
buffers, not with windows.
One consequence of this is that if you're viewing the same buffer in multiple
windows and fold some text in one of them, it'll normally be folded in the
other windows too.
The <em>folding</em> window option gives you a way to reveal
folded text in one window, while leaving it folded in another.
It is normally true, to allow folding in the window.
Setting it to false will disable folding in the window.
<dt><a name="show">show <em>(String, global)</em></a>
<dd>This option tells Elvis what to show at the bottom of a window,
whenever it has nothing better to show there such as error messages.
Its value is a list of keywords, and optionally some slash characters.
Each keyword causes Elvis to add one more piece of information to the
bottom row.
The keywords and their meanings are:
<pre graphic>
| file | value of the current buffer's <a href="#filename">filename</a> or <a href="#bufname">bufname</a> |
| tag | name of <a href="elvistag.html">tag</a> defined at or above the current line |
| cmd | characters of a partially-entered vi command |
| face | name of text face at cursor (as used by <a href="elvisex.html#color">:color</a>) |
| link | destination of an <a href="elvisdm.html#html">HTML</a> link at the cursor position |
| spell | suggested corrections for a <a href="elvistip.html#SPELL">misspelled word</a> |
| region | comment of current region (as used by <a href="elvisex.html#region">:region</a>) |
| state | value of the <a href="#state">state</a> option |
<p>Many of the above keywords won't always generate output.
For example, "tag" won't generate output if the current file doesn't define
any tags, or if the cursor is positioned before the first tag definition.
Also, many of the above keywords depend on features which can be disabled
at compile-time.
<p>Using the "tag" keyword, by the way, may cause Elvis to load files more
This is because it must locate every tag definition in that file.
The version of ctags distributed with Elvis
(usually installed as "elvtags" on Unix/Linux systems) 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.
<p>The "spell" keyword only works if the <a href="#spell">spell</a> option
is set.
Also, it works better if the whole spelling dictionary has
been loaded into memory, so you should either set the
<a href="#spellautoload">spellautoload</a> option or
explicitly invoke the <a href="elvisex.html#wordfile">:wordfile</a>
command if you want to use it.
<p>If the value contains slashes, then Elvis will stop looking for keywords
at the first slash after a keyword which generated information.
Or to put it another way, slashes divide the <code>show</code> value into
segments, and Elvis will only show the first segment which actually has
something to show you.
<p>The default value is "spell/tag,region".
This causes Elvis to display spelling suggestions if the cursor is on a
misspelled word, or the tag name and region comment otherwise.
<dt><a name="state">state <em>(String, global)</em></a>
<dd>The value of the <em>state</em> option may be shown at the bottom of the
screen if the <a href="#show">show</a> option contains the keyword "state".
This is the only thing that <code>state</code> is used for.
Its default value is "".
<dt><a name="showmatch">showmatch, sm <em>(Boolean, win)</em></a>
<dd>The <em>showmatch</em> option helps you locate
matching parentheses.
When you're in input mode, and you type a <kbd>), ],</kbd> or <kbd>}</kbd>
character, Elvis will cause the matching <kbd>(, [,</kbd> or <kbd>{</kbd>
character to be highlighted on the screen.
This option is false by default.
<dt><a name="showmode">showmode, smd <em>(Boolean, win)</em></a>
<dd>The <em>showmode</em> 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.
<dt><a name="nonascii">nonascii, asc <em>(One-Of, global)</em></a>
<dd>The <em>nonascii</em> option tells Elvis how to
display characters 0x80 through 0xff.
It can have one of the following values:
<pre graphic>
| 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 <code>nonascii</code> is "most", because that is the correct
value for the Latin-1 symbol set.
<dt><a name="showstack">showstack, sstk <em>(Boolean, win)</em></a>
<dd>The <em>showstack</em> 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.
<h2><a name="MODE">6.9 Options for a particular display mode</a></h2>
<pre graphic>.---------------------.---------.--------.-----------------------------.
| <a href="#includepath">includepath, inc</a> | String | syntax | where to find #include files|
<dt><a name="includepath">includepath, inc <em>(String, syntax)</em></a>
<dd>The <em>includepath</em> 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 <a href="elvisvi.html#^cbra">^]</a>, and have Elvis load the indicated
header file.
The default value is taken from the INCLUDE environment variable if set,
or an OS-dependent value otherwise.
<h2><a name="SPELL">6.10 Spell-checking options</a></h2>
<pre graphic>.---------------------.---------.--------.-----------------------------.
| <a href="#spell">spell, sp</a> | Boolean | buf | highlight misspelled words |
| <a href="#spelldict">spelldict, spd</a> | String | global | name of dictionary file |
| <a href="#spellautoload">spellautoload, sal</a> | Boolean | global | load whole dict when needed |
| <a href="#spellsuffix">spellsuffix, sps</a> | String | global | list of suffixes |
These options all pertain to the spell-checking feature.
For more information, see the discussion in the
<a href="elvistip.html#SPELL">Tips</a> chapter.
Also see the <a href="#show">show</a> option's "spell" keyword to show
alternative spellings at the bottom of the window, and how that feature
relates to the <a href="#spellautoload">spellautoload</a> option.
<dt><a name="spell">spell, sp <em>(Boolean, buffer)</em></a>
<dd>When set, the <em>spell</em> option causes misspelled words to be
highlighted via the "spell" face.
You can adjust the highlighting style via the "<a href="elvisex.html#color">:color spell ...</a>" command.
The default is <strong>nospell</strong>, which disables all spell-checking.
<dt><a name="spelldict">spelldict, spd <em>(String, global)</em></a>
<dd>The <em>spelldict</em> option should be set to the name of a file
which contains a sorted list of natural-language words, one per line.
The spell-checker will then look up words in that file as needed.
<p>The default value is "", which prevents the use of any such file.
However, the initialization script tries to locate a suitable file.
Many Unix systems have a <strong>/usr/dict/words</strong> file which works well.
If you set <code>spelldict</code> to the name of a non-existent or unreadable
file, then Elvis will reset it "".
Elvis reads that file in a case-insensitive manner.
There are two consequences of this.
First, the file should be sorted case-insensitively
(like "sort -f" on POSIX systems).
Second, if a word is capitalized in the dictionary file, then Elvis will
accept a non-capitalized version of the same word in the buffer as being
correctly spelled.
The only way to add case-sensitive words to the dictionary is via the
<a href="elvisex.html#words">:words</a> command.
<dt><a name="spellautoload">spellautoload, sal <em>(Boolean, global)</em></a>
<dd>The <em>spellautoload</em> option causes the whole spelling dictionary
(identified by <a href="#spelldict">spelldict</a> option)
to be loaded into memory the first time you call the
<a href="elvisexp.html#spell">spell()</a> function,
or move the cursor onto a misspelled word while the
<a href="#show">show</a> option contains "spell".
This is desirable because Elvis will only suggest words that have been loaded,
so if you haven't loaded the whole dictionary then it won't be able to make
very many suggestions.
The <code>spellautoload</code> option is on by default.
<p>Loading the whole dictionary takes some time (usually about 1 second)
and memory (about 1 megabyte) so you may prefer to
turn off <code>spellautoload</code> to avoid this.
You could then explicitly load it via the
<a href="elvisex.html#wordfile">:wordfile</a> command, if you want.
<dt><a name="spellsuffix">spellsuffix, sps <em>(String, global)</em></a>
<dd>This stores a list of possible suffixes for natural-language words.
When looking up a word, if Elvis is unable to find an exact match then it
will check to see if the word ends with one of the suffixes listed here;
if so, it'll remove the suffix and try the resulting word.
<p>The value is a string, interpreted as a space-delimited list
of suffixes.
Each suffix can be either a simple suffix to remove, or an expression
of the form "<var>suffix</var>=<var>replacement</var>" to replace the suffix
with some other text.
For example, <code>spellsuffix="ies=y"</code> would be able to
convert "flies" into the root word "fly".
<p>One important detail of the <code>spellsuffix</code> option is that it
is only used the first time Elvis encounters a word.
After looking up a word once, Elvis the simply remembers the result.
Consequently, changing the <code>spellsuffix</code> option won't cause any
words that are currently marked as misspelled to be rechecked and marked as
<p>Another quirk of <code>spellsuffix</code> is that it doesn't work on
case-sensitive root words that you add via the
<a href="elvisex.html#words">:words</a> command.
This is a low-priority bug which I expect to fix eventually.
Until then, you can simply add both the root word and suffixed word to
your personal dictionary.
<p>The compiled-in default value is "", but the default configuration files
(mostly the <a href="elvisses.html#elvis.spe">elvis.spe</a> file)
change that to something that works well for English text.
<h2><a name="MSG">6.11 Messages</a></h2>
<pre graphic>.---------------------.---------.--------.-----------------------------.
| <a href="#terse">terse, te</a> | Boolean | global | don't translate messages |
| <a href="#verbose">verbose</a> | Numeric | global | give more status messages |
| <a href="#errorbells">errorbells, eb</a> | Boolean | global | ring bell for error message |
| <a href="#warningbells">warningbells, wb</a> | Boolean | global | ring bell for warning msg |
| <a href="#flash">flash, vbell</a> | Boolean | global | substitute flash for bell |
<dt><a name="terse">terse, te <em>(Boolean, global)</em></a>
<dd>The <em>terse</em> option indicates whether Elvis should
attempt to translate messages via the
<a href="elvismsg.html#elvis.msg">elvis.msg</a> 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
"<var>terse</var>:<var>verbose</var>" and if found it'll use the verbose
version instead.
By default, terse is false.
<dt><a name="verbose">verbose <em>(Boolean, global)</em></a>
<dd>The <em>verbose</em> option has nothing to do with
the terse option.
Instead, it indicates the number of <strong>-V</strong> 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 <code>verbose</code>
and automatically writes status messages when <code>verbose</code> is set to
a high enough level.
Values normally range from 0 (no extra output) to 9 (maximum output).
<dt><a name="errorbells">errorbells, eb <em>(Boolean, global)</em></a>
<br><a name="warningbells">warningbells, wb <em>(Boolean, global)</em></a>
<dd>The <em>errorbells</em> and <em>warningbells</em> options cause the
terminal's bell to ring when an error message or warning message is generated,
By default the errorbells option is true, and the warningbells option is
<dt><a name="flash">flash, vbell <em>(Boolean, global)</em></a>
<dd>Setting the <em>flash</em> 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.
<h2><a name="WORDS">6.12 Words</a></h2>
<pre graphic>.---------------------.---------.--------.-----------------------------.
| <a href="#true">true, True</a> | String | global | locale's True value |
| <a href="#false">false, False</a> | String | global | locale's False value |
| <a href="#submit">submit, Submit</a> | String | x11 | locale's Submit label |
| <a href="#cancel">cancel, Cancel</a> | String | x11 | locale's Cancel label |
| <a href="#help">help, Help</a> | String | x11 | locale's Help label |
These options store words, which are translated via the
<a href="elvismsg.html#elvis.msg">elvis.msg</a> file when Elvis starts up.
The default versions of all of them are their capitalized English names.
<dt><a name="true">true, True <em>(String, global)</em></a>
<br><a name="false">false, False <em>(String, global)</em></a>
<dd>The <em>true</em> and <em>false</em> options exist primarily to allow the
english words <strong>true</strong> and <strong>false</strong> to be used
in expressions to represent Boolean literals. Also, the value of
<code>false</code> 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
<code>true</code> option's value.) A Boolean option will return the value
of either the <code>true</code> or <code>false</code> option, as appropriate.
<dt><a name="submit">submit, Submit <em>(String, global)</em></a>
<br><a name="cancel">cancel, Cancel <em>(String, global)</em></a>
<dd>If you're using the "x11" user interface, then values of the <em>submit</em>
and <em>cancel</em> 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 <code>true</code> and
<code>false</code> options.
<dt><a name="help">help, Help <em>(String, global)</em></a>
<dd>Currently the <em>help</em> 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 <code>help</code> option will allow Elvis to recognize the "Help" menu.
<h2><a name="GUI">6.13 Options for a particular user interface</a></h2>
<pre graphic>.---------------------.---------.--------.-----------------------------.
| <a href="#term">term, ttytype</a> | String | termcap| terminal's termcap entry |
| <a href="#ttyrows">ttyrows, ttylines</a> | Number | termcap| height of screen |
| <a href="#ttycolumns">ttycolumns, ttycols</a> | Number | termcap| width of screen |
| <a href="#ttyunderline">ttyunderline, ttyu</a> | Boolean | termcap| okay to mix color &amp; underln |
| <a href="#ttyitalic">ttyitalic, ttyi</a> | Boolean | termcap| okay to use "dim" for italic|
| <a href="#ttyunderline">ttywrap, ttyw</a> | Boolean | termcap| trust termcap's line wrap |
| <a href="#codepage">codepage, cp</a> | Number | win32 | console character set |
| <a href="#scrollbar">scrollbar, sb</a> | Boolean | (gui) | enable the scrollbar |
| <a href="#toolbar">toolbar, tb</a> | Boolean | (gui) | enable the toolbar |
| <a href="#statusbar">statusbar, stb</a> | Boolean | (gui) | enable the statusbar |
| <a href="#scrollwheelspeed">scrollwheelspeed,sws</a>| Number | (gui) | adjust speed of scroll wheel|
| <a href="#scrollbgimage">scrollbgimage, sbi</a> | Boolean | (gui) | scroll background image |
| <a href="#font">font, fnt</a> | String | (gui) | base font |
| <a href="#iconimage">iconimage, ii</a> | String | (gui) | window icon |
| <a href="#menubar">menubar, mb</a> | Boolean | windows| enable the menubar |
| <a href="#titleformat">titleformat, title</a> | Boolean | windows| window title |
| <a href="#boldfont">boldfont, xfb</a> | String | x11 | name of bold font |
| <a href="#italicfont">italicfont, xfi</a> | String | x11 | name of italic font |
| <a href="#controlfont">controlfont, xfc</a> | String | x11 | name of toolbar font |
| <a href="#xencoding">xencoding, xe</a> | String | x11 | registry &amp; encoding of fonts|
| <a href="#scrollbarleft">scrollbarleft, xsl</a> | Boolean | x11 | enable scrollbar on side |
| <a href="#scrollbarwidth">scrollbarwidth, xsw</a> | Number | x11 | size of scrollbar, in pixels|
| <a href="#scrollbartime">scrollbartime, xst</a> | Number | x11 | delay for scrollbar repeat |
| <a href="#borderwidth">borderwidth, xbw</a> | Number | x11 | size of text area's border |
| <a href="#dblclicktime">dblclicktime, xdct</a> | Number | x11 | double-click speed, 1/10 Sec|
| <a href="#blinktime">blinktime, xbt</a> | Number | x11 | cursor blink rate, 1/10 Sec |
| <a href="#textcursor">textcursor, tc</a> | Number | x11 | one of hollow, opaque, xor |
| <a href="#synccursor">synccursor, xsync</a> | Boolean | x11 | avoid partial characters |
| <a href="#xrows">xrows, xlines</a> | Number | x11 | height of new windows |
| <a href="#xcolumns">xcolumns, xcols</a> | Number | x11 | width of new windows |
| <a href="#firstx">firstx, xpos</a> | Number | x11 | horiz. position of first win|
| <a href="#firsty">firsty, ypos</a> | Number | x11 | vert. position of first win |
| <a href="#stagger">stagger</a> | Number | x11 | offset for next new window |
| <a href="#icon">icon</a> | Boolean | x11 | use the built-in icon? |
| <a href="#iconic">iconic</a> | Boolean | x11 | windows start out iconified |
| <a href="#stopshell">stopshell, ssh</a> | String | x11 | interactive shell command |
| <a href="#autoiconify">autoiconify, aic</a> | Boolean | x11 | iconify old window |
| <a href="#altkey">altkey, metakey</a> | One of | x11 | effect of the Alt key |
| <a href="#focusnew">focusnew, fn</a> | Boolean | x11 | force focus into new window |
| <a href="#warpto">warpto, wt</a> | One of | x11 | ^W^W forces pointer movement|
| <a href="#warpback">warpback, xwb</a> | Boolean | x11 | upon exit, point to xterm |
| <a href="#outlinemono">outlinemono, om</a> | Number | x11 | char outlining for X11-mono |
| <a href="#antialias">antialias, aa</a> | Boolean | x11 | use antialiased fonts |
| <a href="#aasqueeze">aasqueeze, aas</a> | Boolean | x11 | reduce the gap between lines|
| <a href="#secret">secret</a> | Number | x11 | identifies trusted clients |
<h3>6.13.1 Termcap options</h3>
<dt><a name="term">term, ttytype <em>(String, termcap)</em></a>
<br><a name="ttyrows">ttyrows, ttylines <em>(Number, termcap)</em></a>
<br><a name="ttycolumns">ttycolumns, ttycols <em>(Number, termcap)</em></a>
<dd>The <em>term, ttyrows,</em> and <em>ttycolumns</em> options are only present
if you're using the <a href="elvisgui.html#termcap">termcap</a> user interface.
They indicate the name of the termcap entry being used and the size of the screen.
<p>The value of <code>term</code> is taken from the <code>$TERM</code>
environment variable.
<code>ttyrows</code> and <code>ttycolumns</code> are set from the
<code>$LINES</code> and <code>$COLUMNS</code> environment variables,
or from the stty "rows" and "columns" settings (or other OS-specific
configuration settings), or, as a last resort, from the termcap/terminfo
<dt><a name="ttyunderline">ttyunderline, ttyu <em>(Boolean, termcap)</em></a>
<dd>The <em>ttyunderline</em> option is only present if you're using the
<a href="elvisgui.html#termcap">termcap</a> interface.
It indicates whether it is safe to try underlining text when colors
have been assigned to fonts.
The <code>ttyunderline</code> option is true by default, which allows Elvis
to use underlining without restrictions of any kind.
<p>But on PC text screens, any attempt to underline is likely to interfere
with the use of background colors, because PC video hardware traditionally
uses the same bit for underlining (on monochrome screens) as it does for a
red background (on color screens).
If underlining causes problems for you, try turning off
This will have two main effects:
<li>If you've set the background color via the
"<a href="elvisex.html#color">:color</a>" command,
then Elvis won't use underlining at all.
<li>To draw the borders between windows, Elvis will convert any spaces on the
bottom row of a window into underscore characters.
(With ttyunderline set, Elvis normally draws the bottom row with the
underlining turned on.)
<p>Note that if you want to totally disable the underline escape sequence
without setting a background color, you can simply set the background to
"transparent", like this:
:set nottyunderline
:color normal on transparent</pre>
<dt><a name="ttyitalic">ttyitalic, ttyi <em>(Boolean, termcap)</em></a>
<dd>Elvis normally displays italic text using the "dim" attribute, but
standard PC VGA hardware can't do that very well.
The Linux console driver implements it by using gray, which is unfortunate
if you want to mix colors and italics.
The <em>ttyitalic</em> option gives you a way to disable this,
so you can see colors on the screen, while still allowing the
<a href="elvisex.html#lpr">:lpr</a> command to print italics.
This option is true by default,
but the <a href="elvisses.html#elvis.ini">elvis.ini</a> file turns it off
for the linux console.
<p>If your terminal doesn't implement half-bright (via the
:mh=: termcap field or <code>dim</code> terminfo field), then Elvis
uses underlining to represent italics.
Underlining is influenced by the <a href="#ttyunderline">ttyunderline</a>
<dt><a name="ttywrap">ttywrap, ttyw <em>(Boolean, termcap)</em></a>
<dd>Elvis normally tries to be smart about line-wrap, more so than most
But this only works right if the terminal's termcap/terminfo description is
By default, <em>ttywrap</em> is on which enables Elvis' normal line-wrap
intelligence, but if your screen gets messed up by long lines then you might
try turning it off so Elvis will make no assumptions about the terminal's
line-wrap behavior.
<dt><a name="codepage">codepage, cpg <em>(Number, win32)</em></a>
<dd>The <em>codepage</em> option only exists in the Win32 version with the
<a href="elvisgui.html#termcap">termcap</a> 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
<a href="elvisinp.html#DIG">digraph table,</a>
or Elvis' idea of which <a href="#nonascii">non-ASCII</a> 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.
<h3>6.13.2 Options common to Windows and X11</h3>
<dt><a name="scrollbar">scrollbar, sb <em>(Boolean, windows or x11)</em></a>
<br><a name="toolbar">toolbar, tb <em>(Boolean, windows or x11)</em></a>
<br><a name="statusbar">statusbar, xstat <em>(Boolean, windows or x11)</em></a>
<dd>The <em>scrollbar</em>, <em>toolbar</em>, and <em>statusbar</em> options
indicate whether the scrollbar, toolbar, and statusbar should be visible,
By default, all are visible.
<dt><a name="scrollwheelspeed">scrollwheelspeed,sws <em>(Number, windows or x11)</em></a>
<dd>The <em>scrollwheelspeed</em> option controls the speed and direction of
scrolling when you move the mouse's scroll wheel.
Its value can be any integer from -999 to 999, indicating the number of
lines to scroll for each detent of wheel movement.
The default is 2.
(To configure X11 to support wheel mice see the
<a href="howto.html#scrollwheel">How to</a> section of the manual.)
<dt><a name="scrollbgimage">scrollbgimage, sbi <em>(Boolean, windows or x11)</em></a>
<dd>If you're using a background image, then the <em>scrollbgimage</em> option
will indicate whether the image should scroll when the text scrolls.
The default is true since that is usually more efficient,
but the choice is a personal one.
<dt><a name="font">font <em>(String, windows or x11)</em></a>
<dd>The <em>font</em> option stores the name of the base font.
Both windows and x11 allow you to set a font by giving the name of the font,
followed by an asterisk and a point size, such as "courier*14".
Because Elvis only supports fixed-pitch text,
you should only choose fixed-pitch fonts.
<p>In Windows the easiest way to set the font is via the "Options-&gt;Font"
menu item.
The default is "Courier new*10" in Windows.
<p>In X11, the default is "" which is interpreted as meaning "fixed".
("fixed" is usually an alias for a small fixed-pitch font.)
The <a href="elvisses.html#elvis.ini">elvis.ini</a> script tries to choose
an appropriate sized Courier font, though.
You can also choose one yourself using the <code>:courier</code> alias.
In the "x11" interface, changing <code>font</code> has the side-effect of
resetting the <a href="#boldfont">boldfont</a> and
<a href="#italicfont">italicfont</a> options.
In addition to the "courier*14" notation for font names, the x11 interface
also allows you to append "b" or "i" for bold or italic versions of the font.
See also the <a href="#xencoding">xencoding</a> option.
<dt><a name="iconimage">iconimage, ii <em>(String, windows or x11)</em></a>
<dd>The <em>iconimage</em> option controls the icon used for Elvis windows.
The default is an empty string, which causes a built-in icon to be used.
Other possibilities include setting it to the name of a *.xpm file, or
the basenames of icons in the <em>data/icons/</em> directory.
For example, ":set ii=elvis2" looks nice.
<h3>6.13.3 Windows options</h3>
<dt><a name="menubar">menubar, mbar <em>(Boolean, windows)</em></a>
<dd>The <em>menubar</em> option indicates whether the menu bar should be visible.
By default, it is visible.
<dt><a name="titleformat">titleformat, title <em>(String, windows)</em></a>
<dd>The <em>titleformat</em> option is used to control the format of the
window's title.
This is a value is an expression using
the <a href="elvisexp.html#SIMPLER">simpler expression syntax</a> with
$1 set to the current file name.
The default value is "$1", so the default window title is simply the
file name.
Another possible value would be <code>titleformat="(dirfile($1)) - Elvis"</code>
which shows the file name without any leading directory name, and then
appends "- Elvis" to the end.
Window titles are only adjusted when you switch to a different file by running
a <a href="elvisex.html#edit">:e <var>file</var></a> command
or something similar.
Merely changing the <code>titleformat</code> option will not have any
immediate effect on the window's title.
If you set a <code>titleformat</code> in your elvis.rc file, then its
value will affect all windows that are created later.
This is the most useful place to change <code>titleformat</code>.
See the <a href="elvisex.html#mkexrc">:mkexrc</a> command.
<h3>6.13.4 X11 options</h3>
<dt><a name="boldfont">boldfont, xfb <em>(String, x11)</em></a>
<br><a name="italicfont">italicfont, xfi <em>(String, x11)</em></a>
<dd>The <em>boldfont</em> and <em>italicfont</em> options
control the X fonts used for displaying bold and italic text.
Typically, the <a href="elvisses.html#elvis.ini">elvis.ini</a>
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 both default to an empty string;
this is a special case which causes Elvis to derive the bold and italic
fonts from the normal <a href="#font">font</a>.
<dt><a name="controlfont">controlfont, xfc <em>(String, x11)</em></a>
<dd>The <em>controlfont</em> 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.
<dt><a name="xencoding">xencoding, xe <em>(String, x11)</em></a>
<dd>When font names are given in "<var>fontname</var>*<var>size</var>" notation,
Elvis uses the value of this option to supply the registry and encoding for
the font selection.
The default value is "*-*" which allows Elvis to use fonts from any registry
and encoding.
Other popular choices are likely to be "iso8859-1" for Latin-1 symbol sets,
and "iso8859-15" for Latin-1 with a euro symbol in place of the generic
currency symbol, at 0xa4.
When anti-aliasing is enabled, this option should still work but it doesn't.
I believe this is a bug in the Xft library.
<dt><a name="antialias">antialias, aa <em>(Boolean, x11)</em></a>
<dd>This option only exists if Elvis was compiled with FEATURE_XFT defined
(i.e., <a href="elvisexp.html#feature">feature("xft")</a> returns <code>true</code>).
It indicates whether antialiased fonts should be used.
Its default value is true, which allows antialiased fonts to be used
when available.
Turning it off (<code>:set noantialias</code>) will use the standard
bitmapped fonts, which are usually uglier but can be drawn faster.
<dt><a name="aasqueeze">aasqueeze, aas <em>(Number, x11)</em></a>
<dd>Some of the Xft antialiased fonts have very large gaps between lines.
This is especially true for the Courier font, which looks almost doublespaced.
Since programmers like to see as many lines of their code as possible,
I decided to create this option for trimming down gap.
The default value is 4, which reduces the height of each text row by
4 raster lines.
You can set it to any value from 0 to 10.
<dt><a name="scrollbarleft">scrollbarleft, xsl <em>(Boolean, x11)</em></a>
<dd>The <em>scrollbarleft</em> option determines 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.
<dt><a name="scrollbarwidth">scrollbarwidth, xsw <em>(Number, x11)</em></a>
<dd>The <em>scrollbarwidth</em> option controls the size of the x11 scrollbar.
The default value is 14 pixels, and the allowed range is 5 to 40 pixels.
<dt><a name="scrollbartime">scrollbartime, xst <em>(Number, x11)</em></a>
<dd>The scrollbar buttons automatically repeat if you hold a mouse button down
<em>scrollbartime</em> tenths of a second.
The default is 4 tenths of a second.
<dt><a name="borderwidth">borderwidth, xbw <em>(Number, x11)</em></a>
<dd>The main text area of a window looks better when the characters aren't
drawn immediately adjacent to the edge.
The <em>borderwidth</em> 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.
<dt><a name="dblclicktime">dblclicktime, xdct <em>(Number, x11)</em></a>
<dd>The <em>dblclicktime</em> 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.
<dt><a name="blinktime">blinktime, xbt <em>(Number, x11)</em></a>
<dd>The <em>blinktime</em> 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.
<dt><a name="textcursor">textcursor, tc <em>(Number, x11)</em></a>
<dd>The <em>textcursor</em> option controls
the way the block text cursor is drawn.
It can be <strong>xor, hollow,</strong> or <strong>opaque.</strong>
The default is <strong>xor</strong>, 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 <strong>hollow</strong> 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 <strong>opaque</strong> cursor style draws a filled rectangle, which is
easier to locate but you can only see the underlying character between blinks.
<dt><a name="synccursor">synccursor, xsync <em>(Boolean, x11)</em></a>
<dd>This option attempts to work around an apparent bug in some versions
of XFree86 which causes partial characters to be erased when the text cursor
moves rapidly.
If you see partial characters when you do things like use the mouse to
select text, then you should set <em>synccursor</em> to fix it.
(This bug is known to occur on XFree86 4.003 on a 3dfx Voodoo3 video card.)
<dt><a name="xrows">xrows, xlines <em>(Number, x11)</em></a>
<br><a name="xcolumns">xcolumns, xcols <em>(Number, x11)</em></a>
<dd>The <em>xrows</em> and <em>xcolumns</em> options control the
initial size of windows.
They default to 34 and 80, respectively, and can also be set via the
<b>-geometry</b> command-line flag.
After a window has been created, you can use your window manager to
resize the window.
<dt><a name="firstx">firstx, xpos <em>(Number, x11)</em></a>
<br><a name="firsty">firsty, ypos <em>(Number, x11)</em></a>
<br><a name="stagger">stagger <em>(Number, x11)</em></a>
<dd>The <em>firstx</em> and <em>firsty</em> 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 <b>-geometry</b> command-line flag can be used to set these options.
After the first window has been created, if the <em>stagger</em> 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 <em>stagger</em> is zero,
then Elvis won't specify a position for the new windows, so the window manager
can choose the location itself.
<dt><a name="icon">icon <em>(Boolean, x11)</em></a>
<dd>The <em>icon</em> option can only be set in an initialization file
such as <a href="elvisses.html#elvis.ini">elvis.ini</a> 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
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
<a href="elvisses.html#elvis.ini">elvis.ini</a> file.
<dt><a name="iconic">iconic <em>(Boolean, x11)</em></a>
<dd>The <em>iconic</em> option tells Elvis whether new windows should
be created in the iconfied state.
The default is <code>noiconic</code>.
<dt><a name="stopshell">stopshell, ssh <em>(String, x11)</em></a>
<dd>The <em>stopshell</em> option stores a command which runs an interactive
It is used for the <a href="elvisex.html#shell">:shell</a> and
<a href="elvisex.html#stop">:stop</a> ex commands, and the
<a href="elvisvi.html#^Z">^Z</a> visual command.
Normally, this is set to "xterm &amp;" so you get a shell in a window.
The "&amp;" at the end of the command allows Elvis to continue responding to
user input while the shell is running.
<dt><a name="autoiconify">autoiconify, aic <em>(Boolean, x11)</em></a>
<dd>When the <a href="elvisvi.html#^W">^W^W</a> visual command switches
keyboard control to an X11 window which as been iconified, Elvis automatically
deiconifies it.
When it does this, if the <em>autoiconify</em> 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.
<dt><a name="altkey">altkey, metakey <em>(One of, x11)</em></a>
<dd>The <em>altkey</em> option controls the effect of the <kbd>Alt</kbd> or
<kbd>Meta</kbd> keys.
It can be set to either <b>control-O, setbit,</b> or <b>ignore.</b>
The <strong>ignore</strong> value is self explanatory.
If the option is set to <strong>control-O</strong> then the x11 interface will
simulate a <kbd>^O</kbd> keystroke before each actual keystroke.
This is handy because if you're in input mode you can just hold down
<kbd>Alt</kbd>/<kbd>Meta</kbd> to perform a series of visual commands.
If the option is set to <strong>setbit</strong> then the x11 interface will
set the most significant bit of each ASCII character while the
<kbd>Alt</kbd>/<kbd>Meta</kbd> key is held down.
Some other programs use this trick as a means of entering non-ASCII
(Elvis has a better way though;
check out the <a href="elvisex.html#digraph">:digraph</a> command.)
The default is <strong>setbit.</strong>
<dt><a name="focusnew">focusnew, fn <em>(Boolean, x11)</em></a>
<dd>The <em>focusnew</em> 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 ("<code>:set nofocusnew</code>") 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 <a href="elvisvi.html#^W^W">^W^W</a>.
<dt><a name="warpto">warpto, wt <em>(One of, x11)</em></a>
<dd>The <em>warpto</em> option can cause Elvis to force the mouse pointer
to move whenever you use keyboard commands such as <a href="elvisvi.html#^W^W">^W^W</a>
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.
<p>You can set the warpto option to any one of the following values:
<strong>don't, scrollbar, origin,</strong> or <strong>corners.</strong>
The default is <strong>don't</strong> which prevents any automatic pointer
The <strong>scrollbar</strong> value causes the pointer to move to the
scrollbar, and <strong>origin</strong> moves it to the upper-left corner.
The <strong>corners</strong> 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.
<dt><a name="warpback">warpback, xwb <em>(Boolean, x11)</em></a>
<dd>The <em>warpback</em> 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
Just as the <code>firstx, firsty,</code> and <code>stagger</code> options are intended
to allow mouseless positioning of Elvis windows, the <code>warpback</code> 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, <code>warpback</code> is false.
<dt><a name="outlinemono">outlinemono, om <em>(Number, x11)</em></a>
<dd>The <em>outlinemono</em> 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
<code>outlinemono</code> 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.
<dt><a name="secret">secret <em>(Number, x11)</em></a>
<dd>Normally, when any clients sends ex commands to a server elvis
(via "elvis -client -c <var>excmd</var>", for example),
those commands are executed with
<a href="#security">security</a>=<code>safer</code>.
The <em>secret</em> option provides a way to recognize trusted clients
which are not forced into this high-security mode.
If <code>secret</code> is non-zero, and
a command is received which begins with the <code>secret</code> value
enclosed in double-quote characters, then elvis will run the command without
forcing <code>security=safer</code>.
Initally <code>secret</code> is 0, which will disable this feature so that all
clients' requests are run in <code>security=safer</code> mode.
If you set <code>secret</code> to a random value,
and then pass that value to a program started by elvis,
then elvis will be able to recognize that program's requests as coming from
a client that it trusts.
This mechanism is used by the <a href="elvistip.html#gdb">gdb</a> interface.
<h2><a name="REGEXP">6.14 Regular expression options</a></h2>
<pre graphic>.---------------------.---------.--------.-----------------------------.
| <a href="#ignorecase">ignorecase, ic</a> | Boolean | global | uppercase matches lowercase |
| <a href="#smartcase">smartcase, scs</a> | Boolean | global | defeat <a href="#ignorecase">ignorecase</a> if upper |
| <a href="#magic">magic, ma</a> | Boolean | global | use normal regexp syntax |
| <a href="#magicchar">magicchar, mac</a> | String | global | list of metacharacters |
| <a href="#magicname">magicname, man</a> | Boolean | global | allow $name substitution |
| <a href="#magicperl">magicperl, map</a> | Boolean | global | Perl-compatible \b |
| <a href="#autoselect">autoselect, as</a> | Boolean | global | visibly mark searched text |
| <a href="#hlsearch">hlsearch, hls</a> | Boolean | global | highlight all marches |
| <a href="#wrapscan">wrapscan, ws</a> | Boolean | global | searching wraps at EOF&lt;-&gt;BOF|
| <a href="#gdefault">gdefault, gd</a> | Boolean | global | default change all instances|
| <a href="#edcompatible">edcompatible, ed</a> | Boolean | global | remember regsub flags |
| <a href="#saveregexp">saveregexp, sre</a> | Boolean | global | remember regexp to use as //|
| <a href="#incsearch">incsearch, is</a> | Boolean | global | <a href="elvisvi.html#slash">/</a> and <a href="elvisvi.html#quest">?</a> search incrementally|
<dt><a name="ignorecase">ignorecase, ic <em>(Boolean, global)</em></a>
<dd>Setting the <em>ignorecase</em> option to true will
cause Elvis to treat uppercase and lowercase letters as being equal, except
in <a href="elvisre.html#charlist">character list</a> metacharacters.
When ignorecase is false (the default), they are treated as different.
<dt><a name="smartcase">smartcase, scs <em>(Boolean, global)</em></a>
<dd>The <em>smartcase</em> option modifies the meaning of the
<a href="#ignorecase">ignorecase</a> option so that if you type in a regular
expression which contains uppercase letters, the search will be case sensitive.
The <code>smartcase</code> option has no effect unless <code>ignorecase</code>
is also set.
<dt><a name="magic">magic, ma <em>(Boolean, global)</em></a>
<dd>The <em>magic</em> option selects one of two different
syntaxes for regular expressions.
When it is false, all metacharacters begin with a backslash, except for ^ at
the start of an expression or $ at the end of one.
When <code>magic</code> is true, the <a href="#magicchar">magicchar</a> option
allows some characters to be metacharacters without a backslash.
<dt><a name="magicchar">magicchar, mac <em>(String, global)</em></a>
<dd>The <em>magicchar</em> option gives you a way to tweak the syntax of
Elvis' <a href="elvisre.html">regular expressions</a>.
This is handy because there are several regular expression notations which
are similar, but not quite identical.
The main difference is that sometimes a given metacharacter requires a
leading backslash, and sometimes it doesn't.
The <code>magicchar</code> value is a list of metacharacters that don't
require a leading backslash.
<p>The <code>magicchar</code> option has no effect unless the
<a href="#magic">magic</a> option is true.
This is a good thing.
<a href="elvistag.html">Tag searches</a> are always done in
<code>nomagic</code> mode, so they're
immune to any changes you make to <code>magicchar</code>.
<p>The default value is "<code>^$.[*</code>", which makes Elvis mimic the
traditional vi syntax.
Some users may prefer to add "<code>+?(){|</code>",
which makes it more like Perl and egrep.
You'll need a backslash before the | to prevent it from being interpreted
as a command separator, so the complete command is:
:set magicchar=^$.[*+?(){\|</pre>
<p>Note that you never need to add "<code>]</code>" or "<code>}</code>";
they are implied by the corresponding "<code>[</code>" or "<code>{</code>"
However, you do need to explicitly add "<code>)</code>" if you want it to
be recognized without the backslash.
Changing <code>magicchar</code> could potentially break scripts and aliases
that expect it to have the default value, if you aren't careful.
Elvis' standard configuration scripts and aliases take steps to avoid this problem.
You should do the same for your own scripts and aliases.
There are three ways to do this:
<li>Put a <code>\V</code> metacharacter at the front of every regular
expression. This will force the remainder of the expression to be
interpreted using the traditional vi syntax.
<li>Add "<code>local magicchar=^$.[*</code>" to the top of each script or
alias, to temporarily force magicchar back to its default value.
<li>Use the <a href="elvistip.html#AliasEnter">AliasEnter</a> and
<a href="elvistip.html#ScriptEnter">ScriptEnter</a> events to trigger
an <a href="elvisex.html#autocmd">:autocmd</a> at the top of each alias
and script. This way, you don't need to modify your aliases and scripts.
au AliasEnter,ScriptEnter * local magicchar=^$.[*</pre>
<dt><a name="magicname">magicname, man <em>(Boolean, global)</em></a>
<dd>The <em>magicname</em> option enables the use of
<code>$</code><var>name</var> substitution in
<a href="elvisre.html">regular expressions</a>,
and the <a href="elvisex.html#substitute">:s</a> command's replacement text.
Normally this option is off, so you can search for dollar signs easily.
<a href="elvistip.html#ALIAS">Aliases</a> that compute regular expressions
often use "<a href="elvisex.html#local">:local</a> <code>magicname</code>"
to access their computed regular expression by name.
<dt><a name="magicperl">magicperl, map <em>(Boolean, global)</em></a>
<dd>The <em>magicperl</em> option changes the meanings of a few metacharacters
to be more Perl-like.
Currently this only changes the <code>\b</code> metacharacter to mean
"edge of a word", instead of "backspace"
(except in <code>[</code><var>charlist</var><code>]</code> metacharacters,
where <code>\b</code> always means "backspace").
Future versions of Elvis are expected to change more metacharacters.
<dt><a name="autoselect">autoselect, as <em>(Boolean, global)</em></a>
<dd>The <em>autoselect</em> option, when true, causes
a successful visual search command such as <a href="elvisvi.html#slash">/regexp</a>
to visibly mark the matching text just like the <a href="elvisvi.html#v">v</a>
command does.
<dt><a name="hlsearch">hlsearch, hls <em>(Boolean, global)</em></a>
<dd>The <em>hlsearch</em> option causes Elvis to highlight
all instances of text which match the regular expression of the most recent
<a href="elvisvi.html#slash">/</a> or <a href="elvisvi.html#quest">?</a>
visual command.
The appearance of the highlighting is controlled by the
<a href="elvisex.html#color">:color hlsearch</a> setting.
Although highlighted, the matching text is not marked for later operations
the way it would be with the <a href="elvisvi.html#v">v</a> command or
<a href="#autoselect">autoselect</a> option.
<dt><a name="wrapscan">wrapscan, ws <em>(Boolean, global)</em></a>
<dd>The <em>wrapscan</em> 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 and a short "wrapped" message will be displayed, 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.
<dt><a name="gdefault">gdefault, gd <em>(Boolean, global)</em></a>
<dd>The <em>gdefault</em> option affects the default behavior of the
<a href="elvisex.html#substitute">:s/old/new/</a> command.
It is false by default, which causes <code>:s/old/new/</code> to assume an instance number of &quot;.1&quot; so only
the first instance in each line is changed.
Making gdefault true will cause a
<a href="elvisex.html#substitute">:s/old/new/</a> command
to change all instances in each line,
as though the &quot;g&quot; flag had been given.
If you give an explicit instance number or &quot;g&quot; flag,
then the value of gdefault is ignored.
<dt><a name="edcompatible">edcompatible, ed <em>(Boolean, global)</em></a>
<dd>The <em>edcompatible</em> option causes
Elvis to remember any flags that are passed into the <a href="elvisex.html#substitute">:s/old/new/flags</a> command, and use them as the default for the next
such command.
Explicitly naming a flag will toggle that flag's value.
This is <em>not</em> the way the old <code>ed</code> editor worked,
but this option's name and behavior are traditional in vi.
This option is false by default.
<dt><a name="saveregexp">saveregexp, sre <em>(Boolean, global)</em></a>
<dd>The <em>saveregexp</em> option is normally true, which causes Elvis to remember
each regular expression. If, in a later command, you give an empty regular
expression, then Elvis will recall the saved regular expression instead. This
also affects the <a href="elvisvi.html#n">n</a> and
<a href="elvisvi.html#N">N</a> commands. You may wish to turn this option off
temporarily in the <a href="elvisses.html#elvis.arf">lib/elvis.arf</a> file
if you're using any regular expressions there, so that loading a file doesn't
interfere with <code>n</code> and <code>N</code>.
<dt><a name="incsearch">incsearch, is <em>(Boolean, global)</em></a>
<dd>The <em>incsearch</em> option affects the behavior of the vi
<a href="elvisvi.html#slash">/</a> and <a href="elvisvi.html#quest">?</a>
search commands.
<code>incsearch</code> is false by default.
<p>When <code>incsearch</code> is false, those commands wait for you to enter
a complete regular expression before search; while entering it, you have
access to the full set of <a href="elvisinp.html">input mode</a> editing
<p>When <code>incsearch</code> is true, those commands search through the
buffer after each keystroke as you type in the regular expression, without
waiting for you to hit the <kbd>&lt;Enter&gt;</kbd> key.
The only special keystrokes available are:
<pre graphic>
| Keystoke | Action |
| Enter | Exits the incremental search mode, leaving the |
| | cursor at the found text |
| Esc | Exits the incremental search mode, returning the |
| | cursor to its previous location. |
| Backspace | Erases last character from the regular expression. |
| Ctrl-V | Quotes the next character, so you can search for |
| | an <kbd>Enter</kbd>, <kbd>Esc</kbd>, or <kbd>Backspace</kbd> character. |
<p>The <code>incsearch</code> option interferes with the use of the
<a href="elvisvi.html#slash">/</a> and <a href="elvisvi.html#quest">?</a>
commands as a destination for <a href="elvisvi.html#operators">operators</a>.
To get around this, the <code>incsearch</code> option is temporarily
disabled when executing an operator.
<h2><a name="TAG">6.15 Tag options</a></h2>
<pre graphic>.---------------------.---------.--------.-----------------------------.
| <a href="#taglength">taglength, tl</a> | Number | global | significant length of tags |
| <a href="#tags">tags, tagpath</a> | String | global | list of possible tag files |
| <a href="#tagstack">tagstack, tsk</a> | Boolean | global | remember origin of tag srch |
| <a href="#tagprg">tagprg, tp</a> | String | global | external tag search program |
| <a href="#smartargs">smartargs, sa</a> | Boolean | buf | show args when inputing func|
| <a href="#tagkind">tagkind, tk</a> | Boolean | global | highlight tags |
| <a href="#taglibrary">taglibrary, tlib</a> | Boolean | global | highlight library tags |
These options control how Elvis performs tag lookup, as for the
<a href="elvisex.html#tag">:tag</a> ex command or the
<a href="elvisvi.html#^]">^]</a> visual command.
You should also check out the <a href="#previoustag">previoustag</a> option,
and the <a href="#show">show</a> option's "tag" keyword.
In fact, this manual has a whole <a href="elvistag.html">Tags chapter</a>.
<dt><a name="taglength">taglength, tl <em>(Number, global)</em></a>
<dd>The <em>taglength</em> 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.
<dt><a name="tags">tags, tagpath <em>(String, global)</em></a>
<dd>The <em>tags</em> 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.
<p>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
"<code>:set tags=./tags:tags</code>" 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.
Traditionally, the 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
This makes Elvis' "tags" settings incompatible with other versions of
vi, though.
If this is a problem for you, then you might consider adding the following
to the top of your .exrc file...
alias fixtags {
" Convert spaces to colons in the tags option
local i t
let t = tags[1]
for i (2 .. tags[0])
do let t = t : tags[i]
let tags = t
au optchanged tags fixtags
<dt><a name="tagstack">tagstack, tsk <em>(Boolean, global)</em></a>
<dd>If the <em>tagstack</em> 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 <a href="elvisex.html#pop">:pop</a> or visual
<a href="elvisvi.html#">^T</a> commands to return to your original position.
If <code>tagstack</code> is false, then the tag stack is unaffected by tag look-up.
It is true by default.
<dt><a name="tagprg">tagprg, tp <em>(String, global)</em></a>
<dd>If the <em>tagprg</em> option is set to any value
other than "", then whenever you try to do a tag search via
<a href="elvisex.html#tag">:tag</a> or
<a href="elvisex.html#browse">:browse</a>, Elvis will execute
<code>tagprg</code>'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 <a href="elvisexp.html#SIMPLER">simpler expression syntax</a> with
<strong>$1</strong> indicating where the arguments should go.
The default value of <code>tagprg</code> is "" which causes Elvis to use
the internal tag search algorithm.
<p><strong>NOTE:</strong> You might also consider using the
<a href="#ccprg">ccprg</a> option for this sort of thing, since the
<a href="elvisex.html#cc">:cc</a> command has a smarter line parser than the
<a href="elvisex.html#tag">:tag</a> command.
<dt><a name="smartargs">smartargs, sa <em>(Boolean, buf)</em></a>
<dd>The <em>smartargs</em> option causes Elvis to display the arguments to a
function when you're inputting text.
It only works in <a href="elvisdm.html#syntax">syntax display mode</a>.
When you type the <a href="elvisdm.html#function">function character</a>,
Elvis performs a tag search on the function name, and extracts the arguments
from the tag's source line.
These arguments are then inserted into your buffer, but then "backspaced"
over to effectively remove them from the input.
You can still see the argument text until you overtype it or hit the
<kbd>&lt;Esc&gt;</kbd> key, but it has no effect on keys you type or on
the ultimate contents of the edit buffer.
<dt><a name="tagkind">tagkind, tk <em>(Boolean, global)</em></a>
<br><a name="taglibrary">taglibrary, tlib <em>(Boolean, global)</em></a>
<dd>The <em>tagkind</em> and <em>taglibrary</em> options cause tags to be
displayed in distinctive faces.
The name of the face is derived from the tag's "kind" attribute.
<p>If the <code>tagkind</code> option is set, then the first time any given
language's <a href="elvisdm.html#elvis.syn">syntax description</a> is loaded,
Elvis reads through any <code>tags</code> files in the
<a href="#tags">tagpath</a> for any tags defined in a file that is callable
by this language.
For each such tag, Elvis adds the tag name as a keyword, and sets the face
to either "<code>kind</code><var>k</var>" where <var>k</var> is the value
of its "kind" attribute, or simply "<code>kind</code>" if the tag has no "kind"
For example, your data types are displayed in the "<code>kindt</code>" face.
You can use the <a href="elvisex.html#color">:color</a> command to change
the appearance of the face.
:color kindt underlined like keyword</pre>
<p>The <code>taglibrary</code> option does the same thing, except that it
looks for tags in the directories listed in the
<a href="#elvispath">elvispath</a> option, and the face names
are of the form "<code>lib</code><var>k</var>".
Generally, <code>taglibrary</code> is intended to be used with tags for stub
files of libraries.
<p>Not all library tags are added.
Static functions are skipped, as are
non-function tags that are defined in anything other than an "enum" data type.
<p>Because <code>tagkind</code> and <code>taglibrary</code> are only checked the
first time a given language's syntax is loaded, any changes to your tags file
won't be detected until you exit Elvis and restart it.
For <code>taglibrary</code>, this doesn't matter since libraries don't change much,
but for <code>tagkind</code> it can be annoying.
You might want to consider using the <a href="#spell">spell</a> option
instead of <code>tagkind</code>.
<p>Also, since setting these options <em>will not</em> cause Elvis to reload syntax
descriptions, you probably only want to set these options via your ".exrc"
(See the <a href="elvisex.html#mkexrc">:mkexrc</a> command.)
<h2><a name="DRAW">6.16 Window update parameters</a></h2>
<pre graphic>.---------------------.---------.--------.-----------------------------.
| <a href="#exrefresh">exrefresh, er</a> | Boolean | global | redraw scrn after each line |
| <a href="#nearscroll">nearscroll, ns</a> | Number | global | scroll vs. jump&amp;center param|
| <a href="#wrap">wrap</a> | Boolean | win | how long lines are displayed|
| <a href="#sidescroll">sidescroll, ss</a> | Number | win | sideways scrolling amount |
| <a href="#optimize">optimize, op</a> | Boolean | global | run faster |
| <a href="#animation">animation, anim</a> | Number | global | animation macro speed |
| <a href="#window">window, wi</a> | Number | global | lines to show for :z command|
| <a href="#pollfrequency">pollfrequency, pf</a> | Number | global | rate of testing for ^C |
| <a href="#maptrace">maptrace, mt</a> | One of | global | debugger: off, run, or step |
| <a href="#maplog">maplog, mlog</a> | One of | global | logging: off, reset, append |
<dt><a name="exrefresh">exrefresh, er <em>(Boolean, global)</em></a>
<dd>The <em>exrefresh</em> 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.
<dt><a name="nearscroll">nearscroll, ns <em>(Number, global)</em></a>
<dd>The <em>nearscroll</em> 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.
<dt><a name="wrap">wrap <em>(Boolean, win)</em></a>
<dd>The <em>wrap</em> 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.
<dt><a name="sidescroll">sidescroll, ss <em>(Number, win)</em></a>
<dd>If the <a href="#wrap">wrap</a> option is false
(indicating that long lines should be displayed via side-scrolling) then the
<em>sidescroll</em> option controls the scrolling increment.
The default is 8, so the display will scroll sideways in chunks of 8
characters at a time.
<dt><a name="optimize">optimize, opt <em>(Boolean, global)</em></a>
<dd>The <em>optimize</em> 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.
<dt><a name="animation">animation, anim <em>(Number, global)</em></a>
<dd>The <em>animation</em> option is related to
<a href="#optimize">optimize</a>.
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.
<p>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.
<dt><a name="window">window, wi <em>(Number, global)</em></a>
<dd>The <em>window</em> option stores the default number
of lines to be displayed by the <a href="elvisex.html#z">:z</a> 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.
<dt><a name="pollfrequency">pollfrequency, pf <em>(Number, global)</em></a>
<dd>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 <em>pollfrequency</em> 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 <kbd>^C</kbd> sooner.
<dt><a name="maptrace">maptrace, mt <em>(One of, global)</em></a>
<dd>The <em>maptrace</em> option controls Elvis' built-in macro debugger.
It can be <strong>off, run</strong>, or <strong>step</strong>.
The default is <strong>off,</strong> which causes macros to run normally.
If you change it to <strong>run</strong> then Elvis will display the
contents of the mapping queue at the bottom of the screen while running
any macro;
depending on <a href="#maplog">maplog</a>, it may also log it.
The <strong>step</strong> value displays the mapping queue, and then
waits for a keystroke before proceeding.
If the keystroke is <kbd>^C</kbd> then the macro is terminated.
If the keystroke is <kbd>r</kbd> then maptrace is set to <strong>run.</strong>
Any other keystroke causes Elvis to pause again after processing the macro's
next character.
See section <a href="elvistip.html#DEBUG">16.3 How to debug macros</a> for more
suggestions for debugging macros.
<dt><a name="maplog">maplog, mlog <em>(One of, global)</em></a>
<dd>The <em>maplog</em> option can be used to log the information displayed by
the <a href="#maptrace">maptrace</a> option.
It also logs any ex commands that are executed,
other than those that you enter manually.
It is <strong>off</strong> by default.
Setting it to <strong>append</strong> causes the map trace information to be
appended to an internal edit buffer named "Elvis map log".
Setting it to <strong>reset</strong> causes that buffer to be clobbered
before the next map trace; when that happens, maplog will be automatically
switched to <strong>append</strong>.
You can view the logged data via the command...
or the long version, "<code>:(Elvis map log)split</code>".
<h2><a name="CACHE">6.17 Cache options</a></h2>
<pre graphic>.---------------------.---------.--------.-----------------------------.
| <a href="#blkcache">blkcache, cache</a> | Number | global | number of blocks in cache |
| <a href="#blksize">blksize, bsz</a> | Number | global | size of cache block |
| <a href="#blkfill">blkfill, bfill</a> | Number | global | initial chars per text block|
| <a href="#blkhash">blkhash, hash</a> | Number | global | size of cache hash table |
| <a href="#blkgrow">blkgrow, bgr</a> | Number | global | allocation table parameter |
| <a href="#blkhit">blkhit, bh</a> | Number | global | # of block requests in cache|
| <a href="#blkmiss">blkmiss, bm</a> | Number | global | # of block req. not in cache|
| <a href="#blkwrite">blkwrite, bw</a> | Number | global | # of blocks written |
| <a href="#sync">sync</a> | Boolean | global | force changes to disk |
<dt><a name="blkcache">blkcache, cache <em>(Number, global)</em></a>
<br><a name="blksize">blksize, bsz <em>(Number, global)</em></a>
<br><a name="blkfill">blkfill, bfill <em>(Number, global)</em></a>
<br><a name="blkhash">blkhash, hash <em>(Number, global)</em></a>
<br><a name="blkgrow">blkgrow, bgr <em>(Number, global)</em></a>
<br><a name="blkhit">blkhit, bh <em>(Number, global)</em></a>
<br><a name="blkmiss">blkmiss, bm <em>(Number, global)</em></a>
<dd>You probably don't need to know about the "blk" options.
The <em>blkcache</em> option indicates how many blocks
from the session file Elvis should keep in its own internal cache,
and <em>blkhit</em> and <em>blkmiss</em> can be used to gauge the efficiency
of the cache.
<em>blkwrite</em> indicates how many blocks have been written to the session
The <em>blksize</em> option indicates the size of each block,
<em>blkfill</em> indicates how many characters should be stuffed into
each block initially (leaving room for more text that the user may insert
later), and
<em>blkhash</em> and <em>blkgrow</em> affect a couple of internal tables.
<p>Note that the value of <em>blksize</em> can only be set via the
<strong>-B</strong><var>blksize</var> command line flag, and its value must
be a power of 2 in the range [512, 8192].
You can't change <em>blksize</em> after Elvis has started
(not even in configuration scripts), because by then the session file has
already been created with the other block size.
<dt><a name="sync">sync <em>(Boolean, global)</em></a>
<dd>If the <em>sync</em> 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.
<h2><a name="SYSTEM">6.18 Options that describe the system</a></h2>
<pre graphic>.---------------------.---------.--------.-----------------------------.
| <a href="#version">version, ver</a> | String | global | Elvis version number (2.2) |
| <a href="#bitsperchar">bitsperchar, bits</a> | Number | global | character size (always 8) |
| <a href="#gui">gui</a> | String | global | name of user interface |
| <a href="#os">os</a> | String | global | name of operating system |
| <a href="#locale">locale</a> | String | global | user's language |
| <a href="#program">program, argv0</a> | String | global | invocation name of Elvis |
| <a href="#session">session, ses</a> | String | global | name of session file |
| <a href="#tempsession">tempsession, temp</a> | Boolean | global | delete session file on exit |
| <a href="#newsession">newsession, newses</a> | Boolean | global | session file is new |
| <a href="#recovering">recovering, rflag</a> | Boolean | global | recovering after a crash |
| <a href="#exitcode">exitcode, exit</a> | Number | global | exit code of Elvis process |
<dt><a name="version">version, ver <em>(String, global)</em></a>
<dd>The <em>version</em> option stores the version number of Elvis
-- currently "2.2".
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 incompatible commands.
<dt><a name="bitsperchar">bitsperchar, bits <em>(Number, global)</em></a>
<dd>The <em>bitsperchar</em> option indicates the size
of characters that Elvis uses internally.
Currently this is always 8, but I expect to support 16-bit characters eventually.
<dt><a name="gui">gui <em>(String, global)</em></a>
<dd>The <em>gui</em> 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.
<dt><a name="os">os <em>(String, global)</em></a>
<dd>The <em>os</em> option allows Elvis' initialization files to act differently
on different operating systems.
Its value indicates the name of the local operating system.
<dt><a name="locale">locale <em>(String, global)</em></a>
<dd>The natural-language spoken by the user.
The value is initialized by the <a href="elvisses.html#elvis.ini">elvis.ini</a>
script from the $LANG or $LC_ALL environment variables.
<p>The <em>locale</em> option has no direct effect on Elvis;
it is only used in some scripts.
In particular, the it affects the default value chosen for the
<a href="#spelldict">spelldict</a> option.
Elvis itself uses the <a href="elvisinp.html#DIGRAPH">digraph table</a>
to handle different symbol sets, and the
<a href="">elvis.msg</a> file for different languages.
<dt><a name="program">program, argv0 <em>(String, global)</em></a>
<dd>The <em>program</em> 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
The default <a href="elvisses.html#elvis.ini">elvis.ini</a> file evaluates
<code>tolower(basename(program))</code> and compares the result to "ex" and "view",
to set the <a href="#initialstate">initialstate</a>
and <a href="#defaultreadonly">defaultreadonly</a> options, respectively.
<dt><a name="session">session, ses <em>(String, global)</em></a>
<dd>The <em>session</em> 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.
<dt><a name="tempsession">tempsession, temp <em>(Boolean, global)</em></a>
<br><a name="newsession">newsession, newses <em>(Boolean, global)</em></a>
<br><a name="recovering">recovering, rflag <em>(Boolean, global)</em></a>
<dd>The <em>tempsession, newsession,</em> and <em>recovering</em> 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
<a href="elvisses.html#elvis.ini">elvis.ini</a> 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.
<dt><a name="exitcode">exitcode, exit <em>(Number, global)</em></a>
<dd>The <em>exitcode</em> 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 detects an error during initialization
and exitcode has not been explicitly set,
then Elvis changes exitcode to 1, so the parent process can know that
Elvis had an error.
<h2><a name="EXTERNAL">6.19 External programs</a></h2>
<pre graphic>.---------------------.---------.--------.-----------------------------.
| <a href="#ccprg">ccprg, cp</a> | String | buf | shell command for :cc |
| <a href="#makeprg">makeprg, mp</a> | String | buf | shell command for :make |
| <a href="#anyerror">anyerror, ae</a> | Boolean | global | allow :errlist if readonly |
| <a href="#equalprg">equalprg, ep</a> | String | buf | shell command for = operator|
| <a href="#keywordprg">keywordprg, kp</a> | String | buf | shell command for K command |
| <a href="#shell">shell, sh</a> | String | global | name of shell program |
| <a href="#warn">warn</a> | Boolean | global | warn if file not saved |
<dt><a name="ccprg">ccprg, cp <em>(String, buf)</em></a>
<br><a name="makeprg">makeprg, mp <em>(String, buf)</em></a>
<dd>The <em>ccprg</em> and <em>makeprg</em> options store the shell commands
that are used by the
<a href="elvisex.html#cc">:cc</a> and <a href="elvisex.html#make">:make</a>
Before the program strings are executed, they are subjected to the same
sort of expression evaluation as the <a href="elvisex.html#eval">:eval</a>
command, with $1 representing any extra arguments from the ex command line,
and $2 representing the name of the current file.
Their defaults are <code>cp="cc ($1?$1:$2)"</code> and <code>mp="make $1"</code>.
<p>Spaces in filenames can be a problem with the <code>$2</code> symbol.
This is especially true when running Microsoft Windows.
Most command-line programs such as "cc" use whitespace to delimit their
arguments, so if your filename contains whitespace then the natural tendency
of the system is to divide that filename into multiple arguments, none of which
happens to be the correct name of your file.
To get around this problem, you need to add double-quote characters around
the filename.
This is a little tricky, since double-quotes are also special to both the
<a href="elvisex.html#set">:set</a> command and Elvis'
<a href="elvisexp.html">expression evaluator</a>.
Do it this way:
:set cp="cc ($1?$1:(char(34);$2;char(34)))"</pre>
<dt><a name="anyerror">anyerror, ae <em>(Boolean, global)</em></a>
<dd>When searching for error messages after a
<a href="elvisex.html#cc">:cc</a> or <a href="elvisex.html#make">:make</a>
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 <em>anyerror</em> to true will make it read any file that
generates a complaint, even if you can't write to it.
<dt><a name="equalprg">equalprg, ep <em>(String, buf)</em></a>
<dd>The <em>equalprg</em> option stores the name
of a program to be executed for the visual <a href="elvisvi.html#=">=</a>
operator command.
Its default value is "fmt", which is a simple text formatting program.
<dt><a name="keywordprg">keywordprg, kp <em>(String, buf)</em></a>
<dd>The <em>keywordprg</em> option stores the name
of the program used by the visual <a href="elvisvi.html#K">K</a> 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 <em>ref</em> program looks up
a tag and displays it.
If you're using the <a href="elvisgui.html#x11">x11</a> 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&gt;&amp;1 \| xmessage -file - &gt;/dev/null 2&gt;&amp;1 &amp;"</pre>
<dt><a name="shell">shell, sh <em>(String, global)</em></a>
<dd>The <em>shell</em> 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 <a href="elvisex.html#BANG">:!</a> and visual
<a href="elvisvi.html#bang">!</a> commands.
Its default value is system-dependent; typically it will be "/bin/sh"
for UNIX, and "C:\COMMAND.COM" for MS-DOS.
<dt><a name="warn">warn <em>(Boolean, global)</em></a>
<dd>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 <em>warn</em> option to false disables this message.
<h2><a name="DIR">6.20 Directory names</a></h2>
<pre graphic>.---------------------.---------.--------.-----------------------------.
| <a href="#home">home</a> | String | global | home directory |
| <a href="#elvispath">elvispath, epath</a> | String | global | list of possible config dirs|
| <a href="#sessionpath">sessionpath, spath</a> | String | global | list of possible session dir|
| <a href="#directory">directory, dir</a> | String | global | where to store temp files |
<dt><a name="home">home <em>(String, global)</em></a>
<dd>The <em>home</em> 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:
<th>For UNIX:</th>
<td>The default is "/".</td>
<th>For Win32:</th>
<td>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.</td>
<th>For OS/2:</th>
<td>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.</td>
<th>For MS-DOS:</th>
<td>The default home directory is the one containing ELVIS-2.2_1</td>
<dt><a name="elvispath">elvispath, epath <em>(String, global)</em></a>
<dd>The <em>elvispath</em> 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 "~/.elvis:/etc/elvis:/usr/share/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:
<th>For UNIX:</th>
<td>The default contains <em>~/.elvis</em> and the directories that you
specified as the data and doc directories when you ran the
<code>configure</code> script.
The default data directories are <em>/usr/share/elvis</em> for data,
and <em>/usr/share/elvis/doc</em> for documentation, so usually
elvispath will default to "~/.elvis:/etc/elvis:/usr/share/elvis:<br>
<th>For Win32, OS/2,<br>or MS-DOS:</th>
<td>The default contains <em>~\dotelvis</em>,
and subdirectories named <em>data</em> and <em>doc</em> under
the directory where <em>elvis.exe</em> resides.
For example, if Elvis is installed as <em>C:\elvis\elvis.exe</em> then
elvispath would be <em>~\dotelvis;C:\elvis\data;c:\elvis\doc</em>.</td>
<dt><a name="sessionpath">sessionpath, spath <em>(String, global)</em></a>
<dd>The <em>sessionpath</em> option gives Elvis a
list of possible directories where <a href="elvisses.html#SESSION">session
files</a> 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.
<dt><a name="directory">directory, dir <em>(String, global)</em></a>
<dd>The <em>directory</em> option gives the name of
the directory where Elvis will store its temporary files.
The default value is system-dependent.
Note that this is <em>not</em> where the session file is stored;
the <a href="#session">session</a> option gives the name of the session file.
<h2><a name="INIT">6.21 Initialization options</a></h2>
<pre graphic>.---------------------.---------.--------.-----------------------------.
| <a href="#initializing">initializing, ing</a> | Boolean | global | has first file been loaded? |
| <a href="#exrc">exrc, ex</a> | Boolean | global | interpret ./.exrc file |
| <a href="#modeline">modeline, ml</a> | Boolean | global | interpret modelines |
| <a href="#modelines">modelines, mls</a> | Number | global | positions of modelines |
| <a href="#security">security, sec</a> | One-of | global | normal, safer,or restricted |
| <a href="#initialstate">initialstate, init</a> | One-Of | global | command mode of new windows |
| <a href="#mkexrcfile">mkexrcfile, rc</a> | String | global | name of user's init script |
| <a href="#persistfile">persistfile, perf</a> | String | global | file that remembers cursors |
| <a href="#persist">persist, pers</a> | Packed | global | what to store in persistfile|
<dt><a name="initializing">initializing, ing <em>(Boolean, global)</em></a>
<dd>The <em>initializing</em> option indicates whether Elvis is currently
in the early stages of its initialization, before an edit buffer has been
created for first file.
You can't modify this option yourself;
Elvis changes it when appropriate.
It will be set while running the <a href="elvisses.html#elvis.ini">elvis.ini</a>
script (which runs your <code>~/.elvisrc</code> or <code>~/elvis.rc</code> file).
It is cleared while running the <a href="elvisses.html#elvis.brf">elvis.brf</a>
script, and for <a href="elvistip.html#BufReadPre">BufReadPre</a> and
<a href="elvistip.html#BufReadPost">BufReadPost</a> events.
This is significant because commands that access the edit buffer are disabled
while <code>intializing</code> is true.
<dt><a name="exrc">exrc, ex <em>(Boolean, global)</em></a>
<dd>The <em>exrc</em> option has no built-in meaning to Elvis,
however the default <a href="elvisses.html#elvis.ini">elvis.ini</a> file uses this option to determine whether
it should look for a ".exrc" file in the current directory.
<dt><a name="modeline">modeline, ml <em>(Boolean, global)</em></a>
<br><a name="modelines">modelines, mls <em>(Number, global)</em></a>
<dd>The <em>modeline</em> 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
<em>modelines</em> lines of the buffer for something that looks like
"<code>ex:</code><var>commands</var><code>:</code>" or
"<code>vi:</code><var>commands</var><code>:</code>" and
if found, it executes the <var>commands</var> as an ex command line.
(This behavior is implemented in the
<a href="elvisses.html#elvis.arf">elvis.arf</a> file.)
This is typically used for changing tabstops and the like.
The modeline option is false by default, and modelines is 5.
<dt><a name="security">security, sec <em>(One-of, global)</em></a>
<dd>The <em>security</em> option offers a way to close some security holes.
I'm not making any promises!
If you use Elvis in a sensitive environment, you do so at your own risk.
Elvis is distributed without guarantees of any kind.
There are three levels of security: normal, safer, and restricted.
"normal" has no security rules,
"safer" tries to protect the user against writing by malicious scripts, and
"restricted" tries to protect the system against reading by a malicious user.
There are four things that must be avoided to maintain security:
<li>You shouldn't be able to run external programs.
<li>You shouldn't be able to write over any arbitrary file.
<li>You shouldn't be able to load any arbitrary file, modify it, and
write it.
<li>You shouldn't be able to create maps or aliases which trick the
user into doing any of the above.
Items 1, 2, and 4 are pretty easy.
Item 3 requires some compromise and that's
why there are two different secure modes.
"safer" allows you to load any file, and modify it, but not write it;
this makes "safer" useless for interactive work.
"restricted" only allows you to load files named on the command line, but
you can modify them and write them (back over the old version of the file,
not out to any random file).
<tr><th valign=top align=left>normal</th><td>
This is the weakest level of protection.
In other words, it gives the user the most power.
All commands are allowed.
You will normally want to run in "normal" mode as much as possible.
<tr><th valign=top align=left>safer</th><td>
This is intended to make modelines and a .exrc file in the current directory
safe to use, but I'm not making any promises.
When security=safer, certain commands are disabled,
wildcard expansion in filenames is disabled, and
certain options are locked (including the <code>security</code> option itself).
Typically you will use the ex command
"<a href="elvisex.html#safely">:safely source <em>filename</em></a>"
to execute an untrusted script,
rather than futz with the value of the safer option directly.
<p>The disabled ex commands are
<a href="elvisex.html#BANG">:!</a>,
<a href="elvisex.html#abbreviate">:abbreviate</a>,
<a href="elvisex.html#alias">:alias</a>,
<a href="elvisex.html#autocmd">:autocmd</a>,
<a href="elvisex.html#cc">:cc</a>,
<a href="elvisex.html#cd">:cd</a>,
<a href="elvisex.html#chdir">:chdir</a>,
<a href="elvisex.html#lpr">:lpr</a>,
<a href="elvisex.html#make">:make</a>,
<a href="elvisex.html#map">:map</a>,
<a href="elvisex.html#mkexrc">:mkexrc</a>,
<a href="elvisex.html#shell">:shell</a>,
<a href="elvisex.html#write">:write</a>,
<a href="elvisex.html#write">:wquit</a>, and
<a href="elvisex.html#write">:xit</a>.
<p>The locked options are
<a href="#ccprg">ccprg</a>,
<a href="#elvispath">elvispath</a>,
<a href="#equalprg">equalprg</a>,
<a href="#home">home</a>,
<a href="#keywordprg">keywordprg</a>,
<a href="#lpout">lpout</a>,
<a href="#makeprg">makeprg</a>,
<a href="#modeline">modeline</a>,
<a href="#persistfile">persistfile</a>,
<a href="#secret">secret</a>,
<a href="#security">security</a>,
<a href="#shell">shell</a>,
<a href="#spelldict">spelldict</a>,
<a href="#stopshell">stopshell</a>, and
<a href="#tagprg">tagprg</a>.
<p>In expressions, the <a href="elvisexp#shell">shell</a>() function will fail.
<tr><th valign=top align=left>restricted</th><td>
This is intended to make Elvis safe for use as a restricted editor.
Although "restricted" is generally stricter than "safer", it does allow
you to save your files while "safer" does not.
The disabled ex commands are:
<a href="elvisex.html#BANG">:!</a>,
<a href="elvisex.html#abbreviate">:abbreviate</a>,
<a href="elvisex.html#alias">:alias</a>,
<a href="elvisex.html#autocmd">:autocmd</a>,
<a href="elvisex.html#cc">:cc</a>,
<a href="elvisex.html#cd">:cd</a>,
<a href="elvisex.html#chdir">:chdir</a>,
<a href="elvisex.html#errlist">:errlist</a>,
<a href="elvisex.html#lpr">:lpr</a>,
<a href="elvisex.html#make">:make</a>,
<a href="elvisex.html#map">:map</a>,
<a href="elvisex.html#mkexrc">:mkexrc</a>,
<a href="elvisex.html#read">:read</a>,
<a href="elvisex.html#shell">:shell</a>,
<a href="elvisex.html#source">:source</a>,
<a href="elvisex.html#stop">:stop</a>, and
<a href="elvisex.html#suspend">:suspend</a>.
Also, the following ex commands can only be invoked without any arguments:
<a href="elvisex.html#args">:args</a>,
<a href="elvisex.html#edit">:edit</a>,
<a href="elvisex.html#ex">:ex</a>,
<a href="elvisex.html#file">:file</a>,
<a href="elvisex.html#next">:next</a>,
<a href="elvisex.html#open">:open</a>,
<a href="elvisex.html#push">:push</a>,
<a href="elvisex.html#snext">:snext</a>,
<a href="elvisex.html#split">:split</a>,
<a href="elvisex.html#visual">:visual</a>,
<a href="elvisex.html#wordfile">:wordfile</a>,
<a href="elvisex.html#write">:write</a>,
<a href="elvisex.html#wquit">:wquit</a>, and
<a href="elvisex.html#xit">:xit</a>.
"restricted" locks the same options as "safer":
<a href="#ccprg">ccprg</a>,
<a href="#elvispath">elvispath</a>,
<a href="#equalprg">equalprg</a>,
<a href="#home">home</a>,
<a href="#keywordprg">keywordprg</a>,
<a href="#lpout">lpout</a>,
<a href="#makeprg">makeprg</a>,
<a href="#modeline">modeline</a>,
<a href="#persistfile">persistfile</a>,
<a href="#secret">secret</a>,
<a href="#security">security</a>,
<a href="#shell">shell</a>,
<a href="#spelldict">spelldict</a>,
<a href="#stopshell">stopshell</a>, and
<a href="#tagprg">tagprg</a>.
The "restricted" level also
inhibits filename completion via the <kbd>&lt;Tab&gt;</kbd> key.
In expressions, the
<a href="elvisexp#time">time</a>(<var>filename</var>) function will fail if
invoked with a <var>filename</var> parameter, and the
<a href="elvisexp#exists">exists</a>(),
<a href="elvisexp#dirperm">dirperm</a>(),
<a href="elvisexp#fileeol">fileeol</a>(), and
<a href="elvisexp#shell">shell</a>() functions always fail.
<dt><a name="initialstate">initialstate, init <em>(One-Of, global)</em></a>
<dd>The <em>initialstate</em> option determines
what command mode new windows will start in.
It can be one of <b>input, replace, vi,</b> or <b>ex.</b>
The default is <b>vi,</b> the visual command mode.
<dt><a name="mkexrcfile">mkexrcfile, rc <em>(String, global)</em></a>
<dd>The <em>mkexrcfile</em> option contains the name of the file
which contains the user's initialization script.
It is used by the <a href="elvisex.html#mkexrc">:mkexrc</a> command.
It has no default value, but scripts generated by <code>:mkexrc</code>
always set this option to the name of that script file.
<dt><a name="persistfile">persistfile, perf <em>(String, global)</em></a>
<br><a name="persist">persist, pers <em>(Packed, global)</em></a>
<dd>Elvis can store some information about buffers between invocations.
This resembles Vim's 'viminfo' option.
For example, it can save your cursor location in each buffer so that the
next time you edit the same file, your cursor can start in the same place.
This only works if Elvis was compiled with FEATURE_PERSIST
(i.e., if "<code>:calc feature("persist")</code>" returns True.)
<p>The <em>persistfile</em> option tells Elvis where to save these things,
and the <em>persist</em> option controls what gets saved and restored.
<p>The default value of <code>persistfile</code> is an empty string,
which disables persistent information.
This behavior is more compatible with vi.
You must set it to some other value to enable the "persist" feature.
You can set it to either a relative file such as "elvisinfo" to give
each directory its own list of current positions, or an absolute file
such as ~/elvisinfo to use a single file for all of your persistent
<p>The <code>persist</code> option's value is a comma-delimited list of
keywords identifying the things that should be saved and restored.
The list of keywords includes:
<th align=left>SYMBOL</th>
<th align=left>MEANING</th>
<td valign=top>cursor</td>
<td>Restore the cursor location.</td>
<td valign=top>change</td>
<td>Start with the cursor at the location of the last change, except that if <strong>cursor</strong> is also given then set the '' mark to the change position.</td>
<td valign=top>hours:<var>hours</var></td>
<td>If the last change was at least <var>hours</var> hours ago then don't move cursor; set the '' mark instead.</td>
<td valign=top>marks</td>
<td>Save &amp; restore the named marks, 'a - 'z.</td>
<td valign=top>regions</td>
<td>Save &amp; restore any highlighting <a href="elvisex.html#REGION">regions</a>.</td>
<td valign=top>folds</td>
<td>Save &amp; restore any folds (both folded &amp; unfolded)</td>
<td valign=top>external:<var>adjust</var></td>
<td>How to deal with changes made by other programs.
<strong>external:top</strong> tells Elvis to expect changes at the
top of the file, and <strong>external:skip</strong> tells Elvis to
avoid loading the persistent information if there's a change.
Else expect changes at the bottom of the file.</td>
<td valign=top>ex:<var>lines</var></td>
<td>Save the last <var>lines</var> lines of ex history</td>
<td valign=top>search:<var>lines</var></td>
<td>Save the last <var>lines</var> lines of search history</td>
<td valign=top>args</td>
<td>Save the current <a href="elvisex.html#args">args</a> list as the default</td>
<td valign=top>max:<var>bytes</var></td>
<td>Impose a size limit on the persistfile</td>
<p>Note that setting <strong>hours:0</strong> never allows the cursor to move,
but you can still use <strong>cursor</strong> or <strong>change</strong> to set
the '' mark.
To completely disable timeouts,
simply omit the <strong>hours:</strong><var>hours</var> item from the value
of <code>persist</code>.
<p>The <strong>external:</strong><var>adjust</var> field is intended to help
Elvis deal with changes made to the file by other programs.
For example, the RCS <strong>ci</strong> program could alter RCS keywords
such as <code>$</code><code>Id$</code> in your file.
If such changes usually occur near the bottoms of your files, then the change
won't affect any stored cursors, marks, folds, or regions so you won't need
an <strong>external:</strong><var>adjust</var> field.
If the changes usually occur near the tops of your files, then you should
use <strong>external:top</strong> which tells Elvis to adjust the character
offsets and line numbers to be relative to the end of the file.
If the changes are likely to be scattered throughout the file, then you can
use <strong>external:skip</strong> to avoid reloading the persistent information
when the file changes.
<p>The <strong>ex:</strong><var>lines</var>,
<strong>search:</strong><var>lines</var>, and <strong>args</strong>
symbols are global; i.e., they aren't associated with any specific buffer.
<p>The <strong>max:</strong><var>bytes</var> field can be used to impose an
overall size limit on the persist file.
The <var>bytes</var> is a number, optionally followed by "K" or "M" to scale
it to be kilobytes or megabytes.
The limit causes less recently accessed files to be removed from the
persist file.
If omitted, then the size is unlimited.
<p>The format of the <code>persist</code> option is compatible with
<a href="elvisexp.html#fields">field notation</a> and
<a href="elvisexp.html#sets">set notation</a>,
so you can do things such as...
:let persist.max="32K"
:let persist|="args"
:set persist^="change"</pre>
<p>The default value of <code>persistfile</code> is any empty string which
disabled persistent information.
The default value of <code>persist</code> is
<h2><a name="MAP">6.22 Keyboard map options</a></h2>
<pre graphic>.---------------------.---------.--------.-----------------------------.
| <a href="#remap">remap</a> | Boolean | global | allow key maps to use maps |
| <a href="#timeout">timeout, to</a> | Boolean | global | allow timeout for maps? |
| <a href="#keytime">keytime, kt</a> | Number | global | timeout for function keys |
| <a href="#usertime">usertime, ut</a> | Number | global | timeout for multi-key maps |
| <a href="#mapmode">mapmode, mm</a> | String | buf | which maps to use |
Elvis allows keystrokes to be mapped via the <a href="elvisex.html#map">:map</a>
Once a map has been defined, these options control how and when those maps are
<dt><a name="remap">remap <em>(Boolean, global)</em></a>
<dd>The <em>remap</em> 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.
<dt><a name="timeout">timeout, to <em>(Boolean, global)</em></a>
<dd>The <em>timeout</em> option is normally <code>true</code>, which
allows the <a href="#keytime">keytime</a> and <a href="#usertime">usertime</a>
options to control the amount of time allowed for key maps (for a function
key or cursor key) and user maps (for multiple keystrokes of any type of key)
to be received.
Turning off the <code>timeout</code> option will cause Elvis to allow any
amount for maps to be completed,
regardless of the values of <code>keytime</code> and <code>usertime</code>.
<dt><a name="keytime">keytime, kt <em>(Number, global)</em></a>
<br><a name="usertime">usertime, ut <em>(Number, global)</em></a>
<dd>The <em>keytime</em> and <em>usertime</em> options come into play when
characters are received which <em>partially</em> match one or more maps.
For example, suppose the arrow keys are mapped to <kbd>h, j, k,</kbd> and <kbd> l</kbd>,
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 <kbd>Esc</kbd> key or an arrow key?
<p>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
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.
<p>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 <kbd>Esc</kbd> while still allowing users to key in their
own keymaps at a leisurely pace.
Their default values are <code>keytime=3</code> and <code>usertime=15.</code>
<dt><a name="mapmode">mapmode, mm <em>(String, buf)</em></a>
<dd>The <em>mapmode</em> option indicates which mode-sensitive maps to use.
When defining a map via the <a href="elvisex.html#map">:map</a> command,
you can use a <code>mode=</code><var>name</var> flag to indicate which mode
the map applies to.
The <var>name</var> is then compared to the value of <em>mapmode</em> after
each keystroke, when Elvis is deciding which maps to apply.
<p>For example, you could define a set of maps that are appropriate only for
HTML commands, and some that are appropriate only for man-pages...
:map BB mode=html select c&lt;strong&gt;^P&lt;/strong&gt;^[
:map II mode=html select c&lt;em&gt;^P&lt;/em&gt;^[
:map BB mode=man select c\fB^P\fR^[
:map II mode=man select c\fI^P\fR^[
... and then set each edit buffer's <code>mapmode</code> appropriately to
ensure that the proper set of maps are used.
<p>The default value is "",
but the standard <a href="elvisini.html#elvis.arf">elvis.arf</a> script
sets it to be the same as the <a href="elvisopt.html#bufdisplay">bufdisplay</a>
option, if that option's value is one of "html", "man", or "tex".
<h2><a name="AUTOCMD">6.23 Auto command options</a></h2>
<pre graphic>.---------------------.---------.--------.-----------------------------.
| <a href="#eventignore">eventignore, ei</a> | String | global | list of events to ignore |
| <a href="#eventerrors">eventerrors, ee</a> | Boolean | global | allow error msg during event|
| <a href="#aufilename">aufilename, afile</a> | String | au | name of file |
| <a href="#auevent">auevent, ev</a>  | String | au | name of current event |
| <a href="#auforce">auforce, bang</a> | Boolean | au | did trigger cmd have "!" ? |
These options are all related to the <a href="elvisex.html#autocmd">:autocmd</a>
The options in the "au" group only exist while an auto command is executing.
For a description of how auto commands work,
see the <a href="elvistip.html#AUTOCMD">Tips</a> chapter.