3.3. Checking Spelling Using Ispell

Emacs includes two spell-checking interfaces: to the Unix spell checker, spell, and to Ispell, which many people, including us, prefer. We say "interfaces" because Emacs does not include the executables for either of these spell-checkers. Because Ispell is superior and runs on a variety of platforms, we'll cover only Ispell here. If you attempt to run Ispell and it is not available, you'll have to install it. Chapter 13 provides details on installing Ispell on Windows and on Mac OS X.

A further enhancement to Ispell is Flyspell, a command that highlights misspelled words on the fly. If you have Ispell installed, you'll have Flyspell support as well.

3.3.1 Checking a Buffer

Ispell includes options to check a buffer, a region, the comments in a program, or a single word. 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. Let's spell-check a hastily typed passage from Homer's Odyssey.

Type: Esc x ispell-buffer Enter

Ispell finds the first unrecognized word in the buffer.

Ispell moves to the first unrecognized word, in this case a proper name correctly spelled (except for the proper accent marks). At the top of the screen, Ispell opens a small window that displays alternative spellings, numbered starting with 0. The minibuffer says C-h or ? for more options, SPC to leave unchanged, character to replace word. In this case, we have a properly spelled name, so press i to ask Ispell to insert it into your private dictionary, which is kept in a file called .ispell_<language> in your home directory,^[1] where language is the language you are using (English by default). If this file doesn't exist, Ispell creates it without complaint and later asks you if you want to save it. To insert the word in the dictionary in lowercase, press u and Ispell lowercases the word and then puts it into your dictionary. Of course, because this is a proper name, we insert it as it appears in the passage.

^[1] Your default dictionary might be called something else entirely, like .aspell.language.pws. If you run the command ispell-check-version, you'll see that although Ispell is supposedly running, it's really Aspell behind the scenes.

Press i:

Ispell moves to the next unrecognized word, another proper name.

We insert a few more proper names and move along to the first real misspelling, pwers.

Ispell finds pwers misspelled.

Ispell opens a window at the top of the screen listing choices for a replacement. Usually one of its top few choices is correct.

To select powers, press: 1

Ispell replaces the word and goes on to the next misspelling.

If one of the words that Ispell lists at the top of the screen is correct, you type the number, and Ispell makes the replacement. To replace a word yourself, press r. After you type the corrected word, Ispell replaces it. If you press 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, press a (for accept). Uppercase A has one subtle difference: it tells Ispell to accept the word for this session but only in this buffer.

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

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

Type: R

Ispell asks for the correction for wuld.

Change wuld to would and press Enter.

Ispell starts a query-replace.

We want to replace all occurrences of the misspelled word, so we'll type !, which, as you might recall, means "replace them all without asking."

Type ! then y when prompted about saving your personal dictionary.

Emacs moves to the "next" misspelling, crse.

Ispell replaces the words, then goes on to the next misspelling, crse. Note that this misspelling occurs before the second incorrect wuld. Because we already query-replaced wuld with would, Ispell had to move backward to find the next misspelling.

Remember that Ispell, like all spellcheckers, corrects only true misspellings. If a misspelling forms another word, Ispell will leave it alone. It's up to you to change fries to fires in this passage.

Different forms of the same word must be corrected separately. For example, if you misspell receive, receives, and receiving by reversing the i and the e, you must change each misspelled word.

3.3.2 Checking a Single Word

Sometimes when you are typing, you'll say, "That doesn't look right." To check the word the cursor is on, type M-$ (for ispell-word). 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 options discussed earlier.

3.3.3 Completing a Word

You might start typing a word and then wonder, "How is that spelled?" This is where ispell-complete-word comes in. You're typing a word and you get stuck. Type M-Tab (for ispell-complete-word) and you get a list of choices. After typing occur, you use this command to find out the answer.

Type: occur M-Tab

Ispell choices appear at the top of the screen.

To select occurrence, type: 2

Ispell completes the word for you.

This feature varies in its helpfulness. In this case the replacement needed was shown. It won't always work that way, but you can always simply spell it wrong and then use ispell-buffer to fix it.

3.3.4 Spellchecking on the Fly with Flyspell

Flyspell highlights misspelled words as you type. You can also use it to check existing text. The commands for doing this are different.

To check text as you type, enter Flyspell mode by typing M-x flyspell-mode Enter. Fly appears on the mode line. If you set up Emacs to enter Flyspell mode automatically, your text is always spell-checked "on the fly." An alternative to Flyspell mode is Flyspell prog mode. In this mode, designed for programmers, Emacs highlights misspellings only in comments or strings. To enter it, type M-x flyspell-prog-mode Enter.

To check existing text, you run M-x flyspell-buffer Enter. This command is like ispell-buffer; it spell-checks the entire buffer. Flyspell's interface is different; it underlines all the words it suspects are misspelled and gives you a pop-up menu of alternatives.

The best way to check out Flyspell mode is to turn it on and type some misspelled text to see it in action. No matter whether you enter Flyspell mode or run flyspell-buffer, you correct errors in the same way. We'll demonstrate flyspell-buffer on our misspelled odyssey file. Because it's an existing file (not a new file we're typing), we need to issue the flyspell-buffer command.

Type: Esc x flyspell-buffer Enter

Flyspell highlights misspelled words (Mac OS X).

Flyspell highlights misspelled words in red. Words that are repeatedly misspelled are highlighted in yellow. Note that it doesn't highlight the proper names we inserted in the dictionary earlier using Ispell; Flyspell checks to see whether words are in your personal dictionary before highlighting them as errors.

You move to a misspelled word and press the middle mouse button to display a pop-up menu of possible replacements. (This implies that you have a three-button mouse, and, to be honest, you need one to make Flyspell work properly.) You select a replacement using the mouse.

Move the cursor to crse and press the middle mouse button.

Flyspell displays a pop-up window of alternatives; you choose one with the mouse (Mac OS X).

Choose curse with the mouse.

Emacs inserts the correct replacement (Mac OS X).

Ispell inserts new words in the dictionary. Flyspell takes it a step further, creating word abbreviations for words that you misspell. In essence, a word abbreviation tells Emacs, in this case, that wrd is just an abbreviation for word, and that therefore Emacs should replace it automatically. If you turn on word abbreviation mode, described in the next section, chronic misspellings that Flyspell encounters will be automatically corrected.

How can you tell Flyspell is using word abbreviations? When you exit a session in which you've used Flyspell, you see a prompt that says, Save abbrevs in ~/.abbrev_defs (y or n). This automatic correction won't occur without turning on word abbreviation mode, whether in your startup or manually. Read the section on this topic in this chapter for more details.

What do you do if you encounter a word that's spelled correctly but that Flyspell doesn't recognize? You could insert it in your Ispell dictionary if it's a word you use frequently. The Save word option on the Flyspell pop-up menu handles this. For a temporary fix, the options Accept buffer and Accept session tell Flyspell to accept a word for the current buffer or for all buffers in the current Emacs session automatically. Of course, if it's a word you use frequently, you may want to insert it in the Ispell dictionary to keep Flyspell from flagging it each time.

To enter flyspell mode automatically, add this line to your .emacs file:

(setq-default flyspell-mode t)

Table 3-6 summarizes the Ispell and Flyspell commands.

Table 3-6. Spell-checking commands

Keystrokes	Command name	Action
M-$Tools Spell-Check Word	ispell-word	Check the word the cursor is on or the word following the cursor.
(none)Tools Spell Checking ispell-region	Check spelling of the region.
(none)Tools Spell Checking ispell-buffer	Check spelling of the buffer.
(none)Tools Spell Checking ispell-message	Check spelling of the body of a mail message.
(none)Tools Spell Checking ispell-comments-and-strings	Check spelling of comments and strings in a program.
C-u M-$Tools Continue Spell-Checking	ispell-continue	Resume Ispell; it works only if stopped Ispell with C-g.
(none)	ispell-kill-ispell	Kill the Ispell process, which continues to run in the background after it is invoked.
M-TabTools Complete Word	ispell-complete-word	In text mode, list possible completions for the current word.
(none)Tools Spell Checking Automatic Spell-Checking (Flyspell)	flyspell-mode	Enter the Flyspell minor mode, in which incorrectly spelled words are highlighted.
(none)	flyspell-buffer	Spell-check the current buffer, underlining all misspelled words. Use middle mouse button to correct.