bug#41021: [PATCH] New command apropos-function

bug#41021: [PATCH] New command apropos-function

[Stefan Kangas]

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

bug#41021: [PATCH] New command apropos-function

[Eli Zaretskii]

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

bug#41021: [PATCH] New command apropos-function

[Stefan Kangas]

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

bug#41021: [PATCH] New command apropos-function

[Eli Zaretskii]

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

bug#41021: [PATCH] New command apropos-function

[Dmitry Gutov]

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.

bug#41021: [PATCH] New command apropos-function

[Drew Adams]

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

bug#41021: [PATCH] New command apropos-function

[Richard Stallman]

[[[ 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)

bug#41021: [PATCH] New command apropos-function

[Richard Stallman]

[[[ 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)

bug#41021: [PATCH] New command apropos-function

[Eli Zaretskii]

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

bug#41021: [PATCH] New command apropos-function

[Drew Adams]

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

bug#41021: [PATCH] New command apropos-function

[Richard Stallman]

[[[ 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)

bug#41021: [PATCH] New command apropos-function

[Lars Ingebrigtsen]

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

bug#41021: [PATCH] New command apropos-function

[Stefan Kangas]

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

bug#41021: [PATCH] New command apropos-function

[Lars Ingebrigtsen]

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

bug#41021: [PATCH] New command apropos-function

[Lars Ingebrigtsen]

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

bug#41021: [PATCH] New command apropos-function

[Stefan Kangas]

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