From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: Philippe Vaucher Newsgroups: gmane.emacs.devel Subject: Re: Prefixed manual describe-function and api overview Date: Sat, 13 Jun 2020 11:23:37 +0200 Message-ID: References: <87zh98xofe.fsf@gmail.com> Mime-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="127767"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel To: =?UTF-8?B?Sm/Do28gVMOhdm9yYQ==?= Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sat Jun 13 11:24:45 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 1jk2P6-000X9D-8f for ged-emacs-devel@m.gmane-mx.org; Sat, 13 Jun 2020 11:24:44 +0200 Original-Received: from localhost ([::1]:42724 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jk2P5-00039I-B9 for ged-emacs-devel@m.gmane-mx.org; Sat, 13 Jun 2020 05:24:43 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:35160) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jk2Oc-00025r-9s for emacs-devel@gnu.org; Sat, 13 Jun 2020 05:24:14 -0400 Original-Received: from mail-lj1-x22c.google.com ([2a00:1450:4864:20::22c]:44493) by eggs.gnu.org with esmtps (TLS1.3:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jk2OZ-0002Z2-G6 for emacs-devel@gnu.org; Sat, 13 Jun 2020 05:24:14 -0400 Original-Received: by mail-lj1-x22c.google.com with SMTP id c17so13712266lji.11 for ; Sat, 13 Jun 2020 02:24:05 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=VDKCiuZOwFbIufawIEHo9645+bL+FW4F0HAhWWmVDEs=; b=uIjoyUePvf/wag36T/GXgE9xV6Dc4cKwaYrGTO4U50bpR1py/GxOEbJ0rkLBE91K9o Qq47hzuZORFB69Tn3s14nXikKCDrOReiGErViLVism249FRJe5p88KXTp40Cw6lAwQzB Q6EWzaIcWmts4dPQ5JwQ1uvLbeR8fJ3UOlJUdEbxjpqbMEGMSwsf0+Lhwvq8vy461rk6 pnwqWeRydSNIpNtUjHXSmeIUZzvoB6dN+hl95/FSOZr3+R6fOeNI0UgK73cht7FjdIys nNSp6HId8bbkfckNjl6+iwrN7QuTS7TmdjzcoEkzUAlq1te2fYZbBRMNcF8NRCmQW0Z0 P50g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=VDKCiuZOwFbIufawIEHo9645+bL+FW4F0HAhWWmVDEs=; b=JEs2/myLkcWDRs6Dq4aMch/g9917804LQuwrHi8C7O0bDOHK+GReWdquyoj9a9qhq2 XklFvj+fz7KbFVsCorYhUTdzDpEO4332aoQOVTJB82wy8R8eQYxH2tUsDM5QwBEdP7tK SS//WvLn4sbNigHphtpNQs6EEjf1cJmMeEQNWjU6aqqYZ6DSuEaQOz0i8Et/NFFzwe9l 1QbcZ8VW4P7e3aua5riLOW6gED284VySN9VsIc7mN58x+Px1jwGhb5MBpFisNHMdlB3Z c5u6DwiCPGSLLbN5pj8E65LfeECoz1Ce11lF1VBBThRezbhx14ynHt+XADy+hcWSKxd3 m0ZQ== X-Gm-Message-State: AOAM531Qj9qs189zL/IptIoOqMbecORURa3zFG9r7gXh+j2tsfOaQPAn TtMpvDVaS0l57tebWgLffEtVurhj0ZnNLOiJ0wY= X-Google-Smtp-Source: ABdhPJxh/YtsoZi6SR/QmfyvxTCiIVJswYP6CRg3WUGaMnglFCCGndwCn2ml8HGU8TNkXtcZWBphW16AHvzWm7Grf2U= X-Received: by 2002:a2e:998f:: with SMTP id w15mr8565529lji.463.1592040243965; Sat, 13 Jun 2020 02:24:03 -0700 (PDT) In-Reply-To: <87zh98xofe.fsf@gmail.com> Received-SPF: pass client-ip=2a00:1450:4864:20::22c; envelope-from=philippe.vaucher@gmail.com; helo=mail-lj1-x22c.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:252154 Archived-At: > >> 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; I understand the distinction. I agree to a certain degree. I just find it inefficient to implement these separately. 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. I understand it's the point of view of a minority around here, that's ok. > 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. > >> 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. 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. We'll see if I find time to write that texinfo macro. Regards, Philippe