From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Stefan Kangas Newsgroups: gmane.emacs.bugs Subject: bug#37178: 26.2; doc strings of `eshell' and `eshell-buffer-name' Date: Sat, 19 Oct 2019 03:00:19 +0200 Message-ID: References: Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="0000000000002c9634059538fabc" Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="15661"; mail-complaints-to="usenet@blaine.gmane.org" Cc: 37178@debbugs.gnu.org To: Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Oct 19 03:01:22 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1iLd7R-0003wn-4Y for geb-bug-gnu-emacs@m.gmane.org; Sat, 19 Oct 2019 03:01:21 +0200 Original-Received: from localhost ([::1]:47360 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iLd7P-00089P-Vk for geb-bug-gnu-emacs@m.gmane.org; Fri, 18 Oct 2019 21:01:19 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:41158) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iLd7C-00089F-CO for bug-gnu-emacs@gnu.org; Fri, 18 Oct 2019 21:01:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iLd7B-0005eV-87 for bug-gnu-emacs@gnu.org; Fri, 18 Oct 2019 21:01:06 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:42899) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iLd78-0005e2-0M for bug-gnu-emacs@gnu.org; Fri, 18 Oct 2019 21:01:05 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1iLd77-0001oo-S3 for bug-gnu-emacs@gnu.org; Fri, 18 Oct 2019 21:01:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Stefan Kangas Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 19 Oct 2019 01:01:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 37178 X-GNU-PR-Package: emacs Original-Received: via spool by 37178-submit@debbugs.gnu.org id=B37178.15714468426953 (code B ref 37178); Sat, 19 Oct 2019 01:01:01 +0000 Original-Received: (at 37178) by debbugs.gnu.org; 19 Oct 2019 01:00:42 +0000 Original-Received: from localhost ([127.0.0.1]:51720 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iLd6m-0001o3-7f for submit@debbugs.gnu.org; Fri, 18 Oct 2019 21:00:40 -0400 Original-Received: from mail-pg1-f172.google.com ([209.85.215.172]:42846) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iLd6j-0001np-QL for 37178@debbugs.gnu.org; Fri, 18 Oct 2019 21:00:39 -0400 Original-Received: by mail-pg1-f172.google.com with SMTP id f14so4234046pgi.9 for <37178@debbugs.gnu.org>; Fri, 18 Oct 2019 18:00:37 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=fZSTz9/yV8dwNyIj/r6095SNwKqG84su1kuKIqUN84M=; b=btFu3Q/Gcg4fS4oTGv687qC0WeH0GAlfvu0PaT46otbJRXTh72Z+Wp0W5FxoOzuhb8 9hnlzdskc63fzT+3vdXfG8LJZiJ6/P+aDnCVHTXzsnJcwsQU0cArKRSf8zqyCTG8gqkW JhADicSxlVCEoOaK9MqCBC3DmlLBI13OyhZKxWOZ+GbwZIaYjfB3LNHgOqsrKPIGP95/ a7I1UL4k371DJzUUD60xQPxRt9zZ+TqA7ov1VXWA6wo+i+g20Rk8TZQPlZAWEJCER84u mL1vDfPr7qchHNh9i6voQpZ5KLHlTLH0nyYNJ02p1M4yH8Lo71d3Mbeu7G3W12u8cElD hbQA== X-Gm-Message-State: APjAAAWUIz6JACPKPITAgd3sY0BsfTyc6rvzKvYIGDAol3t+qBaYrAry Uxk64Tm+HkX0cScyVsAsJysrY8NhK1QCCs5BbJ4= X-Google-Smtp-Source: APXvYqz7ePTD3coy8I48pKj+pUQoIZEu/okvy8uGksYyXSi/VgqMsCE7rqKXlNpJN0Xq1c3m8VpADCTk/tEdg976Lkk= X-Received: by 2002:a17:90a:fb92:: with SMTP id cp18mr14798740pjb.2.1571446831477; Fri, 18 Oct 2019 18:00:31 -0700 (PDT) In-Reply-To: X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:169688 Archived-At: --0000000000002c9634059538fabc Content-Type: text/plain; charset="UTF-8" Drew Adams 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 "", 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 . > > 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 --0000000000002c9634059538fabc Content-Type: application/octet-stream; name="0001-Improve-doc-string-of-eshell-and-eshell-buffer-name.patch" Content-Disposition: attachment; filename="0001-Improve-doc-string-of-eshell-and-eshell-buffer-name.patch" Content-Transfer-Encoding: base64 Content-ID: X-Attachment-Id: f_k1wuuzzs0 RnJvbSBlMDljYTc0OGQ4NGNmYTMxMmJiODU0ZjNkMjIzMzRkMzNmZTQ4MTZmIE1vbiBTZXAgMTcg MDA6MDA6MDAgMjAwMQpGcm9tOiBTdGVmYW4gS2FuZ2FzIDxzdGVmYW5rYW5nYXNAZ21haWwuY29t PgpEYXRlOiBTYXQsIDE5IE9jdCAyMDE5IDAyOjUxOjIxICswMjAwClN1YmplY3Q6IFtQQVRDSF0g SW1wcm92ZSBkb2Mgc3RyaW5nIG9mIGVzaGVsbCBhbmQgZXNoZWxsLWJ1ZmZlci1uYW1lCgoqIGxp c3AvZXNoZWxsL2VzaGVsbC5lbCAoZXNoZWxsLWJ1ZmZlci1uYW1lLCBlc2hlbGwpOiBJbXByb3Zl IGRvYwpzdHJpbmdzLCBieSBjbGFyaWZ5aW5nIGhvdyBidWZmZXJzIGFyZSBuYW1lZC4gIEFsc28g cmVmZXIgdXNlcnMgdG8gdGhlCkluZm8gbWFudWFsLiAgKEJ1ZyMzNzE3OCkKLS0tCiBsaXNwL2Vz aGVsbC9lc2hlbGwuZWwgfCAyNyArKysrKysrKysrKysrKysrKysrLS0tLS0tLS0KIDEgZmlsZSBj aGFuZ2VkLCAxOSBpbnNlcnRpb25zKCspLCA4IGRlbGV0aW9ucygtKQoKZGlmZiAtLWdpdCBhL2xp c3AvZXNoZWxsL2VzaGVsbC5lbCBiL2xpc3AvZXNoZWxsL2VzaGVsbC5lbAppbmRleCBkYjIwZjdk OWVjLi43Mjg4YmNkM2IwIDEwMDY0NAotLS0gYS9saXNwL2VzaGVsbC9lc2hlbGwuZWwKKysrIGIv bGlzcC9lc2hlbGwvZXNoZWxsLmVsCkBAIC0yMTYsNyArMjE2LDEzIEBAIGVzaGVsbC11bmxvYWQt aG9vawogICA6Z3JvdXAgJ2VzaGVsbCkKIAogKGRlZmN1c3RvbSBlc2hlbGwtYnVmZmVyLW5hbWUg Iiplc2hlbGwqIgotICAiVGhlIGJhc2VuYW1lIHVzZWQgZm9yIEVzaGVsbCBidWZmZXJzLiIKKyAg IlRoZSBiYXNlbmFtZSB1c2VkIGZvciBFc2hlbGwgYnVmZmVycy4KK1RoaXMgaXMgdGhlIGRlZmF1 bHQgbmFtZSB1c2VkIHdoZW4gcnVubmluZyBgZXNoZWxsJy4KKworV2l0aCBhIG51bWVyaWMgcHJl Zml4IGFyZ3VtZW50IHRvIGBlc2hlbGwnLCB0aGUgYnVmZmVyIG5hbWUgd2lsbAorYmUgdGhlIHZh bHVlIG9mIHRoaXMgdmFyaWFibGUgZm9sbG93ZWQgYnkgdGhlIG51bWJlci4gIEZvcgorZXhhbXBs ZSwgd2l0aCB0aGUgbnVtZXJpYyBwcmVmaXggYXJndW1lbnQgMiwgdGhlIGJ1ZmZlciB3b3VsZCBi ZQorbmFtZWQgXCIqZXNoZWxsKjwyPlwiLiIKICAgOnR5cGUgJ3N0cmluZwogICA6Z3JvdXAgJ2Vz aGVsbCkKIApAQCAtMjI5LDEzICsyMzUsMTggQEAgZXNoZWxsLWJ1ZmZlci1uYW1lCiA7OzsjIyNh dXRvbG9hZAogKGRlZnVuIGVzaGVsbCAoJm9wdGlvbmFsIGFyZykKICAgIkNyZWF0ZSBhbiBpbnRl cmFjdGl2ZSBFc2hlbGwgYnVmZmVyLgotVGhlIGJ1ZmZlciB1c2VkIGZvciBFc2hlbGwgc2Vzc2lv bnMgaXMgZGV0ZXJtaW5lZCBieSB0aGUgdmFsdWUgb2YKLWBlc2hlbGwtYnVmZmVyLW5hbWUnLiAg SWYgdGhlcmUgaXMgYWxyZWFkeSBhbiBFc2hlbGwgc2Vzc2lvbiBhY3RpdmUgaW4KLXRoYXQgYnVm ZmVyLCBFbWFjcyB3aWxsIHNpbXBseSBzd2l0Y2ggdG8gaXQuICBPdGhlcndpc2UsIGEgbmV3IHNl c3Npb24KLXdpbGwgYmVnaW4uICBBIG51bWVyaWMgcHJlZml4IGFyZyAoYXMgaW4gYEMtdSA0MiBN LXggZXNoZWxsIFJFVCcpCi1zd2l0Y2hlcyB0byB0aGUgc2Vzc2lvbiB3aXRoIHRoYXQgbnVtYmVy LCBjcmVhdGluZyBpdCBpZiBuZWNlc3NhcnkuICBBCi1ub25udW1lcmljIHByZWZpeCBhcmcgbWVh bnMgdG8gY3JlYXRlIGEgbmV3IHNlc3Npb24uICBSZXR1cm5zIHRoZQotYnVmZmVyIHNlbGVjdGVk IChvciBjcmVhdGVkKS4iCitTdGFydCBhIG5ldyBFc2hlbGwgc2Vzc2lvbiwgb3Igc3dpdGNoIHRv IGFuIGFscmVhZHkgYWN0aXZlCitzZXNzaW9uLiAgUmV0dXJuIHRoZSBidWZmZXIgc2VsZWN0ZWQg KG9yIGNyZWF0ZWQpLgorCitXaXRoIGEgbnVtZXJpYyBwcmVmaXggYXJnIChhcyBpbiBgQy11IDQy IE0teCBlc2hlbGwgUkVUJyksIHN3aXRjaAordG8gdGhlIHNlc3Npb24gd2l0aCB0aGF0IG51bWJl ciwgb3IgY3JlYXRlIGl0IGlmIGl0IGRvZXNuJ3QKK2V4aXN0LiAgQSBub25udW1lcmljIHByZWZp eCBhcmcgbWVhbnMgdG8gY3JlYXRlIGEgbmV3IHNlc3Npb24uCisKK1RoZSBidWZmZXIgbmFtZSB1 c2VkIGZvciBFc2hlbGwgc2Vzc2lvbnMgaXMgZGV0ZXJtaW5lZCBieSB0aGUKK3ZhbHVlIG9mIGBl c2hlbGwtYnVmZmVyLW5hbWUnLCB3aGljaCBzZWUuCisKK0VzaGVsbCBpcyBhIHNoZWxsLWxpa2Ug Y29tbWFuZCBpbnRlcnByZXRlci4gIEZvciBtb3JlCitpbmZvcm1hdGlvbiBvbiBFc2hlbGwsIHNl ZSBJbmZvIG5vZGUgYChlc2hlbGwpVG9wJy4iCiAgIChpbnRlcmFjdGl2ZSAiUCIpCiAgIChjbC1h c3NlcnQgZXNoZWxsLWJ1ZmZlci1uYW1lKQogICAobGV0ICgoYnVmIChjb25kICgobnVtYmVycCBh cmcpCi0tIAoyLjIzLjAKCg== --0000000000002c9634059538fabc--