Creating Online Help for vi

Michael Harold

Introduction

vi is the text editor users love to hate. In spite of the bad press it receives, however, vi offers several distinct advantages. One: it is free and comes with every copy of UNIX. Two: it can give you access to sophisticated editing functions once you understand its command set. In fact, though, vi remains largely unused precisely because of the cryptic nature of the vi commands. This online help for vi can provide a powerful editing tool for users and developers (and, since administrators often have responsibility for introducing users to vi, make the system administrator's job a little easier).

The software tools described in this article were used to create online help for vi. The same programs which provide online help for vi can be used to provide online help for menus and procedures such as shell scripts and C programs. In addition to creating online help, this simple toolset can be used to generate complex menus and procedures. This article describes this toolset and provides examples of help files, menus, and procedures that were created with it. (An excellent guide to the vi editor, Learning the vi Editor, is available from O'Reilly and Associates.)

The .exrc File

The .exrc file allows a vi user to customize the editor environment to support user-defined commands. When a user executes vi, the user's home directory is checked for an occurrence of the .exrc file. In the following example, the set and map commands are used to custom configure the vi session. An example .exrc file would look like this:

set wrapmargin=10
set aw
set ic
map q :x
map v :!vh main vitxt^M
map V :!forms mainmenu mantxt^M
map M :!forms mainmenu menutxt^M

In this example the set commands set the right margin to 10 characters and autowrap each line as it is entered. The set ic command tells vi to ignore the case of any text strings entered in search commands.

Mapping allows the user to substitute a command string for a vi command character. When the character is pressed in command mode, the character string is substituted and the command is executed. For these purposes, remember to use characters such as "v," "V," "q," or "Q" that are not already defined as vi commands.

The ^M character at the end of each map command is a newline character. To insert a control character in a vi text file, press Ctrl-v followed by the control character you wish to insert. A carriage return is inserted with the sequence Ctrl-v Ctrl-m.

The vh Help Script

The .exrc file maps the character "v" to the command:

:!vh main vitxt

The ":" character makes a call to the ex editor (which is contained within the vi editor). The "!" character tell vi to spawn a new shell. The shell command following the "!" is optional.

The vh shell script is shown in Listing 1. The first argument is a keyword within the help file which identifies the menu or text to be displayed. The second argument is the file name of the help file. An abbreviated example of a help file is shown in Listing 2. In this example the keyword is main and the help file is vitxt.

Once the vi "menu" is displayed, the user is asked to enter the vi command for which help is needed. The user enters a command and the vh script displays the online help associated with that command. Upon exiting the help screen, the user is returned to the vi editor.

Online man Pages

The .exrc file maps the character "V" to the command:

:!forms mainmenu mantxt

The forms shell script is shown in Listing 3 and is an expanded form of the vh shell script. The first argument, mainmenu, specifies a label in the command file which is identified by the second argument. Any lines preceeded by the label are sent to standard output.

The program also allows the association of procedures with displayed text. For any given label (mainmenu), procedures associated with that label may be identified with a special procedure label (mainmenu p). Those lines labeled as procedures are written to a file which is then executed.

A special file named formkey is used to contain the next label to be processed. This allows the creation of decision procedures within the help file.

An example of an online help menu for commonly used UNIX commands is provided in Listing 4. The combination of online help for vi and the man pages within the vi editor can be very useful to developers new to the UNIX environment.

Menus and Procedures

The forms program can also be used to create menus and online help for menus and procedures. An example of a "desktop" menu system is provided in Listing 5. This menu contains examples of user-defined online help as well as help from the man pages.

The .exrc file maps the character "M" to the command:

:!forms mainmenu menutxt

The forms command used to execute the menu from the shell command line is:

$ forms mainmenu menutxt

Menus created in this manner can access other help files and can contain complex procedures. Programmers and analysts will find this feature very useful. For example, a programmer can edit a source file, save it, recompile it, display the error listing, and make corrections in the program source without ever leaving the vi editor.

About the Author

Michael Harold is a systems analyst/programmer currently employed by Willis-Knighton Medical Center in Shreveport, Louisiana. He has worked with UNIXsystems for thirteen years as an educator, systems administrator, database administrator, and application developer.