Re: [ELPA] New package: transient

[Eli Zaretskii]

> From: Philippe Vaucher <address@hidden>
> Date: Sat, 2 May 2020 11:53:07 +0200
> Cc: Richard Stallman <address@hidden>, address@hidden, Emacs developers 
> <address@hidden>
> 
> 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.

I fail to see how will the above list be useful, if you know nothing
about the function's name.  E.g., a newbie that has no previous Lisp
baggage will never be able to guess that assq should have anything to
do with association lists.  They will need the text keep-lines removes.

So maybe you should make your argument more concrete by saying what
you did know in this case.  My proposal to use Info-index was based on
the assumption that you knew nothing except that the function was
about alists.  In another message you said that you actually knew the
function will include "copy" and "alist" somewhere in its name, so I
suggested a different command that is better for that use case.

IOW, for each use case there's the best tool, and there are others
which are good, but not the best.  For example, even if you did go to
the above manual section, why would you need to generate the list of
functions?  "C-s copy" finds copy-alist as the first hit.  So even
being presented with a relatively long (290 lines) section in the
manual, finding what you want in that section is a matter of seconds.
I fail to see the problem.

> 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.

I cannot put myself in your shoes unless you describe the situation
more completely.  Specifically, what _did_ you know about string-match
and match-string, and which topics relevant to these would be in your
opinion relevant for looking up those functions?  Then we could
continue having a useful discussion, one where the results are that we
improve Emacs, including in ways other than those you thought about.

E.g., based on what _I_ have in mind in the above situation, I'd first
try "i regexp TAB" in the ELisp manual, see nothing pertinent, then
try "match TAB", and voila! I see match-data and match-string.

>  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.

No need to read the entire section, just use C-s to search for what
you want.

> 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.

You don't know me very well, do you?  Try "C-h d alist" in a recent
development snapshot, and I think you will see those functions there.
I fixed that within 5 minutes of your saying that those functions
couldn't be found by "C-h d".

> 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.

That depends on what you know about the function; see my earlier
response about "C-h a" and in particular about finding a function
about which you know that its name should include "copy" and "alist".

> 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"?

I think by now you should already know the answer.  I have the ELisp
manual open in a dedicated frame at all times, and I consult it all
the time.  I use "C-h f" only if I think I know the function's name
quite accurately, and the same with "C-h v" and variables.