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 17:46:19 +0200 Message-ID: References: <87zh98xofe.fsf@gmail.com> <87o8pnxevl.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="120894"; 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 17:47:55 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 1jk8Nu-000VL6-2N for ged-emacs-devel@m.gmane-mx.org; Sat, 13 Jun 2020 17:47:54 +0200 Original-Received: from localhost ([::1]:54552 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jk8Nt-00040l-58 for ged-emacs-devel@m.gmane-mx.org; Sat, 13 Jun 2020 11:47:53 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:32990) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jk8Mx-0002qS-D2 for emacs-devel@gnu.org; Sat, 13 Jun 2020 11:46:55 -0400 Original-Received: from mail-lj1-x22a.google.com ([2a00:1450:4864:20::22a]:39545) by eggs.gnu.org with esmtps (TLS1.3:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jk8Mv-0007Ho-IF for emacs-devel@gnu.org; Sat, 13 Jun 2020 11:46:55 -0400 Original-Received: by mail-lj1-x22a.google.com with SMTP id a9so14387156ljn.6 for ; Sat, 13 Jun 2020 08:46:47 -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=GE+h9cuEYIU1Wj/5JwSbp1NQ3Ue1lZPIOXdzCPS/5kU=; b=Qs4lFeTgT/+KJpCyB31BybtigljIg1oHpLELX/FU+lDdeBZbKmez3ffnWrhDb+cDKJ zU1PUCi3HZ354I3QI3L9a4Pf+fxCu6kP5a3NIVOvV4F+Pw8RES1ZUv80ODZEiPGrk/qW BPTmbqMI4OMwokIGvVDJcLbv59+hKEW0fls0CxsbCQB4hIhfkTzvlIeCDWiFrYp94sSb U8j8ZG9ZKf1mVGLkFdW2Vajy1hNVO76YsV+zVT4mLJn1AtqVgRy5Ej55i9zGyIH9RfHV YyMilSz3JOJuSfrmkadmRl9ES1HYg3Bo4QgPUWJ3K/YY2nzO9ETaMRBNJTV6VuTbsPxj pa5A== 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=GE+h9cuEYIU1Wj/5JwSbp1NQ3Ue1lZPIOXdzCPS/5kU=; b=RTWOFzvx8xcnjg5mBqsYZ+56rU1bTMnEHDp/ttWu3CXjIM6Og/uzyspT/ZpO3WPMlh +NQP2l2/6GrOMnFFyt9pbxczzBk4PsDgaj6RhZuXad21ONEGg8RRJGNEu2IkJBk+TTAc +RQn3GMz1XNH66OBhD1vF/0Fr/qbLGE8jT2XwopiQXkbBjlVASS9UU68sBqNf5Q0q43n C70cve7DNXq3r0gHzPLv556iwHlVsJ4qGFVBqBEz4h/r+QzqlFzEeenRRdlUrrnpIw0J zewly+85sp8j4ZOdzu88+hUPy2YbVAGNm8SbNnkxFuaDjQ1ZhXO9uY15yTUHQyKnY6s6 xvsQ== X-Gm-Message-State: AOAM532um77OG5qPAsCnUzWRxjD6Udd4iZuz0inmrzuBoqGDDYqOyKHI TEaJ3iDwR5FGPdDUl25aHKTFZ3SVgqPLboL0rWg= X-Google-Smtp-Source: ABdhPJxouKMe1wbgbb1jzt1ONJIAY9vorUSZanRU99SndmuS87SXrR/Q8aojG+xPTQ59SFJVKTLw7BuuxKc2QXn0/eo= X-Received: by 2002:a2e:8e2f:: with SMTP id r15mr6038936ljk.54.1592063205893; Sat, 13 Jun 2020 08:46:45 -0700 (PDT) In-Reply-To: <87o8pnxevl.fsf@gmail.com> Received-SPF: pass client-ip=2a00:1450:4864:20::22a; envelope-from=philippe.vaucher@gmail.com; helo=mail-lj1-x22a.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:252180 Archived-At: > > 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. Well, yes I do see the drawbacks for you, that's why I'm not proposing it anymore? If I didn't recognize them I'd still be pushing. Maybe you want me to actually agree that these are also drawbacks for me, that sorry I cannot do. > 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. At some point I wanted to add aliases (that's not really "changing the API" in my book but I can understand it is in yours), and that was seen as disruptive so I gave up. Anyway, I wanted to make the API more discoverable for me and those who think like me. I understand my definition of "discoverable" is different from yours and because of that we run in circles. You think improving discoverability by adding more manuals is sufficient, I believe it's not. It's ok, we don't need to agree. I don't know why we are talking about this again. > > 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. But we don't agree on problem A :-) That's the crux, for most of the people here there's no problem to fix. > >> 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. Hum, you are correct. What I meant is that because I'll implement the "better C-h f" anyway, implementing the manual is "more work". Because I'm lazy I'd prefer to implement only the first and rip the benefits of the second for free. > > 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. No, I was hinting at having more parts of the manual be generated from the code. But that's such a wide topic that I don't even want to start. > > 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. I think what happened is: I explained clearly where I wanted to go, I was told "no" and thus moved on to other things. I don't understand what you are talking about with me not knowing where I want to go. I don't think discussing this topic will bring anything new, I came in this thread asking for feedback on a new library I work on, to get ideas and test the water about what might get considered for inclusion in Emacs. From what I understand a .texi "elisp api overview" might be considered for inclusion in the manual, the rest not so much. I thank you for your feedback, but re-discussing previous discussions seems pointless to me. Regards, Philippe