Improve documentation of 'server-name'

* doc/emacs/misc.texi (Emacs Server, TCP Emacs server)
(emacsclient Options):
* lisp/server.el (server-name):  Document the usage of
'server-name' to specify the server file as an absolute file
name.  Do not merge to master.  (Bug#33934)

2 files changed, 23 insertions, 9 deletions

diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index 41a540a7610..2d1617ef964 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -1646,7 +1646,9 @@ each one a unique @dfn{server name}, using the variable
 @code{server-name}.  For example, @kbd{M-x set-variable @key{RET}
 server-name @key{RET} "foo" @key{RET}} sets the server name to
 @samp{foo}.  The @code{emacsclient} program can specify a server by
-name, using the @samp{-s} option (@pxref{emacsclient Options}).
+name, using the @samp{-s} or the @samp{-f} option (@pxref{emacsclient
+Options}), depending on whether or not the server uses a TCP socket
+(@pxref{TCP Emacs server}).
 
   If you want to run multiple Emacs daemons (@pxref{Initial Options}),
 you can give each daemon its own server name like this:
@@ -1711,18 +1713,20 @@ use @kbd{M-x server-generate-key} to get a random key.
   When you start a TCP Emacs server, Emacs creates a @dfn{server file}
 containing the TCP information to be used by @command{emacsclient} to
 connect to the server.  The variable @code{server-auth-dir} specifies
-the directory containing the server file; by default, this is
+the default directory containing the server file; by default, this is
 @file{~/.emacs.d/server/}.  In the absence of a local socket with file
 permissions, the permissions of this directory determine which users
 can have their @command{emacsclient} processes talk to the Emacs
-server.
+server.  If @code{server-name} is an absolute file name, the server
+file is created where specified by that file name.
 
 @vindex EMACS_SERVER_FILE@r{, environment variable}
   To tell @command{emacsclient} to connect to the server over TCP with
 a specific server file, use the @samp{-f} or @samp{--server-file}
 option, or set the @env{EMACS_SERVER_FILE} environment variable
 (@pxref{emacsclient Options}).  If @code{server-auth-dir} is set to a
-non-standard value, @command{emacsclient} needs an absolute file name
+non-standard value, or if @code{server-name} is set to an absolute
+file name, @command{emacsclient} needs an absolute file name
 to the server file, as the default @code{server-auth-dir} is
 hard-coded in @command{emacsclient} to be used as the directory for
 resolving relative filenames.
@@ -1914,10 +1918,13 @@ evaluation performed is for side-effect rather than result.
 
 @item -s @var{server-name}
 @itemx --socket-name=@var{server-name}
-Connect to the Emacs server named @var{server-name}.  The server name
-is given by the variable @code{server-name} on the Emacs server.  If
-this option is omitted, @command{emacsclient} connects to the first
-server it finds.  (This option is not supported on MS-Windows.)
+Connect to the Emacs server named @var{server-name}.  (This option is
+not supported on MS-Windows.)  The server name is given by the
+variable @code{server-name} on the Emacs server.  If this option is
+omitted, @command{emacsclient} connects to the first server it finds.
+If you set @code{server-name} of the Emacs server to an absolute file
+name, give the same absolute file name as @var{server-name} to this
+option to instruct @command{emacsclient} to connect to that server.
 
 @item -t
 @itemx --tty
diff --git a/lisp/server.el b/lisp/server.el
index 599f2728b99..a39b1cb46d4 100644
--- a/lisp/server.el
+++ b/lisp/server.el
@@ -255,7 +255,14 @@ are done with it in the server.")
 (defcustom server-name "server"
   "The name of the Emacs server, if this Emacs process creates one.
 The command `server-start' makes use of this.  It should not be
-changed while a server is running."
+changed while a server is running.
+If this is a file name with no leading directories, Emacs will
+create a socket file by that name under `server-socket-dir'
+if `server-use-tcp' is nil, else under `server-auth-dir'.
+If this is an absolute file name, it specifies where the socket
+file will be created.  To have emacsclient connect to the same
+socket, use the \"-s\" switch for local non-TCP sockets, and
+the \"-f\" switch otherwise."
   :group 'server
   :type 'string
   :version "23.1")