Cleaning up and improving guide

[matu3ba]

checklist:

1. [x] Start or link the why (showing very fast lua plugins/faster startup time)
2. [x] vim.call and vim.fn expose quite the same functionality, so remove the non-luaish and link to the according neovim :help, pending core dev reply...
3. [x] The linked guides are outdated or dont use best practice. Better define it here and remove all nonconforming guides. TBD(separate issue, once #13823 is upstreamed) 4. [ ] Best practice for less clutter is using vim.o.backup = false for set options (it also checks types etc), remove the other
4. [x] Show wrapper around vim.api.nvim_set_keymap('i', '<Tab>', 'v:lua.smart_tab()', {expr = true, noremap = true}) such that one can use something like localfunction_setting_mmode(dictionary) (dictionary) with variables definable as tab.somekey = "some value" to minimize clutter => better than vimscript :) use neovim core PR for keymap after it landed => once #13823 is upstreamed
5. [x] make a plan how to proceed on "General tips and recommendations" and "Miscellaneous" TBD(clarify content, once motivation is upstreamed)
6. [x] make init.lua best practice or minimal example for the pitifalls? TBD (separate issue, once 5. is upstreamed)
7. [x] shortening TOC TBD

Do you prefer individual PRs for each issue?

EDIT: according to information in discussion, TBD:=to be discussed

[nanotee]

Hello! Thanks for your contributions! :)

Start or link the why (showing very fast lua plugins/faster startup time)

I haven't noticed any difference in terms of startup speed and I haven't done any benchmarks so I wouldn't make such a claim. But you're right, linking to tjdevries' VimConf talk would be nice to explain why you'd use Lua

vim.call and vim.fn expose quite the same functionality, so remove the non-luaish and link to the according neovim :help

I don't have a strong opinion on this, it's true that removing clutter would make the guide easier to follow but there might be situations where vim.call is useful?

The linked guides are outdated or dont use best practice. Better define it here and remove all nonconforming guides.

Not sure which ones you're talking about, it may be worthwhile to contact the authors so they can update them if you have any suggestions to improve them. They often contain useful information that doesn't quite fit in this guide

Best practice for less clutter is using vim.o.backup = false for set options (it also checks types etc), remove the other

I'd rather keep the api functions, I don't want to be too opinionated on best practices

Show wrapper around vim.api.nvim_set_keymap('i', '<Tab>', 'v:lua.smart_tab()', {expr = true, noremap = true}) such that one can use something like localfunction_setting_mmode(dictionary) (dictionary) with variables definable as tab.somekey = "some value" to minimize clutter => better than vimscript :)

There's a PR in Neovim core that adds a nicer interface for Lua keymaps, but I'm waiting for it to be merged before I mention it in this guide

make a plan how to proceed on "General tips and recommendations" and "Miscellaneous"

Yeah I have definitely been procrastinating on this! :sweat_smile: Ideas / PRs are very much welcome!

Do you prefer individual PRs for each issue?

Individual PRs are probably easier to review so I'd say yes

Thanks again!

[matu3ba]

I don't have a strong opinion on this, it's true that removing clutter would make the guide easier to follow but there might be situations where vim.call is useful?

If you look at the help page: :help vim.call:

vim.call({func}, {...})                 *vim.call()*
        Invokes |vim-function| or |user-function| {func} with arguments {...}.
        See also |vim.fn|.
        Equivalent to: >
            vim.fn[func]({...})

Why would you want another "equivalent" function, which is less documented in the help page?

They often contain useful information that doesn't quite fit in this guide

I would prefer additional collecting the important essentials in a wiki with proper sources. Authors often do not respond and then you need to keep checking or mediate etc. Is this okay for you?

I'd rather keep the api functions, I don't want to be too opinionated on best practices There's a PR in Neovim core that adds a nicer interface for Lua keymaps, but I'm waiting for it to be merged before I mention it in this guide

LGTM.

[matu3ba]

Yeah I have definitely been procrastinating on this! sweat_smile Ideas / PRs are very much welcome!

I dont think lsp, coc,vim.loop,vim.lsp,vim.treesitter,transpilers belong to the beginner guide. Probably one does not want to deal with syntax highlighting either at first.

They can be mentioned as motivation etc, but should be moved to an intermediate/advanced guide.

nvim.utils and popup.nvim also feel abit out of place, since they are not essential to move to init.lua or develop stuff in lua.

Does the TOC need to be so long?

[matu3ba]

I think it would make sense to have a minimal init.lua to show the pitifalls, because examplifying it would clutter the text too much.

[nanotee]

Why would you want another "equivalent" function, which is less documented in the help page?

I don't mind dropping it from the guide, but vim.fn is based on vim.call internally

I would prefer additional collecting the important essentials in a wiki with proper sources. Authors often do not respond and then you need to keep checking or mediate etc. Is this okay for you?

Sure, if you feel some articles are really outdated then I guess it's better not to mention them.

I dont think lsp, coc,vim.loop,vim.lsp,vim.treesitter,transpilers belong to the beginner guide.

LSP/CoC stuff was suggested to me in #21 because people often have questions about setting up Neovim for Lua development (linters not knowing about the vim global is a common one for example). I feel like it's important to at least mention what's available in terms of tooling so newcomers can have a good experience writing Lua

As for vim.loop/vim.treesitter/transpilers, they're already mostly just links. They're there to give a brief overview of the Lua ecosystem and for people who want to go further, which is why I put them at the end. I don't feel like they add much clutter, but I'm open to suggestions for improving that part of the guide

nvim.utils and popup.nvim also feel abit out of place, since they are not essential to move to init.lua or develop stuff in lua.

nvim_utils contains some useful stuff like nvim.ex. Maybe popup.nvim isn't directly related to Lua development, I should probably put a link to rockerBOO/awesome-neovim for folks who want to see more plugins

[matu3ba]

@nanotee What do you think of shortening the TOC by removing the second nested level (caveats, tips) and instead make them fat text ?

[matu3ba]

Advanced guide/references

The one and only luajit wiki.

1. Performance tips
2. Debugging
3. luarocks
4. :checkhealth integration
5. ?

closest to proper benchmarks what I found are the julia microbenchmarks for this nice library. I contacted the author for a performance guide (for luajit), since he should be kind of an authority. There is also this about performance, but the answer is very cluttered. And this general advices.

[nanotee]

@nanotee What do you think of shortening the TOC by removing the second nested level (caveats, tips) and instead make them fat text ?

Not sure about this, we'd lose the ability to link directly to them with URI fragments

Advanced guide/references

The one and only luajit wiki.

1. Performance tips

Yeah, the LuaJIT wiki is a good resource, adding a link to it would be nice. This page can be interesting for people who want to optimize specifically for LuaJIT

2. Debugging

So far every Lua debugger I've tried has made Neovim crash :confused: But if you know of a solution that works, it'd be nice to add

3. luarocks

wbthomason/packer.nvim recently added support for luarocks packages

4. :checkhealth integration

Sounds good to me!

[matu3ba]

Not sure about this, we'd lose the ability to link directly to them with URI fragments

If the section is "short enough", it wont make a big difference. It would be however annoying to readd later it due the section becoming longer.

wbthomason/packer.nvim recently added support for luarocks packages

Oh no. Then I need to write to write a neovim and luarocks profile for firejail, because luarocks uses some non-default methods and folders. Shame on them for not using XDGBDS.

[nanotee]

because luarocks uses some non-default methods and folders. Shame on them for not using XDGBDS.

Are you referring to the fact that luarocks creates a ~/.luarocks/ folder by default? packer.nvim does not touch global rocks and instead relies on hererocks to install its own version of luarocks, independent from the version that's installed on your system . Packages are installed in ~/.cache/nvim/packer_hererocks

[matu3ba]

Then it might work.

[matu3ba]

Closing as all things were fixed or clarified.