Ispell.el Frequently Asked Questions

Ispell has a long and convoluted history. Originally called SPELL, it was written by Ralph E. Gorin in 1971. That version was written in assembly language for the DEC PDP-10 to run under the WAITS operating system at the Stanford Artificial Intelligence Laboratory. Subsequent versions, also in PDP-10 assembly language, were developed for the BBN TENEX, MIT ITS, and DEC TOPS-10 and TOPS-20 operating systems. It was later revised by W. E. Matson (1974), and W. B. Ackerman (1978), changing its name to ISPELL in the process.

In 1983, Pace Willisson converted this version to the C language and modified it to work under UNIX. This version of ispell only supported plain text and UNIX ROFF formats. Since I (Ken Stevens) was and abysmal speller, and most of the documents I wrote which had to be correctly spelled were written in LaTeX, I added a Tex parser to this version of ispell.

In 1987, Walt Buehring revised and enhanced ispell, and posted it to the Usenet along with a dictionary. Geoff Kuenning picked up this version of the C code, fixed many bugs, and added further enhancements. In 1988 Geoff got ambitious and rewrote major portions of the code, resulting in the table-driven multi-lingual version.

The first emacs interface with ispell was developed by Leigh Klotz in TECO when he was at the MIT AI Lab in 1980. He defined most of the emacs key bindings that are still in use today. By 1987 GNU Emacs had been developed and disseminated by Richard Stallman, and Walt wrote the first version of "ispell.el", the emacs interface we see today.

I was incredibly happy not to hack TECO code anymore, and picked up Walt's ispell.el. Walt had apparently left TI, and I was never able to contact him. Over the years, I have completely rewritten and enhanced his original e-lisp and the result is the version that is now available.

In the early 1990's Richard Stallman desired a version of Ispell to be placed under the copyleft. This resulted in the short-lived ispell version 4.0 that was developed at the FSF and then abandoned in favor of this version of ispell. We decided to keep the current version numbering scheme, so the latest version of ispell is 3.1. The C code remains under a Berkeley-like copyright, and I released ispell.el e-lisp to the copyleft in 1994.

The latest version of ispell.el is maintained on this site. There will always be some variance between what is distributed with GNU Emacs and the ispell source code, since this code is always being improved. Although the code available from this site is under development, it has been tested and is stable enough to be freely distributed.

The version numbers on this code slowly evolve, but I try to update the time stamps as I release changes. If you pick up a version from this site, be sure to look at the date.

Contributions to ispell.el are very welcome! (As you can see, I don't even have enough time to do a good job with this FAQ! ;-)

Ispell.el checks the ispell program for compatibility before launching an interactive spelling session. If an incompatible version is detected, you will receive and error message and the spell session will fail.

Problem: Certain words are incorrectly split in ispell when checked inside emacs. This will typically happen with ISO character sets such as German, Brazilian, etc. For example, the word `Universität' will be split into `Universit' and `t'.

The following are possible reasons for this:

Problem: Ispell will run on the command line but not in emacs when running under cygwin. You may get an error message stating that ispell exited with code 128.

This most likely occurs win the cygwin dll file is not found on your Windoze search path. Cygwin1.dll is responsible for implementing all Unix system calls under Windoze operating systems. The DLL must be found in the search path of any application that uses it, or the app will fail. In the case of Ispell, it will quit with a 128 return code if the DLL is not found.

Make sure that the cygwin DLL, normally located at something like is found on you system's search path. You can determine if this is the case by starting up a new command prompt, and typing:
echo %path%

If you have administrative privileges you can add the cygwin directory to the search path for everyone on the system. You can do this on Win NT, 2000, and XP by using the Control Panel to modify the system PATH variable.

If you lack administrative privileges, you can't change the system PATH variable, but you can define a user PATH in the Control Panel's editor box:

     Variable Name:   [PATH]
     Variable Value:  [D:\CYGWIN\BIN]

Don't type the square brackets! They only represent the text boxes you type into. Don't type the name of the DLL itself, just the directory it is in. Also, if you already have a user PATH variable defined, don't mess it up. Here is how to append to an already-existing PATH:

     Variable Value:  [...;D:\CYGWIN\BIN]

All of this will be appended to your system's PATH at system startup, but only for yourself, not other people.

The case of the variable name and variable value don't matter under Windows.

Newer versions of ispell have a function check-ispell-version which determines whether the current version of ispell on your system is compatible with the e-lisp code in Emacs. Later versions of this function return the ispell version numbers.

Use the following steps to determine your version number(s):

• Use ispell to make sure everything has been loaded. You can do this by typing: M-$ (The Escape key then the $ key), or M-x ispell-word (the Escape key, then the letter x, then ispell-word, then enter).
• Type: M-x check-ispell-version
• The mode-line will contain the version numbers of ispell and ispell.el (if you have a newer version). If the text is too wide to fit on the screen, you can either enlarge the screen (if running under a window system), look in the *messages* buffer for later versions of Emacs, or stuff the result of this function call into a buffer. To load the version line into a buffer: (Only versions of ispell after June 1997 enable this:)
  • Ctl-x Ctl-b *scratch* (or wherever you want this to go)
  • M-x eval-expression
  • (insert (format "%s" (check-ispell-version t)))
• If the above doesn't work, you probably have an older version of ispell. For most versions, the constant ispell-version is defined. You can look its value with the following commands:
  • M-x eval-expression
  • ispell-version

Once you download a new version of ispell.el you need to get it installed. This requires two steps: replacing the old ispell.el file or placing the new one in your "search path" earlier than the old version, and compiling the file.

1. Uncompressing the download.

   Unfortunately there are a number of ways the program will download from the web based on the browser and plugins you are using.
   

   • If the program appears in your browser as text, save the file out with the File | Save As command from in your browser. Be sure to name the file ispell.el
   • If the file is downloaded and remains compressed, you will need to uncompress the file with the command
     gunzip -v ispell.el.gz

2. Placing the new ispell.el in the correct location.

   Emacs uses a "search path" mechanism for finding libraries. The system library directories get loaded by all users. The system directories are typically the last in the search path, which allows one to override the default directories by placing directories earlier in the search path.

   If you want everyone on the system to get the ispell.el upgrade, you either need to put the program in the original system directory or in a directory for "global customizations". The original library directory is called something like `.../lisp' or `.../lisp/ispell'. The global customization directory will usually be named `.../site-lisp'.

   I suggest looking at the current installation, by following the "overwrite" directions below, and if that directory is not writable by you or you deem it unsatisfactory, you should put ispell.el in a new location.

   1. Overwrite the old ispell version with the new.

      This is the best option, but is only possible if you have write permission to the old directory. Following are the steps to do this:

      1. Locate the directory of the ispell version that you are currently using. This is achieved with the command in Emacs:

         M-x locate-library
         ispell.el

         This will tell you where ispell.el is being loaded.

      2. Copy the new ispell.el to this directory and overwrite the old version you will get the new version in your search path.

         You may not want to do this if the load-path is the original install directory, something like: `.../lisp/ispell.el'. In this case, you may want to see the directions for installing in a new directory below.

   2. Place ispell.el in a new directory.

      For widest use, put the program in a "site-lisp" directory. You can determine the search path of your installation with the following steps:

      1. Start a new emacs session with the command
         emacs -q
         This makes sure you only get *system* libraries.
      2. Switch to the *scratch buffer.
      3. Type the following on a new line:
         (mapcan (lambda (x) (and (string-match "site-lisp" x) (cons x nil))) load-path)
         and hit CTL-j
         This will list all of the site-lisp directories in your search path.

         Alternatively, you can list your entire search path by putting the following on a separate line in the *scratch* buffer:
         load-path
         and hit CTL-j
         (you can also get the same effect by evaluating the expression (insert (format "%s" load-path)).)

      If this list has a "site-lisp" directory, you can usually put ispell.el there and it will be in the search path for everyone.

      If you do not want to make the ispell.el upgrade available for everyone, then place ispell.el in your personal site-lisp directory. If you already have one, then you can find it by following the above three steps, except don't do step 1; start emacs as you normally do.

      If you don't have a site-lisp directory, you can create one. To place this directory in your search path, edit your .emacs file, and include something like the following command:
      (set-variable 'load-path (cons (concat (getenv "HOME") "/emacs/site-lisp") load-path))
      where the "emacs/site-lisp" is a directory you created in your home directory in this case. (You can of course make the directory be anywhere you want.)

3. Compile ispell.el

   The next step is to compile the program.

   1. Visit the new ispell.el in emacs buffer. (^X^F DIR/ispell.el)
   2. Execute this command to compile ispell.el:
      M-x byte-compile-file
      ispell.el
      

   This will give you a list of warnings. Most of these are of the sort "undefined variable ..." This should be okay, because ispell.el contains *lots* of dynamic features that depend on variables being set to direct its behavior. If you don't have all the options, then some warnings will be given at compile time.

4. Check installation

   Check to make sure you are getting the correct version by the following steps:

   1. Either start a new emacs session, or execute the following command in the current session:
      M-x load-library
      ispell
      
   2. Check the version number:
      M-x eval-expression
      ispell-version

   This should be the same version number that you downloaded and installed. If this is not the case then execute `M-: locate-library ispell.el' to see which file is actually being loaded.

First you must install ispell. :-) Then follow these easy steps:

Many distributions of Linux provide "ancient" versions of ispell and ispell.el. Most of the problems stem from mixing new and old versions of the ispell program and ispell e-lisp codes. Several interfaces between the program and emacs code have been improved and enhanced over the years, resulting in incompatibilities.

See if the file  ~/.ispell_words  exists. If so, this is a hold-over from the days when ispell only supported English. If this file is found, it will be used as your personal dictionary regardless of the language being used (unless you explicitly redefine the personal dictionary file in the ispell variable  ispell-personal-dictionary).

Modifying or adding dictionary entries to ispell.el can be tricky. You can change them in ispell.el, quit and reload emacs, yet the changes won't appear!

This is the notorious "autoload" bug.

We want emacs to start up quickly, and the menus need to be defined at load time. The solution is to load all the common functions and define the menus at load time. This is accomplished by creating a file "loaddefs.el" which contains all the definitions.

The problem is that this file is created at compile time, so any dynamic changes to the autoloaded definitions typically will not be recognized.

There are two solutions:

1. The global fix:
   • Edit the file loaddefs.el in your load-path to incorporate the new values for ispell-dictionary-alist-1 and ispell-dictionary-alist-2 with the values in the latest version of ispell.el (or with your new or modified dictionary definition).

   • Restarting emacs should then load up the modified dictionary definition and create an updated menu.

2. The local fix:
   I recommend this fix only for debugging new dictionaries. If you update to a new dictionary then you should use the above option. If you don't have access to change loaddefs.el you should have a system administrator do this so everyone can enjoy the new dictionary!
   • Define the dictionaries:

     (setq ispell-dictionary-alist-1 your-new-dictionary-definition)
     (setq ispell-dictionary-alist-2 your-new-dictionary-definition)
     

     (setq ispell-dictionary-alist (append	ispell-dictionary-alist-1
     	ispell-dictionary-alist-2))

     (setq ispell-menu-map nil)
     (load-library "ispell")

   • This will reset your dictionary definitions, and can be put in your .emacs file.

   • If you wish to run this interactively, you can do so with the M-: command or M-x setq ... commands.

   • For XEmacs, set the variable ispell-menu-xemacs to nil rather than the variable ispell-menu-map.

There is a "buffer-local" feature in ispell that allows you to define various features that are local to the particular buffer. One you should already know about is the ability to store misspellings that you want to accept for this buffer but not place in your general dictionary. (For you that don't know about this, you would use the `A' key. :-)

A "buffer-local" feature exists to define the dictionary. There are two methods that can be used, however, we strongly recommend the first method be used since the second may go away in the future.

1. Use emacs local variables.

   Set the variable `ispell-local-dictionary' to the desired dictionary (a string) in emacs' local variables section. For example:

   ;;; Local Variables:
   ;;; ispell-local-dictionary: "castellano"
   ;;; End:
   

2. Use ispell.el's custom keyword `Local IspellDict'.

   Include the following in the bottom of your document:

   ;;; Local IspellDict: "american"

• Capitalization is important.
• You should use the comment syntax appropriate for the buffer. These examples use lisp comments.
• The dictionary name is a string.

This bug has been fixed in ispell version 3.2

Version 3.1.20 contains an irritating bug when using latex that causes all sorts of problems when the backslash is used. (The backslash is a common character in latex that is used, among other things, to create a forced space similar to the tilde character.) In the current version, 3.1.20, the next TWO characters are skipped after a backslash. This can results in misspellings and the file being incorrectly parsed. (For example, if the text contains the sequence `\ $' math mode will not be entered until the matching $ which should end it, resulting in the body of the text not being spell checked and the math region being checked.)

This can be fixed by downloading the patch, installing the patch, and recompiling and installing ispell.

Follow these steps:

When compiling ispell.el you will get a number of warnings like the following:

** reference to free variable start
** reference to free variable end
** assignment to free variable start
** assignment to free variable end
** reference to free variable mh-ins-buf-prefix
** The following functions are not known to be defined: framepop-display-buffer

These messages are normal and can be ignored.

There are two reasons for these messages:

1. The emacs lisp parser reports warnings for variables that are lexically parsed. The variables `start' and `end' are set in their lexical context which produces this error message.
2. Ispell supports numerous optional features. These features have configuration information or functions that are only defined if the feature is used. If you do not use a particular feature (such as `framepop' in the above example) you will get a warning message that variables or functions for that feature are not defined.

All latex environments are not supported in ispell. However, with the general region-skipping ability they can be added.

If you use the AMS tex gather environment a lot, you may want to define it as a region to skip. The following shows you how to do this in ispell.el.

Modify the definition of ispell-tex-skip-alists in ispell.el (or set the variable in your .emacs file). The definition for gather must be added in the delimited section. In the example below it was placed after the verbatim definition:

(defvar ispell-tex-skip-alists
  '((("%\\[" . "%\\]")
     ;; All the standard LaTeX keywords from L. Lamport's guide:
     ;; \cite, \hspace, \hspace*, \hyphenation, \include, \includeonly, \input,
     ;; \label, \nocite, \rule (in ispell - rest included here)
     ("\\\\addcontentsline"              ispell-tex-arg-end 2)
     ("\\\\add\\(tocontents\\|vspace\\)" ispell-tex-arg-end)
     ("\\\\\\([aA]lph\\|arabic\\)"	 ispell-tex-arg-end)
     ("\\\\author"			 ispell-tex-arg-end)
     ("\\\\bibliographystyle"		 ispell-tex-arg-end)
     ("\\\\makebox"			 ispell-tex-arg-end 0)
     ;;("\\\\epsfig"		ispell-tex-arg-end)
     ("\\\\document\\(class\\|style\\)" .
      "\\\\begin[ \t\n]*{[ \t\n]*document[ \t\n]*}"))
    (;; delimited with \begin.  In ispell: displaymath, eqnarray, eqnarray*,
     ;; equation, minipage, picture, tabular, tabular* (ispell)
     ("\\(figure\\|table\\)\\*?"  ispell-tex-arg-end 0)
     ("list"			  ispell-tex-arg-end 2)
     ("program"		. "\\\\end[ \t\n]*{[ \t\n]*program[ \t\n]*}")
     ("verbatim\\*?"	. "\\\\end[ \t\n]*{[ \t\n]*verbatim\\*?[ \t\n]*}")
     ("gather\\*?"	. "\\\\end[ \t\n]*{[ \t\n]*gather\\*?[ \t\n]*}")))
  "*Lists of regions to be skipped in TeX mode.
First list is used raw.
Second list has key placed inside \\begin{}.

Delete or add any regions you want to be automatically selected
for skipping in latex mode.")