branch: externals/denote
commit 53b52d56db1402abc5e25f7581b00da986a4d215
Author: Protesilaos Stavrou <i...@protesilaos.com>
Commit: Protesilaos Stavrou <i...@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
