branch: externals/denote
commit 97e8c30bcf0d01e6f550fddac401a851ea652211
Author: Protesilaos Stavrou <i...@protesilaos.com>
Commit: Protesilaos Stavrou <i...@protesilaos.com>
Rewrite the package Overview
---
README.org | 89 +++++++++++++++++++++++++++++++++++---------------------------
denote.el | 78 ++++++++++++++++++++++++++++++++++--------------------
2 files changed, 101 insertions(+), 66 deletions(-)
diff --git a/README.org b/README.org
index b86e939d92..89cbc5588f 100644
--- a/README.org
+++ b/README.org
@@ -70,47 +70,60 @@ modify this GNU manual.”
:CUSTOM_ID: h:a09b70a2-ae0b-4855-ac14-1dddfc8e3241
:END:
-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 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
-without Emacs or any other advanced tool for that matter (though Emacs,
-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 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, 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.
-
-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
([[#h:8ed2bb6f-b5be-4711-82e9-8bee5bb06ece][Extending Denote]]).
-
-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 the "note"
-concept. Plus, we can come up with acronyms of dubious utility like:
-
-+ Don't Ever Note Only The Ephemeral
+NOTE THAT WE ARE ACTIVELY WORKING TOWARDS VERSION =0.1.0= AND MIGHT
+STILL INTRODUCE BREAKING, BACKWARD-INCOMPATIBLE CHANGES. This is
+particularly true for the linking facility. Everything else is in a
+stable state.
+
+Denote aims to be a simple-to-use, focused-in-scope, and effective
+note-taking tool for Emacs. It is based on the following core design
+principles:
+
++ Predictability :: File names must follow a consistent and 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 contents are, without
+ reference to any other metadatum. This convention is not specific to
+ note-taking, as it is pertinent to any form of file that is part of
+ the user's long-term storage
([[#h:532e8e2a-9b7d-41c0-8f4b-3c5cbb7d4dca][Renaming files]]).
+
++ Composability :: Be a good Emacs citizen, by integrating with other
+ packages or built-in functionality instead of re-inventing functions
+ such as for filtering or greping. Do not introduce dependencies on
+ specific libraries. While Org is a killer app for Emacs and the
+ default file type for new notes, Denote does not depend on org.el nor
+ its extensions and does allow notes to be created in a variety of
+ formats ([[#h:f34b172b-3440-446c-aec1-bf818d0aabfe][Notes in multiple file
types]]). The author of Denote
+ (Protesilaos, aka "Prot") writes ordinary notes in plain text
+ (=.txt=), switching to an Org file only when its expanded set of
+ functionality is required for the task at hand
([[#h:17896c8c-d97a-4faa-abf6-31df99746ca6][Points of entry]]).
+
++ Portability :: Notes are plain text and should remain portable. The
+ way Denote writes file names, the front matter it include in the
+ note's header, and the links it establishes must all be adequately
+ usable with standard Unix tools. No need for a databse or some
+ specialised software. As Denote develops and this manual is fully
+ fleshed out, there will be concrete examples on how to do the
+ Denote-equivalent on the command-line.
+
++ Flexibility :: Do not assume the user's preference for a note-taking
+ methodology. Denote is conceptually similar to the Zettelkasten
+ Method, which you can learn more about in this detailed introduction:
+ <https://zettelkasten.de/introduction/>. Notes are atomic (one file
+ per note) and have a unique identifier. However, Denote does not
+ enforce a particular methodology for knowledge management, such as a
+ restricted vocabulary or mutually exclusive sets of keywords. It is
+ up to the user to apply the requisite rigor in pursuit of their
+ preferred workflow.
+
+Now the important part... "Denote" is the familiar word, though it also
+is a play on the "note" concept. Plus, we can come up with acronyms,
+recursive or otherwise, of increasingly dubious utility like:
+
++ Don't Ever Note Only The Epiphenomenal
+ Denote Everything Neatly; Omit The Excesses
But we'll let you get back to work. Don't Eschew or Neglect your
-Obligations, Tasks, Engagements...
+Obligations, Tasks, and Engagements.
* The file-naming scheme
:PROPERTIES:
diff --git a/denote.el b/denote.el
index cd96e27952..4ee4bc3c28 100644
--- a/denote.el
+++ b/denote.el
@@ -24,41 +24,63 @@
;;; Commentary:
;;
-;; 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.
+;; NOTE THAT WE ARE ACTIVELY WORKING TOWARDS VERSION `0.1.0' AND MIGHT
+;; STILL INTRODUCE BREAKING, BACKWARD-INCOMPATIBLE CHANGES. This is
+;; particularly true for the linking facility. Everything else is in a
+;; stable state.
;;
-;; What Denote prioritizes with the enforcement of a strict file-naming
-;; scheme is portability. Notes can be accessed, filtered, and understood
-;; without Emacs or any other advanced tool for that matter (though Emacs,
-;; Org, and the like are excellent programs).
+;; Denote aims to be a simple-to-use, focused-in-scope, and effective
+;; note-taking tool for Emacs. It is based on the following core design
+;; principles:
;;
-;; 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
-;; 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.
+;; * Predictability :: File names must follow a consistent and
+;; descriptive naming convention (read the manual's "The file-naming
+;; scheme"). The file name alone should offer a clear indication of
+;; what the contents are, without reference to any other metadatum.
+;; This convention is not specific to note-taking, as it is pertinent
+;; to any form of file that is part of the user's long-term storage
+;; (read the manual's "Renaming files").
;;
-;; By default, Denote creates 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').
+;; * Composability :: Be a good Emacs citizen, by integrating with other
+;; packages or built-in functionality instead of re-inventing
+;; functions such as for filtering or greping. Do not introduce
+;; dependencies on specific libraries. While Org is a killer app for
+;; Emacs and the default file type for new notes, Denote does not
+;; depend on org.el nor its extensions and does allow notes to be
+;; created in a variety of formats ((read the manual's "Notes in
+;; multiple file types"). The author of Denote (Protesilaos, aka
+;; "Prot") writes ordinary notes in plain text (`.txt'), switching to
+;; an Org file only when its expanded set of functionality is required
+;; for the task at hand (read the manual's "Points of entry").
;;
-;; "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:
+;; * Portability :: Notes are plain text and should remain portable.
+;; The way Denote writes file names, the front matter it include in
+;; the note's header, and the links it establishes must all be
+;; adequately usable with standard Unix tools. No need for a databse
+;; or some specialised software. As Denote develops and this manual
+;; is fully fleshed out, there will be concrete examples on how to do
+;; the Denote-equivalent on the command-line.
;;
-;; + Don't Ever Note Only The Ephemeral
-;; + Denote Everything Neatly; Omit The Excesses
+;; * Flexibility :: Do not assume the user's preference for a
+;; note-taking methodology. Denote is conceptually similar to the
+;; Zettelkasten Method, which you can learn more about in this
+;; detailed introduction: <https://zettelkasten.de/introduction/>.
+;; Notes are atomic (one file per note) and have a unique identifier.
+;; However, Denote does not enforce a particular methodology for
+;; knowledge management, such as a restricted vocabulary or mutually
+;; exclusive sets of keywords. It is up to the user to apply the
+;; requisite rigor in pursuit of their preferred workflow.
+;;
+;; Now the important part... "Denote" is the familiar word, though it
+;; also is a play on the "note" concept. Plus, we can come up with
+;; acronyms, recursive or otherwise, of increasingly dubious utility
+;; like:
+;;
+;; * Don't Ever Note Only The Epiphenomenal
+;; * Denote Everything Neatly; Omit The Excesses
;;
;; But we'll let you get back to work. Don't Eschew or Neglect your
-;; Obligations, Tasks, Engagements...
+;; Obligations, Tasks, and Engagements.
;;; Code:
