Improve documentation of textsec

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

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

1 files changed, 35 insertions, 23 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