From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: [ELPA] New package: transient Date: Sat, 02 May 2020 13:54:36 +0300 Message-ID: <83k11utxn7.fsf@gnu.org> References: <87368npxw4.fsf@bernoul.li> <87v9ljo5d0.fsf@bernoul.li> <87ftcnxu5m.fsf@bernoul.li> <83y2qezlpd.fsf@gnu.org> <83tv12zjx1.fsf@gnu.org> <20200429101755.GF24737@tuxteam.de> <838sicw4do.fsf@gnu.org> <83zhaqu89z.fsf@gnu.org> <83sggiu2p9.fsf@gnu.org> Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="57460"; mail-complaints-to="usenet@ciao.gmane.io" Cc: tomas@tuxteam.de, rms@gnu.org, emacs-devel@gnu.org To: Philippe Vaucher Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sat May 02 12:55:25 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 1jUpno-000Eq8-GR for ged-emacs-devel@m.gmane-mx.org; Sat, 02 May 2020 12:55:24 +0200 Original-Received: from localhost ([::1]:42964 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jUpnn-0004zS-IK for ged-emacs-devel@m.gmane-mx.org; Sat, 02 May 2020 06:55:23 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:60938) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jUpnJ-0004CN-FB for emacs-devel@gnu.org; Sat, 02 May 2020 06:54:54 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:54793) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jUpnJ-0002mT-5M; Sat, 02 May 2020 06:54:53 -0400 Original-Received: from [176.228.60.248] (port=3831 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1jUpnB-00049O-PP; Sat, 02 May 2020 06:54:46 -0400 In-Reply-To: (message from Philippe Vaucher on Sat, 2 May 2020 11:53:07 +0200) 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:248398 Archived-At: > From: Philippe Vaucher > Date: Sat, 2 May 2020 11:53:07 +0200 > Cc: Richard Stallman , tomas@tuxteam.de, Emacs developers > > Searching the manual lands me on > https://www.gnu.org/software/emacs/manual/html_node/elisp/Association-Lists.html. This is all good, but > most of the time I don't need all this introduction, I just really need a curated list of the function names related > to the topic I'm searching. When learning this page is really useful but when trying to quickly find what > function you need, this page is 95% noise. What happens is that I'll look at each "-- function" part and enter a > loop of "not that, skip paragraph" until I find the function I want. > > If I take that entry manual and then toggle read only and then "M-x keep-lines -- function" I end up with: > > -- Function: assoc key alist &optional testfn > -- Function: rassoc value alist > -- Function: assq key alist > -- Function: alist-get key alist &optional default remove testfn > -- Function: rassq value alist > -- Function: assoc-default key alist &optional test default > -- Function: copy-alist alist > -- Function: assq-delete-all key alist > -- Function: assoc-delete-all key alist > -- Function: rassq-delete-all value alist > > That's what I would like to get out of the manual easily. I fail to see how will the above list be useful, if you know nothing about the function's name. E.g., a newbie that has no previous Lisp baggage will never be able to guess that assq should have anything to do with association lists. They will need the text keep-lines removes. So maybe you should make your argument more concrete by saying what you did know in this case. My proposal to use Info-index was based on the assumption that you knew nothing except that the function was about alists. In another message you said that you actually knew the function will include "copy" and "alist" somewhere in its name, so I suggested a different command that is better for that use case. IOW, for each use case there's the best tool, and there are others which are good, but not the best. For example, even if you did go to the above manual section, why would you need to generate the list of functions? "C-s copy" finds copy-alist as the first hit. So even being presented with a relatively long (290 lines) section in the manual, finding what you want in that section is a matter of seconds. I fail to see the problem. > Over 95% of my documentation search is just that (quickly looking at a list of functions). I'm fluent in many > languages already, I don't need a regexp (or whatever) introduction with detailed explanations. I just want to > find how to do a regexp match and extract the results. When I fall on > https://www.gnu.org/software/emacs/manual/html_node/elisp/Regexp-Search.html it takes way too much > reading to find `string-match`, and this page doesn't even mention `match-string`! That means I have to do > another search and find > https://www.gnu.org/software/emacs/manual/html_node/elisp/Simple-Match-Data.html. I'm sure that if you > put yourself in my shoes you'd be able to understand my frustration. I cannot put myself in your shoes unless you describe the situation more completely. Specifically, what _did_ you know about string-match and match-string, and which topics relevant to these would be in your opinion relevant for looking up those functions? Then we could continue having a useful discussion, one where the results are that we improve Emacs, including in ways other than those you thought about. E.g., based on what _I_ have in mind in the above situation, I'd first try "i regexp TAB" in the ELisp manual, see nothing pertinent, then try "match TAB", and voila! I see match-data and match-string. > So now I'm no confused because my conclusion from the above was that > you don't want to use the documentation features, but you now > evidently disagreed with that conclusion. Sorry. > > What I said here is that I have to find that manual entry and read 300 lines of text when I could have had a > list of 10 lines to start with. The manual has the information I want, just way too verbose. No need to read the entire section, just use C-s to search for what you want. > Also remember that you were talking about "C-h d alist", I think you missed my further explanations of that > point, allow me quote myself again: > > On Wed, Apr 29, 2020 at 3:19 PM Philippe Vaucher wrote: > >> > >> I think "C-h d alist RET" is your friend. > > > > To further illustrate my point, this doesn't lists `assq` or `assoc`, both functions being indispensable when > using alists. > > My point is that "C-h d alist" is not sufficient to find assq or assoc, thus while a useful tool it's not very > efficient. You don't know me very well, do you? Try "C-h d alist" in a recent development snapshot, and I think you will see those functions there. I fixed that within 5 minutes of your saying that those functions couldn't be found by "C-h d". > There's also a lot of noise on that listing when searching something as generic as "alist". I simply > want a mechanism where I'm close to 100% certain that I have the whole list of functions related to a topic. That depends on what you know about the function; see my earlier response about "C-h a" and in particular about finding a function about which you know that its name should include "copy" and "alist". > Maybe I'm asking for too much, or maybe my way of functionning is "wrong" in the Emacs Lisp world. I'm > curious, please tell me more about how you function, maybe Emacs Lisp is your most used language so you > know it all by heart? How often do you popup the manual, and how often do you use "C-h f"? I think by now you should already know the answer. I have the ELisp manual open in a dedicated frame at all times, and I consult it all the time. I use "C-h f" only if I think I know the function's name quite accurately, and the same with "C-h v" and variables.