═══ 1. Elvis 2.1 Documentation ═══ TABLE OF CONTENTS  1. What is elvis?  2. Visual command mode (by function or name)  3. Input mode  4. EX command mode (by function or name)  5. Regular expressions (searches and substitutions)  6. Options (by function or name)  7. Display modes  8. User interfaces  9. Operating systems  10. Sessions, initialization, and recovery  11. Cut buffers  12. Messages  13. Arithmetic expressions (arithmetic, tests, and functions)  14. Tags  15. The Internet  16. Tips  A. List of terse messages (not in here, see elvistrs.msg)  B. Quick Reference  C. How To...  elvis(1) Man-page for elvis (not in here, see elvis.man)  ctags(1) Man-page for ctags (not in here, see ctags.man)  ref(1) Man-page for ref (not in here, see ref.man)  fmt(1) Man-page for fmt (not in here, see fmt.man) HINT: If you're reading this via elvis' built-in :help command, then you should probably begin by reading about :help itself. To do that, move the cursor onto the word ":help" and press the Enter key. .--------------------------------------------------------------. | Copyright (C) 1995 by Steve Kirkendall. Permission is granted | | to use and distribute this software in either source code | | form, or executable form, under the terms described in the | | license. The license is in the file "lib/license". This | | software is provided with no warranty of any kind. The | | author is not liable for any consequences arising from the | | use of this software. | ^--------------------------------------------------------------^ You can contact the author via e-mail at kirkenda@cs.pdx.edu, or via postal mail at: Steve Kirkendall 1500 SW Park Avenue, #326 Portland OR 97201 USA ═══ 1.1. What is elvis? ═══ 1. WHAT IS ELVIS? Elvis is a clone of vi/ex, the standard UNIX editor. Elvis supports nearly all of the vi/ex commands, in both visual mode and ex mode. Elvis adds support for multiple files, multiple windows, a variety of display modes, on-line help, and other miscellaneous extensions. Like vi/ex, Elvis stores most of the text in a temporary file, instead of RAM. This allows it to edit files that are too large to fit in a single process' data space. Also, the edit buffer can survive a power failure or crash. Elvis 2.1 runs under the following operating systems:  UNIX. If you have X-windows, elvis can use a graphical interface, in addition to the traditional text-based interface.  MS-Windows/95 and Windows/NT. Both a console (text-based) and a graphical version are available.  MS-DOS. It can also run in a DOS window under Windows 3.1. However, there is no graphic 16-bit version of elvis.  OS/2. The basic OS/2 port only supports a text-mode interface using VIO calls; it acts exactly like the termcap interface. There is also a real port of the termcap version which requires the EMX library, and a version which uses the graphical "x11" interface which requires XFree86. Elvis is freely redistributable, in either source form or executable form. There are very few restrictions on how you may use it. 1.1 About this manual This document is written in HTML. You should be able to view it with any Web browser, such as Mosaic or Netscape. These browsers also allow you to print the manual, if you prefer. You can also use elvis to view it or print it; elvis has a built-in HTML display mode. To print this document using elvis, you must first set some printer options. After that, you can just load any of these files, maybe set the display mode to HTML via the command ":display html" (if elvis doesn't set the display mode automatically), and then give the command ":lp". Each chapter is stored in a separate file; you'll need to print each one separately. A shell script/batch file named printdoc.bat is provided to help you do this. 1.2 Overview of Elvis The user interface of Elvis/vi/ex is weird. There are two major command modes in Elvis, and a few text input modes as well. Each command mode has a command which allows you to switch to the other mode. You will probably use the visual command mode most of the time. This is the mode that Elvis normally starts up in. In visual command mode, the entire screen is filled with lines of text from your file. Each keystroke is interpreted as part of a visual command. If you start typing text, it will not be inserted, it will be treated as part of a command. To insert text, you must first give an "insert text" command, such as i. This will take some getting used to. (An alternative exists. Look up the initialstate option.) The ex mode is quite different. Elvis displays a ":" character on the bottom line of the screen, as a prompt. You are then expected to type in a command line and hit the Enter key. The set of commands recognized in the ex mode is different from visual mode's. 1.3 Special features of Elvis Compared to the traditional ex/vi, elvis supports the following major new features: Multiple edit buffers You can edit several files at the same time. The :buffer ex command lists the current edit buffers. You can switch to a different buffer by typing :(buffername or :buffer buffername. Multiple windows The :split ex command or ^Ws visual command will create a new window showing the same edit buffer. You can use :split filename to edit a different file in a new window. Related commands allow you to do things like search for a tag and display it in a new window, or move among windows. Multiple user interfaces In addition to the traditional termcap user interface, elvis also supports graphical interfaces for X11 and Windows95, plus some other stripped-down interfaces. A variety of display modes The :display command lists the available display modes, and can set the display to a particular mode. The ^Wd visual command toggles between display modes. Online help This uses elvis' built-in "html" display mode to display the manual, which uses multiple fonts and hypertext links to improve readability. To access it, give the command :help. (But you already figured that out, didn't you?) Highly configurable Elvis has a set of configuration scripts, each of which is run at a specific time. For example, elvis.ini is run when elvis starts up, and elvis.arf is run after reading a file. See the chapter on sessions for a discussion of these. There is also an elvis.msg file which can be used to translate the built-in messages into another language. The X11 interface has a fully configurable toolbar. The elvis.syn file contains descriptions of various languages, for use with the syntax-coloring display mode. Enhanced tags The tags feature has been extended to support overloaded tags, which C++ tends to use a lot. See the tags chapter. Macro debugger To help you develop keyboard macros (and also report incompatibilities between elvis and vi), elvis has a built-in macro debugger. The the article in the Tips chapter. Network support Elvis can read via the http protocol, and read/write via the ftp protocol. See the Internet chapter. Aliases You can construct csh-style aliases for the ex commands, via the :alias command. See the article in the Tips chapter. New options Elvis has roughly 200 different options. See the Options chapter for a list. Built-in calculator Elvis has a : calc command which evaluates C-like expressions. These expressions are also used for some other commands, such as :if and :eval, among other things. See the Arithmetic expressions chapter. ═══ 1.2. Elvis 2.1 Visual Command Mode ═══ 2. VISUAL COMMAND MODE Most visual mode commands are one keystroke long. The following tables list the operation performed by each keystroke, and also denotes any options or arguments that it accepts. In addition to the keys listed here, your keyboard's "arrow" keys will be interpreted as the appropriate cursor movement commands. The same goes for (PgUp) and (PgDn), if your keyboard has them. The (Insert) key will toggle between insert mode and replace mode. There is a colon mode command (":map", to be described later) which will allow you to define other keys, such as function keys. A tip: visual command mode looks a lot like text input mode. If you forget which mode you're in, just hit the (Esc) key. If Elvis beeps, then you're in visual command mode. If Elvis does not beep, then you were in input mode, but by hitting (Esc) you will have switched to visual command mode. So, one way or another, after (Esc) Elvis will be ready for a command. 2.1 Notation The following notation is used in the tables that follow... count Many commands may be preceded by a count. This is a sequence of digits representing a decimal number. For most commands that use a count, the command is repeated count times, but a few commands use the count value for some completely different purpose. The count is always optional, and usually defaults to 1. key Some commands require two keystrokes. The first key always determines which command is to be executed. The second key is used as a parameter to the command. mv Some commands (! < > = c d y) operate on text between the cursor and some other position. Usually, the other position is specified by typing a movement command after the operator command, but there are other options. See the section on operators for more information. inp Many commands allow the user to interactively enter text. See the discussion of "input mode" in the following chapter. 2.2 Visual Commands, Grouped by Function  2.2.1 Edit commands  2.2.2 Edit commands which are operators  2.2.3 Edit commands which are shortcuts for operators  2.2.4 Movement commands which move by a line or column  2.2.5 Movement commands which are window-relative  2.2.6 Movement commands which search for strings  2.2.7 Movement commands which search for characters  2.2.8 Movement commands which move by words  2.2.9 Movement commands which move by sentences or sections  2.2.10 Movement/mark commands  2.2.11 Scrolling commands  2.2.12 Window commands  2.2.13 Other commands 2.2.1 Edit commands .--------------.------------------------------------------------------. | COMMAND | DESCRIPTION | |--------------|------------------------------------------------------| | P | Paste text before the cursor | | p | Paste text after the cursor | | count J | Join lines, to form one big line | | count X | Delete the character(s) to the left of the cursor | | count x | Delete the character that the cursor's on | | count ~ | Switch a character between uppercase & lowercase | | count r key | Replace "count" chars by a given character | | R inp | Overtype | | count a inp | Insert text after the cursor | | count A inp | Append at end of the line | | count i inp | Insert text at the cursor | | count I inp | Insert at the front of the line (after indents) | | count o inp | Open a new line below the current line | | count O inp | Open up a new line above the current line | | count . | Repeat the previous "edit" command | | count u | Undo the previous edit command | | count ^R | Redo commands which were undone by the u command | | U | Undo all recent changes to the current line | ^--------------^------------------------------------------------------^ P p The P and p commands paste text from a cut buffer. The difference between them is that p pastes after the cursor, and P pastes before it. See the section on cut buffers for more information. count J The J command joins the current line with the following line. If you supply a count argument, then it will joint that many lines together, starting at the current line. count X count x The X and x commands delete characters. The difference between them is that x deletes the character at the cursor, and X deletes the character before the cursor. If you supply a count, then it will delete that many characters. The deleted characters are copied into a cut buffer. The X and x commands never delete newline characters. count ~ The ~ command changes uppercase letters to lowercase, or vice versa, and moves the cursor forward. Non-letters are unaffected, but the cursor will still be moved forward. count r key The r command replaces a single character in the edit buffer with a single character read from the keyboard. If you supply a count, then it will replace that many characters in the edit buffer with multiple copies of a single character from the keyboard. R inp The R command switches the window to "replace mode" which is a variation of input mode. count a inp The a command switches to input mode with the cursor starting immediately after its previous position. If a count is supplied, then after you manually insert the first copy of the new text, elvis will automatically insert count-1 additional copies. count A inp The A command switches to input mode with the cursor starting at the end of the current line. If a count is supplied, then after you manually insert the first copy of the new text, elvis will automatically insert count-1 additional copies. count i inp The i command switches to input mode with the cursor starting at its current position. If a count is supplied, then after you manually insert the first copy of the new text, elvis will automatically insert count-1 additional copies. count I inp The I command switches to input mode with the cursor starting at the beginning of the current line. If a count is supplied, then after you manually insert the first copy of the new text, elvis will automatically insert count-1 additional copies. count o inp The o command switches to input mode. A new, blank line is created after the current line, and the cursor starts at the beginning of that new line. If a count is supplied, then after you manually insert the first copy of the new text, elvis will automatically insert count-1 additional copies. count O inp The O command switches to input mode. A new, blank line is created before the current line, and the cursor starts at the beginning of that new line. If a count is supplied, then after you manually insert the first copy of the new text, elvis will automatically insert count-1 additional copies. count . The . command repeats the previous command which changed text. If a count is supplied, it overrides count of the original command. count u The u command undoes the previous edit command. If a count is supplied, then it will undo that many changes, within the limit defined by the undolevels option. count ^R The ^R command redoes commands which were undone by the u command. Essentially it undoes the "undo". U The U command undoes all changes which were made to the current line since the cursor was moved onto it. 2.2.2 Edit commands which are operators .--------------.------------------------------------------------------. | COMMAND | DESCRIPTION | |--------------|------------------------------------------------------| | < mv | Shift text left | | > mv | Shift text right | | ! mv text| Run selected lines thru an external filter program | | = mv | Reformat | | c mv inp | Change text | | d mv | Delete text | | y mv | Yank text (copy it into a cut buffer) | ^--------------^------------------------------------------------------^ These commands all affect text between the cursor's current position and some other position. There are three ways that you can specify that other position:  Follow the command keystroke with a movement command. For example, dw deletes a single word. d3w and 3dw both delete three words.  Type the command keystroke twice. This causes whole lines to be acted upon. For example, >> indents the current line. 3>> indents the current line and the following two lines.  Move the cursor to one end of the text, type v, V, or ^V to start marking, move the cursor to the other end, and then type the desired command key. < mv > mv These commands adjust the indentation of lines. The < command reduces indentation by shiftwidth columns, and the > command increases indentation by the same amount. The type of whitespace used for the new indentation is determined by the autotab option. The doubled-up << and >> commands reduce or increase the indentation for the current line, respectively. ! mv text This command prompts you to enter a shell command line at the bottom of the window. When you've entered the command line, that command is executed and the selected text is piped through it. The resulting text replaces the original selected text. For example, 10!!sort will send 10 lines through the sort program. = mv When applied to lines, this command resembles the ! command, except that instead of prompting for a command line, the = command will always execute the program specified via the equalprg option. If you expect to be running the same filter program over and over again, then = is more convenient. When applied to characters selected via the v command, the = command uses elvis' built-in calculator to evaluate the characters, and then replaces the original text with the result of that evaluation. For example, if you move the cursor to the start of a parenthesized arithmetic expression and hit v%= then the expression will be simplified. c mv inp This command puts you in input mode so you can replace the selected text with new, manually-entered text. The doubled-up cc command changes the current line. d mv y mv These commands copy the selected text into a cut buffer. The d command then deletes the text from the edit buffer, but y leaves the original text intact. The doubled-up dd and yy commands delete or yank the current line, respectively. 2.2.3 Edit commands which are shortcuts for operators .--------------.------------------------------------------------------. | COMMAND | DESCRIPTION | |--------------|------------------------------------------------------| | C inp | Change text from the cursor to the end of the line | | D | Delete text from the cursor to the end of the line | | count S inp | Change lines, like "count" cc | | count s inp | Replace characters, like "count" cl | | count Y | Yank text line(s) (copy them into a cut buffer) | ^--------------^------------------------------------------------------^ C inp D count S inp count s int count Y All of these commands are shortcuts for particular operator/movement command combinations. C is short for c$, D is short for d$, uppercase S is short for cc, lowercase s is short for cl, and Y is short for yy. 2.2.4 Movement commands which move by a line or column .--------------.------------------------------------------------------. | COMMAND | DESCRIPTION | |--------------|------------------------------------------------------| | 0 | If not part of count, move to 1st char of this line | | ^ | Move to the front of the current line (after indent) | | $ | Move to the rear of the current line | | count | | Move to column "count" (defaulting to column 1) | | count ^X | Move to column "count" (defaulting to the right edge)| | count ^M | Move to the front of the next line | | count + | Move to the front of the next line | | count - | Move to the front of the preceding line | | count G | Move to line #"count" (default is the bottom line) | | count h | Move left | | count ^H | Move left | | count l | Move right | | count Space | Move right | | count j | Move down | | count ^J | Move down | | count ^N | Move down | | count k | Move up | | count ^P | Move up | | count _ | Move to the current line | ^--------------^------------------------------------------------------^ 0 The 0 command moves the cursor to the first character in the current line. ^ The ^ command moves the cursor to the first non-whitespace character in the current line. If the current line doesn't contain any non-whitespace characters, then the cursor is moved to the end of the line. $ The $ command moves the cursor to the last character in the line. count | count ^X These commands move the cursor to a given column. The leftmost column is designated "column 1." If the cursor can't be moved to the exact column number requested (e.g., because the line isn't that long, or the requested column falls in the middle of a tab character), then elvis will move the cursor as close as possible. If no count is given, then the | command moves the cursor to column 1 and the ^X move the cursor to the rightmost visible column (taking side scrolling into account). count ^M count + The ^M and + commands move the cursor down count lines (or 1 line if no count is given), and then to the first non-whitespace character in that destination line. It is equivalent to a j command followed by a ^ command. count - The - command moves the cursor up count lines (or 1 line if no count is given), and then to the first non-whitespace character in that destination line. It is equivalent to a k command followed by a ^ command. count G The G command moves the cursor directly to the start of a given line, or to the last line if no count is given. For the purposes of this command, the "line number" of the cursor position is defined to be one plus the number of newline characters which precede it in the buffer. This definition is used regardless of what display mode you happen to be using. The number and ruler options use the same definition. count h count ^H The h and ^H commands move the cursor count characters to the left, or 1 character leftward if no count is given. They won't move the cursor past the beginning of the line. count l count Space The h and Space commands move the cursor count characters to the right, or 1 character rightward if no count is given. They won't move the cursor past the end of the line. count j count ^J count ^N These commands all move the cursor down count lines (or 1 line if no count is given), without changing the column of the cursor if possible. count k count ^P These commands all move the cursor up count lines (or 1 line if no count is given), without changing the column of the cursor if possible. count _ The _ command moves the cursor down count-1 lines. This command is used internally to implement the double-operators; for example, << is interpreted as <_. By itself the _ command is pretty useless. 2.2.5 Movement commands which are window-relative .--------------.------------------------------------------------------. | COMMAND | DESCRIPTION | |--------------|------------------------------------------------------| | count H | Move to home row (the line at the top of the screen) | | M | Move to middle row | | count L | Move to last row (i.e., line at bottom of window) | ^--------------^------------------------------------------------------^ count H The H command moves the cursor to the front of the first line that is currently visible in the window. If a count is given, then it will move down count-1 lines from the top of the window. M The M command moves the cursor to the front of the line in the middle of the window. count L The L command moves the cursor to the front of the line line that is currently visible in the window. If a count is given, then it will move up count-1 lines from the bottom of the window. 2.2.6 Movement commands which search for strings .--------------.------------------------------------------------------. | COMMAND | DESCRIPTION | |--------------|------------------------------------------------------| | / text | Search forward for a given regular expression | | ? text | Search backward for a given regular expression | | ^A | Search for next occurrence of word at cursor | | n | Repeat the previous search | | N | Repeat previous search, but in the opposite direction| ^--------------^------------------------------------------------------^ All of these search commands are affected by the magic, ignorecase, wrapscan, and autoselect options. / text ? text These commands prompt you to enter a regular expression at the bottom of the window. When you have entered it, elvis will search forward (for /) or backward (for ?) for text which matches the regular expression. Normally the cursor is positioned at the start of the matching text. If you want to include a / or ? character in the regular expression, you must precede it with a backslash; otherwise it will be interpreted as a closing delimiter. When entering the regular expression, you can append a closing delimiter (/ or ?, as appropriate) followed by a line delta (+ or - followed by a line number) to move the cursor to the start of a line after or before the matching text. You can also use v or n flags to temporarily force the autoselect option on or off for that one search. ^A This command searches forward for the next instance of the word under the cursor. It is a shortcut for the /\<\@\> Enter command. n N These commands repeat the previous /, ?, or ^A command. The n command repeats it in the same direction as the original search, and N repeats it in the opposite direction. 2.2.7 Movement commands which search for characters .--------------.------------------------------------------------------. | COMMAND | DESCRIPTION | |--------------|------------------------------------------------------| | count % | Move to matching (){}[] or to a given % of file | | count F key | Move leftward to a given character | | count f key | Move rightward to a given character | | count T key | Move leftward *almost* to a given character | | count t key | Move rightward *almost* to a given character | | count , | Repeat the previous [fFtT] but in the other direction| | count ; | Repeat the previous [fFtT] cmd | ^--------------^------------------------------------------------------^ count % This command actually performs one of two totally separate movements, depending on whether a count was supplied. With no count, if the cursor is on a parenthesis character from the matchchar list, then it moves the cursor to the opposite parenthesis. If the cursor isn't on a parenthesis to begin with, then elvis will scan forward on the current line until it finds one, and then move to its opposite. It can also show matching preprocessor directives, if the window is in the syntax display mode for a language which has a preprocessor. However, if a count is supplied, then it is used as a percentage from 1 to 100, and the cursor is moved to that percentage of the way into the buffer. For example, typing 50% will move the cursor to the middle of the buffer. count F key count f key These commands search for the character key in the current line, starting from the cursor position. For example, fk searches forward for the next "k". F4 searches backward for the previous "4". If the end of line is reached without finding the character, then the command fails. count T key count t key These commands move almost, but not quite, to the next instance of key. The t and T commands stop one character short of where f and F would stop, respectively. count , count ; The ; command repeats the previous f, F, t, or T command. You don't need to type a key because elvis automatically uses whatever key you looked for last time. The , command also repeats the previous f, F, t, or T command, but in the reverse direction. 2.2.8 Movement commands which move by words .--------------.------------------------------------------------------. | COMMAND | DESCRIPTION | |--------------|------------------------------------------------------| | count w | Move forward "count" words | | count e | Move forward to the end of the current word | | count b | Move back "count" words | | count W | Move forward "count" Words | | count E | Move end of Word | | count B | Move back Word | ^--------------^------------------------------------------------------^ The uppercase and lowercase versions of these commands differ only in their definition of a "word." The uppercase commands consider a word to be any sequence of non-whitespace characters, bound by whitespace characters or the ends of the buffer. The lowercase commands define a word as either a sequence of alphanumeric characters, or a sequence of punctuation characters, but not a mixture of the two; these words can be bound by whitespace, the ends of the buffer, or by characters from the other class of lowercase word. (I.e, an alphanumeric word can be bound by punctuation characters, and a punctuation word can be bound by alphanumeric characters.) The underscore character is considered to be alphanumeric. count w count W The w and W commands move the cursor forward to the start of the next word. If a count is given, the cursor will move forward count words. count e count E The e and E commands move the cursor forward to the end of the current word, or if it is already at the end of the word then it'll move to the end of the following word. If a count is given, the cursor will move forward count word ends. NOTE: These commands are often used as the targets of the operator commands, as in dw or de. When used this way, the difference between them is that dw includes any whitespace after the word, but de does not. count b count B The b and B commands move the cursor backward to the start of the current word, or if it is already at the start of the word then it'll move to the start of the preceding word. If a count is given, the cursor will move backward count word starts. 2.2.9 Movement commands which move by sentences or sections .--------------.------------------------------------------------------. | COMMAND | DESCRIPTION | |--------------|------------------------------------------------------| | count ( | Move backward "count" sentences | | count ) | Move forward "count" sentences | | count { | Move back "count" paragraphs | | count } | Move forward "count" paragraphs | | [ [ | Move back 1 section | | ] ] | Move forward 1 section | ^--------------^------------------------------------------------------^ count ( count ) These commands move backward or forward to the start of a sentence. The start of a sentence is defined to be the first non-whitespace character in the file, or the first non-whitespace character after the end of a sentence. The exact definition of the end of a sentence depends on the values of the sentenceend, sentencegap, and sentencequote options. The default values of those options define a sentence end to be a period, question mark, or exclamation mark, followed by either a newline character, or two or more space characters. Any number of double-quote characters or closing parentheses may appear between the punctuation and the whitespace. count { count } These commands move backward or forward to the start of a paragraph. The start of a paragraph is defined to be the first blank line encountered after a non-blank line; or a line which contains a troff paragraph command listed in the paragraphs option's value; or the start of a section as described below. [[ ]] These commands move backward or forward to the start of a section. The start of a section is defined to be '{' character in column 1 of a line; or a troff section command listed in the value of the sections option. Note: There are also [key and ]key commands for recording keystrokes. Those commands are not related to the [[ and ]] movement commands. 2.2.10 Movement/mark commands .--------------.------------------------------------------------------. | COMMAND | DESCRIPTION | |--------------|------------------------------------------------------| | m key | Mark a line or character | | ' key | Move to a marked line | | ` key | Move to a marked character | | V | Start marking lines for c d y < > or ! | | v | Start marking characters for c d y < > or ! | | ^V | Start marking a rectangle for c d y < > or ! | ^--------------^------------------------------------------------------^ m key The mkey command stores the current cursor position in mark named key, where key is any letter. The mark is not visible. ' key ` key These commands move the cursor back to a position which was stored via the mkey command. The `key (grave) command is a character-movement command which positions the cursor exactly on the marked character. The 'key (apostrophe) command is a line-movement command which positions the cursor at the front of the line containing the mark. The distinction between character-movement and line-movement becomes more significant when you're using the movement command as the target of an operator command. For example, after an ma command and some cursor movement, the command d'a would delete whole lines, but the command d`a would delete only the text between the cursor and the "a" mark. v V ^V These commands start visually selecting text for use by an operator command. The lowercase v command starts selecting characters, uppercase V starts selecting lines, and ^V starts selecting a rectangular area. 2.2.11 Scrolling commands .--------------.------------------------------------------------------. | COMMAND | DESCRIPTION | |--------------|------------------------------------------------------| | ^F | Move toward the bottom of the file by 1 screen full | | ^B | Move toward the top of the file by 1 screen full | | z key | Scroll current line to window's +top -bottom .middle | | count ^D | Scroll forward "count" lines (default 1/2 screen) | | count ^E | Scroll forward "count" lines (default 1 line) | | count ^U | Scroll backward "count" lines (default 1/2 screen) | | count ^Y | Scroll backward "count" lines (default 1 line) | ^--------------^------------------------------------------------------^ ^F This command moves forward one screen. Specifically, it locates the line at the bottom of the window and moves it to the top of the window. This means that for a 24-row window, ^F will generally move forward 22 lines. The cursor is moved if necessary to keep it on the screen. ^B This command moves backward one screen, by moving the line at the top of the window to the bottom. It is the opposite of the ^F command. z key This command scrolls the current line to either the top (if key is "+"), middle (if key is "." or "z"), or bottom (if key is "-") of the window. count ^D count ^E These commands scroll the window forward by count lines. If no count is given, then ^E defaults to 1 line, and ^D defaults to the value of the scroll option. Supplying a count to the ^D option has the side-effect of setting the scroll option to count. count ^U count ^Y These commands scroll the window backward by count lines. If no count is given, then ^Y defaults to 1 line, and ^U defaults to the value of the scroll option. Supplying a count to the ^U option has the side-effect of setting the scroll option to count. 2.2.12 Window commands .--------------.------------------------------------------------------. | COMMAND | DESCRIPTION | |--------------|------------------------------------------------------| | ^W s | Split current window | | ^W ] | Split window, then look up tag at cursor | | ^W n | Split window, and create a new buffer | | ^W q | Save buffer & close window, like ZZ | | ^W c | Hide buffer & close window | | ^W d | Toggle the display mode | | ^W S | Toggle the sidescroll option | | ^W j | Move down to next window | | ^W k | Move up to previous window | | count ^W ^W | Move to next window, or to the "count" window | ^--------------^------------------------------------------------------^ ^W s This creates a new window, showing the same buffer as the current window. It is equivalent to the ex :split command with no arguments. ^W ] This performs tag lookup on the word at the cursor, and then creates a new window to show the tag definition. It is similar to the ex :stag command. ^W n This creates a new buffer, and then creates a new window to show that buffer. It is similar to the ex :snew command. ^W q This saves the buffer if it has changed, and then closes the window. It is identical to the visual ZZ command, and similar to the ex :xit command. ^W c This closes the window, but it neither saves nor discards the current buffer. The buffer continues to exist. This command is like the ex :close command. ^W d This toggles the windows display mode between two different modes. If the buffer's bufdisplay option is set to "html", "man", or "tex", then it will toggle between that mode and the syntax coloring mode. If bufdisplay is set to a syntax-coloring mode or "hex" then it toggles between that mode and "normal". If bufdisplay is "normal", then this command toggles between that mode and the "hex" mode. ^W S This toggles the wrap option off or on, causing sideways scrolling to be alternately disabled and enabled. ^W j ^W k count ^W ^W These commands make other windows be current. This is the only possible way to switch windows for some user interfaces such as the termcap interface. NOTE: In addition to the commands shown here, some user interfaces may support extensions to these commands. For example, the termcap interface uses ^W+ to increase the size of the current window, ^W- to reduce the size of the current window, and ^W\ to make the current window as large as possible. 2.2.13 Other commands .--------------.------------------------------------------------------. | COMMAND | DESCRIPTION | |--------------|------------------------------------------------------| | " key | Select which cut buffer to use next | | @ key | Execute the contents of a cut-buffer as VI commands | | [ key | Start recording keystrokes into a cut-buffer | | ] key | Stop recording keystrokes into a cut-buffer | | : text | Run single EX cmd | | Q | Quit to EX mode | | K | Run keywordprg on the word at the cursor | | Z Z | Save the file & exit | | ^Z | Either suspend elvis, or fork a shell | | ^G | Show file status, and the current line # | | ^L | Redraw the screen | | * | Go to the next error in the errlist | | ^I | In HTML mode, move forward to next link | | ^T | Return to source of previous :tag or ^] command. | | ^] | If the cursor is on a tag name, go to that tag | | ^^ | Switch to the previous file, like ":e #" | | count # key | Increment a number | | count & | Repeat the previous ":s//" command here | ^--------------^------------------------------------------------------^ " key This command determines which cut buffer the next command will use. If the next command doesn't involve a cut buffer, then this command has no effect. If you don't use this command, then the following command will use the anonymous cut buffer. @ key The @ command executes the contents of a cut buffer as a series of vi command keystrokes. The key after the @ is the name of the cut buffer to be executed. [ key ] key These commands are used for recording keystrokes into a cut-buffer. The key is the name of the cut buffer; it must be a letter. Later, you can replay the keystrokes via the @key command. Note: There are also [[ and ]] commands for moving the cursor to the start of a section. Those movement commands are unrelated to these [key and ]key keystroke recording commands. : Q This : command allows you to enter a single ex command, and then immediately return to visual command. The Q command is similar, except that it causes you to remain in ex mode until you give the ex :vi command. K This command executes the program named in the keywordprg option, passing it the word at the cursor. This is intended to provide an easy way to run on-line manuals and the like. ZZ The ZZ command writes the current file if it has changed, and then exits. It is equivalent to the ex :xit command. ^Z This command will either suspend elvis, or fork a shell program. Either way, you'll get a shell prompt. ^Z is equivalent to the :stop ex command. ^G The ^G command displays the status of the current file. It is equivalent to the ex :file command with no arguments. ^L The ^L command causes the current window to be redrawn from scratch. This is handy when another program or line noise changes the screen in a way that elvis can't detect & correct automatically. * The * command moves the cursor to the next error reported by the compiler. It is equivalent to the ex :errlist command. ^I The ^I command (the Tab key) moves the cursor forward to the next hypertext link, if you're in the "html" display mode. ^] ^T The ^] command performs tag lookup on the word at the cursor position, and moves the cursor to the file/line where the tag is defined. It resembles the ex :tag command. The ^T command returns the cursor to the previous position, like :pop. ^^ After you've switched edit buffers in a window, the ^^ (Control-Carat) command switches back to the previous buffer, and moves the cursor to its previous position within that buffer. It is like the ex :e# command. count # key This command allows you add or subtract count to the number at the cursor. If the cursor isn't on a word that looks like a number, then the command fails. If no count is given, then 1 is assumed. If the key is "-" then count is subtracted from the number. If the key is "+" or "#" then count is added to the number. If the key is "=" then the word is changed to count. Any other key causes the command to fail. count & Repeat the previous :s/re/new/ command on the current line. If count is given, then also apply it to each of the count-1 following lines as well. 2.3 Visual Commands, sorted by their ASCII code .--------------.------------------------------------------------------. | COMMAND | DESCRIPTION | |--------------|------------------------------------------------------| | NUL | (undefined) | | ^A | Search for next occurrence of word at cursor | | ^B | Move toward the top of the file by 1 screen full | | ^C | (undefined; may abort a time-consuming command) | | count ^D | Scroll forward "count" lines (default 1/2 screen) | | count ^E | Scroll forward "count" lines (default 1 line) | | ^F | Move toward the bottom of the file by 1 screen full | | ^G | Show file status, and the current line # | | count ^H | Move left | | ^I | (Tab) In "html" display mode, move to next hyperlink | | count ^J | Move down | | ^K | (undefined) | | ^L | Redraw the screen | | count ^M | Move to the front of the next line | | count ^N | Move down | | ^O | ignored, to simplify implementation of "visual" map | | count ^P | Move up | | ^Q | (undefined; may resume stopped output) | | count ^R | Redo commands which were undone by the u command | | ^S | (undefined; may stop output) | | ^T | Return to source of previous :tag or ^] command. | | count ^U | Scroll backward "count" lines (default 1/2 screen) | | ^V | Start marking a rectangle for c d y < > or ! | | count ^W ^W | Move to next window, or to the "count" window | | ^W S | Toggle the sidescroll option | | ^W ] | Split window, then look up tag at cursor | | ^W c | Hide buffer & close window | | ^W d | Toggle the display mode | | ^W j | Move down to next window | | ^W k | Move up to previous window | | ^W n | Split window, and create a new buffer | | ^W q | Save buffer & close window, like ZZ | | ^W s | Split current window | | count ^X | Move to column "count" (defaulting to the right edge)| | count ^Y | Scroll backward "count" lines (default 1 line) | | ^Z | Either suspend elvis, or fork a shell | | ^[ | (Escape) Cancels a partially-entered command | | ^\ | (undefined; may cause core dump) | | ^] | If the cursor is on a tag name, go to that tag | | ^^ | Switch to the previous file, like ":e #" | | ^_ | (undefined) | | count Space | Move right | | ! mv | Run selected lines thru an external filter program | | " key | Select which cut buffer to use next | | count # key | Increment a number | | $ | Move to the rear of the current line | | count % | Move to matching (){}[] or to a given % of file | | count & | Repeat the previous ":s//" command here | | ' key | Move to a marked line | | count ( | Move backward "count" sentences | | count ) | Move forward "count" sentences | | * | Go to the next error in the errlist | | count + | Move to the front of the next line | | count , | Repeat the previous [fFtT] but in the other direction| | count - | Move to the front of the preceding line | | count . | Repeat the previous "edit" command | | / text | Search forward for a given regular expression | | 0 | If not part of count, move to 1st char of this line | | 1 | Part of a count argument | | 2 | Part of a count argument | | 3 | Part of a count argument | | 4 | Part of a count argument | | 5 | Part of a count argument | | 6 | Part of a count argument | | 7 | Part of a count argument | | 8 | Part of a count argument | | 9 | Part of a count argument | | : text | Run single EX cmd | | count ; | Repeat the previous [fFtT] cmd | | < mv | Shift text left | | = mv | Reformat | | > mv | Shift text right | | ? text | Search backward for a given regular expression | | @ key | Execute the contents of a cut-buffer as VI commands | | count A inp | Append at end of the line | | count B | Move back Word | | C inp | Change text from the cursor to the end of the line | | D | Delete text from the cursor to the end of the line | | count E | Move end of Word | | count F key | Move leftward to a given character | | count G | Move to line #"count" (default is the bottom line) | | count H | Move to home row (the line at the top of the screen) | | count I inp | Insert at the front of the line (after indents) | | count J | Join lines, to form one big line | | K | Run keywordprg on the word at the cursor | | count L | Move to last row (i.e., line at bottom of window) | | M | Move to middle row | | N | Repeat previous search, but in the opposite direction| | count O inp | Open up a new line above the current line | | P | Paste text before the cursor | | Q | Quit to EX mode | | R inp | Overtype | | count S inp | Change lines, like "count" cc | | count T key | Move leftward *almost* to a given character | | U | Undo all recent changes to the current line | | V | Start marking lines for c d y < > or ! | | count W | Move forward "count" Words | | count X | Delete the character(s) to the left of the cursor | | count Y | Yank text line(s) (copy them into a cut buffer) | | Z Z | Save the file & exit | | [ [ | Move back 1 section | | [ key | Start recording keystrokes into a cut-buffer | | \ | (undefined) | | ] ] | Move forward 1 section | | ] key | Stop recording keystrokes into a cut-buffer | | ^ | Move to the front of the current line (after indent) | | count _ | (the underscore character) Move to the current line | | ` key | Move to a marked character | | count a inp | Insert text after the cursor | | count b | Move back "count" words | | c mv | Change text | | d mv | Delete text | | count e | Move forward to the end of the current word | | count f key | Move rightward to a given character | | g | (undefined) | | count h | Move left | | count i inp | Insert text at the cursor | | count j | Move down | | count k | Move up | | count l | Move right | | m key | Mark a line or character | | n | Repeat the previous search | | count o inp | Open a new line below the current line | | p | Paste text after the cursor | | q | (undefined) | | count r key | Replace "count" chars by a given character | | count s inp | Replace characters, like "count" cl | | count t key | Move rightward *almost* to a given character | | count u | Undo the previous edit command | | v | Start marking characters for c d y < > or ! | | count w | Move forward "count" words | | count x | Delete the character that the cursor's on | | y mv | Yank text (copy it into a cut buffer) | | z key | Scroll current line to window's +top -bottom .middle | | count { | Move back "count" paragraphs | | count | | Move to column "count" (defaulting to column 1) | | count } | Move forward "count" paragraphs | | count ~ | Switch a character between uppercase & lowercase | | DEL | (undefined) | ^--------------^------------------------------------------------------^ ═══ 1.3. Elvis 2.1 Input Mode ═══ 3. INPUT MODE You can't type text into your file directly from visual command mode. Instead, you must first give a command which will put you into input mode. The commands to do this are A, C, I, O, R, S, a, i, o, and s. The S, s, C, and c commands temporarily place a $ at the end of the text that they are going to change. In input mode, all keystrokes are inserted into the text at the cursor's position, except for the following: .-----.-----------------------------------------------------. | KEY | FUNCTION | |-----|-----------------------------------------------------| | ^@ | (Nul) Insert a copy of last input text, then exit | | ^A | Insert a copy of the last input text | | ^D | Delete one indent character | | ^H | (Backspace) Erase the character before the cursor | | ^I | (Tab) Depends on the inputtab option | | ^K | Compose the next two characters as a digraph | | ^M | (Enter) Insert a newline (^J, linefeed) | | ^O | Read & run a single vi command, then resume input | | ^P | Insert the contents of the cut buffer | | ^R | Redraw the window, like ^L | | ^T | Insert an indent character | | ^U | Backspace to the beginning of the line | | ^V | Insert the following keystroke, even if special | | ^W | Backspace to the beginning of the current word | | ^X | Use the next two keystrokes as hex digits of 1 byte | | ^[ | (ESCape) Exit from input mode, back to command mode | ^-----^-----------------------------------------------------^ Also, on some systems, ^S may stop output, ^Q may restart output, and ^C may interrupt execution. The R visual command puts you in overtype mode, which is a slightly different form of input mode. In overtype mode, each time you insert a character, one of the old characters is deleted from the file. 3.1 Arrow keys in Input Mode The arrow keys can be used to move the cursor in input mode. (This is an extension; the real Vi doesn't support arrow keys in input mode.) The PgUp, PgDn, Home, and End keys work in input mode, too. The Delete key deletes a single character in input mode. The Insert key toggles between input mode and replace mode. 3.2 Digraphs Elvis supports digraphs as a way to enter non-ASCII characters. A digraph is a character which is composed of two other characters. For example, an apostrophe and the letter i could be defined as a digraph which is to be stored and displayed as an accented i. There is no single standard for extended ASCII character sets, so elvis uses a configurable digraph table. You can view or edit the digraph table via the :digraph! ex command. When inputting text, there are two ways you can type in a digraph. The first way is to type the first character, then hit backspace, and then type the second character. Elvis will then substitute the non-ASCII character in their place. Digraphs entered this way will not be recognized unless you've turned on the digraph option. The other way is to type ^K followed by the two characters, without a backspace. This method works regardless of the value of the digraph option. 3.2.1 Latin-1 digraphs The most common standard for non-ASCII symbol sets is called Latin-1 (or ISO 8859/1, or ECMA-94 -- these are all the same). This symbol set is used by X-windows and graphical Windows95 programs, but not MS-DOS. Elvis is distributed with a file named lib/elvis.lat which contains the :digraph commands necessary to set up the digraph table appropriately for Latin-1. Most of these digraphs are fairly straight-forward. For example, to generate an accented "i", type ^K, i, and an apostrophe character. You can list all of the digraphs via the command ":dig!" The default lib/elvis.ini file reads the lib/elvis.lat file automatically. This is very handy if your system really does use Latin-1, but if it doesn't then you'll probably want to disable the automatic loading. You can disable it by editing the lib/elvis.ini file, searching for the "source! (elvispath("elvis.lat"))" line, and inserting a double-quote character at the start of that line. 3.2.2 PC-8 digraphs MS-DOS doesn't use Latin-1, and neither do OS/2 or Win32 console applications, such as elvis. So for Microsoft operating systems, elvis loads its digraph table via a file named lib/elvis.pc8. This sets up the digraph table appropriately for the 437 code page, which is Microsoft's default. If you use a different code page, you may wish to edit lib/elvis.pc8. 3.3 Abbreviations Elvis can expand abbreviations for you. You define an abbreviation with the :abbr command, and then whenever you type in the abbreviated form while in input mode, Elvis will immediately replace it with the long form. COBOL programmers should find this useful. :-) Elvis doesn't perform the substitution until you type a non-alphanumeric character to mark the end of the word. If you type a control-V before that non-alphanumeric character, then Elvis will not perform the substitution. Elvis also requires the abbreviated text to either appear at the start of a line, or immediately after a non-alphanumeric character. This prevents elvis from trying to treat the ends of words as abbreviations. This is necessary so that if you set up an abbreviation which maps "ed" to "editor", elvis won't mangle "confused" into "confuseditor". Abbreviations are allowed to contain punctuation characters. For example, TeX users might find it useful to map "\b" to "\begin". 3.4 Auto-Indent With the autoindent option turned on, Elvis will automatically insert leading whitespace at the beginning of each new line that you type in. The leading whitespace is copied from the preceding line. To add more leading whitespace, type control-T. To remove some whitespace, type control-D. If you ":set noautotab", then the whitespace generated by control-T will always consist of spaces -- never tabs. Some people seem to prefer this. Elvis' autoindent mode isn't 100% compatible with vi's. In Elvis, 0^D and ^^D don't work, ^U can wipe out all indentation, and sometimes Elvis will use a different amount of indentation than vi would. ═══ 1.4. Elvis 2.1 Ex Mode ═══ 4. EX COMMAND MODE Ex is an editing mode in which elvis acts like a line editor. This means that you type in a command line, and when the line is complete elvis executes it on the current text buffer. I.e., in ex each line (or group of lines) is a command, as opposed to vi where each character (or group of characters) is a command. Typically, ex commands are used to do perform complex actions such as global search & replace, or actions which require an argument such as writing the edit buffer out to a different file. Ex is also used as the configuration language for elvis; configuration scripts such as elvis.ini, .exrc (or elvis.rc), and elvis.arf contain a series of ex commands. You can switch freely between vi and ex. If you're in vi mode, you can enter a single ex command line via the visual : command, or more permanently switch via the visual Q command. If you're in ex mode, you can switch to vi mode via ex's :vi command. Normally elvis will start in vi mode, but you can force it to start in ex mode by supplying a -e command line flag. On UNIX systems, you can link elvis to a name which ends with "x" to achieve the same effect. The remainder of this section discusses how to enter lines, the general syntax of an ex command line, and the specific commands which elvis supports. 4.1 Entering lines In elvis, when you're typing in an ex command line you're really inputting text into a buffer named "Elvis ex history". All of the usual input mode commands are available, including Backspace to erase the previous character, Control-W to erase the previous word, and so on. Any previously entered lines will still be in the "Elvis ex history" buffer, and you can use the arrow keys to move back and edit earlier commands. You can even use the Control-O input-mode command with the ?regexp visual command, to search for an earlier command line. When you hit the Enter key on a line in the "Elvis ex history" buffer, elvis sends that line to the ex command parser, which is described in the next section. 4.1.1 An example Suppose you enter the command... :e ~/proj1/src/header.h ...and then realize that you really wanted "header2.h" instead of "header.h". You simplest way to get "header2.h" is to... 1. Hit the : key to start a new ex command line. 2. Hit the Up arrow key, or ^O k to move back to the preceding command line (which was ":e ~/proj1/src/header.h"). ^O k works because ^O reads and executes one vi command, and the k vi command moves the cursor back one line. The Up arrow key works because it is mapped to "visual k", which does exactly the same thing as ^O k. 3. Hit the Left arrow key twice, or ^O 2 h, to move the cursor back to the '.' character in "header.h". 4. Hit 2 to insert a '2' before the '.' character. At this point, the line should look like ":e ~/proj1/src/header2.h". 5. Hit Enter to submit the revised command line. Or suppose you really wanted "footer2.h" instead of "header2.h". This is a little trickier because you want to delete characters in the middle of the command line, before inserting the correct text. The simplest way to do this is move the cursor to a point just after the last character that you want to delete, and then backspace over them. The steps are: 1. Hit the : key to start a new ex command line. 2. Hit the Up arrow key or ^O k repeatedly to move back to the ":e ~/proj1/src/header2.h"command line. 3. Hit the Left arrow key five times, or ^O 5 h, to move the cursor back to the last 'e' character in "header2.h". 4. Hit the Backspace key four times to delete the word "head". It will still show on the screen, but elvis will know that it has been deleted. This is the same sort of behavior that elvis (and vi) exhibits when you backspace over newly entered text in input mode. 5. Type f o o t to insert "foot" where "head" used to be. At this point, the line should look like ":e ~/proj1/src/footer2.h". 6. Hit Enter to submit the revised command line. 4.1.2 The TAB key The Tab key has a special function when you're inputting text into the "Elvis ex history" buffer. It is used for name completion. (Exception: Under MS-DOS, this feature is disabled in order to reduce the size of the program, so it will fit in the lower 640K.) Name completion works like this: The preceding word is assumed to be a partial name for an ex command, an option, a tag, or a file. The type of name is determined by the context in which it appears -- commands appear at the start of an ex command line, and the others can only occur after certain, specific command names. Elvis searches for all matches of the appropriate type. If there are multiple matches, then elvis fills in as many characters of the name as possible, and then stops; or, if no additional characters are implied by the matching names, then elvis lists all matching names and redisplays the command line. If there is a single match, then elvis completes the name and appends a tab character or some other appropriate character. If there are no matches, then elvis simply inserts a tab character. Also, if while entering a :set command you hit the Tab key immediately after "option=" then elvis will insert the current value of the option. You can then edit that value before submitting the command line. I tried to make elvis smart enough that the Tab key will only attempt file/command/option completion in contexts where it makes sense to do so, but that code might not be 100% correct. You can bypass the completion by typing a Control-V before the Tab key. You can also disable name completion altogether by setting the "Elvis ex history" buffer's inputtab option to "tab", via the following command: :(Elvis ex history)set inputtab=tab By default, elvis ignores binary files when performing filename completion. The completebinary option can be used to make elvis include binary files. That's a global option (unlike inputtab which is associated with a specific buffer), so you don't need to specify the buffer name; a simple :set completebinary will set it. 4.2 Syntax and Addressing In general, ex command lines can begin with an optional window id. This may be followed by an optional buffer id, and then 0, 1, or 2 line addresses, followed by a command name, and perhaps some arguments after that (depending on the command name). A window ID is typed in as a decimal number followed by a colon character. If you don't supply a window ID (and you almost never will) then it defaults to the window where you typed in the command line. The :buffer command lists the buffers, and shows which one is being edited in which window. Also, the windowid option indicates the ID of the current window. A buffer ID is given by typing an opening parenthesis, the name of the buffer, and a closing parenthesis. For user buffers, the name of the buffer is usually identical to the name of the file that it corresponds to. For example, a file named ~/.Xdefaults would be loaded into a buffer which could be addressed as (~/.Xdefaults). Elvis also assigns numbers to user buffers, which may be more convenient to type since numbers are generally shorter than names. If ~/.Xdefaults is the first file you've edited since starting elvis, then its buffer could be addressed as (1). The :buffer command shows the number for each user buffer. Elvis also has several internal buffers, all of which have names that start with "Elvis ", such as (Elvis cut buffer x) and (Elvis error list). The :buffer! command (with a ! suffix) will list them all. For the sake of brevity, elvis allows you to refer to cut buffers as ("x). Similarly, the other internal buffers can be referred to via a " character and the initial letter in each word of the full name, such as ("Eel) for (Elvis error list). Commands which don't access the text, such as ":quit", don't allow any line addresses. Other commands, such as ":mark", only allow a single line address. Most commands, though, allow two line addresses; the command is applied to all lines between the two specified lines, inclusively. The tables below indicate how many line addresses each command allows. Line addresses are always optional. The first line address of most commands usually defaults to the current line. The second line address usually defaults to be the same as the first line address. Exceptions are :write, :lpr, :global, and :vglobal, which act on all lines of the file by default, and :!, which acts on no lines by default. If you use the visual V command to mark a range of lines, and then use the visual : command to execute a single ex command, then the default range affected by the ex command will be the visibly marked text. Line addresses consist of an absolute part and a relative part. The absolute part of a line specifier may be either an explicit line number, a mark, a dot to denote the current line, a dollar sign to denote the last line of the file, or a forward or backward search. An explicit line number is simply a decimal number, expressed as a string of digits. A mark is typed in as an apostrophe followed by a letter. Marks must be set before they can be used. You can set a mark in visual command mode by typing "m" and a letter, or you can set it in ex command mode via the "mark" command. A forward search is typed in as a regular expression surrounded by slash characters; searching begins at the default line. A backward search is typed in as a regular expression surrounded by question marks; searching begins at the line before the default line. If you omit the absolute part, then the default line is used. The relative part of a line specifier is typed as a + or - character followed by a decimal number. The number is added to or subtracted from the absolute part of the line specifier to produce the final line number. As a special case, the % character may be used to specify all lines of the file. It is roughly equivalent to saying 1,$. This can be a handy shortcut. Here are some addressing examples, using the :p command: COMMAND | ACTION -------------|------------------------------------------- :p | print the current line :37p | print line 37 :'gp | print the line which contains mark g :/foo/p | print the next line that contains "foo" :$p | print the last line of the buffer :20,30p | print lines 20 through 30 :1,$p | print all lines of the buffer :%p | print all lines of the buffer :(zot)%p | print all lines of the "zot" buffer :/foo/-2,+4p | print 5 lines around the next "foo" The optional addresses are followed by the command name. Command names may be abbreviated. In the sections that follow, the command's full name is given with the optional part enclosed in square brackets. Some commands allow a '!' character to appear immediately after the command name. The significance of the '!' varies from one command to another, but typically it forces the command to do something dangerous that it would ordinarily refuse to do. For example, :w file refuses to overwrite an existing file, but :w! file will do it. Many commands allow (or even require) additional arguments. The descriptions below list which arguments each command accepts with optional commands denoted by square brackets. The most common argument types are: /regexp/ This is a regular expression. You can use any punctuation character to delimit it, but the '/' character is the most commonly used. /regexp/newtext/ This is a regular expression followed by replacement text. count This is a number - a string of digits. Generally, it is used as the repeat count for certain commands. cutbuf This is the name of a cut buffer - a single letter. Elvis also allows (but does not require) a quote character before the letter. excmds This is another ex command, or list of ex commands. Traditionally, the whole list of commands had to appear on the same line, delimited by '|' characters. Elvis has the added versatility of allowing a '{' character on the first line, each command on a separate following line, and then '}' on a line by itself to mark the end of the ex command list. lhs This is string of characters. If whitespace characters are to be included in it, then they must be quoted by embedding a ^V character before them. line This is a line address, as described earlier. mark This is the name of a mark - a single lowercase letter. Elvis allows (but does not require) an apostrophe before the letter. rhs This is a string of characters. If it begins with a whitespace character, then that character must be quoted by embedding a ^V character in the command line before it. Other whitespace characters in the string do not need to be quoted. expr This is an arithmetic expression using the normal syntax. shellcmd This is a command line which is passed to the system's command interpreter. Within the command line, the following character substitutions take place, unless preceded by a backslash: .-----------.----------------------------. | CHARACTER | REPLACED BY | |-----------|----------------------------| | % | Name of current file | | # | Name of alternate file | | #n | Name of file whose bufid=n | | ! | Previous command line | | \@ | Word at cursor location | ^-----------^----------------------------^ Note that the \@ substitution requires a backslash. This quirk exists for the sake of backward compatibility - the real vi doesn't perform any substitutions for just plain @. file or files This is one or more file name, or a "wildcard" pattern which matches the names of zero or more files. File names are subjected to three levels of processing. First, leading ~ characters and certain other characters are replaced with text, as follows: .---------.------------------------------------------------. | SYMBOL | REPLACED BY | |---------|------------------------------------------------| | ~user | (Unix only) Replaced by home directory of user | | ~+ | Replaced by current working directory | | ~- | Replaced by previous directory (previousdir) | | ~ | Replaced by home directory (home) | | % | Replaced by the name of the current file | | # | Replaced by the name of the alternate file | | #n | Replaced by the filename of buffer with bufid=n| | (space) | Delimits one file name from another | ^---------^------------------------------------------------^ The second stage of processing evaluates each name using the simpler expression syntax. This basically means that expressions of the form $NAME will be replaced with the value of the environment variable named NAME. Also, you can use parentheses around option names or more complex expressions. For example, if the user option f contains the name of a file, then you could say ":e (f)" to edit that file. In either of the first two stages, backslashes may be used to prevent the special symbols from having their usual meaning; they'll be treated as normal text instead. In particular, a backslash-space sequence can be used to give a filename which includes spaces; e.g., to edit "C:\Program Files\foo" you would type ":e C:\Program\ Files\foo". Note that backslashes which are followed by a normal character are simply retained as normal characters, so you rarely need to type a double-backslash when your file name needs only a single backslash. The third stage of processing checks for "wildcard" characters in the name, and if there are any then the whole name is replaced by the name of each matching file. The exact list of supported wildcards will vary from one operating system to another, but the following are typical: .--------.----------------------------------------------. | SYMBOL | MATCHES | |--------|----------------------------------------------| | * | Any string of characters, of any length | | ? | Any single character | | [a-z] | (Unix only) Any single character from A to Z | ^--------^----------------------------------------------^ In most operating systems, wildcards are only recognized when they occur in the last file name part of a longer pathname. In other words, you can use wildcards for file names, but not in directory names leading up to file names. Traditionally, vi has used the Unix shell to expand wildcards. However, this interferes with the use of spaces in file names, isn't easily portable to non-Unix operating systems, and is a potential security hole. So elvis performs all wildcard expansion itself. The only disadvantage of this is that you loose other shell notations such as `command` and {alt1,alt2}. Most commands can be followed by a '|' character and another ex command. Others can't. In particular, any command which takes a excmd or shellcmd argument doesn't treat '|' as a command delimiter. If a command does treat '|' as a delimiter, and you want '|' to be treated as part of a command argument, then you'll need to quote the '|' character by preceding it with a backslash or ^V, depending on the command. (Sadly, different commands require different quote characters.) 4.3 Ex Commands, Grouped by Function  4.3.1 The help command itself  4.3.2 Editing commands  4.3.3 Global edit commands  4.3.4 Displaying text  4.3.5 Tags  4.3.6 File I/O commands  4.3.7 The args list, and selecting a file to edit  4.3.8 Quitting  4.3.9 Scripts and macros  4.3.10 Working with a compiler  4.3.11 Built-in calculator  4.3.12 Buffer commands  4.3.13 Window commands  4.3.14 Configuration  4.3.15 Miscellaneous 4.3.1 The help command itself .-------.-------------------.-----------------------------------. |ADDRESS| COMMAND | ARGUMENTS | |-------|-------------------|-----------------------------------| | | h[elp] | topic | ^-------^-------------------^-----------------------------------^ The :help command loads and displays a help file for a given topic. There are several help files, covering a wide variety of topics. Elvis looks at the topic you supply, and tries to determine whether it is an ex command name, vi keystroke, option name, or something else. Based on this, it generates a hypertext link to the topic in the appropriate help file, and shows the topic in a separate window. Elvis uses the following rules to convert your requested topic into a hypertext reference: .---------------.-------------------------------------------. | COMMAND | ELVIS' INTERPRETATION | |---------------|-------------------------------------------| | :help | With no topic, elvis loads the table of | | | contents. This has hypertext links that | | | can lead you to any other topic. | | :help ex | Elvis loads the chapter describing ex | | | commands. | | :help vi | Elvis loads the chapter describing vi | | | commands. | | :help set XXX | If XXX is an option name, elvis will show | | | the description of that option; else it | | | will list groups of all options. | | :help :XXX | If XXX is an ex command name, elvis will | | | show its description; else elvis will | | | list groups of all ex commands. | | :help XXX | If XXX appears to be a keystroke then | | | elvis will assume it is meant to be a | | | vi command and will show the command's | | | description. Else if it is an option | | | name elvis will show that. Else if it | | | is an ex command, elvis will show that. | | | Else elvis will show this description | | | of the :help command itself. | ^---------------^-------------------------------------------^ Although this chart only mentions sections on ex commands, vi commands, and options, there are many others which are only accessible via the table of contents shown by ":help" with no arguments. All of these help files are HTML documents. Elvis' standard HTML editing facilities are available while you're viewing the help text. Some of the highlights of this are:  To close this help window, type ZQ. Actually, this works for all windows. (You must hold the Shift key as you type ZQ, because lowercase zq does something else entirely: nothing!)  Any underlined text is a hypertext reference. This means that you can move the cursor onto it, and hit the Enter key, and the cursor will move to a topic describing the underlined text.  To return to your original position after following a hypertext reference, hit ^T (Control-T).  The Tab key moves the cursor forward to the next hypertext reference. You can use elvis to print the document via the :lpr command. This assumes you have set the printing options correctly. 4.3.2 Editing commands .-------.-------------------.-----------------------------------. |ADDRESS| COMMAND | ARGUMENTS | |-------|-------------------|-----------------------------------| | line | a[ppend][!] | [text] | | line | i[nsert][!] | [text] | | range | c[hange][!] | [count] [text] | | range | d[elete] | [cutbuf] [count] | | range | y[ank] | [cutbuf] [count] | | line | pu[t] | [cutbuf] | | range | co[py] | line | | range | m[ove] | line | | range | t[o] | line | | range | ! | shellcmd | | range | > | | | range | < | | | range | j[oin][!] | | | | u[ndo] | [count] | | | red[o] | [count] | ^-------^-------------------^-----------------------------------^ The :append command inserts text after the current line. If no new text is supplied on the command line, then elvis will wait for you to type in text; you can then mark the end of the new text by typing a "." (period) on a line by itself. In the real vi, adding a '!' suffix temporarily toggles the autoindent option, but elvis just ignores the '!'. The :insert command inserts text before the current line. Other than that, it is identical to the :append command. In the real vi, adding a '!' suffix temporarily toggles the autoindent option, but elvis just ignores the '!'. The :change command deletes old text lines (copying them into the anonymous cut buffer) and then waits for you to enter new text to replace it. You can then mark the end of the new text by typing a "." (period) on a line by itself. In the real vi, adding a '!' suffix temporarily toggles the autoindent option, but elvis just ignores the '!'. The :delete command copies text into a cut buffer, and then deletes it from the edit buffer. The :yank command copies text into a cut buffer but leaves the edit buffer unchanged. The :put command "pastes" text from a cut buffer back into the edit buffer. The cut buffer's contents are inserted after the addressed line. If you want to insert before the first line, you can use address 0 like this: :0put The :copy and :to commands are identical. They both make a copy of a portion of an edit buffer, and insert that copy at a specific point. The destination line can be specified with an optional buffer name and the full address syntax as described in section 4.2. Consequently, you can use this command to copy part of one edit buffer into another edit buffer. The following example copies an 11-line window from the current buffer onto the end of a buffer named "otherbuf" :-5,+5t(otherbuf)$ The :move command resembles :copy except that :move deletes the original text. The :! command allows you to send parts of your edit buffer though some external "filter" program. The output of the program then replaces the original text. For example, this following will sort lines 1 through 10 using the "sort" program. :1,10!sort If you use the :! command without any line addresses, then elvis will simply execute the program and display its output. This is only guaranteed to work correctly for non-interactive programs; to execute an interactive program you should use the :shell command. The :< and :> commands adjust the indentation on the addressed lines. The :< command decreases the leading whitespace by the number of spaces indicated in the shiftwidth option, and :> does the reverse. You can use multiple < or > characters in a single command to increase the shift amount; for example, :>>> shifts text by triple the shiftwidth amount. Normally elvis' versions of these commands will leave blank lines unchanged, but if you append a '!' (as in :>!) then the command will affect blank lines in addition to other lines. The :join command joins multiple lines together so they form one long line. Normally it will intelligently decide how much whitespace it should place between lines, depending on the sentenceend, sentencegap, and sentencequote options. When invoked with a '!' suffix (as in :join!), it joins the lines without doing fancy things to whitespace. The :undo command undoes recent changes. The number of undoable changes is controllable on a buffer-by-buffer basis, via the undolevels option. The :redo command undoes an undo. 4.3.3 Global edit commands .-------.-------------------.-----------------------------------. |ADDRESS| COMMAND | ARGUMENTS | |-------|-------------------|-----------------------------------| | range | g[lobal][!] | /regexp/ excmds | | range | v[global][!] | /regexp/ excmds | | range | s[ubstitute] | /regexp/text/[g|.n][x][c][p|l|#] | | range | & | [g|.n][p|l|#][x][c] | | range | ~ | [g|.n][p|l|#][x][c] | ^-------^-------------------^-----------------------------------^ The :global command searches for lines which contain the /regexp/ and executes the given excmds for each matching line. The :vglobal command executes the excmds for each line which does not match the /regexp/. In script files, you can supply multiple command lines to a single :global or :vglobal by placing a '{' character on the :global/:vglobal line, following that with any number of command lines, and then finally a '}' character on a line by itself to mark the end. This notation doesn't allow nesting; you can't use {...} inside a larger {...} command list. (Hopefully this limitation will be lifted soon.) The :substitute command searches for the /regexp/ in each line, and replaces the matching text with newtext. The interpretation of newtext is described in section 5.2 The newtext can be followed by a g flag to replace all instances in each line. Without the g flag, only the first match within each line is changed (unless the gdefault option is set). To replace some other instance in each line, give a decimal point followed by the instance number, such as .3 to replace the third instance of matching text in each line. You can also supply a p flag. This causes each affected line to be printed (like :p), after all substitutions have been made to that line. Similarly, l lists it (like :l), and #prints it with a line number (like :nu or :#). You can also make elvis ask for confirmation before each substitution by appending a c flag. The :s command will locate the first match and then exit immediately, but it will leave the window in an unusual input state in which y performs a substitution and then moves on to the next match, n does not perform the substitution but still moves to the next match, and Esc cancels the operation. Most other keys act like y in this mode. Elvis supports a special x flag. Instead of performing each substitution, elvis will execute the final replacement text as an ex command line. This is used in the implementation of modelines, like this: 1,5 s/ex:\(.*\):/\1/x $-4,$ s/ex:\(.*\):/\1/x The :& and :~ commands both repeat the previous :substitute command, discarding any previous flags. The difference between them is that :& uses the regular expression from the previous :s command, but :~ uses the most recent regular expression from any context. 4.3.4 Displaying text .-------.-------------------.-----------------------------------. |ADDRESS| COMMAND | ARGUMENTS | |-------|-------------------|-----------------------------------| | range | p[rint] | [count] | | range | l[ist] | [count] | | range | nu[mber] | [count] | | range | # | [count] | | line | z | [spec] | | range | = | | ^-------^-------------------^-----------------------------------^ The :print command displays lines from the edit buffer. It displays them the normal way -- with tabs expanded and so on. The :list command also displays lines, but it tries to make all non-printing characters visible, and it marks the end of each line with a '$' character. The :number and :# commands are identical to each other. They both display lines the normal way except that each line is preceded by its line number. The :z command shows a "window" of lines surrounding the current line. The default size of the "window" is taken from the window option. If a line address is supplied, then it becomes the current line before this command is executed. The spec can be one of the following characters; the default is z+. .------.-----------------------------------------------------. | SPEC | OUTPUT STYLE | |------|-----------------------------------------------------| | - | Place the current line at the bottom of the window. | |------|-----------------------------------------------------| | + | Place the current line at the top of the window. | | | Upon completion of this command, the last line | | | output will become the current line. | |------|-----------------------------------------------------| | ^ | Jump back 2 windows' worth of lines, and then do | | | the equivalent of z+. Note that z+ is like paging | | | forward and z^ is like paging backward. | |------|-----------------------------------------------------| | . | Place the current line in the middle of the window. | | | Upon completion of this command, the last line | | | output will become the current line. | |------|-----------------------------------------------------| | = | Place the current line in the middle of the window, | | | and surround it with lines containing hyphens. | ^------^-----------------------------------------------------^ The := command displays the line number of the current line, or the addressed line if given one address. If given a range of addresses, it tells you the line numbers of the two endpoints and the total number of lines in the range. 4.3.5 Tags .-------.-------------------.-----------------------------------. |ADDRESS| COMMAND | ARGUMENTS | |-------|-------------------|-----------------------------------| | | ta[g][!] | [tag] | | | stac[k] | | | | po[p][!] | | | | br[owse][!] | restrictions | ^-------^-------------------^-----------------------------------^ Tags provide a way to associate names with certain places within certain files. Typically, you will run the ctags program to create a file named "tags" which describes the location of each function and macro used in the source code for your project. The tag names are the same as the function names, in this case. In HTML mode, elvis uses the tags commands to follow hypertext links, but we'll generally ignore that in the following discussions. The :tag command performs tag lookup. It reads the "tags" file to locate the named tag. It then loads the source file where that tag is defined, and moves the cursor to the specific point within that buffer where the tag is defined. Elvis' implementation of :tag also allows you to give extra restrictions and hints. There is also a :stag command which creates a new window and moves its cursor to the tag's definition point. The :browse command extracts selected tags from the tags file, constructs an HTML document listing those tags (with hypertext links to their definition points inside your source code) and displays it in the current window. There is also a :sbrowse command which displays the same list in a new window. If invoked with no args, they browse all tags in the current file. If invoked with a '!' suffix, they browse all tags. See chapter 14. Tags for a full description of restrictions and hints, and browsing. Before moving the cursor, elvis will save the old cursor position on a stack. You can use the :stack command to display the contents of that stack. Each window has an independent stack. The :pop command pops a cursor position off the stack, restoring the cursor to its previous position. When you're browsing though source code, you will typically use :tag to go deeper into the call tree, and :pop to come back out again. In HTML mode, these all work the same except that :tag expects to be given an URL instead of a tag name. URLs don't depend on having a "tags" file, so the "tags" file is ignored when in HTML mode. Elvis doesn't support any network protocols, so its URLs can only consist of a file name and/or a #label. The following example would move the cursor to the start of this section: :tag elvisopt.html#TAGS 4.3.6 File I/O commands .-------.-------------------.-----------------------------------. |ADDRESS| COMMAND | ARGUMENTS | |-------|-------------------|-----------------------------------| | line | r[ead] | file | !shellcmd | | range | w[rite][!] | [file | >>file | !shellcmd] | | range | lp[r][!] | [file | >>file | !shellcmd] | ^-------^-------------------^-----------------------------------^ The :read command reads a file or external program, and inserts the new text into the edit buffer after the addressed line. If you don't explicitly give a line address, then the text will be inserted after the current line. To insert the file's contents into the top of the buffer ( before line 1), you should specify line 0. For example, to insert the contents of "foo.txt" before line 1, you would give the command... :0 read foo.txt The :write command writes either the entire edit buffer (if no address range is given) or a part of it (if a range is given) out to either a file or an external filter program. If you don't specify the output file or external command, then elvis will assume it should write to the file that the buffer was originally loaded from. Elvis will normally prevent you from overwriting existing files. (The exact details of this protection depend on the edited, filename, newfile, readonly, and writeany options.) If you want to force elvis to overwrite an existing file, you can append a "!" to the end of the command name, but before the file name. In order to avoid ambiguity, there must not be any whitespace between the "write" command name and the "!" character when you want to overwrite an existing file. Conversely, when writing to an external program there should be whitespace before the "!" that marks the start of the program's command line. The ">>file" notation tells elvis to append to "file" instead of overwriting it. The :lpr command sends text to the printer. It is similar to :write except that :lpr formats the buffer contents as defined by the bufdisplay option and the printing options. If no output file or external program is specified, then the printer output is sent to the file or external program specified by the lpout option. 4.3.7 The args list, and selecting a file to edit .-------.-------------------.-----------------------------------. |ADDRESS| COMMAND | ARGUMENTS | |-------|-------------------|-----------------------------------| | | ar[gs] | [file...] | | | n[ext][!] | [file...] | | | N[ext][!] | | | | pre[vious][!] | | | | rew[ind][!] | | | | la[st] | | | | wn[ext][!] | | | | f[ile] | [file] | | | e[dit][!] | [+line] [file] | | | ex[!] | [+line] [file] | | | vi[sual][!] | [+line] [file] | | | o[pen][!] | [+line] [file] | ^-------^-------------------^-----------------------------------^ The "args list" is a list of file names. It provides an easy way to edit a whole series of files, one at a time. Initially, it contains any file names that you named on the command line when you invoked elvis. The :args command displays the args list, with the current file name enclosed in brackets. You can also use :args to replace the args list with a new set of files; this has no effect on whatever file you're editing at that time, but it will affect any :next commands that you give later. The :next command switches to the next file in the args list. This means it loads the next file from the args list into an edit buffer, and makes that edit buffer be the current buffer for this window. You can also give a new args list on the :next command line; this acts like a :args command to set the args list, followed by an argumentless :next command to load the next (first) file in that list. The :Next (with a capital "N") and :previous commands are identical to each other. They both move backwards through the args list. The :rewind and :last commands switch to the first and last files in the args list, respectively. The :wnext command is like a :write command followed by a :next command. It saves any changes made to the current file before switching to the next file. (The autowrite option offers a better alternative.) The :file command displays information about the current buffer. It can also be used to change the filename associated with this buffer. The :edit and :ex commands are identical to each other. They both switch to a new file, or if no file is named then they reread the current file. This has no effect on the args list. The :visual and :open commands switch to a new file if one is named; otherwise they continue to use the current buffer without reloading it from the original file. These commands have the side-effect of switching the window mode from ex mode to either the normal visual mode or the uglier "open" mode, respectively. "Open" mode allows you to use all of the visual commands, but it only displays a single line (the line that the cursor is on) at the bottom of the screen. The sole advantage that "open" mode has over "visual" mode is that "open" mode doesn't need to know what kind of terminal you're using. 4.3.8 Quitting .-------.-------------------.-----------------------------------. |ADDRESS| COMMAND | ARGUMENTS | |-------|-------------------|-----------------------------------| | | cl[ose][!] | | | | q[uit][!] | | | | wq[uit][!] | [file] | | | x[it][!] | [file] | | | qa[ll][!] | | | | pres[erve] | | ^-------^-------------------^-----------------------------------^ Except for :qall, all of these commands attempt to close the current window without losing any changes. When the last window is closed, elvis exits. The differences between these commands concern how modified buffers are handled. In the discussions below, it is assumed that tempsession is True and the buffer's retain option is False, which is usually the case. The :close command is the simplest. If the current window is the only window and one or more buffers have been modified but not yet saved, then :close will fail; otherwise the current window will be closed. The visual ^Wq command uses this command internally. If the window's buffer was modified, then elvis will just have a modified buffer lying around, which may or may not be visible in some other window. That's okay. The other quitting commands won't allow you to lose that buffer accidentally. You can make some other window view that buffer by giving that buffer's name in parentheses on an ex command line in that other window. The :quit command fails if the current buffer has been modified. If you wish to abandon the changes made to the current buffer, you can add a "!" to the end of the command name; this has the effect of turning off the buffer's modified flag. The :xit command saves the file if it has been modified, and then closes the window. The visual ZZ command uses this command internally. The :wquit command saves the file regardless of whether it has been modified, and then closes the window. The :qall command tries to close all of the windows at once. It is equivalent to giving the :quit command in each window. The :preserve command closes all windows and exits, but it doesn't delete the session file. You can restart the same edit session later by giving the command... elvis -ssessionfile ...where sessionfile is the name of the session file, usually "/var/tmp/elvis1.ses". You may want to check the value of the session option first, just to make sure. 4.3.9 Scripts and macros .-------.-------------------.-----------------------------------. |ADDRESS| COMMAND | ARGUMENTS | |-------|-------------------|-----------------------------------| | | @ | cutbuf | | | so[urce][!] | file | | | saf[er][!] | file | | | al[ias] | [name [excmds]] | | | unal[ias][!] | name | ^-------^-------------------^-----------------------------------^ The :@ command executes the contents of a cut buffer as a series of ex command lines. The :source command reads a file, and executes its contents as a series of ex commands. Normally, elvis would issue an error message if the requested file didn't exist but when a "!" is appended to the command name, elvis will silently ignore the command if it doesn't exist. The :safer command is exactly like :source, except that :safer will temporarily set the safer option while it is executing the commands. You should use :safer instead of :source when it is possible that the file to be executed could contain potentially harmful commands. For example, the default "elvis.ini" file uses :source to execute the ".exrc" file in your home directory since it is presumably secure, but :safer is used to execute the ".exrc" file in the current directory since it could have been created by anybody. As with :source!, invoking :safer! (with a '!' suffix) prevents elvis from complaining about nonexistent script files. The :alias and :unalias commands manipulate the alias list. (See the Tips section of the manual for a discussion of aliases.) With no arguments, :alias displays all aliases. When given a name but no commands, :alias displays the complete definition of the named alias. When given a name and commands, :alias defines (or redefines) an alias. The :unalias command deletes the alias with a given name. 4.3.10 Working with a compiler .-------.-------------------.-----------------------------------. |ADDRESS| COMMAND | ARGUMENTS | |-------|-------------------|-----------------------------------| | | cc[!] | [args] | | | mak[e][!] | [args] | | | er[rlist][!] | [file] | ^-------^-------------------^-----------------------------------^ If you use elvis to edit source code for programs, then you can have elvis read the output of your compiler and parse that output for error messages. When elvis finds an error message, it can move the cursor to the file and line number where the error was reported. To parse the compiler output, elvis first breaks the output into lines. Each line is then broken into words. If a word looks like a number, then it is assumed to be a line number. If a word looks like the name of an existing file, then it is assumed to be a file name. Any line which contains both a line number and a file name is treated as an error report (with the remainder of the line serving as a description of the error); lines which don't have both of these are simply ignored. The :cc and :make commands use the ccprg and makeprg options, respectively, to run your compiler or "make" utility, and collect the output. Elvis will then move the cursor to where the first error was detected. (If there were no errors, elvis will say so and leave the cursor unchanged.) After that, the :errlist command can be used repeatedly to move to each successive error. You can also use the :errlist command with a file name argument to load a new batch of error messages from a file; the cursor is then moved to the first error in that batch. 4.3.11 Built-in calculator .-------.-------------------.-----------------------------------. |ADDRESS| COMMAND | ARGUMENTS | |-------|-------------------|-----------------------------------| | | ca[lculate] | expr | | | ev[al] | expr | ^-------^-------------------^-----------------------------------^ Elvis has a built-in calculator which uses a C-like syntax. It is described in section 12: Arithmetic Expressions. The :if and :let commands also use the calculator. The :calculate command evaluates an expression and displays the result. The :eval command evaluates an expression using the simpler syntax (which basically means that text outside of parentheses is left alone), and then executes the result as an ex command line. This provides a way to use expressions with commands which would not ordinarily use expressions. For example, the following command line inserts the value the elvispath option into the current edit buffer. :eval insert elvispath=(elvispath) Note: There is a hardcoded limit of (normally) 1023 characters for the result of any expression. This limit will sometimes impact the use of :eval. For example, if your $EXINIT environment variable is longer than 1023 characters then elvis will be unable to interpret it during initialization. 4.3.12 Buffer commands .-------.-------------------.-----------------------------------. |ADDRESS| COMMAND | ARGUMENTS | |-------|-------------------|-----------------------------------| | | al[l][!] | excmds | | | b[uffer][!] | [buffer] | | | ( | buffer | | | bb[rowse][!] | | | | sbb[rowse][!] | | ^-------^-------------------^-----------------------------------^ The :all command applies a given ex command line to each edit buffer in turn. Normally the command is applied just to the user edit buffers, but if you append a "!" to the command name, then the ex command line is applied to internal buffers as well. For example, the following sets the "bufdisplay" option of all user edit buffers: :all set bufdisplay=normal In script files, you can supply multiple command lines to a single :all commands by placing a '{' character on the :all line, following that with any number of command lines, and then finally a '}' character on a line by itself to mark the end. This notation doesn't allow nesting; you can't use {...} inside a larger {...} command list. (Hopefully this limitation will be lifted soon.) The :buffer command lists either all user edit buffers, or (when "!" is appended to the command name) all buffers including internal ones. If the buffer is being edited in one or more windows, then the window ID is also displayed. Buffers which have been modified will be marked with an asterisk. You can also use the :buffer command to make the current window display a different buffer. The :(buffer notation causes the current window to display the named buffer, instead of the current buffer. This isn't really a command; it is part of an address. Whenever you give an address without specifying a command, elvis moves the cursor to the addressed line. In this particular case, we're addressing the most recently changed line of a given buffer, so that's where the cursor is moved to. For more information, see the discussion of Buffer IDs earlier in this chapter (in the discussion of addresses). The :bbrowse and :sbbrowse commands create an HTML document which lists the names of all user buffers (or, when a '!' is appended to the command name, all buffers including internal buffers). You can then go to one of the buffers just by following the hypertext link. The difference between these two commands is that :bbrowse displays the list in the current window, but :sbbrowse creates a new window to display it. 4.3.13 Window commands .-------.-------------------.-----------------------------------. |ADDRESS| COMMAND | ARGUMENTS | |-------|-------------------|-----------------------------------| | | sp[lit] | [+line] [file | !shellcmd] | | | new | | | | sne[w] | | | | sn[ext] | [file...] | | | sN[ext] | | | | sre[wind] | | | | sl[ast] | | | | sta[g] | [tag] | | | sb[rowse] | restrictions | | | sa[ll] | | | | wi[ndow] | [ +[+] | -[-] | number | buffer] | | | di[splay] | [modename [language]] | | | no[rmal] | | ^-------^-------------------^-----------------------------------^ The :split command creates a new window. If you supply a file name, then it will load that file into an edit buffer and the new window will show that buffer. If you supply a shell command line preceded by a '!' character, then it will create an untitled buffer, and read the output of that command line into the buffer. Otherwise, the new window will show the same buffer as the current window. The :new and :snew commands are identical to each other. They both create a new empty buffer, and then create a new window to show that buffer. The :snext, :sNext, :srewind, :slast, :stag, and :sbrowse commands resemble the :next, :Next, :rewind, :last, :tag, and :browse commands, respectively, except that these "s" versions create a new window for the newly loaded file, and leave the current window unchanged. The :sall command creates a new window for any files named in the args list, which don't already have a window. (See section 4.3.7: The args list... for a discussion of the args list.) The :window command either lists all windows (when invoked with no arguments) or switches to a given window. You can specify which to switch to by giving one of the following arguments. .----------.-----------------------------------------------. | ARGUMENT | MEANING | |----------|-----------------------------------------------| | + | Switch to the next window, like ^Wk | | ++ | Switch to the next window, wrapping like ^W^W | | - | Switch to the previous window, like ^Wj | | -- | Switch to the previous window, wrapping | | number | Switch to the window whose windowid=number | | buffer | Switch to the window editing the named buffer | ^----------^-----------------------------------------------^ The :display command switches the window to a new display mode, overriding the value of the bufdisplay option. The display option indicates the current display mode. If you omit the new modename, then the :display command will list all supported display modes, with an asterisk next to the current mode. The "syntax" mode allows you to specify which language's syntax it is supposed to use; if you don't specify a language, elvis will guess the language from the file name's extension. The :normal command is equivalent to ":display normal". It can be abbreviated to ":no", which is certainly easier to type than ":dis normal". 4.3.14 Configuration .-------.-------------------.-----------------------------------. |ADDRESS| COMMAND | ARGUMENTS | |-------|-------------------|-----------------------------------| | | ab[breviate][!] | [lhs rhs] | | | una[bbreviate][!] | lhs | | | map[!] | [lhs rhs] | | | unm[ap][!] | lhs | | | bre[ak][!] | lhs | | | unb[reak][!] | lhs | | | dig[raph][!] | [lhs [rhs]] | | | col[or] | [font color ["on" color]] | | | gu[i] | text | | | se[t][!] | [option=value | option? | all] | | | lo[cal][!] | [option=value | option ] | | | le[t][!] | option=expr | | | if | expr | | | th[en] | excmds | | | el[se] | excmds | | | try | excmds | | | wh[ile] | expr | | | do | excmds | | | mk[exrc][!] | [file] | ^-------^-------------------^-----------------------------------^ The :abbreviate and :unabbreviate commands add and remove entries to the abbreviation table, respectively. Also, the :abbreviate command can be used with no arguments to list the current contents of the abbreviation table. For a discussion of abbreviations, see section 3.3: Abbreviations. Normal abbreviations are only active while you're typing in a normal text buffer; adding a '!' suffix to the command name causes the macro to be active while you're entering ex command lines. The :map and :unmap commands add and remove entries to the map tables, respectively. When the :map command is given without any arguments, it lists the contents of a map table. There are two map tables. When a "!" is appended to the command name, these commands use the table that applies to input mode; without the "!" these commands use the table that applied to visual command mode. The primary purpose of map tables is to assign actions to the cursor keypad and the function keys. Each of these keys sends an arbitrary but distinctive sequence of characters when pressed. The map tables are used to convert these arbitrary character sequences into command keystrokes that elvis can do something useful with. For example, arrow keys are normally mapped to the h, j, k, and l commands. The first argument to :map is the raw character sequence sent by a key, and the remaining arguments are the characters that elvis should pretend you pressed. This can be either a literal sequence of characters, or a gui-dependent symbol representing a particular keystroke. See the User Interfaces chapter for lists of keystrokes. Also, function keys can usually be denoted by #1 for the key, #2 for the key, and so on. The second argument is character sequence that elvis should pretend you typed whenever the raw characters are received. This may be preceded by the word "visual" which causes the remaining argument characters to be processed as visual commands, even if the key is pressed in input mode. This trick is used to allow the cursor to be moved via the arrow keys when in input mode. The :break and :unbreak commands set and reset the breakpoint flag for a given macro, respectively. Using a '!' suffix causes the breakpoint to be set for an input-mode map. This is used for debugging macros, as described in section 16.3: How to debug macros. If a macro has its breakpoint flag set, and the maptrace option is set to run, then when that map is encountered elvis will automatically switch maptrace to step mode. The :digraph command manipulates the digraph table. (See section 3.2: Digraphs for a discussion on digraphs.) With no arguments, it lists the digraph table. With one argument, it removes the given digraph from the table. With two arguments, it adds the given digraph to the table, or if the same two ASCII characters are already in the table then it alters the existing entry. Normally, the :digraph command sets the most significant bit in the last argument's character. That way you don't need to be able to type a non-ASCII character on your keyboard in order to enter it into the table; you can type the ASCII equivalent and allow elvis to convert it to non-ASCII before storing the digraph. If you don't want elvis to set the most significant bit, then append a "!" to the end of the command name. The :color command allows you to choose a color to use for displaying each font. Some user interfaces don't support this. The ones that do will vary in the color names that they support. The termcap interface supports black, white, gray, red, green, blue, brown, yellow, magenta, and cyan, plus light or bright versions of most of those. The windows interface supports the same colors, except that it is pickier: it doesn't allow spaces, and only "light" is accepted, such as "lightblue". The x11 interface supports all standard X color names. The first argument should be the name of the font to change. This can be "normal", "bold", "emphasized", "italic", "underlined", or "fixed". Some user interfaces may also support "standout", "cursor", "scrollbar", and/or "toolbar". All of these can be either spelled out completely, or abbreviated to the first letter. (Currently no user interface supports both "standout" and "scrollbar" so there is no ambiguity.) If you omit the font name, then "normal" is assumed. The termcap interface requires you to assign a "normal" color before any of the other fonts. You can specify an optional background color. The word "on" is used to delimit the foreground color name from the background color name. For example, the command ":color yellow on blue" causes normal text to be displayed as yellow characters on a blue background. The x11 user interface allows you to specify both the foreground and background color for the cursor. The cursor is drawn in the foreground color normally, but the background color if elvis own the current X selection. The :gui command provides a way to pass unusual commands to the user interface. Currently, the only user interface which uses this is the "x11" interface, which uses it to configure the toolbar. The :set command allows you to examine or change the values of options. Using :set! (with a "!" at the end of the command name) causes it to include the group name of any option that is output. In addition, "!" inhibits the setting of any option's "modified" flag, which will then prevent it from being output by a later argumentless :set command. With no arguments, :set lists the names and values of any options that have been altered or are of frequent interest. If given the argument "all" it will list the names and values of most (but not really all) options. If given the name of an option followed by a "?" character, :set will output the option's name and value. If given the name of a group of options, followed by a "?" character, :set will output the names and values of all options in that group. To turn a Boolean option on, just give the name of the option. You can turn it off by adding the prefix "no" to the option name, and you can negate it by adding the "neg" prefix to its name. To change the value of a non-Boolean option, give the name followed immediately by an "=" and the new value. If the new value contains whitespace, you should either enclose the entire value in quotes, or precede each whitespace character with a backslash. If you give the name of a non-Boolean option, without either "=value" or "?", then elvis will display its value. .-----------.--------------------------------------------------------. | EXAMPLE | WHAT IT DOES | |-----------|--------------------------------------------------------| | :set | display names & values of changed/interesting options | | :set all | display names & values of most POSIX-compliant options | | :set ts? | display name & value of the tabstop option | | :set lp? | display names & values of all printing options | | :set ts=4 | set value of the tabstop option to 4 | | :set ai | turn on the autoindent option | | :set noai | turn off the autoindent option | | :set negai| toggle the autoindent option | ^-----------^--------------------------------------------------------^ The :local command is similar to :set, and is intended to be used in aliases and scripts. In addition to setting options' values, it also pushes the old values onto a stack; the old values are automatically restored at the end of the alias or script. Another difference is that where :set would output an option, :local merely pushes its old value, without outputting or changing the option's value. This means that you can save a non-Boolean option simply by mentioning its name on a :local command line; Boolean options can also be saved without altering them, but you must put a question mark after the option's name. Here's a simple alias which uses :local. It totals the numbers in all lines from the current line forward to the next line which contains the "total:", and stores the total in the "total:" line. :alias total { local nowrapscan ignorecase t=0 .,/total:/-1 s/\d\+/let t=t+&/x eval /total/ s/:.*/: (t)/ } The :let command computes a new value for an option. The :let command should be followed by the name of an option, then an "=" sign, and then an expression that produces the new value. Note that even Boolean options use the "=" notation here. When invoked as :let! (with a '!' suffix), elvis won't set the option's "changed" flag so it won't be output by an argumentless :set command. The :if command evaluates an expression, and sets an internal variable according to whether the result was true or false. Later, the :then and :else commands can be used to test that variable, and conditionally execute other ex commands. Note that after an :if command, any other ex commands which don't start with :then or :else will be executed unconditionally. In aliases or script files, you can supply multiple command lines to a single :then or :else by placing a '{' character on the :then/:else line, following that with any number of command lines, and then finally a '}' character on a line by itself to mark the end. The following example demonstrates this syntax, and also shows that you can safely use :if inside a :then or :else command: :if i <= 0 :then { if i == 0 then echo zero else echo negative } :else echo positive The :try command executes its argument text as an ex command line. Regardless of whether that command line succeeds or fails, the :try command itself always succeeds. That's significant because a command fails, all pending aliases, macros, and scripts are cancelled; :try prevents that. Error messages and warning messages are disabled while the command line runs. Afterward, the then/else is set to indicate whether the command line succeeded. This command is useful for implementing specialized error handing in an alias or script. The following example will search for "foo"; if there is no "foo" then it will search for "bar": :try /foo :else /bar The :while command stores an expression. It should be followed by a :do command; the :do command repeatedly evaluates the expression, and as long as the result is true it executes the commands which follow the :do. The following example counts from 1 to 10: :let i=1 :while i <= 10 :do { calc i let i=i+1 } Both the :if/:then/:else and :while/:do command structures permit nesting. I.e., the commands in a :then command can't affect the "if" variable to cause the :else command to also be executed. The :mkexrc command creates a file containing ex commands which recreate the current map, abbreviation, and digraph tables, and also sets any options which have been changed. Basically it stores your current configuration in a file which you can later :source to restore your configuration. If you don't specify a filename, then it will write to ".exrc" or "elvis.rc" in the current directory. NOTE: The :mkexrc command does not store information for :alias or :gui commands. This is expected to be added in a later version of elvis. 4.3.15 Miscellaneous .-------.-------------------.-----------------------------------. |ADDRESS| COMMAND | ARGUMENTS | |-------|-------------------|-----------------------------------| | | " | text | | | cd[!] | [directory] | | | chd[ir][!] | [directory] | | | ec[ho] | text | | | me[ssage] | text | | | wa[rning] | text | | | erro[r] | text | | | sh[ell] | | | | st[op][!] | | | | sus[pend][!] | | | | ve[rsion] | | | line | go[to] | | | line | ma[rk] | mark | | line | k | mark | | | { | | ^-------^-------------------^-----------------------------------^ The " command causes the remainder of the line to be ignored. It is used for inserting comments into ex scripts. The :cd and :chdir commands are identical. They both change the current working directory for elvis and all its windows. If you don't specify a new directory name then elvis will switch to your home directory. The :echo command displays its arguments as a message. This may be useful in ex scripts. The :message, :warning, and :error commands all output their arguments as a message. The command name indicates the importance of the message. This is diffs from :echo as follows: the messages are translated via the elvis.msg file, then evaluated using the simpler syntax, and finally stuffed into the message queue. The message queue collects all messages, and outputs them immediately before waiting for the next keystroke. Also, the :error command has the side-effect of terminating any macros, aliases, or scripts. The :shell command starts up an interactive shell (command-line interpreter). Elvis will be suspended while the shell executes. (Exception: the "x11" GUI runs the shell in a separate xterm window. The elvis and the shell can then run simultaneously.) The :stop and :suspend commands are identical to each other. If the operating system and user interface support it, they will suspend elvis and resume the shell that started elvis. (This is like hitting ^Z on many UNIX systems.) If the OS or GUI don't support it, then elvis will generally treat these commands as synonyms for the :shell command. The :version command identifies this version number of elvis, and displays credits. The :goto moves the cursor to the addressed line. This is the only command which can be abbreviated down to zero characters, so if you type in a line containing just a line address, then elvis will treat that as a :goto command. The :mark and :k commands are identical to each other. They set a named mark to equal the addressed line, or the current line if no address was given. The { commands } notation isn't really a command; it is a feature of elvis' syntax which allows you to pass several command lines to a command which normally expects a single command line as its argument. It is supported by the :global, :vglobal, :all, :then, and :else commands. Instead of placing the argument command at the end of one of those command lines, you can place a single '{' character there. That should be followed by one or more command lines, and terminated by a '}' on a line by itself. 4.4 Alphabetical list of ex commands .-------.-------------------.-----------------------------------. |ADDRESS| COMMAND | ARGUMENTS | |-------|-------------------|-----------------------------------| | | ab[breviate][!] | [lhs rhs] | | | al[l][!] | excmds | | line | a[ppend][!] | [text] | | | ar[gs] | [file...] | | | bb[rowse] | | | | bre[ak][!] | lhs | | | br[owse][!] | restrictions | | | b[uffer][!] | [buffer] | | | ca[lculate] | expr | | | cc[!] | [args] | | | cd[!] | [directory] | | range | c[hange][!] | [count] [text] | | | chd[ir][!] | [directory] | | | cl[ose][!] | | | | col[or] | [font color ["on" color]] | | range | co[py] | line | | range | d[elete] | [cutbuf] [count] | | | dig[raph][!] | [lhs [rhs]] | | | di[splay] | [modename [language]] | | | do | excmds | | | ec[ho] | text | | | e[dit][!] | [+line] [file] | | | el[se] | excmds | | | er[rlist][!] | [file] | | | erro[r] | text | | | ev[al] | expr | | | ex[!] | [+line] [file] | | | f[ile] | [file] | | range | g[lobal][!] | /regexp/ excmds | | line | go[to] | | | | gu[i] | text | | | h[elp] | topic | | | if | expr | | line | i[nsert][!] | [text] | | range | j[oin][!] | | | line | k | mark | | | la[st] | | | | le[t][!] | option=expr | | range | l[ist] | [count] | | | lo[cal][!] | [option=value | option ] | | range | lp[r][!] | [ file | >>file | !shellcmd ] | | | mak[e][!] | [args] | | | map[!] | [lhs rhs] | | line | ma[rk] | mark | | | me[ssage] | text | | | mk[exrc][!] | [file] | | range | m[ove] | line | | | new | | | | n[ext][!] | [file...] | | | N[ext][!] | | | | no[rmal] | | | range | nu[mber] | [count] | | | o[pen][!] | [+line] [file] | | | po[p][!] | | | | pre[vious][!] | | | range | p[rint] | [count] | | line | pu[t] | [cutbuf] | | | qa[ll][!] | | | | q[uit][!] | | | line | r[ead] | file | !shellcmd | | | red[o] | [count] | | | rew[ind][!] | | | | sN[ext] | | | | saf[er][!] | file | | | sa[ll] | | | | sbb[rowse] | | | | sb[rowse] | restrictions | | | se[t][!] | [option=value | option? | all] | | | sh[ell] | | | | sl[ast] | | | | sne[w] | | | | sn[ext] | [file...] | | | so[urce][!] | file | | | sp[lit] | [file | !shellcmd] | | | sre[wind][!] | | | | stac[k] | | | | sta[g] | [tag] | | | st[op][!] | | | range | s[ubstitute] | /regexp/newtext/[g][p][x][count] | | | sus[pend][!] | | | | ta[g][!] | [tag] | | | th[en] | excmds | | range | t[o] | line | | | try | excmds | | | una[bbreviate][!] | lhs | | | unb[reak][!] | lhs | | | u[ndo] | [count] | | | unm[ap][!] | lhs | | | ve[rsion] | | | range | v[global][!] | /regexp/ excmds | | | vi[sual][!] | [+line] [file] | | | wa[rning] | text | | | wh[ile] | expr | | | wi[ndow] | [+ | - | number | buffer ] | | | wn[ext][!] | | | | wq[uit][!] | [file] | | range | w[rite][!] | [file | >>file | !shellcmd] | | | x[it][!] | [file] | | range | y[ank] | [cutbuf] [count] | | line | z | [spec] | | range | ! | shellcmd | | | " | text | | range | # | [count] | | range | & | | | | ( | buffer | | range | < | | | range | = | | | range | > | | | | @ | cutbuf | | | { | | | range | ~ | | ^-------^-------------------^-----------------------------------^ ═══ 1.5. Elvis 2.1 Regular Expressions ═══ 5. REGULAR EXPRESSIONS Elvis uses regular expressions for searching and substitutions. A regular expression is a text string in which some characters have special meanings. This is much more powerful than simple text matching. 5.1 Syntax Elvis' regexp package treats the following one- or two-character strings (called meta-characters) in special ways: \(subexpression\) The \( and \) metacharacters are used to delimit subexpressions. When the regular expression matches a particular chunk of text, Elvis will remember which portion of that chunk matched the subexpression. The :s/regexp/newtext/ command makes use of this feature. ^ The ^ metacharacter matches the beginning of a line. If, for example, you wanted to find "foo" at the beginning of a line, you would use a regular expression such as /^foo/. Note that ^ is only a metacharacter if it occurs at the beginning of a regular expression; practically anyplace else, it is treated as a normal character. (Exception: It also has a special meaning inside a [character-list] metacharacter, as described below.) $ The $ metacharacter matches the end of a line. It is only a metacharacter when it occurs at the end of a regular expression; elsewhere, it is treated as a normal character. For example, the regular expression /$$/ will search for a dollar sign at the end of a line. \< The \< metacharacter matches a zero-length string at the beginning of a word. A word is considered to be a string of 1 or more letters, digits, or underscores. A word can begin at the beginning of a line or after 1 or more non-alphanumeric characters. \> The \> metacharacter matches a zero-length string at the end of a word. A word can end at the end of the line or before 1 or more non-alphanumeric characters. For example, /\/ would find any instance of the word "end", but would ignore any instances of e-n-d inside another word such as "calendar". \@ When you're performing a search in visual mode, and the cursor is on a word before you start typing the search command, then \@ matches the word at the cursor. \= Ordinarily, the visual mode search command leaves the cursor on the first character of the matching text that it finds. If your regular expression includes a \= metacharacter, then it will leave the cursor at the position that matched the \=. For example, if you place \= at the end of your regular expression, then the cursor will be left after the matching text instead of at the start of it. . The . metacharacter matches any single character. NOTE: If the magic option is turned off, then . is treated as an ordinary, literal character. You should use \. to get the meta-character version in this case. [character-list] This matches any single character from the character-list. Inside the character-list, you can denote a span of characters by writing only the first and last characters, with a hyphen between them. If the character-list is preceded by a ^ character, then the list is inverted -- it will match any character that isn't mentioned in the list. For example, /[a-zA-Z]/ matches any ASCII letter, and /[^ ]/ matches anything other than a blank. There is no way to quote the ']' or '-' characters, which means that if you want to include those characters as members of the list, you must place them in positions where they couldn't be mistaken for the end of the list or a range. Specifically, ']' can appear only as the first character in the list (immediately after the "[" or "[^" that starts the list) or as the last character in a range. '-' can appear there too, or immediately after the last character of a range. For example, [])}] matches a closing bracket, parentheses, or curly brace. [^-+] matches any character except '+' or '-'. Probably the trickiest example, []-]-] matches a closing bracket or a '-'. (Note that the range "]-]" matches a single bracket; we wrote it this way so that the following "-" would be in a context where it couldn't be mistaken for a range and so must be a literal '-' character.) There are also special cases for some common character lists. When one of the following special symbols appears in a character list, the list will include all appropriate characters for that symbol including the non-ascii characters as indicated by the digraph table. Note that he brackets around these symbols are in addition to the brackets around the whole class. For example, /[[:alpha:]]/ matches any single letter, and /[[:alpha:]_][[:alnum:]_]*/ matches any C identfier. .----------------.-------------------------------------------. | SPECIAL SYMBOL | INCLUDED CHARACTERS | |----------------|-------------------------------------------| | [:alnum:] | all letters and digits | | [:alpha:] | all letters | | [:ascii:] | all ASCII characters | | [:blank:] | the space and tab characters | | [:cntrl:] | ASCII control characters | | [:digit:] | all digits | | [:graph:] | all printable characters excluding space | | [:lower:] | all lowercase letters | | [:print:] | all printable characters including space | | [:punct:] | all punctuation characters | | [:space:] | all whitespace characters except linefeed | | [:upper:] | all uppercase characters | | [:xdigit:] | all hexadecimal digits | ^----------------^-------------------------------------------^ NOTE: If the magic option is turned off, then the opening [ is treated as an ordinary, literal character. To get the meta-character behavior, you should use \[character-list] in this case. \s, \S, \d, \D, \w, \W, \p, and \P These are all shortcuts for certain character lists. The lowercase \s, \d, \w, and \p symbols match (respectively) any whitespace character, digit, alphanumeric character, or any printable character. The uppercase versions are the opposites; they match any single character that the lowercase versions don't match. \0, \a, \b, \f, \r, and \t These are control characters, just as they would be in C strings. Note that there is no \n. \{n\} or \{n} This is a closure operator, which means that it can only be placed after something that matches a single character. It controls the number of times that the single-character expression should be repeated. The \{n\} or \{n} operator, in particular, means that the preceding expression should be repeated exactly n times. For example, /^-\{80\}$/ matches a line of eighty hyphens, and /\<[[:alpha:]]\{4}\>/ matches any four-letter word. \{n,m\} or \{n,m} This is a closure operator which means that the preceding single-character expression should be repeated between n and m times, inclusive. If the m is omitted (but the comma is present) then m is taken to be infinity. For example, /"[^"]\{3,5\}"/ matches any pair of quotes which contains three, four, or five non-quote characters. /.\{81,}/ matches any line which contains more than 80 characters. * The * metacharacter is a closure operator which means that the preceding single-character expression can be repeated zero or more times. It is equivalent to \{0,\}. For example, /.*/ matches a whole line. NOTE: If the magic option is turned off, then * is treated as an ordinary, literal character. You should use \* to get the meta-character version in this case. \+ The \+ metacharacter is a closure operator which means that the preceding single-character expression can be repeated one or more times. It is equivalent to \{1,\}. For example, /.\+/ matches a whole line, but only if the line contains at least one character. It doesn't match empty lines. \? The \? metacharacter is a closure operator which indicates that the preceding single-character expression is optional -- that is, that it can occur 0 or 1 times. It is equivalent to \{0,1\}. For example, /no[ -]\?one/ matches "no one", "no-one", or "noone". Anything else is treated as a normal character which must exactly match a character from the scanned text. The special strings may all be preceded by a backslash to force them to be treated normally. 5.2 Substitutions The :s command has at least two arguments: a regular expression, and a substitution string. The text that matched the regular expression is replaced by text which is derived from the substitution string. You can use any punctuation character to delimit the regular expression and the replacement text. The first character after the command name is used as the delimiter. Most folks prefer to use a slash character most of the time, but if either the regular expression or the replacement text uses a lot of slashes, then some other punctuation character may be more convenient. Most other characters in the substitution string are copied into the text literally but a few have special meaning: .-------.----------------------------------------------------------. |SYMBOL | MEANING | |-------|----------------------------------------------------------| | ^M | Insert a newline (instead of a carriage-return) | | & | Insert a copy of the original text | | ~ | Insert a copy of the previous replacement text | | \1 | Insert a copy of that portion of the original text which | | | matched the first set of \( \) parentheses | | \2-\9 | Do the same for the second (etc.) pair of \( \) | | \U | Convert following characters to uppercase | | \L | Convert following characters to lowercase | | \E | End the effect of \U or \L | | \u | Convert the next character to uppercase | | \l | Convert the next character to lowercase | | \# | Insert the line number, as a string of digits | | \0 | Insert a nul character | | \a | Insert a bell character | | \b | Insert a backspace character | | \f | Insert a form-feed character | | \n | Insert a line-feed character | | \r | Insert a carriage-return character | | \t | Insert a tab character | ^-------^----------------------------------------------------------^ These may be preceded by a backslash to force them to be treated normally. The delimiting character can also be preceeded by a backslash to include it in either the regular expression or the substitution string. Traditionally \0 was a synonym for the & symbol -- they both inserted a copy of the matching text. Elvis breaks from tradition here to make \0 insert a NUL character because there would otherwise be no way to have a substitution insert a NUL character. 5.3 Options Elvis has two options which affect the way regular expressions are used. These options may be examined or set via the :set command. The first option is called "[no]magic". This is a boolean option, and it is "magic" (TRUE) by default. While in magic mode, all of the meta-characters behave as described above. In nomagic mode, the ., [...], and * characters loose their special meaning unless preceeded by a backslash. Also, in substitution text the & and ~ characters are treated literally unless preceeded by a backslash. The second option is called "[no]ignorecase". This is a boolean option, and it is "noignorecase" (FALSE) by default. While in ignorecase mode, the searching mechanism will not distinguish between an uppercase letter and its lowercase form, except in a character list metacharacter. In noignorecase mode, uppercase and lowercase are treated as being different. Also, the "[no]wrapscan" and "[no]autoselect" options affect searches. 5.4 Examples This example changes every occurrence of "utilize" to "use": :%s/utilize/use/g This example deletes all whitespace that occurs at the end of a line anywhere in the file. :%s/\s\+$// This example converts the current line to uppercase: :s/.*/\U&/ This example underlines each letter in the current line, by changing it into an "underscore backspace letter" sequence. (The ^H is entered as "control-V backspace".): :s/[a-zA-Z]/_^H&/g This example locates the last colon in a line, and swaps the text before the colon with the text after the colon. The first \( \) pair is used to delimit the stuff before the colon, and the second pair delimit the stuff after. In the substitution text, \1 and \2 are given in reverse order to perform the swap: :s/\(.*\):\(.*\)/\2:\1/ ═══ 1.6. Elvis 2.1 Options ═══ 6. OPTIONS Options are a primary means of configuring the appearance and behavior of elvis. They are set via the :set command, or the :let command. The options' values are examined directly by elvis internally, and can also be displayed via :set, or in an expression. The following tables list the names, type, group, and description of each option. One table lists all options alphabetically, and the other breaks list down into groups of related options. I recommend the latter, since there are a lot of options. Most options have two names -- a short name that is easy to type in, and a longer descriptive name. You can type in either name; they work equivalently. Elvis always outputs the longer name when it is listing values. Each option accepts a specific type of value. The most common types are boolean, number, string, and one-of, but some options have weird types. Each option serves as an attribute of something. The group of an option designates what it is an attribute of. For example, the "filename" option is an attribute of buffers; when you switch to a different buffer, it will have a different value for the "filename" option. Other options are attributes of windows, or display modes, etc. Here's a complete list: .---------.-------------------------------------------------------. | GROUP | DESCRIPTION | |---------|-------------------------------------------------------| | buf | Attributes of buffers | | win | Attributes of windows | | syntax | Attributes of the "syntax" display mode | | x11 | Attributes of the "x11" user interface | | tcap | Attributes of the "termcap" user interface | | windows | Attributes of the "windows" user interface | | win32 | User interface attributes for the Win32 port | | global | Global options | | lp | Printing options | | user | User variables a - z (Global, useful in ex scripts) | ^---------^-------------------------------------------------------^ You don't need to know an option's group to set that option. You can output the values of all options in a group by passing the group name followed by a question mark to the :set command. The following example outputs all of the attributes of the current buffer: :set buf? 6.1 Options, grouped by function  6.1.1 Options that relate the buffer to a file  6.1.2 Statistics about a buffer  6.1.3 Options that affect movement commands  6.1.4 Options that affect input mode  6.1.5 Ex options  6.1.6 Window statistics  6.1.7 Options affecting the appearance of text  6.1.8 Options for a particular display mode  6.1.9 Messages  6.1.10 Words  6.1.11 Options for a particular user interface  6.1.12 Regular expression options  6.1.13 Tag options  6.1.14 Window update parameters  6.1.15 Cache options  6.1.16 Options that describe the system  6.1.17 External programs  6.1.18 Directory names  6.1.19 Initialization options  6.1.20 Keyboard map options  6.1.21 Printing options  6.1.22 Previous arguments  6.1.23 Unsupported options  6.1.24 User variables 6.1.1 Options that relate the buffer to a file .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | filename, file | String | buf | name of file in buffer | | bufname, buffer | String | buf | name of buffer | | bufid, bufferid | Number | buf | ID number of user buffer | | retain, ret | Boolean | buf | keep buffer in session file | | modified, mod | Boolean | buf | buffer differs from file | | edited, samename | Boolean | buf | buffer loaded from filename | | newfile, new | Boolean | buf | filename doesn't exist yet | | readonly, ro | Boolean | buf | don't overwrite filename | | defaultreadonly, dro| Boolean | global | assume all files readonly | | locked, lock | Boolean | win | prevent any alterations | | autowrite, aw | Boolean | global | save file before switching | | writeany, wa | Boolean | global | don't warn of existing file | | backup, bk | Boolean | global | make *.bak file before write| | undolevels, ul | Number | buf | number of undoable commands | | beautify, bf | Boolean | global | strip ctrl chars from files | ^---------------------^---------^--------^-----------------------------^ The filename option stores the name of the text file whose text was initially loaded into the buffer. If no file name is known (e.g., for an internal buffer or a new, untitled buffer) then this will be an empty string. The :file command can be used to change the filename. Also, the filename is set automatically when you write the buffer out, if it had no filename before. The bufname option stores the name of the buffer. Usually this will be the same as the filename, but it can be different. Every buffer has a bufname, even if it doesn't have a filename. The name of a buffer can be changed via the :buffer command. For user buffers, the bufid option stores a unique id number for each buffer. Anyplace where you can use the (name) notation to specify a buffer, you can also use (n) as an abbreviation for the buffer whose bufid=n. Also, for filenames you can use #n for the filename of the buffer whose bufid=n. The retain option indicates whether the buffer is intended to survive past the end of this elvis process. If this option is true and the tempsession option is false (":set retain notempsession") then elvis will allow you to exit even if this buffer hasn't been saved since its last change. When you restart the session, the buffer will still exist with all its changed text intact. By default, the retain option is false (":set noretain") because that mimics traditional vi behavior. The modified option indicates whether the buffer has been modified since the last time it was written out completely. The edited option indicates whether the filename option has been modified since the last time it was written out. If this option is false, elvis will be more cautious about writing the file out. The newfile option indicates that when the buffer was created it tried to load the file identified by the filename option, but that file did not exist at that time. The readonly option indicates that when the buffer was loaded, the original file was marked as being unwritable. Either that, or the defaultreadonly option was set to true (probably via the -R command line flag). This option has two purposes: it gives you a way to detect that you can't write the file out, and it protects you from writing out a file that you meant to just look at without modifying. The locked option prevents you from modifying the buffer. Nearly any command which would modify the buffer will fail. The only exceptions are "undo" commands, and commands such as :e which merely reload the buffer from its original file. Setting the autowrite option allows elvis to automatically write the current buffer out to a file if it has been modified, before switching to another buffer. By default this option is off, so if you try to switch away from a modified buffer, elvis will just give an error message and refuse to switch until you manually write the file out. Elvis tries to save you from accidentally clobbering existing files. Setting the writeany option disables this protection; elvis will allow you to overwrite any file that the operating system will allow, without giving any warnings. The backup option isn't used internally by elvis, but the default elvis.bwf file checks this flag to determine whether it should attempt to make a backup of a file it is about to overwrite. By default, this option is false, so backups will not be made. For each buffer, the undolevels option indicates the number of "undo" versions elvis will maintain. Each undo level requires at least three blocks of the session file (typically 2K bytes each, 6K total) so you probably don't want to set this higher than 100 or so, and you probably want to keep it much lower. The default is 0, which is a special case that mimics vi's traditional behavior. If the beautify option is true, then whenever elvis reads text from a file or external program, it will strip any control characters other than tab, linefeed or formfeed. This is false by default. 6.1.2 Statistics about a buffer .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | readeol, reol | One of | buf | newline mode when reading | | writeeol, weol | One of | global | newline mode when writing | | bufchars, bc | Number | buf | number of characters | | buflines, bl | Number | buf | number of lines | | partiallastline, pll| Boolean | buf | file didn't end with newline| | errlines | Number | buf | buflines when :make was run | | internal | Boolean | buf | elvis requires this buffer | | putstyle, ps | One of | buf | type of text in a cut buffer| ^---------------------^---------^--------^-----------------------------^ The readeol option determines how elvis reads the file into a buffer. It can be one of the following:  "unix" The file is opened in binary mode, and any Line Feed characters in the file are converted to newline characters in the buffer.  "dos" The file is opened in binary mode, and any Carriage Return/Line Feed pairs from the file are converted to newline characters in the buffer.  "mac" The file is opened in binary mode, and any Carriage Return characters from the file are converted to newline characters in the buffer.  "text" The file is opened in text mode, and no other conversion takes place.  "binary" The file is opened in binary mode, and no conversion takes place. The compiled-in default is "text", but the standard elvis.brf file sets it to a file-dependent value via the fileeol() function. The writeeol option influences how elvis writes buffers out to a file. If a buffer's readeol option is set to "binary", then the value of writeeol is ignored for that buffer; the file will be written in binary. Otherwise it can be one of the following to determine the output format:  "unix" The file is opened in binary mode, and newlines are written out as Line Feed characters.  "dos" The file is opened in binary mode, and newlines are written out as Carriage Return/Line Feed pairs.  "mac" The file is opened in binary mode, and newlines are written out as Carriage Return characters.  "text" The file is opened in text mode, and no conversion takes place.  "binary" The file is opened in binary mode, and no conversion takes place.  "same" The value of the readeol option is used to control the output format. The default value is "same". You might want to change that to some other mode to force the file to be written in a specific format; for example, setting it to "text" will cause a non-binary file to be written in the local text format. The bufchars and buflines options indicate the number of characters and lines in the buffer, respectively. The buflines option works by counting newline characters; it is unaffected by vagaries of the display mode. These options can't be set. The partiallastline option indicates whether the file's last line ended with a newline. Text files should always end with a newline. Traditionally, when vi loaded a file that contained a partial last line, it would append a newline to the edit buffer to complete that last line. The extra newline would be written out when the buffer was saved to a file. That's great for vi, but elvis can edit binary files as well as text, and appending newlines onto binary files could cause some problems. So elvis appends a newline just like vi, but also sets the partiallastline option to remind itself that when the buffer is saved in binary mode, the last newline should be omitted. Also, the hex display mode is smart enough to hide the added newline when this option is set. The errlines option is used to store the number of lines that were in the buffer when the last :make or :cc command was run. Any difference between buflines and errlines is used to adjust the line numbers reported in any error messages, to compensate for lines which have been inserted or deleted since then. The internal option indicates that elvis uses the buffer internally. Such buffers can't be deleted. The putstyle option is only relevant for cut buffers. It indicates whether the cut buffer contains characters, whole lines, or a rectangular area. It is set automatically whenever you yank or cut text into a cut buffer; when you put (paste) the contents of that buffer, elvis checks the value of this option to determine how the text should be inserted into your edit buffer. 6.1.3 Options that affect movement commands .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | matchchar, mc | String | global | characters matched by % | | paragraphs, para | String | buf | nroff paragraph commands | | sections, sect | String | buf | nroff section commands | | sentenceend, se | String | global | punct at end of sentence | | sentencequote, sq | String | global | punct allowed after se | | sentencegap, sg | Number | global | spaces required after sq | | scroll, scr | Number | win | scroll amount for ^D/^U | ^---------------------^---------^--------^-----------------------------^ The matchchar option stores a list of matching character pairs, for use by the % visual command. In each pair, the first character should be an opening parenthesis (or whatever) and the second character should be the corresponding closing parenthesis. If both characters are identical, then the % command will try to guess whether it should search forward or backward. The default value is mc=[]{}(), but you may wish to add :set mc=[]{}()<>\"\" to your ~/.exrc (or ~/elvis.rc) file. The paragraphs option stores a list of two-letter nroff paragraph commands. This list is used by the { and } movement commands. Similarly, the sections option stores a list of section commands, affecting the [[ and ]] commands. Their defaults are paragraphs="PPppIPLPQP" and sections="NHSHSSSEse". The sentenceend, sentencequote, and sentencegap options all affect the ( and ) sentence motion commands. The sentenceend option is a list of punctuation characters which can appear at the end of a sentence. The sentencegap option is the number spaces that must follow a sentenceend character in order for it to count as the end of a sentence. The sentencequote option is a list of punctuation characters that can appear between the sentenceend character and the spaces. Their defaults are sentenceend="?!.", sentencequote=")\"", and sentencegap=2, which meets the proposed POSIX specifications. The scroll option indicates the number of lines that the ^U and ^D commands should scroll the screen by. Its default value is 12. 6.1.4 Options that affect input mode .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | autoindent, ai | Boolean | buf | auto-indent new text | | inputtab, it | One-Of | buf | input mode's (Tab) key | | completebinary, cob | Boolean | global | complete names of binaries? | | autotab, at | Boolean | buf | allow autoindent to use '\t'| | tabstop, ts | Number | buf | width of tabstop columns | | shiftwidth, sw | Number | buf | width used by < and > | | textwidth, tw | Number | buf | width for word-wrap, or 0 | | wrapmargin, wm | (weird) | win | set textwidth from right | | digraph, dig | Boolean | global | allow X-backspace-Y entry | ^---------------------^---------^--------^-----------------------------^ Setting the autoindent option causes elvis to automatically insert whitespace at the start of each line, to make it line up with the preceding line. This is convenient when you're editing C source code. It is off by default. The inputtab option controls the behavior of the Tab key. It can be set to one of the following values:  tab - insert an actual tab character. This is the traditional vi behavior, and the default for user buffers.  spaces - insert enough space characters to look like a tab character.  filename - attempt filename completion on the preceding word.  identifier - attempt tag name completion on the preceeding word. If the word is already comlete, or if cursor isn't at the end of a word, then it inserts a plain tab character. This can be handy when you're editing source code.  ex - a smarter version of filename completion, it knows enough about ex command line syntax to avoid some tabbing mistakes that the filename setting can make. It can also complete ex command names, tag names, option names, and option values. This is the default for the (Elvis ex history) buffer, which is used for entering in ex commands. The completebinary option controls whether binary files are included in the list of possible filename completions. The default setting is nocompletebinary, so binary files are omitted. This is handy when you're editing source code -- if your directory contains "foo.c" and "foo.o" (or "FOO.OBJ" in the Land of the Lost), then typing f-o-o-TAB will complete the "foo.c" name. The autotab option affects the behavior of the < and > operator commands, and the ^D and ^T input mode keystrokes. If autotab is true then elvis will include tab characters in the indentation whitespace; if it is false then the indentation whitespace will consist entirely of space characters. By default, it is true. Note that if you start with a buffer which contains no tabs, and do a ":set inputtab=spaces noautotab" then no amount of editing will result in the buffer containing tabs... unless you get tricky with ^V or something. The tabstop option affects the way tab characters are displayed, by specifying how far apart the tab stops should be located. When elvis displays a file with tabs, it displays the tabs as a variable number of spaces. You should probably leave this option at its default value (8) since changing this will make your file look strange in any other context. If you want to use indentation levels of less than 8 characters, you're better off changing shiftwidth. The shiftwidth option indicates how far left or right the < and > operator commands (and the ^D and ^T input mode keystrokes) should shift the line of text. This is used for adjusting the indentation of lines. When editing a text file in "normal" display mode, the textwidth option can be used to cause word-wrap to occur when a line gets too long. The default value of textwidth is 0, which disables automatic word-wrap. Setting it to any larger value causes word-wrap to occur when text is inserted into a line, causing that line to become wider than textwidth columns. (Note that this has nothing to do with the display formatting of the "html" and "man" display modes.) The wrapmargin option is provided for backwards compatibility. It allows you to set the textwidth relative to the right edge of the window, instead of the left edge. This option's value is actually derived from the textwidth option's value and the window's width, so if you resize a window this option's value will appear to change to correspond to the new width; textwidth will not change. Digraphs allow you to enter non-ASCII characters as a combination of two ASCII characters. There are two ways to enter digraphs: ^K X Y and X backspace Y. The second form can cause some confusion if you're not expecting it, so the digraph option was created as a way to disable that second form. The first form of digraphs is always available. This option is false by default, to avoid the confusion. 6.1.5 Ex options .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | prompt | Boolean | global | issue ":" prompt in ex mode | | autoprint, ap | Boolean | global | print current line in ex | | report | Number | global | minimum # lines to report | | optionwidth, ow | Number | global | widths of ":set all" values | ^---------------------^---------^--------^-----------------------------^ The prompt option controls whether a ":" prompt is issued before reading each command line in EX mode. It is true by default, and should usually be left that way. The autoprint option causes elvis to display the current line of the edit buffer in certain circumstances, while you're in EX mode. It is true by default. The report option determines the minimum number of lines that must change in a file, before elvis will bother to display a count of the changed lines. As a special case, if report=0 then it won't report any changes, or failed :s/old/new/ commands. Its default value is 5, so small changes won't be reported but big ones will. optionwidth sets a limit on how wide a single option can be when output by a ":set" or ":set all" command. Limiting the widths is a good idea, because otherwise a single option that has a long value could force the output to use fewer columns, forcing some options scrolling off the top of the screen before you can read them. The ":set" command likes to leave at least two spaces after each column. The default value is optionwidth=24, which guarantees that at least 3 columns can fit on an 80-character terminal, since 80/(24+2)=3. Note that optionwidth has no effect on options that you explicitly name in a ":set" command; for example, ":set tags?" will show you the entire tag path regardless of the value of optionwidth. 6.1.6 Window statistics .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | windowid, id | Number | win | ID number of current window | | columns, cols | Number | win | width of window | | lines, rows | Number | win | height of window | ^---------------------^---------^--------^-----------------------------^ The windowid option stores the ID number of the current window. These window IDs are listed by the :buffer command. Some GUIs may also display the window ID as part of the window's title. This value is set to a unique value automatically when the window is created. You can't change it. The columns and lines options indicate the size of the window. 6.1.7 Options affecting the appearance of text .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | list, li | Boolean | win | show markups, newlines, etc.| | showmarkups, smu | Boolean | global | show markup at cursor | | bufdisplay, bd | String | buf | default display mode | | display, mode | String | win | name of current display mode| | number, nu | Boolean | win | display line numbers | | ruler, ru | Boolean | win | display cursor's line/column| | showcmd, sc | Boolean | win | display command characters | | showmatch, sm | Boolean | win | highlight matching parens | | showmode, smd | Boolean | win | display the command state | | showname, snm | Boolean | global | display the buffer name | | showtag, st | Boolean | global | display tag on status line | | nonascii, asc | One-Of | global | how to display non-ascii | | showstack, sstk | Boolean | win | display some debugging info | ^---------------------^---------^--------^-----------------------------^ In the "normal" or "syntax" display modes, the list option causes tab characters to be shown as ^I instead of being expanded to the appropriate amount of whitespace, and it causes the end of each line to be marked with a $ character. In "html" or "man" mode, it causes all of the markups to be displayed. In "html" or "man" mode, the showmarkups option causes the markup at the cursor to be displayed, but leaves other markups hidden. It has no effect in other display modes. This option is off by default, so markups won't suddenly become visible as you move the cursor around. Each buffer has a bufdisplay option, which indicates that buffer's preferred display mode. Whenever a window starts to show a buffer, it switches its display mode to that buffer's bufdisplay mode. You should set bufdisplay to the name of a supported display mode: normal, syntax, html, man, tex, or hex. The compiled-in default is normal but the standard elvis.arf file tries to choose a more clever default, based on the extension of the buffer's filename. The display option indicates which display mode the window is currently in. You can't set this option directly; you must use the :display command instead. The number option causes a line number to be prepended to the start of each line. The line numbers are defined as "one plus the number of newlines preceding the start of the line," which is not necessarily how the current display mode defines lines. Consequently, the line numbers may not increment by 1 every time. These line numbers do correspond to the ruler and the visual G command, though. This option is false by default. The ruler option causes the current line number and column number to be displayed at the bottom of the screen. This uses the same definition of "line number" as the number option, above. This option is false by default. When entering multi-character commands, the showcmd option causes the preceding characters of the command to be displayed at the bottom of the window. The showmatch option helps you locate matching parentheses. When you're in input mode, and you type a ), ], or } character, elvis will cause the matching (, [, or { character to be highlighted on the screen. This option is false by default. The showmode option causes elvis to display a one-word label for its current parse state in the lower right-hand corner of the window. Usually, this will be either "Command" or "Input". This option is false by default, but I suggest you make it true because it really is handy. The showname option causes elvis to display the buffer name on the bottom row of each window, unless it has something else to show there such as an error message. The showtag option causes elvis to display (on the bottom row of each window) the name of the tag being defined at the cursor's position. Usually, this means it tells you the name of the function you're editing. When this option is true, each time you load a text file into an edit buffer elvis will scan the "tags" file for any tags which are defined in the text file. Elvis builds a table of those tags, and stores it in RAM for the sake of speed. Then, each time the window is updated, elvis will compare the cursor position to the definition lines of each tag, and display the name of the last tag it found which is defined at or before the cursor position. By default, this option is false because the tag loading can be slow. The version of ctags distributed with elvis has a "-l" flag which causes it to generate "ln" hints, which give the line number where the tag is defined. Elvis can use these hints to greatly accelerate the loading of tags when you switch files. The "-l" option is enabled by default if you don't give any flags, so you don't need to give it explicitly unless you're also giving some other flags. NOTE: The MS-DOS version of elvis is normally configured to omit the showtag option, because memory is tight in the lower 640K. The nonascii option tells elvis how to display characters 0x80 through 0xff. It can have one of the following values: .-------.------------------------------------------------. | VALUE | MEANING | |-------|------------------------------------------------| | all | All characters 0x80-0xff are visible | | most | Chars 0xa0-0xff are visible, but not 0x80-0x9f | | none | Chars 0x80-0xff are not visible | | strip | Convert 0xa0-0xfe to ASCII; others not visible | ^-------^------------------------------------------------^ Any characters which aren't visible will be displayed as '.' characters. Note that this only affects the way the characters are displayed; they are actually stored with their true 8-bit value. The default value of nonascii is "most", because that is the correct value for the Latin-1 symbol set. The showstack option causes some debugging output to appear on the bottom row of the window. It is false by default, and you should leave it that way. 6.1.8 Options for a particular display mode .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | commentfont, cfont | One-Of | syntax | font used for comments | | stringfont, sfont | One-Of | syntax | font used for strings | | keywordfont, kfont | One-Of | syntax | font used for reserved words| | functionfont, ffont | One-Of | syntax | font used for function names| | variablefont, vfont | One-Of | syntax | font used for variables | | prepfont, pfont | One-Of | syntax | font used for preprocessor | | otherfont, ofont | One-Of | syntax | font used for other symbols | | includepath, inc | String | syntax | where to find #include files| ^---------------------^---------^--------^-----------------------------^ In the syntax display mode, the commentfont, stringfont, keywordfont, functionfont, variablefont, prepfont and otherfont options specify which font is to be used for different parts of the source code. Each option can be set to normal, bold, emphasized, italic, underlined, or fixed. The prepfont is used for preprocessor directives. The keywordfont is used for reserved words such as "int" and "return". The functionfont is used for any other word which is followed by an opening parenthesis character. The otherfont is used for any other word which matches some language-dependent criteria; for C, the word must either contain no lowercase letters or end with a "_t" (probably a constant or a user-defined type). The variablefont is used for all other words. Punctuation is always in the normal font; you can't control that. You can set these variables during initialization, in the .exrc or elvis.rc file. After that, your window must actually be in the "syntax" mode for these to be accessible. As a separate step, some user interfaces allow you to specify a color to be used for each font, via the :color command. The includepath option contains a list of directory names where elvis should look for #include files. When you look up a tag whose name begins with a quote character, elvis searches through those directories for a file with the same name as the tag (with the quotes stripped off). This means that you can move the cursor onto a #include file name, hit ^], and have elvis load the indicated header file. 6.1.9 Messages .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | terse, te | Boolean | global | don't translate messages | | verbose | Numeric | global | give more status messages | | errorbells, eb | Boolean | global | ring bell for error message | | warningbells, wb | Boolean | global | ring bell for warning msg | | flash, vbell | Boolean | global | substitute flash for bell | ^---------------------^---------^--------^-----------------------------^ The terse option indicates whether elvis should attempt to translate messages via the elvis.msg file. If terse is true, then no such translation takes place; the built-in messages are used. If terse is false, then elvis will search through the file (actually the "Elvis messages" buffer) for a line which looks like "terse:verbose" and if found it'll use the verbose version instead. By default, terse is false. The verbose option has nothing to do with the terse option. Instead, it indicates the number of -V flags given when elvis was invoked. Larger values indicate that the user wants more status messages to be generated. This is handy when elvis isn't initializing itself the way you expected it to; elvis' initialization code frequently tests the value of verbose and automatically writes status messages when verbose is set to a high enough level. The errorbells and warningbells options cause the terminal's bell to ring when an error message or warning message is generated, respectively. By default the errorbells option is true, and the warningbells option is false. Setting the flash option causes elvis to use a visible alternative to the bell, if one exists. This is nice in a crowded terminal room. By default this option is false. 6.1.10 Words .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | true, True | String | global | locale's True value | | false, False | String | global | locale's False value | | submit, Submit | String | x11 | locale's Submit label | | cancel, Cancel | String | x11 | locale's Cancel label | | help, Help | String | x11 | locale's Help label | ^---------------------^---------^--------^-----------------------------^ These options store words, which are translated via the elvis.msg file when elvis starts up. The default versions of all of them are their capitalized English names. The true and false options exist primarily to allow the english words true and false to be used in expressions to represent Boolean literals. Also, the value of false is used as an alternative false string, in addition to "", "0", or "false". (In a Boolean context, any string that isn't false is considered to be true, so elvis never compares a string to the true option's value.) A Boolean option will return the value of either the true or false option, as appropriate. If you're using the "x11" user interface, then values of the submit and cancel options are used as the labels for the [Submit] and [Cancel] buttons in a dialog. Also, if the dialog contains any Boolean options, the value will be displayed using values of the true and false options. Currently the help option does nothing. Eventually I expect to add pull-down menus to the "x11" interface, though, and in Motif menu bars the "Help" menu traditionally appears on the far right edge. The value of the help option will allow elvis to recognize the "Help" menu. 6.1.10 Options for a particular user interface .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | term, ttytype | String | tcap | terminal's termcap entry | | ttyrows, ttylines | Number | tcap | height of screen | | ttycolumns, ttycols | Number | tcap | width of screen | | ttyunderline, ttyu | Boolean | tcap | okay to mix color & underln | | codepage, cp | Number | win32 | console character set | |---------------------|---------|--------|-----------------------------| | scrollbar, sb | Boolean | (gui) | enable the scrollbar | | toolbar, tb | Boolean | (gui) | enable the toolbar | | statusbar, stb | Boolean | (gui) | enable the statusbar | |---------------------|---------|--------|-----------------------------| | menubar, mb | Boolean | windows| enable the menubar | | font, fnt | String | windows| base font | | normalstyle, nfn | String | windows| n or combination of b/i/u | | boldstyle, bfn | String | windows| n or combination of b/i/u | | italicstyle, ifn | String | windows| n or combination of b/i/u | | fixedstyle, ffn | String | windows| n or combination of b/i/u | | emphasizedstyle, efn| String | windows| n or combination of b/i/u | | underlinedstyle, nfn| String | windows| n or combination of b/i/u | |---------------------|---------|--------|-----------------------------| | normalfont, xfn | String | x11 | name of normal font | | boldfont, xfb | String | x11 | name of bold font | | italicfont, xfi | String | x11 | name of italic font | | controlfont, xfc | String | x11 | name of toolbar font | | underline, uln | Boolean | x11 | enables underlining | | toolbar, xtb | Boolean | x11 | enables the toolbar | | scrollbarleft, xsl | Boolean | x11 | enable scrollbar on side | | scrollbarwidth, xsw | Number | x11 | size of scrollbar, in pixels| | scrollbartime, xst | Number | x11 | delay for scrollbar repeat | | borderwidth, xbw | Number | x11 | size of text area's border | | dblclicktime, xdct | Number | x11 | double-click speed, 1/10 Sec| | blinktime, xbt | Number | x11 | cursor blink rate, 1/10 Sec | | textcursor, tc | Number | x11 | one of hollow, opaque, xor | | xrows, xlines | Number | x11 | height of new windows | | xcolumns, xcols | Number | x11 | width of new windows | | firstx, xpos | Number | x11 | horiz. position of first win| | firsty, ypos | Number | x11 | vert. position of first win | | stagger | Number | x11 | offset for next new window | | icon | Boolean | x11 | use the built-in icon? | | stopshell, ssh | String | x11 | interactive shell command | | autoiconify, aic | Boolean | x11 | iconify old window | | altkey, metakey | One of | x11 | effect of the Alt key | | focusnew, fn | Boolean | x11 | force focus into new window | | warpto, wt | One of | x11 | ^W^W forces pointer movement| | warpback, xwb | Boolean | x11 | upon exit, point to xterm | | outlinemono, om | Number | x11 | char outlining for X11-mono | ^---------------------^---------^--------^-----------------------------^ 6.1.10.1 Termcap options The term, ttyrows, ttycolumns, and ttyunderline options are only present if you're using the termcap user interface. They indicate the name of the termcap entry being used (normally taken from the TERM environment variable), the size of the screen, and whether it is safe to try underlining text when colors have been assigned to fonts. The ttyunderline option is true by default, but it should be made false on the Linux console, because the console driver has a bug which prevents underlined text from being shown in color. The codepage option only exists in the Win32 version with the termcap interface (WindowsNT or Windows95, in console mode). It indicates which code page (character map) the console is using. Its value is persistent; if you change it in elvis, the console will remain changed even after you exit elvis. Changing the code page has no effect on the digraph table, or elvis' idea of which non-ASCII characters are printable or should be treated as letters; it only reconfigures the console driver. Typical values are 437 for the standard IBM PC character set, and 850 for extra European characters. 6.1.10.2 Options common to Windows and X11 The scrollbar, toolbar, and statusbar options indicate whether the scrollbar, toolbar, and statusbar should be visible, respectively. By default, all are are visible. 6.1.10.2 Windows options The menubar option indicates whether the menu bar should be visible. By default, it is visible. The font option stores the name of the base font. The easiest way to set it is via the "Options->Font" menu item. The normalstyle, boldstyle, italicstyle, fixedstyle, emphasizedstyle, and underlinedstyle options determine how elvis will derive each of its fonts from the base font. The values of these options are strings. If the string is "n" then the base font is used unmodified. Other possibilities are any combination of "b" for bold, "i" for italic (slanted), and "u" for underlined. For example, ":set ufn=bu" causes elvis' underlined font to be drawn in bold with an underline. 6.1.10.3 X11 options The other options all apply to the x11 interface. The normalfont, boldfont, and italicfont options control the X fonts used for displaying text. Typically, the elvis.ini or ".exrc" file will set these. If you do choose to set them in one of these files, be sure to have your initialization script check which interface is being used because if elvis is using the termcap interface then these x11 options won't exist. These options all default to an empty string; this is a special case which causes elvis to use the "fixed" font for normal text, and to derive the bold and italic fonts from the normal font. The controlfont option determines which font is used for displaying the labels of toolbar buttons, and also the statusbar. Unlike the other fonts, this one is permitted to have a variable pitch. If it is unset, then elvis will use the font named "variable" by default. The underline option determines whether characters in the "underlined" font should be displayed as underlined. Normally, underline is true, so they are underlined. Setting nounderline will cause them to be displayed as normal characters, but in the color of underlined text. The toolbar option controls whether the toolbar is visible or not. It is normally true, which makes the toolbar visible. The toolbar can be configured via the :gui command. The statusbar option controls the visibility of the statusbar. It is true by default, which makes the statusbar is visible. The statusbar always displays the information which would otherwise be shown on the bottom row of the text area only when the ruler and showmode options were true. When you press a toolbar button, the button's one-line description is shown on the statusbar. The scrollbarleft option deterimines which side of the window the scrollbar will be drawn on. This option is false by default, so the scrollbar appears on the right side of the window. Making it true will cause the scrollbar to be drawn on the left. The scrollbarwidth option controls the size of the x11 scrollbar. The default value is 14 pixels, and the allowed range is 5 to 40 pixels. The scrollbar buttons automatically repeat if you hold a mouse button down scrollbartime tenths of a second. The default is 4 tenths of a second. The main text area of a window looks better when the characters aren't drawn immediately adjacent to the edge. The borderwidth option allows you to specify how many pixels should be left blank between a character and any edge of the text area. The default is 1 pixel. The dblclicktime option allows you to adjust the speed of mouse double-clicks to match your own clicking habits. The default is 3 tenths of a second. The blinktime option controls the cursor blink rate. If set to 0, the cursor will not blink. If set to a value from 1 to 10, then the cursor will first be visible for that many tenths of a second, and then invisible for the same amount of time. The cursor will only blink in the window which currently has keyboard focus. The textcursor option controls the way the block text cursor is drawn. It can be xor, hollow, or opaque. The default is xor, which causes the cursor to be drawn as a filled rectangle with the XOR bitblt function. This converts the background color to the cursor color, and the foreground color to an unpredictable color; hopefully the foreground color will contrast with the cursor color well enough to allow you to discern what the underlying character is. The hollow cursor style causes the cursor to be drawn as an unfilled rectangle. This allows you to easily see the underlying character, and detect whether it is highlighted or not. The opaque cursor style draws a filled rectangle, which is easier to locate but you can only see the underlying character between blinks. The xrows and xcolumns options control the initial size of windows. They default to 34 and 80, respectively, and can also be set via the -geometry command-line flag. After a window has been created, you can use your window manager to resize the window. The firstx and firsty options, if set, control the position of the first window that elvis creates. If they are unset, then elvis doesn't specify a position for the window. The -geometry command-line flag can be used to set these options. After the first window has been created, if the stagger option is set to a non-zero value then any new windows are created that many pixels down and to the right of the current window. If stagger is zero, then elvis won't specify a position for the new windows, so the window manager can choose the location itself. The icon option can only be set in an initialization file such as elvis.ini or ".exrc"; once the first window has been created it is too late to change it. This option controls whether the window will be given the default, built-in icon. It is true by default, so windows will get the icon. This is usually a good thing. Some window managers don't allow you to override built-in icons, though, so if you want your window manager to use a different icon for elvis then you'll need to have a "set noicon" in your elvis.ini file. The stopshell option stores a command which runs an interactive shell. It is used for the :shell and :stop ex commands, and the ^Z visual command. Normally, this is set to "xterm &" so you get a shell in a window. The "&" at the end of the command allows elvis to continue responding to user input while the shell is running. When the ^W^W visual command switches keyboard control to an X11 window which as been iconified, elvis automatically deiconifies it. When it does this, if the autoiconify option is set then elvis will iconify the previous window, so the number of iconified elvis windows remains constant. By default, this option is false. Regardless of whether autoiconify is set, you can always use your window manager to iconify or deiconify windows manually. The altkey option controls the effect of the Alt or Meta keys. It can be set to either control-O, setbit, or ignore. The ignore value is self explanatory. If the option is set to control-O then the x11 interface will simulate a ^O keystroke before each actual keystroke. This is handy because if you're in input mode you can just hold down Alt/Meta to perform a series of visual commands. If the option is set to setbit then the x11 interface will set the most significant bit of each ASCII character while the Alt/Meta key is held down. Some other programs use this trick as a means of entering non-ASCII characters. (Elvis has a better way though; check out the :digraph command.) The default is setbit. The focusnew option causes elvis to force input focus to switch to any newly created window, or to one which has been deiconified. It is true by default; making it false (":set nofocusnew") prevents elvis from forcing a change of input focus in those two situations. Note that elvis always forces a change of input focus when you give a command which switches windows, such as ^W^W. The warpto option can cause elvis to force the mouse pointer to move whenever you use keyboard commands such as ^W^W to switch from one elvis window to another. There are two reasons you may wish to do this: either your window manager requires the pointer to be in a window for that window to receive keystrokes, or you want to have your X server automatically pan the screen to bring the next window into view. You can set the warpto option to any one of the following values: don't, scrollbar, origin, or corners. The default is don't which prevents any automatic pointer movement. The scrollbar value causes the pointer to move to the scrollbar, and origin moves it to the upper-left corner. The corners value causes the pointer to move first to the corner furthest from the window's text cursor, and then to the nearest corner; this will cause the X server to pan (if necessary) to bring the entire window into view. The warpback option, if set, causes the X terminal's graphic cursor to be moved back to the window which held keyboard focus at the time when elvis was started. Usually this will be the xterm where you typed in the "elvis files..." command line. Just as the firstx, firsty, and stagger options are intended to allow mouseless positioning of elvis windows, the warpback option is intended to serve as a mouseless way to switch keyboard focus back to the original xterm, so that mouse haters will find elvis' x11 interface as convenient to use as the termcap interface. By default, warpback is false. The outlinemono option affects the way that text is drawn against a stippled background when elvis is run on monochrome X terminals (or with the -mono command-line flag). It has no effect on color systems. Because characters drawn on a stippled background can be hard to read, elvis can draw a white outline around the black characters. The value of outlinemono is a number that indicates how thick the outline should be. 3 is the thickest supported outline, and 0 is no outline at all. The default is 2. 6.1.11 Regular expression options .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | ignorecase, ic | Boolean | global | regexp uppercase=lowercase | | magic, ma | Boolean | global | use normal regexp syntax | | autoselect, as | Boolean | global | visibly mark searched text | | wrapscan, ws | Boolean | global | searching wraps at EOF<->BOF| | gdefault, gd | Boolean | global | default change all instances| | edcompatible, ed | Boolean | global | remember regsub flags | | saveregexp, sre | Boolean | global | remember regexp to use as //| ^---------------------^---------^--------^-----------------------------^ Setting the ignorecase option to true will cause elvis to treat uppercase and lowercase letters as being equal, except in character list metacharacters. When ignorecase is false (the default), they are treated as different. The magic option selects one of two different syntaxes for regular expressions. When magic is true, it uses the normal syntax in which * and . are special characters. When magic is false, it uses a simplified syntax. The autoselect option, when true, causes a successful visual search command such as /regexp to visibly mark the matching text just like the v command does. This is intended to compensate for elvis 2.1's lack of a "c" option in the :s/old/new/ command. By default, autoselect is false. The wrapscan option determines what happens when a search command bumps into the top or bottom of a buffer. If wrapscan is true, then the search will wrap around to the other end of the buffer, so if there's a match anywhere in the buffer, the search will find it. If wrapscan is false, then searches fail when they hit the end of the buffer. By default, wrapscan is true. The gdefault option affects the default behavior of the :s/old/new/ command. It is false by default, which causes :s/old/new/ to assume a count of 1 so only the first instance in each line is changed. Making gdefault true will cause it change all instances in each line, as though the "g" flag had been given. If you give an explicit count or "g" flag, then the value of gdefault is ignored. The edcompatible option causes elvis to remember any flags that are passed into the :s/old/new/flags command, and use them as the default for the next such command. Explicitly naming a flag will toggle that flag's value. This is not the way the old ed editor worked, but this option's name and behavior are traditional in vi. This option is false by default. The saveregexp option is normally true, which causes elvis to remember each regular expression. If, in a latter command, you give an empty regular expression, then elvis will recall the saved regular expression instead. This also affects the n and N commands. You may wish to turn this option off temporarily in a the lib/elvis.arf file if you're using any regular expressions there, so that loading a file doesn't interfere with n and N. 6.1.12 Tag options .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | taglength, tl | Number | global | significant length of tags | | tags, tagpath | String | global | list of possible tag files | | tagstack, tsk | Boolean | global | remember origin of tag srch | | tagprg, tp | String | global | external tag search program | | tagprgonce, tpo | String | global | like tagprg, but auto-resets| ^---------------------^---------^--------^-----------------------------^ These options control how elvis performs tag lookup, as for the :tag ex command or the ^] visual command. You should also check out the previoustag and showtag options. The taglength option defines how many characters are significant in a tag name. By default this option is set to 0, which is a special value indicating that all characters are significant. If you have a lot of long names, you might want to set this to some other value so that you could type in abbreviated names. The tags option stores a list of filenames or directory names where tags are stored. (For directory names, it looks for a file named "tags" in that directory.) When performing tag lookup, elvis will begin by looking for it in the first directory/file mentioned in the list; if it doesn't find it there, then it moves on to the next one, and so on. By default, it just looks in a file named "tags" in the current directory. In a path, names which start with "./" (or ".\" in MS-Windows) are assumed to be relative to the directory of the current file. This means that ":set tags=./tags:tags" will cause elvis to first check the "tags" file in the directory of the current text file, and then the "tags" file in the current directory. NOTE: Traditionally, this elements in this path have been space-delimited. Since every other path in any other context is either colon-delimited (for Unix) or semicolon-delimited (for Microsoft), and it is becoming more common for filenames to contain spaces, elvis uses colons or semicolons for the tag path too. This makes elvis' "tags" settings incompatible with other versions of vi, though. If the tagstack option is true, then before switching to the file and location of a looked-up tag, elvis will store the original file and position on a stack. Later, you can use the :pop or visual ^T commands to return to your original position. If tagstack is false, then the tag stack is unaffected by tag look-up. It is true by default. If the tagprg option is set to any value other than "", then whenever you try to do a tag search via :tag or :browse, elvis will execute tagprg's value as a shell command and interpret its stdout as a list of matching tags. Before the command is run, it is evaluated using the simpler expression syntax with $1 indicating where the arguments should go. The default value of tagprg is "" which causes elvis to use the internal tag search algorithm. The tagprgonce options acts just like the tagprg option, except that tagprgonce automatically reverts to "" the first time it is used. If tagprg and tagprgonce are both set, then tagprgonce is used. It exists mostly so you can easily write aliases which perform specialized searches, without interfering with normal tag searches. The following example creates a new :text command which finds instances of a given text string in any *.c or *.h files. (Note that the "set tagprgonce..." command should be entered on one line; it is shown here on three lines simply as a typographical convenience.) :alias text { set tagprgonce="grep -nsw '(quote(\"'\",$1))' *.[ch] /dev/null \| sed 's/^\\\\\\(.*\\\\\\):\\\\\\(.*\\\\\\):.*/!^ \\1 \\2/'" tag!? !* } NOTE: You might also consider using the ccprg option for this sort of thing, since the :cc command has a smarter line parser than the :tag command. 6.1.13 Window update parameters .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | exrefresh, er | Boolean | global | redraw scrn after each line | | nearscroll, ns | Number | global | scroll vs. jump¢er param| | wrap | Boolean | win | how long lines are displayed| | sidescroll, ss | Number | win | sideways scrolling amount | | optimize, op | Boolean | global | run faster | | animation, anim | Number | global | animation macro speed | | window, wi | Number | global | lines to show for :z command| | pollfrequency, pf | Number | global | rate of testing for ^C | | maptrace, mt | One of | global | debugger: off, run, or step | | maplog, mlog | One of | global | logging: off, reset, append | ^---------------------^---------^--------^-----------------------------^ The exrefresh option affects the frequency of window updates when in EX mode. It is normally false, which causes the window to be refreshed at the end of each EX command. If you set exrefresh to true, then elvis will update the window's image every time an output line is generated; this makes the command run much slower, but gives you more feedback. The nearscroll option controls elvis' behavior when the cursor is moved off the top or bottom of the window. If the new cursor position is within nearscroll lines of the window, then the window is scrolled to bring the new line into view. If the new cursor position is outside that range, then elvis uses a "jump and center" approach, in which the window's image is drawn from scratch with the new cursor line shown in the center of the window. Its default value is 5. The wrap option determines how elvis will display lines which are too long to fit on a single row of the display. It is true by default, which causes long lines to be wrapped onto multiple rows of the display. This is the traditional vi behavior. Changing it to false will cause long lines to be partially displayed on a single row of the display; you can scroll sideways to reveal the rest of the line my moving the cursor onto it, and then off the edge. If the wrap option is false (indicating that long lines should be displayed via side-scrolling) then the sidescroll option controls the scrolling increment. The default is 8, so the display will scroll sideways in chunks of 8 characters at a time. The optimize option affects the efficiency of screen updates. It is normally true, which tells elvis to update the screen image only when it must wait for user input. If you make it false, then elvis will update the screen after every command; among other things, this allows you to see intermediate effects of macros. The animation option is similar. When the optimize option is true, elvis still refreshes the screen periodically while executing a large macro so that animation macros can be seen in all their glory. Elvis attempts to figure out which macros are loops, and when one of those macros is invoked elvis considers updating the screen. If animation=1 then elvis updates the screen every time; when animation=2 it updates the screen an alternate invocations of those macros, and so on. The default, chosen simply through experimentation, is 3. Sometimes elvis will choose the wrong macros to refresh. If that happens, then try running the macro with optimize option turned off. For example, the bouncing ball macros look better with optimize turned off. The window option stores the default number of lines to be displayed by the :z command. Historically it has also been used for forcing vi to update only a portion of the screen, but elvis doesn't use it for that. When elvis is performing some time-consuming operations, such as a global substitution, it will periodically check to see if the user is trying to cancel the operation. For some user interfaces, this inspection takes a significant amount of time so elvis allows the pollfrequency option to reduce the frequency of these checks. The default is 20. Larger values of pollfrequency will make global substitutions run faster; smaller values make elvis respond to ^C sooner. The maptrace option controls elvis' built-in macro debugger. It can be off, run or step. The default is off, which causes macros to run normally. If you change it to run then elvis will display the contents of the mapping queue at the bottom of the screen while running any macro. The step value also displays the mapping queue, but then waits for a keystroke before proceeding. If the keystroke is ^C then the macro is terminated. If the keystroke is r then maptrace is set to run. Any other keystroke causes elvis to pause again after processing the macro's next character. See section 16.3 How to debug macros for more suggestions for debugging macros. The maplog option can be used to log the information displayed by the maptrace option. It also logs any ex commands that are executed, other than those that you enter manually. It is off by default. Setting it to append causes the map trace information to be appended to an internal edit buffer named "Elvis map log". Setting it to reset causes that buffer to be clobbered before the next map trace; when that happens, maplog will be automatically switched to append. You can view the logged data via the command... :("Eml)sp or the long version, ":(Elvis map log)split". 6.1.14 Cache options .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | blkcache, cache | Number | global | number of blocks in cache | | blksize, bsz | Number | global | size of cache block | | blkfill, bfill | Number | global | initial chars per text block| | blkhash, hash | Number | global | size of cache hash table | | blkgrow, bgr | Number | global | allocation table parameter | | blkhit, bh | Number | global | # of block requests in cache| | blkmiss, bm | Number | global | # of block req. not in cache| | blkwrite, bw | Number | global | # of blocks written | | sync | Boolean | global | force changes to disk | ^---------------------^---------^--------^-----------------------------^ You probably don't need to know about the "blk" options. The blkcache option indicates how many blocks from the session file elvis should keep in its own internal cache, and blkhit and blkmiss can be used to gauge the efficiency of the cache. blkwrite indicates how many blocks have been written to the session file. The blksize option indicates the size of each block, blkfill indicates how many characters should be stuffed into each block initially (leaving room for more text that the user may insert later), and blkhash and blkgrow affect a couple of internal tables. Note that the value of blksize can only be set via the -bblksize command line flag, and its value must be a power of 2 in the range [512, 8192]. You can't change blksize after elvis has started (not even in configuration scripts), because by then the session file has already been created with the other block size. If the sync option is true, then elvis will flush all dirty blocks from its cache at the end of each edit command. Doing this will just about guarantee that you can recover your changes after a crash, but it can slow down the computer tremendously. The sync option is false by default, and on multi-user systems it should be left that way. On a single-user system, you might consider setting the sync option. 6.1.15 Options that describe the system .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | version, ver | String | global | elvis version number (2.1) | | bitsperchar, bits | Number | global | character size (always 8) | | gui | String | global | name of user interface | | os | String | global | name of operating system | | program, argv0 | String | global | invocation name of elvis | | session, ses | String | global | name of session file | | tempsession, temp | Boolean | global | delete session file on exit | | newsession, newses | Boolean | global | session file is new | | recovering, rflag | Boolean | global | recovering after a crash | | exitcode, exit | Number | global | exit code of elvis process | ^---------------------^---------^--------^-----------------------------^ The version option stores the version number of elvis -- currently "2.1". If later versions of elvis have features which are incompatible with this version, your script files can use this to check the version number, and skip the uncompatible commands. The bitsperchar option indicates the size of characters that elvis uses internally. Currently this is always 8, but I expect to support 16-bit characters eventually. The gui option indicates which user interface is being used. This can be handy in your initialization files. For example, you might prefer white characters on a blue background when using the "termcap" interface, and black characters on a white background when using the "x11" interface. The os option allows elvis' initialization files to act differently on different operating systems. Its value indicates the name of the local operating system. The program option stores the name by which elvis was invoked; i.e., the value of argv[0]. Typical values would be "elvis" under UNIX, "elvis.exe" under Win32, or "C:\BIN\ELVIS.EXE" under MS-DOS. The default elvis.ini file evaluates tolower(basename(program)) and compares the result to "ex" and "view", to set the initialstate and defaultreadonly options, respectively. The session option stores the name of the current session file. There is rarely any need to check this, but I had to store it someplace and it might as well be accessible, I figured. The tempsession, newsession, and recovering options describe different aspects of the session file. If tempsession is true, then elvis will delete the session file when it exits. If newsession is true, then elvis has just created the file so there may be extra initialization that needs to take place in elvis.ini or someplace. If recovering is true, then the session file may be damaged, so it may be a good idea to skip some initialization steps, or automatically write out all user buffers. The exitcode is the value that elvis will return to its parent process when the elvis process exits. Initially this is 0, which is the conventional indication of a normal, successful exit. You can explicitly set it to other values to indicate special situations. Also, if elvis outputs an error message and exitcode has not been explicitly set, then elvis changes exitcode to 1, so the parent process can know that elvis had an error. 6.1.16 External programs .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | ccprg, cp | String | buf | shell command for :cc | | makeprg, mp | String | buf | shell command for :make | | anyerror, ae | Boolean | global | allow :errlist if readonly | | equalprg, ep | String | buf | shell command for = operator| | keywordprg, kp | String | buf | shell command for K command | | shell, sh | String | global | name of shell program | | warn | Boolean | global | warn if file not saved | ^---------------------^---------^--------^-----------------------------^ The ccprg and makeprg are the programs used by the :cc and :make commands. Before the program strings are executed, they are subjected to the same sort of expression evaluation as the :eval command, with $1 representing any extra arguments from the ex command line, and $2 representing the name of the current file. Their defaults are cc="cc ($1?$1:$2)" and make="make $1". When searching for error messages after a :cc or :make command, elvis will normally ignore errors about files that you don't have write access to. Usually this is convenient, because it prevents elvis from reading header files that you've misused. However, setting anyerror to true will make it read any file that generates a complaint, even if you can't write to it. The equalprg option stores the name of a program to be executed for the visual = operator command. Its default value is "fmt", which is a simple text formatting program. The keywordprg option stores the name of the program used by the visual K command. This string is evaluated with $1 being replaced with the word under the cursor at that time, and $2 the name of the current file. The default value is "ref $1 file:$2"; the ref program looks up a tag and displays it. If you're using the x11 user interface, then you might want try the following, which causes the function's header to be displayed in a separate pop-up window: set kp="ref $1 file:$2 2>&1 \| xmessage -file - >/dev/null 2>&1 &" The shell option stores the name of the system's command-line interpreter. It is used when executing all of the above programs, as well as commands entered for the EX :! and visual ! commands. Its default value is system-dependent; typically it will be "/bin/sh" for UNIX, and "C:\COMMAND.COM" for MS-DOS. When any external program is executed, if the current buffer has been changed but not written out to the file, then elvis will normally give a warning message. Setting the warn option to false disables this message. 6.1.17 Directory names .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | home | String | global | home directory | | elvispath, epath | String | global | list of possible config dirs| | sessionpath, spath | String | global | list of possible session dir| | directory, dir | String | global | where to store temp files | ^---------------------^---------^--------^-----------------------------^ The home option is the name of your home directory. The value of this option is used for replacing the ~ character at the start of a full pathname. If an environment variable named HOME exists, then home is initialized from its value. Otherwise, its default value is set as follows: For UNIX: The default is "/". For Win32: The default is derived from environment variables named HOMEDRIVE and HOMEPATH, which will normally always be defined. Their default value is usually "C:\users\default". If either of those environment variables is undefined, then elvis will attempt to find the pathname of the program, and use its directory. As a last resort, elvis will use "C:\" as the default home directory. For OS/2: The default home directory is the one containing ELVIS.EXE, or if that can't be found then it will use "C:\" as the default home directory. For MS-DOS: The default home directory is the one containing ELVIS.EXE. The elvispath option stores a list of directory names where elvis might find its configuration files. If there is an ELVISPATH environment variable, then the elvispath option is initialized from the value of ELVISPATH. Otherwise it is set to a value such as "~/.elvislib:/usr/local/lib/elvis" so that elvis will search first in a subdirectory of the user's home directory, and then in the directory where the standard versions of those files were installed. A path like this allows users to override elvis' behavior if they want. The default value depends the operating system, as follows: For UNIX: The default contains ~/.elvislib and the directory that you specified as the data directory when you ran the configure script. (E.g, "configure --datadir=/usr/lib/elvis") The default data directory is /usr/local/lib/elvis, so usually elvispath will default to "~/.elvislib:/usr/local/lib/elvis". For Win32, OS/2, or MS-DOS: The default contains ~\elvislib, and the directory where elvis.exe resides, and a subdirectory under that named "lib". For example, if elvis is installed as C:\elvis\elvis.exe then elvispath would be ~\elvislib;C:\elvis;C:\elvis\lib. The sessionpath option gives elvis a list of possible directories where session files might be placed. Elvis uses the first writable directory in that list, and ignores all of the others. The default value depends on the operating system, and can be overridden by the SESSIONPATH environment variable. You can't change the sessionpath option after elvis has started, because the session file has already been created by then. The directory option gives the name of the directory where elvis will store its temporary files. The default value is system-dependent. Note that this is not where the session file is stored; the session option gives the name of the session file. 6.1.18 Initialization options .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | exrc, ex | Boolean | global | interpret ./.exrc file | | modeline, ml | Boolean | global | interpret modelines | | modelines, mls | Number | global | positions of modelines | | safer, trapunsafe | Boolean | global | be paranoid | | initialstate, is | One-Of | global | command mode of new windows | ^---------------------^---------^--------^-----------------------------^ The exrc option has no built-in meaning to elvis, however the default elvis.ini file uses this option to determine whether it should look for a ".exrc" file in the current directory. The modeline option controls whether elvis will look for modelines in each buffer after it has been loaded from a file. If modelines is true, then elvis will search through the first and last modelines lines of the buffer for something that looks like "ex:commands:" or "vi:commands:" and if found, it executes the commands as an ex command line. This is typically used for changing tabstops and the like. The modeline option is false by default, and modelines is 5. The safer option closes some security holes. It is intended to make modelines and a .exrc file in the current directory safe to use, but I'm not making any promises. When the "safer" option is true, certain commands are disabled, wildcard expansion in filenames is disabled, and certain options are locked (including the safer option itself). Typically you will use the ex command :safer to execute an untrusted file, and :source to execute a trusted one, rather than futz with the value of the safer option directly. The initialstate option determines what command mode new windows will start in. It can be one of input, replace, vi, or ex. The default is vi, the visual command mode. 6.1.19 Keyboard map options .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | remap | Boolean | global | allow key maps to use maps | | keytime, kt | Number | global | timeout for function keys | | usertime, ut | Number | global | timeout for multi-key maps | ^---------------------^---------^--------^-----------------------------^ Elvis allows keystrokes to be mapped via the :map command. Once a map has been defined, these options control how and when those maps are recognized. The remap option controls how many times elvis will attempt to reapply key maps. If the remap option is true (the default), then elvis will repeatedly attempt to reapply maps as long as there are any that match. This means that maps can be written to use other maps, allowing some very complex behavior. If remap is false, then it will attempt to apply maps only once, so the result of any map is not altered any further. By default, remap is true. The keytime and usertime options come into play when characters are received which partially match one or more maps. For example, suppose the arrow keys are mapped to h, j, k, and l, those arrow keys send escape sequences when pressed, and elvis has just received an escape character. How can it tell whether the user hit the Esc key or an arrow key? In this situation, elvis must perform a read-keystrokes-with-timeout operation to determine which map applies, if any. If all of the partially matching maps are for special keys such as function keys, then elvis will use the keytime value. If at least one of them is for a user map, then elvis will use the usertime value. Either way, the values indicate the time, in tenths of a second, that elvis should allow for the rest of the map characters to arrive. If they don't arrive, then none of the partially matching maps is used. Typically, the usertime value will be much longer than the keytime value, because the user must hit a series of keys for a user map. For example, many people like to create maps consisting of a semicolon and one or two following letters. (If you're a touch typist, then your right-hand pinky normally rests on the semicolon key, so this is convenient.) By distinguishing between key maps and user maps, elvis can give quick response to the Esc while still allowing users to key in their own keymaps at a leisurely pace. Their default values are keytime=3 and usertime=15. 6.1.20 Printing options .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | lptype, lpt | String | lp | printer type | | lpconvert, lpcvt | Boolean | lp | convert Latin-1 to PC-8 | | lpcrlf, lpc | Boolean | lp | printer needs CR-LF newline | | lpout, lpo | String | lp | printer file or filter | | lpcolumns, lpcols | Number | lp | width of printer page | | lpwrap, lpw | Boolean | lp | simulate line-wrap | | lplines, lprows | Number | lp | length of printer page | | lpnumber, lpn | Boolean | lp | print line numbers in margin| | lpheader, lph | Boolean | lp | print header at top of page | | lpformfeed, lpff | Boolean | lp | send form-feed after last pg| | lppaper, lpp | String | lp | paper size (letter, a4, ...)| | lpcolor, lpcl | Boolean | lp | use colors when printing | ^---------------------^---------^--------^-----------------------------^ These options all affect hardcopy output, done via the :lpr command. Note that these options are in a separate group, so you can display all of them by giving the command "se lp?". The lptype option lets elvis know what type of printer you're using, so it can use the correct escape codes (or whatever) to switch fonts. The default is "dumb" because it is the most conservative value, but it is also the least expressive. (Exception: When using the Win32 user interface, the default is "windows".) You should set lptype to one of the following values: .---------.---------------------------------------------. | VALUE | PRINTER DESCRIPTION | |---------|---------------------------------------------| | ps | PostScript, one logical page per sheet | | ps2 | PostScript, two logical pages per sheet | | epson | Most dot-matrix printers, no graphic chars | | pana | Panasonic dot-matrix printers | | ibm | Dot-matrix printers with IBM graphic chars | | hp | HP printers, and most non-PostScript lasers | | cr | Line printers, overtypes via carriage-return| | bs | Overtypes via backspace, like nroff | | dumb | Plain ASCII, no font control | |-- --- --|-- --- --- --- --- --- --- --- --- --- --- --| | windows | The Win32 print facility (in WinElvis only) | ^---------^---------------------------------------------^ The lpconvert option, when set, causes some printer types to convert non-ASCII Latin-1 characters to PC-8 characters. Most computers use Latin-1 internally for storing text, but many printers use PC-8; hence the need for conversion. This option has no effect on ASCII characters because they never need conversion. This option is ignored if your computer doesn't appear to be using Latin-1 (or, more precisely, if there is no digraph which maps AE to 0xc6, the Latin-1 code for the ╞ ligature.) This option is false by default. NOTE: Not all printer types obey the lpconvert option. Postscript printers don't do conversion because they use Latin-1 themselves. The "cr", "bs", and "dumb" printer types ignore it simply because they are typically used for writing to files, not actual printers, and as long as the text remains in the computer no conversion is necessary. Only the "epson", "pana", "ibm", and "hp" printers will obey the lpconvert option. The lpcrlf option forces elvis to convert each newline character to a CR/LF pair. Some printers, on some systems, require this. Most don't, so this option is false by default. If you attempt to print something and only the first line is visible, or the text is badly jumbled, then try ":set lpcrlf" and maybe that'll fix it. The lpout option should be either the name of a file or device (such as "prn" or "/dev/lp0") to which the printer output should be sent, or ! character followed by a shell command (such as "!lp -s") which reads printer text from stdin and submits it to the printer spooler. The default is system dependent. The lpcolumns option tells elvis how wide the printer page is. The default is 80 columns. If you have a wide-carriage printer, you may wish to set lpcolumns=132. If you have a postscript printer and set lpcolumns to a value greater than 80, elvis will compress the characters to make the longer lines fit. The lpwrap option tells elvis how to handle lines that are wider than lpcolumns. If this options is true (the default) then long lines will wrap onto multiple printed lines. If lpwrap is false, then it will clip long lines. The lplines option tells elvis how long the usable portion of each page is; i.e., how many lines it should print on each page. The default is 60. Some display modes ("html" and "man") print headers at the top of each page; those lines are included in the lplines count. Setting lplines=0 causes elvis to assume that pages are infinitely long, which sounds about right for fan-fold printer paper. If you have a PostScript printer and set lplines to a value greater than 60, then the page will be compressed vertically to make it fit. The lpnumber option does to printouts what the number option does for a window -- it causes the line number to be output in the left margin. If the buffer's bufdisplay option is "normal" or "syntax", then it also causes a header to be printed at the top of each page, showing the file name, page number, and date/time when the printout was created. The lpheader option controls whether printouts will have a line at the top of each page showing the file name, date, and page number. It only affects the normal, syntax, and hex display modes; the others always have a header. The lpformfeed option controls whether elvis will send a form-feed control character after the last page of any print job. This should generally be false if you're printing through a print spooler program, because print spoolers usually add the final formfeed themselves. Under MS-DOS, elvis is normally configured to send the text directly to the printer device, prn, and you may wish to set the lpformfeed option there. The lppaper option is only significant for PostScript printers. The value of lppaper is inserted into the PostScript output before the contents of the elvis.ps file. elvis.ps contains code which scales the output to fit on the paper. The default version supports letter, legal, executive, a4 and a3 paper sizes. Adding new paper sizes to that file is fairly easy. You should be careful when setting lppaper because elvis won't prevent you from setting it to an unsupported value. The default value is letter. The lpcolor option is currently only supported for the "windows" printer type under Microsoft Windows95/98/NT. When true, it allows printouts to use color for the foreground. (The background is always white.) Normally it is false (nolpcolor), which forces all printouts to use black since that usually prints faster and looks better, and is always less expensive. 6.1.21 Previous arguments .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | previousdir, pdir | String | global | previous directory name | | previousfile | String | global | name of alternate file | | previousfileline | Number | global | line# from previousfile | | previouscommand | String | global | previous shell command line | | previoustag, ptag | String | global | previous search tag | ^---------------------^---------^--------^-----------------------------^ These options all store the previous value of some type of input, so that the same value can be used again later. You can set these options, but there really isn't much point to it, usually. The previousdir option stores the name of the previous working directory. Initially it is set from the value of the $OLDPWD environment variable. After that, each :cd command will store the old current working directory into this option before switching to the new working directory. If you give elvis a file name which begins with "~-", elvis will replace the "~-" with the value of this option. The previousfile option stores the name of an alternate file. Usually this is the name of the last file you mentioned, other than that of the current file. When you switch from one file to another, the name of the previous file is stored here, along with the line number (in previousfileline), so you can easily bounce between this file and the previous one. Whenever you type in a filename as an argument to an ex command, any instances of the # character are replaced by the value of previousfile. The previouscommand option stores the last shell command you typed in. When you enter the next shell command line, any instances of the ! character will be replaced by the value of previouscommand. The previoustag option stores the name of the last tag you looked up. This value is also stored on the tagstack in the hope that it may help you remember where you were when you performed all of your recent tag lookups. 6.1.22 Unsupported options .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | hardtabs, ht | Number | global | width of terminal's tabs | | mesg | Boolean | global | disable SysAdmin messages | | more, mo | Boolean | global | allow "Hit " prompt | | novice | Boolean | global | beginner mode | | redraw | Boolean | global | redraw screen during input | ^---------------------^---------^--------^-----------------------------^ The hardtabs, mesg, more, novice, and redraw options exist in elvis, but they don't do anything. Perhaps some day... 6.1.23 User variables .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | a | String | user | user variable | | b | String | user | user variable | | c | String | user | user variable | | d | String | user | user variable | | e | String | user | user variable | | f | String | user | user variable | | g | String | user | user variable | | h | String | user | user variable | | i | String | user | user variable | | j | String | user | user variable | | k | String | user | user variable | | l | String | user | user variable | | m | String | user | user variable | | n | String | user | user variable | | o | String | user | user variable | | p | String | user | user variable | | q | String | user | user variable | | r | String | user | user variable | | s | String | user | user variable | | t | String | user | user variable | | u | String | user | user variable | | v | String | user | user variable | | w | String | user | user variable | | x | String | user | user variable | | y | String | user | user variable | | z | String | user | user variable | ^---------------------^---------^--------^-----------------------------^ These one-letter options have no preset purpose. They are useful for holding temporary values which you expect to use in an expression later. These are all string values, but because the expression evaluator doesn't distinguish between a number and a string which happens to look like number, you can also use these as numbers. For example, the command... :let i=i+1 ...does exactly what you would expect. 6.2 Alphabetical list of options .---------------------.---------.--------.-----------------------------. | OPTION NAMES | TYPE | GROUP | DESCRIPTION | |---------------------|---------|--------|-----------------------------| | a | String | user | user variable | | altkey, metakey | One of | x11 | effect of the Alt key | | animation, anim | Number | global | animation macro speed | | anyerror, ae | Boolean | global | allow :errlist if readonly | | autoiconify, aic | Boolean | x11 | iconify old window | | autoindent, ai | Boolean | buf | auto-indent new text | | autoprint, ap | Boolean | global | print current line in ex | | autoselect, as | Boolean | global | visibly mark searched text | | autotab, at | Boolean | buf | allow autoindent to use '\t'| | autowrite, aw | Boolean | global | save file before switching | | b | String | user | user variable | | backup, bk | Boolean | global | make *.bak file before write| | beautify, bf | Boolean | global | strip ctrl chars from files | | bitsperchar, bits | Number | global | character size (always 8) | | blkcache, cache | Number | global | number of blocks in cache | | blkfill, bfill | Number | global | initial chars per text block| | blkgrow, bgr | Number | global | allocation table parameter | | blkhash, hash | Number | global | size of cache hash table | | blkhit, bh | Number | global | # of block requests in cache| | blkmiss, bm | Number | global | # of block req. not in cache| | blksize, bsz | Number | global | size of cache block | | boldstyle, bfn | String | windows| n or combination of b/i/u | | boldfont, xfb | String | x11 | name of bold font | | borderwidth, xbw | Number | x11 | size of text area's border | | bufchars, bc | Number | buf | number of characters | | bufdisplay, bd | String | buf | default display mode | | bufid, bufferid | Number | buf | ID number of user buffer | | buflines, bl | Number | buf | number of lines | | bufname, buffer | String | buf | name of buffer | | c | String | user | user variable | | ccprg, cp | String | buf | shell command for :cc | | codepage, cpg | Number | win32 | console character set | | columns, cols | Number | win | width of window | | commentfont, cfont | One-Of | syntax | font used for comments | | d | String | user | user variable | | dblclicktime, xdct | Number | x11 | double-click milliseconds | | defaultreadonly, dro| Boolean | global | assume all files readonly | | digraph, dig | Boolean | global | allow X-backspace-Y entry | | directory, dir | String | global | where to store temp files | | display, mode | String | win | name of current display mode| | e | String | user | user variable | | edcompatible, ed | Boolean | global | remember regsub flags | | edited, samename | Boolean | buf | buffer loaded from filename | | elvispath, epath | String | global | list of possible config dirs| | emphasizedstyle, efn| String | windows| n or combination of b/i/u | | equalprg, ep | String | buf | shell command for = operator| | errlines | Number | buf | buflines when :make was run | | errorbells, eb | Boolean | global | ring bell for error message | | exitcode, exit | Number | global | exit code of elvis process | | completebinary, cob | Boolean | global | complete names of binaries? | | exrc, ex | Boolean | global | interpret ./.exrc file | | exrefresh, er | Boolean | global | redraw scrn after each line | | f | String | user | user variable | | filename, file | String | buf | name of file in buffer | | firstx, xpos | Number | x11 | horiz. position of first win| | firsty, ypos | Number | x11 | vert. position of first win | | fixedstyle, ffn | String | windows| n or combination of b/i/u | | flash, vbell | Boolean | global | substitute flash for bell | | focusnew, fn | Boolean | x11 | force focus into new window | | font, fnt | String | windows| base font | | functionfont, ffont | One-Of | syntax | font used for function names| | g | String | user | user variable | | gdefault, gd | Boolean | global | default change all instances| | gui | String | global | name of user interface | | h | String | user | user variable | | hardtabs, ht | Number | global | width of terminal's tabs | | home | String | global | home directory | | i | String | user | user variable | | icon | Boolean | x11 | use the built-in icon? | | ignorecase, ic | Boolean | global | regexp uppercase=lowercase | | initialstate, is | One-Of | global | command mode of new windows | | inputtab, itab | One-Of | buf | input mode's (Tab) key | | internal | Boolean | buf | elvis requires this buffer | | italicstyle, ifn | String | windows| n or combination of b/i/u | | italicfont, xfi | String | x11 | name of italic font | | j | String | user | user variable | | k | String | user | user variable | | keytime, kt | Number | global | timeout for function keys | | keywordfont, kfont | One-Of | syntax | font used for reserved words| | keywordprg, kp | String | buf | shell command for K command | | l | String | user | user variable | | lines, rows | Number | win | height of window | | list, li | Boolean | win | show markups, newlines, etc.| | locked, lock | Boolean | win | prevent any alterations | | lpcolor, lpcl | Boolean | lp | use colors when printing | | lpcolumns, lpcols | Number | lp | width of printer page | | lpcrlf, lpc | Boolean | lp | printer needs CR-LF newline | | lpformfeed, lpff | Boolean | lp | send form-feed after last pg| | lpheader, lph | Boolean | lp | print header at top of page | | lplines, lprows | Number | lp | length of printer page | | lpnumber, lpn | Boolean | lp | print line numbers in margin| | lpout, lpo | String | lp | printer file or filter | | lppaper, lpp | String | lp | paper size (letter, a4, ...)| | lptype, lpt | String | lp | printer type | | lpwrap, lpw | Boolean | lp | simulate line-wrap | | m | String | user | user variable | | magic, ma | Boolean | global | use normal regexp syntax | | makeprg, mp | String | buf | shell command for :make | | maplog, mlog | One of | global | logging: off, reset, append | | maptrace, mt | One of | global | debugger: off, run, or step | | mesg | Boolean | global | disable SysAdmin messages | | modeline, ml | Boolean | global | interpret modelines | | modelines, mls | Number | global | positions of modelines | | modified, mod | Boolean | buf | buffer differs from file | | n | String | user | user variable | | nearscroll, ns | Number | global | scroll vs. jump¢er param| | newfile, new | Boolean | buf | filename doesn't exist yet | | newsession, newses | Boolean | global | session file is new | | nonascii, asc | One-Of | global | how to display non-ascii | | normalstyle, nfn | String | windows| n or combination of b/i/u | | normalfont, xfn | String | x11 | name of normal font | | novice | Boolean | global | beginner mode | | number, nu | Boolean | win | display line numbers | | o | String | user | user variable | | optimize, opt | Boolean | global | run faster | | optionwidth, ow | Number | global | widths of ":set all" values | | os | String | global | name of operating system | | otherfont, ofont | One-Of | syntax | font used for other symbols | | outlinemono, om | Number | x11 | char outlining for X11-mono | | p | String | user | user variable | | paragraphs, para | String | buf | nroff paragraph commands | | partiallastline, pll| Boolean | buf | file didn't end with newline| | pollfrequency, pf | Number | global | rate of testing for ^C | | prepfont, pfont | One-Of | syntax | font used for preprocessor | | previouscommand | String | global | previous shell command line | | previousdir, pdir | String | global | previous directory name | | previousfile | String | global | name of alternate file | | previousfileline | Number | global | line# from previousfile | | previoustag, ptag | String | global | previous search tag | | program, argv0 | String | global | invocation name of elvis | | prompt | Boolean | global | issue ":" prompt in ex mode | | putstyle, ps | One of | buf | type of text in a cut buffer| | q | String | user | user variable | | r | String | user | user variable | | readeol, reol | One of | buf | newline mode when reading | | readonly, ro | Boolean | buf | don't overwrite filename | | recovering, rflag | Boolean | global | recovering after a crash | | redraw | Boolean | global | redraw screen during input | | remap | Boolean | global | allow key maps to use maps | | report | Number | global | minimum # lines to report | | retain, ret | Boolean | buf | keep buffer in session file | | ruler, ru | Boolean | win | display cursor's line/column| | s | String | user | user variable | | safer, trapunsafe | Boolean | global | be paranoid | | saveregexp, sre | Boolean | global | remember regexp to use as //| | scroll, scr | Number | win | scroll amount for ^D/^U | | scrollbar, sb | Boolean | (gui) | enable the scrollbar | | scrollbarleft, xsl | Boolean | x11 | draw scrollbar on left side | | scrollbartime, xst | Number | x11 | delay for scrollbar repeat | | scrollbarwidth, xsw | Number | x11 | size of scrollbar, in pixels| | sections, sect | String | buf | nroff section commands | | sentenceend, se | String | global | punct at end of sentence | | sentencegap, sg | Number | global | spaces required after sq | | sentencequote, sq | String | global | punct allowed after se | | session, ses | String | global | name of session file | | sessionpath, spath | String | global | list of possible session dir| | shell, sh | String | global | name of shell program | | shiftwidth, sw | Number | buf | width used by < and > | | showcmd, sc | Boolean | win | display command characters | | showmarkups, smu | Boolean | global | show markup at cursor | | showmatch, sm | Boolean | win | highlight matching parens | | showmode, smd | Boolean | win | display the command state | | showname, snm | Boolean | global | display the buffer name | | showstack, sstk | Boolean | win | display some debugging info | | showtag, st | Boolean | global | display tag on status line | | sidescroll, ss | Number | win | sideways scrolling amount | | stagger | Number | x11 | offset for next new window | | statusbar, xstat | Boolean | x11 | enables the statusbar | | stringfont, sfont | One-Of | syntax | font used for strings | | sync | Boolean | global | force changes to disk | | t | String | user | user variable | | tabstop, ts | Number | buf | width of tabstop columns | | taglength, tl | Number | global | significant length of tags | | tagprg, tp | String | global | external tag search program | | tagprgonce, tpo | String | global | like tagprg, but auto-resets| | tags, tagpath | String | global | list of possible tag files | | tagstack, tsk | Boolean | global | remember origin of tag srch | | tempsession, temp | Boolean | global | delete session file on exit | | term, ttytype | String | tcap | terminal's termcap entry | | terse, te | Boolean | global | don't translate messages | | textcursor, tc | Number | x11 | one of hollow, opaque, xor | | textwidth, tw | Number | buf | width for word-wrap, or 0 | | toolbar, tb | Boolean | (gui) | enable the toolbar | | ttycolumns, ttycols | Number | tcap | width of screen | | ttyrows, ttylines | Number | tcap | height of screen | | ttyunderline, ttyu | Boolean | tcap | okay to mix color & underln | | u | String | user | user variable | | underline, uln | Boolean | x11 | enables underlining | | underlinedstyle, nfn| String | windows| n or combination of b/i/u | | undolevels, ul | Number | buf | number of undoable commands | | usertime, ut | Number | global | timeout for multi-key maps | | v | String | user | user variable | | variablefont, vfont | One-Of | syntax | font used for variables | | verbose | Boolean | global | give more status messages | | w | String | user | user variable | | warn | Boolean | global | warn if file not saved | | warningbells, wb | Boolean | global | ring bell for warning msg | | warpback, xwb | Boolean | x11 | upon exit, point to xterm | | warpto, wt | One of | x11 | ^W^W forces pointer movement| | window, wi | Number | global | lines to show for :z command| | windowid, id | Number | win | ID number of current window | | wrap | Boolean | win | how long lines are displayed| | wrapmargin, wm | Boolean | win | set textwidth from right | | wrapscan, ws | Boolean | global | searching wraps at EOF<->BOF| | writeany, wa | Boolean | global | don't warn of existing file | | writeeol, weol | One of | buf | newline mode when writing | | x | String | user | user variable | | xcolumns, xcols | Number | x11 | width of new windows | | xrows, xlines | Number | x11 | height of new windows | | y | String | user | user variable | | z | String | user | user variable | ^---------------------^---------^--------^-----------------------------^ ═══ 1.7. Elvis 2.1 Display Modes ═══ 7. DISPLAY MODES A "display mode" consists primarily of an algorithm that elvis uses internally to convert the bytes in a buffer into an image in a window. The same algorithm is also used for printing via the ":lpr" command. The display mode also affects tag lookup, and image-dependent operations such as determining the column number of the cursor's location, and moving the cursor vertically. You can list the supported display modes by giving the ":display" command without any arguments. Typically, the supported modes will include the following: .--------.----------------------------------------------. | MODE | DESCRIPTION | |--------|----------------------------------------------| | normal | Traditional vi, displays plain ASCII | | syntax | Like "normal" but does syntax coloring | | hex | Interactive hex dump, good for binary files | | html | Simple Web page formatter | | man | Simple Man page formatter, like "nroff -man" | | tex | Simple subset of the TeX formatter | ^--------^----------------------------------------------^ Elvis 2.1 allows each window to be in a different display mode. You can manually change a window's display mode via the ":display mode" command, where mode is the name of a supported display mode. There is also a ":no" command, which is short for ":display normal". 7.1 Options There are two options which pertain to display modes: display and bufdisplay. The display option is associated with a window. It always contains the name of the window's current display mode. You aren't allowed to change the value of this option directly; you must use the ":display mode" command to change the display mode. This option exists solely so that you can write EX scripts which behave differently, depending on the display mode. The bufdisplay option is associated with a buffer. It should be set to the name of the usual display mode for that buffer. Typically this option will be set from the elvis.arf initialization file, based on the name of the file like this: let e=tolower(dirext(filename)) if knownsyntax(filename) then set! bufdisplay=syntax else if os=="unix" && buflines >= 1 then 1s/^#! *[^ ]*\/\([^ ]\+\).*/set! bufdisplay="syntax \1"/x if e<<4==".htm" then set! bufdisplay=html if e==".man" || e==".1" then set! bufdisplay=man if binary then set! bufdisplay=hex When a new window is created for that buffer, or an existing window switches to that buffer, that window's display mode will automatically be switched to the bufdisplay mode. The bufdisplay mode also affects the ^Wd visual command. This command toggles the window between the normal mode and the bufdisplay mode. If bufdisplay is also set to "normal", then ^Wd will toggle between the normal and hex display modes. 7.2 Normal mode The "normal" display mode looks like a traditional vi screen. All characters are displayed literally except for the following... Tab The tab character is displayed as a variable number of spaces -- however many are needed to move to the next tabstop position. Newline The newline character (linefeed) marks the end of a line. Other control characters Control characters other than tab and newline are displayed as a caret and a printable ASCII character. For example Control-A is displayed as ^A, and NUL is displayed as ^@. The delete character is displayed as ^?. Non-ASCII characters The appearance of non-ASCII characters (i.e., characters 128-255) is controlled by the nonascii option. By default, most non-ASCII characters are assumed to be ordinary printable characters. 7.3 Syntax mode The "syntax" display mode acts exactly like the normal mode, except that this mode automatically uses different fonts for various types of tokens in any supported programming language. You can then use the :color command to assign colors for each font. 7.3.1 Options The following options determine which font is used for each type of token: .---------------------.----------^-------------------------------------. | OPTION NAMES | DEFAULT | AFFECTED TOKEN TYPE | |---------------------|----------^-------------------------------------| | commentfont, cfont | italic | comments | | stringfont, sfont | fixed | string, character, & regexp literals| | prepfont, pfont |emphasized| preprocessor directives | | keywordfont, kfont | bold | keywords | | functionfont, ffont | normal | identifier followed by function char| | otherfont, ofont | bold | other special words | | variablefont, vfont | normal | variables, fields, etc. | ^---------------------^----------^-------------------------------------^ Each of those options can be set to one of normal, bold, italic, underlined, emphasized, or fixed. When typing these values into a :set command line, you are only required to type the initial letter (n, b, i, u, e or f). Any text that doesn't fall into one of the above groups (punctuation, mostly) is displayed in the normal font. There is no option that controls this; it is hard coded. You can use the :color command to choose a color for each font, if you wish. Not all user interfaces support color, but the "x11" and "termcap" interfaces do. 7.3.2 Language specification All supported languages are described in a file named "elvis.syn". Each time a window switches to the "syntax" display mode, elvis scans this file for a description of the language. If it can't find a description of the language, then nothing will be displayed in a different font; "syntax" mode will look exactly like "normal" mode. The "elvis.syn" file is a text file. In it, blank lines and lines which start with a '#' are ignored. Other lines begin with the name of an attribute; the remaining words in the line are values for that attribute. Each language's description begins with an attribute named "language". The following lines (up to the next "language" line or the end of the file) describe that language. The attributes names are: language This word is followed by a whitespace-delimited list of language names. The names are case-sensitive, so you should probably give all names in lowercase so they're easier for the user to type in. The user can indicate which language to use by appending its name to the name of the "syntax" display mode. For example, ":display syntax c++" causes elvis to highlight the text appropriately for C++. extension This word is followed by the filename extensions which are commonly used for this language. If the user doesn't specify which language to load, then elvis scans through "elvis.syn" for an extension line which matches the current file name. The extension lines must come immediately after the language line. NOTE: This is case sensitive! If the file name extension will often be used on case-insensitive file systems (e.g., most Microsoft) then you'll probably want to give both uppercase and lowercase versions of the extension. For example, the description of Microsoft batch file syntax includes "extension .bat .BAT". keyword This word is followed by a list of words which should be shown in the keywordfont font. If omitted, then no words are shown in the keywordfont. Long lists can be split into several keyword lines, if you wish. Elvis doesn't care about the order of the words, but the list will be easier to maintain if you keep it alphabetized. Elvis supports three forms of keywords...  Most keywords begin with an alphanumeric character or a character in the startword list, and continue with zero or more characters which are alphanumeric or in the inword list.  The same startword/inword type of keywords can be made somewhat context sensitive by appending a single character which does not appear in the inword. The keyword will only be recognized when it is immediately followed by that character. The HTML syntax highlighting uses this feature to display parameters in a distinctive font.  Rarely, you may find it convenient to have keywords which consist of one or two punctuation characters, but which don't match the first form of keywords. This is mostly so that Perl's $# variable won't be displayed as a simple dollar sign followed by a comment. You can list the same keyword in multiple lines (once each in a keyword line, a font line, an anchor line, and a comment line) to specify the various attributes of each keyword. You don't need to list it in a keyword line first; you can introduce new keywords in any of these four line types. font This word can be used to cause certain keywords to be displayed in some font other than the keywordfont. The first word after font should be the name of the font (normal, fixed, bold, emphasized, italic, or underlined) or a one-letter abbreviation of a font name. The line's remaining words are keywords which will be displayed in that font. anchor This offers a way to restrict certain keywords, so they will only be recognized as such if they occur in a particular column. The first word after "anchor" is a column number -- 1 for the leftmost column, 9 for the first tabstop, and so on. You can also use ^ instead of a number to indicate that the keyword can only appear after whitespace at the front of a line. The remainder of the "anchor" line is the list of keywords which are only special when they occur in that column. comment This word is followed by a keyword which marks the beginning of a comment. The comment is assumed to end at the end of the line. Comments are normally shown in the commentfont font, but if you've overridden the keyword's font via a font line in elvis.syn, then the whole comment will be displayed in that font instead. You can define multiple comment keywords, and assign different fonts to them if you wish. The comment word can also be followed by a pair of one- or two-character sequences which mark the beginning and end of comments which can include newlines. Elvis only supports one multi-line comment style for each language, and it will always be displayed in the commentfont font. operator This word is followed by a keyword which the language uses as a prefix for operators, and then by a list of characters which can appear in the operator itself. This affects the ^] visual command for tag searches. As far as I know, the only language that uses this is C++, where it is specified like this: operator operator ~!%^&*+|-=[]<>/ preprocessor This word is followed by a single character which, when used at the beginning of a line, marks the start of a preprocessor directive. For C, this is the # character. All preprocessor directives will then be shown in the prepfont font. If omitted, nothing is displayed in the prepfont. prepquote This word is followed by a single character, or a pair of single characters, which are used as the quote characters surrounding a file name in a preprocessor directive. For C, this is the < and > characters. The name of the included file will then be displayed using the stringfont font. If omitted, then preprocessor file names will be highlighted as though they were arithmetic expressions. function This word is followed by a single character which, if it appears after a word, indicates that the word should be displayed in the functionfont font. For most languages, this will be a ( character. If omitted, nothing is displayed in the functionfont. startword inword These can be followed by a list of punctuation characters which may appear at the start of a word, or in the remainder of the word, respectively. Letters and digits are always legal in words; you don't need to list them. other This word indicates which types of words should be displayed in the otherfont font. If omitted, nothing is displayed in the otherfont. It can be any combination of the following symbols: .-------------.-------------------------------------------------. | SYMBOL | HOW TO RECOGNIZE "OTHER" WORDS | |-------------|-------------------------------------------------| | allcaps | length >= 2 chars, no lowercase characters | | initialcaps | 1st character is uppercase, some are lowercase | | initialpunct| 1st character is punctuation, from "startword" | | mixedcaps | 1st character is lowercase, some are uppercase | | final_t | length >= 3 chars, ends with "_t" | ^-------------^-------------------------------------------------^ string This word is followed by a single character, or a pair of single characters, which are used as the quote characters surrounding string literals. For C, this is the " character. String literals will then be displayed using the stringfont font. If omitted, then strings will not be recognized. strnewline This is followed by backslash, allowed, indent, or empty to indicate how strings can be continued across lines. The default is backslash which indicates a C-style backslash is required to quote the newline characters (which C will then exclude from the string, but elvis doesn't care about that). The other values all indicate that a backslash is not needed, and also give some hints that help elvis detect whether the top of the screen is inside a multi-line string. Specifically, the indent value means that indented lines are rarely a continuation of a string, empty means that empty lines are probably not part of a string, and allowed makes no promises. The allowed value would be too slow if strings' opening and closing quotes are identical (e.g., if the " character appears at both ends of a string); in this situation, elvis uses empty instead. Note that the hints are only used for detecting whether the first line starts in a multi-line string. When drawing text after that, elvis treats all non-backslash values identically. character This word is followed by a single character, or a pair of single characters, which are used as the quote characters surrounding character literals. For C, this is the ' character. This is shown using the stringfont font, like strings. When parsing, the only difference between the two is that characters can't span lines, but strings can. regexp This word is followed by a list of characters which can be used for delimiting a regular expression, which some languages support as a means for specifying strings with metacharacters. (See Section 5 of this manual for a description of elvis' own implementation of regular expressions, which is a typical example.) Regular expressions are displayed using the stringfont font. Note that regexp accepts a list of characters, while string and character support only a single character. This is because many programming languages allow the programmer to choose from a variety of delimiting characters. useregexp The most commonly used delimiter for regular expressions is '/', which many languages also use as the division operator. To avoid mistakenly displaying the division operator as the start of a regular expression, elvis must be sensitive to the context in which it is used. That's what this word is for. The useregexp word is followed by a list of keywords and/or punctuation characters which allow the next character to be recognized as a regular expression. Additionally, regular expressions are allowed at the start of a line. useregsub This is used for listing keywords and punctuation characters which may be followed by a regular expression and then substitution text. ignorecase This word should be followed by true or false. If true, then elvis won't distinguish between uppercase and lowercase letters when testing whether a word is a keyword (except that in the elvis.syn file, the keywords should be listed in lowercase). If omitted, elvis assumes it should be false. 7.3.3 Example The elvis.syn file shipped with elvis contains some good examples of language descriptions. Here's an excerpt from it, describing the Java language. language java extension .java .jav keyword abstract boolean break byte byvalue case cast catch char keyword class const continue default do double else extends false keyword final finally float for future generic goto if implements keyword import inner instanceof int interface long native new null keyword operator outer package private protected public rest return keyword short static super switch synchronized this throw throws keyword transient true try var void volatile while comment // comment /* */ function ( string " character ' startword _ inword _ other allcaps initialcaps There is no preprocessor line, because java doesn't use a preprocessor. The "allcaps" and "initialcaps" symbols are given so that constants and class names will be shown in the otherfont. 7.4 Hex mode The "hex" display mode is an interactive hex dump of the buffer. This is good for examining or editing binary files. One handy feature is the ability to enter characters in hex (either in input mode or as the argument to an r visual command) by typing ^X followed by two hex digits. This feature is always available regardless of the display mode... but this is where is it most useful. 7.5 HTML mode HTML is the language used for constructing pages on the World Wide Web. Elvis' "html" display mode supports a subset of HTML, which it uses for displaying the online help documentation (including this very document). HTML is a markup language. This means that documents contain a mixture of text and formatting instructions. In HTML there are two types of instructions, called tags and entities. When the document is processed by a program such as Netscape or elvis (in html mode), the tags are stripped out, the entities are converted to a kind of text, and the text is formatted and presented to the user. Ordinarily the user will never see the tags. Since elvis is primarily an editor, not a viewer, it has two options which allow the tags to become visible: the showmarkups option causes a tag to become visible if the cursor is moved onto it, and the list option makes all tags visible regardless of the cursor position. There are a lot of good "How To Use HTML" documents on the Net. This is not one of them! I don't intend to do much more than describe the quirks of elvis' implementation of HTML here. I added HTML support to elvis mostly to support the online help. Consequently, if a feature is hard to implement and the online documentation doesn't use it, then I didn't implement that feature. If you intend to use elvis as a browser, then I suggest you read the approriate section in the Tip chapter. 7.5.1 Formatting tags Elvis supports the following HTML tags. Unsupported tags are silently ignored. Newline characters aren't supported within tags; each tag must fit on a single line. ... The entire document should be enclosed in these tags. They don't actually do anything to help format the document, but they may help programs recognize that the document is, in fact, written in HTML. ... These should be used to bracket the document's header, if it has one. ... These tags are only legal in the document's header. Any text between the and tags will be stored internally as the title of the document. If you print the document, elvis will display the title at the top of each page. ... These should be used to bracket the body of the document. They don't actually do anything in elvis, but real Web browsers such as Netscape allow you to specify backgrounds and patterns via BGCOLOR=... and BACKGROUND=... arguments, respectively.

...

These tags bracket the most visible type of section header. Elvis displays

...

headers in boldface, flush against the left edge of the page. When printing, these headers cause a page break.

...

These bracket the second most visible type of section header. Elvis displays

...

headers in boldface, indented slightly from the left edge. When printing, these may cause a page break if they would otherwise appear near the bottom of a page.

...

These bracket the third most visible type of section header. Elvis displays them in boldface, indented fully from the left edge so that it lines up with normal text.

...

...
...
These are very minor section headers. Conventional wisdom says that if you're using this many section headers then you would probably do better to split your document into several smaller documents. Elvis displays these headers in an italic font.

This tag should be placed at the start of each normal paragraph, with the possible exception of the first paragraph after a section header. It causes a blank line to be generated, and any later text to appear starting on a new line.
This causes any later text to appear starting on a new line. It differs from

in that
doesn't output a blank line.

This outputs a "horizontal rule" -- a line all the way across the page. ... Elvis can't display graphics, but if it encounters an tag which has an alternate text form (as denoted by an img="text" parameter) then it'll display the alternate text. Otherwise elvis will display "src" URL. Also, if the image isn't already part of a hypertext link, then elvis will treat it as a link to the image's binary data; this offers you a way to fetch images, even though elvis can't display them. The supported URL formats are described in the discussion of the tag, below. Elvis can't display frames either, but it will display the frame's name, and treat that name as a hypertext link to the frame's document. This offers a simple work-around for elvis' lack of real frame support. The supported URL formats are described in the discussion of the tag, below.
...
This is used to mark a large chunk text which is quoted from another source. Elvis will indent the enclosed text. 
 ...
This brackets text which has already been preformatted by the document's author. Elvis will treat tabs and newlines literally. (Outside of 
 ...
, they would normally be treated like spaces.) This has been used for presenting tables, poetry, and source code examples. In fact, elvis has an extension that is useful for tables: If you start with 
 then elvis will convert certain characters 
           into graphic line-drawing characters. When adjacent to a hyphen 
           character, the hyphen, period, caret are converted into appropriate 
           graphic characters. Additionally, the vertical bar character is 
           always converted to a graphic character. The following was done with 
           a plain 
... 

                      .--.--.
                      |--|--|
                      |  |  |
                      ^--^--^
           ... and this was done with 
... 

                      .--.--.
                      |--|--|
                      |  |  |
                      ^--^--^

 ...
 
 ... 
 ... 
 ... 
           These are used for implementing tables in HTML 3.0. Each table 
           should be enclosed in a ...
 pair. Within the table, 
           each row should be delimited with a ... pair. Within each 
           row, the information for each column should be enclosed in either a 
           ... pair for headers, or a ... pair for data. 

           Elvis doesn't really support these tags very well. Only the bare 
           essentials of these commands have been implemented. They are 
           intended to make tables recognizable as being tables, but not 
           necessarily make them easy to read. 
 ... 
 ... 
           These are treated almost exactly like 
 ... 
. There are 
           supposed to be some differences, but elvis doesn't support those 
           differences. 
 
 ... 
 
           These are used to bracket a list of definitions. The definitions 
           themselves are marked with the 
 and 
 tags, described below. 
 
 
           The text after this tag is used as a term to be defined. Elvis 
           displays this text in bold face, indented by the same amount as 
           normal text. This is only legal in a 
...
 pair. 
 
 
           The text after this tag is used as the definition of a term. Elvis 
           displays it in the normal font, indented somewhat more than normal 
           text or the 
 text. This is only legal in a 
...
 pair. 
 
     ... 
 
           These are used to enclose an ordered list. The official 
           specifications say that lists may be nested inside one another, but 
           elvis doesn't allow ordered lists to appear inside any other type of 
           list. If a document uses 
     ... 
 inside another list, then 
           elvis will act as though  
     ... 
 had been used instead. This 
           means that the list items will be marked with bullets instead of 
           numbers. Within the list, 
  •  tags are used to mark the items. 
 
       ... 
     
           These enclose an unordered list. Each item in the list should be 
           marked with a 
  •  tag. 
  ...  
           These enclose an unordered list, like 
       ... 
    , but other Web 
           browsers may display  ...  lists in a more compact 
           manner. 
 
  •  
           This is used to mark the start of a new item in a list.