upstream

12 files changed, 497 insertions, 363 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 5a1d1394b23..f5ccba1005f 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,18 @@
+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):
+        * mule.texi (International Chars):
+        etc/HELLO is for character demonstration.
+
+2012-03-15  Dani Moncayo  <dmoncayo@gmail.com>  (tiny change)
+
+        * dired.texi (Shell Commands in Dired): Fix typo.
+
 2012-03-04  Chong Yidong  <cyd@gnu.org>
 
         * killing.texi (Clipboard): Document clipboard manager.
diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi
index e048237a4e2..7dd290939fe 100644
--- a/doc/emacs/dired.texi
+++ b/doc/emacs/dired.texi
@@ -823,9 +823,9 @@ replaces each occurrence.
 
 @item
 If the command string contains neither @samp{*} nor @samp{?}, Emacs
-runs the shell command once for each file, adding the file name is
-added at the end.  For example, @kbd{! uudecode @key{RET}} runs
-@code{uudecode} on each file.
+runs the shell command once for each file, adding the file name at the
+end.  For example, @kbd{! uudecode @key{RET}} runs @code{uudecode} on
+each file.
 @end itemize
 
   To iterate over the file names in a more complicated fashion, use an
diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index 05a3e546322..84da0a9a681 100644
--- a/doc/emacs/help.texi
+++ b/doc/emacs/help.texi
@@ -464,7 +464,8 @@ listing the associated character sets, coding systems, and input
 methods, as well as some sample text for that language environment.
 
   The command @kbd{C-h h} (@code{view-hello-file}) displays the file
-@file{etc/HELLO}, which shows how to say ``hello'' in many languages.
+@file{etc/HELLO}, which demonstrates various character sets by showing
+how to say ``hello'' in many languages.
 
   The command @kbd{C-h I} (@code{describe-input-method}) describes an
 input method---either a specified input method, or by default the
diff --git a/doc/emacs/mule.texi b/doc/emacs/mule.texi
index aebff1e463a..aeaec2c502e 100644
--- a/doc/emacs/mule.texi
+++ b/doc/emacs/mule.texi
@@ -1,5 +1,5 @@
 @c This is part of the Emacs manual.
-@c Copyright (C) 1997, 1999-2012  Free Software Foundation, Inc.
+@c Copyright (C) 1997, 1999-2012 Free Software Foundation, Inc.
 @c See file emacs.texi for copying conditions.
 @node International, Modes, Frames, Top
 @chapter International Character Set Support
@@ -137,8 +137,8 @@ writing files, and when exchanging data with subprocesses.
 @cindex undisplayable characters
 @cindex @samp{?} in display
   The command @kbd{C-h h} (@code{view-hello-file}) displays the file
-@file{etc/HELLO}, which shows how to say ``hello'' in many languages.
-This illustrates various scripts.  If some characters can't be
+@file{etc/HELLO}, which illustrates various scripts by showing
+how to say ``hello'' in many languages.  If some characters can't be
 displayed on your terminal, they appear as @samp{?} or as hollow boxes
 (@pxref{Undisplayable Characters}).
 
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 3584c89d5fe..43ae349cb4c 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,52 @@
+2012-03-20  Chong Yidong  <cyd@gnu.org>
+
+        * display.texi (Forcing Redisplay): Various rewrites to reflect
+        new value of redisplay-dont-pause.
+        (Truncation): Copyedits.
+
+2012-03-20  Glenn Morris  <rgm@gnu.org>
+
+        * os.texi (Startup Summary): Don't mention initial-buffer-choice = t.
+        Add summary table of some relevant command-line options.
+
+2012-03-18  Chong Yidong  <cyd@gnu.org>
+
+        * internals.texi (Building Emacs, Garbage Collection): Copyedits.
+        (Writing Emacs Primitives): Re-organize discussion of functions
+        with variable Lisp arguments are handled.  Delete an obsolete
+        remark, previously tagged as FIXME.
+
+        * os.texi (Idle Timers): Minor clarification.
+        (Idle Timers): Link to Time of Day for description of time list.
+
+2012-03-18  Glenn Morris  <rgm@gnu.org>
+
+        * os.texi (System Interface): Flow control was removed.
+        (Startup Summary): General update.
+        (Init File): Don't mention compiling it.
+
+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
+        minibuffer-only frame.
+
+2012-03-16  Glenn Morris  <rgm@gnu.org>
+
+        * modes.texi (Major Mode Conventions): Mention the strange
+        relationship between View mode and special modes.  (Bug#10650)
+
 2012-03-11  Chong Yidong  <cyd@gnu.org>
 
         * windows.texi (Window Configurations): save-window-excursion is
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index c70418be52b..b68b0697936 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -86,59 +86,57 @@ attempt to redisplay, in the middle of Lisp code, without actually
 waiting for input.
 
 @defun redisplay &optional force
-This function tries immediately to redisplay, provided there are no
-pending input events.
-
-If the optional argument @var{force} is non-@code{nil}, it does all
-pending redisplay work even if input is available, with no
-pre-emption.
+This function tries immediately to redisplay.  The optional argument
+@var{force}, if non-@code{nil}, forces the redisplay to be performed,
+instead of being preempted, even if input is pending and the variable
+@code{redisplay-dont-pause} is @code{nil} (see below).  If
+@code{redisplay-dont-pause} is non-@code{nil} (the default), this
+function redisplays in any case, i.e.@: @var{force} does nothing.
 
 The function returns @code{t} if it actually tried to redisplay, and
 @code{nil} otherwise.  A value of @code{t} does not mean that
-redisplay proceeded to completion; it could have been pre-empted by
-newly arriving terminal input.
-@end defun
-
-  @code{redisplay} with no argument tries immediately to redisplay,
-but has no effect on the usual rules for what parts of the screen to
-redisplay.  By contrast, the following function adds certain windows
-to the pending redisplay work (as if their contents had completely
-changed), but doesn't immediately try to do any redisplay work.
-
-@defun force-window-update &optional object
-This function forces some or all windows to be updated on next
-redisplay.  If @var{object} is a window, it requires eventual
-redisplay of that window.  If @var{object} is a buffer or buffer name,
-it requires eventual redisplay of all windows displaying that buffer.
-If @var{object} is @code{nil} (or omitted), it requires eventual
-redisplay of all windows.
+redisplay proceeded to completion; it could have been preempted by
+newly arriving input.
 @end defun
 
-  @code{force-window-update} does not do a redisplay immediately.
-(Emacs will do that when it waits for input.)  Rather, its effect is
-to put more work on the queue to be done by redisplay whenever there
-is a chance.
-
 @defvar redisplay-dont-pause
-If this variable is non-@code{nil}, pending input does not prevent or
-halt redisplay; redisplay occurs, and finishes, regardless of whether
-input is available.  If it is @code{nil}, Emacs redisplay stops if
-input arrives, and does not happen at all if input is available before
-it starts.  The default is @code{t}.
+If this variable is @code{nil}, arriving input events preempt
+redisplay; Emacs avoids starting a redisplay, and stops any redisplay
+that is in progress, until the input has been processed.  In
+particular, @code{(redisplay)} returns @code{nil} without actually
+redisplaying, if there is pending input.
+
+The default value is @code{t}, which means that pending input does not
+preempt redisplay.
 @end defvar
 
 @defvar redisplay-preemption-period
-This variable specifies how many seconds Emacs waits between checks
-for new input during redisplay.  (The default is 0.1 seconds.)  If
-input has arrived when Emacs checks, it pre-empts redisplay and
-processes the available input before trying again to redisplay.
+If @code{redisplay-dont-pause} is @code{nil}, this variable specifies
+how many seconds Emacs waits between checks for new input during
+redisplay; if input arrives during this interval, redisplay stops and
+the input is processed.  The default value is 0.1; if the value is
+@code{nil}, Emacs does not check for input during redisplay.
+
+This variable has no effect when @code{redisplay-dont-pause} is
+non-@code{nil} (the default).
+@end defvar
 
-If this variable is @code{nil}, Emacs does not check for input during
-redisplay, and redisplay cannot be preempted by input.
+  Although @code{redisplay} tries immediately to redisplay, it does
+not change how Emacs decides which parts of its frame(s) to redisplay.
+By contrast, the following function adds certain windows to the
+pending redisplay work (as if their contents had completely changed),
+but does not immediately try to perform redisplay.
 
-This variable is only obeyed on graphical terminals.  For
-text terminals, see @ref{Terminal Output}.
-@end defvar
+@defun force-window-update &optional object
+This function forces some or all windows to be updated the next time
+Emacs does a redisplay.  If @var{object} is a window, that window is
+to be updated.  If @var{object} is a buffer or buffer name, all
+windows displaying that buffer are to be updated.  If @var{object} is
+@code{nil} (or omitted), all windows are to be updated.
+
+This function does not do a redisplay immediately; Emacs does that as
+it waits for input, or when the function @code{redisplay} is called.
+@end defun
 
 @node Truncation
 @section Truncation
@@ -169,7 +167,7 @@ If this buffer-local variable is non-@code{nil}, lines that extend
 beyond the right edge of the window are truncated; otherwise, they are
 continued.  As a special exception, the variable
 @code{truncate-partial-width-windows} takes precedence in
-@dfn{partial-width} windows (i.e., windows that do not occupy the
+@dfn{partial-width} windows (i.e.@: windows that do not occupy the
 entire frame width).
 @end defopt
 
@@ -192,37 +190,37 @@ a window, that forces truncation.
 
 @defvar wrap-prefix
 If this buffer-local variable is non-@code{nil}, it defines a
-``prefix'' that is prepended to every continuation line at
-display time.  (If lines are truncated, the wrap-prefix is never
-used.)  It may be a string or an image (@pxref{Other Display Specs}),
-or a stretch of whitespace such as specified by the @code{:width} or
-@code{:align-to} display properties (@pxref{Specified Space}).  The
-value is interpreted in the same way as a @code{display} text
-property.  @xref{Display Property}.
-
-A wrap-prefix may also be specified for regions of text, using the
+@dfn{wrap prefix} which Emacs displays at the start of every
+continuation line.  (If lines are truncated, @code{wrap-prefix} is
+never used.)  Its value may be a string or an image (@pxref{Other
+Display Specs}), or a stretch of whitespace such as specified by the
+@code{:width} or @code{:align-to} display properties (@pxref{Specified
+Space}).  The value is interpreted in the same way as a @code{display}
+text property.  @xref{Display Property}.
+
+A wrap prefix may also be specified for regions of text, using the
 @code{wrap-prefix} text or overlay property.  This takes precedence
 over the @code{wrap-prefix} variable.  @xref{Special Properties}.
 @end defvar
 
 @defvar line-prefix
 If this buffer-local variable is non-@code{nil}, it defines a
-``prefix'' that is prepended to every non-continuation line at
-display time.  It may be a string or an image (@pxref{Other Display
-Specs}), or a stretch of whitespace such as specified by the
-@code{:width} or @code{:align-to} display properties (@pxref{Specified
-Space}).  The value is interpreted in the same way as a @code{display}
-text property.  @xref{Display Property}.
-
-A line-prefix may also be specified for regions of text using the
+@dfn{line prefix} which Emacs displays at the start of every
+non-continuation line.  Its value may be a string or an image
+(@pxref{Other Display Specs}), or a stretch of whitespace such as
+specified by the @code{:width} or @code{:align-to} display properties
+(@pxref{Specified Space}).  The value is interpreted in the same way
+as a @code{display} text property.  @xref{Display Property}.
+
+A line prefix may also be specified for regions of text using the
 @code{line-prefix} text or overlay property.  This takes precedence
 over the @code{line-prefix} variable.  @xref{Special Properties}.
 @end defvar
 
   If your buffer contains @emph{very} long lines, and you use
 continuation to display them, computing the continuation lines can
-make Emacs redisplay slow.  The column computation and indentation
-functions also become slow.  Then you might find it advisable to set
+make redisplay slow.  The column computation and indentation functions
+also become slow.  Then you might find it advisable to set
 @code{cache-long-line-scans} to @code{t}.
 
 @defvar cache-long-line-scans
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index a01ad051489..125d6071cab 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -420,10 +420,11 @@ the initial frame, specify the same parameters in
 @code{initial-frame-alist} with values that match the X resources.
 @end defopt
 
-If these parameters specify a separate minibuffer-only frame with
+If these parameters specify a separate @dfn{minibuffer-only frame} with
 @code{(minibuffer . nil)}, and you have not created one, Emacs creates
 one for you.
 
+@cindex minibuffer-only frame
 @defopt minibuffer-frame-alist
 This variable's value is an alist of parameter values used when
 creating an initial minibuffer-only frame.  This is the
diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index 55b18edf2ec..edf892e751a 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -28,42 +28,39 @@ internal aspects of GNU Emacs that may be of interest to C programmers.
   This section explains the steps involved in building the Emacs
 executable.  You don't have to know this material to build and install
 Emacs, since the makefiles do all these things automatically.  This
-information is pertinent to Emacs maintenance.
+information is pertinent to Emacs developers.
 
    Compilation of the C source files in the @file{src} directory
 produces an executable file called @file{temacs}, also called a
-@dfn{bare impure Emacs}.  It contains the Emacs Lisp interpreter and I/O
-routines, but not the editing commands.
+@dfn{bare impure Emacs}.  It contains the Emacs Lisp interpreter and
+I/O routines, but not the editing commands.
 
 @cindex @file{loadup.el}
-  The command @w{@samp{temacs -l loadup}} uses @file{temacs} to create
-the real runnable Emacs executable.  These arguments direct
-@file{temacs} to evaluate the Lisp files specified in the file
-@file{loadup.el}.  These files set up the normal Emacs editing
-environment, resulting in an Emacs that is still impure but no longer
-bare.
+  The command @w{@command{temacs -l loadup}} would run @file{temacs}
+and direct it to load @file{loadup.el}.  The @code{loadup} library
+loads additional Lisp libraries, which set up the normal Emacs editing
+environment.  After this step, the Emacs executable is no longer
+@dfn{bare}.
 
 @cindex dumping Emacs
-  It takes some time to load the standard Lisp files.  Luckily,
-you don't have to do this each time you run Emacs; @file{temacs} can
-dump out an executable program called @file{emacs} that has these files
-preloaded.  @file{emacs} starts more quickly because it does not need to
-load the files.  This is the Emacs executable that is normally
-installed.
-
+  Because it takes some time to load the standard Lisp files, the
+@file{temacs} executable usually isn't run directly by users.
+Instead, as one of the last steps of building Emacs, the command
+@samp{temacs -batch -l loadup dump} is run.  The special @samp{dump}
+argument causes @command{temacs} to dump out an executable program,
+called @file{emacs}, which has all the standard Lisp files preloaded.
+(The @samp{-batch} argument prevents @file{temacs} from trying to
+initialize any of its data on the terminal, so that the tables of
+terminal information are empty in the dumped Emacs.)
+
+@cindex preloaded Lisp files
 @vindex preloaded-file-list
-@cindex dumped Lisp files
-  To create @file{emacs}, use the command @samp{temacs -batch -l loadup
-dump}.  The purpose of @samp{-batch} here is to prevent @file{temacs}
-from trying to initialize any of its data on the terminal; this ensures
-that the tables of terminal information are empty in the dumped Emacs.
-The argument @samp{dump} tells @file{loadup.el} to dump a new executable
-named @file{emacs}.  The variable @code{preloaded-file-list} stores a
-list of the Lisp files that were dumped with the @file{emacs} executable.
-
-  If you port Emacs to a new operating system, and are not able to
-implement dumping, then Emacs must load @file{loadup.el} each time it
-starts.
+  The dumped @file{emacs} executable (also called a @dfn{pure} Emacs)
+is the one which is installed.  The variable
+@code{preloaded-file-list} stores a list of the Lisp files preloaded
+into the dumped Emacs.  If you port Emacs to a new operating system,
+and are not able to implement dumping, then Emacs must load
+@file{loadup.el} each time it starts.
 
 @cindex @file{site-load.el}
   You can specify additional files to preload by writing a library named
@@ -163,7 +160,7 @@ all the new data created during an Emacs session are kept
 in the preloaded standard Lisp files---data that should never change
 during actual use of Emacs.
 
-  Pure storage is allocated only while @file{temacs} is loading the
+  Pure storage is allocated only while @command{temacs} is loading the
 standard preloaded Lisp libraries.  In the file @file{emacs}, it is
 marked as read-only (on operating systems that permit this), so that
 the memory space can be shared by all the Emacs jobs running on the
@@ -214,31 +211,27 @@ You should not change this flag in a running Emacs.
 
 @node Garbage Collection
 @section Garbage Collection
-@cindex garbage collection
 
 @cindex memory allocation
-  When a program creates a list or the user defines a new function (such
-as by loading a library), that data is placed in normal storage.  If
-normal storage runs low, then Emacs asks the operating system to
-allocate more memory in blocks of 1k bytes.  Each block is used for one
-type of Lisp object, so symbols, cons cells, markers, etc., are
-segregated in distinct blocks in memory.  (Vectors, long strings,
-buffers and certain other editing types, which are fairly large, are
-allocated in individual blocks, one per object, while small strings are
-packed into blocks of 8k bytes.)
-
-  It is quite common to use some storage for a while, then release it by
-(for example) killing a buffer or deleting the last pointer to an
-object.  Emacs provides a @dfn{garbage collector} to reclaim this
-abandoned storage.  (This name is traditional, but ``garbage recycler''
-might be a more intuitive metaphor for this facility.)
+  When a program creates a list or the user defines a new function
+(such as by loading a library), that data is placed in normal storage.
+If normal storage runs low, then Emacs asks the operating system to
+allocate more memory.  Different types of Lisp objects, such as
+symbols, cons cells, markers, etc., are segregated in distinct blocks
+in memory.  (Vectors, long strings, buffers and certain other editing
+types, which are fairly large, are allocated in individual blocks, one
+per object, while small strings are packed into blocks of 8k bytes.)
 
-  The garbage collector operates by finding and marking all Lisp objects
-that are still accessible to Lisp programs.  To begin with, it assumes
-all the symbols, their values and associated function definitions, and
-any data presently on the stack, are accessible.  Any objects that can
-be reached indirectly through other accessible objects are also
-accessible.
+@cindex garbage collection
+  It is quite common to use some storage for a while, then release it
+by (for example) killing a buffer or deleting the last pointer to an
+object.  Emacs provides a @dfn{garbage collector} to reclaim this
+abandoned storage.  The garbage collector operates by finding and
+marking all Lisp objects that are still accessible to Lisp programs.
+To begin with, it assumes all the symbols, their values and associated
+function definitions, and any data presently on the stack, are
+accessible.  Any objects that can be reached indirectly through other
+accessible objects are also accessible.
 
   When marking is finished, all objects still unmarked are garbage.  No
 matter what the Lisp program or the user does, it is impossible to refer
@@ -336,11 +329,9 @@ The total size of all strings, in characters.
 The total number of elements of existing vectors.
 
 @item used-floats
-@c Emacs 19 feature
 The number of floats in use.
 
 @item free-floats
-@c Emacs 19 feature
 The number of floats for which space has been obtained from the
 operating system, but that are not currently being used.
 
@@ -417,7 +408,6 @@ memory used by Lisp data, broken down by data type.  By contrast, the
 function @code{memory-limit} provides information on the total amount of
 memory Emacs is currently using.
 
-@c Emacs 19 feature
 @defun memory-limit
 This function returns the address of the last byte Emacs has allocated,
 divided by 1024.  We divide the value by 1024 to make sure it fits in a
@@ -428,7 +418,7 @@ memory usage.
 @end defun
 
 @defvar memory-full
-This variable is @code{t} if Emacs is close to out of memory for Lisp
+This variable is @code{t} if Emacs is nearly out of memory for Lisp
 objects, and @code{nil} otherwise.
 @end defvar
 
@@ -519,8 +509,9 @@ appearance.)
 @smallexample
 @group
 DEFUN ("or", For, Sor, 0, UNEVALLED, 0,
-  doc: /* Eval args until one of them yields non-nil, then return that
-value.  The remaining args are not evalled at all.
+  doc: /* Eval args until one of them yields non-nil, then return
+that value.
+The remaining args are not evalled at all.
 If all args return nil, return nil.
 @end group
 @group
@@ -566,14 +557,11 @@ This is the name of the Lisp symbol to define as the function name; in
 the example above, it is @code{or}.
 
 @item fname
-This is the C function name for this function.  This is
-the name that is used in C code for calling the function.  The name is,
-by convention, @samp{F} prepended to the Lisp name, with all dashes
-(@samp{-}) in the Lisp name changed to underscores.  Thus, to call this
-function from C code, call @code{For}.  Remember that the arguments must
-be of type @code{Lisp_Object}; various macros and functions for creating
-values of type @code{Lisp_Object} are declared in the file
-@file{lisp.h}.
+This is the C function name for this function.  This is the name that
+is used in C code for calling the function.  The name is, by
+convention, @samp{F} prepended to the Lisp name, with all dashes
+(@samp{-}) in the Lisp name changed to underscores.  Thus, to call
+this function from C code, call @code{For}.
 
 @item sname
 This is a C variable name to use for a structure that holds the data for
@@ -627,38 +615,35 @@ too.
 @end table
 
   After the call to the @code{DEFUN} macro, you must write the
-argument list that every C function must have, including the types for
-the arguments.  For a function with a fixed maximum number of
-arguments, declare a C argument for each Lisp argument, and give them
-all type @code{Lisp_Object}.  When a Lisp function has no upper limit
-on the number of arguments, its implementation in C actually receives
-exactly two arguments: the first is the number of Lisp arguments, and
-the second is the address of a block containing their values.  They
-have types @code{int} and @w{@code{Lisp_Object *}}.
+argument list for the C function, including the types for the
+arguments.  If the primitive accepts a fixed maximum number of Lisp
+arguments, there must be one C argument for each Lisp argument, and
+each argument must be of type @code{Lisp_Object}.  (Various macros and
+functions for creating values of type @code{Lisp_Object} are declared
+in the file @file{lisp.h}.)  If the primitive has no upper limit on
+the number of Lisp arguments, it must have exactly two C arguments:
+the first is the number of Lisp arguments, and the second is the
+address of a block containing their values.  These have types
+@code{int} and @w{@code{Lisp_Object *}} respectively.
 
 @cindex @code{GCPRO} and @code{UNGCPRO}
 @cindex protect C variables from garbage collection
   Within the function @code{For} itself, note the use of the macros
-@code{GCPRO1} and @code{UNGCPRO}.  @code{GCPRO1} is used to
-``protect'' a variable from garbage collection---to inform the garbage
-collector that it must look in that variable and regard its contents
-as an accessible object.  GC protection is necessary whenever you call
-@code{eval_sub} (or @code{Feval}) either directly or indirectly.
-At such a time, any Lisp object that this function may refer to again
-must be protected somehow.
+@code{GCPRO1} and @code{UNGCPRO}.  These macros are defined for the
+sake of the few platforms which do not use Emacs' default
+stack-marking garbage collector.  The @code{GCPRO1} macro ``protects''
+a variable from garbage collection, explicitly informing the garbage
+collector that that variable and all its contents must be as
+accessible.  GC protection is necessary in any function which can
+perform Lisp evaluation by calling @code{eval_sub} or @code{Feval} as
+a subroutine, either directly or indirectly.
 
   It suffices to ensure that at least one pointer to each object is
-GC-protected; that way, the object cannot be recycled, so all pointers
-to it remain valid.  Thus, a particular local variable can do without
+GC-protected.  Thus, a particular local variable can do without
 protection if it is certain that the object it points to will be
 preserved by some other pointer (such as another local variable that
-has a @code{GCPRO}).
-@ignore
-@footnote{Formerly, strings were a special exception; in older Emacs
-versions, every local variable that might point to a string needed a
-@code{GCPRO}.}.
-@end ignore
-Otherwise, the local variable needs a @code{GCPRO}.
+has a @code{GCPRO}).  Otherwise, the local variable needs a
+@code{GCPRO}.
 
   The macro @code{GCPRO1} protects just one local variable.  If you
 want to protect two variables, use @code{GCPRO2} instead; repeating
@@ -667,34 +652,17 @@ want to protect two variables, use @code{GCPRO2} instead; repeating
 implicitly use local variables such as @code{gcpro1}; you must declare
 these explicitly, with type @code{struct gcpro}.  Thus, if you use
 @code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}.
-Alas, we can't explain all the tricky details here.
 
   @code{UNGCPRO} cancels the protection of the variables that are
 protected in the current function.  It is necessary to do this
 explicitly.
 
-  Built-in functions that take a variable number of arguments actually
-accept two arguments at the C level: the number of Lisp arguments, and
-a @code{Lisp_Object *} pointer to a C vector containing those Lisp
-arguments.  This C vector may be part of a Lisp vector, but it need
-not be.  The responsibility for using @code{GCPRO} to protect the Lisp
-arguments from GC if necessary rests with the caller in this case,
-since the caller allocated or found the storage for them.
-
   You must not use C initializers for static or global variables unless
 the variables are never written once Emacs is dumped.  These variables
 with initializers are allocated in an area of memory that becomes
 read-only (on certain operating systems) as a result of dumping Emacs.
 @xref{Pure Storage}.
 
-@c FIXME is this still true?  I don't think so...
-  Do not use static variables within functions---place all static
-variables at top level in the file.  This is necessary because Emacs on
-some operating systems defines the keyword @code{static} as a null
-macro.  (This definition is used because those systems put all variables
-declared static in a place that becomes read-only after dumping, whether
-they have initializers or not.)
-
 @cindex @code{defsubr}, Lisp symbol for a primitive
   Defining the C function is not enough to make a Lisp primitive
 available; you must also create the Lisp symbol for the primitive and
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index b0e9d4a3139..946dcb91317 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -525,6 +525,10 @@ mode when creating new buffers (@pxref{Auto Major Mode}), but with such
 @code{special} modes, Fundamental mode is used instead.  Modes such as
 Dired, Rmail, and Buffer List use this feature.
 
+The function @code{view-buffer} does not enable View mode in buffers
+whose mode-class is special, because such modes usually provide their
+own View-like bindings.
+
 The @code{define-derived-mode} macro automatically marks the derived
 mode as special if the parent mode is special.  Special mode is a
 convenient parent for such modes to inherit from; @xref{Basic Major
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index f7df5f4bf87..2563bc57aef 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -8,8 +8,7 @@
 @chapter Operating System Interface
 
   This chapter is about starting and getting out of Emacs, access to
-values in the operating system environment, and terminal input, output,
-and flow control.
+values in the operating system environment, and terminal input, output.
 
   @xref{Building Emacs}, for related information.  @xref{Display}, for
 additional operating system status information pertaining to the
@@ -60,7 +59,7 @@ can customize these actions.
 @cindex @file{startup.el}
 
   When Emacs is started up, it performs the following operations
-(which are defined in @file{startup.el}):
+(see @code{normal-top-level} in @file{startup.el}):
 
 @enumerate
 @item
@@ -70,6 +69,15 @@ adds the directory's subdirectories to the list, and those are scanned
 in their turn.  The files @file{subdirs.el} are normally generated
 automatically when Emacs is installed.
 
+@item
+It registers input methods by loading any @file{leim-list.el} file
+found in the @code{load-path}.
+
+@c It removes PWD from the environment if it is not accurate.
+@c It abbreviates default-directory.
+
+@c Now normal-top-level calls command-line.
+
 @vindex before-init-time
 @item
 It sets the variable @code{before-init-time} to the value of
@@ -77,32 +85,49 @@ It sets the variable @code{before-init-time} to the value of
 @code{after-init-time} to @code{nil}, which signals to Lisp programs
 that Emacs is being initialized.
 
+@c set-locale-environment
+@item
+It sets the language environment and the terminal coding system,
+if requested by environment variables such as @code{LANG}.
+
+@item
+It does some basic parsing of the command-line arguments.
+
 @vindex initial-window-system@r{, and startup}
 @vindex window-system-initialization-alist
 @item
-It loads the initialization library for the window system specified by
-the variable @code{initial-window-system} (@pxref{Window Systems,
-initial-window-system}).  This library's name is
-@file{term/@var{windowsystem}-win.el}, where @var{windowsystem} is the
-value of @code{initial-window-system}.  From that library, it calls
-the appropriate initialization function.  The initialization function
-for each supported window system is specified by
-@code{window-system-initialization-alist}.
+If not running in batch mode, it initializes the window system that
+the variable @code{initial-window-system} specifies (@pxref{Window
+Systems, initial-window-system}).  The initialization function for
+each supported window system is specified by
+@code{window-system-initialization-alist}.  If the value
+of @code{initial-window-system} is @var{windowsystem}, then the
+appropriate initialization function is defined in the file
+@file{term/@var{windowsystem}-win.el}.  This file should have been
+compiled into the Emacs executable when it was built.
 
 @item
-It sets the language environment and the terminal coding system,
-if requested by environment variables such as @code{LANG}.
+It runs the normal hook @code{before-init-hook}.
 
 @item
-It processes the initial options.  (Some of them are handled
-even earlier than this.)
+If appropriate (e.g., not in batch mode or started as a daemon), it
+creates a graphical frame.
 
 @item
-It runs the normal hook @code{before-init-hook}.
+It initializes the initial frame's faces, and sets up the menu bar
+and tool bar if needed.  If graphical frames are supported, it sets up
+the tool bar even if the current frame is not a graphical one, since a
+graphical frame may be created later on.
 
 @item
-It initializes the initial frame's faces, and turns on the menu bar
-and tool bar if needed.
+It use @code{custom-reevaluate-setting} to re-initialize the members
+of the list @code{custom-delayed-init-variables}.  These are any
+pre-loaded user options whose default value depends on the run-time,
+rather than build-time, context.
+@xref{Building Emacs, custom-initialize-delay}.
+
+@c @item
+@c It registers the colors available for tty frames.
 
 @item
 It loads the library @file{site-start}, if it exists.  This is not
@@ -127,6 +152,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
@@ -149,13 +179,17 @@ Lisp library, which is specified by the variable
 @code{term-file-prefix} (@pxref{Terminal-Specific}).  This is not done
 in @code{--batch} mode, nor if @code{term-file-prefix} is @code{nil}.
 
+@c Now command-line calls command-line-1.
+
 @item
 It displays the initial echo area message, unless you have suppressed
 that with @code{inhibit-startup-echo-area-message}.
 
 @item
-It processes the action arguments from the command line.
+It processes any command-line options that were not handled earlier.
 
+@c This next one is back in command-line, but the remaining bits of
+@c command-line-1 are not done if noninteractive.
 @item
 It now exits if the option @code{--batch} was specified.
 
@@ -164,6 +198,15 @@ If @code{initial-buffer-choice} is a string, it visits the file with
 that name.  Furthermore, if the @samp{*scratch*} buffer exists and is
 empty, it inserts @code{initial-scratch-message} into that buffer.
 
+@c To make things nice and confusing, the next three items can be
+@c called from two places.  If displaying a startup screen, they are
+@c called in command-line-1 before the startup screen is shown.
+@c inhibit-startup-hooks is then set and window-setup-hook set to nil.
+@c If not displaying a startup screen, they are are called in
+@c normal-top-level.
+@c FIXME?  So it seems they can be called before or after the
+@c daemon/session restore step?
+
 @item
 It runs @code{emacs-startup-hook} and then @code{term-setup-hook}.
 
@@ -176,23 +219,38 @@ specify.
 It runs @code{window-setup-hook}.  @xref{Window Systems}.
 
 @item
-If the option @code{--daemon} was specified, it calls
-@code{server-start} and detaches from the controlling terminal.
-@xref{Emacs Server,,, emacs, The GNU Emacs Manual}.
-
-@item
 It displays the @dfn{startup screen}, which is a special buffer that
 contains information about copyleft and basic Emacs usage.  This is
 not done if @code{initial-buffer-choice} or
 @code{inhibit-startup-screen} are @code{nil}, nor if the
 @samp{--no-splash} or @samp{-Q} command-line options were specified.
 
+@c End of command-line-1.
+
+@c Back to command-line from command-line-1.
+
+@c This is the point at which we actually exit in batch mode, but the
+@c last few bits of command-line-1 are not done in batch mode.
+
+@item
+If the option @code{--daemon} was specified, it calls
+@code{server-start} and detaches from the controlling terminal.
+@xref{Emacs Server,,, emacs, The GNU Emacs Manual}.
+
 @item
 If started by the X session manager, it calls
 @code{emacs-session-restore} passing it as argument the ID of the
 previous session.  @xref{Session Management}.
+
+@c End of command-line.
+
+@c Back to normal-top-level from command-line.
+
 @end enumerate
 
+@noindent
+The following options affect some aspects of the startup sequence.
+
 @defopt inhibit-startup-screen
 This variable, if non-@code{nil}, inhibits the startup screen.  In
 that case, Emacs typically displays the @samp{*scratch*} buffer; but
@@ -210,9 +268,13 @@ aliases for this variable.
 
 @defopt initial-buffer-choice
 This variable, if non-@code{nil}, determines a file or buffer for
-Emacs to display after starting up, instead of the startup screen.  If
-its value is @code{t}, Emacs displays the @samp{*scratch*} buffer.  If
-its value is a string, that specifies the name of a file for Emacs to
+Emacs to display after starting up, instead of the startup screen.
+@ignore
+@c I do not think this should be mentioned.  AFAICS it is just a dodge
+@c around inhibit-startup-screen not being settable on a site-wide basis.
+If its value is @code{t}, Emacs displays the @samp{*scratch*} buffer. 
+@end ignore
+If its value is a string, that specifies the name of a file for Emacs to
 visit.
 @end defopt
 
@@ -228,7 +290,7 @@ form to your init file:
 
 Emacs explicitly checks for an expression as shown above in your init
 file; your login name must appear in the expression as a Lisp string
-constant.  Other methods of setting
+constant.  You can also use the Custom interface.  Other methods of setting
 @code{inhibit-startup-echo-area-message} to the same value do not
 inhibit the startup message.  This way, you can easily inhibit the
 message for yourself if you wish, but thoughtless copying of your init
@@ -241,18 +303,49 @@ inserted into the @samp{*scratch*} buffer when Emacs starts up.  If it
 is @code{nil}, the @samp{*scratch*} buffer is empty.
 @end defopt
 
+@noindent
+The following command-line options affect some aspects of the startup
+sequence.  @xref{Initial Options,,, emacs, The GNU Emacs Manual}.
+
+@table @code
+@item --no-splash
+Do not display a splash screen.
+
+@item --batch
+Run without an interactive terminal.  @xref{Batch Mode}.
+
+@item --daemon
+Do not initialize any display; just start a server in the background.
+
+@item --no-init-file
+@itemx -Q
+Do not load either the init file, or the @file{default} library.
+
+@item --no-site-file
+Do not load the @file{site-start} library.
+
+@item --quick
+@itemx -Q
+Equivalent to @samp{-q --no-site-file --no-splash}.
+@c and --no-site-lisp, but let's not mention that here.
+@end table
+
+
 @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}
 in your home directory, or a file named @file{init.el} in a
-subdirectory named @file{.emacs.d} in your home directory.  Whichever
-place you use, you can also compile the file (@pxref{Byte
+subdirectory named @file{.emacs.d} in your home directory.
+@ignore
+Whichever place you use, you can also compile the file (@pxref{Byte
 Compilation}); then the actual file loaded will be @file{.emacs.elc}
 or @file{init.elc}.
+@end ignore
 
   The command-line switches @samp{-q}, @samp{-Q}, and @samp{-u}
 control whether and where to find the init file; @samp{-q} (and the
@@ -267,13 +360,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 +436,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 +468,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 +501,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 +602,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 +1180,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 +1231,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 +1261,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 +1274,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
@@ -1718,9 +1795,9 @@ certain length of time.  Aside from how to set them up, idle timers
 work just like ordinary timers.
 
 @deffn Command run-with-idle-timer secs repeat function &rest args
-Set up a timer which runs when Emacs has been idle for @var{secs}
-seconds.  The value of @var{secs} may be an integer or a floating point
-number; a value of the type returned by @code{current-idle-time}
+Set up a timer which runs the next time Emacs is idle for @var{secs}
+seconds.  The value of @var{secs} may be an integer or a floating
+point number; a value of the type returned by @code{current-idle-time}
 is also allowed.
 
 If @var{repeat} is @code{nil}, the timer runs just once, the first time
@@ -1733,13 +1810,13 @@ can use in calling @code{cancel-timer} (@pxref{Timers}).
 @end deffn
 
 @cindex idleness
-  Emacs becomes ``idle'' when it starts waiting for user input, and it
-remains idle until the user provides some input.  If a timer is set for
-five seconds of idleness, it runs approximately five seconds after Emacs
-first becomes idle.  Even if @var{repeat} is non-@code{nil}, this timer
-will not run again as long as Emacs remains idle, because the duration
-of idleness will continue to increase and will not go down to five
-seconds again.
+  Emacs becomes @dfn{idle} when it starts waiting for user input, and
+it remains idle until the user provides some input.  If a timer is set
+for five seconds of idleness, it runs approximately five seconds after
+Emacs first becomes idle.  Even if @var{repeat} is non-@code{nil},
+this timer will not run again as long as Emacs remains idle, because
+the duration of idleness will continue to increase and will not go
+down to five seconds again.
 
   Emacs can do various things while idle: garbage collect, autosave or
 handle data from a subprocess.  But these interludes during idleness do
@@ -1753,22 +1830,12 @@ minutes, and even if there have been garbage collections and autosaves.
 input.  Then it becomes idle again, and all the idle timers that are
 set up to repeat will subsequently run another time, one by one.
 
-@c Emacs 19 feature
 @defun current-idle-time
 If Emacs is idle, this function returns the length of time Emacs has
-been idle, 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 of idleness, 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).
+been idle, as a list of three integers: @code{(@var{sec-high}
+@var{sec-low} @var{microsec})}, where @var{high} and @var{low} are the
+high and low bits for the number of seconds and @var{microsec} is the
+additional number of microseconds (@pxref{Time of Day}).
 
 When Emacs is not idle, @code{current-idle-time} returns @code{nil}.
 This is a convenient way to test whether Emacs is idle.
@@ -1801,9 +1868,9 @@ Here's an example:
 @end smallexample
 @end defun
 
-  Some idle timer functions in user Lisp packages have a loop that
-does a certain amount of processing each time around, and exits when
-@code{(input-pending-p)} is non-@code{nil}.  That approach seems very
+  Do not write an idle timer function containing a loop which does a
+certain amount of processing each time around, and exits when
+@code{(input-pending-p)} is non-@code{nil}.  This approach seems very
 natural but has two problems:
 
 @itemize
@@ -1816,9 +1883,9 @@ It blocks out any idle timers that ought to run during that time.
 @end itemize
 
 @noindent
-To avoid these problems, don't use that technique.  Instead, write
-such idle timers to reschedule themselves after a brief pause, using
-the method in the @code{timer-function} example above.
+The correct approach is for the idle timer to reschedule itself after
+a brief pause, using the method in the @code{timer-function} example
+above.
 
 @node Terminal Input
 @section Terminal Input
@@ -2014,9 +2081,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