From 5f10fbf0197b0b51dde5fbd8916d1a881d84c534 Mon Sep 17 00:00:00 2001 From: Protesilaos Stavrou Date: Sun, 12 Nov 2023 15:49:06 +0200 Subject: [PATCH] Update to Denote version 2.1.0 --- CHANGELOG.org | 633 +++++++++++++++++++++++++++++++++++++++++++++++++- README.org | 112 ++------- denote.el | 2 +- 3 files changed, 649 insertions(+), 98 deletions(-) diff --git a/CHANGELOG.org b/CHANGELOG.org index 64bcbed..3cd710e 100644 --- a/CHANGELOG.org +++ b/CHANGELOG.org @@ -9,6 +9,629 @@ project's main git repository: . The newest release is at the top. For further details, please consult the manual: . +* Version 2.1.0 on 2023-11-12 +:PROPERTIES: +:CUSTOM_ID: h:167beb8f-14be-40de-a1f2-d13910924c00 +:END: + +The general theme of this release is improvements to the quality of +life with Denote. While these release notes and the overall +documentation are comprehensive, make no mistake: Denote can be used +with =M-x denote=, =M-x denote-link=, =M-x denote-backlinks=, =M-x +denote-rename-file=. These have been rock solid from the beginning. +Everything else is for more specialised workflows. + +I hope to produce a companion video to this changelog in the coming +days. Though I am still reeling from the injury to my left hand (I +wrote all this to not delay the package any longer). Please check back +in my website's coding blog section to find the follow-up video: +. + +[ Remember to consult the manual whenever you have a question about + Denote. It is comprehensive and, in my opinion, a paradigm of how + free software should be done for the benefit of users. I document + everything in detail and am eager to continue this way. If something + is unclear, contact me in person, use the mailing list, or open an + issue on the GitHub/GitLab mirror. I do not check other fora or + media and will thus not help you there. If you are writing custom + code, remember to read the doc strings. I write them for you too. ] + +** Deprecated the ~denote-allow-multi-word-keywords~ +:PROPERTIES: +:CUSTOM_ID: h:a086d1d2-adb3-4151-a7af-813d79b4b3dc +:END: + +This user option enabled the use of keywords that consisted of +multiple words. Those would be separated by hyphens. Such keywords do +not work as Org =#+filetags= and also mess up with the neat search +semantics of Denote's file-naming scheme where a hyphen prefix +anchors the query to the =TITLE= component of the name. + +Users who absolutely need multi-word keywords are encouraged to use +the new ~denote-file-name-letter-casing~ option. More below. + +** Control the letter casing of file name components +:PROPERTIES: +:CUSTOM_ID: h:29319b8a-698b-4a1c-bab4-7b106a623de8 +:END: + +By default, Denote downcases all components of the file name. The user +option ~denote-file-name-letter-casing~ provides granular control over +this behaviour. + +The value it accepts is an alist where each element is a cons cell of +the form =(COMPONENT . METHOD)=. The manual, or the variable's doc +string, cover the details. The gist is that we can now instruct Denote +to accept input verbatim, such as because we want to apply a +=camelCase= convention or variants thereof. + +Here is an example, where we downcase the title, but preserve the +letter casing of the signature and keyword components with this: + +#+begin_src emacs-lisp +(setq denote-file-name-letter-casing + '((title . downcase) + (signature . verbatim) + (keywords . verbatim) + (t . downcase))) +#+end_src + +Users of the now-deprecated ~denote-allow-multi-word-keywords~ are +encouraged to implement a letter casing convention with the help of +this new user option. + +Relevant sections in the manual: + +- The file-naming scheme: + . +- Contol the letter casing of file names: + + +** The ~denote-dired-mode~ should now work while toggling ~wdired~ +:PROPERTIES: +:CUSTOM_ID: h:18a3b515-9306-4911-ba2d-73e36efbdd32 +:END: + +The writable version of Dired would break the colouration applied by +~denote-dired-mode~. I have arranged for this to not happen anymore, +although it means that I had to add an advice to relevant wdired +symbols because no proper hook is on offer. + +** The "do or create" commands are more intuitive to use +:PROPERTIES: +:CUSTOM_ID: h:5bcdc4b8-ecba-44d7-accc-0b26657aa29b +:END: + +Denote provides several commands with a "do or create" logic. For +example, the ~denote-open-or-create~ prompts for a file to visit: if +something matches the user's input, it is visited in a buffer, +otherwise a new note is created with the given input. Same for +~denote-link-or-create~, mutatis mutandis. + +Before, the "... or create" step did not make it obvious how the +previous search terms could be reused. Whereas now those are set as +the default minibuffer value at the title prompt, meaning that typing +=RET= at the empty prompt will use that value, while =M-n= +(~next-history-element~ with default settings) will put the text into +the prompt for further editing. + +I will answer this because I get asked about it: we still refrain from +creating the new note outright because the search terms are not +necessarily suitable for a new title. Remember that Denote's file name +is optimised for searching: =-word= is specific to the title, =_word= +to the keywords, and ==word= to the signature. Combine this with the +~orderless~ package and you frequently type something like =_jou -he= +to match a file with the =journal= keyword and the word =hesitation= +in its title. + +*IMPORTANT NOTE:* some minibuffer completion User Interfaces preselect +the first completion candidate, which is not always the same as the +default value. Check with your UI of choice how to pass a default +value and/or provide an empty input. For example, with the ~vertico~ +package one can move up from the first candidate to select the prompt +itself (the counter switches from =1/N= to =*/N=). + +Relevant sections in the manual: + +- Open an existing note or create it if missing: + . +- Link to a note or create it if missing: + . + +*** New "... or create with command" features for more flexibility +:PROPERTIES: +:CUSTOM_ID: h:6f475151-9d64-4dfb-8c59-694c93d56ce8 +:END: + +As part of the wider "do or create" feature set, Denote provides the +option to run a specific note-creating command instead of just using +the standard ~denote~ one. For example, it is possible to call the +~denote-subdirectory~ command to pick a subdirectory of the +~denote-directory~ for the new note. Commands providing this facility +are ~denote-open-or-create-with-command~ and ~denote-link-after-creating-with-command~. + +Thanks to Vedang Manerikar for fixing a broken ~if~ clause during +development: . + +** The title and signature prompts use minibuffer completion +:PROPERTIES: +:CUSTOM_ID: h:429847c8-ebf4-4b23-a597-5276309ef61a +:END: + +All Denote minibuffer prompts come with their own history. This means +that =M-p= (~previous-history-element~) and =M-n= +(~next-history-element~) always return relevant input. + +The title and signature prompts now reuse their input history to +provide completion. This means that the user can quickly access +previous inputs, either to pass them directly or edit them further +before inputting them. + +[ Use the built-in ~savehist-mode~ to persist histories across sessions. ] + +Remember to check with your minibuffer UI on how to input empty +values at the prompt, should you ever need to do so. + +For posterity, I first implemented this in commit =0d855bb=. However, +it did not work with the default minibuffer because the =SPC= key +performs completion (popping up the Completions buffer). So users +could not easily input an arbitrary string for the title/signature. I +thus reverted that commit in =9f692cb=. + +[ The bug was reported by Suhail Singh on the mailing list: + . ] + +Stefan Monnier suggested the use of the ~minibuffer-with-setup-hook~, +which lets us disable =SPC= completion for the purposes of these +functions. This is most welcome as the functionality is nice to have. +Stefan's feedback was provided on the emacs-devel mailing list: +. + +** Create a note with the region's contents +:PROPERTIES: +:CUSTOM_ID: h:ae798d1f-6fa2-4d99-91c9-0d5eb18b1bb0 +:END: + +The command ~denote-region~ takes the contents of the active region +and then prompts for a title and keywords. Once a new note is +created, it inserts the contents of the region therein. This is +useful to quickly elaborate on some snippet of text or capture it for +future reference. + +It also provides the ~denote-region-after-new-note-functions~ abnormal +hook. Read the manual for more: +. + +** Comprehensive refinements to the ~denote-rename-buffer-mode~ +:PROPERTIES: +:CUSTOM_ID: h:91b3ba9f-8b10-4f1c-a08b-70f5e7140923 +:END: + +This is an opt-in feature that automatically renames the buffer of +newly visited Denote files according to the user's preferences. Not to +be confused with renaming files: buffers are internal to Emacs. Enable +it at startup by adding this to your configuration file: + +#+begin_src emacs-lisp +(denote-rename-buffer-mode 1) +#+end_src + +Relevant entries in the manual: + +- Automatically rename Denote buffers: + . +- The ~denote-rename-buffer-format~ option: + . + +*** The ~denote-rename-buffer-format~ option +:PROPERTIES: +:CUSTOM_ID: h:beeafe57-f110-4c11-87e7-10f682ca2386 +:END: + +The user option ~denote-rename-buffer-format~ controls how the +function ~denote-rename-buffer~ chooses the name of the +buffer-to-be-renamed. This function is the one used by the +~denote-rename-buffer-mode~. + +Users may want, for example, to include some text that makes Denote +buffers stand out, such as a =[D]= prefix. Examples: + +#+begin_src emacs-lisp +;; Use the title (default) +(setq denote-rename-buffer-format "%t") + +;; Use the title and keywords with some emoji in between. +(setq denote-rename-buffer-format "%t 🤨 %k") + +;; Use the title with a literal "[D]" before it +(setq denote-rename-buffer-format "[D] %t") +#+end_src + +Users who need yet more flexibility are best served by writing their +own function and assigning it to the ~denote-rename-buffer-function~ +(in such a case, please contact me as I am curious to know what the +underlying need is). + +The manual or doc string of ~denote-rename-buffer-format~ cover the +technicalities of the available format specifiers. + +Thanks to Jean-Philippe Gagné Guay for intermediately refining parts +of the code. This was done in pull request 177 on the GitHub mirror: +. + +Thanks to Vedang Manerikar for ensuring that the string of the buffer +is trimmed so that it never starts with an empty space (those buffers +count as "internal" to Emacs and are not shown to the user): +. + +*** The ~denote-rename-buffer-mode~ also works with unsaved buffers +:PROPERTIES: +:CUSTOM_ID: h:e65bb546-af22-45fb-a918-d0e621b0e415 +:END: + +Internal refinements to a Denote Lisp macro make this minor mode also +work with new and unsaved Denote buffers. Whereas before only the +buffers of existing files would be renamed. + +** Denote's renaming facilities are better than ever +:PROPERTIES: +:CUSTOM_ID: h:703b9021-f917-4b3f-9406-14992b2a4fe8 +:END: + +Denote's value proposition is its efficient file-naming scheme that +makes it easier to retrieve files even with rudimentary search tools. +We provide several commands to rename existing files according to this +scheme. The underlying file type does not matter (e.g. I use Denote to +name my video files). + +Relevant sections in the manual: + +- Renaming files: + . +- Front matter: + . + +*** Rename like an expert with ~denote-rename-no-confirm~ +:PROPERTIES: +:CUSTOM_ID: h:8798dd8c-819d-4fda-9865-77d9734da28c +:END: + +By default, the ~denote-rename-file~ command asks for a final +confirmation before carrying out its function. The new user option +~denote-rename-no-confirm~ can be bound to a non-nil value to skip +that step. + +This only applies to ~denote-rename-file~. Other commands that rename +files in bulk never prompt for such confirmation (it would make them +cumbersome to use, plus it is assumed that the user who performs a +batch operation understands the implications). + +*** The ~denote-rename-file~ command prompts for a signature +:PROPERTIES: +:CUSTOM_ID: h:e4e7e3d8-40e3-4f58-a19f-df34ccbfdbbd +:END: + +This command used to only ask for a title and keywords. Now it allows +to use a signature as well. An empty input means that the signature is +ignored. AGAIN, please check with your minibuffer completion UI on how +to input an empty value, otherwise you will not get what you expect. + +*** Rename mutliple files sequentially with ~denote-dired-rename-files~ +:PROPERTIES: +:CUSTOM_ID: h:dcb623aa-fc4d-4d84-80e4-a540b6dbb144 +:END: + +This provides the same interface as ~denote-rename-file~, only it +works over a list of marked Dired files. + +Internally, the prompts for title, keywords, and signature are +improved to display the underlying file that is affected by the +current operation. As the user renames files, the prompts reflect +which one is current. + +*** The name of ~denote-dired-rename-marked-files~ has changed +:PROPERTIES: +:CUSTOM_ID: h:f9a16fc1-840d-400f-a5ae-a7791fac441f +:END: + +It is now called ~denote-dired-rename-marked-files-with-keywords~ to +better communicate what it does. In short, this is a quick way to add +the given keywords to a list of files, converting them to the Denote +file-naming scheme in case they are not already using it. For the full +interactive power, use the aforementioned ~denote-dired-rename-files~. + +*** The ~denote-rename-file-using-front-matter~ can be used without saving its buffer +:PROPERTIES: +:CUSTOM_ID: h:bfc194c2-5980-482a-aa1c-feb4ced992d1 +:END: + +This is now possible because of changes to underlying functions (a +Denote Lisp macro---not to bother you with technicalities). + +Same principle for ~denote-rename-file-using-front-matter~. + +*** The name of ~denote-change-file-type~ has changed +:PROPERTIES: +:CUSTOM_ID: h:3bf4b6c4-8399-4d5d-8df1-6495f5bfc579 +:END: + +It is now called ~denote-change-file-type-and-front-matter~ to avoid +confusion as to whether Denote converts files from one format to +another (there are specialised tools for that). + +*** Renaming a file returns the new file path for programmatic use +:PROPERTIES: +:CUSTOM_ID: h:1d7bffd1-e422-420d-b453-9a36dd8508f7 +:END: + +Thanks to mentalisttraceur for requesting this feature in issue 183 on +the GitHub mirror: . + +** Link to a file with a signature +:PROPERTIES: +:CUSTOM_ID: h:b154ef64-c3b4-4e15-b533-c59d5b2ebf6b +:END: + +The ~denote-link-with-signature~ command prompts for a file that has a +=SIGNATURE= component and links to it. The link's description includes +the text of the signature as well as the title. + +Thanks to Mark Olson for mentioning this idea. It was done in issue +167 on the GitHub mirror: . + +I implemented it live, while also refactoring relevant parts of the +code to be more abstract/reusable: +. + +Thanks to Alan Schmitt for spotting and fixing a regression caused by +the above: +. + +** Renaming GPG or Age encrypted file works as expected +:PROPERTIES: +:CUSTOM_ID: h:9ceaf432-797c-46e5-aaf8-d7180ad66689 +:END: + +Emacs can seamlessly visit a =.gpg= or =.age= file. Denote has nothing +to do with encryption, though it takes care to recognise the +underlying file type and to perform its work accordingly. However, +prior versions of Denote contained a bug in how file extensions were +handled: it would keep the encryption extension but remove the file +type extension before it (so ".org.gpg" would wrongly become ".gpg"). + +Thanks to Jens Östlund for reporting a bug with ~denote-keywords-add~ +on an encrypted file, which prompted me to investigate this further +and fix the issue holistically. This was done in issue 172 on the +GitHub mirror: . + +Interested parties are advised to check the two new public functions, +~denote-get-file-extension~ and ~denote-get-file-extension-sans-encryption~, +for the implementation details. In short, we had a problem with all +operations that needed to retrieve the file extension when that +included an encryption component. + +** The optional ~denote-journal-extras~ +:PROPERTIES: +:CUSTOM_ID: h:54723661-31f8-4cab-9be5-4cab19e44dc7 +:END: + +The manual of Denote has long provided code samples to achieve +particularised results. Among those were snippets to streamline the +use of Denote for journaling. + +To make things even easier for users, we now have the +=denote-journal-extras.el=. It consolidates the rich corpus of +documented snippets into an easy-to-use and formally maintained +package. Thanks to Vedang Manerikar for providing the impetus for this +process. This was done on the mailing list: +. + +The new file is optional. It can be loaded thus: + +#+begin_src emacs-lisp +(require 'denote-journal-extras) +#+end_src + +The main idea is to quickly create journal entries. Check the manual +for the details, including the commands to use and the variables to +configure: . + +Thanks to Kostas Andreadis for working on a comment I had included in +a working state of the code about the inclusion of templates. Kostas +made it possible to use the Denote template prompt (per the +~denote-templates~ user option) as part of the creation of a new +journal entry. This was done in pull request 173 on the GitHub mirror: +. The change is less +than 15 lines and thus Kostas does not need to assign copyright to the +Free Software Foundation. + +Also thanks to TJ Stankus for reporting a case where +~denote-journal-extras-title-format~ did not accept a ~nil~ value (as +it should). This was done in issue 176 on the GitHub mirror: +. + +** The optional ~denote-silo-extras~ +:PROPERTIES: +:CUSTOM_ID: h:618495d2-0c5b-48b4-af88-56f3d969697c +:END: + +This is the same idea as with the =denote-journal-extras.el=: we had +the code in the manual and are now formally distributing it. Thanks +again to Vedang Manerikar for initiating this process. It was done on +the mailing list: +. + +Use this optional feature with: + +#+begin_src emacs-lisp +(require 'denote-silo-extras) +#+end_src + +Consult the manual for the details: +. + +** The infrastructure for unique identifiers is more robust +:PROPERTIES: +:CUSTOM_ID: h:1d538d7f-52e6-4653-b057-c62606752934 +:END: + +For Denote version =2.0.0= I introduced a general scheme intended to +avoid scenaria where duplicate identifiers could be created (thus +breaking a premise of Denote). Jean-Philippe Gagné Guay iterated over +the code to make it more robust and to fix some of the cases I had not +accounted for. This was done in pull request 159 on the GitHub mirror: +. Same idea in pull +request 187: . + +** For developers or advanced users +:PROPERTIES: +:CUSTOM_ID: h:9031dc82-ab75-438c-a2c8-a1250ae48671 +:END: + +Denote has a clean code base with small and composable functions. This +encourages hackability. Each definition in the source is documented, +while the manual provides an overview of every public symbol. + +- Added :: ~denote-get-file-extension~, + ~denote-get-file-extension-sans-encryption~, + ~denote-keywords-combine~, + ~denote-retrieve-keywords-value-as-string~, + ~denote-title-prompt-current-default~, ~denote-command-prompt~. + +- Refactored :: ~denote-all-files~, ~denote-signature-prompt~, + ~denote-file-prompt~, ~denote-title-prompt~, + ~denote-rewrite-front-matter~. + +Please read their documentation strings for the details. Or check the +manual: . + +** Check out the ~denote-explore~ package by Peter Prevos +:PROPERTIES: +:CUSTOM_ID: h:759d0276-17e8-4461-9ee4-b4d07840dd7a +:END: + +Peter posted this on the mailing list and I asked if it was okay to +mention it in the release notes of Denote. If you have a relevant +announcement to make, consider sending it to our mailing list. + +#+begin_quote +Hi folks, + +I have just updated the denote-explore package: +https://github.com/pprevos/denote-explore + +It does three things: + +1. Summary statistics: Count and visualise keywords and note types +2. Random walks: Generate new ideas using serendipity +3. Network visualisation: Visualise your Denote network of links + +It contains a rudimentary network visualisation function, relying +on the R language. I will need some D3.js expertise to improve the +visualisation. + +There should be a way to generate the basic network structure just +using Elisp and feeding a JSON to D3.js. + +Regards + +P:) +#+end_quote + +** Miscellaneous +:PROPERTIES: +:CUSTOM_ID: h:01dc6bb0-53ac-43e1-b12e-484c99a6c2a7 +:END: + +- During this release cycle, I made lots of changes that in one way or + another related to the ~denote-file-prompt~. It was relying on a + =project.el= mechanism that did not allow us to do everything we + needed. I have thus arranged for it to use the standard + ~completing-read~ mechanism. There are subtle differences in + behaviour, though the core idea is the same. This change fixes a few + not-so-obvious bugs. Interested parties are advised to refer to the + message in commit =50d1bbdf1e8ffe0f449f2f5da02f9b70322fff7d=. + +- All commands that use the ~denote~ function internally (i.e. + anything that creates a new note) call the + ~denote-after-new-note-hook~ as part of their work. This hook is + mostly intended for advanced users who want to do something after a + new note is produced. + +- The ~menu-bar-mode~ submenu of Denote is now positioned where it + should be after the "Tools". Thanks to Noboru Ota for the patch: + . + +- The ~menu-bar-mode~ entry of Denote includes the new commands. This + is a nice way to discover more of what Denote can do. + +- The commands ~denote-backlinks-prev~ and ~denote-backlinks-next~ are + only meant to be used inside the Denote backlinks buffer. As such, + they now produce an error when called elsewhere (I wish I could hide + them from =M-x= altogether). + +- The ~denote-extract-keywords-from-front-matter~ always returns a + list, thus avoiding an erroneous case. Thanks to Vedang Manerikar + for fixing the bug: . + +- The =T= in the Denote identifier component now has its own face: + ~denote-faces-time-delimiter~. This is used by the backlinks buffer + and the ~denote-dired-mode~. The idea is to introduce a subtle + distinction between the date and time constituents of the + identifier. Those who want the =T= to be the same colour as the rest + of the identifier, can make the ~denote-faces-time-delimiter~ + inherit the ~denote-faces-date~. For example: + + #+begin_src emacs-lisp + (set-face-attribute 'denote-faces-time-delimiter nil :inherit 'denote-faces-date) + #+end_src + + Thanks to Jean-Charles Bagneris for sending this patch: + . + +- Fixed a ~nil~ file expansion in the function + ~denote--extract-title-from-file-history~. Thanks to ezchi for + bringing this matter to my attention. It was done in issue 166 on + the GitHub mirror: + . + +- A link can be created from inside an ~org-capture~ buffer. This + means that we can call ~denote-link~ (and related) while capturing a + new note with ~org-capture~. Thanks to Peter Smith for reporting the + bug in issue 186 on the GitHub mirror: + . + +- We stopped using ~vc-rename-file~ to rename files. The reason is + that it requires the buffer to be saved, but we do not want that + after modifying the front matter because we want to give the user a + chance to confirm what happened. Thanks to Frédéric Willem for + reporting the problem in issue 185 on the GitHub mirror: + . + +- Thanks to Ivan Sokolov for removing a double negative logic in a + snippet. This was done in pull request 162 on the GitHub mirror: + . + +** Git commits +:PROPERTIES: +:CUSTOM_ID: h:d8f30943-70dd-45fe-8cf1-4c3918152aeb +:END: + +Just an overview of what we did. Every contribution matters. + +#+begin_src +~/Git/Projects/denote $ git shortlog 2.0.0..2.1.0 --summary --numbered + 153 Protesilaos Stavrou + 15 Jean-Philippe Gagné Guay + 5 Vedang Manerikar + 1 Alan Schmitt + 1 Ivan Sokolov + 1 Jean-Charles Bagneris + 1 Kostas Andreadis + 1 Noboru Ota + 1 Peter Prevos +#+end_src + * Version 2.0.0 on 2023-07-21 :PROPERTIES: :CUSTOM_ID: h:3f17bf03-4c47-4410-abf8-1db4a0ac7775 @@ -70,7 +693,7 @@ Read the original announcement: 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. @@ -228,7 +851,7 @@ 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: - + - - - @@ -308,7 +931,7 @@ problem and discussing it with me in issue 135 on the GitHub mirror: 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 @@ -529,11 +1152,11 @@ request of Alan Schmitt: 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": . The issue is diff --git a/README.org b/README.org index 0948397..f9a6248 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 2.0.0 -#+macro: release-date 2023-07-21 -#+macro: development-version 2.1.0-dev +#+macro: stable-version 2.1.0 +#+macro: release-date 2023-11-12 +#+macro: development-version 2.2.0-dev #+export_file_name: denote.texi #+texinfo_filename: denote.info #+texinfo_dir_category: Emacs misc features @@ -175,7 +175,7 @@ explained: [[#h:4e9c7512-84dc-4dfb-9fa9-e15d51178e5d][The file naming scheme]] #+vindex: denote-after-new-note-hook The ~denote~ command runs the hook ~denote-after-new-note-hook~ after -creating the new note. [ Part of {{{development-version}}}. ] +creating the new note. The file type of the new note is determined by the user option ~denote-file-type~ ([[#h:13218826-56a5-482a-9b91-5b6de4f14261][Front matter]]). @@ -256,8 +256,7 @@ The value is a list of symbols, which includes any of the following: matter. They are reserved solely for creating a sequence in a file listing, at least for the time being. To insert a link that includes the signature, use the command ~denote-link-with-signature~ - ([[#h:066e5221-9844-474b-8858-398398646f86][Insert link to file with signature]]). [ The ~denote-link-with-signature~ - is part of {{{development-version}}}. ] + ([[#h:066e5221-9844-474b-8858-398398646f86][Insert link to file with signature]]). The prompts occur in the given order. @@ -671,8 +670,6 @@ treated the same as =:title= or ~t~). :CUSTOM_ID: h:ad91ca39-cf10-4e16-b224-fdf78f093883 :END: -[ Rewritten and expanded as part of {{{development-version}}}. ] - #+findex: denote-open-or-create #+findex: denote-open-or-create-with-command Sometimes it is necessary to briefly interrupt the ongoing writing @@ -849,7 +846,7 @@ sufficient. The manual shall be expanded accordingly. :CUSTOM_ID: h:0f72e6ea-97f0-42e1-8fd4-0684af0422e0 :END: -[ As part of {{{development-version}}}, the contents of this section +[ As part of version 2.1.0, the contents of this section are formally provided in the file =denote-silo-extras.el=. We keep this here for existing users. Otherwise consult the new entry in the manual ([[#h:e43baf95-f201-4fec-8620-c0eb5eaa1c85][The =denote-silo-extras.el=]]). ] @@ -926,8 +923,6 @@ To see another example of a wrapper function that uses :CUSTOM_ID: h:e43baf95-f201-4fec-8620-c0eb5eaa1c85 :END: -[ Part of {{{development-version}}}. ] - 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: @@ -1052,9 +1047,6 @@ line or switching between then with commands like ~switch-to-buffer~. :CUSTOM_ID: h:7cc9e000-806a-48da-945c-711bbc7426b0 :END: -[ Refactored as part of {{{development-version}}} to prompt for a - signature (plus other refinements under the hood). ] - #+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 @@ -1141,8 +1133,6 @@ all the requisite mechanisms in place. :CUSTOM_ID: h:a2ae9090-c49e-4b32-bcf5-eb8944241fd7 :END: -[ Part of {{{development-version}}}. ] - The default behaviour of the ~denote-rename-file~ command is to ask for an affirmative answer as a final step before changing the file name and, where relevant, inserting or updating the corresponding @@ -1164,10 +1154,6 @@ remain unsaved)). :CUSTOM_ID: h:3ab08ff4-81fa-4d24-99cb-79f97c13a373 :END: -[ Refactored as part of {{{development-version}}} to not require - saving the buffer before renaming it. This means that Denote can now - correctly read unsaved file contents. ] - #+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 @@ -1223,8 +1209,6 @@ the like. :CUSTOM_ID: h:1b6b2c78-42f0-45b8-9ef0-6de21a8b2cde :END: -[ Part of {{{development-version}}}. ] - #+findex: denote-dired-rename-files The command ~denote-dired-rename-files~ renames the files that are marked in a Dired buffer. Its behaviour is similar to the @@ -1246,13 +1230,6 @@ check the command ~denote-dired-rename-marked-files~: :CUSTOM_ID: h:f365ff7e-2140-4e14-a92f-666ae97382a4 :END: -[ The command ~denote-dired-rename-marked-files~ is now called - ~denote-dired-rename-marked-files-with-keywords~ to better describe - what it actually does. To rename multiple Dired marked files while - being asked about each file's specifics, use the command - ~denote-dired-rename-files~ ([[#h:1b6b2c78-42f0-45b8-9ef0-6de21a8b2cde][Rename multiple files interactively]]). - This change is done as part of {{{development-version}}}. ] - #+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 @@ -1287,12 +1264,6 @@ so by writing keywords to them. Specifically, it does the following: :CUSTOM_ID: h:ea5673cd-e6ca-4c42-a066-07dc6c9d57f8 :END: -[ Refactored as part of {{{development-version}}} to not require - saving the buffer before renaming it. This means that Denote can now - correctly read unsaved file contents. Also, the command itself is - simplified to be a wrapper of ~denote-rename-file-using-front-matter~ - for the Dired marked files. ] - #+findex: denote-dired-rename-marked-files-using-front-matter As already noted, Denote can rename a file based on the data in its front matter ([[#h:3ab08ff4-81fa-4d24-99cb-79f97c13a373][Rename a single file based on its front matter]]). The @@ -1312,10 +1283,6 @@ possible to rename them interactively ([[#h:1b6b2c78-42f0-45b8-9ef0-6de21a8b2cde :CUSTOM_ID: h:85b65995-89fd-4978-bba3-7bb6c8d6f945 :END: -[ The command is renamed from ~denote-change-file-type~ to - ~denote-change-file-type-and-front-matter~ as part of {{{development-version}}} - because some users thought it was performing full text conversion. ] - #+findex: denote-change-file-type-and-front-matter The command ~denote-change-file-type-and-front-matter~ provides the convenience of converting a note taken in one file type, say, =.txt= @@ -1378,8 +1345,6 @@ through Denote files. Users who need to compose a keyword out of multiple words are encouraged to apply a letter casing convention such as camelCase/CamelCase and set the ~denote-file-name-letter-casing~ user option accordingly ([[#h:6ae1ab8c-5e36-4216-8e93-f37f4447582c][Contol the letter casing of file names]]). -[ The ~denote-allow-multi-word-keywords~ is obsolete as part of - {{{development-version}}}. ] #+vindex: denote-file-type The =EXTENSION= is the file type. By default, it is =.org= (~org-mode~) @@ -1475,8 +1440,6 @@ keyword. :CUSTOM_ID: h:6ae1ab8c-5e36-4216-8e93-f37f4447582c :END: -[ Part of {{{development-version}}}. ] - #+vindex: denote-file-name-letter-casing The user option ~denote-file-name-letter-casing~ controls the letter casing of the individual components of file names ([[#h:4e9c7512-84dc-4dfb-9fa9-e15d51178e5d][The file-naming scheme]]). @@ -1792,10 +1755,6 @@ region is active, its text is used as the link's description instead. If the active region has no text, the inserted link uses just the identifier, as with the =C-u= prefix mentioned above. -[ For more advanced uses, refer to the doc string of the ~denote-link~ - function. The ~denote-link~ gained new arguments as part of - {{{development-version}}}. ] - Inserted links are automatically buttonized and remain active for as long as the buffer is available. In Org this is handled by the major mode: the =denote:= hyperlink type works exactly like the standard @@ -1888,8 +1847,6 @@ purposes ([[#h:fc913d54-26c8-4c41-be86-999839e8ad31][Linking notes]]). :CUSTOM_ID: h:066e5221-9844-474b-8858-398398646f86 :END: -[ Part of {{{development-version}}}. ] - #+findex: denote-link-with-signature The command ~denote-link-with-signature~ prompts for a file among those that contain a ===SIGNATURE= and inserts a link to it. The @@ -2159,8 +2116,6 @@ in a dedicated buffer ([[#h:c73f1f68-e214-49d5-b369-e694f6a5d708][The backlinks' :CUSTOM_ID: h:b6056e6b-93df-4e6b-a778-eebd105bac46 :END: -[ Rewritten and expanded as part of {{{development-version}}}. ] - #+findex: denote-link-after-creating #+findex: denote-link-after-creating-with-command #+findex: denote-link-or-create @@ -2234,8 +2189,6 @@ select commands. :CUSTOM_ID: h:98c732ac-da0e-4ebd-a0e3-5c47f9075e51 :END: -[ Part of {{{development-version}}}. ] - #+vindex: denote-commands-for-new-notes The user option ~denote-commands-for-new-notes~ specifies a list of commands that are available at the ~denote-command-prompt~. This @@ -2317,8 +2270,6 @@ its standand attachments' facility). :CUSTOM_ID: h:3ca4db16-8f26-4d7d-b748-bac48ae32d69 :END: -[ Refactored and expanded as part of {{{development-version}}}. ] - #+findex: denote-rename-buffer-mode The minor mode ~denote-rename-buffer-mode~ provides the means to automatically rename the buffer of a Denote file upon visiting the @@ -2350,8 +2301,6 @@ available to all programs. :CUSTOM_ID: h:35507c18-35b1-41b9-9d80-52f54fcef3cb :END: -[ Part of {{{development-version}}}. ] - The user option ~denote-rename-buffer-format~ controls how the function ~denote-rename-buffer~ chooses the name of the buffer-to-be-renamed. @@ -2532,10 +2481,6 @@ specialised third-party packages. This section covers the details. :CUSTOM_ID: h:4a6d92dd-19eb-4fcc-a7b5-05ce04da3a92 :END: -[ Rewritten as part of {{{development-version}}}, which now includes - the optional =denote-journal-extras.el= file that the user can load - as part of their Denote setup. ] - Denote provides a general-purpose mechanism to create new files that broadly count as "notes" ([[#h:17896c8c-d97a-4faa-abf6-31df99746ca6][Points of entry]]). Such files can be daily entries in a journal. While it is possible to use the generic @@ -2620,7 +2565,7 @@ by calling ~denote-journal-extra-new-entry~ (as described above). :CUSTOM_ID: h:4af1f81e-e93a-43cc-b344-960032a16d42 :END: -[ Revised as part of {{{development-version}}} to conform with how we +[ Revised as part of version 2.1.0 to conform with how we now tend to the needs of users who use Denote for journaling purposes ([[#h:4a6d92dd-19eb-4fcc-a7b5-05ce04da3a92][Keep a journal or diary]]). ] @@ -2688,10 +2633,6 @@ Sources for ~tmr~: :CUSTOM_ID: h:2f8090f1-50af-4965-9771-d5a91a0a87bd :END: -[ Rewritten as part of {{{development-version}}} to include the - ~denote-region~ command which supersedes a custom function that was - once documented herein. ] - #+findex: denote-region The command ~denote-region~ takes the contents of the active region and then prompts for a title and keywords. Once a new note is @@ -3686,14 +3627,14 @@ might change them without further notice. + Function ~denote-get-file-extension~ :: Return extension of =FILE= with dot included. Account for ~denote-encryption-file-extensions~. In other words, return something like =.org.gpg= if it is part of - the file, else return =.org=. [ Part of {{{development-version}}}. ] + the file, else return =.org=. #+findex: denote-get-file-extension-sans-encryption + Function ~denote-get-file-extension-sans-encryption~ :: Return extension of =FILE= with dot included and without the encryption part. Build on top of ~denote-get-file-extension~ though always return something like =.org= even if the actual file extension is - =.org.gpg=. [ Part of {{{development-version}}}. ] + =.org.gpg=. #+findex: denote-keywords + Function ~denote-keywords~ :: Return appropriate list of keyword @@ -3710,8 +3651,7 @@ might change them without further notice. #+findex: denote-keywords-combine + Function ~denote-keywords-combine~ :: Combine =KEYWORDS= list of strings into a single string. Keywords are separated by the - underscore character, per the Denote file-naming scheme. [ Made - public as part of {{{development-version}}}. ] + underscore character, per the Denote file-naming scheme. #+findex: denote-directory + Function ~denote-directory~ :: Return path of the variable @@ -3750,8 +3690,7 @@ might change them without further notice. #+findex: denote-all-files + Function ~denote-all-files~ :: Return the list of Denote files in the variable ~denote-directory~. With optional =OMIT-CURRENT=, do - not include the current Denote file in the returned list. [ The - =OMIT-CURRENT= is part of {{{development-version}}}. ] + not include the current Denote file in the returned list. #+findex: denote-file-name-relative-to-denote-directory + Function ~denote-file-name-relative-to-denote-directory~ :: Return @@ -3860,8 +3799,7 @@ might change them without further notice. + Function ~denote-retrieve-keywords-value~ :: Return keywords value from =FILE= front matter per =FILE-TYPE=. The return value is a list of strings. To get a combined string the way it would appear in a - Denote file name, use ~denote-retrieve-keywords-value-as-string~ [ - That function is part of {{{development-version}}}. ]. + Denote file name, use ~denote-retrieve-keywords-value-as-string~. #+findex: denote-retrieve-keywords-value-as-string + Function ~denote-retrieve-keywords-value-as-string~ :: Return @@ -3869,7 +3807,7 @@ might change them without further notice. value is a string, with the underscrore as a separator between individual keywords. To get a list of strings instead, use ~denote-retrieve-keywords-value~ (the current function uses that - internally). [ Part of {{{development-version}}}. ] + internally). #+findex: denote-retrieve-keywords-line + Function ~denote-retrieve-keywords-line~ :: Return keywords line @@ -3881,16 +3819,12 @@ might change them without further notice. value. With optional =PROMPT-TEXT= use it in the minibuffer instead of the default prompt. Previous inputs at this prompt are available for minibuffer completion. Consider ~savehist-mode~ to persist - minibuffer histories between sessions. [ The =DEFAULT-SIGNATURE= and - =PROMPT-TEXT= arguments, as well as previous input completion, are - added as part of {{{development-version}}}. ] + minibuffer histories between sessions. #+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. [ Refactored - as part of {{{development-version}}} because the old =INITIAL-INPUT= - argument was not actually used anywhere. ] + filter the candidates per the given regular expression. #+findex: denote-keywords-prompt + Function ~denote-keywords-prompt~ :: Prompt for one or more @@ -3899,9 +3833,7 @@ might change them without further notice. =PROMPT-TEXT=, use it to prompt the user for keywords. Else use a generic prompt. Process the return value with ~denote-keywords-sort~ and sort with ~string-collate-lessp~ if the user option - ~denote-sort-keywords~ is non-nil. [ Refactored as part of - {{{development-version}}} to refine how the sorting is done and to - include the optional =PROMPT-TEXT=. ] + ~denote-sort-keywords~ is non-nil. #+findex: denote-title-prompt + Function ~denote-title-prompt~ :: Read file title for ~denote~. With @@ -3909,16 +3841,14 @@ might change them without further notice. =PROMPT-TEXT= use it in the minibuffer instead of the generic prompt. Previous inputs at this prompt are available for minibuffer completion. Consider ~savehist-mode~ to persist minibuffer histories - between sessions. [ The =PROMPT-TEXT= and completion of previous - inputs are part of {{{development-version}}}. ] + between sessions. #+vindex: denote-title-prompt-current-default + Variable ~denote-title-prompt-current-default~ :: Currently bound default title for ~denote-title-prompt~. Set the value of this variable within the lexical scope of a command that needs to supply a default title before calling ~denote-title-prompt~ and use - ~unwind-protect~ to set its value back to nil. [ Part of - {{{development-version}}}. ] + ~unwind-protect~ to set its value back to nil. #+findex: denote-file-type-prompt + Function ~denote-file-type-prompt~ :: Prompt for ~denote-file-type~. @@ -3935,8 +3865,7 @@ might change them without further notice. #+findex: denote-command-prompt + Function ~denote-command-prompt~ :: Prompt for command among - ~denote-commands-for-new-notes~ ([[#h:17896c8c-d97a-4faa-abf6-31df99746ca6][Points of entry]]). [ Part of - {{{development-version}}}. ] + ~denote-commands-for-new-notes~ ([[#h:17896c8c-d97a-4faa-abf6-31df99746ca6][Points of entry]]). #+findex: denote-prompt-for-date-return-id + Function ~denote-prompt-for-date-return-id~ :: Use @@ -3967,8 +3896,7 @@ might change them without further notice. command and are used to construct new front matter values if appropriate. With optional =NO-CONFIRM=, do not prompt to confirm the rewriting of the front matter. Otherwise produce a ~y-or-n-p~ prompt - to that effect. [ The =NO-CONFIRM= argument is part of - {{{development-version}}}. ] + to that effect. #+findex: denote-rewrite-keywords + Function ~denote-rewrite-keywords~ :: Rewrite =KEYWORDS= in =FILE= diff --git a/denote.el b/denote.el index 5ae72ad..440496c 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: 2.0.0 +;; Version: 2.1.0 ;; Package-Requires: ((emacs "28.1")) ;; This file is NOT part of GNU Emacs.