Re: Prefixed manual describe-function and api overview

[Philippe Vaucher]

> > The discoverability should be in the language itself. The more it is
> > in the language, the less you need to document and maintain it, and
> > all tooling benefit from it.
>
> You're going in circles, again.  You don't recognize that Elisp, in its
> current namespaceless form, doesn't lend itself to this as well as you
> would wish.  And you don't recognize the drawbacks that your proposal
> would bring upon others.

Well, yes I do see the drawbacks for you, that's why I'm not proposing
it anymore? If I didn't recognize them I'd still be pushing.
Maybe you want me to actually agree that these are also drawbacks for
me, that sorry I cannot do.

> It is somewhat tiring to try to make progress, because you mis-state
> your goals: you don't want to make this API more discoverable: you want
> to change the API.

At some point I wanted to add aliases (that's not really "changing the
API" in my book but I can understand it is in yours), and that was
seen as disruptive so I gave up.

Anyway, I wanted to make the API more discoverable for me and those
who think like me. I understand my definition of "discoverable" is
different from yours and because of that we run in circles. You think
improving discoverability by adding more manuals is sufficient, I
believe it's not.

It's ok, we don't need to agree. I don't know why we are talking about
this again.

> > I understand it's the point of view of a minority around here, that's ok.
>
> It's not a question of majorities it's a question of the moral
> imperative: we agree about problem A, we find solutions for problem A
> Doing otherwise amounts to a trojan horse, and you face resistance.

But we don't agree on problem A :-) That's the crux, for most of the
people here there's no problem to fix.

> >> It seems we both want the first objective.  But you seem want it with --
> >> or by means of -- the specific side-effect of the second.  I don't that
> >> side-effect at all, and this was already discussed extensively, I think.
> >> Therefore my proposal, the "thing I was pushing for" is a way to have
> >> the first objective without what I (and others) view as the drawbacks of
> >> the second.
> >
> > Yes. I think implementing the first objective without the second is
> > just more work and more things to maintain. and because I'm lazy I
> > prefer to do less work.
>
> You're mistaken.  The solution I gave doesn't require any maintenance
> beyond what is already done, unless you're proposing we cease to
> document functions in the manual altogether.

Hum, you are correct.

What I meant is that because I'll implement the "better C-h f" anyway,
implementing the manual is "more work". Because I'm lazy I'd prefer to
implement only the first and rip the benefits of the second for free.

> > Okay, I guess that's because Texinfo is a language of its own. Yeah ok
> > then I understand your point, you want a texinfo macro that generates
> > the "elisp api overview" so you have the manual-first option. I prefer
> > the code-first option, where the code is the source of truth and
> > things are generated the maximum possible from it instead of having to
> > maintain two separate systems, which can easily become out of sync.
>
> You seem to be proposing to abolish or abandon the Elisp manual.  You
> don't understand its function and utility, is my opinion.

No, I was hinting at having more parts of the manual be generated from
the code. But that's such a wide topic that I don't even want to
start.

> > I understand that's not how Emacs works and it's not conceivable to
> > change this, but I hope you understand where I come from.
>
> I understand where you come from, but not where you want to go to.  And
> neither do you, I suspect.  You should state your difficulties clearly
> and think about them without the prejudice of some foreign predilection.

I think what happened is: I explained clearly where I wanted to go, I
was told "no" and thus moved on to other things. I don't understand
what you are talking about with me not knowing where I want to go.

I don't think discussing this topic will bring anything new, I came in
this thread asking for feedback on a new library I work on, to get
ideas and test the water about what might get considered for inclusion
in Emacs. From what I understand a .texi "elisp api overview" might be
considered for inclusion in the manual, the rest not so much.

I thank you for your feedback, but re-discussing previous discussions
seems pointless to me.

Regards,
Philippe