Re: Imports / inclusion of s.el into Emacs

[Eli Zaretskii]

> From: 조성빈 <address@hidden>
> Date: Sun, 3 May 2020 03:01:03 +0900
> Cc: Philippe Vaucher <address@hidden>,
>  Dmitry Gutov <address@hidden>,
>  Richard Stallman <address@hidden>,
>  address@hidden,
>  address@hidden,
>  address@hidden
> 
> > It sounds very strange to me that the method of learning about strings
> > is by looking at the list of string-related APIs.
> 
> Unless one doesn’t have any programming experience, IMO one can learn
> (or refresh old memory) of how strings work from the API list.

I doubt that.

> > 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.
> 
> Does every Emacs user have to go through the long manual to write some  
> short functions?

Of course not.

The Emacs manuals are designed to support 2 general use cases:

  . reading on a subject (like strings) for the first time, i.e. using
    the manual as a textbook
  . finding quickly the details about some small topic, i.e. using the
    manual as a reference

In the first use case you are supposed to read the chapter, in the
second you are supposed to use index-search for that topic you have in
mind (the topic could also be the name of a function or a key
sequence).  That second use case would be the case of writing a short
function.

> > How can a single example of "typical usage" help you understand a
> > complex topic such as threads?
> 
> A single example is of course not for understanding the whole complex
> topic, but it serves as a reminder.

A reminder of a single example can only be useful if that example
happens to be what you want.  For a subject as broad as strings or
threads, this is unlikely to be the case.

The ELisp manual includes quite a few examples, each one where we want
to explain some topic by showing concrete code.

> > 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, that’s great when one doesn’t know about programming in general or
> how Emacs work. It’s not great when you forgot what string API Emacs
> provides, and trying to find out what operations exist, to write my
> custom interactive function in the cleanest way possible.

I invite you to read the chapter about strings and characters in the
ELisp manual, and also examine the index entries in that chapter.
Then we could talk specifics.  Otherwise I have no way of connecting
what you say with what is actually in the manual.

> > "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?
> 
> No, of course not. I’m pretty sure nobody wants a manual like that.
> Just that it would be better if there’s a good way to view all of
> the string operations that Emacs supports without text.

And I'm sure such a list will be almost useless.  Nevertheless, I'm
not opposed to having such a list somewhere.  I just don't think it's
an efficient way of finding information quickly and efficiently --
except if one already knows the name of the function.

But I already said that several times, so it's time to stop repeating
myself.

> I think a lot of people here are misunderstanding why this is a
> virtue -  understandable since most here are already Elisp masters,
> can guess make-string or split-string based on memory, write out
> code without searching.

You are mistaken: I'm not such a master.  Like Stefan, I can never
remember whether its string-multibyte-p or multibyte-string-p.  I use
the manual and the doc strings all the time because I don't remember
all those details.  So what I wrote is based on personal experience of
looking up and finding this information quickly and efficiently.