Update docs for a bunch of 24.3 changes.

* doc/emacs/killing.texi (Rectangles): Document copy-rectangle-as-kill.

* doc/emacs/search.texi (Special Isearch): Document the lax space search
feature and M-s SPC.
(Regexp Search): Move main search-whitespace-regexp description to
Special Isearch.
(Replace): Document replace-lax-whitespace.

* doc/emacs/basic.texi (Position Info): Document C-u M-=.
(Moving Point): Document move-to-column.

* doc/emacs/display.texi (Useless Whitespace): Add delete-trailing-lines.

* doc/emacs/misc.texi (emacsclient Options): Document the effect of
initial-buffer-choice on client frames.  Document server-auth-dir.
Do not document server-host, which is bad security practice.

* doc/emacs/building.texi (Lisp Libraries): Docstring lookups can trigger
autoloading.  Document help-enable-auto-load.

* doc/emacs/mini.texi (Yes or No Prompts): New node.

* doc/emacs/ack.texi (Acknowledgments): Remove obsolete packages.

* doc/lispref/commands.texi (Click Events): Define "mouse position list".
Remove mention of unimplemented horizontal scroll bars.
(Drag Events, Motion Events): Refer to "mouse position list".
(Accessing Mouse): Document posnp.

* doc/lispref/errors.texi (Standard Errors): Tweak arith-error description.
Tweak markup.  Remove domain-error and friends, which seem to be
unused after the floating-point code revamp.

* doc/lispref/functions.texi (Obsolete Functions): Obsolescence also affects
documentation commands.  Various clarifications.
(Declare Form): New node.

* doc/lispref/loading.texi (Autoload):
* doc/lispref/help.texi (Documentation Basics): The special sequences can
trigger autoloading.

* doc/lispref/macros.texi (Defining Macros): Move description of `declare' to
Declare Form node.

* doc/lispref/numbers.texi (Integer Basics): Copyedits.
(Float Basics): Consider IEEE floating point always available.
(Random Numbers): Document actual limits.
(Arithmetic Operations): Clarify division by zero.  Don't mention
the machine-independence of negative division since it does not
happen in practice.

* doc/lispref/os.texi (Idle Timers): Minor clarifications.
(User Identification): Add system-users and system-groups.

* doc/lispref/strings.texi (String Basics): Copyedits.

* lisp/minibuffer.el (minibuffer-local-filename-syntax): Doc fix.

* lisp/server.el (server-host): Document the security implications.
(server-auth-key): Doc fix.

* lisp/startup.el (initial-buffer-choice): Doc fix.

* src/fns.c (Frandom): Doc fix.

12 files changed, 469 insertions, 403 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 76f06edaacb..b5c847b4b72 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,45 @@
+2012-09-30  Chong Yidong  <cyd@gnu.org>
+
+        * commands.texi (Click Events): Define "mouse position list".
+        Remove mention of unimplemented horizontal scroll bars.
+        (Drag Events, Motion Events): Refer to "mouse position list".
+        (Accessing Mouse): Document posnp.
+
+        * errors.texi (Standard Errors): Tweak arith-error description.
+        Tweak markup.  Remove domain-error and friends, which seem to be
+        unused after the floating-point code revamp.
+
+        * functions.texi (Obsolete Functions): Obsolescence also affects
+        documentation commands.  Various clarifications.
+        (Declare Form): New node.
+
+        * strings.texi (String Basics): Copyedits.
+
+        * os.texi (Idle Timers): Minor clarifications.
+        (User Identification): Add system-users and system-groups.
+
+        * macros.texi (Defining Macros): Move description of `declare' to
+        Declare Form node.
+
+        * loading.texi (Autoload):
+        * help.texi (Documentation Basics): The special sequences can
+        trigger autoloading.
+
+        * numbers.texi (Integer Basics): Copyedits.
+        (Float Basics): Consider IEEE floating point always available.
+        (Random Numbers): Document actual limits.
+        (Arithmetic Operations): Clarify division by zero.  Don't mention
+        the machine-independence of negative division since it does not
+        happen in practice.
+
+2012-09-28  Chong Yidong  <cyd@gnu.org>
+
+        * os.texi (Startup Summary): Document leim-list.el change.
+
+2012-09-25  Chong Yidong  <cyd@gnu.org>
+
+        * functions.texi (Defining Functions): defun is now a macro.
+
 2012-09-28  Leo Liu  <sdl.web@gmail.com>
 
         * files.texi (Files): Fix typo.
diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index dc0fa4c639d..93dba237013 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -1275,12 +1275,21 @@ describe events by their types; thus, if there is a key binding for
 @var{event-type} is @code{mouse-1}.
 
 @item @var{position}
-This is the position where the mouse click occurred.  The actual
-format of @var{position} depends on what part of a window was clicked
-on.
+@cindex mouse position list
+This is a @dfn{mouse position list} specifying where the mouse click
+occurred; see below for details.
 
-For mouse click events in the text area, mode line, header line, or in
-the marginal areas, @var{position} has this form:
+@item @var{click-count}
+This is the number of rapid repeated presses so far of the same mouse
+button.  @xref{Repeat Events}.
+@end table
+
+  To access the contents of a mouse position list in the
+@var{position} slot of a click event, you should typically use the
+functions documented in @ref{Accessing Mouse}.  The explicit format of
+the list depends on where the click occurred.  For clicks in the text
+area, mode line, header line, or in the fringe or marginal areas, the
+mouse position list has the form
 
 @example
 (@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
@@ -1289,18 +1298,16 @@ the marginal areas, @var{position} has this form:
 @end example
 
 @noindent
-The meanings of these list elements are documented below.
-@xref{Accessing Mouse}, for functions that let you easily access these
-elements.
+The meanings of these list elements are as follows:
 
 @table @asis
 @item @var{window}
-This is the window in which the click occurred.
+The window in which the click occurred.
 
 @item @var{pos-or-area}
-This is the buffer position of the character clicked on in the text
-area, or if clicked outside the text area, it is the window area in
-which the click occurred.  It is one of the symbols @code{mode-line},
+The buffer position of the character clicked on in the text area; or,
+if the click was outside the text area, the window area where it
+occurred.  It is one of the symbols @code{mode-line},
 @code{header-line}, @code{vertical-line}, @code{left-margin},
 @code{right-margin}, @code{left-fringe}, or @code{right-fringe}.
 
@@ -1310,22 +1317,23 @@ happens after the imaginary prefix keys for the event are registered
 by Emacs.  @xref{Key Sequence Input}.
 
 @item @var{x}, @var{y}
-These are the relative pixel coordinates of the click.  For clicks in
-the text area of a window, the coordinate origin @code{(0 . 0)} is
-taken to be the top left corner of the text area.  @xref{Window
-Sizes}.  For clicks in a mode line or header line, the coordinate
-origin is the top left corner of the window itself.  For fringes,
-margins, and the vertical border, @var{x} does not have meaningful
-data.  For fringes and margins, @var{y} is relative to the bottom edge
-of the header line.  In all cases, the @var{x} and @var{y} coordinates
-increase rightward and downward respectively.
+The relative pixel coordinates of the click.  For clicks in the text
+area of a window, the coordinate origin @code{(0 . 0)} is taken to be
+the top left corner of the text area.  @xref{Window Sizes}.  For
+clicks in a mode line or header line, the coordinate origin is the top
+left corner of the window itself.  For fringes, margins, and the
+vertical border, @var{x} does not have meaningful data.  For fringes
+and margins, @var{y} is relative to the bottom edge of the header
+line.  In all cases, the @var{x} and @var{y} coordinates increase
+rightward and downward respectively.
 
 @item @var{timestamp}
-This is the time at which the event occurred, in milliseconds.
+The time at which the event occurred, as an integer number of
+milliseconds since a system-dependent initial time.
 
 @item @var{object}
-This is either @code{nil} if there is no string-type text property at
-the click position, or a cons cell of the form (@var{string}
+Either @code{nil} if there is no string-type text property at the
+click position, or a cons cell of the form (@var{string}
 . @var{string-pos}) if there is one:
 
 @table @asis
@@ -1371,8 +1379,7 @@ These are the pixel width and height of @var{object} or, if this is
 @code{nil}, those of the character glyph clicked on.
 @end table
 
-@sp 1
-For mouse clicks on a scroll-bar, @var{position} has this form:
+For clicks on a scroll bar, @var{position} has this form:
 
 @example
 (@var{window} @var{area} (@var{portion} . @var{whole}) @var{timestamp} @var{part})
@@ -1380,32 +1387,35 @@ For mouse clicks on a scroll-bar, @var{position} has this form:
 
 @table @asis
 @item @var{window}
-This is the window whose scroll-bar was clicked on.
+The window whose scroll bar was clicked on.
 
 @item @var{area}
-This is the scroll bar where the click occurred.  It is one of the
-symbols @code{vertical-scroll-bar} or @code{horizontal-scroll-bar}.
+This is the symbol @code{vertical-scroll-bar}.
 
 @item @var{portion}
-This is the distance of the click from the top or left end of
-the scroll bar.
+The number of pixels from the top of the scroll bar to the click
+position.  On some toolkits, including GTK+, Emacs cannot extract this
+data, so the value is always @code{0}.
 
 @item @var{whole}
-This is the length of the entire scroll bar.
+The total length, in pixels, of the scroll bar.  On some toolkits,
+including GTK+, Emacs cannot extract this data, so the value is always
+@code{0}.
 
 @item @var{timestamp}
-This is the time at which the event occurred, in milliseconds.
+The time at which the event occurred, in milliseconds.  On some
+toolkits, including GTK+, Emacs cannot extract this data, so the value
+is always @code{0}.
 
 @item @var{part}
-This is the part of the scroll-bar which was clicked on.  It is one
-of the symbols @code{above-handle}, @code{handle}, @code{below-handle},
-@code{up}, @code{down}, @code{top}, @code{bottom}, and @code{end-scroll}.
+The part of the scroll bar on which the click occurred.  It is one of
+the symbols @code{handle} (the scroll bar handle), @code{above-handle}
+(the area above the handle), @code{below-handle} (the area below the
+handle), @code{up} (the up arrow at one end of the scroll bar), or
+@code{down} (the down arrow at one end of the scroll bar).
+@c The `top', `bottom', and `end-scroll' codes don't seem to be used.
 @end table
 
-@item @var{click-count}
-This is the number of rapid repeated presses so far of the same mouse
-button.  @xref{Repeat Events}.
-@end table
 
 @node Drag Events
 @subsection Drag Events
@@ -1429,10 +1439,9 @@ For a drag event, the name of the symbol @var{event-type} contains the
 prefix @samp{drag-}.  For example, dragging the mouse with button 2
 held down generates a @code{drag-mouse-2} event.  The second and third
 elements of the event give the starting and ending position of the
-drag.  They have the same form as @var{position} in a click event
-(@pxref{Click Events}) that is not on the scroll bar part of the
-window.  You can access the second element of any mouse event in the
-same way, with no need to distinguish drag events from others.
+drag, as mouse position lists (@pxref{Click Events}).  You can access
+the second element of any mouse event in the same way, with no need to
+distinguish drag events from others.
 
 The @samp{drag-} prefix follows the modifier key prefixes such as
 @samp{C-} and @samp{M-}.
@@ -1575,13 +1584,14 @@ represented by lists that look like this:
 (mouse-movement POSITION)
 @end example
 
-The second element of the list describes the current position of the
-mouse, just as in a click event (@pxref{Click Events}).
+@noindent
+@var{position} is a mouse position list (@pxref{Click Events}),
+specifying the current position of the mouse cursor.
 
-The special form @code{track-mouse} enables generation of motion events
-within its body.  Outside of @code{track-mouse} forms, Emacs does not
-generate events for mere motion of the mouse, and these events do not
-appear.  @xref{Mouse Tracking}.
+The special form @code{track-mouse} enables generation of motion
+events within its body.  Outside of @code{track-mouse} forms, Emacs
+does not generate events for mere motion of the mouse, and these
+events do not appear.  @xref{Mouse Tracking}.
 
 @node Focus Events
 @subsection Focus Events
@@ -1648,13 +1658,11 @@ frame has already been made visible, Emacs has no work to do.
 @cindex @code{wheel-up} event
 @cindex @code{wheel-down} event
 @item (wheel-up @var{position})
-@item (wheel-down @var{position})
-These kinds of event are generated by moving a mouse wheel.  Their
-usual meaning is a kind of scroll or zoom.
-
-The element @var{position} is a list describing the position of the
-event, in the same format as used in a mouse-click event (@pxref{Click
-Events}).
+@itemx (wheel-down @var{position})
+These kinds of event are generated by moving a mouse wheel.  The
+@var{position} element is a mouse position list (@pxref{Click
+Events}), specifying the position of the mouse cursor when the event
+occurred.
 
 @vindex mouse-wheel-up-event
 @vindex mouse-wheel-down-event
@@ -1922,14 +1930,8 @@ must be the last element of the list.  For example,
   This section describes convenient functions for accessing the data in
 a mouse button or motion event.
 
-  These two functions return the starting or ending position of a
-mouse-button event, as a list of this form (@pxref{Click Events}):
-
-@example
-(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp}
- @var{object} @var{text-pos} (@var{col} . @var{row})
- @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height}))
-@end example
+  The following two functions return a mouse position list
+(@pxref{Click Events}), specifying the position of a mouse event.
 
 @defun event-start event
 This returns the starting position of @var{event}.
@@ -1948,9 +1950,15 @@ event, the value is actually the starting position, which is the only
 position such events have.
 @end defun
 
+@defun posnp object
+This function returns non-@code{nil} if @var{object} is a mouse
+oposition list, in either of the formats documented in @ref{Click
+Events}); and @code{nil} otherwise.
+@end defun
+
 @cindex mouse position list, accessing
-  These functions take a position list as described above, and
-return various parts of it.
+  These functions take a mouse position list as argument, and return
+various parts of it:
 
 @defun posn-window position
 Return the window that @var{position} is in.
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index db770616820..d46cb071bf7 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -516,6 +516,7 @@ Functions
 * Obsolete Functions::      Declaring functions obsolete.
 * Inline Functions::        Defining functions that the compiler
                               will expand inline.
+* Declare Form::          Adding additional information about a function.
 * Declaring Functions::     Telling the compiler that a function is defined.
 * Function Safety::         Determining whether a function is safe to call.
 * Related Topics::          Cross-references to specific Lisp primitives
diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi
index a822a2d9608..b7b26c8708c 100644
--- a/doc/lispref/errors.texi
+++ b/doc/lispref/errors.texi
@@ -37,78 +37,69 @@ handled.
 
 @table @code
 @item error
-@code{"error"}@*
-@xref{Errors}.
+The message is @samp{error}.  @xref{Errors}.
 
 @item quit
-@code{"Quit"}@*
-@xref{Quitting}.
+The message is @samp{Quit}.  @xref{Quitting}.
 
 @item args-out-of-range
-@code{"Args out of range"}@*
-This happens when trying to access an element beyond the range of a
-sequence or buffer.@*
-@xref{Sequences Arrays Vectors}, @xref{Text}.
+The message is @samp{Args out of range}.  This happens when trying to
+access an element beyond the range of a sequence, buffer, or other
+container-like object.  @xref{Sequences Arrays Vectors}, and
+@xref{Text}.
 
 @item arith-error
-@code{"Arithmetic error"}@*
+The message is @samp{Arithmetic error}.  This occurs when trying to
+perform integer division by zero.  @xref{Numeric Conversions}, and
 @xref{Arithmetic Operations}.
 
 @item beginning-of-buffer
-@code{"Beginning of buffer"}@*
-@xref{Character Motion}.
+The message is @samp{Beginning of buffer}.  @xref{Character Motion}.
 
 @item buffer-read-only
-@code{"Buffer is read-only"}@*
-@xref{Read Only Buffers}.
+The message is @samp{Buffer is read-only}.  @xref{Read Only Buffers}.
 
 @item circular-list
-@code{"List contains a loop"}@*
-This happens when some operations (e.g. resolving face names)
-encounter circular structures.@*
-@xref{Circular Objects}.
+The message is @samp{List contains a loop}.  This happens when a
+circular structure is encountered.  @xref{Circular Objects}.
 
 @item cl-assertion-failed
-@code{"Assertion failed"}@*
-This happens when the @code{assert} macro fails a test.@*
-@xref{Assertions,,, cl, Common Lisp Extensions}.
+The message is @samp{Assertion failed}.  This happens when the
+@code{assert} macro fails a test.  @xref{Assertions,,, cl, Common Lisp
+Extensions}.
 
 @item coding-system-error
-@code{"Invalid coding system"}@*
-@xref{Lisp and Coding Systems}.
+The message is @samp{Invalid coding system}.  @xref{Lisp and Coding
+Systems}.
 
 @item cyclic-function-indirection
-@code{"Symbol's chain of function indirections contains a loop"}@*
-@xref{Function Indirection}.
+The message is @samp{Symbol's chain of function indirections contains
+a loop}.  @xref{Function Indirection}.
 
 @item cyclic-variable-indirection
-@code{"Symbol's chain of variable indirections contains a loop"}@*
-@xref{Variable Aliases}.
+The message is @samp{Symbol's chain of variable indirections contains
+a loop}.  @xref{Variable Aliases}.
 
 @item dbus-error
-@code{"D-Bus error"}@*
-This is only defined if Emacs was compiled with D-Bus support.@*
-@xref{Errors and Events,,, dbus, D-Bus integration in Emacs}.
+The message is @samp{D-Bus error}.  This is only defined if Emacs was
+compiled with D-Bus support.  @xref{Errors and Events,,, dbus, D-Bus
+integration in Emacs}.
 
 @item end-of-buffer
-@code{"End of buffer"}@*
-@xref{Character Motion}.
+The message is @samp{End of buffer}.  @xref{Character Motion}.
 
 @item end-of-file
-@code{"End of file during parsing"}@*
-Note that this is not a subcategory of @code{file-error},
-because it pertains to the Lisp reader, not to file I/O.@*
-@xref{Input Functions}.
+The message is @samp{End of file during parsing}.  Note that this is
+not a subcategory of @code{file-error}, because it pertains to the
+Lisp reader, not to file I/O.  @xref{Input Functions}.
 
 @item file-already-exists
-This is a subcategory of @code{file-error}.@*
-@xref{Writing to Files}.
+This is a subcategory of @code{file-error}.  @xref{Writing to Files}.
 
 @item file-date-error
 This is a subcategory of @code{file-error}.  It occurs when
 @code{copy-file} tries and fails to set the last-modification time of
-the output file.@*
-@xref{Changing Files}.
+the output file.  @xref{Changing Files}.
 
 @item file-error
 We do not list the error-strings of this error and its subcategories,
@@ -116,122 +107,109 @@ because the error message is normally constructed from the data items
 alone when the error condition @code{file-error} is present.  Thus,
 the error-strings are not very relevant.  However, these error symbols
 do have @code{error-message} properties, and if no data is provided,
-the @code{error-message} property @emph{is} used.@*
-@xref{Files}.
+the @code{error-message} property @emph{is} used.  @xref{Files}.
 
 @c jka-compr.el
 @item compression-error
 This is a subcategory of @code{file-error}, which results from
-problems handling a compressed file.@*
-@xref{How Programs Do Loading}.
+problems handling a compressed file.  @xref{How Programs Do Loading}.
 
 @c userlock.el
 @item file-locked
-This is a subcategory of @code{file-error}.@*
-@xref{File Locks}.
+This is a subcategory of @code{file-error}.  @xref{File Locks}.
 
 @c userlock.el
 @item file-supersession
-This is a subcategory of @code{file-error}.@*
-@xref{Modification Time}.
+This is a subcategory of @code{file-error}.  @xref{Modification Time}.
 
 @c net/ange-ftp.el
 @item ftp-error
-This is a subcategory of @code{file-error}, which results from problems
-in accessing a remote file using ftp.@*
-@xref{Remote Files,,, emacs, The GNU Emacs Manual}.
+This is a subcategory of @code{file-error}, which results from
+problems in accessing a remote file using ftp.  @xref{Remote Files,,,
+emacs, The GNU Emacs Manual}.
 
 @item invalid-function
-@code{"Invalid function"}@*
-@xref{Function Indirection}.
+The message is @samp{Invalid function}.  @xref{Function Indirection}.
 
 @item invalid-read-syntax
-@code{"Invalid read syntax"}@*
-@xref{Printed Representation}.
+The message is @samp{Invalid read syntax}.  @xref{Printed
+Representation}.
 
 @item invalid-regexp
-@code{"Invalid regexp"}@*
-@xref{Regular Expressions}.
+The message is @samp{Invalid regexp}.  @xref{Regular Expressions}.
 
 @c simple.el
 @item mark-inactive
-@code{"The mark is not active now"}@*
-@xref{The Mark}.
+The message is @samp{The mark is not active now}.  @xref{The Mark}.
 
 @item no-catch
-@code{"No catch for tag"}@*
-@xref{Catch and Throw}.
+The message is @samp{No catch for tag}.  @xref{Catch and Throw}.
 
 @ignore
 @c Not actually used for anything?  Probably definition should be removed.
 @item protected-field
-@code{"Attempt to modify a protected field"}
+The message is @samp{Attempt to modify a protected fiel.
 @end ignore
 
 @item scan-error
-@code{"Scan error"}@*
-This happens when certain syntax-parsing functions
-find invalid syntax or mismatched parentheses.@*
-@xref{List Motion}, and @ref{Parsing Expressions}.
+The message is @samp{Scan error}.  This happens when certain
+syntax-parsing functions find invalid syntax or mismatched
+parentheses.  @xref{List Motion}, and @xref{Parsing Expressions}.
 
 @item search-failed
-@code{"Search failed"}@*
-@xref{Searching and Matching}.
+The message is @samp{Search failed}.  @xref{Searching and Matching}.
 
 @item setting-constant
-@code{"Attempt to set a constant symbol"}@*
-The values of the symbols @code{nil} and @code{t},
-and any symbols that start with @samp{:},
-may not be changed.@*
-@xref{Constant Variables, , Variables that Never Change}.
+The message is @samp{Attempt to set a constant symbol}.  This happens
+when attempting to assign values to @code{nil}, @code{t}, and keyword
+symbols.  @xref{Constant Variables}.
 
 @c simple.el
 @item text-read-only
-@code{"Text is read-only"}@*
-This is a subcategory of @code{buffer-read-only}.@*
-@xref{Special Properties}.
+The message is @samp{Text is read-only}.  This is a subcategory of
+@code{buffer-read-only}.  @xref{Special Properties}.
 
 @item undefined-color
-@code{"Undefined color"}@*
-@xref{Color Names}.
+The message is @samp{Undefined color}.  @xref{Color Names}.
 
 @item void-function
-@code{"Symbol's function definition is void"}@*
+The message is @samp{Symbol's function definition is void}.
 @xref{Function Cells}.
 
 @item void-variable
-@code{"Symbol's value as variable is void"}@*
+The message is @samp{Symbol's value as variable is void}.
 @xref{Accessing Variables}.
 
 @item wrong-number-of-arguments
-@code{"Wrong number of arguments"}@*
-@xref{Classifying Lists}.
+The message is @samp{Wrong number of arguments}.  @xref{Classifying
+Lists}.
 
 @item wrong-type-argument
-@code{"Wrong type argument"}@*
-@xref{Type Predicates}.
+The message is @samp{Wrong type argument}.  @xref{Type Predicates}.
 @end table
 
+@ignore    The following seem to be unused now.
   The following kinds of error, which are classified as special cases of
 @code{arith-error}, can occur on certain systems for invalid use of
 mathematical functions.  @xref{Math Functions}.
 
 @table @code
 @item domain-error
-@code{"Arithmetic domain error"}
+The message is @samp{Arithmetic domain error}.
 
 @item overflow-error
-@code{"Arithmetic overflow error"}@*
-This is a subcategory of @code{domain-error}.
+The message is @samp{Arithmetic overflow error}.  This is a subcategory
+of @code{domain-error}.
 
 @item range-error
-@code{"Arithmetic range error"}
+The message is @code{Arithmetic range error}.
 
 @item singularity-error
-@code{"Arithmetic singularity error"}@*
-This is a subcategory of @code{domain-error}.
+The mssage is @samp{Arithmetic singularity error}.  This is a
+subcategory of @code{domain-error}.
 
 @item underflow-error
-@code{"Arithmetic underflow error"}@*
-This is a subcategory of @code{domain-error}.
+The message is @samp{Arithmetic underflow error}.  This is a
+subcategory of @code{domain-error}.
 @end table
+@end ignore
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 356a891fbcd..af6f4b4c079 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -1529,24 +1529,14 @@ track of such changes.  @xref{Misc Events}.
 @node Raising and Lowering
 @section Raising and Lowering Frames
 
-  Most window systems use a desktop metaphor.  Part of this metaphor is
-the idea that windows are stacked in a notional third dimension
-perpendicular to the screen surface, and thus ordered from ``highest''
-to ``lowest''.  Where two windows overlap, the one higher up covers
-the one underneath.  Even a window at the bottom of the stack can be
-seen if no other window overlaps it.
-
-@c @cindex raising a frame  redundant with raise-frame
+@cindex raising a frame
 @cindex lowering a frame
-  A window's place in this ordering is not fixed; in fact, users tend
-to change the order frequently.  @dfn{Raising} a window means moving
-it ``up'', to the top of the stack.  @dfn{Lowering} a window means
-moving it to the bottom of the stack.  This motion is in the notional
-third dimension only, and does not change the position of the window
-on the screen.
-
-  With Emacs, frames constitute the windows in the metaphor sketched
-above. You can raise and lower frames using these functions:
+  Most window systems use a desktop metaphor.  Part of this metaphor
+is the idea that system-level windows (e.g.@: Emacs frames) are
+stacked in a notional third dimension perpendicular to the screen
+surface.  Where two overlap, the one higher up covers the one
+underneath.  You can @dfn{raise} or @dfn{lower} a frame using the
+functions @code{raise-frame} and @code{lower-frame}.
 
 @deffn Command raise-frame &optional frame
 This function raises frame @var{frame} (default, the selected frame).
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 9e1d3f9c6ae..cab6d12a3d8 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -23,6 +23,7 @@ define them.
 * Closures::              Functions that enclose a lexical environment.
 * Obsolete Functions::    Declaring functions obsolete.
 * Inline Functions::      Functions that the compiler will expand inline.
+* Declare Form::          Adding additional information about a function.
 * Declaring Functions::   Telling the compiler that a function is defined.
 * Function Safety::       Determining whether a function is safe to call.
 * Related Topics::        Cross-references to specific Lisp primitives
@@ -521,7 +522,7 @@ Scheme.)
 is called @dfn{defining a function}, and it is done with the
 @code{defun} special form.
 
-@defspec defun name argument-list body-forms...
+@defmac defun name argument-list body-forms...
 @code{defun} is the usual way to define new Lisp functions.  It
 defines the symbol @var{name} as a function that looks like this:
 
@@ -578,7 +579,7 @@ without any hesitation or notification.  Emacs does not prevent you
 from doing this, because redefining a function is sometimes done
 deliberately, and there is no way to distinguish deliberate
 redefinition from unintentional redefinition.
-@end defspec
+@end defmac
 
 @cindex function aliases
 @defun defalias name definition &optional docstring
@@ -1132,29 +1133,46 @@ examining or altering the structure of closure objects.
 @node Obsolete Functions
 @section Declaring Functions Obsolete
 
-You can use @code{make-obsolete} to declare a function obsolete.  This
-indicates that the function may be removed at some stage in the future.
+  You can mark a named function as @dfn{obsolete}, meaning that it may
+be removed at some point in the future.  This causes Emacs to warn
+that the function is obsolete whenever it byte-compiles code
+containing that function, and whenever it displays the documentation
+for that function.  In all other respects, an obsolete function
+behaves like any other function.
+
+  The easiest way to mark a function as obsolete is to put a
+@code{(declare (obsolete @dots{}))} form in the function's
+@code{defun} definition.  @xref{Declare Form}.  Alternatively, you can
+use the @code{make-obsolete} function, described below.
+
+  A macro (@pxref{Macros}) can also be marked obsolete with
+@code{make-obsolete}; this has the same effects as for a function.  An
+alias for a function or macro can also be marked as obsolete; this
+makes the alias itself obsolete, not the function or macro which it
+resolves to.
 
 @defun make-obsolete obsolete-name current-name &optional when
-This function makes the byte compiler warn that the function
-@var{obsolete-name} is obsolete.  If @var{current-name} is a symbol, the
-warning message says to use @var{current-name} instead of
-@var{obsolete-name}.  @var{current-name} does not need to be an alias for
-@var{obsolete-name}; it can be a different function with similar
-functionality.  If @var{current-name} is a string, it is the warning
-message.
+This function marks @var{obsolete-name} as obsolete.
+@var{obsolete-name} should be a symbol naming a function or macro, or
+an alias for a function or macro.
+
+If @var{current-name} is a symbol, the warning message says to use
+@var{current-name} instead of @var{obsolete-name}.  @var{current-name}
+does not need to be an alias for @var{obsolete-name}; it can be a
+different function with similar functionality.  @var{current-name} can
+also be a string, which serves as the warning message.  The message
+should begin in lower case, and end with a period.  It can also be
+@code{nil}, in which case the warning message provides no additional
+details.
 
 If provided, @var{when} should be a string indicating when the function
 was first made obsolete---for example, a date or a release number.
 @end defun
 
-You can define a function as an alias and declare it obsolete at the
-same time using the macro @code{define-obsolete-function-alias}:
-
 @defmac define-obsolete-function-alias obsolete-name current-name &optional when docstring
-This macro marks the function @var{obsolete-name} obsolete and also
-defines it as an alias for the function @var{current-name}.  It is
-equivalent to the following:
+This convenience macro marks the function @var{obsolete-name} obsolete
+and also defines it as an alias for the function @var{current-name}.
+It is equivalent to the following:
 
 @example
 (defalias @var{obsolete-name} @var{current-name} @var{docstring})
@@ -1236,6 +1254,63 @@ body uses the arguments, as you do for macros.
   After an inline function is defined, its inline expansion can be
 performed later on in the same file, just like macros.
 
+@node Declare Form
+@section The @code{declare} Form
+@findex declare
+
+  @code{declare} is a special macro which can be used to add ``meta''
+properties to a function or macro: for example, marking it as
+obsolete, or giving its forms a special @key{TAB} indentation
+convention in Emacs Lisp mode.
+
+@anchor{Definition of declare}
+@defmac declare @var{specs}@dots{}
+This macro ignores its arguments and evaluates to @code{nil}; it has
+no run-time effect.  However, when a @code{declare} form occurs as the
+@emph{very first form} in the body of a @code{defun} function
+definition or a @code{defmacro} macro definition (@pxref{Defining
+Macros}, for a description of @code{defmacro}), it appends the
+properties specified by @var{specs} to the function or macro.  This
+work is specially performed by the @code{defun} and @code{defmacro}
+macros.
+
+Note that if you put a @code{declare} form in an interactive function,
+it should go before the @code{interactive} form.
+
+Each element in @var{specs} should have the form @code{(@var{property}
+@var{args}@dots{})}, which should not be quoted.  These have the
+following effects:
+
+@table @code
+@item (advertised-calling-convention @var{signature} @var{when})
+This acts like a call to @code{set-advertised-calling-convention}
+(@pxref{Obsolete Functions}); @var{signature} specifies the correct
+argument list for calling the function or macro, and @var{when} should
+be a string indicating when the variable was first made obsolete.
+
+@item (debug @var{edebug-form-spec})
+This is valid for macros only.  When stepping through the macro with
+Edebug, use @var{edebug-form-spec}.  @xref{Instrumenting Macro Calls}.
+
+@item (doc-string @var{n})
+Use element number @var{n}, if any, as the documentation string.
+
+@item (indent @var{indent-spec})
+Indent calls to this function or macro according to @var{indent-spec}.
+This is typically used for macros, though it works for functions too.
+@xref{Indenting Macros}.
+
+@item (obsolete @var{current-name} @var{when})
+Mark the function or macro as obsolete, similar to a call to
+@code{make-obsolete} (@pxref{Obsolete Functions}).  @var{current-name}
+should be a symbol (in which case the warning message says to use that
+instead), a string (specifying the warning message), or @code{nil} (in
+which case the warning message gives no extra details).  @var{when}
+should be a string indicating when the function or macro was first
+made obsolete.
+@end table
+@end defmac
+
 @node Declaring Functions
 @section Telling the Compiler that a Function is Defined
 @cindex function declaration
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 5dd8f3c11f5..1375a057a5a 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -58,11 +58,17 @@ use @kbd{C-h f} (@code{describe-function}) or @kbd{C-h v}
 are many other conventions for documentation strings; see
 @ref{Documentation Tips}.
 
-  Documentation strings can contain several special substrings, which
-stand for key bindings to be looked up in the current keymaps when the
-documentation is displayed.  This allows documentation strings to refer
-to the keys for related commands and be accurate even when a user
-rearranges the key bindings.  (@xref{Keys in Documentation}.)
+  Documentation strings can contain several special text sequences,
+referring to key bindings which are looked up in the current keymaps
+when the user views the documentation.  This allows the help commands
+to display the correct keys even if a user rearranges the default key
+bindings.  @xref{Keys in Documentation}.
+
+  In the documentation string of an autoloaded command
+(@pxref{Autoload}), these special text sequences have an additional
+special effect: they cause @kbd{C-h f} (@code{describe-function}) on
+the command to trigger autoloading.  (This is needed for correctly
+setting up the hyperlinks in the @file{*Help*} buffer).
 
 @vindex emacs-lisp-docstring-fill-column
   Emacs Lisp mode fills documentation strings to the width
diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index 3c9bee96639..aa243185359 100644
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -384,11 +384,13 @@ non-@acronym{ASCII} characters written as @code{?v@var{literal}}.
 @section Autoload
 @cindex autoload
 
-  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
+  The @dfn{autoload} facility lets you register the existence of a
+function or macro, but put off loading the file that defines it.  The
+first call to the function automatically loads the proper library, in
 order to install the real definition and other associated code, then
 runs the real definition as if it had been loaded all along.
+Autoloading can also be triggered by looking up the documentation of
+the function or macro (@pxref{Documentation Basics}).
 
   There are two ways to set up an autoloaded function: by calling
 @code{autoload}, and by writing a special ``magic'' comment in the
diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi
index efe298bf647..0a5152a43a1 100644
--- a/doc/lispref/macros.texi
+++ b/doc/lispref/macros.texi
@@ -235,43 +235,8 @@ of constants and nonconstant parts.  To make this easier, use the
 @end example
 
   The body of a macro definition can include a @code{declare} form,
-which can specify how @key{TAB} should indent macro calls, and how to
-step through them for Edebug.
-
-@defmac declare @var{specs}@dots{}
-@anchor{Definition of declare}
-A @code{declare} form is used in a macro definition to specify various
-additional information about it.  The following specifications are
-currently supported:
-
-@table @code
-@item (debug @var{edebug-form-spec})
-Specify how to step through macro calls for Edebug.
-@xref{Instrumenting Macro Calls}.
-
-@item (indent @var{indent-spec})
-Specify how to indent calls to this macro.  @xref{Indenting Macros},
-for more details.
-
-@item (doc-string @var{number})
-Specify which element of the macro is the documentation string, if
-any.
-@end table
-
-A @code{declare} form only has its special effect in the body of a
-@code{defmacro} form if it immediately follows the documentation
-string, if present, or the argument list otherwise.  (Strictly
-speaking, @emph{several} @code{declare} forms can follow the
-documentation string or argument list, but since a @code{declare} form
-can have several @var{specs}, they can always be combined into a
-single form.)  When used at other places in a @code{defmacro} form, or
-outside a @code{defmacro} form, @code{declare} just returns @code{nil}
-without evaluating any @var{specs}.
-@end defmac
-
-  No macro absolutely needs a @code{declare} form, because that form
-has no effect on how the macro expands, on what the macro means in the
-program.  It only affects the secondary features listed above.
+which specifies additional properties about the macro.  @xref{Declare
+Form}.
 
 @node Problems with Macros
 @section Common Problems Using Macros
diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi
index 7c9672a38c0..a086f2b3af1 100644
--- a/doc/lispref/numbers.texi
+++ b/doc/lispref/numbers.texi
@@ -48,9 +48,8 @@ to
 @tex
 @math{2^{29}-1}),
 @end tex
-but some machines provide a wider range.  Many examples in this
-chapter assume that an integer has 30 bits and that floating point
-numbers are IEEE double precision.
+but many machines provide a wider range.  Many examples in this
+chapter assume the minimum integer width of 30 bits.
 @cindex overflow
 
   The Lisp reader reads an integer as a sequence of digits with optional
@@ -160,8 +159,9 @@ The value of this variable is the smallest integer that Emacs Lisp can
 handle.  It is negative.
 @end defvar
 
-  @xref{Character Codes, max-char}, for the maximum value of a valid
-character codepoint.
+  In Emacs Lisp, text characters are represented by integers.  Any
+integer between zero and the value of @code{max-char}, inclusive, is
+considered to be valid as a character.  @xref{String Basics}.
 
 @node Float Basics
 @section Floating Point Basics
@@ -171,8 +171,8 @@ character codepoint.
 not integral.  The precise range of floating point numbers is
 machine-specific; it is the same as the range of the C data type
 @code{double} on the machine you are using.  Emacs uses the
-@acronym{IEEE} floating point standard where possible (the standard is
-supported by most modern computers).
+@acronym{IEEE} floating point standard, which is supported by all
+modern computers.
 
   The read syntax for floating point numbers requires either a decimal
 point (with at least one digit following), an exponent, or both.  For
@@ -316,17 +316,16 @@ compare them, then you test whether two values are the same
 @emph{object}.  By contrast, @code{=} compares only the numeric values
 of the objects.
 
-  At present, each integer value has a unique Lisp object in Emacs Lisp.
+  In Emacs Lisp, each integer value is a unique Lisp object.
 Therefore, @code{eq} is equivalent to @code{=} where integers are
-concerned.  It is sometimes convenient to use @code{eq} for comparing an
-unknown value with an integer, because @code{eq} does not report an
-error if the unknown value is not a number---it accepts arguments of any
-type.  By contrast, @code{=} signals an error if the arguments are not
-numbers or markers.  However, it is a good idea to use @code{=} if you
-can, even for comparing integers, just in case we change the
-representation of integers in a future Emacs version.
-
-  Sometimes it is useful to compare numbers with @code{equal}; it
+concerned.  It is sometimes convenient to use @code{eq} for comparing
+an unknown value with an integer, because @code{eq} does not report an
+error if the unknown value is not a number---it accepts arguments of
+any type.  By contrast, @code{=} signals an error if the arguments are
+not numbers or markers.  However, it is better programming practice to
+use @code{=} if you can, even for comparing integers.
+
+  Sometimes it is useful to compare numbers with @code{equal}, which
 treats two numbers as equal if they have the same data type (both
 integers, or both floating point) and the same value.  By contrast,
 @code{=} can treat an integer and a floating point number as equal.
@@ -439,15 +438,16 @@ If @var{number} is already a floating point number, @code{float} returns
 it unchanged.
 @end defun
 
-There are four functions to convert floating point numbers to integers;
-they differ in how they round.  All accept an argument @var{number}
-and an optional argument @var{divisor}.  Both arguments may be
-integers or floating point numbers.  @var{divisor} may also be
+  There are four functions to convert floating point numbers to
+integers; they differ in how they round.  All accept an argument
+@var{number} and an optional argument @var{divisor}.  Both arguments
+may be integers or floating point numbers.  @var{divisor} may also be
 @code{nil}.  If @var{divisor} is @code{nil} or omitted, these
 functions convert @var{number} to an integer, or return it unchanged
 if it already is an integer.  If @var{divisor} is non-@code{nil}, they
 divide @var{number} by @var{divisor} and convert the result to an
-integer.  An @code{arith-error} results if @var{divisor} is 0.
+integer.  integer.  If @var{divisor} is zero (whether integer or
+floating-point), Emacs signals an @code{arith-error} error.
 
 @defun truncate number &optional divisor
 This returns @var{number}, converted to an integer by rounding towards
@@ -524,14 +524,12 @@ depending on your machine.
 @section Arithmetic Operations
 @cindex arithmetic operations
 
-  Emacs Lisp provides the traditional four arithmetic operations:
-addition, subtraction, multiplication, and division.  Remainder and modulus
-functions supplement the division functions.  The functions to
-add or subtract 1 are provided because they are traditional in Lisp and
-commonly used.
-
-  All of these functions except @code{%} return a floating point value
-if any argument is floating.
+  Emacs Lisp provides the traditional four arithmetic operations
+(addition, subtraction, multiplication, and division), as well as
+remainder and modulus functions, and functions to add or subtract 1.
+Except for @code{%}, each of these functions accepts both integer and
+floating point arguments, and returns a floating point number if any
+argument is a floating point number.
 
   It is important to note that in Emacs Lisp, arithmetic functions
 do not check for overflow.  Thus @code{(1+ 536870911)} may evaluate to
@@ -620,40 +618,49 @@ quotient.  If there are additional arguments @var{divisors}, then it
 divides @var{dividend} by each divisor in turn.  Each argument may be a
 number or a marker.
 
-If all the arguments are integers, then the result is an integer too.
-This means the result has to be rounded.  On most machines, the result
-is rounded towards zero after each division, but some machines may round
-differently with negative arguments.  This is because the Lisp function
-@code{/} is implemented using the C division operator, which also
-permits machine-dependent rounding.  As a practical matter, all known
-machines round in the standard fashion.
-
-@cindex @code{arith-error} in division
-If you divide an integer by 0, an @code{arith-error} error is signaled.
-(@xref{Errors}.)  Floating point division by zero returns either
-infinity or a NaN if your machine supports @acronym{IEEE} floating point;
-otherwise, it signals an @code{arith-error} error.
+If all the arguments are integers, the result is an integer, obtained
+by rounding the quotient towards zero after each division.
+(Hypothetically, some machines may have different rounding behavior
+for negative arguments, because @code{/} is implemented using the C
+division operator, which permits machine-dependent rounding; but this
+does not happen in practice.)
 
 @example
 @group
 (/ 6 2)
      @result{} 3
 @end group
+@group
 (/ 5 2)
      @result{} 2
+@end group
+@group
 (/ 5.0 2)
      @result{} 2.5
+@end group
+@group
 (/ 5 2.0)
      @result{} 2.5
+@end group
+@group
 (/ 5.0 2.0)
      @result{} 2.5
+@end group
+@group
 (/ 25 3 2)
      @result{} 4
+@end group
 @group
 (/ -17 6)
-     @result{} -2   @r{(could in theory be @minus{}3 on some machines)}
+     @result{} -2
 @end group
 @end example
+
+@cindex @code{arith-error} in division
+If you divide an integer by the integer 0, Emacs signals an
+@code{arith-error} error (@pxref{Errors}).  If you divide a floating
+point number by 0, or divide by the floating point number 0.0, the
+result is either positive or negative infinity (@pxref{Float Basics}).
 @end defun
 
 @defun % dividend divisor
@@ -661,10 +668,18 @@ otherwise, it signals an @code{arith-error} error.
 This function returns the integer remainder after division of @var{dividend}
 by @var{divisor}.  The arguments must be integers or markers.
 
-For negative arguments, the remainder is in principle machine-dependent
-since the quotient is; but in practice, all known machines behave alike.
+For any two integers @var{dividend} and @var{divisor},
+
+@example
+@group
+(+ (% @var{dividend} @var{divisor})
+   (* (/ @var{dividend} @var{divisor}) @var{divisor}))
+@end group
+@end example
 
-An @code{arith-error} results if @var{divisor} is 0.
+@noindent
+always equals @var{dividend}.  If @var{divisor} is zero, Emacs signals
+an @code{arith-error} error.
 
 @example
 (% 9 4)
@@ -676,18 +691,6 @@ An @code{arith-error} results if @var{divisor} is 0.
 (% -9 -4)
      @result{} -1
 @end example
-
-For any two integers @var{dividend} and @var{divisor},
-
-@example
-@group
-(+ (% @var{dividend} @var{divisor})
-   (* (/ @var{dividend} @var{divisor}) @var{divisor}))
-@end group
-@end example
-
-@noindent
-always equals @var{dividend}.
 @end defun
 
 @defun mod dividend divisor
@@ -697,10 +700,9 @@ in other words, the remainder after division of @var{dividend}
 by @var{divisor}, but with the same sign as @var{divisor}.
 The arguments must be numbers or markers.
 
-Unlike @code{%}, @code{mod} returns a well-defined result for negative
-arguments.  It also permits floating point arguments; it rounds the
-quotient downward (towards minus infinity) to an integer, and uses that
-quotient to compute the remainder.
+Unlike @code{%}, @code{mod} permits floating point arguments; it
+rounds the quotient downward (towards minus infinity) to an integer,
+and uses that quotient to compute the remainder.
 
 If @var{divisor} is zero, @code{mod} signals an @code{arith-error}
 error if both arguments are integers, and returns a NaN otherwise.
@@ -1086,8 +1088,8 @@ numbers as arguments.
 @defun sin arg
 @defunx cos arg
 @defunx tan arg
-These are the ordinary trigonometric functions, with argument measured
-in radians.
+These are the basic trigonometric functions, with argument @var{arg}
+measured in radians.
 @end defun
 
 @defun asin arg
@@ -1154,20 +1156,6 @@ This function returns the logarithm of @var{arg}, with base
 returns a NaN.
 @end defun
 
-@ignore
-@defun expm1 arg
-This function returns @code{(1- (exp @var{arg}))}, but it is more
-accurate than that when @var{arg} is negative and @code{(exp @var{arg})}
-is close to 1.
-@end defun
-
-@defun log1p arg
-This function returns @code{(log (1+ @var{arg}))}, but it is more
-accurate than that when @var{arg} is so small that adding 1 to it would
-lose accuracy.
-@end defun
-@end ignore
-
 @defun log10 arg
 This function returns the logarithm of @var{arg}, with base 10:
 @code{(log10 @var{x})} @equiv{} @code{(log @var{x} 10)}.
@@ -1201,20 +1189,20 @@ The mathematical constant @math{pi} (3.14159@dots{}).
 @section Random Numbers
 @cindex random numbers
 
-A deterministic computer program cannot generate true random numbers.
-For most purposes, @dfn{pseudo-random numbers} suffice.  A series of
-pseudo-random numbers is generated in a deterministic fashion.  The
-numbers are not truly random, but they have certain properties that
-mimic a random series.  For example, all possible values occur equally
-often in a pseudo-random series.
+  A deterministic computer program cannot generate true random
+numbers.  For most purposes, @dfn{pseudo-random numbers} suffice.  A
+series of pseudo-random numbers is generated in a deterministic
+fashion.  The numbers are not truly random, but they have certain
+properties that mimic a random series.  For example, all possible
+values occur equally often in a pseudo-random series.
 
-In Emacs, pseudo-random numbers are generated from a ``seed''.
-Starting from any given seed, the @code{random} function always
-generates the same sequence of numbers.  Emacs typically starts with a
-different seed each time, so the sequence of values of @code{random}
-typically differs in each Emacs run.
+  Pseudo-random numbers are generated from a ``seed''.  Starting from
+any given seed, the @code{random} function always generates the same
+sequence of numbers.  By default, Emacs initializes the random seed at
+startup, in such a way that the sequence of values of @code{random}
+(with overwhelming likelihood) differs in each Emacs run.
 
-Sometimes you want the random number sequence to be repeatable.  For
+  Sometimes you want the random number sequence to be repeatable.  For
 example, when debugging a program whose behavior depends on the random
 number sequence, it is helpful to get the same behavior in each
 program run.  To make the sequence repeat, execute @code{(random "")}.
@@ -1227,8 +1215,10 @@ This function returns a pseudo-random integer.  Repeated calls return a
 series of pseudo-random integers.
 
 If @var{limit} is a positive integer, the value is chosen to be
-nonnegative and less than @var{limit}.  Otherwise, the value
-might be any integer representable in Lisp.
+nonnegative and less than @var{limit}.  Otherwise, the value might be
+any integer representable in Lisp, i.e.@: an integer between
+@code{most-negative-fixnum} and @code{most-positive-fixnum}
+(@pxref{Integer Basics}).
 
 If @var{limit} is @code{t}, it means to choose a new seed based on the
 current time of day and on Emacs's process @acronym{ID} number.
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 68e53c78972..54754f8e5e9 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -70,13 +70,11 @@ 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.
+If the library @file{leim-list.el} exists, Emacs loads it.  This
+optional library is intended for registering input methods; Emacs
+looks for it in @code{load-path} (@pxref{Library Search}), skipping
+those directories containing the standard Emacs libraries (since
+@file{leim-list.el} should not exist in those directories).
 
 @vindex before-init-time
 @item
@@ -1159,6 +1157,20 @@ This function returns the effective @acronym{UID} of the user.
 The value may be a floating point number.
 @end defun
 
+@defun system-users
+This function returns a list of strings, listing the user names on the
+system.  If Emacs cannot retrieve this information, the return value
+is a list containing just the value of @code{user-real-login-name}.
+@end defun
+
+@cindex user groups
+@defun system-groups
+This function returns a list of strings, listing the names of user
+groups on the system.  If Emacs cannot retrieve this information, the
+return value is @code{nil}.
+@end defun
+
+
 @node Time of Day
 @section Time of Day
 
@@ -1812,6 +1824,29 @@ 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.
 
+  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
+@item
+It blocks out all process output (since Emacs accepts process output
+only while waiting).
+
+@item
+It blocks out any idle timers that ought to run during that time.
+@end itemize
+
+@noindent
+Similarly, do not write an idle timer function that sets up another
+idle timer (including the same idle timer) with @var{secs} argument
+less than or equal to the current idleness time.  Such a timer will
+run almost immediately, and continue running again and again, instead
+of waiting for the next time Emacs becomes idle.  The correct approach
+is to reschedule with an appropriate increment of the current value of
+the idleness time, as described below.
+
 @defun current-idle-time
 If Emacs is idle, this function returns the length of time Emacs has
 been idle, as a list of four integers: @code{(@var{sec-high}
@@ -1820,60 +1855,34 @@ been idle, as a list of four integers: @code{(@var{sec-high}
 
 When Emacs is not idle, @code{current-idle-time} returns @code{nil}.
 This is a convenient way to test whether Emacs is idle.
+@end defun
 
-The main use of this function is when an idle timer function wants to
-``take a break'' for a while.  It can set up another idle timer to
-call the same function again, after a few seconds more idleness.
-Here's an example:
+  The main use of @code{current-idle-time} is when an idle timer
+function wants to ``take a break'' for a while.  It can set up another
+idle timer to call the same function again, after a few seconds more
+idleness.  Here's an example:
 
-@smallexample
-(defvar resume-timer nil
-  "Timer that `timer-function' used to reschedule itself, or nil.")
+@example
+(defvar my-resume-timer nil
+  "Timer for `my-timer-function' to reschedule itself, or nil.")
 
-(defun timer-function ()
-  ;; @r{If the user types a command while @code{resume-timer}}
+(defun my-timer-function ()
+  ;; @r{If the user types a command while @code{my-resume-timer}}
   ;; @r{is active, the next time this function is called from}
-  ;; @r{its main idle timer, deactivate @code{resume-timer}.}
-  (when resume-timer
-    (cancel-timer resume-timer))
+  ;; @r{its main idle timer, deactivate @code{my-resume-timer}.}
+  (when my-resume-timer
+    (cancel-timer my-resume-timer))
   ...@var{do the work for a while}...
   (when @var{taking-a-break}
-    (setq resume-timer
+    (setq my-resume-timer
           (run-with-idle-timer
             ;; Compute an idle time @var{break-length}
             ;; more than the current value.
             (time-add (current-idle-time)
                       (seconds-to-time @var{break-length}))
             nil
-            'timer-function))))
-@end smallexample
-@end defun
-
-  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
-@item
-It blocks out all process output (since Emacs accepts process output
-only while waiting).
-
-@item
-It blocks out any idle timers that ought to run during that time.
-@end itemize
-
-@noindent
-For similar reasons, do not write an idle timer function that sets
-up another idle time (including the same idle timer) with the
-@var{secs} argument less or equal to the current idleness time.  Such
-a timer will run almost immediately, and continue running again and
-again, instead of waiting for the next time Emacs becomes idle.
-
-@noindent
-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.
+            'my-timer-function))))
+@end example
 
 @node Terminal Input
 @section Terminal Input
@@ -1907,7 +1916,6 @@ If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff}
 (@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal.  This
 has no effect except in @sc{cbreak} mode.
 
-@c Emacs 19 feature
 The argument @var{meta} controls support for input character codes
 above 127.  If @var{meta} is @code{t}, Emacs converts characters with
 the 8th bit set into Meta characters.  If @var{meta} is @code{nil},
@@ -1916,7 +1924,6 @@ it as a parity bit.  If @var{meta} is neither @code{t} nor @code{nil},
 Emacs uses all 8 bits of input unchanged.  This is good for terminals
 that use 8-bit character sets.
 
-@c Emacs 19 feature
 If @var{quit-char} is non-@code{nil}, it specifies the character to
 use for quitting.  Normally this character is @kbd{C-g}.
 @xref{Quitting}.
@@ -1925,7 +1932,6 @@ use for quitting.  Normally this character is @kbd{C-g}.
 The @code{current-input-mode} function returns the input mode settings
 Emacs is currently using.
 
-@c Emacs 19 feature
 @defun current-input-mode
 This function returns the current mode for reading keyboard input.  It
 returns a list, corresponding to the arguments of @code{set-input-mode},
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index b7097e057c0..865435c91b3 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -35,28 +35,31 @@ keyboard character events.
 @node String Basics
 @section String and Character Basics
 
-  Characters are represented in Emacs Lisp as integers;
-whether an integer is a character or not is determined only by how it is
-used.  Thus, strings really contain integers.  @xref{Character Codes},
-for details about character representation in Emacs.
-
-  The length of a string (like any array) is fixed, and cannot be
-altered once the string exists.  Strings in Lisp are @emph{not}
-terminated by a distinguished character code.  (By contrast, strings in
-C are terminated by a character with @acronym{ASCII} code 0.)
+  A character is a Lisp object which represents a single character of
+text.  In Emacs Lisp, characters are simply integers; whether an
+integer is a character or not is determined only by how it is used.
+@xref{Character Codes}, for details about character representation in
+Emacs.
+
+  A string is a fixed sequence of characters.  It is a type of
+sequence called a @dfn{array}, meaning that its length is fixed and
+cannot be altered once it is created (@pxref{Sequences Arrays
+Vectors}).  Unlike in C, Emacs Lisp strings are @emph{not} terminated
+by a distinguished character code.
 
   Since strings are arrays, and therefore sequences as well, you can
-operate on them with the general array and sequence functions.
-(@xref{Sequences Arrays Vectors}.)  For example, you can access or
-change individual characters in a string using the functions @code{aref}
-and @code{aset} (@pxref{Array Functions}).  However, note that
-@code{length} should @emph{not} be used for computing the width of a
-string on display; use @code{string-width} (@pxref{Width}) instead.
-
-  There are two text representations for non-@acronym{ASCII} characters in
-Emacs strings (and in buffers): unibyte and multibyte (@pxref{Text
-Representations}).  For most Lisp programming, you don't need to be
-concerned with these two representations.
+operate on them with the general array and sequence functions
+documented in @ref{Sequences Arrays Vectors}.  For example, you can
+access or change individual characters in a string using the functions
+@code{aref} and @code{aset} (@pxref{Array Functions}).  However, note
+that @code{length} should @emph{not} be used for computing the width
+of a string on display; use @code{string-width} (@pxref{Width})
+instead.
+
+  There are two text representations for non-@acronym{ASCII}
+characters in Emacs strings (and in buffers): unibyte and multibyte.
+For most Lisp programming, you don't need to be concerned with these
+two representations.  @xref{Text Representations}, for details.
 
   Sometimes key sequences are represented as unibyte strings.  When a
 unibyte string is a key sequence, string elements in the range 128 to
@@ -88,7 +91,7 @@ for information about the syntax of characters and strings.
 representations and to encode and decode character codes.
 
 @node Predicates for Strings
-@section The Predicates for Strings
+@section Predicates for Strings
 
 For more information about general sequence and array predicates,
 see @ref{Sequences Arrays Vectors}, and @ref{Arrays}.