GNU bug report logs - #31311
27.0; doc of `pcase'

Previous Next

Full log

View this message in rfc822 format

From: Thien-Thi Nguyen <ttn <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 31311 <at> debbugs.gnu.org
Subject: bug#31311: 27.0; doc of `pcase'
Date: Mon, 30 Apr 2018 09:48:15 +0200

[Message part 1 (text/plain, inline)]

() Drew Adams <drew.adams <at> oracle.com>
() Sun, 29 Apr 2018 19:47:08 -0700 (PDT)

   > > 2. Don't use ATOM [...]
   > 
   > "ATOM can be a keyword, an integer, or a string".  In
   > particular, floats are excluded.  nil and t are also
   > excluded.  "KEYWORD-OR-INTEGER-OR-STRING" is not a good
   > name, however.

   It may not be a good name, but it is not so misleading.  And
   it's not used in a zillion places, so it's not a big deal if
   the name is long: INTEGER-STRING-OR-KEYWORD or even perhaps
   INTEGER|STRING|KEYWORD.  We have much longer stuff in the
   description of font-lock stuff and elsewhere.  Complex things
   need careful breakdowns and named parts.

   "Atom", without that qualification, includes lots of other
   things, including vectors and, in particular, symbols.

Since "atom" is a shorthand for this set of types in an @item
context, another solution is to list the types explicitly:

 @item @var{integer}
 @itemx @var{string}
 @itemx @var{keyword}

 These types are self-quoting [...]

In this way, we achieve grouping through presentation and not
through coining (possibly confusing) terms.  This makes the text
longer vertically, but flattens the conceptual model (for this
particular grouping of types) for the reader, who can mentally
coin terms on their own, like "!@#$%-complicated-sh*t".  :-D

   Oh, and do the other two occurrences of ATOM - those in the
   description of Q-patterns - mean the same thing: keyword,
   string, or integer?  Nothing said about that; not clear.

Same technique applicable, here.  Generally, it's good to use
abstractions in code (DRY principle), but for documentation, a
flatter landscape w/ simple landmarks is easier to navigate.

This is one of the sadnesses i have come to realize as a
programmer trying to communicate w/ non-programmers.

-- 
Thien-Thi Nguyen -----------------------------------------------
 (defun responsep (query)
   (pcase (context query)
     (`(technical ,ml) (correctp ml))
     ...))                              748E A0E8 1CB8 A748 9BFA
--------------------------------------- 6CE4 6703 2224 4C80 7502

[signature.asc (application/pgp-signature, inline)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.