branch: externals/denote
commit c98c74ec74fb6f0c894c5bf730d092d716e55b84
Author: Protesilaos Stavrou <i...@protesilaos.com>
Commit: Protesilaos Stavrou <i...@protesilaos.com>
Update to Denote version 4.0.0
---
CHANGELOG.org | 593 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
README.org | 126 ++++---------
denote.el | 6 +-
3 files changed, 629 insertions(+), 96 deletions(-)
diff --git a/CHANGELOG.org b/CHANGELOG.org
index bb1111a76b..4f545859df 100644
--- a/CHANGELOG.org
+++ b/CHANGELOG.org
@@ -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
diff --git a/README.org b/README.org
index 7378a96be0..505300ca60 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 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
diff --git a/denote.el b/denote.el
index 6b73b22f2d..e0677608ee 100644
--- a/denote.el
+++ b/denote.el
@@ -5,7 +5,7 @@
;; Author: Protesilaos Stavrou <i...@protesilaos.com>
;; Maintainer: Protesilaos Stavrou <i...@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."
