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

From: Drew Adams <[email-masked]>
Date: Sun, 22 Jun 2014 09:15:52 -0700 (PDT)

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 [email-masked]
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''