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

[Phillip Lord]

Eli Zaretskii <address@hidden> writes:

>> From: address@hidden (Phillip Lord)
>> Cc: David Kastrup <address@hidden>,  <address@hidden>,  <address@hidden>
>> Date: Sat, 19 Dec 2015 20:35:14 +0000
>> 
>> Eli Zaretskii <address@hidden> writes:
>> 
>> >> 
>> >>     Conditionals
>> >> 
>> >>     * Pattern matching case statement::  How to use @code{pcase}.
>> >> 
>> >>     Nonlocal Exits
>> >> 
>> >>     * Catch and Throw::         Nonlocal exits for the program's own 
>> >> purposes.
>> >>     * Examples of Catch::       Showing how such nonlocal exits can be 
>> >> written.
>> >>     * Errors::                  How errors are signaled and handled.
>> >>     * Cleanups::                Arranging to run a cleanup form if an
>> >> 
>> >> Note that "Conditionals" now appears twice: as a proper node name and as
>> >> a newly added section containing only "pcase" and nothing else.
>> >
>> > Yes, and that is a problem because...?
>> 
>> I would think that it would make more sense to have "Pattern Matching"
>> at top-level. pcase is conditional, but neither pcase-let nor
>> pcase-lambda really is. The "conditional" can have a short section
>> saying "pcase is like case but with pattern matching", as can the "let"
>> and "lambda" documentation.
>
> Sorry, I'm not following.  If we think the second instance of
> "Conditionals" is not the best text, we can change it at will.  Only
> the first one must me identical to the node name.  The second one is
> "Conditionals" because it was produced by a program and I left it
> unchanged, but it can be changed if we want to.


Simple change would be from:

Conditionals

* Pattern matching case statement::  How to use @code{pcase}.


to

Pattern Matching

* Conditional::  How to use @code{pcase}



In the grand scheme I would aim for this....




Control Structures

* Sequencing::              Evaluation in textual order.
* Conditionals::            ‘if’, ‘cond’, ‘when’, ‘unless’.
* Combining Conditions::    ‘and’, ‘or’, ‘not’.
....etc

Pattern Matching

(this would contain a generalised introduction and tutorial, based
around pcase)

* List Clauses::            Destructuring Lists
* Predicates::              Matching with predicate functions
* Booleans::                and and or
* Guards::                  I don't quite understand guards
* Conditionals::            pcase
* Binding::                 pcase-let 
* Lambda::                  pcase-lambda
* New Patterns::            pcase-macro, with description of seq and map 
support.

Nonlocal Exits

* Catch and Throw::         Nonlocal exits for the program’s own purposes.
* Examples of Catch::       Showing how such nonlocal exits can be written.
* Errors::                  How errors are signaled and handled.
* Cleanups::                Arranging to run a cleanup form if an



Some of these detailed nodes might be too much -- pcase will inevitably
get heavily described in the introduction to pattern matching, while
"predicates, booleans and guards" could be described in one place.

Phil