docs(remote): update remote.txt for current nvim implementation

1 files changed, 55 insertions, 113 deletions

diff --git a/runtime/doc/remote.txt b/runtime/doc/remote.txt
index 6c2ceb45be..dd5d44387d 100644
--- a/runtime/doc/remote.txt
+++ b/runtime/doc/remote.txt
@@ -11,9 +11,10 @@ Vim client-server communication				*client-server*
 ==============================================================================
 1. Common functionality					*clientserver*
 
-When compiled with the |+clientserver| option, Vim can act as a command
-server.  It accepts messages from a client and executes them.  At the same
-time, Vim can function as a client and send commands to a Vim server.
+Nvim's |RPC| functionality allows clients to programmatically control Nvim. Nvim
+itself takes command-line arguments that cause it to become a client to another
+Nvim running as a server. These arguments match those provided by Vim's
+clientserver option.
 
 The following command line arguments are available:
 
@@ -22,39 +23,27 @@ The following command line arguments are available:
    --remote [+{cmd}] {file} ...					*--remote*
 				Open the file list in a remote Vim.  When
 				there is no Vim server, execute locally.
-				There is one optional init command: +{cmd}.
+				Vim allows one init command: +{cmd}.
 				This must be an Ex command that can be
-				followed by "|".
+				followed by "|". It's not yet supported by
+				Nvim.
 				The rest of the command line is taken as the
 				file list.  Thus any non-file arguments must
 				come before this.
 				You cannot edit stdin this way |--|.
 				The remote Vim is raised.  If you don't want
 				this use >
-				 vim --remote-send "<C-\><C-N>:n filename<CR>"
+				 nvim --remote-send "<C-\><C-N>:n filename<CR>"
 <
    --remote-silent [+{cmd}] {file} ...			*--remote-silent*
 				As above, but don't complain if there is no
 				server and the file is edited locally.
-   --remote-wait [+{cmd}] {file} ...				*--remote-wait*
-				As --remote, but wait for files to complete
-				(unload) in remote Vim.
-   --remote-wait-silent [+{cmd}] {file} ...		*--remote-wait-silent*
-				As --remote-wait, but don't complain if there
-				is no server.
 							*--remote-tab*
    --remote-tab			Like --remote but open each file in a new
 				tabpage.
 							*--remote-tab-silent*
    --remote-tab-silent		Like --remote-silent but open each file in a
 				new tabpage.
-							*--remote-tab-wait*
-   --remote-tab-wait		Like --remote-wait but open each file in a new
-				tabpage.
-
-						*--remote-tab-wait-silent*
-   --remote-tab-wait-silent	Like --remote-wait-silent but open each file
-				in a new tabpage.
 								*--remote-send*
    --remote-send {keys}		Send {keys} to server and exit.  The {keys}
    				are not mapped.  Special key names are
@@ -63,127 +52,80 @@ The following command line arguments are available:
 								*--remote-expr*
    --remote-expr {expr}		Evaluate {expr} in server and print the result
 				on stdout.
+								*--server*
+   --server {addr}		Connect to the named pipe or socket at the
+				given address for executing remote commands.
+				See |--listen| for specifying an address when
+				starting a server.
 
 Examples ~
 
-Edit "file.txt" in an already running GVIM server: >
-    gvim --remote file.txt
-
-Edit "file.txt" in an already running server called FOOBAR: >
-    gvim --servername FOOBAR --remote file.txt
+Start an Nvim server listening on a named pipe at '~/.cache/nvim/server.pipe': >
+    nvim --listen ~/.cache/nvim/server.pipe
 
-Edit "file.txt" in server "FILES" if it exists, become server "FILES"
-otherwise: >
-    gvim --servername FILES --remote-silent file.txt
+Edit "file.txt" in an Nvim server listening at '~/.cache/nvim/server.pipe': >
+    nvim --server ~/.cache/nvim/server.pipe --remote file.txt
 
 This doesn't work, all arguments after --remote will be used as file names: >
-    gvim --remote --servername FOOBAR file.txt
-
-Edit file "+foo" in a remote server (note the use of "./" to avoid the special
-meaning of the leading plus): >
-    vim --remote ./+foo
-
-Tell the remote server "BLA" to write all files and exit: >
-    vim --servername BLA --remote-send '<C-\><C-N>:wqa<CR>'
-
-
-SERVER NAME						*client-server-name*
-
-By default Vim will try to register the name under which it was invoked (gvim,
-egvim ...).  This can be overridden with the --servername argument.  If the
-specified name is not available, a postfix is applied until a free name is
-encountered, i.e. "gvim1" for the second invocation of gvim on a particular
-X-server.  The resulting name is available in the servername builtin variable
-|v:servername|.  The case of the server name is ignored, thus "gvim" and
-"GVIM" are considered equal.
-
-When Vim is invoked with --remote, --remote-wait or --remote-send it will try
-to locate the server name determined by the invocation name and --servername
-argument as described above.  If an exact match is not available, the first
-server with the number postfix will be used.  If a name with the number
-postfix is specified with the --servername argument, it must match exactly.
+    nvim --remote --server ~/.cache/nvim/server.pipe file.txt
 
-If no server can be located and --remote or --remote-wait was used, Vim will
-start up according to the rest of the command line and do the editing by
-itself.  This way it is not necessary to know whether gvim is already started
-when sending command to it.
-
-The --serverlist argument will cause Vim to print a list of registered command
-servers on the standard output (stdout) and exit.
-
-Win32 Note: Making the Vim server go to the foreground doesn't always work,
-because MS-Windows doesn't allow it.  The client will move the server to the
-foreground when using the --remote or --remote-wait argument and the server
-name starts with "g".
+Tell the remote server to write all files and exit: >
+    nvim --server ~/.cache/nvim/server.pipe --remote-send '<C-\><C-N>:wqa<CR>'
 
 
 REMOTE EDITING
 
 The --remote argument will cause a |:drop| command to be constructed from the
 rest of the command line and sent as described above.
-The --remote-wait argument does the same thing and additionally sets up to
-wait for each of the files to have been edited.  This uses the BufUnload
-event, thus as soon as a file has been unloaded, Vim assumes you are done
-editing it.
 Note that the --remote and --remote-wait arguments will consume the rest of
 the command line.  I.e. all remaining arguments will be regarded as filenames.
 You can not put options there!
 
 
-FUNCTIONS
-								*E240* *E573*
-There are a number of Vim functions for scripting the command server.  See
-the description in |eval.txt| or use CTRL-] on the function name to jump to
-the full explanation.
-
-    synopsis				     explanation ~
-    remote_startserver( name)		     run a server
-    remote_expr( server, string, idvar)      send expression
-    remote_send( server, string, idvar)      send key sequence
-    serverlist()			     get a list of available servers
-    remote_peek( serverid, retvar)	     check for reply string
-    remote_read( serverid)		     read reply string
-    server2client( serverid, string)	     send reply string
-    remote_foreground( server)		     bring server to the front
-
-See also the explanation of |CTRL-\_CTRL-N|.  Very useful as a leading key
-sequence.
-The {serverid} for server2client() can be obtained with expand("<client>")
-
 ==============================================================================
-2. X11 specific items					*x11-clientserver*
-				    *E247* *E248* *E251* *E258* *E277*
+2. Missing functionality				*clientserver-missing*
 
-The communication between client and server goes through the X server.  The
-display of the Vim server must be specified.  The usual protection of the X
-server is used, you must be able to open a window on the X server for the
-communication to work.  It is possible to communicate between different
-systems.
+Vim supports additional functionality in clientserver that's not yet
+implemented in Nvim. In particular, none of the 'wait' variants are supported
+yet. The following command line arguments are not yet available:
 
-By default, a GUI Vim will register a name on the X-server by which it can be
-addressed for subsequent execution of injected strings.  Vim can also act as
-a client and send strings to other instances of Vim on the same X11 display.
+    argument			meaning	~
 
-When an X11 GUI Vim (gvim) is started, it will try to register a send-server
-name on the 'VimRegistry' property on the root window.
+   --remote-wait [+{cmd}] {file} ...				*--remote-wait*
+				Not yet supported by Nvim.
+				As --remote, but wait for files to complete
+				(unload) in remote Vim.
+   --remote-wait-silent [+{cmd}] {file} ...		*--remote-wait-silent*
+				Not yet supported by Nvim.
+				As --remote-wait, but don't complain if there
+				is no server.
+							*--remote-tab-wait*
+   --remote-tab-wait		Not yet supported by Nvim.
+				Like --remote-wait but open each file in a new
+				tabpage.
+						*--remote-tab-wait-silent*
+   --remote-tab-wait-silent	Not yet supported by Nvim.
+				Like --remote-wait-silent but open each file
+				in a new tabpage.
+							    *--servername*
+   --servername {name}          Not yet supported by Nvim.
+				Become the server {name}.  When used together
+                                with one of the --remote commands: connect to
+                                server {name} instead of the default (see
+                                below).  The name used will be uppercase.
 
-An empty --servername argument will cause the command server to be disabled.
+								*--serverlist*
+   --serverlist			Not yet supported by Nvim.
+				Output a list of server names.
 
-To send commands to a Vim server from another application, read the source
-file src/if_xcmdsrv.c, it contains some hints about the protocol used.
 
-==============================================================================
-3. Win32 specific items					*w32-clientserver*
 
-Every Win32 Vim can work as a server, also in the console.  You do not need a
-version compiled with OLE.  Windows messages are used, this works on any
-version of MS-Windows.  But only communication within one system is possible.
 
-Since MS-Windows messages are used, any other application should be able to
-communicate with a Vim server.
+SERVER NAME						*client-server-name*
 
-When using gvim, the --remote-wait only works properly this way: >
+By default Vim will try to register the name under which it was invoked (gvim,
+egvim ...).  This can be overridden with the --servername argument.  Nvim
+either listens on a named pipe or a socket and does not yet support this
+--servername functionality.
 
-	start /w gvim --remote-wait file.txt
-<
  vim:tw=78:sw=4:ts=8:noet:ft=help:norl: