[elpa] externals/denote 7cba33e08e 119/355: LAST BREAKING CHANGE to file-naming scheme

[ELPA Syncer]

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

    LAST BREAKING CHANGE to file-naming scheme
    
    The pattern now is:
    
        DATE--TITLE__KEYWORDS.EXTENSION
    
    Multiple keywords are separated by underscores.  A multi-word keyword is
    separated by hyphens:
    
        _two_keywords
        one-keyword-many-words
    
    Also see the enforcement of sluggified keywords in commit 6000313.
---
 README.org | 80 +++++++++++++++++++++++++++++++++++++++-----------------------
 denote.el  | 10 ++++----
 2 files changed, 56 insertions(+), 34 deletions(-)

diff --git a/README.org b/README.org
index 41a7d5ffe1..9063211eb3 100644
--- a/README.org
+++ b/README.org
@@ -72,10 +72,10 @@ modify this GNU manual.”
 
 Denote is a simple, yet effective note-taking tool for Emacs.  It is
 based on the principle that notes must follow a predictable and
-descriptive file-naming scheme.  The file name alone should offer a
-clear indication of what the note is about, without reference to any
-other metadata.  Denote basically streamlines the creation of such
-files.
+descriptive naming convention ([[#h:4e9c7512-84dc-4dfb-9fa9-e15d51178e5d][The 
file-naming scheme]]).  The file name
+alone should offer a clear indication of what the note is about, without
+reference to any other metadata.  Denote basically streamlines the
+creation of such files.
 
 What Denote prioritizes with the enforcement of a strict file-naming
 scheme is portability.  Notes can be accessed, filtered, and understood
@@ -84,21 +84,27 @@ Org, and the like are excellent programs).
 
 Denote only has a strong opinion about the file name.  It otherwise is
 flexible and poses no constraints on the desired workflow.  Denote has
-no mechanism to test for adherence to a given note-taking method, such
+no mechanism to test for adherence with a given note-taking method, such
 as that of Zettelkasten (i.e. the contemporary digital equivalent of
 Niklas Luhmann's methodology).  It is possible to employ such a method,
 though it is ultimately up to the user to apply the requisite rigor.
 What matters for our purposes is that Denote is not a zettelkasten
-implementation per se.
+implementation per se, does not compel the user to manage a restricted
+vocabulary for tagging purposes, will not insist on mutual exclusivity
+between keyword subsets, and so on.
 
-By default, Denote creates note files using the =.org= extension.
+Denote does not manage a database and does not try to be smart about how
+notes are handled.  It creates notes and otherwise delegates extra
+functionality to other tools.
+
+By default, Denote writes note files using the =.org= extension.
 However, Denote does not depend on org.el or any of its accoutrements
 and extensions.  Users are given the option to change from Org to either
 Markdown (=.md=) or Plain Text (=.txt=), as explained further in the
 manual (search for ~denote-file-type~).
 
 "Denote" is the familiar word, though it also is a play on to the "note"
-concept.  Plus, we can come up with acronyms (of dubious utility) like:
+concept.  Plus, we can come up with acronyms of dubious utility like:
 
 + Don't Ever Note Only The Ephemeral
 + Denote Everything Neatly; Omit The Excesses
@@ -111,9 +117,13 @@ Obligations, Tasks, Engagements...
 :CUSTOM_ID: h:4e9c7512-84dc-4dfb-9fa9-e15d51178e5d
 :END:
 
-Every note produced by Denote follows this pattern:
+#+vindex: denote-directory
+Notes are stored as a flat list in the ~denote-directory~ (i.e. no
+subdirectories).  The default path is =~/Documents/notes=.
 
-: DATE--TITLE--KEYWORDS.EXTENSION
+Every note produced by Denote follows this pattern 
([[#h:17896c8c-d97a-4faa-abf6-31df99746ca6][Points of entry]]):
+
+: DATE--TITLE__KEYWORDS.EXTENSION
 
 The =DATE= field represents the date in year-month-day format followed
 by the capital letter =T= (for "time") and the current time in
@@ -121,37 +131,49 @@ hour-minute-second notation.  The presentation is compact:
 =20220531T091625=.  The =DATE= serves as the unique identifier of each
 note.
 
-The =TITLE= field is the title of the note, as provided by the user,
-that automatically gets downcased and hyphenated.  An entry about
-"Economics in the Euro Area" produces an =economics-in-the-euro-area=
-string for the =TITLE= of the file name.
+The =TITLE= field is the title of the note, as provided by the user.  It
+automatically gets downcased and hyphenated.  An entry about "Economics
+in the Euro Area" produces an =economics-in-the-euro-area= string for
+the =TITLE= of the file name.
 
-The =KEYWORDS= field consists of one or more entries demarcated by a
-plus sign (the separator is inserted automatically).  Each keyword is a
+The =KEYWORDS= field consists of one or more entries demarcated by an
+underscore (the separator is inserted automatically).  Each keyword is a
 string provided by the user at the relevant prompt which broadly
 describes the contents of the entry.  Keywords that need to be more than
-one-word-long must be written with an underscore.  So when
-=emacs_library= appears in a file name, it is interpreted as a single
-keyword, whereas =emacs+library= are two distinct keywords.
+one-word-long must be written with hyphens: any other character, such as
+spaces or the plus sign is converted into a hyphen.  So when
+=emacs_library= appears in a file name, it is interpreted as two
+distinct keywords, whereas =emacs-library= is one keyword.  This is
+reflected in how the keywords are recorded in the note 
([[#h:13218826-56a5-482a-9b91-5b6de4f14261][Front matter]]).
 
 #+vindex: denote-file-type
 The =EXTENSION= is the file type.  By default, it is =.org= (~org-mode~)
 though the user option ~denote-file-type~ provides support for Markdown
-(=.md= which runs ~markdown-mode~) and plain text (=.txt= via
-~text-mode~).  Consult its doc string for the minutia.
+with YAML or TOML variants (=.md= which runs ~markdown-mode~) and plain
+text (=.txt= via ~text-mode~).  Consult its doc string for the minutia.
+While files end in the =.org= extension by default, the Denote code base
+does not actually depend on org.el and/or its accoutrements.
 
 Examples:
 
-: 20220107T124941--plentiful-and-predictable-liquidity--economics.org
-: 20220214T104945--git-patch-formatting--emacs+git.md
-: 20220420T113805--this-is-a-test--three_word_keyword.txt
+: 20220610T043241--initial-thoughts-on-the-zettelkasten-method__notetaking.org
+: 20220610T062201--define-custom-org-hyperlink-type__denote_emacs_package.md
+: 20220610T162327--on-hierarchy-and-taxis__notetaking_philosophy.txt
 
-While files end in the =.org= extension by default, the Denote code base
-does not actually depend on org.el and/or its accoutrements.
+The different field separators, namely =--= and =__= introduce an
+efficient way to anchor searches (such as with Emacs commands like
+~isearch~ or from the command-line with ~find~ and related).  A query
+for =_word= always matches a keyword, while a regexp in the form of,
+say, ="\\([0-9T]+?\\)--\\(.*?\\)_"= captures the date in group =\1= and
+the title in =\2= (test any regular expression in the current buffer by
+invoking =M-x re-builder=).
 
-#+vindex: denote-directory
-Notes are stored as a flat list in the ~denote-directory~ (i.e. no
-subdirectories).  The default path is =~/Documents/notes=.
+[[#h:8ed2bb6f-b5be-4711-82e9-8bee5bb06ece][Extending Denote]].
+
+While Denote is an Emacs package, notes should work long-term and not
+depend on the functionality of a specific program.  The file-naming
+scheme we apply guarantees that a listing is readable in a variety of
+contexts.
 
 ** Sluggified title and keywords
 :PROPERTIES:
diff --git a/denote.el b/denote.el
index 19e578811a..a305cfa81b 100644
--- a/denote.el
+++ b/denote.el
@@ -166,11 +166,11 @@ is suspended: we use whatever the user wants."
   "Regular expression to match `denote--id'.")
 
 (defconst denote--file-regexp
-  (concat denote--id-regexp "\\(--\\)\\(.*\\)\\(--\\)")
+  (concat denote--id-regexp "\\(--\\)\\(.*\\)\\(__\\)")
   "Regular expression to match file names from `denote'.")
 
 (defconst denote--keyword-regexp
-  (concat denote--file-regexp "\\([0-9A-Za-z_+]*\\)\\(\\.?.*\\)")
+  (concat denote--file-regexp "\\([0-9A-Za-z_]*\\)\\(\\.?.*\\)")
   "Regular expression to match `denote-keywords'.")
 
 (defconst denote--punctuation-regexp "[][{}!@#$%^&*()_=+'\"?,.\|;:~`‘’“”]*"
@@ -275,7 +275,7 @@ With optional N, search in the Nth line from point."
   "Extract keywords from `denote--directory-files'."
   (let ((sequence (denote--keywords-in-files)))
     (mapcan (lambda (s)
-              (split-string s "+" t))
+              (split-string s "_" t))
             sequence)))
 
 (defun denote-keywords ()
@@ -311,7 +311,7 @@ output is sorted with `string-lessp'."
   "Format KEYWORDS output of `denote--keywords-prompt'."
   (if (and (> (length keywords) 1)
            (not (stringp keywords)))
-      (mapconcat #'downcase keywords "+")
+      (mapconcat #'downcase keywords "_")
     keywords))
 
 (defun denote--keywords-add-to-history (keywords)
@@ -348,7 +348,7 @@ include the starting dot or the return value of
                  (denote--keywords-combine keywords)
                keywords))
         (ext (or extension (denote--file-extension))))
-    (format "%s%s--%s--%s%s" path id slug kws ext)))
+    (format "%s%s--%s__%s%s" path id slug kws ext)))
 
 (defun denote--map-quote-downcase (seq)
   "Quote and downcase elements in SEQ."