branch: externals/denote
commit f806ed7db0933dcce158ff7480261e9e33f547b3
Author: Protesilaos Stavrou <i...@protesilaos.com>
Commit: Protesilaos Stavrou <i...@protesilaos.com>
Add user options for the denote-sort-dired sorting functions per file name
component
---
README.org | 31 +++++++++++++++++++++++++++++--
denote-sort.el | 26 +++++++++++++++++++++++++-
2 files changed, 54 insertions(+), 3 deletions(-)
diff --git a/README.org b/README.org
index ed1dfacce9..b41066b151 100644
--- a/README.org
+++ b/README.org
@@ -3410,8 +3410,9 @@ given file name component
([[#h:4e9c7512-84dc-4dfb-9fa9-e15d51178e5d][The file-n
#+findex: denote-sort-dired
The command ~denote-sort-dired~ produces a Dired file listing with a
-flat, filtered, and sorted set of files from the ~denote-directory~.
-It does so by means of three minibuffer prompts:
+flat, filtered, and sorted set of files from the ~denote-directory~
+([[#h:c958e087-1d23-4a25-afdd-db7bf5606b4c][Define a sorting function per
component]]). It does so by means of
+three minibuffer prompts:
1. It first asks for a regular expression with which to match Denote
files. Remember that due to Denote's efficient file-naming scheme,
@@ -3430,6 +3431,32 @@ The resulting Dired listing is a regular Dired buffer,
unlike that of
The dynamic Org blocks that Denote defines to insert file contents
also use this feature ([[#h:f15fa143-5036-416f-9bff-1bcabbb03456][Org dynamic
block to insert file contents]]).
+** Define a sorting function per component
+:PROPERTIES:
+:CUSTOM_ID: h:c958e087-1d23-4a25-afdd-db7bf5606b4c
+:END:
+
+[ Part of {{{development-version}}}. ]
+
+When sorting by =title=, =keywords=, or =signature= with the
+~denote-sort-dired~ command, Denote will internally apply a sorting
+function that is specific to each component. These are subject to user
+configuration:
+
+#+vindex: denote-sort-title-comparison-function
+- ~denote-sort-title-comparison-function~
+
+#+vindex: denote-sort-keywords-comparison-function
+- ~denote-sort-keywords-comparison-function~
+
+#+vindex: denote-sort-signature-comparison-function
+- ~denote-sort-signature-comparison-function~
+
+By default, all these user options use the same sorting function,
+namely ~string-collate-lessp~. Users who have specific needs for any
+of those file name components can write their own sorting algorithms
+([[#h:95345870-4ccd-484f-9adf-de4747ad5760][Sort signatures that include
Luhmann-style sequences]]).
+
* Keep a journal or diary
:PROPERTIES:
:CUSTOM_ID: h:4a6d92dd-19eb-4fcc-a7b5-05ce04da3a92
diff --git a/denote-sort.el b/denote-sort.el
index cc272b0a52..681b6b57fa 100644
--- a/denote-sort.el
+++ b/denote-sort.el
@@ -42,6 +42,30 @@
(defvar denote-sort-components '(title keywords signature identifier)
"List of sorting keys applicable for `denote-sort-files' and related.")
+(defcustom denote-sort-title-comparison-function
denote-sort-comparison-function
+ "Function to sort the TITLE component in file names.
+The function accepts two arguments and must return a non-nil value if
+the first argument is smaller than the second one."
+ :type 'function
+ :package-version '(denote . "3.1.0")
+ :group 'denote-sort)
+
+(defcustom denote-sort-keywords-comparison-function
denote-sort-comparison-function
+ "Function to sort the KEYWORDS component in file names.
+The function accepts two arguments and must return a non-nil value if
+the first argument is smaller than the second one."
+ :type 'function
+ :package-version '(denote . "3.1.0")
+ :group 'denote-sort)
+
+(defcustom denote-sort-signature-comparison-function
denote-sort-comparison-function
+ "Function to sort the SIGNATURE component in file names.
+The function accepts two arguments and must return a non-nil value if
+the first argument is smaller than the second one."
+ :type 'function
+ :package-version '(denote . "3.1.0")
+ :group 'denote-sort)
+
;; NOTE 2023-12-04: We can have compound sorting algorithms such as
;; title+signature, but I want to keep this simple for the time being.
;; Let us first hear from users to understand if there is a real need
@@ -62,7 +86,7 @@ two title values."
(cond
(one-empty-p nil)
((and (not one-empty-p) two-empty-p) one)
- (t (funcall denote-sort-comparison-function one two)))))))
+ (t (funcall ,(intern (format "denote-sort-%s-comparison-function"
component)) one two)))))))
;; TODO 2023-12-04: Subject to the above NOTE, we can also sort by
;; directory and by file length.
