GNU bug report logs - #37178
26.2; doc strings of `eshell' and `eshell-buffer-name'

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 37178 in the body.
You can then email your comments to 37178 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: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 26.2; doc strings of `eshell' and `eshell-buffer-name'
Date: Sat, 24 Aug 2019 16:37:50 -0700 (PDT)

This is the `eshell' doc string:

 Create an interactive Eshell buffer.
 The buffer used for Eshell sessions is determined by the value of
 'eshell-buffer-name'.  If there is already an Eshell session active in
 that buffer, Emacs will simply switch to it.  Otherwise, a new session
 will begin.  A numeric prefix arg (as in 'C-u 42 M-x eshell RET')
 switches to the session with that number, creating it if necessary.  A
 nonnumeric prefix arg means to create a new session.  Returns the
 buffer selected (or created).

That's a wall of text.  But the problem to report here is that the
_number_ of a session is unclear.  What is it and, especially, what, if
anything, does it have to do with `eshell-buffer-name'.

Experimenting a bit, a guess is that the names of Eshell buffers use
`eshell-buffer-name' followed, by all but the first, by "<N>", where N =
2,3,4... as additional sessions are created.  And with a numeric prefix
arg M, `eshell' tries to find a session with buffer name ending in <M>.

E.g., I tried `M-x eshell' followed by `C-u M-x eshell'.  The first
created buffer `*eshell*', and the second created buffer `*eshell<2>*'
(not `*eshell<4>*', BTW).

This naming convention should be described in the doc string, in order
to make clear (1) how `eshell-buffer-name' is used as a "base name" and
(2) how the prefix arg relates to the buffer-name convention.

Also, the doc string for variable `eshell-buffer-name' is poor.  That's
really where the use of the value as a "base name" needs to be described
(i.e., make clear what is mean by "base name" and how multiple eshell
buffers are named).


In GNU Emacs 26.2 (build 1, x86_64-w64-mingw32)
 of 2019-04-13
Repository revision: fd1b34bfba8f3f6298df47c8e10b61530426f749
Windowing system distributor `Microsoft Corp.', version 10.0.17763
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 37178 <at> debbugs.gnu.org
Subject: Re: bug#37178: 26.2; doc strings of `eshell' and `eshell-buffer-name'
Date: Sat, 19 Oct 2019 03:00:19 +0200

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

Drew Adams <drew.adams <at> oracle.com> writes:

> This is the `eshell' doc string:
>
>  Create an interactive Eshell buffer.
>  The buffer used for Eshell sessions is determined by the value of
>  'eshell-buffer-name'.  If there is already an Eshell session active in
>  that buffer, Emacs will simply switch to it.  Otherwise, a new session
>  will begin.  A numeric prefix arg (as in 'C-u 42 M-x eshell RET')
>  switches to the session with that number, creating it if necessary.  A
>  nonnumeric prefix arg means to create a new session.  Returns the
>  buffer selected (or created).
>
> That's a wall of text.  But the problem to report here is that the
> _number_ of a session is unclear.  What is it and, especially, what, if
> anything, does it have to do with `eshell-buffer-name'.
>
> Experimenting a bit, a guess is that the names of Eshell buffers use
> `eshell-buffer-name' followed, by all but the first, by "<N>", where N =
> 2,3,4... as additional sessions are created.  And with a numeric prefix
> arg M, `eshell' tries to find a session with buffer name ending in <M>.
>
> E.g., I tried `M-x eshell' followed by `C-u M-x eshell'.  The first
> created buffer `*eshell*', and the second created buffer `*eshell<2>*'
> (not `*eshell<4>*', BTW).
>
> This naming convention should be described in the doc string, in order
> to make clear (1) how `eshell-buffer-name' is used as a "base name" and
> (2) how the prefix arg relates to the buffer-name convention.
>
> Also, the doc string for variable `eshell-buffer-name' is poor.  That's
> really where the use of the value as a "base name" needs to be described
> (i.e., make clear what is mean by "base name" and how multiple eshell
> buffers are named).

How about the attached patch?

Best regards,
Stefan Kangas

[0001-Improve-doc-string-of-eshell-and-eshell-buffer-name.patch (application/octet-stream, attachment)]

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 37178 <at> debbugs.gnu.org
Subject: RE: bug#37178: 26.2; doc strings of `eshell' and `eshell-buffer-name'
Date: Sat, 19 Oct 2019 05:21:19 +0000 (UTC)

> > This is the `eshell' doc string:
> >
> >  Create an interactive Eshell buffer.
> >  The buffer used for Eshell sessions is determined by the value of
> >  'eshell-buffer-name'.  If there is already an Eshell session active
> in
> >  that buffer, Emacs will simply switch to it.  Otherwise, a new
> session
> >  will begin.  A numeric prefix arg (as in 'C-u 42 M-x eshell RET')
> >  switches to the session with that number, creating it if necessary.
> A
> >  nonnumeric prefix arg means to create a new session.  Returns the
> >  buffer selected (or created).
> >
> > That's a wall of text.  But the problem to report here is that the
> > _number_ of a session is unclear.  What is it and, especially, what,
> if
> > anything, does it have to do with `eshell-buffer-name'.
> >
> > Experimenting a bit, a guess is that the names of Eshell buffers use
> > `eshell-buffer-name' followed, by all but the first, by "<N>", where
> N =
> > 2,3,4... as additional sessions are created.  And with a numeric
> prefix
> > arg M, `eshell' tries to find a session with buffer name ending in
> <M>.
> >
> > E.g., I tried `M-x eshell' followed by `C-u M-x eshell'.  The first
> > created buffer `*eshell*', and the second created buffer
> `*eshell<2>*'
> > (not `*eshell<4>*', BTW).
> >
> > This naming convention should be described in the doc string, in
> order
> > to make clear (1) how `eshell-buffer-name' is used as a "base name"
> and
> > (2) how the prefix arg relates to the buffer-name convention.
> >
> > Also, the doc string for variable `eshell-buffer-name' is poor.
> That's
> > really where the use of the value as a "base name" needs to be
> described
> > (i.e., make clear what is mean by "base name" and how multiple eshell
> > buffers are named).
> 
> How about the attached patch?

Yes, thanks; much better.

But the problem I pointed out is still there.

If you use a numeric prefix arg and a buffer with that number already exists, then it is used.  No problem.

But if you use a numeric prefix arg and no buffer with that number exists, it's not true that a buffer with that number is created (as both the original and your patch say).  As mentioned, I tried `C-u' (numerically 4) with one existing buffer, but it created buffer <2>, not <4>.

Instead, a new buffer is created with, as number, the successor of the largest existing one.

Actually, even that might not be correct, if some existing buffers have been deleted.  I don't have time now to check what happens in general - does it pick the successor of the largest existing number? does it pick the first number after an existing one before a hole, i.e., starting to fill in the hole?

E.g., if there are buffers <2>, <3>, and <7>, does it pick <8>? does it pick <4>?

Not very important, but the text as written is not exact.

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 37178 <at> debbugs.gnu.org
Subject: Re: bug#37178: 26.2; doc strings of `eshell' and `eshell-buffer-name'
Date: Sat, 19 Oct 2019 14:22:20 +0200

Drew Adams <drew.adams <at> oracle.com> writes:

> Yes, thanks; much better.

Thanks for reviewing.

> But the problem I pointed out is still there.
>
> If you use a numeric prefix arg and a buffer with that number already exists, then it is used.  No problem.
>
> But if you use a numeric prefix arg and no buffer with that number exists, it's not true that a buffer with that number is created (as both the original and your patch say).  As mentioned, I tried `C-u' (numerically 4) with one existing buffer, but it created buffer <2>, not <4>.
>
> Instead, a new buffer is created with, as number, the successor of the largest existing one.

Indeed.  It treats a plain prefix argument ('C-u') differently from a
numeric prefix argument ('C-u 42').

> Actually, even that might not be correct, if some existing buffers have been deleted.  I don't have time now to check what happens in general - does it pick the successor of the largest existing number? does it pick the first number after an existing one before a hole, i.e., starting to fill in the hole?
>
> E.g., if there are buffers <2>, <3>, and <7>, does it pick <8>? does it pick <4>?

It picks <4> in this case, which I think makes sense.  But I don't
think the doc string needs to go into that level of detail, since that
part of the behaviour is less important than the use cases:

1. Create a new Eshell session, or pop to an existing. (M-x eshell)
2. Create a new Eshell session (C-u M-x eshell)
3. Visit given Eshell session (C-u 2 M-x eshell)

All of that is actually already documented in the suggested doc string:

    Start a new Eshell session, or switch to an already active
    session.  Return the buffer selected (or created).

    With a numeric prefix arg (as in `C-u 42 M-x eshell RET'), switch
    to the session with that number, or create it if it doesn't
    exist.  A nonnumeric prefix arg means to create a new session.

Maybe it could be made more clear, but I don't see how if we also want
to keep it sufficiently succinct.

Best regards,
Stefan Kangas

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 37178 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#37178: 26.2; doc strings of `eshell' and `eshell-buffer-name'
Date: Sat, 19 Oct 2019 15:47:13 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Sat, 19 Oct 2019 14:22:20 +0200
> Cc: 37178 <at> debbugs.gnu.org
> 
> It picks <4> in this case, which I think makes sense.  But I don't
> think the doc string needs to go into that level of detail, since that
> part of the behaviour is less important than the use cases:

I think we don't need to document this specifically, because the
special interpretation of just "C-u" is well documented in the Emacs
manual, and should be familiar to users.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 37178 <at> debbugs.gnu.org
Subject: RE: bug#37178: 26.2; doc strings of `eshell' and `eshell-buffer-name'
Date: Sat, 19 Oct 2019 16:27:11 +0000 (UTC)

> Maybe it could be made more clear, but I don't see how if we also want
> to keep it sufficiently succinct.

If the behavior, when there is no such existing
buffer, is to just create a buffer with a new
number, maybe just say that, instead of saying
that we "create it", where "it" is a "session
with that number".

IOW, say what it does: you get a new buffer,
but we say nothing about the particular number
it gets.

Another possibility is to change the behavior,
to actually create a session with that number
(why not, if that's what the user really asked
for?): create the buffer with number <42>.

Anyway, I'm OK with what you have now.  Thx.
Mentioning these things mostly for completion.

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 37178 <at> debbugs.gnu.org
Subject: Re: bug#37178: 26.2; doc strings of `eshell' and `eshell-buffer-name'
Date: Sun, 20 Oct 2019 15:16:59 +0200

close 37178 27.1
thanks

Drew Adams <drew.adams <at> oracle.com>:

> Another possibility is to change the behavior,
> to actually create a session with that number
> (why not, if that's what the user really asked
> for?): create the buffer with number <42>.

When I say `C-u 42 M-x eshell RET', that's what I get: a new buffer
named "*eshell*<42>".

> Anyway, I'm OK with what you have now.  Thx.
> Mentioning these things mostly for completion.

Thanks.  I've made some minor changes to make it more clear and pushed
the change as commit c1544feba0.  I'm consequently closing this bug.

Best regards,
Stefan Kangas

Previous Next

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