6. OPTIONS

Most options have two names -- a short name that is easy to type in, and a longer descriptive name. You can type in either name; they work equivalently. Elvis always outputs the longer name when it is listing values.

Each option accepts a specific type of value. The most common types are boolean, number, string, one-of, and tab-list, but some options have weird types. String options can be set to any value (although not all possible values make sense). One-of options can only be set a single value from a specific list of legal values. (The list varies from one option to another.) Boolean options are either true or false; see the :set and :let commands for a description of how to set their values. Number options can only be set to a numeric value, often only within a limited range. Tab-list 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.

Each option serves as an attribute of something. The group of an option designates what it is an attribute of. For example, the "filename" option is an attribute of buffers; when you switch to a different buffer, it will have a different value for the "filename" option. Other options are attributes of windows, or display modes, etc. Here's a complete list:

.---------.-------------------------------------------------------.
|  GROUP  |  DESCRIPTION                                          |
|---------|-------------------------------------------------------|
| buf     | Attributes of buffers                                 |
| win     | Attributes of windows                                 |
| syntax  | Attributes of the "syntax" display mode               |
| x11     | Attributes of the "x11" user interface                |
| tcap    | Attributes of the "termcap" user interface            |
| windows | Attributes of the "windows" user interface            |
| win32   | User interface attributes for the Win32 port          |
| global  | Global options                                        |
| lp      | Printing options                                      |
| bang    | Used only when writing a file                         |
| user    | User variables a - z (Global, useful in ex scripts)   |
^---------^-------------------------------------------------------^

:set buf?

6.1 Options, grouped by function

6.2 Options that relate the buffer to a file

.---------------------.---------.--------.-----------------------------.
| OPTION NAMES        | TYPE    | GROUP  | DESCRIPTION                 |
|---------------------|---------|--------|-----------------------------|
| filename, file      | String  | buf    | name of file in buffer      |
| bufname, buffer     | String  | buf    | name of buffer              |
| bufid, bufferid     | Number  | buf    | ID number of user buffer    |
| retain, ret         | Boolean | buf    | keep buffer in session file |
| modified, mod       | Boolean | buf    | buffer differs from file    |
| edited, samename    | Boolean | buf    | buffer loaded from filename |
| newfile, new        | Boolean | buf    | filename doesn't exist yet  |
| readonly, ro        | Boolean | buf    | don't overwrite filename    |
| defaultreadonly, dro| Boolean | global | assume all files readonly   |
| locked, lock        | Boolean | win    | prevent any alterations     |
| autowrite, aw       | Boolean | global | save file before switching  |
| writeany, wa        | Boolean | global | don't warn of existing file |
| timestamp, time     | String  | buf    | time when file was modified |
| backup, bk          | Boolean | global | make *.bak file before write|
| undolevels, ul      | Number  | buf    | number of undoable commands |
| beautify, bf        | Boolean | global | strip ctrl chars from files |
| bang                | Boolean | bang   | writing with a '!' ?        |
| userprotocol, up    | Boolean | buf    | URL, user-defined protocol  |
^---------------------^---------^--------^-----------------------------^

filename, file (String, buf)

The filename option stores the name of the text file whose text was initially loaded into the buffer. If no file name is known (e.g., for an internal buffer or a new, untitled buffer) then this will be an empty string. The :file command can be used to change the filename. Also, the filename is set automatically when you write the buffer out, if it had no filename before.

bufname, buffer (String, buf)

The bufname option stores the name of the buffer. Usually this will be the same as the filename, but it can be different. Every buffer has a bufname, even if it doesn't have a filename. The name of a buffer can be changed via the :buffer command.

bufid, bufferid (Number, buf)

For user buffers, the bufid option stores a unique id number for each buffer. Anyplace where you can use the (name) notation to specify a buffer, you can also use (n) as an abbreviation for the buffer whose bufid=n. Also, for filenames you can use #n for the filename of the buffer whose bufid=n.

retain, ret (Boolean, buf)

The retain option indicates whether the buffer is intended to survive past the end of this Elvis process. If this option is true and the tempsession option is false (":set retain notempsession") then Elvis will allow you to exit even if this buffer hasn't been saved since its last change. When you restart the session, the buffer will still exist with all its changed text intact. By default, the retain option is false (":set noretain") because that mimics traditional vi behavior.

modified, mod (Boolean, buf)

The modified option indicates whether the buffer has been modified since the last time it was written out completely.

edited, samename (Boolean, buf)

The edited option indicates whether the filename option has been modified since the last time it was written out. If this option is false, Elvis will be more cautious about writing the file out.

newfile, new (Boolean, buf)

The newfile option indicates that when the buffer was created it tried to load the file identified by the filename option, but that file did not exist at that time.

readonly, ro (Boolean, buf)
defaultreadonly, dro (Boolean, global)

The readonly option indicates that when the buffer was loaded, the original file was marked as being unwritable. Either that, or the defaultreadonly option was set to true (probably via the -R command line flag). This option has two purposes: it gives you a way to detect that you can't write the file out, and it protects you from writing out a file that you meant to just look at without modifying.

locked, lock (Boolean, win)

The locked option prevents you from modifying the buffer. Nearly any command which would modify the buffer will fail. The only exceptions are "undo" commands, and commands such as :e which merely reload the buffer from its original file.

autowrite, aw (Boolean, global)

Setting the autowrite option allows Elvis to automatically write the current buffer out to a file if it has been modified, before switching to another buffer. By default this option is off, so if you try to switch away from a modified buffer, Elvis will just give an error message and refuse to switch until you manually write the file out.

writeany, wa (Boolean, global)

Elvis tries to save you from accidentally clobbering existing files. Setting the writeany option disables this protection; Elvis will allow you to overwrite any file that the operating system will allow, without giving any warnings.

timestamp, time (String, buf)

This option has no hardcoded purpose, but the default elvis.arf, elvis.bwf, and elvis.awf scripts use it store the modification time of a file (as detected by the time() function), and detect whether the file has been modified by some other program while you were editing it in Elvis.

backup, bk (Boolean, global)

The backup option isn't used internally by Elvis, but the default elvis.bwf file checks this flag to determine whether it should attempt to make a backup of a file it is about to overwrite. By default, this option is false, so backups will not be made.

undolevels, ul (Number, buf)

For each buffer, the undolevels option indicates the number of "undo" versions Elvis will maintain. Each undo level requires at least three blocks of the session file (typically 2K bytes each, 6K total) so you probably don't want to set this higher than 100 or so, and you probably want to keep it much lower. The default is 0, which is a special case that mimics vi's traditional behavior.

beautify, bf (Boolean, global)

If the beautify option is true, then whenever Elvis reads text from a file or external program, it will strip any control characters other than tab, linefeed or formfeed. This is false by default.

bang (Boolean, bang)

The bang option only exists while executing the elvis.bwf and elvis.awf scripts, when writing a file. It indicates whether the write was forced (:w!) or normal (:w or ZZ). Those scripts can check the value of bang and skip some tests if it is set. For example, the default version of elvis.bwf checks the timestamp before writing the file, unless the bang option is set.

userprotocol, up (Boolean, buf)

The userprotocol option indicates whether the buffer was loaded via a user-defined protocol. It can be handy in automatically executed scripts.

Initially, all buffers are created with userprotocol turned off. It remains off while the elvis.brf is executed, and then turned on immediately before the readPROTOCOL alias is executed. The default elvis.arf script is sensitive to this value; it skips some setup steps when userprotocol is set, on the theory that if you really needed those options to be set then you would have either set them in the readPROTOCOL alias, or you would have at least turned off userprotocol there.

6.3 Statistics about a buffer

.---------------------.---------.--------.-----------------------------.
| OPTION NAMES        | TYPE    | GROUP  | DESCRIPTION                 |
|---------------------|---------|--------|-----------------------------|
| binary, bin         | Boolean | global | -b flag for binary files    |
| readeol, reol       | One of  | buf    | newline mode when reading   |
| writeeol, weol      | One of  | global | newline mode when writing   |
| bufchars, bc        | Number  | buf    | number of characters        |
| buflines, bl        | Number  | buf    | number of lines             |
| partiallastline, pll| Boolean | buf    | file didn't end with newline|
| errlines            | Number  | buf    | buflines when :make was run |
| internal            | Boolean | buf    | Elvis requires this buffer  |
| putstyle, ps        | One of  | buf    | type of text in a cut buffer|
^---------------------^---------^--------^-----------------------------^

binary, bin (Boolean, global)

The binary option indicates whether Elvis was invoked with the "-b" flag for working with binary files. It affects the way the default readeol value is chosen for new buffers. If binary, then readeol=binary. If nobinary readeol=text except that the default elvis.brf file will try to guess a better value . the default is nobinary.

readeol, reol (One of, buf)

The readeol option determines how Elvis reads the file into a buffer. It can be one of the following:

• unix - The file is opened in binary mode, and any Line Feed characters in the file are converted to newline characters in the buffer.
• dos - The file is opened in binary mode, and any Carriage Return/Line Feed pairs from the file are converted to newline characters in the buffer.
• mac - The file is opened in binary mode, and any Carriage Return characters from the file are converted to newline characters in the buffer.
• text - The file is opened in text mode, and no other conversion takes place.
• binary - The file is opened in binary mode, and no conversion takes place.

The compiled-in default is "binary" or "text", depending on the binary option, but the standard elvis.brf file may change "text" to a file-dependent value via the fileeol() function.

writeeol, weol (One of, buf)

The writeeol option influences how Elvis writes buffers out to a file. If a buffer's readeol option is set to "binary", then the value of writeeol is ignored for that buffer; the file will be written in binary. Otherwise it can be one of the following to determine the output format:

• unix - The file is opened in binary mode, and newlines are written out as Line Feed characters.
• dos - The file is opened in binary mode, and newlines are written out as Carriage Return/Line Feed pairs.
• mac - The file is opened in binary mode, and newlines are written out as Carriage Return characters.
• text - The file is opened in text mode, and no conversion takes place.
• binary - The file is opened in binary mode, and no conversion takes place.
• same - The value of the readeol option is used to control the output format.

The default value is "same". You might want to change that to some other mode to force the file to be written in a specific format; for example, setting it to "text" will cause a non-binary file to be written in the local text format.

bufchars, bc (Number, buf)
buflines, bl (Number, buf)

The bufchars and buflines options indicate the number of characters and lines in the buffer, respectively. The buflines option works by counting newline characters; it is unaffected by vagaries of the display mode. These options can't be set.

partiallastline, pll (Boolean, buf)

The partiallastline option indicates whether the file's last line ended with a newline. Text files should always end with a newline. Traditionally, when vi loaded a file that contained a partial last line, it would append a newline to the edit buffer to complete that last line. The extra newline would be written out when the buffer was saved to a file. That's great for vi, but Elvis can edit binary files as well as text, and appending newlines onto binary files could cause some problems. So Elvis appends a newline just like vi, but also sets the partiallastline option to remind itself that when the buffer is saved in binary mode, the last newline should be omitted. Also, the hex display mode is smart enough to hide the added newline when this option is set.

errlines (Number, buf)

The errlines option is used to store the number of lines that were in the buffer when the last :make or :cc command was run. Any difference between buflines and errlines is used to adjust the line numbers reported in any error messages, to compensate for lines which have been inserted or deleted since then.

internal (Boolean, buf)

The internal option indicates that Elvis uses the buffer internally. Such buffers can't be deleted.

putstyle, ps (One of, buf)

The putstyle option is only relevant for cut buffers. It indicates whether the cut buffer contains characters, whole lines, or a rectangular area. It is set automatically whenever you yank or cut text into a cut buffer; when you put (paste) the contents of that buffer, Elvis checks the value of this option to determine how the text should be inserted into your edit buffer.

6.4 Options that affect movement commands

.---------------------.---------.--------.-----------------------------.
| OPTION NAMES        | TYPE    | GROUP  | DESCRIPTION                 |
|---------------------|---------|--------|-----------------------------|
| matchchar, mc       | String  | global | characters matched by %     |
| paragraphs, para    | String  | buf    | nroff paragraph commands    |
| sections, sect      | String  | buf    | nroff section commands      |
| tweaksection, twks  | Boolean | global | allow text before { section?|
| sentenceend, se     | String  | global | punct at end of sentence    |
| sentencequote, sq   | String  | global | punct allowed after se      |
| sentencegap, sg     | Number  | global | spaces required after sq    |
| scroll, scr         | Number  | win    | scroll amount for ^D/^U     |
^---------------------^---------^--------^-----------------------------^

matchchar, mc (String, global)

The matchchar option stores a list of matching character pairs, for use by the % visual command. In each pair, the first character should be an opening parenthesis (or whatever) and the second character should be the corresponding closing parenthesis. If both characters are identical, then the % command will try to guess whether it should search forward or backward. The default value is mc=[]{}(), but you may wish to add :set mc=[]{}()<>\"\" to your ~/.exrc (or ~/elvis.rc) file.

If your copy of Elvis was compiled with text objects enabled (i.e., if :calc feature("textobj") returns true) then the matchchar option may also contain the names of text objects. The most useful example of this is probably :set mc=[]{}()ax which allows the % command to bounce between the endpoints of an XML tag pair.

paragraphs, para (String, buf)
sections, sect (String, buf)

The paragraphs option stores a list of two-letter nroff paragraph commands. This list is used by the { and } movement commands. Similarly, the sections option stores a list of section commands, affecting the [[ and ]] commands. Their defaults are paragraphs="PPppIPLPQP" and sections="NHSHSSSEse".

tweaksection, twks (Boolean, global)

In addition to the sections option described above, the [[, ]], and gd 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 :alias syntax uses this style. To support this style, Elvis normally tweaks the definition of a section to allow any unindented text to appear before the '{' character.

The tweaksection option is normally on, so Elvis allows unindented text before the '{'. Turning it off will cause Elvis to use the traditional definition of sections.

sentenceend, se (String, global)
sentencequote, sq (String, global)
sentencegap, sg (Number, global)

The sentenceend, sentencequote, and sentencegap options all affect the ( and ) sentence motion commands. The sentenceend option is a list of punctuation characters which can appear at the end of a sentence. The sentencegap option is the number spaces that must follow a sentenceend character in order for it to count as the end of a sentence. The sentencequote option is a list of punctuation characters that can appear between the sentenceend character and the spaces. Their defaults are sentenceend="?!.", sentencequote=")\"", and sentencegap=2, which meets the proposed POSIX specifications.

scroll, scr (Number, win)

The scroll option indicates the number of lines that the ^U and ^D commands should scroll the screen by. Its default value is 12.

6.5 Options that affect input mode

.---------------------.---------.--------.-----------------------------.
| OPTION NAMES        | TYPE    | GROUP  | DESCRIPTION                 |
|---------------------|---------|--------|-----------------------------|
| autoindent, ai      | Boolean | buf    | auto-indent new text        |
| inputtab, it        | One-Of  | buf    | input mode's (Tab) key      |
| smarttab, sta       | Boolean | global | if indenting, (Tab) shifts  |
| completebinary, cob | Boolean | global | complete names of binaries? |
| autotab, at         | Boolean | buf    | allow autoindent to use '\t'|
| tabstop, ts         | Tab-List| buf    | widths of tabstop columns   |
| shiftwidth, sw      | Tab-List| buf    | width used by < and >       |
| textwidth, tw       | Number  | buf    | width for word-wrap, or 0   |
| wrapmargin, wm      | (weird) | win    | set textwidth from right    |
| digraph, dig        | Boolean | global | allow X-backspace-Y entry   |
| cleantext, ct       | Packed | global | Rules for erasing old text  |
^---------------------^---------^--------^-----------------------------^

autoindent, ai (Boolean, buf)

Setting the autoindent option causes Elvis to automatically insert whitespace at the start of each line, to make it line up with the preceding line. This is convenient when you're editing C source code. It is off by default.

inputtab, itab (One-Of, buf)

The inputtab option controls the behavior of the Tab key. It can be set to one of the following values:

• tab - insert an actual tab character. This is the traditional vi behavior, and the default for user buffers.
• spaces - insert enough space characters to look like a tab character.
• filename - attempt filename completion on the preceding word. Normally this only completes the names of text files, but you can set the completebinary option to allow binary file names to be completed too.
• identifier - 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.
• ex - a smarter version of filename completion, it knows enough about ex command line syntax to avoid some tabbing mistakes that the filename setting can make. It can also complete ex command names, tag names, option names, and option values. This is the default for the (Elvis ex history) buffer, which is used for entering in ex commands.

smarttab, sta (Boolean, global)

The smarttab option only affects the behavior of the Tab 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 Tab is treated like ^T, so the line is shifted rightward by one shiftwidth. By default this option is false, so the Tab key is treated normally (in accordance with the inputtab option).

completebinary, cob (Boolean, global)

The completebinary option controls whether binary files are included in the list of possible filename completions. The default setting is nocompletebinary, so binary files are omitted. This is handy when you're editing source code -- if your directory contains "foo.c" and "foo.o" (or "FOO.OBJ" in the Land of the Lost), then typing f-o-o-TAB will complete the "foo.c" name.

autotab, at (Boolean, buf)

The autotab option affects the behavior of the < and > operator commands, and the ^D and ^T input mode keystrokes. If autotab is true then Elvis will include tab characters in the indentation whitespace; if it is false then the indentation whitespace will consist entirely of space characters. By default, it is true.

Note that if you start with a buffer which contains no tabs, and do a ":set inputtab=spaces noautotab" then no amount of editing will result in the buffer containing tabs... unless you get tricky with ^V or something.

tabstop, ts (Tab-List, buf)

The tabstop option affects the way tab characters are displayed, by specifying how far apart the tab stops should be located. When Elvis displays a file with tabs, it displays the tabs as a variable number of spaces. 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 shiftwidth and maybe setting inputtab=spaces and smarttab.

shiftwidth, sw (Tab-List, buf)

The shiftwidth option indicates how far left or right the < and > operator commands (and the ^D and ^T input mode keystrokes) should shift the line of text. This is used for adjusting the indentation of lines. 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 < 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 > it would be indented 9 spaces (1 space into the third shift zone). The default value is "8".

textwidth, tw (Number, buf)

When editing a text file in "normal" display mode, the textwidth option can be used to cause word-wrap to occur when a line gets too long. The default value of textwidth is 0, which disables automatic word-wrap. Setting it to any larger value causes word-wrap to occur when text is inserted into a line, causing that line to become wider than textwidth columns. (Note that this has nothing to do with the display formatting of the "html" and "man" display modes.)

wrapmargin, wm (Boolean, win)

The wrapmargin option is provided for backwards compatibility. It allows you to set the textwidth relative to the right edge of the window, instead of the left edge. This option's value is actually derived from the textwidth option's value and the window's width (the columns 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.

digraph, dig (Boolean, global)

Digraphs allow you to enter non-ASCII characters via a combination of two ASCII characters. There are two ways to enter digraphs: ^K X Y and X backspace Y. The second form can cause some confusion if you're not expecting it, so the digraph option was created as a way to disable that second form. The first form of digraphs is always available. This option is false by default, to avoid the confusion.

cleantext, ct (Packed, global)

The cleantext option tells Elvis when it should remove old text. All old text goes away when you exit input mode, 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 cleantext is a comma-delimited list of rule names, taken from the following table. For example, ":se cleantext=long,bs,ex" causes backspaced-over characters to be erased immediately, or at the start of a long change. The default value is simply "long".

bs	Erase text when <Backspace>, ^H, or ^U is pressed.
short	Erase old text at the start of a short change (the c operator, or related commands). A short change is one in which the old text doesn't contain any newlines.
long	Erase old text at the start of a long change. A long change is one in which the old text contains at least one newline.
input	Erase old text whenever a new keystroke is inserted into the text.
ex	Erase text when <Backspace>, ^H, or ^U is pressed while entering a command line or regular expression. This is similar to bs but for command lines instead of the main buffer.

6.6 Ex options

.---------------------.---------.--------.-----------------------------.
| OPTION NAMES        | TYPE    | GROUP  | DESCRIPTION                 |
|---------------------|---------|--------|-----------------------------|
| prompt              | Boolean | global | issue ":" prompt in ex mode |
| autoprint, ap       | Boolean | global | print current line in ex    |
| report              | Number  | global | minimum # lines to report   |
| optionwidth, ow     | Number  | global | widths of ":set all" values |
| filenamerules, fnr  | Packed  | global | how to parse file names     |
^---------------------^---------^--------^-----------------------------^

prompt (Boolean, global)

The prompt option controls whether a ":" prompt is issued before reading each command line in EX mode. It is true by default, and should usually be left that way.

autoprint, ap (Boolean, global)

The autoprint option causes Elvis to display the current line of the edit buffer in certain circumstances, while you're in EX mode. It is true by default.

report (Number, global)

The report option determines the minimum number of lines that must change in a file, before Elvis will bother to display a count of the changed lines. As a special case, if report=0 then it won't report any changes, or failed :s/old/new/ commands. Its default value is 5, so small changes won't be reported but big ones will.

optionwidth, ow (Number, global)

optionwidth sets a limit on how wide a single option can be when output by a ":set" or ":set all" command. Limiting the widths is a good idea, because otherwise a single option that has a long value could force the output to use fewer columns, forcing some options scrolling off the top of the screen before you can read them. The ":set" command likes to leave at least two spaces after each column. The default value is optionwidth=24, which guarantees that at least 3 columns can fit on an 80-character terminal, since 80/(24+2)=3. Note that optionwidth has no effect on options that you explicitly name in a ":set" command; for example, ":set tags?" will show you the entire tag path regardless of the value of optionwidth.

filenamerules, fnr (Packed, global)

The filenamerules option controls the way file names are parsed and processed. Its value is a comma-delimited list of keywords, taken from the following list.

    .----------.----------------------------------------------.
    | KEYWORD  | WHAT IT DOES                                 |
    |----------|----------------------------------------------|
    | dollar   | $VARIABLE for environment vars               |
    | paren    | (expression) evaluation                      |
    | space    | <space> 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 then with <Tab>.

6.7 Window statistics

.---------------------.---------.--------.-----------------------------.
| OPTION NAMES        | TYPE    | GROUP  | DESCRIPTION                 |
|---------------------|---------|--------|-----------------------------|
| windowid, id        | Number  | win    | ID number of current window |
| columns, cols       | Number  | win    | width of window             |
| lines, rows         | Number  | win    | height of window            |
| eventcounter, evct  | Number  | win    | when window was last used   |
^---------------------^---------^--------^-----------------------------^

windowid, id (Number, win)

The windowid option stores the ID number of the current window. These window IDs are listed by the :buffer command. Some GUIs may also display the window ID as part of the window's title. This value is set to a unique value automatically when the window is created. You can't change it.

columns, cols (Number, win)
lines, rows (Number, win)

The columns and lines options indicate the size of the window.

eventcounter, evct (Number, win)

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 eventcounter option of the current window. The ^W^W command uses this option to determine which two windows are the "most recently used", so it can toggle between them.

6.8 Options affecting the appearance of text

.---------------------.---------.--------.-----------------------------.
| OPTION NAMES        | TYPE    | GROUP  | DESCRIPTION                 |
|---------------------|---------|--------|-----------------------------|
| list, li            | Boolean | win    | show markups, newlines, etc.|
| listchars, lcs      | Packed  | global | controls the "list" option  |
| showmarkups, smu    | Boolean | global | show markup at cursor       |
| bufdisplay, bd      | String  | buf    | default display mode        |
| initialsyntax, isyn | Boolean | buf    | start in "syntax" mode?     |
| prefersyntax, psyn  | String  | global | when to set initialsyntax   |
| display, mode       | String  | win    | name of current display mode|
| number, nu          | Boolean | win    | display line numbers        |
| ruler, ru           | Boolean | win    | display cursor's line/column|
| guidewidth, gw      | Tab-list| buf    | draw vertial lines on screen|
| hlobject, hlo       | String  | buf    | type of object to highlight |
| hllayers, hll       | Number  | win    | how many layers to highlight|
| background, bg      | One-of  | global | assumed background color    |
| folding, fold       | Boolean | win    | enable folding              |
| show                | String  | global | what to show on bottom row  |
| showmatch, sm       | Boolean | win    | highlight matching parens   |
| showmode, smd       | Boolean | win    | display the command state   |
| nonascii, asc       | One-Of  | global | how to display non-ascii    |
| showstack, sstk     | Boolean | win    | display some debugging info |
^---------------------^---------^--------^-----------------------------^

list, li (Boolean, win)

In the "normal" or "syntax" display modes, the list option causes tabs and newlines to be visible, under the influence of the listchars option. In "html", "man", or "tex" mode, it causes all of the markups to be displayed.

listchars, lcs (Packed, global)

This option is only effective if feature("listchars") returns true. It alters the effect of the list option, and can also cause markers to be shown when sidescrolling is active if the wrap option is off. The value is a comma-delimited list of "name:value" pairs, as follows:

NAME	HOW THE VALUE IS USED
eol	Marks the end of the line. If omitted, then there is no mark at the end of the line.
tab	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 ^I, and do not fill the tabstop.
trail	Appearance of trailing spaces at the end of the line. Like tab, this is truncated or stretched to be as wide as the spaces. If omitted, then trailing spaces will simply be displayed as spaces.
ff	Alternate form of the FormFeed character. If omitted, FormFeed will be displayed as ^L.
cr	Altername form of the CarriageReturn character. If omitted, CarriageReturn will be displayed as ^M.
esc	Alternate form of the Escape character. If omitted, Escape will be displayed as ^[.
bs	Alternate form of the Backspace character. If omitted, Backspace will be displayed as ^H.
del	Alternate form of the Delete character. If omitted, Delete will be displayed as ^?.
nul	Alternate form of the Null character. If omitted, Null will be displayed as ^@.
precedes	When wrap is off and you've scrolled horizontally, this marker is displayed at the left edge of non-empty lines.
extends	When wrap is off, this marker is displayed at the right edge of lines that extend past the edge of the window.
markup	In the html, man, and tex display modes, the list option will cause all markups to be displayed if the listchars contains "markup". This field has no ":value" component.

A typical example is ":set lcs=eol:[EOL],tab:[TAB]-", which makes the newline marker look like "[EOL]", and tabs look like "[TAB]---". The default value is "eol:$" which makes the list option look exactly like it does in the traditional vi.

In the normal and syntax display modes, the eol marker is displayed in the "nontext" typeface, the precedes and extends markers are displayed in the "extends" typeface, and all others are displayed in the "specialkey" face. In the html, man, and tex display modes, markups are displayed in the "markup" face. You can adjust the appearance of these faces via the :color command.

NOTE: You can scroll sideways by clicking on the precedes and extends 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.

showmarkups, smu (Boolean, global)

In "html" or "man" mode, the showmarkups option causes the markup at the cursor to be displayed, but leaves other markups hidden. It has no effect in other display modes. This option is off by default, so markups won't suddenly become visible as you move the cursor around.

bufdisplay, bd (String, buf)

Each buffer has a bufdisplay option, which indicates that buffer's preferred display mode. You should set bufdisplay to the name of a supported display mode: normal, syntax, html, man, tex, or hex. The compiled-in default is normal but the standard elvis.arf file tries to choose a more clever default, based on the extension of the buffer's filename.

For syntax, the exact syntax used normally depends on the filename's extension. 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:

	:set bufdisplay="syntax c++"

initialsyntax, isyn (Boolean, buf)

Whenever a new window is created, or an existing window switches buffers, its display mode is set to either "syntax" if initialsyntax is true, or to the value of the bufdisplay option otherwise. This option is normally false, so that HTML documents are shown formatted, but the default elvis.arf file tries to choose a better value, using the prefersyntax option for guidance.

NOTE: The :mkexrc command never stores the value of this option permanently. This is intentional; you may want different buffers to have their initialsyntax option set or cleared, depending on the type of text in it, but the initialization file created by :mkexrc only stores one value for each option. You should set the prefersyntax option instead.

prefersyntax, psyn (String, global)

The prefersyntax option has no hardcoded meaning, but the default elvis.arf file uses it to turn initialsyntax on or off. You can set prefersyntax to one of the following:

.----------.------------------------------------------------------.
|  VALUE   | WHEN INITIALSYNTAX WILL BE SET                       |
|----------|------------------------------------------------------|
| 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 |
^----------^------------------------------------------------------^

display, mode (String, win)

The display option indicates which display mode the window is currently in. You can't set this option directly; you must use the :display command instead.

number, nu (Boolean, win)

The number option causes a line number to be prepended to the start of each line. The line numbers are defined as "one plus the number of newlines preceding the start of the line," which is not necessarily how the current display mode defines lines. Consequently, the line numbers may not increment by 1 every time. These line numbers do correspond to the ruler and the visual G command, though. This option is false by default.

ruler, ru (Boolean, win)

The ruler option causes the current line number and column number to be displayed at the bottom of the screen. This uses the same definition of "line number" as the number option, above. This option is false by default.

guidewidth, gw (Tab-list, buf)

The guidewidth 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 tabstop and shiftwidth options. The lines can be hidden again by setting guidewidth to an empty list. This option is only effective in the normal and syntax display modes.

In graphical user interfaces, the color of the guide lines can be set by ":color guide colorname". The following map causes the <F4> key to display a guide line at the cursor column:

	:map #4 :let gw=current("column")-1,columns^M

hlobject, hlo (String, buf)

The hlobject 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 text object, but you can also set it to a whole list of objects 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. (For example, hlobject="Va{" will highlight whole lines via brace-delimited blocks.) If you set hllayers to more layers than you've defined in this option, then the last object type will be repeated with increasing counts. The default value is "" which inhibits highlighting. For highlighting to occur, you must set both hlobject to a valid object name, and hllayers to a non-zero value.

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

hllayers, hll (Number, win)

The hllayers option specifies how many objects (as defined by the hlobject option) should be highlighted around the cursor. The default value is 0, which disables highlighting. Changing it to 1 (and setting hlobject 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 :color command to set these up.

background, bg (One of, global)

The background option does not change the background color! It may affect the choices that Elvis makes for foreground colors though, if all of the following are true:

• You're using a non-graphical user interface such as the the termcap interface. For graphical interfaces, Elvis knows the real background color and makes its choices from that.
• You have not explicitly set the normal background color. In other words, your background should be the terminal's default background color.
• You have configured extra possible foreground colors by using the "or color" clause in a :color 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.

NOTE: In expressions, you can use current("background") 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 background option.

folding, fold (Boolean, win)

Folded regions 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 folding 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.

show (String, global)

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:

.---------.-----------------------------------------------------.
| KEYWORD | WHAT IT SHOWS                                       |
|---------|-----------------------------------------------------|
| file    | value of the current buffer's filename or bufname   |
| tag     | name of tag 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 :color)     |
| link    | destination of an HTML link at the cursor position  |
| spell   | suggested corrections for a misspelled word         |
| region  | comment of current region (as used by :region)      |
^---------^-----------------------------------------------------^

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.

Using the "tag" keyword, by the way, may cause Elvis to load files more slowly. 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.

The "spell" keyword only works if the spell option is set. Also, it works better if the whole spelling dictionary has been loaded into memory, so you should either set the spellautoload option or explicitly invoke the :wordfile command if you want to use it.

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 show value into segments, and Elvis will only show the first segment which actually has something to show you.

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.

showmatch, sm (Boolean, win)

The showmatch option helps you locate matching parentheses. When you're in input mode, and you type a ), ], or } character, Elvis will cause the matching (, [, or { character to be highlighted on the screen. This option is false by default.

showmode, smd (Boolean, win)

The showmode option causes Elvis to display a one-word label for its current parse state in the lower right-hand corner of the window. Usually, this will be either "Command" or "Input". This option is false by default, but I suggest you make it true because it really is handy.

nonascii, asc (One-Of, global)

The nonascii option tells Elvis how to display characters 0x80 through 0xff. It can have one of the following values:

   .-------.------------------------------------------------.
   | VALUE | MEANING                                        |
   |-------|------------------------------------------------|
   | all   | All characters 0x80-0xff are visible           |
   | most  | Chars 0xa0-0xff are visible, but not 0x80-0x9f |
   | none  | Chars 0x80-0xff are not visible                |
   | strip | Convert 0xa0-0xfe to ASCII; others not visible |
   ^-------^------------------------------------------------^

Any characters which aren't visible will be displayed as '.' characters. Note that this only affects the way the characters are displayed; they are actually stored with their true 8-bit value. The default value of nonascii is "most", because that is the correct value for the Latin-1 symbol set.

showstack, sstk (Boolean, win)

The showstack option causes some debugging output to appear on the bottom row of the window. It is false by default, and you should leave it that way.

6.9 Options for a particular display mode

.---------------------.---------.--------.-----------------------------.
| OPTION NAMES        | TYPE    | GROUP  | DESCRIPTION                 |
|---------------------|---------|--------|-----------------------------|
| includepath, inc    | String  | syntax | where to find #include files|
^---------------------^---------^--------^-----------------------------^

includepath, inc (String, syntax)

The includepath option contains a list of directory names where Elvis should look for #include files. When you look up a tag whose name begins with a quote character, Elvis searches through those directories for a file with the same name as the tag (with the quotes stripped off). This means that you can move the cursor onto a #include file name, hit ^], and have Elvis load the indicated header file. The default value is taken from the INCLUDE environment variable if set, or an OS-dependent value otherwise.

6.10 Spell-checking options

.---------------------.---------.--------.-----------------------------.
| OPTION NAMES        | TYPE    | GROUP  | DESCRIPTION                 |
|---------------------|---------|--------|-----------------------------|
| spell, sp           | Boolean | buf    | highlight misspelled words  |
| spelldict, spd      | String  | global | name of dictionary file     |
| spellautoload, sal  | Boolean | global | load whole dict when needed |
| spellsuffix, sps    | String  | global | list of suffixes            |
^---------------------^---------^--------^-----------------------------^

spell, sp (Boolean, buffer)

When set, the spell option causes misspelled words to be highlighted via the "spell" face. You can adjust the highlighting style via the ":color spell ..." command. The default is nospell, which disables all spell-checking.

spelldict, spd (String, global)

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

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 /usr/dict/words file which works well. If you set spelldict to the name of a non-existent or unreadable file, then Elvis will reset it "".

NOTE: 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 :words command.

spellautoload, sal (Boolean, global)

The spellautoload option causes the whole spelling dictionary (identified by spelldict option) to be loaded into memory the first time you call the spell() function, or move the cursor onto a misspelled word while the show 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. However, loading the whole dictionary takes some time (usually about 1 second) and memory (about 1 megabyte) so you may prefer to load the dictionary explicitly ahead of time via the :wordfile command.

spellsuffix, sps (String, global)

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.

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 "suffix=replacement" to replace the suffix with some other text. For example, spellsuffix="ies=y" would be able to convert "flies" into the root word "fly".

One important detail of the spellsuffix 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 spellsuffix option won't cause any words that are currently marked as misspelled to be rechecked and marked as correct.

Another quirk of spellsuffix is that it doesn't work on case-sensitive root words that you add via the :words 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.

The compiled-in default value is "", but the default configuration files (mostly the elvis.spe file) change that to something that works well for English text.

6.11 Messages

.---------------------.---------.--------.-----------------------------.
| OPTION NAMES        | TYPE    | GROUP  | DESCRIPTION                 |
|---------------------|---------|--------|-----------------------------|
| terse, te           | Boolean | global | don't translate messages    |
| verbose             | Numeric | global | give more status messages   |
| errorbells, eb      | Boolean | global | ring bell for error message |
| warningbells, wb    | Boolean | global | ring bell for warning msg   |
| flash, vbell        | Boolean | global | substitute flash for bell   |
^---------------------^---------^--------^-----------------------------^

terse, te (Boolean, global)

The terse option indicates whether Elvis should attempt to translate messages via the elvis.msg file. If terse is true, then no such translation takes place; the built-in messages are used. If terse is false, then Elvis will search through the file (actually the "Elvis messages" buffer) for a line which looks like "terse:verbose" and if found it'll use the verbose version instead. By default, terse is false.

verbose (Boolean, global)

The verbose option has nothing to do with the terse option. Instead, it indicates the number of -V flags given when Elvis was invoked. Larger values indicate that the user wants more status messages to be generated. This is handy when Elvis isn't initializing itself the way you expected it to; Elvis' initialization code frequently tests the value of verbose and automatically writes status messages when verbose is set to a high enough level. Values normally range from 0 (no extra output) to 9 (maximum output).

errorbells, eb (Boolean, global)
warningbells, wb (Boolean, global)

The errorbells and warningbells options cause the terminal's bell to ring when an error message or warning message is generated, respectively. By default the errorbells option is true, and the warningbells option is false.

flash, vbell (Boolean, global)

Setting the flash option causes Elvis to use a visible alternative to the bell, if one exists. This is nice in a crowded terminal room. By default this option is false.

6.12 Words

.---------------------.---------.--------.-----------------------------.
| OPTION NAMES        | TYPE    | GROUP  | DESCRIPTION                 |
|---------------------|---------|--------|-----------------------------|
| true, True          | String  | global | locale's True value         |
| false, False        | String  | global | locale's False value        |
| submit, Submit      | String  | x11    | locale's Submit label       |
| cancel, Cancel      | String  | x11    | locale's Cancel label       |
| help, Help          | String  | x11    | locale's Help label         |
^---------------------^---------^--------^-----------------------------^

true, True (String, global)
false, False (String, global)

The true and false options exist primarily to allow the english words true and false to be used in expressions to represent Boolean literals. Also, the value of false is used as an alternative false string, in addition to "", "0", or "false". (In a Boolean context, any string that isn't false is considered to be true, so Elvis never compares a string to the true option's value.) A Boolean option will return the value of either the true or false option, as appropriate.

submit, Submit (String, global)
cancel, Cancel (String, global)

If you're using the "x11" user interface, then values of the submit and cancel options are used as the labels for the [Submit] and [Cancel] buttons in a dialog. Also, if the dialog contains any Boolean options, the value will be displayed using values of the true and false options.

help, Help (String, global)

Currently the help option does nothing. Eventually I expect to add pull-down menus to the "x11" interface, though, and in Motif menu bars the "Help" menu traditionally appears on the far right edge. The value of the help option will allow Elvis to recognize the "Help" menu.

6.13 Options for a particular user interface

.---------------------.---------.--------.-----------------------------.
| OPTION NAMES        | TYPE    | GROUP  | DESCRIPTION                 |
|---------------------|---------|--------|-----------------------------|
| term, ttytype       | String  | tcap   | terminal's termcap entry    |
| ttyrows, ttylines   | Number  | tcap   | height of screen            |
| ttycolumns, ttycols | Number  | tcap   | width of screen             |
| ttyunderline, ttyu  | Boolean | tcap   | okay to mix color & underln |
| ttyitalic, ttyi     | Boolean | tcap   | okay to use "dim" for italic|
| ttywrap, ttyw       | Boolean | tcap   | trust termcap's line wrap   |
| codepage, cp        | Number  | win32  | console character set       |
|---------------------|---------|--------|-----------------------------|
| scrollbar, sb       | Boolean | (gui)  | enable the scrollbar        |
| toolbar, tb         | Boolean | (gui)  | enable the toolbar          |
| statusbar, stb      | Boolean | (gui)  | enable the statusbar        |
| scrollwheelspeed,sws| Number  | (gui)  | adjust speed of scroll wheel|
| scrollbgimage, sbi  | Boolean | (gui)  | scroll background image     |
| font, fnt           | String  | (gui)  | base font                   |
| iconimage, ii       | String  | (gui)  | window icon                 |
|---------------------|---------|--------|-----------------------------|
| menubar, mb         | Boolean | windows| enable the menubar          |
| titleformat, title  | Boolean | windows| window title                |
|---------------------|---------|--------|-----------------------------|
| boldfont, xfb       | String  | x11    | name of bold font           |
| italicfont, xfi     | String  | x11    | name of italic font         |
| controlfont, xfc    | String  | x11    | name of toolbar font        |
| xencoding, xe       | String  | x11    | registry & encoding of fonts|
| scrollbarleft, xsl  | Boolean | x11    | enable scrollbar on side    |
| scrollbarwidth, xsw | Number  | x11    | size of scrollbar, in pixels|
| scrollbartime, xst  | Number  | x11    | delay for scrollbar repeat  |
| borderwidth, xbw    | Number  | x11    | size of text area's border  |
| dblclicktime, xdct  | Number  | x11    | double-click speed, 1/10 Sec|
| blinktime, xbt      | Number  | x11    | cursor blink rate, 1/10 Sec |
| textcursor, tc      | Number  | x11    | one of hollow, opaque, xor  |
| synccursor, xsync   | Boolean | x11    | avoid partial characters    |
| xrows, xlines       | Number  | x11    | height of new windows       |
| xcolumns, xcols     | Number  | x11    | width of new windows        |
| firstx, xpos        | Number  | x11    | horiz. position of first win|
| firsty, ypos        | Number  | x11    | vert. position of first win |
| stagger             | Number  | x11    | offset for next new window  |
| icon                | Boolean | x11    | use the built-in icon?      |
| iconic              | Boolean | x11    | windows start out iconified |
| stopshell, ssh      | String  | x11    | interactive shell command   |
| autoiconify, aic    | Boolean | x11    | iconify old window          |
| altkey, metakey     | One of  | x11    | effect of the Alt key       |
| focusnew, fn        | Boolean | x11    | force focus into new window |
| warpto, wt          | One of  | x11    | ^W^W forces pointer movement|
| warpback, xwb       | Boolean | x11    | upon exit, point to xterm   |
| outlinemono, om     | Number  | x11    | char outlining for X11-mono |
| antialias, aa       | Boolean | x11    | use antialiased fonts       |
| aasqueeze, aas      | Boolean | x11    | reduce the gap between lines|
^---------------------^---------^--------^-----------------------------^

6.13.1 Termcap options

term, ttytype (String, tcap)
ttyrows, ttylines (Number, tcap)
ttycolumns, ttycols (Number, tcap)

The term, ttyrows, and ttycolumns options are only present if you're using the termcap user interface. They indicate the name of the termcap entry being used and the size of the screen.

The value of term is taken from the $TERM environment variable. ttyrows and ttycolumns are set from the $LINES and $COLUMNS 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 entry.

ttyunderline, ttyu (Boolean, tcap)

The ttyunderline option is only present if you're using the termcap interface. It indicates whether it is safe to try underlining text when colors have been assigned to fonts. The ttyunderline option is true by default, which allows Elvis to use underlining without restrictions of any kind.

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 ttyunderline. This will have two main effects:

• If you've set the background color via the ":color" command, then Elvis won't use underlining at all.
• 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.)

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

ttyitalic, ttyi (Boolean, tcap)

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 ttyitalic option gives you a way to disable this, so you can see colors on the screen, while still allowing the :lpr command to print italics. This option is true by default, but the elvis.ini file turns it off for the linux console.

If your terminal doesn't implement half-bright (via the :mh=: termcap field or dim terminfo field), then Elvis uses underlining to represent italics. Underlining is influenced by the ttyunderline option.

ttywrap, ttyw (Boolean, tcap)

Elvis normally tries to be smart about line-wrap, more so than most programs. But this only works right if the terminal's termcap/terminfo description is accurate. By default, ttywrap 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.

codepage, cpg (Number, win32)

The codepage option only exists in the Win32 version with the termcap interface (WindowsNT or Windows95, in console mode). It indicates which code page (character map) the console is using. Its value is persistent; if you change it in Elvis, the console will remain changed even after you exit Elvis. Changing the code page has no effect on the digraph table, or Elvis' idea of which non-ASCII characters are printable or should be treated as letters; it only reconfigures the console driver. Typical values are 437 for the standard IBM PC character set, and 850 for extra European characters.

6.13.2 Options common to Windows and X11

scrollbar, sb (Boolean, windows or x11)
toolbar, tb (Boolean, windows or x11)
statusbar, xstat (Boolean, windows or x11)

The scrollbar, toolbar, and statusbar options indicate whether the scrollbar, toolbar, and statusbar should be visible, respectively. By default, all are are visible.

scrollwheelspeed,sws (Number, windows or x11)

The scrollwheelspeed 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 How to section of the manual.)

scrollbgimage, sbi (Boolean, windows or x11)

If you're using a background image, then the scrollbgimage 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.

font (String, windows or x11)

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

In Windows the easiest way to set the font is via the "Options->Font" menu item. The default is "Courier new*10" in Windows.

In X11, the default is "" which is interpreted as meaning "fixed". ("fixed" is usually an alias for a small fixed-pitch font.) The elvis.ini script tries to choose an appropriate sized Courier font, though. You can also choose one yourself using the :courier alias. In the "x11" interface, changing font has the side-effect of resetting the boldfont and italicfont 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 xencoding option.

iconimage, ii (String, windows or x11)

The iconimage 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 data/icons/ directory. For example, ":set ii=elvis2" looks nice.

6.13.3 Windows options

menubar, mbar (Boolean, windows)

The menubar option indicates whether the menu bar should be visible. By default, it is visible.

titleformat, title (String, windows)

The titleformat option is used to control the format of the window's title. This is a value is an expression using the simpler expression syntax 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 titleformat="(dirfile($1)) - Elvis" 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 :e file command or something similar. Merely changing the titleformat option will not have any immediate effect on the window's title.

If you set a titleformat in your elvis.rc file, then its value will affect all windows that are created later. This is the most useful place to change titleformat. See the :mkexrc command.

boldfont, xfb (String, x11)
italicfont, xfi (String, x11)

The boldfont and italicfont options control the X fonts used for displaying bold and italic text. Typically, the elvis.ini or ".exrc" file will set these. If you do choose to set them in one of these files, be sure to have your initialization script check which interface is being used because if Elvis is using the termcap interface then these x11 options won't exist. These options both default to an empty string; this is a special case which causes Elvis to derive the bold and italic fonts from the normal font.

controlfont, xfc (String, x11)

The controlfont option determines which font is used for displaying the labels of toolbar buttons, and also the statusbar. Unlike the other fonts, this one is permitted to have a variable pitch. If it is unset, then Elvis will use the font named "variable" by default.

xencoding, xe (String, x11)

When font names are given in "fontname*size" 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.

antialias, aa (Boolean, x11)

This option only exists if Elvis was compiled with FEATURE_XFT defined (i.e., feature("xft") returns true). 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 (:set noantialias) will use the standard bitmapped fonts, which are usually uglier but can be drawn faster.

aasqueeze, aas (Number, x11)

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.

scrollbarleft, xsl (Boolean, x11)

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

scrollbarwidth, xsw (Number, x11)

The scrollbarwidth option controls the size of the x11 scrollbar. The default value is 14 pixels, and the allowed range is 5 to 40 pixels.

scrollbartime, xst (Number, x11)

The scrollbar buttons automatically repeat if you hold a mouse button down scrollbartime tenths of a second. The default is 4 tenths of a second.

borderwidth, xbw (Number, x11)

The main text area of a window looks better when the characters aren't drawn immediately adjacent to the edge. The borderwidth option allows you to specify how many pixels should be left blank between a character and any edge of the text area. The default is 1 pixel.

dblclicktime, xdct (Number, x11)

The dblclicktime option allows you to adjust the speed of mouse double-clicks to match your own clicking habits. The default is 3 tenths of a second.

blinktime, xbt (Number, x11)

The blinktime option controls the cursor blink rate. If set to 0, the cursor will not blink. If set to a value from 1 to 10, then the cursor will first be visible for that many tenths of a second, and then invisible for the same amount of time. The cursor will only blink in the window which currently has keyboard focus.

textcursor, tc (Number, x11)

The textcursor option controls the way the block text cursor is drawn. It can be xor, hollow, or opaque. The default is xor, which causes the cursor to be drawn as a filled rectangle with the XOR bitblt function. This converts the background color to the cursor color, and the foreground color to an unpredictable color; hopefully the foreground color will contrast with the cursor color well enough to allow you to discern what the underlying character is. The hollow cursor style causes the cursor to be drawn as an unfilled rectangle. This allows you to easily see the underlying character, and detect whether it is highlighted or not. The opaque cursor style draws a filled rectangle, which is easier to locate but you can only see the underlying character between blinks.

synccursor, xsync (Boolean, x11)

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 synccursor to fix it. (This bug is known to occur on XFree86 4.003 on a 3dfx Voodoo3 video card.)

xrows, xlines (Number, x11)
xcolumns, xcols (Number, x11)

The xrows and xcolumns options control the initial size of windows. They default to 34 and 80, respectively, and can also be set via the -geometry command-line flag. After a window has been created, you can use your window manager to resize the window.

firstx, xpos (Number, x11)
firsty, ypos (Number, x11)
stagger (Number, x11)

The firstx and firsty options, if set, control the position of the first window that Elvis creates. If they are unset, then Elvis doesn't specify a position for the window. The -geometry command-line flag can be used to set these options. After the first window has been created, if the stagger option is set to a non-zero value then any new windows are created that many pixels down and to the right of the current window. If stagger is zero, then Elvis won't specify a position for the new windows, so the window manager can choose the location itself.

icon (Boolean, x11)

The icon option can only be set in an initialization file such as elvis.ini or ".exrc"; once the first window has been created it is too late to change it. This option controls whether the window will be given the default, built-in icon. It is true by default, so windows will get the icon. This is usually a good thing. Some window managers don't allow you to override built-in icons, though, so if you want your window manager to use a different icon for Elvis then you'll need to have a "set noicon" in your elvis.ini file.

iconic (Boolean, x11)

The iconic option tells Elvis whether new windows should be created in the iconfied state. The default is noiconic.

stopshell, ssh (String, x11)

The stopshell option stores a command which runs an interactive shell. It is used for the :shell and :stop ex commands, and the ^Z visual command. Normally, this is set to "xterm &" so you get a shell in a window. The "&" at the end of the command allows Elvis to continue responding to user input while the shell is running.

autoiconify, aic (Boolean, x11)

When the ^W^W visual command switches keyboard control to an X11 window which as been iconified, Elvis automatically deiconifies it. When it does this, if the autoiconify option is set then Elvis will iconify the previous window, so the number of iconified Elvis windows remains constant. By default, this option is false. Regardless of whether autoiconify is set, you can always use your window manager to iconify or deiconify windows manually.

altkey, metakey (One of, x11)

The altkey option controls the effect of the Alt or Meta keys. It can be set to either control-O, setbit, or ignore. The ignore value is self explanatory. If the option is set to control-O then the x11 interface will simulate a ^O keystroke before each actual keystroke. This is handy because if you're in input mode you can just hold down Alt/Meta to perform a series of visual commands. If the option is set to setbit then the x11 interface will set the most significant bit of each ASCII character while the Alt/Meta key is held down. Some other programs use this trick as a means of entering non-ASCII characters. (Elvis has a better way though; check out the :digraph command.) The default is setbit.

focusnew, fn (Boolean, x11)

The focusnew option causes Elvis to force input focus to switch to any newly created window, or to one which has been deiconified. It is true by default; making it false (":set nofocusnew") prevents Elvis from forcing a change of input focus in those two situations. Note that Elvis always forces a change of input focus when you give a command which switches windows, such as ^W^W.

warpto, wt (One of, x11)

The warpto option can cause Elvis to force the mouse pointer to move whenever you use keyboard commands such as ^W^W to switch from one Elvis window to another. There are two reasons you may wish to do this: either your window manager requires the pointer to be in a window for that window to receive keystrokes, or you want to have your X server automatically pan the screen to bring the next window into view.

You can set the warpto option to any one of the following values: don't, scrollbar, origin, or corners. The default is don't which prevents any automatic pointer movement. The scrollbar value causes the pointer to move to the scrollbar, and origin moves it to the upper-left corner. The corners value causes the pointer to move first to the corner furthest from the window's text cursor, and then to the nearest corner; this will cause the X server to pan (if necessary) to bring the entire window into view.

warpback, xwb (Boolean, x11)

The warpback option, if set, causes the X terminal's graphic cursor to be moved back to the window which held keyboard focus at the time when Elvis was started. Usually this will be the xterm where you typed in the "elvis files..." command line. Just as the firstx, firsty, and stagger options are intended to allow mouseless positioning of Elvis windows, the warpback option is intended to serve as a mouseless way to switch keyboard focus back to the original xterm, so that mouse haters will find Elvis' x11 interface as convenient to use as the termcap interface. By default, warpback is false.

outlinemono, om (Number, x11)

The outlinemono option affects the way that text is drawn against a stippled background when Elvis is run on monochrome X terminals (or with the -mono command-line flag). It has no effect on color systems. Because characters drawn on a stippled background can be hard to read, Elvis can draw a white outline around the black characters. The value of outlinemono is a number that indicates how thick the outline should be. 3 is the thickest supported outline, and 0 is no outline at all. The default is 2.

6.14 Regular expression options

.---------------------.---------.--------.-----------------------------.
| OPTION NAMES        | TYPE    | GROUP  | DESCRIPTION                 |
|---------------------|---------|--------|-----------------------------|
| ignorecase, ic      | Boolean | global | uppercase matches lowercase |
| smartcase, scs      | Boolean | global | defeat ignorecase if upper  |
| magic, ma           | Boolean | global | use normal regexp syntax    |
| magicchar, mac      | String  | global | list of metacharacters      |
| magicname, man      | Boolean | global | allow $name substitution    |
| magicperl, map      | Boolean | global | Perl-compatible \b          |
| autoselect, as      | Boolean | global | visibly mark searched text  |
| hlsearch, hls       | Boolean | global | highlight all marches       |
| wrapscan, ws        | Boolean | global | searching wraps at EOF<->BOF|
| gdefault, gd        | Boolean | global | default change all instances|
| edcompatible, ed    | Boolean | global | remember regsub flags       |
| saveregexp, sre     | Boolean | global | remember regexp to use as //|
| incsearch, is       | Boolean | global | / and ? search incrementally|
^---------------------^---------^--------^-----------------------------^

ignorecase, ic (Boolean, global)

Setting the ignorecase option to true will cause Elvis to treat uppercase and lowercase letters as being equal, except in character list metacharacters. When ignorecase is false (the default), they are treated as different.

smartcase, scs (Boolean, global)

The smartcase option modifies the meaning of the ignorecase option so that if you type in a regular expression which contains uppercase letters, the search will be case sensitive. The smartcase option has no effect unless ignorecase is also set.

magic, ma (Boolean, global)

The magic 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 magic is true, the magicchar option allows some characters to be metacharacters without a backslash.

magicchar, mac (String, global)

The magicchar option gives you a way to tweak the syntax of Elvis' regular expressions. 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 magicchar value is a list of metacharacters that don't require a leading backslash.

The magicchar option has no effect unless the magic option is true. This is a good thing. Tag searches are always done in nomagic mode, so they're immune to any changes you make to magicchar.

The default value is "^$.[*", which makes Elvis mimic the traditional vi syntax. Some users may prefer to add "+?(){|", 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=^$.[*+?(){\|

Note that you never need to add "]" or "}"; they are implied by the corresponding "[" or "{" respectively. However, you do need to explicitly add ")" if you want it to be recognized without the backslash.

Warning: Changing magicchar 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:

• Put a \V metacharacter at the front of every regular expression. This will force the remainder of the expression to be interpreted using the traditional vi syntax.
• Add "local magicchar=^$.[*" to the top of each script or alias, to temporarily force magicchar back to its default value.
• Use the AliasEnter and ScriptEnter events to trigger an :autocmd 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=^$.[*

magicname, man (Boolean, global)

The magicname option enables the use of $name substitution in regular expressions, and the :s command's replacement text. Normally this option is off, so you can search for dollar signs easily. Aliases that compute regular expressions often use ":local magicname" to access their computed regular expression by name.

magicperl, map (Boolean, global)

The magicperl option changes the meanings of a few metacharacters to be more Perl-like. Currently this only changes the \b metacharacter to mean "edge of a word", instead of "backspace" (except in [charlist] metacharacters, where \b always means "backspace"). Future versions of Elvis are expected to change more metacharacters.

autoselect, as (Boolean, global)

The autoselect option, when true, causes a successful visual search command such as /regexp to visibly mark the matching text just like the v command does.

hlsearch, hls (Boolean, global)

The hlsearch option causes Elvis to highlight all instances of text which match the regular expression of the most recent / or ? visual command. The appearance of the highlighting is controlled by the :color hlsearch setting. Although highlighted, the matching text is not marked for later operations the way it would be with the v command or autoselect option.

wrapscan, ws (Boolean, global)

The wrapscan option determines what happens when a search command bumps into the top or bottom of a buffer. If wrapscan is true, then the search will wrap around to the other end of the buffer 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.

gdefault, gd (Boolean, global)

The gdefault option affects the default behavior of the :s/old/new/ command. It is false by default, which causes :s/old/new/ to assume an instance number of ".1" so only the first instance in each line is changed. Making gdefault true will cause a :s/old/new/ command to change all instances in each line, as though the "g" flag had been given. If you give an explicit instance number or "g" flag, then the value of gdefault is ignored.

edcompatible, ed (Boolean, global)

The edcompatible option causes Elvis to remember any flags that are passed into the :s/old/new/flags command, and use them as the default for the next such command. Explicitly naming a flag will toggle that flag's value. This is not the way the old ed editor worked, but this option's name and behavior are traditional in vi. This option is false by default.

saveregexp, sre (Boolean, global)

The saveregexp 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 n and N commands. You may wish to turn this option off temporarily in the lib/elvis.arf file if you're using any regular expressions there, so that loading a file doesn't interfere with n and N.

incsearch, is (Boolean, global)

The incsearch option affects the behavior of the vi / and ? search commands. incsearch is false by default.

When incsearch 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 input mode editing commands.

When incsearch 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 <Enter> key. The only special keystrokes available are:

.-----------.----------------------------------------------------.
| 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 Enter, Esc, or Backspace character.           |
^-----------^----------------------------------------------------^

The incsearch option interferes with the use of the / and ? commands as a destination for operators. To get around this, the incsearch option is temporarily disabled when executing an operator.

6.15 Tag options

.---------------------.---------.--------.-----------------------------.
| OPTION NAMES        | TYPE    | GROUP  | DESCRIPTION                 |
|---------------------|---------|--------|-----------------------------|
| taglength, tl       | Number  | global | significant length of tags  |
| tags, tagpath       | String  | global | list of possible tag files  |
| tagstack, tsk       | Boolean | global | remember origin of tag srch |
| tagprg, tp          | String  | global | external tag search program |
| smartargs, sa       | Boolean | buf    | show args when inputing func|
| tagkind, tk         | Boolean | global | highlight tags              |
| taglibrary, tlib    | Boolean | global | highlight library tags      |
^---------------------^---------^--------^-----------------------------^

taglength, tl (Number, global)

The taglength option defines how many characters are significant in a tag name. By default this option is set to 0, which is a special value indicating that all characters are significant. If you have a lot of long names, you might want to set this to some other value so that you could type in abbreviated names.

tags, tagpath (String, global)

The tags option stores a list of filenames or directory names where tags are stored. (For directory names, it looks for a file named "tags" in that directory.) When performing tag lookup, Elvis will begin by looking for it in the first directory/file mentioned in the list; if it doesn't find it there, then it moves on to the next one, and so on. By default, it just looks in a file named "tags" in the current directory.

In a path, names which start with "./" (or ".\" in MS-Windows) are assumed to be relative to the directory of the current file. This means that ":set tags=./tags:tags" will cause Elvis to first check the "tags" file in the directory of the current text file, and then the "tags" file in the current directory.

NOTE: Traditionally, 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 too. 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

tagstack, tsk (Boolean, global)

If the tagstack option is true, then before switching to the file and location of a looked-up tag, Elvis will store the original file and position on a stack. Later, you can use the :pop or visual ^T commands to return to your original position. If tagstack is false, then the tag stack is unaffected by tag look-up. It is true by default.

tagprg, tp (String, global)

If the tagprg option is set to any value other than "", then whenever you try to do a tag search via :tag or :browse, Elvis will execute tagprg's value as a shell command and interpret its stdout as a list of matching tags. Before the command is run, it is evaluated using the simpler expression syntax with $1 indicating where the arguments should go. The default value of tagprg is "" which causes Elvis to use the internal tag search algorithm.

NOTE: You might also consider using the ccprg option for this sort of thing, since the :cc command has a smarter line parser than the :tag command.

smartargs, sa (Boolean, buf)

The smartargs option causes Elvis to display the arguments to a function when you're inputting text. It only works in syntax display mode. When you type the function character, 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 <Esc> key, but it has no effect on keys you type or on the ultimate contents of the edit buffer.

tagkind, tk (Boolean, global)
taglibrary, tlib (Boolean, global)

The tagkind and taglibrary options cause tags to be displayed in distinctive faces. The name of the face is derived from the tag's "kind" attribute.

If the tagkind option is set, then the first time any given language's syntax description is loaded, Elvis reads through any tags files in the tagpath 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 "kindk" where k is the value of its "kind" attribute, or simply "kind" if the tag has no "kind" attribute. For example, your data types are displayed in the "kindt" face. You can use the :color command to change the appearance of the face.

	:color kindt underlined like keyword

The taglibrary option does the same thing, except that it looks for tags in the directories listed in the elvispath option, and the face names are of the form "libk". Generally, taglibrary is intended to be used with tags for stub files of libraries.

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.

Because tagkind and taglibrary 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 taglibrary, this doesn't matter since libraries don't change much, but for tagkind it can be annoying. You might want to consider using the spell option instead of tagkind.

Also, since setting these options will not cause Elvis to reload syntax descriptions, you probably only want to set these options via your ".exrc" file. (See the :mkexrc command.)

6.16 Window update parameters

.---------------------.---------.--------.-----------------------------.
| OPTION NAMES        | TYPE    | GROUP  | DESCRIPTION                 |
|---------------------|---------|--------|-----------------------------|
| exrefresh, er       | Boolean | global | redraw scrn after each line |
| nearscroll, ns      | Number  | global | scroll vs. jump&center param|
| wrap                | Boolean | win    | how long lines are displayed|
| sidescroll, ss      | Number  | win    | sideways scrolling amount   |
| optimize, op        | Boolean | global | run faster                  |
| animation, anim     | Number  | global | animation macro speed       |
| window, wi          | Number  | global | lines to show for :z command|
| pollfrequency, pf   | Number  | global | rate of testing for ^C      |
| maptrace, mt        | One of  | global | debugger: off, run, or step |
| maplog, mlog        | One of  | global | logging: off, reset, append |
^---------------------^---------^--------^-----------------------------^

exrefresh, er (Boolean, global)

The exrefresh option affects the frequency of window updates when in EX mode. It is normally false, which causes the window to be refreshed at the end of each EX command. If you set exrefresh to true, then Elvis will update the window's image every time an output line is generated; this makes the command run much slower, but gives you more feedback.

nearscroll, ns (Number, global)

The nearscroll option controls Elvis' behavior when the cursor is moved off the top or bottom of the window. If the new cursor position is within nearscroll lines of the window, then the window is scrolled to bring the new line into view. If the new cursor position is outside that range, then Elvis uses a "jump and center" approach, in which the window's image is drawn from scratch with the new cursor line shown in the center of the window. Its default value is 5.

wrap (Boolean, win)

The wrap option determines how Elvis will display lines which are too long to fit on a single row of the display. It is true by default, which causes long lines to be wrapped onto multiple rows of the display. This is the traditional vi behavior. Changing it to false will cause long lines to be partially displayed on a single row of the display; you can scroll sideways to reveal the rest of the line my moving the cursor onto it, and then off the edge.

sidescroll, ss (Number, win)

If the wrap option is false (indicating that long lines should be displayed via side-scrolling) then the sidescroll option controls the scrolling increment. The default is 8, so the display will scroll sideways in chunks of 8 characters at a time.

optimize, opt (Boolean, global)

The optimize option affects the efficiency of screen updates. It is normally true, which tells Elvis to update the screen image only when it must wait for user input. If you make it false, then Elvis will update the screen after every command; among other things, this allows you to see intermediate effects of macros.

animation, anim (Number, global)

The animation option is related to optimize. When the optimize option is true, Elvis still refreshes the screen periodically while executing a large macro so that animation macros can be seen in all their glory. Elvis attempts to figure out which macros are loops, and when one of those macros is invoked Elvis considers updating the screen. If animation=1 then Elvis updates the screen every time; when animation=2 it updates the screen an alternate invocations of those macros, and so on. The default, chosen simply through experimentation, is 3.

Sometimes Elvis will choose the wrong macros to refresh. If that happens, then try running the macro with optimize option turned off. For example, the bouncing ball macros look better with optimize turned off.

window, wi (Number, global)

The window option stores the default number of lines to be displayed by the :z command. Historically it has also been used for forcing vi to update only a portion of the screen, but Elvis doesn't use it for that.

pollfrequency, pf (Number, global)

When Elvis is performing some time-consuming operations, such as a global substitution, it will periodically check to see if the user is trying to cancel the operation. For some user interfaces, this inspection takes a significant amount of time so Elvis allows the pollfrequency option to reduce the frequency of these checks. The default is 20. Larger values of pollfrequency will make global substitutions run faster; smaller values make Elvis respond to ^C sooner.

maptrace, mt (One of, global)

The maptrace option controls Elvis' built-in macro debugger. It can be off, run, or step. The default is off, which causes macros to run normally. If you change it to run then Elvis will display the contents of the mapping queue at the bottom of the screen while running any macro; depending on maplog, it may also log it.

The step value displays the mapping queue, and then waits for a keystroke before proceeding. If the keystroke is ^C then the macro is terminated. If the keystroke is r then maptrace is set to run. Any other keystroke causes Elvis to pause again after processing the macro's next character. See section 16.3 How to debug macros for more suggestions for debugging macros.

maplog, mlog (One of, global)

The maplog option can be used to log the information displayed by the maptrace option. It also logs any ex commands that are executed, other than those that you enter manually. It is off by default. Setting it to append causes the map trace information to be appended to an internal edit buffer named "Elvis map log". Setting it to reset causes that buffer to be clobbered before the next map trace; when that happens, maplog will be automatically switched to append. You can view the logged data via the command...

:("Eml)sp

or the long version, ":(Elvis map log)split".

6.17 Cache options

.---------------------.---------.--------.-----------------------------.
| OPTION NAMES        | TYPE    | GROUP  | DESCRIPTION                 |
|---------------------|---------|--------|-----------------------------|
| blkcache, cache     | Number  | global | number of blocks in cache   |
| blksize, bsz        | Number  | global | size of cache block         |
| blkfill, bfill      | Number  | global | initial chars per text block|
| blkhash, hash       | Number  | global | size of cache hash table    |
| blkgrow, bgr        | Number  | global | allocation table parameter  |
| blkhit, bh          | Number  | global | # of block requests in cache|
| blkmiss, bm         | Number  | global | # of block req. not in cache|
| blkwrite, bw        | Number  | global | # of blocks written         |
| sync                | Boolean | global | force changes to disk       |
^---------------------^---------^--------^-----------------------------^

blkcache, cache (Number, global)
blksize, bsz (Number, global)
blkfill, bfill (Number, global)
blkhash, hash (Number, global)
blkgrow, bgr (Number, global)
blkhit, bh (Number, global)
blkmiss, bm (Number, global)

You probably don't need to know about the "blk" options. The blkcache option indicates how many blocks from the session file Elvis should keep in its own internal cache, and blkhit and blkmiss can be used to gauge the efficiency of the cache. blkwrite indicates how many blocks have been written to the session file. The blksize option indicates the size of each block, blkfill indicates how many characters should be stuffed into each block initially (leaving room for more text that the user may insert later), and blkhash and blkgrow affect a couple of internal tables.

Note that the value of blksize can only be set via the -Bblksize command line flag, and its value must be a power of 2 in the range [512, 8192]. You can't change blksize after Elvis has started (not even in configuration scripts), because by then the session file has already been created with the other block size.

sync (Boolean, global)

If the sync option is true, then Elvis will flush all dirty blocks from its cache at the end of each edit command. Doing this will just about guarantee that you can recover your changes after a crash, but it can slow down the computer tremendously. The sync option is false by default, and on multi-user systems it should be left that way. On a single-user system, you might consider setting the sync option.

6.18 Options that describe the system

.---------------------.---------.--------.-----------------------------.
| OPTION NAMES        | TYPE    | GROUP  | DESCRIPTION                 |
|---------------------|---------|--------|-----------------------------|
| version, ver        | String  | global | Elvis version number (2.2)  |
| bitsperchar, bits   | Number  | global | character size (always 8)   |
| gui                 | String  | global | name of user interface      |
| os                  | String  | global | name of operating system    |
| locale              | String  | global | user's language             |
| program, argv0      | String  | global | invocation name of Elvis    |
| session, ses        | String  | global | name of session file        |
| tempsession, temp   | Boolean | global | delete session file on exit |
| newsession, newses  | Boolean | global | session file is new         |
| recovering, rflag   | Boolean | global | recovering after a crash    |
| exitcode, exit      | Number  | global | exit code of Elvis process  |
^---------------------^---------^--------^-----------------------------^

version, ver (String, global)

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

bitsperchar, bits (Number, global)

The bitsperchar option indicates the size of characters that Elvis uses internally. Currently this is always 8, but I expect to support 16-bit characters eventually.

gui (String, global)

The gui option indicates which user interface is being used. This can be handy in your initialization files. For example, you might prefer white characters on a blue background when using the "termcap" interface, and black characters on a white background when using the "x11" interface.

os (String, global)

The os option allows Elvis' initialization files to act differently on different operating systems. Its value indicates the name of the local operating system.

locale (String, global)

The natural-language spoken by the user. The value is initialized by the elvis.ini script from the $LANG or $LC_ALL environment variables.

The locale 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 spelldict option. Elvis itself uses the digraph table to handle different symbol sets, and the elvis.msg file for different languages.

program, argv0 (String, global)

The program option stores the name by which Elvis was invoked; i.e., the value of argv[0]. Typical values would be "elvis" under UNIX, "elvis.exe" under Win32, or "C:\BIN\ELVIS.EXE" under MS-DOS. The default elvis.ini file evaluates tolower(basename(program)) and compares the result to "ex" and "view", to set the initialstate and defaultreadonly options, respectively.

session, ses (String, global)

The session option stores the name of the current session file. There is rarely any need to check this, but I had to store it someplace and it might as well be accessible, I figured.

tempsession, temp (Boolean, global)
newsession, newses (Boolean, global)
recovering, rflag (Boolean, global)

The tempsession, newsession, and recovering options describe different aspects of the session file. If tempsession is true, then Elvis will delete the session file when it exits. If newsession is true, then Elvis has just created the file so there may be extra initialization that needs to take place in elvis.ini or someplace. If recovering is true, then the session file may be damaged, so it may be a good idea to skip some initialization steps, or automatically write out all user buffers.

exitcode, exit (Number, global)

The exitcode is the value that Elvis will return to its parent process when the Elvis process exits. Initially this is 0, which is the conventional indication of a normal, successful exit. You can explicitly set it to other values to indicate special situations. Also, if Elvis 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.

6.19 External programs

.---------------------.---------.--------.-----------------------------.
| OPTION NAMES        | TYPE    | GROUP  | DESCRIPTION                 |
|---------------------|---------|--------|-----------------------------|
| ccprg, cp           | String  | buf    | shell command for :cc       |
| makeprg, mp         | String  | buf    | shell command for :make     |
| anyerror, ae        | Boolean | global | allow :errlist if readonly  |
| equalprg, ep        | String  | buf    | shell command for = operator|
| keywordprg, kp      | String  | buf    | shell command for K command |
| shell, sh           | String  | global | name of shell program       |
| warn                | Boolean | global | warn if file not saved      |
^---------------------^---------^--------^-----------------------------^

ccprg, cp (String, buf)
makeprg, mp (String, buf)

The ccprg and makeprg are the programs used by the :cc and :make commands. Before the program strings are executed, they are subjected to the same sort of expression evaluation as the :eval command, with $1 representing any extra arguments from the ex command line, and $2 representing the name of the current file. Their defaults are cp="cc ($1?$1:$2)" and mp="make $1".

Spaces in filenames can be a problem with the $2 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 :set command and Elvis' expression evaluator. Do it this way:

	:set cp="cc ($1?$1:(char(34);$2;char(34)))"

anyerror, ae (Boolean, global)

When searching for error messages after a :cc or :make command, Elvis will normally ignore errors about files that you don't have write access to. Usually this is convenient, because it prevents Elvis from reading header files that you've misused. However, setting anyerror to true will make it read any file that generates a complaint, even if you can't write to it.

equalprg, ep (String, buf)

The equalprg option stores the name of a program to be executed for the visual = operator command. Its default value is "fmt", which is a simple text formatting program.

keywordprg, kp (String, buf)

The keywordprg option stores the name of the program used by the visual K command. This string is evaluated with $1 being replaced with the word under the cursor at that time, and $2 the name of the current file. The default value is "ref $1 file:$2"; the ref program looks up a tag and displays it. If you're using the x11 user interface, then you might want try the following, which causes the function's header to be displayed in a separate pop-up window:

set kp="ref $1 file:$2 2>&1 \| xmessage -file - >/dev/null 2>&1 &"

shell, sh (String, global)

The shell option stores the name of the system's command-line interpreter. It is used when executing all of the above programs, as well as commands entered for the EX :! and visual ! commands. Its default value is system-dependent; typically it will be "/bin/sh" for UNIX, and "C:\COMMAND.COM" for MS-DOS.

warn (Boolean, global)

When any external program is executed, if the current buffer has been changed but not written out to the file, then Elvis will normally give a warning message. Setting the warn option to false disables this message.

6.20 Directory names

.---------------------.---------.--------.-----------------------------.
| OPTION NAMES        | TYPE    | GROUP  | DESCRIPTION                 |
|---------------------|---------|--------|-----------------------------|
| home                | String  | global | home directory              |
| elvispath, epath    | String  | global | list of possible config dirs|
| sessionpath, spath  | String  | global | list of possible session dir|
| directory, dir      | String  | global | where to store temp files   |
^---------------------^---------^--------^-----------------------------^

home (String, global)

The home option is the name of your home directory. The value of this option is used for replacing the ~ character at the start of a full pathname. If an environment variable named HOME exists, then home is initialized from its value. Otherwise, its default value is set as follows:

For UNIX:	The default is "/".
For Win32:	The default is derived from environment variables named HOMEDRIVE and HOMEPATH, which will normally always be defined. Their default value is usually "C:\users\default". If either of those environment variables is undefined, then Elvis will attempt to find the pathname of the program, and use its directory. As a last resort, Elvis will use "C:\" as the default home directory.
For OS/2:	The default home directory is the one containing ELVIS.EXE, or if that can't be found then it will use "C:\" as the default home directory.
For MS-DOS:	The default home directory is the one containing ELVIS-2.2_0

elvispath, epath (String, global)

The elvispath option stores a list of directory names where Elvis might find its configuration files. If there is an ELVISPATH environment variable, then the elvispath option is initialized from the value of ELVISPATH. Otherwise it is set to a value such as "~/.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:

For UNIX:	The default contains ~/.elvis and the directories that you specified as the data and doc directories when you ran the configure script. The default data directories are /usr/share/elvis for data, and /usr/share/elvis/doc for documentation, so usually elvispath will default to "~/.elvis:/etc/elvis:/usr/share/elvis: /usr/share/elvis/doc".
For Win32, OS/2, or MS-DOS:	The default contains ~\dotelvis, and subdirectories named data and doc under the directory where elvis.exe resides. For example, if Elvis is installed as C:\elvis\elvis.exe then elvispath would be ~\dotelvis;C:\elvis\data;c:\elvis\doc.

sessionpath, spath (String, global)

The sessionpath option gives Elvis a list of possible directories where session files might be placed. Elvis uses the first writable directory in that list, and ignores all of the others. The default value depends on the operating system, and can be overridden by the SESSIONPATH environment variable. You can't change the sessionpath option after Elvis has started, because the session file has already been created by then.

directory, dir (String, global)

The directory option gives the name of the directory where Elvis will store its temporary files. The default value is system-dependent. Note that this is not where the session file is stored; the session option gives the name of the session file.

6.21 Initialization options

.---------------------.---------.--------.-----------------------------.
| OPTION NAMES        | TYPE    | GROUP  | DESCRIPTION                 |
|---------------------|---------|--------|-----------------------------|
| exrc, ex            | Boolean | global | interpret ./.exrc file      |
| modeline, ml        | Boolean | global | interpret modelines         |
| modelines, mls      | Number  | global | positions of modelines      |
| security, sec       | One-of  | global | normal, safer,or restricted |
| initialstate, init  | One-Of  | global | command mode of new windows |
| mkexrcfile, rc      | String  | global | name of user's init script  |
^---------------------^---------^--------^-----------------------------^

exrc, ex (Boolean, global)

The exrc option has no built-in meaning to Elvis, however the default elvis.ini file uses this option to determine whether it should look for a ".exrc" file in the current directory.

modeline, ml (Boolean, global)
modelines, mls (Number, global)

The modeline option controls whether Elvis will look for modelines in each buffer after it has been loaded from a file. If modelines is true, then Elvis will search through the first and last modelines lines of the buffer for something that looks like "ex:commands:" or "vi:commands:" and if found, it executes the commands as an ex command line. (This behavior is implemented in the elvis.arf file.) This is typically used for changing tabstops and the like. The modeline option is false by default, and modelines is 5.

security, sec (One-of, global)

The security 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. Basically, "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. Specifically...

normal	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.
safer	This is an intermediate level of protection. It is intended to make modelines and a .exrc file in the current directory safe to use, but I'm not making any promises. When security=safer, certain commands are disabled, wildcard expansion in filenames is disabled, and certain options are locked (including the security option itself). Typically you will use the ex command :safely source to execute an untrusted script, rather than futz with the value of the safer option directly. The disabled ex commands are :!, :abbreviate, :alias, :args, :augroup, :autocmd, :cc, :cd, :chdir, :last, :lpr, :make, :map, :mkexrc, :next, :Next, :previous, :rewind, :shell, :slast, :snew, :snext, :sNext, :srewind, and :write. Some commands are allowed only when invoked without a filename argument. These are :edit, :ex, :file, :open, :push, :split, :visual, :wquit, and :xit. The locked options are ccprg, elvispath, equalprg, home, keywordprg, lpout, makeprg, modeline, security, shell, spelldict, and tagprg. In expressions, the shell() function will fail.
restricted	This is the most secure setting. It is intended to make Elvis safe for use as a restricted editor, e.g. to be invoked on a specific file via the sudo(8) program. In addition to all of the rules implied by "safer" level, "restricted" disables the :stop, :source, :suspend commands. Also, the :errlist, :read, and :wordfile commands won't allow filename arguments. The "restricted" level also inhibits filename completion via the <Tab> key. In expressions, the time(filename) function will fail if invoked with a filename parameter, and the exists(), dirperm(), and fileeol() functions always fail. initialstate, init (One-Of, global) The initialstate option determines what command mode new windows will start in. It can be one of input, replace, vi, or ex. The default is vi, the visual command mode. mkexrcfile, rc (String, global) The mkexrcfile option contains the name of the file which contains the user's initialization script. It is used by the :mkexrc command. It has no default value, but scripts generated by :mkexrc always set this option to the name of that script file. 6.22 Keyboard map options .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | remap | Boolean | global | allow key maps to use maps | | timeout, to | Boolean | global | allow timeout for maps? | | keytime, kt | Number | global | timeout for function keys | | usertime, ut | Number | global | timeout for multi-key maps | | mapmode, mm | String | buf | which maps to use | ^---------------------^---------^--------^-----------------------------^ Elvis allows keystrokes to be mapped via the :map command. Once a map has been defined, these options control how and when those maps are recognized. remap (Boolean, global) The remap option controls how many times Elvis will attempt to reapply key maps. If the remap option is true (the default), then Elvis will repeatedly attempt to reapply maps as long as there are any that match. This means that maps can be written to use other maps, allowing some very complex behavior. If remap is false, then it will attempt to apply maps only once, so the result of any map is not altered any further. By default, remap is true. timeout, to (Boolean, global) The timeout option is normally true, which allows the keytime and usertime 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 timeout option will cause Elvis to allow any amount for maps to be completed, regardless of the values of keytime and usertime. keytime, kt (Number, global) usertime, ut (Number, global) The keytime and usertime options come into play when characters are received which partially match one or more maps. For example, suppose the arrow keys are mapped to h, j, k, and l, those arrow keys send escape sequences when pressed, and Elvis has just received an escape character. How can it tell whether the user hit the Esc key or an arrow key? In this situation, Elvis must perform a read-keystrokes-with-timeout operation to determine which map applies, if any. If all of the partially matching maps are for special keys such as function keys, then Elvis will use the keytime value. If at least one of them is for a user map, then Elvis will use the usertime value. Either way, the values indicate the time, in tenths of a second, that Elvis should allow for the rest of the map characters to arrive. If they don't arrive, then none of the partially matching maps is used. Typically, the usertime value will be much longer than the keytime value, because the user must hit a series of keys for a user map. For example, many people like to create maps consisting of a semicolon and one or two following letters. (If you're a touch typist, then your right-hand pinky normally rests on the semicolon key, so this is convenient.) By distinguishing between key maps and user maps, Elvis can give quick response to the Esc while still allowing users to key in their own keymaps at a leisurely pace. Their default values are keytime=3 and usertime=15. mapmode, mm (String, buf) The mapmode option indicates which mode-sensitive maps to use. When defining a map via the :map command, you can use a mode=name flag to indicate which mode the map applies to. The name is then compared to the value of mapmode after each keystroke, when Elvis is deciding which maps to apply. 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<strong>^P</strong>^[ :map II mode=html select c<em>^P</em>^[ :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 mapmode appropriately to ensure that the proper set of maps are used. The default value is "", but the standard elvis.arf script sets it to be the same as the bufdisplay option, if that option's value is one of "html", "man", or "tex". 6.23 Auto command options .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | eventignore, ei | String | global | list of events to ignore | | eventerrors, ee | Boolean | global | allow error msg during event| | aufilename, afile | String | au | name of file | | auevent, ev  | String | au | name of current event | | auforce, bang | Boolean | au | did trigger cmd have "!" ? | ^---------------------^---------^--------^-----------------------------^ These options are all related to the :autocmd command. The options in the "au" group only exist while an auto command is executing. For a description of how auto commands work, see the Tips chapter. eventignore, ei (String, global) The eventignore option contains a list of events which should be ignored. You can set it to a comma-delimited list of event names, or "all" to ignore all events. By default it is an empty list, so no events are ignored. eventerrors, ee (Boolean, global) The eventerrors option is used for allowing or hiding error messages from commands that run automatically when an event occurs. By default it is off (noeventerrors), which hides the errors; this is because users are likely to be confused if they see error messages from commands that they aren't running. If you wish to debug your :autocmd configuration, you might want to turn it on. You can also selectively turn off error messages by running the command via :try, like this... :au BufNew *.html try r skeleton.html aufilename, afile (String, au) While an auto command is running, the aufilename option is set to the name that was compared against the auto command's pattern (the second argument of a :au command). 95% of the time, this will be identical to the filename option. The only exceptions are for the :doau command allows you to specify a different name, and some I/O events such as FileReadPost and FileWritePre where aufilename is set to the name of the file being read or written to. auevent, ev (String, au) While an auto command is running, the auevent option is set to the name of the event that triggered it. This allows you to use a single auto command to handle multiple events in slightly different ways. When you're trying to learn about auto commands and events, one of the best things you can do is set up an auto command which announces all events as they happen, like this... :au * * set auevent? auforce, bang (Boolean, au) While an auto command is running, the auforce option indicates whether the command that triggered it was invoked with a "!" suffix or not. This is most useful for the BufWritePre event. For many events, it is irrelevant. 6.24 Printing options .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | lptype, lpt | String | lp | printer type | | lpconvert, lpcvt | Boolean | lp | convert Latin-1 to PC-8 | | lpcrlf, lpc | Boolean | lp | printer needs CR-LF newline | | lpout, lpo | String | lp | printer file or filter | | lpcolumns, lpcols | Number | lp | width of printer page | | lpwrap, lpw | Boolean | lp | simulate line-wrap | | lplines, lprows | Number | lp | length of printer page | | lpnumber, lpn | Boolean | lp | print line numbers in margin| | lpheader, lph | Boolean | lp | print header at top of page | | lpformfeed, lpff | Boolean | lp | send form-feed after last pg| | lpoptions, lpopt | String | lp | driver-specific options | | lpcolor, lpcl | Boolean | lp | use colors when printing | | lpcontrast, lpct | Number | lp | minimum color darkness 0-100| ^---------------------^---------^--------^-----------------------------^ These options all affect hardcopy output, done via the :lpr command. Note that these options are in a separate group, so you can display all of them by giving the command "se lp?". lptype, lpt (String, lp) The lptype option lets Elvis know what type of printer you're using, so it can use the correct escape codes (or whatever) to switch fonts. The default is "dumb" because it is the most conservative value, but it is also the least expressive. (Exception: When using the Win32 user interface, the default is "windows".) You should set lptype to one of the following values: .---------.-------------------------------------------------. | VALUE | PRINTER DESCRIPTION | |---------|-------------------------------------------------| | ps | [1] PostScript, one logical page per sheet | | ps2 | [1] PostScript, two logical pages per sheet | | epson | [2] Most dot-matrix printers, no graphic chars | | pana | [2] Panasonic dot-matrix printers | | ibm | [2] Dot-matrix printers with IBM graphic chars | | hp | [2] HP printers, and most non-PostScript lasers | | cr | Line printers, overtypes via carriage-return| | bs | Overtypes via backspace, like nroff | | dumb | Plain ASCII, no font control | | html | HTML source code | | ansi | ANSI terminal codes (for VT-100, xterm, etc)| |-- --- --|-- --- --- --- --- --- --- --- --- --- --- --- --| | windows | [1] The Win32 print facility (in WinElvis only) | ^---------^-------------------------------------------------^ [1] Full support for proportional character attribute [2] Partial support for proportional character attribute lpconvert, lpcvt (Boolean, lp) The lpconvert option, when set, causes some printer types to convert non-ASCII Latin-1 characters to PC-8 characters. Most computers use Latin-1 internally for storing text, but many printers use PC-8; hence the need for conversion. This option has no effect on ASCII characters because they never need conversion. This option is ignored if your computer doesn't appear to be using Latin-1 (or, more precisely, if there is no digraph which maps AE to 0xc6, the Latin-1 code for the Æ ligature.) This option is false by default. NOTE: Not all printer types obey the lpconvert option. Postscript printers don't do conversion because they use Latin-1 themselves. The "cr", "bs", and "dumb" printer types ignore it simply because they are typically used for writing to files, not actual printers, and as long as the text remains in the computer no conversion is necessary. Only the "epson", "pana", "ibm", "hp", and "html" printers will obey the lpconvert option. lpcrlf, lpc (Boolean, lp) The lpcrlf option forces Elvis to convert each newline character to a CR/LF pair. Some printers, on some systems, require this. Most don't, so this option is false by default. If you attempt to print something and only the first line is visible, or the text is badly jumbled, then try ":set lpcrlf" and maybe that'll fix it. lpout, lpo (String, lp) The lpout option should be either the name of a file or device (such as "PRN" or "/dev/lp0") to which the printer output should be sent, or ! character followed by a shell command (such as "!lp -s") which reads printer text from stdin and submits it to the printer spooler. The default is system dependent. Windows users who wish to use an lptype other than "windows" should check the How To appendix for instructions on how to assign printer ports. lpcolumns, lpcols (Number, lp) The lpcolumns option tells Elvis how wide the printer page is. The default is 80 columns. If you have a wide-carriage printer, you may wish to set lpcolumns=132. If lptype is set to "ps", "ps2", or "windows", and you set lpcolumns to a value greater than 80, Elvis will compress the characters to make the longer lines fit. lpwrap, lpw (Boolean, lp) The lpwrap option tells Elvis how to handle lines that are wider than lpcolumns. If this options is true (the default) then long lines will wrap onto multiple printed lines. If lpwrap is false, then it will clip long lines. lplines, lprows (Number, lp) The lplines option tells Elvis how long the usable portion of each page is; i.e., how many lines it should print on each page. The default is 60. Some display modes print headers at the top of each page; those lines are included in the lplines count. Setting lplines=0 causes Elvis to assume that pages are infinitely long, which sounds about right for fan-fold printer paper. If you have a PostScript printer and set lplines to a value greater than 60, then the page will be compressed vertically to make it fit. lpnumber, lpn (Boolean, lp) The lpnumber option does to printouts what the number option does for a window -- it causes the line number to be output in the left margin. This is false by default. lpheader, lph (Boolean, lp) The lpheader option controls whether printouts will have a line at the top of each page showing the file name, date, and page number, or other information. Different display modes have different header formats. This is true by default. lpformfeed, lpff (Boolean, lp) The lpformfeed option controls whether Elvis will send a form-feed control character after the last page of any print job. This should generally be false if you're printing through a print spooler program, because print spoolers usually add the final formfeed themselves. Under MS-DOS, Elvis is normally configured to send the text directly to the printer device, prn, and you may wish to set the lpformfeed option there. lpoptions, lpopt (String, lp) The lpoptions option is only significant for PostScript printers, and even there most people will leave it set to "". The values in lpoptions are inserted into the PostScript output before the contents of the elvis.ps file. The value should be a comma-delimited list of "fieldname:value" pairs. The ps and ps2 lptypes use the following options: .------------.------------------------------------------------. | FIELD NAME | MEANING OF THE VALUE | |------------|------------------------------------------------| | paper | The paper size. It can be one of letter, | | | legal, executive, a4, or a3. If you omit | | | this field, then Elvis will allow the printer | | | to figure out the paper size itself. | | | | | frame | This determines whether Elvis will draw a box | | | around each page. It can be true or false. | | | The default is true. | | | | | bar | This determines whether Elvis will draw a | | | vertical bar between pages when lptype=ps2. | | | It can be true or false. The default is false. | | | | | punch | This determines whether Elvis will leave space | | | along the left edge of each sheet to accomodate| | | a three-hole punch. It can be true or false. | | | The default is false. | | | | | clip | This determines whether Elvis will leave space | | | along the top edge of each sheet to accomodate | | | a clip board. It can be true or false. The | | | default is false. | ^------------^------------------------------------------------^ For example, "lpoptions=frame:false,bar:true" will cause elvis to draw a bar between logical pages on each sheet in lptype=ps2 mode, instead of drawing a box around them. lpcolor, lpcl (Boolean, lp) The lpcolor option is currently only supported for the "windows" printer type under Microsoft Windows95/98/NT, and for the "ps", "ps2", "html", and "ansi" printer types under all operating systems. When true, it allows printouts to use color for the foreground. (The background is always white.) Normally it is false (nolpcolor), which forces all printouts to use black since that usually prints faster and looks better, and is always less expensive. lpcontrast, lpct (Number, lp) When lpcolor is set, the lpcontrast option defines a minimum darkness level to use. Colors that are too light will be darkened, while colors that are already dark enough will be left unchanged. The value of lpcontrast is a number from 0 (allow any colors) to 100 (darken every color to black). The default is 50. A better way to control printing colors is via the "or color" clause in a :color command. When you give multiple foreground colors this way, Elvis chooses the darkest one for printing, and then uses lpcontrast to darken it even more if necessary. The lpcontrast option has no effect on the "html" and "ansi" lptypes, because Elvis has no way of knowing what the background color will be when you view it. 6.25 Previous arguments .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | previousdir, pdir | String | global | previous directory name | | previousfile | String | global | name of alternate file | | previousfileline | Number | global | line# from previousfile | | previouscommand | String | global | previous shell command line | | previoustag, ptag | String | global | previous search tag | ^---------------------^---------^--------^-----------------------------^ These options all store the previous value of some type of input, so that the same value can be used again later. You can set these options, but there really isn't much point to it, usually. previousdir, pdir (String, global) The previousdir option stores the name of the previous working directory. Initially it is set from the value of the $OLDPWD environment variable. After that, each :cd command will store the old current working directory into this option before switching to the new working directory. If you give Elvis a file name which begins with "~-", Elvis will replace the "~-" with the value of this option. previousfile (String, global) previousfileline (Number, global) The previousfile option stores the name of an alternate file. Usually this is the name of the last file you mentioned, other than that of the current file. When you switch from one file to another, the name of the previous file is stored here, along with the line number (in previousfileline), so you can easily bounce between this file and the previous one. Whenever you type in a filename as an argument to an ex command, any instances of the # character are replaced by the value of previousfile. previouscommand (String, global) The previouscommand option stores the last shell command you typed in. When you enter the next shell command line, any instances of the ! character will be replaced by the value of previouscommand. previoustag, ptag (String, global) The previoustag option stores the name of the last tag you looked up. This value is also stored on the tagstack in the hope that it may help you remember where you were when you performed all of your recent tag lookups. 6.26 Unsupported options .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | hardtabs, ht | Number | global | width of terminal's tabs | | lisp | Boolean | buf | lisp mode | | mesg | Boolean | global | disable SysAdmin messages | | more, mo | Boolean | global | allow "Hit <Enter>" prompt | | novice | Boolean | global | beginner mode | | redraw | Boolean | global | redraw screen during input | ^---------------------^---------^--------^-----------------------------^ hardtabs, ht (Number, global) lisp (Boolean, buf) mesg (Boolean, global) more, mo (Boolean, global) novice (Boolean, global) redraw (Boolean, global) The hardtabs, lisp, mesg, more, novice, and redraw options exist in Elvis, but they don't do anything. They exist mostly for backward compatibility with vi. This doesn't mean they're useless, though. You can catch OptChanged or OptSet events on these options, and use that to alter other options or perform actions. For example, the following makes the novice option act pretty much as it does in vi: :au OptSet novice set nomagic report=1 showmode 6.27 User variables .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | a | String | user | user variable | | b | String | user | user variable | | c | String | user | user variable | | d | String | user | user variable | | e | String | user | user variable | | f | String | user | user variable | | g | String | user | user variable | | h | String | user | user variable | | i | String | user | user variable | | j | String | user | user variable | | k | String | user | user variable | | l | String | user | user variable | | m | String | user | user variable | | n | String | user | user variable | | o | String | user | user variable | | p | String | user | user variable | | q | String | user | user variable | | r | String | user | user variable | | s | String | user | user variable | | t | String | user | user variable | | u | String | user | user variable | | v | String | user | user variable | | w | String | user | user variable | | x | String | user | user variable | | y | String | user | user variable | | z | String | user | user variable | | bb | String | buf | user variable per buffer | | ww | String | win | user variable per window | ^---------------------^---------^--------^-----------------------------^ a (String, user) b (String, user) c (String, user) d (String, user) e (String, user) f (String, user) g (String, user) h (String, user) i (String, user) j (String, user) k (String, user) l (String, user) m (String, user) n (String, user) o (String, user) p (String, user) q (String, user) r (String, user) s (String, user) t (String, user) u (String, user) v (String, user) w (String, user) x (String, user) y (String, user) z (String, user) These one-letter options have no preset purpose. They are useful for holding temporary values which you expect to use in an expression later. These are all string values, but because the expression evaluator doesn't distinguish between a number and a string which happens to look like number, you can also use these as numbers. For example, the command... :let i=i+1 ...does exactly what you would expect. bb (String, buf) ww (String, win) These are user options that are associated with a buffer or window, respectively. If you need more than one variable, consider using named fields to stuff multiple values into a single option. 6.27 Alphabetical list of options .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | a | String | user | user variable | | aasqueeze, aas | Boolean | x11 | reduce the gap between lines| | altkey, metakey | One of | x11 | effect of the Alt key | | animation, anim | Number | global | animation macro speed | | antialias, aa | Boolean | x11 | use antialiased fonts | | anyerror, ae | Boolean | global | allow :errlist if readonly | | auevent, ev  | String | au | name of current event | | aufilename, afile | String | au | name of file | | auforce, bang | Boolean | au | did trigger cmd have "!" ? | | autoiconify, aic | Boolean | x11 | iconify old window | | autoindent, ai | Boolean | buf | auto-indent new text | | autoprint, ap | Boolean | global | print current line in ex | | autoselect, as | Boolean | global | visibly mark searched text | | autotab, at | Boolean | buf | allow autoindent to use '\t'| | autowrite, aw | Boolean | global | save file before switching | | b | String | user | user variable | | background, bg | One-of | global | assumed background color | | backup, bk | Boolean | global | make *.bak file before write| | bang | Boolean | bang | writing with a '!' ? | | bb | String | buf | user variable per buffer | | beautify, bf | Boolean | global | strip ctrl chars from files | | binary, bin | Boolean | global | -b flag for binary files | | bitsperchar, bits | Number | global | character size (always 8) | | blinktime, xbt | Number | x11 | cursor blink rate, 1/10 Sec | | blkcache, cache | Number | global | number of blocks in cache | | blkfill, bfill | Number | global | initial chars per text block| | blkgrow, bgr | Number | global | allocation table parameter | | blkhash, hash | Number | global | size of cache hash table | | blkhit, bh | Number | global | # of block requests in cache| | blkmiss, bm | Number | global | # of block req. not in cache| | blksize, bsz | Number | global | size of cache block | | blkwrite, bw | Number | global | # of blocks written | | boldfont, xfb | String | x11 | name of bold font | | borderwidth, xbw | Number | x11 | size of text area's border | | bufchars, bc | Number | buf | number of characters | | bufdisplay, bd | String | buf | default display mode | | bufid, bufferid | Number | buf | ID number of user buffer | | buflines, bl | Number | buf | number of lines | | bufname, buffer | String | buf | name of buffer | | c | String | user | user variable | | cancel, Cancel | String | x11 | locale's Cancel label | | ccprg, cp | String | buf | shell command for :cc | | cleantext, ct | Packed | global | Rules for erasing old text | | codepage, cp | Number | win32 | console character set | | columns, cols | Number | win | width of window | | completebinary, cob | Boolean | global | complete names of binaries? | | controlfont, xfc | String | x11 | name of toolbar font | | d | String | user | user variable | | dblclicktime, xdct | Number | x11 | double-click speed, 1/10 Sec| | defaultreadonly, dro| Boolean | global | assume all files readonly | | digraph, dig | Boolean | global | allow X-backspace-Y entry | | directory, dir | String | global | where to store temp files | | display, mode | String | win | name of current display mode| | e | String | user | user variable | | edcompatible, ed | Boolean | global | remember regsub flags | | edited, samename | Boolean | buf | buffer loaded from filename | | elvispath, epath | String | global | list of possible config dirs| | equalprg, ep | String | buf | shell command for = operator| | errlines | Number | buf | buflines when :make was run | | errorbells, eb | Boolean | global | ring bell for error message | | eventerrors, ee | Boolean | global | allow error msg during event| | eventignore, ei | String | global | list of events to ignore | | exitcode, exit | Number | global | exit code of Elvis process | | exrc, ex | Boolean | global | interpret ./.exrc file | | exrefresh, er | Boolean | global | redraw scrn after each line | | f | String | user | user variable | | false, False | String | global | locale's False value | | filename, file | String | buf | name of file in buffer | | filenamerules, fnr | Packed | global | how to parse file names | | firstx, xpos | Number | x11 | horiz. position of first win| | firsty, ypos | Number | x11 | vert. position of first win | | flash, vbell | Boolean | global | substitute flash for bell | | focusnew, fn | Boolean | x11 | force focus into new window | | folding, fold | Boolean | win | enable folding | | font, fnt | String | windows| base font | | g | String | user | user variable | | gdefault, gd | Boolean | global | default change all instances| | gui | String | global | name of user interface | | guidewidth, gw | Tab-list| buf | draw vertial lines on screen| | h | String | user | user variable | | hardtabs, ht | Number | global | width of terminal's tabs | | help, Help | String | x11 | locale's Help label | | hllayers, hll | Number | win | how many layers to highlight| | hlobject, hlo | String | buf | type of object to highlight | | hlsearch, hls | Boolean | global | highlight all marches | | home | String | global | home directory | | i | String | user | user variable | | icon | Boolean | x11 | use the built-in icon? | | iconic | Boolean | x11 | windows start out iconified | | iconimage, ii | String | (gui) | window icon | | ignorecase, ic | Boolean | global | uppercase matches lowercase | | includepath, inc | String | syntax | where to find #include files| | incsearch, is | Boolean | global | / and ? search incrementally| | initialstate, init | One-Of | global | command mode of new windows | | initialsyntax, isyn | Boolean | buf | start in "syntax" mode? | | inputtab, it | One-Of | buf | input mode's (Tab) key | | internal | Boolean | buf | Elvis requires this buffer | | italicfont, xfi | String | x11 | name of italic font | | j | String | user | user variable | | k | String | user | user variable | | keytime, kt | Number | global | timeout for function keys | | keywordprg, kp | String | buf | shell command for K command | | l | String | user | user variable | | lines, rows | Number | win | height of window | | lisp | Boolean | buf | lisp mode (not supported) | | list, li | Boolean | win | show markups, newlines, etc.| | listchars, lcs | Packed | global | controls the "list" option | | locale | String | global | user's language | | locked, lock | Boolean | win | prevent any alterations | | lpcolor, lpcl | Boolean | lp | use colors when printing | | lpcolumns, lpcols | Number | lp | width of printer page | | lpcontrast, lpct | Number | lp | minimum color darkness 0-100| | lpconvert, lpcvt | Boolean | lp | convert Latin-1 to PC-8 | | lpcrlf, lpc | Boolean | lp | printer needs CR-LF newline | | lpformfeed, lpff | Boolean | lp | send form-feed after last pg| | lpheader, lph | Boolean | lp | print header at top of page | | lplines, lprows | Number | lp | length of printer page | | lpnumber, lpn | Boolean | lp | print line numbers in margin| | lpoptions, lpopt | String | lp | driver-specific options | | lpout, lpo | String | lp | printer file or filter | | lptype, lpt | String | lp | printer type | | lpwrap, lpw | Boolean | lp | simulate line-wrap | | m | String | user | user variable | | magic, ma | Boolean | global | use normal regexp syntax | | magicchar, mac | String | global | list of metacharacters | | magicname, man | Boolean | global | allow $name substitution | | magicperl, map | Boolean | global | Perl-compatible \b | | makeprg, mp | String | buf | shell command for :make | | maplog, mlog | One of | global | logging: off, reset, append | | maptrace, mt | One of | global | debugger: off, run, or step | | matchchar, mc | String | global | characters matched by % | | menubar, mb | Boolean | windows| enable the menubar | | mesg | Boolean | global | disable SysAdmin messages | | modeline, ml | Boolean | global | interpret modelines | | modelines, mls | Number | global | positions of modelines | | modified, mod | Boolean | buf | buffer differs from file | | more, mo | Boolean | global | allow "Hit <Enter>" prompt | | n | String | user | user variable | | nearscroll, ns | Number | global | scroll vs. jump&center param| | newfile, new | Boolean | buf | filename doesn't exist yet | | newsession, newses | Boolean | global | session file is new | | nonascii, asc | One-Of | global | how to display non-ascii | | novice | Boolean | global | beginner mode | | number, nu | Boolean | win | display line numbers | | o | String | user | user variable | | optimize, op | Boolean | global | run faster | | optionwidth, ow | Number | global | widths of ":set all" values | | os | String | global | name of operating system | | outlinemono, om | Number | x11 | char outlining for X11-mono | | p | String | user | user variable | | paragraphs, para | String | buf | nroff paragraph commands | | partiallastline, pll| Boolean | buf | file didn't end with newline| | pollfrequency, pf | Number | global | rate of testing for ^C | | prefersyntax, psyn | String | global | when to set initialsyntax | | previouscommand | String | global | previous shell command line | | previousdir, pdir | String | global | previous directory name | | previousfile | String | global | name of alternate file | | previousfileline | Number | global | line# from previousfile | | previoustag, ptag | String | global | previous search tag | | program, argv0 | String | global | invocation name of Elvis | | prompt | Boolean | global | issue ":" prompt in ex mode | | putstyle, ps | One of | buf | type of text in a cut buffer| | q | String | user | user variable | | r | String | user | user variable | | readeol, reol | One of | buf | newline mode when reading | | readonly, ro | Boolean | buf | don't overwrite filename | | recovering, rflag | Boolean | global | recovering after a crash | | redraw | Boolean | global | redraw screen during input | | remap | Boolean | global | allow key maps to use maps | | report | Number | global | minimum # lines to report | | retain, ret | Boolean | buf | keep buffer in session file | | ruler, ru | Boolean | win | display cursor's line/column| | s | String | user | user variable | | saveregexp, sre | Boolean | global | remember regexp to use as //| | scroll, scr | Number | win | scroll amount for ^D/^U | | scrollbar, sb | Boolean | (gui) | enable the scrollbar | | scrollbarleft, xsl | Boolean | x11 | enable scrollbar on side | | scrollbartime, xst | Number | x11 | delay for scrollbar repeat | | scrollbarwidth, xsw | Number | x11 | size of scrollbar, in pixels| | scrollbgimage, sbi | Boolean | (gui) | scroll background image | | scrollwheelspeed,sws| Number | (gui) | adjust speed of scroll wheel| | sections, sect | String | buf | nroff section commands | | security, sec | One-of | global | normal, safer,or restricted | | sentenceend, se | String | global | punct at end of sentence | | sentencegap, sg | Number | global | spaces required after sq | | sentencequote, sq | String | global | punct allowed after se | | session, ses | String | global | name of session file | | sessionpath, spath | String | global | list of possible session dir| | shell, sh | String | global | name of shell program | | shiftwidth, sw | Tab-List| buf | width used by < and > | | showmarkups, smu | Boolean | global | show markup at cursor | | showmatch, sm | Boolean | win | highlight matching parens | | showmode, smd | Boolean | win | display the command state | | sidescroll, ss | Number | win | sideways scrolling amount | | smartargs, sa | Boolean | buf | show args when inputing func| | smartcase, scs | Boolean | global | defeat ignorecase if upper | | smarttab, sta | Boolean | global | if indenting, (Tab) shifts | | spell, sp | Boolean | global | highlight misspelled words | | spellautoload, sal | Boolean | global | load whole dict when needed | | spelldict, spd | String | global | name of dictionary file | | spellsuffix, sps | String | global | list of suffixes | | stagger | Number | x11 | offset for next new window | | statusbar, stb | Boolean | (gui) | enable the statusbar | | stopshell, ssh | String | x11 | interactive shell command | | submit, Submit | String | x11 | locale's Submit label | | sync | Boolean | global | force changes to disk | | t | String | user | user variable | | tabstop, ts | Tab-List| buf | widths of tabstop columns | | taglength, tl | Number | global | significant length of tags | | tagprg, tp | String | global | external tag search program | | tags, tagpath | String | global | list of possible tag files | | tagstack, tsk | Boolean | global | remember origin of tag srch | | tempsession, temp | Boolean | global | delete session file on exit | | term, ttytype | String | tcap | terminal's termcap entry | | terse, te | Boolean | global | don't translate messages | | textcursor, tc | Number | x11 | one of hollow, opaque, xor | | textwidth, tw | Number | buf | width for word-wrap, or 0 | | timeout, to | Boolean | global | allow timeout for maps? | | timestamp, time | String | buf | time when file was modified | | toolbar, tb | Boolean | (gui) | enable the toolbar | | true, True | String | global | locale's True value | | ttycolumns, ttycols | Number | tcap | width of screen | | ttyrows, ttylines | Number | tcap | height of screen | | ttyitalic, ttyi | Boolean | tcap | okay to use "dim" for italic| | ttyunderline, ttyu | Boolean | tcap | okay to mix color & underln | | ttywrap, ttyw | Boolean | tcap | trust termcap's line wrap | | tweaksection, twks | Boolean | global | allow text before { section?| | u | String | user | user variable | | undolevels, ul | Number | buf | number of undoable commands | | userprotocol, up | Boolean | buf | URL, user-defined protocol | | usertime, ut | Number | global | timeout for multi-key maps | | v | String | user | user variable | | verbose | Numeric | global | give more status messages | | version, ver | String | global | Elvis version number (2.2) | | w | String | user | user variable | | warn | Boolean | global | warn if file not saved | | warningbells, wb | Boolean | global | ring bell for warning msg | | warpback, xwb | Boolean | x11 | upon exit, point to xterm | | warpto, wt | One of | x11 | ^W^W forces pointer movement| | window, wi | Number | global | lines to show for :z command| | windowid, id | Number | win | ID number of current window | | wrap | Boolean | win | how long lines are displayed| | wrapmargin, wm | (weird) | win | set textwidth from right | | wrapscan, ws | Boolean | global | searching wraps at EOF<->BOF| | writeany, wa | Boolean | global | don't warn of existing file | | writeeol, weol | One of | global | newline mode when writing | | ww | String | win | user variable per window | | x | String | user | user variable | | xcolumns, xcols | Number | x11 | width of new windows | | xencoding, xe | String | x11 | registry & encoding of fonts| | xrows, xlines | Number | x11 | height of new windows | | y | String | user | user variable | | z | String | user | user variable | ^---------------------^---------^--------^-----------------------------^