From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Michael Heerdegen Newsgroups: gmane.emacs.devel Subject: Re: The poor state of documentation of pcase like things. Date: Sat, 19 Dec 2015 16:26:52 +0100 Message-ID: <87fuyytq6b.fsf@web.de> References: <20151216202605.GA3752@acm.fritz.box> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1450538835 9536 80.91.229.3 (19 Dec 2015 15:27:15 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 19 Dec 2015 15:27:15 +0000 (UTC) Cc: emacs-devel@gnu.org To: Alan Mackenzie Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Dec 19 16:27:06 2015 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 1aAJPW-000231-06 for ged-emacs-devel@m.gmane.org; Sat, 19 Dec 2015 16:27:06 +0100 Original-Received: from localhost ([::1]:37673 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aAJPV-0000fP-9z for ged-emacs-devel@m.gmane.org; Sat, 19 Dec 2015 10:27:05 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:57248) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aAJPR-0000fB-Jh for emacs-devel@gnu.org; Sat, 19 Dec 2015 10:27:02 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aAJPO-00015S-AF for emacs-devel@gnu.org; Sat, 19 Dec 2015 10:27:01 -0500 Original-Received: from mout.web.de ([212.227.17.12]:50990) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aAJPO-00015K-0u for emacs-devel@gnu.org; Sat, 19 Dec 2015 10:26:58 -0500 Original-Received: from drachen.dragon ([90.186.0.107]) by smtp.web.de (mrweb103) with ESMTPSA (Nemesis) id 0LjJH1-1al1X633hn-00dUpw; Sat, 19 Dec 2015 16:26:55 +0100 In-Reply-To: <20151216202605.GA3752@acm.fritz.box> (Alan Mackenzie's message of "Wed, 16 Dec 2015 20:26:05 +0000") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.0.50 (gnu/linux) X-Provags-ID: V03:K0:zQo2qXa3zNDC9OWK7e2UpPW/Q5/RcHAR1VPwyEuPi17gVZbzC8H Az0paFvcKiKyicLVmXOXXW7E/1rPOj69Y/KsbINh8s2Afb2ullsmSiKhKswWCsdBZtfII/M eZWBPfI06LiA9EOMIrLRIw7q0OlrnD+kJYUkO2m4o5UUOECVYpOFgE0qqcuwtmxqUzkQa65 JIJdOuqptJUgXL2k6THvQ== X-UI-Out-Filterresults: notjunk:1;V01:K0:XJFE6aZiklM=:dYK3Tmp6qTbnthglx5KvL1 FwC7y2QzjCi4dSoHg3CoCIjlm35zOxxZd7lQHKNMdmL3wOJHNyMq3cFDag3gbHkKYNFVXAp/v W+j+bY/qDCaXgtLhzYUKaL+wV1t40WCEyA6C1V3vh10J0IATDoWWy8V/J+kMS40nNcSSDqeKQ O6aG36rI+HP1lZLaTntbnk/qInTZVZF3NWLcUyT60zbumhj8qi9OmwnDkbZ9iUTuAnXOAhi5L cXbV9ZxFu2SDHQ2RsoX71Px95hWcPok4UJXoyWC8dg/ebt8Nny7uN5RcPlUWbipNVf7AsBJI/ jYj4/F69skwF5Gyu+f6Z3Kk1FVpQUOPDW8oiIEw4uaI+eZOpg9xC862Q+UClmb1EFQp01Zb9z Qchtd/AhOe+Q8y7wBAtyxSt3+RiJgO50QfrzyQSTisphCUiqmqFhUgA7wK9fwjKdgsnAvkamU TYNwTsDe39udsAPg6BBzDS/DII+dWvEE0VMfgHdLFl9K1mtc4n9VwJN9awAbFvju2KxEqlk/6 dtVXVUKn00E6Ff4raiS6w0MigybSJRTtKtLhAR5Es0Y2ggwauZHMK55QL/FMw3WUtTUhkvNoc F7/OqXALrqUMHXffebD/ubCsIcQz7slrJbVi3szBj5fTaKQQrquJcyaHxtisdIYEfTitpgyZm Y96RB+1+FM9wkc7rDbmqYZ6wkC9jYASy9xPCbdBAoUKJ4t2SmEJl8dJEhEAXMNL8Cm1kk3BBu i3iunEshb4XT/nse010t+oxytfX10pfksOzIUgLAwYt8ALL/BsC+tTP7x7YPUw7YRcJ6oMWU X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 212.227.17.12 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:196505 Archived-At: Alan Mackenzie writes: > Hello, Emacs. Hello. (no, I'm not Emacs) > Months after recognising that the documentation of pcase like things > is in need of vast improvement, we haven't advanced significantly. I wished you had not raised this issue so shortly before Christmas. > We appear to have the following functions/macros: pcase, pcase-let, > pcase-let*, pcase-codegen, pcase-defmacro, pcase-dolist, > pcase-exhaustive, and pcase-lambda. > > NONE OF THESE, with the exception of pcase itself, IS EVEN MENTIONED IN > THE ELISP MANUAL. > > NONE OF THESE, with the exception of pcase itself, HAS A MEANINGFUL DOC > STRING. > > Some of these doc strings are patronising indeed. They all seem to say, > implicitly, "the author's time is far too valuable to waste in writing > meaningful documentation". As far as I understand how Stefan used to work, most of the semantics of most of the pcase derivatives, like `pcase-let', are not yet 100% fixed, we are not yet sure how useful we are, or if they may later be better be replaced by other forms that are more general, etc. IMHO it's good to leave the documentation of the derivatives as is for now. > What do "U" and "Q" stand for? > There are people on this list who are using pcase like things, and so > clearly understand their syntax and semantics. Could these people > PLEASE document these things, and do so before the release of Emacs > 25.1. Preferably well before. To be honest, I tweaked some of the pcase related documentation, and was quite happy with it. I think the pcase docstring is quite good. A tutorial is missing though, clearly. Michael.