Hour 11: Editing Utilities: Using a Spelling Checker

Sams Teach Yourself Emacs in 24 Hours

Hour 11: Editing Utilities

Sections in this Hour:
Using a Spelling Checker		Summary
Automatically Replacing One String with Another		Q&A
Completing Text from Another Part of the Buffer		Exercises
Transposing and Changing Case

Hour 11
Editing Utilities

Imagine writing a document on a typewriter. When you finish, you ask someone to check the document for you and, when she is finished, you have to type everything once again to reflect the spelling corrections made. Well that was the reality for most people fewer than 10 years ago! Think about it! Today, however, we have spelling checkers, which help us track down spelling errors and, with minimal effort, correct them.

Some of the errors are not real spelling errors but, rather, a problem with your fingers being incapable of typing as fast as your brain thinks. You might, for example, type yuo when you intend to type you. These errors are more appropriately fixed by means other than a spelling checker. This will be discussed later in this section.

Using a Spelling Checker

Replacing a Misspelled Word		On-the-Fly Spell-Checking
Fixing an Error While Spell-Checking		Using the Dictionary to Search for a Word
Accepting a Word		Changing the Spelling Language

Emacs interfaces to the spelling checker program, called ispell, and you can use it to spell-check a single word, a region, or a whole buffer. Furthermore, a library called flyspell exists, which makes it possible to get on-the-fly spell-checking; that is, whenever you type a word, it is spell-checked and, if it contains errors, the word is highlighted and you are offered a menu of suggestions.

Three basic spelling commands exist--ispell-word (bound to M-$), ispell-region, and ispell-buffer. The latter two are not bound to any keys by default. For each word that you request a spell-check on, Emacs looks it up in a dictionary. Every time it's incapable of finding a given word in the dictionary, it searches for near matches and asks you for help. This can be seen in Figure 11.1, where the word forgotton is misspelled.

Figure 11.1
Spell-checking of a buffer using ispell-buffer.

If you should be so lucky that the word you intend to write is one of the suggestions, simply type the number (or, in general, the symbol) next to it, and Emacs continues to the next misspelling.

This is, however, not always the case. The following alternatives exist:

The word is so greatly misspelled that Emacs is incapable of finding it.

The word is a technical term, a foreign-language word, or maybe slang which Emacs does not know about.

The word simply isn't in Emacs's dictionary. This is an important point. Not every dictionary that comes with ispell is complete, so be warned: A word might be spelled correctly, although Emacs says it can't find it.

Replacing a Misspelled Word

When Emacs finds a word that is not in its dictionary it searches for an alternative. Sometimes it fails because the word is too greatly misspelled (such as requcnice for recognize). In these cases either it finds no alternatives at all for you, or none of the alternatives it presents is correct.

In these cases you have to tell it which word is the correct one. To do this, press r (for replace). Emacs asks you for a word to replace the misspelling with, as can be seen in Figure 11.2. It types the word to edit, so you do not need to retype it all to fix the error.

Figure 11.2
Pressing r when spell-checking lets you type the correct word yourself.

When you have typed the correct word (or what you at least think is the correct word), Emacs spell-checks it, to ensure that you do not replace a wrong word with another wrong word.

If the misspelling comes from an assumption that the word should be spelled that way, you might, in fact, misspell it several places in the document. In this case it is useful (and most often time saving) to replace the misspelled word throughout the whole document once and for all. To do this, press R (for Replace). Emacs then asks you for the word to replace with and, when you have told it the word, it does a query-replace throughout the rest of the region or buffer (depending on whether you started ispell-region or ispell-buffer).

Note - At the beginning it might be a bit confusing to you that Emacs invokes query-replace when you are spell-checking but, when you get used to it, you will enjoy the fact that replacing a word when spell-checking is similar to any other kind of replacing. Think about the alternatives! Emacs might instead have offered a button that said "replace all occurrences" and, when you pressed it, all occurrences would be replaced unconditionally. Having this interface would make you ask: "Why can't I have the capability to do query-replace when spell-checking, so I might avoid replacing occurrences that I do not want to replace?" Aha! This is, in fact, what you have now!

In the cases where the word is very misspelled, you might, in fact, be unable to spell it correctly, even when you get a second try. (I find it hard to spell miscellaneous.) In these cases you can ask Emacs to look into the dictionary once again, and this time show you all the words that match a given pattern (That is, the star from patterns is available). Thus in my example, I would ask it to look for words matching miscel. To ask Emacs do this, press l (for list) This can be seen in Figures 11.3 and 11.4.

Figure 11.3
When pressing l during spell-checking, you can ask Emacs to search for a given pattern in the dictionary. Please note that Emacs wasn't able to help me with this word during normal spell-checking.

Figure 11.4
This is the list Emacs shows me, when I ask for miscel*.

Fixing an Error While Spell-Checking

When you are spell-checking you might find that there is an error of some kind in the surrounding text of the word being checked. There are several things you can do about that. Hey! Stop! Haven't we been through this before? Yes, we have! Recursive editing was discussed in Hour 7, "Searching for Text in a Buffer." When you spell-check, it is also possible to do recursive editing. To enter recursive editing, press C-r. If you have forgotten what recursive editing is all about, I strongly suggest that you review Hour 7.

Accepting a Word

There are, of course, also situations where Emacs is incapable of finding a given word in its dictionary, even though the word is perfectly spelled. In these cases, you have to tell Emacs that the word is okay. You can do this in several ways:

You can tell Emacs that this word is okay, and ask it to continue on to the next word. If this word is found once again in another place, Emacs complains once again. This is most useful in situations where you are not entirely certain that the word is spelled correctly, but you do not care to take the time to double-check it. To ask Emacs to continue this way, press the Spacebar.

You can tell Emacs that the word is okay, and ask it to continue spell-checking. If it later finds this word, it ignores it as if it were spelled correctly. This applies only to the current Emacs session. Next time you start Emacs and spell-check the document it complains about the word again. This solution is bound to a (for accept).

If you really believe that this word is spelled correctly, but you recognize it as, for example, being a technical expression, which is likely to be used only in the given buffer, tell Emacs to record this word as correct for this buffer for all future Emacs sessions. Do this by pressing A. The actual recording is done by inserting a section in the button of your document containing the word. This section is inserted in a way that makes it look like a comment. (Thus, in C, it is inserted within /* ... */ ), given, of course, comments exist in the file's major mode. In Figure 11.5 you can see an example of this.

Figure 11.5
ispell dictionary local to a given buffer.

To insert a word in the dictionary in the given buffer, press A (for Accept)

Finally you can tell Emacs to insert the word into your personal dictionary. This means that every subsequent spell-checking operation will think that the given word is okay. Your personal dictionary is located in your home directory under the name .ispell_dictionary-name, where dictionary-name is the name of the dictionary used (see the section "Changing the Spelling Language" ). Press i (for insert) to insert the word in your local dictionary).

Tip - If you find it hard to remember these keys you can always press ? to get a list of the available commands when spell-checking. Furthermore, please note that in the cases where a command is bound to both a lowercase letter and a capital one, the capital one does the most. For example, r replaces the word one time, whereas R replaces the word throughout the rest of the spell region.

On-the-Fly Spell-Checking

An alternative to spell-checking the whole buffer in one go is to do on-the-fly spell-checking; that is, when you finish typing a word, it is spell-checked and, if it is not in the dictionary, the word is highlighted to indicate to you that you need to change this word. The highlighting is active until you correct the word. This can be seen in Figure 11.6.

Figure 11.6
On-the-fly spell-checking.

Windows Notes - GNU Emacs on Windows won't highlight the text, but will beep at you if it detects a misspelling.

To correct the word, you can either edit it or press the second mouse button on top of the word. Pressing the second mouse button brings up a menu with suggestions, such as with ispell (in fact, it is ispell that is invoked behind the scenes). This can be seen in Figure 11.7.

Figure 11.7
Window shown when spell-checking using flyspell-mode.

As mentioned previously, the mode that gives on-the-fly spell-checking facilities to Emacs is called flyspell-mode. This mode comes as the default with XEmacs 20, but not with GNU Emacs 20. For GNU Emacs, you have to install it in your Lisp directory from the CD. The version of ispell.el that comes with XEmacs contains a bug, which causes flyspell.el not to work unless you replace it. See Appendix A, "Installing Functions and Packages from the CD," for a description of this.

Tip - Unless you never write documents that need to be spelled correctly or you never make a spelling error, it's a good idea to have the spelling commands bound to keys. I suggest using the function keys. You might find the following layout useful: F10--Spell word, S-F10--Spell region, C-F10--Spell buffer, and M-F10--toggle fly-spell mode.

Using the Dictionary to Search for a Word

When you are writing, you might find that there is a word that you do not know how to spell. In such a case you might try to spell it, ask ispell to spell-check it for you, and hope that the word is close enough to the real word. If it isn't, ask ispell to search for a word, given a pattern as described in "Replacing a Misspelled Word" earlier this hour. Fortunately there is an easier way: Ask ispell to complete a given word. This is identical to the method described in "Replacing a Misspelled Word," with the exception that you do not need to spell-check the word first. This function is available using the function ispell-complete-word. This function is bound to C-Tab in text mode, and might be bound to this in other modes, but many modes use this key for another purpose. It might, therefore, be a good idea to add this to a function key.

Changing the Spelling Language

Several different dictionaries exist for the ispell package, including German, French, British, and Danish. To change a dictionary, you must invoke the command ispell-change-dictionary. An alternative is to select the dictionary from the menu bar under the Edit, Spell menu.

Caution - The list of dictionaries listed in the menu bar does not reflect which dictionaries are installed on your system! Several additional dictionaries can be downloaded for the ispell program. If the command ispell-word results in a message similar to Can't open /usr/lib/ispell/british.hash, it means that you do not have this dictionary installed.

A given file almost always needs only one dictionary; therefore, it is desirable to specify which language a given file should be spell-checked with. This can be done by inserting the following at the end of the file:


/* Local Variables: */ 
/* ispell-dictionary: "british" */ 
/* End: */

british must be replaced with the dictionary that you want to use. /* and */ should be replaced with the comment characters for the given file. For a further description of this method, please refer to the section "Configuring Options for a Single File" in Hour 22, "Learning Lisp Basics."