From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: phillip.lord@russet.org.uk (Phillip Lord) Newsgroups: gmane.emacs.devel Subject: Re: The poor state of documentation of pcase like things. Date: Thu, 17 Dec 2015 13:59:56 +0000 Message-ID: <87lh8t6uqr.fsf@russet.org.uk> 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 1450360814 21473 80.91.229.3 (17 Dec 2015 14:00:14 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Thu, 17 Dec 2015 14:00:14 +0000 (UTC) Cc: emacs-devel@gnu.org To: Alan Mackenzie Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Dec 17 15:00:14 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 1a9Z6I-00057k-Rr for ged-emacs-devel@m.gmane.org; Thu, 17 Dec 2015 15:00:11 +0100 Original-Received: from localhost ([::1]:53854 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9Z6I-0004ey-Ba for ged-emacs-devel@m.gmane.org; Thu, 17 Dec 2015 09:00:10 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:41007) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9Z6D-0004cs-4m for emacs-devel@gnu.org; Thu, 17 Dec 2015 09:00:06 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1a9Z66-0005TC-MT for emacs-devel@gnu.org; Thu, 17 Dec 2015 09:00:02 -0500 Original-Received: from cheviot22.ncl.ac.uk ([128.240.234.22]:54440) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9Z66-0005Sn-HF for emacs-devel@gnu.org; Thu, 17 Dec 2015 08:59:58 -0500 Original-Received: from smtpauth-vm.ncl.ac.uk ([10.8.233.129] helo=smtpauth.ncl.ac.uk) by cheviot22.ncl.ac.uk with esmtp (Exim 4.63) (envelope-from ) id 1a9Z64-0004T4-Ei; Thu, 17 Dec 2015 13:59:56 +0000 Original-Received: from jangai.ncl.ac.uk ([10.66.67.223] helo=localhost) by smtpauth.ncl.ac.uk with esmtpsa (TLSv1:AES128-SHA:128) (Exim 4.63) (envelope-from ) id 1a9Z64-0003Uc-Cu; Thu, 17 Dec 2015 13:59:56 +0000 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/24.5 (gnu/linux) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 128.240.234.22 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:196420 Archived-At: Alan Mackenzie writes: > 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". I think it's probably better to make your points (which are reasonable) without making such aspersions. The author in question has been extremely generous with their time. > > Particularly egregious is the doc string for pcase-exhaustive: "The > exhaustive version of `pcase' (which see).". Uhh???? Needless to say, > the doc string of pcase makes no mention of "exhaustive". > > Let us analyse the documentation of the one macro which is documented to > any meaningful extent, pcase itself: > > The article in the Elisp manual for pcase starts well, documenting the > basic form and outlining the basic semantics, but then starts rambling > on like a tutorial, rather than filling in the semantic details. Here > is a partial list of what is missing from that manual page: > > (i) A @dfn{U-PATTERN}. > (ii) A @dfn{Q-PATTERN}. > These two things are described only in terms of their structure, not > what they are conceptually. What do "U" and "Q" stand for? What is the > semantic significance of a Q-PATTERN? These defined in terms, but unfortunately, the definition is a bit recursive -- so a Q-PATTERN is defined in terms of other Q-PATTERNs (or an atom). > It would appear that Lisp programmers are expected to absorb the > semantics (and sometimes even the syntax) of pcase-* by osmosis: > studying and imitating examples. This is a Bad Thing. I am not 100% convinced that this is a bad thing. The actual semantics of pcase do mess your head up a bit. The first part, the tutorial section, is for me one of the clearest sections. I think it's something that we should have more off, personally. > Most (?all) of the rest of Emacs Lisp is effectively and rigorously > documented. For example, both the Elisp manual entry and the doc string > for cond are effective. > > 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. It is indeed worth doing these things. Phil