From bb6dce33c14df5090030bc91f8d76c3486ce3d90 Mon Sep 17 00:00:00 2001
From: Jim Porter <jporterbugs@gmail.com>
Date: Wed, 16 Jul 2025 19:30:09 -0700
Subject: [PATCH] Improve wording of messages and documentation for
 'eww-readable'

* lisp/net/eww.el (eww-readable, eww-mode): Improve wording; avoid using
the word "content".

* doc/misc/eww.texi (Basics): Improve wording.

(cherry picked from commit 291cd2d3419c7be20200db3f0ee5936661ab79f2)
---
 doc/misc/eww.texi | 17 +++++++++--------
 lisp/net/eww.el   |  4 ++--
 2 files changed, 11 insertions(+), 10 deletions(-)

diff --git a/doc/misc/eww.texi b/doc/misc/eww.texi
index 5be59972811..98514aa0dec 100644
--- a/doc/misc/eww.texi
+++ b/doc/misc/eww.texi
@@ -142,9 +142,10 @@ a new tab is created on the frame tab bar.
 
 @findex eww-readable
 @kindex R
-  The @kbd{R} command (@code{eww-readable}) will attempt to determine
-which part of the document contains the ``readable'' text, and will
-only display this part.  This usually gets rid of menus and the like.
+  The @kbd{R} command (@code{eww-readable}) attempts to determine
+which part of the current page contains the ``readable'' text, and will
+only display this part.  This removes clutter like navigation menus to
+help you focus on the important text.
 
   When called interactively, this command toggles the display of the
 readable parts.  With a positive prefix argument, this command always
@@ -152,15 +153,15 @@ displays the readable parts, and with a zero or negative prefix, it
 always displays the full page.
 
 @vindex eww-readable-urls
-  If you want EWW to render a certain page in ``readable'' mode by
+  If you want EWW to render certain pages using the ``readable'' view by
 default, you can add a regular expression matching its URL to
 @code{eww-readable-urls}.  Each entry can either be a regular expression
 in string form or a cons cell of the form
 @w{@code{(@var{regexp} . @var{readability})}}.  If @var{readability} is
-non-@code{nil}, this behaves the same as the string form; otherwise,
-URLs matching @var{regexp} will never be displayed in readable mode by
-default.  For example, you can use this to make all pages default to
-readable mode, except for a few outliers:
+non-@code{nil}, this behaves the same as the string form; if @code{nil},
+EWW will always render the full page by default for matching URLs.  For
+example, you can use this to make all pages default to readable mode,
+except for a few outliers:
 
 @example
 (setq eww-readable-urls '(("https://example\\.com/" . nil)
diff --git a/lisp/net/eww.el b/lisp/net/eww.el
index 70566599de7..f946b440641 100644
--- a/lisp/net/eww.el
+++ b/lisp/net/eww.el
@@ -1138,7 +1138,7 @@ adds a new entry to `eww-history'."
          (base (plist-get eww-data :url)))
     (when make-readable
       (unless (setq dom (eww-readable-dom dom))
-        (message "Unable to find readable content")))
+        (message "Unable to extract readable text from this page")))
     (when dom
       (when eww-readable-adds-to-history
         (eww-save-history)
@@ -1390,7 +1390,7 @@ within text input fields."
   `("eww"
     (:eval (when (plist-get eww-data :readable)
              '(:propertize ":readable"
-               help-echo "Displaying readable content"))))
+               help-echo "Showing only human-readable text of page"))))
   "Mode for browsing the web."
   :interactive nil
   (setq-local eww-data (list :title ""))
-- 
2.39.5