[elpa] externals/denote 4d5063f68a: Update to version 0.3.0

[ELPA Syncer]

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

    Update to version 0.3.0
---
 CHANGELOG.org         | 197 ++++++++++++++++++++++++++++++++++++++++++++++++++
 README.org            |  18 ++---
 denote-dired.el       |   2 +-
 denote-faces.el       |   2 +-
 denote-link.el        |   2 +-
 denote-org-capture.el |   2 +-
 denote-retrieve.el    |   2 +-
 denote.el             |   2 +-
 8 files changed, 210 insertions(+), 17 deletions(-)

diff --git a/CHANGELOG.org b/CHANGELOG.org
index c5d66f638c..548518893f 100644
--- a/CHANGELOG.org
+++ b/CHANGELOG.org
@@ -9,6 +9,203 @@ project's main git repository: 
<https://git.sr.ht/~protesilaos/denote>.
 The newest release is at the top.  For further details, please consult
 the manual: <https://protesilaos.com/emacs/denote>.
 
+* Version 0.3.0 on 2022-07-11
+:PROPERTIES:
+:CUSTOM_ID: h:6864cfd4-d0be-4c89-b313-39ba6e892a03
+:END:
+
++ Fixed how references are analysed to produce the backlinks' buffer.
+  This should resolve the issue that some users faced where the
+  backlinks would not be produced.
+
+  The previous implementation would not yield the appropriate results if
+  (i) the value of the user option ~denote-directory~ was a "project"
+  per the built-in project.el and (ii) the link to the given entry was
+  from a subdirectory.  In short, the references were sometimes returned
+  as relative file paths, whereas they should always be absolute.
+  Thanks to Jean-Philippe Gagné Guay for the feedback in issue 42 over
+  at the GitHub mirror: <https://github.com/protesilaos/denote/pull/42>.
+
+  [ Jean-Philippe has assigned copyright to the Free Software
+    Foundation.  It is a prerequisite for contributing to core Emacs
+    and/or any package distributed via the official GNU ELPA. ]
+
++ Addressed a regression in the function ~denote-directory~ (this is the
+  function that normalises the variable of the same name) which
+  prevented it from returning an expanded file path.  This too
+  contributed to problems with the backlinking facility.  Thanks to
+  Jean-Philippe Gagné Guay for the contribution in pull request 44 over
+  at the GitHub mirror: <https://github.com/protesilaos/denote/pull/44>.
+
+  Also thanks to user pRot0ta1p for the relevant feedback in issue 43
+  (also on the mirror): <https://github.com/protesilaos/denote/issues/43>.
+  More thanks to Alfredo Borrás, Benjamin Kästner, and Sven Seebeck for
+  their comments in a related thread on the mailing list:
+  
<https://lists.sr.ht/~protesilaos/denote/%3CCA73E705-1194-4324-9962-70708C4C72E5%40zoho.eu%3E>.
+  These discussions showed we had a problem, which we managed to
+  identify.
+
++ Introduced the user option ~denote-prompts~ (read its doc string or
+  the relevant entry in the manual).  It governs how the standard
+  ~denote~ command for creating new notes will behave in interactive
+  usage.  By default, ~denote~ prompts for a title and keywords.  With
+  ~denote-prompts~, the command can also ask for a file type (per
+  ~denote-file-type~), subdirectory of the ~denote-directory~, and a
+  specific date+time.  Prompts occur in the order they are specified.
+  Furthermore, the ~denote-prompts~ can be set to values which do not
+  include the title and keywords.  This means that the resulting file
+  names can be any of those permutations:
+
+  : DATE.EXT
+  : DATE--TITLE.EXT
+  : DATE__KEYWORDS.EXT
+
+  Recall that Denote's standard file-naming scheme is defined as follows
+  (read the manual for the details):
+
+  : DATE--TITLE__KEYWORDS.EXT
+
+  For our purposes, Denote will work perfectly fine for linking and
+  backlinking, even if file names do not include the =TITLE= and
+  =KEYWORDS= fields.  However, the user is advised to consider the
+  implications on usability: notes without a descriptive title and/or
+  useful keywords may be hard to filter and practically impossible to
+  manage at scale.  File names without such information should at least
+  be added to subdirectories which themselves have a descriptive name.
+
+  At any rate, Denote does not have strong opinions about one's
+  workflow.  The standard file name is the culmination of years of
+  experience.
+
+  Consider the ~denote-prompts~ the affirmative answer to the question
+  "Can keywords be optional?" as posed by Jack Baty on the mailing list:
+  
<https://lists.sr.ht/~protesilaos/denote/%3C8D392BC3-980A-4E5B-9480-D6A00BE8279F%40baty.net%3E>.
+
+  Thanks to Jean-Philippe Gagné Guay for the original contribution in
+  commit 9b981a2.  It was originally part of a pull request, but due to
+  some internal changes I had to merge it as a patch and technically the
+  web UI did not count the PR as "merged" (though it was in terms of
+  substance).
+
++ Refactored the ~denote~ command to (i) accommodate the new user option
+  ~denote-prompts~ via its interactive specification and (ii) be more
+  flexible when called from Lisp.  The latter scenario is for advanced
+  users or, generally, those who can maintain some custom code in their
+  configuration.  A case in point is one of the examples we show in the
+  manual for a programmatic way to create notes that automatically get
+  the =journal= tag:
+
+  #+begin_src emacs-lisp
+  (defun my-denote-journal ()
+    "Create an entry tagged 'journal', while prompting for a title."
+    (interactive)
+    (denote
+     (denote--title-prompt)
+     '("journal")))
+  #+end_src
+
+  Notice that the ='("journal")= is a list of strings even for a single
+  keyword.  Whereas before a single one was a plain string.  This is a
+  breaking change.
+
+  Please consult the doc string of the ~denote~ command for the
+  technicalities.
+
++ Refashioned the interactive convenience functions of ~denote-type~,
+  ~denote-date~, ~denote-subdirectory~ to leverage the ~denote-prompts~
+  user option while calling ~denote~ interactively.  In practical terms,
+  they no longer accept any arguments when called from Lisp.  Users who
+  need a programmatic approach are advised to either call ~denote~
+  directly, or check how these commands ~let~ bind the ~denote-prompts~
+  to carry out their operations.  The doc string of each command
+  explains how it works.  Or evaluate this to check the manual:
+
+  #+begin_src emacs-lisp
+  (info "(denote) Convenience commands for note creation")
+  #+end_src
+
+  Else visit:
+  <https://protesilaos.com/emacs/denote#h:887bdced-9686-4e80-906f-789e407f2e8f>
+
++ Documented how the user option ~denote-directory~ can accept a local
+  value.  This is pertinent to scenaria where the user needs to maintain
+  separate directories of notes.  By "separate" we mean sets of notes
+  that do not communicate with each other, cannot create links between
+  them, etc.  The manual delves into the technicalities.  If you have
+  the Info entry installed, evaluate:
+
+  #+begin_src emacs-lisp
+  (info "(denote) Maintain separate directories for notes")
+  #+end_src
+
+  Else visit:
+  
<https://protesilaos.com/emacs/denote#h:15719799-a5ff-4e9a-9f10-4ca03ef8f6c5>.
+
+  Thanks to user "Summer Emacs" for starting the discussion on the
+  mailing list, and Benjamin Kästner for their participation:
+  <https://lists.sr.ht/~protesilaos/denote/%3Cm25yk5e856.fsf@gmail.com%3E>.
+
++ Added an entry to the manual's Frequently Asked Questions about a
+  failed search for backlinks.  It includes sample code that users of
+  Windows can apply, if necessary.  (The error is not Denote's fault.)
+  Thanks to Benjamin Kästner for the patch, which is below the ~15 line
+  threshold and thus does not require copyright assignment to the Free
+  Software Foundation:
+  
<https://lists.sr.ht/~protesilaos/denote/%3Cce117b14-55cf-622e-6cd8-0af698091ae3%40gmail.com%3E>.
+
++ Removed duplicate entries from the list of file paths that the =xref=
+  library returns for the purposes of backlinking.  Thanks to
+  Jean-Philippe Gagné Guay for the contribution in pull request 44 on
+  the GitHub mirror: <https://github.com/protesilaos/denote/issues/44>.
+
++ Applied an appropriate face to the backlinks' button to mitigate an
+  error.  Thanks to Jean-Philippe Gagné Guay for the contribution in
+  pull request 45 on the GitHub mirror and for later testing a
+  subsequent tweak: <https://github.com/protesilaos/denote/issues/45>.
+
++ Simplfied all the faces we define to make them work with all themes.
+  The previous colours were consistent with the =modus-themes=:
+  <https://protesilaos.com/emacs/modus-themes>.
+
++ Refined how strings are sluggified under all circumstances.  Before, a
+  nil value for the user option ~denote-allow-multi-word-keywords~ would
+  have the adverse effect of joining all the strings in the title field
+  of the file name.  The intent always was to do that only for
+  multi-word keywords, not the title.  This change was part of a hotfix,
+  formalised as version =0.2.1= a day after the release of =0.2.0=.
+
++ Made the fontification rules more robust, while avoiding any false
+  positives.  This was done over a series of commits as it had
+  implications for the file name permutations that were mentioned
+  earlier.  Thanks to Jean-Philippe Gagné Guay for the patches and/or
+  discussion about the merits of each change and concomitant
+  considerations:
+
+  - https://github.com/protesilaos/denote/pull/36
+  - https://github.com/protesilaos/denote/pull/38
+  - https://github.com/protesilaos/denote/pull/40
+  - https://github.com/protesilaos/denote/pull/42
+
++ Rewrote all relevant entries in the manual to reflect all the
+  user-facing aspects of the aforementioned.
+
++ Discussed a use-case of rewriting old journal entries as Denote-style
+  files.  As of this writing, we do not support migration of files in
+  bulk.  It might happen at some point, though it is no mean task.
+  Thanks to Summer Emacs and Alan Schmitt for their participation:
+  <https://lists.sr.ht/~protesilaos/denote/%3Cm27d4mbktj.fsf%40gmail.com%3E>.
+
+  An aside here as this topic was brought up: my packages are open to
+  users of all skill levels and is why I maintain a mailing list as well
+  as mirrors of the official git repository on SourceHut.  Do not
+  hesitate to ask a question.  If, for whatever reason, those
+  communication channels are not appropriate, you are welcome to contact
+  me in private: <https://protesilaos.com/contact>.
+
+Thanks again to Jean-Philippe Gagné Guay for the numerous contributions.
+Please read the commit log for the minutia, as this change log entry
+omitted some of the finer yet important details.
+
 * Version 0.2.0 on 2022-07-04
 :PROPERTIES:
 :CUSTOM_ID: h:2002fee6-3f0c-48be-9727-6d4e20f34856
diff --git a/README.org b/README.org
index f876bcca4f..3bf220c57b 100644
--- a/README.org
+++ b/README.org
@@ -4,9 +4,9 @@
 #+language:              en
 #+options:               ':t toc:nil author:t email:t num:t
 #+startup:               content
-#+macro:                 stable-version 0.2.0
-#+macro:                 release-date 2022-07-04
-#+macro:                 development-version 0.3.0-dev
+#+macro:                 stable-version 0.3.0
+#+macro:                 release-date 2022-07-11
+#+macro:                 development-version 0.4.0-dev
 #+export_file_name:      denote.texi
 #+texinfo_filename:      denote.info
 #+texinfo_dir_category:  Emacs misc features
@@ -166,8 +166,6 @@ When the user option ~denote-sort-keywords~ is non-nil (the 
default),
 keywords are sorted alphabetically (technically, the sorting is done
 with ~string-lessp~).
 
-[ The ~denote-prompts~ is part of {{{development-version}}} ]
-
 The interactive behaviour of the ~denote~ command is influenced by the
 user option ~denote-prompts~ ([[#h:f9204f1f-fcee-49b1-8081-16a08a338099][The 
denote-prompts option]]).
 
@@ -183,9 +181,6 @@ alias ~denote-create-note~.
 :CUSTOM_ID: h:f9204f1f-fcee-49b1-8081-16a08a338099
 :END:
 
-[ What is described in this section is part of
-  {{{development-version}}}. ]
-
 #+vindex: denote-prompts
 The user option ~denote-prompts~ determines how the ~denote~ command
 will behave interactively ([[#h:6a92a8b5-d766-42cc-8e5b-8dc255466a23][Standard 
note creation]]).
@@ -1804,9 +1799,10 @@ Denote is meant to be a collective effort.  Every bit of 
help matters.
   Cassou, Jack Baty, Jean-Philippe Gagné Guay, Kaushal Modi, Stefan
   Monnier.
 
-+ Ideas and/or user feedback :: Benjamin Kästner, Colin McLear, Damien
-  Cassou, Frank Ehmsen, Jack Baty, Kaushal Modi, M. Hadi Timachi, Peter
-  Prevos, Shreyas Ragavan, Sven Seebeck, Ypot, pRot0ta1p.
++ Ideas and/or user feedback :: Alan Schmitt, Alfredo Borrás, Benjamin
+  Kästner, Colin McLear, Damien Cassou, Frank Ehmsen, Jack Baty, Kaushal
+  Modi, M. Hadi Timachi, Peter Prevos, Shreyas Ragavan, Summer Emacs,
+  Sven Seebeck, Ypot, pRot0ta1p.
 
 Special thanks to Peter Povinec who helped refine the file-naming
 scheme, which is the cornerstone of this project.
diff --git a/denote-dired.el b/denote-dired.el
index 8e097404ca..886d067881 100644
--- a/denote-dired.el
+++ b/denote-dired.el
@@ -6,7 +6,7 @@
 ;; Maintainer: Denote Development <~protesilaos/denote@lists.sr.ht>
 ;; URL: https://git.sr.ht/~protesilaos/denote
 ;; Mailing-List: https://lists.sr.ht/~protesilaos/denote
-;; Version: 0.2.1
+;; Version: 0.3.0
 ;; Package-Requires: ((emacs "27.2"))
 
 ;; This file is NOT part of GNU Emacs.
diff --git a/denote-faces.el b/denote-faces.el
index 12e2220922..54d509bb94 100644
--- a/denote-faces.el
+++ b/denote-faces.el
@@ -6,7 +6,7 @@
 ;; Maintainer: Denote Development <~protesilaos/denote@lists.sr.ht>
 ;; URL: https://git.sr.ht/~protesilaos/denote
 ;; Mailing-List: https://lists.sr.ht/~protesilaos/denote
-;; Version: 0.2.1
+;; Version: 0.3.0
 ;; Package-Requires: ((emacs "27.2"))
 
 ;; This file is NOT part of GNU Emacs.
diff --git a/denote-link.el b/denote-link.el
index 6f7264e567..1b316b9bac 100644
--- a/denote-link.el
+++ b/denote-link.el
@@ -6,7 +6,7 @@
 ;; Maintainer: Denote Development <~protesilaos/denote@lists.sr.ht>
 ;; URL: https://git.sr.ht/~protesilaos/denote
 ;; Mailing-List: https://lists.sr.ht/~protesilaos/denote
-;; Version: 0.2.1
+;; Version: 0.3.0
 ;; Package-Requires: ((emacs "27.2"))
 
 ;; This file is NOT part of GNU Emacs.
diff --git a/denote-org-capture.el b/denote-org-capture.el
index f4ef6337f8..3f96d76aba 100644
--- a/denote-org-capture.el
+++ b/denote-org-capture.el
@@ -6,7 +6,7 @@
 ;; Maintainer: Denote Development <~protesilaos/denote@lists.sr.ht>
 ;; URL: https://git.sr.ht/~protesilaos/denote
 ;; Mailing-List: https://lists.sr.ht/~protesilaos/denote
-;; Version: 0.2.1
+;; Version: 0.3.0
 ;; Package-Requires: ((emacs "27.2"))
 
 ;; This file is NOT part of GNU Emacs.
diff --git a/denote-retrieve.el b/denote-retrieve.el
index c83785f5c0..56a5f30c57 100644
--- a/denote-retrieve.el
+++ b/denote-retrieve.el
@@ -6,7 +6,7 @@
 ;; Maintainer: Denote Development <~protesilaos/denote@lists.sr.ht>
 ;; URL: https://git.sr.ht/~protesilaos/denote
 ;; Mailing-List: https://lists.sr.ht/~protesilaos/denote
-;; Version: 0.2.1
+;; Version: 0.3.0
 ;; Package-Requires: ((emacs "27.2"))
 
 ;; This file is NOT part of GNU Emacs.
diff --git a/denote.el b/denote.el
index 27104c4b95..6f1b7045d8 100644
--- a/denote.el
+++ b/denote.el
@@ -6,7 +6,7 @@
 ;; Maintainer: Denote Development <~protesilaos/denote@lists.sr.ht>
 ;; URL: https://git.sr.ht/~protesilaos/denote
 ;; Mailing-List: https://lists.sr.ht/~protesilaos/denote
-;; Version: 0.2.1
+;; Version: 0.3.0
 ;; Package-Requires: ((emacs "27.2"))
 
 ;; This file is NOT part of GNU Emacs.