branch: externals/denote
commit c9ba0b5bd025cadee12aa4b01c2c790e0172f284
Author: Protesilaos Stavrou <i...@protesilaos.com>
Commit: Protesilaos Stavrou <i...@protesilaos.com>
Rewrite the section in the manual about denote-rename-file-signature
---
README.org | 46 +++++++++++++++++++++++++++-------------------
1 file changed, 27 insertions(+), 19 deletions(-)
diff --git a/README.org b/README.org
index 6365646e4a..53744b8304 100644
--- a/README.org
+++ b/README.org
@@ -1687,25 +1687,33 @@ accordingly. An empty input means to remove all
keywords.
:CUSTOM_ID: h:b08a350f-b269-47ed-8c2a-b8ecf1b63c7f
:END:
-#+findex: denote-rename-add-signature
-#+findex: denote-rename-remove-signature
-The commands ~denote-rename-add-signature~ and
-~denote-rename-remove-signature~ streamline the process of
-interactively adding or removing a signature from a given file
([[#h:4e9c7512-84dc-4dfb-9fa9-e15d51178e5d][The file-naming scheme]]).
-
-The ~denote-rename-add-signature~ prompts for a file and a signature. The
-default value for the file prompt is the file of the currently open
-buffer or the file-at-point in a Dired buffer. The signature is an
-ordinary string, defaulting to the selected file's signature, if any.
-
-The ~denote-rename-remove-signature~ uses the same file prompt as
-above. It performs its action only if the selected file has a
-signature. Otherwise, it does nothing.
-
-Both commands respect the value of ~denote-rename-confirmations~
-([[#h:a2ae9090-c49e-4b32-bcf5-eb8944241fd7][The ~denote-rename--confirmations~
option]]). They also both take care
-to reload any Dired buffers and run the ~denote-after-rename-file-hook~
-as a final step.
+#+findex: denote-rename-file-signature
+The command ~denote-rename-file-signature~ streamlines the process of
+interactively adding or removing a signature to/from a file, while
+changing its file name accordingly. It asks for a signature using the
+familiar minibuffer prompt
([[#h:6a92a8b5-d766-42cc-8e5b-8dc255466a23][Standard note creation]]). It then
renames
+the file. The command respect the values of
+~denote-rename-confirmations~ and ~denote-save-buffers~:
+
+- [[#h:a2ae9090-c49e-4b32-bcf5-eb8944241fd7][The ~denote-rename-confirmations~
option]].
+- [[#h:bf80f4cd-6f56-4f7c-a991-8573161e4511][The ~denote-save-buffers~
option]].
+
+Technically, ~denote-rename-file-signature~ is a wrapper for
+~denote-rename-file~, doing all the things that does
([[#h:7cc9e000-806a-48da-945c-711bbc7426b0][Rename a single file]]).
+
+Concretely, this command can add or remove a signature in one go. It
+does it by prepopulating the minibuffer prompt with the existing
+signature. Users can then modify it. An empty input means to remove
+the signature altogether ([[#h:4e9c7512-84dc-4dfb-9fa9-e15d51178e5d][The
file-naming scheme]]).
+
+[ NOTE: Please check with your minibuffer user interface how to
+ provide an empty input. The Emacs default setup accepts the empty
+ minibuffer contents as they are, though popular packages like
+ ~vertico~ use the first available completion candidate instead. For
+ ~vertico~, the user must either move one up to select the prompt and
+ then type =RET= there with empty contents, or use the command
+ ~vertico-exit-input~ with empty contents. That Vertico command is
+ bound to =M-RET= as of this writing on 2024-06-30 10:37 +0300. ]
** Faces used by rename commands
:PROPERTIES:
