Problem:
`vim.keymap.*.Opts.buf` allows `boolean` aliases for more widely
used `integer?` values, `true` -> `0` and `false` -> `nil`. This
conversion is unnecessary and can be handled at call sites.
Solution:
As a follow-up to deprecating the `buffer` option, drop support for
boolean values for the new `buf` option. The deprecated `buffer`
continues to support booleans for backward compatibility.
The `buffer` option remains functional but is now undocumented.
Providing both will raise an error. Since providing `buf` was disallowed
before, there is no code that will break due to using `buffer` alongside
`buf`.
Problem:
In autocmd examples, using "args" as the event-object name is vague and
may be confused with a user-command.
Solution:
Use "ev" as the conventional event-object name.
- Problem: It's not clear for new plugin developers that `:help` uses
a help-tags file for searching the docs, generated by `:helptags`.
- Solution: Hint to the |:helptags| docs for regenerating the tags
file for their freshly written documentation.
Co-authored-by: Yochem van Rosmalen <git@yochem.nl>
Problem:
- Missing some important Vim features
- Since Nvim 0.5, package.path and package.cpath don't include
`'runtimepath'` (thought `require()` can still find modules in
`runtimepath`)
Closes#33938
Co-authored-by: Justin M. Keyes <justinkz@gmail.com>
Problem:
There are some "boilerplate" steps for new users. Although we are
constantly improving defaults and lifting patterns into core, users
eventually want to know how to start their own config, add plugins, etc.
Solution:
Add `runtime/example_init.lua` and refer to it from docs.
Problem:
- `vim.highlight` module does not follow `:help dev-name-common`, which
documents the name for "highlight" as "hl".
- Shorter names are usually preferred.
Solution:
Rename `vim.highlight` to `vim.hl`.
This is not a breaking change until 2.0 (or maybe never).
* feat(lua): allow vim.wo to be double indexed
Problem: `vim.wo` does not implement `setlocal`
Solution: Allow `vim.wo` to be double indexed
Co-authored-by: Christian Clason <c.clason@uni-graz.at>
Problem:
The function name `vim.pretty_print`:
1. is verbose, which partially defeats its purpose as sugar
2. does not draw from existing precedent or any sort of convention
(except external projects like penlight or python?), which reduces
discoverability, and degrades signaling about best practices.
Solution:
- Rename to `vim.print`.
- Change the behavior so that
1. strings are printed without quotes
2. each arg is printed on its own line
3. tables are indented with 2 instead of 4 spaces
- Example:
:lua ='a', 'b', 42, {a=3}
a
b
42
{
a = 3
}
Comparison of alternatives:
- `vim.print`:
- pro: consistent with Lua's `print()`
- pro: aligns with potential `nvim_print` API function which will
replace nvim_echo, nvim_notify, etc.
- con: behaves differently than Lua's `print()`, slightly misleading?
- `vim.echo`:
- pro: `:echo` has similar "pretty print" behavior.
- con: inconsistent with Lua idioms.
- `vim.p`:
- pro: very short, fits with `vim.o`, etc.
- con: not as discoverable as "echo"
- con: less opportunity for `local p = vim.p` because of potential shadowing.
Add introductory guide explaining how to use Lua in Neovim:
where to put Lua files, how to set variables and options, how
to create mappings, autocommands, and user commands.
Adapted with kind permission from
https://github.com/nanotee/nvim-lua-guide
