diff options
Diffstat (limited to 'runtime/doc/starting.txt')
| -rw-r--r-- | runtime/doc/starting.txt | 42 |
1 files changed, 20 insertions, 22 deletions
diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt index a8ba64fda8..d148e1d8cd 100644 --- a/runtime/doc/starting.txt +++ b/runtime/doc/starting.txt @@ -355,35 +355,33 @@ argument. --embed Use stdin/stdout as a msgpack-RPC channel, so applications can 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. - - See |ui-startup| for more information about UI startup. - - 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|. + Waits for the client ("embedder") to call |nvim_ui_attach()| + before sourcing startup files and reading buffers, so that UIs + can deterministically handle (display) early messages, + dialogs, etc. The client can do other requests before + `nvim_ui_attach` (e.g. `nvim_get_api_info` for feature-detection). + During this pre-startup phase the user config is of course not + available (similar to `--cmd`). + + Embedders _not_ using the UI protocol must pass |--headless|: > + nvim --embed --headless + +< Then startup will continue without waiting for `nvim_ui_attach`. + This is equivalent to: > + nvim --headless --cmd "call stdioopen({'rpc': v:true})" + +< See also: |ui-startup| |channel-stdio| *--headless* ---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. +--headless Start without UI, and do not wait for `nvim_ui_attach`. The + builtin TUI is not used, so stdio works as an arbitrary + communication channel. |channel-stdio| 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 in or after |VimEnter|. + empty during or after |VimEnter|. To read stdin as text, "-" must be given explicitly: --headless cannot assume that stdin is just text. > |