
          ZapSpell, a module interfacing Zap to spell checkers
          ====================================================

Features
~~~~~~~~
The module provides an interface between Zap and the 'Impress'n Spell'
spell-checking module.  It provides spell-checking of entire files and 
selections.  It offers an interface using throwback of misspelled words in
conjunction with a more next/previous misspelled word dialogue.

Operation
~~~~~~~~~
Words with lengths greater than twenty characters or less than three, are not
checked.  Non alphabetic characters, including numbers and the underscore
character (but excepting the single quote) are treated as delimiters.

The front end may be activated by the SPELL command.  This brings up a window
near the top-right hand corner of the window from which it was brought up.
This has a large number of action buttons on it.

"Previous" and "Next" locate the previous and next misspelled words in the
file (relative to the cursor position).  If there is no word that fits into
this category a beep is generated.

"Current" highlights the word nearest to the cursor and brings up a list of
alternative words based around this.

"Replace" snips the current selection, and replaces this by the contents of
the writable icon.  If there is no selection then a beep is generated.

"Add" adds the current word to the current Impression Spell user dictionary.

"Find" opens the dictionary at the nearest word to that in the writable icon.

"Cancel" closes the dialogue box.

"Check selection" feeds the entire current selection to the spell-checker and
generates throwback based on the results.

"Check buffer" feeds the entire zap buffer to the spell-checker and generates
throwback based on the results.

Clicking on dictionary entries copy the word into the writable icon.

The up and down arrows browse through the dictionary 1, 8 and 100 words at a
time.

With the cursor in the main writable icon, typing words dynamically looks
them up in the dictionary.  Cursor up/down and page up/down navigate the
dictionary, and pressing "Insert" inserts the first visible word in the
dictionary into the main icon.  Pressing "Tab" actually performs an
insertion in the document. "Return" finds the word in the dictionary.

The "Ignore" button doesn't work yet...

Impression Spell
~~~~~~~~~~~~~~~~
The 'Impress'n Spell' module is copyright (C) Computer Concepts.  The author
has asked for permission to distribute it with ZapSpell, but permission has
not currently been granted.  Consequently the module is not being supplied
with ZapSpell at the moment.

It is, however, freely available on the internet as part of the Impression
Junior package.  This is usually downloadable from Computer Concepts' web
site at http://www.cconcepts.co.uk.

The module was also made available on an 'Archimedes World' cover CD-ROM a
couple of years ago.  It's path on the CD is:

CDFS::AWCD1.$.FREESOFT.IMPRESSION.!JUNIOR.RMSTORE.!SPELLMOD;

...it was also on the second Acorn User CD ROM as:

CDFS::ACORN_U2.$.DEMOS.CCONCEPTS.JUNIOR.!JUNIOR.RMSTORE.!SPELLMOD;

...and, for good measure, the third one as:

CDFS::AUCD3.$.ADSTUDIO.DTP.IMPJUNIOR.JUNIOR.!Junior.RMStore.!SpellMod.

The version included with Impression Junior reports itself as being:

	"Impress'n Spell	1.24 (17 Dec 1992)"

...there are more recent versions of the module than this; version 1.27 is
the latest known about but the author hasn't performed any testing using
anything except version 1.24.  Version 1.27 however is reported to work with
ZapSpell.

ZapSpell has not been tested with Computer Concepts' 'Spell Master' module,
(a precursor to Impression Spell?) and probably won't work with it.

Installation
~~~~~~~~~~~~
To install, it is recommended that you use something like:

<Zap$3rdParty>.Tyler.!ZapSpell.ZapSpell Obey <Zap$3rdParty>.Tyler.!ZapSpell.!Setup
	-
	IMPRESSIONSPELL_ADDWORD		&1F
	IMPRESSIONSPELL_BUF		&1
	IMPRESSIONSPELL_CURRENT		&0
	IMPRESSIONSPELL_DELDIC		&7
	IMPRESSIONSPELL_DELWORD		&1F
	IMPRESSIONSPELL_LOADDIC		&1F
	IMPRESSIONSPELL_NEXT		&0
	IMPRESSIONSPELL_OFFSETS		&21
	IMPRESSIONSPELL_PREV		&0
	IMPRESSIONSPELL_SAVEDIC		&1F
	IMPRESSIONSPELL_SELBUF		&1
	IMPRESSIONSPELL_SELECTION	&1
	IMPRESSIONSPELL_USEDIC		&1F
	ISPELL				&1
	SPELL				&0
	SPELL_INFOBOX			&10007
	SPELL_REPLACE			&0
	WORDWORKS_SELECTION		&1
	-

...In the file called "External", in the directory "!Zap.Options.Default" or 
wherever the variable Zap$External points to.

You will also need to alter the !Setup file to point to the 'Impress'n Spell'
module, or ZapSpell will complain that the module cannot be located.

Probably the easiest way for new users to access the features provided is
through the front end provided by the 'SPELL' command.  Note that this has
not yet been completely finished.

Something like...

10 "File" 16
   "Save           " QUICKSAVE > SAVE
   "New view       " NEWVIEW
   "Print          " > 11
   "Spelling ...   " COMMAND "SPELL"
   "Word count ... " COMMAND "WC"
   "Undo enabled   " TOGGLEUNDO
   "Read only      " READONLY
   "DOS text file  " FFLAGS_TOGGLE 27
   "Search ...     " SEARCHBUF > SEARCHBUF
   "Replace ...    " REPLACE > REPLACE
   "Goto ...       " GOTO > GOTO

...in Zap's main 'Menus' file will complete the installation.

The SPELL command may very usefully be bound to a key, but it cannot yet be
used as a submenu in a menu.

Zap will need to be restarted before anything begins to work.

Commands
~~~~~~~~
Details of the commands provided may be found in the HelpData file.
Most of the functionality can be accessed through the front end provided by
the 'SPELL' command.

Clients
~~~~~~~
Modes may participate in the spell-checking process if they so choose, by
becoming ZapSpell clients.  There are only a few modes playing this role at
the moment:

ZapHoTMeaL interacts helpfully with ZapSpell.  This means that HTML texts
may be spell-checked without the user being endlessly prompted about HTML
tags and entities.

ZapMsg also participates and avoids prompting the user over message tokens.
Also, words involving "|M", "%s" and "\S" sequences and the like, which
ZapSpell would otherwise be confused by are dealt with intelligently.

StrongZap avoids checking words which are part of embedded sequences and
comments.

ZapEmail now offers pretty comprehensive support, allowing only the sections
of the email which aren't in the header/signature or in quoted sections of
the text to be checked.

ZapTeX also offers support.

More details about the support offered by these modes is available in their
respective !Help files.

Technical
~~~~~~~~~
ZapSpell uses a new reason code with e_init to confirm spelling queries with
the owning mode.
R1=9  => ZapSpell wants to know if a word is correctly spelled.
	 ;E R0=offset of the first character of the possibly misspelled word
	    (you will only be called if ZapSpell thinks it is incorrect).
	    R1 = 9
	    R2 = pointer to the last character (in a buffer with the word in)
	    R3 = length of word to be checked
	    R4 = pointer to the start of a 32 character buffer
	    R5 (byte 0) = type: 0 = BUF | 1 = SELBUF | 2 = PREV | 3 = NEXT
	                        4 = SINGLE | 5 = AS-YOU-TYPE | >= 6 reserved.
	    R5 (rest) = unique ID, maintained over a single ZapSpell command.
	    R8/R9=the relevant file
	 ;X R1 < 0 : this word is OK - don't prompt;
	       > 0 : prompt user as normal;
	       = 0 : the word was malformed - skip the first R0 characters
	             of the word and try again.  This option is mainly used
	             for parsing escape sequences.  ZapMsg uses this option;
	       = 1 : this word is OK skip to offset R0, though;
	       = 2 : prompt for this word, but then carry on from offset R0;
	       = 3 - 8 : reserved...
	       = 9 : prompt user as normal;
	       > 9 : reserved...

R1=10 => ZapSpell is about to perform a spelling operation.  Modes may
	 make modifications to the operation if they so choose.
	 ;E R0=type: 0 = BUF | 1 = SELBUF | 2 = PREV | 3 = NEXT 4 = CURRENT
	    0/1 R2=start offset R3=end offset R8/R9
	    2/3 R2=current cursor offset R8/R9/R10
	 ;X 0/1 R2 and R3 may be modified if needed
	    2/3 R2 may be changed - the cursor /may/ also have to be moved :|

Modes may modify the contents of the buffer at R4 if they so choose - they
may wish to do this if they want to modify the message given to the user in
throwback, for example.  Note that the buffer is only 32 characters long in
total.

Returned offsets are not currently sanity checked - beware of the infinite
loop.

Programming modes may if they wish restrict the spell-checked text to that
inside comments and quoted sections.  Modes may, if they wish, spell-check
their own keywords manually.

Plans
~~~~~
Interfaces with other spell-checkers are under consideration.  Be advised
that an interface with ISpell looks completely unappealing, for technical
reasons associated with ISpell's external interface.

Problems
~~~~~~~~
ZapSpell cannot 'detokenise' files before it checks them (like Zap's search
routines can).  At the moment, this mainly affects spelling of tokenised
BASIC files (where the effect is beneficial in some respects).

At the moment the list of 'suggested' words consists of an alphabetic list
of dictionary entries starting at the alphabetically nearest spelling; I'm
hoping to get hold of some documentation for Impression Spell before trying
to improve this situation.

I have contacted Computer Concepts in the hope of obtaining some
documentation for Impression Spell, but they do not appear to have addressed
my requests.

Only 'simple' user dictionaries are supported.

Interactive help messages are not yet processed by ZapSpell.

There appear to be some historical problems with the Impression Spell module.
The dictionary is not alphabetic - plurals ending in 's' are generally
stored immediately following their singular equivalents for example.
There are some strange 'words' in the dictionary.
The user dictionary format seems a trifle unusual.

Disclaimer
~~~~~~~~~~
Although the author welcomes correspondence concerning this mode (especially
about any spelling mistakes in this file), he makes no claim that it is bug
free and, it is not guaranteed to perform any particular function.  It is to
be used entirely at one's own risk.

Legal status
~~~~~~~~~~~~
This program is distributed as Freeware; it may be distributed freely
provided that all the associated files remain intact.

History
~~~~~~~
v0.15 - (11-Jan-1998)
      * Crude ability to load default dictionaries provided, by providing a
        system variable which executes an arbitrary Zap command whenever the
        !SpellMod is loaded.
        
v0.14 - (17-Oct-1997)
      * SPELL_REPLACE command updated to allow spell-as-you-type spelling
        completion...

v0.13 - (14-Sep-1997)
      * Spell-as-you-type interface created.

v0.12 - (14-Jul-1997)
      * Saving user dictionaries now supported.  No DragASprite support yet,
        and no RAM transfer protocol implemented so saving data to other
        applications may not work as expected.
      * A path is now used to specify the location of Impression Spell in the
        !Setup file.

v0.11 - (12-Jul-1997)
      * Menu added and the interface to modes extended slightly.

v0.10 - (11-Jul-1997)
      * Back end for manipulating user dictionaries constructed.  Loading
        dictionaries, and "Add" and "Delete" now work, but much more work
        needs to be done before it's usable.

v0.09 - (04-Jul-1997)
      * The writable icon has been made 'hot' so that typing into it
        instantly looks up the word in the dictionary.
      * Some problems with the location of the dictionary's end resolved.
        
v0.08 - (30-Jun-1997)
      * Cured another severe problem affecting the stability of the module.
      * Made the redraw of the window into the dictionary multi-task - the
        redraw will look slightly slower, but will allow smoother operation,
        and allow for a bigger window if needed.
        
v0.07 - (29-Jun-1997)
      * Cured a severe problem affecting the stability of the module when
        most of the commands were used.  This may not solve all the stability
        difficulties people have been experiencing, but hopefully it will.
      * Added support for various internal protocols designed mainly to
        provide support for ZapEmail.
      * Elliot Hughes' spelling commands from ZapENH included.  Many thanks
        are due to Elliot for providing me with the source code to this.
        
v0.06 - (28-Jun-1997)
      * Improvements to the caret handling code - if the caret is is the
        writable, then it now stays there when forward/next are pressed.

v0.05 - (27-Jun-1997)
      * Various bug fixes: IMPRESSIONSPELL_PREV improved; ESCAPEing improved.

v0.04 - (26-Jun-1997)
      * Options to choose between possible alternative words made available.

v0.03 - (25-Jun-1997)
      * Now reports queries using logical line numbers rather than using
        offsets in the throwback.
      * No longer goes into an infinite loop if IMPRESSIONSPELL_BUF is
        applied to an empty buffer.
      * Front end made semi-functional.
      * IMPRESSIONSPELL_CURRENT command added.

v0.02 - (23-Jun-1997)
      * The ESCAPE key is now being checked during throwback generation.

v0.01 - (19-Jun-1997)
      * Throwback and next/previous features with "Impress'n Spell" only.

Enjoy
__________
 |im |yler  The Mandala Centre - tt@cryogen.com - http://www.mandala.co.uk
