How can I use multiple spell files at the same time?

Question

Based upon documentation there is explicitly a way to have multiple spell file for "spell" but I cannot, for the life of me, figure out how to use more than one spell file at the same time.

Under my current configuration I have two spell files, but I am unsure of how I got them. The first is, of course, the master spelling file for English, and the second is my custom words. I assume the custom word file was created upon my first instance of designating a word correct (pressing "zg"), and that seems to be indicated in the documentation.

What I would ideally like is to have four total spell files, configured as follows:

1. the master "English" file with all of the standard English words.
2. a second "custom" file which are for all the words that I use regularly, and are common across all file types.
3. a file type specific spell file for words that I only use in certain files (e.g. tex, md etc.)
4. a file for each individual document, for words that I only want registered as correct in that document.

I have the first two as it stands, and that seems to be the default. Based upon documentation it seems like the 4th should be possible as well, as the documentation seems to indicate that, at least for some versions of vim, the spell file would be contained in the same directory as the file in the buffer if not explicitly located elsewhere in .vimrc.

If this seems overly complicated, the logic is as follows. The need for files 1 and 2 are to keep from corrupting the English language by accidentally changing a standard spelling (which is probably why it is the default). File type 3 is so that I can put in custom commands that I will normally only use for certain file types, but I do not want those accidentally marked as good in other file types, when they would not be appropriate there. Finally, in each file I have words (usually names) which are correct within that file, and only that file, but which might be wrong elsewhere.

Any guidance is welcome.

Answer 1

Vim finds the file you're referring to as the "master" file by searching for files with a particular naming scheme in the spell subdirectory within the paths specified by your runtimepath. (See :help spell-load) This is already working in your setup, though, so you don't need to worry about it.

You can then have as many additional files as you like by specifying the 'spellfile' option as a comma-separated list: in your case, you would have three values: the first for your global custom list, the second for a filetype based list, and the third for per-file spellings.

You could try adding something like the following to your .vimrc:

" Global spellfile
set spellfile=~/.vim/custom.utf-8.add

augroup spellfiles
  autocmd!
  " Per file spellfile
  autocmd BufNewFile,BufRead * let &l:spellfile .= ',' . expand('%:p:h') . '/.' .
  \ expand('%:t') . '.utf-8.add,'

  " Per file type spellfile (FileType autocmd seems to fire before BufNewFile)
  autocmd BufNewFile,BufRead *.markdown setlocal spellfile+=~/.vim/markdown.utf-8.add
augroup END

This sets up the three 'spellfile' files in the order:

1. Global "custom" spell file
2. Per file spell file
3. Per file type spell file

Then you just need to specify which file you want to add corrections to, by passing a count to the various spell commands, e.g. to add a word to the "markdown" file type spellfile, you'd use the command: 3zg

(The slightly odd ordering is because the file type spellfile may not always exist, and so must go last in order that the per-file spellfile always be in the same position.)