[elpa] externals/denote e59b606e19: Use better default for file dates in front matter

[ELPA Syncer]

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