bug#31311: 27.0; doc of `pcase'

[Drew Adams <drew.adams@oracle.com>]

1. Please rename Elisp manual node `Pattern matching case statement'.
   It should use Title Case (not Sentence case), like the other nodes.
   And do not refer to "case", as the other index entries that match
   `case' have nothing to do with conditionals.  And the node name can
   be shorter, e.g., `Pattern-Matching Conditional'.

2. Don't use ATOM unless you mean any atom, even if you explain
   subsequently that you really mean a self-evaluating atom.  In
   particular, an arbitrary symbol is an atom, and (especially if ATOM
   is described before SYMBOL) ATOM would seem to cover the SYMBOL case,
   which it does not.  Just use "CONSTANT" instead of "ATOM".  AFAIK,
   every self-evaluating sexp in Emacs Lisp satisfies `atomp' (but not
   everything that satisfies `atomp' is a self-evaluating sexp).

   The doc should also make clear whether the ATOM clause covers a
   symbol defined using `defconst'.  The answer seems to be no; it
   seems to be covered instead by the SYMBOL clause.

3. The doc string (but not the Elisp manual, node `Pattern matching case
   statement') refers to "the object" without ever specifying what it
   is.  This makes all of the specifications that use "the object"
   meaningless: 'VAL, (pred FUN), and (app FUN PAT).

   The manual uses "the value being matched" instead, which is OK
   (understandable).  Still, it would be clearer to give a name to "the
   value being matched" at the beginning: EXPVAL, for example, at the
   place where you say, "based on the value of EXPRESSION".

   Similarly, replace "value of the EXPRESSION that is the first
   argument of 'pcase'" by the name you give that (e.g. EXPVAL).

4. The doc string seems to be describing a different animal from the
   manual.  Try to harmonize the two descriptions, including wrt the
   order of pattern presentation.

5. Don't use "QPattern" and "UPattern".  Use "Q pattern" and "U
   pattern", or (probably better) "Q-pattern" and "U-pattern".

6. This part of the description of `guard' is unclear, to me:

   For example ... and let-binds the variable 'x' to that number.

   I see nothing in the descriptions of `guard' and `and' that indicates
   why `x' would be let-bound in this example.

7. The doc-string descriptions do not correspond to those in the manual,
   in several cases.  E.g. (app FUN PAT) is different from (app FUNCTION
   UPATTERN).  Is the pattern necessarily a U-pattern?  Similary for
   `or' etc.

8. Please check for typos.  E.g., "Matches if one the argument UPatterns
   matches."

9. This is not clear to m: "For this reason, if any of the UPatterns
   let-bind symbols to the matched value, they should all bind the same
   symbols."  Should it instead say that they should all bind the same
   symbols to the matched value"?  Also, does a similar thing need to be
   said for `and'?

10. This text: "The function calls used in the 'pred' and 'app'
    UPatterns can have one of the following forms" seems wrong.
    Presumably what it is trying to say is that PREDFUN and FUNCTION
    "can have one of the following forms".  Those forms are not
    necessarily function calls.  Similarly, for the text "The FUNCTION
    call can use one of the forms described below" - just say "FUNCTION
    can use...", not "The FUNCTION call can use...".

11. Do not say "lambda-function".  Say either "lambda expression" or
    "anonymous function".  There is no such thing as a lambda function.
    You might also want to xref node `Lambda Expressions'.

12. "Here is an illustrative example" -> "Here is an example".

13. "you can use backquoted patterns that are more powerful" -> "you can
    use backquoted patterns, which that are more powerful".  The comma
    is important.  This part of the node is not "in addition" to some
    previous description of backquoted patterns; this _is_ the
    description of backquoted patterns, i.e., Q-patterns.  What came
    before was the description of unquoted patterns, i.e., U-patterns.

14. "(note that this example requires lexical binding, *note Lexical
    Binding::)".  Say _why_ this is the case, not just that it is true.
    Why does it require lexical binding?

    Also, the code needs wrapping; two of the lines are too long:

    (funcall (evaluate fun env) (evaluate arg env)) ->
    (funcall (evaluate fun env)
             (evaluate arg env))

    (lambda (val)
      (evaluate body (cons (cons arg val) env))) ->

    (lambda (val)
      (evaluate body
                (cons (cons arg val) env)))

15. Break up the paragraph that begins "Here '`(add ,x ,y)' is a..."

16. All of the following text in the _doc string_ is pretty much
   incomprehensible, to me.  It's not clear what it's trying to say or
   even, in some cases, how it relates to `pcase' at all.  And most of
   it seems to have no correspondence in the manual.

   -- (radix-tree-leaf VPAT)

   Not documented.

   -- (cl-struct TYPE &rest FIELDS)

   Pcase patterns to match cl-structs.
   Elements of FIELDS can be of the form (NAME PAT) in which case the
   contents of field NAME is matched against PAT, or they can be of the
   form NAME which is a shorthand for (NAME NAME).

   -- (seq &rest PATTERNS)

   Build a 'pcase' pattern that matches elements of SEQUENCE.

   The 'pcase' pattern will match each element of PATTERNS against the
   corresponding element of SEQUENCE.

   Extra elements of the sequence are ignored if fewer PATTERNS are
   given, and the match does not fail.

   -- (eieio &rest FIELDS)

   Pcase patterns to match EIEIO objects.
   Elements of FIELDS can be of the form (NAME PAT) in which case the
   contents of field NAME is matched against PAT, or they can be of the
   form NAME which is a shorthand for (NAME NAME).

   -- `QPAT

   Backquote-style pcase patterns.
   QPAT can take the following forms:
     (QPAT1 . QPAT2)       matches if QPAT1 matches the car and QPAT2 the cdr.
     [QPAT1 QPAT2..QPATn]  matches a vector of length n and QPAT1..QPATn match
                              its 0..(n-1)th elements, respectively.
     ,PAT                  matches if the pcase pattern PAT matches.
     ATOM                  matches if the object is 'equal' to ATOM.
                              ATOM can be a symbol, an integer, or a string.

In GNU Emacs 27.0.50 (build 3, x86_64-w64-mingw32)
 of 2018-03-21
Repository revision: e70d0c9e66d7a8609450b2889869d16aeb0363b5
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install -C 'CFLAGS=-O2 -static -g3''