From 59eadebe335f54f8cdd6cefe25d9fa00daf01371 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Mon, 23 Mar 2026 06:41:00 -0400 Subject: [PATCH] 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 | 35 +++++++++++++------ runtime/doc/news.txt | 2 ++ runtime/doc/plugins.txt | 21 ++++++----- .../dist/opt/nvim.difftool/lua/difftool.lua | 5 ++- .../dist/opt/nvim.tohtml}/lua/tohtml.lua | 12 ++++--- .../dist/opt/nvim.tohtml}/plugin/tohtml.lua | 0 .../dist/opt/nvim.undotree/lua/undotree.lua | 11 +++--- runtime/plugin/{nvim => }/net.lua | 0 runtime/plugin/{nvim => }/spellfile.lua | 0 src/gen/gen_vimdoc.lua | 10 +++++- test/functional/plugin/tohtml_spec.lua | 1 + 11 files changed, 64 insertions(+), 33 deletions(-) rename runtime/{ => pack/dist/opt/nvim.tohtml}/lua/tohtml.lua (99%) rename runtime/{ => pack/dist/opt/nvim.tohtml}/plugin/tohtml.lua (100%) rename runtime/plugin/{nvim => }/net.lua (100%) rename runtime/plugin/{nvim => }/spellfile.lua (100%) diff --git a/runtime/doc/dev_arch.txt b/runtime/doc/dev_arch.txt index e8aee5e7bb..ee6939ed44 100644 --- a/runtime/doc/dev_arch.txt +++ b/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 - a third-party plugin, and which do not have a formal API. Examples: - "editorconfig", "comment". - - "opt-out": `runtime/plugin/` - - "opt-in": `runtime/pack/dist/opt/` -2. `runtime/lua/vim/` (the runtime): Lazy-loaded modules. Examples: `treesitter`, `lpeg`. -3. `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. -4. `runtime/lua/vim/_core/`: Eager-loaded code which directly interacts with the Nvim - editor state. Only available in the main thread. See |dev-lua-builtin| - below. + model for non-essential functionality which (1) has "autoload" behavior, + (2) the user may disable or replace with a third-party plugin, (3) is + primarily user-facing, not an API. + - "Opt-out" plugins (activated on startup): `runtime/plugin/` + - "Opt-in" plugins (activated via `:packadd`): `runtime/pack/dist/opt/` + - NOTE: New plugins should place Lua modules in the shared "nvim" + namespace: `require('nvim.foo')`, not `require('foo')`. + - Examples: + - ✅ spellfile `runtime/lua/nvim/spellfile.lua` + - ✅ tutor + - 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 diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index 033c434f1a..c4f7a08f80 100644 --- a/runtime/doc/news.txt +++ b/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 diff --git a/runtime/doc/plugins.txt b/runtime/doc/plugins.txt index e6c34984b6..e36fd7f8ec 100644 --- a/runtime/doc/plugins.txt +++ b/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 -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: >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 - - Load the plugin with this command: > - packadd nvim.undotree + The plugin is not loaded by default; use `:packadd` to activate it: > + :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 diff --git a/runtime/pack/dist/opt/nvim.difftool/lua/difftool.lua b/runtime/pack/dist/opt/nvim.difftool/lua/difftool.lua index 1de4f77d93..b916dd1d32 100644 --- a/runtime/pack/dist/opt/nvim.difftool/lua/difftool.lua +++ b/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. --- --- ---- 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: --- diff --git a/runtime/lua/tohtml.lua b/runtime/pack/dist/opt/nvim.tohtml/lua/tohtml.lua similarity index 99% rename from runtime/lua/tohtml.lua rename to runtime/pack/dist/opt/nvim.tohtml/lua/tohtml.lua index 464ac1c6ad..035199f674 100644 --- a/runtime/lua/tohtml.lua +++ b/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. --- +--- +--- 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 --- Vim's TOhtml converter, download it from the vim GitHub repo. --- Here are the Vim files related to this functionality: +-- This HTML conversion script is different from Vim's. If you want to use Vim's TOhtml converter, +-- download the related files from the Vim repo: -- - 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) diff --git a/runtime/plugin/tohtml.lua b/runtime/pack/dist/opt/nvim.tohtml/plugin/tohtml.lua similarity index 100% rename from runtime/plugin/tohtml.lua rename to runtime/pack/dist/opt/nvim.tohtml/plugin/tohtml.lua diff --git a/runtime/pack/dist/opt/nvim.undotree/lua/undotree.lua b/runtime/pack/dist/opt/nvim.undotree/lua/undotree.lua index 38f107e615..658a90337d 100644 --- a/runtime/pack/dist/opt/nvim.undotree/lua/undotree.lua +++ b/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 ---- ---- Load the plugin with this command: +--- The plugin is not loaded by default; use `:packadd` to activate it: --- ``` ---- 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) diff --git a/runtime/plugin/nvim/net.lua b/runtime/plugin/net.lua similarity index 100% rename from runtime/plugin/nvim/net.lua rename to runtime/plugin/net.lua diff --git a/runtime/plugin/nvim/spellfile.lua b/runtime/plugin/spellfile.lua similarity index 100% rename from runtime/plugin/nvim/spellfile.lua rename to runtime/plugin/spellfile.lua diff --git a/src/gen/gen_vimdoc.lua b/src/gen/gen_vimdoc.lua index 1d426a664b..2db5b85b1d 100755 --- a/src/gen/gen_vimdoc.lua +++ b/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), diff --git a/test/functional/plugin/tohtml_spec.lua b/test/functional/plugin/tohtml_spec.lua index 0b0b2de097..f677392234 100644 --- a/test/functional/plugin/tohtml_spec.lua +++ b/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)