| Name: | Spellcheck |
| Version: | 1.2 |
| Last update: | 2020-01-06 09:54:23 |
This help file describes the Spellcheck package.
Introduction
The Spellcheck core package provides the Edit ↣ Spelling menu which has items to perform spell checking
on the current window or on a selection of text within the current window.
This package is always active.
Alpha has built-in spell checking facilities based on the OS X spell
checker, but it can also interact with external tools to perform this task.
Spell checking with an external application can be performed using
the aspell command line tool. Still, the spell checking takes place
interactively inside the document window in Alpha.
Note that, since version 9.0rc5 of Alpha, the Excalibur
implementation of the Spellcheck service has been removed because
the Excalibur application appears to be broken on recent versions
of Mac OS X (Sierra and greater).
Selecting a spell checker
By default, Alpha's internal spell checker is enabled. Unless you want to
use another spell checker, there is nothing special to do.
Otherwise, if you want to change your spellcheck client, select the menu
item Edit ↣ Spelling ↣ Select Spelling Service… or click here to display the
Helper Applications dialog.
Currently two services are available:
Obviously if you choose Aspell, the corresponding application must
be installed on your machine. This is explained in the next sections.
The Spelling Panel
The Alpha and Aspell implementations provide their service through
a spelling panel. This is a simple user interface that lets you interact
with the spell checker. The panel is a floating window which remains over
the document windows. You may leave around or close it at any moment.
Calling a spell checking command will display it again.
When the spell checker finds a misspelled word, it hilites it in the
text, then reports the information in the Spelling Panel.
The top left field of the panel is the Word Field: it displays the
misspelled word currently found by the spell checker.
Under the word field is a table view which displays guesses or suggestions
of correction. When the user clicks on a suggestion in the table view,
this suggestion is inserted in the word field.
Four buttons let you decide what to do with the suggestion:
- Correct
- Pressing this button causes the suggestion displayed in the word field to
replace the current selection in the document. Then the spell
checker starts looking for another misspelled word. Note that a correction
can be typed directly in the word field.
- Find Next
- Pressing this button does not insert any correction and starts looking for
the next misspelled word.
- Ignore
- This button lets you declare that the current word is to be considered as
correct in the rest of the document. If the spell checker finds it again in
the same document, it will not report it as a misspelled word. After a
click on this button, the spell checker looks for the next misspelled word.
- Learn
- This button lets you add the current word to the user's dictionary. The
word will be ignored permanently (and not only for the current document).
After a click on this button, the spell checker looks for the next
misspelled word.
Finally there is, in the lower left corner, a Languages popup menu
which lets you specify the language of the document. The contents of this
menu depend on which dictionaries are currently installed on your machine
and which spelling service (Alpha or Aspell) you are using.
Tip: you can double-click a word in the Guesses table to have it
directly selected and inserted in the text. This is a shortcut for
selecting a suggestion and then clicking on the Correct button.
Spell checking with 'Alpha'
If you choose the Alpha built-in spell checker, there is nothing to
install as it is provided by the system and handled directly by Alpha.
Note that this spell checker is clever and is able to handle files
containing special markups like TeX, LaTeX, Html, Xml files. Everything is
handled by Alpha which automatically detects if the document is in one of
the corresponding modes.
The Edit ↣ Spelling menu will contain
a submenu called Dictionaries where you can select the language of
your document. You can select the language either in this Dictionaries submenu or in the Languages popup menu of the Spelling Panel.
Selecting Edit ↣ Spelling ↣ Spellcheck Window or
Edit ↣ Spelling ↣ Spellcheck Selection will
open a Spelling Panel and start an interactive spelling session. At any
time you can stop it if necessary by closing the panel.
Note that the Alpha spell checker provides automatic language
detection. The Languages popup menu has a first item called Automatic. If it is selected, the spell checker detects automatically
the language to use when a word is found. This is useful if you spell check
a multilingual document.
Spell checking with 'aspell'
Alpha can interact with the command-line spell checker aspell.
It establishes a connection with this tool and communicates with it in
order to perform an interactive spell checking session.
Note that aspell is clever and is able to handle files containing
special markups like TeX, LaTeX, Html, Xml files. Everything is handled
automatically by Alpha.
Obtaining Aspell
Aspell can be obtained from
http://aspell.sourceforge.net/. The easiest way to
install aspell on your machine is to use a package manager such as
MacPorts, or
Fink, or
Homebrew.
For instance, if MacPorts is installed on your machine, you just have to
type the following instruction in a Terminal window:
sudo port install aspell
then enter your admin password.
You will also need to install dictionaries. With MacPorts, just type the
following in order to install the english language dictionaries:
sudo port install aspell-dict-en
Similarly you can obtain the french or german dictionaries (and many
others) with commands like:
sudo port install aspell-dict-fr
sudo port install aspell-dict-de
How it works
Selecting the Edit ↣ Spelling commands
will instruct Alpha to start running the spell checker and communicate with
it behind the scenes. The suggestion and replacement of corrected words
will take place through the Spelling Panel described above.
The Edit ↣ Spelling menu will contain
a submenu called Dictionaries where you can select the language of
your document. The contents of this submenu depends on the Aspell
dictionaries you installed on your machine. You can select the language
either in the Dictionaries submenu or in the Languages
popup menu of the Spelling Panel.
If a misspelled word is found in your document window, it is
hilighted and a list of suggested corrections is displayed in the spelling
panel.
The Spelling menu
The Edit ↣ Spelling menu contains the
following items:
- Spellcheck Window
- Perform spellchecking of the entire current document.
- Spellcheck Selection
- Perform spellchecking only in the current selection.
- Spellcheck Region…
- Perform spellchecking in a specified region. This allows you in particular
to start from the current position.
- Spellcheck Current Word
- Display suggestions for the word around the insertion cursor.
- Dictionaries
- This submenu contains the currently available language dictionaries. Its
content depends on the currently selected spelling service.
- Hide/Show Spelling Panel
- Lets you display or close the spelling panel.
- Select Spelling Service…
- Lets you select the spelling service. See the
Selecting a spell checker section.
- Spelling Help
- Display the Spell Check Help file.
Spell checking LaTeX documents
All spelling services provided by Alpha are able to intelligently manage
LaTeX documents. Typically, such a document is full of LaTeX macros (like
\usepackage, etc.) which are usually flagged as misspelled words by
ordinary spellcheckers. When spellchecking a document in TeX mode, Alpha
will ignore most of the LaTeX constructs and markup, and will not report
them as misspelled words.
There is nothing particular to do to enable this feature: Alpha
automatically detects that it is dealing with a LaTeX document.
However, the different spelling services are more or less
efficient. In particular,
aspell does not
handle correctly the Tex/LaTeX accent macros (like \'e for
é, etc.).
On the contrary, Alpha's internal spell checker (see Spell checking with 'Alpha') can handle these macros nicely if
the Latex Accents package is activated. In that case,
if you type the french word définition, it will be inserted as d\'efinition (or d\'{e}finition, depending on the Latex
Accents preferences). When the word d\'efinition is parsed by
the aspell spell checker, it is confused by the \'e and
stops on the partial word efinition (without the initial d)
and reports it as a misspelled word. Alpha's internal spell checker on the
contrary will not be misled by the \'e and will happily accept the
word.
Alpha's internal spell checker is also smart enough to insert accented
corrections with Tex/LaTeX accents if the Latex Accents
package is activated. For instance, if you mistyped the word théorème, then select the correct spelling in the suggestions and click on the
Correct button in the Spelling panel, the correction will be
inserted as expected as th\'{e}or\`{e}me (or th\'eor\`eme).
Spell checking in other modes
The Aspell spelling service can manage, not only LaTeX documents
(as explained in the previous section), but also HTML, XML,
C, and C++ files.
Alpha's internal spell checker (see Spell checking with 'Alpha') also provides special treatment for various modes, including
HTML, Tcl, Aida.
This is very useful in markup languages in order not to hinder the spell
checker with tags and syntactic attributes.
In HTML mode, Alpha's internal spell checker skips
all the tag attribute declarations (except the ALT attribute whose
value is in general a piece of text). By default, it also checks spelling
inside the HTML comments but you can modify this behavior with the Spell Check Comments preference (in HTML Menu ↣ Preferences ↣ General…).
The spell checking contextual items
The spell checking commands can be accessed from the contextual menu that
is displayed when the user control-clicks (that is to say clicks while
pressing the Control key) in a document window.
The following items are available:
- Spellcheck Word
- There is a Spellcheck Word item which lets you check the
spelling of the word found beneath the mouse cursor when you perform a
control-click. If corrections are available, they are displayed in a
popover window as shown in the next image:
In this example, the user control-clicked on the word "window" and
selected Spellcheck Word in the contextual menu. If you
double-click on a word inside the popover, it replaces the word found
beneath the cursor. Clicking anywhere outside the popover dismisses it.
The suggested corrections are based on the currently selected
language dictionary and obtained through the current spelling service.
Note that if the Embrace package is activated, the
Spellcheck Word feature can also be obtained with the ⌃B Z keyboard shortcut.
- Spelling module
- There is a Spelling module that inserts a submenu in the contextual
menu. This module must be explicitely activated to be displayed: choose Customize in the contextual menu and then select the Spelling Menu checkbox. It contains commands to spellcheck a window, a selection or a
region.
Notes for Developers
New spell checking services may be added in the future. Any spell checker
may take advantage of the Spelling Panel's facilities. Have a look
at the comments contained in the file spellcheck.tcl
to learn how a package may register as a client of the Spelling Panel and
which procs have to be implemented in order to communicate with the panel.
Known problems
Please report any problem or bug you encounter to
Alpha's Bug Tracker.
License and Disclaimer
Original Author: Vince Darley.
Co-Authors: Craig Barton Upright, Joachim Kock, Bernard Desgraupes.
The aspell intercommunication was implemented by Joachim Kock.
Alpha's internal spell checker was implemented by Bernard Desgraupes.
Copyright (c) 2002-2020, Vince Darley and Contributors.
Contributors: Craig Barton Upright, Joachim Kock, Bernard Desgraupes.
All rights reserved.
The spellcheck package is free software and distributed under
the terms of the new BSD license:
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
- Neither the name of Vince Darley nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL VINCE DARLEY OR THE CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
This document has been placed in the public domain.