Doc: $NVIM_LISTEN_ADDRESS is obsolete in nvim

The server should be started with `nvim --listen /tmp/nvimsocket` or just `nvr`.

When used as client, nvr still supports $NVIM_LISTEN_ADDRESS for backward
compatibility.

README.md

@@ -31,12 +31,12 @@ If you encounter any issues, e.g. permission denied errors or you can't find the
 
 ## Theory
 
-Nvim always starts a server. Get its address via `:echo $NVIM_LISTEN_ADDRESS` or
+**Nvim** always starts a server. Get its address with `:echo v:servername`. Or
-`:echo v:servername`. Or specify an address at startup:
+specify an address at startup: `nvim --listen /tmp/nvimsocket`.
-`NVIM_LISTEN_ADDRESS=/tmp/nvimsocket nvim`.
 
-**nvr** will use `$NVIM_LISTEN_ADDRESS` or any address given to it via
+**nvr** (the client) will use any address given to it via `--servername`,
-`--servername`.
+`$NVIM_LISTEN_ADDRESS` (obsolete in nvim but still supported in nvr), or
+defaults to `/tmp/nvimsocket`.
 
 If the targeted address does not exist, **nvr** starts a new process by running
 "nvim". You can change the command by setting `$NVR_CMD`. _(This requires
@@ -46,7 +46,7 @@ forking, so it won't work on Windows.)_
 
 Start a nvim process (which acts as a server) in one shell:
 
-    NVIM_LISTEN_ADDRESS=/tmp/nvimsocket nvim
+    nvim --listen /tmp/nvimsocket
 
 And do this in another shell:
 
@@ -155,18 +155,19 @@ Happy hacking!
 
     Easy-peasy! Just `nvr file`.
 
-    This works without any prior setup, because `$NVIM_LISTEN_ADDRESS` is always
+    This works without any prior setup, because `$NVIM` is always set for all
-    set within Nvim. And `nvr` will default to that address.
+    children of the nvim process, including `:terminal`, and `nvr` will default
+    to that address.
 
     I often work with two windows next to each other. If one contains the
     terminal, I can use `nvr -l foo` to open the file in the other window.
 
 - **Open files always in the same nvim process no matter which terminal you're in.**
 
-    If you just run `nvr -s`, a new nvim process will start and set its address
+    Just `nvr -s` starts a new nvim process with the server address set to
-    to `/tmp/nvimsocket` automatically.
+    `/tmp/nvimsocket`.
 
-    Now, no matter in which terminal you are, `nvr file` will always work on
+    Now, no matter which terminal you are in, `nvr file` will always work on
     that nvim process. That is akin to `emacsclient` from Emacs.
 
 - **Use nvr in plugins.**

nvr/nvr.py

@@ -309,36 +309,40 @@ def parse_args(argv):
 
 
 def show_message(address):
-    print(textwrap.dedent('''
+    print(textwrap.dedent(f'''
-        [!] Can't connect to: {}
+        [!] Can't connect to: {address}
 
             The server (nvim) and client (nvr) have to use the same address.
 
             Server:
 
-                Expose $NVIM_LISTEN_ADDRESS to the environment before
+                Specify the server address when starting nvim:
-                starting nvim:
 
-                $ NVIM_LISTEN_ADDRESS={} nvim
+                $ nvim --listen {address}
 
                 Use `:echo v:servername` to verify the address.
 
-                Security: When using Unix domain sockets on a multi-user system,
+                Alternatively, run nvr without arguments. It defaults to
-                the socket should have proper permissions so that it is only
+                starting a new nvim process with the server name set to
-                accessible by your user.
+                "/tmp/nvimsocket".
+
+                Security: When using an Unix domain socket, that socket should
+                have proper permissions so that it is only accessible by your
+                user.
 
             Client:
 
-                Expose $NVIM_LISTEN_ADDRESS to the environment before
+                Expose $NVIM_LISTEN_ADDRESS (obsolete in nvim but still
-                using nvr or use its --servername option. If neither
+                supported by nvr) to the environment before using nvr or use
-                is given, nvr assumes \"/tmp/nvimsocket\".
+                its --servername option. If neither is given, nvr assumes
+                \"/tmp/nvimsocket\".
 
-                $ NVIM_LISTEN_ADDRESS={} nvr file1 file2
+                $ NVIM_LISTEN_ADDRESS={address} nvr file1 file2
-                $ nvr --servername {} file1 file2
+                $ nvr --servername {address} file1 file2
                 $ nvr --servername 127.0.0.1:6789 file1 file2
 
             Use -s to suppress this message.
-        '''.format(address, address, address, address)))
+        '''))
 
 
 def split_cmds_from_files(args):