bug#31311: 27.0; doc of `pcase'

[Thien-Thi Nguyen]

() Eli Zaretskii <eliz@gnu.org>
() Thu, 24 May 2018 19:23:22 +0300

   The documentation of 'pcase' is inside Conditionals not
   because it expands to 'cond', but because it can be perceived
   as a kind-of generalization of 'cond' (and the current text
   even says so explicitly).

Yes.  Commit 81d1eaff54ad corrects the count of conditional
forms, mentions this relationship, and adds xref.

   > [because of "sequencing patterns", pcase
   > should follow "Combining Conditions"]

   I think you read too much into the tree-like structure of the
   manual, in particular it sounds like you assume many people
   will read all the sections of this chapter in strict
   depth-first order.

When the output format is text or PDF, depth-first is the order
of presentation.  I was thinking about that use-case primarily,
for this portion of the reasoning.

   But that is not what happens in most use cases.  People
   usually read just the part(s) they need to understand the
   particular feature they need to use in their programs.  When
   read like this, the order matters much less.  What does
   matter is that details and "advanced" features are at lower
   levels, so that first reading doesn't require people to
   negotiate too many obstacles unnecessarily, which would
   prevent them from easily grasping the higher-level picture
   and main ideas.

Agreed.  Random-access readers need less help.

   So I personally don't see too many serious reasons to promote
   this subsection to the level of a section; quite the
   contrary.  But neither am I willing to make yet another
   dispute out of a minor issue such as this.  If you feel
   strongly about this, feel free to do it.

Ack.  My feelings are strong but not validated by experience (in
this case).  If people complain, i'll gladly change it back.

   P.S.  Your messages in this thread have a Mail-Followup-To
   header that [...] causes Rmail to produce both To and CC
   headers to the bug address when I reply, and I'm forced to
   manually remove one of them, which is an annoyance.  Would it
   be possible for you to avoid using that header, please?  TIA.

Sure, no problem.

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