JSPELL 2.11 (Release date: Oct.21, 1998)
Copyright 1993-1998 by Joohee Jeong
Email:
[email protected]
==========================================================
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...] <filename>
to spell check <filename>, where
option = -bd <base dictionary name>
-ud <user dictionary name>
-fd <file dictionary name>
-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 <filename>, 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.<ext>, where <ext> 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 <word> of legal characters and/or special
characters can be considered to be a legitimate word only if the
length of <word> 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 <sample>
will ignore all words in the text file <sample> that has length
1 or 2.
Suppose that <word> has proper length. In non-TeX-mode, the
only special character that can appear in <word> is the
apostrophe ('). Moreover, there's some restriction in the use of
apostrophe in <word>. It must occur at the end of <word> 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 <word> 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 <filename>
will spell-check the file <filename> 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 <filename>
will spell-check the file <filename> 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 <filename>.<ext>
is defined to be a user dictionary with filename
<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 <filename>
will spell-check the file <filename> using the file dictionary
"project1.dic" (instead of the default one <filename>.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
<filename>.<ext> by specifying them in the file dictionary, say
<filename>.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 <filename>.dic---so the
content of the resulting file dictionary for our input file
<filename>.<ext> should look like:
+math.dic
+comp.dic
<word1>
<word2>
...
...
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 <badword>, (ii) the dictionary that contains
<badword> and (iii) the line in which <badword> occurs. You
should immediately delete or fix this <badword>.
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 <filename>.<ext> by
jspell -t <filename>.<ext>
Conversely, you may force non-TeX-mode to the file
<filename>.tex by
jspell -t- <filename>.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
<word> appearing as \cite{<word>}. Since <word> 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 <word1> and <words2>
appearing as
\newcommand{<word1>}{<word2>}
Note that <word1> and/or <word2> 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
<n>mycommand,
where <n> is a numeral, then the arity of \mycommand will be set
to be <n>. An exception to this is the <n> = 0 case. This is
supplied to treat some commands like \input that has fuzzy
syntax. (Both "\input <filename>" and "\input{<filename>}" 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:
$ <math mode> $
$$ <math mode> $$
\( <math mode> \)
\[ <math mode> \]
\begin{math} <math mode> \end{math}
\begin{equations} <math mode> \end{equation}
\begin{eqnarray} <math mode> \end{eqnarray}
\begin{eqnarray*} <math mode> \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+ <filename>
will force jspell to spell-check text in math mode and
jspell -math- <filename>
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 <filename>, you first go to the
directory in which <filename> resides and then enter the command
jspell [-options...] <filename>
at the DOS prompt. (<filename> may contain path. In this case
you don't have to go to the directory of <filename> 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
<word> in <filename> (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. <word> 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 <word> is the
first misspelled word in <filename>).
Words in the jspell's dictionary that are *close* to <word> 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 <filename>.bak
(assuming that the input file has filename <filename>.<ext>) 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 <filename>.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 <word> has capitalization type:
"no-cap" if no uppercase letter appears in <word>,
(e.g., apple)
"first-only-cap" if the first letter of <word> is the
only uppercase letter appearing in <word>, (e.g., Berlin)
"all-cap" if all letters of <word> 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 <spotted.word> into the user
dictionary <user.dic> if the menu button [Add to user.dic] is
being highlighted at that moment, but replaces <spotted.word> by
a suggested word <suggested.word> if the suggested word
<suggested.word> is being highlighted. You can move the
highlighted area by arrow keys.
From now on, "use the menu button <menubutton>" means "click
the left mouse button on <menubutton> or press ENTER while
<menubutton> 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-<space> instead of <space>. This is because
<space> 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 <space>. 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-<space>.
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 <word>
and all the subsequent occurrences of <word> 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 <word> by a
correctly spelled word.
First, if you want to replace <word> 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 <word> 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 "<main user dic>" and Replace, or
Add to "<file specific dic>" 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 <main user dic>] or [add To <file specific> 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
<filename>. If <filename> is read-only (i.e., not rewritable),
then jspell exits with the message
"<filename>" is READ_ONLY
This is because the changes made by jspell cannot be saved in
the read-only file <filename>. 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 <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 <filename>.bak of the original
input file <filename>.<ext>. 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 <base dictionary> ...
The main user dictionary name is overridden by the switch -ud:
jspell -ud <main user dictionary> ...
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
<filename>.<ext>, then the default file dictionary name is
<filename}.dic. But you can override this by the switch -fd:
jspell -fd <file dictionary> ...
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 <filename>.<ext>
to force TeX-mode on the input file <filename>.<ext> and
jspell -t- <filename>.tex
to force non-TeX-mode on the input file <filename>.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,
[<string>] 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.<n> exists already,
then it is saved as snapshot.<n+1>, 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 <filename> from
the base dictionary. You'll get prompted to enter the
<filename>. The file <filename> 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 <pattern>. You'll get prompted to enter a
regular expression for this <pattern>.
[Find] Finds (and displays) the words in the base dictionary
that match the input <pattern>. You'll get prompted to
enter a regular expression for this <pattern>. 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 <pattern>. You'll get prompted to enter a
regular expression for this <pattern>.
[Find] Finds (and displays) the words in the user dictionary
that match the input <pattern>. You'll get prompted to enter
a regular expression for this <pattern>. 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 <pattern>. You'll get
prompted to enter a regular expression for this <pattern>.
[Find] Finds (and displays) the words in the combined base/user
dictionary that match the input <pattern>. You'll get
prompted to enter a regular expression for this <pattern>.
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 <mywords> 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 <mywords> 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 <space> 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.<ext>, 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
<filename>.<ext> and the backup file <filename>.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
