Suggestion to rename a denote-file-type value

[kaushalmodi]

Hello,

From https://protesilaos.com/codelog/2022-06-07-denote-introduction/, I see:

May I suggest that that denote-file-type be changed to something like markdown-yaml?

If a user is using a static site generator like Hugo and few others, they can specify the front-matter in YAML, TOML, or even JSON.

For example, in TOML format, the same will look like this:

+++
title = "This is a sample note"
date = 2022-06-10
tags = ["denote", "testing"]
identifier = "20220610T134640"
+++

If this data is organized internally as a plist, it can be easily exported to TOML using tomelr [Disclaimer: I am maintaining that library and it's available on GNU ELPA too.]

Here's an example of using tomelr-encode from that library, which will generate the above TOML.

(tomelr-encode '(:title "This is a sample note"
                 :date "2022-06-10"
                 :tags ("denote" "testing")
                 :identifier "20220610T134640"))

Summary

• Suggestion is to only rename the markdown value to markdown-yaml for now.
• If there is motivation to add TOML front-matter export in future, something like above using tomelr can be done if denote-file-type is set to markdown-toml.

[protesilaos]

May I suggest that that denote-file-type be changed to something like
markdown-yaml?

Yes, sure!

+++
title = "This is a sample note"
date = 2022-06-10
tags = ["denote", "testing"]
identifier = "20220610T134640"
+++

I think we can add this as well. Is that okay?

If this data is organized internally as a plist, it can be easily
exported to TOML using tomelr [Disclaimer: I am maintaining that
library and it's available on GNU ELPA too.]

I admit to have never used toml before, so I need your help here. I
understand it is similar to yaml, but that's about it.

Suggestion is to only rename the markdown value to markdown-yaml for
now.

Will do it right away.

• If there is motivation to add TOML front-matter export in future,
  something like above using tomelr can be done if
  denote-file-type is set to markdown-toml.

I am not sure I follow you on the "export" part. But yes, if we can
support that use-case like we do with the others right now, then I see
no problem with it.

[kaushalmodi]

I think we can add this as well. Is that okay?

This can be an incremental feature if people request it. I don't think it will be necessary to support a different flavor of front-matter in the first release. But renaming markdown to markdown-yaml at least leaves the scope open.. just in case 😄

I admit to have never used toml before, so I need your help here. I understand it is similar to yaml, but that's about it.

The main benefit of TOML is that it's indentation-agnostic, and it has a tight and concise spec: https://toml.io/en/v1.0.0

Will do it right away.

💯

I am not sure I follow you on the "export" part.

I was using "export" just as an umbrella term for the process of converting the user-entered data to a different format (TOML in this case).

I think it will be another case statement here:

denote/denote.el

Lines 345 to 351 in f9b8614

	(defun denote--file-meta-header (title date keywords id)
	"Front matter for new notes.
	TITLE, DATE, KEYWORDS, FILENAME, ID are all strings which are
	provided by `denote-new-note'."
	(let ((kw (denote--file-meta-keywords keywords)))
	(pcase denote-file-type

But as I was looking through it, I realized that a bit more work might be needed if we want to support spaces in tags/keywords.

[protesilaos]

All clear about the "export" part. I am already working on it, though I must pause for ~30 minutes and be back to finalise it (diff below).

 denote.el | 34 ++++++++++++++++++++++++++--------
 1 file changed, 26 insertions(+), 8 deletions(-)

diff --git a/denote.el b/denote.el
index 6bc4c23..5352405 100644
--- a/denote.el
+++ b/denote.el
@@ -118,8 +118,9 @@ (defcustom denote-file-type nil
 By default (a nil value), the file type is that of Org mode.
 
 When the value is the symbol `markdown-yaml', the file type is
-that of Markdown mode and the front matter uses a YAML-compliant
-way to represent tags.
+that of Markdown mode and the front matter uses YAML.  Similarly,
+`markdown-toml' will use Markdown but apply TOML to the front
+matter.
 
 When the value is `text', the file type is that of Text mode.
 
@@ -127,6 +128,7 @@ (defcustom denote-file-type nil
   :type '(choice
           (const :tag "Org mode (default)" nil)
           (const :tag "Markdown (YAML front matter)" markdown-yaml)
+          (const :tag "Markdown (TOML front matter)" markdown-toml)
           (const :tag "Plain text" text))
   :group 'denote)
 
@@ -316,6 +318,7 @@ ;;;; New note
 (defun denote--file-extension ()
   "Return file type extension based on `denote-file-type'."
   (pcase denote-file-type
+    ('markdown-toml ".md")
     ('markdown-yaml ".md")
     ('text ".txt")
     (_ ".org")))
@@ -333,15 +336,22 @@ (defun denote--format-file (path id keywords slug extension)
         (ext (or extension (denote--file-extension))))
     (format "%s%s--%s--%s%s" path id slug kws ext)))
 
-(defun denote--file-meta-keywords (keywords)
+(defun denote--file-meta-keywords (keywords &optional type)
   "Prepare KEYWORDS for inclusion in the file's front matter.
 Parse the output of `denote--keywords-prompt', using `downcase'
 on the keywords and separating them by two spaces.  A single
-keyword is just downcased."
-  (if (and (> (length keywords) 1)
-           (not (stringp keywords)))
-      (mapconcat #'downcase keywords "  ")
-    (downcase keywords)))
+keyword is just downcased.
+
+With optional TYPE, format the keywords
+appropriately (WORK-IN-PROGRESS)."
+  (cond
+   ((and (> (length keywords) 1)
+         (not (stringp keywords)))
+    (pcase type
+      ('toml (format "[%s]" (mapconcat #'downcase keywords ", ")))
+      (_ (mapconcat #'downcase keywords "  "))))
+   (t
+    (downcase keywords))))
 
 (defun denote--file-meta-header (title date keywords id)
   "Front matter for new notes.
@@ -350,6 +360,14 @@ (defun denote--file-meta-header (title date keywords id)
  provided by `denote-new-note'."
   (let ((kw (denote--file-meta-keywords keywords)))
     (pcase denote-file-type
+      ('markdown-toml (concat "+++" "\n"
+                              "title:      " title "\n"
+                              "date:       " date  "\n"
+                              "tags:       " kw    "\n"
+                              "identifier: " id    "\n"
+                              "+++"                "\n"
+                              "\n"))
+
       ('markdown-yaml (concat "---" "\n"
                               "title:      " title "\n"
                               "date:       " date  "\n"

Can you please share TOML front matter with one and then with two tags? Just to be sure I use the correct syntax.

[kaushalmodi]

Can you please share TOML front matter with one and then with two tags? Just to be sure I use the correct syntax.

Sure!

TOML with 1 tag

+++
title = "def"
date = 2022-06-10
tags = ["tag1"]
identifier = "20220610T110603"
+++

TOML with more tags

+++
title = "def"
date = 2022-06-10
tags = ["tag1", "tag2", "tag3"]
identifier = "20220610T110603"
+++

---

Main differences compared to YAML

This applies only to the simple scalar and list types that we are seeing here:

• key/val separator : becomes = (white-space around key and val are ignored, but it's more canonical to surround the = with spaces: key = "val")

The list format above will work for YAML too.

[kaushalmodi]

I find this website very useful: https://toolkit.site/format.html

[protesilaos]

Just pushed the changes to a new branch: markdown-toml. The one thing
I am not sure about is the use of single quotes. They are easier to
format. The TOML docs suggest that those are literal strings, though I
do not know if that is okay for the use-case we have here.

What do you think?

[ Will update the README.org afterwards. ]

[protesilaos]

Sample output:

+++
title:      This is a test
date:       2022-06-10
tags:       ['tag1']
identifier: 20220610T192415
+++

And with more tags:

+++
title:      This is a test
date:       2022-06-10
tags:       [ 'tag1', 'tag2', 'tag3' ]
identifier: 20220610T192450
+++

[kaushalmodi]

For TOML,

1. We will need = as key/val separator instead of :.
2. Single quotes instead of double quotes for the scope of tags is OK.
3. The title value will need to be double quoted because it has spaces.
   • It's canonical to wrap TOML string values in double quotes.

+++
title = "This is a test"
date = 2022-06-10
tags = [ 'tag1', 'tag2', 'tag3' ]
identifier = "20220610T192450"
+++

They are easier to format.

Strings get auto-double-quoted if you format them using %S (upper case).

(format "%s" "abc")   ;; => abc
(format "%S" "abc")   ;; => "abc"

[protesilaos]

Strings get auto-double-quoted if you format them using %S (upper case).

Good to know!

Updated everything. We now get:

+++
title      = "This is a test"
date       = 2022-06-10
tags       = ["testing"]
identifier = 20220610T195052
+++

And:

+++
title      = "This is a test"
date       = 2022-06-10
tags       = ["tag1", "tag2"]
identifier = 20220610T195544
+++

[protesilaos]

Once we sort this out, we can move to the date format issue: #7

[kaushalmodi]

identifier = 20220610T195544

We are almost there..

This is seen as illegal by a TOML parser because it begins with numbers and then sees a "T" in middle. To make it a string, it would be need to wrapped in double-quotes as well.

With that last change, the generated TOML will be valid.

[protesilaos]

Done!

I will now merge this, update the docs, and then we can proceed to the next items.

[kaushalmodi]

I will now merge this, update the docs, and then we can proceed to the next items.

Perfect! Thank you!