[elpa] externals/denote 9efa59452b: Add denote-add-front-matter command

[ELPA Syncer]

branch: externals/denote
commit 9efa59452bfb956d20af7d95ea52d431893d9969
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@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 ()