mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2026-05-23 21:30:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

refactor(docs): generate tui.txt $NVIM_TERMDEFS keys #39836

Browse Source 
Problem:
Potential documentation drift in `tui.txt` if fields for
`$NVIM_TERMDEFS` change.

Solution:
Generate docs for `tui.txt`. Add `brief_xform` to `gen_vimdoc.lua` to
allow transforming briefs during generation.
This commit is contained in:
Kyle
2026-05-21 03:39:45 -05:00
committed by GitHub
parent a952575c3b
commit 7337e02563
10 changed files with 213 additions and 110 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
runtime/doc/api.txt
View File

@@ -2311,7 +2311,6 @@ nvim_get_autocmds({opts}) *nvim_get_autocmds()*
==============================================================================
Buffer Functions *api-buffer*
For more information on buffers, see |buffers|.
Unloaded Buffers: ~

4
runtime/doc/health.txt
View File

@@ -7,7 +7,7 @@
Type |gO| to see the table of contents.
==============================================================================
Checkhealth *vim.health* *health*
Checkhealth *vim.health* *health*
vim.health is a minimal framework to help users troubleshoot configuration and
any other environment conditions that a plugin might care about. Nvim ships
@@ -20,7 +20,6 @@ To run all healthchecks, use: >vim
Plugin authors are encouraged to write new healthchecks. |health-dev|
COMMANDS *health-commands*
*:che* *:checkhealth*
@@ -73,7 +72,6 @@ in the health report: >vim
autocmd FileType checkhealth :set modifiable | silent! %s/\v( ?[^\x00-\x7F])//g
<
--------------------------------------------------------------------------------
Create a healthcheck *health-dev*

6
runtime/doc/lua.txt
View File

@@ -596,11 +596,9 @@ A subset of the `vim.*` stdlib is available in threads, including:
`vim.split`, `vim.tbl_*`, `vim.list_*`, etc.
- `vim.is_thread()` returns true from a non-main thread.
==============================================================================
VIM *vim.builtin*
vim.api.{func}({...}) *vim.api*
Invokes Nvim |API| function {func} with arguments {...}.
Example: call the "nvim_get_current_line()" API function: >lua
@@ -868,7 +866,6 @@ Lua list copies the list object to Vimscript and does NOT modify the Lua list: >
vim.print(list) --> "{ 1, 2, 3 }"
<
vim.call({func}, {...}) *vim.call()*
Invokes |vim-function| or |user-function| {func} with arguments {...}.
See also |vim.fn|.
@@ -947,7 +944,6 @@ vim.v *vim.v*
|v:| variables.
Invalid or unset key returns `nil`.
*lua-options*
*lua-vim-options*
*lua-vim-set*
@@ -971,7 +967,6 @@ window-scoped options. Note that this must NOT be confused with
|local-options| and |:setlocal|. There is also |vim.go| that only accesses the
global value of a |global-local| option, see |:setglobal|.
*vim.opt_local*
*vim.opt_global*
*vim.opt*
@@ -3964,7 +3959,6 @@ set_level({log}, {level}) *vim.log.set_level()*
==============================================================================
Lua module: vim.lpeg *vim.lpeg*
LPeg is a pattern-matching library for Lua, based on Parsing Expression
Grammars (PEGs). https://bford.info/packrat/

1
runtime/doc/pack.txt
View File

@@ -355,7 +355,6 @@ Check for pending updates ~
with different `rev` and `rev_to` fields. To not download new updates from
source, use plain `vim.pack.get()`.
Commands *vim.pack-commands* *E5807*
*:packu* *:packupdate* *E5808*

2
runtime/doc/plugins.txt
View File

@@ -44,7 +44,6 @@ Help-link Loaded Short description ~
==============================================================================
Builtin plugin: difftool *difftool*
:DiffTool {left} {right} *:DiffTool*
Compares two directories or files side-by-side.
Supports directory diffing, rename detection, and highlights changes
@@ -235,7 +234,6 @@ get({lang}) *spellfile.get()*
==============================================================================
Builtin plugin: tohtml *package-tohtml*
:[range]TOhtml {file} *:TOhtml*
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

4
runtime/doc/treesitter.txt
View File

@@ -657,7 +657,7 @@ The earliest parser ABI version that is supported by the bundled treesitter
library.
==============================================================================
TREESITTER TREES *treesitter-tree* *TSTree*
TREESITTER TREES *treesitter-tree* *TSTree*
A "treesitter tree" represents the parsed contents of a buffer, which can be
used to perform further analysis. It is a |userdata| reference to an object
@@ -680,7 +680,7 @@ TSTree:root() *TSTree:root()*
==============================================================================
TREESITTER NODES *treesitter-node* *TSNode*
TREESITTER NODES *treesitter-node* *TSNode*
A "treesitter node" represents one specific element of the parsed contents of
a buffer, which can be captured by a |treesitter-query| for, e.g.,

182
runtime/doc/tui.txt
View File

@@ -69,94 +69,7 @@ style" sequence, and set the <Home> and <S-Home> sequences: >
}' nvim
<
Be careful when putting escape sequences in strings, as JSON uses unicode
escapes like `\u001b`. The following fields are supported. For fields of type
`string[]`, the first entry is the unshifted variant of the key, and the
second entry is the shifted variant.
>
Field Type
------------------------------------------------------------
carriage_return string
change_scroll_region string
clear_screen string
clr_eol string
clr_eos string
cursor_address string
cursor_down string
cursor_home string
cursor_invisible string
cursor_left string
cursor_normal string
cursor_right string
cursor_up string
delete_line string
enter_blink_mode string
enter_bold_mode string
enter_ca_mode string
enter_dim_mode string
enter_italics_mode string
enter_reverse_mode string
enter_secure_mode string
enter_standout_mode string
enter_underline_mode string
erase_chars string
exit_attribute_mode string
exit_ca_mode string
from_status_line string
insert_line string
keypad_local string
keypad_xmit string
parm_delete_line string
parm_down_cursor string
parm_insert_line string
parm_left_cursor string
parm_right_cursor string
parm_up_cursor string
set_a_background string
set_a_foreground string
set_attributes string
set_lr_margin string
to_status_line string
enter_strikethrough_mode string
reset_cursor_color string
reset_cursor_style string
set_cursor_color string
set_cursor_style string
set_rgb_background string
set_rgb_foreground string
set_underline_style string
key_backspace string
key_btab string
key_clear string
key_npage string
key_ppage string
key_select string
key_beg string[]
key_dc string[]
key_end string[]
key_find string[]
key_home string[]
key_ic string[]
key_left string[]
key_right string[]
key_suspend string[]
key_undo string[]
key_f1 string
...
key_f63 string
RGB bool
Su bool
Tc bool
back_color_erase bool
columns int
lines int
max_colors int
<
escapes like `\u001b`. For all available fields, see |tui-termdefs|.
*$TERM*
The $TERM environment variable must match the terminal you are using!
@@ -394,5 +307,96 @@ colours of whitespace are immaterial, in practice they change the colours of
cursors and selections that cross them. This may have a visible, but minor,
effect on some UIs.
==============================================================================
Terminfo override *tui-termdefs*
vim:et:sw=2:tw=78:ts=8:ft=help:norl:
Below are the available fields in |$NVIM_TERMDEFS|. For keys of type `string[]`,
the first entry is the unshifted variant of the key, and the second entry is
the shifted variant. >
Field Type
-----------------------------------
RGB bool
Su bool
Tc bool
back_color_erase bool
columns int
lines int
max_colors int
carriage_return string
change_scroll_region string
clear_screen string
clr_eol string
clr_eos string
cursor_address string
cursor_down string
cursor_home string
cursor_invisible string
cursor_left string
cursor_normal string
cursor_right string
cursor_up string
delete_line string
enter_blink_mode string
enter_bold_mode string
enter_ca_mode string
enter_dim_mode string
enter_italics_mode string
enter_reverse_mode string
enter_secure_mode string
enter_standout_mode string
enter_underline_mode string
erase_chars string
exit_attribute_mode string
exit_ca_mode string
from_status_line string
insert_line string
keypad_local string
keypad_xmit string
parm_delete_line string
parm_down_cursor string
parm_insert_line string
parm_left_cursor string
parm_right_cursor string
parm_up_cursor string
set_a_background string
set_a_foreground string
set_attributes string
set_lr_margin string
to_status_line string
enter_strikethrough_mode string
reset_cursor_color string
reset_cursor_style string
set_cursor_color string
set_cursor_style string
set_rgb_background string
set_rgb_foreground string
set_underline_style string
key_backspace string
key_btab string
key_clear string
key_npage string
key_ppage string
key_select string
key_beg string[]
key_dc string[]
key_end string[]
key_find string[]
key_home string[]
key_ic string[]
key_left string[]
key_right string[]
key_suspend string[]
key_undo string[]
key_f1 string
... string
key_f63 string
<
vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:

11
runtime/lua/vim/_meta/tui.lua Normal file
View File

@@ -0,0 +1,11 @@
--- @meta
-- This file is NOT generated, edit it directly.
error('Cannot require a meta file')
--- @brief <pre>help
--- Below are the available fields in |$NVIM_TERMDEFS|. For keys of type `string[]`,
--- the first entry is the unshifted variant of the key, and the second entry is
--- the shifted variant. >
---
--- NVIM_TERMDEFS_TABLE
--- <

106
src/gen/gen_vimdoc.lua
View File

@@ -28,6 +28,7 @@ local fmt = string.format
local wrap = util.wrap
local md_to_vimdoc = util.md_to_vimdoc
local align_tags = util.align_tags
local TEXT_WIDTH = 78
local INDENTATION = 4
@@ -49,6 +50,8 @@ local INDENTATION = 4
---
--- @field fn_xform? fun(fun: nvim.luacats.parser.fun)
---
--- @field brief_xform? fun(brief: string): string
---
--- For generated section names.
--- @field section_fmt fun(name: string): string
---
@@ -477,6 +480,89 @@ local config = {
return name
end,
},
tui = {
filename = 'tui.txt',
section_order = { 'tui.lua' },
files = { 'runtime/lua/vim/_meta/tui.lua' },
section_fmt = function(_name)
return 'Terminfo override'
end,
helptag_fmt = function()
return { 'tui-termdefs' }
end,
brief_xform = function(brief)
local terminfo = require('src.gen.terminfo').fields
local booleans = terminfo.bools
local numbers = terminfo.ints
local strings = terminfo.strings
local strings_ext = vim.tbl_map(function(v)
return v[1]
end, terminfo.strings_ext)
local unshifted_keys = vim.tbl_map(function(v)
return 'key_' .. v[1]
end, (vim.tbl_filter(function(v)
return not v[2]
end, terminfo.termkeys)))
local shifted_keys = vim.tbl_map(function(v)
return 'key_' .. v[1]
end, (vim.tbl_filter(function(v)
return v[2]
end, terminfo.termkeys)))
local f_keys = { 'key_f1', '...', 'key_f' .. terminfo.func_key_max }
local table_rows = { { 'Field', 'Type' } }
local col1_max_width = 0
--- @param defs string[]
--- @param type string
--- @param omit_padding_row nil | boolean
--- @param skip_sort nil | boolean
local function add_defs(defs, type, omit_padding_row, skip_sort)
if not skip_sort then
table.sort(defs)
end
for _, def in ipairs(defs) do
table.insert(table_rows, { def, type })
col1_max_width = math.max(col1_max_width, #def)
end
if not omit_padding_row then
table.insert(table_rows, { '', '' })
end
end
add_defs(booleans, 'bool')
add_defs(numbers, 'int')
add_defs(strings, 'string')
add_defs(strings_ext, 'string')
add_defs(unshifted_keys, 'string')
add_defs(shifted_keys, 'string[]')
add_defs(f_keys, 'string', true, true)
-- Convert all the table rows into strings by calculating the padding
-- needed between them
local table_str_rows = {}
local min_padding = 3 -- padding between table columns
local max_width = 0 -- max width of col1 + padding + col2
local indent = ' '
for _, row in ipairs(table_rows) do
if #row[1] == 0 then
table.insert(table_str_rows, '')
else
local padding = string.rep(' ', col1_max_width + min_padding - #row[1])
local val = table.concat(row, padding)
max_width = math.max(max_width, #val)
table.insert(table_str_rows, indent .. val)
end
end
-- Add table header
table.insert(table_str_rows, 2, indent .. string.rep('-', max_width))
return (brief:gsub('NVIM_TERMDEFS_TABLE', table.concat(table_str_rows, '\n')))
end,
},
}
--- @param ty string
@@ -939,6 +1025,21 @@ local function render_fun(fun, classes, cfg)
return table.concat(ret)
end
--- @param briefs string[]
--- @param cfg nvim.gen_vimdoc.Config
local function render_briefs(briefs, cfg)
local ret = {} --- @type string[]
for _, b in ipairs(briefs) do
if cfg.brief_xform then
b = cfg.brief_xform(b)
end
ret[#ret + 1] = b
end
return ret
end
--- @param funs nvim.luacats.parser.fun[]
--- @param classes table<string,nvim.luacats.parser.class>
--- @param cfg nvim.gen_vimdoc.Config
@@ -1063,8 +1164,7 @@ local function render_section(section, add_header)
vim.list_extend(doc, {
string.rep('=', TEXT_WIDTH),
'\n',
section.title,
fmt('%' .. (TEXT_WIDTH - section.title:len()) .. 's', section.help_tag),
align_tags(TEXT_WIDTH)(section.title .. ' ' .. section.help_tag),
})
end
@@ -1173,7 +1273,7 @@ local function gen_target(cfg)
sections[f_base] = make_section(
f_base,
cfg,
briefs,
render_briefs(briefs, cfg),
render_funs(funs, all_classes, cfg),
render_classes(classes, funs, cfg)
)

6
src/gen/util.lua
View File

@@ -311,7 +311,7 @@ local function render_md(node, start_indent, indent, text_width, level, is_list)
end
parts[#parts + 1] = '<\n'
elseif ntype == 'html_block' then
local text = node.text:gsub('^<pre>help', '')
local text = node.text:gsub('^<pre>help%s*', '')
text = text:gsub('</pre>%s*$', '')
parts[#parts + 1] = text
elseif ntype == 'list_marker_dot' then
@@ -358,7 +358,7 @@ local function render_md(node, start_indent, indent, text_width, level, is_list)
end
--- @param text_width integer
local function align_tags(text_width)
function M.align_tags(text_width)
--- @param line string
--- @return string
return function(line)
@@ -393,7 +393,7 @@ function M.md_to_vimdoc(text, start_indent, indent, text_width, is_list)
local lines = vim.split(table.concat(ret):gsub(NBSP, ' '), '\n')
lines = vim.tbl_map(align_tags(text_width), lines)
lines = vim.tbl_map(M.align_tags(text_width), lines)
local s = table.concat(lines, '\n')