From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: =?utf-8?B?Sm/Do28gVMOhdm9yYQ==?= Newsgroups: gmane.emacs.devel Subject: Re: Prefixed manual describe-function and api overview Date: Sat, 13 Jun 2020 14:41:02 +0100 Message-ID: <87o8pnxevl.fsf@gmail.com> References: <87zh98xofe.fsf@gmail.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="126454"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.91 (gnu/linux) Cc: emacs-devel To: Philippe Vaucher Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sat Jun 13 15:42:12 2020 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jk6QF-000WlE-Dp for ged-emacs-devel@m.gmane-mx.org; Sat, 13 Jun 2020 15:42:11 +0200 Original-Received: from localhost ([::1]:58154 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jk6QE-0000CS-ES for ged-emacs-devel@m.gmane-mx.org; Sat, 13 Jun 2020 09:42:10 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:36464) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jk6PM-0007zk-0v for emacs-devel@gnu.org; Sat, 13 Jun 2020 09:41:16 -0400 Original-Received: from mail-wm1-x336.google.com ([2a00:1450:4864:20::336]:40501) by eggs.gnu.org with esmtps (TLS1.3:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jk6PK-0001wj-5Z for emacs-devel@gnu.org; Sat, 13 Jun 2020 09:41:15 -0400 Original-Received: by mail-wm1-x336.google.com with SMTP id r15so10475718wmh.5 for ; Sat, 13 Jun 2020 06:41:07 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version:content-transfer-encoding; bh=pQNJaemNfsn+owVi20k2YyDn8RRoJRnBHTnJlBpfzgo=; b=Sn/MnNQ5yCuD4iOOFaJ2VsLT4b16BeveKQX7NyhavXl+rud8B7uaHEzu7+yG9ADhvK Q67tKdF4EssqRRhcFj7u7LndKig8avO0l+oUFJ8/oXTBJ7RH7+gY3TkGAdtnZOfCuyCf Lfsd7sZLw8hDhuoiggkoyh/jBY2sJQqv8kgdak6LOeOoTX3G9y4ccf/0+7P/wpKKSdQA AY9W3NvQlgUcq9l2UDLtLb92tvQAPRxfYJA5i7GZim6OKy5+HAb7U+9lUPxtdaPucPWa DqhT+O1uik9K35l9kJd6AcikgNa/yHqnWKmDtrFza0Bocdoz9Sz6VSu3ycpmyO8q1paX bTMA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:references:date:in-reply-to :message-id:user-agent:mime-version:content-transfer-encoding; bh=pQNJaemNfsn+owVi20k2YyDn8RRoJRnBHTnJlBpfzgo=; b=Gh7TCRPHCvvbgjIa54iLyKd9f7RWk16/+pqsyk1zkjErYnZXvT7axblluxJu7hVv7E zrL28i/jTuPIeSItnaB7i3tIKDN8f6vSvImIJ5Wht7usU7z47E2U4c3IuFr3v9CvYEr2 NJeI22EFfS107Uu7iBxvOhiddnqXTXmg3oQ7mHpwM1Nf9ohSFN69t6kvp9HK/b6ExqxI Rjxy/SC89CmEb58RbfHJUR2wlnIbIOSlM13/Db8esSwf5248cX4ymynxVoxyJ/BqdQd4 53aCDIlnocIrZi0fVowi/t/sWafkdTs4B0Bvwh2tV8QYBuF4BsJEBvLfGM0a5P5IUp2A IE7w== X-Gm-Message-State: AOAM531FAduLfSrgX+eb2xhI9SPfc/4oX73aThwyWLqcZkMdsX8yt6Ei aIuXinnVtjmsy2wj2/6OCXnGgVwDnec= X-Google-Smtp-Source: ABdhPJwCaRx6eIBkuXzXFv2pYq5QfiRBGhNE4GhNIGVfDlO7Dp+Qm0AbVkKB9OaLfa0cFYikxLA4YQ== X-Received: by 2002:a1c:acc8:: with SMTP id v191mr4201527wme.154.1592055665643; Sat, 13 Jun 2020 06:41:05 -0700 (PDT) Original-Received: from krug ([2001:818:d820:9500:824a:171:15a:2213]) by smtp.gmail.com with ESMTPSA id b185sm22016805wmd.3.2020.06.13.06.41.04 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 13 Jun 2020 06:41:04 -0700 (PDT) In-Reply-To: (Philippe Vaucher's message of "Sat, 13 Jun 2020 11:23:37 +0200") Received-SPF: pass client-ip=2a00:1450:4864:20::336; envelope-from=joaotavora@gmail.com; helo=mail-wm1-x336.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=_AUTOLEARN X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:252164 Archived-At: Philippe Vaucher 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 na= me. >> >> 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 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 thi= nking >> >> about code that performs this extraction into a new output (a new man= ual, >> >> or a new section in the existing Elisp manual) including all those fo= rmats. >> >> Without needing to touch the (.texi) files themselves. Maybe this co= uld >> >> 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=C3=A3o