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