From e5cb3104d07228de4f2614c425355e8f2f99507d Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Fri, 14 Oct 2022 11:01:13 -0400 Subject: docs: fix/remove invalid URLs #20647 --- scripts/gen_help_html.lua | 14 +++++++++++--- 1 file changed, 11 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 06ea1831b0..39c516ee96 100644 --- a/scripts/gen_help_html.lua +++ b/scripts/gen_help_html.lua @@ -319,6 +319,16 @@ local function validate_link(node, bufnr, fname) return helppage, tagname, ignored end +local function validate_url(text, fname) + local ignored = false + if vim.fs.basename(fname) == 'pi_netrw.txt' then + ignored = true + elseif text:find('http%:') then + invalid_urls[text] = vim.fs.basename(fname) + end + return ignored +end + -- 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 @@ -353,9 +363,7 @@ local function visit_validate(root, level, lang_tree, opt, stats) end end elseif node_name == 'url' then - if text:find('http%:') then - invalid_urls[text] = vim.fs.basename(opt.fname) - end + validate_url(text, opt.fname) elseif node_name == 'taglink' or node_name == 'optionlink' then local _, _, _ = validate_link(root, opt.buf, opt.fname) end -- cgit From ef4c339fb9de87f7534303e006c281e40327f803 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Tue, 18 Oct 2022 10:18:44 -0400 Subject: feat(docs): update parser, HTML gen #20720 Note: although the tolerance in help_spec.lua increased, the actual error count with the new parser decreased by about 20%. The difference is that the old ignore_parse_error() ignored many more errors with the old parser. fix https://github.com/neovim/tree-sitter-vimdoc/issues/37 fix https://github.com/neovim/tree-sitter-vimdoc/issues/44 fix https://github.com/neovim/tree-sitter-vimdoc/issues/47 --- scripts/gen_help_html.lua | 37 +++++++++++++++++++++++++++++-------- 1 file changed, 29 insertions(+), 8 deletions(-) (limited to 'scripts/gen_help_html.lua') diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua index 39c516ee96..b1d41cf89e 100644 --- a/scripts/gen_help_html.lua +++ b/scripts/gen_help_html.lua @@ -74,6 +74,23 @@ local exclude_invalid = { ["vim.treesitter.start()"] = "treesitter.txt", } +-- False-positive "invalid URLs". +local exclude_invalid_urls = { + ["http://"] = "usr_23.txt", + ["http://."] = "usr_23.txt", + ["http://aspell.net/man-html/Affix-Compression.html"] = "spell.txt", + ["http://aspell.net/man-html/Phonetic-Code.html"] = "spell.txt", + ["http://canna.sourceforge.jp/"] = "mbyte.txt", + ["http://gnuada.sourceforge.net"] = "ft_ada.txt", + ["http://lua-users.org/wiki/StringLibraryTutorial"] = "lua.txt", + ["http://michael.toren.net/code/"] = "pi_tar.txt", + ["http://papp.plan9.de"] = "syntax.txt", + ["http://wiki.services.openoffice.org/wiki/Dictionaries"] = "spell.txt", + ["http://www.adapower.com"] = "ft_ada.txt", + ["http://www.ghostscript.com/"] = "print.txt", + ["http://www.jclark.com/"] = "quickfix.txt", +} + local function tofile(fname, text) local f = io.open(fname, 'w') if not f then @@ -278,10 +295,13 @@ local function ignore_invalid(s) ) end -local function ignore_parse_error(s) - -- Ignore parse errors for unclosed codespan/optionlink/tag. - -- This is common in vimdocs and is treated as plaintext by :help. - return s:find("^[`'|*]") +local function ignore_parse_error(s, fname) + local helpfile = vim.fs.basename(fname) + return (helpfile == 'pi_netrw.txt' + -- Ignore parse errors for unclosed tag. + -- This is common in vimdocs and is treated as plaintext by :help. + or s:find("^[`'|*]") + ) end local function has_ancestor(node, ancestor_name) @@ -323,7 +343,7 @@ local function validate_url(text, fname) local ignored = false if vim.fs.basename(fname) == 'pi_netrw.txt' then ignored = true - elseif text:find('http%:') then + elseif text:find('http%:') and not exclude_invalid_urls[text] then invalid_urls[text] = vim.fs.basename(fname) end return ignored @@ -348,7 +368,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(text, opt.fname) then return end -- Store the raw text to give context to the error report. @@ -363,7 +383,8 @@ local function visit_validate(root, level, lang_tree, opt, stats) end end elseif node_name == 'url' then - validate_url(text, opt.fname) + local fixed_url, _ = fix_url(trim(text)) + validate_url(fixed_url, opt.fname) elseif node_name == 'taglink' or node_name == 'optionlink' then local _, _, _ = validate_link(root, opt.buf, opt.fname) end @@ -523,7 +544,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(trimmed, opt.fname) then return text end -- cgit From 10ab7489ebb2bcbc7c1b5360921978c1ca2d0a4b Mon Sep 17 00:00:00 2001 From: Yee Cheng Chin Date: Thu, 20 Oct 2022 03:22:46 -0700 Subject: fix(docs-html): misaligned tabs after conceal #20690 Problem: `gen_help_html.lua` does not properly handle tab characters after "concealed" text (tags, taglinks, codespans). This causes misaligned layout in "old" (preformatted) docs. For text like `*tag*`, |tag_link|, and `code_span`, Vim hides the "*", "|", "`" characters, but Vim still counts those characters for "virtual column" when a tab character follows it. So if you have a tag of say 6 characters long, those two concealed character would lead to the tab character after it start at column 8. gen_help_html.lua doesn't account for that which leads to formatting flaws in the generated output. Solution: Add two spaces after concealed nodes that are followed by a tab char. --- scripts/gen_help_html.lua | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 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 b1d41cf89e..3a384bccf9 100644 --- a/scripts/gen_help_html.lua +++ b/scripts/gen_help_html.lua @@ -390,6 +390,18 @@ local function visit_validate(root, level, lang_tree, opt, stats) end end +-- Fix tab alignment issues caused by concealed characters like |, `, * in tags +-- and code blocks. +local function fix_tab_after_conceal(text, next_node_text) + -- Vim tabs take into account the two concealed characters even though they + -- are invisible, so we need to add back in the two spaces if this is + -- followed by a tab to make the tab alignment to match Vim's behavior. + if string.sub(next_node_text,1,1) == '\t' then + text = text .. ' ' + end + return text +end + -- Generates HTML from node `root` recursively. local function visit_node(root, level, lang_tree, headings, opt, stats) level = level or 0 @@ -506,12 +518,20 @@ local function visit_node(root, level, lang_tree, headings, opt, stats) if ignored then return text end - return ('%s%s'):format(ws(), helppage, url_encode(tagname), html_esc(tagname)) + local s = ('%s%s'):format(ws(), helppage, url_encode(tagname), html_esc(tagname)) + if node_name == 'taglink' and opt.old then + s = fix_tab_after_conceal(s, node_text(root:next_sibling())) + end + return s elseif vim.tbl_contains({'codespan', 'keycode'}, node_name) then if root:has_error() then return text end - return ('%s%s'):format(ws(), trimmed) + local s = ('%s%s'):format(ws(), trimmed) + if node_name == 'codespan' and opt.old then + s = fix_tab_after_conceal(s, node_text(root:next_sibling())) + end + return s elseif node_name == 'argument' then return ('%s{%s}'):format(ws(), text) elseif node_name == 'codeblock' then @@ -533,6 +553,10 @@ local function visit_node(root, level, lang_tree, headings, opt, stats) 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) + if opt.old then + s = fix_tab_after_conceal(s, node_text(root:next_sibling())) + end + if in_heading and prev ~= 'tag' then -- Start the container for tags in a heading. -- This makes "justify-content:space-between" right-align the tags. -- cgit From e6917306f6d3ba99747d14bea3f0b078631c5c0e Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Thu, 20 Oct 2022 09:20:02 -0400 Subject: docs: update vimdoc parser #20747 Remove the user-manual ToC from help.txt, because: 1. it duplicates usr_toc.txt 2. it is not what most readers are looking for in the main help page. fix https://github.com/neovim/tree-sitter-vimdoc/issues/49 fix https://github.com/neovim/tree-sitter-vimdoc/issues/50 fix https://github.com/neovim/tree-sitter-vimdoc/issues/51 --- scripts/gen_help_html.lua | 4 ++-- 1 file changed, 2 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 3a384bccf9..afc045dc96 100644 --- a/scripts/gen_help_html.lua +++ b/scripts/gen_help_html.lua @@ -519,7 +519,7 @@ local function visit_node(root, level, lang_tree, headings, opt, stats) return text end local s = ('%s%s'):format(ws(), helppage, url_encode(tagname), html_esc(tagname)) - if node_name == 'taglink' and opt.old then + if opt.old and node_name == 'taglink' then s = fix_tab_after_conceal(s, node_text(root:next_sibling())) end return s @@ -528,7 +528,7 @@ local function visit_node(root, level, lang_tree, headings, opt, stats) return text end local s = ('%s%s'):format(ws(), trimmed) - if node_name == 'codespan' and opt.old then + if opt.old and node_name == 'codespan' then s = fix_tab_after_conceal(s, node_text(root:next_sibling())) end return s -- cgit From 24c9561a68aa9b9cf8d8a503c5e85f63d7ebb543 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Fri, 21 Oct 2022 06:56:09 -0400 Subject: vim-patch: bump VIM_VERSION from 8.0 => 8.1 #20762 There are 6 remaining 8.0.x patches, tracked in: https://github.com/neovim/neovim/issues/5431 --- 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 afc045dc96..e5251b7f25 100644 --- a/scripts/gen_help_html.lua +++ b/scripts/gen_help_html.lua @@ -339,6 +339,7 @@ local function validate_link(node, bufnr, fname) return helppage, tagname, ignored 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 -- cgit From 5093f38c9fed9fae04234035ea253862ba8375ef Mon Sep 17 00:00:00 2001 From: Christian Clason Date: Tue, 22 Nov 2022 13:50:50 +0100 Subject: feat(help): highlighted codeblocks --- scripts/gen_help_html.lua | 7 ++++++- 1 file changed, 6 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 e5251b7f25..e5e99b308a 100644 --- a/scripts/gen_help_html.lua +++ b/scripts/gen_help_html.lua @@ -489,7 +489,7 @@ local function visit_node(root, level, lang_tree, headings, opt, stats) end return string.format('
\n%s\n
\n', text) elseif node_name == 'line' then - if parent ~= 'codeblock' and (is_blank(text) or is_noise(text, stats.noise_lines)) then + if parent ~= 'code' and (is_blank(text) or is_noise(text, stats.noise_lines)) then return '' -- Discard common "noise" lines. end -- XXX: Avoid newlines (too much whitespace) after block elements in old (preformatted) layout. @@ -535,7 +535,12 @@ local function visit_node(root, level, lang_tree, headings, opt, stats) return s elseif node_name == 'argument' then return ('%s{%s}'):format(ws(), text) + -- TODO: use language for proper syntax highlighted code blocks elseif node_name == 'codeblock' then + return text + elseif node_name == 'language' then + return '' + elseif node_name == 'code' then if is_blank(text) then return '' end -- cgit From 9e1187e4896bebb481a3f9595155f2a40adbc45e Mon Sep 17 00:00:00 2001 From: Christian Clason Date: Tue, 22 Nov 2022 21:23:33 +0100 Subject: feat(web): syntax highlighting via highlight.js download from https://highlightjs.org/download/ place `highlight/` directory next to `css/` style needs adapting for Neovim colors --- scripts/gen_help_html.lua | 17 ++++++++++++++--- 1 file changed, 14 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 e5e99b308a..532e28ebb8 100644 --- a/scripts/gen_help_html.lua +++ b/scripts/gen_help_html.lua @@ -35,6 +35,7 @@ local spell_dict = { lua = 'Lua', VimL = 'Vimscript', } +local language = nil local M = {} @@ -489,7 +490,7 @@ local function visit_node(root, level, lang_tree, headings, opt, stats) end return string.format('
\n%s\n
\n', text) elseif node_name == 'line' then - if parent ~= 'code' and (is_blank(text) or is_noise(text, stats.noise_lines)) then + if (parent ~= 'codeblock' or parent ~= 'code') and (is_blank(text) or is_noise(text, stats.noise_lines)) then return '' -- Discard common "noise" lines. end -- XXX: Avoid newlines (too much whitespace) after block elements in old (preformatted) layout. @@ -535,16 +536,23 @@ local function visit_node(root, level, lang_tree, headings, opt, stats) return s elseif node_name == 'argument' then return ('%s{%s}'):format(ws(), text) - -- TODO: use language for proper syntax highlighted code blocks elseif node_name == 'codeblock' then return text elseif node_name == 'language' then + language = node_text(root) return '' elseif node_name == 'code' then if is_blank(text) then return '' end - return ('
%s
'):format(trim(trim_indent(text), 2)) + local code + if language then + code = ('
%s
'):format(language,trim(trim_indent(text), 2)) + language = nil + else + code = ('
%s
'):format(trim(trim_indent(text), 2)) + end + return code elseif node_name == 'tag' then -- anchor if root:has_error() then return text @@ -690,6 +698,9 @@ local function gen_one(fname, to_fname, old, commit) + + + %s - Neovim docs -- cgit From ea39fc2cadc1d87109216da354a876427eeea31a Mon Sep 17 00:00:00 2001 From: Dave Lage Date: Thu, 8 Dec 2022 17:00:18 -0500 Subject: docs: dark/light color/accessibilty pass for generated html docs #21345 --- scripts/gen_help_html.lua | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) (limited to 'scripts/gen_help_html.lua') diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua index 532e28ebb8..3a0ed5ffc5 100644 --- a/scripts/gen_help_html.lua +++ b/scripts/gen_help_html.lua @@ -843,8 +843,14 @@ end local function gen_css(fname) local css = [[ :root { - --code-color: #008B8B; - --tag-color: gray; + --code-color: #004b4b; + --tag-color: #095943; + } + @media (prefers-color-scheme: dark) { + :root { + --code-color: #00c243; + --tag-color: #00b7b7; + } } @media (min-width: 40em) { .toc { @@ -863,11 +869,6 @@ local function gen_css(fname) display: block; } } - @media (prefers-color-scheme: dark) { - :root { - --code-color: cyan; - } - } .toc { /* max-width: 12rem; */ height: 85%; /* Scroll if there are too many items. https://github.com/neovim/neovim.github.io/issues/297 */ @@ -887,7 +888,7 @@ local function gen_css(fname) } h1, h2, h3, h4, h5 { font-family: sans-serif; - border-bottom: 1px solid #41464bd6; /*rgba(0, 0, 0, .9);*/ + border-bottom: 1px solid var(--tag-color); /*rgba(0, 0, 0, .9);*/ } h3, h4, h5 { border-bottom-style: dashed; -- cgit From 1c324cb1927e03b5a3584a8982e3d5029498f14e Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 11 Dec 2022 21:41:26 -0500 Subject: docs #20986 - https://github.com/neovim/tree-sitter-vimdoc v1.2.4 eliminates most errors in pi_netrw.txt, so we can remove that workaround from ignore_parse_error(). - improved codeblock --- scripts/gen_help_html.lua | 11 +++++------ 1 file changed, 5 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 3a0ed5ffc5..78fb917764 100644 --- a/scripts/gen_help_html.lua +++ b/scripts/gen_help_html.lua @@ -296,12 +296,11 @@ local function ignore_invalid(s) ) end -local function ignore_parse_error(s, fname) - local helpfile = vim.fs.basename(fname) - return (helpfile == 'pi_netrw.txt' +local function ignore_parse_error(s) + return ( -- Ignore parse errors for unclosed tag. -- This is common in vimdocs and is treated as plaintext by :help. - or s:find("^[`'|*]") + s:find("^[`'|*]") ) end @@ -370,7 +369,7 @@ local function visit_validate(root, level, lang_tree, opt, stats) end if node_name == 'ERROR' then - if ignore_parse_error(text, opt.fname) then + if ignore_parse_error(text) then return end -- Store the raw text to give context to the error report. @@ -582,7 +581,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, opt.fname) then + if ignore_parse_error(trimmed) then return text end -- cgit From 5841a97500bffa5a2b9eed2eb41025f5587790ba Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Tue, 3 Jan 2023 10:07:43 +0000 Subject: feat!: remove hardcopy Co-authored-by: Justin M. Keyes --- scripts/gen_help_html.lua | 1 - 1 file changed, 1 deletion(-) (limited to 'scripts/gen_help_html.lua') diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua index 78fb917764..4f42633c57 100644 --- a/scripts/gen_help_html.lua +++ b/scripts/gen_help_html.lua @@ -88,7 +88,6 @@ local exclude_invalid_urls = { ["http://papp.plan9.de"] = "syntax.txt", ["http://wiki.services.openoffice.org/wiki/Dictionaries"] = "spell.txt", ["http://www.adapower.com"] = "ft_ada.txt", - ["http://www.ghostscript.com/"] = "print.txt", ["http://www.jclark.com/"] = "quickfix.txt", } -- cgit From 1bd6e4469bb84bb49b342c10d9aa14ffd5f01187 Mon Sep 17 00:00:00 2001 From: Chris DeLuca <637174+bronzehedwick@users.noreply.github.com> Date: Wed, 4 Jan 2023 10:15:08 -0500 Subject: docs(website): soft wrap code blocks #21644 Use `white-space: pre-wrap` to preserve white space as per `pre`, but to allow line wrapping if the display runs out of horizontal space. This prevents lines overflowing their box, and causing horizontal scrolling across the entire page on small screens. This `pre-wrap` technique is used by GitHub to format code for mobile. See https://developer.mozilla.org/en-US/docs/Web/CSS/white-space#pre-wrap --- 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 4f42633c57..fa7c14eaa3 100644 --- a/scripts/gen_help_html.lua +++ b/scripts/gen_help_html.lua @@ -961,7 +961,7 @@ local function gen_css(fname) pre { /* Tabs are used in codeblocks only for indentation, not alignment, so we can aggressively shrink them. */ tab-size: 2; - white-space: pre; + white-space: pre-wrap; line-height: 1.3; /* Important for ascii art. */ overflow: visible; /* font-family: ui-monospace,SFMono-Regular,SF Mono,Menlo,Consolas,Liberation Mono,monospace; */ -- cgit From ef89f9fd46ab591183b7f59f31f5a2e55f7a526b Mon Sep 17 00:00:00 2001 From: Ching Pei Yang <59727193+horriblename@users.noreply.github.com> Date: Mon, 16 Jan 2023 13:39:19 +0100 Subject: docs: treesitter.add_directive, add_predicate #21206 --- scripts/gen_help_html.lua | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) (limited to 'scripts/gen_help_html.lua') diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua index fa7c14eaa3..2563f2f410 100644 --- a/scripts/gen_help_html.lua +++ b/scripts/gen_help_html.lua @@ -60,19 +60,18 @@ local exclude_invalid = { ["'previewpopup'"] = "quickref.txt", ["'pvp'"] = "quickref.txt", ["'string'"] = "eval.txt", - Query = "treesitter.txt", - ["eq?"] = "treesitter.txt", - ["lsp-request"] = "lsp.txt", - matchit = "vim_diff.txt", - ["matchit.txt"] = "help.txt", + Query = 'treesitter.txt', + ['eq?'] = 'treesitter.txt', + ['lsp-request'] = 'lsp.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", - ["vim.lsp.buf_request()"] = "lsp.txt", - ["vim.lsp.util.get_progress_messages()"] = "lsp.txt", - ["vim.treesitter.start()"] = "treesitter.txt", + ['v:_null_blob'] = 'builtin.txt', + ['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', } -- False-positive "invalid URLs". -- cgit