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

[Stefan Kangas]

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

0001-Improve-doc-string-of-eshell-and-eshell-buffer-name.patch
Description: Binary data