From d7f7450017b9b05303698a6cda54303ef22c63b3 Mon Sep 17 00:00:00 2001 From: Christian Clason Date: Fri, 31 Mar 2023 17:09:00 +0200 Subject: refactor(treesitter)!: rename help parser to vimdoc --- scripts/gen_help_html.lua | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'scripts/gen_help_html.lua') diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua index 2563f2f410..367ce60765 100644 --- a/scripts/gen_help_html.lua +++ b/scripts/gen_help_html.lua @@ -624,7 +624,7 @@ local function get_helptags(help_dir) return m end --- Use the help.so parser defined in the build, not whatever happens to be installed on the system. +-- Use the vimdoc parser defined in the build, not whatever happens to be installed on the system. local function ensure_runtimepath() if not vim.o.runtimepath:find('build/lib/nvim/') then vim.cmd[[set runtimepath^=./build/lib/nvim/]] @@ -643,8 +643,8 @@ local function parse_buf(fname) buf = fname vim.cmd('sbuffer '..tostring(fname)) -- Buffer number. end - -- vim.treesitter.require_language('help', './build/lib/nvim/parser/help.so') - local lang_tree = vim.treesitter.get_parser(buf, 'help') + -- vim.treesitter.require_language('help', './build/lib/nvim/parser/vimdoc.so') + local lang_tree = vim.treesitter.get_parser(buf) return lang_tree, buf end -- cgit From 4d04feb6629cb049cb2a13ba35f0c8d3c6b67ff4 Mon Sep 17 00:00:00 2001 From: Christian Clason Date: Fri, 14 Apr 2023 10:39:57 +0200 Subject: feat(lua): vim.tbl_contains supports general tables and predicates (#23040) * feat(lua): vim.tbl_contains supports general tables and predicates Problem: `vim.tbl_contains` only works for list-like tables (integer keys without gaps) and primitive values (in particular, not for nested tables). Solution: Rename `vim.tbl_contains` to `vim.list_contains` and add new `vim.tbl_contains` that works for general tables and optionally allows `value` to be a predicate function that is checked for every key. --- scripts/gen_help_html.lua | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'scripts/gen_help_html.lua') diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua index 367ce60765..e2ab70eca2 100644 --- a/scripts/gen_help_html.lua +++ b/scripts/gen_help_html.lua @@ -491,7 +491,7 @@ local function visit_node(root, level, lang_tree, headings, opt, stats) return '' -- Discard common "noise" lines. end -- XXX: Avoid newlines (too much whitespace) after block elements in old (preformatted) layout. - local div = opt.old and root:child(0) and vim.tbl_contains({'column_heading', 'h1', 'h2', 'h3'}, root:child(0):type()) + local div = opt.old and root:child(0) and vim.list_contains({'column_heading', 'h1', 'h2', 'h3'}, root:child(0):type()) return string.format('%s%s', div and trim(text) or text, div and '' or '\n') elseif node_name == 'line_li' then local sib = root:prev_sibling() @@ -522,7 +522,7 @@ local function visit_node(root, level, lang_tree, headings, opt, stats) s = fix_tab_after_conceal(s, node_text(root:next_sibling())) end return s - elseif vim.tbl_contains({'codespan', 'keycode'}, node_name) then + elseif vim.list_contains({'codespan', 'keycode'}, node_name) then if root:has_error() then return text end @@ -554,7 +554,7 @@ local function visit_node(root, level, lang_tree, headings, opt, stats) if root:has_error() then return text end - local in_heading = vim.tbl_contains({'h1', 'h2', 'h3'}, parent) + local in_heading = vim.list_contains({'h1', 'h2', 'h3'}, parent) local cssclass = (not in_heading and get_indent(node_text()) > 8) and 'help-tag-right' or 'help-tag' local tagname = node_text(root:child(1), false) if vim.tbl_count(stats.first_tags) < 2 then @@ -601,7 +601,7 @@ local function get_helpfiles(include) for f, type in vim.fs.dir(dir) do if (vim.endswith(f, '.txt') and type == 'file' - and (not include or vim.tbl_contains(include, f))) then + and (not include or vim.list_contains(include, f))) then local fullpath = vim.fn.fnamemodify(('%s/%s'):format(dir, f), ':p') table.insert(rv, fullpath) end -- cgit From bfb19a110d93ce5cb7c09fee2442651db182ca4b Mon Sep 17 00:00:00 2001 From: Christian Clason Date: Tue, 2 May 2023 09:45:44 +0200 Subject: docs(html): right-align inline tags (#23403) --- scripts/gen_help_html.lua | 3 +++ 1 file changed, 3 insertions(+) (limited to 'scripts/gen_help_html.lua') diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua index e2ab70eca2..1bddd3aa8b 100644 --- a/scripts/gen_help_html.lua +++ b/scripts/gen_help_html.lua @@ -927,6 +927,9 @@ local function gen_css(fname) /* Tag pseudo-header common in :help docs. */ .help-tag-right { color: var(--tag-color); + margin-left: auto; + margin-right: 0; + float: right; } h1 .help-tag, h2 .help-tag, h3 .help-tag { font-size: smaller; -- cgit From 3913ebbfcde7d327dd6f1d85e30ce114a9e8193e Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Tue, 30 May 2023 17:32:38 -0700 Subject: docs(html): algolia docsearch #23839 Need to manually include this in the generated docs html because it doesn't use the website's (jekyll) layout template. Maintenance notes: https://github.com/neovim/neovim.github.io/#maintenance Related: https://github.com/neovim/neovim.github.io/commit/ce9aef12eb1c98135965e3a9c5c792bf9e506a76 --- scripts/gen_help_html.lua | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) (limited to 'scripts/gen_help_html.lua') diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua index 1bddd3aa8b..96289c45ec 100644 --- a/scripts/gen_help_html.lua +++ b/scripts/gen_help_html.lua @@ -696,6 +696,11 @@ local function gen_one(fname, to_fname, old, commit) + + + + + %s - Neovim docs @@ -766,12 +771,13 @@ local function gen_one(fname, to_fname, old, commit) main = ([[
@@ -825,6 +831,18 @@ local function gen_one(fname, to_fname, old, commit) parse_errors: %d %s | noise_lines: %d
+ + + + + ]]):format( os.date('%Y-%m-%d %H:%M'), commit, commit:sub(1, 7), #stats.parse_errors, bug_link, -- cgit From 36fd2fcaae757e8ac64c8ff7a66e4f480a075dcf Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Fri, 2 Jun 2023 02:45:23 -0700 Subject: docs(html): define anchors for search engine #23879 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Problem: Selecting a search result from the Algolia Docsearch widget does not navigate to a page anchor. The docs HTML provides `` anchors _near_ the `

`/`

`/… headings, but Algolia Docsearch expects the anchors to be _defined on_ the headings. That's also "semantically" nicer. https://docsearch.algolia.com/docs/manage-your-crawls/ Solution: Set `id` on the heading element instead of placing `` nearby. related: 3913ebbfcde7 #23839 --- scripts/gen_help_html.lua | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) (limited to 'scripts/gen_help_html.lua') diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua index 96289c45ec..7bc48a0662 100644 --- a/scripts/gen_help_html.lua +++ b/scripts/gen_help_html.lua @@ -461,6 +461,7 @@ local function visit_node(root, level, lang_tree, headings, opt, stats) local hname = (node_text():gsub('%-%-%-%-+', ''):gsub('%=%=%=%=+', ''):gsub('%*.*%*', '')) -- Use the first *tag* node as the heading anchor, if any. local tagnode = first(root, 'tag') + -- Use the *tag* as the heading anchor id, if possible. local tagname = tagnode and url_encode(node_text(tagnode:child(1), false)) or to_heading_tag(hname) if node_name == 'h1' or #headings == 0 then table.insert(headings, { name = hname, subheadings = {}, tag = tagname }) @@ -468,9 +469,7 @@ local function visit_node(root, level, lang_tree, headings, opt, stats) table.insert(headings[#headings].subheadings, { name = hname, subheadings = {}, tag = tagname }) end local el = node_name == 'h1' and 'h2' or 'h3' - -- If we are re-using the *tag*, this heading anchor is redundant. - local a = tagnode and '' or (''):format(tagname) - return ('%s<%s class="help-heading">%s\n'):format(a, el, text, el) + return ('<%s id="%s" class="help-heading">%s\n'):format(el, tagname, text, el) elseif node_name == 'column_heading' or node_name == 'column_name' then if root:has_error() then return text @@ -563,12 +562,14 @@ local function visit_node(root, level, lang_tree, headings, opt, stats) return '' end local el = in_heading and 'span' or 'code' - local s = ('%s<%s class="%s">%s'):format(ws(), url_encode(tagname), el, cssclass, trimmed, el) + local s = ('%s<%s id="%s" class="%s">%s'):format(ws(), el, url_encode(tagname), cssclass, trimmed, el) if opt.old then s = fix_tab_after_conceal(s, node_text(root:next_sibling())) end if in_heading and prev ~= 'tag' then + -- Don't set "id", let the heading use the tag as its "id" (used by search engines). + s = ('%s<%s class="%s">%s'):format(ws(), el, cssclass, trimmed, el) -- Start the container for tags in a heading. -- This makes "justify-content:space-between" right-align the tags. --

foo bartag1 tag2

@@ -643,7 +644,7 @@ local function parse_buf(fname) buf = fname vim.cmd('sbuffer '..tostring(fname)) -- Buffer number. end - -- vim.treesitter.require_language('help', './build/lib/nvim/parser/vimdoc.so') + -- vim.treesitter.language.add('vimdoc', { path = vim.fn.expand('~/Library/Caches/tree-sitter/lib/vimdoc.so') }) local lang_tree = vim.treesitter.get_parser(buf) return lang_tree, buf end @@ -784,7 +785,7 @@ local function gen_one(fname, to_fname, old, commit)
-

%s

+

%s

Nvim :help pages, generated @@ -795,7 +796,7 @@ local function gen_one(fname, to_fname, old, commit)

%s
- ]]):format(logo_svg, stats.first_tags[1] or '', stats.first_tags[2] or '', title, vim.fs.basename(fname), main) + ]]):format(logo_svg, stats.first_tags[2] or '', stats.first_tags[1] or '', title, vim.fs.basename(fname), main) local toc = [[
-- cgit From 72a6643b1380cdf6f1153d70eeaffb90bdca30d6 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Mon, 19 Jun 2023 08:40:33 -0700 Subject: docs #24061 - nvim requires rpc responses in reverse order. https://github.com/neovim/neovim/issues/19932 - NVIM_APPNAME: UIs normally should NOT set this. ref #23520 fix #24050 fix #23660 fix #23353 fix #23337 fix #22213 fix #19161 fix #18088 fix #20693 --- scripts/gen_help_html.lua | 2 -- 1 file changed, 2 deletions(-) (limited to 'scripts/gen_help_html.lua') diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua index 7bc48a0662..6cdf028f5c 100644 --- a/scripts/gen_help_html.lua +++ b/scripts/gen_help_html.lua @@ -62,7 +62,6 @@ local exclude_invalid = { ["'string'"] = "eval.txt", Query = 'treesitter.txt', ['eq?'] = 'treesitter.txt', - ['lsp-request'] = 'lsp.txt', matchit = 'vim_diff.txt', ['matchit.txt'] = 'help.txt', ["set!"] = "treesitter.txt", @@ -70,7 +69,6 @@ local exclude_invalid = { ['v:_null_dict'] = 'builtin.txt', ['v:_null_list'] = 'builtin.txt', ['v:_null_string'] = 'builtin.txt', - ['vim.lsp.buf_request()'] = 'lsp.txt', ['vim.lsp.util.get_progress_messages()'] = 'lsp.txt', } -- cgit From 5c73b1bb4c876d207e868bffc9f741c2a60d4aaf Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Tue, 20 Jun 2023 09:49:49 +0200 Subject: docs: lsp, vim_diff - quickstart - mark lsp.txt as `new_layout` - remove lsp-handler documentation for notifications: they don't have handlers because they don't have server responses. --- scripts/gen_help_html.lua | 1 + 1 file changed, 1 insertion(+) (limited to 'scripts/gen_help_html.lua') diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua index 6cdf028f5c..43c0e135d4 100644 --- a/scripts/gen_help_html.lua +++ b/scripts/gen_help_html.lua @@ -43,6 +43,7 @@ local M = {} -- All other files are "legacy" files which require fixed-width layout. local new_layout = { ['api.txt'] = true, + ['lsp.txt'] = true, ['channel.txt'] = true, ['deprecated.txt'] = true, ['develop.txt'] = true, -- cgit From 81d8fce8f9e1b369e64d57b018221e378841fb88 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Thu, 22 Jun 2023 09:00:49 +0200 Subject: feat(gen_help_html): non-default vimdoc.so parser Callers can specify a non-default vimdoc.so file path. --- scripts/gen_help_html.lua | 105 +++++++++++++++++++++++++--------------------- 1 file changed, 58 insertions(+), 47 deletions(-) (limited to 'scripts/gen_help_html.lua') diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua index 43c0e135d4..c03dc21d85 100644 --- a/scripts/gen_help_html.lua +++ b/scripts/gen_help_html.lua @@ -144,11 +144,11 @@ local function trim(s, dir) return vim.fn.trim(s, '\r\t\n ', dir or 0) end --- Remove common punctuation from URLs. --- --- TODO: fix this in the parser instead... https://github.com/neovim/tree-sitter-vimdoc --- --- @returns (fixed_url, removed_chars) where `removed_chars` is in the order found in the input. +--- Removes common punctuation from URLs. +--- +--- TODO: fix this in the parser instead... https://github.com/neovim/tree-sitter-vimdoc +--- +--- @returns (fixed_url, removed_chars) where `removed_chars` is in the order found in the input. local function fix_url(url) local removed_chars = '' local fixed_url = url @@ -162,7 +162,7 @@ local function fix_url(url) return fixed_url, removed_chars end --- Checks if a given line is a "noise" line that doesn't look good in HTML form. +--- Checks if a given line is a "noise" line that doesn't look good in HTML form. local function is_noise(line, noise_lines) if ( -- First line is always noise. @@ -187,7 +187,7 @@ local function is_noise(line, noise_lines) return false end --- Creates a github issue URL at neovim/tree-sitter-vimdoc with prefilled content. +--- Creates a github issue URL at neovim/tree-sitter-vimdoc with prefilled content. local function get_bug_url_vimdoc(fname, to_fname, sample_text) local this_url = string.format('https://neovim.io/doc/user/%s', vim.fs.basename(to_fname)) local bug_url = ('https://github.com/neovim/tree-sitter-vimdoc/issues/new?labels=bug&title=parse+error%3A+' @@ -200,7 +200,7 @@ local function get_bug_url_vimdoc(fname, to_fname, sample_text) return bug_url end --- Creates a github issue URL at neovim/neovim with prefilled content. +--- Creates a github issue URL at neovim/neovim with prefilled content. local function get_bug_url_nvim(fname, to_fname, sample_text, token_name) local this_url = string.format('https://neovim.io/doc/user/%s', vim.fs.basename(to_fname)) local bug_url = ('https://github.com/neovim/neovim/issues/new?labels=bug&title=user+docs+HTML%3A+' @@ -215,7 +215,7 @@ local function get_bug_url_nvim(fname, to_fname, sample_text, token_name) return bug_url end --- Gets a "foo.html" name from a "foo.txt" helpfile name. +--- Gets a "foo.html" name from a "foo.txt" helpfile name. local function get_helppage(f) if not f then return nil @@ -230,9 +230,9 @@ local function get_helppage(f) return (f:gsub('%.txt$', '.html')) end --- Counts leading spaces (tab=8) to decide the indent size of multiline text. --- --- Blank lines (empty or whitespace-only) are ignored. +--- Counts leading spaces (tab=8) to decide the indent size of multiline text. +--- +--- Blank lines (empty or whitespace-only) are ignored. local function get_indent(s) local min_indent = nil for line in vim.gsplit(s, '\n') do @@ -244,7 +244,7 @@ local function get_indent(s) return min_indent or 0 end --- Removes the common indent level, after expanding tabs to 8 spaces. +--- Removes the common indent level, after expanding tabs to 8 spaces. local function trim_indent(s) local indent_size = get_indent(s) local trimmed = '' @@ -255,7 +255,7 @@ local function trim_indent(s) return trimmed:sub(1, -2) end --- Gets raw buffer text in the node's range (+/- an offset), as a newline-delimited string. +--- Gets raw buffer text in the node's range (+/- an offset), as a newline-delimited string. local function getbuflinestr(node, bufnr, offset) local line1, _, line2, _ = node:range() line1 = line1 - offset @@ -264,8 +264,8 @@ local function getbuflinestr(node, bufnr, offset) return table.concat(lines, '\n') end --- Gets the whitespace just before `node` from the raw buffer text. --- Needed for preformatted `old` lines. +--- Gets the whitespace just before `node` from the raw buffer text. +--- Needed for preformatted `old` lines. local function getws(node, bufnr) local line1, c1, line2, _ = node:range() local raw = vim.fn.getbufline(bufnr, line1 + 1, line2 + 1)[1] @@ -282,7 +282,7 @@ local function get_tagname(node, bufnr) return helppage, tag end --- Returns true if the given invalid tagname is a false positive. +--- Returns true if the given invalid tagname is a false positive. local function ignore_invalid(s) return not not ( exclude_invalid[s] @@ -314,7 +314,7 @@ local function has_ancestor(node, ancestor_name) return false end --- Gets the first matching child node matching `name`. +--- Gets the first matching child node matching `name`. local function first(node, name) for c, _ in node:iter_children() do if c:named() and c:type() == name then @@ -336,7 +336,7 @@ local function validate_link(node, bufnr, fname) return helppage, tagname, ignored end --- TODO: port the logic from scripts/check_urls.vim +--- TODO: port the logic from scripts/check_urls.vim local function validate_url(text, fname) local ignored = false if vim.fs.basename(fname) == 'pi_netrw.txt' then @@ -347,7 +347,7 @@ local function validate_url(text, fname) return ignored end --- Traverses the tree at `root` and checks that |tag| links point to valid helptags. +--- Traverses the tree at `root` and checks that |tag| links point to valid helptags. local function visit_validate(root, level, lang_tree, opt, stats) level = level or 0 local node_name = (root.named and root:named()) and root:type() or nil @@ -609,7 +609,7 @@ local function get_helpfiles(include) return rv end --- Populates the helptags map. +--- Populates the helptags map. local function get_helptags(help_dir) local m = {} -- Load a random help file to convince taglist() to do its job. @@ -624,17 +624,19 @@ local function get_helptags(help_dir) return m end --- Use the vimdoc parser defined in the build, not whatever happens to be installed on the system. +--- Use the vimdoc parser defined in the build, not whatever happens to be installed on the system. local function ensure_runtimepath() if not vim.o.runtimepath:find('build/lib/nvim/') then vim.cmd[[set runtimepath^=./build/lib/nvim/]] end end --- Opens `fname` in a buffer and gets a treesitter parser for the buffer contents. --- --- @returns lang_tree, bufnr -local function parse_buf(fname) +--- Opens `fname` in a buffer and gets a treesitter parser for the buffer contents. +--- +--- @param fname string help file to parse +--- @param parser_path string? path to non-default vimdoc.so +--- @returns lang_tree, bufnr +local function parse_buf(fname, parser_path) local buf if type(fname) == 'string' then vim.cmd('split '..vim.fn.fnameescape(fname)) -- Filename. @@ -643,21 +645,25 @@ local function parse_buf(fname) buf = fname vim.cmd('sbuffer '..tostring(fname)) -- Buffer number. end - -- vim.treesitter.language.add('vimdoc', { path = vim.fn.expand('~/Library/Caches/tree-sitter/lib/vimdoc.so') }) + if parser_path then + vim.treesitter.language.add('vimdoc', { path = parser_path }) + end local lang_tree = vim.treesitter.get_parser(buf) return lang_tree, buf end --- Validates one :help file `fname`: --- - checks that |tag| links point to valid helptags. --- - recursively counts parse errors ("ERROR" nodes) --- --- @returns { invalid_links: number, parse_errors: number } -local function validate_one(fname) +--- Validates one :help file `fname`: +--- - checks that |tag| links point to valid helptags. +--- - recursively counts parse errors ("ERROR" nodes) +--- +--- @param fname string help file to validate +--- @param parser_path string? path to non-default vimdoc.so +--- @returns { invalid_links: number, parse_errors: number } +local function validate_one(fname, parser_path) local stats = { parse_errors = {}, } - local lang_tree, buf = parse_buf(fname) + local lang_tree, buf = parse_buf(fname, parser_path) for _, tree in ipairs(lang_tree:trees()) do visit_validate(tree:root(), 0, tree, { buf = buf, fname = fname, }, stats) end @@ -666,20 +672,21 @@ local function validate_one(fname) return stats end --- Generates HTML from one :help file `fname` and writes the result to `to_fname`. --- --- @param fname Source :help file --- @param to_fname Destination .html file --- @param old boolean Preformat paragraphs (for old :help files which are full of arbitrary whitespace) --- --- @returns html, stats -local function gen_one(fname, to_fname, old, commit) +--- Generates HTML from one :help file `fname` and writes the result to `to_fname`. +--- +--- @param fname string Source :help file +--- @param to_fname string Destination .html file +--- @param old boolean Preformat paragraphs (for old :help files which are full of arbitrary whitespace) +--- @param parser_path string? path to non-default vimdoc.so +--- +--- @returns html, stats +local function gen_one(fname, to_fname, old, commit, parser_path) local stats = { noise_lines = {}, parse_errors = {}, first_tags = {}, -- Track the first few tags in doc. } - local lang_tree, buf = parse_buf(fname) + local lang_tree, buf = parse_buf(fname, parser_path) local headings = {} -- Headings (for ToC). 2-dimensional: h1 contains h2/h3. local title = to_titlecase(basename_noext(fname)) @@ -1059,18 +1066,20 @@ end --- @param include table|nil Process only these filenames. Example: {'api.txt', 'autocmd.txt', 'channel.txt'} --- --- @returns info dict -function M.gen(help_dir, to_dir, include, commit) +function M.gen(help_dir, to_dir, include, commit, parser_path) vim.validate{ help_dir={help_dir, function(d) return vim.fn.isdirectory(d) == 1 end, 'valid directory'}, to_dir={to_dir, 's'}, include={include, 't', true}, commit={commit, 's', true}, + parser_path={parser_path, function(f) return f == nil or vim.fn.filereadable(vim.fn.expand(f)) == 1 end, 'valid vimdoc.{so,dll} filepath'}, } local err_count = 0 ensure_runtimepath() tagmap = get_helptags(help_dir) helpfiles = get_helpfiles(include) + parser_path = parser_path and vim.fn.expand(parser_path) or nil print(('output dir: %s'):format(to_dir)) vim.fn.mkdir(to_dir, 'p') @@ -1079,7 +1088,7 @@ function M.gen(help_dir, to_dir, include, commit) for _, f in ipairs(helpfiles) do local helpfile = vim.fs.basename(f) local to_fname = ('%s/%s'):format(to_dir, get_helppage(helpfile)) - local html, stats = gen_one(f, to_fname, not new_layout[helpfile], commit or '?') + local html, stats = gen_one(f, to_fname, not new_layout[helpfile], commit or '?', parser_path) tofile(to_fname, html) print(('generated (%-4s errors): %-15s => %s'):format(#stats.parse_errors, helpfile, vim.fs.basename(to_fname))) err_count = err_count + #stats.parse_errors @@ -1102,19 +1111,21 @@ end -- This is 10x faster than gen(), for use in CI. -- -- @returns results dict -function M.validate(help_dir, include) +function M.validate(help_dir, include, parser_path) vim.validate{ help_dir={help_dir, function(d) return vim.fn.isdirectory(d) == 1 end, 'valid directory'}, include={include, 't', true}, + parser_path={parser_path, function(f) return f == nil or vim.fn.filereadable(vim.fn.expand(f)) == 1 end, 'valid vimdoc.{so,dll} filepath'}, } local err_count = 0 ensure_runtimepath() tagmap = get_helptags(help_dir) helpfiles = get_helpfiles(include) + parser_path = parser_path and vim.fn.expand(parser_path) or nil for _, f in ipairs(helpfiles) do local helpfile = vim.fs.basename(f) - local rv = validate_one(f) + local rv = validate_one(f, parser_path) print(('validated (%-4s errors): %s'):format(#rv.parse_errors, helpfile)) err_count = err_count + #rv.parse_errors end -- cgit From b0cf9c5feeae789d832256569488a3b98d265d2c Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Thu, 22 Jun 2023 08:42:10 +0200 Subject: feat(gen_help_html): ignore pi_netrw.txt errors IDGAF about netrw --- scripts/gen_help_html.lua | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) (limited to 'scripts/gen_help_html.lua') diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua index c03dc21d85..268fd12f6f 100644 --- a/scripts/gen_help_html.lua +++ b/scripts/gen_help_html.lua @@ -89,6 +89,11 @@ local exclude_invalid_urls = { ["http://www.jclark.com/"] = "quickfix.txt", } +-- Deprecated, brain-damaged files that I don't care about. +local ignore_errors = { + ['pi_netrw.txt'] = true, +} + local function tofile(fname, text) local f = io.open(fname, 'w') if not f then @@ -293,7 +298,10 @@ local function ignore_invalid(s) ) end -local function ignore_parse_error(s) +local function ignore_parse_error(fname, s) + if ignore_errors[vim.fs.basename(fname)] then + return true + end return ( -- Ignore parse errors for unclosed tag. -- This is common in vimdocs and is treated as plaintext by :help. @@ -339,7 +347,7 @@ end --- TODO: port the logic from scripts/check_urls.vim local function validate_url(text, fname) local ignored = false - if vim.fs.basename(fname) == 'pi_netrw.txt' then + if ignore_errors[vim.fs.basename(fname)] then ignored = true elseif text:find('http%:') and not exclude_invalid_urls[text] then invalid_urls[text] = vim.fs.basename(fname) @@ -366,7 +374,7 @@ local function visit_validate(root, level, lang_tree, opt, stats) end if node_name == 'ERROR' then - if ignore_parse_error(text) then + if ignore_parse_error(opt.fname, text) then return end -- Store the raw text to give context to the error report. @@ -579,7 +587,7 @@ local function visit_node(root, level, lang_tree, headings, opt, stats) end return s elseif node_name == 'ERROR' then - if ignore_parse_error(trimmed) then + if ignore_parse_error(opt.fname, trimmed) then return text end -- cgit From 4e6356559c8cd44dbcaa765d1f39e176064526ec Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Thu, 22 Jun 2023 03:44:51 -0700 Subject: test: spellcheck :help (vimdoc) files #24109 Enforce consistent terminology (defined in `gen_help_html.lua:spell_dict`) for common misspellings. This does not spellcheck English in general (perhaps a future TODO, though it may be noisy). --- scripts/gen_help_html.lua | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) (limited to 'scripts/gen_help_html.lua') diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua index 268fd12f6f..b369e0db5e 100644 --- a/scripts/gen_help_html.lua +++ b/scripts/gen_help_html.lua @@ -70,7 +70,6 @@ local exclude_invalid = { ['v:_null_dict'] = 'builtin.txt', ['v:_null_list'] = 'builtin.txt', ['v:_null_string'] = 'builtin.txt', - ['vim.lsp.util.get_progress_messages()'] = 'lsp.txt', } -- False-positive "invalid URLs". @@ -359,6 +358,8 @@ end local function visit_validate(root, level, lang_tree, opt, stats) level = level or 0 local node_name = (root.named and root:named()) and root:type() or nil + -- Parent kind (string). + local parent = root:parent() and root:parent():type() or nil local toplevel = level < 1 local function node_text(node) return vim.treesitter.get_node_text(node or root, opt.buf) @@ -380,13 +381,13 @@ local function visit_validate(root, level, lang_tree, opt, stats) -- Store the raw text to give context to the error report. local sample_text = not toplevel and getbuflinestr(root, opt.buf, 3) or '[top level!]' table.insert(stats.parse_errors, sample_text) - elseif node_name == 'word' or node_name == 'uppercase_name' then - if spell_dict[text] then - if not invalid_spelling[text] then - invalid_spelling[text] = { vim.fs.basename(opt.fname) } - else - table.insert(invalid_spelling[text], vim.fs.basename(opt.fname)) - end + elseif (node_name == 'word' or node_name == 'uppercase_name') + and (not vim.tbl_contains({'codespan', 'taglink', 'tag'}, parent)) + then + local text_nopunct = vim.fn.trim(text, '.,', 0) -- Ignore some punctuation. + if spell_dict[text_nopunct] then + invalid_spelling[text_nopunct] = invalid_spelling[text_nopunct] or {} + invalid_spelling[text_nopunct][vim.fs.basename(opt.fname)] = node_text(root:parent()) end elseif node_name == 'url' then local fixed_url, _ = fix_url(trim(text)) @@ -544,7 +545,7 @@ local function visit_node(root, level, lang_tree, headings, opt, stats) elseif node_name == 'language' then language = node_text(root) return '' - elseif node_name == 'code' then + elseif node_name == 'code' then -- Highlighted codeblock (child). if is_blank(text) then return '' end -- cgit From 036da0d07921e67090d1a62c9a4e382ca09d8584 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sat, 24 Jun 2023 13:47:10 +0200 Subject: fix(docs): vimdoc syntax errors gen_help_html: truncate parse-error sample text --- scripts/gen_help_html.lua | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) (limited to 'scripts/gen_help_html.lua') diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua index b369e0db5e..c89a7c70da 100644 --- a/scripts/gen_help_html.lua +++ b/scripts/gen_help_html.lua @@ -379,7 +379,9 @@ local function visit_validate(root, level, lang_tree, opt, stats) return end -- Store the raw text to give context to the error report. - local sample_text = not toplevel and getbuflinestr(root, opt.buf, 3) or '[top level!]' + local sample_text = not toplevel and getbuflinestr(root, opt.buf, 0) or '[top level!]' + -- Flatten the sample text to a single, truncated line. + sample_text = vim.trim(sample_text):gsub('[\t\n]', ' '):sub(1, 80) table.insert(stats.parse_errors, sample_text) elseif (node_name == 'word' or node_name == 'uppercase_name') and (not vim.tbl_contains({'codespan', 'taglink', 'tag'}, parent)) @@ -667,7 +669,7 @@ end --- --- @param fname string help file to validate --- @param parser_path string? path to non-default vimdoc.so ---- @returns { invalid_links: number, parse_errors: number } +--- @returns { invalid_links: number, parse_errors: string[] } local function validate_one(fname, parser_path) local stats = { parse_errors = {}, @@ -1127,6 +1129,7 @@ function M.validate(help_dir, include, parser_path) parser_path={parser_path, function(f) return f == nil or vim.fn.filereadable(vim.fn.expand(f)) == 1 end, 'valid vimdoc.{so,dll} filepath'}, } local err_count = 0 + local files_to_errors = {} ensure_runtimepath() tagmap = get_helptags(help_dir) helpfiles = get_helpfiles(include) @@ -1136,6 +1139,10 @@ function M.validate(help_dir, include, parser_path) local helpfile = vim.fs.basename(f) local rv = validate_one(f, parser_path) print(('validated (%-4s errors): %s'):format(#rv.parse_errors, helpfile)) + if #rv.parse_errors > 0 then + files_to_errors[helpfile] = rv.parse_errors + vim.print(('%s'):format(vim.iter(rv.parse_errors):fold('', function(s, v) return s..'\n '..v end))) + end err_count = err_count + #rv.parse_errors end @@ -1145,6 +1152,7 @@ function M.validate(help_dir, include, parser_path) invalid_links = invalid_links, invalid_urls = invalid_urls, invalid_spelling = invalid_spelling, + parse_errors = files_to_errors, } end -- cgit From 957d05d16bc80cef14c2e9fe31b6b847e698f9d1 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 25 Jun 2023 12:29:56 -0700 Subject: fix(docs): too much whitespace around 
 blocks #24151

Problem:
In the generated docs HTML there is too much whitespace before/after `
`
blocks.
- In the old layout (fixed-width), all text in `.old-help-para` is formatted as
  `white-space:pre`.
- In the new layout, when `
` is at the end of a `
`, the margins of
  both are redundant, causing too much space.

Solution:
- In the old layout, always remove `
` margin.
- In the new layout, disable `
` margin if it is the last child.
---
 scripts/gen_help_html.lua | 10 ++++++++++
 1 file changed, 10 insertions(+)

(limited to 'scripts/gen_help_html.lua')

diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua
index c89a7c70da..f741efcaeb 100644
--- a/scripts/gen_help_html.lua
+++ b/scripts/gen_help_html.lua
@@ -944,6 +944,7 @@ local function gen_css(fname)
       padding-top: 10px;
       padding-bottom: 10px;
     }
+
     .old-help-para {
       padding-top: 10px;
       padding-bottom: 10px;
@@ -953,6 +954,12 @@ local function gen_css(fname)
       font-size: 16px;
       font-family: ui-monospace,SFMono-Regular,SF Mono,Menlo,Consolas,Liberation Mono,monospace;
     }
+    .old-help-para pre {
+      /* All text in .old-help-para is formatted as "white-space:pre" so text following 
 is
+         already visually separated by the linebreak. */
+      margin-bottom: 0;
+    }
+
     a.help-tag, a.help-tag:focus, a.help-tag:hover {
       color: inherit;
       text-decoration: none;
@@ -1006,6 +1013,9 @@ local function gen_css(fname)
       font-size: 16px;
       margin-top: 10px;
     }
+    pre:last-child {
+      margin-bottom: 0;
+    }
     pre:hover,
     .help-heading:hover {
       overflow: visible;
-- 
cgit 


From ab65a98adba4d32b03e7296529c4bf1491c783eb Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" 
Date: Tue, 27 Jun 2023 10:21:27 -0700
Subject: fix(docs): ignore_invalid #24174

Regex bug in scripts/gen_help_html.lua:ignore_invalid()
---
 scripts/gen_help_html.lua | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'scripts/gen_help_html.lua')

diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua
index f741efcaeb..7f84a4d54d 100644
--- a/scripts/gen_help_html.lua
+++ b/scripts/gen_help_html.lua
@@ -293,7 +293,7 @@ local function ignore_invalid(s)
     -- Strings like |~/====| appear in various places and the parser thinks they are links, but they
     -- are just table borders.
     or s:find('===')
-    or s:find('---')
+    or s:find('%-%-%-')
   )
 end
 
-- 
cgit 


From 6da110d617dba6378f770c5d66d523df92f2d355 Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" 
Date: Mon, 3 Jul 2023 05:04:43 -0700
Subject: docs(gen_help_html): accept "~/" in file/dir params #24240

---
 scripts/gen_help_html.lua | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

(limited to 'scripts/gen_help_html.lua')

diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua
index 7f84a4d54d..5575de5b36 100644
--- a/scripts/gen_help_html.lua
+++ b/scripts/gen_help_html.lua
@@ -1089,7 +1089,7 @@ end
 --- @returns info dict
 function M.gen(help_dir, to_dir, include, commit, parser_path)
   vim.validate{
-    help_dir={help_dir, function(d) return vim.fn.isdirectory(d) == 1 end, 'valid directory'},
+    help_dir={help_dir, function(d) return vim.fn.isdirectory(vim.fn.expand(d)) == 1 end, 'valid directory'},
     to_dir={to_dir, 's'},
     include={include, 't', true},
     commit={commit, 's', true},
@@ -1098,8 +1098,9 @@ function M.gen(help_dir, to_dir, include, commit, parser_path)
 
   local err_count = 0
   ensure_runtimepath()
-  tagmap = get_helptags(help_dir)
+  tagmap = get_helptags(vim.fn.expand(help_dir))
   helpfiles = get_helpfiles(include)
+  to_dir = vim.fn.expand(to_dir)
   parser_path = parser_path and vim.fn.expand(parser_path) or nil
 
   print(('output dir: %s'):format(to_dir))
@@ -1134,14 +1135,14 @@ end
 -- @returns results dict
 function M.validate(help_dir, include, parser_path)
   vim.validate{
-    help_dir={help_dir, function(d) return vim.fn.isdirectory(d) == 1 end, 'valid directory'},
+    help_dir={help_dir, function(d) return vim.fn.isdirectory(vim.fn.expand(d)) == 1 end, 'valid directory'},
     include={include, 't', true},
     parser_path={parser_path, function(f) return f == nil or vim.fn.filereadable(vim.fn.expand(f)) == 1 end, 'valid vimdoc.{so,dll} filepath'},
   }
   local err_count = 0
   local files_to_errors = {}
   ensure_runtimepath()
-  tagmap = get_helptags(help_dir)
+  tagmap = get_helptags(vim.fn.expand(help_dir))
   helpfiles = get_helpfiles(include)
   parser_path = parser_path and vim.fn.expand(parser_path) or nil
 
-- 
cgit 


From 0a90e4b05ad3263bf656e24f616b6dadf6ba92e4 Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" 
Date: Sat, 8 Jul 2023 15:58:50 +0200
Subject: fix(docs): match DocSearch style with site theme

ref https://github.com/neovim/neovim.github.io/commit/2b4f9e47809c16743f7d31d0dc1f1e3c2f313a56
---
 scripts/gen_help_html.lua | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

(limited to 'scripts/gen_help_html.lua')

diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua
index 5575de5b36..1b997a5614 100644
--- a/scripts/gen_help_html.lua
+++ b/scripts/gen_help_html.lua
@@ -709,16 +709,17 @@ local function gen_one(fname, to_fname, old, commit, parser_path)
     
     
     
+
+    
+    
+    
+
     
     
     
     
     
 
-    
-    
-    
-
     
     
     %s - Neovim docs
-- 
cgit 


From ca9f4a7cb1fea1ef1f22c011679fd8afa0a5d161 Mon Sep 17 00:00:00 2001
From: zeertzjq 
Date: Fri, 21 Jul 2023 16:30:05 +0800
Subject: docs: also change "vimL" and "viml" to "Vimscript" (#24414)

---
 scripts/gen_help_html.lua | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'scripts/gen_help_html.lua')

diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua
index 1b997a5614..5e06830336 100644
--- a/scripts/gen_help_html.lua
+++ b/scripts/gen_help_html.lua
@@ -34,6 +34,8 @@ local spell_dict = {
   neovim = 'Nvim',
   lua = 'Lua',
   VimL = 'Vimscript',
+  vimL = 'Vimscript',
+  viml = 'Vimscript',
 }
 local language = nil
 
-- 
cgit 


From bc67cf3ccdf935a0e2974fbbe5557a3d24931c54 Mon Sep 17 00:00:00 2001
From: Sergey Slipchenko 
Date: Tue, 12 Sep 2023 15:51:38 +0400
Subject: feat(gen_help_html): add anchors to help tags #25112

Fixes #21911

Co-authored by: wispl
---
 scripts/gen_help_html.lua | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

(limited to 'scripts/gen_help_html.lua')

diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua
index 5e06830336..c8e004e2ab 100644
--- a/scripts/gen_help_html.lua
+++ b/scripts/gen_help_html.lua
@@ -574,14 +574,15 @@ local function visit_node(root, level, lang_tree, headings, opt, stats)
       return ''
     end
     local el = in_heading and 'span' or 'code'
-    local s = ('%s<%s id="%s" class="%s">%s'):format(ws(), el, url_encode(tagname), cssclass, trimmed, el)
+    local encoded_tagname = url_encode(tagname)
+    local s = ('%s<%s id="%s" class="%s">%s'):format(ws(), el, encoded_tagname, cssclass, encoded_tagname, trimmed, el)
     if opt.old then
         s = fix_tab_after_conceal(s, node_text(root:next_sibling()))
     end
 
     if in_heading and prev ~= 'tag' then
       -- Don't set "id", let the heading use the tag as its "id" (used by search engines).
-      s = ('%s<%s class="%s">%s'):format(ws(), el, cssclass, trimmed, el)
+      s = ('%s<%s class="%s">%s'):format(ws(), el, cssclass, encoded_tagname, trimmed, el)
       -- Start the  container for tags in a heading.
       -- This makes "justify-content:space-between" right-align the tags.
       --    
foo bartag1 tag2

@@ -963,6 +964,7 @@ local function gen_css(fname)
       margin-bottom: 0;
     }
 
+    /* TODO: should this rule be deleted? help tags are rendered as  or , not  */
     a.help-tag, a.help-tag:focus, a.help-tag:hover {
       color: inherit;
       text-decoration: none;
@@ -977,6 +979,14 @@ local function gen_css(fname)
       margin-right: 0;
       float: right;
     }
+    .help-tag a,
+    .help-tag-right a {
+      color: inherit;
+    }
+    .help-tag a:not(:hover),
+    .help-tag-right a:not(:hover) {
+      text-decoration: none;
+    }
     h1 .help-tag, h2 .help-tag, h3 .help-tag {
       font-size: smaller;
     }
-- 
cgit 


From 5a2543c1598a0cf97b8eca0573139c9c20d6c93a Mon Sep 17 00:00:00 2001
From: dundargoc <33953936+dundargoc@users.noreply.github.com>
Date: Fri, 3 Nov 2023 00:22:02 +0100
Subject: docs: small fixes (#25831)

Co-authored-by: Peter Aronoff 
---
 scripts/gen_help_html.lua | 8 --------
 1 file changed, 8 deletions(-)

(limited to 'scripts/gen_help_html.lua')

diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua
index c8e004e2ab..633207e018 100644
--- a/scripts/gen_help_html.lua
+++ b/scripts/gen_help_html.lua
@@ -60,18 +60,10 @@ local new_layout = {
 
 -- TODO: These known invalid |links| require an update to the relevant docs.
 local exclude_invalid = {
-  ["'previewpopup'"] = "quickref.txt",
-  ["'pvp'"] = "quickref.txt",
   ["'string'"] = "eval.txt",
   Query = 'treesitter.txt',
-  ['eq?'] = 'treesitter.txt',
   matchit = 'vim_diff.txt',
-  ['matchit.txt'] = 'help.txt',
   ["set!"] = "treesitter.txt",
-  ['v:_null_blob'] = 'builtin.txt',
-  ['v:_null_dict'] = 'builtin.txt',
-  ['v:_null_list'] = 'builtin.txt',
-  ['v:_null_string'] = 'builtin.txt',
 }
 
 -- False-positive "invalid URLs".
-- 
cgit 


From d50274812b275edff58418b3d17868385599fc14 Mon Sep 17 00:00:00 2001
From: rsynnest 
Date: Tue, 14 Nov 2023 09:33:18 -0800
Subject: docs: adjust help-tag-right CSS for HTML #25858

---
 scripts/gen_help_html.lua | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

(limited to 'scripts/gen_help_html.lua')

diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua
index 633207e018..706335342d 100644
--- a/scripts/gen_help_html.lua
+++ b/scripts/gen_help_html.lua
@@ -967,13 +967,16 @@ local function gen_css(fname)
     /* Tag pseudo-header common in :help docs. */
     .help-tag-right {
       color: var(--tag-color);
-      margin-left: auto;
-      margin-right: 0;
-      float: right;
+      background-color: inherit;
+      display: flex;
+      justify-content: right;
+      margin-top: 1.5em;
+      margin-bottom: 1em;
     }
     .help-tag a,
     .help-tag-right a {
       color: inherit;
+      background-color: var(--accent-bg-color);
     }
     .help-tag a:not(:hover),
     .help-tag-right a:not(:hover) {
-- 
cgit 


From 1a4db51d064e1ef6925e3545f80a13da4b92d4ef Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" 
Date: Tue, 14 Nov 2023 09:55:54 -0800
Subject: Revert "docs: adjust help-tag-right CSS for HTML" #26046

The style change is mostly a regression.

Reverts #25858 d50274812b275edff58418b3d17868385599fc14
---
 scripts/gen_help_html.lua | 9 +++------
 1 file changed, 3 insertions(+), 6 deletions(-)

(limited to 'scripts/gen_help_html.lua')

diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua
index 706335342d..633207e018 100644
--- a/scripts/gen_help_html.lua
+++ b/scripts/gen_help_html.lua
@@ -967,16 +967,13 @@ local function gen_css(fname)
     /* Tag pseudo-header common in :help docs. */
     .help-tag-right {
       color: var(--tag-color);
-      background-color: inherit;
-      display: flex;
-      justify-content: right;
-      margin-top: 1.5em;
-      margin-bottom: 1em;
+      margin-left: auto;
+      margin-right: 0;
+      float: right;
     }
     .help-tag a,
     .help-tag-right a {
       color: inherit;
-      background-color: var(--accent-bg-color);
     }
     .help-tag a:not(:hover),
     .help-tag-right a:not(:hover) {
-- 
cgit