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

They _are_ separate things.  When you call a plumber to your house, do
you expect him to install the deluxe cable package?

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

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.

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

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

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

You seem to be proposing to abolish or abandon the Elisp manual.  You
don't understand its function and utility, is my opinion.

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

João