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

["João Távora" <joaotavora@gmail.com>]

Eli Zaretskii <eliz@gnu.org> writes:

> Such improvements are always welcome here.  I just answered your
> original question, viz.:
>
>> > seq.el's documentation is where?  I don't see it.
>
> which seemed to imply that you didn't know at all that we have seq.el
> functions described in the manual.

Sorry, I should have been clearer.  I was talking for some while in this
thread about API implementor's documentation, a description on how to
_extend_ seq.el to define new sequence types, not how to _use_ it in
programs to process sequences.

> Feel free to suggest improvements and additions to what we have.

I've been doing that.  But it still feels like some people are not
convinced that that documentation is essential at all (you seem to be
one of them, reading further).  And before this manual is written down,
we have to come to an agreement of exactly what guarantees seq.el gives
the user who wants to extend it for new sequence types.

> Do you see something like that in other Lisp-related manuals we have?

Yes, for my part see Flymake, Eglot and JSONrpc manuals.  They're not
great, but they each have a section on how to extend the library to
provide new diagnostic backends, new request handlers and new JSONRPC
transports, respectively.

> Does cl.info has this information regarding cl-lib? I think the answer
> is NO

Of course, and that's obvious.  cl-lib is not extensible.

>, because we generally don't say such things in our manuals,

Of course we do.  See 21.6.7

    * Programmed Completion::  Writing your own completion function.

It tells you how to _write_ a completion backend.  The instructions on
how to _use_ completion functions to complete things are elsewhere.

I use this part of the manual all the time, and so does everyone else
writing a backend.  We've been upholding that contract very well for a
number of Emacs releases so, we don't break backends willy-nilly.  I
recently added an optimization (completion-lazy-hilit) that doesn't
break anything (AFAI and other reviewers could tell).

> except in rare exceptional cases

Huh, is Flymake rare and exceptional?  I see a lot of backends popping
up that (correctly) take inspiration from the manual describing how to
extend Flymake.

> (which the seq.el one isn't, IMNSHO).

As far as I could gather from this discussion, seq.el is to be
recommended to users as the preferred way to process sequences in their
Lisp programs, most any program, including basic facilities in the core.

I have shown that performance aspects of this library, even when applied
to primitive data types such as lists and vectors, vary in accordance
with the presence or absence of other custom sequences, because of the
GF-based nature of seq.el.  The nature of these custom sequences changes
the magnitude of the impact.  So IMO it is wise to explain to users
exactly what custom sequences are and aren't supported/recommended.

João