VERSION 2

ABOUT
~~~~~

This package contains instructions and files to enable spell checking on every
version of Mystic BBS software found at www.mysticbbs.com.


HOW TO INSTALL AND ENABLE SPELL CHECKING IN MYSTIC BBS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Spell Checking Capabilities
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Mystic offers the ability to perform spell checking on-the-fly, meaning it can
highlight misspelled words while you're actually typing.  Mystic can also
optionally make word suggestions as you are typing based on the current word
you are working on.

Mystic also provides a single hotkey that can pop open a list of suggested and
correctly spelled words for the word that is under the cursor.  Simply
selecting the word and pressing enter will auto correct the word in your edit
window.

About Hunspell
~~~~~~~~~~~~~~

Mystic uses the Hunspell engine for its spell checking and depending on
operating system, some basic steps will need to be performed to install
the required files.

Hunspell is a widely used spell checking engine found in some pretty big
applications such as Google Chrome, Open Office, Photoshop, Firefox, and more.
Because of its wide usage, there are many pre existing dictionaries for many
different languages and dialects that Mystic can use!

If you speak English for example, its not difficult to find English
dictionaries with variations for US, Canada, UK, and Austrialian dialects and
any of them can be used by Mystic BBS.

Mystic also has the ability to load multiple dictionaries, so if you speak
Spanish, but would like to also include English words, Mystic can load a
primary Spanish dictionary and language rules but then append the English
words from a secondary English dictionary!

Mystic also provides the ability to define your own custom words that will be
included in any dictionary regardless of language.  This is handy to add in
any BBS specific terms or arcronyms which may not be found in any actual
dictionary that you don't want reported as a spelling error.

Step #1: Hunspell Installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Windows:

	Copy appropriate .DLL into root Mystic directory or system lib path.  Note
	that the 32-bit version of Mystic requires the 32-bit version of Hunspell,
	and the 64-bit version of Mystic requires the 64-bit version of Hunspell.

	For the 32-bit version, Mystic will be looking for libhunspell32.dll and
	for the 64-bit version, Mystic will be looking for the libhunspell64.dll.

	Copy the apropriate .dll into the root Mystic directory or somewhere else
	in your Windows system that is configured in a way that will allow Mystic to
	find it on startup.

Linux:

	In Linux, Mystic looks for the existance of "libhunspell.so" somewhere in a
	common library path.  For Ubuntu, this could already be installed by default
	and Mystic may work out of the box without any installation other than
	dictionary files.

	If this is not true with the distribution you are using then you may need to
	install it using a package manager.  For example:

		Raspbian Jessie/Ubuntu installation for Hunspell:

			sudo apt-get update
			sudo apt-get install libhunspell-dev

	If the package installed does not already create a symbolic link so that
	libhunspell.so exists, then you must create a symbolic link.  First, find
	where the file exists:

		sudo find /usr -name libhunspell*

	If you do not see a "libhunspell.so" file then you'll need to create a link
	in that name and point it to where the Hunspell library is.  So if the find
	above returns "/usr/lib/libhunspell-1.3.so.0" then you'd create a symbolic
	link of that file which points to libhunspell.so:

		sudo ln -s /usr/lib/libhunspell-1.3.so.0 /usr/lib/libhunspell.so

	After that you're all set with the Hunspell installation

Mac OSX:

	OS X uses libhunspell itself, so every version of OS X comes with hunspell
	already installed.  However, this is an older version of Hunspell (1.2.0)
	while the current versions are in the 1.4.X iterations.

	The 1.2.0 version to my knowledge does not support multiple dictionaries
	so one may wish to install a later version.  For those who wish to install
	the later versions, "Homebrew" can be used:

		First update Homebrew to the latest:

			brew update

		Next install hunspell:

			brew install hunspell

		To verify it installed type "hunspell --version" on a command prompt, you
		should see it print out a version which is currently 1.4.1.

	Regardless of if you've just installed Hunspell or you want to use the default
	OS X version, you'll need to locate where the Hunspell library is installed:

		sudo find /usr -name libhunspell*.dylib

	Mystic looks for "libhunspell.dylib" which allows the Sysop to create a
	symbolic link to whatever version of Hunspell is installed or they wish to
	use.  Lets say the search above gives us a location of:
	
		"/usr/local/lib/libhunspell-1.4.dylib"

	In order for Mystic to find it, we need to create a symbolic link from the
	actual file to the name that Mystic is looking for:

	sudo ln -s /usr/local/lib/libhunspell-1.4.dylib /usr/local/lib/libhunspell.dylib

	Once that is done, Hunspell is ready to be used.


Step #2: Enabling Mystic BBS spell checking
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Mystic's spell checker requires that dictionary files "dictionary.aff" and
"dictionary.dic" exist in the DATA directory.  These can be any valid ISPELL
or HUNSPELL dictionary file of your chosen language.

These files determine the "primary" language and the language rules that will
be applied to the spell checker.

At a minimum, those files need to exist for the spell checker to operate.  The
default spelling package comes with the "US English" variation of these, so if
want to use US English as your primary language, just copy the provided .dic
and .aff file into your DATA directory.

If you want to locate additional dictionaries, you can use any ISPELL or
HUNSPELL .dic and .aff file.  Some web resources available to help you
locate new dictionaries are:

	cgit.freedesktop.org/libreoffice/dictionaries/tree
	hunspell.github.io/
	google.com
	
Remember, you only need a .dic and a .aff for the language and dialect you
want to use, and only the .dic file for any secondary languages you may
wish to use.

Once you have the .dic and .aff file of the primary language you want, then
copy them into the DATA directory as "directory.aff" and "dictionary.dic" and
you'll be ready to go.

There are some additional optional things to know about as well.  You probably
want to copy the wordlist.txt included in the package into your DATA directory:

	WORDLIST.TXT
	~~~~~~~~~~~~

	This file can exist in the DATA directory and it can contain words that will
	be added into the dictionary regardless of what dictionaries are being used.

	This file is helpful to prevent common BBS related acrynyms and the sort of
	words that would not normally be found in an official dictionarty, and the
	package includes a WORDLIST.TXT already for you with some common terms.  This
	will continued to be built upon as new words are noticed.

	Blank lines are skipped and any line that begins with a semi-colon (;) will
	also be ignored, so that comments can be made in the file if desired.

	DICTLIST.TXT
	~~~~~~~~~~~~

	This optional file contains a list of secondary .dic files that will be loaded
	after the primary language.  This allows works from a different language to be
	included into the primary dictionaty and language rules.  For example, you may
	have a primary French dictionary, with an English secondary word list.

	In this file, blank lines are ignored as well as any line which begins with a
	semi-colon (;).  If just a filename (ie french.dic) is referenced, Mystic will
	look in the DATA directory for the file, but a full directory name can be
	included here as well.  The "@ROOT@" code will be replaced with the root
	Mystic BBS if it is found, ie: "c:\mystic\", etc.  For example:

		french.dic
		@ROOT@data\french.dic
		c:\mystic\data\french.dic

	In the above examples, all three of those lines will point to the same
	location in the DATA directory.

	NOTE: Some versions of Hunspell do not allow multiple dictionaries to be used
	and when Mystic encounters this situation, only the primary dictionary will
	be loaded.

	
Step #3: Enable spell checking in Mystic template
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	By default, Mystic already ships with this step already configured, but if
	have an older customized template, you'll just want to make sure that you
	verify that the spell check settings look okay.

	See the default msg_editor.ini for information and default examples of how
	this is configured, but for a quick reference there are the following
	options which can be changed:

		[Options] auto_suggest
		[Options] suggest_delay
		[Coords] Coord6
		[Prompts] str16
		[Prompts] str17

	Suggestion Delay
	~~~~~~~~~~~~~~~~

	In particular, the suggest_delay may be a good thing to experiment with.  By
	default this is set to true, which causes Mystic to wait until the user does
	not type for around a half of a second before it will try to auto suggest
	words.  However, if you are on a faster system, you may prefer to remote the
	delay which causes Mystic to perform instant suggestions.


TROUBLESHOOTING
~~~~~~~~~~~~~~~

If the spell checker does not show as enabled while editing a message, then
read the node's log file for any Hunspell related error messages, and also
validate that the dictionary.aff and dictionary.dic files exist in the data
folder.

Make sure you are using the proper "bit" version of Hunspell.  If you are
using a 32-bit Mystic, you need a 32-bit Hunspell and the same goes for
64-bit you need a 64-bit hunspell.
