all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
From: "João Távora" <joaotavora@gmail.com>
To: Philippe Vaucher <philippe.vaucher@gmail.com>
Cc: emacs-devel <emacs-devel@gnu.org>
Subject: Re: Prefixed manual describe-function and api overview
Date: Sat, 13 Jun 2020 14:41:02 +0100	[thread overview]
Message-ID: <87o8pnxevl.fsf@gmail.com> (raw)
In-Reply-To: <CAGK7Mr7EG-Ug_WXDqe5fsB_a8HiRGiBY8O+DTDA_MQnf6tXS4g@mail.gmail.com> (Philippe Vaucher's message of "Sat, 13 Jun 2020 11:23:37 +0200")

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



  reply	other threads:[~2020-06-13 13:41 UTC|newest]

Thread overview: 14+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-06-04  9:39 Prefixed manual describe-function and api overview Philippe Vaucher
2020-06-04 12:16 ` Stefan Monnier
2020-06-04 14:06   ` Philippe Vaucher
     [not found] ` <E1jh2ly-000090-Hp@fencepost.gnu.org>
2020-06-05  7:55   ` Philippe Vaucher
2020-06-06  3:59     ` Richard Stallman
2020-06-07 12:10       ` Philippe Vaucher
2020-06-08  3:35         ` Richard Stallman
     [not found] ` <CAGK7Mr4_2zus2Hq9=ArpR-ya6FNxxqXWvDxLGTsHsH4-XuM=CQ@mail.gmail.com>
2020-06-11 19:13   ` João Távora
2020-06-12 14:18     ` Philippe Vaucher
2020-06-12 16:02       ` João Távora
2020-06-13  9:23         ` Philippe Vaucher
2020-06-13 13:41           ` João Távora [this message]
2020-06-13 15:46             ` Philippe Vaucher
2020-06-13 16:41               ` Dmitry Gutov

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=87o8pnxevl.fsf@gmail.com \
    --to=joaotavora@gmail.com \
    --cc=emacs-devel@gnu.org \
    --cc=philippe.vaucher@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.