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

[Alan Mackenzie]

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:

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

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

(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).