From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: pcase docs Date: Sat, 23 Jan 2016 13:43:07 +0200 Message-ID: <83fuxo5xo4.fsf@gnu.org> References: <83a8o8gcya.fsf@gnu.org> <87zivx5ree.fsf@web.de> <87r3h95qs3.fsf@web.de> <83wpr15mk1.fsf@gnu.org> <8737toiota.fsf@web.de> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1453549389 32727 80.91.229.3 (23 Jan 2016 11:43:09 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 23 Jan 2016 11:43:09 +0000 (UTC) Cc: jwiegley@gmail.com, emacs-devel@gnu.org To: Michael Heerdegen Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Jan 23 12:43:08 2016 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1aMwax-0008Gy-0O for ged-emacs-devel@m.gmane.org; Sat, 23 Jan 2016 12:43:07 +0100 Original-Received: from localhost ([::1]:56951 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aMwaw-0001gN-JA for ged-emacs-devel@m.gmane.org; Sat, 23 Jan 2016 06:43:06 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:36623) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aMwai-0001gF-Kh for emacs-devel@gnu.org; Sat, 23 Jan 2016 06:42:53 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aMwaf-0006p5-FH for emacs-devel@gnu.org; Sat, 23 Jan 2016 06:42:52 -0500 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:47031) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aMwaf-0006ow-BY; Sat, 23 Jan 2016 06:42:49 -0500 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:2142 helo=HOME-C4E4A596F7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1aMwae-0005R5-6j; Sat, 23 Jan 2016 06:42:48 -0500 In-reply-to: <8737toiota.fsf@web.de> (message from Michael Heerdegen on Sat, 23 Jan 2016 11:16:01 +0100) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:198630 Archived-At: > From: Michael Heerdegen > Cc: jwiegley@gmail.com, emacs-devel@gnu.org > Date: Sat, 23 Jan 2016 11:16:01 +0100 > > Eli Zaretskii writes: > > > Since we don't have a separate "Emacs Lisp for Developers of Internal > > Packages" manual, I don't see why we should omit these or describe > > them in less detail. > > I didn't mean it like that. But I think we can assume that they will > already know how `defmacro' works - something I would not assume for > every user of Emacs. Sorry, I don't understand: how can knowing what 'defmacro' does help to know what 'pcase-defmacro' does? At the very least, one needs to know which patterns will be possible after using 'pcase-defmacro', don't you agree? Btw, this macro also has "issues". The doc string is less than helpful: "Define a new kind of pcase PATTERN, by macro expansion. Patterns of the form (NAME ...) will be expanded according to this macro." It says nothing about ARGS, and the "by macro expansion" part sounds strange -- what useful information does it supply here? And if you turn to the users of this macro, in the hope of gaining some understanding, you will see, for example, that map.el defines a pattern whose NAME is "map": (pcase-defmacro map (&rest args) "Build a `pcase' pattern matching map elements. The `pcase' pattern will match each element of PATTERN against the corresponding elements of the map. (btw: what PATTERN?), but then uses it like this: (pcase type (`list (map-pairs map)) (`hash-table (map--into-hash-table map)) (_ (error "Not a map type name: %S" type)))) IOW, it actually uses sub-classes of 'map' as patterns. Hmm... (You can now understand why the documentation of 'pcase-defmacro' I added is rather laconic and in some sense unsatisfactory.) As an aside, when I look at such doc strings, I always become frustrated, because I must be extremely stupid to ask all these questions, when no one else evidently cares, which must mean they all understand this stuff, and only I alone don't, right? Thanks.