bug#17832: 24.4.50; `apropos-library' behavior for a top-level library file

bug#17832: 24.4.50; `apropos-library' behavior for a top-level library file

[Drew Adams]

1. I have a library foo.el that just `require's a set of component
libraries (files).  foo.el itself defines no functions or variables.

`M-x apropos-library foo' just shows this message:

  No apropos matches for `'

Granted, the doc string of `apropos-library' says that it lists the
variables and functions defined by library FILE, and there are none
defined in file foo.el.

But the command is called `apropos-library', not `apropos-lisp-file'.
That somewhat justifies a user in thinking that it should return a
list of the vars and functions defined in the _library_ as a whole,
which includes all of those defined in libraries that it requires.

Rather than just saying that the command is misnamed, or the name is
misleading, the first part of this bug report is to request that the
command live up to its name: give you a report of the functions and
variables defined in the _whole library_, recursively including those
of its required component libraries.

2. But before (or even without) fixing #1: The message "No apropos
matches for `'" is inappropriate.  The user did not explicitly
provide an apropos pattern to match, and s?he certainly did not
provide an empty pattern for Emacs to complain about.

Instead of just blindly piggybacking on `apropos-symbols-internal',
`apropos-library' should provide a reasonable message in this case.

3. When `apropos-library' calls `apropos-symbols-internal' it in fact
passes these args:

 SYMBOLS: nil
 KEYS:    t
 TEXT:    "Library `foo' provides: foo
and requires: foo-1 and foo-2 and foo-3 and foo-4 and foo-5 and foo-6
and foo-7 and foo-8"

The TEXT arg provides useful information about library foo.  It
should, I think, be included in the apropos output (whether or not
`apropos-library' is upgraded to show the symbols for the whole
library, as this bug report (#1) requests).

As a first and partial bug fix then, I propose that `apropos-library'
always print TEXT (which it does when there are defined symbols in the
file).  If there are no functions or vars defined in the file, then,
while waiting for a proper fix (#1), show buffer *Apropos* with just
TEXT and a statement that no functions or variables are defined in file
foo.el.  Get rid of the unhelpful message No apropos matches for `'.

In GNU Emacs 24.4.50.1 (i686-pc-mingw32)
 of 2014-06-17 on ODIEONE
Bzr revision: 117359 monnier@iro.umontreal.ca-20140617193358-2t1nl1te9gc2mqrx
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/snapshot/trunk
 --enable-checking=yes,glyphs 'CFLAGS=-O0 -g3'
 LDFLAGS=-Lc:/Devel/emacs/lib 'CPPFLAGS=-DGC_MCHECK=1
 -Ic:/Devel/emacs/include''

bug#17832: 24.4.50; `apropos-library' behavior for a top-level library file

[Stefan Monnier]

> Rather than just saying that the command is misnamed, or the name is
> misleading, the first part of this bug report is to request that the
> command live up to its name: give you a report of the functions and
> variables defined in the _whole library_, recursively including those
> of its required component libraries.

Many libraries will then appear to define all the CL macros&functions.

To do a better job, we'd need to distinguish the case where it
"requires" some other library for internal use compared to the case
where it requires a file which is conceptually part of the same library
(just split over several files).

The most common case, AFAICT, is the first, so I think in doubt it's
better to assume "requires" aren't really part of the library.

> As a first and partial bug fix then, I propose that `apropos-library'
> always print TEXT (which it does when there are defined symbols in the
> file).

Sounds good.


        Stefan

bug#17832: 24.4.50; `apropos-library' behavior for a top-level library file

[Drew Adams]

> > Rather than just saying that the command is misnamed, or the name is
> > misleading, the first part of this bug report is to request that the
> > command live up to its name: give you a report of the functions and
> > variables defined in the _whole library_, recursively including those
> > of its required component libraries.
> 
> Many libraries will then appear to define all the CL macros&functions.
> To do a better job, we'd need to distinguish the case where it
> "requires" some other library for internal use compared to the case
> where it requires a file which is conceptually part of the same library
> (just split over several files).

Yes.

And make the recursive behavior optional.  E.g., `C-u' for recursive,
and a button in the top-level output that refreshes the output after
descending recursively.

Additional feature: Since the top-level output lists the required
libraries, make each library name a link/button which if followed
descends into that library (non-recursively, or recursively with
C-u).  IOW, let users drill down manually, a level at a time or
recursively.  (This should be in addition to the possibility of
one-fell-swoop recursive descent at the top level.)

> The most common case, AFAICT, is the first, so I think in doubt
> it's better to assume "requires" aren't really part of the library.

Or have an option that lists libraries to exclude, whose default
value includes all libraries distributed with Emacs.  That gives
users reasonable control over the behavior.

bug#17832: 24.4.50; `apropos-library' behavior for a top-level library file

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> Rather than just saying that the command is misnamed, or the name is
> misleading, the first part of this bug report is to request that the
> command live up to its name: give you a report of the functions and
> variables defined in the _whole library_, recursively including those
> of its required component libraries.

The command (in Emacs 28, at least) lists libraries it requires.

> 2. But before (or even without) fixing #1: The message "No apropos
> matches for `'" is inappropriate.  The user did not explicitly
> provide an apropos pattern to match, and s?he certainly did not
> provide an empty pattern for Emacs to complain about.

I've now fixed this in Emacs 28.

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

bug#17832: [External] : Re: bug#17832: 24.4.50; `apropos-library' behavior for a top-level library file

[Drew Adams]

> > Rather than just saying that the command is misnamed, or the name is
> > misleading, the first part of this bug report is to request that the
> > command live up to its name: give you a report of the functions and
> > variables defined in the _whole library_, recursively including those
> > of its required component libraries.
> 
> The command (in Emacs 28, at least) lists libraries it requires.

That doesn't correspond to the bug reported / request.

Listing required libraries isn't listing functions
and variables they define, and so on, recursively.

Seems to ignore what both I and Stefan suggested.
Apparently another "won't fix".