11 files changed, 142 insertions, 40 deletions

diff --git a/doc/emacs/buffers.texi b/doc/emacs/buffers.texi
index 8a8584689fc..94e9d2760ec 100644
--- a/doc/emacs/buffers.texi
+++ b/doc/emacs/buffers.texi
@@ -629,7 +629,6 @@ buffer, but killing an indirect buffer has no effect on its base buffer.
   One way to use indirect buffers is to display multiple views of an
 outline.  @xref{Outline Views}.
 
-@vindex clone-indirect-buffer-hook
   A quick and handy way to make an indirect buffer is with the command
 @kbd{M-x clone-indirect-buffer}.  It creates and selects an indirect
 buffer whose base buffer is the current buffer.  With a numeric
@@ -637,14 +636,19 @@ argument, it prompts for the name of the indirect buffer; otherwise it
 uses the name of the current buffer, with a @samp{<@var{n}>} suffix
 added.  @kbd{C-x 4 c} (@code{clone-indirect-buffer-other-window})
 works like @kbd{M-x clone-indirect-buffer}, but it selects the new
-buffer in another window.  These functions run the hook
-@code{clone-indirect-buffer-hook} after creating the indirect buffer.
+buffer in another window.
 
   The more general way to make an indirect buffer is with the command
 @kbd{M-x make-indirect-buffer}.  It creates an indirect buffer
 named @var{indirect-name} from a buffer @var{base-buffer}, prompting for
 both using the minibuffer.
 
+@vindex clone-indirect-buffer-hook
+  The functions that create indirect buffers run the hook
+@code{clone-indirect-buffer-hook} after creating the indirect buffer.
+When this hook runs, the newly created indirect buffer is the current
+buffer.
+
 @node Buffer Convenience
 @section Convenience Features and Customization of Buffer Handling
 
diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index c641b8ccb14..29edbe98633 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -1633,13 +1633,14 @@ Parameters,,, elisp, The Emacs Lisp Reference Manual}, and also
 For additional customization options for displaying tooltips, use
 @kbd{M-x customize-group @key{RET} tooltip @key{RET}}.
 
-@vindex x-gtk-use-system-tooltips
-  If Emacs is built with GTK+ support, it displays tooltips via GTK+,
-using the default appearance of GTK+ tooltips.  To disable this,
-change the variable @code{x-gtk-use-system-tooltips} to @code{nil}.
-If you do this, or if Emacs is built without GTK+ support, most
-attributes of the tooltip text are specified by the @code{tooltip}
-face, and by X resources (@pxref{X Resources}).
+@vindex use-system-tooltips
+  If Emacs is built with the GTK+ toolkit or Haiku windowing support,
+it displays tooltips via the toolkit, using the default appearance of
+the toolkit's tooltips.  To disable this, change the variable
+@code{use-system-tooltips} to @code{nil}.  If you do this, or if Emacs
+is built without GTK+ or Haiku windowing support, most attributes of
+the tooltip text are specified by the @code{tooltip} face, and by X
+resources (@pxref{X Resources}).
 
   @dfn{GUD tooltips} are special tooltips that show the values of
 variables when debugging a program with GUD@.  @xref{Debugger
diff --git a/doc/emacs/haiku.texi b/doc/emacs/haiku.texi
index eeae379e06a..ac631a39a69 100644
--- a/doc/emacs/haiku.texi
+++ b/doc/emacs/haiku.texi
@@ -85,16 +85,12 @@ instead.
 
 @cindex tooltips (haiku)
 @cindex haiku tooltips
-@vindex haiku-use-system-tooltips
   On Haiku, Emacs defaults to using the system tooltip mechanism.
 This usually leads to more responsive tooltips, but the tooltips will
 not be able to display text properties or faces.  If you need those
-features, customize the variable @code{haiku-use-system-tooltips} to
-the nil value, and Emacs will use its own implementation of tooltips.
-
-  Both system tooltips and Emacs's own tooltips cannot display above
-the menu bar, so help text in the menu bar will display in the echo
-area instead.
+features, customize the variable @code{use-system-tooltips} to the
+@code{nil} value, and Emacs will use its own implementation of
+tooltips.
 
 @cindex X resources on Haiku
   Unlike the X window system, Haiku does not have a system-wide
diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi
index fa1b0eee7c3..a57cfac8daf 100644
--- a/doc/emacs/search.texi
+++ b/doc/emacs/search.texi
@@ -463,14 +463,15 @@ transient input method (@pxref{transient input method}) with
 @kbd{C-x \} (@code{isearch-transient-input-method}) to insert a single
 character to the search string using an input method, and
 automatically disable the input method afterwards.
-@end itemize
 
+@item
 @findex isearch-char-by-name
 @kindex C-x 8 RET @r{(Incremental Search)}
 Type @kbd{C-x 8 @key{RET}} (@code{isearch-char-by-name}), followed by
 a Unicode name or code-point in hex.  This adds the specified
 character into the search string, similar to the usual
 @code{insert-char} command (@pxref{Inserting Text}).
+@end itemize
 
 @findex isearch-emoji-by-name
 @kindex C-x 8 e RET @r{(Incremental Search)}
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 12e19efab0e..9020b98a1eb 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -8438,13 +8438,14 @@ displayed in the echo area.
 @end defun
 
 @cindex system tooltips
-@vindex x-gtk-use-system-tooltips
-When Emacs is built with GTK+ support, it by default displays tooltips
-using GTK+ functions, and the appearance of the tooltips is then
-controlled by GTK+ settings.  GTK+ tooltips can be disabled by
-changing the value of the variable @code{x-gtk-use-system-tooltips} to
-@code{nil}.  The rest of this subsection describes how to control
-non-GTK+ tooltips, which are presented by Emacs itself.
+@vindex use-system-tooltips
+When Emacs is built with the GTK+ toolkit or Haiku windowing support,
+it by default displays tooltips using toolkit functions, and the
+appearance of the tooltips is then controlled by by the toolkit's
+settings.  Toolkit-provided tooltips can be disabled by changing the
+value of the variable @code{use-system-tooltips} to @code{nil}.  The
+rest of this subsection describes how to control non-toolkit tooltips,
+which are presented by Emacs itself.
 
 @cindex tooltip frames
 Tooltips are displayed in special frames called tooltip frames, which
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 91926e05794..426bb6d0176 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -1231,6 +1231,7 @@ Text
 * Decompression::           Dealing with compressed data.
 * Base 64::                 Conversion to or from base 64 encoding.
 * Checksum/Hash::           Computing cryptographic hashes.
+* Suspicious Text::         Determining whether a string is suspicious.
 * GnuTLS Cryptography::     Cryptographic algorithms imported from GnuTLS.
 * Database::                Interacting with an SQL database.
 * Parsing HTML/XML::        Parsing HTML and XML.
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index ca7d9ada0ba..2eeb8b7ed74 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -3154,10 +3154,8 @@ raises @var{frame} above all other child frames of its parent.
 @deffn Command lower-frame &optional frame
 This function lowers frame @var{frame} (default, the selected frame)
 below all other frames belonging to the same or a higher z-group as
-@var{frame}.@footnote{Lowering frames is not supported on Haiku, due
-to limitations imposed by the system.}  If @var{frame} is a child
-frame (@pxref{Child Frames}), this lowers @var{frame} below all other
-child frames of its parent.
+@var{frame}.  If @var{frame} is a child frame (@pxref{Child Frames}),
+this lowers @var{frame} below all other child frames of its parent.
 @end deffn
 
 @defun frame-restack frame1 frame2 &optional above
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index b9df66dbdb4..37cf376bd53 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -59,6 +59,7 @@ the character after point.
 * Decompression::    Dealing with compressed data.
 * Base 64::          Conversion to or from base 64 encoding.
 * Checksum/Hash::    Computing cryptographic hashes.
+* Suspicious Text::  Determining whether a string is suspicious.
 * GnuTLS Cryptography:: Cryptographic algorithms imported from GnuTLS.
 * Database::         Interacting with an SQL database.
 * Parsing HTML/XML:: Parsing HTML and XML.
@@ -4943,6 +4944,92 @@ It should be somewhat more efficient on larger buffers than
 @c according to what we find useful.
 @end defun
 
+@node Suspicious Text
+@section Suspicious Text
+@cindex suspicious text
+@cindex insecure text
+@cindex security vulnerabilities in text
+
+  Emacs can display text from many external sources, like email and Web
+sites.  Attackers may attempt to confuse the user reading this text by
+using obfuscated @acronym{URL}s or email addresses, and tricking the
+user into visiting a web page they didn't intend to visit, or sending
+an email to the wrong address.
+
+This usually involves using characters from scripts that visually look
+like @acronym{ASCII} characters (i.e., are homoglyphs), but there are
+also other techniques used, like using bidirectional overrides, or
+having an @acronym{HTML} link text that says one thing, while the
+underlying @acronym{URL} points somewhere else.
+
+@cindex suspicious text strings
+To help identify these @dfn{suspicious text strings}, Emacs provides a
+library to do a number of checks on text.  (See
+@url{https://www.unicode.org/reports/tr39/, UTS #39: Unicode Security
+Mechanisms} for the rationale behind the checks that are available and
+more details about them.)  Packages that present data that might be
+suspicious should use this library to flag suspicious text on display.
+
+@vindex textsec-check
+@defun textsec-suspicious-p object type
+This function is the high-level interface function that packages
+should use.  It respects the @code{textsec-check} user option, which
+allows the user to disable the checks.
+
+This function checks @var{object} (whose data type depends on
+@var{type}) to see if it looks suspicious when interpreted as a thing
+of @var{type}.  The available types and the corresponding @var{object}
+data types are:
+
+@table @code
+@item domain
+Check whether a domain (e.g., @samp{www.gnu.org} looks suspicious.
+@var{object} should be a string, the domain name.
+
+@item url
+Check whether an @acronym{URL} (e.g., @samp{http://gnu.org/foo/bar})
+looks suspicious.  @var{object} should be a string, the @acronym{URL}
+to check.
+
+@item link
+Check whether an @acronym{HTML} link (e.g., @samp{<a
+href='http://gnu.org'>fsf.org</a>} looks suspicious.  In this case,
+@var{object} should be a @code{cons} cell where the @code{car} is the
+@acronym{URL} string, and the @code{cdr} is the link text.  The link
+is deemed suspicious if the link text contains a domain name, and that
+domain name points to something other than the @acronym{URL}.
+
+@item email-address
+Check whether an email address (e.g., @samp{foo@@example.org}) looks
+suspicious.  @var{object} should be a string.
+
+@item local-address
+Check whether the local part of an email address (the bit before the
+@samp{@@} sign) looks suspicious.  @var{object} should be a string.
+
+@item name
+Check whether a name (used in an email address header) looks
+suspicious.  @var{object} should be a string.
+
+@item email-address-header
+Check whether a full RFC2822 email address header (e.g.,
+@samp{=?utf-8?Q?=C3=81?= <foo@@example.com>}) looks suspicious.
+@var{object} should be a string.
+@end table
+
+If @var{object} is suspicious, this function returns a string that
+explains why it is suspicious.  If @var{object} is not suspicious, the
+function returns @code{nil}.
+@end defun
+
+@vindex textsec-suspicious@r{ (face)}
+If the text is suspicious, the application should mark the suspicious
+text with the @code{textsec-suspicious} face, and make the explanation
+returned by @code{textsec-suspicious-p} available to the user in some way
+(for example, in a tooltip).  The application might also prompt the
+user for confirmation before taking any action on a suspicious string
+(like sending an email to a suspicious email address).
+
 @node GnuTLS Cryptography
 @section GnuTLS Cryptography
 @cindex MD5 checksum
diff --git a/doc/misc/ert.texi b/doc/misc/ert.texi
index 0d01efb0355..91288db45a2 100644
--- a/doc/misc/ert.texi
+++ b/doc/misc/ert.texi
@@ -444,8 +444,9 @@ emacs -batch -l ert -l my-tests.el \
 @vindex EMACS_TEST_VERBOSE@r{, environment variable}
 By default, ERT test failure summaries are quite brief in batch
 mode---only the names of the failed tests are listed.  If the
-@env{EMACS_TEST_VERBOSE} environment variable is set, the failure
-summaries will also include the data from the failing test.
+@env{EMACS_TEST_VERBOSE} environment variable is set and is non-empty,
+the failure summaries will also include the data from the failing
+test.
 
 @vindex EMACS_TEST_JUNIT_REPORT@r{, environment variable}
 ERT can produce JUnit test reports in batch mode.  If the environment
diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index f1d7c638056..df6e3b861e4 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -407,9 +407,16 @@ Summarize disk usage for each file.
 
 @item echo
 @cmindex echo
-Echoes its input.  If @code{eshell-plain-echo-behavior} is
-non-@code{nil}, @command{echo} will try to behave more like a plain
-shell's @command{echo}.
+Echoes its input.  By default, this prints in a Lisp-friendly fashion
+(so that the value is useful to a Lisp command using the result of
+@command{echo} as an argument).  If a single argument is passed,
+@command{echo} prints that; if multiple arguments are passed, it
+prints a list of all the arguments; otherwise, it prints the empty
+string.
+
+If @code{eshell-plain-echo-behavior} is non-@code{nil}, @command{echo}
+will try to behave more like a plain shell's @command{echo}, printing
+each argument as a string, separated by a space.
 
 @item env
 @cmindex env
diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi
index b3efdfbacba..306d66de64e 100644
--- a/doc/misc/gnus.texi
+++ b/doc/misc/gnus.texi
@@ -14838,12 +14838,17 @@ mail belongs in that group.
 The last of these groups should always be a general one, and the regular
 expression should @emph{always} be @samp{""} so that it matches any mails
 that haven't been matched by any of the other regexps.  (These rules are
-processed from the beginning of the alist toward the end.  The first rule
-to make a match will ``win'', unless you have crossposting enabled.  In
-that case, all matching rules will ``win''.)  If no rule matched, the mail
-will end up in the @samp{bogus} group.  When new groups are created by
-splitting mail, you may want to run @code{gnus-group-find-new-groups} to
-see the new groups.  This also applies to the @samp{bogus} group.
+processed from the beginning of the alist toward the end.
+
+If multiple rules match (excluding the general @samp{""} group), mail
+is crossposted to all these groups.  However, if
+@code{nnmail-crosspost} is set to @code{nil}, the first rule to make a
+match will ``win''.
+
+If no rule matched, the mail will end up in the @samp{bogus} group.
+When new groups are created by splitting mail, you may want to run
+@code{gnus-group-find-new-groups} to see the new groups.  This also
+applies to the @samp{bogus} group.
 
 If you like to tinker with this yourself, you can set this variable to a
 function of your choice.  This function will be called without any