Misc manual updates.

* doc/emacs/package.texi (Package Installation): Document use of
package-initialize in init file.

* doc/lispref/os.texi (Startup Summary): Mention package loading.
(Init File): Don't refer to .emacs in section title.  Copyedits.
(Terminal-Specific): Give a realistic example.
(Command-Line Arguments): Reference Entering Emacs instead of
repeating the spiel about not restarting Emacs.
(Time of Day): Discuss time representation at beginning of node.
(Sound Output): Copyedits.

* doc/lispref/package.texi (Packaging Basics): Document package-initialize.

5 files changed, 165 insertions, 127 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 2d03bae1a1b..f5ccba1005f 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,8 @@
+2012-03-17  Chong Yidong  <cyd@gnu.org>
+
+        * package.texi (Package Installation): Document use of
+        package-initialize in init file.
+
 2012-03-16  Glenn Morris  <rgm@gnu.org>
 
         * help.texi (Language Help):
diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi
index 7e2aa20d52e..91b25cfa00e 100644
--- a/doc/emacs/package.texi
+++ b/doc/emacs/package.texi
@@ -157,25 +157,38 @@ directory name of the package archive.  You can alter this list if you
 wish to use third party package archives---but do so at your own risk,
 and use only third parties that you think you can trust!
 
-  Once a package is downloaded and installed, it takes effect in the
-current Emacs session.  What ``taking effect'' means depends on the
-package; most packages just make some new commands available, while
-others have more wide-ranging effects on the Emacs session.  For such
-information, consult the package's help buffer.
-
-  By default, Emacs also automatically loads all installed packages
-(causing them to ``take effect'') in subsequent Emacs sessions.  This
-happens at startup, after processing the init file (@pxref{Init
-File}).  As an exception, Emacs does not load packages at startup if
-invoked with the @samp{-q} or @samp{--no-init-file} options
-(@pxref{Initial Options}).
+  Once a package is downloaded and installed, it is @dfn{loaded} into
+the current Emacs session.  Loading a package is not quite the same as
+loading a Lisp library (@pxref{Lisp Libraries}); its effect varies
+from package to package.  Most packages just make some new commands
+available, while others have more wide-ranging effects on the Emacs
+session.  For such information, consult the package's help buffer.
+
+  By default, Emacs also automatically loads all installed packages in
+subsequent Emacs sessions.  This happens at startup, after processing
+the init file (@pxref{Init File}).  As an exception, Emacs does not
+load packages at startup if invoked with the @samp{-q} or
+@samp{--no-init-file} options (@pxref{Initial Options}).
 
 @vindex package-enable-at-startup
-@findex package-initialize
   To disable automatic package loading, change the variable
-@code{package-enable-at-startup} to @code{nil}.  If you do this, you
-can use the command @kbd{M-x package-initialize} to load your
-packages.
+@code{package-enable-at-startup} to @code{nil}.
+
+@findex package-initialize
+  The reason automatic package loading occurs after loading the init
+file is that user options only receive their customized values after
+loading the init file, including user options which affect the
+packaging system.  In some circumstances, you may want to load
+packages explicitly in your init file (usually because some other code
+in your init file depends on a package).  In that case, your init file
+should call the function @code{package-initialize}.  It is up to you
+to ensure that relevant user options, such as @code{package-load-list}
+(see below), are set up prior to the @code{package-initialize} call.
+You should also set @code{package-enable-at-startup} to @code{nil}, to
+avoid loading the packages again after processing the init file.
+Alternatively, you may choose to completely inhibit package loading at
+startup, and invoke the command @kbd{M-x package-initialize} to load
+your packages manually.
 
 @vindex package-load-list
   For finer control over package loading, you can use the variable
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index b1138e8363d..64b17ad420d 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,15 @@
+2012-03-17  Chong Yidong  <cyd@gnu.org>
+
+        * os.texi (Startup Summary): Mention package loading.
+        (Init File): Don't refer to .emacs in section title.  Copyedits.
+        (Terminal-Specific): Give a realistic example.
+        (Command-Line Arguments): Reference Entering Emacs instead of
+        repeating the spiel about not restarting Emacs.
+        (Time of Day): Discuss time representation at beginning of node.
+        (Sound Output): Copyedits.
+
+        * package.texi (Packaging Basics): Document package-initialize.
+
 2012-03-17  Eli Zaretskii  <eliz@gnu.org>
 
         * frames.texi (Initial Parameters): Add an index entry for
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index f7df5f4bf87..8b158e602fd 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -127,6 +127,11 @@ It loads your abbrevs from the file specified by
 (@pxref{Abbrev Files, abbrev-file-name}).  This is not done if the
 option @samp{--batch} was specified.
 
+@item
+If @code{package-enable-at-startup} is non-@code{nil}, it calls the
+function @code{package-initialize} to activate any optional Emacs Lisp
+package that has been installed.  @xref{Packaging Basics}.
+
 @vindex after-init-time
 @item
 It sets the variable @code{after-init-time} to the value of
@@ -242,9 +247,10 @@ is @code{nil}, the @samp{*scratch*} buffer is empty.
 @end defopt
 
 @node Init File
-@subsection The Init File, @file{.emacs}
+@subsection The Init File
 @cindex init file
 @cindex @file{.emacs}
+@cindex @file{init.el}
 
   When you start Emacs, it normally attempts to load your @dfn{init
 file}.  This is either a file named @file{.emacs} or @file{.emacs.el}
@@ -267,13 +273,13 @@ file.  If those environment variables are absent, though, Emacs uses
 your user-id to find your home directory.
 
 @cindex default init file
-  A site may have a @dfn{default init file}, which is the library
-named @file{default.el}.  Emacs finds the @file{default.el} file
-through the standard search path for libraries (@pxref{How Programs Do
-Loading}).  The Emacs distribution does not come with this file; sites
-may provide one for local customizations.  If the default init file
-exists, it is loaded whenever you start Emacs, except in batch mode or
-if @samp{-q} (or @samp{-Q}) is specified.  But your own personal init
+  An Emacs installation may have a @dfn{default init file}, which is a
+Lisp library named @file{default.el}.  Emacs finds this file through
+the standard search path for libraries (@pxref{How Programs Do
+Loading}).  The Emacs distribution does not come with this file; it is
+intended for local customizations.  If the default init file exists,
+it is loaded whenever you start Emacs, except in batch mode or if
+@samp{-q} (or @samp{-Q}) is specified.  But your own personal init
 file, if any, is loaded first; if it sets @code{inhibit-default-init}
 to a non-@code{nil} value, then Emacs does not subsequently load the
 @file{default.el} file.
@@ -343,23 +349,22 @@ in the normal manner, by searching the @code{load-path} directories, and
 trying the @samp{.elc} and @samp{.el} suffixes.
 
 @cindex Termcap
-  The usual function of a terminal-specific library is to enable
-special keys to send sequences that Emacs can recognize.  It may also
-need to set or add to @code{input-decode-map} if the Termcap or
-Terminfo entry does not specify all the terminal's function keys.
-@xref{Terminal Input}.
+  The usual role of a terminal-specific library is to enable special
+keys to send sequences that Emacs can recognize.  It may also need to
+set or add to @code{input-decode-map} if the Termcap or Terminfo entry
+does not specify all the terminal's function keys.  @xref{Terminal
+Input}.
 
   When the name of the terminal type contains a hyphen, and no library
 is found whose name is identical to the terminal's name, Emacs strips
 from the terminal's name the last hyphen and everything that follows
 it, and tries again.  This process is repeated until Emacs finds a
-matching library or until there are no more hyphens in the name (the
-latter means the terminal doesn't have any library specific to it).
-Thus, for example, if there are no @samp{aaa-48} and @samp{aaa-30}
-libraries, Emacs will try the same library @file{term/aaa.el} for
-terminal types @samp{aaa-48} and @samp{aaa-30-rv}.  If necessary, the
-library can evaluate @code{(getenv "TERM")} to find the full name of
-the terminal type.@refill
+matching library, or until there are no more hyphens in the name
+(i.g.@: there is no terminal-specific library).  For example, if the
+terminal name is @samp{xterm-256color} and there is no
+@file{term/xterm-256color.el} library, Emacs tries to load
+@file{term/xterm.el}.  If necessary, the terminal library can evaluate
+@code{(getenv "TERM")} to find the full name of the terminal type.
 
   Your init file can prevent the loading of the
 terminal-specific library by setting the variable
@@ -376,8 +381,8 @@ have their own libraries.  @xref{Hooks}.
 
 @defvar term-file-prefix
 @cindex @code{TERM} environment variable
-If the @code{term-file-prefix} variable is non-@code{nil}, Emacs loads
-a terminal-specific initialization file as follows:
+If the value of this variable is non-@code{nil}, Emacs loads a
+terminal-specific initialization file as follows:
 
 @example
 (load (concat term-file-prefix (getenv "TERM")))
@@ -409,29 +414,14 @@ feature.
 @subsection Command-Line Arguments
 @cindex command-line arguments
 
-  You can use command-line arguments to request various actions when you
-start Emacs.  Since you do not need to start Emacs more than once per
-day, and will often leave your Emacs session running longer than that,
-command-line arguments are hardly ever used.  As a practical matter, it
-is best to avoid making the habit of using them, since this habit would
-encourage you to kill and restart Emacs unnecessarily often.  These
-options exist for two reasons: to be compatible with other editors (for
-invocation by other programs) and to enable shell scripts to run
-specific Lisp programs.
-
-  This section describes how Emacs processes command-line arguments,
-and how you can customize them.
-
-@ignore
-  (Note that some other editors require you to start afresh each time
-you want to edit a file.  With this kind of editor, you will probably
-specify the file as a command-line argument.  The recommended way to
-use GNU Emacs is to start it only once, just after you log in, and do
-all your editing in the same Emacs process.  Each time you want to edit
-a different file, you visit it with the existing Emacs, which eventually
-comes to have many files in it ready for editing.  Usually you do not
-kill the Emacs until you are about to log out.)
-@end ignore
+  You can use command-line arguments to request various actions when
+you start Emacs.  Command-line arguments should not be commonly used,
+since the recommended way of using Emacs is to start it just once,
+after logging in, and do all editing in the same Emacs session
+(@pxref{Entering Emacs,,, emacs, The GNU Emacs Manual}); nonetheless,
+they can be useful when invoking Emacs from session scripts or
+debugging Emacs itself.  This section describes how Emacs processes
+command-line arguments.
 
 @defun command-line
 This function parses the command line that Emacs was called with,
@@ -525,9 +515,7 @@ as a file name to visit.
 
   There are two ways to get out of Emacs: you can kill the Emacs job,
 which exits permanently, or you can suspend it, which permits you to
-reenter the Emacs process later.  As a practical matter, you seldom kill
-Emacs---only when you are about to log out.  Suspending is much more
-common.
+reenter the Emacs process later.
 
 @menu
 * Killing Emacs::        Exiting Emacs irreversibly.
@@ -1105,24 +1093,47 @@ The value may be a floating point number.
 @node Time of Day
 @section Time of Day
 
-  This section explains how to determine the current time and the time
+  This section explains how to determine the current time and time
 zone.
 
+@cindex epoch
+  Most of these functions represent time as a list of either three
+integers, @code{(@var{sec-high} @var{sec-low} @var{microsec})}, or of
+two integers, @code{(@var{sec-high} @var{sec-low})}.  The integers
+@var{sec-high} and @var{sec-low} give the high and low bits of an
+integer number of seconds.  This integer number,
+@ifnottex
+@var{high} * 2**16 + @var{low},
+@end ifnottex
+@tex
+$high*2^{16}+low$,
+@end tex
+is the number of seconds from the @dfn{epoch} (0:00 January 1, 1970
+UTC) to the specified time.  The third list element @var{microsec}, if
+present, gives the number of microseconds from the start of that
+second to the specified time.
+
+  The return value of @code{current-time} represents time using three
+integers, while the timestamps in the return value of
+@code{file-attributes} use two integers (@pxref{Definition of
+file-attributes}).  In function arguments, e.g.@: the @var{time-value}
+argument to @code{current-time-string}, both two- and three-integer
+lists are accepted.  You can convert times from the list
+representation into standard human-readable strings using
+@code{current-time}, or to other forms using the @code{decode-time}
+and @code{format-time-string} functions documented in the following
+sections.
+
 @defun current-time-string &optional time-value
 This function returns the current time and date as a human-readable
-string.  The format of the string is unvarying; the number of characters
-used for each part is always the same, so you can reliably use
-@code{substring} to extract pieces of it.  It is wise to count the
-characters from the beginning of the string rather than from the end, as
-additional information may some day be added at the end.
+string.  The format of the string is unvarying; the number of
+characters used for each part is always the same, so you can reliably
+use @code{substring} to extract pieces of it.  You should count
+characters from the beginning of the string rather than from the end,
+as additional information may some day be added at the end.
 
 The argument @var{time-value}, if given, specifies a time to format
-instead of the current time.  This argument should have the same form
-as the times obtained from @code{current-time} (see below) and from
-@code{file-attributes} (@pxref{Definition of file-attributes}).  It
-should be a list whose first two elements are integers; a third
-(microsecond) element, if present, is ignored.  @var{time-value} can
-also be a cons of two integers, but this usage is obsolete.
+(represented as a list of integers), instead of the current time.
 
 @example
 @group
@@ -1133,33 +1144,16 @@ also be a cons of two integers, but this usage is obsolete.
 @end defun
 
 @defun current-time
-This function returns the system's time value as a list of three
-integers: @code{(@var{high} @var{low} @var{microsec})}.  The integers
-@var{high} and @var{low} combine to give the number of seconds since
-0:00 January 1, 1970 UTC (Coordinated Universal Time), which is
-@ifnottex
-@var{high} * 2**16 + @var{low}.
-@end ifnottex
-@tex
-$high*2^{16}+low$.
-@end tex
-
-The third element, @var{microsec}, gives the microseconds since the
-start of the current second (or 0 for systems that return time with
-the resolution of only one second).
-
-The first two elements can be compared with file time values such as you
-get with the function @code{file-attributes}.
-@xref{Definition of file-attributes}.
+This function returns the current time, represented as a list of three
+integers @code{(@var{sec-high} @var{sec-low} @var{microsec})}.  On
+systems with only one-second time resolutions, @var{microsec} is 0.
 @end defun
 
 @defun float-time &optional time-value
 This function returns the current time as a floating-point number of
-seconds since the epoch.  The argument @var{time-value}, if given,
-specifies a time to convert instead of the current time.  The argument
-should have the same form as for @code{current-time-string} (see
-above).  Thus, it accepts the output of @code{current-time} and
-@code{file-attributes} (@pxref{Definition of file-attributes}).
+seconds since the epoch.  The optional argument @var{time-value}, if
+given, specifies a time (represented as a list of integers) to convert
+instead of the current time.
 
 @emph{Warning}: Since the result is floating point, it may not be
 exact.  Do not use this function if precise time stamps are required.
@@ -1180,11 +1174,8 @@ adjustment, then the value is constant through time.
 If the operating system doesn't supply all the information necessary to
 compute the value, the unknown elements of the list are @code{nil}.
 
-The argument @var{time-value}, if given, specifies a time to analyze
-instead of the current time.  The argument should have the same form
-as for @code{current-time-string} (see above).  Thus, you can use
-times obtained from @code{current-time} (see above) and from
-@code{file-attributes}.  @xref{Definition of file-attributes}.
+The argument @var{time-value}, if given, specifies a time (represented
+as a list of integers) to analyze instead of the current time.
 @end defun
 
 The current time zone is determined by the @samp{TZ} environment
@@ -1196,16 +1187,15 @@ time zone.
 @node Time Conversion
 @section Time Conversion
 
-  These functions convert time values (lists of two or three integers)
-to calendrical information and vice versa.  You can get time values
-from the functions @code{current-time} (@pxref{Time of Day}) and
-@code{file-attributes} (@pxref{Definition of file-attributes}).
+  These functions convert time values (lists of two or three integers,
+as explained in the previous section) into calendrical information and
+vice versa.
 
-  Many 32-bit operating systems are limited to time values that contain 32 bits
-of information; these systems typically handle only the times from
-1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC.  However, 64-bit
-and some 32-bit operating systems have larger time values, and can
-represent times far in the past or future.
+  Many 32-bit operating systems are limited to time values containing
+32 bits of information; these systems typically handle only the times
+from 1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC.
+However, 64-bit and some 32-bit operating systems have larger time
+values, and can represent times far in the past or future.
 
   Time conversion functions always use the Gregorian calendar, even
 for dates before the Gregorian calendar was introduced.  Year numbers
@@ -2014,9 +2004,8 @@ See also @code{open-dribble-file} in @ref{Recording Input}.
 @cindex sound
 
   To play sound using Emacs, use the function @code{play-sound}.  Only
-certain systems are supported; if you call @code{play-sound} on a system
-which cannot really do the job, it gives an error.  Emacs version 20 and
-earlier did not support sound at all.
+certain systems are supported; if you call @code{play-sound} on a
+system which cannot really do the job, it gives an error.
 
   The sound must be stored as a file in RIFF-WAVE format (@samp{.wav})
 or Sun Audio format (@samp{.au}).
diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi
index eb3612dc868..b17f13b6b89 100644
--- a/doc/lispref/package.texi
+++ b/doc/lispref/package.texi
@@ -15,6 +15,8 @@ install, uninstall, and upgrade it.
 
   The following sections describe how to create a package, and how to
 put it in a @dfn{package archive} for others to download.
+@xref{Packages,,, emacs, The GNU Emacs Manual}, for a description of
+user-level features of the packaging system.
 
 @menu
 * Packaging Basics::        The basic concepts of Emacs Lisp packages.
@@ -91,17 +93,34 @@ definitions are saved to a file named @file{@var{name}-autoloads.el}
 in the content directory.  They are typically used to autoload the
 principal user commands defined in the package, but they can also
 perform other tasks, such as adding an element to
-@code{auto-mode-alist} (@pxref{Auto Major Mode}).  During this time,
-Emacs will also byte-compile the Lisp files.
-
-  After installation, and (by default) each time Emacs is started, the
-installed package is @dfn{activated}.  During activation, Emacs adds
-the package's content directory to @code{load-path}, and evaluates the
-autoload definitions in @file{@var{name}-autoloads.el}.
-
-  Note that a package typically does @emph{not} autoload every
-function and variable defined within it---only the handful of commands
-typically called to begin using the package.
+@code{auto-mode-alist} (@pxref{Auto Major Mode}).  Note that a package
+typically does @emph{not} autoload every function and variable defined
+within it---only the handful of commands typically called to begin
+using the package.  Emacs then byte-compiles every Lisp file in the
+package.
+
+  After installation, the installed package is @dfn{loaded}: Emacs
+adds the package's content directory to @code{load-path}, and
+evaluates the autoload definitions in @file{@var{name}-autoloads.el}.
+
+  Whenever Emacs starts up, it automatically calls the function
+@code{package-initialize} to load installed packages.  This is done
+after loading the init file and abbrev file (if any) and before
+running @code{after-init-hook} (@pxref{Startup Summary}).  Automatic
+package loading is disabled if the user option
+@code{package-enable-at-startup} is @code{nil}.
+
+@deffn Command package-initialize &optional no-activate
+This function initializes Emacs' internal record of which packages are
+installed, and loads them.  The user option @code{package-load-list}
+specifies which packages to load; by default, all installed packages
+are loaded.  @xref{Package Installation,,, emacs, The GNU Emacs
+Manual}.
+
+The optional argument @var{no-activate}, if non-@code{nil}, causes
+Emacs to update its record of installed packages without actually
+loading them; it is for internal use only.
+@end deffn
 
 @node Simple Packages
 @section Simple Packages