From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#26233: 26.0.50; [PATCH] Improve documentation for display-buffer-alist Date: Fri, 24 Mar 2017 07:51:06 -0700 (PDT) Message-ID: <1a350894-ae16-4706-888f-6575cdc559ec@default> References: <87o9wq6c31.fsf@wi.uni-muenster.de> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1490367130 24856 195.159.176.226 (24 Mar 2017 14:52:10 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Fri, 24 Mar 2017 14:52:10 +0000 (UTC) To: Jens Lechtenboerger , 26233@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Mar 24 15:52:06 2017 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1crQZR-00064o-U3 for geb-bug-gnu-emacs@m.gmane.org; Fri, 24 Mar 2017 15:52:06 +0100 Original-Received: from localhost ([::1]:33505 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1crQZX-0002Z0-Un for geb-bug-gnu-emacs@m.gmane.org; Fri, 24 Mar 2017 10:52:11 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:35134) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1crQZR-0002XE-89 for bug-gnu-emacs@gnu.org; Fri, 24 Mar 2017 10:52:06 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1crQZO-0001hy-57 for bug-gnu-emacs@gnu.org; Fri, 24 Mar 2017 10:52:05 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:44343) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1crQZO-0001hu-2S for bug-gnu-emacs@gnu.org; Fri, 24 Mar 2017 10:52:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1crQZN-00081i-Oe for bug-gnu-emacs@gnu.org; Fri, 24 Mar 2017 10:52:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 24 Mar 2017 14:52:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 26233 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 26233-submit@debbugs.gnu.org id=B26233.149036707830801 (code B ref 26233); Fri, 24 Mar 2017 14:52:01 +0000 Original-Received: (at 26233) by debbugs.gnu.org; 24 Mar 2017 14:51:18 +0000 Original-Received: from localhost ([127.0.0.1]:42542 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1crQYg-00080j-Dg for submit@debbugs.gnu.org; Fri, 24 Mar 2017 10:51:18 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:27243) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1crQYe-00080V-8B for 26233@debbugs.gnu.org; Fri, 24 Mar 2017 10:51:16 -0400 Original-Received: from userv0022.oracle.com (userv0022.oracle.com [156.151.31.74]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id v2OEp8au028333 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Fri, 24 Mar 2017 14:51:09 GMT Original-Received: from aserv0122.oracle.com (aserv0122.oracle.com [141.146.126.236]) by userv0022.oracle.com (8.14.4/8.14.4) with ESMTP id v2OEp8RG027601 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=FAIL); Fri, 24 Mar 2017 14:51:08 GMT Original-Received: from abhmp0009.oracle.com (abhmp0009.oracle.com [141.146.116.15]) by aserv0122.oracle.com (8.14.4/8.14.4) with ESMTP id v2OEp7Ua005766; Fri, 24 Mar 2017 14:51:07 GMT In-Reply-To: <87o9wq6c31.fsf@wi.uni-muenster.de> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 12.0.6753.5000 (x86)] X-Source-IP: userv0022.oracle.com [156.151.31.74] 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: 208.118.235.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:130879 Archived-At: > in Bug#25946 we discussed how to replace the obsolete variables > special-display-buffer-names and special-display-regexps. The > attached patch extends the doc string of display-buffer-alist > based on that discussion. FWIW: 1. I *strongly* object to the deprecation of these user options. Instead of deprecating them, we should not only continue to support them, as we have been doing, but fully document and even promote them. If they did not exist then Emacs would be well advised to invent them, as they are convenient, _simple_ ways to specify special-display of buffers. "Special-display" is a thing. Or at least it was. Now, the term has been liquidated from the manual. The only vestige of it is in the description of menu "`Display Property': Enabling special display features." That's unfortunate for users. It is fine to have introduced a generalization, which was done with `display-buffer-alist' etc. It is not fine to remove these simple, easy-to-use ways of expressing common use cases. 2. The patch, though it proceeds from a good motivation no doubt, can suggest that adding that code or similar (e.g. some other regexp) in your init file will give you the behavior of those deprecated options, in general. That impression would be incorrect. First, there are two such options, not just the `-regexps' one. More importantly are the so-called=20 "alternative" forms of the option values - two=20 "alternatives" for each option. Just one example such=20 as that given indicates nothing about these=20 possibilities. These options, and users, deserve a complete description of how to get their full behavior using the more general apparatus (`display-buffer-alist' etc.). We should have a section in the manual that describes these options and "special-display" in general, just as was the case in the past. In that section it should be shown how this or that behavior, which you can obtain simply using these options, can also be had using `display-buffer-alist'. I can almost guarantee that if we did that, then, as a side benefit (and one that is sorely needed, IMO), users would come away with a better understanding of `display-buffer-alist' itself, and how to use it. To this day - years after it was introduced - users (including me) are still in the dark and confused about `display-buffer-alist'. IOW, introduce these options as first-class citizens, and show _how they correspond_ to the more general apparatus. 3. I also object to the way the doc strings for these options were changed, to suggest that the "alternative" value forms are perhaps only arcane or less-important "alternatives". Originally, the doc strings just said, outright, that there are 3 forms the value can take: 1, 2, 3. None of those forms were relegated to the background, as an afterthought or as something obscure or inferior. Though simple to use, these are powerful options, which should not be trivialized. Users should be encouraged to use these options whenever they do the job needed, and to use the more general constructs when they need something else. Instead, we've hidden these simple constructs, told users that they are now deprecated, and tossed users immediately onto the rocks of `display-buffer-alist' as their only resort, even for these simple use cases. That's not right. Just one opinion.