9 files changed, 45 insertions, 18 deletions

diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in
index 9fa5901a1ac..50d6d161ef6 100644
--- a/doc/lispref/Makefile.in
+++ b/doc/lispref/Makefile.in
@@ -118,6 +118,7 @@ srcs = \
   $(srcdir)/package.texi \
   $(srcdir)/positions.texi \
   $(srcdir)/processes.texi \
+  $(srcdir)/records.texi \
   $(srcdir)/searching.texi \
   $(srcdir)/sequences.texi \
   $(srcdir)/streams.texi \
diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index 57ff06085d9..9123e93a5bf 100644
--- a/doc/lispref/compile.texi
+++ b/doc/lispref/compile.texi
@@ -94,7 +94,7 @@ the @code{byte-compile} function.  You can compile a whole file with
 recorded in a buffer called @file{*Compile-Log*}, which uses
 Compilation mode.  @xref{Compilation Mode,,,emacs, The GNU Emacs
 Manual}.  However, if the variable @code{byte-compile-debug} is
-non-nil, error message will be signaled as Lisp errors instead
+non-@code{nil}, error messages will be signaled as Lisp errors instead
 (@pxref{Errors}).
 
 @cindex macro compilation
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index b257c328f4d..f7eafcadc44 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2282,7 +2282,8 @@ because this is not portable.  Always use
 @code{file-name-as-directory}.
 
   To avoid the issues mentioned above, or if the @var{dirname} value
-might be nil (for example, from an element of @code{load-path}), use:
+might be @code{nil} (for example, from an element of @code{load-path}),
+use:
 
 @example
 (expand-file-name @var{relfile} @var{dirname})
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index d84f09d8462..3f993901d4d 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -1753,8 +1753,8 @@ code) obey the advice and other calls (from C code) do not.
 @defmac define-advice symbol (where lambda-list &optional name depth) &rest body
 This macro defines a piece of advice and adds it to the function named
 @var{symbol}.  The advice is an anonymous function if @var{name} is
-nil or a function named @code{symbol@@name}.  See @code{advice-add}
-for explanation of other arguments.
+@code{nil} or a function named @code{symbol@@name}.  See
+@code{advice-add} for explanation of other arguments.
 @end defmac
 
 @defun advice-add symbol where function &optional props
diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index 73f5572e69d..71b054e063c 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -988,8 +988,9 @@ function is called with no arguments, prior to running each command,
 while @var{keymap} is active; it should return non-@code{nil} if
 @var{keymap} should stay active.
 
-The optional argument @var{on-exit}, if non-nil, specifies a function
-that is called, with no arguments, after @var{keymap} is deactivated.
+The optional argument @var{on-exit}, if non-@code{nil}, specifies a
+function that is called, with no arguments, after @var{keymap} is
+deactivated.
 
 This function works by adding and removing @var{keymap} from the
 variable @code{overriding-terminal-local-map}, which takes precedence
diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index 0c993806824..230ea4b48eb 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -1514,9 +1514,10 @@ of property lists and association lists.
 @defun assoc key alist &optional testfn
 This function returns the first association for @var{key} in
 @var{alist}, comparing @var{key} against the alist elements using
-@var{testfn} if non-nil, or @code{equal} if nil (@pxref{Equality
-Predicates}).  It returns @code{nil} if no association in @var{alist}
-has a @sc{car} equal to @var{key}.  For example:
+@var{testfn} if it is non-@code{nil} and @code{equal} otherwise
+(@pxref{Equality Predicates}).  It returns @code{nil} if no
+association in @var{alist} has a @sc{car} equal to @var{key}.  For
+example:
 
 @smallexample
 (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index bd94aeadf15..1a601baee86 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -314,6 +314,11 @@ Data}, for other possible forms).  The name of the mode appears
 in the mode line.
 
 @item
+Calling the major mode command twice in direct succession should not
+fail and should do the same thing as calling the command only once.
+In other words, the major mode command should be idempotent.
+
+@item
 @cindex functions in modes
 Since all global names are in the same name space, all the global
 variables, constants, and functions that are part of the mode should
@@ -1412,6 +1417,10 @@ a minor mode in a mode hook is a little uglier:
 @noindent
 However, this is not very commonly done.
 
+  Enabling or disabling a minor mode twice in direct succession should
+not fail and should do the same thing as enabling or disabling it only
+once.  In other words, the minor mode command should be idempotent.
+
 @item
 Add an element to @code{minor-mode-alist} for each minor mode
 (@pxref{Definition of minor-mode-alist}), if you want to indicate the
diff --git a/doc/lispref/records.texi b/doc/lispref/records.texi
index 7cc36f14068..cae0f31f273 100644
--- a/doc/lispref/records.texi
+++ b/doc/lispref/records.texi
@@ -5,7 +5,7 @@
 @c See the file elisp.texi for copying conditions.
 @node Records
 @chapter Records
-@cindex record
+@cindex records
 
   The purpose of records is to allow programmers to create objects
 with new types that are not built into Emacs.  They are used as the
@@ -28,6 +28,13 @@ type descriptor, the symbol naming its type will be returned;
 list specifying the contents.  The first list element must be the
 record type.  The following elements are the record slots.
 
+  To avoid conflicts with other type names, Lisp programs that define
+new types of records should normally use the naming conventions of the
+package where these record types are introduced for the names of the
+types.  Note that the names of the types which could possibly conflict
+might not be known at the time the package defining a record type is
+loaded; they could be loaded at some future point in time.
+
   A record is considered a constant for evaluation: the result of
 evaluating it is the same record.  This does not evaluate or even
 examine the slots.  @xref{Self-Evaluating Forms}.
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 08ed092c48c..d73b410f977 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -125,11 +125,13 @@ including for the case where @var{object} is a deleted window.
 as @dfn{selected within the frame}.  For the selected frame, that
 window is called the @dfn{selected window}---the one in which most
 editing takes place, and in which the cursor for selected windows
-appears (@pxref{Cursor Parameters}).  The selected window's buffer is
-usually also the current buffer, except when @code{set-buffer} has
-been used (@pxref{Current Buffer}).  As for non-selected frames, the
-window selected within the frame becomes the selected window if the
-frame is ever selected.  @xref{Selecting Windows}.
+appears (@pxref{Cursor Parameters}).  Keyboard input that inserts or
+deletes text is also normally directed to this window.   The selected
+window's buffer is usually also the current buffer, except when
+@code{set-buffer} has been used (@pxref{Current Buffer}).  As for
+non-selected frames, the window selected within the frame becomes the
+selected window if the frame is ever selected.  @xref{Selecting
+Windows}.
 
 @defun selected-window
 This function returns the selected window (which is always a live
@@ -1726,7 +1728,7 @@ windows.
 
 @defun select-window window &optional norecord
 This function makes @var{window} the selected window and the window
-selected within its frame (@pxref{Basic Windows}) and selects that
+selected within its frame (@pxref{Basic Windows}), and selects that
 frame.  It also makes @var{window}'s buffer (@pxref{Buffers and
 Windows}) current and sets that buffer's value of @code{point} to the
 value of @code{window-point} (@pxref{Window Point}) in @var{window}.
@@ -1743,6 +1745,11 @@ next time.  If @var{norecord} is non-@code{nil}, such updates are
 usually not performed.  If, however, @var{norecord} equals the special
 symbol @code{mark-for-redisplay}, the additional actions mentioned above
 are omitted but @var{window} will be nevertheless updated.
+
+Note that sometimes selecting a window is not enough to show it, or
+make its frame the top-most frame on display: you may also need to
+raise the frame or make sure input focus is directed to that frame.
+@xref{Input Focus}.
 @end defun
 
 @cindex select window hook
@@ -3059,7 +3066,7 @@ This function handles @var{window} and its buffer after quitting.  The
 optional argument @var{window} must be a live window and defaults to
 the selected one. The function's behavior is determined by the four
 elements of the @code{quit-restore} window parameter (@pxref{Window
-Parameters}), which is set to nil afterwards.
+Parameters}), which is set to @code{nil} afterwards.
 
 The window is deleted entirely if: 1) the first element of the
 @code{quit-restore} parameter is one of 'window or 'frame, 2) the
@@ -3126,7 +3133,7 @@ possible to set it manually, using the following code for displaying
 @end group
 @end example
 
-Setting the window history to nil ensures that a future call to
+Setting the window history to @code{nil} ensures that a future call to
 @code{quit-window} can delete the window altogether.
 
 @end defun