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

Previous Next

Full log

Message #28 received at 68370 <at> debbugs.gnu.org (full text, mbox):

From: Ihor Radchenko <yantar92 <at> posteo.net>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: Stefan Kangas <stefankangas <at> gmail.com>, 68370 <at> debbugs.gnu.org
Subject: Re: bug#68370: 30.0.50; pcase eieio, map, seq, and cl-struct
 constructs are not described in the manual
Date: Fri, 12 Jan 2024 12:47:42 +0000

Stefan Monnier <monnier <at> iro.umontreal.ca> 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>

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.