branch: externals/denote
commit 9efa59452bfb956d20af7d95ea52d431893d9969
Author: Protesilaos Stavrou <i...@protesilaos.com>
Commit: Protesilaos Stavrou <i...@protesilaos.com>
Add denote-add-front-matter command
The idea for this command originates in the discussion in issue 74 over
at the GitHub mirror: <https://github.com/protesilaos/denote/issues/74>.
The relevant point is this comment of mine:
<https://github.com/protesilaos/denote/issues/74#issuecomment-1207201324>.
---
README.org | 31 +++++++++++++++++++++++++++++++
denote.el | 48 +++++++++++++++++++++++++++++++++++++++++++++---
2 files changed, 76 insertions(+), 3 deletions(-)
diff --git a/README.org b/README.org
index da04e2544b..915100b619 100644
--- a/README.org
+++ b/README.org
@@ -913,6 +913,37 @@ provide examples at this point as this is a more advanced
feature and we
are not yet sure what the user's needs are. Please provide feedback and
we shall act accordingly.
+** Regenerate front matter
+:PROPERTIES:
+:CUSTOM_ID: h:54b48277-e0e5-4188-ad54-ef3db3b7e772
+:END:
+
+[ Part of {{{development-version}}} ]
+
+#+findex: denote-add-front-matter
+Sometimes the user needs to produce new front matter for an existing
+note. Perhaps because they accidentally deleted a line and could not
+undo the operation. The command ~denote-add-front-matter~ can be used
+for this very purpose.
+
+In interactive use, ~denote-add-front-matter~ must be invoked from a
+buffer that visits a Denote note. It prompts for a title and then for
+keywords. These are the standard prompts we already use for note
+creation, so the keywords' prompt allows minibuffer completion and the
+input of multiple entries, each separated by a comma
([[#h:17896c8c-d97a-4faa-abf6-31df99746ca6][Points of entry]]).
+
+The newly created front matter is added to the top of the file.
+
+This command does not rename the file (e.g. to update the keywords). To
+rename a file by reading its front matter as input, the user can rely on
+~denote-rename-file-using-front-matter~
([[#h:532e8e2a-9b7d-41c0-8f4b-3c5cbb7d4dca][Renaming files]]).
+
+Note that ~denote-add-front-matter~ is useful only for existing Denote
+notes. If the user needs to convert a generic text file to a Denote
+note, they can use one of the command which first rename the file to
+make it comply with our file-naming scheme and then add the relevant
+front matter.
+
* Linking notes
:PROPERTIES:
:CUSTOM_ID: h:fc913d54-26c8-4c41-be86-999839e8ad31
diff --git a/denote.el b/denote.el
index b9bbc011fe..36c75522b8 100644
--- a/denote.el
+++ b/denote.el
@@ -1124,9 +1124,13 @@ appropriate."
(defun denote--edit-front-matter-p (file)
"Test if FILE should be subject to front matter rewrite.
-This is relevant for `denote--rewrite-front-matter'. We can edit
-the front matter if it contains a \"title\" line and a \"tags\"
-line (the exact syntax depending on the file type)."
+This is relevant for operations that insert or rewrite the front
+matter in a Denote note.
+
+For the purposes of this test, FILE is a Denote note when it (i)
+is a regular file, (ii) is writable, (iii) has a supported file
+type extension per `denote-file-type', and (iv) is stored in the
+variable `denote-directory'."
(when-let ((ext (file-name-extension file)))
(and (file-regular-p file)
(file-writable-p file)
@@ -1440,6 +1444,44 @@ their respective front matter."
(revert-buffer))
(user-error "No marked files; aborting")))
+;;;;; Creation of front matter
+
+;;;###autoload
+(defun denote-add-front-matter (file title keywords)
+ "Insert front matter at the top of FILE.
+
+When called interactively, FILE is the return value of the
+function `buffer-file-name'. FILE is checked to determine
+whether it is a note for Denote's purposes.
+
+TITLE is a string. Interactively, it is the user input at the
+minibuffer prompt.
+
+KEYWORDS is a list of strings. Interactively, it is the user
+input at the minibuffer prompt. This one supports completion for
+multiple entries, each separated by the `crm-separator' (normally
+a comma).
+
+The purpose of this command is to help the user generate new
+front matter for an existing note (perhaps because the user
+deleted the previous one and could not undo the change).
+
+This command does not rename the file (e.g. to update the
+keywords). To rename a file by reading its front matter as
+input, use `denote-rename-file-using-front-matter'.
+
+Note that this command is useful only for existing Denote notes.
+If the user needs to convert a generic text file to a Denote
+note, they can use one of the command which first rename the file
+to make it comply with our file-naming scheme and then add the
+relevant front matter."
+ (interactive
+ (list
+ (buffer-file-name)
+ (denote--title-prompt)
+ (denote--keywords-prompt)))
+ (denote--add-front-matter file title keywords (denote--file-name-id file)))
+
;;;; The Denote faces
(defgroup denote-faces ()
