This is ispell version 3.1, an interactive spelling checker. Contents of this README file: What Is Ispell and Why Do I Want It? What's New in This Version? Where Can I Get Ispell? OK, How Do I Install It? Who Wrote Ispell? Where Do I Send Bug Reports? How Do I Reference Ispell in Scholarly Papers? Where Do I Get Dictionaries? How Long Does It Take to Make Dictionaries? Special Installation Notes for Certain Machines: What About Ispell for MS-DOS? ------------------------------------------------------------------------ What Is Ispell and Why Do I Want It? Ispell is a fast screen-oriented spelling checker that shows you your errors in the context of the original file, and suggests possible corrections when it can figure them out. Compared to UNIX spell, it is faster and much easier to use. Ispell can also handle languages other than English. What's New in This Version? Compared to ispell versions 2 and 4.0 (the latter was the short-lived Gnu version), ispell 3.1 contains many new features, notably TeX support, international language support, and handling of prefixes as well as suffixes. Compared to ispell version 3.0, ispell 3.1 has many bug fixes, a number of minor improvements, and vastly improved support for multiple languages. The only truly important difference between 3.0 and 3.1 is in the format of the "defstringtype" and "altstringtype" statements, which now require a deformatter argument. Existing affix files will have to be converted. See ispell.4 for documentation, or deutsch.aff for an extended example. The conversion is very easy to do. All affix files distributed with ispell have already been converted. The complete list of bug fixes and improvements is too long to include here (and besides, I'm too overworked to create it). However, users of ispell 2.0 and ispell 4.0 should note that the "x" and "q" commands have been interchanged. Where Can I Get Ispell? If you have a Web browser, visit the ispell home page: http://www.cs.ucla.edu/ficus-members/geoff/ispell.html The current version of ispell is available for anonymous ftp from ftp.cs.ucla.edu (131.179.240.10) or ftp.math.orst.edu (128.193.80.161), in the pub/ispell-3.1 directory. The latest version is always named "ispell-3.1.xx.tar.gz", where "xx" is the patch level. There are also sometimes files named "README-patchxx" which contain notes specific to a given version. Announcements of patches to ispell will be posted to comp.text.tex, gnu.announce, and gnu.emacs.help. A number of ftp mirror sites also store ispell. Check Archie for "ispell-3.1" to find a site near you. Ispell comes with English dictionaries. For other languages, check the "Where" and "README" files in the "languages" subdirectory for hints on where to find dictionaries and how to install them. OK, How Do I Install It? Ispell is quite portable (thanks to many people). If you speak American English and have a BSD-like system, you may be able to get away with simply typing "make all" to finish unpacking the kit and make ispell and a dictionary, all configured to be installed in /usr/local/*. If you have a USG (System V) system, you will at least have to copy "local.h.samp" to "local.h", then add "#define USG" to local.h before compiling. Be sure you have at least 10 MB of free space in /tmp, or set your TMPDIR environment variable to point somewhere with that much space. For more complex installations, you will have to create a fancier local.h file. All customization of ispell 3.1, even for the Makefile, is done by creating or editing the file "local.h" to override the default definitions of certain variables. The most common changes will be to the LANGUAGES variable (to set the languages; see also the Makefiles in the various language subdirectories), CC (to choose gcc), and BINDIR through MAN4DIR (to control where ispell is installed). There are many other configuration parameters; see config.X for the complete list and further instructions. *DO NOT* make changes to config.X or to any of the Makefiles. Anything you define in "local.h" will override definitions in those files. The English-language dictionary comes in four sizes: small, medium, large, and extra-large. I recommend using the medium dictionary unless you are very short on space. The small and medium dictionaries have been hand-checked against a paper dictionary to improve their accuracy. This is not true of the two larger ones. The large and extra-large dictionaries contain less-frequently-used words, and most sites will not want to pay the price of storing them, especially because they may contain errors. Also, a large dictionary can hide misspellings of short words because there is some similar word that nobody uses. (For example, the crossword-puzzle favorite "ort" can hide misspellings of "or".) For each dictionary size, you can also choose to make a "plus" version, named by adding a plus sign to the size indication. These versions are created by incorporating a dictionary file of your own, usually /usr/dict/words. (I can't distribute a dictionary based on that file because it's copyrighted.) Making a plus version requires extra time and disk space, but will give you some computer and technical terms that aren't in the basic ispell word list. That's why the default dictionary is "americanmed+.hash". After all edits, you are ready to compile ispell. Make sure you have set your TMPDIR environment variable, and then type "make all". This will compile all the programs, put the dictionaries together, and build the hash file. If you get errors while compiling term.c, change the setting of "#define USG" in your local.h file and try again. If you chose a "+" version of the dictionary (the LANGUAGES macro in config.X), expect this first make to run for quite a while (usually about half an hour, but as much as 24 hours on a very limited machine) because of the munchlist step. If you chose a non-plus version, the make will not take long. The munchlist step will also take a *lot* of disk space (see the table below for more information), so be sure to set TMPDIR in your environment to point to someplace with lots of room. After your first make completes, you are ready to install ispell. The standard "make install" will install ispell, the auxiliary programs and scripts, the manual page, and the dictionary hash file, all in the directories you have chosen for them. This usually has to be done as root, and on some systems you will not be able to redirect the output to a file. (If you're the careful sort, you'll check the output of "make -n install" first to be sure there are no hidden surprises.) If you don't want to install the dictionary-building tools, you can type "make partial-install" to install just the files needed to use ispell itself. If you have emacs, note that the installation process does not modify the top-level Info menu to include ispell; you must do this by hand if you want ispell to appear in the top-level menu. The installation process may clobber emacs-related files from ispell 4.0. If you don't consider this a feature, you should preserve them first. Also, if you have emacs you can ignore the warnings issued when ispell.el is byte-compiled. Finally, ispell.el contains some platform-dependent stuff, such as path names and egrep switches. This is a bug that will be cleaned up someday. As well as the standard "make clean" and "make realclean" targets, there is also a "make dictclean" target which will get rid of constructed dictionary files such as "english.med+". This is a separate target because of the time it takes to build dictionaries. Finally, there is a directory named "addons", which contains shar kits for ispell helper programs that were generously written by other people. These are not copyrighted or supported by the ispell maintainer. Contact the original authors (listed in README files in the kits) for more information. Who Wrote Ispell? Ispell is a very old program. The original was written in PDP-10 assembly in 1971, by R. E. Gorin. The C version was written by Pace Willisson of MIT. Walt Buehring of Texas Instruments added the emacs interface and posted it to the net. Geoff Kuenning added the international support and created the current release. Many, many other people contributed to the current version; a complete list (with a much more detailed history) can be found in the file "Contributors". Where Do I Send Bug Reports? Most ispell bug reports, except bugs related to the emacs-lisp interface, should be sent to "ispell-bugs@itcorp.com". Bugs in the emacs interface (ispell.el) should be sent to "ispell-el-bugs@itcorp.com". If you're not sure which address to use, send your report to "ispell-bugs@itcorp.com" and I'll sort it out from there. Bugs in add-on packages (found in the "addons" subdirectory) should not be sent to itcorp.com. Instead, send reports to the developers of those packages (see the README file for the package you are using). How Do I Reference Ispell in Scholarly Papers? There is no published paper on ispell, so if you make use of ispell in a fashion that requires a reference (e.g., using the dictionary as a word list in a research project), you are limited to an Internet reference. The full proper title is printed by "ispell -v": "International Ispell Version x.y.z". Please include the full version number in your reference so that people can discover the exact variant that you used; sometimes it's important. If you're feeling really nice, you can also credit me, Geoffrey H. Kuenning, as the author. Usually, you should also include a mention of the master ftp site, ftp.cs.ucla.edu, so that readers of your paper can locate a copy if they wish. Where Do I Get Dictionaries? Ispell comes with American and British dictionaries. American-style spellings are the default. To get British spellings, copy the LANGUAGES and MASTERHASH definitions from config.X into your local.h, and then globally replace "american" with "british". For other languages, consult the file "languages/Where", which lists everything I know about. You can also check the ispell home page: http://www.cs.ucla.edu/ficus-members/geoff/ispell.html which contains pointers to all known dictionaries. If you create a dictionary of your own and make it available for ftp, please send a notification to ispell-bugs@itcorp.com so that I can add your dictionary to the ftp list. How Long Does It Take to Make Dictionaries? The following tables give approximate timings and peak disk usage for making each of the three augmented English dictionaries (the so-called "plus" versions). The timings were collected on an unloaded 68040. Your mileage may vary. Using EXTRADICT=/usr/dict/words: Time to build Peak temp space Final size english.sml+ 30 minutes 7.1M 306K english.med+ 35 minutes 8.8M 359K english.lrg+ 60 minutes 10.7M 680K Using EXTRADICT=/usr/dict/words and /usr/dict/web2: Time to build Peak temp space Final size english.sml+ 2-1/2 hours 19.5M 2243K english.med+ 2-1/2 hours 19.6M 2265K english.lrg+ 3 hours 20.7M 2347K The peak disk usage occurs fairly early in the munching process. When creating english.lrg+ with /usr/dict/web2, the peak was reached within 30 minutes. When web2 was omitted, the peak was always reached within 1/4 of the total running time of munchlist. Again, remember that these times will vary depending on your load and your machine's power. Special Installation Notes for Certain Machines: Although I have tried to avoid putting in specific machine dependencies as a general rule, some machine-specific #defines will be found at the end of config.X. If you get lots of warnings when compiling term.c, check to be sure that you have correctly defined SIGNAL_TYPE in your local.h. Some versions of ISC Unix have TIOCGWINSZ defined even though it's not supported and the necessary structures are not present. The solution is to add "#undef TIOCGWINSZ" in your local.h. Under ISC (Solaris) Unix System V.3, you may have to add includes of and to your local.h to get around compilation problems in term.c. Some versions of SCO Unix define "struct winsize" conditionally. The solution is to add "#define _IBCS2" in your local.h. Some versions of SCO Unix define "struct winsize" in a weird place. Add #includes of and to your local.h to get around this. Suns running 4.1.1 also have a bug in sort which causes core dumps when running munchlist. Sun users who have the System 5 option can work around this bug by making sure that /usr/5bin precedes /usr/bin in their path, so that /usr/5bin/sort is used by munchlist. It is reported that some older versions of gnu sort do not recognize the -T option. (However, as of textutils 1.9 it does.) Define SORTTMP and MAKE_SORTTMP as the null string ("") if you use gnu sort, or change your path to use the manufacturer's sort command (but watch out for Sun's sort bug, above!). Some versions of gcc for the Sparc have an optimizer bug that causes problems for languages that use 8-bit characters. The solution is to turn off optimization when compiling at least makedent.c, or for all of ispell. The bug is known to exist in gcc 2.4.5, and is known to have been fixed in gcc 2.5.8. There is a report that on Solaris 2.3 for the sparc, buildhash may core dump. The cure is to use "bison -y" instead of yacc. On SunOS 4.1.3 using Sun's SPARCompiler C2.0.1, you may have to select static linking (-Bstatic option in CFLAGS). The AIX RS6000 should use -lcurses for TERMLIB, rather than -ltermcap. Amiga users will need to #define fork vfork. Other than this, ispell should compile using gcc on the Amiga. There have been reports that some BSD releases don't properly declare "extern int errno" in errno.h. If you suffer from this problem, you'll have to add your own declaration in your local.h. There are known problems on Ultrix with the interaction between ispell and some versions of elm on Ultrix. You may be able to fix this by making sure USG is undefined, or you may have to make more extensive changes to term.c to cause it to use the "termios" interface instead of the "termio" one. The DEC Alpha and Cray have 64-bit longs. Make sure you define MASKTYPE_WIDTH as 64 for these machines. Some versions of the DEC Alpha compiler may compile ispell incorrectly. The cure is to turn optimization off and compile with the -g switch. The symptoms are segmentation faults and garbage characters in the ~/.ispell_english file. If you get this symptom, be sure to clean out the garbage before you rerun ispell or recompiling won't help. Some versions of "uniq" on the DEC Alpha, OSF/1 2.x, generate garbage output if given null input, causing munchlist to loop forever. This can by checked by running "uniq < /dev/null | wc -c", which ought print zero. If it does not, you'll have to use GNU uniq (from textutils/1.11) instead, or upgrade to OSF/1 3.0 which does not have the bug. DEC OSF/1 keeps the extra dictionary in a wierd place. Set EXTRADICT to /usr/share/dict/words. HP systems will need C compiler patch PHSS_3015 to compile ispell correctly, bringing the revision to A.09.34 or higher. The symptom of the wrong compiler is incorrect highlighting of misspelled words. Gcc will also compile ispell correctly on HP systems. I have a report that on HP systems 300-400, you must use either gcc or the non-ansi CCFLAG ("cc +o2"), at least for the ispell.c source. However, it is possible that this problem has been corrected by a bug fix to term.c. I'd be interested in hearing whether the report is still true. Some "internationalized" Unixes (HP, for instance) vary the behavior of sort(1) based on an environment variable such as LANG or LOCALE. The symptom is that munchlist does not produce an optimal dictionary. Munchlist tries to protect against this by setting LANG and LOCALE to "C", but if your system uses different environment variables, you may have to do this by hand. If you get core dumps from the sort command (reported on HP systems building large German dictionaries), try adding the "-y" flag to the appropriate invocation of sort in the Makefile or in munchlist. This flag is only available on some systems. SGI Irix systems store /usr/dict/words in /usr/lib/dict or /usr/share/lib/dict. You may have to install the normal "spell" and associated files from cd-rom before it will exist. If you get errors compiling with Irix 4.0.5 or others, try defining __STDC__ in local.h, to get around problems caused by the fact that the compiler accepts prototypes but doesn't define __STDC__. Some BSDI systems have a screwy sort command that uses -T to specify the record (as opposed to field) delimiter. You'll have to disable SORTTMP and enable MAKE_SORTTMP. You'll also have to be sure that /usr/tmp has lots and lots of free space. What About Ispell for MS-DOS? Although ispell is not officially supported on MS-DOS, there are a couple of #defines that you might find useful if you want to do such a thing. Check the end of config.X. Several people have reported success building DOS versions using emx/gcc. Others have used the djgpp package, with bison replacing yacc. Some places to look for a DOS ispell if you have an x86: ftp.cdrom.com:pub/os2/unix/isp3009b.zip. or ftp-os2.cdrom.com:pub/os2/2_x/unix/ There is also a program named jspell, which is an ispell lookalike. Look on ftp.tex.ac.uk, in the directory pub/archive/support/jspell.