[elpa] externals/denote 3384ee91df 2/2: Add commands for linking to existing or new notes

[ELPA Syncer]

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

    Add commands for linking to existing or new notes
    
    Thanks to user sienic for suggesting the idea and for testing the
    prototypes.  And thanks to Juanjo Presa for participating in the
    discussion to share the view that this functionality should be part of
    denote.el.  This happened in issue 96 over at the GitHub mirror:
    <https://github.com/protesilaos/denote/issues/96>.
---
 README.org | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---
 denote.el  | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 105 insertions(+), 3 deletions(-)

diff --git a/README.org b/README.org
index 95236f1da4..24a9768153 100644
--- a/README.org
+++ b/README.org
@@ -1240,6 +1240,58 @@ Dired buffer.
 As always, links are created only for files which qualify as a "note"
 for our purposes ([[#h:fc913d54-26c8-4c41-be86-999839e8ad31][Linking notes]]).
 
+** Link to an existing note or create a new one
+:PROPERTIES:
+:CUSTOM_ID: h:9e41e7df-2aac-4835-94c5-659b6111e6de
+:END:
+
+[ The ~denote-link-after-creating~ and ~denote-link-or-create~ are part
+  of {{{development-version}}}. ]
+
+In one's note-taking workflow, there may come a point where they are
+expounding on a certain topic but have an idea about another subject
+they would like to link to ([[#h:fc913d54-26c8-4c41-be86-999839e8ad31][Linking 
notes]]).  The user can always rely on
+the other linking facilities we have covered herein to target files that
+already exist.  Though they may not know whether they already have notes
+covering the subject or whether they would need to write new ones.  To
+this end, Denote provides two convenience commands:
+
+#+findex: denote-link-after-creating
++ ~denote-link-after-creating~ :: Create new note in the background and
+  link to it directly.
+
+  Use ~denote~ interactively to produce the new note.  Its doc string or
+  this manual explains which prompts will be used and under what
+  conditions ([[#h:6a92a8b5-d766-42cc-8e5b-8dc255466a23][Standard note 
creation]]).
+
+  With optional =ID-ONLY= as a prefix argument (this is the =C-u= key,
+  by default) create a link that consists of just the identifier.  Else
+  try to also include the file's title.  This has the same meaning as in
+  ~denote-link~ ([[#h:5e5e3370-12ab-454f-ba09-88ff44214324][Adding a single 
link]]).
+
+  IMPORTANT NOTE: Normally, ~denote~ does not save the buffer it
+  produces for the new note.  This is a safety precaution to not write
+  to disk unless the user wants it (e.g. the user may choose to kill the
+  buffer, thus cancelling the creation of the note).  However, for this
+  command the creation of the note happens in the background and the
+  user may miss the step of saving their buffer.  We thus have to save
+  the buffer in order to (i) establish valid links, and (ii) retrieve
+  whatever front matter from the target file.
+
+#+findex: denote-link-or-create
++ ~denote-link-or-create~ :: Use ~denote-link~ on =TARGET= file,
+  creating it if necessary.
+
+  If =TARGET= file does not exist, call ~denote-link-after-creating~
+  which runs the ~denote~ command interactively to create the file.  The
+  established link will then be targeting that new file.
+
+  With optional =ID-ONLY= as a prefix argument create a link with just
+  the file's identifier.  This has the same meaning as in ~denote-link~.
+
+  This command has the alias ~denote-link-to-existing-or-new-note~,
+  which helps with discoverability.
+
 ** The backlinks' buffer
 :PROPERTIES:
 :CUSTOM_ID: h:c73f1f68-e214-49d5-b369-e694f6a5d708
@@ -1907,6 +1959,9 @@ Everything is in place to set up the package.
                  :immediate-finish nil
                  :kill-buffer t
                  :jump-to-captured t)))
+
+;; Also check the commands `denote-link-after-creating',
+;; `denote-link-or-create'.  You may want to bind them to keys as well.
 #+end_src
 
 * Contributing
@@ -2370,9 +2425,9 @@ Denote is meant to be a collective effort.  Every bit of 
help matters.
 
 + Ideas and/or user feedback :: Abin Simon, Alan Schmitt, Alfredo
   Borrás, Benjamin Kästner, Colin McLear, Damien Cassou, Frank Ehmsen,
-  Hanspeter Gisler, Jack Baty, Kaushal Modi, M. Hadi Timachi, Paul van
-  Gelder, Peter Prevos, Shreyas Ragavan, Summer Emacs, Sven Seebeck,
-  Taoufik, Ypot, atanasj, hpgisler, pRot0ta1p.
+  Hanspeter Gisler, Jack Baty, Juanjo Presa, Kaushal Modi, M. Hadi
+  Timachi, Paul van Gelder, Peter Prevos, Shreyas Ragavan, Summer Emacs,
+  Sven Seebeck, Taoufik, Ypot, atanasj, hpgisler, pRot0ta1p, sienic.
 
 Special thanks to Peter Povinec who helped refine the file-naming
 scheme, which is the cornerstone of this project.
diff --git a/denote.el b/denote.el
index e679ea84e3..89ad183d52 100644
--- a/denote.el
+++ b/denote.el
@@ -2070,6 +2070,53 @@ format is always [[denote:IDENTIFIER]]."
          (denote-link--find-file-prompt files))))
     (user-error "No links found in the current buffer")))
 
+;;;###autoload
+(defun denote-link-after-creating (&optional id-only)
+  "Create new note in the background and link to it directly.
+
+Use `denote' interactively to produce the new note.  Its doc
+string explains which prompts will be used and under what
+conditions.
+
+With optional ID-ONLY as a prefix argument create a link that
+consists of just the identifier.  Else try to also include the
+file's title.  This has the same meaning as in `denote-link'.
+
+IMPORTANT NOTE: Normally, `denote' does not save the buffer it
+produces for the new note.  This is a safety precaution to not
+write to disk unless the user wants it (e.g. the user may choose
+to kill the buffer, thus cancelling the creation of the note).
+However, for this command the creation of the note happens in the
+background and the user may miss the step of saving their buffer.
+We thus have to save the buffer in order to (i) establish valid
+links, and (ii) retrieve whatever front matter from the target
+file."
+  (interactive "P")
+  (let (path)
+    (save-window-excursion
+      (call-interactively #'denote)
+      (save-buffer)
+      (setq path (buffer-file-name)))
+    (denote-link path id-only)))
+
+;;;###autoload
+(defun denote-link-or-create (target &optional id-only)
+  "Use `denote-link' on TARGET file, creating it if necessary.
+
+If TARGET file does not exist, call `denote-link-after-creating'
+which runs the `denote' command interactively to create the file.
+The established link will then be targeting that new file.
+
+With optional ID-ONLY as a prefix argument create a link that
+consists of just the identifier.  Else try to also include the
+file's title.  This has the same meaning as in `denote-link'."
+  (interactive (list (denote--retrieve-read-file-prompt) current-prefix-arg))
+  (if (file-exists-p target)
+      (denote-link target id-only)
+    (call-interactively #'denote-link-after-creating)))
+
+(defalias 'denote-link-to-existing-or-new-note (symbol-function 
'denote-link-or-create))
+
 ;;;;; Link buttons
 
 ;; Evaluate: (info "(elisp) Button Properties")