blob: a9cc7e1ed4eaaef8b84b029bc2300f7d13dd9b62 [file] [log] [blame]
Bram Moolenaar5c5474b2005-04-19 21:40:26 +00001*spell.txt* For Vim version 7.0aa. Last change: 2005 Apr 19
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.
Bram Moolenaar5c5474b2005-04-19 21:40:26 +000038 NOTE: doesn't obey syntax highlighting yet, thus
39 will stop at more places than what is highlighted.
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +000040
41 *[s*
42[s Move to next misspelled word before the cursor.
43 DOESN'T WORK YET!
44
Bram Moolenaar217ad922005-03-20 22:37:15 +000045
Bram Moolenaar6bb68362005-03-22 23:03:44 +000046PERFORMANCE
47
48Note that Vim does on-the-fly spellchecking. To make this work fast the
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +000049word list is loaded in memory. Thus this uses a lot of memory (1 Mbyte or
Bram Moolenaar6bb68362005-03-22 23:03:44 +000050more). There might also be a noticable delay when the word list is loaded,
51which happens when 'spelllang' is set. Each word list is only loaded once,
52they are not deleted when 'spelllang' is made empty. When 'encoding' is set
53the word lists are reloaded, thus you may notice a delay then too.
54
55
Bram Moolenaar217ad922005-03-20 22:37:15 +000056REGIONS
57
58A word may be spelled differently in various regions. For example, English
59comes in (at least) these variants:
60
61 en all regions
Bram Moolenaar5c5474b2005-04-19 21:40:26 +000062 en_au Australia
Bram Moolenaar217ad922005-03-20 22:37:15 +000063 en_ca Canada
Bram Moolenaar5c5474b2005-04-19 21:40:26 +000064 en_gb Great Britain
65 en_nz New Zealand
66 en_us USA
Bram Moolenaar217ad922005-03-20 22:37:15 +000067
68Words that are not used in one region but are used in another region are
69highlighted with SpellLocal.
70
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +000071Always use lowercase letters for the language and region names.
Bram Moolenaar217ad922005-03-20 22:37:15 +000072
73
74SPELL FILES
75
76Vim searches for spell files in the "spell" subdirectory of the directories in
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +000077'runtimepath'. The name is: LL-XXX.EEE.spl, where:
78 LL the language name
79 -XXX optional addition
80 EEE the value of 'encoding'
Bram Moolenaar217ad922005-03-20 22:37:15 +000081
Bram Moolenaar0e21a3f2005-04-17 20:28:32 +000082Exceptions:
83- Vim uses "latin1" when 'encoding' is "iso-8859-15". The euro sign doesn't
84 matter for spelling.
85- When no spell file for 'encoding' is found "ascii" is tried. This only
86 works for languages where nearly all words are ASCII, such as English. It
87 helps when 'encoding' is not "latin1", such as iso-8859-2, and English text
88 is being edited.
Bram Moolenaar217ad922005-03-20 22:37:15 +000089
Bram Moolenaar6bb68362005-03-22 23:03:44 +000090Spelling for EBCDIC is currently not supported.
91
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +000092A spell file might not be available in the current 'encoding'. See
93|spell-mkspell| about how to create a spell file. Converting a spell file
Bram Moolenaar0e21a3f2005-04-17 20:28:32 +000094with "iconv" will NOT work!
Bram Moolenaar217ad922005-03-20 22:37:15 +000095
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +000096 *E758* *E759*
97When loading a spell file Vim checks that it is properly formatted. If you
Bram Moolenaar0e21a3f2005-04-17 20:28:32 +000098get an error the file may be truncated, modified or intended for another Vim
99version.
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000100
Bram Moolenaar6bb68362005-03-22 23:03:44 +0000101
102WORDS
103
104Vim uses a fixed method to recognize a word. This is independent of
105'iskeyword', so that it also works in help files and for languages that
106include characters like '-' in 'iskeyword'. The word characters do depend on
107'encoding'.
108
109A word that starts with a digit is always ignored.
110
111
112SYNTAX HIGHLIGHTING
113
114Files that use syntax highlighting can specify where spell checking should be
115done:
116
117 everywhere default
118 in specific items use "contains=@Spell"
119 everywhere but specific items use "contains=@NoSpell"
120
121Note that mixing @Spell and @NoSpell doesn't make sense.
122
Bram Moolenaar217ad922005-03-20 22:37:15 +0000123==============================================================================
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001242. Generating a spell file *spell-mkspell*
Bram Moolenaar217ad922005-03-20 22:37:15 +0000125
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000126Vim uses a binary file format for spelling. This greatly speeds up loading
127the word list and keeps it small.
Bram Moolenaar217ad922005-03-20 22:37:15 +0000128
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000129You can create a Vim spell file from the .aff and .dic files that Myspell
130uses. Myspell is used by OpenOffice.org and Mozilla. You should be able to
131find them here:
132 http://lingucomponent.openoffice.org/spell_dic.html
Bram Moolenaar217ad922005-03-20 22:37:15 +0000133
Bram Moolenaar0e21a3f2005-04-17 20:28:32 +0000134:mksp[ell] [-ascii] {outname} {inname} ... *:mksp* *:mkspell*
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000135 Generate spell file {outname}.spl from Myspell files
136 {inname}.aff and {inname}.dic.
Bram Moolenaar0e21a3f2005-04-17 20:28:32 +0000137 When the [-ascii] argument is present, words with
138 non-ascii characters are skipped. The resulting file
139 ends in "ascii.spl". Otherwise the resulting file
140 ends in "ENC.spl", where ENC is the value of
141 'encoding'.
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000142 Multiple {inname} arguments can be given to combine
143 regions into one Vim spell file. Example: >
144 :mkspell ~/.vim/spell/en /tmp/en_US /tmp/en_CA /tmp/en_AU
145< This combines the English word lists for US, CA and AU
146 into one en.spl file.
147 Up to eight regions can be combined. *E754* *755*
Bram Moolenaar217ad922005-03-20 22:37:15 +0000148
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000149Since you might want to change the word list for use with Vim the following
150procedure is recommended:
Bram Moolenaar217ad922005-03-20 22:37:15 +0000151
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +00001521. Obtain the xx_YY.aff and xx_YY.dic files from Myspell.
1532. Make a copy of these files to xx_YY.orig.aff and xx_YY.orig.dic.
1543. Change the xx_YY.aff and xx_YY.dic files to remove bad words, add missing
155 words, etc.
1564. Use |:mkspell| to generate the Vim spell file and try it out.
Bram Moolenaar217ad922005-03-20 22:37:15 +0000157
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000158When the Myspell files are updated you can merge the differences:
1595. Obtain the new Myspell files as xx_YY.new.aff and xx_UU.new.dic.
1606. Use Vimdiff to see what changed: >
161 vimdiff xx_YY.orig.dic xx_YY.new.dic
1627. Take over the changes you like in xx_YY.dic.
163 You may also need to change xx_YY.aff.
1648. 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 +0000165
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000166==============================================================================
1679. Spell file format *spell-file-format*
Bram Moolenaar217ad922005-03-20 22:37:15 +0000168
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000169This is the format of the files that are used by the person who creates and
170maintains a word list.
Bram Moolenaar217ad922005-03-20 22:37:15 +0000171
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000172Note that we avoid the word "dictionary" here. That is because the goal of
173spell checking differs from writing a dictionary (as in the book). For
174spelling we need a list of words that are OK, thus need not to be highlighted.
175Names will not appear in a dictionary, but do appear in a word list. And
176some old words are rarely used and are common misspellings. These do appear
177in a dictionary but not in a word list.
Bram Moolenaar217ad922005-03-20 22:37:15 +0000178
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000179There are two files: the basic word list and an affix file. The affixes are
180used to modify the basic words to get the full word list. This significantly
181reduces the number of words, especially for a language like Polish. This is
182called affix compression.
Bram Moolenaar217ad922005-03-20 22:37:15 +0000183
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000184The format for the affix and word list files is mostly identical to what
185Myspell uses (the spell checker of Mozilla and OpenOffice.org). A description
186can be found here:
187 http://lingucomponent.openoffice.org/affix.readme ~
188Note that affixes are case sensitive, this isn't obvious from the description.
189Vim supports a few extras. Hopefully Myspell will support these too some day.
190See |spell-affix-vim|.
Bram Moolenaar217ad922005-03-20 22:37:15 +0000191
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000192The basic word list and the affix file are combined and turned into a binary
193spell file. All the preprocessing has been done, thus this file loads fast.
194The binary spell file format is described in the source code (src/spell.c).
195But only developers need to know about it.
196
197The preprocessing also allows us to take the Myspell language files and modify
198them before the Vim word list is made. The tools for this can be found in the
199"src/spell" directory.
200
201
202WORD LIST FORMAT *spell-wordlist-format*
203
204A very short example, with line numbers:
205
206 1 1234
207 2 aan
208 3 Als
209 4 Etten-Leur
210 5 et al.
211 6 's-Gravenhage
212 7 's-Gravenhaags
213 8 bedel/P
214 9 kado/1
215 10 cadeau/2
216
217The first line contains the number of words. Vim ignores it. *E760*
218
219What follows is one word per line. There should be no white space after the
220word.
221
222When the word only has lower-case letters it will also match with the word
223starting with an upper-case letter.
224
225When the word includes an upper-case letter, this means the upper-case letter
226is required at this position. The same word with a lower-case letter at this
227position will not match. When some of the other letters are upper-case it will
228not match either.
229
230The same word with all upper-case characters will always be OK.
231
232 word list matches does not match ~
233 als als Als ALS ALs AlS aLs aLS
234 Als Als ALS als ALs AlS aLs aLS
235 ALS ALS als Als ALs AlS aLs aLS
236 AlS AlS ALS als Als ALs aLs aLS
237
238Note in line 5 to 7 that non-word characters are used. You can include
239any character in a word. When checking the text a word still only matches
240when it appears with a non-word character before and after it. For Myspell a
241word starting with a non-word character probably won't work.
242
243After the word there is an optional slash and flags. Most of these flags are
244letters that indicate the affixes that can be used with this word.
245
246 *spell-affix-vim*
247A flag that Vim adds and is not in Myspell is the "=" flag. This has the
248meaning that case matters. This can be used if the word does not have the
249first letter in upper case at the start of a sentence. Example:
250
251 word list matches does not match ~
252 's morgens/= 's morgens 'S morgens 's Morgens
253 's Morgens 's Morgens 'S morgens 's morgens
254
255 *spell-affix-mbyte*
256The basic word list is normally in an 8-bit encoding, which is mentioned in
257the affix file. The affix file must always be in the same encoding as the
258word list. This is compatible with Myspell. For Vim the encoding may also be
259something else, any encoding that "iconv" supports. The "SET" line must
260specify the name of the encoding. When using a multi-byte encoding it's
261possible to use more different affixes.
262
263Performance hint: Although using affixes reduces the number of words, it
264reduces the speed. It's a good idea to put all the often used words in the
265word list with the affixes prepended/appended.
Bram Moolenaar217ad922005-03-20 22:37:15 +0000266
267
268 vim:tw=78:sw=4:ts=8:ft=help:norl: