                ASPELL.VDM
                ==========

V 1.6  2010-08-29   (c) Pauli Lindgren


Introduction
------------

Aspell is a freeware / open source spelling checker. See:
  http://aspell.net/

Aspell.vdm contains several macros for integrating Aspell with Vedit.
The main functions are:

- You can check spelling in file currently being edited, or in a selected block.

- After spelling check is run, words that contain spelling error are highlighted.

- Move cursor to a highlighted word and press a hotkey to open a window with
  suggested words to correct spelling.
  

Files in this package:
---------------------

aspell.vdm      - Contains all the macros needed for spelling check
aspell.ini      - Settings file. Edit this to specify available languages
aspell_vdm.txt  - This document file
aspell.mnu      - Tools menu for spelling check functions, loaded by the macro.

When the macro is run, it generates file spellchk.syn (and aspell.ini if missing) in user-mac directory,
and several temporary files in directory specified by variable VEDIT_TEMP.


Installing aspell.vdm
---------------------

1. Install Aspell spelling checker and at least one dictionary

2. Unzip the files in this package to Vedit user-mac directory.

3. You may add call to aspell.vdm into your User or Tools menu if you like.
   You can for example copy the first item (3 lines) from ASPELL.MNU.
   You do not need to copy the other menu items, since aspell.vdm loads ASPELL.MNU
   automatically when you run spelling check.

4. If you have installed dictionaries other than English, edit aspell.ini file to
   list them in dialog box (see below).


Adding languages
----------------

If you install dictionaries for other languages than English, you need to edit
aspell.ini file (in user-mac directory) to make them visible in the dialog box.
You can open the file for edit by clicking [Edit aspell.ini] button in Options dialog.

For each language to be available in "Dictionary" radio buttons, there is one
line in format
  lang=code,text
where
- "code" is the 2 character language code (e.g. "en" for English), optionally
  followed by character '_' and 2 character dialect code in upper case,
  forming code to the specific dialect (e.g. "en_GB" for British English.
  Note: There is a .multi file in aspell\dict folder for each language available.
- "text" is the text to be displayed in the dialog box.

Example:
  lang=en_GB,English GB

The keyword lang must begin at the first column of the line.
There must not be any spaces around '=' or ',' characters.

Max 9 languages can be listed. (On Vedit 6.15.2, it is recommended to have no more
than 6, otherwise the file type radio button selection may not work correctly.)
Languages can be listed in any order. They appear in that order in the dialog box.
Note: if there are multiple dialects of same language, and "Auto detect language"
is used, the first dialect of that language in the list is selected by default.


USING ASPELL.VDM
----------------

Checking the spelling
---------------------

To check spelling in a file, call the macro aspell.vdm.
If you have marked a block, the spelling will be checked within this block only.
Otherwise, the spelling is checked either from beginning of file or starting from
cursor location (see below).

A dialog box opens for selecting spelling options.
The dialog box contains the following items:

 [ ] Start at beginning of file
  - If selected, the checking starts at beginning of the current file.
  - If not selected, checking starts from cursor location.
  - This option is initially checked, but if you run spelling check again without
    exiting spelling check mode, it is unchecked.
  - Note: the max number of lines checked is limited by configuration option,
    see "Options" below.

 Dictionary radio buttons:
  - Select which language dictionary you want to use for checking spelling.
  - Initially, English language variations that come with English dictionary are included.
    If you add more dictionaries, edit aspell.ini to make them visible in the dialog
    (see "Adding languages" above).
  - Initial setting can be automatically detected, see "Auto detect language" below.
 
 File type radio buttons:
  - Selects filter to limit what parts of file are to be checked.
    - Plain text: check everything.
    - Text with URL: If the text contains web addresses, those are not checked for spelling.
    - HTML: Do not check inside HTML tags.
    - TeX: Do not check TeX commands.
    - Source code: Check spelling in comments and strings in program source code file.
      Thus the program keywords, variable names etc. are not flagged as spelling errors.
      The comment delimiters are automatically fetched from currently active syntax file.
      For strings, only single line strings delimited by double quote (") are checked.
  - Initial setting is automatically set based on the filename extension.

 [ ] Allow Run-together words
  - When enabled, any composite words that are created by combining two or more
    correct words are accepted.
    When disabled, only those composite words are accepted that are included in
    the dictionary.

 [ ] ignore Case
  - When enabled, upper/lower case of characters is ignored.

 [ ] ignore Accents
  - When enabled, accents and umlauts are ignored.
    For example, clich and cliche are both accepted (with English dictionary).

 [ OK ]     - Start spelling check
 [Cancel]   - Cancel operation
 [Options]  - Go to Options dialog (see below)


Options dialog:
---------------

Contains the following items:

 Max number of lines to check
  - Limit the number of lines for safety and speed.

 Max number of errors to look for:
  - Maximum number of different misspelled words accepted. When the maximum
    is reached, spelling check ends. This is for safety and speed, but also
    because adding too many words to syntax highlight keyword list may cause
    problems.

 Color for errors with suggestions
  - Syntax color for Reserved4
 
 Color for errors without suggestions
  - Syntax color for Reserved3

 [ ] Auto detect language
  - If this option is selected, the macro tries to automatically detect
    the language used in current document, and selects the corresponding radio
    button as default. (You can still change the selection manually.)
  - Currently recognizes French, German, Spanish and Swedish.
  - If there are multiple dialects of the same language (e.g. de_DE, de_CH),
    the one listed first in aspell.ini will be selected.
  - If the detected language is not listed in aspell.ini, the previously used
    language will be selected.
  - If this option is not selected, previously used language will always be
    selected as initial setting.

 [ ] Find next error automatically
  - If this option is selected, cursor is automatically moved to first error
    after running spelling check. After you have selected one of the suggested
    replacement words or selected ignore or add to dictionary, cursor is moved
    to next error.
 
 [ Edit aspell.ini ] button
  - Opens aspell.ini file for editing and exits the macro.
    You can change the list of installed dictionaries here.

You may increase the max values somewhat if it seems to not cause problems.
For color codes, see for example Syntax Color in the Config menu of Vedit.


After spelling check has been run:
---------------------------------

After you click OK in the main menu, spelling check begins.
This usually takes a few seconds, depending on how big file is being checked
and what are the maximum values set (see Options above).

After the spelling check is done, any words with spelling errors are highlighted
with yellow background (by default, you can change that from Options dialog).
Your normal Tools menu is changed to ASPELL.MNU and the menu title is changed
to "spTools". Shortcut keys are configured for selecting items in the menu.

The menu contains the following items (shortcut keys in parentheses):

  Check spelling                         (Shift-F5)
  Suggest correction for word at cursor  (Shift-F6)
  Ignore word                            (Ctrl-Shift-i)
  Next error                             (Shift-F7 or Alt-N)
  Previous error                         (Alt-P)
  Exit spelling check mode               (Shift-F8)

(Note: Alt-N and Alt-P are defined in Vedit standard keyboard layout.)

You can now correct any errors manually, ask for suggestions, or remove the
highlighting by selecting "ignore word", see below.


Spelling correction:
--------------------

To ask for suggested correction for a spelling error, move cursor on a highlighted
word and press Shift-F6 (or select "Suggest correction for word at cursor" from
spTools menu).

A window opens with list of suggested corrections, most probable word first.
Use cursor up/down, PageUp, PageDown, Home, and End keys to navigate in this
list, then press Enter to replace the error word with the selected word.
To cancel, press Esc, Space or Shift-F6.

On top of the list, there are commands that you can execute instead of replacing
the word:

-> Ignore word
 - Just removes the word from syntax highlighting, but it has no effect on
   subsequent runs of spell check.

-> Add word to dict
 - Adds the current word into language specific user dictionary, so that on subsequent
   runs of spell check this word is no more marked as spelling error.
 - For confirmation, a dialog opens to display the word being added. In addition,
   there is option to save the word in lower case, which causes Aspell to ignore case
   in spelling check.
 - If you confirm the save to dictionary, the word is removed from syntax highlighting, too.

Keys available while in Spelling Correction window:
  Up/Down       - Move up/down in the list
  PgUp/PgDown   - Move up/down one page. Does not move above 1st suggested word.
  Home/End      - Move to beginning/end of word list
  Enter         - Replace word with the word selected from list, or execute command.
  Esc           - Cancel and close window
  Space         - Cancel and close window
  Shift-F6      - Cancel and close window
  I             - Execute "-> Ignore word" command
  A             - Execute "-> Add word to dict" command

Ignore word option can be executed directly without opening word list, by selecting it
from spTools menu or by pressing the hotkey Ctrl-Shift-i.


Check word/block:
----------------

With this option in spTools menu you can check spelling of a single word or highlighted
block instantly, without going through the main dialog box. If a block is highlighted,
the whole block is checked. If no block is highlighted, the single word on which the
cursor is located is checked.
This menu option calls the label INSTANT in aspell.vdm.
This option can only be used while spelling mode is active.
It uses the same settings (language etc.) that were used when you originally ran aspell.vdm.


Exit spelling check mode:
------------------------ 

After you have finished doing corrections, you should select "Exit spelling check mode"
from the spTools menu (or press Shift-F8).

This restores your original syntax colors, original Tools menu, word delimiter setting,
and keyboard configuration.

In addition, it updates the User Dictionary if any words were added.


Bugs:
----

If you have more than 5 languages (dictionaries) listed in the dialog box,
the "File type" radio buttons may not be updated correctly on screen.
This is due to the VEDIT bug that splits radio button groups after 10th radio button.
As a result, you may see two radio buttons selected in the "File type" group.
In this case, the last radio button is the one that takes effect.

If an error words is a substring of a longer word (e.g. hotkey and hotkeys), and the
shorter one was found first, the longer one may not be found by NextError/PreviousError.

Aspell interprets numbers as word separators. Syntax highlighting can not highlight such
words, and the word is not found by Next Error.

If you have multiple files open with different syntax highlighting files in use,
Vedit (V 6.15.3) may mess up the syntax colors of current window after running a macro.
You can restore the correct colors by switching to another window and back, or
by pressing PageUp/PageDown (if the file is long enough for paging).


Revision history:
-----------------

V1.6  2010-08-15
    - Source code filter option added.
    - INSTANT entry point for instant spelling check without showing the dialog box.
    - Restore keyboard configuration on exit.
    - Restore cursor position on exit if no errors found.

V1.5  2009-01-07
    - No DOS parameter in Sys() command (for 64bit Windows)

V1.4  2008-06-05
    - Suggest and Next-Error now work even if the error is at the very beginning or end of file
    - Removed "no more errors" message from Next-Error since it may overwrite other messages.
    - Spell checking text in binary file (e.g. Word .doc file) is now possible
      (does not set binary file type for tmp text file).
    - Language auto detect parameters adjusted and added detection for Spanish.
    - Language auto detect starts check at block begin if block highlighted.


V1.3  2008-05-09
    - Path to Aspell home directory fetched from registry
    - List of available languages can be defined in aspell.ini file
    - Added [Edit aspell.ini] button in Options dialog
    - Commands to find next/previous error
    - Option to automatically find next error after correction
    - Option to automatically detect language
    - Ignore Case option added
    - Ignore Accents option added
    - Added error checks in case aspell.exe could not be run or dictionary not found
    - Save settings when OK clicked in Options dialog
    - Fix: command line parameter for TeX mode was wrong
    - Fix: in Suggest, top line for PgUp and Home 4 -> 3
    - Default colors changed
    - Changed hotkeys: Shift-F7 = Next error, Shift-F8 = Exit

V1.2  2008-04-24
    - Save syntax file and tools menu settings, load ASPELL.MNU
    - "Ignore word" option in suggest window and in ASPELL.MNU
    - "Add word" option in suggest window
    - Save word-separator and define new setting to match aspell word separator
    - Max lines and max errors moved to Options dialog
    - "Allow run-together words" option
    - Swedish dictionary option
    - Save options into aspell.ini file
    - Show errors for which there are no suggestion, in different color
    - Color settings in Options menu

V1.1  2008-04-15
    - If block highlighted, check spelling in the block only.
    - Select dictionary language and file type from dialog.
    - Use terse mode to speed up operation.
    - "Suggest" operation searches for full words only.
    - Fixed setting of max errors and max lines values
    - Quote Aspell command characters used in pipe mode

V1.0 2008-04-14
    - First release: Call Aspell, highlight errors, suggest correction.


