fix(runtime)!: move "tohtml" to pack/dist/opt/ #34557

Problem:
The "tohtml" plugin is loaded by default.

Solution:
- Move it to `pack/dist/opt/nvim.tohtml/`, it is an "opt-in" plugin now.
- Document guidelines.
- Also revert the `plugin/` locations of `spellfile.lua` and `net.lua`.
  That idea was not worth the trouble, it will be too much re-education
  for too little gain.

runtime/doc/dev_arch.txt

@@ -51,17 +51,30 @@ LUA CODE
 Lua code lives in one of four places:
 
 1. Plugins! Not everything needs to live on `vim.*`. Plugins are the correct
-   model for non-essential features which the user may disable or replace with
+   model for non-essential functionality which (1) has "autoload" behavior,
-   a third-party plugin, and which do not have a formal API. Examples:
+   (2) the user may disable or replace with a third-party plugin, (3) is
-   "editorconfig", "comment".
+   primarily user-facing, not an API.
-   - "opt-out": `runtime/plugin/`
+   - "Opt-out" plugins (activated on startup): `runtime/plugin/`
-   - "opt-in": `runtime/pack/dist/opt/`
+   - "Opt-in" plugins (activated via `:packadd`): `runtime/pack/dist/opt/`
-2. `runtime/lua/vim/` (the runtime): Lazy-loaded modules. Examples: `treesitter`, `lpeg`.
+   - NOTE: New plugins should place Lua modules in the shared "nvim"
-3. `runtime/lua/vim/_core/shared.lua`: pure Lua functions which always are available.
+     namespace: `require('nvim.foo')`, not `require('foo')`.
-   Used in the test runner, and worker threads/processes launched from Nvim.
+   - Examples:
-4. `runtime/lua/vim/_core/`: Eager-loaded code which directly interacts with the Nvim
+     - ✅ spellfile `runtime/lua/nvim/spellfile.lua`
-   editor state. Only available in the main thread. See |dev-lua-builtin|
+     - ✅ tutor
-   below.
+   - Don't use these legacy plugins as examples (their modules should live
+     in `lua/nvim/x.lua`, not `lua/x.lua`):
+     - ❌ editorconfig.lua
+     - ❌ man.lua
+     - ❌ nvim.difftool
+     - ❌ nvim.tohtml
+     - ❌ nvim.undotree
+2. Runtime: `runtime/lua/vim/`. Lazy-loaded modules. Examples: `treesitter`, `lpeg`.
+3. Core: `runtime/lua/vim/_core/`. Compiled-into Nvim binary, may directly
+   interact with Nvim internals. Only available in the main thread. See
+   |dev-lua-builtin| below.
+4. "Shared" core: `runtime/lua/vim/_core/shared.lua`. Pure Lua functions which
+   always are available. Used in the test runner, and worker threads/processes
+   launched from Nvim.
 
 The top-level `vim.` namespace is for fundamental Lua and editor features. Use
 submodules (`vim.foo`) for everything else (but avoid excessive "nesting"), or

runtime/doc/news.txt

@@ -124,6 +124,8 @@ OPTIONS
 PLUGINS
 
 • Removed "shellmenu" plugin, an old menu-based quasi-snippet plugin for shell scripts.
+• |tohtml| is now an "opt-in" plugin. Use |:packadd| to activate it: >
+  :packadd nvim.tohtml
 
 TREESITTER
 

runtime/doc/plugins.txt

@@ -50,8 +50,9 @@ Compares two directories or files side-by-side.
 Supports directory diffing, rename detection, and highlights changes
 in quickfix list. Replaces the built-in `nvim -d` diff mode with this interface.
 
-The plugin is not loaded by default; use `:packadd nvim.difftool` before
+The plugin is not loaded by default; use `:packadd` to activate it: >
-invoking `:DiffTool`.
+    :packadd nvim.difftool
+<
 
 Example `git difftool -d` integration using `nvim -d` replacement: >ini
     [difftool "nvim_difftool"]
@@ -240,6 +241,10 @@ Converts the buffer shown in the current window to HTML, opens the generated
 HTML in a new split window, and saves its contents to {file}. If {file} is not
 given, a temporary file (created by |tempname()|) is used.
 
+The plugin is not loaded by default; use `:packadd` to activate it: >
+    :packadd nvim.tohtml
+<
+
 
 tohtml({winid}, {opt})                                       *tohtml.tohtml()*
     Converts the buffer shown in the window {winid} to HTML and returns the
@@ -268,18 +273,16 @@ tohtml({winid}, {opt})                                       *tohtml.tohtml()*
 Builtin plugin: undotree                                     *undotree-plugin*
 
 open({opts})                                                 *undotree.open()*
-    Open a window that displays a textual representation of the |undo-tree|.
+    Open a window that displays a textual representation of the |undo-tree|,
+    or closes the window if it is already open. Can also be shown with
+    `:Undotree`.                                                   *:Undotree*
 
     While in the window, moving the cursor changes the undo.
 
-    Closes the window if it is already open
+    The plugin is not loaded by default; use `:packadd` to activate it: >
-
+        :packadd nvim.undotree
-    Load the plugin with this command: >
-                packadd nvim.undotree
 <
 
-    Can also be shown with `:Undotree`.                            *:Undotree*
-
     Parameters: ~
       • {opts}  (`table?`) A table with the following fields:
                 • {bufnr} (`integer?`) Buffer to draw the tree into. If

runtime/pack/dist/opt/nvim.difftool/lua/difftool.lua

@@ -6,7 +6,10 @@
 ---in quickfix list. Replaces the built-in `nvim -d` diff mode with this interface.
 ---</pre>
 ---
---- The plugin is not loaded by default; use `:packadd nvim.difftool` before invoking `:DiffTool`.
+--- The plugin is not loaded by default; use `:packadd` to activate it:
+--- ```
+--- :packadd nvim.difftool
+--- ```
 ---
 --- Example `git difftool -d` integration using `nvim -d` replacement:
 ---

runtime/pack/dist/opt/nvim.tohtml/lua/tohtml.lua

@@ -5,15 +5,19 @@
 ---HTML in a new split window, and saves its contents to {file}. If {file} is not
 ---given, a temporary file (created by |tempname()|) is used.
 ---</pre>
+---
+--- The plugin is not loaded by default; use `:packadd` to activate it:
+--- ```
+--- :packadd nvim.tohtml
+--- ```
 
--- The HTML conversion script is different from Vim's one. If you want to use
+-- This HTML conversion script is different from Vim's. If you want to use Vim's TOhtml converter,
--- Vim's TOhtml converter, download it from the vim GitHub repo.
+-- download the related files from the Vim repo:
--- Here are the Vim files related to this functionality:
 -- - https://github.com/vim/vim/blob/master/runtime/syntax/2html.vim
 -- - https://github.com/vim/vim/blob/master/runtime/autoload/tohtml.vim
 -- - https://github.com/vim/vim/blob/master/runtime/plugin/tohtml.vim
 --
--- Main differences between this and the vim version:
+-- Main differences between this and the Vim version:
 -- - No "ignore some visual thing" settings (just set the right Vim option)
 -- - No support for legacy web engines
 -- - No support for legacy encoding (supports only UTF-8)

runtime/pack/dist/opt/nvim.undotree/lua/undotree.lua

@@ -294,19 +294,16 @@ end
 --- source buffer as its only argument and should return a string.
 --- @field title (string|fun(bufnr:integer):string|nil)?
 
---- Open a window that displays a textual representation of the [undo-tree].
+--- Open a window that displays a textual representation of the [undo-tree], or closes the window if
+--- it is already open. Can also be shown with `:Undotree`. [:Undotree]()
 ---
 --- While in the window, moving the cursor changes the undo.
 ---
---- Closes the window if it is already open
+--- The plugin is not loaded by default; use `:packadd` to activate it:
----
---- Load the plugin with this command:
 --- ```
----         packadd nvim.undotree
+--- :packadd nvim.undotree
 --- ```
 ---
---- Can also be shown with `:Undotree`. [:Undotree]()
----
 --- @param opts vim.undotree.opts?
 --- @return boolean? Returns true if the window was already open, nil otherwise
 function M.open(opts)

src/gen/gen_vimdoc.lua

@@ -431,7 +431,7 @@ local config = {
     },
     files = {
       'runtime/lua/editorconfig.lua',
-      'runtime/lua/tohtml.lua',
+      'runtime/pack/dist/opt/nvim.tohtml/lua/tohtml.lua',
       'runtime/pack/dist/opt/nvim.undotree/lua/undotree.lua',
       'runtime/pack/dist/opt/nvim.difftool/lua/difftool.lua',
       'runtime/lua/nvim/spellfile.lua',
@@ -793,6 +793,10 @@ local function render_fun(fun, classes, cfg)
     return
   end
 
+  if not fun.name then
+    error(('fun.name is nil, check fn_xform(). fun: %s'):format(vim.inspect(fun)))
+  end
+
   if vim.startswith(fun.name, '_') or fun.name:find('[:.]_') then
     return
   end
@@ -997,6 +1001,10 @@ end
 local function render_section(section, add_header)
   local doc = {} --- @type string[]
 
+  if not section.title then
+    error(('section.title is nil, check section_fmt(). section: %s'):format(vim.inspect(section)))
+  end
+
   if add_header ~= false then
     vim.list_extend(doc, {
       string.rep('=', TEXT_WIDTH),

test/functional/plugin/tohtml_spec.lua

@@ -186,6 +186,7 @@ describe(':TOhtml', function()
   local screen
   before_each(function()
     clear({ args = { '--clean' } })
+    n.command('packadd nvim.tohtml')
     screen = Screen.new(80, 80, { term_name = 'xterm' })
     exec('colorscheme default')
   end)