Re: Imports / inclusion of s.el into Emacs

[Eli Zaretskii]

> From: Philippe Vaucher <address@hidden>
> Date: Sat, 2 May 2020 18:31:27 +0200
> Cc: João Távora <address@hidden>, 
>       Emacs developers <address@hidden>, Stefan Monnier <address@hidden>, 
>       Richard Stallman <address@hidden>, Dmitry Gutov <address@hidden>
> 
>  > 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.