Source Code 1992 March

home *** CD-ROM | disk | FTP | other *** search

/ Source Code 1992 March / Source_Code_CD-ROM_Walnut_Creek_March_1992.iso / usenet / altsrcs / 1 / 1706 / elvis.man

Wrap

Text File | 1990-12-28 | 87.1 KB | 2,707 lines

_I_n_t_r_o_d_u_c_t_i_o_n 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 colon mode. 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. Elvis runs under BSD UNIX, AT&T SysV UNIX, Minix, MS-DOS, and Atari TOS. Ports to other operating systems are being worked on; contact me before you start porting it to some other OS, because somebody else may have already done it for you. Elvis is freely redistributable, in either source form or executable form. _O_v_e_r_v_i_e_w _o_f _E_l_v_i_s The user interface of elvis/vi/ex is weird. There are two major comand 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 _v_i_s_u_a_l _c_o_m_m_a_n_d _m_o_d_e 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 interpretted as part of a visual command. If you start typing text, it will _n_o_t be inserted, it will be treated as part of a command. To insert text, you must first give an "insert text" command. This will take some getting used to. (An alternative exists. Lookup the "inputmode" option.) The _c_o_l_o_n _m_o_d_e 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 <Return> key. The set of commands recognized in the colon mode is different from visual mode's. - 1 - _V_i_s_u_a_l _M_o_d_e _C_o_m_m_a_n_d_s Most visual mode commands are one keystroke long. The following table lists the operation performed by each keystroke, and also denotes any options or arguments that it accepts. Notes at the end of the table describe the notation used in this table. In addition to the keys listed here, your keyboard's "arrow" keys will be interpretted as the appropriate cursor movement commands. The same goes for <PgUp> and <PgDn>, if your keyboard has them. There is a colon mode command (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. command description type ---------------+-------------------------------------------------------+-------- ^A --- ^B Move toward the top of the file by 1 screenful ^C --- count ^D scroll down <count> lines (default 1/2 screen) count ^E scroll up <count> lines ^F move toward the bottom of the file by 1 screenful ^G show file status, and the current line # count ^H move left, like h MOVE ^I --- count ^J move down MOVE ^K --- ^L redraw the screen count ^M move to the front of the next line MOVE count ^N move down MOVE ^O --- count ^P move up MOVE ^Q --- ^R redraw the screen ^S --- ^T --- count ^U scroll up <count> lines (default 1/2 screen) ^V --- ^W --- ^X --- count ^Y scroll down <count> lines ^Z --- ESC --- ^\ --- ^] if the cursor is on a tag name, go to that tag ^^ --- ^_ --- count SPC move right,like l MOVE ! mv run the selected lines thru an external filter program " key select which cut buffer to use next - 2 - count # + increment a number EDIT $ move to the rear of the current line MOVE % move to the matching (){}[] character MOVE & --- ' key move to a marked line MOVE count ( move backward <count> sentences MOVE count ) move forward <count> sentences MOVE * --- count + move to the front of the next line MOVE count , repeat the previous [fFtT] but in the other direction MOVE count - move to the front of the preceding line MOVE count . repeat the previous "edit" command / text search forward for a given regular expression MOVE 0 if not part of count, move to 1st char of this line MOVE 1 part of count 2 part of count 3 part of count 4 part of count 5 part of count 6 part of count 7 part of count 8 part of count 9 part of count : text run single EX cmd count ; repeat the previous [fFtT] cmd MOVE < mv shift text left EDIT = --- > mv shift text right EDIT ? text search backward for a given regular expression MOVE @ --- count A inp append at end of the line EDIT count B move back Word MOVE C inp change text from the cursor through the end of the line EDIT D delete text from the cursor through the end of the line EDIT count E move end of Word MOVE count F key move leftward to a given character MOVE count G move to line #<count> (default is the bottom line) MOVE 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) EDIT count J join lines, to form one big line EDIT K look up keyword count L move to last row (the line at the bottom of the screen) M move to middle row N repeat previous search, but in the opposite direction MOVE count O inp open up a new line above the current line EDIT P paste text before the cursor Q quit to EX mode R inp overtype EDIT count S inp change lines, like <count>cc count T key move leftward *almost* to a given character MOVE U Undo all recent changes to the current line V --- count W move forward <count> Words MOVE count X delete the character(s) to the left of the cursor EDIT count Y yank text line(s) (copy them into a cut buffer) Z Z save the file & exit - 3 - [ [ move back 1 section MOVE \ --- ] ] move forward 1 section MOVE ^ move to the front of the current line (after indent) MOVE _ --- ` key move to a marked character MOVE count a inp insert text after the cursor EDIT count b move back <count> words MOVE c mv change text EDIT d mv delete text EDIT count e move forward to the end of the current word MOVE count f key move rightward to a given character MOVE g --- count h move left MOVE count i inp insert text at the cursor EDIT count j move down MOVE count k move up MOVE count l move right MOVE m key mark a line or character n repeat the previous search MOVE count o inp open a new line below the current line EDIT p paste text after the cursor q --- count r key replace <count> chars by a given character EDIT count s inp replace <count> chars with text from the user EDIT count t key move rightward *almost* to a given character MOVE u undo the previous edit command v --- count w move forward <count> words MOVE count x delete the character that the cursor's on EDIT y mv yank text (copy it into a cut buffer) z key scroll current line to the screen's +=top -=bottom .=middle count { move back <count> paragraphs MOVE count | move to column <count> (the leftmost column is 1) count } move forward <count> paragraphs MOVE ~ switch a character between uppercase & lowercase EDIT DEL --- -------------------------------------------------------------------------------- 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. 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 Six commands (! < > c d y) operate on text between the cursor and some other position. To specify that other position, you are expected to follow the command keystroke with a movement command. Also, you may have the command operate on the whole line that the cursor is on by typing the command key a second time. inp Many commands allow the user to interactively enter text. - 4 - EDIT These commands affect text, and may be repeated by the "." command. MOVE These commands move the cursor, and may be used to specify the extent of a member of the "mv" class of commands. _I_n_p_u_t _M_o_d_e 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/s. The S/s/C/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: ^A insert a copy of the last input text ^D delete one indent character ^H (backspace) erase the character before the cursor ^L redraw the screen ^M (carriage return) insert a newline (^J, linefeed) ^P insert the contents of the cut buffer ^R redraw the screen, 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 ^Z ^Z write the file & exit elvis ^[ (ESCape) exit from input mode, back to command mode Also, on some systems, ^S may stop output, ^Q may restart output, and ^C may interupt execution. ^@ (the NUL character) cannot be inserted. 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. _A_r_r_o_w _k_e_y_s _i_n _I_n_p_u_t _M_o_d_e 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 best thing about allowing arrow keys to work in input mode is that as long as you're in input mode, Elvis seems to have a fairly ordinary user interface. With most other text editors, you are always in either insert mode or replace mode, and you can use the arrow keys at any time to move the cursor. Now, Elvis can act like that, too. In fact, with the new "inputmode" option and the "control-Z control-Z" input command, you may never have to go into visual command mode for simple edit sessions. - 5 - _D_i_g_r_a_p_h_s Elvis supports digraphs as a way to enter non-ASCII characters. A digraph is a character which is composed of two other characters. For Elvis, the first character must be an ASCII punctuation character, and the second can be any other ASCII character. For example, an apostrophe and the letter i could be defined as a digraph which is to be stored & displayed as an accented i. Elvis has no built-in digraphs, since there is no single standard for extended ASCII character sets. You must explicitly define a custom set of digraphs for the non-ASCII characters that your computer (or terminal) uses. Digraphs are defined via the ":digraph" command. To actually use a digraph, you must first be in input mode. Type the punctuation character, then hit <Backspace>, and then type the other character. Elvis will then substitute the non-ASCII character in their place. - 6 - _C_o_l_o_n _M_o_d_e _C_o_m_m_a_n_d_s To use colon mode commands, you must switch from visual command mode to colon command mode. The visual mode commands to do this are ":" for a single colon command, or "Q" for many colon mode commands. Lines command arguments ---------------+---------------+------------------------------- [line] append args [files] cd [directory] chdir [directory] [line][,line] change [line][,line] copy line [line][,line] debug[!] [line][,line] delete ["x] digraph[!] [XX [Y]] edit[!] [file] ex[!] [file] file [line][,line] global /regexp/ command [line] insert [line][,line] join [line][,line] list map[!] key mapped_to [line] mark x mkexrc [line][,line] move line next[!] [files] Next[!] previous[!] [line][,line] print [line] put ["x] quit[!] [line] read file rewind[!] set [options] source file [line][,line] substitute /regexp/replacement/[p][g] tag[!] tagname [line][,line] to line undo unmap[!] key validate[!] version [line][,line] vglobal /regexp/ command visual wq [line][,line] write[!] [[>>]file] xit[!] [line][,line] yank ["x] [line][,line] ! command [line][,line] < [line][,line] = [line][,line] > - 7 - _L_i_n_e _S_p_e_c_i_f_i_e_r_s Line specifiers are always optional. The first line specifer of most commands usually defaults to the current line. The second line specifer usually defaults to be the same as the first line specifier. Exceptions are :write, :global, and :vglobal, which act on all lines of the file by default, and :!, which acts on no lines by default. Line specifiers consist of an absolute part and a relative part. The absolute part of a line specifer 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 colon 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 specifer 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 equivelent to saying 1,$. This can be a handy shortcut. Some examples: :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 file :20,30p print lines 20 through 30 :1,$p print all lines of the file :%p print all lines of the file :/foo/-2,+4p print 5 lines around the next "foo" - 8 - _T_e_x_t _E_n_t_r_y _C_o_m_m_a_n_d_s [line] append [line][,line] change ["x] [line] insert The (a)ppend command inserts text after the specified line. The (i)nsert command inserts text before the specified line. The (c)hange command copies the range of lines into a cut buffer, deletes them, and inserts new text where the old text used to be. For all of these commands, you indicate the end of the text you're inserting by hitting ^D or by entering a line which contains only a period. _C_u_t & _P_a_s_t_e _C_o_m_m_a_n_d_s [line][,line] delete ["x] [line][,line] yank ["x] [line] put[!] ["x] [line][,line] copy line [line][,line] to line [line][,line] move line The (d)elete command copies the specified range of lines into a cut buffer, and then deletes them. The (y)ank command copies the specified range of lines into a cut buffer, but does *not* delete them. The (pu)t command inserts text from a cut buffer after the specified line -- or before it if the ! is present. The (co)py and (t)o commands yank the specified range of lines and then immediately paste them after some other line. The (m)ove command deletes the specified range of lines and then immediately pastes them after some other line. If the destination line comes after the deleted text, then it will be adjusted automatically to account for the deleted lines. _D_i_s_p_l_a_y _T_e_x_t _C_o_m_m_a_n_d_s [line][,line] print [line][,line] list The (p)rint command displays the specified range of lines. The (l)ist command also displays them, but it is careful to make control characters visible. - 9 - _G_l_o_b_a_l _O_p_e_r_a_t_i_o_n_s _C_o_m_m_a_n_d_s [line][,line] global /regexp/ command [line][,line] vglobal /regexp/ command The (g)lobal command searches through the lines of the specified range (or through the whole file if no range is specified) for lines that contain a given regular expression. It then moves the cursor to each of these lines and runs some other command on them. The (v)global command is similar, but it searches for lines that _d_o_n'_t contain the regular expression. _L_i_n_e _E_d_i_t_i_n_g _C_o_m_m_a_n_d_s [line][,line] join [line][,line] ! program [line][,line] < [line][,line] > [line][,line] substitute /regexp/replacement/[p][g] The (j)oin command catenates all lines in the specified range together to form one big line. If only a single line is specified, then the following line is catenated onto it. The ! command runs an external filter program, and feeds the specified range of lines to it's stdin. The lines are then replaced by the output of the filter. A typical example would be ":'a,'z!sort" to sort the lines 'a,'z. The < and > commands shift the specified range of lines left or right, normally by the width of 1 tab character. The "shiftwidth" option determines the shifting amount. The (s)ubstitute command finds the regular expression in each line, and replaces it with the replacement text. The "p" option causes the altered lines to be printed, and the "g" option permits all instances of the regular expression to be found & replaced. (Without "g", only the first occurrence in each line is replaced.) _U_n_d_o _C_o_m_m_a_n_d undo The (u)ndo command restores the file to the state it was in before your most recent command which changed text. _C_o_n_f_i_g_u_r_a_t_i_o_n & _S_t_a_t_u_s _C_o_m_m_a_n_d_s map[!] [key mapped_to] unmap[!] key digraph[!] [XX [Y]] set [options] mkexrc [line] mark x visual version - 10 - [line][,line] = file source file The (ma)p command allows you to configure Elvis to recognize your function keys, and treat them as though they transmitted some other sequence of characters. Normally this mapping is done only when in the visual command mode, but with the [!] present it will map keys under all contexts. When this command is given with no arguments, it prints a table showing all mappings currently in effect. When called with two arguments, the first is the sequence that your function key really sends, and the second is the sequence that you want Elvis to treat it as having sent. The (unm)ap command removes key definitions that were made via the map command. The (di)graph command allows you to display the set of digraphs that Elvis is using, or add/remove a digraph. To list the set of digraphs, use the digraph command with no arguments. To add a digraph, you should give the digraph command two arguments. The first argument is the two ASCII characters that are to be combined; the second is the non-ASCII character that they represent. The non-ASCII character's most significant bit is automatically set by the digraph command, unless to append a ! to the command name. Removal of a digraph is similar to adding a digraph, except that you should leave off the second argument. The (se)t command allows you examine or set various options. With no arguments, it displays the values of options that have been changed. With the single argument "all" it displays the values of all options, regardless of whether they've been explicitly set or not. Otherwise, the arguments are treated as options to be set. The (mk)exrc command saves the current configuration to a file called ".exrc" in the current directory. The mar(k) command defines a named mark to refer to a specific place in the file. This mark may be used later to specify lines for other commands. The (vi)sual command puts the editor into visual mode. Instead of emulating ex, Elvis will start emulating vi. The (ve)rsion command tells you that what version of Elvis this is. The = command tells you what line you specified, or, if you specified a range of lines, it will tell you both endpoints and the number of lines included in the range. The (f)ile command tells you the name of the file, whether it has been modified, the number of lines in the file, and the current line number. - 11 - The (so)urce command reads a sequence of colon mode commands from a file, and interprets them. _M_u_l_t_i_p_l_e _F_i_l_e _C_o_m_m_a_n_d_s args [files] next[!] [files] Next[!] previous[!] rewind[!] When you invoke Elvis from your shell's command line, any filenames that you give to Elvis as arguments are stored in the args list. The (ar)gs command will display this list, or define a new one. The (n)ext command switches from the current file to the next one in the args list. You may specify a new args list here, too. The (N)ext and (pre)vious commands (they're really aliases for the same command) switch from the current file to the preceding file in the args list. The (rew)ind command switches from the current file to the first file in the args list. _S_w_i_t_c_h_i_n_g _F_i_l_e_s _C_o_m_m_a_n_d_s edit[!] [file] tag[!] tagname The (e)dit command allows to switch from the current file to some other file. This has nothing to do with the args list, by the way. The (ta)g command looks up a given tagname in a file called "tags". This tells it which file the tag is in, and how to find it in that file. Elvis then switches to the tag's file and finds the tag. _E_x_i_t _C_o_m_m_a_n_d_s quit[!] wq xit The (q)uit command exits from the editor without saving your file. The (wq) command writes your file out, then then exits. The (x)it command is similar to the (wq) command, except that (x)it won't bother to write your file if you haven't modified it. - 12 - _F_i_l_e _I/_O _C_o_m_m_a_n_d_s [line] read file [line][,line] write[!][[>>]file] The (r)ead command gets text from another file and inserts it after the specified line. The (w)rite command writes the whole file, or just part of it, to some other file. The !, if present, will permit the lines to be written even if you've set the readonly option. If you precede the filename by >> then the lines will be appended to the file. _D_i_r_e_c_t_o_r_y _C_o_m_m_a_n_d_s cd [directory] chdir [directory] shell The (cd) and (chd)ir commands (really two names for one command) switch the current working directory. The (sh)ell command starts an interactive shell. _D_e_b_u_g_g_i_n_g _C_o_m_m_a_n_d_s [line][,line] debug[!] validate[!] These commands are only available if you compile Elvis with the -DDEBUG flag. The de(b)ug command lists stats for the blocks which contain the specified range of lines. If the ! is present, then the contents of those blocks is displayed, too. The (va)lidate command checks certain variables for internal consistency. Normally it doesn't output anything unless it detects a problem. With the !, though, it will always produce *some* output. - 13 - _R_e_g_u_l_a_r _E_x_p_r_e_s_s_i_o_n_s Elvis uses regular expressions for searching and substututions. _S_y_n_t_a_x The code for handling regular expressions is derived from Henry Spencer's regexp package. However, I have modified the syntax to resemble that of the real vi. Elvis' regexp package treats the following one- or two-character strings (called meta-characters) in special ways:  Used to control grouping ^ Matches the beginning of a line $ Matches the end of a line \< Matches the beginning of a word \> Matches the end of a word [ ] Matches any single character inside the brackets * The preceding may be repeated 0 or more times + The preceding may be repeated 1 or more times ? The preceding is optional \| Separates two alternatives Anything else is treated as a normal character which must match exactly. The special strings may all be preceded by a backslash to force them to be treated normally. For example, "$for\|back$ward" will find "forward" or "backward", and "\<text\>" will find "text" but not "context". _O_p_t_i_o_n_s 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, only ^ and $ retain their special meaning. 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. In noignorecase mode, uppercase and lowercase are treated as being different. Also, the "[no]wrapscan" option affects searches. - 14 - _S_u_b_s_t_i_t_u_t_i_o_n_s 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. Most characters in the substitution string are copied into the text literally but a few have special meaning: & Causes a copy of the original text to be inserted \1 Inserts a copy of that portion of the original text which matched the first set of  parentheses. \2 - \9 Does the same for the second (etc.) pair of . These may be preceded by a backslash to force them to be treated normally. - 15 - _O_p_t_i_o_n_s Options may be set or examined via the colon command "set". The values of options will affect the operation of later commands. There are three types of options: Boolean, string, and numeric. Boolean options are made TRUE by giving the name of the option as an argument to the "set" command; they are made FALSE by prefixing the name with "no". For example, "set autoindent" makes the autoindent option TRUE, and "set noautoindent" makes it FALSE. To change the value of a string or numeric option, pass the "set" command the name of the option, followed by an "=" sign and the option's new value. For example, "set tabstop=8" will give the tabstop option a value of 8. For string options, you may enclose the new value in quotes. For convenience, options have both a long descriptive name and a short name which is easy to type. You may use either name interchangably. I like the short names, myself. Names Type Default Meaning ---------------+-----------+-------------------+-------------------------------- ai, autoindent Boolean noai auto-indent during input aw, autowrite Boolean noaw auto-write when switching files ca, charattr Boolean noca interpret \fX sequences co, columns Numeric co=80 width of the screen dir, directory String dir="/usr/tmp" where tmp files are kept eb, errorbells Boolean eb ring bell on error er, exrefresh Boolean er write lines indiviually in EX hf, hideformat Boolean hf hide text formatter comamnds ic, ignorecase Boolean noic upper/lowercase match in search im, inputmode Boolean noim start vi in insert mode? kt, keytime Numeric kt=2 timeout for mapped key entry kp, keywordprg String kp="/usr/bin/ref" full pathname of shift-K prog ln, lines Numeric ln=25 number of lines on the screen li, list Boolean noli display lines in "list" mode ma, magic Boolean ma use regular expression in search pa, paragraphs String pa="PPppPApa" names of "paragraph" nroff cmd ro, readonly Boolean noro prevent overwriting of orig file re, report Numeric re=5 report when 5 or more changes sc, scroll Numeric sc=12 scroll amount for ^U and ^D se, sections String se="SEseSHsh" names of "section" nroff cmd sh, shell String sh="/bin/sh" full pathname of the shell sho, showmode Boolean noshowmode say when we're in input mode sw, shiftwidth Numeric sw=8 shift amount for < and > ss, sidescroll Numeric ss=8 amount of sideways scrolling sy, sync Boolean nosy call sync() often ts, tabstop Numeric ts=8 width of tab characters te, term String te="?" name of the termcap entry vb, vbell Boolean vb use visible alternative to bell wa, warn Boolean wa warn for ! if file modified wm, wrapmargin Numeric wm=0 wrap long lines in input mode ws, wrapscan Boolean ws at EOF, searches wrap to line 1 - 16 - _a_u_t_o_i_n_d_e_n_t During input mode, the autoindent option will cause each added line to begin with the same amount of leading whitespace as the line above it. Without autoindent, added lines are initially empty. _a_u_t_o_w_r_i_t_e When you're editing one file and decide to switch to another -- via the :tag command, or :next command, perhaps -- if your current file has been modified, then Elvis will normally print an error message and refuse to switch. However, if the autowrite option is on, then Elvis will write the modified version of the current file and successfully switch to the new file. _c_h_a_r_a_t_t_r Many text formatting programs allow you to designate portions of your text to be underlined, italicized, or boldface by embedding the special strings \fU, \fI, and \fB in your text. The special string \fR marks the end of underlined or boldface text. Elvis normally treats those special strings just like any other text. However, if the charattr option is on, then Elvis will interpret those special strings correctly, to display underlined or boldface text on the screen. (This only works, of course, if your terminal can display underlined and boldface, and if the TERMCAP entry says how to do it.) _c_o_l_u_m_n_s This is a "read only" option. You can't change its value, but you can have Elvis print it. It shows how wide your screen is. _d_i_r_e_c_t_o_r_y Elvis stores text in temporary files. This option allows you to control which directory those temporary files will appear in. The default is /usr/tmp. This option can only be set in a .exrc file; after that, elvis will have already started making temporary files in some other directory, so it would be too late. - 17 - _e_r_r_o_r_b_e_l_l_s Elvis normally rings a bell when you do something wrong. This option lets you disable the bell. _e_x_r_e_f_r_e_s_h The EX mode of Elvis writes many lines to the screen. You can make Elvis either write each line to the screen separately, or save up many lines and write them all at once. The exrefresh option is normally on, so each line is written to the screen separately. You may wish to turn the exrefresh option off (:se noer) if the "write" system call is costly on your machine, or if you're using a windowing environment. (Windowing environments scroll text a lot faster when you write many lines at once.) This option has no effect in visual command mode or input mode. _h_i_d_e_f_o_r_m_a_t Many text formatters require you to embed format commands in your text, on lines that start with a "." character. Elvis normally displays these lines like any other text, but if the hideformat option is on, then format lines are displayed as blank lines. _i_g_n_o_r_e_c_a_s_e Normally, when Elvis searches for text, it treats uppercase letters as being different for lowercase letters. When the ignorecase option is on, uppercase and lowercase are treated as equal. _i_n_p_u_t_m_o_d_e This option allows you to have Elvis start up in insert mode. You can still exit insert mode at any time by hitting the ESC key, as usual. Usually, this option would be set in your ".exrc" file. _k_e_y_t_i_m_e The arrow keys of most terminals send a multi-character sequence. It takes a measurable amount of time for these sequences to be transmitted. The keytime option allows you to control the maximum amount of time to allow for an arrow key (or other mapped key) to be received in full. - 18 - The default keytime value is 2. Because of the way UNIX timekeeping works, the actual amount of time allowed will vary slightly, but it will always be between 1 and 2 seconds. If you set keytime to 1, then the actual amount of time allowed will be between 0 and 1 second. This will generally make the keyboard's response be a little faster (mostly for the ESC key), but on those occasions where the time allowed happens to be closer to 0 than 1 second, Elvis may fail to allow enough time for an arrow key's sequence to be received fully. Ugh. As a special case, you can set keytime to 0 to disable this time limit stuff altogether. The big problem here is: If your arrow keys' sequences start with an ESC, then every time you hit your ESC key Elvis will wait... and wait... to see if maybe that ESC was part of an arrow key's sequence. NOTE: this option is a generalization of the timeout option of the real vi. _k_e_y_w_o_r_d_p_r_g Elvis has a special keyword lookup feature. You move the cursor onto a word, and hit shift-K, and Elvis uses another program to look up the word and display information about it. This option says which program gets run. It should contain the full pathname of the program; your whole execution path is _n_o_t checked. The default value of this option is "/usr/bin/ref", which is a program that looks up the definition of a function in C. It looks up the function name in a file called "refs" which is created by ctags. You can subtitute other programs, such as an English dictionary program or the online manual. Elvis runs the program, using the keyword as its only argument. The program should write information to stdout. The program's exit status should be 0, unless you want Elvis to print "<<< failed >>>". _l_i_n_e_s This "read only" option shows how many lines you screen has. _l_i_s_t In nolist mode (the default), elvis displays text in a "normal" manner -- with tabs expanded to an appropriate number of spaces, etc. However, sometimes it is useful to have tab characters displayed differently. In list mode, tabs are displayed as "^I", and a "$" is displayed at the end of each line. - 19 - _m_a_g_i_c The search mechanism in Elvis can accept "regular expressions" -- strings in which certain characters have special meaning. The magic option is normally on, which causes these characters to be treated specially. If you turn the magic option off (:se noma), then all characters except ^ and $ are treated literally. ^ and $ retain their special meanings regardless of the setting of magic. _p_a_r_a_g_r_a_p_h_s The { and } commands move the cursor forward or backward in increments of one paragraph. Paragraphs may be separated by blank lines, or by a "dot" command of a text formatter. Different text formatters use different "dot" commands. This option allows you to configure Elvis to work with your text formatter. It is assumed that your formatter uses commands that start with a "." character at the front of a line, and then have a one- or two-character command name. The value of the paragraphs option is a string in which each pair of characters is one possible form of your text formatter's paragraph command. _r_e_a_d_o_n_l_y Normally, Elvis will let you write back any file to which you have write permission. If you don't have write permission, then you can only write the changed version of the file to a _d_i_f_f_e_r_e_n_t file. If you set the readonly option, then Elvis will pretend you don't have write permission to _a_n_y file you edit. It is useful when you really only mean to use Elvis to look at a file, not to change it. This way you can't change it accidentally. This option is normally off, unless you use the "view" alias of Elvis. "View" is like "vi" except that the readonly option is on. _r_e_p_o_r_t Commands in Elvis may affect many lines. For commands that affect a lot of lines, Elvis will output a message saying what was done and how many lines were affected. This option allows you to define what "a lot of lines" means. The default is 5, so any command which affects 5 or more lines will cause a message to be shown. - 20 - _s_c_r_o_l_l The ^U and ^D keys normally scroll backward or forward by half a screenful, but this is adjustable. The value of this option says how many lines those keys should scroll by. _s_e_c_t_i_o_n_s The [[ and ]] commands move the cursor backward or forward in increments of 1 section. Sections may be delimited by a { character in column 1 (which is useful for C source code) or by means of a text formatter's "dot" commands. This option allows you to configure Elvis to work with your text formatter's "section" command, in exectly the same way that the paragraphs option makes it work with the formatter's "paragraphs" command. _s_h_e_l_l When Elvis forks a shell (perhaps for the :! or :shell commands) this is the program that is uses as a shell. This is "/bin/sh" by default, unless you have set the SHELL (or COMSPEC, for MS-DOS) environment variable, it which case the default value is copied from the environment. _s_h_i_f_t_w_i_d_t_h The < and > commands shift text left or right by some uniform number of columns. The shiftwidth option defines that "uniform number". The default is 8. _s_h_o_w_m_o_d_e In visual mode, it is easy to forget whether you're in the visual command mode or input/replace mode. Normally, the showmode option is off, and you haven't a clue as to which mode you're in. If you turn the showmode option on, though, a little message will appear in the lower right-hand corner of your screen, telling you which mode you're in. _s_i_d_e_s_c_r_o_l_l For long lines, Elvis scrolls sideways. (This is different from the real vi, which wraps a single long line onto several rows of the screen.) To minimize the number of scrolls needed, Elvis moves the screen sideways by several characters at a time. The value of this option says how many characters' widths to scroll at a time. - 21 - Generally, the faster your screen can be redrawn, the lower the value you will want in this option. _s_y_n_c If the system crashes during an edit session, then most of your work can be recovered from the temporary file that elvis uses to store changes. However, sometimes UNIX/Minix will not copy changes to the hard disk immediately, so recovery might not be possible. The [no]sync option lets you control this. In nosync mode (which is the default), elvis lets the operating system control when data is written to the disk. This is generally faster. In sync mode, elvis forces all changes out to disk every time you make a change. This is generally safer, but slower. _t_a_b_s_t_o_p Tab characters are normally 8 characters wide, but you can change their widths by means of this option. _t_e_r_m This "read only" option shows the name of the termcap entry that Elvis is using for your terminal. _v_b_e_l_l If your termcap entry describes a visible alternative to ringing your terminal's bell, then this option will say whether the visible version gets used or not. Normally it will be. If your termcap does NOT include a visible bell capability, then the vbell option will be off, and you can't turn it on. _w_a_r_n If you have modified a file but not yet written it back to disk, then Elvis will normally print a warning before executing a ":!cmd" command. However, in nowarn mode, this warning is not given. Elvis also normally prints a message after a successful search that wrapped at EOF. The [no]warn option can also disable this warning. - 22 - _w_r_a_p_m_a_r_g_i_n Normally (with wrapmargin=0) Elvis will let you type in extremely long lines, if you wish. However, with warpmargin set to something other that 0 (wrapmargin=10 is nice), Elvis will automatically cause long lines to be "wrapped" on a word break for lines longer than wrapmargin's setting. _w_r_a_p_s_c_a_n Normally, when you search for something, Elvis will find it no matter where it is in the file. Elvis starts at the cursor position, and searches forward. If Elvis hits EOF without finding what you're looking for, then it wraps around to continue searching from line 1. If you turn off the wrapscan option (:se nows), then when Elvis hits EOF during a search, it will stop and say so. - 23 - _P_r_o_g_r_a_m_s _e_l_v_i_s, _e_x, _v_i, _v_i_e_w, _i_n_p_u_t - _T_h_e _e_d_i_t_o_r elvis [flags] [+cmd] [files...] -r tell the user to use "virec" instead -R set the "readonly" option to TRUE -t tag search for a tag -e start up in colon command mode -v start up in visual command mode -i start up in input mode The editor itself is called elvis, of course. On systems which pass the program name as an argument, such as Unix and Minix, you may also install elvis under the names "ex", "vi", and "view". These extra names would normally be links to elvis; see the "ln" shell command. When elvis is invoked as "vi", it behaves exactly as though it was invoked as "elvis". However, if you invoke elvis as "view", then the readonly option is set as though you had given it the "-R" flag. If you invoke elvis as "ex", then elvis will start up in the colon command mode instead of the visual command mode, as though you had given it the "-e" flag. If you invoke elvis as "input" or "edit", then elvis will start up in input mode, as though the "-i" flag was given. If you use the "+cmd" parameter, then after the first file is loaded "cmd" is treated like a colon command. A typical example would be "elvis +237 foo", which would cause elvis to start editing foo and then move directly to line 237. _c_t_a_g_s - _G_e_n_e_r_a_t_e_s "_t_a_g_s" _a_n_d (_o_p_t_i_o_n_a_l_l_y) "_r_e_f_s" _f_i_l_e_s ctags [-r] files... -r generate a "refs" file, too The "tags" file is used by Elvis' ":tag" command, control-] command, and -t option. Each C source file is scanned for #define statements and global function definitions. The name of the macro or function becomes the name of a tag. For each tag, a line is added to the "tags" file which contains: - the name of the tag - a tab character - the name of the file containing the tag - a tab character - a way to find the particular line within the file. The "refs" file is used by the "ref" program, which can be invoked via Elvis' K command. When ctags finds a global function definition, it copies the function header into the "refs" file. The first line is flush against the right margin, but the argument definitions are indented. The ref program can search the "refs" file _m_u_c_h faster than it could search all of the C source files. - 24 - The filenames list will typically be the names of all C source files in the current directory, like this: $ ctags -r *.[ch] _r_e_f - _D_i_s_p_l_a_y _a _C _f_u_n_c_t_i_o_n _h_e_a_d_e_r ref function_name Ref is a program which looks up the function header of a particular function in any of a series of reference files. These reference files are produced by the ctags program. Ref is used by vi's shift-K command. The list of files checked includes "refs" in the current directory, and possibly others. See the source code for an accurate list. _v_i_r_e_c - _R_e_c_o_v_e_r _t_h_e _m_o_d_i_f_i_e_d _v_e_r_s_i_o_n _o_f _a _f_i_l_e _a_f_t_e_r _a _c_r_a_s_h virec [-d tmpdir] textfilename... virec [-d tmpdir] </usr/tmp/viname Virec is a program which extracts the most recent version of a text file from a temporary file in /usr/tmp. When you edit a file with Elvis, only about 5K bytes of the file are stored in RAM; the rest is stored in a file in /usr/tmp. This allows you to edit files larger than a process' data space. It also plays a big part in the way that "undo" and "paste" were implemented. The virec program basically extracts the "undo" version from the file. This is most useful when the system (or Elvis) crashes in the middle of a long edit session, because the "undo" version of the file contains everything except your last change. Nearly all of your work can be salvaged. The most common way to invoke virec is this: You just give virec the name of the file you were editing, and it finds the matching file in /usr/tmp and writes the newest available version of the file over the existing version. It then deletes the /usr/tmp file. The other way, where you redirect its stdin to come from a particular /usr/tmp file, is used when you have either forgotten which file that is and you want to see its contents, or when you want to recover the file without losing either the /usr/tmp file or the current version of the text file. - 25 - _D_i_f_f_e_r_e_n_c_e_s _b_e_t_w_e_e_n _e_l_v_i_s _a_n_d _t_h_e _r_e_a_l _v_i/_e_x _E_x_t_e_n_s_i_o_n_s :mkexrc :mk This EX command saves the current :set and :map configurations in the ".exrc" file in your current directory. :args :ar You can use the :args command to define a new args list, as in: :args *.h After you have defined a new args list, the next time you issue a :next command Elvis will switch to the first file of the new list. :Next :previous :N :pre These commands move backwards through the args list. zz In visual command mode, the (lowercase) "zz" command will center the current line on the screen, like "z=". . The default count value for . is the same as the previous command which . is meant to repeat. However, you can supply a new count if you wish. For example, after "3dw", "." will delete 3 words, but "5." will delete 5 words. ". The text which was most recently input (via a "cw" command, or something similar) is saved in a cut buffer called ". (which is a pretty hard name to write in an English sentence). K In visual command mode, you can move the cursor onto a word and press shift-K to have Elvis run a reference program to look that word up. This command alone is worth the price of admission! See the ctags and ref programs. - 26 - # In visual command mode, you can move the cursor onto a number and then hit ## or #+ to increment that number by 1. To increment it by a larger amount, type in the increment value before hitting the initial #. The number can also be decremented or set by hitting #- or #=, respectively. input You can backspace past the beginning of the line. The arrow keys work in input mode. If you type control-A, then the text that you input last time is inserted. You will remain in input mode, so you can backspace over part of it, or add more to it. (This is sort of like control-@ on the real vi, except that control-A really works.) Control-P will insert the contents of the cut buffer. Real vi can only remember up to 128 characters of input, but Elvis can remember any amount. The ^T and ^D keys can adjust the indent of a line no matter where the cursor happens to be in that line. You can save your file and exit Elvis directly from input mode by hitting control-Z twice. Elvis supports digraphs as a way to enter non-ASCII characters. :set inputmode :se im If you set this flag in your .exrc file, then elvis will start up in input mode instead of visual command mode. :set charattr :se ca Elvis can display "backslash-f" style character attributes on the screen as you edit. The following example shows the recognized atributes: normal \fBboldface\fR \fIitalics\fR \fUunderlined\fR normal NOTE: you must compile elvis without the -DNO_CHARATTR flag for this to work. :set noexrefresh :se noer - 27 - Elvis gives you a little more control over how EX mode writes lines to the terminal. In exrefresh mode, each line is individually written; in noexrefresh mode, Elvis writes several lines at once. The latter mode works better on windowing systems. :set sync :se sy After a crash, you can usually recover the altered form of the file from the temporary file that Elvis uses. With the sync option turned on, the odds are shifted a little more in your favor because Elvis will perform a sync() call after each change has been written to the temporary file. cursor shape Elvis changes the shape of the cursor to indicate which mode you're in, if your terminal's termcap entry includes the necessary capabilities. :set hideformat :se hf This option hides format control lines. (They are displayed on the screen as blank lines.) _O_m_i_s_s_i_o_n_s The replace mode is a hack. It doesn't save the text that it overwrites. Long lines are displayed differently -- where the real vi would wrap a long line onto several rows of the screen, Elvis simply displays part of the line, and allows you to scroll the screen sideways to see the rest of it. The ":preserve" and ":recover" commands are missing, as is the -r flag. I've never had a good reason to use ":preserve", and since use of ":recover" is so rare, I decided to implement it as a separate program. There's no need to load the recovery code into memory every time you edit a file. LISP support is missing. The "@" and ":@" commands are missing. You can't APPEND to a cut buffer. The following DOES NOT WORK: "Ayy Due to naming conventions used for the temporary files, Elvis can be creating no more that one new file per directory at any given time. Any number of existing files can be edited at the same time on multitasking computer systems, but only one new file can be created simultaneously per directory. To relieve this problem, you would have to edit tmp.c and virec.c - 28 - _I_n_t_e_r_n_a_l You don't need to know the material in this section to use elvis. You only need it if you intend to modify elvis. _T_h_e _t_e_m_p_o_r_a_r_y _f_i_l_e The temporary file is divided into blocks of 1024 bytes each. When elvis starts up, the file is copied into the temporary file. Small amounts of extra space are inserted into the temporary file to insure that no text lines cross block boundaries; this speeds up processing and simplifies storage management. The "extra space" is filled with NUL charcters; the input file must not contain any NULs, to avoid confusion. The first block of the temporary file is an array of shorts which describe the order of the blocks; i.e. header[1] is the block number of the first block, and so on. This limits the temporary file to 512 active blocks, so the largest file you can edit is about 400K bytes long. I hope that's enough! When blocks are altered, they are rewritten to a _d_i_f_f_e_r_e_n_t block in the file, and the in-core version of the header block is updated accordingly. The in-core header block will be copied to the temp file immediately before the next change... or, to undo this change, swap the old header (from the temp file) with the new (in-core) header. Elvis maintains another in-core array which contains the line-number of the last line in every block. This allows you to go directly to a line, given its line number. _I_m_p_l_e_m_e_n_t_a_t_i_o_n _o_f _E_d_i_t_i_n_g There are three basic operations which affect text: * delete text - delete(from, to) * add text - add(at, text) * yank text - cut(from, to) To yank text, all text between two text positions is copied into a cut buffer. The original text is not changed. To copy the text into a cut buffer, you need only remember which physical blocks that contain the cut text, the offset into the first block of the start of the cut, the offset into the last block of the end of the cut, and what kind of cut it was. (Cuts may be either character cuts or line cuts; the kind of a cut affects the way it is later "put".) This is implemented in the function cut(). To delete text, you must modify the first and last blocks, and remove any reference to the intervening blocks in the header's list. The text to be deleted is specified by two marks. This is implemented in the function delete(). - 29 - To add text, you must specify the text to insert (as a NUL-terminated string) and the place to insert it (as a mark). The block into which the text is to be inserted may need to be split into as many as four blocks, with new intervening blocks needed as well... or it could be as simple as modifying a single block. This is implemented in the function add(). Other interesting functions are paste() (to copy text from a cut buffer into the file), modify() (for an efficient way to implement a combined delete/add sequence), and input() (to get text from the user & insert it into the file). When text is modified, an internal file-revision counter, called "changes", is incremented. This counter is used to detect when certain caches are out of date. (The "changes" counter is also incremented when we switch to a different file, and also in one or two similar situations -- all related to invalidating caches.) _M_a_r_k_s _a_n_d _t_h_e _C_u_r_s_o_r Marks are places within the text. They are represented internally as a long variable which is split into two bitfields: a line number and a character index. Line numbers start with 1, and character indexes start with 0. Since line numbers start with 1, it is impossible for a set mark to have a value of 0L. 0L is therefore used to represent unset marks. When you do the "delete text" change, any marks that were part of the deleted text are unset, and any marks that were set to points after it are adjusted. Similarly, marks are adjusted after new text is inserted. The cursor is represented as a mark. _C_o_l_o_n _C_o_m_m_a_n_d _I_n_t_e_r_p_r_e_t_a_t_i_o_n Colon commands are parsed, and the command name is looked up in an array of structures which also contain a pointer to the function that implements the command, and a description of the arguments that the command can take. If the command is recognized and its arguments are legal, then the function is called. Each function performs its task; this may cause the cursor to be moved to a different line, or whatever. - 30 - _S_c_r_e_e_n _C_o_n_t_r_o_l The screen is updated via a package which looks like the "curses" library, but isn't. It is actually much simpler. Most curses operations are implemented as macros which copy characters into a large I/O buffer, which is then written with a single large write() call as part of the refresh() operation. The functions which modify text remember where text has been modified; the screen redrawing function, redraw(), needs this information to help it reduce the amount of text that is redrawn each time. _P_o_r_t_a_b_i_l_i_t_y To improve portability, Elvis collects as much system-dependent definitions as possible in the config.h file. This file begins with some preprocessor instructions which attempt to determine which compiler and operating system you have. After that, it conditionally defines some macros and constants for your system. One of the more significant macros is ttyread(buf,n). This macro is used to read characters from the keyboard. For UNIX systems, this simply reads bytes from stdin. For MS-DOS and Atari-TOS, ttyread() is a function defined in curses.c. There is also a ttywrite macro. The tread() and twrite() macros are versions of read() and write() that are used for text files. On UNIX systems, these are equivelent to read() and write(). On MS-DOS, these are also equivelent to read() and write(), since DOS libraries are generally clever enough to convert newline characters automatically. For Atari TOS, though, the MWC library is too stupid to do this, so we had to do the conversion explicitly. Other macros may substitute index() for strchr(), or bcopy() for memcpy(), or map the (void) data type to (int), or whatever. - 31 - _C_F_L_A_G_S Elvis uses many preprocessor symbols to control compilation. Some of these control the sizes of buffers and such, but the "-DNO_XXXX" options remove small sets of related features. Most Elvis users will probably want to keep all features available. Minix-PC users, though, will have to sacrifice one or two feature sets because otherwise Elvis would be too bulky to compile. The "asld" phase of the compiler craps out. Interestingly, the full Elvis would probably be able to run under Minix-PC if you could cross-compile it; under SCO Xenix the ".text" segment is only about 59k bytes long, and I would expect the Minix-PC version to be about the same. -_D_M__S_Y_S_V, -_D_T_O_S, -_D_O_S_9 These flags tell the compiler that Elvis is being compliled System-V UNIX, ot Atari TOS, or OS-9/68000, respectively. For other systems, the config.h file can figure it out automatically. -_D_D_A_T_E=\'\"`_d_a_t_e`\"\' DATE should be defined to be a string constant. It is printed by the :version command as the compilation date of the program. It is only used in cmd1.c, and even there you may leave it undefined without causing an urp. The form shown above only works if you use "eval". See the Makefile. -_D_N_B_U_F_S=_1_0 Elvis keeps most of your text in a temporary file; only a small amount is actually stored in RAM. This flag allows you to control how much of the file can be in RAM at any time. The default is 5k bytes; the example above changes that to 10k bytes. More RAM allows global changes to happen a little faster. If you're just making many small changes in one section of a file, though, extra RAM won't help much. -_D_B_L_K_S_I_Z_E=_2_0_4_8 This controls the size of blocks that Elvis uses internally. The value of BLKSIZE must be a power of two. The default value is 1024, which allows you to edit files up to almost 512K bytes long. Every time you double BLKSIZE, you quadruple the size of a text file that Elvis can handle, but you also cause the temporary file to grow faster. - 32 - -_D_T_M_P_D_I_R=\"/_t_m_p\" This sets the default value of the "directory" option, which specifies where the temporary files should reside. The value of TMPDIR must be a string, so be sure your value includes the quote characters on each end. -_D_E_X_R_C=\"._e_l_v_i_s_r_c\" -_D_H_M_E_X_R_C=\"_e_l_v_i_s._i_n_i\" -_D_S_Y_S_E_X_R_C=\"/_e_t_c/_e_l_v_i_s_r_c\" This lets you control the names of the initialization files. Their values must be strings, so be careful about quoting. EXRC is the name of the initialization file in the current directory. Its default value is ".exrc" on UNIX systems -- the same as the real vi. For other systems, check the config.h file. HMEXRC is the name of the initialization file in your home directory. By default, it is the same as EXRC. Elvis will automatically prepend the name of your home directory to HMEXRC at run time, so don't give a full path name. SYSEXRC is the name of a system-wide initialization file. It has no default value; if you don't define a value for it, then the code that supports SYSEXRC just isn't compiled. The value of SYSEXRC should be a full pathname. -_D_K_E_Y_W_O_R_D_P_R_G=\"/_u_s_r/_l_o_c_a_l/_r_e_f\" This flag determines the default value of the "keywordprg" option. Its value must be a string, so be careful about quoting. The default value of this flag is "/usr/bin/ref" on UNIX systems. -_D_D_E_B_U_G This adds the ":debug" and ":validate" commands, and also adds many internal consistency checks. It increases the size of the ".text" segment by about 5K. -_D_N_O__C_H_A_R_A_T_T_R Permanently disables the charattr option. This reduces the size of your ".text" segment by about 850 bytes. -_D_N_O__R_E_C_Y_C_L_E Normally, Elvis will recycle space (from the tmp file) which contains totally obsolete text. This flag disables this recycling. Without recycling, the ".text" segment is about 1K smaller than it would otherwise be, but the tmp file grows much faster. If you have a lot of free space on your harddisk, but Elvis is too bulky to run with recycling, then try it without recycling. - 33 - When using a version of Elvis that has been compiled with -DNO_RECYCLE, you should be careful to avoid making many small changes to a file because each individual change will cause the tmp file to grow by at least 1k. Hitting "x" thirty times counts as thirty changes, but hitting "30x" counts as one change. Also, you should occasionally do a ":w" followed by a ":e" to start with a fresh tmp file. -_D_N_O__S_E_N_T_E_N_C_E Leaves out the "(" and ")" visual mode commands. Also, the "[[", "]]", "{", and "}" commands will not recognize *roff macros. The sections and paragraphs options go away. This saves about 650 bytes in the ".text" segment. -_D_N_O__C_H_A_R_S_E_A_R_C_H Leaves out the visual commands which locate a given character in the current line: "f", "t", "F", "T", "," and ";". This saves about 900 bytes. -_D_N_O__E_X_T_E_N_S_I_O_N_S Leaves out the :mkexrc command, and the "K" and "#" visual commands. Also, the arrow keys will no longer work in input mode. (Other extensions are either inherent in the design of elvis, or are controlled by more specific flags, or are too tiny to be worth removing.) This saves about 500 bytes. -_D_N_O__M_A_G_I_C Permanently disables the "magic" option, so that most meta-characters in a regular expression are *NOT* recognized. This saves about 3k of space in the ".text" segment, because the complex regular expression code can be replaced by much simpler code. -_D_N_O__S_H_O_W_M_O_D_E Permanently disables the "showmode" option, saving about 250 bytes. -_D_N_O__C_U_R_S_O_R_S_H_A_P_E Normally, Elvis tries to adjust the shape of the cursor as a reminder of which mode you're in. The -DNO_CURSORSHAPE flag disables this, saving about 150 bytes. - 34 - -_D_N_O__D_I_G_R_A_P_H To allow entry of non-ASCII characters, Elvis supports digraphs. A digraph is a single (non-ASCII) character which is entered as a combination of two other (ASCII) characters. If you don't need to input non-ASCII characters, or if your keyboard supports a better way of entering non-ASCII characters, then you can disable the digraph code and save about 450 bytes. - 35 - _T_e_r_m_c_a_p Elvis uses fairly standard termcap capabilities for most things. Some of the keyboard sequences were borrowed from SCO Xenix, and I invented some of the character attribute names and all of the cursor shape names, but other than that there should be no surprises. _R_e_q_u_i_r_e_d _n_u_m_e_r_i_c _c_a_p_a_b_i_l_i_t_i_e_s :co#: number of columns on the screen (characters per line) :li#: number of lines on the screen _R_e_q_u_i_r_e_d _s_t_r_i_n_g _c_a_p_a_b_i_l_i_t_i_e_s :ce=: clear to end-of-line :cl=: home the cursor & clear the screen :cm=: move the cursor to a given row/column :up=: move the cursor up one line _B_o_o_l_e_a_n _c_a_p_a_b_i_l_i_t_i_e_s :am: auto margins - wrap when a char is written to the last column? :pt: physical tabs? _O_p_t_i_o_n_a_l _s_t_r_i_n_g _c_a_p_a_b_i_l_i_t_i_e_s :al=: insert a blank row on the screen :dl=: delete a row from the screen :cd=: clear to end of display :ei=: end insert mode :ic=: insert a blank character :im=: start insert mode :dc=: delete a character :sr=: scroll reverse (insert a row at the top of the screen) :vb=: visible bell :ti=: terminal initialization string, to start full-screen mode :te=: terminal termination, to end full-screen mode _O_p_t_i_o_n_a_l _s_t_r_i_n_g_s _r_e_c_e_i_v_e_d _f_r_o_m _t_h_e _k_e_y_b_o_a_r_d :kd=: sequence sent by the <down arrow> key :kl=: sequence sent by the <left arrow> key :kr=: sequence sent by the <right arrow> key :ku=: sequence sent by the <up arrow> key :PU=: sequence sent by the <PgUp> key :PD=: sequence sent by the <PgDn> key :HM=: sequence sent by the <Home> key :EN=: sequence sent by the <End> key - 36 - _O_p_t_i_o_n_a_l _c_a_p_a_b_i_l_i_t_i_e_s _t_h_a_t _d_e_s_c_r_i_b_e _c_h_a_r_a_c_t_e_r _a_t_t_r_i_b_u_t_e_s :so=: :se=: start/end standout mode (We don't care about :sg#:) :us=: :ue=: start/end underlined mode :VB=: :Vb=: start/end boldface mode :as=: :ae=: start/end alternate character set (italics) :ug#: visible gap left by :us=:, :ue=:, :VB=:, or :Vb=: _O_p_t_i_o_n_a_l _c_a_p_a_b_i_l_i_t_i_e_s _t_h_a_t _a_f_f_e_c_t _t_h_e _s_h_a_p_e _o_f _t_h_e _c_u_r_s_o_r The :cQ=: string is used by elvis immediately before exiting to undo the effects of the other cursor shape strings. If :cQ=: is not given, then all other cursor shape strings are ignored. :cQ=: normal cursor :cX=: cursor shape used for reading EX command -- steady underline :cV=: cursor shape used for reading VI commands -- steady block :cI=: cursor shape used during VI input mode -- blinking underline :cR=: cursor shape used during VI replace mode -- blinking block _A_n _e_x_a_m_p_l_e Here's the termcap entry I use on my Minix-ST system. Some of the capabilities in it have nothing to do with Elvis. Some can only work on my system; I have modified my kernel's screen driver. mx|minix|minixst|ansi:\ :co#80:li#25:bs:pt:\ :cm=\E[%i%d;%dH:up=\E[A:do=^J:nd=\E[C:sr=\EM:\ :cd=\E[J:ce=\E[K:cl=\E[H\E[J:\ :al=\E[L:dl=\E[M:ic=\E[@:dc=\E[P:im=:ei=:\ :so=\E[7m:se=\E[m:us=\E[4m:ue=\E[m:\ :VB=\E[1m:Vb=\E[m:as=\E[1;3m:ae=\E[m:\ :rs=\E[?5l:\ :ku=\E[A:kd=\E[B:kr=\E[C:kl=\E[D:kb=^H:\ :k1=\EOP:k2=\EOQ:k3=\EOR:k4=\EOS:k5=\EOT:\ :k6=\EOU:k7=\EOV:k8=\EOW:k9=\EOX:k0=\EOY:\ :kH=\E[V:kU=\E[U:\ :cQ=\E[k:cX=\E[2;0k:cV=\E[16;0k:cI=\E[2;20k:cR=\E[16;20k:\ :G3=%:GU=&:G4=':GR=(:GC=):GL=*:G2=+:GD=,:G1=-:GH=.:GV=/: - 37 - _E_n_v_i_r_o_n_m_e_n_t _V_a_r_i_a_b_l_e_s Elvis examines several environment variables when it starts up. The values of these variables are used internally for a variety of purposes. You don't need to define all of these; on most systems, Elvis only requires TERM to be defined. On MS-DOS systems, even that is optional. _T_E_R_M, _T_E_R_M_C_A_P TERM tells Elvis the name of the termcap entry to use. TERMCAP may contain either the entire termcap entry, or the full pathname of the termcap file to search through. _T_M_P, _T_E_M_P These only work for MS-DOS and Atari TOS. Either of these variables may be used to set the "directory" option, which controls where temporary files are stored. If you define them both, then TMP is used, and TEMP is ignored. _E_X_I_N_I_T This variable may contain a colon-mode command, which will be executed after all of the ".exrc" files but before interactive editing begins. NOTE: the real vi allows you to put multiple commands here, separated by | characters. Elvis doesn't, yet, but you can place a "source" command there to get the same effect. _S_H_E_L_L, _C_O_M_S_P_E_C You can use COMSPEC in MS-DOS, or SHELL in any other system, to specify which shell should be used for executing commands and expanding wildcards. _H_O_M_E This variable should give the full pathname of your home directory. Elvis needs to know the name of your home directory so it can locate the ".exrc" file there. - 38 - _V_e_r_s_i_o_n_s Elvis currently works under BSD UNIX, AT&T System-V UNIX, SCO XENIX, Minix, MS-DOS, and Atari TOS. This section of the manual provides special information that applies to each particular version of Elvis. _B_S_D _U_N_I_X Use "Makefile.bsd" to make Elvis. The only problem you're like to have is that both Elvis and the real Vi read initialization commands from a file called ".exrc", but the commands in that file might work on one but not the other. For example, "set keywordprg=/usr/myself/bin/ref" will work for Elvis, but Vi will complain because it doesn't have a "keywordprg" option. If the warning messages annoy you, then you can edit the config.h file to change the name of the initialization file ".exrc" to something else, such as ".elvisrc". _S_y_s_t_e_m-_V _U_N_I_X Use "Makefile.s5" to make Elvis. If your system uses terminfo instead of termcap, then you will have to edit the Makefile. More detailed instructions are embedded in the Makefile itself. The potential trouble with ".exrc" described above for BSD UNIX applies to System-V UNIX as well. If your system uses terminfo, you may have trouble with some of Elvis' extensions because terminfo can only emulate the standard termcap capabilites and some of the extensions use nonstandard capabilites. In particular, you can expect the "charattr" option to be almost useless, and the cursor's shape won't change. Elvis uses control-C as the interrupt key, not Delete. _S_C_O _X_e_n_i_x Use "Makefile.s5" to make Elvis. On '286 systems, you will have to edit the Makefile so that the compiler generates code with separate instruction & data segments. More detailed instructions are embedded in the Makefile itself. Other than that, the Xenix version behaves like the System-V version, so everything mentioned in the System-V section above applies to SCO Xenix. - 39 - _M_i_n_i_x Use "Makefile.st" on Minix-ST systems, and "Makefile.pc" on Minix-PC systems. The differences between these two Makefiles are that the ST version uses "*.o" files where the PC version uses "*.s" files, and the PC version has some extra flags in CFLAGS to reduce the size of Elvis. Minix-PC users should read the CFLAGS section of this manual very carefully. The temporary files are stored in /usr/tmp. The /usr/tmp directory must exist before you run Elvis, and it must be readable/writable by everybody. Elvis uses control-C as the interrupt key, not Delete. _M_S-_D_O_S Elvis was ported to MS-DOS by Guntram Blohm and Martin Patzel. There are two different Makefiles for Elvis under MS-DOS. "Elvis.prj" should be used with Turbo-C, and "Elvis.mak" should be used with MSC and Microsoft MAKE. The "Elvis.mak" file may work with MS Quick-C if you change the definition of CC to "CC= qcl". I don't know for sure; I haven't tried it. Elvis stores its temporary files in C:\tmp. If this is not satisfactory, then you should edit the CFLAGS line of your Makefile to change it to something else before compiling. The directory must exist before you can run Elvis. Normally, the TERM environment variable should not be set, or else it should be set to "pcbios". This way, Elvis will make calls to BIOS to update the screen. This is the fastest & prettiest way to update the screen. However, if your system is not quite compatible enough, then you can still run Elvis via the ANSI.SYS or NANSI.SYS drivers. Install one of these drivers by adding "driver = ansi.sys" to your CONFIG.SYS file, and then define TERM to be either "ansi" or "nansi" by adding a line such as "set TERM=ansi" to your AUTOEXEC.BAT file. You must then reboot for these changes to take effect. After that, Elvis will notice the "TERM" setting and use the driver. Under MS-DOS, Elvis has an extra ":set" option called "pcbios" which indicates whether the BIOS is being used directly. This is a "read only" option; you can't use it to switch your interface style in the middle of an edit session. An extra program, called "wildcard", is needed for MS-DOS. It expands wildcard characters in file names. - 40 - _A_t_a_r_i _T_O_S Elvis was ported to Atari TOS by Guntram Blohm and Martin Patzel. It is very similar to the MS-DOS version. The Makefile.tos file should be used for TOS. It is intended to be used with the Mark Williams C compiler. The TERM environment variable should be set to "vt52". The SHELL (not COMSPEC!) variable should be set to the name of a line-oriented shell. A simple shell in included with elvis. Its source is in "shell.c", and the name of the executable is "shell.ttp". This was necessary because the standard Atari software doesn't offer any way to set environment variables. The file "profile.sh" should contain a set of instructions to be executed when the shell first starts up. An example of this file is included, but you will almost certainly want to edit it right away to match your configuration. If you already have a command-line shell, then you'll probably want to continue using it. The shell that comes with elvis is very limited. - 41 -