3 files changed, 44 insertions, 1 deletions

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index f5c73e55a4f..2ed848adf37 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2423,7 +2423,9 @@ the values of the @code{:family}, @code{:foundry}, @code{:width},
 The name of a face from which to inherit attributes, or a list of face
 names.  Attributes from inherited faces are merged into the face like
 an underlying face would be, with higher priority than underlying
-faces (@pxref{Displaying Faces}).  If a list of faces is used,
+faces (@pxref{Displaying Faces}).  If the face to inherit from is
+@code{unspecified}, it is treated the same as @code{nil}, since Emacs
+never merges @code{:inherit} attributes.  If a list of faces is used,
 attributes from faces earlier in the list override those from later
 faces.
 @end table
diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index d925c8c8f65..80dcb488983 100644
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -468,6 +468,10 @@ 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}).
 
+@menu
+* When to Autoload::   When to Use Autoload.
+@end menu
+
   There are two ways to set up an autoloaded function: by calling
 @code{autoload}, and by writing a ``magic'' comment in the
 source before the real definition.  @code{autoload} is the low-level
@@ -699,6 +703,42 @@ symbol's new function value.  If the value of the optional argument
 function, only a macro.
 @end defun
 
+@node When to Autoload
+@subsection When to Use Autoload
+@cindex autoload, when to use
+
+Do not add an autoload comment unless it is really necessary.
+Autoloading code means it is always globally visible.  Once an item is
+autoloaded, there is no compatible way to transition back to it not
+being autoloaded (after people become accustomed to being able to use it
+without an explicit load).
+
+@itemize
+@item
+The most common items to autoload are the interactive entry points to a
+library.  For example, if @file{python.el} is a library defining a
+major-mode for editing Python code, autoload the definition of the
+@code{python-mode} function, so that people can simply use @kbd{M-x
+python-mode} to load the library.
+
+@item
+Variables usually don't need to be autoloaded.  An exception is if the
+variable on its own is generally useful without the whole defining
+library being loaded.  (An example of this might be something like
+@code{find-exec-terminator}.)
+
+@item
+Don't autoload a user option just so that a user can set it.
+
+@item
+Never add an autoload @emph{comment} to silence a compiler warning in
+another file.  In the file that produces the warning, use
+@code{(defvar foo)} to silence an undefined variable warning, and
+@code{declare-function} (@pxref{Declaring Functions}) to silence an
+undefined function warning; or require the relevant library; or use an
+explicit autoload @emph{statement}.
+@end itemize
+
 @node Repeated Loading
 @section Repeated Loading
 @cindex repeated loading
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 7108520e79f..b825b1d790b 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -4236,6 +4236,7 @@ A marker represents a buffer position to jump to.
 A string is text saved in the register.
 
 @item a rectangle
+@cindex rectangle, as contents of a register
 A rectangle is represented by a list of strings.
 
 @item @code{(@var{window-configuration} @var{position})}