GNU bug report logs - #66598
Missing options from emacsclient man page

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 66598 in the body.
You can then email your comments to 66598 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Peter Oliver <p.d.oliver <at> mavit.org.uk>
To: bug-gnu-emacs <at> gnu.org
Subject: Missing options from emacsclient man page
Date: Tue, 17 Oct 2023 19:24:33 +0100 (BST)

[Message part 1 (text/plain, inline)]

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

[0001-Document-all-emacsclient-options-in-its-man-page.patch (text/plain, attachment)]

Message #8 received at 66598 <at> debbugs.gnu.org (full text, mbox):

From: Michael Albinus <michael.albinus <at> gmx.de>
To: Peter Oliver <p.d.oliver <at> mavit.org.uk>
Cc: 66598 <at> debbugs.gnu.org
Subject: Re: bug#66598: Missing options from emacsclient man page
Date: Wed, 18 Oct 2023 07:16:27 +0200

Peter Oliver <p.d.oliver <at> 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.

Message #11 received at 66598 <at> debbugs.gnu.org (full text, mbox):

From: Peter Oliver <p.d.oliver <at> mavit.org.uk>
To: Michael Albinus <michael.albinus <at> gmx.de>
Cc: 66598 <at> debbugs.gnu.org
Subject: Re: bug#66598: Missing options from emacsclient man page
Date: Sat, 21 Oct 2023 14:05:40 +0100 (BST)

[Message part 1 (text/plain, inline)]

On Wed, 18 Oct 2023, Michael Albinus wrote:

> Peter Oliver <p.d.oliver <at> 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

[0001-doc-man-emacsclient.1-Add-an-ENVIRONMENT-section.patch (text/plain, attachment)]

Message #14 received at 66598 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Peter Oliver <p.d.oliver <at> mavit.org.uk>
Cc: 66598 <at> debbugs.gnu.org, michael.albinus <at> gmx.de
Subject: Re: bug#66598: Missing options from emacsclient man page
Date: Sat, 21 Oct 2023 16:31:33 +0300

> Cc: 66598 <at> debbugs.gnu.org
> Date: Sat, 21 Oct 2023 14:05:40 +0100 (BST)
> From: Peter Oliver <p.d.oliver <at> 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.

Message #17 received at 66598 <at> debbugs.gnu.org (full text, mbox):

From: Michael Albinus <michael.albinus <at> gmx.de>
To: Peter Oliver <p.d.oliver <at> mavit.org.uk>
Cc: 66598 <at> debbugs.gnu.org
Subject: Re: bug#66598: Missing options from emacsclient man page
Date: Sat, 21 Oct 2023 16:35:05 +0200

Peter Oliver <p.d.oliver <at> 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.

Message #22 received at 66598 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Michael Albinus <michael.albinus <at> gmx.de>
Cc: 66598 <at> debbugs.gnu.org, p.d.oliver <at> mavit.org.uk
Subject: Re: bug#66598: Missing options from emacsclient man page
Date: Sun, 29 Oct 2023 13:27:31 +0200

> From: Michael Albinus <michael.albinus <at> gmx.de>
> Date: Sat, 21 Oct 2023 16:35:05 +0200
> Cc: 66598 <at> 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.

Message #25 received at 66598 <at> debbugs.gnu.org (full text, mbox):

From: Peter Oliver <p.d.oliver <at> mavit.org.uk>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 66598 <at> debbugs.gnu.org, Michael Albinus <michael.albinus <at> gmx.de>
Subject: Re: bug#66598: Missing options from emacsclient man page
Date: Sun, 17 Dec 2023 12:58:47 +0000 (GMT)

[Message part 1 (text/plain, inline)]

On Sun, 29 Oct 2023, Eli Zaretskii wrote:

>> From: Michael Albinus <michael.albinus <at> gmx.de>
>> Date: Sat, 21 Oct 2023 16:35:05 +0200
>> Cc: 66598 <at> 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

[0001-doc-man-emacsclient.1-Add-an-ENVIRONMENT-section.patch (text/plain, attachment)]

Message #30 received at 66598-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Peter Oliver <p.d.oliver <at> mavit.org.uk>
Cc: 66598-done <at> debbugs.gnu.org, michael.albinus <at> gmx.de
Subject: Re: bug#66598: Missing options from emacsclient man page
Date: Sat, 23 Dec 2023 11:51:03 +0200

> Date: Sun, 17 Dec 2023 12:58:47 +0000 (GMT)
> From: Peter Oliver <p.d.oliver <at> mavit.org.uk>
> cc: Michael Albinus <michael.albinus <at> gmx.de>, 66598 <at> 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?

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.