Re: [ELPA] New package: transient

[Philippe Vaucher <philippe.vaucher@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 5878 bytes --]

>
> >  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 <philippe.vaucher@gmail.com>
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

[-- Attachment #2: Type: text/html, Size: 7356 bytes --]