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?7KGw7ISx67mI?= Newsgroups: gmane.emacs.devel Subject: Re: Imports / inclusion of s.el into Emacs Date: Sun, 3 May 2020 03:01:03 +0900 Message-ID: <732552A1-FF05-4292-8972-8C7E3BE922C7@icloud.com> References: <831ro2tqqx.fsf@gnu.org> <4a1fd3f4-df92-c756-9874-4d07b54148ac@yandex.ru> <83v9lesapw.fsf@gnu.org> <83pnbms9m8.fsf@gnu.org> <83a72qs4z2.fsf@gnu.org> Mime-Version: 1.0 (Mac OS X Mail 13.4 \(3608.80.23.2.2\)) Content-Type: text/plain; charset=utf-8; delsp=yes; format=flowed Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="4066"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Philippe Vaucher , Dmitry Gutov , Richard Stallman , joaotavora@gmail.com, monnier@iro.umontreal.ca, emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sat May 02 20:03:08 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 1jUwTk-0000wd-K7 for ged-emacs-devel@m.gmane-mx.org; Sat, 02 May 2020 20:03:08 +0200 Original-Received: from localhost ([::1]:39266 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jUwTj-0002gN-KI for ged-emacs-devel@m.gmane-mx.org; Sat, 02 May 2020 14:03:07 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:49028) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jUwSU-0000nD-Mo for emacs-devel@gnu.org; Sat, 02 May 2020 14:01:55 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.90_1) (envelope-from ) id 1jUwRs-00007U-Ax for emacs-devel@gnu.org; Sat, 02 May 2020 14:01:50 -0400 Original-Received: from pv50p00im-tydg10021701.me.com ([17.58.6.54]:54248) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jUwRr-0008VG-Qe for emacs-devel@gnu.org; Sat, 02 May 2020 14:01:11 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=icloud.com; s=1a1hai; t=1588442470; bh=8eDamFGcHu97iFRiqCcjc1SpQRaRAeAscgFy0Im9cqg=; h=Content-Type:Subject:From:Date:Message-Id:To; b=awW8ls+WKN6G9q5/CPZ1jIPSNfbf9/lVofJ0L9oL5zLwobnZacwmz4L4Vz9HGrPUQ MiTwz2BKrmx76hmgVXIggk9cgjcnUN7D+k7Di4mpVkOyjBx8jzUq2YilPrTfku+sNX JoXE8zqif52TeyaZodDYrVFkYuaWJspMlVGRzvI0KBLp7aOa4ixjnxyDrzEtIvwXLp ByX6sT5I6X3jSRT2WyV7dUyBMKp8ONdLbAa7WSg2v1hb+Ab/2c0j17ErZ/+ztVGYQ+ rcIs/RIe/GFHFit5J/b6DF6j3NUg3XCwY8adhJTsPmwwhLolCERZAm4Ww/p8UGMFur 42CxistwhXMJw== Original-Received: from [192.168.0.2] (unknown [1.230.108.64]) by pv50p00im-tydg10021701.me.com (Postfix) with ESMTPSA id 7347D8400F0; Sat, 2 May 2020 18:01:07 +0000 (UTC) In-Reply-To: <83a72qs4z2.fsf@gnu.org> X-Mailer: Apple Mail (2.3608.80.23.2.2) X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10434:6.0.138, 18.0.676 definitions=2020-05-02_10:2020-05-01, 2020-05-02 signatures=0 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=1 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 mlxscore=0 mlxlogscore=949 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-2002250000 definitions=main-2005020161 Received-SPF: pass client-ip=17.58.6.54; envelope-from=pcr910303@icloud.com; helo=pv50p00im-tydg10021701.me.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/05/02 14:01:10 X-ACL-Warn: Detected OS = Linux 3.11 and newer X-Received-From: 17.58.6.54 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:248515 Archived-At: Eli Zaretskii 작성: >> From: Philippe Vaucher >> Date: Sat, 2 May 2020 17:20:16 +0200 >> Cc: Eli Zaretskii , Emacs developers , >> Stefan Monnier , Richard Stallman , Dmitry Gutov >> >> Say I want to quickly remember how strings work in Emacs, how you >> manipulate them, etc. With a few >> keystrokes I end up on >> https://www.gnu.org/software/emacs/manual/html_node/elisp/Strings-and-Characters.html. >> From there I >> have to select a topics, read it partially, go back, read another topic, >> all that while skipping paragraphs most >> of the time (but that can be improved with my keep-lines trick). >> >> There is no manual entry where I see all these classified string >> functions at once, and "C-h d string" makes >> my emacs so laggy that I cannot use it, also most of the entries are >> irrelevant. > > It sounds very strange to me that the method of learning about strings > is by looking at the list of string-related APIs. Unless one doesn’t have any programming experience, IMO one can learn (or refresh old memory) of how strings work from the API list. (And if that doesn’t work, that’s a design failure. Function names exist for meanings.) > If you want to > learn about strings in Emacs, you should read the entire chapter > "Strings and Characters", including all of its sections and > subsections. This is how a certain topic should be learned for the > first time, or after a long break when you no longer sure you remember > enough of the basics. Does every Emacs user have to go through the long manual to write some short functions? >> Now compare that to https://ruby-doc.org/core-2.6/String.html. Do you >> see how faster that is or is just my >> lack of habit of using the manual? > > What should I look at there? I see a very long list of functions, > each one followed by 5 to 10 lines of description. How is it > different from what we have in the ELisp manual? > >> Or with https://ruby-doc.org/core-2.6/Thread.html, see how you directly >> have an example of common usage? > > How can a single example of "typical usage" help you understand a > complex topic such as threads? A single example is of course not for understanding the whole complex topic, but it serves as a reminder. > And what is "typical usage" of > threads, anyway? I could use threads in umpteen different ways, all > of them "typical". What am I missing? > >> I guess you could argue that I'm not used to having to read big chunks >> of text to get the information I'm >> looking for, that's I think a valid criticism. > > What big chunks of text are you alluding to? Are you saying that the > smaller is the documentation of a function, the better? > > In the ELisp manual we describe each function with as many words as > required to describe its functionality. (There are people who think > we need to tell more.) We also provide "continuity" text to serve as > a "glue" which is supposed to help the reader understand the topic > better and see each API in its context and relation to others. Yes, that’s great when one doesn’t know about programming in general or how Emacs work. It’s not great when you forgot what string API Emacs provides, and trying to find out what operations exist, to write my custom interactive function in the cleanest way possible. > "Manuals" that are just lists of APIs with minimum explanatory text, > a-la JavaDoc, are _bad_ manuals. They don't tell you enough about the > topics for you to understand when use one class of APIs and when to > use another. If you want to see a representative of such bad manuals, > look at the GTK docs. Is this what you'd like to see in the ELisp > manual? No, of course not. I’m pretty sure nobody wants a manual like that. Just that it would be better if there’s a good way to view all of the string operations that Emacs supports without text. I think this is going too far from the original discussion. The original discussion was adding prefixes to *some* functions that aren’t that controversial. (Like make-string, for example.) One of the arguments was that it’s easier to find, remind & predict, which aids in discoverability. The prefix-scheme means that, when one tries to write code, it’s easy to guess based on faint memory or just from pure speculation. And that’s important, especially in Emacs, because one shouldn’t need to read through the manual just to write some interactive functions for a personal configuration. I think a lot of people here are misunderstanding why this is a virtue - understandable since most here are already Elisp masters, can guess make-string or split-string based on memory, write out code without searching. But that’s not true for a lot of Emacs users, including a lot of users who have used Emacs for a long time without writing lots of Elisp or written any packages, and for those people, it’s very useful to guess and write code.