Re: Prefixed manual describe-function and api overview

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

> [I take the liberty from answering to emacs-devel, since you
> seem to be requesting that I weigh in on your work, which is
> public]
>
> > I'm surprised not to hear from you on this. Maybe you missed it?
> >
> > IIRC you were the one pushing for me to implement it, maybe I misremember.
>
> You don't.  I have variable amounts of energy to invest in Emacs
> development, and I didn't think my input would be crucial here.
> Sorry about that, and thank you for your work.

Thanks for your feedback :-)

> I read your email, but was discouraged from trying your program
> since you made it depend on s.el and dash.el which are libraries
> I don't use and steer clear of. Certainly with 120 lines of code you
> can write it without s.el and dash.el, especially now that you've
> supposedly become accustomed with Emacs's API's.

Yeah, I can rewrite it without dash/s.el. It was just the fastest way
for me to get something working. As I said if there is interest, I can
rewrite it without these dependencies. So far I'm not sure there is
interest beyond me and probably some people outside of emacs-devel.

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

About the "Elisp API manual" (prefixed-manual-overview), this is
really just a rough draft and it needs much more work. This one I have
less interest in, but thanks for your description of what you'd like
it to be.

> 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,
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, before resuming with the s.el concrete proposal. I don't
think I have enough time to implement your idea, but we'll see who
knows.

> Hope this helps,
> João Távora

It does ;-)
Philippe