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 19:40:54 +0300 Message-ID: <83wo5uqoh5.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> 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="59167"; 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:41:45 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 1jUvCz-000FIp-FK for ged-emacs-devel@m.gmane-mx.org; Sat, 02 May 2020 18:41:45 +0200 Original-Received: from localhost ([::1]:42402 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jUvCy-0004OT-GU for ged-emacs-devel@m.gmane-mx.org; Sat, 02 May 2020 12:41:44 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:51826) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jUvCU-0003tV-Vr for emacs-devel@gnu.org; Sat, 02 May 2020 12:41:16 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:33415) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jUvCT-0005IS-9t; Sat, 02 May 2020 12:41:13 -0400 Original-Received: from [176.228.60.248] (port=1137 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1jUvCJ-0005Ga-JK; Sat, 02 May 2020 12:41:06 -0400 In-Reply-To: (message from Philippe Vaucher on Sat, 2 May 2020 18:31:27 +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:248492 Archived-At: > From: Philippe Vaucher > Date: Sat, 2 May 2020 18:31:27 +0200 > Cc: João Távora , > Emacs developers , Stefan Monnier , > Richard Stallman , Dmitry Gutov > > > 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? > > Look at the list of methods on the left, which you can click and it makes you jump to the complete > description. I miss that list in Emacs. Why? If you already know what method you want to look up, just use "C-h f" or "i" in Info. If you do NOT know the name of the method, how do you know which method to click on? > > 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'm sorry but I give up. You'd be able to understand on your own why basic examples are helpful. Try to look > at sites like stackoverflow and try to understand why people like it. I guess I'm not smart enough to understand that. > "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? > > I think you need boths. Do you think the Ruby documentation I linked is bad? It's worse than the ELisp manual, yes.