[elpa] externals/denote 1b4dc74e3c 224/355: Update denote-dired.el Commentary section

[ELPA Syncer]

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

    Update denote-dired.el Commentary section
---
 denote-dired.el | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/denote-dired.el b/denote-dired.el
index fa4426dbad..0f2e924295 100644
--- a/denote-dired.el
+++ b/denote-dired.el
@@ -24,6 +24,62 @@
 
 ;;; Commentary:
 ;;
+;; Denote's file-naming scheme is not specific to notes or text files:
+;; it is useful for all sorts of files, such as multimedia and PDFs that
+;; form part of the user's longer-term storage (read manual's "The
+;; file-naming scheme").  While Denote does not manage such files, it
+;; already has all the mechanisms to facilitate the task of renaming
+;; them.
+;;
+;; To this end, we provide the `denote-dired-rename-file' command.  It
+;; has a two-fold purpose: (i) to change the name of an existing file
+;; while retaining its identifier and (ii) to write a Denote-compliant
+;; file name for an item that was not created by `denote' or related
+;; commands (such as an image or PDF).
+;;
+;; The `denote-dired-rename-file' command will target the file at point
+;; if it finds one in the current Dired buffer.  Otherwise it prompts
+;; with minibuffer completion for a file name.  It then uses the
+;; familiar prompts for a `TITLE' and `KEYWORDS' the same way the
+;; `denote' command does (read manual's "Points of entry).  As a final
+;; step, it asks for confirmation before renaming the file at point,
+;; showing a message like:
+;;
+;;     Rename sample.pdf to 20220612T052900--my-sample-title__testing.pdf? (y 
or n)
+;;
+;; However, if the user option `denote-dired-rename-expert' is non-nil,
+;; conduct the renaming operation outright---no questions asked.
+;;
+;; When operating on a file that has no identifier, such as
+;; `sample.pdf', Denote reads the file properties to retrieve its last
+;; modification time.  If the file was from a past date like 2000-11-31
+;; it will get an identifier starting with `20001131' followed by the
+;; time component (per our file-naming scheme).
+;;
+;; The file type extension (e.g. `.pdf') is read from the underlying
+;; file and is preserved through the renaming process.  Files that have
+;; no extension are simply left without one.
+;;
+;; Renaming only occurs relative to the current directory.  Files are not
+;; moved between directories.
+;;
+;; The final step of the `denote-dired-rename-file' command is to call
+;; the special hook `denote-dired-post-rename-functions'.  Functions
+;; added to that hook must accept three arguments, as explained in its
+;; doc string.  For the time being, the only function we define is the
+;; one which updates the underlying note's front matter to match the new
+;; file name: `denote-dired-rewrite-front-matter'.  The function takes
+;; care to only operate on an actual note, instead of arbitrary files.
+;;
+;; DEVELOPMENT NOTE: the `denote-dired-rewrite-front-matter' needs to be
+;; tested thoroughly.  It rewrites file contents so we have to be sure
+;; it does the right thing.  To avoid any trouble, it always asks for
+;; confirmation before performing the replacement.  This confirmation
+;; ignores `denote-dired-rename-expert' for the time being, though we
+;; might want to lift that restriction once everything works as
+;; intended.
+;;
+;;
 ;; One of the upsides of Denote's file-naming scheme is the predictable
 ;; pattern it establishes, which appears as a near-tabular presentation in
 ;; a listing of notes (i.e. in Dired).  The `denote-dired-mode' can help