From f73bc880f4388e678eb4539b26e344159a0ee231 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 19 Oct 2022 06:02:01 -0700 Subject: [PATCH] [Backport release-0.8] feat(docs): update parser, HTML gen (#20737) 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 (cherry picked from commit 10ae8ccbf27eb2ad804b03f889c714a1955c64f6) --- CONTRIBUTING.md | 3 +++ cmake.deps/CMakeLists.txt | 4 ++-- runtime/doc/arabic.txt | 22 ++++++++++-------- runtime/doc/builtin.txt | 28 ++++++++++++++--------- runtime/doc/eval.txt | 8 ++++--- runtime/doc/if_cscop.txt | 2 +- runtime/doc/intro.txt | 2 +- runtime/doc/motion.txt | 2 +- runtime/doc/starting.txt | 30 +++++++++++++------------ scripts/gen_help_html.lua | 37 ++++++++++++++++++++++++------- test/functional/lua/help_spec.lua | 9 ++++---- 11 files changed, 93 insertions(+), 54 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e993d33c52..50acffbef4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,6 +12,9 @@ low-risk/isolated tasks: [Coverity](#coverity). - [Improve documentation](#documenting) - [Merge a Vim patch] (requires strong familiarity with Vim) + - NOTE: read the above link before sending improvements to "runtime files" (anything in `runtime/`). + - Vimscript and documentation files are (mostly) maintained by [Vim](https://github.com/vim/vim), not Nvim. + - Lua files are maintained by Nvim. Reporting problems ------------------ diff --git a/cmake.deps/CMakeLists.txt b/cmake.deps/CMakeLists.txt index 60d919b600..cf19d00a76 100644 --- a/cmake.deps/CMakeLists.txt +++ b/cmake.deps/CMakeLists.txt @@ -210,8 +210,8 @@ set(TREESITTER_LUA_SHA256 564594fe0ffd2f2fb3578a15019b723e1bc94ac82cb6a0103a6b3b set(TREESITTER_VIM_URL https://github.com/vigoux/tree-sitter-viml/archive/v0.2.0.tar.gz) set(TREESITTER_VIM_SHA256 608dcc31a7948cb66ae7f45494620e2e9face1af75598205541f80d782ec4501) -set(TREESITTER_HELP_URL https://github.com/neovim/tree-sitter-vimdoc/archive/v1.2.1.tar.gz) -set(TREESITTER_HELP_SHA256 43ddfebc311b399b284c2f1d4255a8ee3f870fc240ac08b89487c80135c63afe) +set(TREESITTER_HELP_URL https://github.com/neovim/tree-sitter-vimdoc/archive/v1.2.2.tar.gz) +set(TREESITTER_HELP_SHA256 d33b9447dae04f19e1ac50c94b78e305574c07f942791f70aea96fe266447c18) set(TREESITTER_URL https://github.com/tree-sitter/tree-sitter/archive/v0.20.7.tar.gz) set(TREESITTER_SHA256 b355e968ec2d0241bbd96748e00a9038f83968f85d822ecb9940cbe4c42e182e) diff --git a/runtime/doc/arabic.txt b/runtime/doc/arabic.txt index 0df861111c..0a80edb981 100644 --- a/runtime/doc/arabic.txt +++ b/runtime/doc/arabic.txt @@ -14,8 +14,9 @@ It is best to view this file with these settings within VIM's GUI: > :set arabicshape +------------------------------------------------------------------------------ Introduction ------------- + Arabic is a rather demanding language in which a number of special features are required. Characters are right-to-left oriented and ought to appear as such on the screen (i.e. from right to left). @@ -34,8 +35,9 @@ The commands, prompts and help files are not in Arabic, therefore the user interface remains the standard Vi interface. +------------------------------------------------------------------------------ Highlights ----------- + o Editing left-to-right files as in the original Vim hasn't changed. o Viewing and editing files in right-to-left windows. File @@ -64,8 +66,8 @@ o Proper Bidirectional functionality is possible given Vim is started within a Bidi capable terminal emulator. +------------------------------------------------------------------------------ Arabic Fonts *arabicfonts* ------------- Vim requires monospaced fonts of which there are many out there. Arabic requires ISO-8859-6 as well as Presentation Form-B fonts @@ -75,8 +77,8 @@ Do an Internet search or check www.arabeyes.org for further info on where to obtain the necessary Arabic fonts. +------------------------------------------------------------------------------ Font Installation ------------------ o Installation of fonts for X Window systems (Unix/Linux) @@ -88,8 +90,9 @@ o Installation of fonts for X Window systems (Unix/Linux) % xset +fp path_name_of_arabic_fonts_directory +------------------------------------------------------------------------------ Usage ------ + Prior to the actual usage of Arabic within Vim, a number of settings need to be accounted for and invoked. @@ -259,8 +262,8 @@ o Enable Arabic settings [short-cut] ':set arabicshape' to your vimrc file. +------------------------------------------------------------------------------ Keymap/Keyboard *arabickeymap* ---------------- The character/letter encoding used in Vim is the standard UTF-8. It is widely discouraged that any other encoding be used or even @@ -276,7 +279,7 @@ o Keyboard + CTRL-^ in insert/replace mode toggles between Arabic/Latin mode + Keyboard mapping is based on the Microsoft's Arabic keymap (the - de facto standard in the Arab world): + de facto standard in the Arab world): > +---------------------------------------------------------------------+ |! |@ |# |$ |% |^ |& |* |( |) |_ |+ || |~ ّ | @@ -291,17 +294,18 @@ o Keyboard |Z ~ |X ْ |C { |V } |B لآ |N آ |M ' |< , |> . |? ؟ | |z ئ |x ء |c ؤ |v ر |b لا |n ى |m ة |, و |. ز |/ ظ | +-------------------------------------------------+ +< +------------------------------------------------------------------------------ Restrictions ------------- o Vim in its GUI form does not currently support Bi-directionality (i.e. the ability to see both Arabic and Latin intermixed within the same line). +------------------------------------------------------------------------------ Known Bugs ----------- There is one known minor bug, diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt index 01ffd6ae6d..f4b5310dc0 100644 --- a/runtime/doc/builtin.txt +++ b/runtime/doc/builtin.txt @@ -6829,18 +6829,24 @@ serverstart([{address}]) *serverstart()* |RPC| messages. Clients can send |API| commands to the returned address to control Nvim. - Returns the address string (may differ from the requested - {address}). - - - If {address} contains a colon ":" it is interpreted as - a TCP/IPv4/IPv6 address where the last ":" separates host - and port (empty or zero assigns a random port). - - Else it is interpreted as a named pipe or Unix domain socket - path. If there are no slashes it is treated as a name and - appended to a generated path. - - If {address} is empty it generates a path. + Returns the address string (which may differ from the + {address} argument, see below). - Example named pipe: > + - If {address} has a colon (":") it is a TCP/IPv4/IPv6 address + where the last ":" separates host and port (empty or zero + assigns a random port). + - Else {address} is the path to a named pipe (except on Windows). + - If {address} has no slashes ("/") it is treated as the + "name" part of a generated path in this format: > + stdpath("run").."/{name}.{pid}.{counter}" +< - If {address} is omitted the name is "nvim". > + :echo serverstart() + => /tmp/nvim.bram/oknANW/nvim.15430.5 + +< Example bash command to list all Nvim servers: > + ls ${XDG_RUNTIME_DIR:-${TMPDIR}nvim.${USER}}/*/nvim.*.0 + +< Example named pipe: > if has('win32') echo serverstart('\\.\pipe\nvim-pipe-1234') else diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 6a9fb6d03c..30401c31f2 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -2141,9 +2141,11 @@ v:scrollstart String describing the script or function that caused the hit-enter prompt. *v:servername* *servername-variable* -v:servername Primary listen-address of the current Nvim instance, the first - item returned by |serverlist()|. Can be set by |--listen| or - |$NVIM_LISTEN_ADDRESS| (deprecated) at startup. +v:servername Primary listen-address of Nvim, the first item returned by + |serverlist()|. Usually this is the named pipe created by Nvim + at |startup| or given by |--listen| (or the deprecated + |$NVIM_LISTEN_ADDRESS| env var). + See also |serverstart()| |serverstop()|. Read-only. diff --git a/runtime/doc/if_cscop.txt b/runtime/doc/if_cscop.txt index 8947aefc1b..f520a03a86 100644 --- a/runtime/doc/if_cscop.txt +++ b/runtime/doc/if_cscop.txt @@ -324,7 +324,7 @@ place your cursor over the function name or C symbol and quickly query cscope for any matches. Or you may use the following scheme, inspired by Vim/Cscope tutorial from -Cscope Home Page (http://cscope.sourceforge.net/): > +Cscope Home Page (https://cscope.sourceforge.net/): > nmap s :cs find s =expand("") nmap g :cs find g =expand("") diff --git a/runtime/doc/intro.txt b/runtime/doc/intro.txt index 60c2b4c5dd..348c56ba70 100644 --- a/runtime/doc/intro.txt +++ b/runtime/doc/intro.txt @@ -373,7 +373,7 @@ notation meaning equivalent decimal value(s) ~ alt-key or meta-key *META* *ALT* * same as * command-key or "super" key * [count] display lines downward. |exclusive| motion. an operator, because it's not linewise. *-* -- [count] lines upward, on the first non-blank +`-` [count] lines upward, on the first non-blank character |linewise|. + or *+* diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt index baa60f431f..247b281cf6 100644 --- a/runtime/doc/starting.txt +++ b/runtime/doc/starting.txt @@ -401,18 +401,20 @@ accordingly, proceeding as follows: The |-V| argument can be used to display or log what happens next, useful for debugging the initializations. -3. Wait for UI to connect. +3. Start a server (unless |--listen| was given) and set |v:servername|. + +4. Wait for UI to connect. Nvim started with |--embed| waits for the UI to connect before proceeding to load user configuration. -4. Setup |default-mappings| and |default-autocmds|. Create |popup-menu|. +5. Setup |default-mappings| and |default-autocmds|. Create |popup-menu|. -5. Enable filetype and indent plugins. +6. Enable filetype and indent plugins. This does the same as the command: > :runtime! ftplugin.vim indent.vim < Skipped if the "-u NONE" command line argument was given. -6. Load user config (execute Ex commands from files, environment, …). +7. Load user config (execute Ex commands from files, environment, …). $VIMINIT environment variable is read as one Ex command line (separate multiple commands with '|' or ). *config* *init.vim* *init.lua* *vimrc* *exrc* @@ -456,19 +458,19 @@ accordingly, proceeding as follows: - The file ".nvimrc" - The file ".exrc" -7. Enable filetype detection. +8. Enable filetype detection. This does the same as the command: > :runtime! filetype.lua filetype.vim < Skipped if ":filetype off" was called or if the "-u NONE" command line argument was given. -8. Enable syntax highlighting. +9. Enable syntax highlighting. This does the same as the command: > :runtime! syntax/syntax.vim < Skipped if ":syntax off" was called or if the "-u NONE" command line argument was given. -9. Load the plugin scripts. *load-plugins* +10. Load the plugin scripts. *load-plugins* This does the same as the command: > :runtime! plugin/**/*.vim :runtime! plugin/**/*.lua @@ -498,21 +500,21 @@ accordingly, proceeding as follows: if packages have been found, but that should not add a directory ending in "after". -10. Set 'shellpipe' and 'shellredir' +11. Set 'shellpipe' and 'shellredir' The 'shellpipe' and 'shellredir' options are set according to the value of the 'shell' option, unless they have been set before. This means that Nvim will figure out the values of 'shellpipe' and 'shellredir' for you, unless you have set them yourself. -11. Set 'updatecount' to zero, if "-n" command argument used +12. Set 'updatecount' to zero, if "-n" command argument used -12. Set binary options if the |-b| flag was given. +13. Set binary options if the |-b| flag was given. -13. Read the |shada-file|. +14. Read the |shada-file|. -14. Read the quickfix file if the |-q| flag was given, or exit on failure. +15. Read the quickfix file if the |-q| flag was given, or exit on failure. -15. Open all windows +16. Open all windows When the |-o| flag was given, windows will be opened (but not displayed yet). When the |-p| flag was given, tab pages will be created (but not @@ -522,7 +524,7 @@ accordingly, proceeding as follows: Buffers for all windows will be loaded, without triggering |BufAdd| autocommands. -16. Execute startup commands +17. Execute startup commands If a |-t| flag was given, the tag is jumped to. Commands given with |-c| and |+cmd| are executed. The starting flag is reset, has("vim_starting") will now return zero. diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua index 0a6f4d7d0c..9470cd5dd8 100644 --- a/scripts/gen_help_html.lua +++ b/scripts/gen_help_html.lua @@ -73,6 +73,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 @@ -277,10 +294,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) @@ -322,7 +342,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 @@ -347,7 +367,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. @@ -362,7 +382,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 @@ -522,7 +543,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 diff --git a/test/functional/lua/help_spec.lua b/test/functional/lua/help_spec.lua index 242897336d..f5e67ec636 100644 --- a/test/functional/lua/help_spec.lua +++ b/test/functional/lua/help_spec.lua @@ -19,10 +19,11 @@ describe(':help docs', function() local rv = exec_lua([[return require('scripts.gen_help_html').validate('./build/runtime/doc')]]) -- Check that we actually found helpfiles. ok(rv.helpfiles > 100, '>100 :help files', rv.helpfiles) + eq({}, rv.invalid_links, 'found invalid :help tag links') + eq({}, rv.invalid_urls, 'found invalid URLs in :help docs') -- Check that parse errors did not increase wildly. -- TODO: Fix all parse errors in :help files. - ok(rv.err_count < 100, '<100 parse errors', rv.err_count) - eq({}, rv.invalid_links, exec_lua([[return 'found invalid :help tag links:\n'..vim.inspect(...)]], rv.invalid_links)) + ok(rv.err_count < 350, '<350 parse errors', rv.err_count) end) it('gen_help_html.lua generates HTML', function() @@ -43,7 +44,7 @@ describe(':help docs', function() tmpdir ) eq(4, #rv.helpfiles) - ok(rv.err_count == 0, '0 parse errors', rv.err_count) - eq({}, rv.invalid_links, exec_lua([[return 'found invalid :help tag links:\n'..vim.inspect(...)]], rv.invalid_links)) + ok(rv.err_count < 25, '<25 parse errors', rv.err_count) + eq({}, rv.invalid_links, 'found invalid :help tag links') end) end)