Re: What's missing in ELisp that makes people want to use cl-lib?

[Alan Mackenzie]

Hello, Gerd.

On Thu, Nov 09, 2023 at 13:19:28 +0100, Gerd Möllmann wrote:
> Alan Mackenzie <acm@muc.de> writes:

> > On Thu, Nov 09, 2023 at 08:24:14 +0100, Gerd Möllmann wrote:
> >> Alan Mackenzie <acm@muc.de> writes:

> >>>Just take one look at this "reality" you're so supportive of: the
> >>>widespread use of cl-lib, not just in people's own projects, but
> >>>throughout the core of Emacs, has multiplied the size of Lisp language
> >>>part of Emacs by a factor of around 3.   This is a gross increase in
> >>>complexity for maintainers that is not justified by the slight increase
> >>>in facility that cl-lib (along with things like seq.el and oclosures)
> >>>gives.

> >>>Throughout this long discussion, this indiscriminate use of cl-lib has
> >>>been supported only by occasional contributers.  Those who actually
> >>>maintain other people's code, apart from (I think) Eli, Richard and
> >>>myself, have been conspicuously silent.  None of us three have favoured
> >>>such use of cl-lib.

> >>>Occasional contributors may be fascinated by cl-lib, and learn enough
> >>>of it to use random bits of it in their code.  The trouble is, each
> >>>such contributor uses a different piece of cl-lib, with the result that
> >>>those who end up maintaining it need to know a far greater part of it
> >>>just to cope.

> >>>This factor of 3 is, I believe, a significant barrier to new
> >>>programmers coming into Emacs; Elisp is just that much more difficult
> >>>than it was in the past.  And it isn't just for newcomers that it is
> >>>more difficult.  I spend a significant amount of debugging time having
> >>>to look up doc strings and manual pages for obscure cl-lib (etc.)
> >>>functions.

> >> > That is the current reality.

> >> Maybe you could elaborate on what the plan then could look like?
> >> Or is it not about a plan, but something else? 

> > You stripped all the context.  I've put it back again.

> > As a concrete plan, I would propose the following for discussion:

> Thanks for that. I find it much easier to digest than this clean/unclean
> thing.

> And wow, that will not be popular :-).

It will be a mixed popular/unpopular, with probably few people in the
middle.  Back when you were the Maintainer, I think there was a ban on
the use of cl.el and friends, except for at compilation time.  I don't
think that caused any problems.

> > We should deprecate those functions/macros/variables in cl-lib that have
> > no doc string, or a substandard one.  This includes "internal" functions,
> > too.  Also to be deprecated are obscure functions/m/v (such as
> > cl-labels).

> Am I right in assuming that this is not about the documentation itself,
> but just some selection criterium for reducing the size of cl-lib?

The most troublesome cl-lib functions are those without adequate
documentation.  They're the ones that waste unbounded amounts of time
when trying to debug something which uses them.  That's why I'd like to
do away with them.  There are few people willing to fix the doc strings
in cl-lib, though João has volunteered to make a start.

> > Having done this, we recode code currently using those deprecated
> > f/m/v.

> What would recode mean? Using seq/map?

I hadn't really thought of seq.el or map.el.  What do they do?  But it's
clear that working code can be written without these or cl-lib.

> > (Here a "substandard" doc string is contrasted with an adequate one,
> > which does all of the following:
> > (i) It says what the function/macro _does_, or what the variable _is_.
> > (ii) It describes the form and meaning of each parameter, and its
> >   relationship to (i).
> > (iii) If the return value is significant, it describes this.
> > (iv) It describes all effects on the global state, such as where it
> >   writes results to, and suchlike.)

> > This would reduce the size of cl-lib to something more manageable than
> > what we have at the moment.

-- 
Alan Mackenzie (Nuremberg, Germany).