X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/f76840f36cf60feecaf21d55d24ace948800fef7..b3d50cffbd29d451fab160f691eed135f84a5b4b:/doc/lispref/loading.texi

diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index 9b582fe5cf..53067897f8 100644
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -1,7 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
-@c   2002, 2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+@c   2002, 2003, 2004, 2005, 2006, 2007, 2008  Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/loading
 @node Loading, Byte Compilation, Customization, Top
@@ -692,7 +692,7 @@ done.
   When @code{require} is used at top level in a file, it takes effect
 when you byte-compile that file (@pxref{Byte Compilation}) as well as
 when you load it.  This is in case the required package contains macros
-that the byte compiler must know about.  It also avoids byte-compiler
+that the byte compiler must know about.  It also avoids byte compiler
 warnings for functions and variables defined in the file loaded with
 @code{require}.
 
@@ -798,12 +798,15 @@ with a call to @code{provide}.  The order of the elements in the
 
 @defun symbol-file symbol &optional type
 This function returns the name of the file that defined @var{symbol}.
-If @var{type} is @code{nil}, then any kind of definition is
-acceptable.  If @var{type} is @code{defun} or @code{defvar}, that
-specifies function definition only or variable definition only.
-
-The value is normally an absolute file name.  It can also be
-@code{nil}, if the definition is not associated with any file.
+If @var{type} is @code{nil}, then any kind of definition is acceptable.
+If @var{type} is @code{defun}, @code{defvar}, or @code{defface}, that
+specifies function definition, variable definition, or face definition
+only.
+
+The value is normally an absolute file name.  It can also be @code{nil},
+if the definition is not associated with any file.  If @var{symbol}
+specifies an autoloaded function, the value can be a relative file name
+without extension.
 @end defun
 
   The basis for @code{symbol-file} is the data in the variable
@@ -830,6 +833,8 @@ redefined it as a function.  The following element is always
 function.
 @item (autoload . @var{fun})
 The function @var{fun} was defined as an autoload.
+@item (defface . @var{face})
+The face @var{face} was defined.
 @item (require . @var{feature})
 The feature @var{feature} was required.
 @item (provide . @var{feature})
@@ -862,24 +867,27 @@ library with @code{defun}, @code{defalias}, @code{defsubst},
 It then restores any autoloads formerly associated with those symbols.
 (Loading saves these in the @code{autoload} property of the symbol.)
 
-@vindex unload-feature-special-hooks
 Before restoring the previous definitions, @code{unload-feature} runs
 @code{remove-hook} to remove functions in the library from certain
 hooks.  These hooks include variables whose names end in @samp{hook}
 or @samp{-hooks}, plus those listed in
-@code{unload-feature-special-hooks}.  This is to prevent Emacs from
-ceasing to function because important hooks refer to functions that
-are no longer defined.
+@code{unload-feature-special-hooks}, as well as
+@code{auto-mode-alist}.  This is to prevent Emacs from ceasing to
+function because important hooks refer to functions that are no longer
+defined.
+
+Standard unloading activities also undoes ELP profiling of functions
+in that library, unprovides any features provided by the library, and
+cancels timers held in variables defined by the library.
 
-@vindex @var{feature}-unload-hook
+@vindex @var{feature}-unload-function
 If these measures are not sufficient to prevent malfunction, a library
-can define an explicit unload hook.  If @code{@var{feature}-unload-hook}
-is defined, it is run as a normal hook before restoring the previous
-definitions, @emph{instead of} the usual hook-removing actions.  The
-unload hook ought to undo all the global state changes made by the
-library that might cease to work once the library is unloaded.
-@code{unload-feature} can cause problems with libraries that fail to do
-this, so it should be used with caution.
+can define an explicit unloader named @code{@var{feature}-unload-function}.
+If that symbol is defined as a function, @code{unload-feature} calls
+it with no arguments before doing anything else.  It can do whatever
+is appropriate to unload the library.  If it returns @code{nil},
+@code{unload-feature} proceeds to take the normal unload actions.
+Otherwise it considers the job to be done.
 
 Ordinarily, @code{unload-feature} refuses to unload a library on which
 other loaded libraries depend.  (A library @var{a} depends on library