[vim/vim] Preview for cmdline-completion (Issue #18843)
Phạm Bình An
brianhuster created an issue (vim/vim#18843)Is your feature request about something that is currently impossible or hard to do? Please describe the problem.
There is no preview window for built-in cmdline completion (unlike insert mode completion). It is useful because it can quickly give users explanation on what a command does, hence improve discoverability.
This feature is available in qute-browser (a web browser with Vim keymap) and Helix editor
| image.png (view on web) |
| Qute browser |
|---|
| image.png (view on web) |
| Helix editor |
Describe the solution you'd like
- The preview window should show
descof an user command - Built-in Ex commands (that are mentioned in
:h :Ex-commands) should provide cmdline-completion preview with the same content asactioncolumn - Plugins can define preview/desc for each cmdline completion item (not just desc of each command name but also args, etc)
Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.
Additional context
Add any other context or screenshots about the feature request here.
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
Maxim Kim
habamax left a comment (vim/vim#18843)So this is about 2 things:
- Make it possible to show preview/popup window based on non-existent for cmdline
:h complete-items, whereinfois displayed in a popup. - Supply all builtin commands with
infothat could be showed in a popup.
I think pt 1 is hard, however pt2 would require even more effort. Not sure if it would be a rewrite/restructure of existing help topics with possibility to extract relevant part of command description or maintaining a separate descriptions for all the commands.
I was thinking about pt2 for my vim omnicomplete, exactly to display help topic of the command being completed, but couldn't find the approach I would have been happy with.
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
Phạm Bình An
brianhuster left a comment (vim/vim#18843)Not sure if it would be a rewrite/restructure of existing help topics with possibility to extract relevant part of command description or a separate maintainence of the descriptions for all the commands.
Unlike emacs, we in vim, don't have a docstring associated with a command.
Doesn't have to be docstring though. For example, Neovim stores documents of all Vimscript functions in a Lua dictionary, which is then used to generate both help document and Lua docstring of those functions. I think Vim can use Vim9script dictionary or even just JSON.
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
Maxim Kim
habamax left a comment (vim/vim#18843)I think Vim can use Vim9script dictionary or even just JSON.
Yes, that relates to "a separate maintainence of the descriptions for all the commands"
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
Christian Brabandt
chrisbra left a comment (vim/vim#18843)Yes that would be nice, but it will be a huge documentation effort.
In case of Vim, I would imagine that the documents of built-in commands would be stored directly in C code (sorry, not a C expert), or just a JSON file
doc strings could work, someone just needs to write it, which will be quite some effort. And we must make sure the do not get out-dated. JSON is basically the same thing, just even getting faster out of date. The other alternative would be to parse any of the existing documentation, which is fragile of course.
Is it worth it? Not sure, I'd guess most Vim users are quite comfortable with the existing documentation, so the gain is probably not that high.
For example we have optwin.vim to make handling options easier and I highly doubt that this is actually used much (or even widely known).
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
Phạm Bình An
brianhuster left a comment (vim/vim#18843)Why would it be a more huge documentation effort than the current way?
And this issue is not just about documentation.
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
ubaldot
ubaldot left a comment (vim/vim#18843)For example we have optwin.vim to make handling options easier and I highly doubt that this is actually used much (or even widely known).
I have never heard of it.
I think it should be on top of the chapter devoted to options in the help file(s) to stand out. I wish I knew it when I was moving my first steps with Vim.
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
Christian Brabandt
chrisbra left a comment (vim/vim#18843)Why would it be a more huge documentation effort than the current way?
And this issue is not just about documentation.
You want programmatical access to the documentation for normal mode and ex commands, options, Vim script functions, etc? What else than documentation that needs to be made available for your script would this require? And where do you think this comes from?
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
Phạm Bình An
brianhuster left a comment (vim/vim#18843)You want programmatical access to the documentation for normal mode and ex commands, options, Vim script functions, etc?
What else than documentation that needs to be made available for your script would this require?
Seriously, this is very far from what this issue is about. I've never said I need documents for normal mode, options, Vimscript functions, etc. Neither have I said I needed my script to get access to some structurized document. I can't understand where you get such ideas from!
This issue is about a new feature: which is preview description of Cmdline completion. It has 2 parts:
- For built-in EX commands, only this requires the said "structurized document". But there is no reason why a user script needs access to it, such document would only be consumed by Vim internally.
- For user Ex commands, there are also 2 parts:
- Each user command could have a
descthat is later used to provide completion for the command name. This is something a plugin writer will define by themselves, and it is NOT related to whatever documentation you said. - expand
:command-completion-customor:command-completion-customlistso it supports apreviewfield for each completion item, just like inins-completion. This is needed to providepreviewfor command argument. This is also totally NOT related to whatever documentation AT ALL.
- Each user command could have a
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
Christian Brabandt
chrisbra left a comment (vim/vim#18843)For built-in EX commands, only this requires the said "structurized document".
So where do you think this "structurized document" should come from? That is exactly the thing, we need to add documentation for builtin commands and prepare it and maintain it. And once we have this for the builtin ex-commands, next will be normal user commands, options or vimscript functions (like the example you shared from Neovim).
I am not saying this is unwanted, someone just hast to prepare it. And that will be mostly huge effort to prepare such a document.
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.