refactor(spellfile): config() interface, docs #36481

Problem:
- Exposing the raw config as table is a pattern not seen anywhere else
  in the Nvim codebase.
- Old spellfile.vim docs still available, no new documentation

Solution:
- Exposing a `config()` function that both acts as "getter" and "setter"
  is a much more common idiom (e.g. vim.lsp, vim.diagnostic).
- Add new documentation and link old docs to |spellfile.lua| instead of
  |spellfile.vim|.

runtime/doc/options.txt

@@ -6107,7 +6107,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 	encoding is used, Vim doesn't check it.
 	How the related spell files are found is explained here: |spell-load|.
 
-	If the |spellfile.vim| plugin is active and you use a language name
+	If the |spellfile.lua| plugin is active and you use a language name
 	for which Vim cannot find the .spl file in 'runtimepath' the plugin
 	will ask you if you want to download the file.
 

runtime/doc/plugins.txt

@@ -16,7 +16,7 @@ loaded by default while others are not loaded until requested by |:packadd|.
 
 ==============================================================================
 Standard plugins ~
-						*standard-plugin-list*
+                                                        *standard-plugin-list*
 Help-link		Loaded	Short description ~
 |difftool|		No	Compares two directories or files side-by-side
 |editorconfig|		Yes	Detect and interpret editorconfig
@@ -37,7 +37,7 @@ Help-link		Loaded	Short description ~
 |pi_tar.txt|		Yes	Tar file explorer
 |pi_tutor.txt|		Yes	Interactive tutorial
 |pi_zip.txt|		Yes	Zip archive explorer
-|spellfile.vim|		Yes	Install spellfile if missing
+|spellfile.lua|		Yes	Install spellfile if missing
 |tohtml|		Yes	Convert buffer to html, syntax included
 |undotree|		No	Interactive textual undotree
 
@@ -166,6 +166,54 @@ trim_trailing_whitespace               *editorconfig.trim_trailing_whitespace*
     buffer is written.
 
 
+==============================================================================
+Builtin plugin: spellfile                                      *spellfile.lua*
+
+Asks the user to download missing spellfiles. The spellfile is written to
+`stdpath('data') .. 'site/spell'` or the first writable directory in the
+'runtimepath'.
+
+The plugin can be disabled by setting `g:loaded_spellfile_plugin = 1`.
+
+
+*nvim.spellfile.Opts*
+    A table with the following fields:
+
+    Fields: ~
+      • {url}         (`string`) The base URL from where the spellfiles are
+                      downloaded. Uses `g:spellfile_URL` if it's set,
+                      otherwise https://ftp.nluug.nl/pub/vim/runtime/spell.
+      • {timeout_ms}  (`integer`, default: 15000) Number of milliseconds after
+                      which the |vim.net.request()| times out.
+
+
+config({opts})                                            *spellfile.config()*
+    Configure spellfile download options. For example: >lua
+        require('nvim.spellfile').config({ url = '...' })
+<
+
+    Parameters: ~
+      • {opts}  (`nvim.spellfile.Opts?`) When omitted or `nil`, retrieve the
+                current configuration. Otherwise, a configuration table.
+
+    Return: ~
+        (`nvim.spellfile.Opts?`) Current config if {opts} is omitted.
+
+get({lang})                                                  *spellfile.get()*
+    Download spellfiles for language {lang} if available.
+
+    Parameters: ~
+      • {lang}  (`string`) Language code.
+
+    Return: ~
+        (`table?`) A table with the following fields:
+        • {files} (`string[]`)
+        • {key} (`string`)
+        • {lang} (`string`)
+        • {encoding} (`string`)
+        • {dir} (`string`)
+
+
 ==============================================================================
 Builtin plugin: tohtml                                                *tohtml*
 

runtime/doc/spell.txt

@@ -313,10 +313,6 @@ Only the first file is loaded, the one that is first in 'runtimepath'.  If
 this succeeds then additionally files with the name LL.EEE.add.spl are loaded.
 All the ones that are found are used.
 
-If no spell file is found the |SpellFileMissing| autocommand event is
-triggered.  This may trigger the |spellfile.vim| plugin to offer you
-downloading the spell file.
-
 Additionally, the files related to the names in 'spellfile' are loaded.  These
 are the files that |zg| and |zw| add good and wrong words to.
 
@@ -640,48 +636,11 @@ Comment lines with the name of the .spl file are used as a header above the
 words that were generated from that .spl file.
 
 
-SPELL FILE MISSING		*spell-SpellFileMissing* *spellfile.vim*
+SPELL FILE MISSING				    *spell-SpellFileMissing*
 
-If the spell file for the language you are using is not available, you will
-get an error message.  But if the "spellfile.vim" plugin is active it will
-offer you to download the spell file.  Just follow the instructions, it will
-ask you where to write the file (there must be a writable directory in
-'runtimepath' for this).
+If a spell file is missing, the user is asked whether to download it. See
+|spellfile.lua|.
 
-The plugin has a default place where to look for spell files, on the Vim ftp
-server.  The protocol used is TLS (`https://`) for security.  If you want to
-use another location or another protocol, set the g:spellfile_URL variable to
-the directory that holds the spell files.  You can use `http://` or `ftp://`,
-but you are taking a security risk then.  The |netrw| plugin is used for
-getting the file, look there for the specific syntax of the URL.  Example: >
-	let g:spellfile_URL = 'https://ftp.nluug.nl/vim/runtime/spell'
-You may need to escape special characters.
-
-The plugin will only ask about downloading a language once.  If you want to
-try again anyway restart Vim, or set g:spellfile_URL to another value (e.g.,
-prepend a space).
-
-To avoid using the "spellfile.vim" plugin do this in your vimrc file: >
-
-	let loaded_spellfile_plugin = 1
-
-Instead of using the plugin you can define a |SpellFileMissing| autocommand to
-handle the missing file yourself.  You can use it like this: >
-
-	:au SpellFileMissing * call Download_spell_file(expand('<amatch>'))
-
-Thus the <amatch> item contains the name of the language.  Another important
-value is 'encoding', since every encoding has its own spell file.  With two
-exceptions:
-- For ISO-8859-15 (latin9) the name "latin1" is used (the encodings only
-  differ in characters not used in dictionary words).
-- The name "ascii" may also be used for some languages where the words use
-  only ASCII letters for most of the words.
-
-The default "spellfile.vim" plugin uses this autocommand, if you define your
-autocommand afterwards you may want to use ":au! SpellFileMissing" to overrule
-it.  If you define your autocommand before the plugin is loaded it will notice
-this and not do anything.
 							*E797*
 Note that the SpellFileMissing autocommand must not change or destroy the
 buffer the user was editing.

runtime/doc/vim_diff.txt

@@ -97,6 +97,8 @@ Defaults                                            *defaults* *nvim-defaults*
 - |man.lua| plugin is enabled, so |:Man| is available by default.
 - |matchit| plugin is enabled. To disable it in your config: >vim
     :let loaded_matchit = 1
+- |spellfile.lua| plugin is enabled, spellfiles are installed by default if
+  missing.
 
 - |g:vimsyn_embed| defaults to "l" to enable Lua highlighting
 
@@ -741,6 +743,7 @@ Editor:
 - *cscope* support was removed in favour of plugin-based solutions such as:
   https://github.com/dhananjaylatkar/cscope_maps.nvim
 - *popup-window* : Use |floating-windows| instead.
+- *spellfile.vim* : Replaced by |spellfile.lua|.
 - *textprop* : Use |extmarks| instead.
 
 Eval: