bug#66598: Missing options from emacsclient man page

[Eli Zaretskii]

> Cc: 66598@debbugs.gnu.org
> Date: Sat, 21 Oct 2023 14:05:40 +0100 (BST)
> From: Peter Oliver <p.d.oliver@mavit.org.uk>
> 
> On Wed, 18 Oct 2023, Michael Albinus wrote:
> 
> > 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.

Thanks, a couple of comments below.

> @@ -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.

This talks about precedence between the variable and the command-line
option without first introducing the environment variable.  The
precedence part should be not _instead_ of the description of the
variable, but _in_addition_ to it.  It's okay that there's now the
ENVIRONMENT section, but it's too far away, so at least something like
"see ENVIRONMENT below" should be here.

> @@ -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".

Same here.

> @@ -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.

And here.

> @@ -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.

And here.

> @@ -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.

And this section should say that the corresponding command-line
arguments override the environment variables.