I’ve been working on a plugin that does heavy UI manipulation (change text in buffers, resize windows, simulate keypresses using nvim_feedkeys, doing all the above with defer_fn etc etc).
However, some of the scenarious I’ve written didn’t seem to work. At this point I started learning about neovim eventloop, neovim fast events vs regular events, and was able to debug most of my issues.
However, there exists a mysterious beast called textlock. Some of my scenarious don’t work yet, and I suspect that this textlock thing is the issue. Putting aside what I do exactly, let’s consider current documentation for textlock. It does tell you what is forbidden to do while textlock is active, but it does a very poor job explaining WHEN textlock occurs and WHY textlock occurs, which might be very important for plugin developers to understand what’s going on.
You might tell me that these things are too complex for user-faced documentation, but
real users will rarely need consulting textlock docs anyway - I’ve been heavily using Vim/Neovim for 4 years and never needed it
plugin developers ARE users of vim/neovim, and they need information that empowers them to solve problems and not leaving them scratching heads not knowing what to do.
Concluding this, I need advice - should I open an issue in Neovim repository with a request to improve the documentation? Just wanted to verify with a community that this is important and appropriate.
Even if the answer is “yes”, the issue should be opened at the Vim repository, since that is where this documentation is taken from (as part of the regular runtime file updates).
Hey! Thanks a lot for letting me know that. I’m having some further doubts, though. Now, let’s for a minute imagine the answer is yes, then consider the following statements:
getting something done at Vim repository is nearly impossible
getting something done at Neovim repository should be a breeze, everyone’s so kind and welcoming
In other words, if problem exists and needs to be solved, AND we cannot communicate with Bram well enough, we’ll need to tackle this documentation issue from our side. Could you please explain to me why is it bad to simply create a piece of documentation from our side (not editing textlock part of documentation in Vim repo) under a name, let’s say, nvim-textlock, make a link to original textlock?
I realize that the ones who got onto textlock documentation first won’t see a link to our supposedly cool piece of documentation, but the tryhard guys searching docs with fuzzy-finders (and a plugin developer probably will be try-hard-searching in docs whatever he needs to solve his problems) this should be a good solution.
If my train of thought is wrong for some reason, I’d like to hear any critique.
Your assumption is flat-out wrong: Bram is very helpful and cares about documentation. So the conclusion is void and doesn’t really merit discussion.
But, for the sake of explanation, duplicating documentation is bad: it makes it more confusing to users, and makes maintaining it harder. There is great value in consistency, and the consistent policy of the Neovim project has long been and will remain that we do not deviate from Vim except for a very good reason.
Finally, it’s just about being a good open source citizen: If you report the issue at Vim and help them improve their documentation, both projects will profit, and you will have contributed to paying back Neovim’s “debt” to Vim as a fork.