; Merge from branch 'master'scratch/raeburn-startup

12 files changed, 93 insertions, 7 deletions

diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index a756a89e3f8..1c9c14a962a 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -1701,6 +1701,7 @@ and mouse events:
 (global-set-key (kbd "C-c y") 'clipboard-yank)
 (global-set-key (kbd "C-M-q") 'query-replace)
 (global-set-key (kbd "<f5>") 'flyspell-mode)
+(global-set-key (kbd "C-<f5>") 'display-line-numbers-mode)
 (global-set-key (kbd "C-<right>") 'forward-sentence)
 (global-set-key (kbd "<mouse-2>") 'mouse-save-then-kill)
 @end example
diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi
index ddd7229b0c8..150ac8427ab 100644
--- a/doc/emacs/dired.texi
+++ b/doc/emacs/dired.texi
@@ -64,10 +64,22 @@ you to operate on the listed files.  @xref{Directories}.
 directory name using the minibuffer, and opens a @dfn{Dired buffer}
 listing the files in that directory.  You can also supply a wildcard
 file name pattern as the minibuffer argument, in which case the Dired
-buffer lists all files matching that pattern.  The usual history and
-completion commands can be used in the minibuffer; in particular,
-@kbd{M-n} puts the name of the visited file (if any) in the minibuffer
-(@pxref{Minibuffer History}).
+buffer lists all files matching that pattern.  A wildcard may appear
+in the directory part as well.
+For instance,
+
+@example
+C-x d  ~/foo/*.el  @key{RET}
+C-x d  ~/foo/*/*.el  @key{RET}
+@end example
+
+The former lists all the files with extension @samp{.el} in directory
+@samp{foo}.  The latter lists the files with extension @samp{.el}
+in subdirectories 2 levels of depth below @samp{foo}.
+
+The usual history and completion commands can be used in the minibuffer;
+in particular, @kbd{M-n} puts the name of the visited file (if any) in
+the minibuffer (@pxref{Minibuffer History}).
 
   You can also invoke Dired by giving @kbd{C-x C-f} (@code{find-file})
 a directory name.
diff --git a/doc/emacs/fixit.texi b/doc/emacs/fixit.texi
index 2ba3e26c484..f833f572dfc 100644
--- a/doc/emacs/fixit.texi
+++ b/doc/emacs/fixit.texi
@@ -254,6 +254,7 @@ Restart the Aspell/Ispell/Hunspell process, using @var{dict} as the dictionary.
 Kill the Aspell/Ispell/Hunspell subprocess.
 @item M-@key{TAB}
 @itemx @key{ESC} @key{TAB}
+@itemx C-M-i
 Complete the word before point based on the spelling dictionary
 (@code{ispell-complete-word}).
 @item M-x flyspell-mode
diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index e3e59ad43ac..ee33a6848c5 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -575,7 +575,8 @@ font names in X resource files.
 If you are running Emacs on the GNOME desktop, you can tell Emacs to
 use the default system font by setting the variable
 @code{font-use-system-font} to @code{t} (the default is @code{nil}).
-For this to work, Emacs must have been compiled with Gconf support.
+For this to work, Emacs must have been compiled with support for
+Gsettings (or the older Gconf).
 
 @item
 Use the command line option @samp{-fn} (or @samp{--font}).  @xref{Font
diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index fd6df1c7e53..460ced0d21c 100644
--- a/doc/emacs/help.texi
+++ b/doc/emacs/help.texi
@@ -320,12 +320,21 @@ search for non-customizable variables too.
 Search for variables.  With a prefix argument, search for
 customizable variables only.
 
+@item M-x apropos-local-variable
+@findex apropos-local-variable
+Search for buffer-local variables.
+
 @item M-x apropos-value
 @findex apropos-value
 Search for variables whose values match the specified pattern.  With a
 prefix argument, search also for functions with definitions matching
 the pattern, and Lisp symbols with properties matching the pattern.
 
+@item M-x apropos-local-value
+@findex apropos-local-value
+Search for buffer-local variables whose values match the specified
+pattern.
+
 @item C-h d
 @kindex C-h d
 @findex apropos-documentation
diff --git a/doc/emacs/modes.texi b/doc/emacs/modes.texi
index eb0c88b2901..876431aa9e9 100644
--- a/doc/emacs/modes.texi
+++ b/doc/emacs/modes.texi
@@ -225,6 +225,13 @@ Font-Lock mode automatically highlights certain textual units found in
 programs.  It is enabled globally by default, but you can disable it
 in individual buffers.  @xref{Faces}.
 
+@findex display-line-numbers-mode
+@cindex display-line-numbers-mode
+@item
+Display Line Numbers mode is a convenience wrapper around
+@code{display-line-numbers}, setting it using the value of
+@code{display-line-numbers-type}.  @xref{Display Custom}.
+
 @item
 Outline minor mode provides similar facilities to the major mode
 called Outline mode.  @xref{Outline Mode}.
diff --git a/doc/emacs/regs.texi b/doc/emacs/regs.texi
index 7369f6b05b6..40e3e2c1c31 100644
--- a/doc/emacs/regs.texi
+++ b/doc/emacs/regs.texi
@@ -15,7 +15,10 @@ jump back to that position once, or many times.
   Each register has a name that consists of a single character, which
 we will denote by @var{r}; @var{r} can be a letter (such as @samp{a})
 or a number (such as @samp{1}); case matters, so register @samp{a} is
-not the same as register @samp{A}.
+not the same as register @samp{A}.  You can also set a register in
+non-alphanumeric characters, for instance @samp{*} or @samp{C-d}.
+Note, it's not possible to set a register in @samp{C-g} or @samp{ESC},
+because these keys are reserved to terminate interactive commands.
 
 @findex view-register
   A register can store a position, a piece of text, a rectangle, a
diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi
index c9e83da173f..9f7e9a12cd7 100644
--- a/doc/emacs/search.texi
+++ b/doc/emacs/search.texi
@@ -1747,6 +1747,10 @@ 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.
 
+Note that matches for the regexp you type are extended to include
+complete lines, and a match that starts before the previous match ends
+is not considered a match.
+
 @kindex RET @r{(Occur mode)}
 @kindex o @r{(Occur mode)}
 @kindex C-o @r{(Occur mode)}
diff --git a/doc/emacs/xresources.texi b/doc/emacs/xresources.texi
index 7e27ddd1d9a..eaefcee21c3 100644
--- a/doc/emacs/xresources.texi
+++ b/doc/emacs/xresources.texi
@@ -250,6 +250,11 @@ specified if @samp{off}.
 Gamma correction for colors, equivalent to the frame parameter
 @code{screen-gamma}.
 
+@item @code{scrollBar} (class @code{ScrollBar})
+@cindex tool bar
+If the value of this resource is @samp{off} or @samp{false} or
+@samp{0}, Emacs disables Scroll Bar mode at startup (@pxref{Scroll Bars}).
+
 @item @code{scrollBarWidth} (class @code{ScrollBarWidth})
 @cindex scrollbar width
 The scroll bar width in pixels, equivalent to the frame parameter
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})}