From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: Philippe Vaucher Newsgroups: gmane.emacs.devel Subject: Re: Imports / inclusion of s.el into Emacs Date: Sat, 2 May 2020 18:31:27 +0200 Message-ID: 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: multipart/alternative; boundary="000000000000f257eb05a4acd5a4" Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="22982"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Dmitry Gutov , Richard Stallman , =?UTF-8?B?Sm/Do28gVMOhdm9yYQ==?= , Stefan Monnier , Emacs developers To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sat May 02 18:32:51 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 1jUv4N-0005rS-0V for ged-emacs-devel@m.gmane-mx.org; Sat, 02 May 2020 18:32:51 +0200 Original-Received: from localhost ([::1]:37980 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jUv4M-0000rd-2z for ged-emacs-devel@m.gmane-mx.org; Sat, 02 May 2020 12:32:50 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:48584) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jUv3a-00084V-CA for emacs-devel@gnu.org; Sat, 02 May 2020 12:32:02 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.90_1) (envelope-from ) id 1jUv3Z-0007NG-MR for emacs-devel@gnu.org; Sat, 02 May 2020 12:32:02 -0400 Original-Received: from mail-lf1-x12c.google.com ([2a00:1450:4864:20::12c]:44707) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jUv3V-000768-8r; Sat, 02 May 2020 12:31:57 -0400 Original-Received: by mail-lf1-x12c.google.com with SMTP id d25so6159921lfi.11; Sat, 02 May 2020 09:31:56 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=HyAKvSkOBoW0XFCEWqHSG8v+tFPKDz1FbJNFxVO6b9o=; b=paqFKc72+2VBMoO1ipe7OoI3QgK30TU4Dx7gBNFlM96If0a++h/NT+mOvjfh6uqnyC apjSezGrml4vXE+5PT5yxh0kKgMD4kFDiwDw4huwDgF8gcpgVuM6SW6nlLyyWj+ZdB2W HArn2i4N8YqsNTTjuwCm+mPyZ/HxQQqASSV7El02ORAPapEWXyMl0Tm4BDB3tnJcSmbC bJtb5qoJ+aSi4fMNXCARXwBKdSKJppl8neITiRFCI3JdWNL6dwsOiVeByFHXF+cIEh9i c6FsAikqZ9Ivy7D/3eX/+b/zrvsTZaT21nrqnr4UbSb+IZ0JgW/z3n8Pp5VdZAFk4ard 22pQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=HyAKvSkOBoW0XFCEWqHSG8v+tFPKDz1FbJNFxVO6b9o=; b=WcFwNzx9iDHKOhmRtV7YlUfOyIr1SXbKu1TO+iXuAxXvWT8XPaTwhiC04YJl8HWwpp IzXWrSUMJuAEEB0E8OCtcYcq37et18fuoAAMMD8YPg17cXq25UcM1MNsRQ8/dPLRQwxQ t1dkiEXz8k/7TyUoVXpzhgj3ZsPoXb1WaK+Dxe7f1ixf0UaBLDcmo0QCnEQIM4Rwk0z4 hXk30V5raeQ/IzGdf9WFCQtKOcdUeJW5mmmyPTNB/7j0xPZy+AS/2SZBM+kEV9qztHc/ wu2Dq2aXkje3/g8vIbh3SEytQWvllDyccJBlWhYFgLlB3Ps4VhfCnC6gt7GyccrlJKQ+ n9Rw== X-Gm-Message-State: AGi0PubaWIYxI9QQCQZczXXM2vzl44aJ2Qpxa7mJ2eqviZl//srR0o9R vlBmoTut+tw++LvNE2vhM9dkVmU/YLA5jvCAnxlYtupQOaQ= X-Google-Smtp-Source: APiQypKCXW34FcXWeWI5OthPCVI0Iww+NurFfJDIGKkI9jitPPir0xSARLp0Vq2cA6laVlPt0Ts/Ua7Dpf1gpKSyrKw= X-Received: by 2002:ac2:4248:: with SMTP id m8mr6029652lfl.211.1588437114311; Sat, 02 May 2020 09:31:54 -0700 (PDT) In-Reply-To: <83a72qs4z2.fsf@gnu.org> Received-SPF: pass client-ip=2a00:1450:4864:20::12c; envelope-from=philippe.vaucher@gmail.com; helo=mail-lf1-x12c.google.com X-detected-operating-system: by eggs.gnu.org: Error: [-] PROGRAM ABORT : Malformed IPv6 address (bad octet value). Location : parse_addr6(), p0f-client.c:67 X-Received-From: 2a00:1450:4864:20::12c 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:248491 Archived-At: --000000000000f257eb05a4acd5a4 Content-Type: text/plain; charset="UTF-8" > > > 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. > I understand that's how you function. That's not how I & some others function. My way is arguably bad, but it just works in other languages. > > 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. > > 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 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? > Well, do you really believe this is what I'm trying to say? I'm saying the full-blown documentation is all that is available, and I'd like a summarized view like in other languages. > 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, the Emacs manual is good in that regard. > "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? Philippe --000000000000f257eb05a4acd5a4 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
> There is no manual entry where I see all these clas= sified 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 i= rrelevant.

It sounds very strange to me that the method of learning about strings
is by looking at the list of string-related APIs.=C2=A0 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.=C2=A0 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.

I understand that= 's=C2=A0how you function. That's not how I & some others=C2=A0f= unction. My way is arguably bad, but it just works in other languages.

=C2=A0
> 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?=C2=A0 I see a very long list of functions,
each one followed by 5 to 10 lines of description.=C2=A0 How is it
different from what we have in the ELisp manual?

<= /div>
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.

=C2=A0
> Or with https://ruby-doc.org/core-2.6/Threa= d.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?=C2=A0 And what is "typical usage" = of
threads, anyway?=C2=A0 I could use threads in umpteen different ways, all of them "typical".=C2=A0 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 stac= koverflow and try to understand why people like it.

=C2=A0
> I gues= s you could argue that I'm not used to having to read big chunks of tex= t to get the information I'm
> looking for, that's I think a valid criticism.

What big chunks of text are you alluding to?=C2=A0 Are you saying that the<= br> smaller is the documentation of a function, the better?

Well, do you really believe this is what I'm trying to= say?

I'm saying the full-blown documentation = is all that is available, and I'd like a summarized view like in other = languages.

=C2=A0
In the ELisp manual we describe each function with a= s many words as
required to describe its functionality.=C2=A0 (There are people who think we need to tell more.)=C2=A0 We also provide "continuity" text to= serve as
a "glue" which is supposed to help the reader understand the topi= c
better and see each API in its context and relation to others.

Yes, the Emacs manual is good in that regard.
=

=C2=A0
"Manuals" that are just lists of APIs with minimum explana= tory text,
a-la JavaDoc, are _bad_ manuals.=C2=A0 They don't tell you enough about= the
topics for you to understand when use one class of APIs and when to
use another.=C2=A0 If you want to see a representative of such bad manuals,=
look at the GTK docs.=C2=A0 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?

Phil= ippe=C2=A0
--000000000000f257eb05a4acd5a4--