feat: allow tables in vimscript command parser (#1075)

1 files changed, 35 insertions, 0 deletions

diff --git a/doc/telescope.txt b/doc/telescope.txt
index 55c3466..20b3984 100644
--- a/doc/telescope.txt
+++ b/doc/telescope.txt
@@ -272,6 +272,41 @@ telescope.extensions()                                *telescope.extensions()*
 
 
 ================================================================================
+                                                             *telescope.command*
+
+Telescope commands can be called through two apis, the lua api and the viml
+api.
+
+The lua api is the more direct way to interact with Telescope, as you directly
+call the lua functions that Telescope defines. It can be called in a lua file
+using commands like:
+`require("telescope.builtin").find_files({hidden=true, layout_config={prompt_position="top"}})`
+If you want to use this api from a vim file you should prepend `lua` to the
+command, as below:
+`lua require("telescope.builtin").find_files({hidden=true, layout_config={prompt_position="top"}})`
+If you want to use this api from a neovim command line you should prepend
+`:lua` to the command, as below:
+`:lua require("telescope.builtin").find_files({hidden=true, layout_config={prompt_position="top"}})`
+
+The viml api is more indirect, as first the command must be parsed to the
+relevant lua equivalent, which brings some limitations. The viml api can be
+called using commands like:
+`:Telescope find_files hidden=true layout_config={"prompt_position":"top"}`
+This involves setting options using an `=` and using viml syntax for lists and
+dictionaries when the corresponding lua function requires a table.
+
+One limitation of the viml api is that there can be no spaces in any of the
+options. For example, if you want to use the `cwd` option for `find_files` to
+specify that you only want to search within the folder `/foo bar/subfolder/`
+you could not do that using the viml api, as the path name contains a space.
+Similarly, you could NOT set the `prompt_position` to `"top"` using the
+following command:
+`:Telescope find_files layout_config={ "prompt_position" : "top" }`
+as there are spaces in the option.
+
+
+
+================================================================================
                                                              *telescope.builtin*
 
 Telescope Builtins is a collection of community maintained pickers to support