Re: Update of pcase docs for the elisp manual

[Andy Moreton]

On Fri 29 Jan 2016, Eli Zaretskii wrote:

>> From: Andy Moreton <address@hidden>
>> Date: Fri, 29 Jan 2016 13:39:59 +0000
>> 
>> 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.

Fair enough. Please consider starting a new paragraph though:

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

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

I sought improvement, not blame :-)

    AndyM