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 18:59:13 +0300 Message-ID: <83a72qs4z2.fsf@gnu.org> References: <831ro2tqqx.fsf@gnu.org> <4a1fd3f4-df92-c756-9874-4d07b54148ac@yandex.ru> <83v9lesapw.fsf@gnu.org> <83pnbms9m8.fsf@gnu.org> Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="18019"; mail-complaints-to="usenet@ciao.gmane.io" Cc: dgutov@yandex.ru, rms@gnu.org, joaotavora@gmail.com, monnier@iro.umontreal.ca, 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 18:01:09 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 1jUuZg-0004c7-4e for ged-emacs-devel@m.gmane-mx.org; Sat, 02 May 2020 18:01:08 +0200 Original-Received: from localhost ([::1]:46148 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jUuZf-0006tU-4e for ged-emacs-devel@m.gmane-mx.org; Sat, 02 May 2020 12:01:07 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:40274) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jUuY7-0005Ms-Lt for emacs-devel@gnu.org; Sat, 02 May 2020 11:59:32 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:60661) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jUuY7-0002XX-9O; Sat, 02 May 2020 11:59:31 -0400 Original-Received: from [176.228.60.248] (port=2498 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1jUuXz-0003Xw-7R; Sat, 02 May 2020 11:59:23 -0400 In-Reply-To: (message from Philippe Vaucher on Sat, 2 May 2020 17:20:16 +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:248476 Archived-At: > 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. 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. > 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? 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. "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?