GNU bug report logs - #41021
[PATCH] New command apropos-function

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 41021 in the body.
You can then email your comments to 41021 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] New command apropos-function
Date: Sat, 2 May 2020 12:40:06 +0200

[Message part 1 (text/plain, inline)]

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

[Message part 2 (text/html, inline)]

[0001-lisp-apropos.el-apropos-function-New-command.patch (text/x-patch, attachment)]

Message #8 received at 41021 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 41021 <at> debbugs.gnu.org
Subject: Re: bug#41021: [PATCH] New command apropos-function
Date: Sat, 02 May 2020 14:02:16 +0300

> From: Stefan Kangas <stefan <at> 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.

Message #11 received at 41021 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 41021 <at> debbugs.gnu.org
Subject: Re: bug#41021: [PATCH] New command apropos-function
Date: Sat, 02 May 2020 13:35:46 +0200

Eli Zaretskii <eliz <at> 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

Message #14 received at 41021 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 41021 <at> debbugs.gnu.org
Subject: Re: bug#41021: [PATCH] New command apropos-function
Date: Sat, 02 May 2020 14:52:59 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Cc: 41021 <at> 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.

Message #17 received at 41021 <at> debbugs.gnu.org (full text, mbox):

From: Dmitry Gutov <dgutov <at> yandex.ru>
To: Stefan Kangas <stefan <at> marxist.se>, 41021 <at> debbugs.gnu.org
Subject: Re: bug#41021: [PATCH] New command apropos-function
Date: Sat, 2 May 2020 16:37:17 +0300

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.

Message #20 received at 41021 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>, 41021 <at> debbugs.gnu.org
Subject: RE: bug#41021: [PATCH] New command apropos-function
Date: Sat, 2 May 2020 13:18:16 -0700 (PDT)

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

Message #23 received at 41021 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: eliz <at> gnu.org, 41021 <at> debbugs.gnu.org
Subject: Re: bug#41021: [PATCH] New command apropos-function
Date: Sat, 02 May 2020 23:44:23 -0400

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

Message #26 received at 41021 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 41021 <at> debbugs.gnu.org
Subject: Re: bug#41021: [PATCH] New command apropos-function
Date: Sat, 02 May 2020 23:44:41 -0400

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

Message #29 received at 41021 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 41021 <at> debbugs.gnu.org, stefan <at> marxist.se
Subject: Re: bug#41021: [PATCH] New command apropos-function
Date: Sun, 03 May 2020 17:19:17 +0300

> Date: Sat, 2 May 2020 13:18:16 -0700 (PDT)
> From: Drew Adams <drew.adams <at> 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"?

Message #32 received at 41021 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 41021 <at> debbugs.gnu.org, stefan <at> marxist.se
Subject: RE: bug#41021: [PATCH] New command apropos-function
Date: Sun, 3 May 2020 13:13:59 -0700 (PDT)

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

Message #35 received at 41021 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 41021 <at> debbugs.gnu.org, stefan <at> marxist.se, drew.adams <at> oracle.com
Subject: Re: bug#41021: [PATCH] New command apropos-function
Date: Sun, 03 May 2020 23:09:55 -0400

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

Message #38 received at 41021 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 41021 <at> debbugs.gnu.org
Subject: Re: bug#41021: [PATCH] New command apropos-function
Date: Sat, 08 Aug 2020 14:04:46 +0200

Stefan Kangas <stefan <at> 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

Message #41 received at 41021 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 41021 <at> debbugs.gnu.org
Subject: Re: bug#41021: [PATCH] New command apropos-function
Date: Mon, 10 Aug 2020 06:06:14 -0700

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> Stefan Kangas <stefan <at> 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

Message #44 received at 41021 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 41021 <at> debbugs.gnu.org
Subject: Re: bug#41021: [PATCH] New command apropos-function
Date: Mon, 10 Aug 2020 15:22:18 +0200

Stefan Kangas <stefan <at> 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

Message #47 received at 41021 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 41021 <at> debbugs.gnu.org
Subject: Re: bug#41021: [PATCH] New command apropos-function
Date: Mon, 10 Aug 2020 15:25:09 +0200

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> Stefan Kangas <stefan <at> 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

Message #50 received at 41021 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 41021 <at> debbugs.gnu.org
Subject: Re: bug#41021: [PATCH] New command apropos-function
Date: Mon, 10 Aug 2020 06:37:28 -0700

close 41021 28.1
thanks

Lars Ingebrigtsen <larsi <at> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.