Subject: 24.3.50; NEWS item about `apropos-*-face' user options and new faces

From: Drew Adams <[email-masked]>
Date: Tue, 21 Jan 2014 19:06:08 -0800 (PST)

1. This is the inadequate NEWS item:

  ** Apropos

  *** The faces used by Apropos are now directly customizable.
  These faces are named `apropos-symbol', `apropos-keybinding', and so on;
  see the `apropos' Custom group for details.

  *** The old options whose values specified faces to use have been removed
  (i.e. `apropos-symbol-face', `apropos-keybinding-face', etc.).

Why inadequate? Because it does not list the options, so users can check
their current customizations of those options and transfer them to the
new faces (something that Emacs could have done for them, BTW).

It is not enough to say "etc." and "and so on."  List the options.  By
my checking, I find these: apropos-keybinding-face, apropos-label-face,
apropos-match-face, apropos-property-face, apropos-symbol-face.  Is it
so hard to find and state the list, to help users?

You go to great lengths to help users locate the new faces (telling them
to use `M-x customize-group apropos'.  But from a user point of view
what's first needed is the list of options that the new faces replace.
This is what a NEWS item about replacement needs to inform users of: A
has been replaced by B.  Why?  So users can replace A with B in their
own code, custom files, etc.

2. Plus, this removal and replacement is apparently not the case for all
`apropos-*-face' options - see option `apropos-match-face'.  Why this
inconsistency?  Point it out in NEWS, at least, if it really has a good
reason for continuing.  As it stands now, the NEWS text is incorrect,
claiming the removal of all such face options.

In GNU Emacs 24.3.50.1 (i686-pc-mingw32)
 of 2014-01-17 on ODIEONE
Bzr revision: 116059 [email-masked]
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/binary --enable-checking=yes,glyphs
 'CFLAGS=-O0 -g3' LDFLAGS=-Lc:/Devel/emacs/lib
 CPPFLAGS=-Ic:/Devel/emacs/include'