> 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