branch: externals/denote
commit 1b4dc74e3cdb9ca27f6ede1613947f742dd7205b
Author: Protesilaos Stavrou <i...@protesilaos.com>
Commit: Protesilaos Stavrou <i...@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
