all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* bug#41021: [PATCH] New command apropos-function
@ 2020-05-02 10:40 Stefan Kangas
  2020-05-02 11:02 ` Eli Zaretskii
                   ` (4 more replies)
  0 siblings, 5 replies; 16+ messages in thread
From: Stefan Kangas @ 2020-05-02 10:40 UTC (permalink / raw)
  To: 41021


[-- Attachment #1.1: Type: text/plain, Size: 666 bytes --]

Severity: wishlist

I've often found myself reaching for 'apropos-function' command, and found
it strange that it was missing.  This typically would happen by saying M-x
apropos- TAB.  So now I got frustrated again and I decided to bite the
bullet and implement it.

Of course, I quickly realized that I had actually been looking for 'C-u M-x
apropos-command' all along.  But for some reason I never thought to read
the docstring of 'apropos-command'.  (Or maybe I read it at some point but
forgot about it.)

I think a new command would help make this feature more discoverable,
especially to beginners.  Please see the attached patch.

Best regards,
Stefan Kangas

[-- Attachment #1.2: Type: text/html, Size: 865 bytes --]

[-- Attachment #2: 0001-lisp-apropos.el-apropos-function-New-command.patch --]
[-- Type: text/x-patch, Size: 1303 bytes --]

From 89626dd8ba424dedca6862af2b96da1f6a30f827 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Sat, 2 May 2020 12:29:13 +0200
Subject: [PATCH] * lisp/apropos.el (apropos-function): New command.

---
 lisp/apropos.el | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/lisp/apropos.el b/lisp/apropos.el
index e40f94ccb8..1003de8aab 100644
--- a/lisp/apropos.el
+++ b/lisp/apropos.el
@@ -534,6 +534,20 @@ apropos-local-variable
                                  (and (local-variable-if-set-p symbol)
                                       (get symbol 'variable-documentation)))))
 
+;;;###autoload
+(defun apropos-function (pattern)
+  "Show functions that match PATTERN.
+
+PATTERN can be a word, a list of words (separated by spaces),
+or a regexp (using some regexp special characters).  If it is a word,
+search for matches for that word as a substring.  If it is a list of words,
+search for matches for any two (or more) of those words.
+
+This is the same as running `apropos-command' with a \\[universal-argument] prefix,
+or a non-nil `apropos-do-all' argument."
+  (interactive (list (apropos-read-pattern "function")))
+  (apropos-command pattern t))
+
 ;; For auld lang syne:
 ;;;###autoload
 (defalias 'command-apropos 'apropos-command)
-- 
2.26.2


^ permalink raw reply related	[flat|nested] 16+ messages in thread

* bug#41021: [PATCH] New command apropos-function
  2020-05-02 10:40 bug#41021: [PATCH] New command apropos-function Stefan Kangas
@ 2020-05-02 11:02 ` Eli Zaretskii
  2020-05-02 11:35   ` Stefan Kangas
  2020-05-02 13:37 ` Dmitry Gutov
                   ` (3 subsequent siblings)
  4 siblings, 1 reply; 16+ messages in thread
From: Eli Zaretskii @ 2020-05-02 11:02 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: 41021

> From: Stefan Kangas <stefan@marxist.se>
> Date: Sat, 2 May 2020 12:40:06 +0200
> 
> I've often found myself reaching for 'apropos-function' command, and found it strange that it was missing. 
> This typically would happen by saying M-x apropos- TAB.  So now I got frustrated again and I decided to bite
> the bullet and implement it.
> 
> Of course, I quickly realized that I had actually been looking for 'C-u M-x apropos-command' all along.  But
> for some reason I never thought to read the docstring of 'apropos-command'.  (Or maybe I read it at some
> point but forgot about it.)

OK, but now that you have read it, why do we still need an additional
command?

If you type "M-x apropos TAB", how many commands you see there
already?  Is it a good idea to add one more, when we already have the
same functionality?

> I think a new command would help make this feature more discoverable, especially to beginners.

We are being told many beginners don't even want to use the apropos commands.

My vote is against adding this, FWIW.





^ permalink raw reply	[flat|nested] 16+ messages in thread

* bug#41021: [PATCH] New command apropos-function
  2020-05-02 11:02 ` Eli Zaretskii
@ 2020-05-02 11:35   ` Stefan Kangas
  2020-05-02 11:52     ` Eli Zaretskii
  2020-05-03  3:44     ` Richard Stallman
  0 siblings, 2 replies; 16+ messages in thread
From: Stefan Kangas @ 2020-05-02 11:35 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: 41021

Eli Zaretskii <eliz@gnu.org> writes:

> OK, but now that you have read it, why do we still need an additional
> command?

This is not about me personally.  I related my experience only as a
description of a likely use-case.

> If you type "M-x apropos TAB", how many commands you see there
> already?

If I count correctly, I see 13 commands:

- apropos
- apropos-command
- apropos-documentation
- apropos-follow
- apropos-library
- apropos-local-value
- apropos-local-variable
- apropos-mode
- apropos-next-symbol
- apropos-previous-symbol
- apropos-user-option
- apropos-value
- apropos-variable

From looking at that list, I have concluded in the past that there is
no way to search for functions, but only interactive commands.  This
is not a bad first approximation, I think, based on seeing the list of
completions.  Only upon reading the docstring of 'apropos-command'
will you understand that this conclusion was wrong.

But why would you even look there?  The nature of these functions is
to _narrow_ the search in comparison to straight 'apropos'.  It is not
natural to expect that there might be a prefix argument you could use
to _widen_ it again.

In effect I have to say "display only those functions that *are*
commands, only in this case I want to include also all functions that
*are not* commands".

> Is it a good idea to add one more, when we already have the same
> functionality?

Yes, I don't see why not.  We have precedent.

>> I think a new command would help make this feature more
>> discoverable, especially to beginners.
>
> We are being told many beginners don't even want to use the apropos commands.

I would disagree with that statement; on the contrary, apropos is an
important tool /particularly/ to beginners.  I'm sure you agree.

Best regards,
Stefan Kangas





^ permalink raw reply	[flat|nested] 16+ messages in thread

* bug#41021: [PATCH] New command apropos-function
  2020-05-02 11:35   ` Stefan Kangas
@ 2020-05-02 11:52     ` Eli Zaretskii
  2020-05-03  3:44     ` Richard Stallman
  1 sibling, 0 replies; 16+ messages in thread
From: Eli Zaretskii @ 2020-05-02 11:52 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: 41021

> From: Stefan Kangas <stefan@marxist.se>
> Cc: 41021@debbugs.gnu.org
> Date: Sat, 02 May 2020 13:35:46 +0200
> 
> >> I think a new command would help make this feature more
> >> discoverable, especially to beginners.
> >
> > We are being told many beginners don't even want to use the apropos commands.
> 
> I would disagree with that statement; on the contrary, apropos is an
> important tool /particularly/ to beginners.  I'm sure you agree.

I agree, but I also think that beginners are first looking for
commands, not for functions.  It's use more experienced users who
start writing Lisp programs that need to look up functions that are
not commands.

Anyway, I will let other speak their minds.





^ permalink raw reply	[flat|nested] 16+ messages in thread

* bug#41021: [PATCH] New command apropos-function
  2020-05-02 10:40 bug#41021: [PATCH] New command apropos-function Stefan Kangas
  2020-05-02 11:02 ` Eli Zaretskii
@ 2020-05-02 13:37 ` Dmitry Gutov
  2020-05-02 20:18 ` Drew Adams
                   ` (2 subsequent siblings)
  4 siblings, 0 replies; 16+ messages in thread
From: Dmitry Gutov @ 2020-05-02 13:37 UTC (permalink / raw)
  To: Stefan Kangas, 41021

On 02.05.2020 13:40, Stefan Kangas wrote:
> I think a new command would help make this feature more discoverable, 
> especially to beginners.  Please see the attached patch.

Beginners or not, I think it's a good change.





^ permalink raw reply	[flat|nested] 16+ messages in thread

* bug#41021: [PATCH] New command apropos-function
  2020-05-02 10:40 bug#41021: [PATCH] New command apropos-function Stefan Kangas
  2020-05-02 11:02 ` Eli Zaretskii
  2020-05-02 13:37 ` Dmitry Gutov
@ 2020-05-02 20:18 ` Drew Adams
  2020-05-03 14:19   ` Eli Zaretskii
  2020-05-03  3:44 ` Richard Stallman
  2020-08-08 12:04 ` Lars Ingebrigtsen
  4 siblings, 1 reply; 16+ messages in thread
From: Drew Adams @ 2020-05-02 20:18 UTC (permalink / raw)
  To: Stefan Kangas, 41021

FWIW, this has been in my library `apropos-fn+var.el' since 2005.

The file header includes this:

;;  Acknowledgment: Slightly different versions of `apropos-function'
;;  and `apropos-variable' were posted by Kevin Rodgers to
;;  bug-gnu-emacs, Tue, 06 Sep 2005 14:34:54 -0600.  Kevin didn't
;;  actually redefine `apropos-variable' (he would never do that ;-)),
;;  but he provided the new definition.  I redefined `apropos-print'
;;  (and added button type `apropos-user-option' for Emacs < 24.4).

This is my `apropos-function':

(defun apropos-function (pattern)
  "Show functions that match PATTERN.
This includes functions that are not commands.
PATTERN can be a word, a list of words (separated by spaces),
or a regexp (using some regexp special characters).  If it is a word,
search for matches for that word as a substring.  If it is a list of words,
search for matches for any two (or more) of those words.

When called from a Lisp program, a string PATTERN is used as a regexp,
while a list of strings is used as a word list."
  (interactive "i")
  (if (interactive-p)
      (let ((apropos-do-all t))
        (call-interactively 'apropos-command))
    (apropos-command pattern t)))

https://www.emacswiki.org/emacs/download/apropos-fn%2bvar.el





^ permalink raw reply	[flat|nested] 16+ messages in thread

* bug#41021: [PATCH] New command apropos-function
  2020-05-02 11:35   ` Stefan Kangas
  2020-05-02 11:52     ` Eli Zaretskii
@ 2020-05-03  3:44     ` Richard Stallman
  1 sibling, 0 replies; 16+ messages in thread
From: Richard Stallman @ 2020-05-03  3:44 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: 41021

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > >From looking at that list, I have concluded in the past that there is
  > no way to search for functions, but only interactive commands.  This
  > is not a bad first approximation, I think, based on seeing the list of
  > completions.  Only upon reading the docstring of 'apropos-command'
  > will you understand that this conclusion was wrong.

If defining apropos-function would help some people get started on
Lisp programming, I think that is well worth defining one new command.


-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)







^ permalink raw reply	[flat|nested] 16+ messages in thread

* bug#41021: [PATCH] New command apropos-function
  2020-05-02 10:40 bug#41021: [PATCH] New command apropos-function Stefan Kangas
                   ` (2 preceding siblings ...)
  2020-05-02 20:18 ` Drew Adams
@ 2020-05-03  3:44 ` Richard Stallman
  2020-08-08 12:04 ` Lars Ingebrigtsen
  4 siblings, 0 replies; 16+ messages in thread
From: Richard Stallman @ 2020-05-03  3:44 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: 41021

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Of course, I quickly realized that I had actually been looking for 'C-u M-x
  > apropos-command' all along.  But for some reason I never thought to read
  > the docstring of 'apropos-command'.  (Or maybe I read it at some point but
  > forgot about it.)

  > I think a new command would help make this feature more discoverable,
  > especially to beginners.  Please see the attached patch.

From what we've recently learned, this is a good idea.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)







^ permalink raw reply	[flat|nested] 16+ messages in thread

* bug#41021: [PATCH] New command apropos-function
  2020-05-02 20:18 ` Drew Adams
@ 2020-05-03 14:19   ` Eli Zaretskii
  2020-05-04  3:09     ` Richard Stallman
  0 siblings, 1 reply; 16+ messages in thread
From: Eli Zaretskii @ 2020-05-03 14:19 UTC (permalink / raw)
  To: Drew Adams; +Cc: 41021, stefan

> Date: Sat, 2 May 2020 13:18:16 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> This is my `apropos-function':
> 
> (defun apropos-function (pattern)
>   "Show functions that match PATTERN.
> This includes functions that are not commands.
> PATTERN can be a word, a list of words (separated by spaces),
> or a regexp (using some regexp special characters).  If it is a word,
> search for matches for that word as a substring.  If it is a list of words,
> search for matches for any two (or more) of those words.
> 
> When called from a Lisp program, a string PATTERN is used as a regexp,
> while a list of strings is used as a word list."
>   (interactive "i")
>   (if (interactive-p)
>       (let ((apropos-do-all t))
>         (call-interactively 'apropos-command))
>     (apropos-command pattern t)))

Is this to save the user typing C-u before invoking "C-h a"?





^ permalink raw reply	[flat|nested] 16+ messages in thread

* bug#41021: [PATCH] New command apropos-function
       [not found]   ` <<834ksxqexm.fsf@gnu.org>
@ 2020-05-03 20:13     ` Drew Adams
  0 siblings, 0 replies; 16+ messages in thread
From: Drew Adams @ 2020-05-03 20:13 UTC (permalink / raw)
  To: Eli Zaretskii, Drew Adams; +Cc: 41021, stefan

> Is this to save the user typing C-u before invoking "C-h a"?

Yes.  That was the request by OP, AFAIK.

The Commentary of `apropos-fn+var.el' says this:

;;  Standard `apropos' commands `apropos-variable' and
;;  `apropos-command' do not distinguish, by command name,
;;  between the different types of target object (but you
;;  can do that via `C-u').  This library provides
;;  individual `apropos' commands for user options,
;;  variables in general (not just options), and functions
;;  in general (not just commands).





^ permalink raw reply	[flat|nested] 16+ messages in thread

* bug#41021: [PATCH] New command apropos-function
  2020-05-03 14:19   ` Eli Zaretskii
@ 2020-05-04  3:09     ` Richard Stallman
  0 siblings, 0 replies; 16+ messages in thread
From: Richard Stallman @ 2020-05-04  3:09 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: 41021, stefan

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > This is my `apropos-function':
  > > 
  > > (defun apropos-function (pattern)
  > >   "Show functions that match PATTERN.

  > Is this to save the user typing C-u before invoking "C-h a"?

I think the reason to add that function is so that it appears
in the completion list after M-x apropos TAB TAB.


-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)







^ permalink raw reply	[flat|nested] 16+ messages in thread

* bug#41021: [PATCH] New command apropos-function
  2020-05-02 10:40 bug#41021: [PATCH] New command apropos-function Stefan Kangas
                   ` (3 preceding siblings ...)
  2020-05-03  3:44 ` Richard Stallman
@ 2020-08-08 12:04 ` Lars Ingebrigtsen
  2020-08-10 13:06   ` Stefan Kangas
  4 siblings, 1 reply; 16+ messages in thread
From: Lars Ingebrigtsen @ 2020-08-08 12:04 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: 41021

Stefan Kangas <stefan@marxist.se> writes:

> I've often found myself reaching for 'apropos-function' command, and
> found it strange that it was missing.  This typically would happen by
> saying M-x apropos- TAB.  So now I got frustrated again and I decided
> to bite the bullet and implement it.

[...]

> +;;;###autoload
> +(defun apropos-function (pattern)
> +  "Show functions that match PATTERN.
> +
> +PATTERN can be a word, a list of words (separated by spaces),

There was some disagreement whether this duplicates apropos-command
unnecessarily, but I think (as I think most of the people who commented)
that this seems useful -- it helps with discovery, which I think is a
good thing.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no





^ permalink raw reply	[flat|nested] 16+ messages in thread

* bug#41021: [PATCH] New command apropos-function
  2020-08-08 12:04 ` Lars Ingebrigtsen
@ 2020-08-10 13:06   ` Stefan Kangas
  2020-08-10 13:22     ` Lars Ingebrigtsen
  0 siblings, 1 reply; 16+ messages in thread
From: Stefan Kangas @ 2020-08-10 13:06 UTC (permalink / raw)
  To: Lars Ingebrigtsen; +Cc: 41021

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Stefan Kangas <stefan@marxist.se> writes:
>
>> I've often found myself reaching for 'apropos-function' command, and
>> found it strange that it was missing.  This typically would happen by
>> saying M-x apropos- TAB.  So now I got frustrated again and I decided
>> to bite the bullet and implement it.
>
> [...]
>
>> +;;;###autoload
>> +(defun apropos-function (pattern)
>> +  "Show functions that match PATTERN.
>> +
>> +PATTERN can be a word, a list of words (separated by spaces),
>
> There was some disagreement whether this duplicates apropos-command
> unnecessarily, but I think (as I think most of the people who commented)
> that this seems useful -- it helps with discovery, which I think is a
> good thing.

Should it be announced in NEWS?

Best regards,
Stefan Kangas





^ permalink raw reply	[flat|nested] 16+ messages in thread

* bug#41021: [PATCH] New command apropos-function
  2020-08-10 13:06   ` Stefan Kangas
@ 2020-08-10 13:22     ` Lars Ingebrigtsen
  2020-08-10 13:25       ` Lars Ingebrigtsen
  0 siblings, 1 reply; 16+ messages in thread
From: Lars Ingebrigtsen @ 2020-08-10 13:22 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: 41021

Stefan Kangas <stefan@marxist.se> writes:

>>> +;;;###autoload
>>> +(defun apropos-function (pattern)
>>> +  "Show functions that match PATTERN.
>>> +
>>> +PATTERN can be a word, a list of words (separated by spaces),
>>
>> There was some disagreement whether this duplicates apropos-command
>> unnecessarily, but I think (as I think most of the people who commented)
>> that this seems useful -- it helps with discovery, which I think is a
>> good thing.
>
> Should it be announced in NEWS?

Oh yeah, definitely.  I'll add that...

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no





^ permalink raw reply	[flat|nested] 16+ messages in thread

* bug#41021: [PATCH] New command apropos-function
  2020-08-10 13:22     ` Lars Ingebrigtsen
@ 2020-08-10 13:25       ` Lars Ingebrigtsen
  2020-08-10 13:37         ` Stefan Kangas
  0 siblings, 1 reply; 16+ messages in thread
From: Lars Ingebrigtsen @ 2020-08-10 13:25 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: 41021

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Stefan Kangas <stefan@marxist.se> writes:
>
>>>> +;;;###autoload
>>>> +(defun apropos-function (pattern)
>>>> +  "Show functions that match PATTERN.
>>>> +
>>>> +PATTERN can be a word, a list of words (separated by spaces),
>>>
>>> There was some disagreement whether this duplicates apropos-command
>>> unnecessarily, but I think (as I think most of the people who commented)
>>> that this seems useful -- it helps with discovery, which I think is a
>>> good thing.
>>
>> Should it be announced in NEWS?
>
> Oh yeah, definitely.  I'll add that...

Oops.  I thought that was a different patch that I had applied.  :-)

But, yes, it's definitely NEWS-worthy.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no





^ permalink raw reply	[flat|nested] 16+ messages in thread

* bug#41021: [PATCH] New command apropos-function
  2020-08-10 13:25       ` Lars Ingebrigtsen
@ 2020-08-10 13:37         ` Stefan Kangas
  0 siblings, 0 replies; 16+ messages in thread
From: Stefan Kangas @ 2020-08-10 13:37 UTC (permalink / raw)
  To: Lars Ingebrigtsen; +Cc: 41021

close 41021 28.1
thanks

Lars Ingebrigtsen <larsi@gnus.org> writes:

>> Oh yeah, definitely.  I'll add that...
>
> Oops.  I thought that was a different patch that I had applied.  :-)

:-)

> But, yes, it's definitely NEWS-worthy.

Thanks, I've added a news entry and pushed this as commit 170faae31b.

If anyone disagrees with the addition, please feel free to revert it.

Best regards,
Stefan Kangas





^ permalink raw reply	[flat|nested] 16+ messages in thread

end of thread, other threads:[~2020-08-10 13:37 UTC | newest]

Thread overview: 16+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-05-02 10:40 bug#41021: [PATCH] New command apropos-function Stefan Kangas
2020-05-02 11:02 ` Eli Zaretskii
2020-05-02 11:35   ` Stefan Kangas
2020-05-02 11:52     ` Eli Zaretskii
2020-05-03  3:44     ` Richard Stallman
2020-05-02 13:37 ` Dmitry Gutov
2020-05-02 20:18 ` Drew Adams
2020-05-03 14:19   ` Eli Zaretskii
2020-05-04  3:09     ` Richard Stallman
2020-05-03  3:44 ` Richard Stallman
2020-08-08 12:04 ` Lars Ingebrigtsen
2020-08-10 13:06   ` Stefan Kangas
2020-08-10 13:22     ` Lars Ingebrigtsen
2020-08-10 13:25       ` Lars Ingebrigtsen
2020-08-10 13:37         ` Stefan Kangas
     [not found] <<CADwFkmkQxhX+UvfHacDJVi3tuGuzjiv0Eb5p6ywEOKUu4zmg4w@mail.gmail.com>
     [not found] ` <<603ebaa3-3014-4f98-9e1b-a89eeebee6af@default>
     [not found]   ` <<834ksxqexm.fsf@gnu.org>
2020-05-03 20:13     ` Drew Adams

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.