> It doesn't fail, but there are evidently users who want to have that
> information without using the documentation features of Emacs, so any
> solution based on C-h is not acceptable to them.
>
> While there might be some users who think that way, my workflow is mainly to use `C-h f` to find the help of
> the function I'm interested in. This is where not properly namespaced libraries are hurting me.
>
> `C-h d` or `apropos` is plan B, and then I have to filter what is relevant and not, and also because the result
> set of `C-h d` is so big scrolling inside my Emacs becomes sluggish, which is not pleasant. So usually a this
> point I go online and search, and fall on Xah-Lee's page, EmacsWiki, or stackoverflow.
If I may: your strategy is sub-optimal. When looking for a function
whose name you don't know, the first place to look is in the ELisp
manual. Thus, for finding functions that deal with alists, the first
thing to try is "i alist RET" in the ELisp manual. Here "alist" is
not a part of a function's name, it's a topic which you are looking
for. That is much more efficient than the sequence you described
above, because we take special care of having meaningful topics in the
indices of the manual, precisely to help in such situations. (And my
advice is to always have the ELisp manual shown in some frame on your
display, so that you don't even need to type "C-h i" etc. to get to
it.)
Let's try again why this is not an optimal strategy for me:
Searching the manual lands me on
https://www.gnu.org/software/emacs/manual/html_node/elisp/Association-Lists.html. This is all good, but most of the time I don't need all this introduction, I just really need a curated list of the function names related to the topic I'm searching. When learning this page is really useful but when trying to quickly find what function you need, this page is 95% noise. What happens is that I'll look at each "-- function" part and enter a loop of "not that, skip paragraph" until I find the function I want.
If I take that entry manual and then toggle read only and then "M-x keep-lines -- function" I end up with:
-- Function: assoc key alist &optional testfn
-- Function: rassoc value alist
-- Function: assq key alist
-- Function: alist-get key alist &optional default remove testfn
-- Function: rassq value alist
-- Function: assoc-default key alist &optional test default
-- Function: copy-alist alist
-- Function: assq-delete-all key alist
-- Function: assoc-delete-all key alist
-- Function: rassq-delete-all value alist
That's what I would like to get out of the manual easily. Note that if these were properly namespaced I'd just use "C-h f alist" and be done with it. But keep in mind "alist" is a poor example, regexp are a much better example I think. Let me illustrate.
Over 95% of my documentation search is just that (quickly looking at a list of functions). I'm fluent in many languages already, I don't need a regexp (or whatever) introduction with detailed explanations. I just want to find how to do a regexp match and extract the results. When I fall on
https://www.gnu.org/software/emacs/manual/html_node/elisp/Regexp-Search.html it takes way too much reading to find `string-match`, and this page doesn't even mention `match-string`! That means I have to do another search and find
https://www.gnu.org/software/emacs/manual/html_node/elisp/Simple-Match-Data.html. I'm sure that if you put yourself in my shoes you'd be able to understand my frustration.
In the other languages I use (C++, Ruby) I never have that frustration. It looks like that in Clojure or Scheme I'd be happy too. Maybe it's just me and I have a problem with Emacs Lisp, but from looking at the s.el, f.el and dash.el community I believe we are a significant minority.
But at this point I'm completely confused about your central argument,
because my original mentioning of "C-h d" was regarded as missing the
point, and you objected to the very idea of searching the
documentation. Quote:
> I think "C-h d alist RET" is your friend.
>
> You miss the central point of my argument. 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.
>
> It is much easier for the mind to think in terms of namespaces, here are examples from other languages:
So now I'm no confused because my conclusion from the above was that
you don't want to use the documentation features, but you now
evidently disagreed with that conclusion. Sorry.
What I said here is that I have to find that manual entry and read 300 lines of text when I could have had a list of 10 lines to start with. The manual has the information I want, just way too verbose.
Also remember that you were talking about "C-h d alist", I think you missed my further explanations of that point, allow me quote myself again:
On Wed, Apr 29, 2020 at 3:19 PM Philippe Vaucher <
address@hidden> wrote:
>>
>> I think "C-h d alist RET" is your friend.
>
> To further illustrate my point, this doesn't lists `assq` or `assoc`, both functions being indispensable when using alists.
My point is that "C-h d alist" is not sufficient to find assq or assoc, thus while a useful tool it's not very efficient. There's also a lot of noise on that listing when searching something as generic as "alist". I simply want a mechanism where I'm close to 100% certain that I have the whole list of functions related to a topic.
Maybe I'm asking for too much, or maybe my way of functionning is "wrong" in the Emacs Lisp world. I'm curious, please tell me more about how you function, maybe Emacs Lisp is your most used language so you know it all by heart? How often do you popup the manual, and how often do you use "C-h f"?
Kind regards,
Philippe