bug#31311: 27.0; doc of `pcase'

[Thien-Thi Nguyen]

() Drew Adams <drew.adams@oracle.com>
() Sun, 29 Apr 2018 09:03:32 -0700 (PDT)

   [points 1. through 15.]

I have just pushed branches:

 fix/bug-31311-pcase-docs
 fix/bug-31311-pcase-docs-squash

that address these points (and others raised during discussion).
The latter branch is the former, squashed, and additionally
rebased off ‘emacs-26’.  Here are the four commits, briefly:

 25d3e50  Ensure pcase doc shows `QPAT first among extensions
 62b1cef  Introduce EXPVAL for pcase, pcase-defmacro docstrings
 a7bf9ce  Use EXPVAL in docstrings of patterns defined using pcase-defmacro
 2df20b3  Overhaul pcase documentation

(The first is mostly independent of this bug, and so its commit
message lacks the "(Bug#31311)" found in the others'.)

   16. All of the following text in the _doc string_ is pretty
       much incomprehensible, to me.

       [...]

Yeah, i was also flummoxed for a bit.  The third commit touches
many of these docstrings, the ones that i could decipher.  Its
changes do not improve the meaning too much, i'm afraid (but at
least, now they are more consistent in one syntax aspect).

       -- `QPAT

This particular extension is actually "built-in" in spirit.  The
first commit takes care to support that impression (somewhat).
The other commits improve its docstring, i believe.

The -squash branch is ready for merge.  I'll wait a few days for
comments and do the merge, unless someone beats me to it.

Once merged, i'd like to reserve the right to delete those
branches (personal closure :-D), if the maintainers don't mind.

-- 
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