From d1dcab874ecc0d408d7959a0f64e3b51b6d2f7bb Mon Sep 17 00:00:00 2001 From: Protesilaos Stavrou Date: Wed, 24 Sep 2025 13:20:33 +0300 Subject: [PATCH] Make denote-query-sorting docs more consistent between manual and docstring --- README.org | 10 ++++++---- denote.el | 27 ++++++++++++++++----------- 2 files changed, 22 insertions(+), 15 deletions(-) diff --git a/README.org b/README.org index 0b4a1b9..d85b907 100644 --- a/README.org +++ b/README.org @@ -4171,15 +4171,17 @@ they can perform. #+vindex: denote-query-sorting The user option ~denote-query-sorting~ controls the order of matching files in a query buffer (buffers that use the ~denote-query-mode~. The -applies to the buffer that is produced by query links, backlinks, and -the ~denote-grep~ command: +applies to the buffer that is produced by query links for file +contents, backlinks, and the ~denote-grep~ command: - [[#h:d9a84289-2f73-4ef9-b4f0-9a0aa3e9bf0d][Add a query link]]. - [[#h:c73f1f68-e214-49d5-b369-e694f6a5d708][The backlinks' buffer]]. - [[#h:e71c9d14-7e88-4386-91d0-9ad249947077][Use ~denote-grep~ to search inside files]]. -By default, no sorting of matching files is performed. They appear in -the query buffer in the order they were retrieved. +By default (a ~nil~ value), no sorting of matching files is performed. +Files are displayed in the order they are returned by the search +program (which often, but not always, means they are sorted by file +name). #+vindex: denote-sort-components The ~denote-query-sorting~ can be set to a symbol among those listed diff --git a/denote.el b/denote.el index f2b8f2e..7820dac 100644 --- a/denote.el +++ b/denote.el @@ -5544,21 +5544,26 @@ This is used by the commands `denote-backlinks', `denote-grep', (defcustom denote-query-sorting nil "How to sort files in query buffers. +This applies to buffers generated by the `denote-grep' command, query +links for file contents, as well as backlinks. -This applies to buffers generated by `denote-grep' and query links, as -well as backlinks. +By default (a nil value), no sorting of matching files is performed. +Files are displayed in the order they are returned by the search +program (which often, but not always, means they are sorted by file +name). -By default, no sorting is performed, so matching files are displayed as -they are returned by the search program (which often, but not always, -means they are sorted by file name). +The value can be a symbol among those listed in the value of the +variable `denote-sort-components'. Files will then be sorted according +to the given file name component or the relevant method (e.g. randomly +for the `random' symbol). -The user can set this variable to a non-nil value in order to sort the -files in a custom manner. The value is passed as the COMPONENT argument -to the `denote-sort-files' function. That means it can be a symbol -among `denote-sort-components' or a function which performs the sorting. +The value may also be a custom function. It takes two arguments, as +described by `sort' (internally, the function responsible is the +`denote-sort-files'). -The user can also call the command `denote-query-sort-last-search' in -order to sort file names interactively in the query buffer." +Whatever the value of `denote-query-sorting', users may change the +sorting of query buffers on demand by calling the command +`denote-query-sort-last-search'." :type '(radio (const :tag "Don't sort (default)" nil) (const :tag "Sort by identifier" identifier)