1This is Info file ispell.info, produced by Makeinfo-1.55 from the input 2file ispell.texi. 3 4 This file documents GNU ISPELL, an interactive spelling corrector. 5 6 Copyright (C) 1990 Free Software Foundation, Inc. 7 8 Permission is granted to make and distribute verbatim copies of this 9manual provided the copyright notice and this permission notice are 10preserved on all copies. 11 12 Permission is granted to copy and distribute modified versions of 13this manual under the conditions for verbatim copying, provided that 14the entire resulting derived work is distributed under the terms of a 15permission notice identical to this one. 16 17 Permission is granted to copy and distribute translations of this 18manual into another language, under the above conditions for modified 19versions, except that this permission notice may be stated in a 20translation approved by the Foundation. 21 22 23File: ispell.info, Node: Top, Next: License, Prev: (dir), Up: (dir) 24 25 `Ispell' is a program that helps you to correct typos in a file, and 26to find the correct spelling of words. When presented with a word that 27is not in the dictionary, `ispell' attempts to find "near misses" that 28might include the word you meant. 29 30 This manual describes how to use ispell, as well as a little about 31its implementation. 32 33* Menu: 34 35* License:: Licensing information. 36* Emacs:: Using ispell from emacs 37* Standalone:: Using ispell by itself 38* Ask:: Using ispell to look up individual words 39* Private:: Your private dictionary 40* Compatibility:: Compatibility with the traditional spell program 41* Command summary:: All commands in emacs and standalone modes 42 43Implementation details: 44* Near misses:: Definition of a near miss 45* Arguments:: Flags to the ispell command 46* Interface:: How other programs can use ispell 47* Dictionary flags:: How the suffix stripper works 48* History:: Where it came from; authors 49 50 51File: ispell.info, Node: License, Next: Emacs, Prev: Top, Up: Top 52 53Licensing Information 54********************* 55 56 Ispell is "free"; this means that everyone is free to use it and 57free to redistribute it on a free basis. Ispell is not in the public 58domain; it is copyrighted and there are restrictions on its 59distribution, but these restrictions are designed to permit everything 60that a good cooperating citizen would want to do. What is not allowed 61is to try to prevent others from further sharing any version of ispell 62that they might get from you. 63 64 Specifically, we want to make sure that you have the right to give 65away copies of ispell, that you receive source code or else can get it 66if you want it, that you can change ispell or use pieces of it in new 67free programs, and that you know you can do these things. 68 69 To make sure that everyone has such rights, we have to forbid you to 70deprive anyone else of these rights. For example, if you distribute 71copies of ispell, you must give the recipients all the rights that you 72have. You must make sure that they, too, receive or can get the source 73code. And you must tell them their rights. 74 75 Also, for our own protection, we must make certain that everyone 76finds out that there is no warranty for ispell. If these programs are 77modified by someone else and passed on, we want their recipients to know 78that what they have is not what we distributed, so that any problems 79introduced by others will not reflect on our reputation. 80 81 The precise conditions of the licenses for ispell are found in the 82General Public Licenses. The programs that are part of GNU Emacs are 83covered by the GNU Emacs copying terms (*note License: 84(emacs)License.), and other programs are covered by licenses that are 85contained in their source files. 86 87 88File: ispell.info, Node: Emacs, Next: Standalone, Prev: License, Up: Top 89 90Using ispell from emacs 91======================= 92 93* Menu: 94 95* Word:: Checking a single word 96* Buffer:: Checking a whole buffer 97* Region:: Checking a region 98* Old Emacs:: Using ispell with older versions of emacs 99 Look here if M-$ calls the old spell program in your emacs. 100 101 102File: ispell.info, Node: Word, Next: Buffer, Prev: Emacs, Up: Emacs 103 104Checking a single word 105---------------------- 106 107 The simplest emacs command for calling ispell is 'M-$' (meta-dollar. 108On some terminals, you must type ESC-$.) This checks the spelling of 109the word under the cursor. If the word is found in the dictionary, 110then a message is printed in the echo area. Otherwise, ISPELL attempts 111to generate near misses. 112 113 If any near misses are found, they are displayed in a separate 114window, each preceded by a digit. If one of these is the word you 115wanted, just type its digit, and it will replace the original word in 116your buffer. 117 118 If no near miss is right, or if none are displayed, you have four 119choices: 120 121`I' 122 Insert the word in your private dictionary. Use this if you know 123 that the word is spelled correctly. 124 125`A' 126 Accept the word for the duration of this editing session, but do 127 not put it in your private dictionary. Use this if you are not 128 sure about the spelling of the word, but you do not want to look 129 it up immediately. The next time you start ispell, it will have 130 forgotten any accepted words. You can make it forget accepted 131 words at any time by typing `M-x reload-ispell'. 132 133`SPC' 134 Leave the word alone, and consider it misspelled if it is checked 135 again. 136 137`R' 138 Replace the word. This command prompts you for a string in the 139 minibuffer. You may type more than one word, and each word you 140 type is checked again, possibly finding other near misses. This 141 command provides a handy way to close in on a word that you have 142 no idea how to spell. You can keep trying different spellings 143 until you find one that is close enough to get a near miss. 144 145`L' 146 Lookup. Display words from the dictionary that contain a 147 specified substring. The substring is a regular expression, which 148 means it can contain special characters to be more selective about 149 which words get displayed. *Note Regexps: (emacs)Regexps. 150 151 If the only special character in the regular express is a leading 152 `^', then a very fast binary search will be used, instead of 153 scanning the whole file. 154 155 Only a few matching words can be displayed in the ISPELL window. 156 If you want to see more, use the `look' program directly from the 157 shell. 158 159 Of course, you can also typeG to stop the command without changing 160anything. 161 162 If you make a change that you don't like, just use emacs' normal undo 163feature *Note undo: (emacs)undo. 164 165 166File: ispell.info, Node: Buffer, Next: Region, Prev: Word, Up: Emacs 167 168Checking a whole buffer 169----------------------- 170 171 If you want to check the spelling of all the words in a buffer, type 172the command `M-x ispell'. This command scans the file, and makes a 173list of all the misspelled words. When it is done, it moves the cursor 174to the first word on the list, and acts like you just typed M-$ *Note 175Word::. 176 177 When you finish with one word, the cursor is automatically moved to 178the next. If you want to stop in the middle of the list type `Q' or 179G'. Later, you can pick up where you left off by typing `C-X $'. 180 181 182File: ispell.info, Node: Region, Next: Old Emacs, Prev: Buffer, Up: Emacs 183 184Checking a region 185----------------- 186 187 You may check the words in the region with the command M-x 188ispell-region. See *Note mark: (emacs)mark. 189 190 The commands available are the same as for checking a whole buffer. 191 192 193File: ispell.info, Node: Old Emacs, Prev: Region, Up: Emacs 194 195Old Emacs 196========= 197 198 Until ispell becomes part of the standard emacs distribution, you 199will have to explicitly request that it be loaded. Put the following 200lines in your emacs init file *Note init file: (emacs)init file. 201 202 (autoload 'ispell "ispell" "Run ispell over buffer" t) 203 (autoload 'ispell-region "ispell" "Run ispell over region" t) 204 (autoload 'ispell-word "ispell" "Check word under cursor" t) 205 (define-key esc-map "$" 'ispell-word) 206 207 (It will do no harm to have these lines in your init file even after 208ispell is installed by default.) 209 210 211File: ispell.info, Node: Standalone, Next: Ask, Prev: Emacs, Up: Top 212 213Using ispell by itself 214====================== 215 216 To check the words in a file, give the command `ispell FILE'. This 217will present a screen of information, and accept commands for every word 218that is not found in the dictionary. 219 220 The screen shows the offending word at the top, as well as two lines 221of context at the bottom. If any near misses are found, they are shown 222in the middle of the screen, each preceded by a digit. 223 224 You may use the same commands as inside of emacs to accept the word, 225place it in your private dictionary, select a near miss, or type a 226replacement *Note Word::. You may also choose from the following 227commands: 228 229`?' 230 Print a help message. 231 232`Q' 233 Quit. Accept the rest of the words in the file and exit. 234 235`X' 236 Exit. Abandon any changes made to this file and exit immediately. 237 You are asked if you are sure you want to do this. 238 239`!' 240 Shell escape. The shell command that you type is executed as a 241 subprocess. 242 243`^Z' 244 Suspend. On systems that support job control, this suspends 245 ISPELL. On other systems it executes a subshell. 246 247`^L' 248 Redraw the screen. 249 250 If you type your interrupt character (usuallyC or DEL), then ispell 251will immediately enter its command loop. If ispell was generating near 252misses at the time, then all that it had found so far will be 253displayed, along with a message stating that there might be more, and 254that you can type RET to generate them. If it was scanning the file, it 255will display `(INTERRUPT)' where it would normally display a bad word, 256and the commands that change the file will be disabled. 257 258 The feature is handy if you have left out a space between words, and 259ispell is futilely looking up the 1000 potential near misses for a 260string that has twenty letters. 261 262 263File: ispell.info, Node: Ask, Next: Private, Prev: Standalone, Up: Top 264 265Using ispell to look up individual words 266======================================== 267 268 When ispell is run with no arguments, it reads words from the 269standard input. For each one, it prints a message telling whether it 270is in the dictionary. For any words not in the dictionary, near misses 271are computed, and any that are found are printed. 272 273 % ispell 274 word: independant 275 how about: independent 276 word: xyzzy 277 not found 278 word:D 279 280 281File: ispell.info, Node: Private, Next: Compatibility, Prev: Ask, Up: Top 282 283Your private dictionary 284======================= 285 286 Whenever ispell is started the file `ispell.words' is read from your 287home directory (if it exists). This file contains a list of words, one 288per line, and neither the order nor the case of the words is important. 289Ispell will consider all of the words good, and will use them as 290possible near misses. 291 292 The `I' command adds words to `ispell.words', so normally you don't 293have to worry about the file. You may want to check it from time to 294time to make sure you have not accidentally inserted a misspelled word. 295 296 297File: ispell.info, Node: Compatibility, Next: Command summary, Prev: Private, Up: Top 298 299Compatibility with the traditional spell program 300================================================ 301 302 The `-u' flag tells ispell to be compatible with the traditional 303`spell' program. This flag is automatically turned on if the program 304is invoked by the name `spell'. 305 306 This flag causes the following behavior: 307 308 All of the files listed as arguments (or the standard input if none) 309are checked, and misspellings are printed on the standard output. The 310output is sorted, only one instance of each word appears (however, a 311word may appear more than once with different capitalizations.) 312 313 You may specify a file containing good words with `+filename'. 314 315 The troff commands `.so' and `.nx' (to include a file, or switch to 316a file, respectively) are obeyed, unless you give the flag `-i'. 317 318 The other `spell' flags `-v', `-b', `-x' and `-l' are ignored. 319 320 By the way, ispell seems to be about three times faster than 321traditional spell. 322 323 324File: ispell.info, Node: Command summary, Next: Near misses, Prev: Compatibility, Up: Top 325 326All commands in emacs and standalone modes 327========================================== 328 329 Commands valid in both modes: 330 331 DIGIT Select a near miss I Insert into private dictionary 332A Accept for this session SPACE Skip this time R Replace with one 333or more words L Lookup: search the dictionary using a regular 334expression 335 336 Standalone only: 337 338 Q Accept rest of file X Abandon changes ! Shell escape ? Help 339^Z Suspend ^L Redraw screen ^C Give up generating near misses, or 340show position in file 341 342 Emacs only: 343 344 M-$ Check word M-x ispell Check buffer M-x ispell-region Check 345region M-x reload-ispell Reread private dictionary M-x 346kill-ispell Kill current subprocess, and start a new one next 347time ^G When in M-x ispell, stop working on current bad word list ^X 348$ Resume working on bad word list. 349 350 351File: ispell.info, Node: Near misses, Next: Arguments, Prev: Command summary, Up: Top 352 353Definition of a near miss 354========================= 355 356 Two words are near each other if they can be made identical with one 357of the following changes to one of the words: 358 359 Interchange two adjacent letters. 360 Change one letter. 361 Delete one letter. 362 Add one letter. 363 364 Someday, perhaps ispell will be extended so that words that sound 365alike would also be considered near misses. If you would like to 366implement this, see Knuth, Volume 3, page 392 for a description of the 367Soundex algorithm which might apply. 368 369 370File: ispell.info, Node: Arguments, Next: Interface, Prev: Near misses, Up: Top 371 372Flags to the ispell command 373=========================== 374 375 Ispell's arguments are parsed by getopt(3). Therefore, there is 376considerable flexibility about where to put spaces between arguments. 377The way to be safe is to give only one flag per dash, and put a space 378between a flag and its argument. 379 380 If ispell is run with no arguments, it enters `ask' mode *Note Ask::. 381With one or more file name arguments, it interactively checks each one. 382 383`-p privname' 384 Use privname as the private dictionary. 385 386`-d dictname' 387 Use dictname as the system dictionary. You may also specify a 388 system dictionary with the environment variable ISPELL_DICTIONARY. 389 390`-l' 391 List mode. Scan the file, and print any misspellings on the 392 standard output. This mode is compatible with the traditional 393 spell program, except that the output is not sorted. *Note 394 Compatibility::. 395 396`-u' 397 Compatibility mode. *Note Compatibility::. 398 399`-a' 400 Old style program interface, *Note Interface::. 401 402`-S' 403 New program interface, *Note Interface::. 404 405`-D' 406 Print the dictionary on the standard output with flags. 407 408`-E' 409 Print the dictionary on the standard output with all flags 410 expanded. 411 412 413File: ispell.info, Node: Interface, Next: Dictionary flags, Prev: Arguments, Up: Top 414 415How other programs can use ispell 416================================= 417 418 Ispell can be used as a subprocess communicating through a pipe. Two 419interfaces are available: 420 421* Menu: 422 423* New interface:: New style, for EMACS 424* Old interface:: Old style, like ITS 425 426 427File: ispell.info, Node: New interface, Next: Old interface, Prev: Interface, Up: Interface 428 429New style, for EMACS 430==================== 431 432 To use this interface, start ispell with the '-S' flag. Ispell will 433print a version number and greeting message that looks like: 434 435 (1 "ISPELL V4.0")= 436 437 The number is the version number of the protocol to be spoken over 438the pipe. The string is a message possibly of interest to the user. 439 440 All messages from ispell end in an equal sign, and ispell guarantees 441not to print an equal sign except to end a message. Therefore, if you 442do not want to deal with the greeting, just throw away characters until 443you get to an equals. 444 445 Ispell then reads one line commands from the standard input, and 446writes responses on the standard output. 447 448 If a command does not start with a colon, then it is considered a 449single word. The word is looked up in the dictionary, and if it is 450found, the response is `t'. If the word is not in the dictionary, and 451no near misses can be found, then the response is `nil'. If there are 452near misses, the response is a line containing a list of strings in 453lisp form. For example: 454 455 INPUT OUTPUT the t xxx nil teh ("tea" "ten" 456"the") 457 458 The near miss response is suitable for passing directly to the lisp 459`read' function, but it can also be parsed simply in C. In particular, 460ispell promises that the list will appear all on one line, and that the 461structure will not change. A parser that reads the whole line, then 462treats the parentheses and quotes as whitespace will work fine. 463 464 The list will contain a maximum of ten strings, and each string will 465be no longer than 40 characters. Also, the capitalization of the near 466misses is the same as the input word. 467 468Colon commands 469-------------- 470 471 If the input line starts with a colon, then it is one of the 472following commands: 473 474 `:file FILENAME' Run the word checker over the named FILENAME. The 475response is zero or more lines each containing a number. The numbers 476are file offsets of words that do not appear in the dictionary. Since 477the near miss checker is not run, this is fairly fast. 478 479 After the last number, there will be a line containing either `t' if 480the checker got to the end of the file, or `nil' if it received an 481interrupt. If ispell ignores any interrupts received except while 482scanning a file. 483 484 `:insert WORD' Place WORD in the private dictionary. 485 486 `:accept WORD' Do not complain about WORD for the rest of the 487session. 488 489 `:dump' Write the private dictionary. 490 491 `:reload' Reread the private dictionary. 492 493 `:tex' Enable the tex parser for future `:file' commands. 494 495 `:troff' Enable the tex parser for future `:file' commands. 496 497 `:generic' Disable any text formatter parsers for future `:file' 498commands. 499 500 501File: ispell.info, Node: Old interface, Prev: New interface, Up: Interface 502 503Old style, like ITS 504=================== 505 506 To use this interface, start ispell with the '-a' flag. Ispell will 507read words from its standard input (one per line), and write a one line 508of output for each one. 509 510 If the first character of the line is `*', then word was found in the 511dictionary. (Other versions of ispell made a distinction between words 512that were found directly, and words that were found after suffix 513removal. These lines began with `+', followed by a space, then 514followed by the root word. To remain compatible with these version, 515treat `+' and `*' the same.) 516 517 If the line starts with `&', then the input word was not found, but 518some near misses were found. They are listed on the output line 519separated by spaces. Also, the output words will have the same 520capitalization as the input. 521 522 Finally, if the line starts with `#', then the word was not in the 523dictionaries, and no near misses were found. 524 525 INPUT OUTPUT the * xxx # teh & tea ten the 526 527 528File: ispell.info, Node: Dictionary flags, Next: History, Prev: Interface, Up: Top 529 530How the suffix stripper works 531============================= 532 533 This section is excerpted from the ITS spell.info file. 534 535 Words in SPELL's main dictionary (but not the private dictionary) 536may have flags associated with them to indicate the legality of 537suffixes without the need to keep the full suffixed words in the 538dictionary. The flags have "names" consisting of single letters. 539Their meaning is as follows: 540 541 Let # and @ be "variables" that can stand for any letter. 542Upper case letters are constants. "..." stands for any string of 543zero or more letters, but note that no word may exist in the 544dictionary which is not at least 2 letters long, so, for example, FLY 545may not be produced by placing the "Y" flag on "F". Also, no flag 546is effective unless the word that it creates is at least 4 letters 547long, so, for example, WED may not be produced by placing the 548"D" flag on "WE". 549 550 "V" flag: ...E -> ...IVE as in CREATE -> CREATIVE 551if # .ne. E, ...# -> ...#IVE as in PREVENT -> PREVENTIVE 552 553 "N" flag: ...E -> ...ION as in CREATE -> CREATION 554...Y -> ...ICATION as in MULTIPLY -> MULTIPLICATION if # .ne. 555E or Y, ...# -> ...#EN as in FALL -> FALLEN 556 557 "X" flag: ...E -> ...IONS as in CREATE -> CREATIONS 558...Y -> ...ICATIONS as in MULTIPLY -> MULTIPLICATIONS if # 559.ne. E or Y, ...# -> ...#ENS as in WEAK -> WEAKENS 560 561 "H" flag: ...Y -> ...IETH as in TWENTY -> TWENTIETH 562if # .ne. Y, ...# -> ...#TH as in HUNDRED -> HUNDREDTH 563 564 "Y" FLAG: ... -> ...LY as in QUICK -> QUICKLY 565 566 "G" FLAG: ...E -> ...ING as in FILE -> FILING if # 567.ne. E, ...# -> ...#ING as in CROSS -> CROSSING 568 569 "J" FLAG" ...E -> ...INGS as in FILE -> FILINGS if 570# .ne. E, ...# -> ...#INGS as in CROSS -> CROSSINGS 571 572 "D" FLAG: ...E -> ...ED as in CREATE -> CREATED if 573@ .ne. A, E, I, O, or U, ...@Y -> ...@IED as in IMPLY 574-> IMPLIED if # .ne. E or Y, or (# = Y and @ = A, E, I, O, or U) 575 ...@# -> ...@#ED as in CROSS -> CROSSED 576 or CONVEY -> CONVEYED 577 578 "T" FLAG: ...E -> ...EST as in LATE -> LATEST if @ 579.ne. A, E, I, O, or U, ...@Y -> ...@IEST as in DIRTY 580-> DIRTIEST if # .ne. E or Y, or (# = Y and @ = A, E, I, O, or 581U) ...@# -> ...@#EST as in SMALL -> SMALLEST 582 or GRAY -> GRAYEST 583 584 "R" FLAG: ...E -> ...ER as in SKATE -> SKATER if @ 585.ne. A, E, I, O, or U, ...@Y -> ...@IER as in MULTIPLY 586-> MULTIPLIER if # .ne. E or Y, or (# = Y and @ = A, E, I, O, 587or U) ...@# -> ...@#ER as in BUILD -> BUILDER 588 or CONVEY -> CONVEYER 589 590 "Z FLAG: ...E -> ...ERS as in SKATE -> SKATERS if @ 591.ne. A, E, I, O, or U, ...@Y -> ...@IERS as in 592MULTIPLY -> MULTIPLIERS if # .ne. E or Y, or (# = Y and @ = A, 593E, I, O, or U) ...@# -> ...@#ERS as in BUILD -> 594BUILDERS or SLAY -> SLAYERS 595 596 "S" FLAG: if @ .ne. A, E, I, O, or U, ...@Y 597-> ...@IES as in IMPLY -> IMPLIES if # .eq. S, X, Z, or H, 598 ...# -> ...#ES as in FIX -> FIXES if # .ne. S, X, 599Z, H, or Y, or (# = Y and @ = A, E, I, O, or U) ...# -> 600...#S as in BAT -> BATS or CONVEY -> 601CONVEYS 602 603 "P" FLAG: if @ .ne. A, E, I, O, or U, ...@Y 604-> ...@INESS as in CLOUDY -> CLOUDINESS if # .ne. Y, or @ = A, 605E, I, O, or U, ...@# -> ...@#NESS as in LATE -> 606LATENESS or GRAY -> GRAYNESS 607 608 "M" FLAG: ... -> ...'S as in DOG -> DOG'S 609 610 Note: The existence of a flag on a root word in the directory is 611not by itself sufficient to cause SPELL to recognize the indicated 612word ending. If there is more than one root for which a flag will 613indicate a given word, only one of the roots is the correct one for 614which the flag is effective; generally it is the longest root. For 615example, the "D" rule implies that either PASS or PASSE, with a "D" 616flag, will yield PASSED. The flag must be on PASSE; it will be 617ineffective on PASS. This is because, when SPELL encounters the word 618PASSED and fails to find it in its dictionary, it strips off the 619"D" and looks up PASSE. Upon finding PASSE, it then accepts PASSED if 620and only if PASSE has the "D" flag. Only if the word PASSE is not in 621the main dictionary at all does the program strip off the "E" and 622search for PASS. 623 624 Therefore, never install a flag by hand. Instead, just add complete 625new words to the dictionary file, then use the build program with the 626options '-a -r' to replace as many roots with flags as possible. 627 628 629File: ispell.info, Node: History, Prev: Dictionary flags, Up: Top 630 631Where it came from 632================== 633 634 I first came across ispell on TOPS-20 systems at MIT. I tracked it 635down to ITS where I found the PDP-10 assembly program. It appeared 636that it had been in use at the MIT-AI lab since at least the late 6371970's. I think it case from California before then. 638 639 I wrote the first C implementation in the spring of 1983, mostly 640working from the ITS INFO file. 641 642 The present version was created in early 1988, and was motivated by 643the desire to make it run on 80286's, and to provide a better interface 644for GNU EMACS. 645 646 There is another widely distributed version of ispell, which was 647forked from my 1983 version and has a different set of features and 648clever extensions. It is available from the directory /u/public/ispell 649at celray.cs.yale.edu. 650 651 People who have contributed to various versions of ispell include: 652Walt Buehring, Mark Davies, Geoff Kuenning, Rober McQueer, Ashwin Ram, 653Greg Schaffer, Perry Smith, Ken Stevens, and Andrew Vignaux. 654 655Pace Willisson 656pace@ai.mit.edu pace@hx.lcs.mit.edu 657(617) 625-3452 658 659 660 661Tag Table: 662Node: Top876 663Node: License1882 664Node: Emacs3679 665Node: Word4032 666Node: Buffer6573 667Node: Region7197 668Node: Old Emacs7495 669Node: Standalone8130 670Node: Ask9981 671Node: Private10511 672Node: Compatibility11158 673Node: Command summary12198 674Node: Near misses13110 675Node: Arguments13728 676Node: Interface15020 677Node: New interface15368 678Node: Old interface18156 679Node: Dictionary flags19221 680Node: History24178 681 682End Tag Table 683