[elpa] externals/denote 53b52d56db 2/3: Document new user option denote-file-name-components-order

[ELPA Syncer]

branch: externals/denote
commit 53b52d56db1402abc5e25f7581b00da986a4d215
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>

    Document new user option denote-file-name-components-order
    
    The new functionality is contributed by Jean-Philippe Gagné Guay in
    pull request 360: <https://github.com/protesilaos/denote/pull/360>.
---
 README.org | 45 ++++++++++++++++++++++++++++++++++++++++++++-
 denote.el  | 45 ++++++++++++++++++++++++++++-----------------
 2 files changed, 72 insertions(+), 18 deletions(-)

diff --git a/README.org b/README.org
index c855831a48..3b952e9a47 100644
--- a/README.org
+++ b/README.org
@@ -1658,7 +1658,8 @@ following file name permutations:
 : DATE==SIGNATURE--TITLE__KEYWORDS.EXT
 : DATE==SIGNATURE__KEYWORDS.EXT
 
-When in doubt, stick to the default design.
+When in doubt, stick to the default design, which is carefully
+considered and works well ([[#h:dc8c40e0-233a-4991-9ad3-2cf5f05ef1cd][Change 
the order of file name components]]).
 
 While Denote is an Emacs package, notes should work long-term and not
 depend on the functionality of a specific program.  The file-naming
@@ -1666,6 +1667,48 @@ scheme we apply guarantees that a listing is readable in 
a variety of
 contexts.  The Denote file-naming scheme is, in essence, an effective,
 low-tech invention.
 
+** Change the order of file name components
+:PROPERTIES:
+:CUSTOM_ID: h:dc8c40e0-233a-4991-9ad3-2cf5f05ef1cd
+:END:
+
+[ Part of {{{development-version}}}. ]
+
+#+vindex: denote-file-name-components-order
+Our standard file-naming scheme prescribes a specific order for the
+file name components ([[#h:4e9c7512-84dc-4dfb-9fa9-e15d51178e5d][The 
file-naming scheme]]). Though we provide the
+user option ~denote-file-name-components-order~ to let the user
+reorder them as they see fit.
+
+The value of this user option is a list of the following symbols:
+
+- ~identifier~: This is the combination of the date and time. When it
+  is the first on the list, it looks like =20240519T073456= and does
+  not have a component separator of its own due its unambiguous
+  format. When it is placed anywhere else in the file name, it is
+  prefixed with =@@=, so it looks like =@@20240519T073456=.
+
+- ~signature~: This is an arbitrary string that can be used to qualify
+  the file in some way, according to the user's methodology (e.g. to
+  add a sequence to notes). The string is always prefixed with the
+  ~==~ to remain unambiguous.
+
+- ~title~: This is an arbitrary string which describes the file. It is
+  always prefixed with =--= to be unambiguous.
+
+- ~keywords~: This is a series of one or more words that succinctly
+  group the file. Multiple keywords are separated by an underscore
+  prefixed to each of them. The file name component is always prefixed
+  with =__=.
+
+All four symbols must appear exactly once. Duplicates are ignored. Any
+missing symbol is added automatically.
+
+Before deciding on this, please consider the longer-term implications
+of file names with varying patterns. Consistency makes things
+predictable and thus easier to find. So pick one order and never touch
+it again. When in doubt, leave the default file-naming scheme as-is.
+
 ** Sluggification of file name components
 :PROPERTIES:
 :CUSTOM_ID: h:ae8b19a1-7f67-4258-96b3-370a72c43f4e
diff --git a/denote.el b/denote.el
index 63a2b9d13b..09948c1ab7 100644
--- a/denote.el
+++ b/denote.el
@@ -289,7 +289,10 @@ Finally, this user option only affects the interactive use 
of the
 Lisp).  In Lisp usage, the behaviour is always what the caller
 specifies, based on the supplied arguments.
 
-Also see `denote-history-completion-in-prompts'."
+Also see `denote-history-completion-in-prompts'.
+
+To change the order of the file name components, refer to
+`denote-file-name-components-order'."
   :group 'denote
   :package-version '(denote . "2.3.0")
   :link '(info-link "(denote) The denote-prompts option")
@@ -304,30 +307,38 @@ Also see `denote-history-completion-in-prompts'."
                      (const :tag "Signature" signature))))
 
 (defcustom denote-file-name-components-order '(identifier signature title 
keywords)
-  "Specify the order of the file name components of new notes.
+  "Specify the order of the file name components.
 
 The value is a list of the following symbols:
 
-- `identifier': An identifier in a file name looks like
-  \"20240101T111111\" if it appears as the first component.
-  Else, it is prepended with \"@@\" if it appears anywhere else
-  in the file name.
+- `identifier': This is the combination of the date and time.  When it
+  is the first on the list, it looks like \"20240519T073456\" and does
+  not have a component separator of its own due its unambiguous format.
+  When it is placed anywhere else in the file name, it is prefixed with
+  \"@@\", so it looks like \"@@20240519T073456\".
+
+- `signature': This is an arbitrary string that can be used to qualify
+  the file in some way, according to the user's methodology (e.g. to add
+  a sequence to notes).  The string is always prefixed with the \"==\"
+  to remain unambiguous.
 
-- `signature': A signature in a file name is an arbitrary string
-  that combines \"==\" with the signature of
-  `denote-signature-prompt'.
+- `title': This is an arbitrary string which describes the file.  It is
+  always prefixed with \"--\" to be unambiguous.
 
-- `title': A title in a file name is an arbitrary string that
-  combines \"--\" with the title of `denote-title-prompt'.
+- `keywords': This is a series of one or more words that succinctly
+  group the file.  Multiple keywords are separated by an underscore
+  prefixed to each of them.  The file name component is always prefixed
+  with \"__\".
 
-- `keywords': Keywords in a file name are represented as a string
-  that combines \"__\" with the keywords of
-  `denote-keywords-prompt' separated with an underscore.
+All four symbols must appear exactly once.  Duplicates are ignored.  Any
+missing symbol is added automatically.
 
-All the symbols above must appear exactly once.  Any symbol
-missing will be added automatically.
+Also see `denote-prompts'.
 
-See also `denote-prompts'."
+Before deciding on this, please consider the longer-term implications
+of file names with varying patterns. Consistency makes things
+predictable and thus easier to find. So pick one order and never touch
+it again. When in doubt, leave the default file-naming scheme as-is."
   :group 'denote
   :package-version '(denote . "3.0.0")
   ;; FIXME 2024-05-19: This technically works to display the user