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: Sat, 19 Dec 2015 22:23:54 +0000 Message-ID: <87r3iim611.fsf@russet.org.uk> References: <20151216202605.GA3752@acm.fritz.box> <87fuz0ydvb.fsf@russet.org.uk> <83poy4xm60.fsf@gnu.org> <871tak15pb.fsf@gmx.us> <8360zwxgbu.fsf@gnu.org> <87vb7wdpz5.fsf@fencepost.gnu.org> <831takxccb.fsf@gnu.org> <87egej3dvb.fsf@russet.org.uk> <83h9jfwuab.fsf@gnu.org> <83r3iivg02.fsf@gnu.org> <87fuyyllat.fsf@fencepost.gnu.org> <83mvt6vdli.fsf@gnu.org> <878u4qnpml.fsf@russet.org.uk> <83wpsatat1.fsf@gnu.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1450563872 9643 80.91.229.3 (19 Dec 2015 22:24:32 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 19 Dec 2015 22:24:32 +0000 (UTC) Cc: dak@gnu.org, rasmus@gmx.us, emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Dec 19 23:24:22 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 1aAPvJ-00028T-UQ for ged-emacs-devel@m.gmane.org; Sat, 19 Dec 2015 23:24:22 +0100 Original-Received: from localhost ([::1]:38935 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aAPvJ-0006cn-8R for ged-emacs-devel@m.gmane.org; Sat, 19 Dec 2015 17:24:21 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:32802) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aAPv2-0006Zo-6N for emacs-devel@gnu.org; Sat, 19 Dec 2015 17:24:05 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aAPv1-0002O1-0T for emacs-devel@gnu.org; Sat, 19 Dec 2015 17:24:04 -0500 Original-Received: from cheviot22.ncl.ac.uk ([128.240.234.22]:43756) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aAPut-0002Kx-Qz; Sat, 19 Dec 2015 17:23:56 -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 1aAPut-0005FF-Cw; Sat, 19 Dec 2015 22:23:55 +0000 Original-Received: from cpc6-benw10-2-0-cust45.gate.cable.virginm.net ([92.238.179.46] helo=localhost) by smtpauth.ncl.ac.uk with esmtpsa (TLSv1:AES128-SHA:128) (Exim 4.63) (envelope-from ) id 1aAPus-0006dY-KX; Sat, 19 Dec 2015 22:23:54 +0000 In-Reply-To: <83wpsatat1.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 19 Dec 2015 22:58:50 +0200") 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:196536 Archived-At: Eli Zaretskii writes: >> From: phillip.lord@russet.org.uk (Phillip Lord) >> Cc: David Kastrup , , >> Date: Sat, 19 Dec 2015 20:35:14 +0000 >>=20 >> Eli Zaretskii writes: >>=20 >> >>=20 >> >> Conditionals >> >>=20 >> >> * Pattern matching case statement:: How to use @code{pcase}. >> >>=20 >> >> Nonlocal Exits >> >>=20 >> >> * Catch and Throw:: Nonlocal exits for the program's own = purposes. >> >> * Examples of Catch:: Showing how such nonlocal exits can b= e written. >> >> * Errors:: How errors are signaled and handled. >> >> * Cleanups:: Arranging to run a cleanup form if an >> >>=20 >> >> Note that "Conditionals" now appears twice: as a proper node name and= as >> >> a newly added section containing only "pcase" and nothing else. >> > >> > Yes, and that is a problem because...? >>=20 >> I would think that it would make more sense to have "Pattern Matching" >> at top-level. pcase is conditional, but neither pcase-let nor >> pcase-lambda really is. The "conditional" can have a short section >> saying "pcase is like case but with pattern matching", as can the "let" >> and "lambda" documentation. > > Sorry, I'm not following. If we think the second instance of > "Conditionals" is not the best text, we can change it at will. Only > the first one must me identical to the node name. The second one is > "Conditionals" because it was produced by a program and I left it > unchanged, but it can be changed if we want to. Simple change would be from: Conditionals * Pattern matching case statement:: How to use @code{pcase}. to Pattern Matching * Conditional:: How to use @code{pcase} In the grand scheme I would aim for this.... Control Structures * Sequencing:: Evaluation in textual order. * Conditionals:: =E2=80=98if=E2=80=99, =E2=80=98cond=E2=80=99, = =E2=80=98when=E2=80=99, =E2=80=98unless=E2=80=99. * Combining Conditions:: =E2=80=98and=E2=80=99, =E2=80=98or=E2=80=99, = =E2=80=98not=E2=80=99. ....etc Pattern Matching (this would contain a generalised introduction and tutorial, based around pcase) * List Clauses:: Destructuring Lists * Predicates:: Matching with predicate functions * Booleans:: and and or * Guards:: I don't quite understand guards * Conditionals:: pcase * Binding:: pcase-let=20 * Lambda:: pcase-lambda * New Patterns:: pcase-macro, with description of seq and map su= pport. Nonlocal Exits * Catch and Throw:: Nonlocal exits for the program=E2=80=99s own pu= rposes. * Examples of Catch:: Showing how such nonlocal exits can be written. * Errors:: How errors are signaled and handled. * Cleanups:: Arranging to run a cleanup form if an Some of these detailed nodes might be too much -- pcase will inevitably get heavily described in the introduction to pattern matching, while "predicates, booleans and guards" could be described in one place. Phil