bug#66598: Missing options from emacsclient man page

bug#66598: Missing options from emacsclient man page

[Peter Oliver]

[-- Attachment #1: Type: text/plain, Size: 350 bytes --]

On Tue, 17 Oct 2023, Michael Albinus wrote:

> Since Emacs 26, emacsclient is prepared for this. If you call
> "emacsclient --tramp=<PREFIX>", all file names on the server side,
> emacsclient sends as "/path/to/file", are "<PREFIX>/path/to/file".

Attached is a patch to mention this (and other) options in the emacsclient man page.

-- 
Peter Oliver

[-- Attachment #2: Type: text/plain, Size: 1915 bytes --]

From c96e974073556d24da93332b4edb30da88a3ea8a Mon Sep 17 00:00:00 2001
From: Peter Oliver <git@mavit.org.uk>
Date: Tue, 17 Oct 2023 19:11:33 +0100
Subject: [PATCH] Document all emacsclient options in its man page

* doc/man/emacsclient.1: Document omitted options.
---
 doc/man/emacsclient.1 | 27 +++++++++++++++++++++++++--
 1 file changed, 25 insertions(+), 2 deletions(-)

diff --git a/doc/man/emacsclient.1 b/doc/man/emacsclient.1
index 83c8a366f8b..a72e75129f9 100644
--- a/doc/man/emacsclient.1
+++ b/doc/man/emacsclient.1
@@ -94,13 +94,36 @@ Emacs.  If combined with --eval, this option is ignored.
 How long to wait, in seconds, for Emacs to respond before giving up.
 The default is 0, which means to wait forever.
 .TP
-.B \-nw, \-t, \-\-tty
-Open a new Emacs frame on the current terminal.
+.B \-\-parent-id=ID
+Open an
+.B emacsclient
+frame as a client frame in the parent X window with id ID, via the
+XEmbed protocol.
+.TP
+.B \-q, \-\-quiet
+Do not display messages about waiting for Emacs or connecting to
+remote server sockets.
+.TP
+.B \-u, \-\-suppress-output
+Do not display results returned from the server.
 .TP
 .B \-s, \-\-socket-name=FILENAME
 Use socket named FILENAME for communication.
 This can also be specified via the EMACS_SOCKET_NAME environment variable.
 .TP
+.B \-t, \-\-tty, \-nw
+Open a new Emacs frame on the current terminal.
+.TP
+.B \-T, \-\-tramp-prefix=TRAMP-PREFIX’
+Set the 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 a forwarded port or socket.
+
+Setting the environment variable
+.B EMACSCLIENT_TRAMP
+has the same effect as using this option.  If both are specified, the
+command-line option takes precedence.
+.TP
 .B \-V, \-\-version
 Print version information and exit.
 .TP
-- 
2.41.0

bug#66598: Missing options from emacsclient man page

[Michael Albinus]

Peter Oliver <p.d.oliver@mavit.org.uk> writes:

Hi Peter,

>> Since Emacs 26, emacsclient is prepared for this. If you call
>> "emacsclient --tramp=<PREFIX>", all file names on the server side,
>> emacsclient sends as "/path/to/file", are "<PREFIX>/path/to/file".
>
> Attached is a patch to mention this (and other) options in the emacsclient man page.

Thanks for the report. 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.

Since I'm not that fluent with the nroff format, you might cross-check
whether everything is right. And perhaps we could also add an
ENVIRONMENT section.

> Peter Oliver

Best regards, Michael.

bug#66598: Missing options from emacsclient man page

[Peter Oliver]

[-- Attachment #1: Type: text/plain, Size: 564 bytes --]

On Wed, 18 Oct 2023, Michael Albinus wrote:

> Peter Oliver <p.d.oliver@mavit.org.uk> 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

[-- Attachment #2: Type: text/plain, Size: 3536 bytes --]

From f492af1a75e8f47ca6e50a1f59b0922ce24907de Mon Sep 17 00:00:00 2001
From: Peter Oliver <git@mavit.org.uk>
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

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.

bug#66598: Missing options from emacsclient man page

[Michael Albinus]

Peter Oliver <p.d.oliver@mavit.org.uk> writes:

Hi Peter,

>> And perhaps we could also add an ENVIRONMENT section.
>
> Attached is a patch to do that.

Thanks for this. Eli gave you already comments, so here are just my
additional ones.

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

I'm not sure whether we shall mention here the alternative "socket
forwarded over SSH". This is indeed the only existing alternative for
the --server-file option in Emacs 29, but I have rough plans to offer
also network processes in Tramp, which would add more flexibility, and
less configuration need for users. But this is in an early phase of
thinking only ATM.

So perhaps it is OK to mention "socket forwarded over SSH" here in Emacs 29.

> +.SH ENVIRONMENT
> +.TP
> +.B ALTERNATE_EDITOR
> +.TP
> +.B EMACSCLIENT_TRAMP
> +.TP
> +.B EMACS_SERVER_FILE
> +.TP
> +.B EMACS_SOCKET_NAME

Reading emacsclient.c, there are also further environment variables:

XDG_CONFIG_HOME
XDG_RUNTIME_DIR

I'm undecided whether we shall mention them. Eli?

> Peter Oliver

Best regards, Michael.

bug#66598: Missing options from emacsclient man page

[Eli Zaretskii]

> From: Michael Albinus <michael.albinus@gmx.de>
> Date: Sat, 21 Oct 2023 16:35:05 +0200
> Cc: 66598@debbugs.gnu.org
> 
> > +.SH ENVIRONMENT
> > +.TP
> > +.B ALTERNATE_EDITOR
> > +.TP
> > +.B EMACSCLIENT_TRAMP
> > +.TP
> > +.B EMACS_SERVER_FILE
> > +.TP
> > +.B EMACS_SOCKET_NAME
> 
> Reading emacsclient.c, there are also further environment variables:
> 
> XDG_CONFIG_HOME
> XDG_RUNTIME_DIR
> 
> I'm undecided whether we shall mention them. Eli?

I don't see how it could cause any harm to mention them as well.

bug#66598: Missing options from emacsclient man page

[Peter Oliver]

[-- Attachment #1: Type: text/plain, Size: 626 bytes --]

On Sun, 29 Oct 2023, Eli Zaretskii wrote:

>> From: Michael Albinus <michael.albinus@gmx.de>
>> Date: Sat, 21 Oct 2023 16:35:05 +0200
>> Cc: 66598@debbugs.gnu.org
>>
>>> +.SH ENVIRONMENT
>>> +.TP
>>> +.B ALTERNATE_EDITOR
>>> +.TP
>>> +.B EMACSCLIENT_TRAMP
>>> +.TP
>>> +.B EMACS_SERVER_FILE
>>> +.TP
>>> +.B EMACS_SOCKET_NAME
>>
>> Reading emacsclient.c, there are also further environment variables:
>>
>> XDG_CONFIG_HOME
>> XDG_RUNTIME_DIR
>>
>> I'm undecided whether we shall mention them. Eli?
>
> I don't see how it could cause any harm to mention them as well.

Here is an updated patch that does that.

-- 
Peter Oliver

[-- Attachment #2: Type: text/plain, Size: 4620 bytes --]

From 77c38e54a75c0e16e41e047d213e41b3374161e1 Mon Sep 17 00:00:00 2001
From: Peter Oliver <git@mavit.org.uk>
Date: Sat, 21 Oct 2023 14:02:06 +0100
Subject: [PATCH] * doc/man/emacsclient.1: Add an ENVIRONMENT section.

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

diff --git a/doc/man/emacsclient.1 b/doc/man/emacsclient.1
index 0acf3dd339e..b04923262de 100644
--- a/doc/man/emacsclient.1
+++ b/doc/man/emacsclient.1
@@ -62,9 +62,11 @@ 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
+If the empty string is specified, run "emacs \-\-daemon" to
 start Emacs in daemon mode, and try to connect to it.
+
+See also the ALTERNATE_EDITOR environment variable, over which this
+option takes precedence.
 .TP
 .B -c, \-\-create-frame
 Create a new frame instead of trying to use the current Emacs frame.
@@ -84,7 +86,11 @@ 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.
+Relative filenames are relative to "~/.emacs.d/server/" or
+"$XDG_CONFIG_HOME/emacs/server/", and the default is "server".
+
+See also the EMACS_SERVER_FILE environment variable, over which this
+option takes precedence.
 .TP
 .B \-n, \-\-no-wait
 Return immediately without waiting for you to "finish" the buffer in
@@ -114,7 +120,10 @@ 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.
+Relative filenames are relative to "$XDG_RUNTIME_DIR/emacs/" or "$TMPDIR/".
+
+See also the EMACS_SOCKET_NAME environment variable, over which this
+option takes precedence.
 .TP
 .B \-nw, \-t, \-\-tty
 Open a new Emacs frame on the current terminal.
@@ -122,8 +131,11 @@ Open a new Emacs frame on the current terminal.
 .B \-T, \-\-tramp=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).
+
+See also the EMACSCLIENT_TRAMP environment variable, over which this
+option takes precedence.
 .TP
 .B \-V, \-\-version
 Print version information and exit.
@@ -133,10 +145,46 @@ 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.  Will be overridden by the
+.B \-\-alternate-editor
+option, if present.
+.TP
+.B EMACSCLIENT_TRAMP
+A prefix to add to filenames, intended to allow Emacs to locate files
+on remote machines using TRAMP.  Will be overridden by the
+.B \-\-tramp-prefix
+option, if present.
+.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/" or
+"$XDG_CONFIG_HOME/emacs/server/", and the
+default is "server".  Will be overridden by the
+.B \-\-server-file
+option, if present.
+.TP
+.B EMACS_SOCKET_NAME
+The filename of the socket to use for communication with the Emacs server.
+Relative filenames are relative to "$XDG_RUNTIME_DIR/emacs/" or "$TMPDIR/".
+Will be overridden by the
+.B \-\-socket-name
+option, if present.
 .SH "SEE ALSO"
 The program is documented fully in
 .IR "Using Emacs as a Server"
 available via the Info system.
+
+The XDG_ environment variables are described in detail in the
+.UR https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
+XDG Base Directory Specification
+.UE .
+
 .SH AUTHOR
 This manual page was originally written by Stephane Bortzmeyer
 <bortzmeyer@debian.org>, for the Debian GNU/Linux system, but is not
-- 
2.43.0

bug#66598: Missing options from emacsclient man page

[Eli Zaretskii]

> Date: Sun, 17 Dec 2023 12:58:47 +0000 (GMT)
> From: Peter Oliver <p.d.oliver@mavit.org.uk>
> cc: Michael Albinus <michael.albinus@gmx.de>, 66598@debbugs.gnu.org
> 
> On Sun, 29 Oct 2023, Eli Zaretskii wrote:
> 
> >> Reading emacsclient.c, there are also further environment variables:
> >>
> >> XDG_CONFIG_HOME
> >> XDG_RUNTIME_DIR
> >>
> >> I'm undecided whether we shall mention them. Eli?
> >
> > I don't see how it could cause any harm to mention them as well.
> 
> Here is an updated patch that does that.

Thanks, installed on the emacs-29 branch, and closing the bug.

Btw, I don't see your copyright assignment on file; did you sign one?
If not, would you like to start your legal paperwork at this time, so
that we could accept your contributions in the future without
limitations?