diff --git a/CHANGELOG.org b/CHANGELOG.org index 5676a9a..c5d66f6 100644 --- a/CHANGELOG.org +++ b/CHANGELOG.org @@ -9,7 +9,287 @@ project's main git repository: . The newest release is at the top. For further details, please consult the manual: . +* Version 0.2.0 on 2022-07-04 +:PROPERTIES: +:CUSTOM_ID: h:2002fee6-3f0c-48be-9727-6d4e20f34856 +:END: + ++ Version =0.1.0= (from 2022-06-27) was never built as a package. The + reason is that the GNU ELPA machinery reads the =Version:= header of + the main file, not the git tag. As the original commit in =denote.el= + included =Version: 0.1.0=, GNU ELPA rightly tries to build the package + using that reference. But because at that time I had not yet updated + the Copyright header to name the Free Software Foundation, the package + could not be prepared. As such, please consider this release to be + the "first formal stable version". My apologies for the delay, + contrary to what was promised in the last change log entry. + + - Prospective users are advised to read the manual: + . For a video demonstration: + . + + - Thanks to Benjamin Kästner for reporting the issue with the GNU ELPA + package on the mailing list: + . + ++ Originally, Denote was designed to only work with notes in a flat + directory. With code contributions from Jean-Philippe Gagné Guay, + support for subdirectories of the user option ~denote-directory~ is + now available. This covers the case of creating links between notes, + following them, and viewing the backlinks' buffer of the current + entry. + + - Thanks to Jean-Philippe for the contributions which took place on + the GitHub mirror: + + + + + + + + + - Jean-Philippe Gagné Guay has assigned copyright to the Free Software + Foundation. This is a prerequisite to contribute code to any + package on the official GNU ELPA archive (and to emacs.git for that + matter). + ++ The new ~denote-subdirectory~ command lets the user select a directory + to place the new note in. Available candidates are the value of the + ~denote-directory~ as well as all of its subdirectories, minus =.git=. + In future versions, we will consider how to provide a blocklist or a + regexp filter for the user to specify which subdirectories should be + omitted from minibuffer completion. Please consider providing your + feedback on the technicalities. + + - Thanks to Jean-Philippe Gagné Guay and Shreyas Ragavan for the + feedback in issue 31 on the GitHub mirror: + . + + - Thanks to Jean-Philippe Gagné Guay for fixing a potential problem in + how directories are represented when commands enter the directory + instead of selecting it (again, at the GitHub mirror): + . + ++ From 2022-06-24 to 2022-07-03, Denote provided support for links + between Org notes that leveraged the =id:= hyperlink type. + Discussions on the mailing list and the GitHub mirror revealed the + longer-term problems in our implementation. In the Annex below, I + provide my detailed opinion on the matter. The gist is that Denote + does not---and will not---create =id:= links between its notes, but + shall use the =denote:= hyperlink type instead (which works like the + standard =file:= type). As the Annex explains, Denote is not org-roam + lite and we try not to engender such false expectations. + + - Despite the fact that the relevant patches are no longer applicable, + I wish to thank Kaushal Modi and Jean-Philippe Gagné Guay for their + contributions over at the GitHub mirror: + + + + + + ++ The user option ~denote-date-format~ controls how the date and time is + recorded in the file's contents (what we call "front matter"). When + nil (the default value), we use a file-type-specific format (also + check the user option ~denote-file-type~): + + - For Org, an inactive timestamp is used, such as =[2022-06-30 Wed 15:31]=. + + - For Markdown, the RFC3339 standard is applied: =2022-06-30T15:48:00+03:00=. + + - For plain text, the format is that of ISO 8601: =2022-06-30=. + + If the value is a string, ignore the above and use it instead. The + string must include format specifiers for the date. These are described + in the doc string of ~format-time-string~. + + The ~denote-date-format~ supersedes the now obsolete + ~denote-front-matter-date-format~. + + Thanks to Peter Prevos and Kaushal Modi for their feedback in issue 27 + on the GitHub mirror: . + ++ All the faces we define are now declared in the =denote-faces.el= + file. The fontification rules are shared by ~denote-dired-mode~ and + the backlinks' buffer (invoked by ~denote-link-backlinks~ and + controlled by the user option ~denote-link-fontify-backlinks~). The + current list of faces: + + - ~denote-faces-date~ + - ~denote-faces-delimiter~ + - ~denote-faces-extension~ + - ~denote-faces-keywords~ + - ~denote-faces-subdirectory~ + - ~denote-faces-time~ + - ~denote-faces-title~ + ++ Named the mailing list address as the =Maintainer:= of Denote. + Together with the other package headers, they help the user find our + primary sources and/or communication channels. This change conforms + with work being done upstream in package.el by Philip Kaludercic. I + was informed about it here: + . + ++ Fixed how keywords are inferred and combined. The previous code did not + work properly when the user option =denote-infer-keywords= was nil. + It would return a list of symbols, with the parentheses, whereas the + file name needs a string where each keyword is delimited by an + underscore. + ++ Simplified how information in the front matter is retrieved. It fixes + cases where, for example, a special character at the end of the title + was ignored. Thanks to Jean-Philippe Gagné Guay for the patch over at + the GitHub mirror: . + ++ Rewrote parts of the manual in the interest of clarity. + +** Annex about discontinuing support for org-id +:PROPERTIES: +:CUSTOM_ID: h:647d6155-1ac3-4ecb-bd4c-06d09fecd3ba +:END: + +My thanks for their participation in the discussions go to Jean-Philippe +Gagné Guay, Kaushal Modi, and Shreyas Ragavan. + +#+begin_example +commit f35ef05cb451f265213c3aafc1e62c425b1ff043 +Author: Protesilaos Stavrou +Date: Sun Jul 3 17:34:38 2022 +0300 + + REMOVE support for 'id:' hyperlink types + + The original idea was to support the 'org-id' library on the premise + that it makes Denote a good Emacs citizen. However, discussions on the + mailing list[0] and the GitHub mirror[1] have made it clear to me that + 'org-id' is not consistent with Denote's emphasis on simplicity. + + To support the way 'org-id' works, we will eventually have to develop + some caching mechanism, just how the org-roam package does it. This is + because the variable 'org-id-extra-files' needs to be kept up-to-date + whenever an operation on a file is performed. At scale, this sort of + monitoring requires specialised software. Such a mechanism is outside + the scope of Denote---if you need a db, use org-roam which is already + great. + + [0] + + [1] + + Quote of what I wrote on the GitHub mirror issue 29: + + [ggjp] This is what I was implying. That we are, in fact, + providing an option that is not viable long-term, but keeping + the option for expert users who will be able to handle this. + And we should warn about this clearly in the doc of that option. + + [protesilaos] What you write here @ggjp and what @shrysr explained + tells me that those expert users will need to be real experts. To + put it concretely, I am an experienced Emacs user with no + programming background, who has written several Emacs + packages (including the modus-themes which are built into Emacs), + but I have zero knowledge of using a db or of handling things with + python and the like. So if I opt in to 'denote-link-use-org-id' I + will eventually run into problems that my non-existent skills will + prevent me from solving. At that point, I will just use org-roam + which already handles this use-case in a competent way (and has a + massive community to rely on in case I need further support). + + If each package needs to write its own optimisations and maintain + its own cache, to me this shows that 'org-id' is not good enough for + the time being: more work needs to be done in org.git to provide a + universal solution. + + I wanted to support 'org-id' by default on the premise that Denote + must be a good Emacs citizen which interoperates with the rest of + the wider ecosystem. But if 'org-id' leaves something to be + desired, then that goal is not worth pursuing: we add complexity to + our code, offer an option that we cannot genuinely/adequately + support, and make usage of it contingent on reading the docs and + having a high level of expertise. + + I think being a good Emacs citizen is a laudable principle. In this + case, the right thing to do is to recommend the use of org-roam + instead of trying to accommodate 'org-id'. As such, I have now + changed my mind and think we should remove what we previously added. + + For some context here: the reason I never used org-roam is + because (i) it is Org-specific whereas I write notes in different + file types and (ii) I did not want to ever rely on a db or + equivalent dependency. + + + + README.org | 226 ++++++++--------------------------------------------- + denote-link.el | 99 ++++++----------------- + denote-retrieve.el | 2 +- + denote.el | 14 +--- + 4 files changed, 63 insertions(+), 278 deletions(-) +#+end_example + +Followed up by my explanation: + +#+begin_src text +> can we not have denote style links to be default for (de)notes - and +> explicitly supported, while if they need to, users can still link +> denote org files via org-id to any other notes/files (and vice versa) +> -- in which case performance + testing for org-id driven linking is +> not within Denote's purview at all? + +The formal support for `id:` links was added shortly before the release +of version `0.1.0`. In the days prior, we supported what you describe +via the manual. The user could change the `denote-org-front-matter` +variable to include a `PROPERTIES` drawer. This possibility still +exists, though yesterday I removed the relevant entry from the manual. +This way only the real do-it-yourself experts will go down that path. + +My concern here is with managing expectations. If our Org notes are +superficially the same as org-roam's, an unsuspecting user may think +that Denote is an org-roam lite. We will thus get issues/requests, such +as those already mentioned in this GitHub repo, about migrating from +org-roam to Denote. While there are similarities, Denote is not a +minimalist org-roam and I would not like to encourage the idea of +treating the two as interchangeable. + +Doing things half-way-through is a way to create false expectations. A +package on GNU ELPA must be usable by users of all skill levels. If the +functionality we provide is incomplete and needs to be covered by +user-level tweaks, we are excluding a portion of the user base while +still assuming the maintenance burden. If someone trusts Denote to, +say, write a 1000 notes, we do not want to surprise them after the fact. +Imagine if the reported issues that triggered this change happened 6 +months into one's daily usage of Denote: it wouldn't be nice. + +Setting the right expectations is a matter of responsibility: we let the +user make a more informed choice and show respect for their time. It +also makes it easier for me to keep Denote's scope in check by not +supporting every little extra that Org implements. The premier Org +extension is org-roam: we do not need another one (or, if we do, I am +not the one to implement it). + +,* * * + +Some comments on the `denote:` hyperlink type for Org as they may be +relevant in this context: + +,* It is meant to work like the standard `file:` type. This means that + it links to a file, while it can also have additional search + parameters, as explained in the Org manual. Evaluate: + + (info "(org) Search Options") + +,* It does not read the front matter, but only the file name. You can + create a note as usual, delete all its contents, save it, and try to + link to it from another note. It works. + +,* Exporting now works like the `file:` type for HTML, LaTeX, Texinfo, + and Markdown. Technically, it also supports the ASCII backend but the + format of the output could be tweaked further. + +There may be refinements to be made, which is okay as that is part of a +maintainer's duties. +#+end_src + * Version 0.1.0 on 2022-06-27 +:PROPERTIES: +:CUSTOM_ID: h:33939747-ad60-4913-a170-4b2f48f139cc +:END: The present entry is intended for early adopters of Denote who may have not caught up with the latest developments. Prospective users are diff --git a/README.org b/README.org index 2948672..fcf9cee 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 0.1.0 -#+macro: release-date 2022-06-27 -#+macro: development-version 0.2.0-dev +#+macro: stable-version 0.2.0 +#+macro: release-date 2022-07-04 +#+macro: development-version 0.3.0-dev #+export_file_name: denote.texi #+texinfo_filename: denote.info #+texinfo_dir_category: Emacs misc features @@ -216,8 +216,6 @@ The ~denote-create-note-using-date~ is an alias of ~denote-date~. :CUSTOM_ID: h:588c1f96-ca01-4c2c-be7a-ca6359c9465b :END: -[ The ~denote-subdirectory~ is part of {{{development-version}}} ] - The ~denote-subdirectory~ command is like ~denote~ except it prompts for a directory to place the new note in ([[#h:6a92a8b5-d766-42cc-8e5b-8dc255466a23][Standard note creation]]). Candidates are the value of the user option ~denote-directory~ and any @@ -354,8 +352,6 @@ Either way, Denote takes care to only consider "notes" as valid candidates in the relevant operations and will omit other files or directories. -[ Subdirectory support is part of {{{development-version}}} ] - Every note produced by Denote follows this pattern ([[#h:17896c8c-d97a-4faa-abf6-31df99746ca6][Points of entry]]): : DATE--TITLE__KEYWORDS.EXTENSION @@ -536,23 +532,11 @@ If the value is a string, ignore the above and use it instead. The string must include format specifiers for the date. These are described in the doc string of ~format-time-string~.. -[ DEV NOTE: ~denote-date-format~ supersedes the now obsolete - ~denote-front-matter-date-format~ as part of {{{development-version}}} ] - * Linking notes :PROPERTIES: :CUSTOM_ID: h:fc913d54-26c8-4c41-be86-999839e8ad31 :END: -[ Support for =id:= type notes is REMOVED as part of - {{{development-version}}}. The reason is that to fully support org-id - we need to change Denote's scope. That will never be reconciled with - the project's principles. Users of the =id:= functionality are - advised to use org-roam: it has first-class support for it, is a major - project, and has a massive community. My sincere apologies for not - foreseeing this and for breaking some user configurations in the - process. ] - #+findex: denote-link The ~denote-link~ command inserts a link at point to an entry specified at the minibuffer prompt. Links are formatted depending on the file diff --git a/denote-dired.el b/denote-dired.el index 933e696..db8c763 100644 --- a/denote-dired.el +++ b/denote-dired.el @@ -5,8 +5,8 @@ ;; Author: Protesilaos Stavrou ;; Maintainer: Denote Development <~protesilaos/denote@lists.sr.ht> ;; URL: https://git.sr.ht/~protesilaos/denote -;; Version: 0.1.0 ;; Mailing-List: https://lists.sr.ht/~protesilaos/denote +;; Version: 0.2.0 ;; Package-Requires: ((emacs "27.2")) ;; This file is NOT part of GNU Emacs. diff --git a/denote-faces.el b/denote-faces.el index fee2c8d..2d8c0b4 100644 --- a/denote-faces.el +++ b/denote-faces.el @@ -5,8 +5,8 @@ ;; Author: Protesilaos Stavrou ;; Maintainer: Denote Development <~protesilaos/denote@lists.sr.ht> ;; URL: https://git.sr.ht/~protesilaos/denote -;; Version: 0.1.0 ;; Mailing-List: https://lists.sr.ht/~protesilaos/denote +;; Version: 0.2.0 ;; Package-Requires: ((emacs "27.2")) ;; This file is NOT part of GNU Emacs. diff --git a/denote-link.el b/denote-link.el index aa7be7f..06c947f 100644 --- a/denote-link.el +++ b/denote-link.el @@ -5,8 +5,8 @@ ;; Author: Protesilaos Stavrou ;; Maintainer: Denote Development <~protesilaos/denote@lists.sr.ht> ;; URL: https://git.sr.ht/~protesilaos/denote -;; Version: 0.1.0 ;; Mailing-List: https://lists.sr.ht/~protesilaos/denote +;; Version: 0.2.0 ;; Package-Requires: ((emacs "27.2")) ;; This file is NOT part of GNU Emacs. diff --git a/denote-org-capture.el b/denote-org-capture.el index db2657e..639ad62 100644 --- a/denote-org-capture.el +++ b/denote-org-capture.el @@ -5,8 +5,8 @@ ;; Author: Protesilaos Stavrou ;; Maintainer: Denote Development <~protesilaos/denote@lists.sr.ht> ;; URL: https://git.sr.ht/~protesilaos/denote -;; Version: 0.1.0 ;; Mailing-List: https://lists.sr.ht/~protesilaos/denote +;; Version: 0.2.0 ;; Package-Requires: ((emacs "27.2")) ;; This file is NOT part of GNU Emacs. diff --git a/denote-retrieve.el b/denote-retrieve.el index d0e0a10..4fde844 100644 --- a/denote-retrieve.el +++ b/denote-retrieve.el @@ -5,8 +5,8 @@ ;; Author: Protesilaos Stavrou ;; Maintainer: Denote Development <~protesilaos/denote@lists.sr.ht> ;; URL: https://git.sr.ht/~protesilaos/denote -;; Version: 0.1.0 ;; Mailing-List: https://lists.sr.ht/~protesilaos/denote +;; Version: 0.2.0 ;; Package-Requires: ((emacs "27.2")) ;; This file is NOT part of GNU Emacs. diff --git a/denote.el b/denote.el index 1c5428e..12abafb 100644 --- a/denote.el +++ b/denote.el @@ -5,8 +5,8 @@ ;; Author: Protesilaos Stavrou ;; Maintainer: Denote Development <~protesilaos/denote@lists.sr.ht> ;; URL: https://git.sr.ht/~protesilaos/denote -;; Version: 0.1.0 ;; Mailing-List: https://lists.sr.ht/~protesilaos/denote +;; Version: 0.2.0 ;; Package-Requires: ((emacs "27.2")) ;; This file is NOT part of GNU Emacs.