Text Processing With Integrated Spell Checking
and
Paragraph Formatting in the Vim and Vi Editors.


Contents

History of Spell Checking

I used ispell for many years integrated into vi by making the following entry in my .exrc file:
    " Spell aids
    map ^w ^[:w^M:!ispell %^M:e! %^M^M

By typing "Control-W" in the command mode the file being edited is saved with the "^[:w" sequence and then ispell is run in a shell by the ":!ispell" string and is passed the current file being edited with the "%" and the command is terminated with the "Control-M" character. The colon character is putting the vi editor into the ex editor mode. Finally the file is re-read into vi by the ":e! %" command. When you edit the .exrc file the "^w" is typed as shift "6" and then type "w". With vi you type "Control-V,ESC" to get "^[" and then "Control-V,Return|Enter" to get "^M". The "Control-V" means hold the control key and type the "V" key. The "Return|Enter" is dependent on your keyboard key labels. Finally it is not a mistake having two "Control-Ms" at the end of the line. You need one to end the ex command to re-read the file and another one to return from the ex command line mode to the visual mode.

Ispell was written by R. E. Gorin in 1971 in assembly code on a PDP-10. It was rewritten in C by Pace Willisson of MIT. Walt Buehring of Texas Instruments added the emacs interface and posted it to the net. Geoff Kuenning added the international support and created the current release. Many others have made contributions to this program.

Given that Windows has come along and that I now need to work on this platform as well I went searching for a portable editor and spelling checker and found Vim and aspell. The author Kevin Atkinson indicates that they will be distributed together for all future versions. This spell checker started with the algorithms used in ispell and add additional checks and has been bench marked against other spell checkers such as MS Word and performs very well.

Aspell Spelling Checker

To integrate this spelling checker into vi you would add the following lines into your .exec file:
    " Integrate aspell spelling checker
    map \s ^[:w^M:!aspell -c --dont-backup "%"^M:e! "%"^M^M

To integrate it into Vim add the following lines into your .vimrc file for UNIX, Linux, Cygwin located in your HOME directory:
    " Integrate aspell spelling checker
    set autowrite
    map <Leader>s <Esc>:!aspell -c --dont-backup "%"<CR>:e! "%"<CR><CR>

For the Windows version of Vim add the same lines into the _vimrc file located where Vim is installed.

Notice that we have put double quotation marks around the % file name macro. The need for this has risen with the Windows users penchant for putting spaces in file and directory names.

Vim uses a more descriptive mapping syntax with the "<CR>;" representing the "Control-M" character and the <Esc> replaces the "^[" or escape character. The "CR" by the way come from carriage return which was part of the old printer control language. The "-c" flag is to check a file and the "--dont-backup" prevents the keeping a back up file. I use the Cygwin environment on Window so that I have some semblance of a useful system and I use the pre-built Graphical User Interface (GUI) Windows version of Vim with the OLE extension so that I can cut and paste with the clip board between Windows applications and the editor.

If you get an error message in Windows that the shell can not find the program then you do not have the programs location in your execution path. For Window 98 and Windows Me you would need to edit the C:\autoexec.bat file and restart your system. For Window NT 4.0 you need to right click on "My Computer", select properties and then select the "Environment" tab. Edit the "Path" variable and then "Apply". For Windows 2000 right click on "My Computer", select the "Advanced" tab and then "Environment". Select the "Path" variable and then "Edit".

You might have noticed the change in mapping characters. When I started testing across different platforms and window managers I found that many character sequences can cause problems. A logical choice might be to use Control-S, but on UNIX that will freeze your Xterm window until you do a Control-Q. This goes back to the old xon/xoff flow control originating with serial communications. On Windows platforms it seems that almost any control sequence is all ready being used by the Windows GUI. So for the Vim editor I settled on starting a map sequence with <Leader> which will get substituted with "map leader" a "\" if not set as it is the only character that does not have a pre-defined command attached to it. For Windows I also ended up adding the following timer adjustment to the _vimrc file as I intermittently had the key map timer expire on me. I believe the need to make this change is system dependent:
    set timeoutlen=2000 - default is 1000 for 1 second time out.

Helpful Settings

In addition to adding a spelling checker I recommend that you add margin settings and auto indentation as follows:
    set textwidth=72 - does not exist in vi use set wrapmargin=8
    set autoindent
    set shiftwidth=4
    set ruler              - does not exist in vi, type ^G to get current line

This will give you 72 columns of text which is generally the maximum a printer will support without compressed characters, clipping the ends of the lines, or doing line wrapping. If you are sending e-mail you may want to narrow your margining even more to allow for the reply interchanges to include "> " for each return reply. So if you expect several you may want to set textwidth equal to 60. It turns on automatic indentation so that if a line is indented subsequent lines will be indented to the same level until further indentation is done or "Control-D" is typed to jump out a level of indentation. The indentation levels are defined by the shiftwidth setting. The set ruler command turns on a ruler at the bottom line of you window which will show the current line and column position.

I recommend that you never change the tab setting of 8 as all other text processing utilities I have ever used, 8 matches the default setting. You can set the "softtabstop=4" and "shiftwidth=2" if you need a fi ner level of indentation. When ever you get 8 spaces in a row they will be replaced by a tab character, "^I". The command ":set list" will let you see tabs dangling spaces at the end of lines and other normally not seen characters. To turn the listing of these characters off do ":set nolist".

Paragraph Formatting

For paragraphs with lines too long you can reformat the paragraph by typing "gqap" which will wrap the current paragraph having no lines longer than your textwidth setting. You can also justify lines by entering; ":s,e left" or indented would be ":s,e left 4". In the examples "s" means starting line number and "e" means ending line number. The last example having a left justified paragraph with an indent of 4 characters. For right justify you would type ":s,e right" or " :s,e right 68", where the last example would be right justified with an indent of 4 characters if our textwidth setting is 72. Two center text the command is "s,e center 72 " where 72 is the width for the center operation. If you want to do the whole file use the syntax would be "% left".

To do justified margining you can use a macro supplied with the Vim editor. You will need to add it to your Vim setup by putting the following line in your Vim configuration file:
    :runtime macros/justify.vim

Or you can just type the above line when you need this functionality in an editing session. To use the macro you would type the following:
    :s,e call Justify( [ textwidth [, maxspaces [, indent] ] ] )
    :s,e call Justify()        - will use the textwidth setting
    :s,e call Justify('',2,) - will use the textwidth setting and limit to 2 consecutive spaces

To reformat long lines in the old vi UNIX you would need to use another utility like fmt. Which can be integrated by adding this into the vi's .exrc file:
    "Format Paragraph:
    map \p ^[{!} fmt

For vim I make an extra map so I can use the same key sequence for vi and vim and besides I have trouble remembering the default one for vim:
    map <Leader>p gqap

For the paragraph formatting we used a new command sequence to process just the current paragraph. Where "{" means move to start of paragraph, "!" filter motion to external command "}" from current location to end of paragraph.

Sadly to say another very useful utility seems to have vanished. The UNIX Writer's Workbench had another useful utility name adj, for adjust, which would do paragraph justification. For the UNIX platforms there is a replacement, the "par" utility which could be used to extend the vi editor.

Dictionary and Thesaurus

Finally we could also integrate in a web browser to take us to our favorite dictionary and thesaurus site as follows:
    map <Leader>d <Esc>:silent !mozilla http://www.m-w.com/&<CR><CR>
or to send the current word
    map <Leader>d <Esc>:silent !mozilla "http://www.m-w.com/cgi-bin/Dictionary?book=Dictionary&va=<cword>"&<CR><CR>
    map <Leader>d <Esc>:silent !mozilla "http://www.m-w.com/cgi-bin/Thesaurus?book=Thesaurus&va=<cword>"&<CR><CR>

For Windows and the Cygwin environment you will need the following syntax:
    map <Leader>d <Esc>:silent !start mozilla http://www.m-w.com/<CR>
    map <Leader>d <Esc>:silent !start mozilla "http://www.m-w.com/cgi-bin/Dictionary?book=Dictionary&va=<cword>"<CR>
    map <Leader>d <Esc>:silent !start mozilla "http://www.m-w.com/cgi-bin/Thesaurus?book=Thesaurus&va=<cword>"<CR>

There are two new syntax items in the line above. The "silent" suppresses output from the command we invoke and the "start" for the Windows platforms runs the program in the background so we can continue the edit session. The silent option is not available in the vi editor.

There is a catch as with all software. In the examples above if the browser Mozilla is running it will prompt you indicating your profile is in use and ask if you want to create a new one. You can pick the default user and it will start a new browser session using a new profile for the default user. Or you can modify the above as follows:
    map <Leader>d <Esc>:silent !mozilla -remote"openurl(http://www.m-w.com/cgi-bin/Dictionary?book=Dictionary&va=<cword>,new-window)"&<CR><CR>
Or you can use new-tab instead of new-window. Of course this example will not work if the browser is not running. So here is a way to combine the above methods so that it will work if the browser is running or not:
    map <Leader>d <Esc>:silent !mozilla -remote "openurl(http://www.m-w.com/cgi-bin/dictionary?book=Dictionary&va=<cword>,new-tab)" \|\| mozilla "http://www.m-w.com/cgi-bin/dictionary?book=Dictionary&va=<cword>""&<CR><CR>

Be prepared that launching a browser such as Mozilla or Firebird takes time if it is not all ready running. I did an experiment using lynx a light weight text only browser which did work in one sense it starts quickly but was not useful as the Merriam-Webster web pages are so graphic over loaded it was very difficult to determine how to navigate the web pages in a text only mode.

References

Other documentation on this information can be found in the users manual that comes with the Vim editor. Section 25, Editing Formatted Text. Section 40, Make New Commands. Also the built in help, ":h map" will give you information about using the map key feature.

For other information on settings which effect line wrapping and indentation, within Vim type:
    :h formatoptions
    :h fo-table
    :h ins-textwidth

Other move commands that are useful are:
    :h *
    :h #

If you do not have all the program execution paths defined in the Windows environment Path variable or you are using Cygwin you may need to set the directory path character for the the shell you are using:
    :h shellslash

Software

The software referred to in this article maybe found at the following locations.

The Vim, Vi IMproved, editor:
    Vim

The aspell spelling checker:
    Aspell

The Cygwin port of UNIX commands to Windows platforms:
    Cygwin

The Mozilla open source web browser:
    Mozilla

Ispell can be down loaded from:
    Ispell

Par paragraph formatter:
    Par

Dictionaries for many languages can be found at this location:
    Dictionaries

Dictionaries for many languages can be found at this location:
    Dictionaries
    The DICT Development Group: Resources