bug#37178: 26.2; doc strings of `eshell' and `eshell-buffer-name'

bug#37178: 26.2; doc strings of `eshell' and `eshell-buffer-name'

[Drew Adams]

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

bug#37178: 26.2; doc strings of `eshell' and `eshell-buffer-name'

[Stefan Kangas]

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

Drew Adams <drew.adams@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

[-- Attachment #2: 0001-Improve-doc-string-of-eshell-and-eshell-buffer-name.patch --]
[-- Type: application/octet-stream, Size: 2353 bytes --]

From e09ca748d84cfa312bb854f3d22334d33fe4816f Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Sat, 19 Oct 2019 02:51:21 +0200
Subject: [PATCH] Improve doc string of eshell and eshell-buffer-name

* lisp/eshell/eshell.el (eshell-buffer-name, eshell): Improve doc
strings, by clarifying how buffers are named.  Also refer users to the
Info manual.  (Bug#37178)
---
 lisp/eshell/eshell.el | 27 +++++++++++++++++++--------
 1 file changed, 19 insertions(+), 8 deletions(-)

diff --git a/lisp/eshell/eshell.el b/lisp/eshell/eshell.el
index db20f7d9ec..7288bcd3b0 100644
--- a/lisp/eshell/eshell.el
+++ b/lisp/eshell/eshell.el
@@ -216,7 +216,13 @@ eshell-unload-hook
   :group 'eshell)
 
 (defcustom eshell-buffer-name "*eshell*"
-  "The basename used for Eshell buffers."
+  "The basename used for Eshell buffers.
+This is the default name used when running `eshell'.
+
+With a numeric prefix argument to `eshell', the buffer name will
+be the value of this variable followed by the number.  For
+example, with the numeric prefix argument 2, the buffer would be
+named \"*eshell*<2>\"."
   :type 'string
   :group 'eshell)
 
@@ -229,13 +235,18 @@ eshell-buffer-name
 ;;;###autoload
 (defun eshell (&optional arg)
   "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)."
+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.
+
+The buffer name used for Eshell sessions is determined by the
+value of `eshell-buffer-name', which see.
+
+Eshell is a shell-like command interpreter.  For more
+information on Eshell, see Info node `(eshell)Top'."
   (interactive "P")
   (cl-assert eshell-buffer-name)
   (let ((buf (cond ((numberp arg)
-- 
2.23.0

bug#37178: 26.2; doc strings of `eshell' and `eshell-buffer-name'

[Drew Adams]

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

bug#37178: 26.2; doc strings of `eshell' and `eshell-buffer-name'

[Stefan Kangas]

Drew Adams <drew.adams@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

bug#37178: 26.2; doc strings of `eshell' and `eshell-buffer-name'

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sat, 19 Oct 2019 14:22:20 +0200
> Cc: 37178@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.

bug#37178: 26.2; doc strings of `eshell' and `eshell-buffer-name'

[Drew Adams]

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

bug#37178: 26.2; doc strings of `eshell' and `eshell-buffer-name'

[Stefan Kangas]

close 37178 27.1
thanks

Drew Adams <drew.adams@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