[elpa] externals/denote 2c9c9cc18c 3/4: Document in the manual batch front matter rename

[ELPA Syncer]

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

    Document in the manual batch front matter rename
    
    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>
---
 README.org | 42 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 41 insertions(+), 1 deletion(-)

diff --git a/README.org b/README.org
index 79ded336a7..f5563dc1f7 100644
--- a/README.org
+++ b/README.org
@@ -578,6 +578,45 @@ edited in the front matter: Denote considers the file name 
to be the
 source of truth in this case, to avoid potential breakage with typos and
 the like.
 
+** Rename multiple files based on their front matter
+:PROPERTIES:
+:CUSTOM_ID: h:ea5673cd-e6ca-4c42-a066-07dc6c9d57f8
+:END:
+
+[ Part of {{{development-version}}} ]
+
+#+findex: denote-dired-rename-marked-files-using-front-matter
+As already noted, Denote can rename a file based on the data in its
+front matter ([[#h:3ab08ff4-81fa-4d24-99cb-79f97c13a373][Rename a single file 
based on its front matter]]).  The
+command ~denote-dired-rename-marked-files-using-front-matter~ extends
+this principle to a batch operation which applies to all marked files in
+Dired.
+
+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.
+
+The operation does the following:
+
+- the title in the front matter becomes the =TITLE= component of the
+  file name ([[#h:4e9c7512-84dc-4dfb-9fa9-e15d51178e5d][The 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.
+
 * The file-naming scheme
 :PROPERTIES:
 :CUSTOM_ID: h:4e9c7512-84dc-4dfb-9fa9-e15d51178e5d
@@ -1574,7 +1613,8 @@ Everything is in place to set up the package.
 ;; Key bindings specifically for Dired.
 (let ((map dired-mode-map))
   (define-key map (kbd "C-c C-d C-i") #'denote-link-dired-marked-notes)
-  (define-key map (kbd "C-c C-d C-r") #'denote-dired-rename-marked-files))
+  (define-key map (kbd "C-c C-d C-r") #'denote-dired-rename-marked-files)
+  (define-key map (kbd "C-c C-d C-R") 
#'denote-dired-rename-marked-files-using-front-matter))
 
 (with-eval-after-load 'org-capture
   (setq denote-org-capture-specifiers "%l\n%i\n%?")