diff options
Diffstat (limited to 'runtime')
| -rw-r--r-- | runtime/doc/starting.txt | 33 |
1 files changed, 19 insertions, 14 deletions
diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt index 275b08b5dd..dd9f9ad0f3 100644 --- a/runtime/doc/starting.txt +++ b/runtime/doc/starting.txt @@ -348,30 +348,35 @@ argument. *--embed* --embed Use stdin/stdout as a msgpack-RPC channel, so applications can - embed and control Nvim via the |rpc-api|. Implies |--headless|. - - Nvim will wait for a single request before sourcing startup - files and reading buffers. This is mainly so that UIs can call - `nvim_ui_attach` so that the UI can show startup messages - and possible swap file dialog for the first loaded file. In - addition, a `nvim_get_api_info` call before the `nvim_ui_attach` - call is also allowed, so that UI features can be safely - detected by the UI. - - To avoid this behavior, this alterative could be used instead: > + embed and control Nvim via the |rpc-api|. + + By default nvim will wait for the embedding process to call + `nvim_ui_attach` before sourcing startup files and reading + buffers. This is so that UI can show startup messages and + possible swap file dialog for the first loaded file. The + process can do requests before the `nvim_ui_attach`, for + instance a `nvim_get_api_info` call so that UI features can be + safely detected by the UI before attaching. + + To embed nvim without using the UI protocol, `--headless` should + be supplied together with `--embed`. Then initialization is + performed without waiting for an UI. This is also equivalent + to the following alternative: > nvim --headless --cmd "call stdioopen({'rpc': v:true})" < See also |channel-stdio|. *--headless* ---headless Do not start the default UI, so stdio can be used as an - arbitrary communication channel. |channel-stdio| +--headless Start nvim without an UI. The TUI is not used, so stdio + can be used as an arbitrary communication channel. + |channel-stdio| When used together with `--embed`, do not wait + for the embedder to attach an UI. Also useful for scripting (tests) to see messages that would not be printed by |-es|. To detect if a UI is available, check if |nvim_list_uis()| is - empty after |VimEnter|. + empty in or after |VimEnter|. To read stdin as text, "-" must be given explicitly: --headless cannot assume that stdin is just text. > |