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 Denote version 4.0.0

Browse source
This commit is contained in:
Protesilaos Stavrou 2025-04-15 17:32:11 +03:00
parent 23bb1ec373
commit c98c74ec74
No known key found for this signature in database
GPG key ID: 99BD6459CD5CA3EA
3 changed files with 629 additions and 96 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

593
CHANGELOG.org
View file

@ -13,6 +13,599 @@ the manual: <https://protesilaos.com/emacs/denote>.
#+toc: headlines 1 insert TOC here, with one headline level
* Version 4.0.0 on 2025-04-15
:PROPERTIES:
:CUSTOM_ID: h:8a134846-72cc-4fbf-830d-6ca9fd0f9ec8
:END:
This is a massive release. There is one breaking change, which should
be easy to adapt to: this pertains to the reorganisation of the
project to separate the "core" of Denote from its "extensions". The
core is the ~denote~ package. Each extension now has its own package
(details below).
Other than that, this version includes lots of new features for
searching and linking as well as quality-of-life refinements. We have
generalised the infrastructure for performing queries in the
~denote-directory~ and made the buffers with the search results more
useful.
Take your time to read through this publication. I am writing it for
you. Also remember that the most up-to-date resource for anything
related to Denote is its manual. You are always welcome to contact me:
<https://protesilaos.com/contact>. Or join the development on the Git
repository.
As usual, special thanks to Jean-Philippe Gagné Guay for making high
quality contributions to Denote since the beginning of the project ~3
years ago. Those will not always be headline features, but are
important improvements to the underlying code base.
I mention contributions from Jean-Philippe and others in its context.
Though I do not cover implementation details, otherwise this document
will be the size of a book. This does not mean that they are no
important though. Please consult the Git commit log for all the
technicalities.
** All the "extras" are in separate packages, including the Org dynamic blocks
:PROPERTIES:
:CUSTOM_ID: h:26ed2af1-60c8-4217-93b3-bbe344e4eb7b
:END:
In previous versions of Denote, we included some optional extensions
as part of the ~denote~ package. These included the files
=denote-org-extras.el= (Org dynamic blocks, among others),
=denote-journal-extras.el= (streamlined for journaling),
=denote-silo-extras.el= (working with multiple Denote silos).
The files =denote-md-extras.el= (Markdown extras) and
=denote-sequence.el= (sequence notes, including Luhmann-style
alphanumeric sequences) were also part of the project during the last
development cycle, though they never made it into a tagged release.
All these are now available as standalone packages on the official GNU
ELPA archive:
- ~denote-org~ :: In the Emacs configuration file, replace all
instances of =denote-org-extras= with =denote-org=.
- ~denote-journal~ :: Replace =denote-journal-extras= with =denote-journal=.
- ~denote-silo~ :: Replace =denote-silo-extras= with =denote-silo=.
- ~denote-markdown~ :: Replace =denote-md-extras= with =denote-markdown=.
- ~denote-sequence~ :: No changes to any of the defined symbols.
Simply get the new package.
I will document each of these packages further below. The plan, going
forward, is to maintain all the packages and coordinate their new
versions.
** More things in "core"
:PROPERTIES:
:CUSTOM_ID: h:3820e9cf-f034-4c3c-a4ed-1e7d11f1cd23
:END:
While the extras are moved out to their own code repositories, all
other features are merged into =denote.el=. Those include everything
that was in =denote-sort.el= and =denote-rename-buffer.el=.
- The "sort" mechanism is mostly for package developers. We use it
extensively in our Org dynamic blocks, which are now part of the
~denote-org~ package.
- The ~denote-dired~ command (alias ~denote-sort-dired~) is the only
user-facing "sort" command we have always provided. It produces a
fully fledged Dired buffer showing the results of the given search
for file names. The matching files are sorted according to the
user's expressed preference. The details are described in the
manual.
- The ~denote-rename-buffer-mode~ and all of its user options are
unchanged. This mode automatically renames the buffer of a given
Denote file so that it is easier to read it. Again, the manual
covers the technicalities.
Users do not need to make changes, unless they are explicitly loading
=denote-sort-dired= and =denote-rename-buffer=. In that case, they may
just remove those calls: only ~denote~ needs to be loaded.
** The ~denote-query-mode~
:PROPERTIES:
:CUSTOM_ID: h:36f305e2-310d-4327-941a-ca0570b473d2
:END:
Many of the features I will describe below produce search results via
the built-in Xref mechanism. Xref performs a search with a Grep or
Grep-like program, subject to the user option ~xref-search-program~.
The buffer those search results are displayed in runs the
~denote-query-mode~. It supersedes ~denote-backlinks-mode~.
The ~denote-query-mode~ supports the following:
- Results are shown in the context, with the exact match in highlight.
- Matches are grouped by file. Each file is a "heading".
- Headings can be folded with =TAB=, just how it is done in Org buffers.
- The results can be used for further queries. Type =C-h m=
(~describe-mode~) to learn about all the relevant commands.
We have had support for Xref since the original version of Denote. It
now is more generalised to cover backlinks, query links, and
~denote-grep~ (more below).
** Use query links for file contents or file names
:PROPERTIES:
:CUSTOM_ID: h:c217a37a-db73-46bd-ab5f-3f9c54f9d53b
:END:
Denote has always provided the option to link directly to a file with
a given name by referencing its identifier. This can be done with the
command ~denote-link~, among a few others like it (always consult the
manual of Denote).
In addition to these "direct links", we also support "query links".
Those do not point to a file but instead trigger a search. The results
are placed in a buffer that uses the appropriate major mode.
There are two types of query links:
- Query file contents :: Use the command ~denote-query-contents-link~
to insert a query link at point for "file contents". It perform a
search inside files in the ~denote-directory~ and put the results in
a ~denote-query-mode~ buffer.
- Query file names :: Use the ~denote-query-filenames-link~ to insert
a query link for "file names". It performs the query against file
names (not contents!) and puts the results in a ~dired~ buffer.
The display of the buffer with the query link results is controlled by
the user option ~denote-query-links-display-buffer-action~.
Query links are styled a little bit differently than direct links.
Compare the ~denote-faces-link~ with ~denote-faces-query-link~. Both
should look okay with most themes.
Denote query links are supported as part of the =denote:= hyperlink
type. They are available in all file types we define (per the user
option ~denote-file-type~) and should, in principle, work in any
custom file type (advanced users can check the variable ~denote-file-types~).
** Backlinks now always show their context
:PROPERTIES:
:CUSTOM_ID: h:8ebc6ae8-1087-46fa-a0ec-464749f0ac4d
:END:
In the past, the command ~denote-backlinks~ would produce a bespoke
buffer showing a list of file names that included links to the current
file (any file with the Denote file-naming scheme can have backlinks,
by the way, including PDFs, videos, etc.). This buffer did not provide
any additional functionality. We used to support the option to show
results in their context via ~denote-backlinks-show-context~. Those
would be rendered in a standard Xref buffer.
The contextual results are now the default and sole option. This is
because we have expanded the functionality of those buffers to use the
~denote-query-mode~, as explained above. Plus, it makes our code base
simpler.
Users will notice how backlikns look just like a query link for file
contents. This is because backlinks are the original query links since
day one of Denote.
** Direct links to a file with matching contents
:PROPERTIES:
:CUSTOM_ID: h:a1a7b766-328d-4883-93b2-c68b49bd1aa3
:END:
The command ~denote-link-to-file-with-contents~ allows users to
produce a direct link to a file whose contents (not file name!)
includes the given query.
Similarly, the command ~denote-link-to-all-files-with-contents~
generates a typographic list (bullet list) to all files whose contents
match the given query.
The manual covers all linking commands in depth.
** The essence of ~denote-search~ is part of ~denote~
:PROPERTIES:
:CUSTOM_ID: h:5d2ac378-304c-4ea8-bbfb-b3f7b649b27d
:END:
The ~denote-search~ package by Lucas Quintana uses the infrastructure
of Denote to perform searches in file contents. We now provide its
feature set as part of core ~denote~.
We decided to do this since query links already introduced all of the
requisite generalisations to ~denote-query-mode~.
Users can rely on the commands ~denote-grep~, ~denote-grep-marked-dired-files~,
and ~denote-grep-files-referenced-in-region~.
The placement of these buffers is subject to the user option
~denote-grep-display-buffer-action~.
This functionality was introduced in two pull requests by Lucas
Quintana, 571 and 573, with further changes by me:
- <https://github.com/protesilaos/denote/pull/571>.
- <https://github.com/protesilaos/denote/pull/573>.
Lucas has assigned copyright to the Free Software Foundation.
I think this was a much-needed addition to the core of Denote. It
complements ~denote-dired~ and query links.
** Formatting of links with ~denote-link-description-format~
:PROPERTIES:
:CUSTOM_ID: h:635b7f04-891a-4a8b-b420-4e0d9dadc232
:END:
The old user option ~denote-link-description-function~ is deprecated
and superseded by the new ~denote-link-description-format~. The new
user option still accepts a custom function as its value, so the old
behaviour should be retained.
What the new ~denote-link-description-format~ supports is an easier
way to customise the description of a link by using format specifiers
for common options. For example, users who only want to see the title
of the linked file can do this:
#+begin_src emacs-lisp
(setq denote-link-description-format "%t")
#+end_src
The documentation of this user option covers all the format specifiers
and further details.
** Miscellaneous changes for all users
:PROPERTIES:
:CUSTOM_ID: h:76a56ab5-c44b-4c67-8048-25dd0dd88dcf
:END:
- The command ~denote-add-front-matter~ is superseded by
~denote-rename-file~ and related. Those renaming commands will add
missing front matter or rewrite the modified lines of existing front
matter. This is due to refinements made by Jean-Philippe Gagné Guay
to the file renaming mechanism. We discussed this deprecation in
issue 498: <https://github.com/protesilaos/denote/issues/498>. Also
thanks to Samuel Flint for reporting an earlier problem with file
name signatures: <https://github.com/protesilaos/denote/issues/492>.
- The user option ~denote-open-link-function~ specifies the function
used by Denote to open the file of a direct link.
- The user option ~denote-org-store-link-to-heading~ can now be set to
form generic context links without a =PROPERTIES= drawer and
corresponding =CUSTOM_ID=. Set the value of this variable to
='context=. Read its documentation for further details.
- Also about ~denote-org-store-link-to-heading~, we have changed its
default value to ~nil~, which is what we were doing for most of
Denote's history. This means that, by default, ~org-store-link~ and
anything building on top of it will create a link only to the
current Denote file, like =denote:IDENTIFIER=, but not to the
current heading within that file. To create links to the
file+heading, set the value of this variable to ='id=.
- The command ~denote-dired-link-marked-notes~ is an alias for
~denote-link-dired-marked-notes~.
- The user option ~denote-sort-dired-extra-prompts~ control what
~denote-dired~ (alias ~denote-sort-dired~) prompts for. It accepts
either a nil value or a list of symbols among ~sort-by-component~,
~reverse-sort~, and ~exclude-regexp~. The order those symbols appear
in the list is significant, with the leftmost coming first.
- There is a new ~denote-sort-identifier-comparison-function~ variable
which determines how identifier-based sorting should be done by
default. It complements the existing ~denote-sort-title-comparison-function~,
~denote-sort-keywords-comparison-function~, ~denote-sort-signature-comparison-function~.
Thanks to Maikol Solís for the contribution in pull request 517:
<https://github.com/protesilaos/denote/pull/517>. The change is
small, meaning that Maikol does not need to assign copyright to the
Free Software Foundation (though I believe the paperwork is done, anyway).
- Lots of refinements to the doc strings of individual variables
and/or functions as well as the manual.
- Lots of other contributions to discussions and questions on the Git
repository. Granted, these are not "changes" per se but are part of
the development effort nonetheless.
- Made ~denote-get-path-by-id~ use ~denote-get-file-extension-sans-encryption~
instead of ~denote-get-file-extension~. This fixes a bug where the
extension is duplicated if it has an encryption component. Thanks to
eum3l for the patch in pull request 562: <https://github.com/protesilaos/denote/pull/562>.
The change is small, meaning that the author does not need to assign
copyright to the Free Software Foundation.
- Same as above for ~denote--rename-file~, which was done in pull
request 557: <https://github.com/protesilaos/denote/pull/557>.
** For developers or advanced users
:PROPERTIES:
:CUSTOM_ID: h:7eaf43a6-7d62-440e-bf7c-8d9536c7d36e
:END:
The following have been added or modified.
+ NEW Function ~denote-file-has-denoted-filename-p~ :: Return non-nil
if =FILE= respects the file-naming scheme of Denote. This tests the
rules of Denote's file-naming scheme. Sluggification is ignored. It
is done by removing all file name components and validating what
remains. Thanks to Jean-Philippe Gagné Guay for the pull request
515: <https://github.com/protesilaos/denote/pull/515>.
+ NEW Functions ~denote-infer-keywords-from-files~ :: Return list of
keywords in ~denote-directory-files~. With optional
=FILES-MATCHING-REGEXP=, only extract keywords from the matching
files. Otherwise, do it for all files. Keep any duplicates. Users
who do not want duplicates should refer to the functions
~denote-keywords~.
+ MODIFIED Function ~denote-keywords~ :: Returns an appropriate list
of keyword candidates, while accounting for the value of the user
option ~denote-infer-keywords~. It now also accepts the optional
=FILES-MATCHING-REGEXP= parameter.
+ MODIFIED Function ~denote-directory-files~ :: Returns a list of
absolute file paths in variable ~denote-directory~. It now accepts
the optional =EXCLUDE-REGEXP= parameter.
+ MODIFIED Function ~denote-format-file-name~ :: Formats a file name.
The way it treats its =ID= parameter has changed. Please read its
doc string. Thanks to Jean-Philippe Gagné Guay for the pull request
496: <https://github.com/protesilaos/denote/pull/496>.
+ ALIAS Function ~denote-retrieve-filename-keywords-as-list~ :: This
is a name that is easier to discover than ~denote-extract-keywords-from-path~,
because of the many other functions with the =denote-retrieve-*= prefix.
+ MODIFIED Function ~denote-retrieve-filename-identifier~ :: Extracts
the identifier from =FILE= name, if present, else returns nil. To
create a new one from a date, refer to the ~denote-get-identifier~
function. Thanks to Jean-Philippe Gagné Guay for the pull request
476: <https://github.com/protesilaos/denote/pull/476>.
+ MODIFIED Function ~denote-get-identifier~ :: Converts =DATE= into a
Denote identifier using ~denote-id-format~. If =DATE= is nil, it
returns an empty string as the identifier. Also by Jean-Philippe in
pull request 476 mentioned right above.
+ MODIFIED Function ~denote-date-prompt~ :: Prompts for a date,
expecting =YYYY-MM-DD= or that plus =HH:MM= (or even =HH:MM:SS=).
Can also use Org's more advanced date selection utility if the user
option ~denote-date-prompt-use-org-read-date~ is non-nil. It now has
the optional parameters =INITIAL-DATE= and =PROMPT-TEXT=. Thanks to
Jean-Philippe Gagné Guay for the pull request 576:
<https://github.com/protesilaos/denote/pull/576>.
- NEW Function ~denote-retrieve-groups-xref-query~ :: Accesses the
location of xrefs for =QUERY= and group them per file. Limit the
search to text files.
- NEW Function ~denote-retrieve-files-xref-query~ :: Returns sorted,
deduplicated file names with matches for =QUERY= in their contents.
Limits the search to text files.
- NEW Function ~denote-retrieve-xref-alist~ :: Returns xref alist of
files with the location of matches for =QUERY=. With optional
=FILES-MATCHING-REGEXP=, it limits the list of files accordingly
(per ~denote-directory-files~). At all times, it limits the search
to text files.
+ NEW Function ~denote-prepend-front-matter~ :: Prepend front matter
to =FILE=. The =TITLE=, =KEYWORDS=, =DATE=, =ID=, =SIGNATURE=, and
=FILE-TYPE= are passed from the renaming command and are used to
construct a new front matter block if appropriate.
+ MODIFIED Function ~denote-rewrite-front-matter~ :: Rewrites front
matter of note after ~denote-rename-file~ (or related). The =FILE=,
=TITLE=, =KEYWORDS=, =SIGNATURE=, =DATE=, =IDENTIFIER=, and
=FILE-TYPE= arguments are given by the renaming command and are used
to construct new front matter values if appropriate. If
~denote-rename-confirmations~ contains ~rewrite-front-matter~,
prompt to confirm the rewriting of the front matter. Otherwise
produce a ~y-or-n-p~ prompt to that effect. Thanks to
Jean-Philippe Gagné Guay for the pull request 558:
<https://github.com/protesilaos/denote/pull/558>.
** Denote "extensions" that are not in the ~denote~ package anymore
:PROPERTIES:
:CUSTOM_ID: h:40e030cd-f462-44ce-add9-ab1525359ae6
:END:
*** ~denote-journal~ integrates nicely with =M-x calendar=
:PROPERTIES:
:CUSTOM_ID: h:f8ab710d-852f-4d8b-b0f8-9a24c5c83808
:END:
The ~calendar~ can now highlight days that have journal entry. It may
also be used as a date picker to view or write a journal entry for
that day.
- Thanks to Alan Schmitt for reporting an issue with the calendar
integration during development:
<https://github.com/protesilaos/denote-journal/issues/8>.
- Thanks to Vineet C. Kulkarni for tweaking the identification of the
journal keyword to be more robust:
<https://github.com/protesilaos/denote-journal/pull/4>.
- Thanks to Honza Pokorny for fixing two small issues with the path
expansion:
- <https://github.com/protesilaos/denote-journal/pull/5>
- <https://github.com/protesilaos/denote-journal/pull/7>
Other than that, the package is providing the same functionality as
the discontinued =denote-journal-extras.el=.
- Manual: <https://protesilaos.com/emacs/denote-journal>.
- GitHub: <https://github.com/protesilaos/denote-journal>.
*** ~denote-org~ is almost the same as the discontinued =denote-org-extras.el=
:PROPERTIES:
:CUSTOM_ID: h:db491fe0-0c96-4c2e-9320-dc2697106e12
:END:
The only addition to dynamic blocks the optional =:not-regexp= parameter.
This is a regular expression that can further filter the results of a
search, such that the matching items are removed from the output.
The official manual of ~denote-org~ covers the technicalities.
- Manual: <https://protesilaos.com/emacs/denote-org>.
- GitHub: <https://github.com/protesilaos/denote-org>.
Also thanks to Elias Storms for fixing a small issue with the "missing
links" Org dynamic block, in pull request 486: <https://github.com/protesilaos/denote/pull/486>
*** ~denote-silo~ is the same as the discontinued =denote-silo-extras.el=
:PROPERTIES:
:CUSTOM_ID: h:ed7c77f5-9b44-4e76-9ada-80ff0ed6d5f6
:END:
I have only made small tweaks to it, but nothing that changes the user
experience.
+ Manual: <https://protesilaos.com/emacs/denote-silo>
+ GitHub: <https://github.com/protesilaos/denote-silo>
*** ~denote-markdown~ for some Markdown-specific extras
:PROPERTIES:
:CUSTOM_ID: h:e01d236c-fb50-488f-9fb2-15e866fa122a
:END:
This package provides some convenience functions to better integrate
Markdown with Denote. This is mostly about converting links from one
type to another so that they can work in different applications
(because Markdown does not have a standardised way to define custom
link types). It also defines an "Obsidian" file type which does not
have any front matter but only uses a level 1 heading for the title of
the note.
The code of ~denote-markdown~ used to be bundled up with the ~denote~
package before version =4.0.0= of the latter and was available in the
file =denote-md-extras.el=. Users of the old code will need to adapt
their setup to use the ~denote-markdown~ package. This can be done by
replacing all instances of =denote-md-extras= with =denote-markdown=
across their configuration.
+ Manual: <https://protesilaos.com/emacs/denote-markdown>
+ GitHub: <https://github.com/protesilaos/denote-markdown>
*** Write sequence notes (or "folgezettel") with ~denote-sequence~
:PROPERTIES:
:CUSTOM_ID: h:6181df9e-790f-4fcf-8093-cefbba324cb5
:END:
Users who want their notes to have an inherent structure can use
~denote-sequence~. The idea is to have thoughts that naturally form
sequences and are named accordingly. The sequence scheme is either
numeric or alphanumeric. The manual of the package explains all the
details.
+ Manual: <https://protesilaos.com/emacs/denote-sequence>
+ GitHub: <https://github.com/protesilaos/denote-sequence>
I had a lot of fun developing this comprehensive package during the
winter holidays.
Thanks to Claudio Migliorelli, Kierin Bell, Mirko Hernandez for
helping me fix some issues during development:
- <https://github.com/protesilaos/denote/pull/518>.
- <https://github.com/protesilaos/denote/pull/528>.
- <https://github.com/protesilaos/denote/pull/540>.
- <https://github.com/protesilaos/denote/pull/541>.
- <https://github.com/protesilaos/denote-sequence/issues/2>.
** The ~consult-denote~ also gets a small update
:PROPERTIES:
:CUSTOM_ID: h:90a9287d-a7dd-4d65-9214-4be6ebdf5943
:END:
This has always been a standalone package. I made the function
~consult-denote-file-prompt~ read the special-purpose variable
~denote-file-prompt-use-files-matching-regexp~. This is related to
commit =e0f1d47= in denote.git, about issue 536 as reported by Alan
Schmitt: <https://github.com/protesilaos/denote/issues/536>. The
variable =denote-file-prompt-use-files-matching-regexp= is meant to be
~let~ bound and is for advanced users or developers.
** Feature freeze at least until the end of April 2025
:PROPERTIES:
:CUSTOM_ID: h:8624e698-90cd-429e-a072-b0fa2df76662
:END:
I will not develop new features or accept pull request for a couple of
weeks. The idea is to focus on fixing any bug reports. We can then
publish point releases quickly.
New features can be included after we are confident that the packages
we have are okay.
** Git commits
:PROPERTIES:
:CUSTOM_ID: h:5191b423-6dc5-4ca7-9bcc-39797be5707c
:END:
This is just an overview of the Git commits, though remember that
there is more that goes into a project, such as the reporting of
inconsistencies, discussion of new ideas, et cetera. Thanks to
everybody involved! Plus, some commits are large while others are
tiny.
#+begin_src
~/Git/Projects/denote $ git shortlog 3.1.0..4.0.0 --summary --numbered
470 Protesilaos Stavrou
90 Jean-Philippe Gagné Guay
6 Kierin Bell
4 Alan Schmitt
3 eum3l
2 Claudio Migliorelli
2 Lucas Quintana
2 grtcdr
1 Elias Storms
1 Laurent Gatto
1 Maikol Solís
1 Octavian
1 TomoeMami
#+end_src
The following are not accurate because they only reflect the changes
after the reorganisation I made. But we have to start from somewhere.
#+begin_src
~/Git/Projects/denote-journal $ git shortlog --summary --numbered
54 Protesilaos Stavrou
2 Honza Pokorny
1 Vineet C. Kulkarni
#+end_src
#+begin_src
~/Git/Projects/denote-sequence $ git shortlog --summary --numbered
22 Protesilaos Stavrou
#+end_src
#+begin_src
~/Git/Projects/denote-silo $ git shortlog --summary --numbered
17 Protesilaos Stavrou
#+end_src
#+begin_src
~/Git/Projects/denote-org $ git shortlog --summary --numbered
15 Protesilaos Stavrou
#+end_src
#+begin_src
~/Git/Projects/denote-markdown $ git shortlog --summary --numbered
11 Protesilaos Stavrou
#+end_src
* Version 3.1.0 on 2024-09-04
:PROPERTIES:
:CUSTOM_ID: h:f089ab11-4ad7-4fd9-9bf3-2deb2e070297

126
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 3.1.0
#+macro: release-date 2024-09-04
#+macro: development-version 4.0.0-dev
#+macro: stable-version 4.0.0
#+macro: release-date 2025-04-15
#+macro: development-version 4.1.0-dev
#+export_file_name: denote.texi
#+texinfo_filename: denote.info
#+texinfo_dir_category: Emacs misc features
@ -355,9 +355,6 @@ called from Lisp, it returns the path it generates. Before returning
the path, it decides what to do with the buffer of the note, in
accordance with the user option ~denote-kill-buffers~ ([[#h:c8fd826f-3ac9-4820-9709-4375603f8865][The ~denote-kill-buffers~ option]]).
[ As part of {{{development-version}}}, the ~denote~ command runs the
hook and then kills the buffer, whereas it was the other way around before. ]
The file type of the new note is determined by the user option
~denote-file-type~ ([[#h:13218826-56a5-482a-9b91-5b6de4f14261][Front matter]]).
@ -2569,19 +2566,16 @@ we shall act accordingly.
:CUSTOM_ID: h:54b48277-e0e5-4188-ad54-ef3db3b7e772
:END:
As part of version 3.2.0 (currently {{{development-version}}}), the
command ~denote-add-front-matter~ is superseded by
~denote-rename-file~ and related ([[#h:532e8e2a-9b7d-41c0-8f4b-3c5cbb7d4dca][Renaming files]]). Those commands will
add missing front matter or rewrite the modified lines of existing
front matter.
As part of version 4.0.0, the command ~denote-add-front-matter~ is
superseded by ~denote-rename-file~ and related ([[#h:532e8e2a-9b7d-41c0-8f4b-3c5cbb7d4dca][Renaming files]]). Those
commands will add missing front matter or rewrite the modified lines
of existing front matter.
* Linking notes
:PROPERTIES:
:CUSTOM_ID: h:fc913d54-26c8-4c41-be86-999839e8ad31
:END:
[ Support for query links is part of {{{development-version}}}. ]
Denote offers several commands for linking between notes. Those use
the =denote:= hyperlink type. There are two types of links supported
by Denote:
@ -2659,8 +2653,6 @@ exactly like an ordinary link by default.
:CUSTOM_ID: h:25a983ca-049e-43d4-8f6e-06a2325e2c3c
:END:
[ The ~denote-link-to-file-with-contents~ is part of {{{development-version}}}. ]
#+findex: denote-link-to-file-with-contents
The ~denote-link~ command that we covered before prompts to select a
file among those in the ~denote-directory~ ([[#h:5e5e3370-12ab-454f-ba09-88ff44214324][Adding a single direct link using a file name prompt]]).
@ -2685,8 +2677,6 @@ The command ~denote-link-to-file-with-contents~ is the counterpart of
:CUSTOM_ID: h:d9a84289-2f73-4ef9-b4f0-9a0aa3e9bf0d
:END:
[ Query links are part of {{{development-version}}}. ]
As noted in the introduction to this section of the manual, the
=denote:= hyperlink type supports query links ([[#h:fc913d54-26c8-4c41-be86-999839e8ad31][Linking notes]]). Unlike
direct links, they do not point to any given file. Instead, they
@ -2796,8 +2786,6 @@ purposes ([[#h:fc913d54-26c8-4c41-be86-999839e8ad31][Linking notes]]).
:CUSTOM_ID: h:299d3aeb-9946-489e-bd91-e06f8c4ae2a9
:END:
[ The command ~denote-link-to-all-files-with-contents~ is part of {{{development-version}}}. ]
#+findex: denote-link-to-all-files-with-contents
The aforementioned ~denote-add-links~ command takes a query that
matches it against file names ([[#h:9bec2c83-36ca-4951-aefc-7187c5463f90][Insert links to all files matching a query in their file name]]).
@ -2814,8 +2802,6 @@ counterpart of ~denote-link-to-file-with-contents~ ([[#h:25a983ca-049e-43d4-8f6e
:CUSTOM_ID: h:6aa22a2d-3338-433e-ab9f-ba272417aab9
:END:
[ This is part of {{{development-version}}}. ]
#+vindex: denote-open-link-function
The user option ~denote-open-link-function~ specifies the function
used by Denote to open the file of a link. The default value opens the
@ -2832,10 +2818,6 @@ the command ~org-open-at-point~).
:CUSTOM_ID: h:d99de1fb-b1b7-4a74-8667-575636a4d6a4
:END:
[ Revised to also support context links that do not use a =PROPERTIES=
drawer but which are easier to break. This is done as part of
{{{development-version}}}. Also revised to have a nil value by default. ]
#+vindex: denote-org-store-link-to-heading
The user option ~denote-org-store-link-to-heading~ determines whether
~org-store-link~ links to the current Org heading.
@ -2931,9 +2913,7 @@ As always, links are created only for files which qualify as a "note"
for our purposes ([[#h:fc913d54-26c8-4c41-be86-999839e8ad31][Linking notes]]).
#+findex: denote-dired-link-marked-notes
The ~denote-dired-link-marked-notes~ is an alias for
~denote-link-dired-marked-notes~. [ The alias is part of
{{{development-version}}}. ]
The ~denote-dired-link-marked-notes~ is an alias for ~denote-link-dired-marked-notes~.
** Link to an existing note or create a new one
:PROPERTIES:
@ -3012,10 +2992,9 @@ creating a new one ([[#h:ad91ca39-cf10-4e16-b224-fdf78f093883][Open an existing
:END:
[ Older versions of Denote had two types of formatting for the
backlinks' buffer. As part of version =4.0.0= ({{{development-version}}}),
we only support the standard Xref view which shows matches in their
context. The user option ~denote-backlinks-show-context~ is thus
removed. ]
backlinks' buffer. As part of version =4.0.0=, we only support the
standard Xref view which shows matches in their context. The user
option ~denote-backlinks-show-context~ is thus removed. ]
#+findex: denote-backlinks
#+findex: denote-show-backlinks-buffer
@ -3168,12 +3147,6 @@ function ~denote-link-markdown-follow~ for the implementation details.
:CUSTOM_ID: h:f634427c-b451-40e2-993e-e00ac627af68
:END:
[ As part of {{{development-version}}}, the old user option
~denote-link-description-function~ is deprecated and superseded by
the new ~denote-link-description-format~. The new user option still
accepts a custom function as its value, so the old behaviour should
be retained. ]
The user option ~denote-link-description-format~ controls how the
command ~denote-link~ and related functions create a link description
by default.
@ -3191,11 +3164,10 @@ If the value is a string, it treats specially the following specifiers:
- The =%T= is the Denote =TITLE= in the file name.
- The =%i= is the Denote =IDENTIFIER= of the file.
- The =%I= is the identifier converted to =DAYNAME, DAYNUM MONTHNUM
YEAR=. [ The =%I= is part of {{{development-version}}}. ]
YEAR=.
- The =%d= is the same as =%i= (=DATE= mnemonic).
- The =%D= is a "do what I mean" which behaves the same as =%t= and if
that returns nothing, it falls back to =%I=, then =%i=. [ The =%D=
is part of {{{development-version}}}. ]
that returns nothing, it falls back to =%I=, then =%i=.
- The =%d= is the same as =%i= (=DATE= mnemonic).
- The =%s= is the Denote =SIGNATURE= of the file.
- The =%k= is the Denote =KEYWORDS= of the file.
@ -3329,9 +3301,6 @@ its standand attachments' facility).
:CUSTOM_ID: h:3ca4db16-8f26-4d7d-b748-bac48ae32d69
:END:
[ As part of {{{development-version}}}, the code of =denote-rename-buffer.el=
is now part of =denote.el= as part of a wider reorganisation of the project. ]
#+findex: denote-rename-buffer-mode
The minor mode ~denote-rename-buffer-mode~ provides the means to
automatically rename the buffer of a Denote file upon visiting the
@ -3363,9 +3332,6 @@ available to all programs.
:CUSTOM_ID: h:35507c18-35b1-41b9-9d80-52f54fcef3cb
:END:
[ Updated as part of {{{development-version}}} to use a default "do
what I mean" value. ]
The user option ~denote-rename-buffer-format~ controls how the
function ~denote-rename-buffer~ chooses the name of the
buffer-to-be-renamed.
@ -3375,15 +3341,13 @@ are placeholders for Denote file name components ([[#h:4e9c7512-84dc-4dfb-9fa9-e
#+vindex: denote-rename-buffer-backlinks-indicator
- The =%t= is the Denote =TITLE= in the front matter or the file name.
- The =%T= is the Denote =TITLE= in the file name. [ The =%T= is part
of {{{development-version}}}. ]
- The =%T= is the Denote =TITLE= in the file name.
- The =%i= is the Denote =IDENTIFIER= of the file.
- The =%I= is the identifier converted to =DAYNAME, DAYNUM MONTHNUM
YEAR=. [ The =%I= is part of {{{development-version}}}. ]
YEAR=.
- The =%d= is the same as =%i= (=DATE= mnemonic).
- The =%D= is a "do what I mean" which behaves the same as =%t= and if
that returns nothing, it falls back to =%I=, then =%i=. [ The =%D=
is part of {{{development-version}}}. ]
that returns nothing, it falls back to =%I=, then =%i=.
- The =%s= is the Denote =SIGNATURE= of the file.
- The =%k= is the Denote =KEYWORDS= of the file.
- The =%b= is an indicator of whether or not the file has backlinks
@ -3440,10 +3404,6 @@ own function and assigning it to the ~denote-rename-buffer-function~.
:CUSTOM_ID: h:8b542c50-dcc9-4bca-8037-a36599b22779
:END:
[ The ~denote-org~ package is developed in tandem with ~denote~
{{{development-version}}} and will be available when the new Denote
version is published. ]
This section is about the external package ~denote-org~ (by
Protesilaos). The code of ~denote-org~ used to be available as part of
the main ~denote~ package, but we decided to keep each optional
@ -3468,10 +3428,6 @@ reflect on the status of earlier notes ([[#h:6060a7e6-f179-4d42-a9de-a9968aaebec
:CUSTOM_ID: h:9fe01e63-f34f-4479-8713-f162a5ca865e
:END:
[ With {{{development-version}}}, the code of =denote-sort.el= is
merged into =denote.el= as part of a wider reorganisation of the
project. ]
The =denote.el= file contains functions which empower user or
developers to sort files by the given file name component ([[#h:4e9c7512-84dc-4dfb-9fa9-e15d51178e5d][The file-naming scheme]]).
@ -3522,8 +3478,7 @@ Users can configure the latter two by modifying the user option
The ~denote-sort-dired-extra-prompts~ accepts either a nil value or a
list of symbols among ~sort-by-component~, ~reverse-sort~, and
~exclude-regexp~. The order those symbols appear in the list is
significant, with the leftmost coming first. [ The ~exclude-regexp~
feature is part of {{{development-version}}}. ]
significant, with the leftmost coming first.
These symbols correspond to the following:
@ -3572,8 +3527,7 @@ function that is specific to each component ([[#h:a34228cb-484f-48fe-9cbc-8e41f3
These are subject to user configuration:
#+vindex: denote-sort-identifier-comparison-function
- ~denote-sort-identifier-comparison-function~ [ This one was missing
is older versions and is now added as part of {{{development-version}}}. ]
- ~denote-sort-identifier-comparison-function~
#+vindex: denote-sort-title-comparison-function
- ~denote-sort-title-comparison-function~
@ -3648,8 +3602,6 @@ Perform the comparison with `string<'."
:CUSTOM_ID: h:e71c9d14-7e88-4386-91d0-9ad249947077
:END:
[ The ~denote-grep~ command and everything related to it is part of {{{development-version}}}. ]
#+findex: denote-grep
The command ~denote-grep~ searches for the given query across all
readable files in the ~denote-directory~. It puts the collected
@ -3685,8 +3637,6 @@ the same window where the command ~denote-grep~ is called from.
:CUSTOM_ID: h:435592bc-e896-429f-a599-9f1bcd5ab9b8
:END:
[ Part of {{{development-version}}}. ]
Denote commands, such as ~denote-grep~, ~denote-backlinks~, and
~denote-query-contents-link~, produce an Xref buffer with search
results ([[#h:893eec49-d7be-4603-bcff-fcc247244011][Speed up backlinks' or query links' buffer creation?]]).
@ -3904,9 +3854,9 @@ across their configuration.
:CUSTOM_ID: h:c905b733-e959-4aa4-8f2c-0ed9eba459df
:END:
[ As part of version =4.0.0= ({{{development-version}}}), Denote comes
with the ~denote-grep~ command and related functionality ([[#h:e71c9d14-7e88-4386-91d0-9ad249947077][Use ~denote-grep~ to search inside files]]).
The core of this feature set was written by Lucas Quintana. ]
[ As part of version =4.0.0=, Denote comes with the ~denote-grep~
command and related functionality ([[#h:e71c9d14-7e88-4386-91d0-9ad249947077][Use ~denote-grep~ to search inside files]]).
The core of this feature set was written by Lucas Quintana. ]
The ~denote-search~ package by Lucas Quintana provides a search
utility for Denote: <https://github.com/lmq-10/denote-search>.
@ -4962,7 +4912,7 @@ The following sections cover the specifics.
=FILE= respects the file-naming scheme of Denote. This tests the
rules of Denote's file-naming scheme. Sluggification is ignored. It
is done by removing all file name components and validating what
remains. [ This function is part of {{{development-version}}}. ]
remains.
#+findex: denote-file-has-signature-p
+ Function ~denote-file-has-signature-p~ :: Return non-nil if =FILE=
@ -5009,7 +4959,7 @@ The following sections cover the specifics.
=FILES-MATCHING-REGEXP=, only extract keywords from the matching
files. Otherwise, do it for all files. Keep any duplicates. Users
who do not want duplicates should refer to the functions
~denote-keywords~. [ Part of {{{development-version}}}. ]
~denote-keywords~.
#+findex: denote-keywords
+ Function ~denote-keywords~ :: Return appropriate list of keyword
@ -5019,8 +4969,7 @@ The following sections cover the specifics.
([[#h:6a92a8b5-d766-42cc-8e5b-8dc255466a23][Standard note creation]]). In the case of keyword inferrence, use
optional =FILES-MATCHING-REGEXP=, to extract keywords only from the
matching files. Otherwise, do it for all files. Filter inferred
keywords with the user option ~denote-excluded-keywords-regexp~. [
The optional =FILES-MATCHING-REGEXP= parameter is part of {{{development-version}}}. ]
keywords with the user option ~denote-excluded-keywords-regexp~.
#+findex: denote-keywords-sort
+ Function ~denote-keywords-sort~ :: Sort =KEYWORDS= if
@ -5059,8 +5008,7 @@ The following sections cover the specifics.
files that satisfy ~denote-file-is-note-p~. With optional
=EXCLUDE-REGEXP= exclude the files that match the given regular
expression. This is done after =FILES-MATCHING-REGEXP= and
=OMIT-CURRENT= have been applied. [ The optional =EXCLUDE-REGEXP= is
part of {{{development-version}}}. ]
=OMIT-CURRENT= have been applied.
#+findex: denote-directory-subdirectories
+ Function ~denote-directory-subdirectories~ :: Return list of
@ -5170,8 +5118,7 @@ The following sections cover the specifics.
=ID= is a string holding the identifier of the note. It can be an
empty string, in which case its respective file name component is
not added to the base file name. [ This is changed as part of
{{{development-version}}}. ]
not added to the base file name.
=DIR-PATH= and =ID= form the base file name.
@ -5206,9 +5153,7 @@ The following sections cover the specifics.
from =PATH= and return them as a list of strings. =PATH= must be a
Denote-style file name where keywords are prefixed with an
underscore. If =PATH= has no such keywords, which is possible,
return nil ([[#h:4e9c7512-84dc-4dfb-9fa9-e15d51178e5d][The file-naming scheme]]). [ As part of {{{development-version}}},
this function has an alias ~denote-retrieve-filename-keywords-as-list~
which should make it easier to discover this functionality. ]
return nil ([[#h:4e9c7512-84dc-4dfb-9fa9-e15d51178e5d][The file-naming scheme]]).
#+findex: denote-extract-id-from-string
+ Function ~denote-extract-id-from-string~ :: Return existing Denote
@ -5217,8 +5162,7 @@ The following sections cover the specifics.
#+findex: denote-retrieve-filename-identifier
+ Function ~denote-retrieve-filename-identifier~ :: Extract identifier
from =FILE= name, if present, else return nil. To create a new one
from a date, refer to the ~denote-get-identifier~ function. [ This
is changed as part of {{{development-version}}}. ]
from a date, refer to the ~denote-get-identifier~ function.
#+findex: denote-retrieve-filename-title
+ Function ~denote-retrieve-filename-title~ :: Extract Denote title
@ -5242,7 +5186,7 @@ The following sections cover the specifics.
#+findex: denote-get-identifier
+ Function ~denote-get-identifier~ :: Convert =DATE= into a Denote
identifier using ~denote-id-format~. If =DATE= is nil, return an
empty string as the identifier. [ This is changed as part of {{{development-version}}}. ]
empty string as the identifier.
#+findex: denote-retrieve-front-matter-title-value
+ Function ~denote-retrieve-front-matter-title-value~ :: Return title value from
@ -5328,8 +5272,7 @@ The following sections cover the specifics.
=PROMPT-TEXT= use it in the minibuffer instead of the default
prompt. =INITIAL-DATE= is a string that can be processed by
~denote-valid-date-p~, a value that can be parsed by ~decode-time~
or nil. [ The =INITIAL-DATE= and =PROMPT-TEXT= are part of
{{{development-version}}}. ]
or nil.
#+findex: denote-command-prompt
+ Function ~denote-command-prompt~ :: Prompt for command among
@ -5583,8 +5526,6 @@ The following sections cover the specifics.
:CUSTOM_ID: h:e824c215-1c31-4b26-b994-7df67341d075
:END:
[ All of the following are part of {{{development-version}}}. ]
- Function ~denote-retrieve-groups-xref-query~ :: Access location of
xrefs for =QUERY= and group them per file. Limit the search to text
files.
@ -5617,18 +5558,17 @@ The following sections cover the specifics.
+ Function ~denote-prepend-front-matter~ :: Prepend front matter to
=FILE=. The =TITLE=, =KEYWORDS=, =DATE=, =ID=, =SIGNATURE=, and
=FILE-TYPE= are passed from the renaming command and are used to
construct a new front matter block if appropriate. [ This function
is available as part of {{{development-version}}}. ]
construct a new front matter block if appropriate.
#+findex: denote-rewrite-front-matter
+ Function ~denote-rewrite-front-matter~ :: Rewrite front matter of
note after ~denote-rename-file~ (or related) The =FILE=, =TITLE=,
note after ~denote-rename-file~ (or related). The =FILE=, =TITLE=,
=KEYWORDS=, =SIGNATURE=, =DATE=, =IDENTIFIER=, and =FILE-TYPE=
arguments are given by the renaming command and are used to construct
new front matter values if appropriate. If ~denote-rename-confirmations~
contains ~rewrite-front-matter~, prompt to confirm the rewriting of
the front matter. Otherwise produce a ~y-or-n-p~ prompt to that
effect. [ This function is changed as part of {{{development-version}}}. ]
effect.
#+findex: denote-add-front-matter-prompt
+ Function ~denote-add-front-matter-prompt~ :: Prompt to add a

6
denote.el
View file

@ -5,7 +5,7 @@
;; Author: Protesilaos Stavrou <info@protesilaos.com>
;; Maintainer: Protesilaos Stavrou <info@protesilaos.com>
;; URL: https://github.com/protesilaos/denote
;; Version: 3.1.0
;; Version: 4.0.0
;; Package-Requires: ((emacs "28.1"))
;; This file is NOT part of GNU Emacs.
@ -4235,7 +4235,7 @@ they have front matter and what that may be."
;;;;; Creation of front matter
(make-obsolete 'denote-add-front-matter nil "Use `denote-rename-file' or related. Starting with version 3.2.0.")
(make-obsolete 'denote-add-front-matter nil "Use `denote-rename-file' or related. Starting with version 4.0.0.")
;;;###autoload
(defun denote-change-file-type-and-front-matter (file new-file-type)
@ -4856,7 +4856,7 @@ the active region specially, is up to it."
(defalias 'denote-insert-link 'denote-link
"Alias for `denote-link' command.")
(make-obsolete 'denote-link-with-signature nil " 3.2.0: Use the `denote-link-description-format'.")
(make-obsolete 'denote-link-with-signature nil " 4.0.0: Use the `denote-link-description-format'.")
(defun denote-link--collect-identifiers (regexp)
"Return collection of identifiers in buffer matching REGEXP."