From c1544feba0a3b7138b644db200eac687c799662d Mon Sep 17 00:00:00 2001 From: Stefan Kangas 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 | 29 +++++++++++++++++++++-------- 1 file changed, 21 insertions(+), 8 deletions(-) diff --git a/lisp/eshell/eshell.el b/lisp/eshell/eshell.el index db20f7d9ec5..015100bd2ee 100644 --- a/lisp/eshell/eshell.el +++ b/lisp/eshell/eshell.el @@ -216,7 +216,13 @@ shells such as bash, zsh, rc, 4dos." :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,20 @@ shells such as bash, zsh, rc, 4dos." ;;;###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 nonnumeric prefix arg, create a new session. + +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 +already exist. + +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.39.2