Clarification of eval-after-load [was: Problem mit symlinks, locate-library and load-history]

[Alan Mackenzie <acm@muc.de>]

Hi, Emacs!

The doc string (and manual entry) for eval-after-load are a bit hazy and
indefinite.  Here is the doc-string:

   "Arrange that, if FILE is ever loaded, FORM will be run at that time.
    This makes or adds to an entry on `after-load-alist'.
    If FILE is already loaded, evaluate FORM right now.
    It does nothing if FORM is already on the list for FILE.
    FILE must match exactly.  Normally FILE is the name of a library,
    with no directory or extension specified, since that is how `load'
    is normally called.
    FILE can also be a feature (i.e. a symbol), in which case FORM is
    evaluated whenever that feature is `provide'd."

Some problems are:
(i) "FILE must match exactly" doesn't say what FILE must match, or how it
must match it, and it is unclear what "exactly" means.  Given this
description, I would not expect the argument "font-lock" to match the
file name "font-lock.elc", but it does.  :-(

(ii) The doc-string doesn't say what happens when FILE gets loaded again.


I propose the following as a replacement:

   "Arrange that, if FILE is ever loaded, FORM will be run at that time.
    If FILE is already loaded, evaluate FORM right now.

    FILE, a string, must be either an absolute file name or a file name with
    no directory part; in either case it may have an extension
    \(e.g. \".el\") or may lack one.  Symbolic links in an absolute file name
    will be chased out before it is matched against the names of loaded files.

    When FILE is absolute, only FILE in that directory triggers evaluation
    of FORM, otherwise FILE in any directory will do.  If FILE has an
    extension, only a file with that exact extension will trigger evaluation,
    otherwise any extension will do it.

    Alternatively, FILE can be a feature (i.e. a symbol), in which case FORM
    is evaluated whenever that feature is `provide'd.

    Usually FILE is just a library name like \"font-lock\".

    If a matching file is loaded again, FORM will be evaluated again.

    This makes or adds to an entry on `after-load-alist'.
    It does nothing if FORM is already on the list for FILE."

Naturally, the code will need tweaking a bit to fit this doc-string.

What do you think?

-- 
Alan.