apropos for packages [was: plz -> curl?]

apropos for packages [was: plz -> curl?]

[Drew Adams]

> Is there an apropos-package command?
> If not, maybe now is the time to write one.

Good question.

1. There is `describe-package', `C-h P'.

2. It would be good to update `apropos-documentation',
   if this has not already been done, to include the
   doc of packages.

Re: apropos for packages [was: plz -> curl?]

[Eduardo Ochs]

On Tue, 17 May 2022 at 12:20, Drew Adams <drew.adams@oracle.com> wrote:
>
> > Is there an apropos-package command?
> > If not, maybe now is the time to write one.
>
> Good question.
>
> 1. There is `describe-package', `C-h P'.
>
> 2. It would be good to update `apropos-documentation',
>    if this has not already been done, to include the
>    doc of packages.

This looks like a good starting point to me... but find-eppp is
an eev-ism - `(find-eppp o)' displays a pretty-printed version of
o in a temporary buffer. What would normal people use instead of
the `find-eppp' here?

  (find-eppp

   (mapcar
    (lambda (p)
      (list (package-desc-name (cadr p))
            (package-desc-summary (cadr p))))
    package-archive-contents)

   )

Cheers,
  Eduardo Ochs
  http://angg.twu.net/#eev

RE: apropos for packages [was: plz -> curl?]

[Drew Adams]

I wrote:

> 2. It would be good to update `apropos-documentation',
>    if this has not already been done, to include the
     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>    doc of packages.

It seems that, at least as recently as Emacs 27.2,
this has not been done, in spite of the doc of
`apropos-documentation' saying this:

  With C-u prefix, or if ‘apropos-do-all’ is non-nil,
  it searches all currently defined documentation
  strings.

For example, `C-u C-h d backtrace' doesn't show an
entry for package `backtrace', even though the pkg
doc string mentions "backtrace".  (Emacs 27.2)

If this has still not been fixed in Emacs 28, do we
need a bug filed for this, or can it just please be
fixed without a bug?

Re: apropos for packages [was: plz -> curl?]

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> CC: Lars Ingebrigtsen <larsi@gnus.org>, Richard Stallman <rms@gnu.org>, Philip
>  Kaludercic <philipk@posteo.net>, "mardani29@yahoo.es" <mardani29@yahoo.es>,
>  emacs-devel <emacs-devel@gnu.org>
> Date: Tue, 17 May 2022 16:23:20 +0000
> 
> I wrote:
> 
> > 2. It would be good to update `apropos-documentation',
> >    if this has not already been done, to include the
>      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> >    doc of packages.
> 
> It seems that, at least as recently as Emacs 27.2,
> this has not been done, in spite of the doc of
> `apropos-documentation' saying this:
> 
>   With C-u prefix, or if ‘apropos-do-all’ is non-nil,
>   it searches all currently defined documentation
>   strings.
> 
> For example, `C-u C-h d backtrace' doesn't show an
> entry for package `backtrace', even though the pkg
> doc string mentions "backtrace".  (Emacs 27.2)

You are taking that text out of its context.  The doc string _really_
says this:

  Show symbols whose documentation contains matches for PATTERN.

And now we understand why you don't see the package backtrace.el: it's
because it is not a symbol.

> If this has still not been fixed in Emacs 28, do we
> need a bug filed for this, or can it just please be
> fixed without a bug?

I don't think it would make sense to add packages to
apropos-documentation.  That command is supposed to search doc strings
of symbols: variables, functions, faces, etc.  Adding packages to that
would cause the results to show completely unrelated stuff.

So I'm against this.  Packages should have (and already do have)
specialized commands that search their descriptions, keywords, etc.

RE: [External] : Re: apropos for packages [was: plz -> curl?]

[Drew Adams]

> > > 2. It would be good to update `apropos-documentation',
> > >    if this has not already been done, to include the
> > >    doc of packages.
> >
> > It seems that, at least as recently as Emacs 27.2,
> > this has not been done, in spite of the doc of
> > `apropos-documentation' saying this:
> >
> >   With C-u prefix, or if ‘apropos-do-all’ is non-nil,
> >   it searches all currently defined documentation
> >   strings.
> >
> > For example, `C-u C-h d backtrace' doesn't show an
> > entry for package `backtrace', even though the pkg
> > doc string mentions "backtrace".  (Emacs 27.2)
> 
> You are taking that text out of its context.  The doc
> string _really_ says this:
> 
>   Show symbols whose documentation contains matches for PATTERN.

It also _really_ says what I wrote.  I'm not making
anything up, so please don't insinuate that.

Yes, I recognize that the doc in question is that
provided by `describe-package' - it's not technically
a doc string for the package.

> And now we understand why you don't see the package 
> backtrace.el: it's because it is not a symbol.

If you want to quibble, fine.

`C-h P back TAB' completes to `backtrace', _not_ to
`backtrace.el'.  The name of the package is presumably
`backtrace', not `backtrace.el'.

And lo & behold - what does `C-h k C-h P' tell us?

  C-h P runs the command describe-package (found in global-map),
  which is an autoloaded interactive compiled Lisp function in
  ‘package.el’.

  It is bound to C-h P, <f1> P, <help> P, <menu-bar> <help-menu>
  <describe> <describe-package>.

  (describe-package PACKAGE)

    Probably introduced at or before Emacs version 24.1.

  Display the full documentation of PACKAGE (a symbol).
                                             ^^^^^^^^

IOW, at least `describe-package' (the function
that shows the doc for a package - a symbol; the
function that's analogous to `describe-function'
for functions, `describe-variable' for variables,
and `describe-face' for faces) accepts symbols
for packages.

`describe-package' gets its list of packages
(symbols) from here:

 (append (mapcar 'car package-alist)
         (mapcar 'car package-archive-contents)
         (mapcar 'car package--builtins))

And then it gets the description (doc) of each
such package (symbol) like this:

 (and (or (package-desc-p package)
          (and package (symbolp package)))
      (or (and (package-desc-p pkg) pkg)
          (cadr (assq pkg package-alist))
          (let ((built-in  (assq pkg package--builtins)))
            (if built-in
                (package--from-builtin built-in)
              (cadr (assq pkg package-archive-contents)))))

Sure looks like Emacs intends symbol `backtrace' to
be documented as a package.  Sure looks like Emacs
thinks the package name is `backtrace', and not
`backtrace.el', at least for purposes of
`describe-package'.

Whether `apropos-documentation' should include the doc
of packages is a judgment call.  I have my opinion.
But your opinion is of course the one that counts.

> > If this has still not been fixed in Emacs 28, do we
> > need a bug filed for this, or can it just please be
> > fixed without a bug?
> 
> I don't think it would make sense to add packages to
> apropos-documentation.  That command is supposed to 
> search doc strings of symbols: variables, functions,
> faces, etc.

See above, about whether a package symbol such as
`backtrace' counts.

But regardless of whether you think package symbols
count as symbols here, I think the question of
whether `apropos-documentation' should cover packages
shouldn't necessarily be limited to "doc strings of
symbols".

> Adding packages to that would cause the results to
> show completely unrelated stuff.

Sorry, I don't follow you.  What do you have in mind?
`describe-package' shows the help for a package.
Are you afraid that what it shows for some packages
might pollute the apropos space somehow?

Can you please elaborate?  Perhaps give an example
of the kind of problem you envisage?

> So I'm against this.  Packages should have (and
> already do have) specialized commands that search
> their descriptions, keywords, etc.

This is only about their descriptions.

Functions, variables, and faces also have such
specialized commands, no?  Why should the existence
of such commands prevent `apropos-documentation'
from matching the doc that `describe-package'
provides for a package?  That's really all the doc
we need for this, I think: what `describe-package'
provides.

If you've already decided, then that's that.  But
if you're still open to considering the question
then please think about it.

Re: [External] : Re: apropos for packages [was: plz -> curl?]

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "adam@alphapapa.net" <adam@alphapapa.net>,
>         "luangruo@yahoo.com"
> 	<luangruo@yahoo.com>,
>         "larsi@gnus.org" <larsi@gnus.org>, "rms@gnu.org"
> 	<rms@gnu.org>,
>         "philipk@posteo.net" <philipk@posteo.net>,
>         "mardani29@yahoo.es" <mardani29@yahoo.es>,
>         "emacs-devel@gnu.org"
> 	<emacs-devel@gnu.org>
> Date: Tue, 17 May 2022 18:04:25 +0000
> 
> > >   With C-u prefix, or if ‘apropos-do-all’ is non-nil,
> > >   it searches all currently defined documentation
> > >   strings.
> > >
> > > For example, `C-u C-h d backtrace' doesn't show an
> > > entry for package `backtrace', even though the pkg
> > > doc string mentions "backtrace".  (Emacs 27.2)
> > 
> > You are taking that text out of its context.  The doc
> > string _really_ says this:
> > 
> >   Show symbols whose documentation contains matches for PATTERN.
> 
> It also _really_ says what I wrote.  I'm not making
> anything up, so please don't insinuate that.
> 
> Yes, I recognize that the doc in question is that
> provided by `describe-package' - it's not technically
> a doc string for the package.
> 
> > And now we understand why you don't see the package 
> > backtrace.el: it's because it is not a symbol.
> 
> If you want to quibble, fine.

I hereby refuse to talk to you anymore until such time as you learn to
talk in a civilized manner.  This isn't the first time, nor the second
or the third.  It's a constant attitude, and no amount of pointing
this fact to you helps you change your ways.

Shame on you!

RE: [External] : Re: apropos for packages [was: plz -> curl?]

[Drew Adams]

Dunno what your problem is, Eli, but
your reaction is totally uncalled for.

___

https://www.gnu.org/philosophy/kind-communication.html

https://lists.gnu.org/archive/html/emacs-devel/2022-05/msg00792.html

https://lists.gnu.org/archive/html/emacs-devel/2022-05/msg00794.html

Re: apropos for packages [was: plz -> curl?]

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

It would be natural for M-x apropos to include packages as well as
functions and variables.  And likewise apropos-documentation.

It's useful to invite users to think of apropos as a way to search
through all the various namespaces of things in Emacs.


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