Subject: Re: bug#66598: Missing options from emacsclient man page

From: Peter Oliver <[email-masked]>
Date: Sat, 21 Oct 2023 14:05:40 +0100 (BST)

On Wed, 18 Oct 2023, Michael Albinus wrote:

> Peter Oliver <[email-masked]> writes:
>
> Yes, the recent options haven't been added to the
> man page. I've seen this while writing my message you've quoted, and
> I've fixed this in the emacs-29 branch two days ago.

Ah, sorry, I didn’t think to look on the emacs-29 branch.

> Since I'm not that fluent with the nroff format, you might cross-check
> whether everything is right.

Looks good to me.

> And perhaps we could also add an ENVIRONMENT section.

Attached is a patch to do that.

-- 
Peter Oliver

From f492af1a75e8f47ca6e50a1f59b0922ce24907de Mon Sep 17 00:00:00 2001
From: Peter Oliver <[email-masked]>
Date: Sat, 21 Oct 2023 14:02:06 +0100
Subject: [PATCH] * doc/man/emacsclient.1: Add an ENVIRONMENT section.

---
 doc/man/emacsclient.1 | 34 ++++++++++++++++++++++++++++------
 1 file changed, 28 insertions(+), 6 deletions(-)

diff --git a/doc/man/emacsclient.1 b/doc/man/emacsclient.1
index acc2edd4609..42312f24fb3 100644
--- a/doc/man/emacsclient.1
+++ b/doc/man/emacsclient.1
@@ -62,8 +62,8 @@ This option applies only to the next file specified.
 .TP
 .B \-a, \-\-alternate-editor=COMMAND
 If the Emacs server is not running, run the specified shell command instead.
-This can also be specified via the ALTERNATE_EDITOR environment variable.
-If the value of ALTERNATE_EDITOR is the empty string, run "emacs \-\-daemon" to
+This takes precedence over the ALTERNATE_EDITOR environment variable.
+If the empty string is specified, run "emacs \-\-daemon" to
 start Emacs in daemon mode, and try to connect to it.
 .TP
 .B -c, \-\-create-frame
@@ -84,7 +84,9 @@ Lisp expressions.
 .TP
 .B \-f, \-\-server-file=FILENAME
 Use TCP configuration file FILENAME for communication.
-This can also be specified via the EMACS_SERVER_FILE environment variable.
+This takes precedence over the EMACS_SERVER_FILE environment variable.
+Relative filenames are relative to "~/.emacs.d/server/", and the
+default is "server".
 .TP
 .B \-n, \-\-no-wait
 Return immediately without waiting for you to "finish" the buffer in
@@ -114,7 +116,7 @@ side-effect rather than result.
 .TP
 .B \-s, \-\-socket-name=FILENAME
 Use socket named FILENAME for communication.
-This can also be specified via the EMACS_SOCKET_NAME environment variable.
+This takes precedence over the EMACS_SOCKET_NAME environment variable.
 .TP
 .B \-nw, \-t, \-\-tty
 Open a new Emacs frame on the current terminal.
@@ -122,8 +124,9 @@ Open a new Emacs frame on the current terminal.
 .B \-T, \-\-tramp-prefix=PREFIX
 Set PREFIX to add to filenames for Emacs to locate files on remote
 machines using TRAMP.  This is mostly useful in combination with using
-the Emacs server over TCP with --server-file.  This can also be
-specified via the EMACSCLIENT_TRAMP environment variable.
+the Emacs server on a remote host (either using TCP with
+--server-file, or a socket forwarded over SSH).  This takes precedence
+over the EMACSCLIENT_TRAMP environment variable.
 .TP
 .B \-V, \-\-version
 Print version information and exit.
@@ -133,6 +136,25 @@ Print this usage information message and exit.
 .SH "EXIT STATUS"
 Normally, the exit status is 0.  If emacsclient shuts down due to
 Emacs signaling an error, the exit status is 1.
+.SH ENVIRONMENT
+.TP
+.B ALTERNATE_EDITOR
+If the Emacs server is not running, run the shell command in this
+environment variable instead.  If set to the empty string, run
+"emacs \-\-daemon" to start Emacs in daemon mode, and try to connect
+to it.
+.TP
+.B EMACSCLIENT_TRAMP
+A prefix to add to filenames, intended to allow Emacs to locate files
+on remote machines using TRAMP.
+.TP
+.B EMACS_SERVER_FILE
+Look in this file to discover where to find a TCP Emacs server.
+Relative filenames are relative to "~/.emacs.d/server/", and the
+default is "server".
+.TP
+.B EMACS_SOCKET_NAME
+The filename of the socket to use for communication with the Emacs server.
 .SH "SEE ALSO"
 The program is documented fully in
 .IR "Using Emacs as a Server"
-- 
2.41.0