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: Imports / inclusion of s.el into Emacs Date: Sat, 02 May 2020 21:24:51 +0300 Message-ID: <83sggiqjnw.fsf@gnu.org> References: <831ro2tqqx.fsf@gnu.org> <4a1fd3f4-df92-c756-9874-4d07b54148ac@yandex.ru> <83v9lesapw.fsf@gnu.org> <83pnbms9m8.fsf@gnu.org> <83a72qs4z2.fsf@gnu.org> <732552A1-FF05-4292-8972-8C7E3BE922C7@icloud.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="99919"; mail-complaints-to="usenet@ciao.gmane.io" Cc: rms@gnu.org, emacs-devel@gnu.org, joaotavora@gmail.com, dgutov@yandex.ru, monnier@iro.umontreal.ca To: =?utf-8?B?7KGw7ISx67mI?= Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sat May 02 20:26:02 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 1jUwpu-000Pru-Md for ged-emacs-devel@m.gmane-mx.org; Sat, 02 May 2020 20:26:02 +0200 Original-Received: from localhost ([::1]:51880 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jUwpt-0003yw-Oa for ged-emacs-devel@m.gmane-mx.org; Sat, 02 May 2020 14:26:01 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:55998) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jUwpH-0003Om-5J for emacs-devel@gnu.org; Sat, 02 May 2020 14:25:23 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:35692) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jUwpG-0002Mc-6u; Sat, 02 May 2020 14:25:22 -0400 Original-Received: from [176.228.60.248] (port=3457 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1jUwov-0007fC-FU; Sat, 02 May 2020 14:25:02 -0400 In-Reply-To: <732552A1-FF05-4292-8972-8C7E3BE922C7@icloud.com> (message from =?utf-8?B?7KGw7ISx67mI?= on Sun, 3 May 2020 03:01:03 +0900) 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:248522 Archived-At: > From: 조성빈 > Date: Sun, 3 May 2020 03:01:03 +0900 > Cc: Philippe Vaucher , > Dmitry Gutov , > Richard Stallman , > joaotavora@gmail.com, > monnier@iro.umontreal.ca, > emacs-devel@gnu.org > > > 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. I doubt that. > > 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? Of course not. The Emacs manuals are designed to support 2 general use cases: . reading on a subject (like strings) for the first time, i.e. using the manual as a textbook . finding quickly the details about some small topic, i.e. using the manual as a reference In the first use case you are supposed to read the chapter, in the second you are supposed to use index-search for that topic you have in mind (the topic could also be the name of a function or a key sequence). That second use case would be the case of writing a short function. > > 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. A reminder of a single example can only be useful if that example happens to be what you want. For a subject as broad as strings or threads, this is unlikely to be the case. The ELisp manual includes quite a few examples, each one where we want to explain some topic by showing concrete code. > > 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. I invite you to read the chapter about strings and characters in the ELisp manual, and also examine the index entries in that chapter. Then we could talk specifics. Otherwise I have no way of connecting what you say with what is actually in the manual. > > "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. And I'm sure such a list will be almost useless. Nevertheless, I'm not opposed to having such a list somewhere. I just don't think it's an efficient way of finding information quickly and efficiently -- except if one already knows the name of the function. But I already said that several times, so it's time to stop repeating myself. > 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. You are mistaken: I'm not such a master. Like Stefan, I can never remember whether its string-multibyte-p or multibyte-string-p. I use the manual and the doc strings all the time because I don't remember all those details. So what I wrote is based on personal experience of looking up and finding this information quickly and efficiently.