Re: Prefixed manual describe-function and api overview

[João Távora]

Philippe Vaucher <philippe.vaucher@gmail.com> writes:

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

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.

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

> or some variations of. I'm not sure I have time for that, this project
> was more of me musing around with what emacs would look like with a
> prefixed api

Indeed, that's nothing like I want.  I don't want a "prefixed API" at
all.  I want a nicely documented and discoverable API.  Personally,
except for some cases here and there, I think this already exists.  I
don't have much trouble navigating the existing manual and the
documentation mechanisms, I'm personally fine with the ones I know.

But that's not the case with you.  You were (or still are) very
confounded by them.

Therefore, I suggested a documentation source that would help you, and
presumably many more users like you, to learn Emacs's existing Elisp
API.  I suggested this because that would presumably solve your
difficulties and wouldn't interfere negatively on the organization and
working methods of users like me.

Furthermore, I also suggested you do that work yourself, because you're
the person that originally brought the problem to the table and argued
extensively about it.

João