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 2.3.0

Browse source
This commit is contained in:
Protesilaos Stavrou 2024-03-24 19:51:48 +02:00
parent 5f90cc9617
commit 93887bea48
No known key found for this signature in database
GPG key ID: 99BD6459CD5CA3EA
3 changed files with 775 additions and 137 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

733
CHANGELOG.org
View file

@ -13,6 +13,739 @@ the manual: <https://protesilaos.com/emacs/denote>.
#+toc: headlines 1 insert TOC here, with one headline level
* Version 2.3.0 on 2024-03-24
:PROPERTIES:
:CUSTOM_ID: h:e9d3ebdb-8a69-47a9-a5a2-619abc44b7d2
:END:
This release brings a host of user-facing refinements to an already
stable base, as well as some impressive new features. There is a lot
to cover, so take your time reading these notes.
Special thanks to Jean-Philippe Gagné Guay for the numerous
refinements to parts of the code base. Some of these are not directly
visible to users, but are critical regardless. In the interest of
brevity, I will not be covering the most technical parts here. I
mention Jean-Philippe's contributions at the outset for this reason.
Though the Git commit log is there for interested parties to study
things further.
** Check out the ~denote-explore~ package by Peter Prevos
:PROPERTIES:
:CUSTOM_ID: h:3e49dd9d-59db-40e5-9116-ce678231b08d
:END:
This package provides several neat extensions that help you make
better sense of your knowledge base, while keeping it in good order.
The ~denote-explore~ package has commands to summarise the usage of
keywords, visualise connections between notes, spot infrequently used
keywords, and jump to previous historical entries.
- Git repository: <https://github.com/pprevos/denote-explore>.
- Documentation: <https://lucidmanager.org/productivity/denote-explore>.
Now on to Denote version =2.3.0=!
** Link to a heading inside a Denote Org file
:PROPERTIES:
:CUSTOM_ID: h:ca7baf4f-04af-4467-a1e6-20403357280f
:END:
Denote creates links to files by using their unique identifier. As Org
provides the =CUSTOM_ID= property for per-heading identifiers, we now
leverage this infrastructure to compose links that point to a file and
then to a heading therein. This only works for Org, as no other plain
text major mode has a concept of heading identifiers (and it is not
Denote's job to create such a feature).
I demonstrated the functionality in a video:
<https://protesilaos.com/codelog/2024-01-20-emacs-denote-link-org-headings/>
Technically, the =denote:= link type has the same implementation
details as Org's standard =file:= and has always had this potential to
jump to a section inside the given file.
*** The ~denote-org-store-link-to-heading~ user option
:PROPERTIES:
:CUSTOM_ID: h:a7864660-5b4c-4467-a252-9140baedeb1a
:END:
The user option ~denote-org-store-link-to-heading~ determines whether
~org-store-link~ links to the current Org heading (such links are
merely "stored" and need to be inserted afterwards with the command
~org-insert-link~). Note that the ~org-capture~ command uses the
~org-link~ internally if it has to store a link.
When its value is non-nil, ~org-store-link~ stores a link to the
current Org heading inside the Denote Org file. If the heading does
not have a =CUSTOM_ID=, it creates it and includes it in the heading's
=PROPERTIES= drawer. If a =CUSTOM_ID= exists, ~org-store-link~ use it
as-is.
This makes the resulting link a combination of the =denote:= link type,
pointing to the identifier of the current file, plus the value of the
heading's =CUSTOM_ID=, such as:
- =[[denote:20240118T060608][Some test]]=
- =[[denote:20240118T060608::#h:eed0fb8e-4cc7-478f-acb6-f0aa1a8bffcd][Some test::Heading text]]=
Both lead to the same Denote file, but the latter jumps to the heading
with the given =CUSTOM_ID=. Notice that the link to the heading also
has a different description, which includes the heading text.
The value of the =CUSTOM_ID= is determined by the Org user option
~org-id-method~. The sample shown above uses the default UUID
infrastructure.
If ~denote-org-store-link-to-heading~ is set to a nil value, the
command ~org-store-link~ only stores links to the Denote file (using
its identifier), but not to the given heading. This is what Denote was
doing in all versions prior to =2.3.0=.
Thanks to Kristoffer Balintona for discussing with me how
~org-capture~ interfaces with ~org-store-link~. I updated the
documentation accordingly. This was done in issue 267:
<https://github.com/protesilaos/denote/issues/267>.
*** Insert link to an Org file with a further pointer to a heading
:PROPERTIES:
:CUSTOM_ID: h:dd054536-8d20-4251-b23d-77fec7d7d036
:END:
As part of the optional =denote-org-extras.el= extension that comes
with the ~denote~ package, the command ~denote-org-extras-link-to-heading~
prompts for a link to an Org file and then asks for a heading therein,
using minibuffer completion. Once the user provides input at the two
prompts, the command inserts a link at point which has the following
pattern: =[[denote:IDENTIFIER::#ORG-HEADING-CUSTOM-ID]][Description::Heading text]]=.
Because only Org files can have links to individual headings, the
command ~denote-org-extras-link-to-heading~ prompts only for Org files
(i.e. files which include the =.org= extension). Remember that Denote
works with many file types.
This feature is similar to the concept of the aforementioned user
option ~denote-org-store-link-to-heading~. It is, however, interactive
and differs in the directionality of the action. With that user
option, the command ~org-store-link~ will generate a =CUSTOM_ID= for
the current heading (or capture the value of one as-is), giving the
user the option to then call ~org-insert-link~ wherever they see fit.
By contrast, the command ~denote-org-extras-link-to-heading~ prompts
for a file, then a heading, and inserts the link at point.
** Refinements galore to minibuffer prompts
:PROPERTIES:
:CUSTOM_ID: h:e509402b-a58f-4a10-b364-b158b31d1ee5
:END:
*** All commands that affect file names conform with ~denote-prompts~
:PROPERTIES:
:CUSTOM_ID: h:11f0fc1e-552b-4a02-bf01-9d8508ce68c8
:END:
The scope of the ~denote-prompts~ user option is broadened to make it
more useful. In the past, this variable would only affect the
behaviour of the ~denote~ command. For example, the user would make
the command prompt for a subdirectory, then keywords, then a title.
But all other commands were not following this setting, as they were
hardcoding the prompts for title and keywords.
Take the ~denote-subdirectory~ command as an example. It would first
prompt for a subdirectory to place the new note in, then for a title,
and then for keywords. Whereas now, it prepends the =subdirectory=
prompt to the list of ~denote-prompts~. So if the user has configured
their ~denote-prompts~ to, for example, ask for a signature and a file
type, the ~denote-subdirectory~ will do just that with the addition of
the =subdirectory= prompt.
Same idea for all commands that either create or modify file names,
wherever conformity with ~denote-prompts~ makes sense. For example,
the ~denote-rename-file~ will never ask for a =subdirectory= because
our renaming policy is to always rename in place (to avoid
mistakes---you can always move the file afterwards).
This also means that the ~denote-rename-file~ and its multi-file
counterpart, ~denote-dired-rename-files~, will only prompt for a
signature if it is part of the ~denote-prompts~. Whereas in the
previous version this was unconditional, thus burdening users who do
not need the =SIGNATURE= file name component (more about renaming
further into the release notes).
Lots of Git commits went into this redesign, per my initiave in issue
247: <https://github.com/protesilaos/denote/issues/247>. Thanks to
Vedang Manerikar for the changes to the convenience wrappers of the
~denote~ command (like ~denote-subdirectory~), which were done in pull
request 248: <https://github.com/protesilaos/denote/pull/248>.
Vedang has assigned copyright to the Free Software Foundation.
Also thanks to Max Brieiev for joining the technical discussion
therein.
The renaming commands are more intuitive now, which addresses a
discussion point raised by user babusri in issue 204:
<https://github.com/protesilaos/denote/issues/204>.
*** A simple tweak for more informative minibuffer prompts
:PROPERTIES:
:CUSTOM_ID: h:a502217d-8eff-4a6f-b66a-33e5e7ecda9d
:END:
The text of each prompt now has all capital letters for the word
referencing its scope of its application, like =TITLE=, =KEYWORDS=,
=SIGNATURE=. The idea is to make it easier to quickly scan the text,
especially while working through multiple prompts. For example, the
prompt for a title now reads:
: New file TITLE:
This paradigm is followed by all prompts. It is a small yet effective
tweak to get a better sense of context.
*** The file prompt uses relative names once again
:PROPERTIES:
:CUSTOM_ID: h:8f182ad3-c97f-45dc-a451-c552f2a7957c
:END:
In previous versions of Denote, the minibuffer prompt to pick a file
(such as a file to link to) would show relative file names: the name
without the full file system path. The functionality depended on the
built-in =project.el= library, which did not allow us to do everything
we wanted with our prompts, such as to have a dedicated minibuffer
history or to easily enable the workflow of commands like
~denote-open-or-create~.
In the previous version, I made the decision to remove the
=project.el= dependency and the concomitant presentation of relative
names in order to add the functionality we want. I did it with the
intention to find a better solution down the line. Et voilá! Relative
file names are back. We now have all the functionality we need. Sorry
if in the meantime you had to deal with those longer names! It was a
necessary intermediate arrangement for the greater good.
For the technicalities, refer to the source code of the function
~denote-title-prompt~.
*** Completion using previous inputs is now optional
:PROPERTIES:
:CUSTOM_ID: h:bcf382e4-bd00-49f3-859a-3f86e9770b77
:END:
All our minibuffer prompts have their dedicated history (you can
persist histories with the built-in ~savehist-mode~). They store
previous values, giving the user easy access to their past input
values. Some of our commands not only record a history, but also
leverage it to provide completion. These commands are named in the
variable ~denote-prompts-with-history-as-completion~. As of this
writing, they are:
- ~denote-title-prompt~
- ~denote-signature-prompt~
- ~denote-files-matching-regexp-prompt~
Users who do not want to use completion for those can set the new user
option ~denote-history-completion-in-prompts~ to a nil value.
** Renaming files got better all-round
:PROPERTIES:
:CUSTOM_ID: h:747e126a-b966-4ac8-a8ec-cf900012e37e
:END:
One of the pillars of the ~denote~ package is its ability to rename
any file to use the efficient Denote file-naming scheme (makes file
names predictable and easy to retrieve even with rudimentary tools).
To this end, we provide several commands that affect file names,
beside the commands that create new files.
As noted above, the commands which rename files to follow the Denote
file-naming scheme now conform with the user option ~denote-prompts~,
but there is more!
*** A broadened scope for the ~denote-rename-no-confirm~ option
:PROPERTIES:
:CUSTOM_ID: h:f93b8075-de2d-416e-9275-7225d03678ad
:END:
The implementation of this user option is redone (i) to save the
underlying buffer outright if the user does not want to provide their
confirmation for a rename each time and (ii) to cover all relevant
commands that perform a rename operation. The assumption is that the
user who opts in to this feature is familiar with the Denote renaming
modalities and knows they are reliable.
The default is still the same: Denote always asks for confirmation
before renaming a file, showing the difference between the old and new
names, as well as any changes to the file's contents. In this light,
buffers are not saved to give the user the chance to further inspect
the changes (such as by running ~diff-buffer-with-file~).
Commands that will now skip all confirmation prompts to rename the file
and, where relevant, save the corresponding buffer outright:
- ~denote-rename-file~
- ~denote-dired-rename-files~
- ~denote-dired-rename-marked-files-with-keywords~
- ~denote-rename-file-using-front-matter~
- ~denote-rename-add-keywords~
- ~denote-rename-remove-keywords~
- ~denote-rename-add-signature~ (new, more below)
- ~denote-rename-remove-signature~ (new, more below)
*** Rename a file by adding or removing a =SIGNATURE= component
:PROPERTIES:
:CUSTOM_ID: h:01ab0277-b4d4-433e-bd25-b9a0357412f6
:END:
The =SIGNATURE= is an optional free-form field that is part of a
Denote file name. A common use-case is to write sequence notes with
it, though Denote does not enforce any particular convention (you may
prefer to have it as a special kind of keyword for certain files that
simply stands out more due to its placement).
[ Besides, the ~denote-sort-dired~ command lets you filter and sort
files while putting them in a fully fledged Dired buffer, so
manually sequencing notes via their signature may not be needed. ]
We now provide two commands to add or remove a signature from file
names:
- The ~denote-rename-add-signature~ prompts for a file and a
signature. The default value for the file prompt is the file of the
currently open buffer or the file-at-point in a Dired buffer. The
signature is an ordinary string, defaulting to the selected file's
signature, if any.
- The ~denote-rename-remove-signature~ uses the same file prompt as
above. It performs its action only if the selected file has a
signature. Otherwise, it does nothing.
Files that do not have a Denote file name are renamed accordingly.
Though for such cases it is better to use ~denote-rename-file~ or
~denote-dired-rename-files~ as they are more general.
*** Use the ~denote-after-rename-file-hook~ for optional post-rename operations
:PROPERTIES:
:CUSTOM_ID: h:57f4f60c-7873-4542-a7a5-5c997cdbd137
:END:
All renaming commands run the ~denote-after-rename-file-hook~ after a
successful operation. This is meant for users who want to do something
specific after the renaming is done.
** More optional features of the =denote-org-extras.el=
:PROPERTIES:
:CUSTOM_ID: h:a0a2753e-5be9-4776-9f3f-e3b7556c13c1
:END:
I already covered the ~denote-org-extras-link-to-heading~, though the
file =denote-org-extras.el= has some more optional goodies for those
who work with Org files.
*** Create a note from the current Org subtree
:PROPERTIES:
:CUSTOM_ID: h:fbf1e574-e9aa-4c67-8034-27341d7a5536
:END:
In Org parlance, an entry with all its subheadings and other contents
is a "subtree". Denote can operate on the subtree to extract it from
the current file and create a new file out of it. One such workflow is
to collect thoughts in a single document and produce longer standalone
notes out of them upon review.
The command ~denote-org-extras-extract-org-subtree~ (part of the
optional =denote-org-extras.el= extension) is used for this purpose.
It creates a new Denote note using the current Org subtree. In doing
so, it removes the subtree from its current file and moves its
contents into a new file.
The text of the subtree's heading becomes the =#+title= of the new
note. Everything else is inserted as-is.
Read the documentation string of ~denote-org-extras-extract-org-subtree~
or consult the manual for further details.
*** Convert =denote:= links to =file:= links
:PROPERTIES:
:CUSTOM_ID: h:042e26e8-e3e0-4c57-9855-6b363671ae9a
:END:
Sometimes the user needs to translate all =denote:= link types to
their =file:= equivalent. This may be because some other tool does not
recognise =denote:= links (or other custom links types---which are a
standard feature of Org, by the way). The user thus needs to (i)
either make a copy of their Denote note or edit the existing one, and
(ii) convert all links to the generic =file:= link type that
external/other programs understand.
The optional extension =denote-org-extras.el= contains two commands
that are relevant for this use-case:
+ Convert =denote:= links to =file:= links :: The command
~denote-org-extras-convert-links-to-file-type~ goes through the
buffer to find all =denote:= links. It gets the identifier of the
link and resolves it to the actual file system path. It then
replaces the match so that the link is written with the =file:= type
and then the file system path. The optional search terms and/or link
description are preserved.
+ Convert =file:= links to =denote:= links :: The command
~denote-org-extras-convert-links-to-denote-type~ behaves like the
one above. The difference is that it finds the file system path and
converts it into its identifier.
*** The Denote Org dynamic blocks are now in =denote-org-extras.el=
:PROPERTIES:
:CUSTOM_ID: h:51d72c47-d434-4954-98d6-2db7a7ea6812
:END:
As part of this version, all our dynamic blocks are defined in the
file =denote-org-extras.el=. The file which once contained these block
definitions, =denote-org-dblock.el=, now only has aliases for the new
function names and dipslays a warning about its deprecation.
There is no need to ~require~ the ~denote-org-extras~ feature because
all of Denote's Org dynamic blocks are autoloaded (meaning that they
work as soon as they are used). For backward compatibility, all
dynamic blocks retain their original names as an alias for the newer
one.
We will not remove =denote-org-dblock.el= anytime soon to avoid any
potential breakage with people's existing notes. Though if you are new
to this functionality, you better avoid the deprecated symbols.
*** Org dynamic block to only insert missing links
:PROPERTIES:
:CUSTOM_ID: h:45176e63-c609-40f6-a11d-1cc0c28460dd
:END:
The =denote-missing-links= block is available with the command
~denote-org-extras-dblock-insert-missing-links~. It is like the
=denote-links= block (documented at length in the manual), except it
only lists links to files that are not present in the current buffer.
The parameters are otherwise the same:
: #+BEGIN: denote-missing-links :regexp "YOUR REGEXP HERE" :sort-by-component nil :reverse-sort nil :id-only nil
:
: #+END:
Remember to type =C-c C-x C-u= (~org-dblock-update~) with point on the
=#+BEGIN= line to update the block.
This brings back a feature that was deprecated in version 2.2.0, but
makes changes to it so that (i) it is more limited in scope and (ii)
available as a standalone Org dynamic block.
Thanks to Stephen R. Kifer, Peter Prevos, and Elias Storms for the
discussion which made it clear to me that users do have a need for
such functionality. This was done in the now-defunct mailing list:
<https://lists.sr.ht/~protesilaos/denote/%3C1db2104e-70bd-47f9-a7ed-b8d4bb370a7f%40app.fastmail.com%3E>.
Also thanks to Vedang Manerikar for fixing an edge case bug. This was
done in pull request 260: <https://github.com/protesilaos/denote/pull/260>.
Org dynamic blocks are a powerful feature which also showcases how far
we can go with Denote's efficient file-naming scheme.
** Quality-of-life improvements
:PROPERTIES:
:CUSTOM_ID: h:08f27f36-0ed2-4a5e-b02b-f0075c6e904f
:END:
Here I include other changes we made to existing functionality.
*** BREAKING User-defined sluggification of file name components
:PROPERTIES:
:CUSTOM_ID: h:240b80e7-242c-46fb-83d2-1ba36bdcaf66
:END:
In the previous version, we introduced the user option
~denote-file-name-letter-casing~. This was used to control the letter
casing of file name components, but was ultimately not flexible enough
for our purposes. We are thus retiring it and replacing it with the
more powerful, but also more advanced, user option
~denote-file-name-slug-functions~.
For existing users of the deprecated functionality, you can still
preserve the input of a prompt verbatim with something like this:
#+begin_src emacs-lisp
(setq denote-file-name-slug-functions
'((title . denote-sluggify-title)
(keyword . identity)
(signature . denote-sluggify-signature)))
#+end_src
The manual explains the details and shows ready-to-use code samples.
Remember that deviating from the default file-naming scheme of Denote
will make things harder to use in the future, as files will have
permutations that create uncertainty. The sluggification scheme and
concomitant restrictions we impose by default are there for a very
good reason: they are the distillation of years of experience. Here we
give you what you wish, but bear in mind it may not be what you need.
You have been warned.
Thanks to Jean-Philippe Gagné Guay for introducing this variable,
among other tweaks, in pull request 217: <https://github.com/protesilaos/denote/pull/217>.
Jean-Philippe has assigned copyright to the Free Software Foundation.
*** Option to automatically save the buffer of a new note
:PROPERTIES:
:CUSTOM_ID: h:3e1249f1-ac26-4187-9ddd-7391b4e5131f
:END:
The user option ~denote-save-buffer-after-creation~ controls whether
commands that create new notes save their buffer right away.
The default behaviour of commands such as ~denote~ (or related) is to
not save the buffer they create. This gives the user the chance to
review the text before writing it to a file. The user may choose to
delete the unsaved buffer, thus not creating a new file on disk.
If ~denote-save-buffer-after-creation~ is set to a non-nil value, such
buffers are saved automatically and so the file is written to disk.
*** The ~denote-menu-bar-mode~ and the placement of the Denote submenu
:PROPERTIES:
:CUSTOM_ID: h:c8336927-cf6b-4770-b041-123bf9186e57
:END:
The command ~denote-menu-bar-mode~ toggles the inclusion of the
submenu with the Denote entries in the Emacs menu bar (which is on
display when ~menu-bar-mode~ is enabled).
This submenu is now shown after the =Tools= entry.
Thanks to Joseph Turner for sending me the relevant patches. Joseph
has assigned copyright to the Free Software Foundation.
*** The =C-c C-o= works in ~markdown-mode~ for Denote links
:PROPERTIES:
:CUSTOM_ID: h:1c884b19-7ab7-4eb5-a332-815d25f7373c
:END:
In files whose major mode is ~markdown-mode~, the default key binding
=C-c C-o= (which calls the command ~markdown-follow-thing-at-point~)
correctly resolves =denote:= links. This method works in addition to
the =RET= key, which is made available by the buttonization that we
also provide. Interested users can refer to the function
~denote-link-markdown-follow~ for the implementation details.
Thanks to user pmenair for noting a case where this was breaking
general Markdown linking functionality. This was done in issue 290:
<https://github.com/protesilaos/denote/issues/290>.
*** More fine-grained control of Denote faces for dates/identifiers
:PROPERTIES:
:CUSTOM_ID: h:c6f739ef-ea26-41b8-84e6-c87c4622cdba
:END:
We now define more faces for fine-grained control of the identifier in
Dired. Thanks to mentalisttraceur for suggesting the idea in issue
276: <https://github.com/protesilaos/denote/issues/276>.
Before you ask, no, none of my themes will cover those faces because
extra colouration is something only the user can decide if they want
or not. In the above link I provide a sample with a screenshot (apart
from the ~modus-themes~, my ~ef-themes~ and ~standard-themes~ have
similar functionality):
#+begin_src emacs-lisp
(defun my-modus-themes-denote-faces (&rest _)
(modus-themes-with-colors
(custom-set-faces
`(denote-faces-year ((,c :foreground ,cyan)))
`(denote-faces-month ((,c :foreground ,magenta-warmer)))
`(denote-faces-day ((,c :foreground ,cyan)))
`(denote-faces-time-delimiter ((,c :foreground ,fg-main)))
`(denote-faces-hour ((,c :foreground ,magenta-warmer)))
`(denote-faces-minute ((,c :foreground ,cyan)))
`(denote-faces-second ((,c :foreground ,magenta-warmer))))))
(add-hook 'modus-themes-post-load-hook #'my-modus-themes-denote-faces)
#+end_src
*** New convenience command for users of the optional =denote-journal-extras.el=
:PROPERTIES:
:CUSTOM_ID: h:9e7bff88-a6ad-45e7-b802-0493153e0e20
:END:
The command ~denote-journal-extras-link-or-create-entry~ links to the
journal entry for today or creates it in the background, if missing,
and then links to it from the current file. If there are multiple
journal entries for the same day, it prompts to select one among them
and then links to it. When called with an optional prefix argument
(such as =C-u= with default key bindings), the command prompts for a
date and then performs the aforementioned. With a double prefix
argument (=C-u C-u=), it also produces a link whose description
includes just the file's identifier.
Thanks to Alan Schmitt for contributing this command, based on
previous discussions. It was done in pull request 243:
<https://github.com/protesilaos/denote/pull/243>.
** For developers or advanced users
:PROPERTIES:
:CUSTOM_ID: h:03778c8c-60aa-449c-96df-7e41916668a6
:END:
These has new parameters or are new symbols altogether. Please read
their respective doc string for the details.
+ Function ~denote-convert-file-name-keywords-to-crm~.
+ Function ~denote-valid-date-p~.
+ Function ~denote-parse-date~.
+ Function ~denote-retrieve-title-or-filename~.
+ Function ~denote-get-identifier~.
+ Function ~denote-signature-prompt~.
+ Function ~denote-file-prompt~.
+ Function ~denote-keywords-prompt~.
+ Function ~denote-title-prompt~.
+ Function ~denote-rewrite-front-matter~.
+ Function ~denote-rewrite-keywords~.
+ Function ~denote-update-dired-buffers~.
+ Function ~denote-format-string-for-org-front-matter~.
+ Function ~denote-format-string-for-md-front-matter~.
+ Variable ~denote-link-signature-format~.
+ Function ~denote-link-description-with-signature-and-title~.
+ Variable ~denote-link-description-function~.
** Miscellaneous
:PROPERTIES:
:CUSTOM_ID: h:040f2678-674d-4e99-b428-659cd3a3b7c3
:END:
- The ~denote-sort-dired~ function no longer errors out when there is
no match for the given search terms. Thanks to Vedang Manerikar for
the initial patch! This was done in the now-defunct mailing list:
<https://lists.sr.ht/~protesilaos/denote/patches/47625>. Further
changes by me.
- The ~denote-keywords-sort~ function no longer tries to sort keywords
that are not a list. Thanks to Ashton Wiersdorf for the patch. The
change is small. As such, Ashton does not need to assign copyright
to the Free Software Foundation.
- Documented in the manual that custom convenience commands can be
accessed by the ~denote-command-prompt~. Thanks to Glenna D. for
clarifying the language.
- The ~denote-user-enforced-denote-directory~ is obsolete. Those who
used it in their custom code can simply ~let~ bind the value of the
variable ~denote-directory~. Thanks to Jean-Philippe Gagné Guay for
making the relevant changes (the Git history is not direct here and
I cannot quickly find the pull request---the commit is =a48a1da=).
- The ~denote-link-return-links~ no longer keeps buffers around.
Thanks to Matteo Cavada for the patch. This was done in pull request
252: <https://github.com/protesilaos/denote/pull/252>. The change is
small and so Matteo does not need to assign copyright to the Free
Software Foundation.
- Thanks to user jarofromel (recorded in Git as "random" author) for
fixing a mismatched parenthesis in ~denote-parse-date~. This was
done in pull request 258: <https://github.com/protesilaos/denote/pull/258>.
- The ~denote-rename-buffer-mode~ now works as expected with
non-editable files, like PDFs. Thanks to Alan Schmitt for bringing
this matter to my attention and then refining the implementation
details in pull request 268: <https://github.com/protesilaos/denote/pull/268>.
- All the Denote linking functions can be used from any file outside
the ~denote-directory~ (links are still resolved to files inside the
~denote-directory~). Thanks to Jean-Philippe Gagné Guay for the
contribution in pull request 236: <https://github.com/protesilaos/denote/pull/236>.
- We removed all glue code that integrated Denote with the built-in
~ffap~, ~xref~, and ~project~ libraries. We may reconsider how best
to organise such features in the future. Thanks to Noboru Ota
(nobiot), who originally contributed those extensions, for
suggesting their removal from our code base. We did this by
evaluating all use-cases. The discussion with Noboru happened in
issue 264: <https://github.com/protesilaos/denote/issues/264>. Also
thanks to Jean-Philippe Gagné Guay and Alan Schnmitt for checking
the impact of this on how we generate backlinks. The latest
iteration of this was done in pull request 294, by Jean-Philippe:
<https://github.com/protesilaos/denote/pull/294>.
- While renaming files, signatures no longer lose consecutive spaces.
Thanks to Wesley Harvey for the contribution in pull request 207:
<https://github.com/protesilaos/denote/pull/207>. The change is
within the ~15 line limit and so Wesley does not need to assign
copyright to the Free Software Foundation.
- All of the above and lots more are documented at length in the
manual. This is a big task in its own right (as are release notes,
by the way), though it ensures we keep a high standard for the
entire package and can communicate all our knowledge to the user.
** No more SourceHut
:PROPERTIES:
:CUSTOM_ID: h:9a0d6afc-95e0-490e-a573-5a50fe7bdf28
:END:
Development continues on GitHub with GitLab as a mirror. I explained
my reasons here: <https://protesilaos.com/codelog/2024-01-27-sourcehut-no-more/>.
This is a change that affects all my Emacs packages.
** Forward guidance for Denote version 3.0.0
:PROPERTIES:
:CUSTOM_ID: h:61fb340e-5c7c-4a4b-927c-63faf4759a09
:END:
We will not any new features until mid-April or a bit later if
necessary. This gives users enough time to report any potential issues
with version =2.3.0=. If there are any bugs, they will be fixed right
away and new minor releases will be introduced (though without release
notes).
Once we are done with this release cycle, we want to prepare for the
next major version of Denote. The plan is to make the placement of
file name components entirely customisable, among many other power
user features. Though the defaults will remain intact.
For the immediate future, please prioritise bug reports/fixes. Then
see you around for another round of hacking. The Denote code base is a
pleasure to work with due to how composable everything is. I happy to
make it even better for developers and users alike.
** Git commits
:PROPERTIES:
:CUSTOM_ID: h:a6fd8e16-ded9-49cf-afbb-6e1373c3c43d
:END:
Just an overview of what we did. Thanks again to everyone involved.
#+begin_src sh
~/Git/Projects/denote $ git shortlog 2.2.0..2.3.0 --summary --numbered
246 Protesilaos Stavrou
46 Jean-Philippe Gagné Guay
6 Vedang Manerikar
3 Joseph Turner
2 Alan Schmitt
2 Max
2 Peter Prevos
1 Ashton Wiersdorf
1 Glenna D.
1 Matteo Cavada
1 mattyonweb
1 random
1 wlharvey4
#+end_src
** All contributions are valuable
:PROPERTIES:
:CUSTOM_ID: h:967372fa-933b-40d2-b1a8-546d1a50d35d
:END:
I encourage you to provide feedback on any of the functionality of the
Denote package. You do not need to be a developer or indeed an expert
in Emacs. When you have an idea in mind on how you use Denote, or you
think something could be done differently, please speak your mind. I
do listen to feedback and am interested in further improving this
package. Everybody is welcome!
* Version 2.2.0 on 2023-12-10
:PROPERTIES:
:CUSTOM_ID: h:8efed390-cfa0-420d-b300-0cb76bf2c9f9

177
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 2.2.0
#+macro: release-date 2023-12-10
#+macro: development-version 2.3.0-dev
#+macro: stable-version 2.3.0
#+macro: release-date 2024-03-24
#+macro: development-version 3.0.0-dev
#+export_file_name: denote.texi
#+texinfo_filename: denote.info
#+texinfo_dir_category: Emacs misc features
@ -51,7 +51,7 @@ the GNU ELPA machinery automatically generates an Info manual out of it.
:CUSTOM_ID: h:40b18bb2-4dc1-4202-bd0b-6fab535b2a0f
:END:
Copyright (C) 2022-2023 Free Software Foundation, Inc.
Copyright (C) 2022-2024 Free Software Foundation, Inc.
#+begin_quote
Permission is granted to copy, distribute and/or modify this document
@ -208,11 +208,6 @@ alias ~denote-create-note~.
:CUSTOM_ID: h:f9204f1f-fcee-49b1-8081-16a08a338099
:END:
[ As part of {{{development-version}}}, all commands that produce or
modify a Denote file name are revised to do their work while
conforming with the value of ~denote-prompts~, where that is
reasonable to do. ]
#+vindex: denote-prompts
The user option ~denote-prompts~ determines how the ~denote~ command
will behave interactively ([[#h:6a92a8b5-d766-42cc-8e5b-8dc255466a23][Standard note creation]]).
@ -301,8 +296,6 @@ specifies, based on the supplied arguments.
:CUSTOM_ID: h:403422a7-7578-494b-8f33-813874c12da3
:END:
[ Part of {{{development-version}}}. ]
#+vindex: denote-history-completion-in-prompts
The user option ~denote-history-completion-in-prompts~ toggles history
completion in all ~denote-prompts-with-history-as-completion~.
@ -410,8 +403,7 @@ option, there are cases where an ad-hoc method is the appropriate one
To this end, Denote provides the following interactive convenience
commands for note creation. They all work by appending a new prompt to
the existing ~denote-prompts~. [ Appending to the existing
~denote-prompts~ is defined in {{{development-version}}}. ]
the existing ~denote-prompts~.
+ Create note by specifying file type :: The ~denote-type~ command
creates a note while prompting for a file type.
@ -550,8 +542,6 @@ to the list of commands available at the ~denote-command-prompt~
:CUSTOM_ID: h:bf80f4cd-6f56-4f7c-a991-8573161e4511
:END:
[ Part of {{{development-version}}}. ]
#+vindex: denote-save-buffer-after-creation
The user option ~denote-save-buffer-after-creation~ controls whether
commands that creeate new notes save their buffer outright.
@ -584,8 +574,6 @@ that is common in interactions with Org mode, can set the user option
:CUSTOM_ID: h:d0c7cb79-21e5-4176-a6af-f4f68578c8dd
:END:
[ Rewritten as part of {{{development-version}}}. ]
In Org parlance, an entry with all its subheadings and other contents
is a "subtree". Denote can operate on the subtree to extract it from
the current file and create a new file out of it. One such workflow is
@ -1047,9 +1035,6 @@ To see another example of a wrapper function that =let= binds
:CUSTOM_ID: h:e43baf95-f201-4fec-8620-c0eb5eaa1c85
:END:
[ As part of {{{development-version}}}, we fixed an issue where a
=C-u= prefix argument was needed to select a silo. ]
The =denote-silo-extras.el= provides optional convenience functions for
working with silos ([[#h:15719799-a5ff-4e9a-9f10-4ca03ef8f6c5][Maintain separate directory silos for notes]]).
Start by loading the relevant library:
@ -1130,8 +1115,7 @@ development log: <https://protesilaos.com/codelog/2023-03-31-emacs-denote-menu/>
#+findex: denote-menu-bar-mode
The command ~denote-menu-bar-mode~ toggles the presentation of the
menu. It is enabled by default. [ The ~denote-menu-bar-mode~ is part
of {{{development-version}}}. ]
menu. It is enabled by default.
Emacs also provides support for operations through a context menu.
This is typically the set of actions that are made available via a
@ -1169,7 +1153,7 @@ mechanisms to facilitate the task of renaming them.
#+vindex: denote-after-rename-file-hook
All renaming commands run the ~denote-after-rename-file-hook~ after a
succesful operation. [ Part of {{{development-version}}}. ]
succesful operation.
Apart from renaming files, Denote can also rename only the buffer.
The idea is that the underlying file name is correct but it can be
@ -1183,12 +1167,6 @@ line or switching between then with commands like ~switch-to-buffer~.
:CUSTOM_ID: h:7cc9e000-806a-48da-945c-711bbc7426b0
:END:
[ Revised as part of {{{development-version}}} to honour the value of
the user option ~denote-prompts~ where that makes sense ([[#h:f9204f1f-fcee-49b1-8081-16a08a338099][The ~denote-prompts~ option]]).
This version also broadens the scope of the user option
~denote-rename-no-confirm~, such that it automatically saves the
affected buffers, post-rename. ]
#+findex: denote-rename-file
The ~denote-rename-file~ command renames a file and updates existing
front matter if appropriate. It is possible to do the same with
@ -1293,10 +1271,6 @@ one-by-one, use ~denote-dired-rename-files~ ([[#h:1b6b2c78-42f0-45b8-9ef0-6de21a
:CUSTOM_ID: h:a2ae9090-c49e-4b32-bcf5-eb8944241fd7
:END:
[ Revised as part of {{{development-version}}} to save the underlying
buffer. The assumption is that the user who opts in to this feature is
familiar with the Denote renaming operation and knows it is reliable. ]
#+vindex: denote-rename-no-confirm
The user option ~denote-rename-no-confirm~ makes all commands that
rename files not prompt for confirmation and save buffers outright ([[#h:532e8e2a-9b7d-41c0-8f4b-3c5cbb7d4dca][Renaming files]]).
@ -1332,12 +1306,6 @@ use, but carries out the renaming without asking for confirmation
:CUSTOM_ID: h:3ab08ff4-81fa-4d24-99cb-79f97c13a373
:END:
[ Revised as part of {{{development-version}}} to (i) accept an
optional double prefix argument to automatically save the buffer and
(ii) to not ask for confirmation while renaming and to automatically
save the buffer if the user option ~denote-rename-no-confirm~ is
non-nil ([[#h:a2ae9090-c49e-4b32-bcf5-eb8944241fd7][The ~denote-rename-no-confirm~ option]]). ]
#+findex: denote-rename-file-using-front-matter
In the previous section, we covered the more general mechanism of the
command ~denote-rename-file~ ([[#h:7cc9e000-806a-48da-945c-711bbc7426b0][Rename a single file]]). There is also a
@ -1383,8 +1351,6 @@ If called interactively with a prefix argument (=C-u= by default) or
from Lisp with a non-nil =NO-CONFIRM= argument, this "yes or no"
prompt is skipped and the renaming is done outright.
[ The following are part of {{{development-version}}}. ]
If called interactively with a double prefix argument (=C-u C-u= by
default) or from Lisp with a non-nil =SAVE-BUFFER= argument, the
buffer is saved after the front matter is updated and the file is
@ -1404,13 +1370,6 @@ the like.
:CUSTOM_ID: h:1b6b2c78-42f0-45b8-9ef0-6de21a8b2cde
:END:
[ Revised as part of {{{development-version}}} to honour the value of
the user option ~denote-prompts~ where that makes sense ([[#h:f9204f1f-fcee-49b1-8081-16a08a338099][The ~denote-prompts~ option]]). ]
[ As part of {{{development-version}}} the
~denote-dired-rename-marked-files~ is an alias for
~denote-dired-rename-files~. ]
#+findex: denote-dired-rename-files
#+findex: denote-dired-rename-marked-files
The command ~denote-dired-rename-files~ (alias
@ -1434,9 +1393,6 @@ check the command ~denote-dired-rename-marked-files-with-keywords~.
:CUSTOM_ID: h:f365ff7e-2140-4e14-a92f-666ae97382a4
:END:
[ Revised as part of {{{development-version}}} to honour the value of
the user option ~denote-prompts~ where that makes sense ([[#h:f9204f1f-fcee-49b1-8081-16a08a338099][The ~denote-prompts~ option]]). ]
#+findex: denote-dired-rename-marked-files-with-keywords
The ~denote-dired-rename-marked-files-with-keywords~ command renames
marked files in Dired to conform with our file-naming scheme. It does
@ -1532,8 +1488,6 @@ Similarly, the ~denote-keywords-remove~ removes one or more keywords
from the list of existing keywords and then renames the file
accordingly.
[ The following are part of {{{development-version}}}. ]
Both commands accept an optional prefix argument to automatically save
the buffer. Similarly, they both interpret a non-nil value for the
user option ~denote-rename-no-confirm~ the same as the prefix argument
@ -1552,8 +1506,6 @@ Aliases for these commands are: ~denote-rename-add-keywords~ and
:CUSTOM_ID: h:b08a350f-b269-47ed-8c2a-b8ecf1b63c7f
:END:
[ Part of {{{development-version}}}. ]
#+findex: denote-rename-add-signature
#+findex: denote-rename-remove-signature
The commands ~denote-rename-add-signature~ and
@ -1735,9 +1687,6 @@ hackability and so users can deviate from the aforementioned
:CUSTOM_ID: h:d375c6d2-92c7-425f-9d9d-219ff47ed2a3
:END:
[ Part of {{{development-version}}}, superseding the deprecated user
option ~denote-file-name-letter-casing~. ]
#+vindex: denote-file-name-slug-functions
The user option ~denote-file-name-slug-functions~ controls the
sluggification of file name components ([[#h:ae8b19a1-7f67-4258-96b3-370a72c43f4e][Sluggification of file name components]]).
@ -2115,8 +2064,6 @@ like an ordinary link by default. This is just a convenience for the
user/theme in case they want =denote:= links to remain distinct from
other links.
[ The following is part of {{{development-version}}}. ]
#+findex: denote-link-markdown-follow
In files whose major mode is ~markdown-mode~, the default key binding
=C-c C-o= (which calls the command ~markdown-follow-thing-at-point~)
@ -2130,8 +2077,6 @@ buttonization. Interested users can refer to the function
:CUSTOM_ID: h:d99de1fb-b1b7-4a74-8667-575636a4d6a4
:END:
[ Part of {{{development-version}}}. ]
#+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 (such links are
@ -2180,8 +2125,6 @@ regardless of the aforementioned user option ([[#h:fc1ad245-ec08-41be-8d1e-7153d
:CUSTOM_ID: h:fc1ad245-ec08-41be-8d1e-7153d99daf02
:END:
[ Part of {{{development-version}}}. ]
#+findex: denote-org-extras-link-to-heading
As part of the optional =denote-org-extras.el= extension, the command
~denote-org-extras-link-to-heading~ prompts for a link to an Org file
@ -2583,8 +2526,6 @@ creating a new one ([[#h:ad91ca39-cf10-4e16-b224-fdf78f093883][Open an existing
:CUSTOM_ID: h:ed220cac-7dcb-4bb7-9243-1bb85e452e5f
:END:
[ Part of {{{development-version}}}. ]
Sometimes the user needs to translate all =denote:= link types to
their =file:= equivalent. This may be because some other tool does not
recognise =denote:= links (or other custom links types---which are a
@ -2702,8 +2643,7 @@ The faces we define for this purpose are:
+ ~denote-faces-time~
+ ~denote-faces-title~
As part of {{{development-version}}} we also provide these faces for
more fine-grained colouration:
For more control, we also provide these:
#+vindex denote-faces-year
#+vindex denote-faces-month
@ -2815,15 +2755,14 @@ own function and assigning it to the ~denote-rename-buffer-function~.
:CUSTOM_ID: h:8b542c50-dcc9-4bca-8037-a36599b22779
:END:
[ As part of version 2.3.0 (currently {{{development-version}}}), all
dynamic blocks are defined in the file =denote-org-extras.el=. The
file which was once called =denote-org-dblock.el= contains aliases
for the new function names and dipslays a warning about its
deprecation. There is no need to ~require~ the ~denote-org-extras~
feature because all of Denote's Org dynamic blocks are autoloaded
(meaning that they work as soon as they are used). For backward
compatibility, all dynamic blocks retain their original names as an
alias for the newer one. ]
[ As part of version 2.3.0, all dynamic blocks are defined in the file
=denote-org-extras.el=. The file which was once called
=denote-org-dblock.el= contains aliases for the new function names
and dipslays a warning about its deprecation. There is no need to
~require~ the ~denote-org-extras~ feature because all of Denote's
Org dynamic blocks are autoloaded (meaning that they work as soon as
they are used). For backward compatibility, all dynamic blocks
retain their original names as an alias for the newer one. ]
Denote can optionally integrate with Org mode's "dynamic blocks"
facility. This means that it can use special blocks that are evaluated
@ -2856,15 +2795,14 @@ Evaluate:
:CUSTOM_ID: h:50160fae-6515-4d7d-9737-995ad925e64b
:END:
[ As part of version 2.3.0 (currently {{{development-version}}}), all
dynamic blocks are defined in the file =denote-org-extras.el=. The
file which was once called =denote-org-dblock.el= contains aliases
for the new function names and dipslays a warning about its
deprecation. There is no need to ~require~ the ~denote-org-extras~
feature because all of Denote's Org dynamic blocks are autoloaded
(meaning that they work as soon as they are used). For backward
compatibility, all dynamic blocks retain their original names as an
alias for the newer one. ]
[ As part of version 2.3.0, all dynamic blocks are defined in the file
=denote-org-extras.el=. The file which was once called
=denote-org-dblock.el= contains aliases for the new function names
and dipslays a warning about its deprecation. There is no need to
~require~ the ~denote-org-extras~ feature because all of Denote's
Org dynamic blocks are autoloaded (meaning that they work as soon as
they are used). For backward compatibility, all dynamic blocks
retain their original names as an alias for the newer one. ]
#+findex: denote-org-extras-dblock-insert-links
The =denote-links= block can be inserted at point with the command
@ -2925,9 +2863,6 @@ this in an Org file:
:
: #+END:
[ The ~denote-org-extras-dblock-insert-missing-links~ is part of
{{{development-version}}}. ]
#+findex: denote-org-extras-dblock-insert-missing-links
Finally, the =denote-missing-links= block is available with the
command ~denote-org-extras-dblock-insert-missing-links~. It is like
@ -2947,15 +2882,14 @@ Remember to type =C-c C-x C-u= (~org-dblock-update~) with point on the
:CUSTOM_ID: h:f15fa143-5036-416f-9bff-1bcabbb03456
:END:
[ As part of version 2.3.0 (currently {{{development-version}}}), all
dynamic blocks are defined in the file =denote-org-extras.el=. The
file which was once called =denote-org-dblock.el= contains aliases
for the new function names and dipslays a warning about its
deprecation. There is no need to ~require~ the ~denote-org-extras~
feature because all of Denote's Org dynamic blocks are autoloaded
(meaning that they work as soon as they are used). For backward
compatibility, all dynamic blocks retain their original names as an
alias for the newer one. ]
[ As part of version 2.3.0, all dynamic blocks are defined in the file
=denote-org-extras.el=. The file which was once called
=denote-org-dblock.el= contains aliases for the new function names
and dipslays a warning about its deprecation. There is no need to
~require~ the ~denote-org-extras~ feature because all of Denote's
Org dynamic blocks are autoloaded (meaning that they work as soon as
they are used). For backward compatibility, all dynamic blocks
retain their original names as an alias for the newer one. ]
Denote can optionally use Org's dynamic blocks facility to produce a
section that lists entire file contents ([[#h:8b542c50-dcc9-4bca-8037-a36599b22779][Use Org dynamic blocks]]).
@ -3164,9 +3098,6 @@ for one among them using minibuffer completion. If there is only one,
it visits it outright. If there is no journal entry, it creates one
by calling ~denote-journal-extra-new-entry~ (as described above).
[ The ~denote-journal-extras-link-or-create-entry~ is part of
{{{development-version}}}. ]
#+findex: denote-journal-extras-link-or-create-entry
The command ~denote-journal-extras-link-or-create-entry~ links to the
journal entry for today or creates it in the background, if missing,
@ -3855,8 +3786,7 @@ or by advising the Org export function.
Denote also provides commands to convert =denote:= links to their
=file:= equivalent, in case this is a required pre-processing step for
export purposes ([[#h:ed220cac-7dcb-4bb7-9243-1bb85e452e5f][Convert =denote:= links to =file:= links]]). [ This is
part of {{{development-version}}}. ]
export purposes ([[#h:ed220cac-7dcb-4bb7-9243-1bb85e452e5f][Convert =denote:= links to =file:= links]]).
**** Manually configure Org export
:PROPERTIES:
@ -4248,8 +4178,7 @@ might change them without further notice.
with keywords readable by ~completing-read-multiple~. =STRING=
consists of underscore-separated words, as those appear in the
keywords component of a Denote file name. =STRING= is the same as
the return value of ~denote-retrieve-filename-keywords~. [ Part of
{{{development-version}}}. ]
the return value of ~denote-retrieve-filename-keywords~.
#+findex: denote-keywords-sort
+ Function ~denote-keywords-sort~ :: Sort =KEYWORDS= if
@ -4266,15 +4195,12 @@ might change them without further notice.
valid =DATE= is a value that can be parsed by either ~decode-time~
or ~date-to-time~ .Those functions signal an error if =DATE= is a
value they do not recognise. If =DATE= is nil, return nil.
[ Part of {{{development-version}}}. ]
#+findex: denote-parse-date
+ Function ~denote-parse-date~ :: Return =DATE= as an appropriate
value for the ~denote~ command. Pass =DATE= through
~denote-valid-date-p~ and use its return value. If either that or
=DATE= is nil, return ~current-time~. [ The ~denote-valid-date-p~ is
the new name of ~denote--valid-date~, with enhanced functionality.
Done as part of {{{development-version}}}. ]
=DATE= is nil, return ~current-time~.
#+findex: denote-directory
+ Function ~denote-directory~ :: Return path of the variable
@ -4409,15 +4335,12 @@ might change them without further notice.
title for =FILE= given its =TYPE=. Try to find the value of the
title in the front matter of FILE, otherwise use its file name. This
is a wrapper for ~denote-retrieve-front-matter-title-value~ and
=denote-retrieve-filename-title=. [ This was known as the private
function ~denote--retrieve-title-or-filename~. It is made public as
part of {{{development-version}}}. ]
=denote-retrieve-filename-title=.
#+findex: denote-get-identifier
+ Function ~denote-get-identifier~ :: Convert =DATE= into a Denote
identifier using ~denote-id-format~. =DATE= is parsed by
~denote-valid-date-p~. If =DATE= is nil, use the current time.
[ Part of {{{development-version}}}. ]
#+findex: denote-create-unique-file-identifier
+ Function ~denote-create-unique-file-identifier~ :: Create a new unique
@ -4470,18 +4393,12 @@ might change them without further notice.
of the default prompt. Previous inputs at this prompt are available
for minibuffer completion if the user option ~denote-history-completion-in-prompts~
is set to a non-nil value ([[#h:403422a7-7578-494b-8f33-813874c12da3][The ~denote-history-completion-in-prompts~ option]]).
[ Revised as part of {{{development-version}}} to optionally not
provide completion against its previous input history. ]
#+findex: denote-file-prompt
+ Function ~denote-file-prompt~ :: Prompt for file with identifier in
variable ~denote-directory~. With optional =FILES-MATCHING-REGEXP=,
filter the candidates per the given regular expression. With
optional =PROMPT-TEXT=, use it instead of the default "Select NOTE".
[ As part of {{{development-version}}}, completion candidates have a
relative file path, but the return value and what is stored in the
minibuffer history is still the full file system path. Furthermore,
the =PROMPT-TEXT= is added. ]
#+findex: denote-keywords-prompt
+ Function ~denote-keywords-prompt~ :: Prompt for one or more keywords.
@ -4489,8 +4406,7 @@ might change them without further notice.
~crm-separator~, which typically is a comma. With optional
=PROMPT-TEXT=, use it to prompt the user for keywords. Else use a
generic prompt. With optional =INITIAL-KEYWORDS= use them as the
initial minibuffer text. [ The optional =INITIAL-KEYWORDS= argument is
part of {{{development-version}}}. ]
initial minibuffer text.
#+findex: denote-title-prompt
+ Function ~denote-title-prompt~ :: Prompt for title string. With
@ -4499,8 +4415,6 @@ might change them without further notice.
default prompt. Previous inputs at this prompt are available
for minibuffer completion if the user option ~denote-history-completion-in-prompts~
is set to a non-nil value ([[#h:403422a7-7578-494b-8f33-813874c12da3][The ~denote-history-completion-in-prompts~ option]]).
[ Revised as part of {{{development-version}}} to optionally not
provide completion against its previous input history. ]
#+vindex: denote-title-prompt-current-default
+ Variable ~denote-title-prompt-current-default~ :: Currently bound
@ -4534,7 +4448,6 @@ might change them without further notice.
optionally perform completion against their own minibuffer history
when the user option ~denote-history-completion-in-prompts~ is set
to a non-nil value ([[#h:403422a7-7578-494b-8f33-813874c12da3][The ~denote-history-completion-in-prompts~ option]]).
[ This is part of {{{development-version}}}. ]
#+findex: denote-files-matching-regexp-prompt
+ Function ~denote-files-matching-regexp-prompt~ :: Prompt for
@ -4572,8 +4485,7 @@ might change them without further notice.
the rewriting of the front matter. Otherwise produce a ~y-or-n-p~
prompt to that effect. With optional =NO-CONFIRM=, save the buffer
after performing the rewrite. Otherwise leave it unsaved for
furthter review by the user. [ The =NO-CONFIRM= saves the buffer as
part of {{{development-version}}}. ]
furthter review by the user.
#+findex: denote-rewrite-keywords
+ Function ~denote-rewrite-keywords~ :: Rewrite =KEYWORDS= in =FILE=
@ -4582,8 +4494,7 @@ might change them without further notice.
confirmation. With optional =SAVE-BUFFER=, save the buffer
corresponding to =FILE=. This function is for use in the commands
~denote-keywords-add~, ~denote-keywords-remove~,
~denote-dired-rename-files~, or related. [ The =SAVE-BUFFER= saves
the buffer as part of {{{development-version}}}. ]
~denote-dired-rename-files~, or related.
#+findex: denote-update-dired-buffers
+ Function ~denote-update-dired-buffers~ :: Update Dired buffers of
@ -4591,8 +4502,6 @@ might change them without further notice.
even if it is not inside the ~denote-directory~. Note that the
~denote-directory~ accepts a directory-local value for what we
internally refer to as "silos" ([[#h:15719799-a5ff-4e9a-9f10-4ca03ef8f6c5][Maintain separate directories for notes]]).
[ Refined as part of {{{development-version}}} to also revert the
current Dired buffer. ]
#+vindex: denote-file-types
+ Variable ~denote-file-types~ :: Alist of ~denote-file-type~ and
@ -4727,15 +4636,13 @@ might change them without further notice.
#+findex: denote-format-string-for-org-front-matter
+ Function ~denote-format-string-for-org-front-matter~ :: Return
string =S= as-is for Org or plain text front matter. If =S= is not a
string, return an empty string. [ Part of {{{development-version}}}. ]
string, return an empty string.
#+findex: denote-format-string-for-md-front-matter
+ Function ~denote-format-string-for-md-front-matter~ :: Surround
string =S= with quotes. If =S= is not a string, return a literal
emptry string. This can be used in ~denote-file-types~ to format
front mattter. [ Revised as part of {{{development-version}}} and
renamed from ~denote-surround-with-quotes~ to
~denote-format-string-for-md-front-matter~. ]
front mattter.
#+findex: denote-format-keywords-for-md-front-matter
+ Function ~denote-format-keywords-for-md-front-matter~ :: Format
@ -4766,8 +4673,6 @@ might change them without further notice.
+ Function ~denote-link-return-backlinks~ :: Return list of backlinks
in current or optional =FILE=. Also see ~denote-link-return-links~.
[ All of the following are part of {{{development-version}}}. ]
#+vindex: denote-link-signature-format
+ Variable ~denote-link-signature-format~ :: Format of link
description for ~denote-link-with-signature~.

2
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: 2.2.4
;; Version: 2.3.0
;; Package-Requires: ((emacs "28.1"))
;; This file is NOT part of GNU Emacs.