blob: b33dec22016c26d09972bdca474845a03a13b984 [file] [log] [blame]
Bram Moolenaar0e21a3f2005-04-17 20:28:32 +00001*spell.txt* For Vim version 7.0aa. Last change: 2005 Apr 17
Bram Moolenaar217ad922005-03-20 22:37:15 +00002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
7Spell checking *spell*
8
91. Quick start |spell-quickstart|
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000102. Generating a spell file |spell-mkspell|
119. Spell file format |spell-file-format|
Bram Moolenaar217ad922005-03-20 22:37:15 +000012
13{Vi does not have any of these commands}
14
15Spell checking is not available when the |+syntax| feature has been disabled
16at compile time.
17
18==============================================================================
191. Quick start *spell-quickstart*
20
21This command switches on spell checking: >
22
23 :setlocal spell spelllang=en_us
24
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +000025This switches on the 'spell' option and specifies to check for US English.
Bram Moolenaar217ad922005-03-20 22:37:15 +000026
27The words that are not recognized are highlighted with one of these:
28 SpellBad word not recognized
29 SpellRare rare word
30 SpellLocal wrong spelling for selected region
31
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +000032Vim only checks words for spelling, there is no grammar check.
33
34To search for the next misspelled word:
35
36 *]s* *E756*
37]s Move to next misspelled word after the cursor.
38
39 *[s*
40[s Move to next misspelled word before the cursor.
41 DOESN'T WORK YET!
42
Bram Moolenaar217ad922005-03-20 22:37:15 +000043
Bram Moolenaar6bb68362005-03-22 23:03:44 +000044PERFORMANCE
45
46Note that Vim does on-the-fly spellchecking. To make this work fast the
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +000047word list is loaded in memory. Thus this uses a lot of memory (1 Mbyte or
Bram Moolenaar6bb68362005-03-22 23:03:44 +000048more). There might also be a noticable delay when the word list is loaded,
49which happens when 'spelllang' is set. Each word list is only loaded once,
50they are not deleted when 'spelllang' is made empty. When 'encoding' is set
51the word lists are reloaded, thus you may notice a delay then too.
52
53
Bram Moolenaar217ad922005-03-20 22:37:15 +000054REGIONS
55
56A word may be spelled differently in various regions. For example, English
57comes in (at least) these variants:
58
59 en all regions
60 en_us US
61 en_gb Great Britain
62 en_ca Canada
63
64Words that are not used in one region but are used in another region are
65highlighted with SpellLocal.
66
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +000067Always use lowercase letters for the language and region names.
Bram Moolenaar217ad922005-03-20 22:37:15 +000068
69
70SPELL FILES
71
72Vim searches for spell files in the "spell" subdirectory of the directories in
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +000073'runtimepath'. The name is: LL-XXX.EEE.spl, where:
74 LL the language name
75 -XXX optional addition
76 EEE the value of 'encoding'
Bram Moolenaar217ad922005-03-20 22:37:15 +000077
Bram Moolenaar0e21a3f2005-04-17 20:28:32 +000078Exceptions:
79- Vim uses "latin1" when 'encoding' is "iso-8859-15". The euro sign doesn't
80 matter for spelling.
81- When no spell file for 'encoding' is found "ascii" is tried. This only
82 works for languages where nearly all words are ASCII, such as English. It
83 helps when 'encoding' is not "latin1", such as iso-8859-2, and English text
84 is being edited.
Bram Moolenaar217ad922005-03-20 22:37:15 +000085
Bram Moolenaar6bb68362005-03-22 23:03:44 +000086Spelling for EBCDIC is currently not supported.
87
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +000088A spell file might not be available in the current 'encoding'. See
89|spell-mkspell| about how to create a spell file. Converting a spell file
Bram Moolenaar0e21a3f2005-04-17 20:28:32 +000090with "iconv" will NOT work!
Bram Moolenaar217ad922005-03-20 22:37:15 +000091
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +000092 *E758* *E759*
93When loading a spell file Vim checks that it is properly formatted. If you
Bram Moolenaar0e21a3f2005-04-17 20:28:32 +000094get an error the file may be truncated, modified or intended for another Vim
95version.
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +000096
Bram Moolenaar6bb68362005-03-22 23:03:44 +000097
98WORDS
99
100Vim uses a fixed method to recognize a word. This is independent of
101'iskeyword', so that it also works in help files and for languages that
102include characters like '-' in 'iskeyword'. The word characters do depend on
103'encoding'.
104
105A word that starts with a digit is always ignored.
106
107
108SYNTAX HIGHLIGHTING
109
110Files that use syntax highlighting can specify where spell checking should be
111done:
112
113 everywhere default
114 in specific items use "contains=@Spell"
115 everywhere but specific items use "contains=@NoSpell"
116
117Note that mixing @Spell and @NoSpell doesn't make sense.
118
Bram Moolenaar217ad922005-03-20 22:37:15 +0000119==============================================================================
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001202. Generating a spell file *spell-mkspell*
Bram Moolenaar217ad922005-03-20 22:37:15 +0000121
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000122Vim uses a binary file format for spelling. This greatly speeds up loading
123the word list and keeps it small.
Bram Moolenaar217ad922005-03-20 22:37:15 +0000124
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000125You can create a Vim spell file from the .aff and .dic files that Myspell
126uses. Myspell is used by OpenOffice.org and Mozilla. You should be able to
127find them here:
128 http://lingucomponent.openoffice.org/spell_dic.html
Bram Moolenaar217ad922005-03-20 22:37:15 +0000129
Bram Moolenaar0e21a3f2005-04-17 20:28:32 +0000130:mksp[ell] [-ascii] {outname} {inname} ... *:mksp* *:mkspell*
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000131 Generate spell file {outname}.spl from Myspell files
132 {inname}.aff and {inname}.dic.
Bram Moolenaar0e21a3f2005-04-17 20:28:32 +0000133 When the [-ascii] argument is present, words with
134 non-ascii characters are skipped. The resulting file
135 ends in "ascii.spl". Otherwise the resulting file
136 ends in "ENC.spl", where ENC is the value of
137 'encoding'.
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000138 Multiple {inname} arguments can be given to combine
139 regions into one Vim spell file. Example: >
140 :mkspell ~/.vim/spell/en /tmp/en_US /tmp/en_CA /tmp/en_AU
141< This combines the English word lists for US, CA and AU
142 into one en.spl file.
143 Up to eight regions can be combined. *E754* *755*
Bram Moolenaar217ad922005-03-20 22:37:15 +0000144
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000145Since you might want to change the word list for use with Vim the following
146procedure is recommended:
Bram Moolenaar217ad922005-03-20 22:37:15 +0000147
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001481. Obtain the xx_YY.aff and xx_YY.dic files from Myspell.
1492. Make a copy of these files to xx_YY.orig.aff and xx_YY.orig.dic.
1503. Change the xx_YY.aff and xx_YY.dic files to remove bad words, add missing
151 words, etc.
1524. Use |:mkspell| to generate the Vim spell file and try it out.
Bram Moolenaar217ad922005-03-20 22:37:15 +0000153
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000154When the Myspell files are updated you can merge the differences:
1555. Obtain the new Myspell files as xx_YY.new.aff and xx_UU.new.dic.
1566. Use Vimdiff to see what changed: >
157 vimdiff xx_YY.orig.dic xx_YY.new.dic
1587. Take over the changes you like in xx_YY.dic.
159 You may also need to change xx_YY.aff.
1608. Rename xx_YY.new.dic to xx_YY.orig.dic and xx_YY.new.aff to xx_YY.new.aff.
Bram Moolenaar217ad922005-03-20 22:37:15 +0000161
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000162==============================================================================
1639. Spell file format *spell-file-format*
Bram Moolenaar217ad922005-03-20 22:37:15 +0000164
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000165This is the format of the files that are used by the person who creates and
166maintains a word list.
Bram Moolenaar217ad922005-03-20 22:37:15 +0000167
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000168Note that we avoid the word "dictionary" here. That is because the goal of
169spell checking differs from writing a dictionary (as in the book). For
170spelling we need a list of words that are OK, thus need not to be highlighted.
171Names will not appear in a dictionary, but do appear in a word list. And
172some old words are rarely used and are common misspellings. These do appear
173in a dictionary but not in a word list.
Bram Moolenaar217ad922005-03-20 22:37:15 +0000174
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000175There are two files: the basic word list and an affix file. The affixes are
176used to modify the basic words to get the full word list. This significantly
177reduces the number of words, especially for a language like Polish. This is
178called affix compression.
Bram Moolenaar217ad922005-03-20 22:37:15 +0000179
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000180The format for the affix and word list files is mostly identical to what
181Myspell uses (the spell checker of Mozilla and OpenOffice.org). A description
182can be found here:
183 http://lingucomponent.openoffice.org/affix.readme ~
184Note that affixes are case sensitive, this isn't obvious from the description.
185Vim supports a few extras. Hopefully Myspell will support these too some day.
186See |spell-affix-vim|.
Bram Moolenaar217ad922005-03-20 22:37:15 +0000187
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000188The basic word list and the affix file are combined and turned into a binary
189spell file. All the preprocessing has been done, thus this file loads fast.
190The binary spell file format is described in the source code (src/spell.c).
191But only developers need to know about it.
192
193The preprocessing also allows us to take the Myspell language files and modify
194them before the Vim word list is made. The tools for this can be found in the
195"src/spell" directory.
196
197
198WORD LIST FORMAT *spell-wordlist-format*
199
200A very short example, with line numbers:
201
202 1 1234
203 2 aan
204 3 Als
205 4 Etten-Leur
206 5 et al.
207 6 's-Gravenhage
208 7 's-Gravenhaags
209 8 bedel/P
210 9 kado/1
211 10 cadeau/2
212
213The first line contains the number of words. Vim ignores it. *E760*
214
215What follows is one word per line. There should be no white space after the
216word.
217
218When the word only has lower-case letters it will also match with the word
219starting with an upper-case letter.
220
221When the word includes an upper-case letter, this means the upper-case letter
222is required at this position. The same word with a lower-case letter at this
223position will not match. When some of the other letters are upper-case it will
224not match either.
225
226The same word with all upper-case characters will always be OK.
227
228 word list matches does not match ~
229 als als Als ALS ALs AlS aLs aLS
230 Als Als ALS als ALs AlS aLs aLS
231 ALS ALS als Als ALs AlS aLs aLS
232 AlS AlS ALS als Als ALs aLs aLS
233
234Note in line 5 to 7 that non-word characters are used. You can include
235any character in a word. When checking the text a word still only matches
236when it appears with a non-word character before and after it. For Myspell a
237word starting with a non-word character probably won't work.
238
239After the word there is an optional slash and flags. Most of these flags are
240letters that indicate the affixes that can be used with this word.
241
242 *spell-affix-vim*
243A flag that Vim adds and is not in Myspell is the "=" flag. This has the
244meaning that case matters. This can be used if the word does not have the
245first letter in upper case at the start of a sentence. Example:
246
247 word list matches does not match ~
248 's morgens/= 's morgens 'S morgens 's Morgens
249 's Morgens 's Morgens 'S morgens 's morgens
250
251 *spell-affix-mbyte*
252The basic word list is normally in an 8-bit encoding, which is mentioned in
253the affix file. The affix file must always be in the same encoding as the
254word list. This is compatible with Myspell. For Vim the encoding may also be
255something else, any encoding that "iconv" supports. The "SET" line must
256specify the name of the encoding. When using a multi-byte encoding it's
257possible to use more different affixes.
258
259Performance hint: Although using affixes reduces the number of words, it
260reduces the speed. It's a good idea to put all the often used words in the
261word list with the affixes prepended/appended.
Bram Moolenaar217ad922005-03-20 22:37:15 +0000262
263
264 vim:tw=78:sw=4:ts=8:ft=help:norl: