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 10:02:16 -0700 (PDT) Message-ID: <9cd18e10-8f14-4a49-a3a4-ed9d50afe860@default> References: <> <<83wowqrmp8.fsf@gnu.org>> 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 1525021268 30867 195.159.176.226 (29 Apr 2018 17:01:08 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 29 Apr 2018 17:01:08 +0000 (UTC) Cc: 31311@debbugs.gnu.org To: Eli Zaretskii , Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Apr 29 19:01:04 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 1fCph9-0007ru-8R for geb-bug-gnu-emacs@m.gmane.org; Sun, 29 Apr 2018 19:01:03 +0200 Original-Received: from localhost ([::1]:56205 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fCpjE-0004dQ-La for geb-bug-gnu-emacs@m.gmane.org; Sun, 29 Apr 2018 13:03:12 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:39066) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fCpj7-0004dL-PK for bug-gnu-emacs@gnu.org; Sun, 29 Apr 2018 13:03:06 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fCpj4-0003Lb-M0 for bug-gnu-emacs@gnu.org; Sun, 29 Apr 2018 13:03:05 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:35195) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1fCpj4-0003LR-Ik for bug-gnu-emacs@gnu.org; Sun, 29 Apr 2018 13:03:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1fCpj4-0007iF-AG for bug-gnu-emacs@gnu.org; Sun, 29 Apr 2018 13:03: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 17:03: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.152502134729598 (code B ref 31311); Sun, 29 Apr 2018 17:03:02 +0000 Original-Received: (at 31311) by debbugs.gnu.org; 29 Apr 2018 17:02:27 +0000 Original-Received: from localhost ([127.0.0.1]:43092 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fCpiU-0007hJ-3x for submit@debbugs.gnu.org; Sun, 29 Apr 2018 13:02:27 -0400 Original-Received: from userp2120.oracle.com ([156.151.31.85]:37008) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fCpiS-0007h4-GT for 31311@debbugs.gnu.org; Sun, 29 Apr 2018 13:02:24 -0400 Original-Received: from pps.filterd (userp2120.oracle.com [127.0.0.1]) by userp2120.oracle.com (8.16.0.22/8.16.0.22) with SMTP id w3TH1xY7104130; Sun, 29 Apr 2018 17:02: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=KXFeHRWXO9hQhb5Mqi4OYpemlsBhfQtmDpz5sId+0OI=; b=UVBlMISIRgAPUynpLDOlizxruvlSif6usWz8a+hGlOjiSxPESDfCopN7I6BDhpNftzy0 M3ve6dWmaQxVOYJE+HV21/se2jLPU0jt09OVJp5mhu/hIJDLHfwzM4gJ2nWvWu5cwLJp wJPqwDN9YGXH68Oh43Olv8hG5C/KjWKpHAIPbsB4P8zvb926sKpu8qDahE3EPKsMSoKa fWwV9Hib/98hiAQH7aEPbo2A/ZVyvg8wwFSMuUIfd/0+ooQjOTKUoiWIkmz3wWJ1AIIt 6rAAvlOCfkKR/fFJuQrF8t5AY6YVQ+3jQ2fij6JETeBaQRlVuFC2FtlE4qvjYdSTlBYw /w== Original-Received: from userv0021.oracle.com (userv0021.oracle.com [156.151.31.71]) by userp2120.oracle.com with ESMTP id 2hmhmf9y12-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sun, 29 Apr 2018 17:02:18 +0000 Original-Received: from aserv0121.oracle.com (aserv0121.oracle.com [141.146.126.235]) by userv0021.oracle.com (8.14.4/8.14.4) with ESMTP id w3TH2HM6022672 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sun, 29 Apr 2018 17:02:17 GMT Original-Received: from abhmp0008.oracle.com (abhmp0008.oracle.com [141.146.116.14]) by aserv0121.oracle.com (8.14.4/8.13.8) with ESMTP id w3TH2HwH005273; Sun, 29 Apr 2018 17:02:17 GMT In-Reply-To: <<83wowqrmp8.fsf@gnu.org>> 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=887 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1711220000 definitions=main-1804290171 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:145825 Archived-At: > It seems that no one really cares to document this facility. I care enough about `pcase' and its doc to file this bug report. > Maybe 'pcase' is seen as a kind of test: if you succeed in > using and understanding it without any clear documentation, > you are admitted to certain quarters where only wizards can enter. If that's the approach being taken then perhaps remove all of the doc. If users need to resort to analyzing the code and trying examples (tests) then perhaps no doc is better than misleading doc. I don't think that's the case, but if you think it is then please remove the doc. I think the doc is partly helpful. But it needs fixing. Dunno whether it is currently better than nothing, but I think so. > What you see in the manual is mostly the result of desperate efforts > of a single individual to have something remotely palatable in our > documentation. >=20 > Consequently, bug reports without patches are unlikely to yield any > real results, IME. Too bad. 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. There are also some other parts of my report that can be acted on without any real knowledge of `pcase', I believe.