[elpa] externals/denote c594723e98 1/4: Update batch front matter rename doc string

[ELPA Syncer]

branch: externals/denote
commit c594723e98056bbc1ed4cabccd770c19905e6cd2
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>

    Update batch front matter rename doc string
    
    This is part of the work being done to refine the feature set of the
    renaming mechanism.
    
    Issue on the GitHub mirror: 
<https://github.com/protesilaos/denote/issues/74>.
    
    Mailing list threads (I wish they were not split like that, but here we
    are):
    
    - 
<https://lists.sr.ht/~protesilaos/denote/%3C87k081l6vw.fsf%40silverstone.mail-host-address-is-not-set%3E>
    - 
<https://lists.sr.ht/~protesilaos/denote/%3C878rogw5kk.fsf%40protesilaos.com%3E>
    - 
<https://lists.sr.ht/~protesilaos/denote/%3C87fsiljv1s.fsf%40hu.mail-host-address-is-not-set%3E>
    - 
<https://lists.sr.ht/~protesilaos/denote/%3C87r122afe3.fsf%40hu.mail-host-address-is-not-set%3E>
---
 denote.el | 32 ++++++++++++++++++++++++++++----
 1 file changed, 28 insertions(+), 4 deletions(-)

diff --git a/denote.el b/denote.el
index b9a606beb4..b53692e735 100644
--- a/denote.el
+++ b/denote.el
@@ -1403,11 +1403,35 @@ typos and the like."
     (user-error "No front matter for title and/or keywords")))
 
 ;;;###autoload
-(defun denote-rename-marked-files-using-front-matter ()
-  "Rename marked files using the information in their front matter.
+(defun denote-dired-rename-marked-files-using-front-matter ()
+  "Rename marked files in Dired using their front matter as input.
+Marked files must count as notes for the purposes of Denote,
+which means that they at least have an identifier in their file
+name and use a supported file type, per `denote-file-type'.
+Files that do not meet this criterion are ignored.
 
-This command can be used to synchronize multiple file names with
-the content of the file's front matter."
+The operation does the following:
+
+- the title in the front matter becomes the TITLE component of
+  the file name, with hyphenation per Denote's file-naming
+  scheme;
+
+- the keywords in the front matter are used for the KEYWORDS
+  component of the file name and are processed accordingly, if
+  needed;
+
+- the identifier remains unchanged in the file name even if it is
+  modified in the front matter (this is done to avoid breakage
+  caused by typos and the like).
+
+NOTE that files must be saved, because Denote reads from the
+underlying file, not a modified buffer (this is done to avoid
+potential mistakes).  The return value of a modified buffer is
+the one prior to the modification, i.e. the one already written
+on disk.
+
+This command is useful for synchronizing multiple file names with
+their respective front matter."
   (interactive nil dired-mode)
   (if-let ((marks (seq-filter
                    (lambda (file) (denote--only-note-p file))