branch: externals/denote
commit 9eacb2f4e81ba92f1f3250eee8181316a5070672
Author: Protesilaos Stavrou <i...@protesilaos.com>
Commit: Protesilaos Stavrou <i...@protesilaos.com>
Document the denote-rename-confirmations in the manual
---
README.org | 42 ++++++++++++++++++++++--------------------
1 file changed, 22 insertions(+), 20 deletions(-)
diff --git a/README.org b/README.org
index b66e51ee32..04fdafe08e 100644
--- a/README.org
+++ b/README.org
@@ -1275,35 +1275,37 @@ scheme.
For a version of this command that works with multiple files
one-by-one, use ~denote-dired-rename-files~
([[#h:1b6b2c78-42f0-45b8-9ef0-6de21a8b2cde][Rename multiple files
interactively]]).
-*** The ~denote-rename-no-confirm~ option
+*** The ~denote-rename-confirmations~ option
:PROPERTIES:
:CUSTOM_ID: h:a2ae9090-c49e-4b32-bcf5-eb8944241fd7
:END:
-#+vindex: denote-rename-no-confirm
-The user option ~denote-rename-no-confirm~ makes all commands that
-rename files not prompt for confirmation and save buffers outright
([[#h:532e8e2a-9b7d-41c0-8f4b-3c5cbb7d4dca][Renaming files]]).
+[ As part of {{{development-version}}} the ~denote-rename-no-confirm~
+ is deprecated and superseded by the more flexible
~denote-rename-confirmations~. ]
-This affects the behaviour of the commands ~denote-rename-file~,
-~denote-dired-rename-files~, ~denote-rename-file-using-front-matter~,
-~denote-dired-rename-marked-files-with-keywords~,
-~denote-dired-rename-marked-files-using-front-matter~,
-~denote-keywords-add~, ~denote-keywords-remove~, and any other command
-that builds on top of them.
+#+vindex: denote-rename-confirmations
+The user option ~denote-rename-confirmations~ controls what kind of
+confirmation renaming commands ask for
([[#h:532e8e2a-9b7d-41c0-8f4b-3c5cbb7d4dca][Renaming files]]). Its value is
+a list of symbols.
+
+The value is either nil, in which case no confirmation is ever
+requested, or a list of symbols among the following:
+
+- ~modify-file-name~ means that renaming commands will ask for
+ confirmation before modifying the file name.
+
+- ~rewrite-front-matter~ means that renaming commands will ask for
+ confirmation before rewritting the front matter.
+
+- ~add-front-matter~ means that renaming commands will ask for
+ confirmation before adding new front matter to the file.
The default behaviour of the ~denote-rename-file~ command (and others
like it) is to ask for an affirmative answer as a final step before
changing the file name and, where relevant, inserting or updating the
-corresponding front matter. It also does not save the affected file's
-buffer to let the user inspect and confirm the changes (such as by
-invoking the command ~diff-buffer-with-file~).
-
-With this user option bound to a non-nil value, buffers are saved as
-well. The assumption is that the user who opts in to this feature is
-familiar with the ~denote-rename-file~ (or related) operation and
-knows it is reliable.
+corresponding front matter.
-Specialised commands that build on top of ~denote-rename-file~ (or
+Specialized commands that build on top of ~denote-rename-file~ (or
related) may internally bind this user option to a non-nil value in
order to perform their operation (e.g. ~denote-dired-rename-files~
goes through each marked Dired file, prompting for the information to
@@ -3985,7 +3987,7 @@ Everything is in place to set up the package.
(setq denote-prompts '(title keywords))
(setq denote-excluded-directories-regexp nil)
(setq denote-excluded-keywords-regexp nil)
-(setq denote-rename-no-confirm nil) ; Set to t if you are familiar with
`denote-rename-file'
+(setq denote-rename-confirmations '(rewrite-front-matter modify-file-name))
;; Pick dates, where relevant, with Org's advanced interface:
(setq denote-date-prompt-use-org-read-date t)
