1<!-- This HTML file has been created by texi2html 1.29 2 from ispell.texi on 23 April 1994 --> 3 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, 8and to find the correct spelling of words. When presented with a 9word that is not in the dictionary, <CODE>ispell</CODE> attempts to find 10<DFN>near misses</DFN> that might include the word you meant. 11<P> 12This manual describes how to use ispell, as well as a little about 13its implementation. 14<P> 15<H2><A NAME="SEC3" HREF="ispell_toc.html#SEC3">Using ispell from emacs</A></H2> 16<P> 17<H3><A NAME="SEC4" HREF="ispell_toc.html#SEC4">Checking a single word</A></H3> 18<P> 19The simplest emacs command for calling ispell is 'M-$' (meta-dollar. 20On some terminals, you must type ESC-$.) This checks the spelling of 21the word under the cursor. If the word is found in the dictionary, 22then a message is printed in the echo area. Otherwise, ISPELL 23attempts to generate near misses. 24<P> 25If any near misses are found, they are displayed in a separate window, 26each preceded by a digit. If one of these is the word you wanted, 27just type its digit, and it will replace the original word in your 28buffer. 29<P> 30If no near miss is right, or if none are displayed, you 31have four choices: 32<P> 33<DL COMPACT> 34<DT><KBD>I</KBD> 35<DD><P> 36Insert the word in your private dictionary. Use this if you 37know that the word is spelled correctly. 38<P> 39<DT><KBD>A</KBD> 40<DD><P> 41Accept the word for the duration of this editing session, but do not 42put it in your private dictionary. Use this if you are not sure about 43the spelling of the word, but you do not want to look it up 44immediately. The next time you start ispell, it will have forgotten 45any accepted words. You can make it forget accepted words at any time 46by typing <KBD>M-x reload-ispell</KBD>. 47<P> 48<DT><KBD>SPC</KBD> 49<DD><P> 50Leave the word alone, and consider it misspelled if it is checked again. 51<P> 52<DT><KBD>R</KBD> 53<DD><P> 54Replace the word. This command prompts you for a string in the 55minibuffer. You may type more than one word, and each word you type 56is checked again, possibly finding other near misses. This command 57provides a handy way to close in on a word that you have no idea how 58to spell. You can keep trying different spellings until you find one 59that is close enough to get a near miss. 60<P> 61<DT><KBD>L</KBD> 62<DD><P> 63Lookup. Display words from the dictionary that contain a 64specified substring. The substring is a regular expression, 65which means it can contain special characters to be more 66selective about which words get displayed. 67See section `Regexps' in <CITE>emacs</CITE>. <P> 68If 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 70scanning the whole file. 71<P> 72Only a few matching words can be displayed in the ISPELL window. 73If you want to see more, use the <CODE>look</CODE> program directly from 74the shell. 75</DL> 76<P> 77Of course, you can also type ^G to stop the command without 78changing anything. 79<P> 80If you make a change that you don't like, just use emacs' normal undo 81feature See section `undo' in <CITE>emacs</CITE>. 82<P> 83<H3><A NAME="SEC5" HREF="ispell_toc.html#SEC5">Checking a whole buffer</A></H3> 84<P> 85If you want to check the spelling of all the words in a buffer, type 86the command <KBD>M-x ispell</KBD>. This command scans the file, and makes 87a list of all the misspelled words. When it is done, it moves the 88cursor to the first word on the list, and acts like you just typed M-$ 89See section <A HREF="ispell_2.html#SEC4">Checking a single word</A>. 90<P> 91When you finish with one word, the cursor is automatically moved to the 92next. 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 94<KBD>C-X $</KBD>. 95<P> 96<H3><A NAME="SEC6" HREF="ispell_toc.html#SEC6">Checking a region</A></H3> 97<P> 98You may check the words in the region with the command M-x ispell-region. 99See See section `mark' in <CITE>emacs</CITE>. 100<P> 101The commands available are the same as for checking a whole buffer. 102<P> 103<H2><A NAME="SEC7" HREF="ispell_toc.html#SEC7">Old Emacs</A></H2> 104<P> 105Until ispell becomes part of the standard emacs distribution, you will 106have to explicitly request that it be loaded. Put the following lines 107in your emacs init file See section `init file' in <CITE>emacs</CITE>. 108<P> 109<PRE> 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) 114</PRE> 115<P> 116(It will do no harm to have these lines in your init file even after 117ispell is installed by default.) 118<P> 119<H2><A NAME="SEC8" HREF="ispell_toc.html#SEC8">Using ispell by itself</A></H2> 120<P> 121To check the words in a file, give the command <CODE>ispell FILE</CODE>. This 122will present a screen of information, and accept commands for every word 123that is not found in the dictionary. 124<P> 125The screen shows the offending word at the top, as well as two lines of 126context at the bottom. If any near misses are found, they are shown in the 127middle of the screen, each preceded by a digit. 128<P> 129You may use the same commands as inside of emacs to accept the word, 130place it in your private dictionary, select a near miss, or type a 131replacement See section <A HREF="ispell_2.html#SEC4">Checking a single word</A>. You may also choose from the following 132commands: 133<P> 134<DL COMPACT> 135<DT><KBD>?</KBD> 136<DD><P> 137Print a help message. 138<P> 139<DT><KBD>Q</KBD> 140<DD>Quit. Accept the rest of the words in the file and exit. 141<P> 142<DT><KBD>X</KBD> 143<DD>Exit. Abandon any changes made to this file and exit immediately. You 144are asked if you are sure you want to do this. 145<P> 146<DT><KBD>!</KBD> 147<DD>Shell escape. The shell command that you type is executed as 148a subprocess. 149<P> 150<DT><KBD>^Z</KBD> 151<DD>Suspend. On systems that support job control, this suspends ISPELL. 152On other systems it executes a subshell. 153<P> 154<DT><KBD>^L</KBD> 155<DD>Redraw the screen. 156</DL> 157<P> 158If you type your interrupt character (usually ^C or <KBD>DEL</KBD>), then 159ispell will immediately enter its command loop. If ispell was generating 160near misses at the time, then all that it had found so far will be 161displayed, along with a message stating that there might be more, and that 162you can type <KBD>RET</KBD> to generate them. If it was scanning the file, it 163will display <SAMP>`(INTERRUPT)'</SAMP> where it would normally display a bad word, 164and the commands that change the file will be disabled. 165<P> 166The feature is handy if you have left out a space between words, and 167ispell is futilely looking up the 1000 potential near misses for a 168string that has twenty letters. 169<P> 170<H2><A NAME="SEC9" HREF="ispell_toc.html#SEC9">Using ispell to look up individual words 171</A></H2> 172<P> 173When ispell is run with no arguments, it reads words from the standard 174input. For each one, it prints a message telling whether it is in the 175dictionary. For any words not in the dictionary, near misses are 176computed, and any that are found are printed. 177<P> 178<PRE> 179% ispell 180word: independant 181how about: independent 182word: xyzzy 183not found 184word: ^D 185</PRE> 186<P> 187<H2><A NAME="SEC10" HREF="ispell_toc.html#SEC10">Your private dictionary</A></H2> 188<P> 189Whenever ispell is started the file <TT>`ispell.words'</TT> is read from your 190home directory (if it exists). This file contains a list of words, one per 191line, and neither the order nor the case of the words is important. Ispell 192will consider all of the words good, and will use them as possible near 193misses. 194<P> 195The <KBD>I</KBD> command adds words to <TT>`ispell.words'</TT>, so normally you 196don't have to worry about the file. You may want to check it from 197time to time to make sure you have not accidentally inserted a 198misspelled word. 199<P> 200<H2><A NAME="SEC11" HREF="ispell_toc.html#SEC11">Compatibility with the traditional spell program 201</A></H2> 202<P> 203The <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 205program is invoked by the name <SAMP>`spell'</SAMP>. 206<P> 207This flag causes the following behavior: 208<P> 209All of the files listed as arguments (or the standard input if none) 210are checked, and misspellings are printed on the standard output. The 211output is sorted, only one instance of each word appears (however, 212a word may appear more than once with different capitalizations.) 213<P> 214You may specify a file containing good words with <SAMP>`+filename'</SAMP>. 215<P> 216The troff commands <SAMP>`.so'</SAMP> and <SAMP>`.nx'</SAMP> (to include a file, or 217switch to a file, respectively) are obeyed, unless you give the flag 218<SAMP>`-i'</SAMP>. 219<P> 220The other <SAMP>`spell'</SAMP> flags <SAMP>`-v'</SAMP>, <SAMP>`-b'</SAMP>, <SAMP>`-x'</SAMP> and 221<SAMP>`-l'</SAMP> are ignored. 222<P> 223By the way, ispell seems to be about three times faster 224than traditional spell. 225<P> 226<H2><A NAME="SEC12" HREF="ispell_toc.html#SEC12">All commands in emacs and standalone modes 227</A></H2> 228<P> 229Commands valid in both modes: 230<P> 231DIGIT Select a near miss 232I Insert into private dictionary 233A Accept for this session 234SPACE Skip this time 235R Replace with one or more words 236L Lookup: search the dictionary using a regular expression 237<P> 238Standalone only: 239<P> 240Q Accept rest of file 241X Abandon changes 242! Shell escape 243? Help 244^Z Suspend 245^L Redraw screen 246^C Give up generating near misses, or show position in file 247<P> 248Emacs only: 249<P> 250M-$ Check word 251M-x ispell Check buffer 252M-x ispell-region Check region 253M-x reload-ispell Reread private dictionary 254M-x kill-ispell Kill current subprocess, and start a new one 255 next time 256^G When in M-x ispell, stop working on current 257 bad word list 258^X $ Resume working on bad word list. 259<P> 260<H2><A NAME="SEC13" HREF="ispell_toc.html#SEC13">Definition of a near miss</A></H2> 261<P> 262Two words are near each other if they can be made identical with one 263of the following changes to one of the words: 264<P> 265<PRE> 266Interchange two adjacent letters. 267Change one letter. 268Delete one letter. 269Add one letter. 270</PRE> 271<P> 272Someday, perhaps ispell will be extended so that words that sound 273alike would also be considered near misses. If you would like to 274implement this, see Knuth, Volume 3, page 392 for a description of the 275Soundex algorithm which might apply. 276<P> 277<H2><A NAME="SEC14" HREF="ispell_toc.html#SEC14">Flags to the ispell command</A></H2> 278<P> 279Ispell's arguments are parsed by getopt(3). Therefore, there is 280considerable flexibility about where to put spaces between arguments. 281The way to be safe is to give only one flag per dash, and put a space 282between a flag and its argument. 283<P> 284If 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 285</A>. 286With one or more file name arguments, it interactively checks each one. 287<P> 288<DL COMPACT> 289<DT><CODE>-p privname</CODE> 290<DD>Use privname as the private dictionary. 291<P> 292<DT><CODE>-d dictname</CODE> 293<DD>Use dictname as the system dictionary. You may also specify a system 294dictionary with the environment variable ISPELL_DICTIONARY. 295<P> 296<DT><CODE>-l</CODE> 297<DD>List mode. Scan the file, and print any misspellings on the standard 298output. This mode is compatible with the traditional spell program, 299except that the output is not sorted. See section <A HREF="ispell_2.html#SEC11">Compatibility with the traditional spell program 300</A>. 301<P> 302<DT><CODE>-u</CODE> 303<DD>Compatibility mode. See section <A HREF="ispell_2.html#SEC11">Compatibility with the traditional spell program 304</A>. 305<P> 306<DT><CODE>-a</CODE> 307<DD>Old style program interface, See section <A HREF="ispell_2.html#SEC15">How other programs can use ispell 308</A>. 309<P> 310<DT><CODE>-S</CODE> 311<DD>New program interface, See section <A HREF="ispell_2.html#SEC15">How other programs can use ispell 312</A>. 313<P> 314<DT><CODE>-D</CODE> 315<DD>Print the dictionary on the standard output with flags. 316<P> 317<DT><CODE>-E</CODE> 318<DD>Print the dictionary on the standard output with all flags expanded. 319<P> 320</DL> 321<P> 322<H2><A NAME="SEC15" HREF="ispell_toc.html#SEC15">How other programs can use ispell</A></H2> 323<P> 324Ispell can be used as a subprocess communicating through a pipe. Two 325interfaces are available: 326<P> 327<H2><A NAME="SEC16" HREF="ispell_toc.html#SEC16">New style, for EMACS</A></H2> 328<P> 329To use this interface, start ispell with the '-S' flag. Ispell will 330print a version number and greeting message that looks like: 331<P> 332<PRE> 333(1 "ISPELL V4.0")= 334</PRE> 335<P> 336The number is the version number of the protocol to be spoken over 337the pipe. The string is a message possibly of interest to the user. 338<P> 339All messages from ispell end in an equal sign, and ispell guarantees not to 340print an equal sign except to end a message. Therefore, if you do not want 341to deal with the greeting, just throw away characters until you get to an 342equals. 343<P> 344Ispell then reads one line commands from the standard input, and 345writes responses on the standard output. 346<P> 347If a command does not start with a colon, then it is considered a 348single word. The word is looked up in the dictionary, and if it is 349found, the response is <CODE>t</CODE>. If the word is not in the 350dictionary, 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 352a list of strings in lisp form. For example: 353<P> 354 INPUT OUTPUT 355 the t 356 xxx nil 357 teh ("tea" "ten" "the") 358<P> 359The 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 361particular, ispell promises that the list will appear all on one line, 362and that the structure will not change. A parser that reads the whole 363line, then treats the parentheses and quotes as whitespace will work fine. 364<P> 365The list will contain a maximum of ten strings, and each string will be 366no longer than 40 characters. Also, the capitalization of the near 367misses is the same as the input word. 368<P> 369<H3><A NAME="SEC17" HREF="ispell_toc.html#SEC17">Colon commands</A></H3> 370<P> 371If the input line starts with a colon, then it is one of the following 372commands: 373<P> 374<CODE>:file <VAR>filename</VAR></CODE> 375Run the word checker over the named <VAR>filename</VAR>. The response is zero or 376more lines each containing a number. The numbers are file offsets of 377words that do not appear in the dictionary. Since the near miss 378checker is not run, this is fairly fast. 379<P> 380After the last number, there will be a line containing either <CODE>t</CODE> if 381the checker got to the end of the file, or <CODE>nil</CODE> if it received an 382interrupt. If ispell ignores any interrupts received except while 383scanning a file. 384<P> 385<CODE>:insert <VAR>word</VAR></CODE> 386Place <VAR>word</VAR> in the private dictionary. 387<P> 388<CODE>:accept <VAR>word</VAR></CODE> 389Do not complain about <VAR>word</VAR> for the rest of the session. 390<P> 391<CODE>:dump</CODE> 392Write the private dictionary. 393<P> 394<CODE>:reload</CODE> 395Reread the private dictionary. 396<P> 397<CODE>:tex</CODE> 398Enable the tex parser for future <CODE>:file</CODE> commands. 399<P> 400<CODE>:troff</CODE> 401Enable the tex parser for future <CODE>:file</CODE> commands. 402<P> 403<CODE>:generic</CODE> 404Disable any text formatter parsers for future <CODE>:file</CODE> commands. 405<P> 406<H2><A NAME="SEC18" HREF="ispell_toc.html#SEC18">Old style, like ITS</A></H2> 407<P> 408To use this interface, start ispell with the '-a' flag. Ispell 409will read words from its standard input (one per line), and write 410a one line of output for each one. 411<P> 412If the first character of the line is <CODE>*</CODE>, then word was found in the 413dictionary. (Other versions of ispell made a distinction between words 414that were found directly, and words that were found after suffix 415removal. These lines began with <CODE>+</CODE>, followed by a space, then 416followed by the root word. To remain compatible with these version, 417treat <CODE>+</CODE> and <CODE>*</CODE> the same.) 418<P> 419If the line starts with <CODE>&</CODE>, then the input word was not found, but 420some near misses were found. They are listed on the output line 421separated by spaces. Also, the output words will have the same 422capitalization as the input. 423<P> 424Finally, if the line starts with <CODE>#</CODE>, then the word was not in the 425dictionaries, and no near misses were found. 426<P> 427 INPUT OUTPUT 428 the * 429 xxx # 430 teh & tea ten the 431<P> 432<H2><A NAME="SEC19" HREF="ispell_toc.html#SEC19">How the suffix stripper works</A></H2> 433<P> 434This section is excerpted from the ITS spell.info file. 435<P> 436 Words in SPELL's main dictionary (but not the private dictionary) may 437have flags associated with them to indicate the legality of suffixes 438without the need to keep the full suffixed words in the dictionary. The 439flags have "names" consisting of single letters. Their meaning is as 440follows: 441<P> 442Let # and @ be "variables" that can stand for any letter. Upper case 443letters are constants. "..." stands for any string of zero or more 444letters, but note that no word may exist in the dictionary which is not at 445least 2 letters long, so, for example, FLY may not be produced by placing 446the "Y" flag on "F". Also, no flag is effective unless the word that it 447creates is at least 4 letters long, so, for example, WED may not be 448produced by placing the "D" flag on "WE". 449<P> 450"V" flag: 451 ...E --> ...IVE as in CREATE --> CREATIVE 452 if # .ne. E, ...# --> ...#IVE as in PREVENT --> PREVENTIVE 453<P> 454"N" flag: 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 458<P> 459"X" flag: 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 463<P> 464"H" flag: 465 ...Y --> ...IETH as in TWENTY --> TWENTIETH 466 if # .ne. Y, ...# --> ...#TH as in HUNDRED --> HUNDREDTH 467<P> 468"Y" FLAG: 469 ... --> ...LY as in QUICK --> QUICKLY 470<P> 471"G" FLAG: 472 ...E --> ...ING as in FILE --> FILING 473 if # .ne. E, ...# --> ...#ING as in CROSS --> CROSSING 474<P> 475"J" FLAG" 476 ...E --> ...INGS as in FILE --> FILINGS 477 if # .ne. E, ...# --> ...#INGS as in CROSS --> CROSSINGS 478<P> 479"D" FLAG: 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 486<P> 487"T" FLAG: 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 494<P> 495"R" FLAG: 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 502<P> 503"Z FLAG: 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 510<P> 511"S" FLAG: 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 519<P> 520"P" FLAG: 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 526<P> 527"M" FLAG: 528 ... --> ...'S as in DOG --> DOG'S 529<P> 530Note: The existence of a flag on a root word in the directory is not by 531itself sufficient to cause SPELL to recognize the indicated word ending. 532If there is more than one root for which a flag will indicate a given word, 533only one of the roots is the correct one for which the flag is effective; 534generally it is the longest root. For example, the "D" rule implies that 535either PASS or PASSE, with a "D" flag, will yield PASSED. The flag must be 536on PASSE; it will be ineffective on PASS. This is because, when SPELL 537encounters the word PASSED and fails to find it in its dictionary, it 538strips off the "D" and looks up PASSE. Upon finding PASSE, it then accepts 539PASSED if and only if PASSE has the "D" flag. Only if the word PASSE is 540not in the main dictionary at all does the program strip off the "E" and 541search for PASS. 542<P> 543Therefore, never install a flag by hand. Instead, just add complete 544new words to the dictionary file, then use the build program with the 545options '-a -r' to replace as many roots with flags as possible. 546<P> 547<H2><A NAME="SEC20" HREF="ispell_toc.html#SEC20">Where it came from</A></H2> 548<P> 549I first came across ispell on TOPS-20 systems at MIT. I tracked it 550down to ITS where I found the PDP-10 assembly program. It appeared 551that it had been in use at the MIT-AI lab since at least the late 5521970's. I think it case from California before then. 553<P> 554I wrote the first C implementation in the spring of 1983, mostly 555working from the ITS INFO file. 556<P> 557The present version was created in early 1988, and was motivated by 558the desire to make it run on 80286's, and to provide a better interface 559for GNU EMACS. 560<P> 561There is another widely distributed version of ispell, which was forked 562from my 1983 version and has a different set of features and clever 563extensions. It is available from the directory /u/public/ispell at 564celray.cs.yale.edu. 565<P> 566People who have contributed to various versions of ispell include: Walt 567Buehring, Mark Davies, Geoff Kuenning, Rober McQueer, Ashwin Ram, Greg 568Schaffer, Perry Smith, Ken Stevens, and Andrew Vignaux. 569<P> 570Pace Willisson <BR> 571pace@ai.mit.edu pace@hx.lcs.mit.edu <BR> 572(617) 625--3452 573<P> 574<P>Go to the <A HREF="ispell_1.html">previous</A> section.<P> 575