JSPELL 2.11 (Release date: Oct.21, 1998) Copyright 1993-1998 by Joohee Jeong Email: jhjeong@bigfoot.com ========================================================== Please read 00readme.txt for some important information. ========================================================== Table of Contents Chapter I. Introduction 1 Features of JSPELL 2 Installation 3 Test drive 4 Configuration and hardware compatibility 5 Terminologies Chapter II. User's guide for JSPELL 1 Characters, words and dictionaries 1.1 Legal characters and legitimate words 1.2 Base dictionary and user dictionary 1.3 Dictionary loading 2 TeX-mode 2.1 Selecting the TeX-mode 2.2 Legitimate subwords in TeX 2.3 Ignoring the TeX commands 2.4 Math ignore mode 2.5 Miscellanies 3 Running JSPELL, the spell checker 3.1 Overview 3.2 Capitalization of words 3.3 Menu 3.4 [Replace] and [rePlace all] 3.5 Adding spotted word to user dictionaries 3.6 Miscellanies 4 Configuration files and command line options 5 Usage tips Chapter III. User's guide for dictman 1 Introduction 2 Running dictman, the dictionary manager 2.1 [File] menus 2.2 [BaseDic] menus 2.3 [UserDic] menus 2.4 [Utilities] menus 2.5 [Help=F1] menus 3 Dictionary maintenance 3.1 Merging user dictionary to base dictionary 3.2 Deleting words from a base dictionary 3.3 Building up your own base dictionary Appendix A. Networked mode Appendix B. Frequently Asked Questions Appendix C. History Chapter I. Introduction ---------------------------------------- I.1. Features of JSPELL (1) Ease of use: Practically you don't need to study or practice anything to use JSPELL proficiently. With JSPELL's on-line help and the intuitive keystrokes, which are indicated by the highlighted letters in the on-screen menu buttons, you will hardly need to read the manual except for the advanced features of JSPELL, which are not found in other spell checkers. For mouse users, spell-checking with JSPELL can even be fun. (2) Speed: JSPELL is fast in dictionary loading, scanning input files for misspelled words and finding suggestions for near misspelled words. For a typical PC with 386 CPU, JSPELL needs less than two seconds in loading a 40,000 word dictionary and a fraction of a second in building and displaying the list of suggested words for a misspelled word. (3) Dictionary: A unique feature of JSPELL is its ability to handle file specific dictionary and multiple user dictionaries---you can have a dictionary (or dictionaries) that are specific to the input file. The author of JSPELL found this feature very convenient, more than he initially imagined. The accompanying dictionary manager dictman is powerful and easy to use. Merging your personal dictionaries to the space/time- efficient base dictionary and/or building your own base dictionary from scratch is done effortlessly. (4) TeX support: Ignoring the TeX-commands (that start with the backslashes `\') is just the beginning. Refer to (Section 2.2) of this manual for the complete description of how JSPELL handles TeX documents. (5) Foreign characters: Foreign characters can be handled in either (i) extended ASCII characters, or (ii) TeX commands (e.g., G\"odel, Erd\H{o}s). (6) Undo: Not all popular spell checkers support undoing the previous actions---up to 400 steps! Moreover, JSPELL always displays the last action at the bottom row of the screen for added convenience. (7) Network support: Each user can have his/her own configuration and personal dictionary while sharing the executables and the base dictionary with other users. (8) Ignoring specific lines: You may configure to JSPELL to ignore (i.e., not to spell-check) all lines starting with a specified string: for instance the ">". This feature is useful in spell-checking replies to email messages. (9) More... There are countless features of JSPELL that will please you. For instance, the [Find] menu item in the dictionary manager can display all words in the dictionary that match the given regular expression: e.g., the pattern "t???e" will give you the list of all 5 letter words that start with `t' and end with `e', such as "table", "taste", "tease", "tense" etc., in just 3 to 5 seconds for a typical 386 machine. Imagine what you can do with this in solving crossword puzzles! I.2 Installation Installation and configuration: Prepare a "jspell directory", say C:\JSPELL, by the DOS command mkdir C:\JSPELL and copy all JSPELL files into this directory. Then C:\JSPELL should contain the following 9 files ------------------------------------------------------------------ filename description ------------------------------------------------------------------ 00readme.txt readme file base.dic English word list dictman.exe the dictionary manager executable jspell.cfg configuration jspell.exe the spell checker executable jspell.hlp help message file jsptex.cfg TeX configuration manual.txt manual sample.txt sample text for a test drive ------------------------------------------------------------------ In order to be able to run JSPELL (and DICTMAN) in any directory, either add C:\JSPELL to your PATH or put two batch files JSPELL.BAT and DICTMAN.BAT into one of your directories in PATH. The content of the batch files jspell.bat and dictman.bat should look like @echo off C:\JSPELL\jspell.exe %1 %2 %3 %4 %5 %6 %7 %8 %9 and @echo off C:\JSPELL\dictman.exe %1 %2 %3 %4 %5 %6 %7 %8 %9 respectively. The default configuration of JSPELL is set to VGA and AT-keyboard. Also we assume that you work under the plain-vanilla English DOS environment. If your computer's configuration and/or environment is different from this, then you will need to read (Section I.4) of the documentation file manual.txt. If you use non-English DOS, for instance the DOS box in Korean Windows 95, then the screen will surely look ugly. In this case, use the command chcp 437 to get into English mode. To return to Korean mode, use chcp 949 If you are going to run JSPELL under a networked environment, then please read (Appendix A.) of manual.doc to complete the installation. In order to print out the documentation file manual.doc, your printer must be able to handle the IBM graphic characters correctly. I.3 Test drive We assume that JSPELL (and dictman) has been correctly installed on your computer. If not, please refer to the installation information in the previous section. Also, we suggest you making a hard copy of this documentation file manual.doc (by a command like "copy manual.doc prn"), at least this "Test drive" section, with your printer---you can't test drive JSPELL while reading this file on a computer screen unless you run two computers simultaneously. In order to print out this documentation properly, your printer must be able to handle the IBM graphic characters correctly. This test drive is for JSPELL only---not for dictman, which will be needed only after you've determined to use JSPELL as your spell checker. Try the following command at the DOS prompt: jspell You will see the following screen (and the DOS prompt). Usage: jspell [-options...] to spell check , where option = -bd -ud -fd -len n (2 <= n <= 9) -t[+-] -math[+-] -percent[+-] or jspell ? to read the help screen. Don't worry about the -options for the time being. The Usage tells you that you can spell-check a file, say , by the command "jspell filename". We will test this on the text file "sample.txt" which should exist in the same directory as jspell.exe. (It won't take long. After all, you can exit from this test drive whenever you want by hitting Alt-X.) First, copy this sample file "sample.txt" to the current directory by the command copy c:\jspell\sample.txt . or something like this. Then execute the following command at the DOS prompt: jspell sample.txt Three boxes will be shown on the screen. The upper one is for text display, the lower left one is for the suggested words, and the lower right one is for the menu buttons. The row between the upper and lower area is called the "edit row". Each misspelled word in the input file sample.txt will be highlighted in the upper box and also displayed on the edit row. The bottom row is for displaying some information about the current working of JSPELL. First, JSPELL will briefly display the message that looks like Loading "C:\JSPELL\base.dic"..... at the bottom row, and then spot/highlight the first misspelled word "jspell" at the center row of the upper box. Also the edit row will display the highlighted word "jspell" with a half-block cursor flashing at the end of the word. Now press DownArrow to highlight the suggested word "spell" and then press ENTER. You should be able to see that the word "jspell" has been replaced by "spell" and the second misspelled word "typcal" is now being spotted/highlighted. Actually, replacing "jspell" by "spell" was not our intention. We wanted to [iGnore all] the word "jspell" which occurs several times in this sample text file. So, hit Alt-U (or click on the menu button [Undo]) to undo the previous action. Then a dialog box will pop-up at the center of the screen asking us to choose one of the three options "Undo", "Cancel" or "Undo further". Choose the default option "Undo" by either (highlighting "Undo" and) pressing ENTER or clicking the left mouse button on it. Now we are back to the previous step. This time, press Alt-G (or click on the menu button [iGnore all]) to ignore all the subsequent occurrences of "jspell" as well as this spotted one. JSPELL should be spotting/highlighting the word "typcal" now. Naturally we want to replace this by the suggested word "typical". There are several ways of doing this: o Highlight "typical" and then press ENTER, or o Press the key 1, or o Click left mouse button on the suggested word "typical". Do any one of these three actions. Now we want to add the next spotted/highlighted word "CPU" into the user dictionary. We do this by pressing Alt-A or clicking on the menu button [Add to user.dic]. Then JSPELL asks us to select one of the three possible capitalizations "CPU", "Cpu" or "cpu". We should choose the first one, "CPU". Next, you will see that the misspelled word "teh" is spotted/ highlighted. (By the way, although the previous word "CPU" is no longer shown on the upper box, we can still see that the last action was adding "CPU" to the user dictionary user.dic by looking at the bottom row.) Note that the row in the upper box containing the spotted word "teh" has two occurrences of the word "jspell" which were not caught because we have ignored "jspell" globally. We replace this misspelled word "teh" by the correct word "the" by hitting 6. Then we see that another "teh" is spotted by JSPELL. Thus we realize that we should have done [rePlace all] instead of simple [Replace]. To this end, we first undo the last action and then hit Alt-P after highlighting "the" in the lower left box (or alternatively, you may click the left mouse button on the suggested word "the" while pressing down the Ctrl key). The next spotted word "jsspell" lies on a rather long line, but JSPELL handles this situation with no problem. In fact, the limit on the line length in the input file is as large as 512 characters. Note that the correct word "jspell" is suggested although it's not in the dictionary. (Recall that "jspell" had been globally ignored.) Now replace "jsspell" by "jspell". The rest of this test drive is for the TeX-mode. The currently spotted word "sl" is a valid TeX-command. So we could just ignore this "sl" or add it to user.dic. But surely there is a better solution: just ignore all words that follow the backslash character `\', namely the TeX-commands. Normally, JSPELL chooses this TeX-mode automatically if (and only if) the input file name has extension ".tex". But we can force the TeX-mode by the command line switch -t. So we'll end this session and spell-check this text file sample.txt again in TeX-mode. It's good time to test the [eXit] menu. Hit Alt-X. Then JSPELL will pop-up a window asking you to choose one of the following: Yes (save changes before exit), or No (do not save changes and exit), or Cancel (do not exit, and continue JSPELL). We choose the first option "Yes" for now. Before starting another JSPELL session, you might want to look into your user.dic file in the "jspell directory" to check that the word "CPU" has really got in there. Now enter the command jspell -t sample.txt We see that "jspell" is spotted again because [iGnore all] has effect only on that particular session. So, this time we will put this word "jspell" in the file specific dictionary sample.dic, by hitting Alt-T (or clicking mouse on the appropriate menu button). The next spotted word should be "Pythagoras". We put this word into sample.dic. (If you are bothered by the jspell's pop-up window asking you to choose capitalization, then you may do Shift-Alt-T or Shift-LeftMouseClick on [add To sample.dic].) Now JSPELL is done with this input file. It will show you some information about the session (such as the number of words that have been spotted etc.) and displays a pop-up window with two choices Exit and Cancel. If you choose Cancel, then you can undo the last action on "Pythagoras". Otherwise, you just exit. Note that JSPELL ignored the 5 words "sl", "XY", "XZ", "YZ" and "Wat" which would have been caught if TeX-mode had not been used. You may want to look into the file sample.dic, which has been created in the current directory by this JSPELL session. It should contain the two words "Pythagoras" and "jspell". These two words are considered to be in our vocabulary for input files whose filenames are of the form sample., where is any extension, including the empty one. Note that the original file has been saved in a backup file named sample.bak in the current directory. Remark: In this test drive section, there are three places where we made (slightly) wrong statements---on purpose to avoid excessive details. We'll continue this practice of deliberate lying to the rest of this manual whenever it is appropriate. I.4 Configuration and hardware JSPELL and dictman need IBM-PC 100% compatible computer because they use direct video for fast screen update. Also they use low-level keyboard reading. Thus some (old) IBM compatible computers may not be able to run jspell/dictman successfully. For videos, VGA, EGA, CGA and Hercules are supported. Other video cards may or may not work. JSPELL uses two configuration files jspell.cfg and jsptex.cfg. Both of these are plain ASCII text files. jsptex.cfg is for TeX-mode only and has nothing to do with the computer hardware. In fact, only the first three entries of jspell.cfg are pertinent to the hardware. So we will concentrate on these first few lines of jspell.cfg in this section and defer the discussion of the rest until later sections in this manual. The configuration variables in jspell.cfg have effect on the behavior of both JSPELL and dictman. A typical jspell.cfg looks like: AT % keyboard (AT or XT) VGA % video card (CGA,EGA,VGA or Hercules) Enhanced % color option (Standard,Enhanced,Monochrome or Laptop) ... more ... ... more ... The meanings of these three configuration variables should be more or less obvious---if you have an AT-keyboard, then choose the AT option, otherwise choose the XT option and so on. If you want change a variable, say AT to XT, then you may simply replace "AT" by "XT" using your favorite text editor. The order of these configuration variables does matter. So be careful not to mess up the order. Upper/lower-case is ignored. The difference between AT-keyboards and XT-keyboards is not that important. With AT, you can use certain keystrokes that are not recognized by XT: e.g., CtrlUpArrow and CtrlDownArrow are only recognized by AT-keyboards. For video cards not among the four supported ones, it may still be possible to run jspell/dictman by selecting suitable options by trial and error. Just note that Enhanced color option is for VGA or EGA only. About the color options, many people prefer the Enhanced option to the Standard option. But if you run JSPELL in a DOS box under Windows (or you just prefer Standard to Enhanced for any reason) then you may switch to the Standard option by simply replacing "Enhanced" by "Standard" in the third line of the file jspell.cfg. The Laptop option is basically Monochrome that can't display "bright white" properly. So the command keys are highlighted by inverse video instead of bright white if you choose this Laptop option. I.5 Terminologies As you may have already noticed, this manual uses the word "jspell" somewhat ambiguously: sometimes it means the jspell/dictman combo and sometimes it means only the spell checker jspell.exe. Another example of our abuse of terminology is the word TeX--- it usually means TeX/LaTeX: for instance, the LaTeX-command \newenvironment is not really a TeX command in the strict sense, but in this manual we may just say "the TeX-command \newenvironment ..." for convenience. We want use the term jspell directory to mean the directory in which JSPELL is installed: i.e., the directory in which all JSPELL files reside. But if we think about running JSPELL over a networked environment, where each user may want to update user.dic and/or base.dic, it becomes evident that we need some sort of personal jspell directory for each user. For the single user mode, jspell directory will mean the directory in which the JSPELL executable file jspell.exe resides. It is this directory where the JSPELL files such as dictman.exe, jspell.cfg, jsptex.cfg and jspell.hlp normally reside. jspell directory is also the default directory for base.dic and user.dic. For the networked mode, jspell executable directory will mean the directory in which jspell.exe resides. We must put the files dictman.exe and jspell.hlp in this directory. But the other two files jspell.cfg and jsptex.cfg may exist in the jspell configuration directory which is defined by the environment variable JSPELL_DIR, which is normally set by autoexec.bat. Also this jspell configuration directory is the default directory for base.dic and user.dic. For the detailed discussion on this subject, the readers are referred to (Appendix A.). In (Chapter 2) and (Chapter 3), we will always assume that JSPELL is being run under the single user mode. Chapter II. User's guide for JSPELL ---------------------------- II.1 Characters, words and dictionaries II.1.1 Legal characters and legitimate words Following are the list of legal characters that can be used in words: abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ €‚ƒ„…†‡ˆ‰Š‹ŒŽ‘’“”•–—˜™š ¡¢£¤¥á In addition, we may use the following special characters that can be used in words in some circumstances: " ' - . = \ ^ ` { } ~ A finite sequence of legal characters and/or special characters can be considered to be a legitimate word only if the length of is in between MinWordLen and 40, where MinWordLen is some number in between 2 and 9 and defined in the configuration file (as the 11th entry). This configuration variable can be overridden by the command line switch -len For instance jspell -len 3 will ignore all words in the text file that has length 1 or 2. Suppose that has proper length. In non-TeX-mode, the only special character that can appear in is the apostrophe ('). Moreover, there's some restriction in the use of apostrophe in . It must occur at the end of as *n't, *'ve, *'re or *'ll, where * denotes any sequence of characters. To summarize, when JSPELL runs in non-TeX-mode, a finite sequence of legal characters and/or apostrophe is a legitimate word if and only if it has length in between MinWordLen and 40 and satisfies the condition on apostrophe as described in the paragraph above. In TeX-mode, the definition of legitimate words gets more complicated. For this subject, refer to (Section II.2.2) in this chapter. II.1.2 Base dictionary and user dictionary Dictionary means a file that contains a list of words in some systematic way. (Sometimes we may use this term dictionary to mean the list of words in the computer memory that have been loaded from a dictionary file.) Two types of dictionaries are used by jspell: one is "base dictionary" and the other is "user dictionary". Base dictionary exploits the common prefix/suffixes of words to reduce the file size. (Current version of jspell supports only English prefix/suffix. Future versions will allow user configurable prefix/suffix for foreign languages.) Also loading a base dictionary is fast because it is read into the memory directly (i.e., no computation for building up data-structures). If you want to make any change on the content of base dictionary, then it must be done by dictman, the dictionary manager for jspell. To see the extent of the space saving obtained by this prefix/suffix business, run the [BaseDic][Expand] menu in dictman. It will create an ASCII text file that contains all words in the base dictionary currently loaded in the computer memory. User dictionary is simply an ASCII text file that contains one word per line. The words are alphabetically sorted for the ease of maintenance---you can edit this file directly using any text editor. jspell reads user dictionary line by line. If jspell encounters a space character (i.e., space, tab, carriage return, end of line etc.), then it ignores the rest of the line. If an illegitimate word is encountered during loading, then jspell exits with an error message. jspell supports the use of "multiple user dictionaries" and the "file specific user dictionary" as explained in the next section. II.1.3 Dictionary loading When jspell starts it looks for the default base dictionary, say base.dic, in the current directory, where the default dictionary name is defined in the configuration file jspell.cfg (as the 12th entry). If it finds one, then the base dictionary is loaded into the computer memory. Otherwise jspell continues searching base.dic in the jspell directory. If both searches fail, then jspell exits with an appropriate error message. You can override the default base dictionary name defined in jspell.cfg by the command line switch -bd for instance, jspell -bd german.dic will spell-check the file using the base dictionary "german.dic". As we mentioned above jspell allows us to use more than one user dictionaries. There is one special user dictionary, called the main user dictionary, which is used for *all* jspell-check sessions. User dictionaries other than the main one may or may not be used in jspell-checking depending on the filename of the input text file. Dictionary loading of the main user dictionary is similar to that of base dictionary, with one minor difference explained in the next paragraph. The default main user dictionary name is normally user.dic and defined in the configuration file jspell.cfg (as the 13th entry). It can be overridden by the command line switch -ud for instance, jspell -ud math.dic will spell-check the file using the main user dictionary math.dic. The difference between the loading of the base dictionary and the main user dictionary is that if both searches fail (one in the current directory and the other in the jspell directory) then jspell exits with an error message in the former case, while in the latter case jspell (i) does not complain anything in case the default main user dictionary defined in jspell.cfg has been used, (ii) gives warning and option to choose between continue or abort in case the command line defined main user dictionary has been used. If the main user dictionary is not found in either of the directories but some words are added into the main user dictionary during a spell-check session, then a new dictionary is created in the jspell directory. The default file specific dictionary of a file . is defined to be a user dictionary with filename .dic. Dictionary loading of the file specific dictionary, or file dictionary for short, is the same as that of the main user dictionary. The default file dictionary name can be overridden by the command line switch -fd -fd for instance, jspell -fd project1.dic will spell-check the file using the file dictionary "project1.dic" (instead of the default one .dic). If the file dictionary is not found in either of the directories but some words are added into the file dictionary during a spell-check session, then a new dictionary is created in the current directory. (This is different from the main user dictionary case.) You may use additional user dictionaries specific to a text file . by specifying them in the file dictionary, say .dic, in the following way, which is how jspell supports the use of multiple user dictionaries. Suppose that you want to use two additional dictionaries "math.dic" and "comp.dic". Then just add two lines +math.dic and +comp.dic at the beginning of the file dictionary .dic---so the content of the resulting file dictionary for our input file . should look like: +math.dic +comp.dic ... ... As usual, these additional user dictionaries are first searched in the current directory and then in the jspell directory. If both searches fail, then jspell exists with an error message. Up to 9 additional user dictionaries can be used. Among the dictionaries mentioned above, the main user dictionary and the file dictionary may be updated by a jspell session. So if these two dictionaries happen to have the same filename, then the filename collision problem occurs, and jspell exists with an appropriate error message. Other types of dictionary name collision is less harmful and thus silently ignored by jspell. (Some computing resources are wasted due to the duplicate copy of the same dictionary.) Since user dictionaries (main, file, or additional) can be freely edited by any text editor, there is a possibility that an illegitimate word creeps into one of these dictionaries. If jspell finds an illegitimate word during the initial dictionary loading, then it exits with an error message at the bottom of the screen indicating the first encounter of (i) the illegitimate word , (ii) the dictionary that contains and (iii) the line in which occurs. You should immediately delete or fix this . If the same word exists in more than one places---in different dictionaries or in the same dictionary---then it is silently ignored by jspell. (Some computing resources are wasted due to the duplicate copy of the same word.) One final remark: extension of dictionary files need not necessarily be .dic. It's just convenient to stick to this naming convention in most situations. II.2 TeX-mode II.2.1 Selecting the TeX-mode This mode is automatically selected if the extension of the input file is ".tex", case insensitive. You may override this convention by the command line switch -t[+-]. For instance, you may force the TeX-mode to the file . by jspell -t . Conversely, you may force non-TeX-mode to the file .tex by jspell -t- .tex -t+ has the same effect as -t. II.2.2 Legitimate subwords in TeX First of all, any legitimate word in non-TeX-mode is legitimate in the TeX-mode also. In addition, we can use the accenting commands as part of a legitimate word. Thus the following 21 strings are legitimate subwords \` \`{?} \' \'{?} \^ \^{?} \" \"{?} \~ \~{?} \= \={?} \. \.{?} \u{?} \v{?} \H{?} \c{?} \d{?} \b{?} \t{??} where ? denotes any single character. Next, there are 11 special TeX commands that are legitimate subwords: \oe \OE \ae \AE \aa \AA \o \O \l \L \ss which are used to generate the following symbols * omitted in this ASCII version of the manual * respectively. Further, we allow the use of braces { and } for various circumstances like \ss{}, {\oe} etc. Finally, we allow the hyphenation command \- to be part of legitimate words. II.2.3 Ignoring the TeX commands First of all, jspell ignores all TeX (and LaTeX) commands (except the 11 special ones mentioned in the previous section): i.e., all words following the escape character `\'. Note that if `\' is not used as an escape character, as in the second occurrence in the command `\\', jspell doesn't ignore the subsequent word---this is illustrated in the following example: We explain \fbox{gnus} in the next line. \\THis is ... jspell will ignore the command "fbox" but catch "THis" as a misspelled word. Some TeX commands take arguments which need not be usual words. For instance, in the text On this topic, readers are referred to \cite{Knu88a} ... we want the word "Knu" be ignored. So jspell will ignore an appearing as \cite{}. Since itself may contain { and }, the exact rule is: ignore until the first right brace that matches the first left brace after the command \cite, where literal braces following the escape character \ are not counted. Some TeX commands take more than one arguments. jspell takes this into account too: e.g., it ignores and appearing as \newcommand{}{} Note that and/or can be rather long and may span several lines. We call this number of arguments of a TeX command "arity". The arity of \cite is 1, the arity of \newcommand is 2, and the arity of \newenvironment is 3 etc. In fact these arities of TeX commands are user definable by editing the configuration file "jsptex.cfg". If a line in jsptex.cfg is mycommand, where is a numeral, then the arity of \mycommand will be set to be . An exception to this is the = 0 case. This is supplied to treat some commands like \input that has fuzzy syntax. (Both "\input " and "\input{}" are accepted.) Following are the the default arity/command pairs defined in jsptex.cfg. 0input 1include 1includeonly 1documentstyle 1newcounter 1hyphenation 1label 1ref 1bibitem 1pageref 1cite 1nocite 2newcommand 2renewcommand 2newtheorem 3newenvironment 3renewenvironment The commands \begin and \end are treated specially. The arity of \begin is not fixed---normally it is 1, but sometimes it can be 2 as you can see in the following example: \begin{array}{llcr} We don't want to see jspell reporting "llcr" as a misspelled word. A similar situation arises when "array" in the example above is replaced by one of "tabular", "figure" and "table". Another thing that we should consider is that the commands \begin and \end are used in setting on/off math ignore mode, which is explained in detail in the following section. So these two special commands \begin and \end are hard-coded in jspell and do not appear in the TeX command configuration file jsptex.cfg. The number of commands that are accepted in jsptex.cfg can be 32 at maximum. II.2.4 Math ignore mode By default, jspell do not spell-check text in math mode which is defined by one of the followings: $ $ $$ $$ \( \) \[ \] \begin{math} \end{math} \begin{equations} \end{equation} \begin{eqnarray} \end{eqnarray} \begin{eqnarray*} \end{eqnarray*} Math mode across multiple lines are supported of course. The reason why jspell ignores text in math mode is that many nonwords may occur in math mode as in the following example: $$ {\sl XY}^2 + {\sl XZ}^2 = {\sl XZ}^2 $$ On the other hand, we may want jspell not ignore the text in math mode in the following example: $$ {\sl base}^2 + {\sl height}^2 = {\sl hypotenus}^2 $$ (Note the typo "hypotenus" in math mode.) If you prefer to disable this math mode ignoring feature of jspell, then you can do so by editing the configuration file jspell.cfg, the sixth entry, to replace MathIgnore by MathNoIgnore. Alternatively math ignoring can be set/unset by the command line switch -math[+-] jspell -math+ will force jspell to spell-check text in math mode and jspell -math- will force jspell to ignore text in math mode. The switch -math has the same effect as -math+. II.2.5 Miscellanies TeX ignores any input after the percent symbol % until the end of line. So it could be desirable for jspell to follow this after-%-ignoring convention of TeX. For example, we can think of the following situation: Send \$25.00 to ... % don't forget \ before $ Here is a tyypo ... If jspell gets no effect from %, then it will think that the last character $ on the line containing % starts math mode, and thus the word "tyypo" would not be caught as a misspelled word (assuming that the math ignore mode is on). This after-%-ignore mode is set by the 10th entry of the configuration file jspell.cfg: if it is pIgnore, then jspell ignores characters in a line after the first nonliteral occurrence of %, and if it is pNoIgnore then % has no special effect on the behavior of jspell. You can override this by the command line switch -percent[+-]. The switch -percent (or equivalently -percent+) set's the after-%-ignore mode on regardless of what's been defined by the configuration file jspell.cfg. The switch -percent- is the opposite of -percent+. We don't claim that jspell can handle all possible situations of TeX appropriately. For instance jspell doesn't understand the following (unnatural) construction: ... the following displayed equation $% some comment $ x^2 + y^2 = z^2. $$ It is believed that above argument was first invented by ... jspell thinks that "some comment" is in math mode and "It is believed ..." is the beginning of displayed math mode, which is absurd. So if you are determined to fool jspell, then it's relatively easy to do so by using the comment character %---on the other hand such a situation (that jspell is fooled) will seldom occur unless you intentionally create that. II.3 Running jspell, the spell checker This section describes the detail of the usage of the spell checker jspell. If you use jspell for the first time, then perhaps the earlier section Test drive will be sufficient for you. II.3.1 Overview To jspell-check an ASCII file , you first go to the directory in which resides and then enter the command jspell [-options...] at the DOS prompt. ( may contain path. In this case you don't have to go to the directory of of course.) The [-options...], which have been mentioned at least once in earlier sections, will be explained in detail in the next section. In a typical situation of a jspell session, a misspelled word in (assuming that at least one misspelled word exists) is highlighted and shown together with the surrounding text in the 78x11 sized box occupying the upper half of the screen. is also displayed in the row at the middle of the screen right below the upper box, namely the edit row. Also the action of the user on the previous misspelled word is displayed at the bottom of the screen (unless is the first misspelled word in ). Words in the jspell's dictionary that are *close* to are displayed in the lower left box: i.e., the suggestion area. Up to 16 suggested words can be displayed. Under the "Numbered" option (which is the default), the highlighted numeral n is shown in front of the n-th suggested word. (For n > 8, @m is shown in place of n where m := n - 8.) These numerals give us a handy way of selecting a word from the list of the suggested words. We will discuss this in detail in (Section II.3.4). You may disable this Numbered option by editing the 9th entry of the configuration file jspell.cfg to replace "Numbered" by "NoNumbered". The limit L on the length of the suggested words is 40, which is the same as the maximum length for legitimate words. But when there are more than 8 suggested words, then this limit L reduces to 17 under the Numbered option and 19 under the NoNumbered option. The third box in the lower right part of the screen shows menu buttons. Each menu button contains exactly one uppercase letter, which is highlighted (or inverse-video'ed for Laptop color option). This capitalized letter is the command key for that menu. More on this in the next section. The time necessary for jspell to prepare a suggested words list is normally less than a fraction of a second for usual 386 machines. But for longer words (with length, say > 10) and slower machines, it might take several seconds. Sometimes, immediately after a word is spotted, you may realize that it's not really a typo, and you are going to ignore it or add to a user dictionary. So, naturally, you don't want to waste time waiting for jspell to finish the preparation of the suggested words list. In this case, you can just go ahead and do the appropriate action by pressing a command key or clicking the left mouse button. Then jspell will abort preparing the suggested words list and do the action immediately. Whenever a dialog box is displayed, waiting for a user action, pressing the ESC key or clicking the right mouse button has the same effect as choosing the "Cancel" option. At exit, jspell creates a backup file with the name .bak (assuming that the input file has filename .) if (and only if) the "BackUp" option is selected, which is set/unset by the 7th entry of the configuration file jspell.cfg. The backup file .bak is created in the same directory as the input file. II.3.2 Capitalization of words We define four types of words according to the capitalization as follows. A word has capitalization type: "no-cap" if no uppercase letter appears in , (e.g., apple) "first-only-cap" if the first letter of is the only uppercase letter appearing in , (e.g., Berlin) "all-cap" if all letters of are uppercase, (e.g., IBM) "oddly-cap" otherwise. (e.g., TeX) How jspell handles the capitalization is best explained through an example: ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ word in dictionary ³ jspell recognizes ³ jspell spots ³ ÃÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´ ³ apple ³ apple, Apple, APPLE ³ APple ³ ³ Berlin ³ Berlin, BERLIN ³ berlin, BerLin ³ ³ IBM ³ IBM ³ ibm, Ibm, iBm ³ ³ TeX ³ TeX ³ tex, Tex, TEX ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ II.3.3 Menu User action can be made by pressing a command key or clicking the left mouse button. The location of the currently highlighted area, as well as the key pressed or mouse button clicked, affects the action. For instance, pressing the command key ENTER adds the spotted word into the user dictionary if the menu button [Add to user.dic] is being highlighted at that moment, but replaces by a suggested word if the suggested word is being highlighted. You can move the highlighted area by arrow keys. From now on, "use the menu button " means "click the left mouse button on or press ENTER while is being highlighted". If you press a key that is not a command key or click a mouse button when the mouse location is irrelevant, then it will be silently ignored by jspell. Following are the list of actions that can be made by the user. Get help: On-line help screen pops up if the command key F1 is pressed. You can escape the help screen by hitting ESC or get the second level help screen by hitting F1 again. Clicking the right mouse button has the same effect as hitting ESC. Edit: When the edit row is being highlighted, you can edit the spotted/highlighted word in the edit row. You can type in any legal characters and special characters. If you have a US-keyboard and wants to enter extended ASCII character, then type in the corresponding ASCII code using the numeric keys while holding down the Alt key: e.g., you may use Alt-129 for entering umlaut u. If you want to insert a space inside a spotted word, then use Shift- instead of . This is because is a command key for [Ignore]. You can toggle between the insert mode and the overstrike mode by hitting the INS key. The cursor is a half-block in the insert mode and an underscore in the overstrike mode. The usual editing keys like LeftArrow, RightArrow, HOME, END, Backspace, DEL, Ctrl-Backspace, Ctrl-T work as expected. ESC key clears the edit row. If ESC is pressed while the edit row is empty, then it works as an [Ignore] key. You may move the cursor by clicking the left mouse button on the position you want. (This cursor movement by mouse clicking should work even when the edit row is not being highlighted.) Ignore: You can ignore the currently spotted word by hitting Alt-I or . Alternatively, you may use the menu button [Ignore]. Global ignore: You can ignore the currently spotted word to the rest of the file by hitting Alt-G or Ctrl-. Alternatively, you may use the menu button [iGnore all]. Replace: Refer to (Section II.3.4). Global replace: Refer to (Section II.3.4). Mark: Sometimes you may not be sure whether the spotted word is misspelled or not, and you don't have a dictionary at hand. In this case you can "mark" the word by hitting Alt-M. Then the spotted word will be marked by appending "QQ" at the end. Alternatively, you may use the menu button [Mark]. Later you can change this marked word appropriately using a text editor. Global mark: You can mark the currently spotted word and all the subsequent occurrences of by pressing the key Alt-K. Alternatively, you may use the menu button [marK all]. Add the spotted word into the main user dictionary: Refer to (Section II.3.5). Add the spotted word into the file specific dictionary] Refer to (Section II.3.5). Undo: You may undo your last action, which is always displayed at the bottom of the screen, by pressing Alt-U. Alternatively, you may use the menu button [Undo]. A window will pop-up asking you to choose one among the three options "Undo", "Cancel" or "Undo further", whose meanings should be obvious. Up to 400 levels of undoing is allowed. Exit: You may exit from jspell before finishing spell-checking the current input file by hitting Alt-X, or alternatively, by using the menu button [eXit]. A window will pop-up asking you to choose one among the three options: Yes (save changes before exit), or No (do not save changes and exit), or Cancel (do not exit, and continue jspell). By "change" we mean any replacement of words and/or addition of words to user dictionaries (main user dictionary or file specific dictionary). Among these twelve possible user actions, some need more detailed explanations, which are given in the following two sections. When you are done with the last misspelled word in the input text file, jspell opens a dialog box asking you to choose "Exit" or "Cancel", thereby giving you a chance of undoing the last action. Also jspell shows some information about the session such as the number of words processed, number of words added to the main user dictionary etc. II.3.4 [Replace] and [rePlace all] There are various ways of replacing the spotted word by a correctly spelled word. First, if you want to replace by the word in the edit row, then you may do so, by (i) pressing ENTER or Alt-R while the edit row is highlighted, or (ii) use the menu button [Replace]. (If the word in the edit row is the same as the spotted word, then jspell actually [Ignore]s instead of [Replace]ing.) Second, if you want to replace by one of the suggested words, then you may do so by one of the following three methods: (i) hitting the highlighted (or Alt'ed and highlighted) numeral in front of the wanted word, or (ii) highlight the wanted word and press ENTER or Alt-R or click on the menu button [Replace], or (iii) just click on the wanted word in the suggestion area. The menu [rePlace all] is just the global version of [Replace]. Note note that global replacement by a suggested word can be done by clicking mouse on that word while pressing down the Ctrl key. Things get a little bit complicated if the "correct word" you want to replace is illegitimate or not in the dictionary. In the first case jspell asks the user confirmation. In the latter case, jspell opens a pop-up window asking you to choose one of the following: Add to "
" and Replace, or Add to "" and Replace, or Ignore and Replace, or Cancel. The meanings of these four options should be obvious. Such a "composite action" can be undone by user's request, like any other actions, of course. II.3.5 Adding spotted word to user dictionaries When the user wants to add a new word to the dictionary, the user has the option of choosing the main user dictionary or the file specific user dictionary. You may do these actions by the menu [Add to
] or [add To dic] whichever is appropriate. If the spotted word has capitalization type "first-only-cap" or "all-cap", then jspell asks the user to choose the actual capitalization type to be put into the dictionary. Note that an "oddly-cap"ped word, as well as a "no-cap"ped word, is directly put into the dictionary without such a confirmation step. If a word with the capitalization type first-only-cap or all-cap is spotted and you want to add this word to a user dictionary (main user or file specific) without altering the capitalization type, then you probably don't want be bothered by the dialog box which asks you to choose the actual capitalization type. In this case you may skip the confirmation step by doing the action (either by command key or by mouse click) while pressing down the Shift key. (Recall that the Shift key has something to do with the upper/lower case of letters.) If the main user dictionary is initially empty but some words are added in there during a jspell session, then a fresh main user dictionary is created in the jspell directory (assuming that the file/path-name is allowed by DOS). If the file specific dictionary is initially empty but some words are added in there during a jspell session, then a fresh file specific dictionary is created in the current directory (with a similar assumption on the file/path-name). II.3,6 Miscellanies One of the first things that jspell does at the beginning of a session is to check whether the input file is really an ASCII text file. jspell does this ASCII-test by examining the first 1024 bytes of the input file. If the NULL character exists in this beginning part of the input file, then jspell exits with an appropriate error message. There are certain restrictions to the input file, say . If is read-only (i.e., not rewritable), then jspell exits with the message "" is READ_ONLY This is because the changes made by jspell cannot be saved in the read-only file . A similar test is done on the main user dictionary and the file specific user dictionary. When the backup option is set, and if the input file has extension ".bak", then there is no way to make any change to the input file and at the same time keep the backup copy of the original with the filename .bak. In this situation, you'll be warned: that is, you'll have the option of disabling the backup option for the session or just abort at that moment. jspell refuses to work on a file whose filename extension is ".dic". jspell needs about 400K bytes of free memory. The rest of the memory is used as input file buffer. If the input file size is so large that the input file buffer gets full while running jspell, then the overspilt text is saved to the disk. You can't undo an action made on this already-saved part of the text. But even if the buffer gets full and some part of the text is saved to the disk, if you abort jspell by the menu [eXit] and choose not to save the changes made so far, then it'll work without any problem: i.e., the input file remains intact. II.4 Configuration files and command line options jspell uses two configuration files, jspell.cfg and jsptex.cfg. Both are plain ASCII text files that can be freely edited by any text editor. The configuration files should exist in the jspell directory. But the current working directory is first searched as usual. In each lines of these two configuration files, if a space character or the TeX comment character % is encountered then the rest of the line is ignored. In particular, if a line starts with a space of %, then the whole line is ignored. If any illegitimate entry is found in a configuration file, then jspell exists with an error message showing where it has happened. It should be stressed that the order of the entries in the configurations files is important. Be careful not to mess this up. jsptex.cfg has been explained in detail in (Section II.2.3). Hence we'll only look at jspell.cfg in this section. A typical jspell.cfg file is shown below: AT %1. keyboard (AT or XT) VGA %2. video card (CGA,EGA,VGA or Hercules) Enhanced %3. color option (Standard, Enhanced, Monochrome or Laptop) 10 %4. (0-99) (pop-up window explosion speed, delaying interval) *.dic *.txt %5. dictionary filenames pattern MathIgnore %6. MathIgnore or MathNoIgnore (math ignore in TeX) BackUp %7. BackUp or NoBackUp 8 %8. (1-16) TabSize Numbered %9. Numbered or NoNumbered (suggested word list) pNoIgnore %10. pIgnore or pNoIgnore ('%' ignore in TeX) 2 %11. (2-9) Minimum word length base.dic %12. default base dictionary user.dic %13. default main user dictionary > %14. lines starting with this string are ignored The first three entries have already been explained fully in (Section I.4). The fourth entry is the delay interval (in milliseconds) of the explosion speed of pop-up windows. It must be an integer in between 0 and 99. Smaller value results in faster explosion. The fifth entry is for dictman only, and hence will not be explained here. The sixth entry is used to set/unset the math ignore mode. It should be either MathIgnore or MathNoIgnore. This has effect only when the TeX mode is used. The seventh entry is used to set/unset the backup mode. It should be either BackUp or NoBackUp. If the backup mode is set, then a jspell leaves a backup .bak of the original input file .. Otherwise no backup file will be left. This has no effect on dictman. The eighth entry is the tab size. If the input text file contains the tab characters (ASCII code 9), then it is expanded to n spaces where n is the number specified by this entry. We require 1 <= n <= 16. This has no effect on dictman. If the ninth entry is Numbered, then jspell displays a highlighted numeral in front of each suggest word. (The numeral can be used to choose the corresponding word to replace the spotted word.) In case the mouse is installed, then you might want not to display those numerals. Replace Numbered to NoNumbered to this end. This has no effect on dictman. The tenth entry is about the after-%-ignoring feature in TeX. It should be either "pIgnore" or "pNoIgnore". This has effect only when the TeX-mode is used. If you choose pIgnore, then jspell ignores everything in a line after the first encounter of a nonliteral %. Choosing pNoIgnore disables this feature. The eleventh entry sets the minimum word length MinWordLen. Any sequence of characters with length less than this variable MinWordLen will not be considered as a word by jspell and dictman. MinWordLen must take value in between 2 and 9. The next two entries are the default names of the base dictionary and the main user dictionary (in this order). The last entry is a string s such that every line in the input text file starting with (space characters followed by) s is ignored. This feature may be useful in spell-checking a reply to an email message. You can disable this feature by entering an empty line at the end of the file jspell.cfg. Many of the configuration variables above can be overridden by command line switches as follows. The default base dictionary name is overridden by the switch -bd: jspell -bd ... The main user dictionary name is overridden by the switch -ud: jspell -ud
... MinWordLen is overridden by the switch -len: jspell -len n ..., where 2 <= n <= 9. Math ignore mode is overridden by the switch -math[+-]: -math (or equivalently -math+) sets the math ignore mode on and -math- sets the math ignore mode off. After-%-ignore mode is similarly overridden by the switch -percent[+-]. There are two more switches available. One is used to override the default file dictionary name. If the input file name is ., then the default file dictionary name is ... The other is used to override the TeX-mode, which is set on/off if the filename extension is/(is not) ".tex". The switch -t[+-] is used to override this convention: jspell -t . to force TeX-mode on the input file . and jspell -t- .tex to force non-TeX-mode on the input file .tex. -t+ has the same effect as -t. The list of all these 7 switches available can be displayed by entering the command jspell with no command line argument, as explained in the Test drive section. More than one switches can be used in any order: for instance, the command jspell -t -bd german.dic -len 3 text.1 or equivalently, jspell -bd german.dic -len 3 -t text.1 spell-checks the input file text.1 with TeX-mode on, MinWordLen = 3 and base dictionary = german.dic. II.5 Usage tips Each user dictionary can hold fairly large number of words---the limit is 5,000. But it's a good idea to use user dictionaries only for technical words (used in various disciplines of science such as mathematics, medicine, psychology etc.) or personal words (like your friend's names). Words with general nature should be merged to a base dictionary using the accompanying dictionary manager dictman. This is because there is a substantial difference in the speeds of loading base dictionaries and user dictionaries---base dictionaries are loaded into computer memory much faster. (This has been discussed in (Section II.1.2). Note that once the dictionaries are loaded into computer memory, there is no speed penalty for having lots of words from user dictionaries.) Also you can get significant space savings, both in disk and in the computer memory, by this dictionary merging. The rest of this section is devoted for TeX-mode. When spell-checking a TeX document (with lots of mathematics), it's in general better to run TeX before jspell. For instance, if you ended a math mode started by \begin{eqnarray} with \end{eqnarray*} by mistake, then jspell will ignore all the rest of the file starting from \begin{eqnarray}. Such a pitfall can be avoided by spell-checking only TeX-correct files. Another hard-to-catch pitfall may occur when you use the TeX commands in the verbatim mode. This manual uses tons of such constructions. Sometimes we need to use a misspelled word in a document. For instance, this manual used the misspelled word "teh" several times. But it is not a good idea to put this word "teh" in the file dictionary because that would let genuine typos of "teh" unspotted by jspell. One way to overcome such a problem is to use a dummy TeX-command with arity 1: that is, define a command \dummy by \newcommand{\dummy}[1]{#1} Then put a line 1dummy in the TeX configuration file jsptex.cfg. Then whenever a misspelled word, say "teh", needs to be used in the document, use \dummy{teh}. This command \dummy can be conveniently used in ignoring parts of the input text in other situations---for instance, a program listing in verbatim mode. Even if it is TeX-correct, there is some possibility that jspell is fooled: for instance, TeX doesn't complain anything (and produces the correct .dvi file) if you begin a math mode by $ and end it by \). But jspell is less tolerant on this kind of asymmetry. Other ways of fooling jspell by use of the TeX comment character % has been discussed already in (Section II.2.5). Chapter III. User's guide for dictman --------------------------- III.1. Introduction Entering the command dictman ? at the DOS prompt displays the following on the screen: Usage: dictman [-options...] option = -len n (2 <= n <= 9) -t[+-] -math[+-] -percent[+-] Note that dictman does not accept any input file as a command line argument. Each command line switch has the same function as in jspell: i.e., -len n is used to set the minimum value 2 <= n <= 9 for the legitimate word length, -t[+-] is to force TeX/non-TeX-mode, -math[+-] to force math-ignore/math-no-ignore mode and -percent[+-] to force after-%-ignore/ after-%-no-ignore mode. This should be enough explanation on the command line switches for dictman. An important difference between dictman and jspell exists in the way the TeX-mode is selected (in case it is not forced by the command line switch -t[+-]). In jspell the default mode was determined by the extension of the input file name---the TeX-mode is selected if the extension is .tex and not selected otherwise. In dictman, the TeX-mode is always assumed unless the contrary is forced by the switch -t-. This is because the name of a dictionary file containing words using TeX constructs, such as \", \oe etc., has no compelling reason to have the extension .tex. Moreover, even if the non-TeX-mode is selected by the switch -t-, it has effect only on the menu item [UserDic][Read]. dictman shares the two configuration files jspell.cfg, jsptex.cfg and the help message file jspell.hlp with jspell. As was explained before, some of those configuration variables have no effect on dictman, and conversely, one of the variables, namely the fifth one, has effect on dictman only. We will be back to this topic in (Section III.3). dictman provides us with pull-down menu and context sensitive help system. Left mouse button is normally used in clicking and dragging while right mouse button is normally used for canceling. Arrow keys and the usual command keys such as HOME, END, ENTER, ESC behave as expected. Help key is F1 of course. If you need help on a particular menu item, then highlight that item and hit F1. If you use mouse, then hit F1 while the (left) button is being pressed on the menu item. Throughout this manual, a menu item of dictman will be denoted in the following format: [first level][second level] For example, [File][Clear Screen] menu, which is used to clear the main display area, can be shown by pulling down the first level menu item [File]. The main display area saves the previous 200 lines---you can scroll back and forth using the keys Ctrl-UpArrow, Ctrl-DownArrow, PageUp, PageDown, Ctrl-PageUp and Ctrl-PageDown. (If you use XT-keyboard, then use Shift-UpArrow and Shift-DownArrow instead of Ctrl-UpArrow and Ctrl-DownArrow respectively.) Regular expressions are used frequently in dictman. Our convention on regular expressions are as follows: * matches any string, ? matches any single letter, [] matches a single letter as in the following examples: [arD] matches `a', `r' and `D'. [p-s] matches `p', `q', `r' and `s'. [3-5p-sXQa] matches `3', `4', `5' `p', `q', `r', `s', `X', `Q' and `a'. \ is the escape character: for instance, the regular expression \*[a-c\-]?\\ matches any string of length 4 that starts with `*', ends with `\' and has `a', `b', `c' or `-' as the 2nd character. Note that we use above convention for filenames too. This is a little bit different from the usual DOS file name wild card convention. For instance the regular expression `*' matches all files in dictman, but it only matches files with no extension in usual DOS environments. III.2 Running dictman, the dictionary manager In this section, all the menu items are explained. Some of the more important items are briefly explained here and then revisited (with details) in later sections. For the basic (but technical) definitions of words and dictionaries, the readers are referred to (Section II.1). When dictman starts, you will see five first level menu items: [File], [BaseDic], [UserDic], [Utilities] and [Help=F1]. We look at each of these five in the following subsections. III.2.1. [File] menus Under this menu File], there are 4 second level menu items: [Directory], [Clear Screen], [Save Screen] and [Exit=Alt-X]. These are the utilities related to files or the main display area. [Directory] This menu item displays the directory listing of files x such that (i) the filename of x matches the current dictionary name pattern, and (ii) x exists in the current directory or in the jspell directory. You'll get prompted to enter the dictionary name pattern in a dialog box. The default pattern is given in the configuration file jspell.cfg as the 5th entry. More than one regular expressions separated by spaces are allowed in this pattern. [Clear Screen] Clears the main display area. [Save Screen] Saves the current content of the main display area to a file "snapshot.0". If snapshot. exists already, then it is saved as snapshot., where n = 0, ... 8. If you execute this menu item when n reached 9, then it is written over snapshot.0 with a warning message. [Exit=Alt-X] Exits dictman. Asks whether to save any change made during the session. III.2.2. [BaseDic] menus Under this menu [BaseDic], there are 10 second level menu items: [Load], [Save], [Insert a word], [Delete a word], [Delete Words], [Count], [Find], [Clear], [Optimize] and [Expand]. These are the utilities related to base dictionaries. [Load] Loads a base dictionary into the computer memory. Current content of the combined base/user dictionary in the memory is erased. You are prompted to enter the filename. The default filename is given in the configuration file jspell.cfg as the 12th entry. The default directory conforms to the directory searching rule as explained in (Section II.1.3). Gives warning if the dictionary file is read-only. [Save] Saves the current base dictionary in the memory to the disk. You'll get prompted to enter the file name. If the dictionary file is read-only, then gives warning and aborts the save action. [Insert a word] Inserts a word to the base dictionary. You'll get prompted to enter the word. The TeX-mode is always assumed. [Delete a word] Deletes a single word from the base dictionary. You'll get prompted to enter the word. The TeX-mode is always assumed. [Delete Words] Deletes all words in a file from the base dictionary. You'll get prompted to enter the . The file must contain one word per each line, because only the first legitimate word in a line is read. The user dictionary need be empty to execute this menu item. The TeX-mode is always assumed. [Count] Counts the number of words in the base dictionary that match the input . You'll get prompted to enter a regular expression for this . [Find] Finds (and displays) the words in the base dictionary that match the input . You'll get prompted to enter a regular expression for this . Up to 80 words can be displayed. [Clear] Clears the base dictionary from the computer memory. [Optimize] Using common prefix/suffixes, optimizes the base dictionary. For instance, "wanted" is absorbed to "want" (assuming that both words exists). Substantial space saving is obtained by doing this. (For English only in the current version.) The user dictionary need be empty to execute this menu item. [Expand] Write the entire content of the base dictionary in the computer memory to a text file, one word per each line, sorted alphabetically. You'll get prompted to enter the file name. III.2.3. [UserDic] menus Under this menu [UserDic], there are 7 second level menu items: [Read], [Save], [Count], [Find], [Clear] and [Merge to BaseDic]. These are the utilities related to user dictionaries. [Read] Reads a text file and inserts all new legitimate words in it, that are NOT already in the combined base/user dictionary, into the user dictionary. Existing data are not cleared. You'll get prompted to enter the file name. Warns if the file is read-only. The TeX-mode is assumed unless the contrary is forced by the command line switch -t-. Since a user dictionary can hold at most 5,000 words, all words in the user dictionary are automatically moved to the base dictionary each time the user dictionary gets full (i.e., reaches the 5,000 word limit). So, for instance, if 11,200 words are read from a text file using this menu item, then 10,000 words will be read into the base dictionary and the remaining 1,200 words will be read into the user dictionary . [Save] Saves the user dictionary in the computer memory to a disk file. You'll get prompted to enter the file name. If the file is read-only, then gives warning and aborts the save action. [Count] Counts the number of words in the user dictionary that match the input . You'll get prompted to enter a regular expression for this . [Find] Finds (and displays) the words in the user dictionary that match the input . You'll get prompted to enter a regular expression for this . Up to 80 words can be displayed. [Clear] Clears the user dictionary from the computer memory. [Merge to BaseDic] Merges (i.e., moves) all words from the user dictionary to the base dictionary. Normally, you should execute the menu item [BaseDic][Optimize] right after this. III.2.4. [Utilities] menus Under this menu [Utilities], there are 5 second level menu items: [Legal Characters], [Legitimacy], [Count], [Find] and [Clear]. These are the utilities related to the combined base/user dictionaries. [Legal Characters] Prints all the characters (legal and/or special), with their ASCII codes, that can be used in words. [Legitimacy] Tests whether a word is legitimate. You'll get prompted to enter the word. The TeX-mode is always assumed. [Count] Counts the number of words in the combined base/user dictionary that match the input . You'll get prompted to enter a regular expression for this . [Find] Finds (and displays) the words in the combined base/user dictionary that match the input . You'll get prompted to enter a regular expression for this . Up to 80 words can be displayed. [Clear] Clears the combined base/user dictionary from the computer memory. III.2.5. [Help=F1] menus Under this menu [Help=F1], there are 5 second level menu items: [About], [Getting Help], [Keyboard & Mouse], [Configuration] and [Manual]. These are the on-line help messages of dictman. [About] About dictman. [Getting Help] How to get on-line help. [Keyboard & Mouse] Explains the basic usage of the keyboard and the mouse in dictman. [Configuration] Some information on hardware compatibility and configuration. [Manual] A short manual of dictman. III.3. Dictionary maintenance III.3.1. Merging user dictionary to base dictionary Although each user dictionary can hold up to 5,000 words, it's a good idea to keep the size of a user dictionary far less than this limit. The reason is two-fold: first, dictionary loading of base dictionary is several times faster than that of user dictionary. Second, base dictionary is more space efficient than user dictionary. This is due to the inherent structural difference between the two types of dictionaries. Base dictionary is built to be efficient in space and time. User dictionary is built for easy maintenance---it can be managed by direct editing by any text editor. When jspell is used over a network, several users may share the same base dictionary. So it may not be always the best to merge all words in all user dictionaries to the base dictionary. The rule of thumb is that words with general nature should be merged to the base dictionary and words with personal or special nature (e.g., friends' names or technical jargons) should be kept in user dictionaries. Normally, only one base dictionary should be sufficient for a language. For instance, american.dic, british.dic, german.dic, french.dic etc. ** An example of dictionary merging procedure: Suppose that we want to merge all words of the main user dictionary user.dic to the base dictionary base.dic. In any directory, start dictman by the command dictman Load the base dictionary by the menu [BaseDic][Load]. Then read the user dictionary by the menu [UserDic][Read]. Be careful to check the full pathname of the dictionary files. Merge the user dictionary to the base dictionary by the menu [UserDic][Merge to BaseDic]. Now the user dictionary will be empty because all words have been moved to the base dictionary. Then optimize the base dictionary by the menu [BaseDic][Optimize]. Finally save the base dictionary by the menu [BaseDic][Save]. At this point the user dictionary file still exists in the disk. Delete the user dictionary by a DOS command (after you exit from dictman). (If you want to keep the old user dictionary file, then rename user.dic to another, say userold.dic). III.3.2 Deleting words from a base dictionary You may want to delete a word from a base dictionary for various reasons. The obvious situation is that you found a misspelled word in your base dictionary. No matter how you are cautious, some words in most user dictionaries (or base dictionaries after merging) are misspelled. (Typical public domain word lists contain several misspelled words in every thousand words. Spell checkers included in leading commercial word processors have fewer misspelled words but not perfect.) Also it may happen that you want to delete a correct-spelled word from your base dictionary. "abut" and "manger" are examples of such words. They are more likely to be typos of "about" and "manager" respectively. There are two menu items in dictman that are used in deleting words. One is [BaseDic][Delete a word] and the other is [BaseDic][Delete Words]. Using the first, you can delete a word that you type in at the prompt. Using the second, you can delete a list of words saved in a text file, one word per line. If, for some reason, you have a to-be-deleted-words file that contains more than one word per line, then use the menus [UserDic][Read] followed by [UserDic][Save] to obtain a one-word-per-line text file. (Incidentally, the resulting file will be alphabetically sorted.) III.3.3. Building up your own base dictionary This section is about building up a base dictionary starting from scratch. You will definitely need to do this if you use any language other than English (in fact, American English). Normally you will need two steps in doing this: (i) Prepare a word list. (ii) Build a base dictionary from the word list. The easiest way to prepare a word list is to use an already compiled list of words. It should be not too difficult to obtain a public domain word list by anonymous FTP. The drawback of this method is that such a list usually contains a lot of misspelled words. A harder method is to type each and every word appearing in a well-known dictionary yourself. Not recommended---very time consuming and unreliable (i.e., lots of typos). Here is a lazy way: first prepare a short list of very frequently used words. (In English, words such as "the", "of", "to", "this", "that", "be", "is", "are", "go", "come" ... may be used.) You build a small base dictionary consisting of these words as explained in (Section III.3.1). Then you just do spell-checking using this tiny base dictionary, collecting new words in your main user dictionary each time you use jspell. When the main user dictionary gets large, say > 500 words, then merge it to the base dictionary. Since an ordinary person uses less than 3,000 words excluding technical words in his/her specialization, your base dictionary will soon get stabilized (i.e., no fuss of adding too many words in a single spell-check session). (The number of words in the King James Version Bible is less than 13,000 despite the fact that it contains so many geographical and personal names.) If you are going to spell-check files that are prepared by yourself only, then this lazy method is not bad. You will have the advantage of having a compact (and hence fast loading) dictionary. So this method is recommended for users of old XT-computers. Another good method is to use other available spell checkers. You first grab tons of text files. (Well, 10 Meg should be sufficient. Other than your own documents, Usenet is an excellent source of such text files in your specialization field.) Using the method in (Section III.3.1), you build a base dictionary, which is very likely to contain lots of misspelled words. Then get an ASCII text file, say consisting of the words in the base dictionary using the menu [BaseDic][Expand]. (The reason why we are not using user dictionary instead is because of the limit of 5,000 words for user dictionaries.) Then spell-check using your spell-checker---noninteractive one is just fine. Be sure to use a reliable spell-checker--- some of them contain too many misspelled words (UNIX "spell" is one such notorious example. "ispell" is better.) To increase the reliability, use several different spell checkers. After you have obtained a word list in this way, you can build the base dictionary with decent reliability. Don't be ambitious to build a large dictionary---because it will be tedious, unimaginative, time consuming, and (most importantly) unnecessary. Appendix A. Networked mode Let's call the directory in which jspell.exe resides the "jspell executable directory", and denote it by DIR_EXE. jspell runs in the networked mode if a file named "network" exists in the jspell executable directory DIR_EXE. Otherwise jspell runs in the single user mode. The content of the file "network" does not matter. In the networked mode, we use a directory called the "jspell configuration directory", which is denoted by DIR_CFG. Normally, this jspell configuration directory DIR_CFG is defined by the environment variable JSPELL_DIR. For instance, if you want the jspell configuration directory to be C:\MYDIC, then set JSPELL_DIR=C:\MYDIC command should be executed prior to jspell. (Normally, this should be done at booting time by autoexec.bat.) In case the environment variable JSPELL_DIR is not defined, then jspell uses the root directory of the current drive as the default jspell configuration directory. jspell.cfg, jsptex.cfg and base.dic are first searched in the current directory, and then in DIR_CFG. So each user can set his/her own configuration by putting personal configuration files jspell.cfg and jsptex.cfg in the directory DIR_CFG. If jspell fails to find jspell.cfg, then it'll use the default file jspell.cfg in DIR_EXE. The same is true for jsptex.cfg and base.dic. The main user dictionary is searched in the current directory and then in DIR_CFG but NOT in DIR_EXE. It's o.k. not to have the main user dictionary in which case it is simply treated as empty, and a fresh main user dictionary will be created in DIR_CFG if a word is put there during a jspell session. File specific user dictionary search rule is the same as that of the main user dictionary except that the fresh dictionary is created (if not already exist) in the current directory instead of DIR_CFG. Additional user dictionary search rule is the same as that of the base dictionary. Appendix B. Frequently Asked Questions Q1. Sometimes my computer hangs while loading the base dictionary. Ans. Some of your utilities, especially TSR's, may be buggy. For instance, the combination of the expanded memory manager "emm4j.sys" supplied in DOS4.0 and the popular disk-cache utility "superpck" will cause such a problem. Q2. What's the limitation of jspell? Ans. No limit on input file length. (Some limitation related to [Undo] may exist as explained at the end of (Section II.3.6).) Each line in the input file should have length <= 512 (excluding the end of line character). The length of filenames (including path) is limited by 80. Foreign language base dictionary cannot be big due to the lack of support of prefix/suffix. (I have a report saying that 23,000 German word base dictionary is o.k. but 27,000 words cause insufficient memory error.) This will be improved in the future versions. Q3. I don't like the Enhanced color scheme of jspell. Ans. You can switch to the Standard color scheme (or to the Monochrome or Laptop color scheme) by modifying the third line of the configuration file jspell.cfg appropriately. Q4. What's the plan of improving jspell in the future versions? o Windows version Appendix C. History *** Version 2.0 (Nov.15, 1993) *** Released as a shareware. o Complete documentation o Streamlined base.dic (39,000+ words). More than a hundred misspelled words have been deleted. o Consistent directory searching rule. o Configurable default base dictionary name and main user dictionary name in jspell.cfg. o More command line options in jspell and dictman. o Bug fix: (i) During scrolling a help screen of dictman, some garbage could appear occasionally. (ii) jsptex.cfg had no effect on dictman. (iii) Couldn't suggest "Thsi" ==> "This". *** Version 1.99-beta (Oct.18, 1993) *** Released only to a VERY small number of beta testers. o Network support. o The limit on the length of suggested words is increased from 17 to 40. o TeX constructs \begin{table}[htpb] and \begin{figure}[htpb] are correctly handled. o Some minor improvements in dictman. *** Version 1.84-beta (Oct.11, 1993) *** Not released. o Global ignore is now done by Alt-G and/or [iGnore all] button. Similar changes to [rePlace all] and [marK all]. o Digits at the left of suggested words are highlighted to indicate that they are command keys. o If a command key (like for [Ignore]) is pressed during the dictionary look-up process for suggesting words, then the action is immediately taken (i.e., without completing the preparation of the suggested word list). o Laptop color option added. (B/W with no bright white) o Shift-Alt-A and Shift-Alt-T enter word to dictionary without asking capitalization. The same is true for Shift-click. o Bug fix: (i) Math-ignore mode related bugs. (ii) If the input file size is in between 1025 bytes and 2048 bytes, and if Alt-X is hit when more than 1024 bytes are done, then the output file may be messed up at the tail part. (iii) dictman [UserDic][Read] menu couldn't handle some TeX constructions including the hyphenation command \-. (iv) If the input filename is user., then file dictionary get's the name user.dic}---thus filename collision. (v) dictman [UserDic][Read] menu hangs the computer if applied to large (> 1M bytes) files. *** Version 1.81beta (Oct. 1, 1993) *** Released only to a small number of beta testers. o Customizable list of TeX commands for ignoring the subsequent words. o Improved dictman in initial building up of base dictionaries. (The input word list file can contain more than 5,000 words.) o Command line option of choosing base dictionary and/or file dictionary added. o The TeX hyphenation command \- is now considered as a legitimate subword. o The command key letters in the menu buttons are highlighted. o Combined the help files jspell.hlp and dictman.hlp. o Some more little improvements. o Bug fix: (i) Memory related bugs in multilevel undoing of (global) replacement actions. (ii) Erratic behavior in math ignore mode. (iii) NoBackUp option doesn't work as expected. *** Version 1.8beta (Sep. 19, 1993) *** Released only to a small number of beta testers. o Dictionary manager dictman.exe added. o File specific dictionary, multiple user dictionary support. o Accepts foreign characters by (i) extended ASCII code (e.g., 129 for umlaut u etc.), and/or (ii) TeX/LaTeX commands (e.g., \"u, \H{o}, \L, \ss etc.). o Much better interface w/ mouse support. o Multilevel undo up to 400 steps o Better TeX/LaTeX support including the math-ignore mode. o Better word suggestion scheme for capitalized words. o Deleted hundreds of misspelled words from base.dic. o Numerous little improvements. o Bug fix: (i) Occasional name switching of the input file . and the backup file .bak when the input file is large (e.g., above 300K bytes). *** Version 1.01 (Jun. 3, 1993) *** Fixed some bugs related to the installation. Made available by anonymous FTP at garbo.uwasa.fi:pc/spell/jspel101.zip, and Simtel (and its mirrors sites) msdos/tex/jspel101.zip *** Version 1.0 (May 29, 1993) *** First public release. Made available by anonymous FTP at garbo.uwasa.fi:pc/spell/jspell10.zip