mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2026-07-22 00:51:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge #24087 from justinmk/doc

Browse Source 
docs: lsp, fix errors, gen_help_html features
This commit is contained in:
Justin M. Keyes
2023-06-22 01:51:20 -07:00
committed by GitHub
parent 4d3a04279d b0cf9c5fee
commit 130b8c801a
10 changed files with 260 additions and 318 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
runtime/doc/autocmd.txt
View File

@@ -16,7 +16,7 @@ For a basic explanation, see section |40.3| in the user manual.
You can specify commands to be executed automatically when reading or writing
a file, when entering or leaving a buffer or window, and when exiting Vim.
For example, you can create an autocommand to set the 'cindent' option for
files matching *.c. You can also use autocommands to implement advanced
files matching `*.c`. You can also use autocommands to implement advanced
features, such as editing compressed files (see |gzip-example|). The usual
place to put autocommands is in your vimrc file.
@@ -197,7 +197,7 @@ For READING FILES there are four kinds of events possible:
Vim uses only one of these four kinds when reading a file. The "Pre" and
"Post" events are both triggered, before and after reading the file.
Note that the autocommands for the *ReadPre events and all the Filter events
Note that the autocommands for the "*ReadPre" events and all the Filter events
are not allowed to change the current buffer (you will get an error message if
this happens). This is to prevent the file to be read into the wrong buffer.
@@ -1001,7 +1001,7 @@ TextChangedT After a change was made to the text in the
*TextYankPost*
TextYankPost Just after a |yank| or |deleting| command, but not
if the black hole register |quote_| is used nor
for |setreg()|. Pattern must be *.
for |setreg()|. Pattern must be "*".
Sets these |v:event| keys:
inclusive
operator
@@ -1417,8 +1417,8 @@ When there is a matching "*Cmd" autocommand, it is assumed it will do the
writing. No further writing is done and the other events are not triggered.
|Cmd-event|
Note that the *WritePost commands should undo any changes to the buffer that
were caused by the *WritePre commands; otherwise, writing the file will have
Note that the "*WritePost" commands should undo any changes to the buffer that
were caused by the "*WritePre" commands; otherwise, writing the file will have
the side effect of changing the buffer.
Before executing the autocommands, the buffer from which the lines are to be
@@ -1426,15 +1426,15 @@ written temporarily becomes the current buffer. Unless the autocommands
change the current buffer or delete the previously current buffer, the
previously current buffer is made the current buffer again.
The *WritePre and *AppendPre autocommands must not delete the buffer from
The "*WritePre" and "*AppendPre" autocommands must not delete the buffer from
which the lines are to be written.
The '[ and '] marks have a special position:
- Before the *ReadPre event the '[ mark is set to the line just above where
- Before the "*ReadPre" event the '[ mark is set to the line just above where
the new lines will be inserted.
- Before the *ReadPost event the '[ mark is set to the first line that was
- Before the "*ReadPost" event the '[ mark is set to the first line that was
just read, the '] mark to the last line.
- Before executing the *WriteCmd, *WritePre and *AppendPre autocommands the '[
- Before executing the "*WriteCmd", "*WritePre" and "*AppendPre" autocommands the '[
mark is set to the first line that will be written, the '] mark to the last
line.
Careful: '[ and '] change when using commands that change the buffer.
@@ -1542,7 +1542,7 @@ To read a skeleton (template) file when opening a new file: >
:autocmd BufNewFile *.h 0r ~/vim/skeleton.h
:autocmd BufNewFile *.java 0r ~/vim/skeleton.java
To insert the current date and time in a *.html file when writing it: >
To insert the current date and time in a "*.html" file when writing it: >
:autocmd BufWritePre,FileWritePre *.html ks|call LastMod()|'s
:fun LastMod()

2
runtime/doc/eval.txt
View File

@@ -39,7 +39,7 @@ List An ordered sequence of items, see |List| for details.
Dictionary An associative, unordered array: Each entry has a key and a
value. |Dictionary|
Examples:
Examples: >
{"blue": "#0000ff", "red": "#ff0000"}
#{blue: "#0000ff", red: "#ff0000"}

66
runtime/doc/filetype.txt
View File

@@ -54,9 +54,9 @@ you can either set the 'filetype' option manually, or add a modeline to your
file. Example, for an IDL file use the command: >
:set filetype=idl
or add this |modeline| to the file:
/* vim: set filetype=idl : */ ~
or add this |modeline| to the file: >
/* vim: set filetype=idl : */
<
*:filetype-plugin-on*
You can enable loading the plugin files for specific file types with: >
:filetype plugin on
@@ -136,38 +136,38 @@ what kind of file it is. This doesn't always work. A number of global
variables can be used to overrule the filetype used for certain extensions:
file name variable ~
*.asa g:filetype_asa |ft-aspvbs-syntax| |ft-aspperl-syntax|
*.asm g:asmsyntax |ft-asm-syntax|
*.asp g:filetype_asp |ft-aspvbs-syntax| |ft-aspperl-syntax|
*.bas g:filetype_bas |ft-basic-syntax|
*.cfg g:filetype_cfg
*.cls g:filetype_cls
*.csh g:filetype_csh |ft-csh-syntax|
*.dat g:filetype_dat
*.frm g:filetype_frm |ft-form-syntax|
*.fs g:filetype_fs |ft-forth-syntax|
*.i g:filetype_i |ft-progress-syntax|
*.inc g:filetype_inc
*.lsl g:filetype_lsl
*.m g:filetype_m |ft-mathematica-syntax|
*.mod g:filetype_mod
*.p g:filetype_p |ft-pascal-syntax|
*.pl g:filetype_pl
*.pp g:filetype_pp |ft-pascal-syntax|
*.prg g:filetype_prg
*.r g:filetype_r
*.sig g:filetype_sig
*.sql g:filetype_sql |ft-sql-syntax|
*.src g:filetype_src
*.sys g:filetype_sys
*.sh g:bash_is_sh |ft-sh-syntax|
*.tex g:tex_flavor |ft-tex-plugin|
*.typ g:filetype_typ
*.w g:filetype_w |ft-cweb-syntax|
`*.asa` g:filetype_asa |ft-aspvbs-syntax| |ft-aspperl-syntax|
`*.asm` g:asmsyntax |ft-asm-syntax|
`*.asp` g:filetype_asp |ft-aspvbs-syntax| |ft-aspperl-syntax|
`*.bas` g:filetype_bas |ft-basic-syntax|
`*.cfg` g:filetype_cfg
`*.cls` g:filetype_cls
`*.csh` g:filetype_csh |ft-csh-syntax|
`*.dat` g:filetype_dat
`*.frm` g:filetype_frm |ft-form-syntax|
`*.fs` g:filetype_fs |ft-forth-syntax|
`*.i` g:filetype_i |ft-progress-syntax|
`*.inc` g:filetype_inc
`*.lsl` g:filetype_lsl
`*.m` g:filetype_m |ft-mathematica-syntax|
`*.mod` g:filetype_mod
`*.p` g:filetype_p |ft-pascal-syntax|
`*.pl` g:filetype_pl
`*.pp` g:filetype_pp |ft-pascal-syntax|
`*.prg` g:filetype_prg
`*.r` g:filetype_r
`*.sig` g:filetype_sig
`*.sql` g:filetype_sql |ft-sql-syntax|
`*.src` g:filetype_src
`*.sys` g:filetype_sys
`*.sh` g:bash_is_sh |ft-sh-syntax|
`*.tex` g:tex_flavor |ft-tex-plugin|
`*.typ` g:filetype_typ
`*.w` g:filetype_w |ft-cweb-syntax|
For a few filetypes the global variable is used only when the filetype could
not be detected:
*.r g:filetype_r |ft-rexx-syntax|
`*.r` g:filetype_r |ft-rexx-syntax|
*filetype-ignore*
To avoid that certain files are being inspected, the g:ft_ignore_pat variable
@@ -881,7 +881,7 @@ file: |ft_sql.txt|.
TEX *ft-tex-plugin* *g:tex_flavor*
If the first line of a *.tex file has the form >
If the first line of a `*.tex` file has the form >
%&<format>
then this determined the file type: plaintex (for plain TeX), context (for
ConTeXt), or tex (for LaTeX). Otherwise, the file is searched for keywords to

226
runtime/doc/lsp.txt
View File

@@ -24,26 +24,23 @@ QUICKSTART *lsp-quickstart*
Nvim provides an LSP client, but the servers are provided by third parties.
Follow these steps to get LSP features:
1. Install language servers using your package manager or by
following the upstream installation instruction.
1. Install language servers using your package manager or by following the
upstream installation instruction. You can find language servers here:
https://microsoft.github.io/language-server-protocol/implementors/servers/
A list of language servers is available at:
2. Configure the LSP client per language server. See |vim.lsp.start()| or use
this minimal example as a guide: >lua
https://microsoft.github.io/language-server-protocol/implementors/servers/
2. Configure the LSP client per language server.
A minimal example:
>lua
vim.lsp.start({
name = 'my-server-name',
cmd = {'name-of-language-server-executable'},
root_dir = vim.fs.dirname(vim.fs.find({'setup.py', 'pyproject.toml'}, { upward = true })[1]),
})
<
See |vim.lsp.start()| for details.
3. Check that the server attached to the buffer: >
:lua =vim.lsp.get_active_clients()
3. Configure keymaps and autocmds to utilize LSP features.
See |lsp-config|.
4. Configure keymaps and autocmds to use LSP features. See |lsp-config|.
*lsp-config*
*lsp-defaults*
@@ -103,11 +100,9 @@ calls behind capability checks:
<
To learn what capabilities are available you can run the following command in
a buffer with a started LSP client:
a buffer with a started LSP client: >vim
>vim
:lua =vim.lsp.get_active_clients()[1].server_capabilities
<
Full list of features provided by default can be found in |lsp-buf|.
@@ -115,26 +110,20 @@ Full list of features provided by default can be found in |lsp-buf|.
FAQ *lsp-faq*
- Q: How to force-reload LSP?
A: Stop all clients, then reload the buffer. >vim
- A: Stop all clients, then reload the buffer. >vim
:lua vim.lsp.stop_client(vim.lsp.get_active_clients())
:edit
- Q: Why isn't completion working?
A: In the buffer where you want to use LSP, check that 'omnifunc' is set to
"v:lua.vim.lsp.omnifunc": >vim
:verbose set omnifunc?
< Some other plugin may be overriding the option. To avoid that, you could
set the option in an |after-directory| ftplugin, e.g.
"after/ftplugin/python.vim".
- A: In the buffer where you want to use LSP, check that 'omnifunc' is set to
"v:lua.vim.lsp.omnifunc": `:verbose set omnifunc?`
- Some other plugin may be overriding the option. To avoid that you could
set the option in an |after-directory| ftplugin, e.g.
"after/ftplugin/python.vim".
- Q: How do I run a request synchronously (e.g. for formatting on file save)?
A: Check if the function has an `async` parameter and set the value to
false.
E.g. code formatting: >vim
- A: Check if the function has an `async` parameter and set the value to
false. E.g. code formatting: >vim
" Auto-format *.rs (rust) files prior to saving them
" (async = false is the default for format)
@@ -142,7 +131,7 @@ FAQ *lsp-faq*
<
*lsp-vs-treesitter*
- Q: How do LSP and Treesitter compare?
A: LSP requires a client and language server. The language server uses
- A: LSP requires a client and language server. The language server uses
semantic analysis to understand code at a project level. This provides
language servers with the ability to rename across files, find
definitions in external libraries and more.
@@ -173,129 +162,72 @@ when creating a new client. Keys are LSP method names: >vim
*lsp-method*
Methods are the names of requests and notifications as defined by the LSP
specification. These LSP requests/notifications are defined by default:
specification. These LSP requests/notifications are defined by default in the
Nvim LSP client (but depends on server support):
callHierarchy/incomingCalls
callHierarchy/outgoingCalls
textDocument/codeAction
textDocument/completion
textDocument/declaration*
textDocument/definition
textDocument/documentHighlight
textDocument/documentSymbol
textDocument/formatting
textDocument/hover
textDocument/implementation*
textDocument/inlayHint
textDocument/publishDiagnostics
textDocument/rangeFormatting
textDocument/references
textDocument/rename
textDocument/semanticTokens/full
textDocument/semanticTokens/full/delta
textDocument/signatureHelp
textDocument/typeDefinition*
window/logMessage
window/showMessage
window/showDocument
window/showMessageRequest
workspace/applyEdit
workspace/inlayHint/refresh
workspace/symbol
* NOTE: These are sometimes not implemented by servers.
- callHierarchy/incomingCalls
- callHierarchy/outgoingCalls
- textDocument/codeAction
- textDocument/completion
- textDocument/declaration*
- textDocument/definition
- textDocument/documentHighlight
- textDocument/documentSymbol
- textDocument/formatting
- textDocument/hover
- textDocument/implementation*
- textDocument/inlayHint
- textDocument/publishDiagnostics
- textDocument/rangeFormatting
- textDocument/references
- textDocument/rename
- textDocument/semanticTokens/full
- textDocument/semanticTokens/full/delta
- textDocument/signatureHelp
- textDocument/typeDefinition*
- window/logMessage
- window/showMessage
- window/showDocument
- window/showMessageRequest
- workspace/applyEdit
- workspace/inlayHint/refresh
- workspace/symbol
*lsp-handler*
LSP handlers are functions that handle |lsp-response|s to requests made by Nvim
to the server. (Notifications, as opposed to requests, are fire-and-forget:
there is no response, so they can't be handled. |lsp-notification|)
LSP handlers are functions with signatures designed to handle LSP responses
and notifications.
Each response handler has this signature: >
For |lsp-response|, each |lsp-handler| has this signature: >
function(err, result, ctx, config)
function(err, result, ctx, config)
<
Parameters: ~
{err} (table|nil)
When the language server is unable to complete a
request, a table with information about the error is
sent. Otherwise, it is `nil`. See |lsp-response|.
{result} (Result | Params | nil)
When the language server is able to successfully
complete a request, this contains the `result` key of
the response. See |lsp-response|.
{ctx} (table)
Context describes additional calling state associated
with the handler. It consists of the following key,
value pairs:
{method} (string)
The |lsp-method| name.
{client_id} (number)
The ID of the |vim.lsp.client|.
{bufnr} (Buffer)
Buffer handle, or 0 for current.
{params} (table|nil)
The parameters used in the original
request which resulted in this handler
call.
{version} (number) Document version at time of
request. Handlers can compare this to the
current document version to check if the
response is "stale".
See also |b:changedtick|.
{config} (table)
Configuration for the handler.
Each handler can define its own configuration table
that allows users to customize the behavior of a
particular handler.
To configure a particular |lsp-handler|, see:
|lsp-handler-configuration|
- {err} (table|nil) Error info dict, or `nil` if the request
completed.
- {result} (Result | Params | nil) `result` key of the |lsp-response| or
`nil` if the request failed.
- {ctx} (table) Table of calling state associated with the
handler, with these keys:
- {method} (string) |lsp-method| name.
- {client_id} (number) |vim.lsp.client| identifier.
- {bufnr} (Buffer) Buffer handle.
- {params} (table|nil) Request parameters table.
- {version} (number) Document version at time of
request. Handlers can compare this to the
current document version to check if the
response is "stale". See also |b:changedtick|.
- {config} (table) Handler-defined configuration table, which allows
users to customize handler behavior.
For an example, see:
|vim.lsp.diagnostic.on_publish_diagnostics()|
To configure a particular |lsp-handler|, see:
|lsp-handler-configuration|
Returns: ~
The |lsp-handler| can respond by returning two values: `result, err`
Where `err` must be shaped like an RPC error:
`{ code, message, data? }`
You can use |vim.lsp.rpc.rpc_response_error()| to create this object.
For |lsp-notification|, each |lsp-handler| has this signature: >
function(err, result, ctx, config)
<
Parameters: ~
{err} (nil)
This is always `nil`.
See |lsp-notification|
{result} (Result)
This contains the `params` key of the notification.
See |lsp-notification|
{ctx} (table)
Context describes additional calling state associated
with the handler. It consists of the following key,
value pairs:
{method} (string)
The |lsp-method| name.
{client_id} (number)
The ID of the |vim.lsp.client|.
{config} (table)
Configuration for the handler.
Each handler can define its own configuration table
that allows users to customize the behavior of a
particular handler.
For an example, see:
|vim.lsp.diagnostic.on_publish_diagnostics()|
To configure a particular |lsp-handler|, see:
|lsp-handler-configuration|
Returns: ~
The |lsp-handler|'s return value will be ignored.
Two values `result, err` where `err` is shaped like an RPC error: >
{ code, message, data? }
< You can use |vim.lsp.rpc.rpc_response_error()| to create this object.
*lsp-handler-configuration*
@@ -419,12 +351,12 @@ name: >lua
<
*lsp-response*
For the format of the response message, see:
https://microsoft.github.io/language-server-protocol/specifications/specification-current/#responseMessage
LSP response shape:
https://microsoft.github.io/language-server-protocol/specifications/specification-current/#responseMessage
*lsp-notification*
For the format of the notification message, see:
https://microsoft.github.io/language-server-protocol/specifications/specification-current/#notificationMessage
LSP notification shape:
https://microsoft.github.io/language-server-protocol/specifications/specification-current/#notificationMessage
*lsp-on-list-handler*

12
runtime/doc/options.txt
View File

@@ -1449,7 +1449,7 @@ A jump table for the options with a short description can be found at |Q_op|.
*'completeslash'* *'csl'*
'completeslash' 'csl' string (default: "")
local to buffer
{only for MS-Windows}
only for MS-Windows
When this option is set it overrules 'shellslash' for completion:
- When this option is set to "slash", a forward slash is used for path
completion in insert mode. This is useful when editing HTML tag, or
@@ -3741,7 +3741,7 @@ A jump table for the options with a short description can be found at |Q_op|.
*'linespace'* *'lsp'*
'linespace' 'lsp' number (default 0)
global
{only in the GUI}
only in the GUI
Number of pixel lines inserted between characters. Useful if the font
uses the full character cell height, making lines touch each other.
When non-zero there is room for underlining.
@@ -4187,7 +4187,7 @@ A jump table for the options with a short description can be found at |Q_op|.
*'mousehide'* *'mh'* *'nomousehide'* *'nomh'*
'mousehide' 'mh' boolean (default on)
global
{only works in the GUI}
only in the GUI
When on, the mouse pointer is hidden when characters are typed.
The mouse pointer is restored when the mouse is moved.
@@ -4426,7 +4426,7 @@ A jump table for the options with a short description can be found at |Q_op|.
*'opendevice'* *'odev'* *'noopendevice'* *'noodev'*
'opendevice' 'odev' boolean (default off)
global
{only for Windows}
only for Windows
Enable reading and writing from devices. This may get Vim stuck on a
device that can be opened but doesn't actually do the I/O. Therefore
it is off by default.
@@ -5323,7 +5323,7 @@ A jump table for the options with a short description can be found at |Q_op|.
*'shellslash'* *'ssl'* *'noshellslash'* *'nossl'*
'shellslash' 'ssl' boolean (default off)
global
{only for MS-Windows}
only for MS-Windows
When set, a forward slash is used when expanding file names. This is
useful when a Unix-like shell is used instead of cmd.exe. Backward
slashes can still be typed, but they are changed to forward slashes by
@@ -7054,7 +7054,7 @@ A jump table for the options with a short description can be found at |Q_op|.
*'winaltkeys'* *'wak'*
'winaltkeys' 'wak' string (default "menu")
global
{only used in Win32}
only used in Win32
Some GUI versions allow the access to menu entries by using the ALT
key in combination with a character that appears underlined in the
menu. This conflicts with the use of the ALT key for mappings and

10
runtime/doc/pattern.txt
View File

@@ -432,8 +432,6 @@ after: \v \m \M \V matches ~
\\ \\ \\ \\ literal backslash
\{ { { { literal curly brace
{only Vim supports \m, \M, \v and \V}
If you want to you can make a pattern immune to the 'magic' option being set
or not by putting "\m" or "\M" at the start of the pattern.
@@ -455,7 +453,7 @@ More explanation and examples below, follow the links. *E64* *E871*
\{n} \{n} n exactly
\{n,} \{n,} at least n as many as possible
\{,m} \{,m} 0 to m as many as possible
\{} \{} 0 or more as many as possible (same as *)
\{} \{} 0 or more as many as possible (same as "*")
|/\{-| \{-n,m} \{-n,m} n to m as few as possible
\{-n} \{-n} n exactly
@@ -633,7 +631,7 @@ overview.
\{n} Matches n of the preceding atom
\{n,} Matches at least n of the preceding atom, as many as possible
\{,m} Matches 0 to m of the preceding atom, as many as possible
\{} Matches 0 or more of the preceding atom, as many as possible (like *)
\{} Matches 0 or more of the preceding atom, as many as possible (like "*")
*/\{-*
\{-n,m} matches n to m of the preceding atom, as few as possible
\{-n} matches n of the preceding atom
@@ -1256,7 +1254,6 @@ letters only.
When "\c" appears anywhere in the pattern, the whole pattern is handled like
'ignorecase' is on. The actual value of 'ignorecase' and 'smartcase' is
ignored. "\C" does the opposite: Force matching case for the whole pattern.
{only Vim supports \c and \C}
Note that 'ignorecase', "\c" and "\C" are not used for the character classes.
Examples:
@@ -1338,11 +1335,10 @@ difference between them is mostly just notation; here's a summary of where
they differ:
Capability in Vimspeak in Perlspeak ~
----------------------------------------------------------------
force case insensitivity \c (?i)
force case sensitivity \C (?-i)
backref-less grouping \%(atom\) (?:atom)
conservative quantifiers \{-n,m} *?, +?, ??, {}?
conservative quantifiers \{-n,m} `*?,` +?, ??, {}?
0-width match atom\@= (?=atom)
0-width non-match atom\@! (?!atom)
0-width preceding match atom\@<= (?<=atom)

92
runtime/doc/syntax.txt
View File

@@ -197,19 +197,19 @@ be preferred names for highlight groups that are common for many languages.
These are the suggested group names (if syntax highlighting works properly
you can see the actual color, except for "Ignore"):
*Comment any comment
Comment any comment
*Constant any constant
Constant any constant
String a string constant: "this is a string"
Character a character constant: 'c', '\n'
Number a number constant: 234, 0xff
Boolean a boolean constant: TRUE, false
Float a floating point constant: 2.3e10
*Identifier any variable name
Identifier any variable name
Function function name (also: methods for classes)
*Statement any statement
Statement any statement
Conditional if, then, else, endif, switch, etc.
Repeat for, do, while, etc.
Label case, default, etc.
@@ -217,31 +217,31 @@ you can see the actual color, except for "Ignore"):
Keyword any other keyword
Exception try, catch, throw
*PreProc generic Preprocessor
PreProc generic Preprocessor
Include preprocessor #include
Define preprocessor #define
Macro same as Define
PreCondit preprocessor #if, #else, #endif, etc.
*Type int, long, char, etc.
Type int, long, char, etc.
StorageClass static, register, volatile, etc.
Structure struct, union, enum, etc.
Typedef A typedef
*Special any special symbol
Special any special symbol
SpecialChar special character in a constant
Tag you can use CTRL-] on this
Delimiter character that needs attention
SpecialComment special things inside a comment
Debug debugging statements
*Underlined text that stands out, HTML links
Underlined text that stands out, HTML links
*Ignore left blank, hidden |hl-Ignore|
Ignore left blank, hidden |hl-Ignore|
*Error any erroneous construct
Error any erroneous construct
*Todo anything that needs extra attention; mostly the
Todo anything that needs extra attention; mostly the
keywords TODO FIXME and XXX
The names marked with * are the preferred groups; the others are minor groups.
@@ -893,7 +893,7 @@ nasm_no_warn potentially risky syntax not as ToDo
ASPPERL and ASPVBS *ft-aspperl-syntax* *ft-aspvbs-syntax*
*.asp and *.asa files could be either Perl or Visual Basic script. Since it's
`*.asp` and `*.asa` files could be either Perl or Visual Basic script. Since it's
hard to detect this you can set two global variables to tell Vim what you are
using. For Perl script use: >
:let g:filetype_asa = "aspperl"
@@ -979,7 +979,7 @@ Variable Highlight ~
*c_ansi_typedefs* ... but do standard ANSI types
*c_ansi_constants* ... but do standard ANSI constants
*c_no_utf* don't highlight \u and \U in strings
*c_syntax_for_h* for *.h files use C syntax instead of C++ and use objc
*c_syntax_for_h* for `*.h` files use C syntax instead of C++ and use objc
syntax instead of objcpp
*c_no_if0* don't highlight "#if 0" blocks as comments
*c_no_cformat* don't highlight %-formats in strings
@@ -987,7 +987,7 @@ Variable Highlight ~
*c_no_c11* don't highlight C11 standard items
*c_no_bsd* don't highlight BSD specific types
When 'foldmethod' is set to "syntax" then /* */ comments and { } blocks will
When 'foldmethod' is set to "syntax" then `/* */` comments and { } blocks will
become a fold. If you don't want comments to become a fold use: >
:let c_no_comment_fold = 1
"#if 0" blocks are also folded, unless: >
@@ -1034,7 +1034,7 @@ CH *ch.vim* *ft-ch-syntax*
C/C++ interpreter. Ch has similar syntax highlighting to C and builds upon
the C syntax file. See |c.vim| for all the settings that are available for C.
By setting a variable you can tell Vim to use Ch syntax for *.h files, instead
By setting a variable you can tell Vim to use Ch syntax for `*.h` files, instead
of C or C++: >
:let ch_syntax_for_h = 1
@@ -1296,7 +1296,7 @@ dosbatch_colons_comment variable to anything: >
:let dosbatch_colons_comment = 1
There is an option that covers whether *.btm files should be detected as type
There is an option that covers whether `*.btm` files should be detected as type
"dosbatch" (MS-DOS batch files) or type "btm" (4DOS batch files). The latter
is used by default. You may select the former with the following line: >
@@ -1427,13 +1427,13 @@ Euphoria version 3.1.1 (https://www.rapideuphoria.com/) is still necessary
for developing applications for the DOS platform, which Euphoria version 4
(https://www.openeuphoria.org/) does not support.
The following file extensions are auto-detected as Euphoria file type:
The following file extensions are auto-detected as Euphoria file type: >
*.e, *.eu, *.ew, *.ex, *.exu, *.exw
*.E, *.EU, *.EW, *.EX, *.EXU, *.EXW
To select syntax highlighting file for Euphoria, as well as for
auto-detecting the *.e and *.E file extensions as Euphoria file type,
auto-detecting the `*.e` and `*.E` file extensions as Euphoria file type,
add the following line to your startup file: >
:let g:filetype_euphoria = "euphoria3"
@@ -1442,7 +1442,7 @@ add the following line to your startup file: >
:let g:filetype_euphoria = "euphoria4"
Elixir and Euphoria share the *.ex file extension. If the filetype is
Elixir and Euphoria share the `*.ex` file extension. If the filetype is
specifically set as Euphoria with the g:filetype_euphoria variable, or the
file is determined to be Euphoria based on keywords in the file, then the
filetype will be set as Euphoria. Otherwise, the filetype will default to
@@ -1469,11 +1469,11 @@ ELIXIR *elixir.vim* *ft-elixir-syntax*
Elixir is a dynamic, functional language for building scalable and
maintainable applications.
The following file extensions are auto-detected as Elixir file types:
The following file extensions are auto-detected as Elixir file types: >
*.ex, *.exs, *.eex, *.leex, *.lock
Elixir and Euphoria share the *.ex file extension. If the filetype is
Elixir and Euphoria share the `*.ex` file extension. If the filetype is
specifically set as Euphoria with the g:filetype_euphoria variable, or the
file is determined to be Euphoria based on keywords in the file, then the
filetype will be set as Euphoria. Otherwise, the filetype will default to
@@ -1905,7 +1905,7 @@ IA64 *ia64.vim* *intel-itanium* *ft-ia64-syntax*
Highlighting for the Intel Itanium 64 assembly language. See |asm.vim| for
how to recognize this filetype.
To have *.inc files be recognized as IA64, add this to your vimrc file: >
To have `*.inc` files be recognized as IA64, add this to your vimrc file: >
:let g:filetype_inc = "ia64"
@@ -2118,7 +2118,7 @@ set "lite_minlines" to the value you desire. Example: >
LPC *lpc.vim* *ft-lpc-syntax*
LPC stands for a simple, memory-efficient language: Lars Pensjö C. The
file name of LPC is usually *.c. Recognizing these files as LPC would bother
file name of LPC is usually `*.c`. Recognizing these files as LPC would bother
users writing only C programs. If you want to use LPC syntax in Vim, you
should set a variable in your vimrc file: >
@@ -2153,7 +2153,7 @@ For LPC4 series of LPC: >
For uLPC series of LPC:
uLPC has been developed to Pike, so you should use Pike syntax
instead, and the name of your source file should be *.pike
instead, and the name of your source file should be `*.pike`
LUA *lua.vim* *ft-lua-syntax*
@@ -2230,7 +2230,7 @@ the start of a region, for example 500 lines: >
MATHEMATICA *mma.vim* *ft-mma-syntax* *ft-mathematica-syntax*
Empty *.m files will automatically be presumed to be Matlab files unless you
Empty `*.m` files will automatically be presumed to be Matlab files unless you
have the following in your vimrc: >
let filetype_m = "mma"
@@ -2437,7 +2437,7 @@ keywords, etc): >
The option pascal_symbol_operator controls whether symbol operators such as +,
*, .., etc. are displayed using the Operator color or not. To colorize symbol
`*`, .., etc. are displayed using the Operator color or not. To colorize symbol
operators, add the following line to your startup file: >
:let pascal_symbol_operator=1
@@ -2600,7 +2600,7 @@ x = 0 to sync from start.
PLAINTEX *plaintex.vim* *ft-plaintex-syntax*
TeX is a typesetting language, and plaintex is the file type for the "plain"
variant of TeX. If you never want your *.tex files recognized as plain TeX,
variant of TeX. If you never want your `*.tex` files recognized as plain TeX,
see |ft-tex-plugin|.
This syntax file has the option >
@@ -3149,7 +3149,7 @@ The syntax/sh.vim file provides several levels of syntax-based folding: >
let g:sh_fold_enabled= 1 (enable function folding)
let g:sh_fold_enabled= 2 (enable heredoc folding)
let g:sh_fold_enabled= 4 (enable if/do/for folding)
>
then various syntax items (ie. HereDocuments and function bodies) become
syntax-foldable (see |:syn-fold|). You also may add these together
to get multiple types of folding: >
@@ -3446,8 +3446,8 @@ has a starred form (ie. eqnarray*).
*tex-style* *b:tex_stylish*
Tex: Starting a New Style? ~
One may use "\makeatletter" in *.tex files, thereby making the use of "@" in
commands available. However, since the *.tex file doesn't have one of the
One may use "\makeatletter" in `*.tex` files, thereby making the use of "@" in
commands available. However, since the `*.tex` file doesn't have one of the
following suffices: sty cls clo dtx ltx, the syntax highlighting will flag
such use of @ as an error. To solve this: >
@@ -3491,7 +3491,7 @@ substitution will not be made.
Tex: Controlling iskeyword~
Normally, LaTeX keywords support 0-9, a-z, A-z, and 192-255 only. Latex
keywords don't support the underscore - except when in *.sty files. The
keywords don't support the underscore - except when in `*.sty` files. The
syntax highlighting script handles this with the following logic:
* If g:tex_stylish exists and is 1
@@ -3715,7 +3715,7 @@ Vim understands three types of syntax items:
Several syntax ITEMs can be put into one syntax GROUP. For a syntax group
you can give highlighting attributes. For example, you could have an item
to define a "/* .. */" comment and another one that defines a "// .." comment,
to define a `/* .. */` comment and another one that defines a "// .." comment,
and put them both in the "Comment" group. You can then specify that a
"Comment" will be in bold font and have a blue color. You are free to make
one highlight group for one syntax item, or put all items into one group.
@@ -4473,19 +4473,19 @@ Notes:
matched. This doesn't work: "a\nb"ms=e. You can make the highlighting
start in another line, this does work: "a\nb"hs=e.
Example (match a comment but don't highlight the /* and */): >
Example (match a comment but don't highlight the `/* and */`): >vim
:syntax region Comment start="/\*"hs=e+1 end="\*/"he=s-1
<
< >
/* this is a comment */
^^^^^^^^^^^^^^^^^^^ highlighted
A more complicated Example: >
:syn region Exa matchgroup=Foo start="foo"hs=s+2,rs=e+2 matchgroup=Bar end="bar"me=e-1,he=e-1,re=s-1
<
A more complicated Example: >vim
:syn region Exa matchgroup=Foo start="foo"hs=s+2,rs=e+2 matchgroup=Bar end="bar"me=e-1,he=e-1,re=s-1
< >
abcfoostringbarabc
mmmmmmmmmmm match
sssrrreee highlight start/region/end ("Foo", "Exa" and "Bar")
<
Leading context *:syn-lc* *:syn-leading* *:syn-context*
Note: This is an obsolete feature, only included for backwards compatibility
@@ -4785,7 +4785,7 @@ matches, nextgroup, etc. But there are a few differences:
- When a match with a sync pattern is found, the rest of the line (or group of
continued lines) is searched for another match. The last match is used.
This is used when a line can contain both the start end the end of a region
(e.g., in a C-comment like /* this */, the last "*/" is used).
(e.g., in a C-comment like `/* this */`, the last "*/" is used).
There are two ways how a match with a sync pattern can be used:
1. Parsing for highlighting starts where redrawing starts (and where the
@@ -5481,14 +5481,14 @@ memory Vim will consume.
Only highlighting typedefs, unions and structs can be done too. For this you
must use Universal Ctags (https://ctags.io) or Exuberant ctags.
Put these lines in your Makefile:
Put these lines in your Makefile: >
# Make a highlight file for types. Requires Universal/Exuberant ctags and awk
types: types.vim
types.vim: *.[ch]
ctags --c-kinds=gstu -o- *.[ch] |\
awk 'BEGIN{printf("syntax keyword Type\t")}\
{printf("%s ", $$1)}END{print ""}' > $@
# Make a highlight file for types. Requires Universal/Exuberant ctags and awk
types: types.vim
types.vim: *.[ch]
ctags --c-kinds=gstu -o- *.[ch] |\
awk 'BEGIN{printf("syntax keyword Type\t")}\
{printf("%s ", $$1)}END{print ""}' > $@
And put these lines in your vimrc: >

6
runtime/doc/vi_diff.txt
View File

@@ -180,12 +180,12 @@ Command-line editing and history. |cmdline-editing|
forward/backward one character. The shifted right/left cursor keys
can be used to move forward/backward one word. CTRL-B/CTRL-E can be
used to go to the begin/end of the command-line.
{Vi: can only alter the last character in the line}
{Vi: when hitting <Esc> the command-line is executed. This is
(Vi: can only alter the last character in the line)
(Vi: when hitting <Esc> the command-line is executed. This is
unexpected for most people; therefore it was changed in Vim. But when
the <Esc> is part of a mapping, the command-line is executed. If you
want the Vi behaviour also when typing <Esc>, use ":cmap ^V<Esc>
^V^M"}
^V^M")
|cmdline-history|
The command-lines are remembered. The up/down cursor keys can be used
to recall previous command-lines. The 'history' option can be set to

22
runtime/doc/vim_diff.txt
View File

@@ -564,7 +564,8 @@ Aliases:
Commands:
:behave
:fixdel
:hardcopy
*hardcopy* `:hardcopy` was removed. Instead, use `:TOhtml` and print the
resulting HTML using a web browser or other HTML viewer.
:helpfind
:mode (no longer accepts an argument)
:open
@@ -586,6 +587,11 @@ Compile-time features:
Emacs tags support
X11 integration (see |x11-selection|)
Cscope:
*cscope*
Cscope support was removed in favour of plugin-based solutions such as:
https://github.com/dhananjaylatkar/cscope_maps.nvim
Eval:
Vim9script
*cscope_connection()*
@@ -715,6 +721,7 @@ Plugins:
- logiPat
- rrhelper
- *vimball*
Providers:
@@ -771,18 +778,5 @@ TUI:
at how the terminal is sending CSI. Nvim does not issue such a sequence and
always uses 7-bit control sequences.
Cscope:
*cscope*
Cscope support was removed in favour of plugin-based solutions such as:
https://github.com/dhananjaylatkar/cscope_maps.nvim
Hardcopy:
*hardcopy*
`:hardcopy` was removed. Instead, use `:TOhtml` and print the resulting HTML
using a web browser or some other HTML viewer.
Bundled plugins:
vimball *vimball*
==============================================================================
vim:tw=78:ts=8:sw=2:et:ft=help:norl:

122
scripts/gen_help_html.lua
View File

@@ -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,
@@ -88,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
@@ -143,11 +149,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
@@ -161,7 +167,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.
@@ -186,7 +192,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+'
@@ -199,7 +205,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+'
@@ -214,7 +220,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
@@ -229,9 +235,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
@@ -243,7 +249,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 = ''
@@ -254,7 +260,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
@@ -263,8 +269,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]
@@ -281,7 +287,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]
@@ -292,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.
@@ -313,7 +322,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
@@ -335,10 +344,10 @@ 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
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)
@@ -346,7 +355,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
@@ -365,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.
@@ -578,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
@@ -608,7 +617,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.
@@ -623,17 +632,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.
@@ -642,21 +653,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
@@ -665,20 +680,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))
@@ -1058,18 +1074,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')
@@ -1078,7 +1096,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
@@ -1101,19 +1119,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