path: root/support/amspell/amspell.doc

=================
     amSpell
=================


A spell checker for ASCII and (La)TeX files
===========================================


Concepts
--------

amSpell is basically a spell checker for plain ASCII files, with some 
special features for dealing with TeX files. The program is written in 
Turbo Pascal and runs on any MS-DOS computer.

The basic idea behind this program is to make spell checking easier by

*  providing the context of the possibly misspelled word;
*  offering alternatives;
*  offering facilities for editing the word;
*  automatically replacing wrong words by the indicated words;
*  learning new words.


amSpell and (La)TeX
-------------------

amSpell does not require TeX commands to be removed. In fact, it will even 
interpret the standard accenting commands like \", \`, \' and will
automatically use them while replacing wrongly spelled words. When checking 
a TeX file amSpell will ignore all text between $'s and $$'s. Furthermore, 
amSpell will ignore the parameter of the LaTeX commands \ref, \pageref, 
\cite, \nocite, label, and all text between \begin{equation}, 
\begin{eqnarray}, \[ and their counterparts such as \]. All words starting 
with a backslash are ignored.

Naturally amSpell will conform to the capitalization in each word.

amSpell is DesqView aware. If DesqView is active, then for simple screen 
writes, it uses the BIOS and for intensive screen writes, it uses the 
Virtual Screen Buffer of DV.


Dictionaries
------------

It is convenient to make amSpell use three types of input files:

*  A file containing all jargon and correct words not included in the
   dictionary files;
*  The dictionary files: usually about 26 files, each containing all words
   with the same initial, e.g., US.00A, US.00B etc.;
*  Plus of course the file that needs to be checked.

Files of the first and third type should be kept sorted alphabetically, 
i.e., according to the ASCII table. This means that, e.g., french words 
starting with ‚ should not be appended to FR.00E, but should be separated 
in a file called FR.00‚.

These files should be plain text files containing just one word per line.
A compression program is provided (SPCOMP.EXE) as well as a decompression 
program (SPDECOMP.EXE). Compression speeds up the reading of a file and 
saves disk space.

The dictionary files are split into about 26 sections, according to the 
initial of a word. There are two reasons for this approach:

1.  Separate files are relatively easy to edit.
2.  This sectioning enables amSpell to find alternatives for words that are 
    not in the dictionaries. amSpell will look for words with the same 
    initial that somehow `look' like it, in order to correct common typing 
    errors. E.g., if you typed `egnlisch' amSpell will suggest `english' as 
    correction, but it will not find the correct spelling of `Ugoslavia'.


Parameters
----------

If you start amSpell without any parameters it will show the screen below:

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
amSpell 2.03 - Ascii/TeX SpellingChecker - Copyright (c) A. Merckens  92-08-01

All words in the input file will be checked using one or more dictionaries.
SPELL -? for more help.                                    ^Break to ABORT.

Input file                   Inputfil
Output file                  wrong.spl
Batch of Dictionaries (Y/N)  N
Dictionary                   NONE
Auxiliary dictionary         NONE

Occurrences (Y/N)            N          Capitalization (Y/N)         N
Multiple occurrences (Y/N)   N          TeX text (Y/N)               N
Linenumbers (Y/N)            N          Unsorted dictionaries (Y/N)  N
Suggestions (Y/N)            N          Edit misspelled words (Y/N)  N
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

You can interactively enter your file names and parameters.

If you want to know more about the parameters you may enter AMSPELL -? in 
which case amSpell will show the screen below:

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
amSpell 2.03 - Ascii/TeX SpellingChecker - Copyright (c) A. Merckens  92-08-01
                                                                                
Call: AMSPELL <options> <inputfile> <outputfile> <dict1> <dict2> <@optionfile>
Options are:                                                                    
  /b   - up to 100 dictionaries are named in a "Batch" file                     
  /c   - write words with Capitalization based on first occurrence              
  /d   - Directvideo off - use BIOS to write to screen                          
  /e   - Edit the misspelled words; this option puts /m on, /l and /o off       
         Words can be 'learned', i.e. appended to the file LEARNSPL.SPL         
         When editing, F1 gives help on the function of special keys            
  /h   - this Help                                                              
  /i   - Ignore missing directories                                             
  /k   - sKip spellingscheck - all words are misspelled                         
  /l   - write Linenumbers along with the words                                 
  /m   - remember Multiple occurrences with different capitalization
  /n   - Not so many screen updates (somewhat faster)                           
  /o   - write number of Occurrences of the words                               
  /q   - be Quiet: do not ask for confirmation of the command-line              
  /s[i]- search for similar words: give up to i*5 Suggestions, i=1..9           
  /t   - TeX text: do not check formulae, labels, references, cites             
  /u   - the dictionaries are Unsorted                                          
  /v   - Verify off: delete existing output file                                
  /z   - Zero screen writes                                                     
  /_   - ignore words containing an _                                           
  /0   - ignore words containing digits 0-9
  /1   - <inputfile> is not a file but a word to be checked                     
  /-   - the symbol - is NOT a word separator                                   
  /'   - the symbol ' IS a word separator

The options may be specified in the so called optionfile
                                                                                
The dictionary files are assumed to have one "word" per line,                   
or have the special SPL format.                                                 
                                                                                
The special name "NONE" means: no dictionary                                    
                                                                                
If /b is specified, then <dict1> is a "batch" file that contains                
all filenames of the dictionaries to be used.                                   
                                                                                
Copyright (C) 1992 A. Merckens - Internet: ambase@rugr86.rug.nl
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Here is a more detailed description of all parameters:
/b    up to 100 dictionaries are named in a "batch" file.
      A batch file will typically look like this:
         correct.us
         c:\tex\spell\us.00a
         c:\tex\spell\us.00b
         ...
         c:\tex\spell\us.00z
      The first line specifies the name of the file that contains correctly 
      spelled words that are not in the dictionaries (usually jargon, 
      author names etc.). The next 26 or so specify the dictionaries from a 
      through z.
      You may use environment parameters in this file. Example:
         correct.%LANG%
         %DRIVE%%SPELLDIR\us.00a
         %SPELLDIR\us.00b
         ...
         %SPELLDIR%\us.00z
      Now you can dynamically set %LANG%, %DRIVE% and %SPELLDIR% before you 
      start amSpell.
/c    write words with Capitalization based on first occurrence.
/d    Directvideo off -- use BIOS to write to screen. Use this switch if 
      your screen gets messy or shows `snow' running amSpell. This might be 
      the case on old CGA screens.
/e    Edit the misspelled words; this option puts /m on, /l and /o off. 
      Words can be `learned', i.e. appended to the file correct.us. When
      editing, F1 gives help on the function of special keys.
/h    this Help.
/i    Ignore missing directories. Normally amSpell will pause every time a 
      file or directory could not be found. It will ask whether it should 
      continue or abort. This switch will cause amSpell to ignore missing 
      files or directories.
/k    sKip spellingscheck --- all words are misspelled.
/l    write Linenumbers along with the words.
/m    remember Multiple occurrences with different capitalization.
/n    Not so many screen updates (somewhat faster).
/o    write number of Occurrences of the words.
/q    be Quiet: do not ask for confirmation of the command-line.
/s[i] search for similar words: give up to i*5 Suggestions, i = 1..9. If 
      amSpell encounters an unknown word it will search its dictionaries to 
      find alternatives. No more than i alternatives will be presented.
/t    TeX text: do not check formulae, labels, references, cites. This 
      switch makes amSpell ignore all text between $'s, $$'s, 
      \begin{equation}, \begin{eqnarray}, \[ and their counterparts, plus 
      the parameters of \ref, \pageref, \cite, \nocite and \label. All 
      words starting with a backslash are ignored.
/u    the dictionaries are Unsorted. This is not recommended because it 
      will slow down amSpell.
/v    Verify off: delete existing output file. amSpell will not ask whether 
      an existing output file should be overwritten.
/z    Zero screen writes. This switch suppresses all screen output.
/_    ignore words containing an underscore. May be useful for file names 
      in text.
/0    ignore words containing digits 0-9.
/1    <inputfile> is not a FILE but a WORD to be checked. This is 
      especially useful when using an editor macro for checking the word at 
      the cursor position.
/-    the symbol - is NOT a word separator. If your text contains e.g. 
      `outpufile' amSpell will look up `output' and `file'. However, if 
      this switch in on it will look up `output-file'.
/'    the symbol ' IS a word separator. Like the  switch.


Example of application
----------------------

Although it is possible to run amSpell interactively, it is must more
convenient to run it from an MS-DOS batch file, especially if you want to 
check your text AND correct it automatically.

A typical batch file to check the spelling of a TeX file, and correct it
will look something like this
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
   echo off
   set FNAME=%1
   set LANG=%2
   del wrong.spl
   spell.exe %FNAME%.tex wrong.spl alldicts.%LANG% @options.spl
   if not exist learnspl.spl goto nothinglearned
   copy learnspl.spl+correct.%LANG%
   spell.exe learnspl.spl correct.%LANG% @sort.opt
   del learnspl.spl
   :nothinglearned
   if not exist wrong.spl goto nowrongspl
   copy wrong.spl %FNAME%.tex
   del wrong.spl
   :nowrongspl
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

where options.spl look like this:
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
   /0 /t /b /c /m /s2 /q /n /_ /e /v /i /'
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

and sort.opt will look like this:
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
   /q /k /c /_ /v /z
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

correct.us might look like
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
   draggled
   objectfunction
   parser
   scalar
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Note that amSpell is run twice: the first time to correct the spelling, 
writing the new file wrong.spl; the second time to append the newly learned 
words (in the file learnspl.spl) to the file correct.us and sort them.


The user interface
------------------

When you start amSpell in the way described above, amSpell will first read 
your text and look up all the words it found in the dictionaries and you 
own jargon file (e.g., correct.us). Then it will search its dictionaries 
again to find alternatives for words it does not know.

For each unknown word it displays the context, and provides alternatives 
(if possible). Below you can see what the screen looks like (somewhat 
compressed) when amSpell encounters the word `LaserWriter'.

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
amSpell 2.03 - Ascii/TeX SpellingChecker - Copyright (c) A. Merckens  92-08-01

so very complex documents with a lot of fonts can easily be printed even        
on PostScript printers without much memory, such as the original Apple          
LaserWriter.  The PostScript output is also compact, requiring less disk        
space to store and making it feasible as a transfer format.                     
                                                                                
----------------------------------------------------------------------[F1 help]
                             LaserWriter                                        
Liverworts          Legislators         Legislatress        Liverwurst          
Legislatrix         Legislatures        Lubricators         Liferentrix         
Liposarcomata       Liverwort                                                   
                                                                                
                                                                                
LaserWriter
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

The word `LaserWriter' is inverted and you can choose one of the 
alternatives or edit the word yourself. Below you can see
all the keys amSpell accepts.

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
amSpell 2.03 - Ascii/TeX SpellingChecker - Copyright (c) A. Merckens  92-08-01
                                                                                
so very complex documents with a lot of fonts can easily be printed even        
on PostScript printers without much memory, such as the original Apple          
LaserWriter.  The PostScript output is also compact, requiring less disk        
space to store and making it feasible as a transfer format.                     

----------------------------------------------------------------------[F1 help]
Information on special keys when correcting spelling                            
Enter                    : Accept word for this time                            
^Enter                   : Learn word <appended to file LEARNSPL.SPL>           
F10                      : Stop correcting and write changes to file            
Left, Right, End, Home   : Keys used for editing selected word                  
Ins                      : Toggle Insert/Overwrite Mode                         
Del, BS                  : Delete character On/Before cursorposition            
Down, Up                 : Move to Next/Previous word                           
Pg-Dn, Pg-Up             : Move to word one line Down/Up                        
^T, ^Y                   : Remove rest of line                                  
^BREAK                   : Abort                                                
                                                    [Press any key to continue] 
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


Utility programs
----------------

Along with amSpell some utility programs are provided to enable you to edit 
dictionaries or make your own.

* SpDecomp: This program decompresses dictionaries.
  The syntax is: SPDECOMP [inputfile] [outputfile]. Default inputfile and 
  outputfile are the console. Example: spdecomp us.00a us.a.

* SpComp: This program compresses dictionaries.
  The syntax is: SPCOMP [inputfile] [outputfile]. Default inputfile and 
  outputfile are the console. Example: spcomp us.00a us.a. Note that 
  compressing is not required. amSpell reads both normal text files and 
  compressed files.

* In case you merge dictionaries, you may want to exclude double entries. 
  You can use amSpell to write a sorted output file leaving out all double
  entries.
  Call amSpell like this: AMSPELL <inputfile> <outputfile> @NODOUBLE.OPT
  Because amSpell does not require words to be on separate lines, you can
  even use this trick to generate a dictionary from a standard text file.

* ABC: If you have a wordlist file that contains all words starting with a, 
  b, c etc., you can use this program to split it into separate files 
  according to the word initials. Naturally, the file must be sorted 
  alphabetically.
  The syntax is: ABC <inputfile>. The program will produce the files 
  words.00x, where x stands for the initial of a word. It starts a new file 
  (new x) for each initial.

* CrLf: Wordlists copied from a Unix system typically end each line of text 
  by a lone `CarriageReturn'. MS-DOS programs (like ABC and amSpell) will 
  only work correctly on files that end each line of text by a 
  `CarriageReturn' + `LineFeed'. CrLf can convert Unix files to MS-DOS 
  files.
  The syntax is: CRLF [inputfile1 inputfile2 ...]. Default inputfile is the 
  console. For each file it will ask confirmation for conversion.


Availability
------------

amSpell is available on many anonymous file servers such as Simtel. It is 
FREE OF CHARGE and may be used by anyone who wishes to. So, also in a 
commercial/educational environment. However, you are not allowed to remove 
the Copyright Statement, or to sell this program, or bundle it with other 
(commercial) goods. You may give it to anyone you like, but only in its 
original form with the complete documentation.

If you have any (positive or negative) comments or suggestions, we would 
like to hear from you.

Furthermore, we will not be held liable for any misfortune that may or may 
not happen to you, which may or may not be the result of using or not using 
this program. In other words, the usual disclaimer applies here.


Support
-------

In case you have questions about amSpell, or have suggestions for 
improvements, or found a bug, please contact:
Erik Frambach
Faculty of Econometrics
University of Groningen
Netherlands
Email: E.H.M.Frambach@eco.rug.nl
or     frambach@rugr86.rug.nl


Acknowledgments:

The idea of creating amSpell sprouted from the minds of the "TeX group":
Wietse Dol, Maarten van der Vlerk, Erik Frambach. This group gave me much
feedback on amSpell. Especially Erik Frambach, who has not only written this
documentation (except for these few lines), given me numerous useful
suggestions and pointed me to some bugs, but is also willing to handle all
questions about amSpell. Thanks, Erik!


Program history:
* version 2.03
  Name changed from Spell to amSpell. Donated to public domain. Fixed some 
  minor bugs and added some features: accent on first letter of word no 
  longer disappears; all words starting with a backslash ignored 
  (texcom.spl now obsolete); treat \[ like \begin{equation}, and likewise \];
  expand environment parameters in filenames.
* version 2.02
  Minor bug fixes.
* version 2.01
  amSpell released for small public.
* version 2.0
  Major user interface change + many bugs fixed
* version 1.0
  First release.


Other software donated to the public:

ACD - Another Change Directory; quickly change between directories;
      Is better than and has more options than LCD or NCD.
      Current version ACD210.ZIP - date: August 1, 1992