bug#31311: 27.0; doc of `pcase'

[Thien-Thi Nguyen]

() Drew Adams <drew.adams@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
Description: PGP signature