branch: externals/denote
commit e59b606e1924a7a3e536597cb309d1c71d67d380
Author: Protesilaos Stavrou <i...@protesilaos.com>
Commit: Protesilaos Stavrou <i...@protesilaos.com>
Use better default for file dates in front matter
The old user option 'denote-front-matter-date-format' is deprecated. It
is superseded by 'denote-date-format'.
Now we use an inactive timestamp for Org, the RFC3339 standard for
Markdown (YAML or TOML), and the ISO 8601 format for plain text.
The user can specify a string value for 'denote-date-format', which
contains format specifiers as described in the doc string of
'format-time-string'.
Thanks to Peter Prevos and Kaushal Modi for the discussion in issue 27
over at the GitHub mirror:
<https://github.com/protesilaos/denote/issues/27>.
---
README.org | 48 ++++++++++++++++++++++++------------------------
denote.el | 39 +++++++++++++++++++--------------------
2 files changed, 43 insertions(+), 44 deletions(-)
diff --git a/README.org b/README.org
index 9652d9c8b1..c91d70cb00 100644
--- a/README.org
+++ b/README.org
@@ -426,10 +426,10 @@ This is how it looks for Org mode (~denote-file-type~ is
nil):
#+begin_src org
:PROPERTIES:
-:ID: 20220610T202537
+:ID: 20220630T160934
:END:
,#+title: This is a sample note
-,#+date: 2022-06-10
+,#+date: [2022-06-30 Thu 16:09]
,#+filetags: denote testing
#+end_src
@@ -443,9 +443,9 @@ For Markdown with YAML, the front matter looks like this
#+begin_src md
---
title: "This is a sample note"
-date: 2022-06-10
+date: 2022-06-30T16:09:58+03:00
tags: denote testing
-identifier: "20220610T202021"
+identifier: "20220630T160958"
---
#+end_src
@@ -455,9 +455,9 @@ For Markdown with TOML, it looks like this
(~denote-file-type~ has the
#+begin_src md
+++
title = "This is a sample note"
-date = 2022-06-10
+date = 2022-06-30T16:10:13+03:00
tags = ["denote", "testing"]
-identifier = "20220610T201510"
+identifier = "20220630T161013"
+++
#+end_src
@@ -466,31 +466,31 @@ And for plain text, we have the following
(~denote-file-type~ has the
#+begin_example
title: This is a sample note
-date: 2022-06-10
+date: 2022-06-30
tags: denote testing
-identifier: 20220610T202232
+identifier: 20220630T161028
---------------------------
#+end_example
-#+vindex: denote-front-matter-date-format
+#+vindex: denote-date-format
The format of the date in the front matter is controlled by the user
-option ~denote-front-matter-date-format~:
+option ~denote-date-format~. When nil, Denote uses a file-type-specific
+format:
+
+- For Org, an inactive timestamp is used, such as
+ =[2022-06-30 Wed 06:19]=.
-- When the value is nil (the default), the date uses a plain
- =YEAR-MONTH-DAY= notation, like =2022-06-08= (the ISO 8601 standard).
+- For Markdowmn, the RFC3339 standard is applied:
+ =2022-06-30T15:48:00+03:00=.
-- When the value is the =org-timestamp= symbol, the date is recorded as
- an inactive Org timestamp, such as =[2022-06-08 Wed 06:19]=.
+- For plain text, the format is that of ISO 8601: =2022-06-30=.
-- An arbitrary string value is interpreted as the argument for the
- function ~format-time-string~. This gives the user maximum control
- over how time is represented in the front matter.
+If the value is a string, ignore the above and use it instead. The
+string must include format specifiers for the date. These are described
+in the doc string of ~format-time-string~..
-When ~denote-file-type~ specifies one of the Markdown flavors, we ignore
-this user option in order to enforce the RFC3339 specification (Markdown
-is typically employed in static site generators as source code for Web
-pages). However, when ~denote-front-matter-date-format~ has a string
-value, this rule is suspended: we use whatever the user wants.
+[ DEV NOTE: ~denote-date-format~ supersedes the now obsolete
+ ~denote-front-matter-date-format~ as part of {{{development-version}}} ]
** Tweaking the front matter
:PROPERTIES:
@@ -1450,7 +1450,7 @@ Everything is in place to set up the package.
;; preference is for single-word keywords for a more rigid workflow.
(setq denote-allow-multi-word-keywords t)
-(setq denote-front-matter-date-format nil) ; change this to `org-timestamp' or
custom string
+(setq denote-date-format nil) ; read doc string
;; You will not need to `require' all those individually once the
;; package is available.
@@ -1936,7 +1936,7 @@ Denote is meant to be a collective effort. Every bit of
help matters.
Kaushal Modi.
+ Ideas and/or user feedback :: Colin McLear, Damien Cassou, Frank
- Ehmsen, Jack Baty, Kaushal Modi, Sven Seebeck, Ypot.
+ Ehmsen, Jack Baty, Kaushal Modi, Peter Prevos, Sven Seebeck, Ypot.
Special thanks to Peter Povinec who helped refine the file-naming
scheme, which is the cornerstone of this project.
diff --git a/denote.el b/denote.el
index 346986e12e..7dba629c59 100644
--- a/denote.el
+++ b/denote.el
@@ -186,31 +186,29 @@ Any other non-nil value is the same as the default."
(const :tag "Plain text" text))
:group 'denote)
-(defcustom denote-front-matter-date-format nil
+(defcustom denote-date-format nil
"Date format in the front matter (file header) of new notes.
-If the value is nil, use a plain date in YEAR-MONTH-DAY notation,
-like 2022-06-08 (the ISO 8601 standard).
+When nil, use a file-type-specific format:
-If the value is the `org-timestamp' symbol, format the date as an
-inactive Org timestamp such as: [2022-06-08 Wed 06:19].
+- For Org, an inactive timestamp is used, such as [2022-06-30 Wed
+ 06:19].
-If a string, use it as the argument of `format-time-string'.
-Read the documentation of that function for valid format
-specifiers.
+- For Markdowmn, the RFC3339 standard is applied:
+ 2022-06-30T15:48:00+03:00.
-When `denote-file-type' specifies one of the Markdown flavors, we
-ignore this user option in order to enforce the RFC3339
-specification (Markdown is typically employed in static site
-generators as source code for Web pages). However, when
-`denote-front-matter-date-format' has a string value, this rule
-is suspended: we use whatever the user wants."
+- For plain text, the format is that of ISO 8601: 2022-06-30.
+
+If the value is a string, ignore the above and use it instead.
+The string must include format specifiers for the date. These
+are described in the doc string of `format-time-string'."
:type '(choice
- (const :tag "Just the date like 2022-06-08" nil)
- (const :tag "An inactive Org timestamp like [2022-06-08 Wed 06:19]"
org-timestamp)
+ (const :tag "Use appropiate format for each file type" nil)
(string :tag "Custom format for `format-time-string'"))
:group 'denote)
+(make-obsolete 'denote-front-matter-date-format 'denote-date-format "0.2.0")
+
;;;; Main variables
(defconst denote--id-format "%Y%m%dT%H%M%S"
@@ -564,16 +562,17 @@ With optional DATE, use it else use the current one."
(defun denote--date (&optional date)
"Expand the date for a new note's front matter.
With optional DATE, use it else use the current one."
- (let ((format denote-front-matter-date-format))
+ (let ((format denote-date-format))
(cond
((stringp format)
(format-time-string format date))
((or (eq denote-file-type 'markdown-toml)
(eq denote-file-type 'markdown-yaml))
(denote--date-rfc3339 date))
- ((eq format 'org-timestamp)
- (denote--date-org-timestamp date))
- (t (denote--date-iso-8601 date)))))
+ ((eq denote-file-type 'text)
+ (denote--date-iso-8601 date))
+ (t
+ (denote--date-org-timestamp date)))))
(defun denote--prepare-note (title keywords &optional path date id)
"Use TITLE and KEYWORDS to prepare new note file.
