Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Philippe Vaucher <address@hidden>
> Date: Wed, 29 Apr 2020 15:12:50 +0200
> Cc: Jonas Bernoulli <address@hidden>, Emacs developers <address@hidden>, 
>       Adam Porter <address@hidden>, Kyle Meyer <address@hidden>, 
>       Stefan Monnier <address@hidden>
> 
>  > * 
> https://www.gnu.org/software/emacs/manual/html_node/elisp/Association-Lists.html
>  sometimes
>  assoc,
>  >  alist-get, assq, copy-alist. How am I supposed to use `C-h f alist TAB` 
> to discover the function I
>  want? I
>  >  can't, I have to go to that webpage and read it all.
> 
>  I think "C-h d alist RET" is your friend.
> 
> You miss the central point of my argument.

I'm sorry to have missed that, but all I had was what you wrote:

  How am I supposed to use `C-h f alist TAB` to discover the function
  I want?

>From that I assumed that I could use the fact that "alist" is part of
what you did know.  How could I have guessed this wasn't what you
meant?

> The problem is not that the doc is hard to find, it's that I *have* to
> find it to know which are the related functions.

If "alist" is not a keyword that could be used in this case, then what
is? "associaion list"? something else?  When one tries to discover
functionality, one must start with something, we cannot start with
nothing, can we?

> It is much easier for the mind to think in terms of namespaces, here are 
> examples from other languages:
> 
> * https://clojure.github.io/clojure/clojure.string-api.html all string 
> functions stored under string
> * http://www.cplusplus.com/reference/cstring/ almost all string manipulation 
> function start with "str"
> * https://ruby-doc.org/stdlib-2.4.1/libdoc/fileutils/rdoc/FileUtils.html all 
> file manipulation function are stored in
>  FileUtils::
> 
> I could go on but I think you should be able to understand my examples.

I understand the examples, I just don't think you can expect the world
to be so simple.  <cstring> in C++ has just 20 functions, and if you
need to work with multibyte strings, you won't find them there, they
are in <cwchar>, which doesn't even have "string" in its name.

Let's take a simple example: shell-command-to-string.  To which
"namespace" it should belong, in your opinion?  It is relevant to
"shell", "commands", "programs", and "strings".

And then there's the problem of having too many APIs in the same
namespace, if it indeed includes everything relevant.

> * autocompletion can help you guess the right function.
> * searching for function names (C-h f) can help you find the right function.

YMMV, but when completion shows me more than 2 dozen candidates, I'm
infinitely annoyed, and usually give up in despair much earlier that I
read the entire list.

No single trick is perfect, so my conclusion is that we need all of
them to discover what we want quickly and efficiently.  I mention
"C-h d" because people tend to forget about it.