Suggest adding them to news.txt instead.
Also don't ignore changes to intro.txt and sponsor.txt, as they don't
change much these days, and it's necessary to consider whether to
include their changes in Nvim's intro.txt.
This reverts 2875d45e79.
Allowing lintcommit to ignore "fixup" makes it too easy to fixup commits
to be merged on master as the CI won't give any indications that
something is wrong. Contributors can always squash their pull requests
if it annoys them too much.
Problem:
Not using minified version of bootstrap.
Don't need to load normalize with new version of bootstrap.
See https://github.com/neovim/neovim.github.io/pull/350
Solution:
Update link to bootstrap file.
Remove link to normalize.
`vim.health` is not a "plugin" but part of our Lua API and the
documentation should reflect that. This also helps make the
documentation maintenance easier as it is now generated.
Problem: vim-patch commits lack an informative title and summary in the
very first line of the commit message when the vim-revision is a Git SHA
hash, unlike when is a Vim version. This makes it difficult to discern
at a glance what changes are introduced by such vim-patch commits (in
git log, PR title, changelog generated by git-cliff, etc.).
BEFORE:
vim-patch:abcdef123456
runtime(vim): improve performance
<some details>
...
Solution: Repeat the title of the upstream commit message, to improve
the clarity and visibility of the commit message.
AFTER:
vim-patch:abcdef123456: runtime(vim): improve performance
<some details>
...
Note: the `vim-patch:<hash>` token is still needed by `vim-patch.sh`
(but not necessarily in the very first line of the commit message) to
determine which vim patches have been applied. `<hash>` is internally
normalized to 7 hex digits.
Problem:
'modeline' and 'note' are unhandled in the online HTML documentation.
Some (not all) modelines are parsed by the vimdoc parser as a node of
type 'modeline'.
Solution:
- Ignore 'modeline' in HTML rendering.
- Render 'note' text in boldface.
Problem:
- Since #28678, pre-formatted text in the online documentation do not
render whitespaces correctly: should be pre-like text, but shown like
normal paragraph (see #28754).
- Code blocks with long lines should not be wrapped (e.g. see
|dev-vimpatch-list-management|).
Solution:
- Use `white-space: pre-wrap`. Compared to `white-space: pre`, this
option will make long lines including a very long URL wrapped.
This properly fixes#28754 and #28678.
- Use horizontal scrollbar for the code blocks that are horizontally too
long, instead of wrapping text. This will make the code easy to read
while the pre-text block not interfering with the navigation bar.
Problem:
On the page: https://neovim.io/doc/user/dev_vimpatch.html
The links extend beyond the container and thus end up behind the navigation to the right.
Solution:
Add these lines to get_help_html.lua:
white-space: normal;
word-wrap: break-word;
runtime(doc): Add Makefile for the Vim documentation on Windows (vim/vim#13467)
* Makefile for the Vim documentation on Windows
* Corrected comments
b23c1fc596
Co-authored-by: Restorer <69863286+RestorerZ@users.noreply.github.com>
Problem:
While LuaCATS's generics system are still considered WIP by luals, they
currently support type captured generics.
See "Capture with Backtick" example:
https://luals.github.io/wiki/annotations/#generic
Solution:
Add support for it in the LuaCATS grammar
- Sort sections according to custom preference instead of
alphabetically. It is ordered according to "most relevant" to "least
relevant" to users.
- Sort commits alphabetically
- Don't uppercase the first letter of the commit message
Specifically, functions that are run in the context of the test runner
are put in module `test/testutil.lua` while the functions that are run
in the context of the test session are put in
`test/functional/testnvim.lua`.
Closes https://github.com/neovim/neovim/issues/27004.
Problem:
Besides being redundant with vim.iter():flatten(), `tbl_flatten` has
these problems:
- Has `tbl_` prefix but only accepts lists.
- Discards some results! Compare the following:
- iter.flatten():
```
vim.iter({1, { { a = 2 } }, { 3 } }):flatten():totable()
```
- tbl_flatten:
```
vim.tbl_flatten({1, { { a = 2 } }, { 3 } })
```
Solution:
Deprecate tbl_flatten.
Note:
iter:flatten() currently fails ("flatten() requires a list-like table")
on this code from gen_lsp.lua:
local anonym = vim.iter({ -- remove nil
anonymous_num > 1 and '' or nil,
'---@class ' .. anonymous_classname,
}):flatten():totable()
Should we enhance :flatten() to work for arrays?
- Added `@inlinedoc` so single use Lua types can be inlined into the
functions docs. E.g.
```lua
--- @class myopts
--- @inlinedoc
---
--- Documentation for some field
--- @field somefield integer
--- @param opts myOpts
function foo(opts)
end
```
Will be rendered as
```
foo(opts)
Parameters:
- {opts} (table) Object with the fields:
- somefield (integer) Documentation
for some field
```
- Marked many classes with with `@nodoc` or `(private)`.
We can eventually introduce these when we want to.
Then we can just load metadata in C as a single msgpack blob. Which also
can be used directly as binarly data, instead of first unpacking all the
functions and ui_events metadata to immediately pack it again, which was
a bit of a silly walk (and one extra usecase of `msgpack_rpc_from_object`
which will get yak shaved in the next PR)
runtime(sh): Update ftplugin, fixvim/vim#14101 (vim/vim#14102)
Add the 'b' flag to 'comments', so that the shebang line is not detected as comment.
Fixesvim/vim#14101.
e84d2d4432
Co-authored-by: dkearns <dougkearns@gmail.com>
Problem:
The documentation flow (`gen_vimdoc.py`) has several issues:
- it's not very versatile
- depends on doxygen
- doesn't work well with Lua code as it requires an awkward filter script to convert it into pseudo-C.
- The intermediate XML files and filters makes it too much like a rube goldberg machine.
Solution:
Re-implement the flow using Lua, LPEG and treesitter.
- `gen_vimdoc.py` is now replaced with `gen_vimdoc.lua` and replicates a portion of the logic.
- `lua2dox.lua` is gone!
- No more XML files.
- Doxygen is now longer used and instead we now use:
- LPEG for comment parsing (see `scripts/luacats_grammar.lua` and `scripts/cdoc_grammar.lua`).
- LPEG for C parsing (see `scripts/cdoc_parser.lua`)
- Lua patterns for Lua parsing (see `scripts/luacats_parser.lua`).
- Treesitter for Markdown parsing (see `scripts/text_utils.lua`).
- The generated `runtime/doc/*.mpack` files have been removed.
- `scripts/gen_eval_files.lua` now instead uses `scripts/cdoc_parser.lua` directly.
- Text wrapping is implemented in `scripts/text_utils.lua` and appears to produce more consistent results (the main contributer to the diff of this change).
Problem:
When a function has multiple signatures, putting its tag at the last one
may make one think that's its only signature.
Solution:
When a function has multiple signatures, put its tag at the first one.
Implement api_keydict_to_dict as the complement to api_dict_to_keydict
Fix a conversion error when nvim_get_win_config gets called from lua,
where Float values "x" and "y" didn't get converted to lua numbers.
- Consistently use the variable CMAKE_BUILD_TYPE to select build type.
- Remove broken `doc_html` target.
- Remove swap files created by oldtest when cleaning.
- Only rerun `lintdoc` if any documentation files has changed.
- Add type annotations, fix most of the type warnings.
- Fix a minor bug on `spell_ignore_files`: nil error when an invalid
spelling is found but the file is not ignored.
Summary: Separate the lint job (`make lintdoc`) to validate runtime/doc,
it is no longer as a part of functionaltest (help_spec).
Build (cmake) and CI:
- `make lintdoc`: validate vimdoc files and test-generate HTML docs.
CI will run this as a part of the "docs" workflow.
- `scripts/lintdoc.lua` is added as an entry point (executable script)
for validating vimdoc files.
scripts/gen_help_html.lua:
- Move the tests for validating docs and generating HTMLs from
`help_spec.lua` to `gen_help_html`. Added:
- `gen_help_html.run_validate()`.
- `gen_help_html.test_gen()`.
- Do not hard-code `help_dir` to `build/runtime/doc`, but resolve from
`$VIMRUNTIME`. Therefore, the `make lintdoc` job will check doc files
on `./runtime/doc`, not on `./build/runtime/doc`.
- Add type annotations for gen_help_html.
Using CMAKE_INSTALL_PREFIX is unreliable as it's a cache variable,
meaning the users previous value will be used if not supplied. Instead,
use the `--prefix` flag which is guaranteed to always work.
Problem: Any preceding luadocs block that define alias types with
`@alias` magic would be prepended to the documentation of functions
that follow, despite the "blank line" separator. For example:
```
--- @alias some.type.between.functions
--- Blah blah long documentation for alias
--- | "foo" # foo
--- | "bar" # bar
--- The documentation that should appear in vimdoc.
function M.function_to_include_in_doc()
...
end
```
then the vimdoc generated for `function_to_include_in_doc` would include
the text from the alias block (e.g., "Blah blah ... for alias").
Solution:
- refactor: Lua2DoxFilter should maintain its own internal state
`generics`, rather than carrying it as a parameter to local helper
functions.
- Add another boolean state `boolean_state` which represents whether
to ignore the current docstring block (magic lines). This flag will
be reset as soon as the block is end.
Note: As expected, there is no change at all in the current docs
generated, because we have been working around and writing luadoc
comments so that such erroneous docstring resulting from preceding
`@alias` blocks won't appear.
- Add section `VIM.LPEG` and `VIM.RE` to docs/lua.txt.
- Add `_meta/re.lua` which adds luadoc and type annotations, for the
vendored `vim.re` package.
- Fix minor style issues on `_meta/lpeg.lua` luadoc for better vimdocs
generation.
- Fix a bug on `gen_vimdoc` where non-helptags in verbatim code blocks
were parsed as helptags, affecting code examples on `vim.lpeg.Cf`,
etc.
- Also move the `vim.regex` section below so that it can be located
closer to `vim.lpeg` and `vim.re`.
Problem: Some lines in the generated vim doc are overflowing, not
correctly wrapped at 78 characters. This happens when docs body contains
several consecutive 'inline' elements generated by doxygen.
Solution: Take into account the current column offset of the last line,
and prepend some padding before doc_wrap().
Since some point INCLUDE_DEPRECATED stopped working as it is usually
turned off when generating an actual vimdoc. This commit fixes this
hidden feature back again (used for devel purposes only).
Problem: main() has too much logic implemented there, too difficult to
read.
Solution: Do more OOP, introduce `Section` dataclass that stores
information about a "section", with documentation and concrete examples
about what each field and variable would mean. Extract all the lines for
rendering a section into `section.render()` pulled out of `main()`.
Problem:
For function definitions to be included in the vimdoc (formatted) and
to be exported as mpack data (unformatted), we had two internal
representations of the same function/API metadata in duplicate;
one is FunctionDoc (which was previously a dict), and the other is
doxygen XML DOM from which vimdoc (functions sections) was generated.
Solution:
We should have a single path and unified data representation
(i.e. FunctionDoc) that contains all the metadata and information about
function APIs, from which both of mpack export and vimdoc are generated.
I.e., vimdocs are no longer generated directly from doxygen XML nodes,
but generated via:
(XML DOM Nodes) ------------> FunctionDoc ------> mpack (unformatted)
Recursive Internal |
Formatting Metadata +---> vimdoc (formatted)
This refactoring eliminates the hacky and ugly use of `fmt_vimhelp` in
`fmt_node_as_vimhelp()` and all other helper functions! This way,
`fmt_node_as_vimhelp()` can simplified as it no longer needs to handle
generating of function docs, which needs to be done only in the topmost
level of recursion.
There is no reason for this file to be in project root, which is crowded
as is. This also fits nicely part of the ongoing work towards gathering
as much of the documentation as possible into one place.
Style improvements:
1. Anonymous classes derived from `StructureLiteralType` should have a
better name. The class name can be also nested. Examples:
```diff
----@field serverInfo? anonym1
+---@field serverInfo? lsp._anonym1.serverInfo
```
```diff
----@field insertTextModeSupport? anonym26
+---@field insertTextModeSupport? lsp._anonym26.completionItem.insertTextModeSupport
```
2. Add one separate empty line before each `@field` definition. Without
these, empty lines the doc can look confusing because descriptions
also may contain empty lines. See `lsp.CompletionItem` for example:
```lua
---The kind of this completion item. Based of the kind
---an icon is chosen by the editor.
---@field kind? lsp.CompletionItemKind
---Tags for this completion item.
---
---@since 3.15.0
---@field tags? lsp.CompletionItemTag[]
```
It might feel like "Tags for this completion item" belongs to `kind`,
not `tags` due to the lack of separator blank lines. The following
(after this commit) should look much better:
```diff
---The kind of this completion item. Based of the kind
---an icon is chosen by the editor.
---@field kind? lsp.CompletionItemKind
+---
---Tags for this completion item.
---
---@since 3.15.0
---@field tags? lsp.CompletionItemTag[]
```
3. Escape some LSP-specific annotations that can't be recognized by
lua-ls. It'd be better to make them visible in LSP hover doc windows.
Example: `@sample ...`.
Fixes:
1. A type may extend from more than one base types (as well as mixin
types). Previously only the first base class was being considered,
resulting incomplete base classes for `@class` definitions.
Example: `InlayHintOptions` (should have both of `resolveProvider`
and `workDoneProgress`, the latter is from `WorkDoneProgressOptions`)
```diff
----@class lsp.InlayHintOptions
+---@class lsp.InlayHintOptions: lsp.WorkDoneProgressOptions
```
2. Remove `<200b>` (zero-width space) unicode characters.
3. Add the missing newline at EOF.
Problem: We have `P_(BOOL|NUM|STRING)` macros to represent an option's type, which is redundant because `OptValType` can already do that. The current implementation of option type flags is also too limited to allow adding multitype options in the future.
Solution: Remove `P_(BOOL|NUM|STRING)` and replace it with a new `type_flags` attribute in `vimoption_T`. Also do some groundwork for adding multitype options in the future.
Side-effects: Attempting to set an invalid keycode option (e.g. `set t_foo=123`) no longer gives an error.
Problem: Wiki contents are not discoverable and hard to maintain.
Solution: Move FAQ to runtime docs.
Co-authored-by: Christian Clason <c.clason@uni-graz.at>
- Improve CLI argument parsing, rejects invalid argument and commands as
early as possible. Also prints USAGE in the command line.
- No longer allows `--<outfile>`, use `--out <outfile>` instead.
- Print a little bit of verbose messages to better know what's going on
rather than remaining silent at all times.
- Add type annotation `gen_lsp._opt` to avoid type warnings.
Problem:
We don't enable stylua for many Lua scripts. Automating code-style is an
important tool for reducing time spent on accidental (non-essential)
complexity.
Solution:
- Enable lintlua for `scripts/` directory.
- Specify `call_parentheses = "Input"`, we should allow kwargs-style
function invocations.
Problem:
Numerous Vim 8.1 patches are listed by `vim-patch.sh -l`.
Solution:
Mark the following patches as N/A:
obviated by $NVIM env var:
vim-patch:8.1.0049 shell cannot tell running in a terminal window
vim-patch:8.1.0050 $VIM_TERMINAL is also set when not in a terminal window
'termwinkey' is not supported by Nvim:
vim-patch:8.1.0072 use of 'termwinkey' is inconsistent
Nvim handles STOP signal via libuv:
vim-patch:8.1.0304 no redraw when using a STOP signal on Vim and then CONT
vim-patch:8.1.0312 wrong type for flags used in signal handlers
Nvim does not have `parse_queued_messages`:
vim-patch:8.1.0367 getchar(1) no longer processes pending messages
N/A various:
vim-patch:8.1.1396 'wincolor' does not apply to lines below the buffer
vim-patch:8.1.1502 cannot play any sound
vim-patch:8.1.1515 memory leak reported for sound when build with EXITFREE
Nvim has extmarks instead of textprops:
vim-patch:8.1.0579 cannot attach properties to text
vim-patch:8.1.0582 text properties are not enabled
vim-patch:8.1.0634 text properties cannot cross line boundaries
vim-patch:8.1.0638 text property highlighting is off by one column
vim-patch:8.1.0639 text properties test fails on MS-Windows
vim-patch:8.1.0643 computing byte offset wrong
vim-patch:8.1.0654 when deleting a line text property flags are not adjusted
vim-patch:8.1.0655 when appending a line text property flags are not added
vim-patch:8.1.0663 text property display wrong when 'number' is set
vim-patch:8.1.0665 text property display wrong when 'spell' is set
vim-patch:8.1.0667 textprop test leaves file behind
vim-patch:8.1.0675 text property column in screen columns is not practical
vim-patch:8.1.0676 textprop screendump test fails
vim-patch:8.1.0681 text properties as not adjusted for deleted text
vim-patch:8.1.0682 text properties not adjusted when backspacing replaced text
vim-patch:8.1.0688 text properties are not restored by undo
vim-patch:8.1.0689 undo with text properties not tested
vim-patch:8.1.0690 setline() and setbufline() do not clear text properties
vim-patch:8.1.0691 text properties are not adjusted for :substitute
vim-patch:8.1.0694 when using text props may free memory that is not allocated
vim-patch:8.1.0703 compiler warnings with 64-bit compiler
vim-patch:8.1.0707 text property columns are not adjusted for changed indent
vim-patch:8.1.0970 text properties test fails when 'encoding' is not utf-8
vim-patch:8.1.1035 prop_remove() second argument is not optional
vim-patch:8.1.1276 cannot combine text properties with syntax highlighting
vim-patch:8.1.1278 missing change for "combine" field
vim-patch:8.1.1333 text properties don't always move after changes
vim-patch:8.1.1337 get empty text prop when splitting line just after text prop
vim-patch:8.1.1341 text properties are lost when joining lines
vim-patch:8.1.1343 text properties not adjusted for Visual block mode delete
vim-patch:8.1.1340 attributes from 'cursorline' overwrite textprop
vim-patch:8.1.1351 text property wrong after :substitute
vim-patch:8.1.1359 text property wrong after :substitute with backslash
vim-patch:8.1.1387 calling prop_add() in an empty buffer doesn't work
vim-patch:8.1.1388 errors when calling prop_remove() for an unloaded buffer
vim-patch:8.1.1463 gcc warns for uninitialized variable
N/A Nvim has buf_attach instead of "listeners":
vim-patch:8.1.1320 it is not possible to track changes to a buffer
vim-patch:8.1.1321 no docs or tests for listener functions
vim-patch:8.1.1326 no test for listener with partial
vim-patch:8.1.1328 no test for listener with undo operation
vim-patch:8.1.1332 cannot flush listeners without redrawing, mix of changes
vim-patch:8.1.1335 listener callback is called after inserting text
vim-patch:8.1.1419 listener callbacks may be called recursively
vim-patch:8.1.1486 a listener change is merged even when it adds a line
N/A build issues:
vim-patch:8.1.0601 a few compiler warnings
vim-patch:8.1.0612 cannot use two global runtime dirs with configure
vim-patch:8.1.0684 warnings from 64-bit compiler
vim-patch:8.1.1344 Coverity complains about possibly using a NULL pointer
vim-patch:8.1.1376 warnings for size_t/int mixups
vim-patch:8.1.1414 alloc() returning "char_u *" causes a lot of type casts
vim-patch:8.1.1508 sound keeps failing on Travis
vim-patch:8.1.1494 build failure
N/A terminal / job control patches:
vim-patch:8.1.0761 default value for brief_wait is wrong
vim-patch:8.1.0824 SunOS/Solaris has a problem with ttys
vim-patch:8.1.0845 having job_status() free the job causes problems
vim-patch:8.1.0870 Vim doesn't use the new ConPTY support in Windows 10
vim-patch:8.1.0880 MS-Windows: inconsistent selection of winpty/conpty
vim-patch:8.1.0890 pty allocation wrong if using file for out channel
vim-patch:8.1.0906 using clumsy way to get console window handle
vim-patch:8.1.0909 MS-Windows: using ConPTY even though it is not stable
vim-patch:8.1.0928 stray log function call
vim-patch:8.1.0940 MS-Windows console resizing not handled properly
vim-patch:8.1.1028 MS-Windows: memory leak when creating terminal fails
vim-patch:8.1.1265 when GPM mouse support is enabled double clicks do not work
vim-patch:8.1.1267 cannot check if GPM mouse support is working
N/A encoding patches:
vim-patch:8.1.0879 MS-Windows: temp name encoding can be wrong
vim-patch:8.1.0895 MS-Windows: dealing with temp name encoding not quite right
vim-patch:8.1.0918 MS-Windows: startup messages are not converted
vim-patch:8.1.1090 MS-Windows: modify_fname() has problems with some 'encoding'
N/A platform patches:
vim-patch:8.1.1103 MS-Windows: old API calls are no longer needed
N/A Lua patches:
vim-patch:8.1.1019 Lua: may garbage collect function reference in use
N/A Nvim has floating windows instead of popup window:
vim-patch:8.1.1329 plans for popup window support are spread out
vim-patch:8.1.1364 design for popup window support needs more details
vim-patch:8.1.1391 no popup window support
vim-patch:8.1.1400 using global pointer for tab-local popups is clumsy
vim-patch:8.1.1399 popup windows not adjusted when switching tabs
vim-patch:8.1.0062 popup menu broken if a callback changes the window layout
vim-patch:8.1.1405 "highlight" option of popup windows not supported
vim-patch:8.1.1406 popup_hide() and popup_show() not implemented yet
vim-patch:8.1.1407 popup_create() does not support text properties
vim-patch:8.1.1410 popup_move() is not implemented yet
vim-patch:8.1.1402 "timer" option of popup windows not supported
vim-patch:8.1.1408 PFL_HIDDEN conflicts with system header file
vim-patch:8.1.1420 popup window size only uses first line length
vim-patch:8.1.1421 drawing "~" line in popup window
vim-patch:8.1.1422 popup_getoptions() not implemented yet
vim-patch:8.1.1423 popup windows use options from current window and buffer
vim-patch:8.1.1426 no test for syntax highlight in popup window
vim-patch:8.1.1427 popup window screenshot test fails
vim-patch:8.1.1428 popup_atcursor() not implemented yet
vim-patch:8.1.1429 "pos" option of popup window not supported yet
vim-patch:8.1.1430 popup window option "wrap" not supported
vim-patch:8.1.1431 popup window listed as "Scratch"
vim-patch:8.1.1432 can't build with eval feature
vim-patch:8.1.1438 some commands cause trouble in a popup window
vim-patch:8.1.1441 popup window filter not yet implemented
vim-patch:8.1.1442 popup windows not considered when the Vim window is resized
vim-patch:8.1.1443 popup window padding and border not implemented yet
vim-patch:8.1.1444 not using double line characters for popup border
vim-patch:8.1.1445 popup window border highlight not implemented yet
vim-patch:8.1.1446 popup window callback not implemented yet
vim-patch:8.1.1447 not allowed to create an empty popup
vim-patch:8.1.1448 statusline is sometimes drawn on top of popup
vim-patch:8.1.1449 popup text truncated at end of screen
vim-patch:8.1.1450 popup window positioning wrong when using padding or borders
vim-patch:8.1.1451 CTRL-L does not clear screen with a popup window
vim-patch:8.1.1452 line and col property of popup windows not properly checked
vim-patch:8.1.1453 popup window "moved" property not implemented yet
vim-patch:8.1.1455 popup_atcursor() not completely implemented
vim-patch:8.1.1459 popup window border looks bad when 'ambiwidth' is "double"
vim-patch:8.1.1460 popup window border characters may be wrong
vim-patch:8.1.1416 popup_getposition() not implemented yet
vim-patch:8.1.1493 redrawing with popups is slow and causes flicker
vim-patch:8.1.1496 popup window height is not recomputed
vim-patch:8.1.1499 ruler not updated after popup window was removed
vim-patch:8.1.1511 matches in a popup window are not displayed properly
vim-patch:8.1.1513 all popup functionality is in functions, except :popupclear
vim-patch:8.1.1517 when a popup changes all windows are redrawn
vim-patch:8.1.1518 crash when setting 'columns' while a popup is visible
vim-patch:8.1.1520 popup windows are ignored when dealing with mouse position
vim-patch:8.1.1521 when a popup window is closed the buffer remains
vim-patch:8.1.1522 poup_notification() not implemented yet
vim-patch:8.1.1495 memory access error
vim-patch:8.1.1497 accessing memory beyond allocated space
N/A already applied:
vim-patch:8.1.1226 {not in Vi} remarks get in the way of useful help text
vim-patch:8.1.1280 remarks about functionality not in Vi clutters the help
We already have an extensive suite of static analysis tools we use,
which causes a fair bit of redundancy as we get duplicate warnings. PVS
is also prone to give false warnings which creates a lot of work to
identify and disable.
