bug#16810: 24.3.50; `with-eval-after-load'

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

1. The NEWS entry is not helpful enough:

     "This is like the old `eval-after-load', but better behaved."

   What does that even mean?  How so?  How is it like it?  How is it
   different?  What is "better" about the (unspecified) behavior
   difference?  Why was the macro introduced?

   The main difference I can see, based on the available doc, is that
   the macro evaluates the BODY "*each time* LIBRARY is loaded".  Is
   that considered "better behaved"?  Why?

   That important difference (assuming the manual is correct about that)
   is not even mentioned in the doc string.  And it is not stressed in
   the Elisp manual - you have to read carefully to get it.

   Other, obvious differences, which I can hardly imagine to constitute
   "better" behavior and so call for introducing this macro, let alone
   replacing `eval-after-load' with it, are (a) that it is a macro, so
   you do not need to quote its arg (and so cannot pass it something to
   be evaluated) and (b) that it uses an implicit `progn'.  What else is
   different?

2. The doc string is not helpful enough.

   Compare the doc string of `eval-after-load' with this doc string.
   Someone actually tried (and succeeded) to describe what
   `eval-after-load' does.

3. Elisp manual:

   `eval-after-load' is referenced multiple times, but it is not
   described/specified.  Its description has been removed from the
   manual.  It needs to be reinstated.

   The Elisp manual says that`eval-after-load' is primarily for users
   (e.g., in their init files), not for Lisp libraries.  But the Emacs
   manual also does not describe it.  This does not help users.

   The doc for both `eval-after-load' and `with-eval-after-load' is now
   incomplete and confusing.

4. Posts here and there (e.g.,
   http://lists.gnu.org/archive/html/emacs-devel/2014-02/msg00270.html)
   suggest that `eval-after-load' is being replaced by
   `with-eval-after-load'.  All the more reason to document the proposed
   new at least as well as the old was documented.

5. I can find no proposal or discussion of `with-eval-after-load' in
   either emacs-devel or the bug list.  It seems to have just appeared,
   followed by a few statements here and there suggesting that it is
   replacing `eval-after-load'.  What happened to proposal >
   discussion > implementation & doc?  What problem is this solution
   trying to solve?

In GNU Emacs 24.3.50.1 (i686-pc-mingw32)
 of 2014-02-11 on ODIEONE
Bzr revision: 116410 lekktu@gmail.com-20140211204823-l9l2s6tktfitq266
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'