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: Fri, 12 Jun 2020 17:02:29 +0100 Message-ID: <87zh98xofe.fsf@gmail.com> References: 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="74706"; 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 Fri Jun 12 18:04:05 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 1jjm9y-000JJg-Lr for ged-emacs-devel@m.gmane-mx.org; Fri, 12 Jun 2020 18:04:02 +0200 Original-Received: from localhost ([::1]:47258 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jjm9x-0002LJ-OB for ged-emacs-devel@m.gmane-mx.org; Fri, 12 Jun 2020 12:04:01 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:56672) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jjm8h-00012z-3h for emacs-devel@gnu.org; Fri, 12 Jun 2020 12:02:43 -0400 Original-Received: from mail-wr1-x42c.google.com ([2a00:1450:4864:20::42c]:41769) by eggs.gnu.org with esmtps (TLS1.3:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jjm8e-0008Go-Kp for emacs-devel@gnu.org; Fri, 12 Jun 2020 12:02:42 -0400 Original-Received: by mail-wr1-x42c.google.com with SMTP id j10so10264140wrw.8 for ; Fri, 12 Jun 2020 09:02:34 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:in-reply-to:references:user-agent:date :message-id:mime-version:content-transfer-encoding; bh=7ncUZGTQsWJ3Q3wk6vCU/dEb3BXLFgovr+HBhVS35hE=; b=PijJIoYYEJeD3wovPh1YllE98QNPG5mksTJ2i3cHGebVxdjTH0dH+wWOCDow6/ACCy bvZ9Gnba2m3bVJ9Nt+lRgjsOzqykZFWRO5HLBlOrpBjRBf4G6So6b5Q0BwaE8MkdIc2F yxSpoL33DhExVU07btoNoI3q2Me3NbHMFDQ6/MoodEh0bDIJxQLPhao8cRHNm9UsDmuS z2vMg51lSC2rOX4JkuN8xTYC8vV/ALLecniJp32Wm+j8WkEWIQ/chdPtXfc7s/jqgydj VBV/1O5CIv5Is62lNitQhbp2LwQeuNAy3pzo6Me07hRsthv4z22vOYO/Yr98c5nR5Wd5 WliQ== 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:in-reply-to:references :user-agent:date:message-id:mime-version:content-transfer-encoding; bh=7ncUZGTQsWJ3Q3wk6vCU/dEb3BXLFgovr+HBhVS35hE=; b=bZu5m3SOJUb+h+V98qnCjBWn6XwNUA7Lzv80ZU3dUrxE5LFBJdEOi4xPHkvDSbUW68 M9Flp8PdpBqxoQa27aSDyDjRhroMhqlM69VvkgT/xrl++uPeKujtgsdUb1+sij/zJmL/ BRxEuBthYFr3Tc/z7cK+X3XVLlSd/doRRknOfHFYS2f83IJZaFX/EgBNPQaOQjfv1gO/ Z5DHu7a7303iQEVAsmgMjYiuqN8Gw43dBmxAnN9cvQ4YarYeWv7UwfFuDLvk/jJzc+9D 9k8d6ybBuFhkAfsBXGwZxh0QtqAZhwBiwC/Jz20qyr9NMcReqvUaLwQYHRvXZ/wMDQYF G7dg== X-Gm-Message-State: AOAM531HMk7izvfePQDEBTIHxaXC2xn51h9MFXh0CAW4H8BGR1tByGN8 d4551iPpJvFLk/baejCtWsQvYgltEMc= X-Google-Smtp-Source: ABdhPJyzJinf71rziRAMa8hCWdl77Rup1MBbYHuOGmp7mEWsN4EJ9jD6cKm0AaeJlgVLfMM0QvTF+Q== X-Received: by 2002:a5d:4d01:: with SMTP id z1mr16781352wrt.29.1591977752480; Fri, 12 Jun 2020 09:02:32 -0700 (PDT) Original-Received: from krug ([2001:818:d820:9500:824a:171:15a:2213]) by smtp.gmail.com with ESMTPSA id b8sm10994835wrs.36.2020.06.12.09.02.31 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 12 Jun 2020 09:02:31 -0700 (PDT) In-Reply-To: (Philippe Vaucher's message of "Fri, 12 Jun 2020 16:18:22 +0200") Received-SPF: pass client-ip=2a00:1450:4864:20::42c; envelope-from=joaotavora@gmail.com; helo=mail-wr1-x42c.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:252135 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 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 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 thinki= ng >> 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 forma= ts. >> 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=C3=A3o