May I commit this change to loading.texi (re eval-after-load)?

May I commit this change to loading.texi (re eval-after-load)?

[Alan Mackenzie]

Hi, Richard and Emacs!

On Wednesday 2006-05-24, I committed an enhancement to `eval-after-load'.
In my confusion at the time (my PC had died), I didn't get around to
committing the corresponding amendment to loading.texi.  I would like to
commit that change (see below) now.  Is that OK?

This is the change to the code:

#########################################################################

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

        * startup.el (command-line): For names of preloaded files, don't
        append ".elc" (now done in Fload), and call file-truename
	on the lisp directory.

	* subr.el (eval-after-load): Fix the doc-string.  Allow FILE to
	match ANY loaded file with the right name, not just those in
	load-path.  Put a regexp matching the file name into
	after-load-alist, rather than the name itself.

	* subr.el (load-history-regexp, load-history-filename-element)
	(do-after-load-evaluation): New functions.

	* international/mule.el (load-with-code-conversion): Do the
	eval-after-load stuff by calling do-after-load-evaluation.


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

        * lread.c (Vload_history): Enhance doc-string to say that the file
        is the absolute truename of the loaded file.

	* lread.c (Vafter_load_alist): doc-string: state that an element
	now has a regexp to match file names, not a file name as such.

	* lread.c (readevalloop): Call file-truename on the name for
	load-history, except at preloading time.

	* lread.c (Fload): At preloading time, preserve the extension of
	the filename which goes into load-history.  New var hist_file_name.

	* lread.c (Fload): Do eval-after-load stuff by calling the lisp
	function do-after-load-evaluation.

#########################################################################

Here is my proposed change to the Elisp manual:

2007-02-03  Alan Mackenzie  <acm@muc.de>

	* loading.texi (Hooks for Loading): Make the description of
	`eval-after-load' more detailed, and amend the description of
	after-load-alist, in accordance with changes from 2006-05.


Index: loading.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/loading.texi,v
retrieving revision 1.69
diff -c -r1.69 loading.texi
*** loading.texi	16 Jan 2007 03:28:53 -0000	1.69
--- loading.texi	3 Feb 2007 15:42:04 -0000
***************
*** 903,916 ****
  loaded, by calling @code{eval-after-load}.
  
  @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.
--- 903,930 ----
  loaded, by calling @code{eval-after-load}.
  
  @defun eval-after-load library form
! This function arranges to evaluate @var{form} at the end of loading
! the file @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}!
  
! Normally you just give a bare file name for @var{library}, like this:
! 
! @example
! (eval-after-load "edebug" '(def-edebug-spec c-point t))
! @end example
! 
! To restrict which files can trigger the evaluation, include a
! directory or an extension or both in @var{library}.  Only a file whose
! absolute true name (i.e. the name with all symbolic links chased out)
! matches all the given name components will match.  In the following
! example, @file{my_inst.elc} or @file{my_inst.elc.gz} in some directory
! @code{..../foo/bar} will trigger the evaluation, but not
! @file{my_inst.el}:
! 
! @example
! (eval-after-load "foo/bar/my_inst.elc" @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.
***************
*** 932,950 ****
  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
--- 946,965 ----
  programs meant for wider use.
  
  @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 Mackenzie (Ittersbach, Germany)

Re: May I commit this change to loading.texi (re eval-after-load)?

[Richard Stallman]

    ! Normally you just give a bare file name for @var{library}, like this:

That's not clear, because "bare file name" is not a term we use.
You need to spell out what you mean here.

      Only a file whose
    ! absolute true name (i.e. the name with all symbolic links chased out)

Please put a comma after "i.e.".  It always needs one.

Please fix those two points and then install your change.
Thanks.

Re: May I commit this change to loading.texi (re eval-after-load)?

[Alan Mackenzie]

Hi, Richard!

On Sun, Feb 04, 2007 at 12:03:19PM -0500, Richard Stallman wrote:
>     ! Normally you just give a bare file name for @var{library}, like this:
 
> That's not clear, because "bare file name" is not a term we use.
> You need to spell out what you mean here.

DONE.

>       Only a file whose
>     ! absolute true name (i.e. the name with all symbolic links chased out)
 
> Please put a comma after "i.e.".  It always needs one.

DONE.
 
> Please fix those two points and then install your change.

DONE.

> Thanks.

-- 
Alan Mackenzie (Ittersbach, Germany)