Commit 6c1e4b46 authored by Chong Yidong's avatar Chong Yidong
Browse files

Update Loading chapter of Emacs manual.

* doc/emacs/loading.texi (Loading): Don't emphasize "library" terminology.
(Library Search): load-path is not a user option.  Mention role of
-L option and packages.  Improve examples.
(Loading Non-ASCII): Don't mention unibyte Emacs, which is
obsolete.
(Autoload): Minor clarifications.
parent 104dc9c6
...@@ -206,7 +206,7 @@ internals.texi ...@@ -206,7 +206,7 @@ internals.texi
intro.texi cyd intro.texi cyd
keymaps.texi keymaps.texi
lists.texi cyd lists.texi cyd
loading.texi loading.texi cyd
locals.texi locals.texi
macros.texi cyd macros.texi cyd
maps.texi maps.texi
......
2012-02-10 Chong Yidong <cyd@gnu.org>
* loading.texi (Loading): Don't emphasize "library" terminology.
(Library Search): load-path is not a user option. Mention role of
-L option and packages. Improve examples.
(Loading Non-ASCII): Don't mention unibyte Emacs, which is
obsolete.
(Autoload): Minor clarifications.
2012-02-10 Glenn Morris <rgm@gnu.org> 2012-02-10 Glenn Morris <rgm@gnu.org>
* modes.texi (Basic Major Modes): Mention tabulated-list-mode. * modes.texi (Basic Major Modes): Mention tabulated-list-mode.
......
...@@ -10,9 +10,10 @@ ...@@ -10,9 +10,10 @@
@cindex library @cindex library
@cindex Lisp library @cindex Lisp library
Loading a file of Lisp code means bringing its contents into the Lisp Loading a file of Lisp code means bringing its contents into the
environment in the form of Lisp objects. Emacs finds and opens the Lisp environment in the form of Lisp objects. Emacs finds and opens
file, reads the text, evaluates each form, and then closes the file. the file, reads the text, evaluates each form, and then closes the
file. Such a file is also called a @dfn{Lisp library}.
The load functions evaluate all the expressions in a file just The load functions evaluate all the expressions in a file just
as the @code{eval-buffer} function evaluates all the as the @code{eval-buffer} function evaluates all the
...@@ -29,11 +30,6 @@ into a buffer and evaluated there. (Indeed, most code is tested this ...@@ -29,11 +30,6 @@ into a buffer and evaluated there. (Indeed, most code is tested this
way.) Most often, the forms are function definitions and variable way.) Most often, the forms are function definitions and variable
definitions. definitions.
A file containing Lisp code is often called a @dfn{library}. Thus,
the ``Rmail library'' is a file containing code for Rmail mode.
Similarly, a ``Lisp library directory'' is a directory of files
containing Lisp code.
@menu @menu
* How Programs Do Loading:: The @code{load} function and others. * How Programs Do Loading:: The @code{load} function and others.
* Load Suffixes:: Details about the suffixes that @code{load} tries. * Load Suffixes:: Details about the suffixes that @code{load} tries.
...@@ -88,8 +84,8 @@ this case, you must specify the precise file name you want, except ...@@ -88,8 +84,8 @@ this case, you must specify the precise file name you want, except
that, if Auto Compression mode is enabled, @code{load} will still use that, if Auto Compression mode is enabled, @code{load} will still use
@code{jka-compr-load-suffixes} to find compressed versions. By @code{jka-compr-load-suffixes} to find compressed versions. By
specifying the precise file name and using @code{t} for specifying the precise file name and using @code{t} for
@var{nosuffix}, you can prevent perverse file names such as @var{nosuffix}, you can prevent file names like @file{foo.el.el} from
@file{foo.el.el} from being tried. being tried.
If the optional argument @var{must-suffix} is non-@code{nil}, then If the optional argument @var{must-suffix} is non-@code{nil}, then
@code{load} insists that the file name used must end in either @code{load} insists that the file name used must end in either
...@@ -238,73 +234,37 @@ it skips the latter group. ...@@ -238,73 +234,37 @@ it skips the latter group.
When Emacs loads a Lisp library, it searches for the library When Emacs loads a Lisp library, it searches for the library
in a list of directories specified by the variable @code{load-path}. in a list of directories specified by the variable @code{load-path}.
@defopt load-path @defvar load-path
@cindex @code{EMACSLOADPATH} environment variable @cindex @code{EMACSLOADPATH} environment variable
The value of this variable is a list of directories to search when The value of this variable is a list of directories to search when
loading files with @code{load}. Each element is a string (which must be loading files with @code{load}. Each element is a string (which must be
a directory name) or @code{nil} (which stands for the current working a directory name) or @code{nil} (which stands for the current working
directory). directory).
@end defopt @end defvar
The value of @code{load-path} is initialized from the environment
variable @code{EMACSLOADPATH}, if that exists; otherwise its default
value is specified in @file{emacs/src/epaths.h} when Emacs is built.
Then the list is expanded by adding subdirectories of the directories
in the list.
The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};
@samp{:} (or @samp{;}, according to the operating system) separates
directory names, and @samp{.} is used for the current default directory.
Here is an example of how to set your @code{EMACSLOADPATH} variable from
a @code{csh} @file{.login} file:
@smallexample
setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
@end smallexample
Here is how to set it using @code{sh}: Each time Emacs starts up, it sets up the value of @code{load-path}
in several steps. First, it initializes @code{load-path} to the
directories specified by the environment variable @env{EMACSLOADPATH},
if that exists. The syntax of @env{EMACSLOADPATH} is the same as used
for @code{PATH}; directory names are separated by @samp{:} (or
@samp{;}, on some operating systems), and @samp{.} stands for the
current default directory. Here is an example of how to set
@env{EMACSLOADPATH} variable from @command{sh}:
@smallexample @smallexample
export EMACSLOADPATH export EMACSLOADPATH
EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp EMACSLOADPATH=/home/foo/.emacs.d/lisp:/opt/emacs/lisp
@end smallexample @end smallexample
Here is an example of code you can place in your init file (@pxref{Init @noindent
File}) to add several directories to the front of your default Here is how to set it from @code{csh}:
@code{load-path}:
@smallexample @smallexample
@group setenv EMACSLOADPATH /home/foo/.emacs.d/lisp:/opt/emacs/lisp
(setq load-path
(append (list nil "/user/bil/emacs"
"/usr/local/lisplib"
"~/emacs")
load-path))
@end group
@end smallexample @end smallexample
@c Wordy to rid us of an overfull hbox. --rjc 15mar92 If @env{EMACSLOADPATH} is not set (which is usually the case), Emacs
@noindent initializes @code{load-path} with the following two directories:
In this example, the path searches the current working directory first,
followed then by the @file{/user/bil/emacs} directory, the
@file{/usr/local/lisplib} directory, and the @file{~/emacs} directory,
which are then followed by the standard directories for Lisp code.
Dumping Emacs uses a special value of @code{load-path}. If the value of
@code{load-path} at the end of dumping is unchanged (that is, still the
same special value), the dumped Emacs switches to the ordinary
@code{load-path} value when it starts up, as described above. But if
@code{load-path} has any other value at the end of dumping, that value
is used for execution of the dumped Emacs also.
Therefore, if you want to change @code{load-path} temporarily for
loading a few libraries in @file{site-init.el} or @file{site-load.el},
you should bind @code{load-path} locally with @code{let} around the
calls to @code{load}.
The default value of @code{load-path}, when running an Emacs which has
been installed on the system, includes two special directories (and
their subdirectories as well):
@smallexample @smallexample
"/usr/local/share/emacs/@var{version}/site-lisp" "/usr/local/share/emacs/@var{version}/site-lisp"
...@@ -319,33 +279,42 @@ and ...@@ -319,33 +279,42 @@ and
@noindent @noindent
The first one is for locally installed packages for a particular Emacs The first one is for locally installed packages for a particular Emacs
version; the second is for locally installed packages meant for use with version; the second is for locally installed packages meant for use
all installed Emacs versions. with all installed Emacs versions.
There are several reasons why a Lisp package that works well in one
Emacs version can cause trouble in another. Sometimes packages need
updating for incompatible changes in Emacs; sometimes they depend on
undocumented internal Emacs data that can change without notice;
sometimes a newer Emacs version incorporates a version of the package,
and should be used only with that version.
Emacs finds these directories' subdirectories and adds them to
@code{load-path} when it starts up. Both immediate subdirectories and
subdirectories multiple levels down are added to @code{load-path}.
Not all subdirectories are included, though. Subdirectories whose
names do not start with a letter or digit are excluded. Subdirectories
named @file{RCS} or @file{CVS} are excluded. Also, a subdirectory which
contains a file named @file{.nosearch} is excluded. You can use these
methods to prevent certain subdirectories of the @file{site-lisp}
directories from being searched.
If you run Emacs from the directory where it was built---that is, an If you run Emacs from the directory where it was built---that is, an
executable that has not been formally installed---then @code{load-path} executable that has not been formally installed---Emacs puts two more
normally contains two additional directories. These are the @code{lisp} directories in @code{load-path}. These are the @code{lisp} and
and @code{site-lisp} subdirectories of the main build directory. (Both @code{site-lisp} subdirectories of the main build directory. (Both
are represented as absolute file names.) are represented as absolute file names.)
Next, Emacs ``expands'' the initial list of directories in
@code{load-path} by adding the subdirectories of those directories.
Both immediate subdirectories and subdirectories multiple levels down
are added. But it excludes subdirectories whose names do not start
with a letter or digit, and subdirectories named @file{RCS} or
@file{CVS}, and subdirectories containing a file named
@file{.nosearch}.
Next, Emacs adds any extra load directory that you specify using the
@samp{-L} command-line option (@pxref{Action Arguments,,,emacs, The
GNU Emacs Manual}). It also adds the directories where optional
packages are installed, if any (@pxref{Packaging Basics}).
It is common to add code to one's init file (@pxref{Init File}) to
add one or more directories to @code{load-path}. For example:
@smallexample
(push "~/.emacs.d/lisp" load-path)
@end smallexample
Dumping Emacs uses a special value of @code{load-path}. If the
value of @code{load-path} at the end of dumping is unchanged (that is,
still the same special value), the dumped Emacs switches to the
ordinary @code{load-path} value when it starts up, as described above.
But if @code{load-path} has any other value at the end of dumping,
that value is used for execution of the dumped Emacs also.
@deffn Command locate-library library &optional nosuffix path interactive-call @deffn Command locate-library library &optional nosuffix path interactive-call
This command finds the precise file name for library @var{library}. It This command finds the precise file name for library @var{library}. It
searches for the library in the same way @code{load} does, and the searches for the library in the same way @code{load} does, and the
...@@ -401,30 +370,26 @@ example) is read without decoding, the text of the program will be ...@@ -401,30 +370,26 @@ example) is read without decoding, the text of the program will be
unibyte text, and its string constants will be unibyte strings. unibyte text, and its string constants will be unibyte strings.
@xref{Coding Systems}. @xref{Coding Systems}.
The reason Emacs is designed this way is so that Lisp programs give In most Emacs Lisp programs, the fact that non-@acronym{ASCII}
predictable results, regardless of how Emacs was started. In addition, strings are multibyte strings should not be noticeable, since
this enables programs that depend on using multibyte text to work even inserting them in unibyte buffers converts them to unibyte
in a unibyte Emacs. automatically. However, if this does make a difference, you can force
a particular Lisp file to be interpreted as unibyte by writing
In most Emacs Lisp programs, the fact that non-@acronym{ASCII} strings are @samp{-*-unibyte: t;-*-} in a comment on the file's first line. With
multibyte strings should not be noticeable, since inserting them in that designator, the file will unconditionally be interpreted as
unibyte buffers converts them to unibyte automatically. However, if unibyte, even in an ordinary multibyte Emacs session. This can matter
this does make a difference, you can force a particular Lisp file to be when making keybindings to non-@acronym{ASCII} characters written as
interpreted as unibyte by writing @samp{-*-unibyte: t;-*-} in a @code{?v@var{literal}}.
comment on the file's first line. With that designator, the file will
unconditionally be interpreted as unibyte, even in an ordinary
multibyte Emacs session. This can matter when making keybindings to
non-@acronym{ASCII} characters written as @code{?v@var{literal}}.
@node Autoload @node Autoload
@section Autoload @section Autoload
@cindex autoload @cindex autoload
The @dfn{autoload} facility allows you to make a function or macro The @dfn{autoload} facility allows you to register the existence of
known in Lisp, but put off loading the file that defines it. The first a function or macro, but put off loading the file that defines it.
call to the function automatically reads the proper file to install the The first call to the function automatically reads the proper file, in
real definition and other associated code, then runs the real definition order to install the real definition and other associated code, then
as if it had been loaded all along. runs the real definition as if it had been loaded all along.
There are two ways to set up an autoloaded function: by calling There are two ways to set up an autoloaded function: by calling
@code{autoload}, and by writing a special ``magic'' comment in the @code{autoload}, and by writing a special ``magic'' comment in the
......
...@@ -707,12 +707,19 @@ it is displayed along with the global value." ...@@ -707,12 +707,19 @@ it is displayed along with the global value."
(with-current-buffer standard-output (with-current-buffer standard-output
(setq val-start-pos (point)) (setq val-start-pos (point))
(princ "value is ") (princ "value is ")
(let ((from (point))) (let ((from (point))
(terpri) (line-beg (line-beginning-position))
(pp val) ;;
(if (< (point) (+ 68 (line-beginning-position 0))) (print-rep
(delete-region from (1+ from)) (let ((print-quoted t))
(delete-region (1- from) from)) (prin1-to-string val))))
(if (< (+ (length print-rep) (point) (- line-beg)) 68)
(insert print-rep)
(terpri)
(pp val)
(if (< (point) (+ 68 (line-beginning-position 0)))
(delete-region from (1+ from))
(delete-region (1- from) from)))
(let* ((sv (get variable 'standard-value)) (let* ((sv (get variable 'standard-value))
(origval (and (consp sv) (origval (and (consp sv)
(condition-case nil (condition-case nil
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment