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#31311: 27.0; doc of `pcase' Date: Sun, 29 Apr 2018 12:43:14 -0700 (PDT) Message-ID: References: > <83wowqrmp8.fsf@gnu.org>> <9cd18e10-8f14-4a49-a3a4-ed9d50afe860@default> <87a7tlluye.fsf@web.de> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1525030992 7060 195.159.176.226 (29 Apr 2018 19:43:12 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 29 Apr 2018 19:43:12 +0000 (UTC) Cc: 31311@debbugs.gnu.org To: Michael Heerdegen Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Apr 29 21:43:08 2018 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 1fCsDz-0001jA-B1 for geb-bug-gnu-emacs@m.gmane.org; Sun, 29 Apr 2018 21:43:07 +0200 Original-Received: from localhost ([::1]:56598 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fCsG6-00058q-Dk for geb-bug-gnu-emacs@m.gmane.org; Sun, 29 Apr 2018 15:45:18 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:36577) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fCsEw-0004D4-0a for bug-gnu-emacs@gnu.org; Sun, 29 Apr 2018 15:44:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fCsEs-0001WF-Sa for bug-gnu-emacs@gnu.org; Sun, 29 Apr 2018 15:44:06 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:35265) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1fCsEs-0001WA-Ny for bug-gnu-emacs@gnu.org; Sun, 29 Apr 2018 15:44:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1fCsEs-0003J3-Dm for bug-gnu-emacs@gnu.org; Sun, 29 Apr 2018 15:44:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 29 Apr 2018 19:44:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 31311 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 31311-submit@debbugs.gnu.org id=B31311.152503100812661 (code B ref 31311); Sun, 29 Apr 2018 19:44:02 +0000 Original-Received: (at 31311) by debbugs.gnu.org; 29 Apr 2018 19:43:28 +0000 Original-Received: from localhost ([127.0.0.1]:43162 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fCsEK-0003I9-DG for submit@debbugs.gnu.org; Sun, 29 Apr 2018 15:43:28 -0400 Original-Received: from aserp2130.oracle.com ([141.146.126.79]:49920) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fCsEG-0003Hs-Kq for 31311@debbugs.gnu.org; Sun, 29 Apr 2018 15:43:25 -0400 Original-Received: from pps.filterd (aserp2130.oracle.com [127.0.0.1]) by aserp2130.oracle.com (8.16.0.22/8.16.0.22) with SMTP id w3TJc6vB108595; Sun, 29 Apr 2018 19:43:18 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : cc : subject : references : in-reply-to : content-type : content-transfer-encoding; s=corp-2017-10-26; bh=wQHZe11N/IDhU348ewpMeGWOduUvgPQJzy+S4uoiyyA=; b=cvNHEZGaVVn0d3pzCVEU55ffmE905uVLm7P5FXUPSZkDnzsNwLCkS4z2P4qlMQIg19mI wac4TNCHSbNAN+0dk4p0U5ZW3X5IQtYGKvCtKhHyJ9Meh+lssOMetZWvFqpWqGNKy8Xt 8YNJe1DMgCy0TRxxg1zasPt8QhiI5PV+gVpAoI2oFiKP3FOPdSdYfbiA4o2cY09u5OMu adkh1lU/5OZMh2ke7SbCTi0hFy9BDU1BqHKdzXm9sP1UEVs5iBCX2IRp/GMxKb1sExyv ZViHPwGBJalEigd2G1EdUIr5nFMO80r+Ae7UW5MCyNjp5hex65ou5NRHOkmywpeZ6fFD 8g== Original-Received: from aserv0022.oracle.com (aserv0022.oracle.com [141.146.126.234]) by aserp2130.oracle.com with ESMTP id 2hmeg5j67c-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sun, 29 Apr 2018 19:43:18 +0000 Original-Received: from userv0122.oracle.com (userv0122.oracle.com [156.151.31.75]) by aserv0022.oracle.com (8.14.4/8.14.4) with ESMTP id w3TJhHwn022428 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sun, 29 Apr 2018 19:43:18 GMT Original-Received: from abhmp0008.oracle.com (abhmp0008.oracle.com [141.146.116.14]) by userv0122.oracle.com (8.14.4/8.14.4) with ESMTP id w3TJhGmW021178; Sun, 29 Apr 2018 19:43:16 GMT In-Reply-To: <87a7tlluye.fsf@web.de> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4678.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=5900 definitions=8878 signatures=668698 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=0 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1711220000 definitions=main-1804290198 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:145831 Archived-At: > > Perhaps you can at least remove the incomprehensible and > > seemingly unrelated text (I cited) that appears at the end > > of the doc string, as a start. >=20 > This is not unrelated: These are the docs for additional pcase patterns > defined elsewhere: pcase is extensible, and the pattern listing part in > the docstring is generated dynamically. As a result of that conception > it may not read very fluently as a whole, but it's definitely nothing we > want to remove. Sorry, but that extra (dynamically generated?) text at the end makes no sense at all to me. I don't have a clue what it's trying to convey. To me it's just noise that can only confuse, not help, users. If there is some core meaning behind it then great. In that case there is a potential for it to say something. That's not happening at all now, I think. For the time being, i.e., until someone can translate that core meaning (what you really expect it to be trying to say) into understandable text, it should be removed. Please consider moving it to a TODO item somewhere, if you like. But maybe others disagree and only I have trouble seeing what that text is all about. Beyond that, if it is about showing examples of defining additional `pcase' patterns in the Emacs code then I don't think that kind of thing belongs in a doc string - certainly not multiple such examples. Even in the Elisp manual, I'd expect only a simple example of defining a `pcase' pattern, in the node itself. If it were thought to really be helpful then there could perhaps also be a note to see the code of this or that function. But I really don't expect that that should be necessary. Do we do that anywhere else? Either it is simple to define your own `pcase' patterns or it is not. If it is, then no such extra examples should be needed. If it's not, then can't we make it easier to define your own patterns (change the product, not just the doc)? >From what you are saying, it sounds to me like what users need to make sense of `pcase' is a blog article, showing examples etc. and building up from simple to complex. I'd rather encourage someone to write that than for us to try to cram such info into a doc string or manual node. =20 > We clearly have some deficiencies, but the situation IMHO really is not > as horrible as Eli's sarcasm suggests. FWIW, I don't see what Eli wrote as sarcasm. I do see it as negative, nearly despondent. But sarcasm involves some element of humor, irony, or satire, which I don't find there. In any case, there are two different problems being discussed so far in this thread: (1) the doc is bad, and (2) it has been given insufficient love. This bug is really about #1. But according to Eli, #1 likely won't be fixed because of #2. Dunno whether he is right, but #1 is the problem to report.