1 <!-- This HTML file has been created by texi2html 1.29
2 from ispell.texi on 23 April 1994 -->
4 <TITLE>GNU ISPELL V4.0 - GNU ISPELL
</TITLE>
5 <P>Go to the
<A HREF=
"ispell_1.html">previous
</A> section.
<P>
6 <H1><A NAME=
"SEC2" HREF=
"ispell_toc.html#SEC2">GNU ISPELL
</A></H1>
7 <CODE>Ispell
</CODE> is a program that helps you to correct typos in a file,
8 and to find the correct spelling of words. When presented with a
9 word that is not in the dictionary,
<CODE>ispell
</CODE> attempts to find
10 <DFN>near misses
</DFN> that might include the word you meant.
12 This manual describes how to use ispell, as well as a little about
15 <H2><A NAME=
"SEC3" HREF=
"ispell_toc.html#SEC3">Using ispell from emacs
</A></H2>
17 <H3><A NAME=
"SEC4" HREF=
"ispell_toc.html#SEC4">Checking a single word
</A></H3>
19 The simplest emacs command for calling ispell is 'M-$' (meta-dollar.
20 On some terminals, you must type ESC-$.) This checks the spelling of
21 the word under the cursor. If the word is found in the dictionary,
22 then a message is printed in the echo area. Otherwise, ISPELL
23 attempts to generate near misses.
25 If any near misses are found, they are displayed in a separate window,
26 each preceded by a digit. If one of these is the word you wanted,
27 just type its digit, and it will replace the original word in your
30 If no near miss is right, or if none are displayed, you
36 Insert the word in your private dictionary. Use this if you
37 know that the word is spelled correctly.
41 Accept the word for the duration of this editing session, but do not
42 put it in your private dictionary. Use this if you are not sure about
43 the spelling of the word, but you do not want to look it up
44 immediately. The next time you start ispell, it will have forgotten
45 any accepted words. You can make it forget accepted words at any time
46 by typing
<KBD>M-x reload-ispell
</KBD>.
50 Leave the word alone, and consider it misspelled if it is checked again.
54 Replace the word. This command prompts you for a string in the
55 minibuffer. You may type more than one word, and each word you type
56 is checked again, possibly finding other near misses. This command
57 provides a handy way to close in on a word that you have no idea how
58 to spell. You can keep trying different spellings until you find one
59 that is close enough to get a near miss.
63 Lookup. Display words from the dictionary that contain a
64 specified substring. The substring is a regular expression,
65 which means it can contain special characters to be more
66 selective about which words get displayed.
67 See section `Regexps' in
<CITE>emacs
</CITE>.
<P>
68 If the only special character in the regular express is a leading
69 <CODE>^
</CODE>, then a very fast binary search will be used, instead of
70 scanning the whole file.
72 Only a few matching words can be displayed in the ISPELL window.
73 If you want to see more, use the
<CODE>look
</CODE> program directly from
77 Of course, you can also type ^G to stop the command without
80 If you make a change that you don't like, just use emacs' normal undo
81 feature See section `undo' in
<CITE>emacs
</CITE>.
83 <H3><A NAME=
"SEC5" HREF=
"ispell_toc.html#SEC5">Checking a whole buffer
</A></H3>
85 If you want to check the spelling of all the words in a buffer, type
86 the command
<KBD>M-x ispell
</KBD>. This command scans the file, and makes
87 a list of all the misspelled words. When it is done, it moves the
88 cursor to the first word on the list, and acts like you just typed M-$
89 See section
<A HREF=
"ispell_2.html#SEC4">Checking a single word
</A>.
91 When you finish with one word, the cursor is automatically moved to the
92 next. If you want to stop in the middle of the list type
<KBD>Q
</KBD> or
93 <KBD>^G
</KBD>. Later, you can pick up where you left off by typing
96 <H3><A NAME=
"SEC6" HREF=
"ispell_toc.html#SEC6">Checking a region
</A></H3>
98 You may check the words in the region with the command M-x ispell-region.
99 See See section `mark' in
<CITE>emacs
</CITE>.
101 The commands available are the same as for checking a whole buffer.
103 <H2><A NAME=
"SEC7" HREF=
"ispell_toc.html#SEC7">Old Emacs
</A></H2>
105 Until ispell becomes part of the standard emacs distribution, you will
106 have to explicitly request that it be loaded. Put the following lines
107 in your emacs init file See section `init file' in
<CITE>emacs
</CITE>.
110 (autoload 'ispell
"ispell" "Run ispell over buffer" t)
111 (autoload 'ispell-region
"ispell" "Run ispell over region" t)
112 (autoload 'ispell-word
"ispell" "Check word under cursor" t)
113 (define-key esc-map
"$" 'ispell-word)
116 (It will do no harm to have these lines in your init file even after
117 ispell is installed by default.)
119 <H2><A NAME=
"SEC8" HREF=
"ispell_toc.html#SEC8">Using ispell by itself
</A></H2>
121 To check the words in a file, give the command
<CODE>ispell FILE
</CODE>. This
122 will present a screen of information, and accept commands for every word
123 that is not found in the dictionary.
125 The screen shows the offending word at the top, as well as two lines of
126 context at the bottom. If any near misses are found, they are shown in the
127 middle of the screen, each preceded by a digit.
129 You may use the same commands as inside of emacs to accept the word,
130 place it in your private dictionary, select a near miss, or type a
131 replacement See section
<A HREF=
"ispell_2.html#SEC4">Checking a single word
</A>. You may also choose from the following
137 Print a help message.
140 <DD>Quit. Accept the rest of the words in the file and exit.
143 <DD>Exit. Abandon any changes made to this file and exit immediately. You
144 are asked if you are sure you want to do this.
147 <DD>Shell escape. The shell command that you type is executed as
151 <DD>Suspend. On systems that support job control, this suspends ISPELL.
152 On other systems it executes a subshell.
155 <DD>Redraw the screen.
158 If you type your interrupt character (usually ^C or
<KBD>DEL
</KBD>), then
159 ispell will immediately enter its command loop. If ispell was generating
160 near misses at the time, then all that it had found so far will be
161 displayed, along with a message stating that there might be more, and that
162 you can type
<KBD>RET
</KBD> to generate them. If it was scanning the file, it
163 will display
<SAMP>`(INTERRUPT)'
</SAMP> where it would normally display a bad word,
164 and the commands that change the file will be disabled.
166 The feature is handy if you have left out a space between words, and
167 ispell is futilely looking up the
1000 potential near misses for a
168 string that has twenty letters.
170 <H2><A NAME=
"SEC9" HREF=
"ispell_toc.html#SEC9">Using ispell to look up individual words
173 When ispell is run with no arguments, it reads words from the standard
174 input. For each one, it prints a message telling whether it is in the
175 dictionary. For any words not in the dictionary, near misses are
176 computed, and any that are found are printed.
181 how about: independent
187 <H2><A NAME=
"SEC10" HREF=
"ispell_toc.html#SEC10">Your private dictionary
</A></H2>
189 Whenever ispell is started the file
<TT>`ispell.words'
</TT> is read from your
190 home directory (if it exists). This file contains a list of words, one per
191 line, and neither the order nor the case of the words is important. Ispell
192 will consider all of the words good, and will use them as possible near
195 The
<KBD>I
</KBD> command adds words to
<TT>`ispell.words'
</TT>, so normally you
196 don't have to worry about the file. You may want to check it from
197 time to time to make sure you have not accidentally inserted a
200 <H2><A NAME=
"SEC11" HREF=
"ispell_toc.html#SEC11">Compatibility with the traditional spell program
203 The
<SAMP>`-u'
</SAMP> flag tells ispell to be compatible with the traditional
204 <SAMP>`spell'
</SAMP> program. This flag is automatically turned on if the
205 program is invoked by the name
<SAMP>`spell'
</SAMP>.
207 This flag causes the following behavior:
209 All of the files listed as arguments (or the standard input if none)
210 are checked, and misspellings are printed on the standard output. The
211 output is sorted, only one instance of each word appears (however,
212 a word may appear more than once with different capitalizations.)
214 You may specify a file containing good words with
<SAMP>`+filename'
</SAMP>.
216 The troff commands
<SAMP>`.so'
</SAMP> and
<SAMP>`.nx'
</SAMP> (to include a file, or
217 switch to a file, respectively) are obeyed, unless you give the flag
220 The other
<SAMP>`spell'
</SAMP> flags
<SAMP>`-v'
</SAMP>,
<SAMP>`-b'
</SAMP>,
<SAMP>`-x'
</SAMP> and
221 <SAMP>`-l'
</SAMP> are ignored.
223 By the way, ispell seems to be about three times faster
224 than traditional spell.
226 <H2><A NAME=
"SEC12" HREF=
"ispell_toc.html#SEC12">All commands in emacs and standalone modes
229 Commands valid in both modes:
231 DIGIT Select a near miss
232 I Insert into private dictionary
233 A Accept for this session
235 R Replace with one or more words
236 L Lookup: search the dictionary using a regular expression
240 Q Accept rest of file
246 ^C Give up generating near misses, or show position in file
251 M-x ispell Check buffer
252 M-x ispell-region Check region
253 M-x reload-ispell Reread private dictionary
254 M-x kill-ispell Kill current subprocess, and start a new one
256 ^G When in M-x ispell, stop working on current
258 ^X $ Resume working on bad word list.
260 <H2><A NAME=
"SEC13" HREF=
"ispell_toc.html#SEC13">Definition of a near miss
</A></H2>
262 Two words are near each other if they can be made identical with one
263 of the following changes to one of the words:
266 Interchange two adjacent letters.
272 Someday, perhaps ispell will be extended so that words that sound
273 alike would also be considered near misses. If you would like to
274 implement this, see Knuth, Volume
3, page
392 for a description of the
275 Soundex algorithm which might apply.
277 <H2><A NAME=
"SEC14" HREF=
"ispell_toc.html#SEC14">Flags to the ispell command
</A></H2>
279 Ispell's arguments are parsed by getopt(
3). Therefore, there is
280 considerable flexibility about where to put spaces between arguments.
281 The way to be safe is to give only one flag per dash, and put a space
282 between a flag and its argument.
284 If ispell is run with no arguments, it enters
<SAMP>`ask'
</SAMP> mode See section
<A HREF=
"ispell_2.html#SEC9">Using ispell to look up individual words
286 With one or more file name arguments, it interactively checks each one.
289 <DT><CODE>-p privname
</CODE>
290 <DD>Use privname as the private dictionary.
292 <DT><CODE>-d dictname
</CODE>
293 <DD>Use dictname as the system dictionary. You may also specify a system
294 dictionary with the environment variable ISPELL_DICTIONARY.
297 <DD>List mode. Scan the file, and print any misspellings on the standard
298 output. This mode is compatible with the traditional spell program,
299 except that the output is not sorted. See section
<A HREF=
"ispell_2.html#SEC11">Compatibility with the traditional spell program
303 <DD>Compatibility mode. See section
<A HREF=
"ispell_2.html#SEC11">Compatibility with the traditional spell program
307 <DD>Old style program interface, See section
<A HREF=
"ispell_2.html#SEC15">How other programs can use ispell
311 <DD>New program interface, See section
<A HREF=
"ispell_2.html#SEC15">How other programs can use ispell
315 <DD>Print the dictionary on the standard output with flags.
318 <DD>Print the dictionary on the standard output with all flags expanded.
322 <H2><A NAME=
"SEC15" HREF=
"ispell_toc.html#SEC15">How other programs can use ispell
</A></H2>
324 Ispell can be used as a subprocess communicating through a pipe. Two
325 interfaces are available:
327 <H2><A NAME=
"SEC16" HREF=
"ispell_toc.html#SEC16">New style, for EMACS
</A></H2>
329 To use this interface, start ispell with the '-S' flag. Ispell will
330 print a version number and greeting message that looks like:
336 The number is the version number of the protocol to be spoken over
337 the pipe. The string is a message possibly of interest to the user.
339 All messages from ispell end in an equal sign, and ispell guarantees not to
340 print an equal sign except to end a message. Therefore, if you do not want
341 to deal with the greeting, just throw away characters until you get to an
344 Ispell then reads one line commands from the standard input, and
345 writes responses on the standard output.
347 If a command does not start with a colon, then it is considered a
348 single word. The word is looked up in the dictionary, and if it is
349 found, the response is
<CODE>t
</CODE>. If the word is not in the
350 dictionary, and no near misses can be found, then the response is
351 <CODE>nil
</CODE>. If there are near misses, the response is a line containing
352 a list of strings in lisp form. For example:
357 teh (
"tea" "ten" "the")
359 The near miss response is suitable for passing directly to the lisp
360 <CODE>read
</CODE> function, but it can also be parsed simply in C. In
361 particular, ispell promises that the list will appear all on one line,
362 and that the structure will not change. A parser that reads the whole
363 line, then treats the parentheses and quotes as whitespace will work fine.
365 The list will contain a maximum of ten strings, and each string will be
366 no longer than
40 characters. Also, the capitalization of the near
367 misses is the same as the input word.
369 <H3><A NAME=
"SEC17" HREF=
"ispell_toc.html#SEC17">Colon commands
</A></H3>
371 If the input line starts with a colon, then it is one of the following
374 <CODE>:file
<VAR>filename
</VAR></CODE>
375 Run the word checker over the named
<VAR>filename
</VAR>. The response is zero or
376 more lines each containing a number. The numbers are file offsets of
377 words that do not appear in the dictionary. Since the near miss
378 checker is not run, this is fairly fast.
380 After the last number, there will be a line containing either
<CODE>t
</CODE> if
381 the checker got to the end of the file, or
<CODE>nil
</CODE> if it received an
382 interrupt. If ispell ignores any interrupts received except while
385 <CODE>:insert
<VAR>word
</VAR></CODE>
386 Place
<VAR>word
</VAR> in the private dictionary.
388 <CODE>:accept
<VAR>word
</VAR></CODE>
389 Do not complain about
<VAR>word
</VAR> for the rest of the session.
392 Write the private dictionary.
395 Reread the private dictionary.
398 Enable the tex parser for future
<CODE>:file
</CODE> commands.
401 Enable the tex parser for future
<CODE>:file
</CODE> commands.
403 <CODE>:generic
</CODE>
404 Disable any text formatter parsers for future
<CODE>:file
</CODE> commands.
406 <H2><A NAME=
"SEC18" HREF=
"ispell_toc.html#SEC18">Old style, like ITS
</A></H2>
408 To use this interface, start ispell with the '-a' flag. Ispell
409 will read words from its standard input (one per line), and write
410 a one line of output for each one.
412 If the first character of the line is
<CODE>*
</CODE>, then word was found in the
413 dictionary. (Other versions of ispell made a distinction between words
414 that were found directly, and words that were found after suffix
415 removal. These lines began with
<CODE>+
</CODE>, followed by a space, then
416 followed by the root word. To remain compatible with these version,
417 treat
<CODE>+
</CODE> and
<CODE>*
</CODE> the same.)
419 If the line starts with
<CODE>&</CODE>, then the input word was not found, but
420 some near misses were found. They are listed on the output line
421 separated by spaces. Also, the output words will have the same
422 capitalization as the input.
424 Finally, if the line starts with
<CODE>#
</CODE>, then the word was not in the
425 dictionaries, and no near misses were found.
430 teh
& tea ten the
432 <H2><A NAME=
"SEC19" HREF=
"ispell_toc.html#SEC19">How the suffix stripper works
</A></H2>
434 This section is excerpted from the ITS spell.info file.
436 Words in SPELL's main dictionary (but not the private dictionary) may
437 have flags associated with them to indicate the legality of suffixes
438 without the need to keep the full suffixed words in the dictionary. The
439 flags have
"names" consisting of single letters. Their meaning is as
442 Let # and @ be
"variables" that can stand for any letter. Upper case
443 letters are constants.
"..." stands for any string of zero or more
444 letters, but note that no word may exist in the dictionary which is not at
445 least
2 letters long, so, for example, FLY may not be produced by placing
446 the
"Y" flag on
"F". Also, no flag is effective unless the word that it
447 creates is at least
4 letters long, so, for example, WED may not be
448 produced by placing the
"D" flag on
"WE".
451 ...E --
> ...IVE as in CREATE --
> CREATIVE
452 if # .ne. E, ...# --
> ...#IVE as in PREVENT --
> PREVENTIVE
455 ...E --
> ...ION as in CREATE --
> CREATION
456 ...Y --
> ...ICATION as in MULTIPLY --
> MULTIPLICATION
457 if # .ne. E or Y, ...# --
> ...#EN as in FALL --
> FALLEN
460 ...E --
> ...IONS as in CREATE --
> CREATIONS
461 ...Y --
> ...ICATIONS as in MULTIPLY --
> MULTIPLICATIONS
462 if # .ne. E or Y, ...# --
> ...#ENS as in WEAK --
> WEAKENS
465 ...Y --
> ...IETH as in TWENTY --
> TWENTIETH
466 if # .ne. Y, ...# --
> ...#TH as in HUNDRED --
> HUNDREDTH
469 ... --
> ...LY as in QUICK --
> QUICKLY
472 ...E --
> ...ING as in FILE --
> FILING
473 if # .ne. E, ...# --
> ...#ING as in CROSS --
> CROSSING
476 ...E --> ...INGS as in FILE --> FILINGS
477 if # .ne. E, ...# --> ...#INGS as in CROSS --> CROSSINGS
480 ...E --> ...ED as in CREATE --> CREATED
481 if @ .ne. A, E, I, O, or U,
482 ...@Y --> ...@IED as in IMPLY --> IMPLIED
483 if # .ne. E or Y, or (# = Y and @ = A, E, I, O, or U)
484 ...@# --> ...@#ED as in CROSS --> CROSSED
485 or CONVEY --> CONVEYED
488 ...E --> ...EST as in LATE --> LATEST
489 if @ .ne. A, E, I, O, or U,
490 ...@Y --> ...@IEST as in DIRTY --> DIRTIEST
491 if # .ne. E or Y, or (# = Y and @ = A, E, I, O, or U)
492 ...@# --> ...@#EST as in SMALL --> SMALLEST
493 or GRAY --> GRAYEST
496 ...E --> ...ER as in SKATE --> SKATER
497 if @ .ne. A, E, I, O, or U,
498 ...@Y --> ...@IER as in MULTIPLY --> MULTIPLIER
499 if # .ne. E or Y, or (# = Y and @ = A, E, I, O, or U)
500 ...@# --> ...@#ER as in BUILD --> BUILDER
501 or CONVEY --> CONVEYER
504 ...E --
> ...ERS as in SKATE --
> SKATERS
505 if @ .ne. A, E, I, O, or U,
506 ...@Y --
> ...@IERS as in MULTIPLY --
> MULTIPLIERS
507 if # .ne. E or Y, or (# = Y and @ = A, E, I, O, or U)
508 ...@# --
> ...@#ERS as in BUILD --
> BUILDERS
509 or SLAY --
> SLAYERS
512 if @ .ne. A, E, I, O, or U,
513 ...@Y --
> ...@IES as in IMPLY --
> IMPLIES
514 if # .eq. S, X, Z, or H,
515 ...# --
> ...#ES as in FIX --
> FIXES
516 if # .ne. S, X, Z, H, or Y, or (# = Y and @ = A, E, I, O, or U)
517 ...# --
> ...#S as in BAT --
> BATS
518 or CONVEY --
> CONVEYS
521 if @ .ne. A, E, I, O, or U,
522 ...@Y --
> ...@INESS as in CLOUDY --
> CLOUDINESS
523 if # .ne. Y, or @ = A, E, I, O, or U,
524 ...@# --
> ...@#NESS as in LATE --
> LATENESS
525 or GRAY --
> GRAYNESS
528 ... --
> ...'S as in DOG --
> DOG'S
530 Note: The existence of a flag on a root word in the directory is not by
531 itself sufficient to cause SPELL to recognize the indicated word ending.
532 If there is more than one root for which a flag will indicate a given word,
533 only one of the roots is the correct one for which the flag is effective;
534 generally it is the longest root. For example, the
"D" rule implies that
535 either PASS or PASSE, with a
"D" flag, will yield PASSED. The flag must be
536 on PASSE; it will be ineffective on PASS. This is because, when SPELL
537 encounters the word PASSED and fails to find it in its dictionary, it
538 strips off the
"D" and looks up PASSE. Upon finding PASSE, it then accepts
539 PASSED if and only if PASSE has the
"D" flag. Only if the word PASSE is
540 not in the main dictionary at all does the program strip off the
"E" and
543 Therefore, never install a flag by hand. Instead, just add complete
544 new words to the dictionary file, then use the build program with the
545 options '-a -r' to replace as many roots with flags as possible.
547 <H2><A NAME=
"SEC20" HREF=
"ispell_toc.html#SEC20">Where it came from
</A></H2>
549 I first came across ispell on TOPS-
20 systems at MIT. I tracked it
550 down to ITS where I found the PDP-
10 assembly program. It appeared
551 that it had been in use at the MIT-AI lab since at least the late
552 1970's. I think it case from California before then.
554 I wrote the first C implementation in the spring of
1983, mostly
555 working from the ITS INFO file.
557 The present version was created in early
1988, and was motivated by
558 the desire to make it run on
80286's, and to provide a better interface
561 There is another widely distributed version of ispell, which was forked
562 from my
1983 version and has a different set of features and clever
563 extensions. It is available from the directory /u/public/ispell at
566 People who have contributed to various versions of ispell include: Walt
567 Buehring, Mark Davies, Geoff Kuenning, Rober McQueer, Ashwin Ram, Greg
568 Schaffer, Perry Smith, Ken Stevens, and Andrew Vignaux.
571 pace@ai.mit.edu pace@hx.lcs.mit.edu
<BR>
574 <P>Go to the
<A HREF=
"ispell_1.html">previous
</A> section.
<P>