Re: The poor state of documentation of pcase like things.

[Marcin Borkowski]

On 2015-12-18, at 08:15, Eli Zaretskii <address@hidden> wrote:

>> From: address@hidden (Phillip Lord)
>> Date: Thu, 17 Dec 2015 21:16:56 +0000
>> Cc: Alan Mackenzie <address@hidden>, Emacs developers <address@hidden>
>> 
>> Could I suggest [pcase] be promoted in the manual a
>> little. Currently, it's a subnode of "conditionals", but pattern
>> match is really a form of control flow in its own right.
>
> If that's your itch, feel free to scratch it.
>
> IMO, that's largely a waste of your time and energy: the manual is
> rarely if ever read in its entirety, or even in large portions.  Most

Well, I did read most of it some time ago (15 years?).  Then, I mainly
relied on NEWS, `C-s' and `i' in the manual.

I'd love to read the whole manual again some day - I like it - but it's
soo time-consuming...

> of its uses is to quickly find the subject whose description you need,
> hopefully by using the Info-index command ("i TOPIC RET"), and read
> that and perhaps some of the cross-references there.  With this use
> case, the level on which a description is found is irrelevant.
>
> Btw, the importance is in the eyes of the beholder.  You look at that
> through the glasses of someone who hacks Emacs core.  Try to take the
> POV of a casual Lisper who just wants to put some advanced
> customizations in her ~/.emacs, for example.  IOW, advanced features
> and subjects are frequently very important to power users, but much
> less so to "mere mortals".  The manual is supposed to serve both types
> of audience.
>
> Bottom line: what we do need is make the description clear and
> complete.  Where it appears is orders of magnitude less important.

Agreed.

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Faculty of Mathematics and Computer Science
Adam Mickiewicz University