Emacs: denote version 1.1.0
Denote is a simple note-taking tool. It is based on the idea that notes should follow a predictable and descriptive file-naming scheme. The file name must offer a clear indication of what the note is about, without reference to any other metadata. Denote basically streamlines the creation of such files while providing facilities to link between them.
- Package name (GNU ELPA):
- Official manual: https://protesilaos.com/emacs/denote
- Change log: https://protesilaos.com/emacs/denote-changelog
- Git repo on SourceHut: https://git.sr.ht/~protesilaos/denote
- Mailing list: https://lists.sr.ht/~protesilaos/denote
- Video demo: https://protesilaos.com/codelog/2022-06-18-denote-demo/.
- Backronyms: Denote Everything Neatly; Omit The Excesses. Don’t Ever Note Only The Epiphenomenal.
Below are the release notes.
New commands or refinements to common use-cases
denote-link-add-missing-linksis a companion to what we already provide to produce a list of links to Denote files matching a regular expression (the
denote-link-add-links). This new command adds links that are not already present in the current file. So if you have a metanote that references, say, your journal entries but have not updated it in a month, you can revisit the metanote, invoke
denote-link-add-missing-links, and then type the search terms (e.g.
_journal) to include what remains.
Thanks to Elias Storms for the initial contribution, which was done in pull request 108 on the GitHub mirror: https://github.com/protesilaos/denote/pull/108.
Elias has assigned copyright to the Free Software Foundation. It is required for changes that exceed 15 lines in total.
denote-link-find-backlinkprovides a minibuffer interface that shows all backlinks to the current note. It complements the existing
denote-link-backlinkscommand (which also has the alias
denote-link-show-backlinks-buffer). Each command has its own niche: the minibuffer lets the user leverage powerful pattern matching styles, such as those provided by the
orderlesspackage, while the bespoke buffer provides an easy overview of what links to the current note.
Thanks to Elias Storms for the original patch: https://lists.sr.ht/~protesilaos/denote/%3Cm2fsg6o2t6.fsf%40MBA21.fritz.box%3E#%3Cm2pmfam7yi.fsf@MBA21.fritz.box%3E.
denote-keywords-removeare two commands that interactively operate on the current note’s front matter to add or remove keywords. They use the familiar keywords’ prompt which means, among others, that they can read more than one keyword at a time. To specify multiple keywords, separate each input with a comma (or whatever the value of
crm-separatoris, which should be a comma unless something out-of-the-ordinary is in force).
Thanks to Elias Storms for the original patch, which was done as part of a discussion on the mailing list and then iterated on: https://lists.sr.ht/~protesilaos/denote/%3Cm24jwvpbt2.fsf%40MBA21.fritz.box%3E#%3Cm28rlik0tc.fsf@MBA21.fritz.box%3E.
denote-linkcommand will now recognise an active region and use its text as the description of the inserted link. The default behaviour is to use the file’s title from its front matter or file name. Thanks to Charanjit Singh for the original contribution, which was done as part of pull request 109 on the GitHub mirror: https://github.com/protesilaos/denote/pull/109. A subsequent tweak was implemented in pull request 110, following a discussion with me: https://github.com/protesilaos/denote/pull/110.
Charanjit’s contribution is below the ~15 line threshold and thus does not require copyright assignment to the Free Software Foundation.
The renaming operations are now aware of the underlying version control system and will use the appropriate command when a VCS is available. In practice, renaming a file under, say, Git will register it as a “rename” instead of two separate actions of deletion and addition.
Thanks to Florian for the patch. It was discussed on the mailing list and then underwent some changes: https://lists.sr.ht/~protesilaos/denote/%3C166547153518.email@example.com%3E.
denote-rename-file-using-front-matterno longer fails to carry out its intended task when the front matter has no keywords. If no keywords are available, this is interpreted as a request to remove the KEYWORDS component of the file name. This was always technically possible and could be achieved with various permutations of the user option
denote-prompts(as explained in its doc string or the manual). Denote only needs an identifier in the file name to establish unique links (although I strongly encourage you to stick to the standard file-naming scheme as it is informative, reliable, and can work even if you access your data without Emacs).
For more advanced use-cases
denote-file-typeshas been tweaked to respond directly to changes in its value done with
setq. Thanks to Noboru Ota for the patch: https://lists.sr.ht/~protesilaos/denote/%3C86k05gsqsg.fsf%40nobiot.com%3E.
Noboru has assigned copyright to the Free Software Foundation.
:front-matterproperty of the
denote-file-typesnow accepts a nil value. Denote could always work without front matter, but this was not implemented flexibly in the
denote-file-types. Thanks to Noboru Ota (nobiot) for pointing this out on the mailing list: https://lists.sr.ht/~protesilaos/denote/%3C86k05gsqsg.fsf%40nobiot.com%3E.
denote-file-promptfunction now reads an optional
INITIAL-TEXTargument. This is a string that prepopulates the minibuffer. It is useful for custom commands the user may have where, for example, there is a need to automatically filter to entries matching
_journal. Thanks to Alan Schmitt for suggesting the idea: https://lists.sr.ht/~protesilaos/denote/%3C87pmf676n1.firstname.lastname@example.org%3E.
denote-rename-file-using-front-matteraccepts an optional
AUTO-CONFIRMargument. It can either be passed interactively or via Lisp. The doc string (or the manual) explains the details. Thanks to Elias Storms for the initial patch: https://lists.sr.ht/~protesilaos/denote/%3Cm2a667aeku.fsf%40gmail.com%3E.
denote-prompt-for-date-return-idfunction uses the familiar
denote-date-promptand returns the appropriate identifier. It is used internally by some of our function, but we also provide it for anyone who wants to write their own custom code.
denote-retrieve-or-create-file-identifierfunction reads and option
DATEargument to its mandatory
FILEdoes not have an identifier and optional
DATEis non-nil, the function invokes the
denote-prompt-for-date-return-id, as mentioned above.
denote-rename-filecommand accepts an optional
DATEargument. It functionally does what is described right above, with the exception that this is for an interactive function (a “command”). Read the detailed doc string or the manual for everything that pertains to this powerful command.
Thanks to Florian for suggesting the idea on the mailing list: https://lists.sr.ht/~protesilaos/denote/%3C166521684647.7.5483179875879361874.67576870%40aboulafia.org%3E.
denote-directory-text-only-filesfunction filters the
denote-directory-filesto only return a list of text files. This leaves out, say, mp3 files. The function is used internally, though it may also prove useful in custom user code.
revert-buffer-functionfor the backlinks’ buffer, which is produced by the command
denote-link-backlinks. This revert function is what the
gkey invokes with the default key bindings (the command is
revert-buffer). It produces the buffer anew, updating the list of backlinks accordingly.
Documented how to speed up the creation of the backlinks’ buffer. As this depends on the built-in
xreflibrary, the change is done by specifying the value of the user option
xref-search-programin Emacs 28 or higher. For example:
(setq xref-search-program 'ripgrep)
For something more elaborate:
;; Prefer ripgrep, then ugrep, and fall back to regular grep. (setq xref-search-program (cond ((or (executable-find "ripgrep") (executable-find "rg")) 'ripgrep) ((executable-find "ugrep") 'ugrep) (t 'grep)))
Removed some minor duplication of effort in how the buttonisation of links is done (what makes them clickable).
Made refinements to the definition of functions such as
denote-link-add-links. There should be no noticeable change for users, though this shows we care about code quality.
With Eshel Yaron, we tried to remove the empty indices for functions and variables from the HTML version of the manual. These indices are useful in the Info version, which can be accessed directly from Emacs when the
denotepackage is installed (for example, evaluate
(info "(denote) Top")), but they do not work with HTML. Alas, what we tried to do did not work. Maybe Org has a way to control what is exported where. We shall see. At any rate, thanks to Eshel for the effort: https://lists.sr.ht/~protesilaos/denote/patches/36028.
All code that integrates the
denote:custom hyperlink type with Org’s link facility is now assigned
autoloadcookies. These are done to ensure that
denoteis loaded and is available in cases where Org needs to access a
denote:link at some early stage (e.g. at startup before using Denote). Thanks to Sven Seebeck for reporting the problem: https://lists.sr.ht/~protesilaos/denote/%3C87r0zovwix.fsf%40svenseebeck.me%3E. Although Sven could not reproduce a bug reliably, I believe this prevents such an eventuality.
Expanded or otherwise updated the manual to account for all of the above, where appropriate.