Subject: bug#68370: 30.0.50; pcase eieio, map, seq, and cl-struct constructs are not described in the manual

From: Ihor Radchenko <[email-masked]>
Date: Fri, 12 Jan 2024 12:47:42 +0000

Stefan Monnier <[email-masked]> writes:

>>> AFAIK these "belong" to `map.el`, `seq.el`, etc... so that's where they
>>> should be documented.  The documentation for `pcase` could of course
>>> include corresponding cross-references.
>> Do you mean "6.1 Sequences" section of the manual?
>
> I meant "where ever it's documented", so yes that sounds about right :-)

This might be tricky in practice:

1. eieio is more or less clear - it is a separate manual
2. seq.el is documented in 6.1 section, which may be a problem - the
   very concept of pattern matching is only introduced in 11.4.1 (pcase)
   section. So, it might be confusing for the readers to see information
   about pattern matching so early in the manual.
3. map.el does not have any documentation in manual. It may mean that
   (map ..) pattern should not be documented. Or it may mean that we
   need to add a map.el section to the manual.
4. 11.4.1 The ‘pcase’ macro section already documents ‘(cl-type TYPE)’,
   but not (cl-struct TYPE &rest FIELDS). It will be awkward to document
   cl-struct pattern in CL manual, while leaving cl-type in the 11.4.1
   section of the Elisp manual.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>