doc eval-when-compile, eval-and-compile

[Kevin Ryde]

I find I have to think about three times and then think again before
deciding whether eval-when-compile or eval-and-compile or neither are
needed or wanted.

Perhaps it's easy for experts, but it might be nice if the docs had
some examples of typical uses, or typical non-uses.

Below is my go at something like that for the manual.  I think the
eval-when-compile bit is quite nice, but I couldn't think of much good
to say about eval-and-compile.  If eval-when-compile is the more often
used then putting it first in the node might be good.

I see eval-and-compile has been used around autoloads like the
following from gnus, but this is unnecessary now, is it?

        (eval-and-compile
          (autoload 'password-read "password"))



 -- Special Form: eval-and-compile body...
     This form marks BODY to be evaluated both when you compile the
     containing code and when you run it (whether compiled or not).

     You can get a similar result by putting BODY in a separate file
     and referring to that file with `require'.  That method is
     preferable when BODY is large.  Effectively `require' is
     automatically `eval-and-compile', the package is loaded both when
     compiling and executing.

     `autoload' is also effectively `eval-and-compile' too.  It's
     recognised when compiling, so uses of such a function don't produce
     "not known to be defined" warnings.

     Most uses of `eval-and-compile' are fairly sophisticated.

     If a macro has a helper function to build its result, and that
     macro is used both locally and outside the package, then
     `eval-and-compile' should be used to get the helper both when
     compiling and then later when running.

     If functions are defined programmatically (with `fset' say), then
     `eval-and-compile' can be used to have that done at compile-time
     as well as run-time, so calls to those functions are checked (and
     warnings about "not known to be defined" suppressed).

 -- Special Form: eval-when-compile body...
     This form marks BODY to be evaluated at compile time but not when
     the compiled program is loaded.  The result of evaluation by the
     compiler becomes a constant which appears in the compiled program.
     If you load the source file, rather than compiling it, BODY is
     evaluated normally.

     If you have a constant that needs some calculation to produce,
     `eval-when-compile' can do that done at compile-time.  For example,

          (defvar my-regexp
            (eval-when-compile (regexp-opt '("aaa" "aba" "abb"))))

     If you're using another package, but only need macros from it (the
     byte compiler will expand those), then `eval-when-compile' can be
     used to load it for compiling, but not executing.  For example,

          (eval-when-compile
            (require 'my-macro-package))  ;; only macros needed from this

     The same sort of thing goes for macros or `defalias'es defined
     locally and only for use within the file.  They can be defined
     while compiling, but then not needed when executing.  This is good
     for code that's only a fallback for compability with other
     versions of Emacs.  For example.

          (eval-when-compile
            (unless (fboundp 'some-new-thing)
              (defmacro 'some-new-thing ()
                (compatibility code))))

     *Common Lisp Note:* At top level, `eval-when-compile' is analogous
     to the Common Lisp idiom `(eval-when (compile eval) ...)'.
     Elsewhere, the Common Lisp `#.' reader macro (but not when
     interpreting) is closer to what `eval-when-compile' does.

compile.texi.eval-when.diff
Description: Text document