6 files changed, 55 insertions, 27 deletions

diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 2dbe9c27f2d..260f159851b 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -935,6 +935,10 @@ This is a normal hook run whenever the buffer list changes.  Functions
 (@pxref{Creating Buffers}), @code{rename-buffer} (@pxref{Buffer Names}),
 @code{kill-buffer} (@pxref{Killing Buffers}), @code{bury-buffer} (see
 above) and @code{select-window} (@pxref{Selecting Windows}).
+
+Functions run by this hook should avoid calling @code{select-window}
+with a nil @var{norecord} argument or @code{with-temp-buffer} since
+either may lead to infinite recursion.
 @end defvar
 
 @node Creating Buffers
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 95379b342b3..c4cb83977fc 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -4894,6 +4894,16 @@ and the buffer position where the @code{display} property was found,
 respectively.  Both positions can be different when @code{object} is a
 string.
 
+Note that @var{condition} will only be evaluated when redisplay
+examines the text where this display spec is located, so this feature
+is best suited for conditions that are relatively stable, i.e.@:
+yield, for each particular buffer position, the same results on every
+evaluation.  If the results change for the same text location, e.g.,
+if the result depends on the position of point, then the conditional
+specification might not do what you want, because redisplay examines
+only those parts of buffer text where it has reasons to assume that
+something changed since the last display cycle.
+
 @node Display Margins
 @subsection Displaying in the Margins
 @cindex display margins
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 5c99ea2781c..0e57cf9666f 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -16,7 +16,7 @@ described in @ref{Backups and Auto-Saving}.
 names.  A file name is a string.  Most of these functions expand file
 name arguments using the function @code{expand-file-name}, so that
 @file{~} is handled correctly, as are relative file names (including
-@file{../}).  @xref{File Name Expansion}.
+@file{../} and the empty string).  @xref{File Name Expansion}.
 
   In addition, certain @dfn{magic} file names are handled specially.
 For example, when a remote file name is specified, Emacs accesses the
@@ -2402,6 +2402,17 @@ This is for the sake of filesystems that have the concept of a
 superroot above the root directory @file{/}.  On other filesystems,
 @file{/../} is interpreted exactly the same as @file{/}.
 
+Expanding @file{.} or the empty string returns the default directory:
+
+@example
+@group
+(expand-file-name "." "/usr/spool/")
+     @result{} "/usr/spool"
+(expand-file-name "" "/usr/spool/")
+     @result{} "/usr/spool"
+@end group
+@end example
+
 Note that @code{expand-file-name} does @emph{not} expand environment
 variables; only @code{substitute-in-file-name} does that:
 
diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index cc0386c8fc7..6ad665a9502 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -2502,7 +2502,7 @@ can do it this way:
 
   Emacs usually shows a @dfn{menu bar} at the top of each frame.
 @xref{Menu Bars,,,emacs, The GNU Emacs Manual}.  Menu bar items are
-subcommands of the fake function key @code{menu-bar}, as defined
+subcommands of the fake function key @key{MENU-BAR}, as defined
 in the active keymaps.
 
   To add an item to the menu bar, invent a fake function key of your
@@ -2554,9 +2554,10 @@ bar item:
 @end example
 
 @noindent
-Here, @code{edit} is the fake function key used by the global map for
-the @samp{Edit} menu bar item.  The main reason to suppress a global
-menu bar item is to regain space for mode-specific items.
+Here, @code{edit} is the symbol produced by a fake function key, it is
+used by the global map for the @samp{Edit} menu bar item.  The main
+reason to suppress a global menu bar item is to regain space for
+mode-specific items.
 
 @defvar menu-bar-final-items
 Normally the menu bar shows global items followed by items defined by the
@@ -2601,7 +2602,7 @@ If the value is @code{grow-only}, the tool bar expands automatically,
 but does not contract automatically.
 
   The tool bar contents are controlled by a menu keymap attached to a
-fake function key called @code{tool-bar} (much like the way the menu
+fake function key called @key{TOOL-BAR} (much like the way the menu
 bar is controlled).  So you define a tool bar item using
 @code{define-key}, like this:
 
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 22592a57b05..3f6bee9821d 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -1237,6 +1237,7 @@ the conventions listed above:
     (modify-syntax-entry ?\\ ".   " st)
     ;; Add 'p' so M-c on 'hello' leads to 'Hello', not 'hello'.
     (modify-syntax-entry ?' "w p" st)
+    @dots{}
     st)
   "Syntax table used while in `text-mode'.")
 @end group
@@ -1246,6 +1247,7 @@ the conventions listed above:
 (defvar text-mode-map
   (let ((map (make-sparse-keymap)))
     (define-key map "\e\t" 'ispell-complete-word)
+    @dots{}
     map)
   "Keymap for `text-mode'.
 Many other modes, such as `mail-mode', `outline-mode' and
@@ -1289,11 +1291,11 @@ illustrate how these modes are written.
 @smallexample
 @group
 ;; @r{Create mode-specific table variables.}
-(defvar lisp-mode-abbrev-table nil)
-(define-abbrev-table 'lisp-mode-abbrev-table ())
+(define-abbrev-table 'lisp-mode-abbrev-table ()
+  "Abbrev table for Lisp mode.")
 
 (defvar lisp-mode-syntax-table
-  (let ((table (copy-syntax-table emacs-lisp-mode-syntax-table)))
+  (let ((table (make-syntax-table lisp--mode-syntax-table)))
     (modify-syntax-entry ?\[ "_   " table)
     (modify-syntax-entry ?\] "_   " table)
     (modify-syntax-entry ?# "' 14" table)
@@ -1308,10 +1310,9 @@ each calls the following function to set various variables:
 
 @smallexample
 @group
-(defun lisp-mode-variables (&optional syntax keywords-case-insensitive)
+(defun lisp-mode-variables (&optional syntax keywords-case-insensitive elisp)
   (when syntax
     (set-syntax-table lisp-mode-syntax-table))
-  (setq local-abbrev-table lisp-mode-abbrev-table)
   @dots{}
 @end group
 @end smallexample
@@ -1322,8 +1323,7 @@ variable to handle Lisp comments:
 
 @smallexample
 @group
-  (make-local-variable 'comment-start)
-  (setq comment-start ";")
+  (setq-local comment-start ";")
   @dots{}
 @end group
 @end smallexample
@@ -1337,6 +1337,7 @@ common.  The following code sets up the common commands:
 @group
 (defvar lisp-mode-shared-map
   (let ((map (make-sparse-keymap)))
+    (set-keymap-parent map prog-mode-map)
     (define-key map "\e\C-q" 'indent-sexp)
     (define-key map "\177" 'backward-delete-char-untabify)
     map)
@@ -1351,7 +1352,7 @@ And here is the code to set up the keymap for Lisp mode:
 @group
 (defvar lisp-mode-map
   (let ((map (make-sparse-keymap))
-        (menu-map (make-sparse-keymap "Lisp")))
+        (menu-map (make-sparse-keymap "Lisp")))
     (set-keymap-parent map lisp-mode-shared-map)
     (define-key map "\e\C-x" 'lisp-eval-defun)
     (define-key map "\C-c\C-z" 'run-lisp)
@@ -1375,17 +1376,13 @@ Blank lines separate paragraphs.  Semicolons start comments.
 
 \\@{lisp-mode-map@}
 Note that `run-lisp' may be used either to start an inferior Lisp job
-or to switch back to an existing one.
+or to switch back to an existing one."
 @end group
-
 @group
-Entry to this mode calls the value of `lisp-mode-hook'
-if that value is non-nil."
   (lisp-mode-variables nil t)
-  (set (make-local-variable 'find-tag-default-function)
-       'lisp-find-tag-default)
-  (set (make-local-variable 'comment-start-skip)
-       "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *")
+  (setq-local find-tag-default-function 'lisp-find-tag-default)
+  (setq-local comment-start-skip
+              "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *")
   (setq imenu-case-fold-search t))
 @end group
 @end smallexample
diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi
index ae9a8ab6323..11a77bd1479 100644
--- a/doc/lispref/nonascii.texi
+++ b/doc/lispref/nonascii.texi
@@ -1632,11 +1632,16 @@ coding system for a file based on its undecoded contents.
 
 Each function in this list should be written to look at text in the
 current buffer, but should not modify it in any way.  The buffer will
-contain undecoded text of parts of the file.  Each function should
-take one argument, @var{size}, which tells it how many characters to
-look at, starting from point.  If the function succeeds in determining
-a coding system for the file, it should return that coding system.
-Otherwise, it should return @code{nil}.
+contain the text of parts of the file.  Each function should take one
+argument, @var{size}, which tells it how many characters to look at,
+starting from point.  If the function succeeds in determining a coding
+system for the file, it should return that coding system.  Otherwise,
+it should return @code{nil}.
+
+The functions in this list could be called either when the file is
+visited and Emacs wants to decode its contents, and/or when the file's
+buffer is about to be saved and Emacs wants to determine how to encode
+its contents.
 
 If a file has a @samp{coding:} tag, that takes precedence, so these
 functions won't be called.