@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999,
-@c 2003, 2004
+@c 2003, 2004, 2005
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/loading
containing Lisp code.
@menu
-* How Programs Do Loading:: The @code{load} function and others.
-* Library Search:: Finding a library to load.
-* Loading Non-ASCII:: Non-@acronym{ASCII} characters in Emacs Lisp files.
-* Autoload:: Setting up a function to autoload.
-* Repeated Loading:: Precautions about loading a file twice.
-* Named Features:: Loading a library if it isn't already loaded.
-* Where Defined:: Finding which file defined a certain symbol.
-* Unloading:: How to ``unload'' a library that was loaded.
-* Hooks for Loading:: Providing code to be run when
- particular libraries are loaded.
+* How Programs Do Loading:: The @code{load} function and others.
+* Library Search:: Finding a library to load.
+* Loading Non-ASCII:: Non-@acronym{ASCII} characters in Emacs Lisp files.
+* Autoload:: Setting up a function to autoload.
+* Repeated Loading:: Precautions about loading a file twice.
+* Named Features:: Loading a library if it isn't already loaded.
+* Where Defined:: Finding which file defined a certain symbol.
+* Unloading:: How to ``unload'' a library that was loaded.
+* Hooks for Loading:: Providing code to be run when
+ particular libraries are loaded.
@end menu
@node How Programs Do Loading
just @var{filename} with no added suffix.
The argument @var{docstring} is the documentation string for the
-function. Normally, this should be identical to the documentation string
-in the function definition itself. Specifying the documentation string
-in the call to @code{autoload} makes it possible to look at the
-documentation without loading the function's real definition.
+function. Specifying the documentation string in the call to
+@code{autoload} makes it possible to look at the documentation without
+loading the function's real definition. Normally, this should be
+identical to the documentation string in the function definition
+itself. If it isn't, the function definition's documentation string
+takes effect when it is loaded.
If @var{interactive} is non-@code{nil}, that says @var{function} can be
called interactively. This lets completion in @kbd{M-x} work without
@findex update-file-autoloads
@findex update-directory-autoloads
- A magic autoload comment consists of @samp{;;;###autoload}, on a line
-by itself, just before the real definition of the function in its
+@cindex magic autoload comment
+@cindex autoload cookie
+@anchor{autoload cookie}
+ A magic autoload comment (often called an @dfn{autoload cookie})
+consists of @samp{;;;###autoload}, on a line by itself,
+just before the real definition of the function in its
autoloadable source file. The command @kbd{M-x update-file-autoloads}
writes a corresponding @code{autoload} call into @file{loaddefs.el}.
Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}.
Here's what that produces in @file{loaddefs.el}:
@smallexample
-(autoload 'doctor "doctor" "\
-Switch to *doctor* buffer and start giving psychotherapy."
- t)
+(autoload (quote doctor) "doctor" "\
+Switch to *doctor* buffer and start giving psychotherapy.
+
+\(fn)" t nil)
@end smallexample
@noindent
+@cindex @code{fn} in function's documentation string
The backslash and newline immediately following the double-quote are a
convention used only in the preloaded uncompiled Lisp files such as
@file{loaddefs.el}; they tell @code{make-docfile} to put the
documentation string in the @file{etc/DOC} file. @xref{Building Emacs}.
-See also the commentary in @file{lib-src/make-docfile.c}.
+See also the commentary in @file{lib-src/make-docfile.c}. @samp{(fn)}
+in the usage part of the documentation string is replaced with the
+function's name when the various help functions (@pxref{Help
+Functions}) display it.
If you write a function definition with an unusual macro that is not
one of the known and recognized function definition methods, use of an
The simplest way to add an element to an alist is like this:
@example
-(setq minor-mode-alist
- (cons '(leif-mode " Leif") minor-mode-alist))
+(push '(leif-mode " Leif") minor-mode-alist)
@end example
@noindent
@example
(or (assq 'leif-mode minor-mode-alist)
- (setq minor-mode-alist
- (cons '(leif-mode " Leif") minor-mode-alist)))
+ (push '(leif-mode " Leif") minor-mode-alist))
@end example
- To add an element to a list just once, you can also use @code{add-to-list}
-(@pxref{Setting Variables}).
+@noindent
+or this:
+
+@example
+(add-to-list '(leif-mode " Leif") minor-mode-alist)
+@end example
Occasionally you will want to test explicitly whether a library has
already been loaded. Here's one way to test, in a library, whether it
@item @var{var}
The symbol @var{var} was defined as a variable.
@item (defun . @var{fun})
-The @var{fun} was defined by this library.
+The function @var{fun} was defined.
@item (t . @var{fun})
The function @var{fun} was previously an autoload before this library
-redefined it as a function. The following element is always the
-symbol @var{fun}, which signifies that the library defined @var{fun}
-as a function.
+redefined it as a function. The following element is always
+@code{(defun . @var{fun})}, which represents defining @var{fun} as a
+function.
@item (autoload . @var{fun})
The function @var{fun} was defined as an autoload.
@item (require . @var{feature})