12 files changed, 84 insertions, 42 deletions

diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi
index e108a4e7c10..f342aef705e 100644
--- a/doc/emacs/building.texi
+++ b/doc/emacs/building.texi
@@ -394,10 +394,11 @@ match will be highlighted, instead of the entire source line.
   The @command{grep} commands will offer to save buffers before
 running.  This is controlled by the @code{grep-save-buffers} variable.
 The possible values are either @code{nil} (don't save), @code{ask}
-(ask before saving), a function which will be used as a predicate (and
-is called with the file name as the parameter and should return
-non-nil if the buffer is to be saved), and any other non-@code{nil}
-value means that all buffers should be saved without asking.
+(ask before saving), or a function which will be used as a predicate
+(and is called with the file name as the parameter and should return
+non-@code{nil} if the buffer is to be saved).  Any other
+non-@code{nil} value means that all buffers should be saved without
+asking.
 
 @findex grep-find
 @findex find-grep
diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index c94d690cf7f..0c994078327 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -243,9 +243,9 @@ location of point.  Double-clicking on the end of a parenthetical
 grouping or end string-delimiter keeps point at the end of the region
 by default, so the beginning of the region will not be visible if it
 is above the top of the window; setting the user option
-@code{mouse-select-region-move-to-beginning} to non-nil changes this
-to move point to the beginning of the region, scrolling the display
-backward if necessary.
+@code{mouse-select-region-move-to-beginning} to non-@code{nil} changes
+this to move point to the beginning of the region, scrolling the
+display backward if necessary.
 
 @item Double-Drag-mouse-1
 Select the text you drag across, in the form of whole words.
@@ -1094,18 +1094,6 @@ file on a Dired buffer moves or copies the file (according to the
 conventions of the application it came from) into the directory
 displayed in that buffer.
 
-@vindex mouse-drag-and-drop-region
-  Emacs can also optionally drag the region of text by mouse into
-another portion of this or another buffer.  To enable that, customize
-the variable @code{mouse-drag-and-drop-region} to a non-nil value.
-Normally, the text is moved, i.e. cut and pasted, when the destination
-is the same buffer as the origin; dropping the region on another
-buffer copies the text instead.  If the value of this variable names a
-modifier key, such as @samp{shift} or @samp{control} or @samp{alt},
-then pressing that modifier key when dropping the text will copy it
-instead of cutting it, even if you drop on the same buffer as the one
-from which the text came.
-
 @vindex dnd-open-file-other-window
   Dropping a file normally visits it in the window you drop it on.  If
 you prefer to visit the file in a new window in such cases, customize
@@ -1114,6 +1102,31 @@ the variable @code{dnd-open-file-other-window}.
   The XDND and Motif drag and drop protocols, and the old KDE 1.x
 protocol, are currently supported.
 
+@vindex mouse-drag-and-drop-region
+  Emacs can also optionally drag the region with the mouse into
+another portion of this or another buffer.  To enable that, customize
+the variable @code{mouse-drag-and-drop-region} to a non-@code{nil}
+value.  Normally, the text is moved, i.e. cut and pasted, when the
+destination is the same buffer as the origin; dropping the region on
+another buffer copies the text instead.  If the value of this variable
+names a modifier key, such as @samp{shift}, @samp{control} or
+@samp{alt}, then pressing that modifier key when dropping the text
+will copy it instead of cutting it, even if you drop on the same
+buffer as the one from which the text came.
+
+@vindex mouse-drag-and-drop-region-cut-when-buffers-differ
+@vindex mouse-drag-and-drop-region-show-tooltip
+@vindex mouse-drag-and-drop-region-show-cursor
+In order to cut text even when source and destination buffers differ,
+set the option
+@code{mouse-drag-and-drop-region-cut-when-buffers-differ} to a
+non-@code{nil} value.  By default, on a graphic display the selected
+text is shown in a tooltip and point moves together with the mouse
+cursor during dragging.  To suppress such behavior, set the options
+@code{mouse-drag-and-drop-region-show-tooltip} and/or
+@code{mouse-drag-and-drop-region-show-cursor} to @code{nil}.
+
+
 @node Menu Bars
 @section Menu Bars
 @cindex Menu Bar mode
diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi
index 7b334733d67..c4853686ae0 100644
--- a/doc/emacs/search.texi
+++ b/doc/emacs/search.texi
@@ -1746,12 +1746,13 @@ prompt, you can reuse search strings from previous incremental
 searches.  The text that matched is highlighted using the @code{match}
 face.  A numeric argument @var{n} specifies that @var{n} lines of
 context are to be displayed before and after each matching line.
+
 The default number of context lines is specified by the variable
-@code{list-matching-lines-default-context-lines}.
-When @code{list-matching-lines-jump-to-current-line} is non-nil,
-the current line is shown highlighted with face
-@code{list-matching-lines-current-line-face} and the point is set
-at the first match after such line.
+@code{list-matching-lines-default-context-lines}.  When
+@code{list-matching-lines-jump-to-current-line} is non-@code{nil} the
+current line is shown highlighted with face
+@code{list-matching-lines-current-line-face} and the point is set at
+the first match after such line.
 
 You can also run @kbd{M-s o} when an incremental search is active;
 this uses the current search string.
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