Quick intro to elvis 2.2, with links to source code and binaries

CONTENTS
  • 1. About this file
  • 2. Differences between vi and elvis 2.2
  • 3. Differences between 2.1 and 2.2
  • 4. The future of elvis
  • 5. Links to related files
  • .---------------------------------------------------------------.
    | This is not elvis' user manual!  The real documentation for   |
    | elvis is located in its online help facility.  While running  |
    | elvis, enter the command ":help" to see the table of contents.|
    ^---------------------------------------------------------------^
    
    

    1. About this file

    This file is written in the HTML markup language. You can view it with any WWW viewer, such as Netscape. You can also use elvis 2.2 to view it; this version of elvis has the ability to view HTML documents, and print them.

    This file has many hypertext links. Use them! If you're using elvis 2.2 to browse this file, then hypertextual references will appear as underlined text. (Except on color PCs; since color video cards don't support underlining, hypertextual references will be colored -- white on red, by default.) To follow the hypertext link, move the cursor onto the underlined text and press (Enter). To go back, press (Control-T). The (Tab) key moves the cursor forward to the next hypertext reference.

    If elvis 2.2 doesn't automatically start up in HTML mode when you view this file, then you'll need to force it into HTML mode by giving the command ":display html".

    2. Differences between vi and elvis 2.2

    Elvis is a superset of vi. It runs on more operating systems than vi, it is free, and you can obtain the source code. Elvis also has many new features. These new features are described in the first chapter of the online manual, which hypertext links to the other parts of the manual where those features are described in detail. Here's a just brief list:

    3. Differences between 2.1 and 2.2b-alpha

    The following is a summary of changes made since the release of elvis 2.1. These are in addition to any bug fixes.

    3.1 Color

    Elvis' :color command has been rewritten. The new version is much more powerful, and it should be more intuitive. Instead of assigning colors to a small number of fonts as in previous versions of elvis, the new :color command assigns colors and font attributes to be used for a large variety of specialized text types.

    3.1.1 Usage

    The general syntax of the :color command is...
    :color [gui.]type [like type] [bold] [italic] [underlined]
    [boxed] [graphic] [fixed|proportional] [color] [on color]
    ... where the items in brackets are optional, bold text is literal, and italic names represent variable text. The [gui.]type must be the first argument of the command, but the other arguments can appear in any order.

    As a special case, giving the :color command without any arguments will list the current color settings. Invoking :color with just a type argument will list the setting of that text type.

    The meanings of the arguments are as follows:

    gui
    This is the name of the user interface which should be affected by the command. If omitted, then the current user interface is assumed. All color settings are stored, whether they affect the current GUI or not, so that the :mkexrc command can build a .exrc file which works correctly on all GUIs. For example, it might have "color termcap.normal yellow on blue" and "color x11.normal black on linen".
    type
    This describes the type of text to be affected. Eventually the html/man/tex display modes will be modified to allow you to define your own type names, and the syntax display mode already allows keywords to be assigned new type names. For this reason, any word is accepted as a role name by the :color command.

    The normal text type is the most important. It is the only text type used in the "normal" display mode, for the current window. Also, any other text type which for which a color or attribute has not been explicitly set will inherit that color or attribute from the normal text type. This inheritance happens when the screen is drawn, so any time you change the normal background color, the default background for all other text types also changes.

    The idle text type is another special one. What normal does for the current window, idle does for all other windows. This means that if you give normal and idle different background colors, then the current window will always be highlighted. The default setting of idle is "color idle like normal" which avoids that behavior.

    Some other text types are lnum for the line numbers displayed by :set number, hexheading for column headings in "hex" mode, hexcursor for the hexadecimal version of the current character in "hex" mode, and header for the page headers when printing in "normal" or "syntax" display mode.

    The "syntax" display mode will eventually be rewritten to allow users to specify roles in the "elvis.syn" file, but for now the following role names are hardcoded: comment, string, char, regexp, keyword, function, variable, other, number, prep for preprocessor directives, and prepquote for text in angle brackets in an #include directive.

    The markup display modes ("html", "man", and "tex") have not been modified to take advantage of the new color scheme yet, so there are no role names for them. This is a shame, really, because they could really benefit from the new attribute combination rules. That was a big influence in the design of the new color code.

    like role
    All fonts inherit any unset colors or attributes from either the normal or idle role. The like role notation allows you to define an additional role for them to inherit from. For example, you could say "color char like string" to make character literals look like string literals; after that, any change to the "string" role would also automatically change the "char" role too.
    bold
    italic
    underlined
    boxed
    graphic
    These turn on various attributes for the text. There is no way to force the attributes off (to prevent them from being inherited from normal or some other role).

    The boxed attribute is new; it draws a box around the text in the "x11" and "windows" GUIs. This is intended to draw boxes around individual words, not whole paragraphs. It is ignored by the "termcap" interface. When printing, the PostScript print drivers draw boxes around the text, and most other print drivers print a gray background instead of a box.

    fixed
    proportional
    The fixed and proportional attributes have no effect on screen, but when printing to a PostScript printer (lptype=ps or lptype=ps2) they select one of two different fonts. The fonts are configurable in the lib/elvis.ps file; by default fixed text is printed using a Courier font, while proportional is printed using a Times font.

    Printing with a proportional font is a bit quirky though. Elvis' text formatting always assumes fixed-pitch fonts are used, so to keep mixtures of fonts looking good, the PostScript printer driver adjusts the width of each chunk of proportional text to match the width it would have had in a fixed-pitch font. For long segments of proportional text you probably won't notice this, but when an individual word is printed in a proportional font it may be stretched noticibly.

    color
    on color
    These define the foreground and background colors, respectively. In each case, the color is a GUI-dependent string which may contain spaces. Any color that you don't explicitly set will be inherited from normal or some other role.

    The list of supported color names for each GUI is unchanged. Any color names supported by previous versions of elvis should still be supported. See the "User interface" section of the manual for details.

    The "windows" interface now allows any number of different colors to be used, via X11' "#rrggbb" notation. Previously, only a single foreground color plus a single background color could be set this way.

    The "termcap" interface is smart enough to leave colors unchanged if you never explicitly set any foreground and/or background colors. For example, if before starting elvis you set your terminal's background color to blue, and your :color settings only affect the foreground, then the termcap interface will never explicitly change the background color so it should remain blue. (This assumes that the ANSI "^[[0m" escape sequence won't turn off the color.)

    3.1.2 Obsolete options have been removed

    The syntax display mode previously used options named commentfont, stringfont, prepfont, keywordfont, functionfont, otherfont, and variablefont to control the appearance of different parts of the language. Those options are no longer necessary since the :color command can directly assign attributes to text types named "comment", etc. Consequently, those options have been deleted.

    Similarly, the "windows" interface used to have options named boldstyle, emphasizedstyle, fixedstyle, italicstype, normalstyle, and underlinedstyle to control the attributes of fonts. The "x11" interface used to have an "underline" option. Those options have been eliminated, although the Options->Gui... menu item and its dialog remain. The dialog now issues :color commands instead of :set commands.

    However, the "termcap" interface retains its ttyunderline option. That is still necessary because it helps the "termcap" interface avoid problems that occur when underlining and background colors are both used on CGA/EGA/VGA video cards.

    3.1.3 Incomplete code

    I haven't tested any of the Epson-ish print drivers, but I'm pretty confident they'll work because I have verified that the "hp" driver works, and all of those drivers share 98% of their code (in lpescape.c).

    When changing the normal background color of the "windows" GUI window, there are some areas around the outside of the text which aren't redrawn in the new color. If the window is resized, or PAINTed, they're redrawn with the new color, but I can't seem to make that happen automatically. Serge, please check my code at guiwin32/guiwin.c, line 1088, and see if you can figure out what I'm doing wrong.

    I've modified the dialog associated with the Options->Gui... menu item., but it still needs work. In particular, it should be able to set the foreground and background colors, but I haven't been able to get the combo boxes to work correctly yet.

    There is at least one screen glitch in the boxed text: If you delete the last character from boxed text, the right edge of the box is not redrawn.

    I haven't attempted to convert the "vio" user interface. Herbert, that'll have to be your job. The arguments to the (*gui->draw)() and (*gui->color)() functions have changed, and there are two new functions inserted after (*gui->color)() named (*gui->freecolor)() and (*gui->setbg)().

    The new function pointers, (*gui->freecolor)() and (*gui->setbg)(), can both be NULL for vio. The vio version of (*gui->color)() will probably be almost identical to the termcap version. The only function that might cause you grief is (*gui->draw)().

    3.2 Options

    Here's a list of the options added since version 2.1.
    smartargs, sa
    This causes elvis to temporarily display the formal arguments for any function while you're typing in a function call. Specifically, when you input a function name followed by an open parenthesis, elvis performs a tag search on the function name, fetches the source line where the function is defined, and then simulates typing the argument portion of that line and backspacing over it. Since elvis doesn't immediately delete text that you backspace over, you can see the arguments and type over them. This has no effect on the keystrokes that you need to type; it is purely a visual effect.

    This is a global option, but it is only effective while you're in the syntax display mode, because the definitions of "function name" and "open parenthesis" may vary with on your programming language.

    Currently the tag search is performed via the ref program, but this may change in the future. Adding the search code into elvis should make it faster, and also gives the search mechanism access to elvis' tag heuristics.

    In expressions, "feature("smartargs")" will return True if your version of elvis which supports the smartargs feature, and False otherwise. The smartargs option itself always exists in elvis 2.2, even if its behavior isn't supported.

    timestamp
    Each buffer now has a timestamp option. Its value is a string, which will normally be set via the new time function. Elvis doesn't use it for anything internally, but the elvis.arf and elvis.awf functions have been modified to set it, and elvis.bwf has been modified to test it.
    bang
    This option only exists while running elvis.bwf or elvis.awf. It indicates whether the "!" flag was used in a ":w" command. This is important because elvis.bwf is responsible for detecting changes in the file's timestamp, and we want to be able to override that by adding the "!".
    smartcase
    This is a useful option from Vim. When set, it causes ignorecase to be disregarded if the regular expression contains uppercase letters.
    hlsearch
    Another Vim option. When set, executing any search command will cause all matching instances to be highlighted on the screen. (This is different from selections, as in elvis' autoselect option.) The instances will remain highlighted until you give a :nohlsearch command.

    3.3 New functions & other calculator features

    The following features have been added to the built-in calculator. This is used by :if, :let, and others.
    Regular expressions
    The first argument to any function can be a regular expression. This is /-delimited, but is actually passed as a string which begins with a leading /, but without any ending /. This feature was added mostly for the benefit of the current(regexp) feature, described below.
    current(regexp)
    In addition to all the special words that the current() function has previously supported, you can now pass it a regular expression. This can be either a string which starts with a / character, or a literal regular expression as described above.

    The return value will be the matching text. To find this text, elvis starts searching from the beginning of the line, for all non-overlapping instances of text which match the regular expression. When it finds a match which includes the cursor position, it returns that match. If there is no such match, then an empty string is returned.

    For example, current(/./) returns the current character, and current(/\S*/) returns the current whitespace-delimited word (or an empty string if the cursor happens to be on whitespace). Here's a subtle one: current(/..../) divides the line into 4-character chunks and returns the chunk containing the cursor, or "" if the cursor is located after the last complete chunk.

    Using strings instead of literal regular expressions, current("/.") would return the current character, exactly like current(/./). In fact, the current() function can't tell the difference between them, because of the way that regular expressions are parsed.

    ascii(string)
    Return the ASCII value (as a decimal number) of the first character in the string.
    newbuffer(name)
    When invoked with the name of an existing buffer, this function returns "". However, if invoked with the name of a nonexistent buffer, then it creates that buffer and returns the name of it. If the requested name is "" (or is simply omitted) then elvis will create a buffer with a unique name, and return that.

    This is the first function to have a side-effect. I'm not sure I like that.

    Here's an example showing how this might be used.

    	alias man {
    		"Display a man page in a new window
    		local b report=0 nosaveregexp
    		let b = newbuffer()
    		(=b) set bufdisplay=man
    		(=b)split
    		(=b)r !!man !*
    		try (=b)1 s/^Reformatting.*ait\.\.\.$//
    		try (=b)% s/\\/\\\\/g
    		try (=b)% s/_\(.\)/\\fI\1\\fR/g
    		try (=b)% s/.\(.\)/\\fB\1\\fR/g
    		try (=b)% s/\\fR\\fB//g
    		try (=b)% s/\\fR\\fI//g
    		(=b)1 i .nf
    		(=b) set nomod
    	}
    
    
    time(filename)
    Return the timestamp of a file, or the current time if filename is omitted or "". For invalid filenames (such as HTTP URLs), return "". Times are always in the format "YYYY-MM-DDThh:mm:ss"; this is an ISO-8660 time format.

    To implement this, I added a dirtime() function to all of the
    osXXXX/osdir.c files.

    3.4 New ex commands, or changes to existing ones

    The following ex commands are new, or have changed significantly from elvis 2.1.
    :color [role [attributes]]
    Radically changed; see section 3.1, above.
    :push [+line] [file]
    This is exactly like the :edit command, except that :push saves the cursor position on the tag stack.
    :safely excmds
    This temporarily sets the "safer" option while it executes excmds.
    :nohlsearch
    Turns off the highlighting from the hlsearch option.

    3.5 New ports, and new GUI features

    X11 support for scrollwheel
    The "x11" user interface supports mice with a scroll wheel. For instructions on how to configure the mouse under XFree86, start elvis and give the command ":howto scroll wheel".
    Reduced the areas that are insensitive to mouse clicks.
    Clicking on a portion of the text window which doesn't contain text from the file -- for example, line numbers or HTML margins -- used to be totally ignored. Now when you click on those areas, elvis will search rightward to try and find text from the edit buffer, so it can move the cursor to the correct line.

    This is particularly important for WinElvis, since whole lines are selected by dragging the mouse in a narrow strip along the left edge of the window. Previously, this was very difficult to do if the "number" option was turned on. Now it should be easier.

    Improved "windows" printer
    The "windows" lptype will now respect the lpcolumns and lplines settings. Previously, it would change lplines/lpcolumns in order to keep the on-screen font size; now it will change the font size to keep the lpcolumns and lplines values, just like the PostScript lptypes.

    3.6 Miscellany

    ref looks in elvispath
    The ref program has been modified to append elvis' elvispath onto the end of the normal tag path.

    This was done mostly to provide a clean way for ref to act as a reference to the standard C library. Elvis' lib directory now contains an "ansistub.c" file and a "tags" file derived from it. You can now obtain information about a standard C library function by running "ref function", or by moving the cursor onto the function name in an edit buffer and hitting Ctrl-K. It also works well with the new smartargs option.

    Ex addresses can now contain buffer expressions
    When giving an explicit buffer name in an ex command line, you can now use an expression to compute that name. If the first character of the given name is '=' then the remainder of the name is evaluated; the result is used as the real name of the buffer to use.

    This feature was added because using :eval to evaluate buffer names was cumbersome since the parentheses have special meaning in both expressions and ex addresses, and also because :eval affects parentheses and backslashes throughout the line, not just in the buffer name. The following example demonstrates the two techniques, deleting any backspace sequences in the buffer whose name is stored in option x. Clearly, the ":(=x)" version is smaller and easier to understand.

    	:eval \((x)\)%s/.\\b\\\(.\\\)/\\1/g
    	:(=x)%s/.\b\(.\)/\1/g
    Search support more flags
    The visual / and ? commands now allow some new flags to be appended after the regular expression's closing delimiter. The c/i/s flags configure the options for case-sensitive, case-insensitive, and smart sensitivity, and w/x restrict matches to whole word or whole lines.
    Improved printing
    As mentioned previously, the "ps" and "ps2" lptypes now support proportional fonts in a limited way. In addition, "ps", "ps2", and "html" now support the lpcolor option.

    4. The future of elvis

    One of the biggest tasks on my list is to rewrite the ctags program so that it will be able to parse C++ code better. It should read the language descriptions from "elvis.syn", and do at least a half-assed job of generating tags for any language described there. I'm also toying with the idea of a statistical tags generator, but that's still pretty nebulous at this point.

    Windowing will be more versatile. Currently the GUI versions of elvis always split detached windows; sometimes it would be nice if they could be attached to the existing window, as a horizontal or vertical pane.

    I intend to add a true extension language to elvis. The language interface will be general enough to support a variety of languages. The first language supported will probably be PERL, followed rapidly by Python and TCL.

    I'm thinking of modifying the markup display modes (man, tex, and html) to store the list of supported markups, and their effects, in a separate file. That way, you could create your own markups to display nroff -ms, RTF, SGML, and MIME "rich text" documents.

    I'd like to redesign the way elvis assigns assigns buffer names. I'd like to make it always use the full pathname of a file as the buffer name. In addition, I'd like for elvis to store a "current working directory" for each window, and use that to convert a relative buffer name into a the absolute pathname. A similar trick would be used for filenames. When running an external program, elvis would change the real current directory to that window's directory. The benefits of all this:

    • If you're editing "foo" and "./foo", they'll both use the same buffer. This sounds contrived, but a similar thing happens with tag files fairly often.
    • If you do a :cd command, then the old buffers will still write out to their old directories.
    • Different windows could have different directories.
    • The X-windows "-client" flag would behave in a more reasonable manner.
    • The "current directory" could be something other than a local directory. For example, there's no reason you shouldn't be able to ":cd ftp://ftp.sunsite.unc.edu/pub/incoming".

    5. Links to related files

    If the main site (ftp.cs.pdx.edu) is too slow, try the mirror site at ftp.false.com.

    Most of the following are binary files, not text or HTML files, so you can't view then with your Web browser. But you can use your browser to download the files. For Netscape, use <Shift-Click>; for MSIE, use <RightClick> and "download".

    untar.c
    This is the complete source code for "untar", a little program which extracts files from a gzipped tar archive. Comments near the top of "untar.c" describe how to compile and use it. If you already have the gzip and tar utilities, then you don't need this.
    untardos.exe
    This is an MS-DOS executable, produced from the above "untar.c" file. It can also be run under Windows 3.1, in a Dos-prompt window. For brief instructions on how to use untardos, run it with no arguments.
    untarw32.exe
    This is a Win32 executable, produced from the above "untar.c" file. It runs under WindowsNT and Windows95. It runs somewhat faster than the MS-DOS version. It also supports long file names. For brief instructions on how to use untarw32, run it with no arguments, in a text-mode window.

    NOTE: MS-Windows95 and MS-DOS use incompatible methods for mapping long file names to short ones. So if you extract the files under Windows95, DOS programs won't be able to find them with their expected names, and vice versa. Consequently, you must use untardos.exe to unpack elvis-2.1_4-msdos.tar.gz, and untarw32.exe to unpack elvis-2.1_4-win32.tar.gz.

    untaros2.exe
    This is an OS/2 executable, produced from the above "untar.c" file. For brief instructions on how to use untaros2, run it with no arguments.
    elvis-2.1_4.tar.gz
    This is a gzipped tar archive of the source code and documentation for Elvis 2.1 and its related programs.
    elvis-2.1_4-msdos.tar.gz
    This archive contains the documentation and MS-DOS executables for Elvis 2.1.
    elvis-2.1_4-win32.tar.gz
    This archive contains the documentation and Win32 executables for Elvis 2.1. These were compiled and tested under Windows95, but should work under WindowsNT 3.51 (or later) as well.
    elvis-2.1_4-os2.tar.gz
    This archive contains the documentation and OS/2 executables for Elvis 2.1.
    ftp://ftp.fh-wedel.de/pub/fh-wedel/staff/herbert/elvis/00-index.html
    This is where the OS/2 maintainer stores his most up-to-date versions. It may be better than the elvis-2.1_4-os2.tar.gz file, above.