[Emacs-diffs] /srv/bzr/emacs/trunk r107224: Update Loading chapter of Emacs manual.

[Chong Yidong]

------------------------------------------------------------
revno: 107224
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Fri 2012-02-10 15:57:21 +0800
message:
  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.
modified:
  admin/FOR-RELEASE
  doc/lispref/ChangeLog
  doc/lispref/loading.texi
  lisp/help-fns.el

=== modified file 'admin/FOR-RELEASE'
--- a/admin/FOR-RELEASE 2012-02-08 02:05:02 +0000
+++ b/admin/FOR-RELEASE 2012-02-10 07:57:21 +0000
@@ -206,7 +206,7 @@
 intro.texi        cyd
 keymaps.texi      
 lists.texi        cyd
-loading.texi      
+loading.texi      cyd
 locals.texi       
 macros.texi       cyd
 maps.texi         

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-02-10 02:33:01 +0000
+++ b/doc/lispref/ChangeLog     2012-02-10 07:57:21 +0000
@@ -1,3 +1,12 @@
+2012-02-10  Chong Yidong  <address@hidden>
+
+       * 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  <address@hidden>
 
        * modes.texi (Basic Major Modes): Mention tabulated-list-mode.

=== modified file 'doc/lispref/loading.texi'
--- a/doc/lispref/loading.texi  2012-02-08 05:29:16 +0000
+++ b/doc/lispref/loading.texi  2012-02-10 07:57:21 +0000
@@ -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 @@
 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 @@
 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
address@hidden, you can prevent perverse file names such as
address@hidden from being tried.
address@hidden, you can prevent file names like @file{foo.el.el} from
+being tried.
 
 If the optional argument @var{must-suffix} is address@hidden, then
 @code{load} insists that the file name used must end in either
@@ -238,73 +234,37 @@
   When Emacs loads a Lisp library, it searches for the library
 in a list of directories specified by the variable @code{load-path}.
 
address@hidden load-path
address@hidden 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).
address@hidden 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};
address@hidden:} (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:
-
address@hidden
-setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
address@hidden smallexample
-
-  Here is how to set it using @code{sh}:
address@hidden defvar
+
+  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
address@hidden;}, on some operating systems), and @samp{.} stands for the
+current default directory.  Here is an example of how to set
address@hidden variable from @command{sh}:
 
 @smallexample
 export EMACSLOADPATH
-EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
address@hidden 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
address@hidden:
-
address@hidden
address@hidden
-(setq load-path
-      (append (list nil "/user/bil/emacs"
-                    "/usr/local/lisplib"
-                    "~/emacs")
-              load-path))
address@hidden group
address@hidden smallexample
-
address@hidden Wordy to rid us of an overfull hbox.  --rjc 15mar92
+EMACSLOADPATH=/home/foo/.emacs.d/lisp:/opt/emacs/lisp
address@hidden smallexample
+
 @noindent
-In this example, the path searches the current working directory first,
-followed then by the @file{/user/bil/emacs} directory, the
address@hidden/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
address@hidden at the end of dumping is unchanged (that is, still the
-same special value), the dumped Emacs switches to the ordinary
address@hidden value when it starts up, as described above.  But if
address@hidden 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):
+Here is how to set it from @code{csh}:
+
address@hidden
+setenv EMACSLOADPATH /home/foo/.emacs.d/lisp:/opt/emacs/lisp
address@hidden smallexample
+
+  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 @@
 
 @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
address@hidden 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
address@hidden subdirectories of the main build directory.  (Both
 are represented as absolute file names.)
 
+  Next, Emacs ``expands'' the initial list of directories in
address@hidden 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
address@hidden, and subdirectories containing a file named
address@hidden
+
+  Next, Emacs adds any extra load directory that you specify using the
address@hidden 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:
+
address@hidden
+(push "~/.emacs.d/lisp" load-path)
address@hidden 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 @@
 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 address@hidden 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
address@hidden characters written as @address@hidden
+  In most Emacs Lisp programs, the fact that address@hidden
+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
address@hidden: 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 address@hidden characters written as
address@hidden@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

=== modified file 'lisp/help-fns.el'
--- a/lisp/help-fns.el  2012-01-19 07:21:25 +0000
+++ b/lisp/help-fns.el  2012-02-10 07:57:21 +0000
@@ -707,12 +707,19 @@
              (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