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

[Stefan Kangas <stefan@marxist.se>]

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