[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/denote df3aedacdd 1/2: Update to Denote version 2.0.0
|
From: |
ELPA Syncer |
|
Subject: |
[elpa] externals/denote df3aedacdd 1/2: Update to Denote version 2.0.0 |
|
Date: |
Fri, 21 Jul 2023 09:57:54 -0400 (EDT) |
branch: externals/denote
commit df3aedacdd6e96923df2b88492eba1b87147e14f
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>
Update to Denote version 2.0.0
---
CHANGELOG.org | 579 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
README.org | 94 ++--------
denote.el | 2 +-
3 files changed, 600 insertions(+), 75 deletions(-)
diff --git a/CHANGELOG.org b/CHANGELOG.org
index 86c762cc0b..ae9c37d5a3 100644
--- a/CHANGELOG.org
+++ b/CHANGELOG.org
@@ -9,6 +9,585 @@ project's main git repository:
<https://git.sr.ht/~protesilaos/denote>.
The newest release is at the top. For further details, please consult
the manual: <https://protesilaos.com/emacs/denote>.
+* Version 2.0.0 on 2023-07-21
+:PROPERTIES:
+:CUSTOM_ID: h:3f17bf03-4c47-4410-abf8-1db4a0ac7775
+:END:
+
+This is the second major version of Denote, close to one year after
+its initial release. The video demo I did back then remains relevant,
+even though lots of details have changed.
+
+** Notes have a new optional SIGNATURE field
+:PROPERTIES:
+:CUSTOM_ID: h:a3a9e14d-4132-47c0-a23c-cb008a141668
+:END:
+
+It is now possible to create notes that include a =SIGNATURE= field in
+their file name. Either use the convenience command ~denote-signature~
+or configure the user option ~denote-prompts~ to affect what the ~denote~
+command should prompt for.
+
+Signatures are arbitrary strings of characters that enable the user to
+further qualify their documents. One possible workflow is to write
+relational notes, such that =1a1= is the first extension of another
+note with a =1a= signature.
+
+The design of the =SIGNATURE= field is consistent with the Denote
+file-naming scheme. The field separator is the double equals sign
+(~==~), while words that comprise the signature are joined together by
+a single equals sign. As such, the user can prefix a search with an
+equals sign to match words in the =SIGNATURE=, just as they would use
+dashes for the =TITLE= and underscores for the =KEYWORDS=.
+
+[ Read the manual for the technicalities of the Denote file-naming
+ scheme. This is not limited to "notes": any file can be named
+ accordingly (I do it with my videos, for example). ]
+
+Signatures are not included in a file's front matter. This is a
+strategic decision to preserve backward compatibility, while not
+introducing a feature that has not enjoyed widespread usage. I want
+to make signatures behave the same as the rest of the file name
+fields, though I am interested to learn how users employ them in their
+workflow.
+
+The signature extension was discussed at length on the GitHub mirror
+in issue 115: <https://github.com/protesilaos/denote/issues/115>.
+Thanks to Stefan Thesing, Mirko Hernandez, Noboru Ota (nobiot),
+Xiaoxing Hu, nbehrnd, Elias Storms, and 101scholar for helping me
+reason about this feature, understand its scope, and prototype its
+implementation.
+
+Also thanks to Alfredo Borrás and Jeremy Friesen for discussing with
+me the field delimiter of signatures on the mailing list:
+<https://lists.sr.ht/~protesilaos/denote/%3C2A597B4E-5F18-4D97-9457-B3C859DAA020%40zoho.eu%3E>.
+Thanks to Kai von Fintel for doing the same on the GitHub mirror in
+issue 147: <https://github.com/protesilaos/denote/issues/147>.
+
+Read the original announcement:
+<https://protesilaos.com/codelog/2023-03-20-emacs-denote-signature-feature/>.
+
+As part of the development, I fixed a case where
+~denote-rename-file-using-front-matter~ would fail if it could not
+find a signature
+
+The idea is that we want the command to behave the way it always did
+when the file has no signature and to preserve the signature when it
+is present.
+
+Thanks to relict for reporting the issue on the mailing list:
+<https://lists.sr.ht/~protesilaos/denote/%3C87zg86lru9.fsf%40kotlak.com%3E>.
+
+** The rename commands avoid creating duplicate identifiers
+:PROPERTIES:
+:CUSTOM_ID: h:d24645a3-ad02-450c-b3d7-af7802aa0b26
+:END:
+
+Denote provides commands to rename an existing file to one that
+follows the Denote file-naming scheme (videos, PDFs, other text
+documents, ...). Check, for example, the ~denote-rename-file~ and
+~denote-dired-rename-marked-files~. The idea is to make everything
+easier to search.
+
+In prior versions, these commands could produce duplicate identifiers
+if the modification date of the underlying files was the same. Such a
+scenario occurs when the files are modified programmatically, as with
+the =touch= command or the various =git= operations.
+
+Denote will now take care to increment the identifier until it becomes
+unique within the current scope.
+
+Thanks to Felipe Balbi for reporting this bug in issue 105 on the
+GitHub mirror: <https://github.com/protesilaos/denote/issues/105>.
+
+Thanks to Vedang Manerikar and Jean-Charles Bagneris for commenting on
+this feature on the mailing list:
+<https://lists.sr.ht/~protesilaos/denote/%3C87v8emeus0.fsf%40protesilaos.com%3E>.
+
+Thanks to Ashton Wiersdorf for noticing a mistake I made that caused a
+regression in ~denote-rename-file~:
+<https://lists.sr.ht/~protesilaos/denote/%3Cm2lefbbzl1.fsf%40wiersdorfmail.net%3E>.
+
+*** Optional arguments affect ~denote-dired-rename-marked-files~
+:PROPERTIES:
+:CUSTOM_ID: h:6ea998be-83dd-4c67-945c-11011372818f
+:END:
+
+The ~denote-dired-rename-marked-files~ now accepts two optional
+arguments. When called interactively, these are interpreted as a
+single or double universal prefix argument (=C-u= by default, though
+do =M-x where-is= and search for ~universal-argument~).
+
+The first argument, named =SKIP-FRONT-MATTER-PROMPT=, skips the "yes
+or no" prompt requested at the outset of the operation, passing to it
+an affirmative response. Thanks to Jay Rajput for asking the question
+that inspired me to implement this. It was done in issue 155 on the
+GitHub mirror: <https://github.com/protesilaos/denote/issues/155>.
+
+The second argument, named =NO-UNIQUE-ID-CHECK=, will not perform any
+checks for potential duplicate identifiers. The default is to check
+for duplicates and increment them such that they become unique. The
+reason this optional argument exists is for those who want to speed up
+the process, perhaps because they know ahead of time all identifiers
+will be unique or do not care about them.
+
+Thanks to Bruno Boal for refining how the prefix argument is
+processed. The patch was sent via a private channel. The change is
+small and thus does not require copyright assignment to the Free
+Software Foundation.
+
+** Menu entries help users discover Denote
+:PROPERTIES:
+:CUSTOM_ID: h:651e5561-f9ce-41f6-bad3-d54ce2dcff04
+:END:
+
+Users of ~menu-bar-mode~ and/or ~context-menu-mode~ will now find a
+submenu with points of entry to Denote. Refer to the publication I
+made on my website, as it includes a picture:
+<https://protesilaos.com/codelog/2023-03-31-emacs-denote-menu/>. I
+will save the thousand words for the following sections. 🙃
+
+There is a known issue where the ~menu-bar-mode~ entry is positioned
+before the =File= submenu. Apparently, there exists an inelegant way
+to place the menu elsewhere, but I am not willing to maintain hacks
+for missing functionality. If someone knows a clear way to put the
+submenu elsewhere, please contact me: I want it to be after =Tools=.
+
+Thanks to Kai von Fintel and Noboru Ota (nobiot) for discussing the
+placement of the submenu:
+<https://lists.sr.ht/~protesilaos/denote/%3C2B60992C-0FC9-42CC-B669-69A544450FEF%40mit.edu%3E>.
+
+** "Link" commands have simpler names
+:PROPERTIES:
+:CUSTOM_ID: h:acf95a79-3c45-423d-a88f-d6eed7fa5387
+:END:
+
+Originally, Denote was organised as a collection of several files,
+each of which had its own prefix like =denote-dired.el=, and
+=denote-link.el=. This arrangement was deemed surplus to requirements
+and all core code was consolidated in =denote.el=. An artefact of
+that design was the presence of symbols that retained their admittedly
+awkward names, like the command ~denote-link-backlinks~ or
+~denote-link-add-missing-links~.
+
+All such commands are deprecated. They are replaced with more
+discoverable names. The deprecation is done in such a way that the
+old names are aliases for the new ones, but the user is warned not to
+rely on them.
+
+The new names in detail:
+
+| Old name 🤨 | New name 🤩
|
+|-------------------------------------+---------------------------------------------------------------|
+| ~denote-link-add-links~ | ~denote-add-links~
|
+| ~denote-link-add-missing-links~ | ~denote-add-missing-links~
|
+| ~denote-link-backlinks~ | ~denote-backlinks~
|
+| ~denote-link-find-file~ | ~denote-find-link~
|
+| ~denote-link-insert-link~ | ~denote-insert-link~ (alias for
~denote-link~) |
+| ~denote-link-show-backlinks-buffer~ | ~denote-show-backlinks-buffer~ (alias
for ~denote-backlinks~) |
+
+** Denote buffers can have shorter names
+:PROPERTIES:
+:CUSTOM_ID: h:98f6b10a-ea29-49d1-8d3f-e2f0409f4c8f
+:END:
+
+The Denote file-naming scheme is designed to be a low-tech way of
+embedding information in files, making them easier to find. A
+downside is that the names are longer than =blah.txt= and so the
+default Emacs behaviour is to derive a buffer name from the file name.
+
+The new optional =denote-rename-buffer.el= provides a minor mode to
+automatically rename the buffer of an existing file, such that it
+reflects the file's =TITLE= field. Users must enable
+~denote-rename-buffer-mode~.
+
+The renaming procedure is controlled by the user option
+~denote-rename-buffer-function~. By default, it provides the means to
+rename using (i) the title, (ii) the identifier, or (iii) a custom
+function that returns a string. Experienced users can refer to
+~denote-rename-buffer-with-title~ to draw inspiration on the design of
+such a function.
+
+Thanks to Morgan Davidson for asking a question that inspired me to
+implement this feature. The discussion took place in issue 151 on the
+GitHub mirror <https://github.com/protesilaos/denote/issues/151>.
+
+** Silos work as directory trees
+:PROPERTIES:
+:CUSTOM_ID: h:113820c4-7a6f-4126-9a44-92bfa59744e2
+:END:
+
+Denote provides a feature to isolate files in to their own silos, each
+of which functions as its own ~denote-directory~ variable. The
+technicalities are explained in the manual. Silos have proven to be a
+valuable aspect of file management and I have thus expanded their
+scope to work as fully fledged directory trees. This means that we no
+longer assume a silo to be a flat directory listing, but instead
+recognise any subdirectories inside of it.
+
+Thanks to relict007, Hilde Rhyne, Mirko Hernández, Noboru Ota
+(nobiot), Alan Schmitt, hapst3r, and Hilde Rhyne for their
+participation in the relevant discussions:
+
+-
<https://lists.sr.ht/~protesilaos/denote/%3C87fsb72nge.fsf%40protesilaos.com%3E>
+-
<https://lists.sr.ht/~protesilaos/denote/%3C80CBB671-D812-4EA8-8C80-85F9F4144051%40disroot.org%3E>
+- <https://lists.sr.ht/~protesilaos/denote/%3C87pma6t59i.fsf%40kotlak.com%3E>
+- <https://github.com/protesilaos/denote/issues/129> (GitHub mirror)
+-
<https://lists.sr.ht/~protesilaos/denote/%3CB124A5AF-9968-4F7E-9F4B-2BC763E0BFCF@disroot.org%3E#%3Cm0sff0nnhb.fsf@disroot.org%3E>.
+
+** Keywords do not accept multiple words by default
+:PROPERTIES:
+:CUSTOM_ID: h:08f23806-9570-4031-86e4-810b3e93be81
+:END:
+
+The idea is to have short keywords and then use more than one, if
+necessary. We do not want to encourage the habit of long keywords
+that become overly specific, while we want to avoid the use of
+dashes as delimited in the file name's =KEYWORDS= field.
+
+Technically, this changes the default value of the user option
+~denote-allow-multi-word-keywords~. Users who preferred the old
+behaviour can simply toggle it on.
+
+** Pass arguments to Org capture
+:PROPERTIES:
+:CUSTOM_ID: h:58ff6dd3-693a-4437-9217-8e876d92c975
+:END:
+
+Denote is not an extension of Org mode, though it can integrate with
+~org-capture~. I now make it possible to design a capture template
+that uses specific prompts. Consult the section in the manual titled
+"Create note with specific prompts using Org capture".
+
+Thanks to Aditya Yadav for asking about this in issue 132 on the
+GitHub mirror: <https://github.com/protesilaos/denote/issues/132>.
+
+** Change an existing note's file type
+:PROPERTIES:
+:CUSTOM_ID: h:e1e874e3-d8ad-4685-aa62-59ad07078db2
+:END:
+
+The command ~denote-change-file-type~ changes the file type of an
+existing note. The available options are those among
+~denote-file-type~. Thanks to Jean-Philippe Gagné Guay for the
+contribution, which was done in pull request 137 on the GitHub mirror:
+<https://github.com/protesilaos/denote/pull/137>.
+
+** Denote dynamic blocks can now parse ~rx~ notation
+:PROPERTIES:
+:CUSTOM_ID: h:fe595ee7-8ba6-4ca3-aa66-35aa4e5ca0f5
+:END:
+
+Denote can leverage the Org feature of "dynamic blocks" to produce
+lists of links/backlinks. This is especially useful for metanotes
+(read the Denote manual---I document everything for a reason).
+
+Before, regular expressions were implemented only as strings while now
+they can also be written using the ~rx~ notation. Thanks to Mirko
+Hernandez for proposing this feature and discussing it with me in
+issue 122 on the GitHub mirror:
+<https://github.com/protesilaos/denote/issues/122>.
+
+Thanks to Elias Storms, the author of =denote-org-dblock.el=, for
+iterating on this functionality. This was done in pull request 130 on
+the GitHub mirror: <https://github.com/protesilaos/denote/pull/130>.
+
+** Made links to non-note files works as intended
+:PROPERTIES:
+:CUSTOM_ID: h:431a8952-0d71-4ba6-b6ae-85e5f7d520b9
+:END:
+
+The function ~denote-get-path-by-id~ is refactored to accept any file
+with an identifier. This always was its intended purpose. The user
+was always able to create =denote:= Org link types to, for example,
+=jpg= files but ~denote-get-path-by-id~ was refusing to resolve the
+otherwise valid path. Thanks to user relict007 for reporting the
+problem and discussing it with me in issue 135 on the GitHub mirror:
+<https://github.com/protesilaos/denote/issues/135>.
+
+The change was not trivial. It was followed up by a patch from Noboru
+Ota (nobiot) which elaborated on the conditionality. Quoting from
+commit =9ce9a24=:
+
+#+begin_quote
+fix(denote-get-path-by-id): #135
+
+Reference: https://github.com/protesilaos/denote/issues/135
+
+This patch change function 'denote-get-path-by-id' to allow for the following:
+
+- A single ID points to multiple files with different extensions
+- Denote needs to find a single file out of the multiple files
+- This is not necessarily a user error (export an Org file to an HTML)
+- Denote should let user decide their "primary" file extension
+
+The case the patch is intended to fix goes something like this:
+
+- You have 20230216__mynotes--tag.org.
+- You export it to 20230216__mynotes--tag.html.
+- Both files are in denote-directory
+- This means you have two files with the same ID with different
+ extensions denote-link-find-file, denote-link-find-backlink, and xref
+ integration might find the html file INSTEAD OF the .org file
+
+This is because html is earlier in the alphabetical order than
+org. Because the function uses seq-find, it will find the .html file
+first and returns it.
+#+end_quote
+
+** The ~denote-rename-file-using-front-matter~ works with empty keywords
+:PROPERTIES:
+:CUSTOM_ID: h:b00f228d-7f84-4d84-8d5f-ac90ea6b1065
+:END:
+
+Keywords are an optional field in the Denote file-naming scheme.
+However, an earlier version of the command mentioned in this heading
+was considering them mandatory and would refuse to proceed if the
+keywords were nil. Thanks to Eduardo Grajeda for fixing this:
+<https://lists.sr.ht/~protesilaos/denote/patches/39896>.
+
+The change is within the ~15 line limit and does not require copyright
+assignment to the Free Software Foundation.
+
+** The ~denote-title-prompt~ has its own history
+:PROPERTIES:
+:CUSTOM_ID: h:91f370f4-9fd1-461b-8ba4-fd9ba2d9c7a8
+:END:
+
+Denote implements minibuffer histories for all its relevant functions.
+This makes it easier for users to retrieve their previous inputs and
+to not get irrelevant ones.
+
+Before, the ~denote-title-prompt~ was not using its own history but
+was instead relying on another one that was intended only for file
+paths, thus mixing unrelated inputs.
+
+Thanks to Jonathan Sahar for bringing this matter to my attention.
+This was done in issue 144 on the GitHub mirror:
+<https://github.com/protesilaos/denote/issues/144>.
+
+** For developers or advanced users
+:PROPERTIES:
+:CUSTOM_ID: h:dcc52671-2127-47e0-9167-003f40ca3a54
+:END:
+
+*** Made it possible to add predicates for recursive file listing
+:PROPERTIES:
+:CUSTOM_ID: h:62546ec1-6ec8-41c7-9a18-10a531b534ce
+:END:
+
+The helper function ~denote--directory-all-files-recursively~ accepts
+predicates to help speed up its work.
+
+Thanks to Wade Mealing for reporting the issue about the performance
+of the built-in function ~directory-files-recursively~ in large,
+nested directories. And thanks to Graham Marlow for the patch, which
+was prepared as part of an extended discussion with me:
+
+- <https://lists.sr.ht/~protesilaos/denote/patches/40370>
+-
<https://lists.sr.ht/~protesilaos/denote/%3C20230414000311.1981-1-graham%40mgmarlow.com%3E#%3C76ed9fe2-d597-f7b9-5e59-717aeb77c3c3@mgmarlow.com%3E>
+- <https://lists.sr.ht/~protesilaos/denote/patches/40384>
+-
<https://lists.sr.ht/~protesilaos/denote/%3C87edonhvy0.fsf%40protesilaos.com%3E>
+-
<https://lists.sr.ht/~protesilaos/denote/%3C76ed9fe2-d597-f7b9-5e59-717aeb77c3c3%40mgmarlow.com%3E>
+-
<https://lists.sr.ht/~protesilaos/denote/%3C87zg75q4er.fsf%40protesilaos.com%3E>
+-
<https://lists.sr.ht/~protesilaos/denote/%3CCAO4UgPQtxhhqW0tB7eZnVh4nF9vLvnVGx+5oB_78_dg32URSLA%40mail.gmail.com%3E>
+
+*** New public symbols
+:PROPERTIES:
+:CUSTOM_ID: h:ed723274-a78e-4cfd-9655-c3bfe0fb1e68
+:END:
+
+The following are now public symbols that we commit to support and
+document henceforth:
+
++ Function ~denote-file-type-extensions~ :: Return all file type
+ extensions in ~denote-file-types~.
+
++ Variable ~denote-encryption-file-extensions~ :: List of strings
+ specifying file extensions for encryption.
+
++ Function ~denote-file-type-extensions-with-encryption~ :: Derive
+ ~denote-file-type-extensions~ plus ~denote-encryption-file-extensions~.
+
++ Function ~denote-link-return-links~ :: Return list of links in
+ current or optional =FILE=. Also see ~denote-link-return-backlinks~.
+
++ Function ~denote-link-return-backlinks~ :: Return list of links in
+ current or optional =FILE=. Also see ~denote-link-return-links~.
+
++ Function ~denote-rewrite-front-matter~ :: Rewrite front matter of
+ note after ~denote-rename-file~ (or related) The =FILE=, =TITLE=,
+ =KEYWORDS=, and =FILE-TYPE= arguments are given by the renaming
+ command and are used to construct new front matter values if
+ appropriate.
+
++ Function ~denote-rewrite-keywords~ :: Rewrite =KEYWORDS= in =FILE=
+ outright according to =FILE-TYPE=. Do the same as
+ ~denote-rewrite-front-matter~ for keywords, but do not ask for
+ confirmation. This is for use in ~denote-keywords-add~,
+ ~denote-keywords-remove~, ~denote-dired-rename-marked-files~, or
+ related.
+
+I am publicising the ~denote-link-return-links~ and its counterpart in
+response to the mailing list thread started by relict007:
+<https://lists.sr.ht/~protesilaos/denote/%3C87a5ygk6yi.fsf@kotlak.com%3E>.
+relict007 is the developer of the ~denote-cache~ package (in
+progress): <https://git.sr.ht/~relict007/denote-cache>.
+
+Similarly, the ~denote-rewrite-keywords~ is made public upon the
+request of Alan Schmitt:
+<https://lists.sr.ht/~protesilaos/denote/%3Cm2ttzgn2wu.fsf%40m4x.org%3E>.
+
+** Miscellaneous
+:PROPERTIES:
+:CUSTOM_ID: h:918087e6-8cd5-4d4f-a11a-b465dcbd9fe3
+:END:
+
+- Revised ~denote-link-return-{links,backlinks}~ to not produce a
+ ~user-error~. The errors are reserved for the interactive
+ functions. The others are for developers. Thanks to Elias Storms for
+ bringing this matter to my attention:
+
<https://github.com/protesilaos/denote/commit/694c1517be73949edbc3993c105c764da8e2571f#commitcomment-112677876>.
+
+- Refrained from trying to find forward links in non-text-files. If a
+ file extension is not in ~denote-file-types~, we have no way of
+ parsing or finding outgoing links in it. This change checks for the
+ file extension early on in 'when-let*' block and avoids opening the
+ file which is a relatively costly operation (and would fail finding
+ links anyway). Thanks to relict007 for the patch. This was done on
+ the mailing list:
+ <https://lists.sr.ht/~protesilaos/denote/%3C87r0riffdx.fsf%40kotlak.com%3E>
+ The change is small and thus does not require copyright assignment
+ to the Free Software Foundation.
+
+- Explained how to troubleshoot Denote. Refer to the section in the
+ manual titled "Troubleshoot Denote in a pristine environment."
+ While this is about Denote, the skills apply to all Emacs packages.
+
+- Ensured backlinks get correct ~denote-directory~ path. The
+ backlinks buffer will now get the correct path when it is generated
+ inside a silo. This is related to issue 129 reported by hapst3r on
+ the GitHub mirror: <https://github.com/protesilaos/denote/issues/129>.
+ The change is necessary because =.dir-locals.el= do not work for
+ buffers, so we must get the value from the file that calls
+ ~denote-link-backlinks~.
+
+- Added missing underscore from examples in exporting section. Thanks
+ to Peter Prevos for bringing this matter to my attention:
+
<https://lists.sr.ht/~protesilaos/denote/%3C87fs8b85tq.fsf%40prevos.net%3E#%3C87lehiuxfo.fsf@protesilaos.com%3E>.
+
+- Made the command ~denote-open-or-create~ work with an empty
+ ~denote-directory~. The ~denote-file-prompt~ would throw an error
+ before. The correct behaviour is to proceed to the "Create" phase
+ if the ~denote-directory~ is empty. Thanks to user drcxd for
+ reporting the bug in issue 131 on the GitHub mirror and for testing
+ my sample code: <https://github.com/protesilaos/denote/issues/131>.
+
+- Documented how to use tree-based file prompt on demand. This is my
+ solution to a request made by Mirko Hernandez on the possible use of
+ the old Denote file prompt. It is better not to introduce a user
+ option for this case, nor to keep multiple variants of the
+ ~denote-file-prompt~ in denote.el, as we want to keep things simple.
+ Mirko's feedback was provided in issue 121 on the GitHub mirror:
+ <https://github.com/protesilaos/denote/issues/121>.
+
+- Added the variable ~denote-user-enforced-denote-directory~. This is
+ intended for users who write custom code to extend Denote. The
+ value of this variable should be ~let~ bound around calls to the
+ function ~denote-directory~, thus overriding its return value. This
+ was discussed on the mailing list and then introduced by Vedang
+ Manerikar in commit =977c757=, with further changes by me in
+ =20ddc97=: <https://lists.sr.ht/~protesilaos/denote/patches/41776>.
+ Vedang has assigned copyright to the Free Software Foundation.
+
+- Fixed ~my-denote-org-extract-subtree~ section of the documentation.
+ This is part of some sample code that is not part of =denote.el=,
+ but we provide as a convenience/inspiration for interested parties.
+
+ The provided function did not work correctly.
+
+ 1. Tags are extracted before deleting the region from the source file.
+ 2. The function ~org-end-of-subtree~ is called to calculate the
+ point we should delete up to. The previously used function
+ ~org-entry-end-position~ ends at the first sub-heading under the
+ tree, which is not what we want. Instead, we want to cut the
+ whole subtree.
+ 3. The date information available in the subtree is retained. We
+ look for three common places for this information: the =CREATED=
+ or =DATE= properties in the =PROPERTIES= drawer, and the =CLOSED=
+ cookie at the element level itself.
+
+ Thanks to Vedang Manerikar for the contribution:
+
<https://lists.sr.ht/~protesilaos/denote/%3CCABzEscbPx24LCUCc7JsMmQtVGwhou5fUH_5h+%3Dt%3Dqi4396NqNQ%40mail.gmail.com%3E>
+
+- Removed the dependency on the built-in ~xdg~ library and updated the
+ default value of the user option ~denote-directory~. The reason is
+ that XDG is a Linux standard that does not work on other operating
+ systems, according to private feedback I received.
+
+- Fixed a regression for =M-p= (~previous-history-element~) in "do or
+ create" commands. Read the doc string of the commands
+ ~denote-open-or-create~ or ~denote-link-or-create~ for how this is
+ supposed to work. In short:
+
+ - Invoke the "do or create" command.
+ - Type something that does not match a file.
+ - In the following title prompt, hit =M-p= to bring back the last input.
+
+ I realised there was a regression when I read issue 152 on the
+ GitHub mirror, which was created by user "ustcpxy":
+ <https://github.com/protesilaos/denote/issues/152>. The issue is
+ about skipping the file title prompt.
+
+- Simplified the internal ~denote--buffer-file-names~. Thanks to Adam
+ Růžička for noting that my change was not compatible with older
+ Emacs versions, and for preparing the change. This was discussed in
+ pull request 158 on the GitHub mirror, with my suggestion to not use
+ ~seq-filter~ as it affected the return value:
+ <https://github.com/protesilaos/denote/pull/158>. The change is
+ below the 15 line limit, meaning that Adam does have to assign
+ copyright to the Free Software Foundation.
+
+- Documented custom code in the manual on how to interactively select
+ a silo. I am providing this in response to a request from GitHub
+ user rbenit68. The discussion took place in issue 127 on the GitHub
+ mirror, with the participation of Mirko Hernandez:
+ <https://github.com/protesilaos/denote/issues/127>. The custom code
+ I provide is the expanded version of an idea put forth by Mirko, to
+ whom I am thankful.
+
+- Fixed an outdated reference in the ~denote-file-types~ doc string.
+ Thanks to user doolio for spotting the error and reporting it in
+ issue 139 on the GitHub mirror:
+ <https://github.com/protesilaos/denote/issues/139>.
+
+- Cited in the manual's section "Publications about Denote" an article
+ by Mohamed Suliman titled /Managing a bibliography of BiBTeX entries
+ with Denote/ (2022-12-20):
+ <https://www.scss.tcd.ie/~sulimanm/posts/denote-bibliography.html>.
+ If you have published something related to Denote, please let me
+ know and I will add to the list.
+
+- Cited the essay by Summer Emacs titled /An explanation of how I use
+ Emacs/ (2023-05-04):
+
<https://github.com/summeremacs/howiuseemacs/blob/main/full-explanation-of-how-i-use-emacs.org>
+
+- Cited the video series by Stefan Thesing titled /Denote as a
+ Zettelkasten/:
<https://www.thesing-online.de/blog/denote-as-a-zettelkasten/>.
+
+- Added link to Karl Voit's work in the manual's section "Alternative
+ implementations and further reading." Thanks to Norwid Behrnd for
+ the contribution in pull request 123 on the GitHub mirror:
+ <https://github.com/protesilaos/denote/pull/123>.
+
+- Fixed the broken link to jao's blog. Thanks to Tomasz Hołubowicz
+ for the contribution, which was done in pull request 145 on the
+ GitHub mirror: <https://github.com/protesilaos/denote/pull/145>.
+
+- Authored lots of other ancillary changes/features to the code base
+ or the manual (yes, this change log is how I "cut the long store
+ short").
+
* Version 1.2.0 on 2022-12-12
:PROPERTIES:
:CUSTOM_ID: h:92478a05-4a69-413c-8d95-1dacbcf6af2c
diff --git a/README.org b/README.org
index e4a96e5b1f..70346b1059 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 1.2.0
-#+macro: release-date 2022-12-16
-#+macro: development-version 2.0.0-dev
+#+macro: stable-version 2.0.0
+#+macro: release-date 2023-07-21
+#+macro: development-version 2.1.0-dev
#+export_file_name: denote.texi
#+texinfo_filename: denote.info
#+texinfo_dir_category: Emacs misc features
@@ -159,9 +159,6 @@ There are five ways to write a note with Denote: invoke the
~denote~,
function ~denote-org-capture~. We explain all of those in the
subsequent sections.
-[ The ~denote-signature~ and related are part of
-{{{development-version}}}. ]
-
** Standard note creation
:PROPERTIES:
:CUSTOM_ID: h:6a92a8b5-d766-42cc-8e5b-8dc255466a23
@@ -252,7 +249,7 @@ The value is a list of symbols, which includes any of the
following:
notes (Folgezettel). Signatures are not included in a file's front
matter and are not shown in the description of a link. They are
reserved solely for creating a sequence in a file listing, at least
- for the time being. [Part of {{{development-version}}}.]
+ for the time being.
The prompts occur in the given order.
@@ -419,12 +416,11 @@ commands for note creation:
field of the file name and then asks for a title and keywords.
Signatures are arbitrary strings of alphanumeric characters which
can be used to establish sequential relations between file at the
- level of their file name (e.g. 1, 1a, 1b, 1b1, 1b2, ...). [Part of
- {{{development-version}}}.]
+ level of their file name (e.g. 1, 1a, 1b, 1b1, 1b2, ...).
The ~denote-create-note-using-signature~ is an alias of the command
~denote-signature~ intended to make the functionality more
- discoverable. [Also part of {{{development-version}}}.]
+ discoverable.
**** Write your own convenience commands
:PROPERTIES:
@@ -580,8 +576,6 @@ the ~denote-org-capture-specifiers~.
:CUSTOM_ID: h:95b78582-9086-47e8-967f-62373e2369a0
:END:
-[ Part of {{{development-version}}}. ]
-
This section assumes knowledge of how Denote+org-capture work, as
explained in the previous section
([[#h:656c70cd-cf9a-4471-a0b5-4f0aaf60f881][Create note using Org capture]]).
@@ -822,9 +816,6 @@ going through Dired. Since this is specific to the user's
workflow,
it is easier to have some custom code for it. The following should be
added to the user's Denote configuration:
-[ NOTE that the variable ~denote-user-enforced-denote-directory~ is
- part of {{{development-version}}}. ]
-
#+begin_src emacs-lisp
(defvar my-denote-silo-directories
`("/home/prot/Videos/recordings"
@@ -920,8 +911,6 @@ The match is performed with ~string-match-p~.
:CUSTOM_ID: h:c4290e15-e97e-4a9b-b8db-6b9738e37e78
:END:
-[ Part of {{{development-version}}}. ]
-
Denote registers a submenu for the ~menu-bar-mode~. Users will find
the entry called "Denote". From there they can use their pointer to
select a command. For a sample of how this looks, read the
@@ -1000,8 +989,6 @@ identifier based on the following conditions:
variable `denote-directory', increment it such that it becomes
unique.
-[ The check for duplicate identifiers is part of {{{development-version}}}. ]
-
The default =TITLE= is retrieved from a line starting with a title field
in the file's contents, depending on the given file type
([[#h:13218826-56a5-482a-9b91-5b6de4f14261][Front matter]]).
Else, the file name is used as a default value at the minibuffer prompt.
@@ -1047,9 +1034,6 @@ not---manage such files).
:CUSTOM_ID: h:1b6b2c78-42f0-45b8-9ef0-6de21a8b2cde
:END:
-[ The optional =SKIP-FRONT-MATTER-PROMPT= and =NO-UNIQUE-ID-CHECK= are added to
- ~denote-dired-rename-marked-files~ as part of {{{development-version}}}. ]
-
#+findex: denote-dired-rename-marked-files
The ~denote-dired-rename-marked-files~ command renames marked files in
Dired to conform with our file-naming scheme. Specifically, it does
@@ -1190,8 +1174,6 @@ respective front matter.
:CUSTOM_ID: h:85b65995-89fd-4978-bba3-7bb6c8d6f945
:END:
-[ Part of {{{development-version}}}. ]
-
#+findex: denote-change-file-type
The command ~denote-change-file-type~ provides the convenience of
converting a note taken in one file type, say, =.txt= into another
@@ -1247,9 +1229,6 @@ underscore (the separator is inserted automatically).
Each keyword is
a string provided by the user at the relevant prompt which broadly
describes the contents of the entry.
-[ The ~denote-allow-multi-word-keywords~ has a ~nil~ value as part of
- {{{development-version}}}. ]
-
#+vindex: denote-allow-multi-word-keywords
Optionally, when the user option ~denote-allow-multi-word-keywords~ is
non-nil, keywords that need to be more than one-word-long are written
@@ -1328,8 +1307,6 @@ low-tech invention.
:CUSTOM_ID: h:ae8b19a1-7f67-4258-96b3-370a72c43f4e
:END:
-[ Signatures are part of {{{development-version}}}. ]
-
Denote has to be highly opinionated about which characters can be used
in file names and the file's front matter in order to enforce its
file-naming scheme. The variable ~denote-excluded-punctuation-regexp~
@@ -1360,8 +1337,6 @@ When a signature is present, this becomes:
: DATE==SIGNATURE--TITLE__KEYWORDS.EXTENSION
-[ Signatures are part of {{{development-version}}}. ]
-
Field delimiters practically serve as anchors for easier searching.
Consider this example:
@@ -1642,9 +1617,6 @@ other links.
:CUSTOM_ID: h:9bec2c83-36ca-4951-aefc-7187c5463f90
:END:
-[ The ~denote-add-links~ is the new name of ~denote-link-add-links~,
- as part of {{{development-version}}}. ]
-
#+findex: denote-add-links
The command ~denote-add-links~ adds links at point matching a
regular expression or plain string. The links are inserted as a
@@ -1707,9 +1679,6 @@ purposes
([[#h:fc913d54-26c8-4c41-be86-999839e8ad31][Linking notes]]).
:CUSTOM_ID: h:0c1fdaab-5a6b-4792-9694-fed53cd042e6
:END:
-[ The ~denote-add-missing-links~ is the new name of
- ~denote-link-add-missing-links~, as part of {{{development-version}}}. ]
-
#+findex: denote-add-missing-links
As a variation on the ~denote-add-links~ command, one may wish to only
include 'missing links', i.e. links that are not yet present in the
@@ -1811,8 +1780,7 @@ this end, Denote provides two convenience commands:
#+findex: denote-backlinks
The command ~denote-backlinks~ produces a bespoke buffer which
displays backlinks to the current note. A "backlink" is a link back
-to the present entry. [ The ~denote-backlinks~ is the new name of
-~denote-link-backlinks~, as part of {{{development-version}}}.]
+to the present entry.
By default, the backlinks' buffer is designed to display the file name
of the note linking to the current entry. Each file name is presented
@@ -1942,14 +1910,12 @@ For instance, a package such as =marginalia= will
display accurate
annotations, while the =embark= package will be able to work its magic
such as in exporting the list into a filtered Dired buffer (i.e. a
familiar Dired listing with only the files of the current minibuffer
-session). [ The ~denote-find-link~ is the new name of
-~denote-link-find-file~, as part of {{{development-version}}}.]
+session).
#+findex: denote-find-backlink
To visit backlinks to the current note via the minibuffer, use
~denote-find-backlink~. This is an alternative to placing backlinks
-in a dedicated buffer ([[#h:c73f1f68-e214-49d5-b369-e694f6a5d708][The
backlinks' buffer]]). [The command is renamed
-as part of {{{development-version}}}.]
+in a dedicated buffer ([[#h:c73f1f68-e214-49d5-b369-e694f6a5d708][The
backlinks' buffer]]).
** Miscellaneous information about links
:PROPERTIES:
@@ -1966,12 +1932,6 @@ aliased ~denote-link-insert-links-matching-regexp~. The
purpose of
these aliases is to offer alternative, more descriptive names of
select commands.
-[ The ~denote-insert-link~ is the new name of ~denote-link-insert-link~,
- as part of {{{development-version}}}.]
-
-[ The ~denote-show-backlinks-buffer~ is the new name of
- ~denote-link-show-backlinks-buffer~, as part of {{{development-version}}}.]
-
* Fontification in Dired
:PROPERTIES:
:CUSTOM_ID: h:337f9cf0-9f66-45af-b73f-f6370472fb51
@@ -2039,8 +1999,6 @@ its standand attachments' facility).
:CUSTOM_ID: h:3ca4db16-8f26-4d7d-b748-bac48ae32d69
:END:
-[ Part of {{{development-version}}}. ]
-
#+findex: denote-rename-buffer-mode
The ~denote-rename-buffer-mode~ minor mode provides the means to
automatically rename the buffer of a Denote file upon visiting the
@@ -2362,9 +2320,6 @@ It will create a note using the heading's text and tags
for the new
file. The contents of the subtree become the contents of the new note
and are removed from the old one.
-[ NOTE that the variable ~denote-user-enforced-denote-directory~ is
- part of {{{development-version}}}. ]
-
#+begin_src emacs-lisp
(defun my-denote-org-extract-subtree (&optional silo)
"Create new Denote note using current Org subtree.
@@ -3441,7 +3396,7 @@ might change them without further notice.
#+findex: denote-file-has-signature-p
+ Function ~denote-file-has-signature-p~ :: Return non-nil if =FILE=
- has a signature. [Part of {{{development-version}}}.]
+ has a signature.
#+findex: denote-file-has-supported-extension-p
+ Function ~denote-file-has-supported-extension-p~ :: Return non-nil
@@ -3455,7 +3410,7 @@ might change them without further notice.
#+findex: denote-file-type-extensions
+ Function ~denote-file-type-extensions~ :: Return all file type
- extensions in ~denote-file-types~. [Part of {{{development-version}}}.]
+ extensions in ~denote-file-types~.
#+variable: denote-encryption-file-extensions
+ Variable ~denote-encryption-file-extensions~ :: List of strings
@@ -3464,8 +3419,7 @@ might change them without further notice.
#+function: denote-file-type-extensions-with-encryption
+ Function ~denote-file-type-extensions-with-encryption~ :: Derive
~denote-file-type-extensions~ plus ~denote-encryption-file-extensions~.
- [Part of {{{development-version}}}.]
-
+
#+findex: denote-keywords
+ Function ~denote-keywords~ :: Return appropriate list of keyword
candidates. If ~denote-infer-keywords~ is non-nil, infer keywords
@@ -3485,10 +3439,7 @@ might change them without further notice.
([[#h:15719799-a5ff-4e9a-9f10-4ca03ef8f6c5][Maintain separate directories
for notes]]). Custom Lisp code can
~let~ bind the value of the variable ~denote-user-enforced-denote-directory~
to override what this function returns.
-
- [ NOTE that the variable ~denote-user-enforced-denote-directory~ is
- part of {{{development-version}}}. ]
-
+
#+findex: denote-directory-files
+ Function ~denote-directory-files~ :: Return list of absolute file
paths in variable ~denote-directory~. Files only need to have an
@@ -3542,8 +3493,8 @@ might change them without further notice.
=this-is-a-test= to =This is a test=.
#+findex: denote-sluggify-signature
-+ Function ~denote-sluggify-signature~ :: Make STR an appropriate slug
- for signatures. [Part of {{{development-version}}}]
++ Function ~denote-sluggify-signature~ :: Make =STR= an appropriate
+ slug for signatures.
#+findex: denote-sluggify-keywords
+ Function ~denote-sluggify-keywords~ :: Sluggify =KEYWORDS=, which is
@@ -3586,8 +3537,7 @@ might change them without further notice.
#+findex: denote-retrieve-filename-signature
+ Function ~denote-retrieve-filename-signature~ :: Extract signature
- from =FILE= name, if present, else return nil. [Part of
- {{{development-version}}}.]
+ from =FILE= name, if present, else return nil.
#+findex: denote-retrieve-or-create-file-identifier
+ Function ~denote-retrieve-or-create-file-identifier~ :: Return
@@ -3604,9 +3554,7 @@ might change them without further notice.
as an identifier.
- As a fallback, derive an identifier from the current time.
-
- [ The =FILES= argument is part of {{{development-version}}}. ]
-
+
With optional =FILES= as a list of file names, test that the
identifier is unique among them.
@@ -3639,7 +3587,7 @@ might change them without further notice.
#+findex: denote-signature-prompt
+ Function ~denote-signature-prompt~ :: Prompt for signature
- string. [Part of {{{development-version}}}.]
+ string.
#+findex: denote-file-prompt
+ Function ~denote-file-prompt~ :: Prompt for file with identifier in
@@ -3697,7 +3645,7 @@ might change them without further notice.
note after ~denote-rename-file~ (or related) The =FILE=, =TITLE=,
=KEYWORDS=, and =FILE-TYPE= arguments are given by the renaming
command and are used to construct new front matter values if
- appropriate. [Part of {{{development-version}}}.]
+ appropriate.
#+findex: denote-rewrite-keywords
+ Function ~denote-rewrite-keywords~ :: Rewrite =KEYWORDS= in =FILE=
@@ -3705,7 +3653,7 @@ might change them without further notice.
~denote-rewrite-front-matter~ for keywords, but do not ask for
confirmation. This is for use in ~denote-keywords-add~,
~denote-keywords-remove~, ~denote-dired-rename-marked-files~, or
- related. [Part of {{{development-version}}}.]
+ related.
#+findex: denote-update-dired-buffers
+ Function ~denote-update-dired-buffers~ :: Update Dired buffers of
@@ -3869,8 +3817,6 @@ might change them without further notice.
matter =KEYWORDS= for org file type. =KEYWORDS= is a list of
strings. Consult the ~denote-file-types~ for how this is used.
-[ The following two functions are part of {{{development-version}}}. ]
-
#+findex: denote-link-return-links
+ Function ~denote-link-return-links~ :: Return list of links in
current or optional =FILE=. Also see ~denote-link-return-backlinks~.
diff --git a/denote.el b/denote.el
index 01fb006968..322eade3a2 100644
--- a/denote.el
+++ b/denote.el
@@ -6,7 +6,7 @@
;; Maintainer: Denote Development <~protesilaos/denote@lists.sr.ht>
;; URL: https://git.sr.ht/~protesilaos/denote
;; Mailing-List: https://lists.sr.ht/~protesilaos/denote
-;; Version: 1.2.0
+;; Version: 2.0.0
;; Package-Requires: ((emacs "28.1"))
;; This file is NOT part of GNU Emacs.