From 1002852f1aecb5e2568c91e2ca293f0ebfa1c9c9 Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 22 Aug 2020 19:14:35 +0300
Subject: [PATCH] Fix documentation of a recent change in Dired

* etc/NEWS:
* doc/emacs/dired.texi (Dired Enter): Fix the text describing
'dired-maybe-use-globstar'.

* lisp/dired.el (dired-maybe-use-globstar): Add :version.
---
 doc/emacs/dired.texi | 23 ++++++++++++++---------
 etc/NEWS             |  9 ++++++---
 lisp/dired.el        |  3 ++-
 3 files changed, 22 insertions(+), 13 deletions(-)

diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi
index 39caab086c2..19aaca962da 100644
--- a/doc/emacs/dired.texi
+++ b/doc/emacs/dired.texi
@@ -79,23 +79,28 @@ The former lists all the files with extension @samp{.el} in directory
 @samp{foo}.  The latter lists the files with extension @samp{.el}
 in all the subdirectories of @samp{foo}.
 
-When the system shell supports globstar and it's enabled, then you
-can use recursive globbing:
+@cindex globstar, in Dired
+On Posix systems, when the system shell supports @dfn{globstar}, a
+recursive globbing feature, and that support is enabled, you can use
+recursive globbing in Dired:
 
 @example
 C-x d  ~/foo/**/*.el  @key{RET}
 @end example
 
-This command lists all the files with extension @samp{.el} descending
-recursively in all the subdirectories of @samp{foo}.  Note that there
-are small differences in the implementation of globstar between shells.
-Check your shell manual to know the expected behavior.
+This command produces a directory listing with all the files with
+extension @samp{.el}, descending recursively in all the subdirectories
+of @samp{foo}.  Note that there are small differences in the
+implementation of globstar between different shells.  Check your shell
+manual to know the expected behavior.
 
 @vindex dired-maybe-use-globstar
 @vindex dired-enable-globstar-in-shell
-If the shell supports globstar and disables it by default, you
-can still enable this feature with @code{dired-maybe-use-globstar} if
-the shell is included in @code{dired-enable-globstar-in-shell}.
+If the shell supports globstar, but that support is disabled by
+default, you can still let Dired use this feature by customizing
+@code{dired-maybe-use-globstar} to a non-@code{nil} value; then Dired
+will enable globstar for those shells for which it knows how (see
+@code{dired-enable-globstar-in-shell} for the list of those shells).
 
 The usual history and completion commands can be used in the minibuffer;
 in particular, @kbd{M-n} puts the name of the visited file (if any) in
diff --git a/etc/NEWS b/etc/NEWS
index a47b6e10b16..736892db8eb 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -230,9 +230,12 @@ time zones will use a form like "+0100" instead of "CET".
 
 +++
 *** New user option 'dired-maybe-use-globstar'.
-If set, enables globstar in shells that support this feature.  The new
-variable 'dired-enable-globstar-in-shell' lists which shells can have
-globstar enabled.
+If set, enables globstar (recursive globbing) in shells that support
+this feature, but turn it off by default.  This allows producing
+directory listings with files matching a wildcard in all the
+subdirectories of a given directory.  The new variable
+'dired-enable-globstar-in-shell' lists which shells can have globstar
+enabled, and how to enable it.
 
 +++
 *** New user option 'dired-copy-dereference'.
diff --git a/lisp/dired.el b/lisp/dired.el
index d22d52ce627..94d3befda85 100644
--- a/lisp/dired.el
+++ b/lisp/dired.el
@@ -88,7 +88,8 @@ Note that the implementations of globstar have small differences
 between shells.  You must check your shell documentation to see
 what to expect."
   :type 'boolean
-  :group 'dired)
+  :group 'dired
+  :version "28.1")
 
 (defconst dired-enable-globstar-in-shell
   '(("ksh" . "set -G")
-- 
2.39.2