Learning GNU Emacs, Second Edition

Checking Spelling

Emacs spell checks in one of two ways: using Ispell or using the UNIX spell checker, spell. In our opinion, Ispell is the better choice, so we’ll discuss it first.

Before we start, let’s talk about spell checkers. Spell checkers have lists of words that they recognize, called dictionaries. The spell checker doesn’t recognize any word that’s not in the dictionary and so thinks that word is misspelled. Both of the spell checkers we discuss allow you to skip over words that are actually correct but unrecognized (like names and other proper nouns or technical terms). Better, you can insert these additional words into a personal dictionary file, so the spell checker will recognize them. Of course, spell checkers are no substitute for real proofreading; they can’t find errors like the substitution of to for two or too, for example. Despite their limitations, we think spell checkers are one of the great inventions of the modern world. So read on to learn how to use them with Emacs.

Using Ispell

Ispell has options to check a buffer, a region, a mail message or a single word. ^[19]After you type the command telling Ispell what area you want to check, it works the same way for all these options. We’ll describe ispell-buffer here. If all the words are spelled correctly, Ispell displays the message, Spell-checking done. If Ispell finds a misspelled word, a screen like the following appears.

Type: ESC x ispell-buffer RETURN

Ispell moves to the first unrecognized word.

The minibuffer says C-h or ? for more options. Since this is the first time you are using Ispell, type ? to see what the options are.

Type: ?

Ispell displays a list of options.

If one of the words that Ispell lists at the top of the screen is correct, you can type the number, and Ispell makes the replacement. In this case, you would type 1. To replace a word yourself, type r. After you type the corrected word, Ispell rechecks it. If you type R instead, Ispell starts a query-replace through which you can correct all cases of the misspelling in this buffer.

Instead of replacing the word, you may simply want Ispell to skip over it. To skip this occurrence of a misspelled word, press SPACE. To ignore a misspelled word for the rest of the session for all buffers, type a (for accept). Typing uppercase A has one subtle difference: it tells Ispell to accept the word for this session but only in this buffer.

If you encounter this word again and it really is spelled correctly, type i to ask Ispell to insert it into your private dictionary, which is kept in a file called ispell.words in your home directory. If this file doesn’t exist, Ispell creates it without complaint. If you want Ispell to insert the word in the dictionary uncapitalized, type u and Ispell lowercases the word and then puts it into your dictionary.

If you can see that something more complicated is wrong and you want to fix it yourself, you can start a recursive edit by typing C-r. Fix the error, type ESC C-c to exit the recursive edit, and resume Ispell. (You may recall we discussed recursive editing earlier in this chapter.)

Since our memo repeatedly spells receive incorrectly and typing the character beside the correct word only replaces a single incidence, a better choice would be to type R to query-replace the word throughout the buffer.

Type: R

Ispell asks for the correction for recieve.

Change recieve to receive and press RETURN

Ispell starts a query-replace.

Since we want to replace all occurrences of the misspelled word, we’ll type !, which means “replace them all without asking.”

Type: !

Ispell replaces the words, then goes on to the next misspelling, weve.

Type: 7 to select we’ve

Ispell corrects weve, then goes on to the next misspelling.

We corrected recieve earlier, but since Ispell considers recieved to be another word, the spell checker finds it as a separate misspelling. ^[20]

Type: 1

Ispell finished spell checking.

Checking a single word

Sometimes when you are typing, you’ll say, “Now how is that spelled?” or “That doesn’t look right.” To check the word the cursor is on, type ESC $ (for ispell-word) or select Check Word from the Spell menu. Ispell checks the spelling of the word and displays word : ok if the word is spelled correctly. If the word is incorrect, Ispell displays a window with the same options we discussed earlier.

If you can’t remember how to spell a word, type a few letters and press ESC TAB (for ispell-complete-word). Ispell lists possible completions for the word, and you type a character to select one. Note that Ispell’s completion feature works only in text mode. (It works in a few other modes for marking up text, such as nroff mode. ESC TAB means something else in programming modes, however.) Let’s say that we have trouble spelling disambiguate.

Type: dis ESC TAB

Press 2 to select the correct spelling for disambiguate.

The Ispell process

Once you use Ispell, it runs in the background until you need it again. To kill the Ispell process (if it’s slowing down the system), type ESC x ispell-kill-ispell or select Kill Process from the Spell menu.

Table 3-6 summarizes the Ispell commands, including options from the Spell menu.

Table 4-6. Ispell Commands

Keystrokes	Command Name	Action
ESC $	ispell-word	Check the word the cursor is on or the word following the cursor.
Edit→Spell→Check Word
(none)	ispell-region	Check spelling of all words in region.
Edit→Spell→Check Region
(none)	ispell-buffer	Check spelling of all words in buffer.
Edit→Spell→Check Buffer
(none)	ispell-message	Check spelling of all words in the body of a mail message.
Edit→Spell→Check Message
C-u ESC $	ispell-continue	Resume Ispell; it works only if you’ve already been running Ispell and stopped it with C-g.
Edit→Spell→Continue Check
(none)	ispell-kill-ispell	Kill the Ispell process.
Edit→Spell→Kill Process
ESC TAB	ispell-complete-word	In text mode, list possible completions for the current word.
Edit→Spell→Complete Word

Using the UNIX Spell Checker

Emacs also has an interface to the UNIX spell checker. You can check a word, a buffer, or a region. Emacs looks up the words in a dictionary supplied by UNIX.

The spell-word command checks the word the cursor is on (or the word preceding the cursor if you are between words). It begins by printing the message

Checking spelling of word

in the minibuffer; this message tells you that the search is going on, and that you shouldn’t do any editing. If the word is spelled correctly, Emacs tells you so. If Emacs doesn’t think the word is spelled correctly, it displays the message

               word is not recognized; edit a replacement: word

If the word is correct but not in the dictionary (for example, a proper name), press RETURN. If a word is incorrect, use the standard Emacs editing commands to correct it. Emacs then starts a query-replace and shows you the word in context. You use query-replace responses in telling Emacs whether or not to replace the word—that is, press SPACE to correct the spelling, C-g to quit and do nothing, or n to do nothing and go on to the next occurrence of the misspelled word. See Section 3.2.2 earlier in this chapter for a complete list of responses. For example, here’s how to correct our memo by using the UNIX spell checker.

Type: ESC x spell-word RETURN

Correct the spelling of recieve in the minibuffer. When you’re finished, type a RETURN, and the query-replace starts.

Correct the spelling and press RETURN.

Type SPACE to make the replacement and go on to the next misspelling of receive.

Press: SPACE

Continue until you’ve finished the entire buffer.

The spelling facility has two features that might confuse you:

• The spell-word command checks the entire buffer for misspellings of the word you give it. It starts at the beginning and works to the end. Therefore, when it begins the query-replace, it moves the cursor to the first occurrence of your word (in this case, recieve) in the buffer—not necessarily the word that you’re on.

• The spell-word command checks for only whole words. In our example, it fixes recieve, but not recieved. However, if you notice that recieved is misspelled, there’s no reason you can’t use a recursive edit to fix it.

To check the spelling of an entire buffer, type ESC x spell-buffer RETURN. Emacs then starts searching for incorrect words at the beginning of the buffer. Whenever it finds an incorrect word, it prints the message

               word is not recognized; edit a replacement: word

If the word is really spelled correctly, press RETURN (just as you would with spell-word), and Emacs goes on to the next misspelled word. If the word is incorrect, use standard editing commands to fix it. Emacs then enters a query-replace (as with spell-word), giving you an opportunity to fix the word wherever it appears in the buffer. When the query-replace is finished, Emacs continues with the next misspelled word.

You can also check the spelling of a selected region of text. Put a mark at one end of the region, move the cursor to the other end, and give the command ESC x spell-region RETURN. The behavior of spell-region is identical to spell-buffer.

If you confirm the spelling of a word (by pressing RETURN), Emacs won’t ask you about it again for this buffer during this session. However, this “memory” only applies to spell-buffer and spell-region; it does not apply to spell-word.

Adding words to the UNIX spell checker’s dictionary

You can save any special spellings (for example, personal names) in a .spell file. To take advantage of this feature, you change the value of the variable spell-command, which gives the UNIX command that Emacs uses to check spelling. By default, the value of this variable is spell. Change the value of spell-command to spell +.spell by adding this line to your .emacs file:

(setq spell-command "spell +.spell")

Notice the space between spell and the plus sign and the lack of space between the plus sign and .spell. Save the .emacs file and reenter Emacs to have this line take effect. Then put your personal spellings into a file called .spell. This file must be sorted alphabetically and may contain only one word per line. Note that this command requires a different .spell file in every directory. That’s appropriate for most applications: each project you work on may have a separate list of special spellings (names, technical words, and so on).

Table 3-7 summarizes the commands for using spell.

Table 4-7. UNIX Spell-Checking Commands

Keystrokes	Command Name	Action
(none)	spell-word	Check spelling of the word the cursor is on or in front of.
(none)	spell-buffer	Check spelling of the current buffer.
(none)	spell-region	Check spelling of the current region.

---

^[19] The interface to Ispell is easy to use if it’s working. Try it, and if you have problems, come back and read this note. Emacs requires Ispell Version 3.1.x. If you have Ispell Version 4 installed, it won’t work. In some early versions of Emacs 19, we encountered problems with the Emacs-Ispell interface, so if you have problems, you’re not alone. See the last section in this chapter for some suggestions.

^[20] Notice that Ispell’s use of query-replace is slightly different in this way. A regular query-replace would find all instances of recieve, whether it was part of another word (as in recieved) or not. In Ispell and in the UNIX spell checker, which we’ll discuss shortly, different word forms are considered to be different words.