[Emacs-diffs] Changes to emacs/lispref/compile.texi

[Richard M . Stallman]

Index: emacs/lispref/compile.texi
diff -c emacs/lispref/compile.texi:1.24 emacs/lispref/compile.texi:1.25
*** emacs/lispref/compile.texi:1.24     Mon Oct 17 06:45:48 2005
--- emacs/lispref/compile.texi  Fri Oct 28 16:43:12 2005
***************
*** 407,413 ****
  
  You can get a similar result by putting @var{body} in a separate file
  and referring to that file with @code{require}.  That method is
! preferable when @var{body} is large.
  @end defspec
  
  @defspec eval-when-compile address@hidden
--- 407,431 ----
  
  You can get a similar result by putting @var{body} in a separate file
  and referring to that file with @code{require}.  That method is
! preferable when @var{body} is large.  Effectively @code{require} is
! automatically @code{eval-and-compile}, the package is loaded both when
! compiling and executing.
! 
! @code{autoload} is also effectively @code{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 @code{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
! @code{eval-and-compile} should be used to get the helper both when
! compiling and then later when running.
! 
! If functions are defined programmatically (with @code{fset} say), then
! @code{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).
  @end defspec
  
  @defspec eval-when-compile address@hidden
***************
*** 417,423 ****
  you load the source file, rather than compiling it, @var{body} is
  evaluated normally.
  
! @strong{Common Lisp Note:} At top level, this is analogous to the Common
  Lisp idiom @code{(eval-when (compile eval) @dots{})}.  Elsewhere, the
  Common Lisp @samp{#.} reader macro (but not when interpreting) is closer
  to what @code{eval-when-compile} does.
--- 435,472 ----
  you load the source file, rather than compiling it, @var{body} is
  evaluated normally.
  
! If you have a constant that needs some calculation to produce,
! @code{eval-when-compile} can do that done at compile-time.  For
! example,
! 
! @lisp
! (defvar my-regexp
!   (eval-when-compile (regexp-opt '("aaa" "aba" "abb"))))
! @end lisp
! 
! If you're using another package, but only need macros from it (the
! byte compiler will expand those), then @code{eval-when-compile} can be
! used to load it for compiling, but not executing.  For example,
! 
! @lisp
! (eval-when-compile
!   (require 'my-macro-package))  ;; only macros needed from this
! @end lisp
! 
! The same sort of thing goes for macros or @code{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.
! 
! @lisp
! (eval-when-compile
!   (unless (fboundp 'some-new-thing)
!     (defmacro 'some-new-thing ()
!       (compatibility code))))
! @end lisp
! 
! @strong{Common Lisp Note:} At top level, @code{eval-when-compile} is 
analogous to the Common
  Lisp idiom @code{(eval-when (compile eval) @dots{})}.  Elsewhere, the
  Common Lisp @samp{#.} reader macro (but not when interpreting) is closer
  to what @code{eval-when-compile} does.