RE: new apropos feature in Emacs-22

["Drew Adams" <drew.adams@oracle.com>]

This feature changes the syntax and meaning of the input to apropos
functions. We've discussed the effects on the users of apropos commands.

There is also a (similar) effect on the programmatic use to consider. While
it is true that there are internal apropos functions that programs could use
instead of using the end-user commands:

1. There is no guarantee that programs do not use the end-user commands.

2. In some cases, there is no internal function that directly does what's
needed. For example, there is no internal equivalent of `apropos-variable'
(IIUC).

3. There is (still) no documentation for most of the internal commands
(apropos-documentation-check-doc-file, apropos-documentation-check-elc-file,
apropos-documentation-internal, apropos-symbols-internal,
apropos-value-internal). This can suggest to programmers that the internal
functions are not intended to be used externally.

Most of the discussion has centered on _how_ to obtain the syntax and
behavior of both the old (regexp) and the new (keywords) apropos at the same
time, in the same command - not on whether or not that is desirable.

The latest suggestion for combining the old and new in the same command was
to use `M-r' to toggle between old and new (in addition to `C-u' to toggle
`do-all') - and to add a new user option for selecting the default behavior.
This, like the other suggestions, is workable, but it doesn't help existing
programmatic use of the commands.

In order to not break existing code:

1. An extra (e.g. optional) parameter would need to be provided to the
commands.

2. Its default value (nil) would need to reflect the old behavior.

#2 conflicts with the desire to make the default syntax and behavior be
keyword search, in order to be more "novice user-friendly". We could treat
the interactive and programmatic values oppositely wrt to this parameter, of
course, but that would be downright mischievous.

I argued that the old and new syntaxes and behaviors should be implemented
in different commands. That would give all users what they want, without the
complexities of modes and mixed syntaxes. It would also not break any
existing code.

(I also said that I didn't care which commands got the "apropos" name, but
I've changed my mind on that, after thinking about existing programs that
might expect the old behavior from the "apropos" names. That is, I don't
really care about the names, but existing programs might.)

I've still seen _no argument_ (i.e. no rationale) voiced against using
separate commands. One could argue "Occam's razor: don't multiply things
needlessly", but that applies equally to all approaches discussed so far -
whether we multiply the number of commands or the number of use modes (e.g.
`M-r' toggle) for the existing commands.

So, I repeat the question:  _Why not_ leave the apropos commands as they
were, and create new, more "novice user-friendly", keyword-search commands?
The question deserves some reply, at least. It should have been addressed
before launching a discussion of _how_ to change the existing commands.