4 files changed, 98 insertions, 11 deletions
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