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.