emacs/protesilaos.denote
1
0
Fork 0
mirror of https://github.com/protesilaos/denote.git synced 2026-09-10 07:16:20 -04:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update to version 0.3.0

Browse source
This commit is contained in:
Protesilaos Stavrou 2022-07-11 19:33:11 +03:00
parent a40658ed13
commit 4d5063f68a
No known key found for this signature in database
GPG key ID: 99BD6459CD5CA3EA
8 changed files with 210 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

197
CHANGELOG.org
View file

@ -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

18
README.org
View file

@ -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.

2
denote-dired.el
View file

@ -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.

2
denote-faces.el
View file

@ -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.

2
denote-link.el
View file

@ -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.

2
denote-org-capture.el
View file

@ -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.

2
denote-retrieve.el
View file

@ -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.

2
denote.el
View file

@ -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.