Merge from origin/emacs-26

22922c7 (origin/emacs-26) * doc/emacs/entering.texi (Entering Emacs):...
59657c4 Document 'window-at-side-p' in the Elisp manual
2b35ed0 Document external-debugging-output in the Elisp Manual (Bug#2...
db6564c Fix scroll-margin docstring (Bug#13791)
732d1b9 Clarify that `ansi-term' is almost the same as `term' (Bug#18...
f706c59 Update manual description of locate-file (Bug#23650)
1602262 Clarify effect of print-gensym (Bug#27776)
53e9fa2 * lisp/custom.el (defcustom): Fix docstring (Bug#27891).
607cc4e Define cl-type-definition button type as needed (Bug#28899)
9e6889c Emphasize that GPG passphrase caching is temporary (Bug#29907)
4b5711b Fix @examples in cc-mode.info, where lines were getting glued...
71961f1 Minor change in "Mode Line" section of Emacs manual
55a2b76 More fixes in the Emacs manual

17 files changed, 109 insertions, 52 deletions

diff --git a/doc/emacs/ack.texi b/doc/emacs/ack.texi
index ee8649a0451..20c8d4e610b 100644
--- a/doc/emacs/ack.texi
+++ b/doc/emacs/ack.texi
@@ -209,8 +209,8 @@ for Korean Hanja.
 
 @item
 Andrew Choi and Yamamoto Mitsuharu wrote the Carbon support, used
-prior to Emacs 23 for Mac OS@.  Yamamoto Mitsuharu continued to
-contribute to Mac OS support in the newer Nextstep port; and also
+prior to Emacs 23 for macOS@.  Yamamoto Mitsuharu continued to
+contribute to macOS support in the newer Nextstep port; and also
 improved support for multi-monitor displays.
 
 @item
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index 5904740b1f6..0051868fee6 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -221,7 +221,7 @@ Appendices
 * Emacs Invocation::    Hairy startup options.
 * X Resources::         X resources for customizing Emacs.
 * Antinews::            Information about Emacs version 25.
-* Mac OS / GNUstep::    Using Emacs under Mac OS and GNUstep.
+* Mac OS / GNUstep::     Using Emacs under macOS and GNUstep.
 * Microsoft Windows::   Using Emacs on Microsoft Windows and MS-DOS.
 * Manifesto::           What's GNU?  Gnu's Not Unix!
 
@@ -1226,10 +1226,10 @@ GTK resources
 * GTK Names in Emacs::    GTK widgets used by Emacs.
 * GTK styles::            What can be customized in a GTK widget.
 
-Emacs and Mac OS / GNUstep
+Emacs and macOS / GNUstep
 
-* Mac / GNUstep Basics::        Basic Emacs usage under GNUstep or Mac OS.
-* Mac / GNUstep Customization:: Customizations under GNUstep or Mac OS.
+* Mac / GNUstep Basics::        Basic Emacs usage under GNUstep or macOS.
+* Mac / GNUstep Customization:: Customizations under GNUstep or macOS.
 * Mac / GNUstep Events::        How window system events are handled.
 * GNUstep Support::             Details on status of GNUstep support.
 
diff --git a/doc/emacs/entering.texi b/doc/emacs/entering.texi
index 2ff258ffb0c..642c6ec1ab9 100644
--- a/doc/emacs/entering.texi
+++ b/doc/emacs/entering.texi
@@ -18,11 +18,11 @@
 @cindex starting Emacs
 
   The usual way to invoke Emacs is with the shell command
-@command{emacs}.  From a terminal window running a Unix shell in the X
-Window System, you can run Emacs in the background with @command{emacs
-&}; this way, Emacs won't tie up the terminal window, so you can use
-it to run other shell commands.  (For comparable methods of starting
-Emacs on MS-Windows, see @ref{Windows Startup}.)
+@command{emacs}.  From a terminal window running a Unix shell, you can
+run Emacs in the background with @command{emacs &}; this way, Emacs
+won't tie up the terminal window, so you can use it to run other shell
+commands.  (For comparable methods of starting Emacs on MS-Windows,
+see @ref{Windows Startup}.)
 
 @cindex startup screen
   When Emacs starts up, the initial frame displays a special buffer
diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index 7a7e1fd5636..7c1d36c720b 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -975,7 +975,7 @@ variable @code{scroll-bar-mode}.  Its value should be either
 @code{right} (put scroll bars on the right side of windows), @code{left}
 (put them on the left), or @code{nil} (disable vertical scroll bars).
 By default, Emacs puts scroll bars on the right if it was compiled with
-GTK+ support on the X Window System, and on MS-Windows or Mac OS; Emacs
+GTK+ support on the X Window System, and on MS-Windows or macOS; Emacs
 puts scroll bars on the left if compiled on the X Window System without
 GTK+ support (following the old convention for X applications).
 
diff --git a/doc/emacs/macos.texi b/doc/emacs/macos.texi
index 9af6f93b0c8..cf4e48bacb8 100644
--- a/doc/emacs/macos.texi
+++ b/doc/emacs/macos.texi
@@ -2,7 +2,7 @@
 @c Copyright (C) 2000-2018 Free Software Foundation, Inc.
 @c See file emacs.texi for copying conditions.
 @node Mac OS / GNUstep
-@appendix Emacs and Mac OS / GNUstep
+@appendix Emacs and macOS / GNUstep
 @cindex macOS
 @cindex Macintosh
 @cindex GNUstep
@@ -12,7 +12,7 @@ the GNUstep libraries on GNU/Linux or other operating systems, or on
 macOS with native window system support.  On macOS, Emacs can be
 built either without window system support, with X11, or with the
 Cocoa interface; this section only applies to the Cocoa build.  This
-does not support versions before Mac OS X 10.6.
+does not support versions before macOS 10.6.
 
   For various historical and technical reasons, Emacs uses the term
 @samp{Nextstep} internally, instead of ``Cocoa'' or ``macOS''; for
@@ -25,14 +25,14 @@ this writing, Emacs GNUstep support is alpha status (@pxref{GNUstep
 Support}), but we hope to improve it in the future.
 
 @menu
-* Mac / GNUstep Basics::        Basic Emacs usage under GNUstep or Mac OS.
-* Mac / GNUstep Customization:: Customizations under GNUstep or Mac OS.
+* Mac / GNUstep Basics::        Basic Emacs usage under GNUstep or macOS.
+* Mac / GNUstep Customization:: Customizations under GNUstep or macOS.
 * Mac / GNUstep Events::        How window system events are handled.
 * GNUstep Support::             Details on status of GNUstep support.
 @end menu
 
 @node Mac / GNUstep Basics
-@section Basic Emacs usage under Mac OS and GNUstep
+@section Basic Emacs usage under macOS and GNUstep
 
   By default, the @key{alt} and @key{option} keys are the same as
 @key{Meta}.  The Mac @key{Cmd} key is the same as @key{Super}, and
@@ -128,7 +128,7 @@ at the command-line before starting Emacs:
 
 
 @node Mac / GNUstep Events
-@section Windowing System Events under Mac OS / GNUstep
+@section Windowing System Events under macOS / GNUstep
 
   Nextstep applications receive a number of special events which have
 no X equivalent.  These are sent as specially defined key events, which
diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index aeb8560ea00..3300ed67c6e 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -1729,7 +1729,7 @@ different virtual terminals, and switch to the Emacs server's virtual
 terminal after calling @command{emacsclient}; or (ii) call
 @command{emacsclient} from within the Emacs server itself, using Shell
 mode (@pxref{Interactive Shell}) or Term mode (@pxref{Term Mode});
-@code{emacsclient} blocks only the subshell under Emacs, and you can
+@command{emacsclient} blocks only the subshell under Emacs, and you can
 still use Emacs to edit the file.
 
 @kindex C-x #
@@ -1794,13 +1794,13 @@ listed below:
 @table @samp
 @item -a @var{command}
 @itemx --alternate-editor=@var{command}
-Specify a shell command to run if @code{emacsclient} fails to contact Emacs.
-This is useful when running @code{emacsclient} in a script.
-The command may include arguments, which may be quoted "like this".
-Currently, escaping of quotes is not supported.
+Specify a shell command to run if @command{emacsclient} fails to
+contact Emacs.  This is useful when running @code{emacsclient} in a
+script.  The command may include arguments, which may be quoted "like
+this".  Currently, escaping of quotes is not supported.
 
 As a special exception, if @var{command} is the empty string, then
-@code{emacsclient} starts Emacs in daemon mode (as @command{emacs
+@command{emacsclient} starts Emacs in daemon mode (as @samp{emacs
 --daemon}) and then tries connecting again.
 
 @cindex @env{ALTERNATE_EDITOR} environment variable
diff --git a/doc/emacs/screen.texi b/doc/emacs/screen.texi
index fb4eff9711a..8dd5e5f9e56 100644
--- a/doc/emacs/screen.texi
+++ b/doc/emacs/screen.texi
@@ -228,8 +228,8 @@ modified, it shows two stars (@samp{**}).  For a read-only buffer, it
 shows @samp{%*} if the buffer is modified, and @samp{%%} otherwise.
 
   The character after @var{ch} is normally a dash (@samp{-}).
-However, if the default-directory for the current buffer is on a
-remote machine (@pxref{File Names}), @samp{@@} is displayed instead.
+However, if @code{default-directory} (@pxref{File Names}) for the
+current buffer is on a remote machine, @samp{@@} is displayed instead.
 
   @var{fr} gives the selected frame name (@pxref{Frames}).  It appears
 only on text terminals.  The initial frame's name is @samp{F1}.
@@ -279,7 +279,10 @@ the mode line of every window.  @xref{Recursive Edit}.
   You can change the appearance of the mode line as well as the format
 of its contents.  @xref{Optional Mode Line}.  In addition, the mode
 line is mouse-sensitive; clicking on different parts of the mode line
-performs various commands.  @xref{Mode Line Mouse}.
+performs various commands.  @xref{Mode Line Mouse}.  Also, hovering
+the mouse pointer above mouse-sensitive portions of the mode line
+shows tooltips (@pxref{Tooltips}) with information about commands you
+can invoke by clicking on the mode line.
 
 @node Menu Bar
 @section The Menu Bar
@@ -296,10 +299,10 @@ at the end of a menu item means that the command will prompt you for
 further input before it actually does anything.
 
   Some of the commands in the menu bar have ordinary key bindings as
-well; if so, a key binding is shown in parentheses after the item
-itself.  To view the full command name and documentation for a menu
-item, type @kbd{C-h k}, and then select the menu bar with the mouse in
-the usual way (@pxref{Key Help}).
+well; if so, a key binding is shown after the item itself.  To view
+the full command name and documentation for a menu item, type
+@kbd{C-h k}, and then select the menu bar with the mouse in the usual
+way (@pxref{Key Help}).
 
 @kindex F10
 @findex menu-bar-open
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 6a0312bd2f3..70d6ec9cdb3 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -1541,6 +1541,16 @@ argument.  If @var{predicate} is @code{nil} or omitted,
 @xref{Kinds of Files}, for other useful predicates, e.g.,
 @code{file-executable-p} and @code{file-directory-p}.
 
+This function will normally skip directories, so if you want it to
+find directories, make sure the @var{predicate} function returns
+@code{dir-ok} for them.  For example:
+
+@example
+(locate-file "html" '("/var/www" "/srv") nil
+             (lambda (f) (if (file-directory-p f) 'dir-ok)))
+@end example
+
+
 For compatibility, @var{predicate} can also be one of the symbols
 @code{executable}, @code{readable}, @code{writable}, @code{exists}, or
 a list of one or more of these symbols.
diff --git a/doc/lispref/streams.texi b/doc/lispref/streams.texi
index bd7dc2d9af3..6172392274a 100644
--- a/doc/lispref/streams.texi
+++ b/doc/lispref/streams.texi
@@ -503,7 +503,7 @@ in reverse order.
 @end group
 
 @group
-(print "This is the output" 'eat-output)
+(print "This is the output" #'eat-output)
      @result{} "This is the output"
 @end group
 
@@ -530,6 +530,22 @@ Now we can put the output in the proper order by reversing the list:
 Calling @code{concat} converts the list to a string so you can see its
 contents more clearly.
 
+@cindex @code{stderr} stream, use for debugging
+@anchor{external-debugging-output}
+@defun external-debugging-output character
+This function can be useful as an output stream when debugging.  It
+writes @var{character} to the standard error stream.
+
+For example
+@example
+@group
+(print "This is the output" #'external-debugging-output)
+@print{} This is the output
+@result{} "This is the output"
+@end group
+@end example
+@end defun
+
 @node Output Functions
 @section Output Functions
 
@@ -570,8 +586,9 @@ operation:
 @end example
 
   In the functions below, @var{stream} stands for an output stream.
-(See the previous section for a description of output streams.)  If
-@var{stream} is @code{nil} or omitted, it defaults to the value of
+(See the previous section for a description of output streams.  Also
+@xref{external-debugging-output}, a useful stream value for debugging.)
+If @var{stream} is @code{nil} or omitted, it defaults to the value of
 @code{standard-output}.
 
 @defun print object &optional stream
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 3691a2c04f4..5ab6d6ee6a4 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -338,8 +338,8 @@ The functions @code{window-next-sibling} and
 and previous window, respectively, in the cyclic ordering of windows
 (@pxref{Cyclic Window Ordering}).
 
-  You can use the following functions to find the first live window on a
-frame and the window nearest to a given window.
+  The following functions can be useful to locate a window within its
+frame.
 
 @defun frame-first-window &optional frame-or-window
 This function returns the live window at the upper left corner of the
@@ -351,6 +351,20 @@ the assumption that the frame from our canonical example is selected
 @code{(frame-first-window)} returns @var{W2}.
 @end defun
 
+@defun window-at-side-p &optional window side
+This function returns @code{t} if @var{window} is located at
+@var{side} of its containing frame.  The argument @var{window} must be
+a valid window and defaults to the selected one.  The argument
+@var{side} can be any of the symbols @code{left}, @code{top},
+@code{right} or @code{bottom}.  The default value @code{nil} is
+handled like @code{bottom}.
+
+Note that this function disregards the minibuffer window
+(@pxref{Minibuffer Windows}).  Hence, with @var{side} equal to
+@code{bottom} it may return @code{t} also when the minibuffer window
+appears right below @var{window}.
+@end defun
+
 @cindex window in direction
 @defun window-in-direction direction &optional window ignore sign wrap mini
 This function returns the nearest live window in direction
@@ -385,7 +399,12 @@ the minibuffer window if and only if it is currently active.  If
 window even when it's not active.  However, if @var{wrap} is
 non-@code{nil}, it always acts as if @var{mini} were @code{nil}.
 
-If it doesn't find a suitable window, this function returns @code{nil}.
+If it doesn't find a suitable window, this function returns
+@code{nil}.
+
+Don't use this function to check whether there is @emph{no} window in
+@var{direction}.  Calling @code{window-at-side-p} described above is a
+much more efficient way to do that.
 @end defun
 
 The following function allows the entire window tree of a frame to be
diff --git a/doc/misc/cc-mode.texi b/doc/misc/cc-mode.texi
index 292342cb4a3..0132ab1775c 100644
--- a/doc/misc/cc-mode.texi
+++ b/doc/misc/cc-mode.texi
@@ -5634,15 +5634,15 @@ Works with:
 @end ifinfo
 
 @macro sssTBasicOffset
-<--> @i{c-basic-offset}@c
+<--> @i{c-basic-offset}
 @end macro
 
 @macro sssTsssTBasicOffset
-<--><--> @i{c-basic-offset}@c
+<--><--> @i{c-basic-offset}
 @end macro
 
 @macro hereFn{func}
-<- @i{\func\}@c
+<- @i{\func\}
 @end macro
 
 @c The TeX backend seems to insert extra spaces around the argument. :P
diff --git a/doc/misc/epa.texi b/doc/misc/epa.texi
index 80ea43e8032..8c21a262a1e 100644
--- a/doc/misc/epa.texi
+++ b/doc/misc/epa.texi
@@ -455,7 +455,7 @@ GnuPG 2.1 uses a fixed address for the Unix domain socket used to
 communicate with gpg-agent.  The @code{GPG_AGENT_INFO} environment
 variable, which is used by GnuPG 2.0 and 1.4, is ignored.  That means,
 if your system has both GnuPG 2.1 and 1.4, the gpg command from GnuPG
-1.4 is not able to use gpg-agent provided by 2.1 (at least out of box).q
+1.4 is not able to use gpg-agent provided by 2.1 (at least out of box).
 
 @item
 GnuPG 2.1 (2.1.5 or later) has a mechanism to direct the Pinentry
@@ -474,7 +474,9 @@ graphical prompt.
 
 Typing passphrases is a troublesome task if you frequently open and
 close the same file.  GnuPG and EasyPG Assistant provide mechanisms to
-remember your passphrases.  However, the configuration is a bit
+remember your passphrases for a limited time.  Using these, you only
+need to re-enter the passphrase occasionally.
+However, the configuration is a bit
 confusing since it depends on your GnuPG installation@xref{GnuPG
 version compatibility}, encryption method (symmetric or public key),
 and whether or not you want to use gpg-agent.  Here are some
diff --git a/lisp/custom.el b/lisp/custom.el
index edbbc8c1449..b7539685a89 100644
--- a/lisp/custom.el
+++ b/lisp/custom.el
@@ -306,7 +306,8 @@ The following common keywords are also meaningful.
         VALUE should be a list with the form (PACKAGE . VERSION)
         specifying that the variable was first introduced, or its
         default value was changed, in PACKAGE version VERSION.  This
-        keyword takes priority over :version.  The PACKAGE and VERSION
+        keyword takes priority over :version.  For packages which
+        are bundled with Emacs releases, the PACKAGE and VERSION
         must appear in the alist `customize-package-emacs-version-alist'.
         Since PACKAGE must be unique and the user might see it in an
         error message, a good choice is the official name of the
diff --git a/lisp/emacs-lisp/eieio-opt.el b/lisp/emacs-lisp/eieio-opt.el
index dbec48d038b..eeb0bc95d68 100644
--- a/lisp/emacs-lisp/eieio-opt.el
+++ b/lisp/emacs-lisp/eieio-opt.el
@@ -142,7 +142,10 @@ are not abstract."
               (find-lisp-object-file-name ctr def)))
       (when location
         (insert (substitute-command-keys " in `"))
-        (help-insert-xref-button
+        ;; The `cl-type-definition' button type can't be autoloaded
+        ;; due to circularity during bootstrap (Bug#28899).
+        (require 'cl-extra)
+        (help-insert-xref-button
          (help-fns-short-filename location)
          'cl-type-definition ctr location 'define-type)
         (insert (substitute-command-keys "'")))
diff --git a/lisp/term.el b/lisp/term.el
index 20719987a06..a0313d88dac 100644
--- a/lisp/term.el
+++ b/lisp/term.el
@@ -4139,7 +4139,9 @@ the process.  Any more args are arguments to PROGRAM."
 
 ;;;###autoload
 (defun ansi-term (program &optional new-buffer-name)
-  "Start a terminal-emulator in a new buffer."
+  "Start a terminal-emulator in a new buffer.
+This is almost the same as `term' apart from always creating a new buffer,
+and `C-x' being marked as a `term-escape-char'. "
   (interactive (list (read-from-minibuffer "Run program: "
                                            (or explicit-shell-file-name
                                                (getenv "ESHELL")
diff --git a/src/print.c b/src/print.c
index 71579673248..b3c0f6f38fc 100644
--- a/src/print.c
+++ b/src/print.c
@@ -748,7 +748,7 @@ is used instead.  */)
 
 DEFUN ("external-debugging-output", Fexternal_debugging_output, Sexternal_debugging_output, 1, 1, 0,
        doc: /* Write CHARACTER to stderr.
-You can call print while debugging emacs, and pass it this function
+You can call `print' while debugging emacs, and pass it this function
 to make it write to the debugging output.  */)
   (Lisp_Object character)
 {
@@ -2372,10 +2372,10 @@ I.e., (quote foo) prints as \\='foo, (function foo) as #\\='foo.  */);
   DEFVAR_LISP ("print-gensym", Vprint_gensym,
                doc: /* Non-nil means print uninterned symbols so they will read as uninterned.
 I.e., the value of (make-symbol \"foobar\") prints as #:foobar.
-When the uninterned symbol appears within a recursive data structure,
-and the symbol appears more than once, in addition use the #N# and #N=
-constructs as needed, so that multiple references to the same symbol are
-shared once again when the text is read back.  */);
+When the uninterned symbol appears multiple times within the printed
+expression, and `print-circle' is non-nil, in addition use the #N#
+and #N= constructs as needed, so that multiple references to the same
+symbol are shared once again when the text is read back.  */);
   Vprint_gensym = Qnil;
 
   DEFVAR_LISP ("print-circle", Vprint_circle,
diff --git a/src/xdisp.c b/src/xdisp.c
index fd8aad04121..17a3cc3b89a 100644
--- a/src/xdisp.c
+++ b/src/xdisp.c
@@ -32526,8 +32526,8 @@ A value of zero means always recenter point if it moves off screen.  */);
 
   DEFVAR_INT ("scroll-margin", scroll_margin,
     doc: /* Number of lines of margin at the top and bottom of a window.
-Recenter the window whenever point gets within this many lines
-of the top or bottom of the window.  */);
+Trigger automatic scrolling whenever point gets within this many lines
+of the top or bottom of the window (see info node `Auto Scrolling').  */);
   scroll_margin = 0;
 
   DEFVAR_LISP ("maximum-scroll-margin", Vmaximum_scroll_margin,