Improve documentation of textsec

* lisp/international/textsec-check.el (textsec-check): Doc fixes.

* doc/lispref/text.texi (Suspicious Text): Improve wording and
indexing.

3 files changed, 60 insertions, 32 deletions

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index e94b1112d70..097c1de4449 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -4946,9 +4946,12 @@ It should be somewhat more efficient on larger buffers than
 
 @node Suspicious Text
 @section Suspicious Text
+@cindex suspicious text
+@cindex insecure text
+@cindex security vulnerabilities in text
 
-Emacs can display data from many external sources, like mail and web
-pages.  Attackers may attempt to confuse the user reading this data by
+  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.
@@ -4959,11 +4962,13 @@ 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.
 
-To help identify these @dfn{suspicious strings}, Emacs provides a
-library to do a number of checks.  (See
-@url{https://www.unicode.org/reports/tr39/} for the rationale behind
-the checks that are available.)  Packages that present data that might
-be suspicious should use this library.
+@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-check object type
@@ -4971,52 +4976,59 @@ 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} to see if it looks suspicious when
-interpreted as a thing of @var{type}.  The available types are:
+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.
+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} 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}.
+@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.
+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.
+@samp{@@} sign) looks suspicious.  @var{object} should be a string.
 
 @item name
-Check whether a name (used in an email address header) looks suspicious.
+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 will return a string that
-explains why it is suspicious.  If @var{object} is not suspicious, it
-returns @code{nil}.
+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-check} available to the user.  The
-application might also prompt the user before taking any action on a
-suspicious string (like sending an email to a suspicious email
-address).
+returned by @code{textsec-check} 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
diff --git a/etc/NEWS b/etc/NEWS
index d3abe349f2a..17ddd6bc186 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1023,8 +1023,8 @@ may be used to confuse a user.
 If non-nil (which is the default), Emacs packages that are vulnerable
 to attackers trying to confuse the users will use the textsec library
 to mark suspicious text.  For instance shr/eww will mark suspicious
-URLs and links, and Gnus will mark suspicious From addresses, and
-Message will query the user if the user is sending mail to a
+URLs and links, Gnus will mark suspicious From addresses, and
+Message mode will query the user if the user is sending mail to a
 suspicious address.  If this variable is nil, these checks aren't
 performed.
 
diff --git a/lisp/international/textsec-check.el b/lisp/international/textsec-check.el
index f61cc82b5b2..e3662e0d85c 100644
--- a/lisp/international/textsec-check.el
+++ b/lisp/international/textsec-check.el
@@ -29,7 +29,7 @@
   :version "29.1")
 
 (defcustom textsec-check t
-  "If non-nil, perform some checks on certain texts.
+  "If non-nil, perform some security-related checks on text objects.
 If nil, these checks are disabled."
   :type 'boolean
   :version "29.1")
@@ -40,14 +40,30 @@ If nil, these checks are disabled."
 
 ;;;###autoload
 (defun textsec-check (object type)
-  "Test whether OBJECT is suspicious when considered as TYPE.
-If OBJECT is suspicious, a string explaining the possible problem
-is returned.
+  "Test whether OBJECT is suspicious for use as TYPE.
+If OBJECT is suspicious, return a string explaining the reason
+for considering it suspicious, otherwise return nil.
 
-Available types include `url', `link', `domain', `local-address',
-`name', `email-address', and `email-address-header'.
+Available values of TYPE and corresponding OBJECTs are:
 
-If the `textsec-check' user option is nil, these checks are
+ `url'                   -- a URL; OBJECT should be a URL string.
+
+ `link'                 -- an HTML link; OBJECT should be a cons cell
+                           of the form (URL . LINK-TEXT).
+
+ `domain'               -- a Web domain; OBJECT should be a string.
+
+ `local-address'        -- the local part of an email address; OBJECT
+                           should be a string.
+ `name'                 -- the \"display name\" part of an email address;
+                           OBJECT should be a string.
+
+`email-address'         -- a full email address; OBJECT should be a string.
+
+ `email-address-header' -- a raw email address header in RFC 2822 format;
+                           OBJECT should be a string.
+
+If the user option `textsec-check' is nil, these checks are
 disabled, and this function always returns nil."
   (if (not textsec-check)
       nil