Mention url-handler-mode in the Emacs manual

* doc/emacs/misc.texi (Browse-URL): Mention url-handler-mode
(bug#30389).

* lisp/url/url-handlers.el (url-handler-mode): Improve doc string.

2 files changed, 18 insertions, 1 deletions

diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index 8bf1032633b..528cfa94c66 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -2973,6 +2973,15 @@ URLs.
 For more information, view the package commentary by typing @kbd{C-h P
 browse-url @key{RET}}.
 
+@findex url-handler-mode
+  Emacs also has a minor mode that has some support for handling
+@acronym{URL}s as if they were files.  @code{url-handler-mode} is a
+global minor mode that affects most of the Emacs commands and
+primitives that deal with file names.  After switching on this mode,
+you can say, for instance, @kbd{C-x C-f https://www.gnu.org/ RET} to
+see the @acronym{HTML} for that web page, and you can then edit it and
+save it to a local file, for instance.
+
 @node Goto Address mode
 @subsection Activating URLs
 @findex goto-address-mode
diff --git a/lisp/url/url-handlers.el b/lisp/url/url-handlers.el
index 68556d6aa9c..ed0402a5137 100644
--- a/lisp/url/url-handlers.el
+++ b/lisp/url/url-handlers.el
@@ -102,7 +102,15 @@
 
 ;;;###autoload
 (define-minor-mode url-handler-mode
-  "Toggle using `url' library for URL filenames (URL Handler mode)."
+  "Handle URLs as if they were file names throughout Emacs.
+After switching on this minor mode, Emacs file primitives handle
+URLs.  For instance:
+
+  (file-exists-p \"https://www.gnu.org/\")
+  => t
+
+and `C-x C-f https://www.gnu.org/ RET' will give you the HTML at
+that URL in a buffer."
   :global t :group 'url
   ;; Remove old entry, if any.
   (setq file-name-handler-alist