Re: Prefixed manual describe-function and api overview

[Philippe Vaucher <philippe.vaucher@gmail.com>]

> >> You approach is completely different from what I imagined: I was
> >> thinking of creating new sections in the manual itself, or creating
> >> a whole new manual, without having to actually write the contents
> >> for it.  It could be called the "Elisp API manual", or some better name.
> >> One could visit that API manual from inside and from outside Emacs,
> >> just as one does now with the normal Manual.  A minimal amount of
> >> Elisp code would allow some C-h <key> function to take me there.
> >
> > Well there's two things: the "prefixed" `C-h f` and the "Elisp API
> > manual". I think the prefixed `C-h f`
> > (prefixed-manual-describe-function) is pretty much exactly what I want
> > as a user.
>
> In my opinion, you're confusing/conflating two things, again:
>
> - The ability to have, at a glance, nicely documented, and nicely
>   discoverable, the list of the functions associated with a certain data
>   type, or a certain topic.;
>
> - To have that organization be provided by the existing or a new prefix
>   convention;

I understand the distinction. I agree to a certain degree. I just find
it inefficient to implement these separately. 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.

I understand it's the point of view of a minority around here, that's ok.

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

> >> In other words, as you know, a manual in Emacs is extracted from the
> >> Texinfo source  (.texi files) into various output formats.  I was thinking
> >> about code that performs this extraction into a new output (a new manual,
> >> or a new section in the existing Elisp manual) including all those formats.
> >> Without needing to touch the (.texi) files themselves.  Maybe this could
> >> be done with a special Texinfo macro, maybe redefining its built-in
> >> @defun macro, which is what Emacs uses to introduce a function
> >> definition.  That was my idea.
> >
> > Well I don't know texi files yet, but I think it'd be fairly easy to
> > write some helper elisp that generates what you want based on my code,
>
> That would be very strange IMO, to write this in Elisp.  It would be
> even stranger to write it based on your code.  That said, everything can
> be written in anything.

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.

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.

We'll see if I find time to write that texinfo macro.

Regards,
Philippe