519 lines
23 KiB
Plaintext
519 lines
23 KiB
Plaintext
*vimspell.txt* On the fly spell checker with ispell/aspell. v1.100
|
|
|
|
|
|
VIMSPELL REFERENCE MANUAL~
|
|
|
|
|
|
Spelling text with the plugin "Vimspell"
|
|
|
|
|
|
==============================================================================
|
|
CONTENT *vimspell-contents*
|
|
|
|
Installation : |vimspell-install|
|
|
Vimspell intro : |vimspell|
|
|
Requirements : |vimspell-requirements|
|
|
Vimspell commands : |vimspell-commands|
|
|
Customization : |vimspell-customize|
|
|
Bugs : |vimspell-bugs|
|
|
Faq : |vimspell-tips|
|
|
Todo list : |vimspell-todo|
|
|
|
|
==============================================================================
|
|
1. vimspell Installation *vimspell-install*
|
|
|
|
In order to install the plugin, place the vimspell.vim file into a plugin
|
|
directory in your runtime path (please see |add-global-plugin| and
|
|
|'runtimepath'|).
|
|
|
|
By default, on-the-fly spell checking is enable for certain filetypes
|
|
only. To disable it put the following line in your .vimrc : >
|
|
let spell_auto_type = ""
|
|
<
|
|
In order to activate it for a filetype, you should redefine the
|
|
|spell_auto_type| variable (see below).
|
|
|
|
|vimspell| may be customized by setting variables, creating maps, and
|
|
specifying event handlers. Please see |vimspell-customize| for more
|
|
details.
|
|
|
|
Set 'mousemodel' to "popup_setpos" in order to enable popup menus (see
|
|
|vimspell-popup|).
|
|
|
|
*vimspell-auto-help*
|
|
This help file is automagically generated when the |vimspell| script is
|
|
loaded for the first time.
|
|
|
|
==============================================================================
|
|
1.1. vimspell requirements *vimspell-requirements*
|
|
|
|
Vimspell needs the following external tools :
|
|
- 'ispell' or 'aspell' spell checkers
|
|
|
|
It has been tested with vim 6.1, but should also work with vim 6.0.
|
|
|
|
==============================================================================
|
|
2. vimspell intro *vimspell*
|
|
*spell* *vimspell-intro*
|
|
|
|
vimspell script provides functions and mappings to check spelling ; either
|
|
on demand on the whole buffer, or for the current visible window whenever
|
|
the cursor is idle for a certain time.
|
|
|
|
The default mappings are defined as follow (By default, <Leader> stands
|
|
for '\'. See |Leader| for more info) :
|
|
|
|
<Leader>ss - write file, spellcheck file & highlight spelling mistakes.
|
|
<Leader>sA - start autospell mode.
|
|
<Leader>sl - switch between languages.
|
|
<Leader>s? - check for alternatives.
|
|
<RightMouse> - open a popup menu with alternatives (see |vimspell-popup|).
|
|
|
|
<Leader>sn - go to next error.
|
|
<Leader>sp - go to previous error.
|
|
<Leader>si - insert word under cursor into user dictionary.
|
|
<Leader>su - insert word under cursor as lowercase into user dictionary.
|
|
<Leader>sa - accept word for this session only.
|
|
<Leader>sq - return to normal syntax coloring and disable auto spell
|
|
checking.
|
|
|
|
Note that those last mappings are only defined once the spelling was
|
|
checked.
|
|
|
|
See |vimspell-mappings-override| and |vimspell-options| to learn how to
|
|
override those default mappings.
|
|
|
|
==============================================================================
|
|
3. vimspell commands *vimspell-commands*
|
|
|
|
See |vimspell-intro| for default mapping. Vimspell defines the following
|
|
commands:
|
|
|
|
:SpellCheck *:SpellCheck*
|
|
Spell check the text after _writing_ the buffer. Define highlighting and
|
|
mapping for correction and navigation.
|
|
|
|
:SpellAutoEnable *:SpellAutoEnable*
|
|
Enable on-the-fly spell checking.
|
|
|
|
:SpellAutoDisable *:SpellAutoDisable*
|
|
Disable on-the-fly spell checking.
|
|
|
|
:SpellChangeLanguage *:SpellChangeLanguage*
|
|
Select the next language available.
|
|
|
|
:SpellSetLanguage *:SpellSetLanguage*
|
|
Set the language to the one given as a parameter.
|
|
|
|
:SpellSetSpellchecker *:SpellSetSpellchecker*
|
|
Set the spell checker to the string given as a parameter (currently,
|
|
aspell or ispell are supported).
|
|
|
|
:SpellProposeAlternatives *:SpellProposeAlternatives*
|
|
Propose alternative for keyword under cursor. If more than 10
|
|
alternatives exists, you can choose between the first 9 alternatives by
|
|
typing 1 to 9 follow by the 'return' key, or by typing 01 to 09.
|
|
|
|
:SpellExit *:SpellExit*
|
|
Remove syntax highlighting and mapping defined for spell checking.
|
|
|
|
:SpellReload *:SpellReload*
|
|
Reload vimspell script.
|
|
|
|
==============================================================================
|
|
4. Vimspell customization *vimspell-customize*
|
|
|
|
4.1. General configuration ~
|
|
--------------------------
|
|
*loaded_vimspell* *vimspell-disable*
|
|
You can disable this script by putting the following line in your |vimrc| >
|
|
let loaded_vimspell = 1
|
|
<
|
|
|
|
You can define your own color scheme for error highlighting, by setting
|
|
|highlight| on SpellErrors group. For example: >
|
|
highlight SpellErrors guibg=Red guifg=Black
|
|
<
|
|
If no words appear to be highlighted after a spell check, try to put the
|
|
following lines in your |vimrc|: >
|
|
highlight SpellErrors ctermfg=Red guifg=Red
|
|
\ cterm=underline gui=underline term=reverse
|
|
<
|
|
*vimspell-popup*
|
|
You can right click on a word to get a popup menu which contains a "Spell"
|
|
sub-menu with all alternatives for the word under the cursor.
|
|
In order to get the popup menu, you must be sure that 'mousemodel' is set
|
|
to "popup" or to "popup_setpos" (see |'mousemodel'|).
|
|
|
|
4.2. Mapping documentation: ~
|
|
---------------------------
|
|
*vimspell-mappings-override*
|
|
By default, a global mapping is defined for some commands. User-provided
|
|
mappings can be used instead by mapping to <Plug>CommandName. This is
|
|
especially useful when these mappings collide with other existing mappings
|
|
(vim will warn of this during plugin initialization, but will not clobber
|
|
the existing mappings).
|
|
|
|
For instance, to override the default mapping for :SpellCheck to set it to
|
|
\sc, add the following to the |vimrc|:
|
|
>
|
|
nmap \sc <Plug>SpellCheck
|
|
<
|
|
The default global mappings are as follow:
|
|
|
|
<Leader>ss SpellCheck
|
|
<Leader>sA SpellAutoEnable
|
|
<Leader>s? SpellProposeAlternatives
|
|
<Leader>sl SpellChangeLanguage
|
|
|
|
Other mapping are defined according to the context of utilisation, and can
|
|
be redefined by mean of buffer-wise variables. See |vimspell-options| here
|
|
after.
|
|
|
|
4.3. Options documentation: ~
|
|
---------------------------
|
|
*vimspell-options*
|
|
Several variables are checked by the script to customize vimspell
|
|
behavior. Note that variables are looked for in the following order :
|
|
window dependent variables first, buffer dependent variables next and
|
|
global ones last (See |internal-variables|, |buffer-variable|,
|
|
|window-variable| and |global-variable|).
|
|
|
|
spell_case_accept_map *spell_case_accept_map*
|
|
This variable, if set, determines the mapping used to accept the word
|
|
under the cursor, taking case into account. Defaults to: >
|
|
let spell_case_accept_map = "<Leader>si"
|
|
<
|
|
When using 'ispell' the accepted words are put in the
|
|
./.ispell_<language> file if it exists or in the
|
|
$HOME/.ispell_<language> file.
|
|
|
|
|
|
spell_accept_map *spell_accept_map*
|
|
This variable, if set, determines the mapping used to accept a lowercase
|
|
version of the word under the cursor. Defaults to: >
|
|
let spell_accept_map = "<Leader>su"
|
|
<
|
|
|
|
spell_ignore_map *spell_ignore_map*
|
|
This variable, if set, determines the mapping used to ignore the
|
|
spelling error for the current session. Defaults to: >
|
|
let spell_ignore_map = "<Leader>sa"
|
|
<
|
|
|
|
spell_next_error_map *spell_next_error_map*
|
|
This variable, if set, determines the mapping used to jump to the next
|
|
spelling error. Defaults to: >
|
|
let spell_next_error_map = "<Leader>sn"
|
|
<
|
|
|
|
spell_previous_error_map *spell_previous_error_map*
|
|
This variable, if set, determines the mapping used to jump to the
|
|
previous spelling error. Defaults to: >
|
|
let spell_previous_error_map = "<Leader>sp"
|
|
<
|
|
|
|
spell_exit_map *spell_exit_map*
|
|
This variable, if set, determines the mapping used to exit from
|
|
spelling-checker mode. Defaults to: >
|
|
let spell_exit_map = "<Leader>sq"
|
|
<
|
|
|
|
spell_executable *spell_executable*
|
|
This variable, if set, defines the name of the spell-checker. Defaults
|
|
to: >
|
|
let spell_executable = "ispell"
|
|
<
|
|
|
|
spell_filter *spell_filter*
|
|
This variable, if set, defines the name of a script designed to filter
|
|
out certain words from the standard input to the standard output.
|
|
Defaults to: >
|
|
let spell_filter = ""
|
|
< For example : >
|
|
let spell_filter="grep -v '^#' "
|
|
< would prevent line beginning by # to be spell checked.
|
|
|
|
|
|
spell_update_time *spell_update_time*
|
|
This variable, if set, defines the duration (in ms) between the last
|
|
cursor movement and the on-the-fly spell check. Defaults to: >
|
|
let spell_update_time = 2000
|
|
<
|
|
|
|
spell_language_list *vimspell_default_language* *spell_language_list*
|
|
This variable, if set, defines the languages available for spelling. The
|
|
language names are the ones passed as an option to the spell checker.
|
|
Defaults to the languages for which a dictionary is present, or if none
|
|
can be found in the standard location, to: >
|
|
let spell_language_list = "english,francais"
|
|
< Note: The first language of this list is the one selected by default.
|
|
An empty list force vimspell to select dictionaries installed for the
|
|
selected spell checker.
|
|
|
|
|
|
spell_options *spell_options*
|
|
This variable, if set, defines additional options passed to the spell
|
|
checker executable. Defaults for ispell to: >
|
|
let spell_options = "-S"
|
|
< and for aspell to: >
|
|
let spell_options = ""
|
|
<
|
|
|
|
spell_auto_type *spell_auto_type*
|
|
This variable, if set, defines a list of filetype for which spell check
|
|
is done on the fly by default. Set it to "all" if you want on-the-fly
|
|
spell check for every filetype. You can use the token "none" if you
|
|
want on-the-fly spell check for files which do not have a filetype.
|
|
Defaults to: >
|
|
let spell_auto_type = "tex,mail,text,html,sgml,otl,cvs,none"
|
|
< Note: the "text" and "otl" filetypes are not defined by vim. Look at
|
|
|new-filetype| to see how you could yourself define a new filetype.
|
|
|
|
|
|
spell_guess_language_ft *spell_guess_language_ft*
|
|
This variable, if set, defines a list of filetype for which vimspell try
|
|
to automatically find which language is in use. Set it to "all" if you
|
|
want to use the guess heuristic for every filetype. You can use the
|
|
token "none" if you want to use it for files which do not have a
|
|
filetype.
|
|
Defaults to: >
|
|
let spell_guess_language_ft = "tex,mail,text,html"
|
|
< Note: the "text" filetype is not defined by vim. Look at |new-filetype|
|
|
to see how you could yourself define a new filetype.
|
|
|
|
|
|
spell_guess_max_languages *spell_guess_max_languages*
|
|
This variable if set, set up how many languages are checked against the
|
|
current buffer when vimspell try to determines the language in use. At
|
|
most 'spell_ispell_sgml_args' are checked, and the one which best
|
|
matches the current buffer is selected.
|
|
Defaults to: >
|
|
let spell_guess_max_languages = 3
|
|
<
|
|
|
|
|
|
spell_guess_max_lines *spell_guess_max_lines*
|
|
This variable, if set to a positive number, defines the number of lines
|
|
considered when guessing the language of the buffer. Otherwise, the
|
|
entire buffer is considered. Note that this feature makes use of the
|
|
'head' unix command.
|
|
Defaults to: >
|
|
let spell_guess_max_lines = 0
|
|
<
|
|
|
|
spell_insert_mode *spell_insert_mode*
|
|
This variable if set, set up a hack to allow spell checking in insert
|
|
mode. This is normally not possible by mean of autocommands, but is
|
|
done with a map to the <Space> key. Each time that <Space> is hit,
|
|
the current line is spell checked. This feature can slow down vim
|
|
enough but is otherwise very nice.
|
|
Note that the mapping is defined only when spell check is done on the
|
|
fly (see |spell_auto_type|). The 'backspace' may be modified when this
|
|
option is set.
|
|
Defaults to: >
|
|
let spell_insert_mode = 1
|
|
<
|
|
|
|
spell_no_readonly *spell_no_readonly*
|
|
This variable, if set, defines if read-only files are spell checked or
|
|
not. Defaults to: >
|
|
let spell_no_readonly = 1 "no spell check for read only files.
|
|
<
|
|
|
|
spell_auto_jump *spell_auto_jump*
|
|
This variable, if set, make the cursor automatically jump to the next
|
|
error after:
|
|
- inserting a word in the user dictionary,
|
|
- accepting a word for the editing session,
|
|
- accepting a suggestion from the alternative list.
|
|
Defaults to: >
|
|
let spell_auto_jump = 1
|
|
<
|
|
|
|
spell_markup_ft *spell_markup_ft*
|
|
This variable, if set, defines a list of filetype for which vimspell
|
|
highlights all errors, and not only those included in the @Spell cluster
|
|
(see |syn-cluster|).
|
|
Defaults to: >
|
|
let spell_markup_ft = ",html,php,xhtml,dtml,tex,mail,help,text,,"
|
|
< Note the beginning and ending commas.
|
|
|
|
|
|
spell_{spellchecker}_{filetype}_args
|
|
*spell_spellchecker_args* *spell_filetype_args*
|
|
Those variables, if set, define the options passed to the "spellchecker"
|
|
executable for the files of type "filetype". By default, they are set
|
|
to options known by ispell and aspell for tex, html, sgml, email
|
|
filetype. See also |vimspell-ispell-dont-work| below.
|
|
For example: >
|
|
let spell_aspell_tex_args = "-t"
|
|
<
|
|
|
|
spell_{language}_iskeyword *spell_iskeyword*
|
|
Those variables if set define the characters which are part of a word
|
|
in the selected language. See |iskeyword| for more informations.
|
|
Note that the hereafter described variables (the filetype and language
|
|
dependent ones) overrides, if exists, the spell_{language}_iskeyword
|
|
variables.
|
|
The following ones are defined: >
|
|
let s:spell_francais_iskeyword = "@,48-57,_,192-255,39,½,æ,¼,Æ,-"
|
|
let s:spell_russian_iskeyword = "@,48-57,_,192-255,^a-z,^A-Z"
|
|
let s:spell_english_iskeyword = "@,48-57,_,192-255,^192-255"
|
|
< which says for example that the quote, the hyphen and some other digraphs
|
|
must be considered as being part of french words.
|
|
|
|
|
|
spell_{language}_{filetype}_iskeyword
|
|
Those variable have exactly the same impact as the previous one, except
|
|
that they are filetype dependant.
|
|
The following is defined: >
|
|
let s:spell_german_tex_iskeyword = "@,48-57,192-255,=,\,34"
|
|
< which says that the double quote (char 34) must be considered as being
|
|
part of words in german tex files.
|
|
|
|
|
|
spell_root_menu *spell_root_menu*
|
|
This variable, if set, give the name of the menu in which the vimspell
|
|
menu will be put. If set to '-', no menu are displayed. Defaults to: >
|
|
let spell_root_menu = "Plugin."
|
|
< Note the termination dot.
|
|
spell_root_menu_priority must be set accordingly. Set them both to "" if
|
|
you want vimspell menu in the main menu bar.
|
|
|
|
|
|
spell_root_menu_priority *spell_root_menu_priority*
|
|
This variable, if set, give the priority of the menu containing the
|
|
vimspell menu. Defaults to: >
|
|
let spell_root_menu_priority = "500."
|
|
< which is quite on the right of the menu bar.
|
|
Note the termination dot.
|
|
|
|
|
|
spell_menu_priority *spell_menu_priority*
|
|
This variable, if set, give the priority of the vimspell menu. Defaults
|
|
to: >
|
|
let spell_menu_priority = "10."
|
|
< Note the termination dot.
|
|
|
|
|
|
spell_shell *spell_shell*
|
|
This variable, if set, gives the name of the shell use for the system
|
|
calls. Defaults to: >
|
|
let spell_shell = "/bin/sh"
|
|
< Note that other shells may not work as expected. For example, tcsh
|
|
quoting differs from bash.
|
|
|
|
|
|
==============================================================================
|
|
5. Vimspell FAQ *vimspell-faq*
|
|
*vimspell-ispell-dont-work*
|
|
When I try to spell check an HTML file using ispell, I got an error like
|
|
"Not an editor command: -pfile | -wchars | ..."
|
|
|
|
By default, vimspell pass the "-H" option to tell ispell that the file
|
|
in which he is looking for errors is an HTML file. This option changed
|
|
accross ispell versions. You should adjust the
|
|
'spell_ispell_html_args' and 'spell_ispell_sgml_args' variables
|
|
appropriately. For example, with ispell 3.1.20, you should set the
|
|
following lines in your .vimrc : >
|
|
let spell_ispell_html_args = "-h"
|
|
let spell_ispell_sgml_args = "-h"
|
|
<
|
|
*vimspell-latex-geman-quotes*
|
|
Use of vimspell for latex file in german.
|
|
|
|
Vimspell should work fine with german and latex but one problem stays:
|
|
the german quotation marks which can be written "` and "' in latex.
|
|
When replacing a word between german quotation marks, the last double
|
|
quote will be replaced, destroying the quotation marks.
|
|
The solution is to use \glqq and \grqq for german left and right
|
|
quotation marks.
|
|
|
|
How to minimize overhead on a small configuration.
|
|
|
|
Do not use menu nor auto spell. Put the following line in your .vimrc: >
|
|
let spell_root_menu = '-'
|
|
let spell_auto_type = ''
|
|
let spell_insert_mode = 0
|
|
<
|
|
|
|
If you use the automatic guess language feature, you can also limit the
|
|
number of lines used for guessing (this feature need the external
|
|
"head" command to work) : >
|
|
let spell_guess_max_lines = 30
|
|
<
|
|
Or you can disable this feature by putting the following line in your
|
|
.vimrc: >
|
|
let spell_guess_language_ft = ""
|
|
<
|
|
|
|
The number of errors returned by vimspell doesn't match the number of
|
|
keywords underlined !
|
|
|
|
Yes. It is a known problem. When calling the SpellCheck function,
|
|
[ai]spell is fed with the whole text, even if some parts are not
|
|
concerned by error highlighting (for exemple, in shell scripts, only
|
|
errors in strings and comments are highlighted).
|
|
|
|
Aspell doesn't understand the "oe" ligature, in iso-8859-15 encoding.
|
|
|
|
Aspell does understant the ligature, but you must use the good
|
|
dictionary. You can get one at : >
|
|
http://geodisi.u-strasbg.fr/~daurat/latin9/
|
|
<
|
|
==============================================================================
|
|
6. Vimspell bugs *vimspell-bugs*
|
|
|
|
I'm not able to reproduce most of those bug with last version of vim and
|
|
vimspell. If someone has more information about them, I will welcome them.
|
|
|
|
- BUG digraphs are not passed to aspell/ispell. Since iskeyword is set
|
|
globally, they are not underlined in red...
|
|
- When not all errors are highlighted, SpellCheck() display an erroneous
|
|
error count.
|
|
- problem when opening file with a swap files. Messages are not visible.
|
|
to be reproduced...
|
|
- ispell doesn't seem to work with word containing iso-8559 encoded
|
|
characters in TeX files...
|
|
- BUG reported by Fabio Stumbo <f.stumbo@unife.it>:
|
|
Textual navigation in Plugin submenus doesn't work when pressing <F4>
|
|
with the following .vimrc settings: >
|
|
source $VIMRUNTIME/menu.vim
|
|
set wildmenu
|
|
set cpo-=<
|
|
set wcm=<C-Z>
|
|
map <F4> :emenu <C-Z>
|
|
< - BUG reported by Rajarshi Guha. Vim 6.1 hang up with vimspell 1.46 when
|
|
editing HTML (with EasyHtml 0.5.1 script) and sometimes when editing
|
|
latex *with aspell*. Vim need kill -9. -- I'm not able to reproduced it
|
|
with vimspell 1.65 (see also Fabio Stumbo bug below)...
|
|
- BUG with aspell (aspell-0.33.7.1-7mdk) on HTML files where aspell seems
|
|
to loop infinitely (Fabio Stumbo <f.stumbo@unife.it>).
|
|
- autocommands are not called in insert mode : this is apparently a
|
|
feature of VIM. There will perhaps be a hook which will allow this in
|
|
vim 6.2, but Bram seems quite reluctant in implementing it (because
|
|
autocomands are dangerous and difficult to test thoroughly).
|
|
|
|
==============================================================================
|
|
7. Vimspell .TODO list *vimspell-todo*
|
|
|
|
- Take into account the FileType event to setup buffer correctly.
|
|
- Add a way to customize the spell checking (so as to not use the syntax
|
|
highlighting as a way to determine was as to be checked). For example,
|
|
with the current syntax files, html and xml are badly checked.
|
|
- Add a command to spellcheck a visually selected region
|
|
- Add options to prevent some words to be checked (like TODO). If not,
|
|
their highlighting is overwritten by spellcheck's one (depends of TODO
|
|
highlighting definition... To be investigated).
|
|
- selection of syntax group for which spelling is done (for example, only
|
|
string and comments are of interest in a C source code..) - Partly done.
|
|
- update documentation to explain the logic behind the existence of to way
|
|
to redefine mappings, deppending on the mapping.
|
|
- ...
|
|
- reduce this TODO list (I didn't think it would have grown so quickly).
|
|
|
|
==============================================================================
|
|
|
|
vim:tw=78:ts=8:ft=help:norl:
|