Vim-Spell documentation
# VIM: let g:VS_language = 'american'
*VS_help.txt* For Vim version 5.7.+ Last change: 03rd jul 2002
VIM Spell Plugin MANUAL by Luc Hermitte
VIM-Spell version 0.3
------------------------------------------------------------------------------
Presentation:
VIM-Spell is a spell checker plugin for VIM. Actually it wraps external tools
that use the |IA-spell| pipe protocol.
Contents
|Features| The features of the VIM-Spell Plugin.
|Install| Installation notes.
|Options| Options to customize it.
|Future| Known problems & TODO list.
|References| References to related programs and plugins.
------------------------------------------------------------------------------
*Features*
Plugin features:
As its name suggests, the main feature of this plugin is to add spell-checking
functionalities to VIM.
VIM-Spell defines two operating modes ; each one being associated to a buffer.
The first mode is associated to the buffer of the text spell-checked. The
second one is a view that suggests alternatives to a misspelling. See for
instance :
http://hermitte.free.fr/vim/ressources/VS-capture.gif
*main-buffer-mode*
Main-buffer Mode:
From this mode we can :
* |Parse| the buffer for misspellings,
* |Highlight| the misspellings,
* |Jump| from one misspelling to the next/previous,
* |Exit|,
* |Swap| the value of the current language,
* Ask for |Alternatives|.
*corrector-mode*
Corrector Mode:
In this mode, a set of alternatives are suggested to replace the word
which is under the cursor in the parsed buffer. From this list, we can :
* |Choose| an alternative,
* |Correct| the misspelled word and replace it by the chosen alternative,
* |Replace-all| Replace every occurrence of the misspelled word by the
chosen alternative,
* |Replace-buf| Replace every occurrence of the misspelled word in every
opened buffer by the chosen alternative,
* |Ignore| the fact that the word is misspelled,
* |Add| the word to the personal dictionary,
* |Undo/redo| the last action,
* |Jump| from one misspelling to the next/previous,
* |Hide_Help| message for the Corrector mode, or display it.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Details about the features:
*Parse* Parse the buffer for misspellings -- key binded (KB) : <M-s>r
Main mode.
This action issues two calls to |IA-spell|. It first updates the list of
misspelled words within the edited document, and then |cache|s their
possible alternatives. It also |Highlight|s the misspellings.
This must be done at least once before using the other features of this
plugin.
*Highlight* Highlight the misspellings -- <M-s>s ; not yet automatic
Main mode.
Switches in the Error-Syntax style all the misspelled words.
*Jump* Jump from one misspelling to the next/previous -- <M-n>, <M-p>
Both modes.
Puts the cursor under the next/previous misspelling.
In corrector-mode, it also updates the alternatives proposed to match the
new current misspelling.
*Exit* Exit -- <M-s>E
Both modes.
Closes the corrector window (if opened) and un-highlights the misspellings.
*Swap* Swap the value of the current language -- <M-s>L
Main mode.
Changes the value of the option |g:VS_language| in order to be turn after
turn : "American" or what is your default value for |g:VS_language|. BTW,
this feature requires you have installed my |triggering| plugin, otherwise
it won't be enabled.
*Alternatives* Ask for alternatives -- <M-s>a
Main mode.
Opens (if not) the corrector window and suggests alternatives to the current
word (i.e. under the cursor) if misspelled.
This switches to the corrector mode.
- - - - - - - - - -
*Choose* Choose an alternative -- cursors, <tab>, <s-tab>
Corrector mode
An alternative is considered chosen if the cursor (in the corrector window)
is on the line of the alternative.
<tab> and <s-tab> have also been mapped to jump from one alternative to the
next/previous.
*Correct* Correct the misspelled word -- <cr>, <2-click>, number
Corrector mode :: correction
The current misspelled word is replaced by the chosen alternative.
The alternative can also be chosen by directly typing its number.
If the current word within the main buffer differs from the misspelling
considered within the corrector-buffer, nothing is done.
*Replace-all* Replace every occurrence of the misspelled word -- A
Corrector mode :: correction
Every occurrence, in the main buffer, of the misspelling is replaced by the
chosen alternative.
*Replace-buf* Replace every occurrence of the misspelling in every buffer -- B
Corrector mode :: correction
Every occurrence, in every opened buffer, of the misspelling is replaced by
the chosen alternative.
*Ignore* Ignore the fact that the word is misspelled -- i
Corrector mode :: dictionary management
The word is added to the file ./.spell/ignore-list. If you want to change
some of the words, edit the file and remove the words you don't want to be
ignored anymore.
*Add* Add the word to the personal dictionary -- * or &
Corrector mode :: dictionary management
The word is added to the personal dictionary dependent of the current
language. Typing '&' adds the word in lower case.
This issues a call to |IA-spell|.
When using |Aspell|, if the word to add is accentuated (or contains non
alphanumeric characters), this function will propose to directly insert the
word into the dictionary as if |g:VS_aspell_add_directly_to_dict| was set to
true. Hence, all the corresponding warnings apply.
This way of proceeding comes from the fact I wasn't able to add accentuated
words to the personal dictionary through the pipe protocol with Aspell .33.5
alpha compiled with MinGW and used under Windows NT. Any hint/comment on
this point is welcome.
Deleting a word from the dictionary is out of topic here but quite easy
indeed with Aspell. I have identified for instance with the version .33.5
alpha the files fr.pws (for French) and english.pws. Deleting the line of
the word no longer desired and reducing the last number on the first line
should do the trick.
*Undo/redo* Undo/redo the last action -- u / <C-R>
Corrector mode :: correction
Undo/redo the last action that has occurred in the main buffer. This is
helpful to undo a change without (because we haven't click on the right line
for instance) leaving the corrector window.
*Hide_Help* Hide/Display help -- h / <C-R>
Corrector mode ::
Display or hide a several lines help message that sums up the different
key-bindings used within the Corrector Mode.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Internal considerations
*cache*
As the calls to Aspell are quite slow -- due to the need to load the
dictionary each time it is run --, I decided to cache all the calls to Aspell.
Though, a file named ./.spell/errors-list is maintained for every folder
containing files checked with this plugin. Every time a file is parsed, all
the new misspellings detected are added (at the end of the file) with the list
of their suggested alternatives.
Hence, all in all |IA-spell| is called only twice : a first time to detect new
misspellings, and a second one to retrieve the suggested alternatives of all
the new misspellings. Once the file is parsed, the improvement is noticeable :
looking for the alternatives of a misspelling is an instantaneous operation.
All the current misspellings are remembered. It may not be useful in the long
run except for recurrent misspellings. But, the replacing feature will make
this behavior useless and hence we will be able to delete the cache-file
between two sessions. cf. |todo-replace|
Regarding the highlighting policy, every word is considered OK except those
detected misspelled by the |IA-spell| tool. This is the opposite approach of
the one taken in |engspchk|. If the cached file is localized (to folder) and
often erased, this will enable to manage smaller lists of words.
------------------------------------------------------------------------------
*Install*
Installation notes:
Files of the plugin:
The plugin is composed of 2 files plus this file and its HTML version :
- lhVimSpell.vim : the main file, theone that must be sourced
- VS_gui-map.vim : mappings defined in the corrector buffer.
They could be downloaded as a tarball archive at :
http://hermitte.free.fr/vim/ressources/vim-spell.tar.gz
Once you have extracted the archive, with for instance : gzip -cd
VS.tar.gz | tar xf -, you will have to move the files to differents
directories. Several approaches are possible regarding the version of VIM
used.
Note by the way that you will also require the |alternate| plugin. You
will find an old version joined in this archive.
VIM 5.xx
Regarding the files from the archive :
- drop the three .vim files into your $VIM/macros/ directory
- keep the documentation around
- and source lhVimSpell.vim whenever you need the plugin (manually,
automatically from the .vimrc, or automaticaly thanks to ftplugin-like
facilities).
The mappings for the corrector-buffer imply they are unloaded out of the
buffer. Indeed, I remap things like <cr>, a, i, <tab>, 0, 1, ..., 9, and
so on. I wouldn't have done so if there didn't exist a way to implement
buffer-relative mappings with these old versions of VIM. So, to make it
straight, download |buffoption| and copy it into your $VIMRUNTIME/macros
folder. I also suggest you take a look on a my page about "File-type
plugin emulation on VIM 5.xx" for more explanations.
http://hermitte.free.fr/vim/ftplugin.php3
VIM 6.0
Let's note $$ to represent $HOME/.vim/ (on *NIX systems) or
$HOME/vimfiles/ (on Ms-Windows systems) ; check ":help 'runtimepath'"' for
other systems. Then,
- drop the documentation files into $$/doc/ and execute (from VIM)
':helptags $$/doc' once.
- If you want the plugin to be systematically run: drop the three vim
files into your $$/plugin/ directory
Or, if you want the plugin to be run only in specific situations:
drop them into your $$/macros/ directory, and source it whenever you
need it. For instance, I execute ":runtime macros/lhVimSpell.vim"
from my TeX ftplugin.
As I have just said, the "maps local to a buffer" mechanism is required by
VIM-Spell to work correctly. It is directly supported under VIM 6.0,
without any other plugin required. However, as |buffoption| is not used,
menus can no longer be local to buffers.
Customizing the mappings:
I decided to bind all the features to sequences beginning by <M-s> because:
- 's' is like spell ;
- <C-S> is already mapped (in my configuration) to :w<cr> for when I
come back from Ms-Windows products that I used over a long period ;
- 'ó' is not a letter I use in French, Ms-Windows Spanish users may
want to change it ; note: you will (quite) never see my mappings
starting with <M-i> : 'é' probably the accentuated letter the most
used in French.
BTW, notice that <M-s> and <M-S> are two different key strokes.
So, if you want to change the default mappings, just edit the third part
of lhVimSpell.vim (lhVimSpell/corrected buffer functions) and
VS_gui-map.vim and make your customizations.
If required, I'll try to improve the customization of mappings.
Last thing:
I'm aware that this plugin is quite complex. It is the price for all its
features. It depends on external plugins and even external (but common for
VIM users I guess) tools. For compatibility reasons, I've chosen to use as
few new VIM 6.0 features as possible. For maintenance aspects, it is
developped as several inter-dependant files ; if you want to hack the
plugin, you'd better look at the "developpers" version :
http://hermitte.free.fr/vim/ressources/vim-spell-dev.tar.gz
Regarding my choices of folders between $VIM and $VIMRUNTIME, they are
guided from the fact I've installed VIM 5.7 and VIM 6.0 on my Windows NT
system. All the common and compatible (ft)plugins are in $VIM/(ft)plugin
while specific stuff is in the respective $VIMRUNTIME folders. If your
installation is simple, I suggest you use $VIMRUNTIME (VIM 5.x), and $$
(VIM 6.x) everywhere. Sometimes, I will write a note about this
cohabitation topic.
------------------------------------------------------------------------------
*Options*
Options:
The options are global. Making them buffer relative caused me a lot of
troubles when I wanted to |Parse| several buffers.
If you want to change their values, do it into your .vimrc or any other plugin
loaded before, or even after, VIM-Spell.
*g:VS_language* string (...) ; default based on $LANG
This option defines the language/dictionary used. cf. the --master option of
|IA-spell|. If your configuration is not explicitly supported, you may have
to extend the functions VS_default_language() and VS_personal_dict() ; let
me know about it.
*g:VS_spell_prog* string ('ispell'/'aspell') ; default : 'aspell'
This option must be used to set which |IA-spell| tool is used : Ispell or
Aspell -- or any upcoming clone.
*g:VS_strip_accents* boolean (0/1) ; default : 0
Directly passed to |IA-spell| if defined.
*g:VS_aspell_add_directly_to_dict* boolean (0/1) ; default 0
This trick enables to quicken the insertion of words into the personal
dictionary. I guess it will work only with |Aspell|. I've tested this
approach with Aspell .33.5 alpha ; I can't guarantee that it will always
work with future versions of Aspell. By default, this option is set to false
(ie. 0).
If you want to use it, please check :
- You are using Aspell or at least the format of your personal dictionary
looks like : "xxxx <number_of_entries>" on the first line, while the
following lines are made of «personal» words.
- The personal dictionary names are correctly set within VS_personal_dict()
regarding your |g:VS_language|.
- $ASPELL points to the folder where your personal dictionaries are stored.
I think that the name of this env. variable is very badly chosen.
Any feedback is welcome regarding this option (and the rest as well) :
format of personal dictionaries and its everlastingness, their names
regarding the language used, etc.
*g:VS_display_long_help* boolean (0/1) ; default 0
Tells, next time the corrector window is opened, if the help will be
displayed in its totality or not.
*g:VS_jump_next_error_after* boolean (0/1) ; default 1
When true, some operations (|Correct|, |Add| word to dictionary, |Ignore|
word) from the corrector window will provoke the cursor to move to the next
misspelling.
------------------------------------------------------------------------------
*Future*
Known problems & TODO List:
*Known* *problems*
Known problems:
Setting the file-type will cancel the highlighting of misspellings ; So,
try to avoid to reset it every time the buffer is reloaded -- this could
be observed with the affectation of &filetype within modelines like with
this file.
When we hit '*' in the Corrector mode, a space must be hit in order to
activate the associated mapping.
*TODO*
TODO list:
* Manage replacement list ; *todo-replace*
i.e. list of words to be systematically replaced by a predefined word.
Aspell seems to use *.prepl files for this purpose. But how to manage
them through pipes (-a option) ?
Two possible ways (option ?) to execute the replacements:
- can be executed on user's request
- can be executed automatically => map every characters -- possibility
to study ; cf. Word_in_ment() in fr-abbrs.vim
* Ignore some contextual word like "\oe uvre" -- with TeX
and other expressions like for instance the labels of figure the
parameters to \rnode{}{}{}, and so on.
* Cache the dictionary management requests ; delay and merge the calls to
|IA-spell| that add words to the dictionary as long as possible.
* Secondary dictionary.
* Delete words from the dictionary ; Aspell does not seem to permit it
through a piped call, while it is quite easy to perform. But is it safe
in regard of its future versions ? Will be supported if the option
|g:VS_aspell_add_directly_to_dict| is set to true.
* Dedicate a sub-menu for the different options.
* Extension to other file types : extend the file-type2mode recognition
function ; only TeX, ML-like and None/url are recognized for now.
Actually, I do support only the formats supported by Aspell.
* Wrap other functions exclusives to Aspell (e.g. sounds-like words and
lists of words, phonemes, score between words)
* Add g:VS_language to the names of cached files.
* Being able to ask for alternatives on the fly ; i.e. not only for
cached misspellings.
* Improve the customization possibilities of the mappings -- some people
like mappings starting with backslashes.
* Better handling of the splitted window for a more ergonomic plugin.
* Option for vertical splitting of window with vim6 ; could be nicest.
* Option for displaying suggested alternatives in a popup-menu ; why not.
* Delete unneeded code
* Silent execution under VIM 6 to be improved -- allow messages for
instance.
* VIM 6 local menus ; works fine with VIM 5.7 + buffoption.vim
------------------------------------------------------------------------------
*References*
References:
Links to external programs
The VIM editor *VIM*
Do I really need to present you this wonderful text editor ?
Just in case, the plugin presented here has been written for VIM --
http://vim.sourceforge.net/
[IA]spell *IA-spell*
I use [IA]spell to refer to either |Ispell| or |Aspell|. Indeed, these
tools accept a same and important set of parameters. Therefore, this
plugin rely on this common set and can be used with either spell-checker
; see |g:VS_spell_prog|. Of course one or the other is needed by the
plugin.
Ispell *Ispell*
Ispell is the widely distributed spell-checker I use as reference for
this plugin.
Ispell hasn't been tested but should be OK with this plugin.
http://fmg-www.cs.ucla.edu/geoff/ispell.html
Aspell *Aspell*
"Aspell is an Open Source spell checker designed to eventually replace
Ispell. Its main feature is that it does a much better job of coming up
with possible suggestions than Ispell does. In fact recent tests shows
that it even does better than Microsoft Word 97's spell checker in some
cases."
© Kevin Atkinson, from Aspell's introduction.
It takes into account the sonority of words.
http://aspell.sourceforge.net/
Text tools *cat* *echo*
The text tools and more precisely cat is required on your system. Make
sure it is accessible from your ${PATH}.
Rem.: I use "cat" instead of "echo" because "echo" looses accents and
cuts word when they occur on my Windows NT system.
Dependencies
This plugin rely on some other plugins like :
a.vim *alternate*
Defines some functions to go to specific windows/buffers.
Critical. As this plugin has changed since its first version, I join an
usable (with VIM-Spell) version of a.vim in the archive.
http://vim.sf.net/scripts/script.php?script_id=31
Triggers.vim *triggering*
Big piece of script. It permits to execute one action or an other on a
trigger -- extension of the VIM toggling feature.
This script is facultative. If installed, the language |Swap| ping
feature will be automatically enabled.
http://hermitte.free.fr/vim/general.php3#Triggers_vim
buffoption.vim *buffoption*
This file is used to define buffer relative mappings with versions of VIM
prior to the 6 series -- critical in that case. As, I write my mappings
as "noremap"s, you should retrieve my patch from
http://hermitte.free.fr/vim/ftplugin.php3#buffoptions2_vim you
will also need : buffoptions_map2.vim and fileuptodate.vim.
With the VIM 6 series, this file is no longer required.
Other related VIM's plugins
Claudio Fleiner's vimspell.vim. *vimspell*
This plugins is the one that inspired me at first. It generates the list
of misspelled words through a call to |IA-spell|, then highlights them in
the Error syntax style. It permits to : - jump from a misspelled word to
the next one, - add them to the |IA-spell|'s dictionary, - ignore them,
- and see a list of alternative words.
http://www.fleiner.com/vim/spell.html
Dr. Charles E. Campbell, Jr.'s engspchk.vim. *engspchk*
A really big piece of plugin! It needs no external tool. The dictionary
is part of the plugin ; hence, it has to be extended and ported to other
languages. It highlights misspelled words, enables to jump from one to
another, and manages the dictionary. With VIM v6.0+, it can compute
alternative words.
I've stolen my jumping functions, and TeX highlighting rules from this
plugin.
http://www.erols.com/astronaut/vim/index.html#Spelling
Matthias Veit's spellcheck.vim for VIM 6 (only ?) *spellcheck*
Require Aspell and ruby => I haven't tested it. It seems that I permit
much more things.
http://vim.sf.net/scripts/script.php?script_id=131
Johannes Zellner's Aspell.vim for VIM 6.0 *JZ*
Another spell-checking plugin wrapping Aspell.
http://www.zellner.org/vim/autoload/Aspell.vim
Yegappan Lakshmanan's spell.vim *YL*
Plugin that wraps calls to the UNIX spell-checker : spell. It can also
parses selected text, and not only files. But no alternatives proposed.
http://vim.sf.net/scripts/script.php?script_id=232
Text Processing With Integrated Spell Checking
Presents different stuffs and another simple way to call Aspell from VIM:
http://www.highley-recommended.com/text-processing.html
------------------------------------------------------------------------------
© Luc Hermitte, 2001-2002 http://hermitte.free.fr/vim
top