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.

4 files changed, 92 insertions, 111 deletions

diff --git a/admin/FOR-RELEASE b/admin/FOR-RELEASE
index e2ce5c59ff3..58662acb604 100644
--- a/admin/FOR-RELEASE
+++ b/admin/FOR-RELEASE
@@ -206,7 +206,7 @@ internals.texi
 intro.texi        cyd
 keymaps.texi      
 lists.texi        cyd
-loading.texi      
+loading.texi      cyd
 locals.texi       
 macros.texi       cyd
 maps.texi         
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index a823f4272fc..9e6ecdec16a 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,12 @@
+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>
 
         * modes.texi (Basic Major Modes): Mention tabulated-list-mode.
diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index 0b822751df6..3c2fa60248e 100644
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -10,9 +10,10 @@
 @cindex library
 @cindex Lisp library
 
-  Loading a file of Lisp code means bringing its contents into the Lisp
-environment in the form of Lisp objects.  Emacs finds and opens the
-file, reads the text, evaluates each form, and then closes the file.
+  Loading a file of Lisp code means bringing its contents into the
+Lisp environment in the form of Lisp objects.  Emacs finds and opens
+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
 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
 way.)  Most often, the forms are function definitions and variable
 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
 * How Programs Do Loading:: The @code{load} function and others.
 * 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
 that, if Auto Compression mode is enabled, @code{load} will still use
 @code{jka-compr-load-suffixes} to find compressed versions.  By
 specifying the precise file name and using @code{t} for
-@var{nosuffix}, you can prevent perverse file names such as
-@file{foo.el.el} from being tried.
+@var{nosuffix}, you can prevent file names like @file{foo.el.el} from
+being tried.
 
 If the optional argument @var{must-suffix} is non-@code{nil}, then
 @code{load} insists that the file name used must end in either
@@ -238,73 +234,37 @@ it skips the latter group.
   When Emacs loads a Lisp library, it searches for the library
 in a list of directories specified by the variable @code{load-path}.
 
-@defopt load-path
+@defvar load-path
 @cindex @code{EMACSLOADPATH} environment variable
 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
 a directory name) or @code{nil} (which stands for the current working
 directory).
-@end defopt
-
-  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
+@end defvar
 
-  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
 export EMACSLOADPATH
-EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
+EMACSLOADPATH=/home/foo/.emacs.d/lisp:/opt/emacs/lisp
 @end smallexample
 
-  Here is an example of code you can place in your init file (@pxref{Init
-File}) to add several directories to the front of your default
-@code{load-path}:
+@noindent
+Here is how to set it from @code{csh}:
 
 @smallexample
-@group
-(setq load-path
-      (append (list nil "/user/bil/emacs"
-                    "/usr/local/lisplib"
-                    "~/emacs")
-              load-path))
-@end group
+setenv EMACSLOADPATH /home/foo/.emacs.d/lisp:/opt/emacs/lisp
 @end smallexample
 
-@c Wordy to rid us of an overfull hbox.  --rjc 15mar92
-@noindent
-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):
+  If @env{EMACSLOADPATH} is not set (which is usually the case), Emacs
+initializes @code{load-path} with the following two directories:
 
 @smallexample
 "/usr/local/share/emacs/@var{version}/site-lisp"
@@ -319,33 +279,42 @@ and
 
 @noindent
 The first one is for locally installed packages for a particular Emacs
-version; the second is for locally installed packages meant for use 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.
+version; the second is for locally installed packages meant for use
+with all installed Emacs versions.
 
   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}
-normally contains two additional directories.  These are the @code{lisp}
-and @code{site-lisp} subdirectories of the main build directory.  (Both
+executable that has not been formally installed---Emacs puts two more
+directories in @code{load-path}.  These are the @code{lisp} and
+@code{site-lisp} subdirectories of the main build directory.  (Both
 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
 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
@@ -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.
 @xref{Coding Systems}.
 
-  The reason Emacs is designed this way is so that Lisp programs give
-predictable results, regardless of how Emacs was started.  In addition,
-this enables programs that depend on using multibyte text to work even
-in a unibyte Emacs.
-
-  In most Emacs Lisp programs, the fact that non-@acronym{ASCII} strings are
-multibyte strings should not be noticeable, since inserting them in
-unibyte buffers converts them to unibyte automatically.  However, if
-this does make a difference, you can force a particular Lisp file to be
-interpreted as unibyte by writing @samp{-*-unibyte: t;-*-} in a
-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}}.
+  In most Emacs Lisp programs, the fact that non-@acronym{ASCII}
+strings are multibyte strings should not be noticeable, since
+inserting them in unibyte buffers converts them to unibyte
+automatically.  However, if this does make a difference, you can force
+a particular Lisp file to be interpreted as unibyte by writing
+@samp{-*-unibyte: t;-*-} in a 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
 @section Autoload
 @cindex autoload
 
-  The @dfn{autoload} facility allows you to make a function or macro
-known in Lisp, but put off loading the file that defines it.  The first
-call to the function automatically reads the proper file to install the
-real definition and other associated code, then runs the real definition
-as if it had been loaded all along.
+  The @dfn{autoload} facility allows you to register the existence of
+a function or macro, but put off loading the file that defines it.
+The first call to the function automatically reads the proper file, in
+order to install the real definition and other associated code, then
+runs the real definition as if it had been loaded all along.
 
   There are two ways to set up an autoloaded function: by calling
 @code{autoload}, and by writing a special ``magic'' comment in the
diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index 183253878f5..0175ffa4d9a 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -707,12 +707,19 @@ it is displayed along with the global value."
               (with-current-buffer standard-output
                 (setq val-start-pos (point))
                 (princ "value is ")
-                (let ((from (point)))
-                  (terpri)
-                  (pp val)
-                  (if (< (point) (+ 68 (line-beginning-position 0)))
-                      (delete-region from (1+ from))
-                    (delete-region (1- from) from))
+                (let ((from (point))
+                      (line-beg (line-beginning-position))
+                      ;;
+                      (print-rep
+                       (let ((print-quoted t))
+                         (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))
                          (origval (and (consp sv)
                                        (condition-case nil