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

[Gerd Möllmann]

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

>
> 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?

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

What would recode mean? Using seq/map?

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