Re: FIXED!! Re: Clarification of eval-after-load - Patch to the Elisp manual.

Re: FIXED!! Re: Clarification of eval-after-load - Patch to the Elisp manual.

[Alan Mackenzie]

Hi, Richard!

On Wed, 24 May 2006, Richard Stallman wrote:

[ ..... ]

>Aside from those things [amendments to load-history and the eval-after-load
>mechanism], it is good, so please fix them and install it.

DONE.

>By the way, please do read thru the text in the Lisp Manual that talks
>about this stuff, to make sure it is all accurate.

Here's a matching patch for loading.texi.

I've taken out the bit "In general, well-designed Lisp programs should
not use this feature [eval-after-load]".  Given that there's around 70
e-a-l forms in the Emacs source, it is probably not true.  It also makes
us a sitting duck for malicious wits wishing to denigrate the quality of
our code.  So I've taken it out.



2006-05-25  Alan Mackenzie  <acm@muc.de>

	* loading.texi (Hooks for Loading): Amend the descriptions of the
	FILE parameter to eval-after-load, and of after-load-alist.
	Remove the deprecation of eval-after-load.


Index: loading.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/loading.texi,v
retrieving revision 1.64
diff -c -r1.64 loading.texi
*** loading.texi	1 Mar 2006 02:45:05 -0000	1.64
--- loading.texi	25 May 2006 14:13:26 -0000
***************
*** 896,908 ****
  
  @defun eval-after-load library form
  This function arranges to evaluate @var{form} at the end of loading the
! library @var{library}, if and when @var{library} is loaded.  If
  @var{library} is already loaded, it evaluates @var{form} right away.
  
! If @var{library} is a string, it must exactly match the argument of
! @code{load} used to load the library.  To get the proper results when an
! installed library is found by searching @code{load-path}, you should not
! include any directory names in @var{library}.
  
  @var{library} can also be a feature (i.e.@: a symbol), in which case
  @var{form} is evaluated when @code{(provide @var{library})} is called.
--- 896,921 ----
  
  @defun eval-after-load library form
  This function arranges to evaluate @var{form} at the end of loading the
! library @var{library}, each time @var{library} is loaded.  If
  @var{library} is already loaded, it evaluates @var{form} right away.
+ Don't forget to quote @var{form}!
  
! If @var{library} is a string, it is matched against the absolute true
! file name (i.e. the name with all symbolic links chased out) of the
! library to be loaded.  If @var{library} has an extension, the file name
! must have this extension too --- otherwise it may have any extension.  In
! either case, the file name may additionally have an extension denoting a
! compressed file (e.g. the @samp{.gz} in @code{foo.elc.gz}, @ref{Load
! Suffixes}).  If @var{library} is an absolute file name, the file name
! must match it.  If it's a relative name, the file name's tail must match
! it.
! 
! Usually, however, you just specify a bare library name with neither
! directory nor extension.  For example:
! 
! @example
! (eval-after-load "font-lock" @dots{})
! @end example
  
  @var{library} can also be a feature (i.e.@: a symbol), in which case
  @var{form} is evaluated when @code{(provide @var{library})} is called.
***************
*** 911,942 ****
  execution of the rest of @var{form}.
  @end defun
  
- In general, well-designed Lisp programs should not use this feature.
- The clean and modular ways to interact with a Lisp library are (1)
- examine and set the library's variables (those which are meant for
- outside use), and (2) call the library's functions.  If you wish to
- do (1), you can do it immediately---there is no need to wait for when
- the library is loaded.  To do (2), you must load the library (preferably
- with @code{require}).
- 
- But it is OK to use @code{eval-after-load} in your personal
- customizations if you don't feel they must meet the design standards for
- programs meant for wider use.
- 
  @defvar after-load-alist
! This variable holds an alist of expressions to evaluate if and when
! particular libraries are loaded.  Each element looks like this:
  
  @example
! (@var{filename} @var{forms}@dots{})
  @end example
  
! The function @code{load} checks @code{after-load-alist} in order to
! implement @code{eval-after-load}.
  @end defvar
  
- @c Emacs 19 feature
- 
  @ignore
     arch-tag: df731f89-0900-4389-a436-9105241b6f7a
  @end ignore
--- 924,944 ----
  execution of the rest of @var{form}.
  @end defun
  
  @defvar after-load-alist
! This variable, an alist built by @code{eval-after-load}, holds the
! expressions to evaluate when particular libraries are loaded.  Each
! element looks like this:
  
  @example
! (@var{regexp-or-feature} @var{forms}@dots{})
  @end example
  
! The key @var{regexp-or-feature} is either a regular expression or a
! symbol, and the value is a list of forms.  The forms are evaluated when
! the key matches the the absolute true name of the file being
! @code{load}ed or the symbol being @code{provide}d.
  @end defvar
  
  @ignore
     arch-tag: df731f89-0900-4389-a436-9105241b6f7a
  @end ignore



-- 
Alan.

Re: FIXED!! Re: Clarification of eval-after-load - Patch to the Elisp manual.

[Stefan Monnier]

> I've taken out the bit "In general, well-designed Lisp programs should
> not use this feature [eval-after-load]".  Given that there's around 70
> e-a-l forms in the Emacs source, it is probably not true.  It also makes
> us a sitting duck for malicious wits wishing to denigrate the quality of
> our code.  So I've taken it out.

I disagree here.  `eval-after-load' is and will remain a hack.  A very
convenient one when you need it, but not something reliable.


        Stefan