Re: Update of pcase docs for the elisp manual

[Eli Zaretskii]

> From: Andy Moreton <address@hidden>
> Date: Fri, 29 Jan 2016 13:39:59 +0000
> 
> In (info "(elisp) Pattern matching case statement") we currently have:
> 
> "The ‘cond’ form lets you choose between alternatives using predicate
> conditions that compare values of expressions against specific values
> known and written in advance.  However, sometimes it is useful to select
> alternatives based on more general conditions that distinguish between
> broad classes of values.  The ‘pcase’ macro allows you to choose between
> alternatives based on matching the value of an expression against a
> series of patterns.  A pattern can be a literal value (for comparisons
> to literal values you’d use ‘cond’), or it can be a more general
> description of the expected structure of the expression’s value."
> 
> I think this would be clearer without the initial discussion of cond:
> 
> "The ‘pcase’ macro allows you to choose between alternatives based on
> matching the value of an expression against a series of patterns. A
> pattern can be a literal value (for comparisons to literal values you’d
> use ‘cond’), or it can be a more general description of the expected
> structure of the expression’s value."
> 
> This gets straight to saying what pcase is useful for (and when cond is
> sufficient for the task).

I obviously disagree, or else I wouldn't have written that in the
first place.

I think 'pcase' deserves a rationale, and contrasting it with another
similar facility is a good way of presenting that rationale, and at
the same time making the point that 'pcase' shouldn't be used where
'cond' can do the job, something that came up in the recent
discussions.

> Also, the description of CLAUSES for pcase and cond in the manual use:
>   pcase:  (PATTERN BODY-FORMS…)
>   cond:   (CONDITION BODY-FORMS…)
> 
> However the doc strings are inconsistent with the manual:
>   pcase:  (PATTERN CODE...)
>   cond:   (CONDITION BODY...)
> 
> It would be better to use consistent terms.

Blame those who wrote the doc strings ;-)

Thanks.